refactor: group agent launch contracts under concrete owners (#37915)

2026-11-13 09:27:29 +00:00 · 2026-11-03 14:45:49 -08:00
parent ad5657a57f
commit d5f2a17cd2
1238 changed files with 2460 additions and 2319 deletions
@@ -506,10 +506,10 @@
      "invariant": "A literal sleep followed by && must not cause the later harness to lose hook/account preparation or hidden renderer query delivery. Preparation and typed-command hints are not live process evidence. Fresh agent startup output may request one bounded host confirmation after the initial command read window has expired.",
      "oracle": "Delayed OpenCode 2 installs v2 hooks rather than v1, disabled harnesses do not fall back, selected managed accounts survive, and Pi/OMP/Prime preparation targets the requested harness. A captured Claude startup title at 30 seconds yields process-confirmed routing, never title-authorized routing. A title storm causes at most three additional reads; close and untrackable providers cause none.",
      "commands": [
-        "ORCA_BACKGROUND_LAUNCH=1 pnpm test src/shared/agent-command-line-intent.test.ts src/shared/pi-agent-kind.test.ts src/shared/opencode-launch-command.test.ts src/main/ipc/pty/host-env/opencode-hook-installation.test.ts src/main/ipc/pty/pty-spawn-env-terminal-basics.test.ts src/renderer/src/components/terminal-pane/pane-delayed-agent-startup.test.ts src/renderer/src/components/terminal-pane/pty-connection-foreground-agent.test.ts src/renderer/src/components/terminal-pane/pty-connection-visibility-and-exit.test.ts --maxWorkers=2"
+        "ORCA_BACKGROUND_LAUNCH=1 pnpm test src/shared/agent-launch/startup/agent-command-line-intent.test.ts src/shared/pi-agent-kind.test.ts src/shared/opencode-launch-command.test.ts src/main/ipc/pty/host-env/opencode-hook-installation.test.ts src/main/ipc/pty/pty-spawn-env-terminal-basics.test.ts src/renderer/src/components/terminal-pane/pane-delayed-agent-startup.test.ts src/renderer/src/components/terminal-pane/pty-connection-foreground-agent.test.ts src/renderer/src/components/terminal-pane/pty-connection-visibility-and-exit.test.ts --maxWorkers=2"
      ],
      "testFiles": [
-        "src/shared/agent-command-line-intent.test.ts",
+        "src/shared/agent-launch/startup/agent-command-line-intent.test.ts",
        "src/shared/pi-agent-kind.test.ts",
        "src/shared/opencode-launch-command.test.ts",
        "src/main/ipc/pty/host-env/opencode-hook-installation.test.ts",
@@ -546,7 +546,7 @@
          "result": "passed",
          "durationSeconds": 1.86,
          "summary": "214 assertions pass across nine files, including all 45 harness classifications, actual hook files, delayed account preparation, late process routing, hidden query delivery and bounded recovery.",
-          "currentCommand": "ORCA_BACKGROUND_LAUNCH=1 pnpm test src/shared/agent-command-line-intent.test.ts src/shared/pi-agent-kind.test.ts src/shared/opencode-launch-command.test.ts src/main/ipc/pty/host-env/opencode-hook-installation.test.ts src/main/ipc/pty/pty-spawn-env-terminal-basics.test.ts src/renderer/src/components/terminal-pane/pane-delayed-agent-startup.test.ts src/renderer/src/components/terminal-pane/pty-connection-foreground-agent.test.ts src/renderer/src/components/terminal-pane/pty-connection-visibility-and-exit.test.ts --maxWorkers=2"
+          "currentCommand": "ORCA_BACKGROUND_LAUNCH=1 pnpm test src/shared/agent-launch/startup/agent-command-line-intent.test.ts src/shared/pi-agent-kind.test.ts src/shared/opencode-launch-command.test.ts src/main/ipc/pty/host-env/opencode-hook-installation.test.ts src/main/ipc/pty/pty-spawn-env-terminal-basics.test.ts src/renderer/src/components/terminal-pane/pane-delayed-agent-startup.test.ts src/renderer/src/components/terminal-pane/pty-connection-foreground-agent.test.ts src/renderer/src/components/terminal-pane/pty-connection-visibility-and-exit.test.ts --maxWorkers=2"
        }
      ],
      "runtimeBudget": {
@@ -14815,7 +14815,7 @@
      "invariant": "A public CLI send containing non-empty text plus Enter and no interrupt identifies agent-prompt intent. The owning runtime uses bracketed-paste and settled submit only when a fresh foreground-process read positively identifies the exact target as Claude or Codex on a desktop call; every other agent, stale agent metadata over a shell, text-only input, bare Enter, interrupts, mobile input, query replies, and older clients keep the direct terminal contract.",
      "oracle": "Launch a bare fake Codex through the real Electron PTY and delay its composer render for 1,200 ms, beyond the legacy generic 500 ms gap. Send a 557-byte prompt with the public CLI and require the marker, zero premature Enter, no rescue Enter, and one submission. POSIX child stdin must retain one bracketed-paste frame; Windows ConPTY consumes that control frame, so runtime tests require the frame at the PTY write boundary while the Windows child requires the exact prompt. The same harness against the installed pre-fix runtime must record one premature Enter and require one bare rescue Enter. Focused units require CLI intent only for text plus Enter, settlement only for freshly identified Claude/Codex, the legacy platform delay for every other configured agent, stale Codex launch identity over a shell to fall back, no wrapper polling, and byte-for-byte direct delivery for non-targets.",
      "commands": [
-        "pnpm exec vitest run --config config/vitest.config.ts src/cli/handlers/terminal.test.ts src/main/runtime/rpc/terminal-agent-prompt-send.test.ts src/main/runtime/rpc/terminal-send.test.ts src/main/runtime/orca-runtime.test.ts src/shared/agent-prompt-injection.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/cli/handlers/terminal.test.ts src/main/runtime/rpc/terminal-agent-prompt-send.test.ts src/main/runtime/rpc/terminal-send.test.ts src/main/runtime/orca-runtime.test.ts src/shared/agent-launch/startup/agent-prompt-injection.test.ts",
        "pnpm run build:cli && pnpm exec playwright test tests/e2e/terminal-send-agent-prompt-submit.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
        "pnpm.cmd exec playwright test tests/e2e/terminal-send-agent-prompt-submit.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
        "node tests/tools/repro-terminal-send-submit.mjs --cli orca --worktree <registered-worktree> --discard-report"
@@ -14825,7 +14825,7 @@
        "src/main/runtime/rpc/terminal-agent-prompt-send.test.ts",
        "src/main/runtime/rpc/terminal-send.test.ts",
        "src/main/runtime/orca-runtime.test.ts",
-        "src/shared/agent-prompt-injection.test.ts",
+        "src/shared/agent-launch/startup/agent-prompt-injection.test.ts",
        "tests/e2e/terminal-send-agent-prompt-submit.spec.ts",
        "tests/tools/repro-terminal-send-submit.mjs"
      ],
@@ -14895,6 +14895,7 @@
          "runner": "local",
          "platform": "macos",
          "command": "pnpm exec vitest run --config config/vitest.config.ts src/cli/handlers/terminal.test.ts src/main/runtime/rpc/terminal-agent-prompt-send.test.ts src/main/runtime/rpc/terminal-send.test.ts src/main/runtime/orca-runtime.test.ts src/shared/agent-prompt-injection.test.ts",
+          "currentCommand": "pnpm exec vitest run --config config/vitest.config.ts src/cli/handlers/terminal.test.ts src/main/runtime/rpc/terminal-agent-prompt-send.test.ts src/main/runtime/rpc/terminal-send.test.ts src/main/runtime/orca-runtime.test.ts src/shared/agent-launch/startup/agent-prompt-injection.test.ts",
          "result": "passed",
          "durationSeconds": 23.2,
          "summary": "After rebasing onto current main, the final narrowed runtime/CLI/RPC suite passed 1,201 tests with one skip, including fresh Claude/Codex identity, stale-agent shell fallback, and legacy timing for every other configured agent."
@@ -14958,12 +14959,12 @@
      "invariant": "Injected orchestration task prompts for recognized agent CLIs must send the prompt body inside one bracketed-paste frame, sanitize embedded ESC bytes, preserve chunk boundaries without losing the frame, and submit exactly once only after the agent can accept Enter. Local worker-start with supported observation must preserve an unobserved turn as start_unknown without revoking authority, closing questions, or triggering a rescue Enter; a worker report during observation must settle normally. Claude and Codex must emit a post-paste composer marker and then settle, or reach the bounded fallback first; every other agent retains the platform delay.",
      "oracle": "Runtime tests assert the exact PTY write sequence, failure cleanup, Claude/Codex marker-gated multi-frame renders, and the legacy platform delay for every other configured agent. The candidate resets settlement on later frames, gives a late marker a fresh bounded window, and still submits once at the hard deadline if output never settles. The worker-start contract drives the production RPC through a delayed fake Codex composer and independently checks exact turn/Enter counts plus reopened SQLite Task, Dispatch, worker receipt, and mutation receipt state for accepted and swallowed outcomes. Other orchestration tests assert dispatch/coordinator use the agent prompt path; the live CLI harness covers long Codex-like framing.",
      "commands": [
-        "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-launch/startup/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
        "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/rpc/methods/orchestration/worker/worker-start-prompt-contract.test.ts --reporter=dot",
        "node tests/tools/repro-orchestration-long-prompt.mjs --cli out/bin/orca-dev --mode codex-like --size-kb 32 --timeout-ms 20000"
      ],
      "testFiles": [
-        "src/shared/agent-prompt-injection.test.ts",
+        "src/shared/agent-launch/startup/agent-prompt-injection.test.ts",
        "src/main/runtime/orca-runtime.test.ts",
        "src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts",
        "src/main/runtime/rpc/methods/orchestration/worker/worker-start-prompt-contract.test.ts",
@@ -14972,7 +14973,7 @@
      ],
      "assertionRefs": [
        {
-          "file": "src/shared/agent-prompt-injection.test.ts",
+          "file": "src/shared/agent-launch/startup/agent-prompt-injection.test.ts",
          "assertions": [
            "agent prompts are always framed as bracketed paste",
            "Deferred unit obligation: OMP joins submit to the paste frame while Claude, Codex and unidentified agents keep submit separate; the direct predicate table was removed. Runtime-writer coverage is unchanged.",
@@ -15040,6 +15041,7 @@
          "runner": "local",
          "platform": "macos",
          "command": "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
+          "currentCommand": "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-launch/startup/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
          "result": "passed",
          "durationSeconds": 11.32,
          "summary": "4 files and 1,303 tests passed with one skipped. Claude and Codex both wait for post-marker quiescence, and a Codex marker arriving at 7.9 seconds receives a fresh window through its final slow frame. Exact-build live Codex workers accepted injected prompts without manual Enter, replied, called worker_done, and settled successfully in the rendered Electron UI."
@@ -15049,6 +15051,7 @@
          "runner": "local",
          "platform": "macos",
          "command": "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
+          "currentCommand": "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-launch/startup/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
          "result": "passed",
          "durationSeconds": 13.3,
          "summary": "4 files and 1,283 tests passed. The hardened multi-frame oracle failed on the first-marker candidate because it submitted at 751 ms during an intermediate Claude frame; the quiescence candidate waited through the final 1,000 ms frame and submitted once at 2,500 ms. Continuous render output remained bounded to one fallback submit at 8 seconds. An isolated Claude Code 2.1.231 Haiku probe saw the first marker at 400 ms, continued output through 1,500 ms, sent one Enter at 3,000 ms after 1.5 seconds quiet, and created the expected marker; no Fable or Opus probe was used."
@@ -15058,6 +15061,7 @@
          "runner": "local",
          "platform": "macos",
          "command": "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
+          "currentCommand": "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-launch/startup/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
          "result": "passed",
          "durationSeconds": 16.9,
          "summary": "4 files and 1,282 tests passed. Unmodified main wrote Enter at 500 ms before the deterministic Claude composer rendered at 750 ms; the candidate waited for the split show-cursor marker and wrote one Enter. A live Claude Code 2.1.231 Haiku trace rendered the pasted marker and show-cursor in one 523-byte frame without submitting a model request."
@@ -15067,6 +15071,7 @@
          "runner": "local",
          "platform": "macos",
          "command": "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
+          "currentCommand": "pnpm exec vitest run --config config/vitest.config.ts src/shared/agent-launch/startup/agent-prompt-injection.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/rpc/methods/orchestration/runs/tasks-dispatch.test.ts src/main/runtime/orchestration/coordinator.test.ts",
          "result": "passed",
          "durationSeconds": 7.4,
          "summary": "4 test files passed, 697 tests passed; covers framing, runtime PTY writes, orchestration RPC dispatch, and coordinator dispatch behavior."
@@ -11359,12 +11359,12 @@
      "src/shared/__tests__/process-host/windows-tree-kill-late-taskkill.win32.test.ts": 65,
      "src/shared/abort-signal-reason-memory.test.ts": 80,
      "src/shared/abort-signal-reason.test.ts": 81,
-      "src/shared/agent-chat-permission-host-support.test.ts": 195,
-      "src/shared/agent-chat-permission-mode.test.ts": 199,
+      "src/shared/agent-launch/permissions/agent-chat-permission-host-support.test.ts": 195,
+      "src/shared/agent-launch/permissions/agent-chat-permission-mode.test.ts": 199,
      "src/shared/agent-child-row-model.test.ts": 84,
-      "src/shared/agent-cli-flag-detection.test.ts": 56,
+      "src/shared/agent-session/options/agent-cli-flag-detection.test.ts": 56,
      "src/shared/agent-cli-install-dir-fallback.test.ts": 130,
-      "src/shared/agent-command-line-intent.test.ts": 95,
+      "src/shared/agent-launch/startup/agent-command-line-intent.test.ts": 95,
      "src/shared/agent-decorative-title-signature.test.ts": 81,
      "src/shared/agent-detection.test.ts": 188,
      "src/shared/agent-hook-endpoint-file.test.ts": 58,
@@ -11417,23 +11417,23 @@
      "src/shared/agent-hook-status-cache.test.ts": 79,
      "src/shared/agent-hook-transport-interference.test.ts": 49,
      "src/shared/agent-image-paste.test.ts": 55,
-      "src/shared/agent-launch-choices.test.ts": 387,
-      "src/shared/agent-launch-default-choices.test.ts": 209,
-      "src/shared/agent-launch-legacy-publication.test.ts": 314,
-      "src/shared/agent-launch-operation.test.ts": 176,
-      "src/shared/agent-launch-picker-legacy-permission.test.ts": 299,
-      "src/shared/agent-launch-picker.test.ts": 303,
-      "src/shared/agent-launch-settings-auto-projection.test.ts": 219,
-      "src/shared/agent-launch-settings-permissions.test.ts": 199,
+      "src/shared/agent-launch/choices/agent-launch-choices.test.ts": 387,
+      "src/shared/agent-launch/choices/agent-launch-default-choices.test.ts": 209,
+      "src/shared/agent-launch/choices/agent-launch-legacy-publication.test.ts": 314,
+      "src/shared/agent-launch/contracts/agent-launch-operation.test.ts": 176,
+      "src/shared/agent-launch/picker/agent-launch-picker-legacy-permission.test.ts": 299,
+      "src/shared/agent-launch/picker/agent-launch-picker.test.ts": 303,
+      "src/shared/agent-launch/choices/agent-launch-settings-auto-projection.test.ts": 219,
+      "src/shared/agent-launch/choices/agent-launch-settings-permissions.test.ts": 199,
      "src/shared/agent-lead-status-fold.test.ts": 59,
      "src/shared/agent-pending-prompt.test.ts": 99,
      "src/shared/agent-process-presence-platform.test.ts": 64,
      "src/shared/agent-process-presence-probe.test.ts": 88,
      "src/shared/agent-process-recognition.test.ts": 342,
-      "src/shared/agent-prompt-injection.test.ts": 88,
+      "src/shared/agent-launch/startup/agent-prompt-injection.test.ts": 88,
      "src/shared/agent-row-conversation-name.test.ts": 116,
      "src/shared/agent-row-primary-text.test.ts": 60,
-      "src/shared/agent-scoped-permission-defaults.test.ts": 213,
+      "src/shared/agent-launch/permissions/agent-scoped-permission-defaults.test.ts": 213,
      "src/shared/agent-scratch-worktrees.test.ts": 61,
      "src/shared/agent-session-handoff-context.test.ts": 216,
      "src/shared/agent-session/agent-message-display-text.test.ts": 147,
@@ -11497,8 +11497,8 @@
      "src/shared/agent-session/view/structured-agent-session-turn-bars.test.ts": 178,
      "src/shared/agent-session/view/structured-agent-session-turn-timing-retention.test.ts": 221,
      "src/shared/agent-session/view/structured-agent-session-turn-timing.test.ts": 166,
-      "src/shared/agent-startup-default-lifetime.test.ts": 272,
-      "src/shared/agent-startup-update-suppression.test.ts": 206,
+      "src/shared/agent-launch/startup/agent-startup-default-lifetime.test.ts": 272,
+      "src/shared/agent-launch/startup/agent-startup-update-suppression.test.ts": 206,
      "src/shared/agent-status-child-work-admission-activity.test.ts": 232,
      "src/shared/agent-status-child-work-admission-collision.test.ts": 214,
      "src/shared/agent-status-child-work-admission-parse.test.ts": 412,
@@ -11531,7 +11531,7 @@
      "src/shared/agent-title-evidence.test.ts": 166,
      "src/shared/agent-transcript-poll-scheduler.test.ts": 113,
      "src/shared/agent-transitions.test.ts": 105,
-      "src/shared/agent-tui-input-clear.test.ts": 57,
+      "src/shared/agent-launch/startup/agent-tui-input-clear.test.ts": 57,
      "src/shared/ai-vault-resume-command.test.ts": 70,
      "src/shared/ai-vault-resume-target.test.ts": 85,
      "src/shared/ai-vault-scope-paths.test.ts": 73,
@@ -11634,7 +11634,7 @@
      "src/shared/codex-reset-credit-scope.test.ts": 49,
      "src/shared/codex-rollout-jsonl-cursor.test.ts": 231,
      "src/shared/codex-shared-server-command.test.ts": 76,
-      "src/shared/codex-startup-delivery.test.ts": 76,
+      "src/shared/agent-launch/startup/codex-startup-delivery.test.ts": 76,
      "src/shared/codex-status-transcript-line.test.ts": 78,
      "src/shared/codex-subagent-poll-scheduler.test.ts": 52,
      "src/shared/codex-subagent-rollout-lifecycle.test.ts": 239,
@@ -11670,7 +11670,7 @@
      "src/shared/darwin-terminal-names-real-ps.test.ts": 42,
      "src/shared/darwin-terminal-names.test.ts": 267,
      "src/shared/darwin-terminal-naming-single-flight.test.ts": 69,
-      "src/shared/default-agent-settings.test.ts": 31,
+      "src/shared/agent-launch/choices/default-agent-settings.test.ts": 31,
      "src/shared/device-key-proof.test.ts": 112,
      "src/shared/dictation-audio-meter.test.ts": 49,
      "src/shared/dictation-transcript-spacing.test.ts": 48,
@@ -11802,7 +11802,7 @@
      "src/shared/hard-wrapped-terminal-http-links.test.ts": 91,
      "src/shared/harness-injected-user-turns.test.ts": 43,
      "src/shared/headless-serve-ozone-platform.test.ts": 44,
-      "src/shared/hermes-startup-query.windows.test.ts": 43,
+      "src/shared/agent-launch/startup/hermes-startup-query.windows.test.ts": 43,
      "src/shared/home-or-filesystem-root.test.ts": 54,
      "src/shared/hook-command-source-policy.test.ts": 43,
      "src/shared/host-authority.test.ts": 47,
@@ -11994,10 +11994,10 @@
      "src/shared/notebook-venv-location.test.ts": 50,
      "src/shared/nul-delimited-fields.test.ts": 37,
      "src/shared/nvm-default-alias.test.ts": 81,
-      "src/shared/omp-draft-launch-shell.test.ts": 382,
-      "src/shared/omp-draft-launch-windows.test.ts": 270,
-      "src/shared/omp-fresh-launch-cmd.win32.test.ts": 286,
-      "src/shared/omp-fresh-launch-shell.test.ts": 301,
+      "src/shared/agent-launch/startup/omp-draft-launch-shell.test.ts": 382,
+      "src/shared/agent-launch/startup/omp-draft-launch-windows.test.ts": 270,
+      "src/shared/agent-launch/startup/omp-fresh-launch-cmd.win32.test.ts": 286,
+      "src/shared/agent-launch/startup/omp-fresh-launch-shell.test.ts": 301,
      "src/shared/omp-owner-state-title.test.ts": 96,
      "src/shared/omp-pi-semantic-title-preservation.test.ts": 123,
      "src/shared/open-in-applications.test.ts": 48,
@@ -12462,15 +12462,15 @@
      "src/shared/tmux-client-attachment.test.ts": 50,
      "src/shared/tmux-hook-refresh-retirement.test.ts": 608,
      "src/shared/tmux-host-attachment-probe.test.ts": 69,
-      "src/shared/tui-agent-auto-permissions.test.ts": 293,
-      "src/shared/tui-agent-launch-command-argument-values.test.ts": 266,
-      "src/shared/tui-agent-launch-command-override.test.ts": 63,
-      "src/shared/tui-agent-launch-command-pick-flags.test.ts": 242,
-      "src/shared/tui-agent-permission-choice.test.ts": 1009,
-      "src/shared/tui-agent-permissions.test.ts": 42,
-      "src/shared/tui-agent-selection.test.ts": 47,
-      "src/shared/tui-agent-startup-kiro-resume.test.ts": 205,
-      "src/shared/tui-agent-startup.test.ts": 636,
+      "src/shared/agent-launch/permissions/tui-agent-auto-permissions.test.ts": 293,
+      "src/shared/agent-launch/startup/tui-agent-launch-command-argument-values.test.ts": 266,
+      "src/shared/agent-launch/startup/tui-agent-launch-command-override.test.ts": 63,
+      "src/shared/agent-launch/startup/tui-agent-launch-command-pick-flags.test.ts": 242,
+      "src/shared/agent-launch/permissions/tui-agent-permission-choice.test.ts": 1009,
+      "src/shared/agent-launch/permissions/tui-agent-permissions.test.ts": 42,
+      "src/shared/agent-launch/catalog/tui-agent-selection.test.ts": 47,
+      "src/shared/agent-launch/startup/tui-agent-startup-kiro-resume.test.ts": 205,
+      "src/shared/agent-launch/startup/tui-agent-startup.test.ts": 636,
      "src/shared/ui-locale.test.ts": 68,
      "src/shared/updated-at-order.test.ts": 81,
      "src/shared/usage-percentage-display-change-notice.test.ts": 35,
@@ -193,7 +193,7 @@ const CROSS_VERSION_WIRE_PREFIXES = [
  'src/main/runtime/rpc/ws-transport.ts',
  'src/shared/web-origin-security.ts',
  'src/shared/browser-client-host-placement',
-  'src/shared/agent-launch-intent',
+  'src/shared/agent-launch/contracts/agent-launch-intent',
  'src/shared/rpc-contract/agent-launch-params',
  'src/shared/agent-session/agent-session-wire',
  'src/shared/agent-session/view/structured-agent-session-projection.test.ts',
@@ -56,7 +56,7 @@ export const WINDOWS_BOUNDARY_TESTS = [
  'src/shared/__tests__/process-host/windows-cmd-shim-resolution.test.ts',
  'src/shared/__tests__/process-host/windows-cmd-shim-resolution.win32.test.ts',
  'src/shared/__tests__/process-host/windows-tree-kill-late-taskkill.win32.test.ts',
-  'src/shared/omp-fresh-launch-cmd.win32.test.ts',
+  'src/shared/agent-launch/startup/omp-fresh-launch-cmd.win32.test.ts',
  'src/shared/windows-batch-spawn.win32.test.ts',
  'src/main/agent-hooks/windows-hook-payload-delivery.test.ts',
  'src/main/agent-hooks/managed-hook-stdin-lifecycle.test.ts',
@@ -10,7 +10,7 @@ const contracts = [
  'src/main/ipc/pty/runtime/spawn-preflight-saved-resume.test.ts',
  'src/main/native-chat/agent-session-wire/structured-agent-session-terminal-writer-acquire.test.ts',
  'src/main/runtime/hook-status-resume-sleep-ordering.test.ts',
-  'src/shared/tui-agent-permission-choice.test.ts',
+  'src/shared/agent-launch/permissions/tui-agent-permission-choice.test.ts',
  'src/renderer/src/components/settings/agents/permissions/agent-permission-conversion-persistence.test.tsx',
  'src/main/runtime/rpc/methods/repo.test.ts',
  'src/renderer/src/components/tab-bar/use-new-tab-agent-menu-host-preferences.test.tsx',
@@ -47,7 +47,7 @@ precedence. Process-table command recognition still treats the waiting shell
 as a shell.

 Callers use shared launch-token and launch-recognition APIs. Prefix handling is
-contained in `src/shared/agent-command-line-intent.ts`; the setup-sequence resolver
+contained in `src/shared/agent-launch/startup/agent-command-line-intent.ts`; the setup-sequence resolver
 continues to return its supplied command. Launch recognition reuses the existing
 agent registry and headless filters without changing strict process recognition.

@@ -1,6 +1,6 @@
 import { translate } from '../i18n/mobile-i18n'
 import { assertAutomationExtraAgentArgs } from '../../../src/shared/automation-extra-agent-args-record'
-import { isTuiAgent } from '../../../src/shared/tui-agent-config'
+import { isTuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
 import type { RpcSendParams } from '../transport/rpc-params-contract'
 import type { MobileAutomation } from './automation-reply-schema'
 import type { AutomationTargets } from './automation-target-inventory'
@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
-import { isTuiAgent } from '../../../src/shared/tui-agent-config'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
+import { isTuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
 import { bindDeferredRpcOperation, defineRpcOperation } from '../transport/rpc-operation'
 import { rpcResultVariant } from '../transport/rpc-operation-result-reader'
 import { salvagedOptional } from '../../../src/shared/zod-salvage'
@@ -2,7 +2,7 @@ import { useEffect, useState } from 'react'
 import { KeyboardAvoidingView, Pressable, Text, View } from 'react-native'
 import { Sparkles } from 'lucide-react-native'
 import { getRuntimePathBasename } from '../../../src/shared/cross-platform-path'
-import { tuiAgentDisplayName } from '../../../src/shared/tui-agent-display-names'
+import { tuiAgentDisplayName } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
 import { useMobileTranslation } from '../i18n/use-mobile-translation'
 import { hostOs } from '../platform/host-os'
 import { canCommentOnGitHub } from '../session/mobile-diff-review-github'
@@ -1,5 +1,5 @@
 import type { ImageSourcePropType } from 'react-native'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'

 // Bundle desktop-shared favicons for offline/regional access (#8451), via Metro’s src/shared watch.
 // Keep literal require paths: Metro cannot resolve dynamic agent-id asset paths.
@@ -1,4 +1,4 @@
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import { translate } from '../i18n/mobile-i18n'
 import { MOBILE_AGENT_CATALOG } from '../tasks/mobile-agent-catalog'
 import { isMobileTuiAgentEnabled } from '../tasks/mobile-tui-agents'
@@ -1,5 +1,5 @@
 import { View } from 'react-native'
-import { tuiAgentDisplayName } from '../../../src/shared/tui-agent-display-names'
+import { tuiAgentDisplayName } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
 import { hostOs } from '../platform/host-os'
 import { ComposerSendButton } from '../components/composer-input/ComposerSendButton'
 import { MessageBox } from '../components/composer-input/MessageBox'
@@ -7,7 +7,7 @@ import { MobileAgentIcon } from '../components/MobileAgentIcon'
 import { TextField } from '../components/composer-input/TextField'
 import { MOBILE_AGENT_CATALOG } from '../tasks/mobile-agent-catalog'
 import type { TerminalQuickCommand } from '../../../src/shared/terminal-quick-command-types'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import { supportsTerminalAgentQuickCommand } from '../terminal/quick-commands'
 import { QuickCommandRow } from './QuickCommandRow'
 import { useMobileTranslation } from '../i18n/use-mobile-translation'
@@ -1,5 +1,5 @@
 import type { AgentStatusEntry } from '../../../src/shared/agent-status-types'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import { isMobileTerminalTabRunningAgent } from './mobile-terminal-tab-agent'

 export type AgentSendKeyboardDismissalTab = {
@@ -11,8 +11,8 @@ import {
  buildAiVaultRemoteResumeStartup,
  resolveAiVaultResumeHostShell
 } from '../../../src/shared/ai-vault-resume-host-startup'
-import { isTuiAgent } from '../../../src/shared/tui-agent-config'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import { isTuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import { parseWslUncPath } from '../../../src/shared/wsl-paths'
 import { resolveWindowsShellStartupFamily } from '../../../src/shared/windows-terminal-shell'
 import { RESUME_RPC_TIMEOUT_MS } from './ai-vault-resume-preparation'
@@ -3,24 +3,24 @@
 import {
  AGENT_LAUNCH_CHAT_OPTIONS_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_SURFACE_RUNTIME_CAPABILITY
-} from '../../../src/shared/agent-launch-runtime-capability'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-runtime-capability'
 import type {
  AgentLaunchPlacement,
  AgentLaunchPrompt,
  AgentLaunchResult
-} from '../../../src/shared/agent-launch-intent'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-intent'
 import { isStructuredAgentId } from '../../../src/shared/agent-session/lifecycle/agent-session-provider-handle-encoding'
-import { AGENT_LAUNCH_TAB_CLOSED_CODE } from '../../../src/shared/agent-launch-tab-closed'
+import { AGENT_LAUNCH_TAB_CLOSED_CODE } from '../../../src/shared/agent-launch/contracts/agent-launch-tab-closed'
 import { makePaneKey } from '../../../src/shared/stable-pane-id'
 import { createStructuredAgentSessionId } from '../../../src/shared/agent-session/structured-agent-session-create'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type { RpcClient } from '../transport/rpc-client'
 import { agentLaunchReplayRun } from '../tasks/mobile-workspace-create-operations'
 import { agentLaunchExistingParams, readAgentLaunchSupport } from '../tasks/agent-launch-request'
 import {
  classifyAgentLaunchReplayRefusal,
  isAgentLaunchReservationTakenRefusal
-} from '../../../src/shared/agent-launch-replay-refusal'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-replay-refusal'
 import { sendReplayingAmbiguousDelivery } from '../tasks/replay-on-ambiguous-delivery'
 import { structuredSessionOperationId } from './structured-session-operation-id'
 import { randomV4Uuid } from '../platform/random-v4-uuid'
@@ -2,7 +2,7 @@ import { terminalInputSend } from '../terminal/mobile-terminal-operations'
 import { createElement } from 'react'
 import { act, create, type ReactTestRenderer } from 'react-test-renderer'
 import { afterEach, beforeEach, expect, it, vi } from 'vitest'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type { RpcClient } from '../transport/rpc-client'
 import type { RpcResponse } from '../transport/types'
 import type { TerminalLiveInputSender } from '../terminal/terminal-live-input-sender'
@@ -1,10 +1,8 @@
-import type { TuiAgent } from '../../../src/shared/tui-agent'
-import {
-  filterEnabledMobileTuiAgents,
-  isMobileTuiAgent,
-  MOBILE_TUI_AGENT_AUTO_PICK_ORDER,
-  MOBILE_TUI_AGENT_LABELS
-} from '../tasks/mobile-tui-agents'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
+import { filterEnabledMobileTuiAgents } from '../tasks/mobile-tui-agents'
+import { isTuiAgent as isMobileTuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
+import { TUI_AGENT_AUTO_PICK_ORDER as MOBILE_TUI_AGENT_AUTO_PICK_ORDER } from '../../../src/shared/agent-launch/catalog/tui-agent-selection'
+import { TUI_AGENT_DISPLAY_NAMES as MOBILE_TUI_AGENT_LABELS } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'

 export type MobileNewTabAgentSettings = {
  defaultTuiAgent?: TuiAgent | 'blank' | null
@@ -1,7 +1,7 @@
 import type { MobileFileMedia } from '../files/mobile-file-media'
 import type { StructuredAgentId } from '../../../src/shared/agent-session/lifecycle/agent-session-provider-handle'
 import type { DiffComment } from '../../../src/shared/diff-comment-types'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type { AgentStatusEntry } from '../../../src/shared/agent-status-types'
 import type {
  RuntimeMobileSessionAgentTabStatus,
@@ -1,7 +1,7 @@
 import { stripLeadingAgentTitleDecoration } from '../../../src/shared/agent-title-decoration'
 import { redactKagiSessionToken } from '../../../src/shared/browser-url'
-import { TUI_AGENT_DISPLAY_NAMES } from '../../../src/shared/tui-agent-display-names'
-import { isTuiAgent } from '../../../src/shared/tui-agent-config'
+import { TUI_AGENT_DISPLAY_NAMES } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
+import { isTuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
 import { isBlankBrowserUrl } from '../browser/browser-url'
 import { translate } from '../i18n/mobile-i18n'
 import { agentDotState, type AgentDotState } from '../worktree/agent-row-display'
@@ -9,9 +9,9 @@ import {
  pickSourceControlLaunchAgent,
  readSourceControlLaunchRecipeAgentId
 } from '../../../src/shared/source-control-launch-agent-selection'
-import { filterEnabledTuiAgents } from '../../../src/shared/tui-agent-selection'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
-import { isMobileTuiAgent } from '../tasks/mobile-tui-agents'
+import { filterEnabledTuiAgents } from '../../../src/shared/agent-launch/catalog/tui-agent-selection'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
+import { isTuiAgent as isMobileTuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
 import { translate } from '../i18n/mobile-i18n'
 import type { MobileAgentLaunchContext } from './mobile-new-tab-agent-loader'

@@ -9,7 +9,7 @@ import {
  structuredAgentSessionCreateParams,
  type StructuredAgentSessionCreateParams
 } from '../../../src/shared/agent-session/structured-agent-session-create'
-import { TUI_AGENT_DISPLAY_NAMES } from '../../../src/shared/tui-agent-display-names'
+import { TUI_AGENT_DISPLAY_NAMES } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
 import { hasRuntimeRpcErrorCode } from '../../../src/shared/runtime-rpc-error-code'
 import type { RpcClient } from '../transport/rpc-client'
 import {
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { createTerminalTitleTracker } from '../../../src/shared/terminal-output-side-effects'
 import type { AgentStatusEntry } from '../../../src/shared/agent-status-types'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type { MobileSessionTab } from './mobile-session-route-types'
 import {
  getMobileSessionTabTitle,
@@ -4,7 +4,7 @@ import { isShellProcess } from '../../../src/shared/shell-process-detection'
 import { agentTypeToIconAgent } from '../../../src/shared/agent-type-icon-agent'
 import { resolveTabAgentFromSignalSnapshot } from '../../../src/shared/tab-agent-from-signals'
 import type { AgentStatusEntry } from '../../../src/shared/agent-status-types'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import { isBlankBrowserUrl } from '../browser/browser-url'
 import { translate } from '../i18n/mobile-i18n'
 import type { MobileSessionTab } from './mobile-session-route-types'
@@ -17,7 +17,7 @@ import {
 } from './transcript/mobile-native-chat-reply-reveals'
 import { MobileNativeChatRowOverlaysHost } from './transcript/MobileNativeChatRowOverlaysHost'
 import { nativeChatAskRequiresTerminal } from '../../../../src/shared/native-chat/native-chat-agent-support'
-import { tuiAgentDisplayName } from '../../../../src/shared/tui-agent-display-names'
+import { tuiAgentDisplayName } from '../../../../src/shared/agent-launch/catalog/tui-agent-display-names'
 import { MobileNativeChatNoticeContext } from '../mobile-native-chat-notice-context'
 import type { MobileNativeChatImageSource } from './visual/mobile-native-chat-image-preview'

@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest'
 import type { RpcClient } from '../../../transport/rpc-client'
 import type { RpcResponse, RpcSuccess } from '../../../transport/types'
 import { pasteMobileNativeChatImagePaths } from './mobile-native-chat-image-send'
-import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../../src/shared/agent-tui-input-clear'
+import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../../src/shared/agent-launch/startup/agent-tui-input-clear'

 function sendResult(accepted: boolean, id = 'send'): RpcSuccess {
  return { id, ok: true, result: { send: { accepted } }, _meta: { runtimeId: 'r' } }
@@ -1,7 +1,7 @@
 import { resetMobileNativeChatDraftInputsForTests } from './mobile-native-chat-draft-inputs'
 import { createElement } from 'react'
 import { act, create, type ReactTestRenderer } from 'react-test-renderer'
-import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../../src/shared/agent-tui-input-clear'
+import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../../src/shared/agent-launch/startup/agent-tui-input-clear'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { RpcClient } from '../../../transport/rpc-client'
 import type { RpcResponse, RpcSuccess } from '../../../transport/types'
@@ -46,7 +46,7 @@ import {
  AGENT_CHAT_PERMISSION_MODE_ICON_NAMES,
  AGENT_CHAT_PERMISSION_MODE_OPTION_ID,
  isAgentChatPermissionMode
-} from '../../../../../src/shared/agent-chat-permission-mode'
+} from '../../../../../src/shared/agent-launch/permissions/agent-chat-permission-mode'
 import type { MobileNativeChatSessionOptionsController } from './use-mobile-native-chat-session-options'
 import { sessionOptionPickerStyles as styles } from './mobile-native-chat-session-option-picker-styles'

@@ -1,4 +1,4 @@
-import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../../src/shared/agent-tui-input-clear'
+import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../../src/shared/agent-launch/startup/agent-tui-input-clear'
 import { createElement } from 'react'
 import { act, create, type ReactTestRenderer } from 'react-test-renderer'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -2,7 +2,7 @@ import { SquareTerminal } from 'lucide-react-native'
 import type { ActionSheetAction } from '../../components/ActionSheetModal'
 import { translate } from '../../i18n/mobile-i18n'
 import type { MobileSessionController } from '../use-mobile-session-controller'
-import { agentForksConversations } from '../../../../src/shared/agent-resume-argv'
+import { agentForksConversations } from '../../../../src/shared/agent-launch/startup/agent-resume-argv'
 import { SESSION_TABS_CHAT_FORK_CLI_RUNTIME_CAPABILITY } from '../../../../src/shared/session-tabs-runtime-capabilities'

 export function canOfferMobileNativeChatCliFork(args: {
@@ -17,7 +17,7 @@ import {
  type StructuredAgentSessionState
 } from '../../../../src/shared/agent-session/structured-agent-session-reducer'
 import { selectStructuredAgentTurnBars } from '../../../../src/shared/agent-session/view/structured-agent-session-turn-timing'
-import { TUI_AGENT_DISPLAY_NAMES } from '../../../../src/shared/tui-agent-display-names'
+import { TUI_AGENT_DISPLAY_NAMES } from '../../../../src/shared/agent-launch/catalog/tui-agent-display-names'
 import {
  buildMobileNativeChatTransientData,
  foldMobileNativeChatMessages
@@ -11,7 +11,7 @@ import {
  sendMobileNativeChatMessageWithOutcome,
  typeMobileNativeChatCommandWithOutcome
 } from './mobile-native-chat-send'
-import { buildAgentTuiClearInputForText } from '../../../../src/shared/agent-tui-input-clear'
+import { buildAgentTuiClearInputForText } from '../../../../src/shared/agent-launch/startup/agent-tui-input-clear'

 afterEach(() => vi.useRealTimers())

@@ -2,13 +2,13 @@ import type { RpcClient } from '../../transport/rpc-client'
 import { isRpcDeliveryUnknown } from '../../transport/rpc-delivery-ambiguity'
 import { isLogicalClientCutoverError } from '../../transport/stable-logical-rpc-client'
 import { nativeChatTerminalWrite } from '../mobile-session-write-operations'
-import { typeAgentTuiCommand } from '../../../../src/shared/agent-tui-command-typing'
+import { typeAgentTuiCommand } from '../../../../src/shared/agent-launch/startup/agent-tui-command-typing'
 import { readTerminalSendAcknowledgment } from '../../../../src/shared/terminal-send-acknowledgment'
 import {
  AGENT_TUI_CLEAR_MAX_LINES,
  countAgentTuiInputLines,
  buildAgentTuiClearInputForText
-} from '../../../../src/shared/agent-tui-input-clear'
+} from '../../../../src/shared/agent-launch/startup/agent-tui-input-clear'
 import { nativeChatTerminalDraftRead } from '../mobile-session-read-operations'

 export type MobileNativeChatRpcSender = Parameters<typeof nativeChatTerminalWrite.request>[0]
@@ -1,4 +1,4 @@
-import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../src/shared/agent-tui-input-clear'
+import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../src/shared/agent-launch/startup/agent-tui-input-clear'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { RpcClient } from '../../transport/rpc-client'
 import {
@@ -4,7 +4,7 @@ import { agentSessionVisibleFailureFacts } from '../../../../src/shared/agent-se
 import type { NativeChatTurnJournal } from '../../../../src/shared/native-chat/transcript/native-chat-turn-membership'
 import { dispatchWasWithdrawn } from '../../../../src/shared/agent-session/requests/structured-agent-session-dispatch-rejection'
 import { structuredAgentSessionRecordedRejectionParts } from '../../../../src/shared/agent-session/failures/structured-agent-session-rejection-words'
-import { tuiAgentDisplayName } from '../../../../src/shared/tui-agent-display-names'
+import { tuiAgentDisplayName } from '../../../../src/shared/agent-launch/catalog/tui-agent-display-names'

 const NO_NOTICES: ReadonlyMap<string, string> = new Map()

@@ -23,7 +23,7 @@ vi.mock('../mobile-native-chat-stale-input', () => ({

 import { useMobileNativeChatMessageSend } from './use-mobile-native-chat-message-send'
 import { resetMobileNativeChatTerminalWritesForTests } from '../mobile-native-chat-terminal-write-lock'
-import { buildAgentTuiClearInputForText } from '../../../../../src/shared/agent-tui-input-clear'
+import { buildAgentTuiClearInputForText } from '../../../../../src/shared/agent-launch/startup/agent-tui-input-clear'

 type Send = ReturnType<typeof useMobileNativeChatMessageSend>

@@ -1,4 +1,4 @@
-import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../src/shared/agent-tui-input-clear'
+import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../../src/shared/agent-launch/startup/agent-tui-input-clear'
 import { mobileNativeChatDraftDestination } from './composer/mobile-native-chat-draft-inputs'
 import { createElement } from 'react'
 import { act, create, type ReactTestRenderer } from 'react-test-renderer'
@@ -1,7 +1,7 @@
 import type { MobileQuickCommandLaunch } from '../terminal/quick-commands'
 import type { MobileSessionTab } from './mobile-session-route-types'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
-import { AGENT_LAUNCH_PLACEMENT_RUNTIME_CAPABILITY } from '../../../src/shared/agent-launch-runtime-capability'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
+import { AGENT_LAUNCH_PLACEMENT_RUNTIME_CAPABILITY } from '../../../src/shared/agent-launch/contracts/agent-launch-runtime-capability'
 import type { RpcClient } from '../transport/rpc-client'
 import { triggerError, triggerSuccess } from '../platform/haptics'
 import {
@@ -5,9 +5,9 @@ import {
  getDefaultSourceControlAiSettings,
  resolveSourceControlActionRecipe
 } from '../../../src/shared/source-control-ai'
-import { buildAgentStartupPlan } from '../../../src/shared/tui-agent-startup'
-import { resolveAgentStartupPlanInputs } from '../../../src/shared/agent-startup-plan-inputs'
-import { toAgentLaunchPreferences } from '../../../src/shared/agent-launch-preferences'
+import { buildAgentStartupPlan } from '../../../src/shared/agent-launch/startup/tui-agent-startup'
+import { resolveAgentStartupPlanInputs } from '../../../src/shared/agent-launch/startup/agent-startup-plan-inputs'
+import { toAgentLaunchPreferences } from '../../../src/shared/agent-launch/choices/agent-launch-preferences'
 import { AgentLaunchReplay } from '../../../src/shared/rpc-contract/agent-launch-params'
 import { AGENT_LAUNCH_UPDATE_REQUIRED_MESSAGE } from './mobile-existing-agent-launch'
 import {
@@ -3,7 +3,7 @@ import type {
  TerminalQuickCommandAction,
  TerminalQuickCommandScope
 } from '../../../src/shared/terminal-quick-command-types'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import {
  getTerminalQuickCommandBodySize,
  isAgentQuickCommand,
@@ -1,7 +1,7 @@
 import { z } from 'zod'
 import { salvagedOptional, salvagingArray } from '../../../src/shared/zod-salvage'
 import { AGENT_STATUS_STATES } from '../../../src/shared/agent-status-types'
-import { isTuiAgent } from '../../../src/shared/tui-agent-config'
+import { isTuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
 import {
  isMobileTerminalTabRunningAgent,
  resolveMobileTerminalTabOwnedAgentId
@@ -1,4 +1,4 @@
-import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../src/shared/agent-tui-input-clear'
+import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../src/shared/agent-launch/startup/agent-tui-input-clear'
 import { createElement } from 'react'
 import { act, create, type ReactTestRenderer } from 'react-test-renderer'
 import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest'
@@ -1,7 +1,7 @@
 import { useEffect, useState } from 'react'
 import type { SourceControlLaunchActionId } from '../../../src/shared/source-control-ai-actions'
 import type { RpcClient } from '../transport/rpc-client'
-import { MOBILE_TUI_AGENT_LABELS } from '../tasks/mobile-tui-agents'
+import { TUI_AGENT_DISPLAY_NAMES as MOBILE_TUI_AGENT_LABELS } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
 import {
  hostRefusesOtherRuntimeWorkspace,
  loadMobileAgentLaunchContext
@@ -1,4 +1,4 @@
-import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../src/shared/agent-tui-input-clear'
+import { AGENT_TUI_CLEAR_INPUT_MAX } from '../../../src/shared/agent-launch/startup/agent-tui-input-clear'
 import { createElement } from 'react'
 import { resetMobileNativeChatDraftInputsForTests } from './native-chat/composer/mobile-native-chat-draft-inputs'
 import { act, create, type ReactTestRenderer } from 'react-test-renderer'
@@ -1,11 +1,11 @@
 import { createElement } from 'react'
-import { AGENT_LAUNCH_PLACEMENT_RUNTIME_CAPABILITY } from '../../../src/shared/agent-launch-runtime-capability'
+import { AGENT_LAUNCH_PLACEMENT_RUNTIME_CAPABILITY } from '../../../src/shared/agent-launch/contracts/agent-launch-runtime-capability'
 import { act, create, type ReactTestRenderer } from 'react-test-renderer'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type {
  AgentLaunchOutcome,
  AgentLaunchPromptReceipt
-} from '../../../src/shared/agent-launch-intent'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-intent'
 import { parsePaneKey } from '../../../src/shared/stable-pane-id'
 import type { RpcClient } from '../transport/rpc-client'
 import { markRpcDeliveryUnknown } from '../transport/rpc-delivery-ambiguity'
@@ -10,7 +10,7 @@ import {
  structuredAgentSessionMessageSelection,
  structuredAgentSessionShownSnapshot
 } from '../../../src/shared/agent-session/options/structured-agent-session-option-view'
-import { agentChatPermissionModes } from '../../../src/shared/agent-chat-permission-mode'
+import { agentChatPermissionModes } from '../../../src/shared/agent-launch/permissions/agent-chat-permission-support'
 import { legacyHostPermissionDescriptor } from '../../../src/shared/agent-session/options/structured-agent-session-permission-option'
 import type { RpcClient } from '../transport/rpc-client'
 import type { StructuredAgentSessionHostSupport } from './mobile-structured-agent-session-host-support'
@@ -6,7 +6,7 @@ import { createStructuredQuestionProjection } from '../../../src/shared/structur
 import { projectStructuredAgentStartItem } from '../../../src/shared/structured-agent-start-projection'
 import { withNativeChatCutTurnNotices } from '../../../src/shared/native-chat/transcript/native-chat-cut-turn-notice'
 import { agentSessionTranscriptRows } from '../../../src/shared/agent-session/agent-session-context-clear'
-import { tuiAgentDisplayName } from '../../../src/shared/tui-agent-display-names'
+import { tuiAgentDisplayName } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
 import { mobileStructuredAgentSessionWorking } from './mobile-structured-agent-session-working'
 import { isFinalAgentSessionReadRefusal } from '../../../src/shared/agent-session/failures/structured-agent-session-read-refusal'
 import {
@@ -9,7 +9,7 @@ import { createStructuredAgentSessionOptionsReadOwner } from '../../../src/share
 import { BoundedMap } from '../../../src/shared/bounded-map'
 import type { RpcClient } from '../transport/rpc-client'
 import type { AgentSessionOptionCatalog } from '../../../src/shared/agent-session/options/agent-session-option-catalog-types'
-import { usesInstalledAgentModelCatalog } from '../../../src/shared/agent-model-catalog-ownership'
+import { usesInstalledAgentModelCatalog } from '../../../src/shared/agent-session/options/agent-model-catalog-ownership'
 import {
  createStructuredAgentSessionOptionState,
  structuredAgentSessionReportsAtFence
@@ -5,7 +5,7 @@ import { runningStructuredAgentSessionTurnId } from '../../../src/shared/agent-s
 import { mobileStructuredAgentSessionWorking } from './mobile-structured-agent-session-working'
 import { structuredSessionBackgroundTasksView } from '../../../src/shared/structured-session-background-tasks-view'
 import { agentSessionVisibleFailureFacts } from '../../../src/shared/agent-session/failures/agent-session-visible-failures'
-import { tuiAgentDisplayName } from '../../../src/shared/tui-agent-display-names'
+import { tuiAgentDisplayName } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
 import { pendingPromptsAllUnanswerableHere } from '../../../src/shared/agent-session/agent-session-approval-subject'
 import {
  SkillRefLimitError,
@@ -1,6 +1,6 @@
 import { useEffect, useState } from 'react'
 import type { SourceControlLaunchActionId } from '../../../src/shared/source-control-ai-actions'
-import { tuiAgentDisplayName } from '../../../src/shared/tui-agent-display-names'
+import { tuiAgentDisplayName } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
 import type { RpcClient } from '../transport/rpc-client'
 import type { ConnectionState } from '../transport/types'
 import {
@@ -21,7 +21,7 @@ import {
 import {
  AGENT_LAUNCH_REPLAY_REQUIRED_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_RUNTIME_CAPABILITY
-} from '../../../src/shared/agent-launch-runtime-capability'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-runtime-capability'
 import {
  launchAgentInExistingWorkspace,
  reserveMobileAgentLaunch
@@ -6,12 +6,12 @@ import {
  type AgentLaunchPlacement,
  type AgentLaunchPrompt,
  type AgentLaunchResult
-} from '../../../src/shared/agent-launch-intent'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-intent'
 import {
  AGENT_LAUNCH_REPLAY_REQUIRED_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_RUNTIME_CAPABILITY
-} from '../../../src/shared/agent-launch-runtime-capability'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-runtime-capability'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type { RpcSendParams } from '../transport/rpc-params-contract'
 import type { WorkspaceCreateParams } from './workspace-create-params'

@@ -112,5 +112,3 @@ export function isAgentLaunchUnsupportedRefusal(error: {
  }
  return (error.message ?? '').includes('agent_launch_unsupported')
 }
-
-export { isAgentLaunchReplayUnsupportedRefusal } from '../../../src/shared/agent-launch-replay-refusal'
@@ -1,4 +1,4 @@
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type { RpcClient } from '../transport/rpc-client'
 import { createWorktreeWithNameRetry, type WorktreeCreateResult } from './worktree-create-retry'
 import type { WorktreeCreateAgentLaunch } from './agent-launch-request'
@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest'

-import { TUI_AGENT_CONFIG } from '../../../src/shared/tui-agent-config'
-import { TUI_AGENT_DISPLAY_NAMES } from '../../../src/shared/tui-agent-display-names'
-import { TUI_AGENT_AUTO_PICK_ORDER } from '../../../src/shared/tui-agent-selection'
+import { TUI_AGENT_CONFIG } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
+import { TUI_AGENT_DISPLAY_NAMES } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
+import { TUI_AGENT_AUTO_PICK_ORDER } from '../../../src/shared/agent-launch/catalog/tui-agent-selection'
 import { MOBILE_AGENT_CATALOG } from './mobile-agent-catalog'

 describe('mobile agent catalog', () => {
@@ -1,9 +1,7 @@
-import type { TuiAgent } from '../../../src/shared/tui-agent'
-import {
-  MOBILE_TUI_AGENT_AUTO_PICK_ORDER,
-  MOBILE_TUI_AGENT_FAVICON_DOMAINS,
-  MOBILE_TUI_AGENT_LABELS
-} from './mobile-tui-agents'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
+import { TUI_AGENT_AUTO_PICK_ORDER as MOBILE_TUI_AGENT_AUTO_PICK_ORDER } from '../../../src/shared/agent-launch/catalog/tui-agent-selection'
+import { MOBILE_TUI_AGENT_FAVICON_DOMAINS } from './mobile-tui-agents'
+import { TUI_AGENT_DISPLAY_NAMES as MOBILE_TUI_AGENT_LABELS } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'

 export type MobileAgentCatalogEntry = {
  id: TuiAgent
@@ -26,7 +26,7 @@ import { readNewWorktreeRuntimeCapabilities } from './worktree-create-capability
 import {
  AGENT_LAUNCH_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_REPLAY_REQUIRED_RUNTIME_CAPABILITY
-} from '../../../src/shared/agent-launch-runtime-capability'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-runtime-capability'

 const createStructuredSession = vi.fn()
 vi.mock('../../../src/main/runtime/rpc/methods/structured-agent-session-create', () => ({
@@ -141,7 +141,7 @@ export { hasSettledHostRepoList } from './host-repo-list'
 export { useHostRepoList } from './use-host-repo-list'
 export { isHostedTaskRepo, reconcileRepoSelection } from './hosted-repo-selection'
 export type { LinearMobileIssue } from './linear-mobile-issue-read'
-export { MOBILE_TUI_AGENT_AUTO_PICK_ORDER } from './mobile-tui-agents'
+
 export { resolveComposerBranchSelection } from './mobile-composer-branch-selection'
 export {
  clearMobileTaskCopyFeedbackTimer,
@@ -154,7 +154,7 @@ export type {
 } from '../../../src/shared/github/pull-request-types'
 export type { PersistedTrustedOrcaHooks } from '../../../src/shared/orca-yaml-hook-types'
 export type { SparsePreset } from '../../../src/shared/worktree/create-types'
-export type { TuiAgent } from '../../../src/shared/tui-agent'
+
 export type { SshConnectionState } from '../../../src/shared/ssh-types'
 export type { HostedReviewDecision } from '../../../src/shared/hosted-review'
 export {
@@ -1,6 +1,6 @@
 import type { DetailComment } from './mobile-tasks-provider-detail-types'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type {
-  TuiAgent,
  TaskProvider,
  GitHubProjectSettings,
  GitHubProjectRef
@@ -1,17 +1,16 @@
-import type { TuiAgent } from '../../../src/shared/tui-agent'
-import { isTuiAgent } from '../../../src/shared/tui-agent-config'
-import { TUI_AGENT_DISPLAY_NAMES } from '../../../src/shared/tui-agent-display-names'
-import { TUI_AGENT_FAVICON_DOMAINS } from '../../../src/shared/tui-agent-favicon-domains'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
+import { isTuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
+import { TUI_AGENT_DISPLAY_NAMES } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'
+import { TUI_AGENT_FAVICON_DOMAINS } from '../../../src/shared/agent-launch/catalog/tui-agent-favicon-domains'
 import {
-  TUI_AGENT_AUTO_PICK_ORDER,
  filterEnabledTuiAgents,
  isTuiAgentEnabled,
  pickTuiAgent
-} from '../../../src/shared/tui-agent-selection'
+} from '../../../src/shared/agent-launch/catalog/tui-agent-selection'

 // Reuse the shared registry; Metro cannot load renderer ?url icons, so the phone draws favicons.
-export const MOBILE_TUI_AGENT_AUTO_PICK_ORDER = TUI_AGENT_AUTO_PICK_ORDER
-export const MOBILE_TUI_AGENT_LABELS: Record<TuiAgent, string> = TUI_AGENT_DISPLAY_NAMES
+
+const MOBILE_TUI_AGENT_LABELS: Record<TuiAgent, string> = TUI_AGENT_DISPLAY_NAMES

 // Desktop draws these agents with built-in icons; the phone has only favicons for them.
 export const MOBILE_TUI_AGENT_FAVICON_DOMAINS: Partial<Record<TuiAgent, string>> = {
@@ -25,8 +24,6 @@ export const MOBILE_TUI_AGENT_FAVICON_DOMAINS: Partial<Record<TuiAgent, string>>
  droid: 'factory.ai'
 }

-export const isMobileTuiAgent: (value: unknown) => value is TuiAgent = isTuiAgent
-
 /** A newer host's agent reads by its id until this build knows its name. */
 export function mobileTuiAgentLabel(agent: string): string {
  return isTuiAgent(agent) ? MOBILE_TUI_AGENT_LABELS[agent] : agent
@@ -2,7 +2,7 @@ import { z } from 'zod'
 import {
  isAgentLaunchResult,
  type AgentLaunchResult
-} from '../../../src/shared/agent-launch-intent'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-intent'
 import { bindDeferredRpcOperation, defineRpcOperation } from '../transport/rpc-operation'
 import { rpcResultVariant } from '../transport/rpc-operation-result-reader'
 import {
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import type { RpcClient } from '../transport/rpc-client'
 import { createFakeRpcClient } from '../mobile-web-shell/bridge-host-test-fakes'
-import type { AgentLaunchResult } from '../../../src/shared/agent-launch-intent'
+import type { AgentLaunchResult } from '../../../src/shared/agent-launch/contracts/agent-launch-intent'
 import { createWorkspaceFromComposerSource } from './source-workspace-create'
 import type { MobileComposerCreateSelection } from './mobile-composer-source-types'
 import { WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS } from './worktree-create-idempotency-policy'
@@ -1,4 +1,4 @@
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type { RpcClient } from '../transport/rpc-client'
 import { resolveComposerMrBase, resolveComposerPrBase } from './composer-source-base-resolve'
 import type {
@@ -2,10 +2,8 @@ import type { ProjectMetadataLoadingModel } from './use-mobile-tasks-project-met
 import { useMobileTranslation } from '../i18n/use-mobile-translation'
 import {
  type BaseRefSearchResult,
-  MOBILE_TUI_AGENT_AUTO_PICK_ORDER,
  MobileAgentIcon,
  type PickerOption,
-  type TuiAgent,
  type WorkspaceAgentChoice,
  deriveWorkspaceSshGate,
  filterWorkspaceAgents,
@@ -16,6 +14,8 @@ import {
  useMemo,
  workspaceAgentLabel
 } from './mobile-tasks-dependencies'
+import { TUI_AGENT_AUTO_PICK_ORDER as MOBILE_TUI_AGENT_AUTO_PICK_ORDER } from '../../../src/shared/agent-launch/catalog/tui-agent-selection'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import {
  type ActionableTaskItem,
  type RepoSummary,
@@ -1,13 +1,13 @@
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import { translate } from '../i18n/mobile-i18n'
 import {
  filterEnabledMobileTuiAgents,
-  isMobileTuiAgent,
  isMobileTuiAgentEnabled,
-  MOBILE_TUI_AGENT_AUTO_PICK_ORDER,
-  MOBILE_TUI_AGENT_LABELS,
  pickMobileTuiAgent
 } from './mobile-tui-agents'
+import { isTuiAgent as isMobileTuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent-config'
+import { TUI_AGENT_AUTO_PICK_ORDER as MOBILE_TUI_AGENT_AUTO_PICK_ORDER } from '../../../src/shared/agent-launch/catalog/tui-agent-selection'
+import { TUI_AGENT_DISPLAY_NAMES as MOBILE_TUI_AGENT_LABELS } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'

 export type WorkspaceAgentChoice = TuiAgent | 'blank'

@@ -1,4 +1,4 @@
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type {
  CreateSparseCheckoutRequest,
  SetupDecision
@@ -3,7 +3,7 @@ import {
  AGENT_LAUNCH_REPLAY_REQUIRED_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_REPLAY_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_RUNTIME_CAPABILITY
-} from '../../../src/shared/agent-launch-runtime-capability'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-runtime-capability'
 import type { RpcClient } from '../transport/rpc-client'
 import { LogicalClientCutoverError } from '../transport/stable-logical-rpc-client'
 import { readNewWorktreeRuntimeCapabilities } from './worktree-create-capability'
@@ -1,5 +1,5 @@
 import { translate } from '../i18n/mobile-i18n'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import type { RpcClient } from '../transport/rpc-client'
 import type { RpcResponse } from '../transport/types'
 import {
@@ -15,11 +15,11 @@ import {
 } from '../../../src/shared/new-workspace/worktree-create-retry-policy'
 import {
  agentLaunchCreateParams,
-  isAgentLaunchReplayUnsupportedRefusal,
  isAgentLaunchUnsupportedRefusal,
  readAgentLaunchCreateOutcome,
  type WorktreeCreateAgentLaunch
 } from './agent-launch-request'
+import { isAgentLaunchReplayUnsupportedRefusal } from '../../../src/shared/agent-launch/contracts/agent-launch-replay-refusal'
 import { structuredSessionOperationId } from '../session/structured-session-operation-id'
 import { WORKTREE_CREATE_TIMEOUT_MS } from './workspace-create-timeout'
 import type { WorkspaceCreateParams } from './workspace-create-params'
@@ -1,5 +1,5 @@
 import type { TerminalQuickCommand } from '../../../src/shared/terminal-quick-command-types'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'
 import {
  applyTerminalQuickCommandMutation,
  flattenTerminalQuickCommand,
@@ -18,7 +18,7 @@ import {
  terminalQuickCommandAgentPromptMaxLength
 } from '../../../src/shared/terminal-quick-command-prompt-limit'
 import { TERMINAL_QUICK_COMMANDS_RUNTIME_CAPABILITY } from '../../../src/shared/protocol-version'
-import { MOBILE_TUI_AGENT_LABELS } from '../tasks/mobile-tui-agents'
+import { TUI_AGENT_DISPLAY_NAMES as MOBILE_TUI_AGENT_LABELS } from '../../../src/shared/agent-launch/catalog/tui-agent-display-names'

 // Reuse the pure desktop command logic; renderer-only labels and native truncation stay here.
 export {
@@ -1,5 +1,5 @@
 import type { ImageSourcePropType } from 'react-native'
-import type { TuiAgent } from '../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../src/shared/agent-launch/catalog/tui-agent'

 export const MOBILE_AGENT_ICON_ASSETS: Partial<Record<TuiAgent, ImageSourcePropType>> = {
  openclaude: 1,
@@ -8,7 +8,7 @@ import type {
  MobileSessionTabType,
  Terminal
 } from '../../../session/mobile-session-route-types'
-import type { TuiAgent } from '../../../../../src/shared/tui-agent'
+import type { TuiAgent } from '../../../../../src/shared/agent-launch/catalog/tui-agent'
 import { SESSION_TABS_SPLIT_GROUP_PLACEMENT_RUNTIME_CAPABILITY } from '../../../../../src/shared/protocol-version'

 const PREVIOUS_HANDLE = 'terminal-0'
@@ -21,7 +21,7 @@ import {
  AGENT_LAUNCH_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_TAB_CLOSED_CLIENT_CAPABILITY,
  AGENT_LAUNCH_UNSTARTED_TAB_CLIENT_CAPABILITY
-} from '../../../src/shared/agent-launch-runtime-capability'
+} from '../../../src/shared/agent-launch/contracts/agent-launch-runtime-capability'
 import { AGENT_SESSION_OPTIONAL_MODEL_CLIENT_CAPABILITY } from '../../../src/shared/agent-session/options/agent-session-optional-model-capability'
 import { remoteRuntimeClientCapabilities } from '../../../src/shared/remote-runtime/remote-runtime-client-capabilities'
 import { AGENT_SESSION_CREATE_MESSAGE_RUNTIME_CAPABILITY } from '../../../src/shared/agent-session/agent-session-create-capabilities'
@@ -10,7 +10,7 @@ import { z } from 'zod'
 import {
  AGENT_LAUNCH_RUNTIME_CAPABILITIES,
  AGENT_LAUNCH_SURFACE_RUNTIME_CAPABILITY
-} from '../shared/agent-launch-runtime-capability'
+} from '../shared/agent-launch/contracts/agent-launch-runtime-capability'
 import { agentLaunchFixture } from './agent-launch-test-fixtures'

 it('real CLI processes carry surface choices and refuse invalid or unsupported picks before mutation', async () => {
@@ -1,5 +1,5 @@
 import { RuntimeClientError, RuntimeRpcFailureError } from './runtime-client'
-import { classifyAgentLaunchReplayRefusal } from '../shared/agent-launch-replay-refusal'
+import { classifyAgentLaunchReplayRefusal } from '../shared/agent-launch/contracts/agent-launch-replay-refusal'
 import {
  recoverableOrchestrationArgs,
  resolveOrchestrationCliExecutable
@@ -1,21 +1,27 @@
 // agent.launch shares desktop/mobile policy; absent --surface uses the host's Chat | CLI choice for the agent.

 import { randomUUID } from 'node:crypto'
-import type { AgentLaunchPrompt, AgentLaunchResult } from '../shared/agent-launch-intent'
-import { AGENT_LAUNCH_SURFACES, type AgentLaunchSurface } from '../shared/agent-launch-surface'
-import { checkAgentLaunchModelPreferences } from '../shared/agent-launch-model-preferences'
+import type {
+  AgentLaunchPrompt,
+  AgentLaunchResult
+} from '../shared/agent-launch/contracts/agent-launch-intent'
+import {
+  AGENT_LAUNCH_SURFACES,
+  type AgentLaunchSurface
+} from '../shared/agent-launch/contracts/agent-launch-surface'
+import { checkAgentLaunchModelPreferences } from '../shared/agent-launch/choices/agent-launch-model-preferences'
 import {
  AGENT_LAUNCH_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_PROMPT_CARRY_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_LOCAL_PRESENTATION_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_REPLAY_REQUIRED_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_SURFACE_RUNTIME_CAPABILITY
-} from '../shared/agent-launch-runtime-capability'
+} from '../shared/agent-launch/contracts/agent-launch-runtime-capability'
 import { createStructuredAgentSessionOperationId } from '../shared/agent-session/lifecycle/structured-agent-session-mutation'
 import { parseAgentSessionOperationTimestamp } from '../shared/agent-session/agent-session-host-authority'
 import type { RuntimeStatus } from '../shared/runtime-types'
-import type { TuiAgent } from '../shared/tui-agent'
-import { isTuiAgent } from '../shared/tui-agent-config'
+import type { TuiAgent } from '../shared/agent-launch/catalog/tui-agent'
+import { isTuiAgent } from '../shared/agent-launch/catalog/tui-agent-config'
 import {
  getOptionalStringFlag,
  getRequiredStringFlag,
@@ -1,4 +1,4 @@
-import { AGENT_LAUNCH_RUNTIME_CAPABILITIES } from '../shared/agent-launch-runtime-capability'
+import { AGENT_LAUNCH_RUNTIME_CAPABILITIES } from '../shared/agent-launch/contracts/agent-launch-runtime-capability'
 import { okFixture } from './test-fixtures'

 export function agentLaunchHostFixture() {
@@ -1,5 +1,5 @@
 import { resolve as resolvePath } from 'node:path'
-import type { TuiAgent } from '../shared/tui-agent'
+import type { TuiAgent } from '../shared/agent-launch/catalog/tui-agent'
 import {
  isPathInsideOrEqual,
  normalizeRuntimePathForComparison
@@ -3,14 +3,14 @@ import {
  normalizeTaskSourceContext,
  type TaskSourceContext
 } from '../../shared/task-source-context'
-import type { TuiAgent } from '../../shared/tui-agent'
+import type { TuiAgent } from '../../shared/agent-launch/catalog/tui-agent'
 import {
  DEFAULT_AUTOMATION_PRECHECK_TIMEOUT_SECONDS,
  MAX_AUTOMATION_PRECHECK_TIMEOUT_SECONDS
 } from '../../shared/automation-precheck'
 import { buildAutomationRrule } from '../../shared/automation-schedule-occurrences'
 import { isValidAutomationSchedule } from '../../shared/automation-schedule-parsing'
-import { isTuiAgent } from '../../shared/tui-agent-config'
+import { isTuiAgent } from '../../shared/agent-launch/catalog/tui-agent-config'
 import {
  getOptionalPositiveIntegerFlag,
  getOptionalStringFlag,
@@ -5,7 +5,7 @@ import {
 import {
  EXTRA_AGENT_ARGS_HOST_UPDATE_REQUIRED,
  hasExtraAgentArgs
-} from '../../shared/automation-extra-agent-args'
+} from '../../shared/agent-launch/startup/automation-extra-agent-args'
 import type { RuntimeStatus } from '../../shared/runtime-types'
 import type { RuntimeClient } from '../runtime-client'
 import { RuntimeClientError } from '../runtime-client'
@@ -1,10 +1,10 @@
 // Use agent.launch for surface/model/effort; older hosts fall back to the create startup terminal.

-import type { AgentLaunchResult } from '../../shared/agent-launch-intent'
+import type { AgentLaunchResult } from '../../shared/agent-launch/contracts/agent-launch-intent'
 import {
  AGENT_LAUNCH_LOCAL_PRESENTATION_RUNTIME_CAPABILITY,
  AGENT_LAUNCH_PROMPT_CARRY_RUNTIME_CAPABILITY
-} from '../../shared/agent-launch-runtime-capability'
+} from '../../shared/agent-launch/contracts/agent-launch-runtime-capability'
 import type { RuntimeWorktreeCreateResult, RuntimeWorktreeRecord } from '../../shared/runtime-types'
 import {
  callAgentLaunch,
@@ -28,7 +28,7 @@ import {
  resolveWorktreeCreateCwdContext,
  resolveCurrentWorktreeSelector
 } from '../selectors'
-import type { TuiAgent } from '../../shared/tui-agent'
+import type { TuiAgent } from '../../shared/agent-launch/catalog/tui-agent'
 import { parseCliAgent, readCliAgentLaunch } from '../agent-launch-request'
 import { createWorktreeWithAgent } from './worktree-create-agent-launch'
 import { printLineageSummary } from './worktree-lineage-summary'
@@ -7,7 +7,7 @@ import {
 import { quoteWindowsCmdArgument } from '@orca/process-host/windows-command-line'
 import { quotePowerShellNativeArgument } from '../shared/powershell-native-argument'
 import { resolveWindowsShellStartupFamily } from '../shared/windows-terminal-shell'
-import type { AgentStartupShell } from '../shared/tui-agent-startup-shell'
+import type { AgentStartupShell } from '../shared/agent-launch/startup/tui-agent-startup-shell'

 export function orchestrationMutationRecoveryError(
  error: unknown,
@@ -1,5 +1,5 @@
 import { SKILL_INSTALL_RESULT_V2_CAPABILITY } from '../../shared/skill-install-capability'
-import { AGENT_LAUNCH_RUNTIME_CAPABILITY } from '../../shared/agent-launch-runtime-capability'
+import { AGENT_LAUNCH_RUNTIME_CAPABILITY } from '../../shared/agent-launch/contracts/agent-launch-runtime-capability'
 import { createServer, type Server } from 'node:http'
 import { mkdtempSync } from 'node:fs'
 import { tmpdir } from 'node:os'
@@ -4,7 +4,7 @@ import type {
  RuntimeOrchestrationEnvelope
 } from '../../shared/runtime-rpc-envelope'
 import { RemoteRuntimeClientError } from '../../shared/remote-runtime/remote-runtime-client-error'
-import { AGENT_LAUNCH_RUNTIME_CAPABILITY } from '../../shared/agent-launch-runtime-capability'
+import { AGENT_LAUNCH_RUNTIME_CAPABILITY } from '../../shared/agent-launch/contracts/agent-launch-runtime-capability'
 import {
  sendRemoteRuntimeRequest,
  sendRemoteRuntimeRequestWithStatusPreflight
@@ -8,9 +8,9 @@ import { ANTIGRAVITY_ACP_DIALECT } from './acp-dialects/antigravity-dialect'
 import { directoryAccountBinding, type AcpAccountBinding } from './acp-account-binding'
 import { openCodeAcpAccountBinding } from '../opencode/opencode-structured-account-home'
 import { scrubOpenCodeAcpEnvironment } from '../opencode/opencode-acp-environment'
-import type { TuiAgent } from '../../shared/tui-agent'
+import type { TuiAgent } from '../../shared/agent-launch/catalog/tui-agent'
 import type { AgentSessionModelOption } from '../../shared/agent-session/agent-session-wire'
-import type { AgentChatPermissionMode } from '../../shared/agent-chat-permission-mode'
+import type { AgentChatPermissionMode } from '../../shared/agent-launch/permissions/agent-chat-permission-mode'
 import type { InitializeResponse } from './generated/acp-protocol.generated'
 import { compareAppVersions } from '../../shared/app-version'
 import type { ManagedRuntime } from '../node-runtime/managed-runtime-release'
@@ -6,7 +6,7 @@ import { join } from 'node:path'
 import { vi } from 'vitest'
 import { z } from 'zod'
 import type { AgentJournalMessageItem } from '../../shared/agent-session/journal/agent-session-journal-types'
-import type { AgentChatPermissionChoice } from '../../shared/agent-chat-permission-mode'
+import type { AgentChatPermissionChoice } from '../../shared/agent-launch/permissions/agent-chat-permission-mode'
 import type { StructuredAgentSessionLifecycleEvent } from '../native-chat/agent-session-wire/structured-agent-session-adapter'
 import type { StructuredAgentSessionProviderOpenResult } from '../native-chat/agent-session-wire/structured-agent-session-provider-open-contract'
 import {
@@ -1,7 +1,7 @@
 import type { StructuredAgentDefinition } from '../native-chat/agent-session-wire/structured-agent-definition'
 import type { AcpLaunchSpec } from './acp-launch-specs'
-import { TUI_AGENT_DISPLAY_NAMES } from '../../shared/tui-agent-display-names'
-import { isTuiAgent } from '../../shared/tui-agent-config'
+import { TUI_AGENT_DISPLAY_NAMES } from '../../shared/agent-launch/catalog/tui-agent-display-names'
+import { isTuiAgent } from '../../shared/agent-launch/catalog/tui-agent-config'

 export function acpAgentName(agent: string): string {
  return isTuiAgent(agent) ? TUI_AGENT_DISPLAY_NAMES[agent] : agent
@@ -28,7 +28,7 @@ import {
  copyBesidePinnedMembers,
  resolveInstalledRuntimeRelease
 } from '../node-runtime/managed-runtime-release'
-import { hasExplicitTuiLaunchCommand } from '../../shared/tui-agent-launch-command-override'
+import { hasExplicitTuiLaunchCommand } from '../../shared/agent-launch/startup/tui-agent-launch-command-override'
 import { readAgentJournalTurn } from '../../shared/agent-session/lifecycle/agent-session-turn-record'
 import type { JournalLoad } from '../native-chat/agent-session-journal/journal-open'
 import {
@@ -14,7 +14,7 @@ import type { AgentJournalDispatchRejection } from '../../shared/agent-session/f
 import type { AcpLaunchSpec } from './acp-launch-specs'
 import type { ConnectAcpAgent } from './acp-structured-connection'
 import type { AgentChildWorkEvidence } from '../../shared/agent-status-child-work-evidence'
-import type { AgentChatPermissionChoice } from '../../shared/agent-chat-permission-mode'
+import type { AgentChatPermissionChoice } from '../../shared/agent-launch/permissions/agent-chat-permission-mode'

 // Grace begins at cancellation, before process close.
 export const ACP_STOP_GRACE_MS = 4_000
@@ -3,7 +3,7 @@ import {
  getManagedAgentHookTarget,
  isManagedAgentHookTarget
 } from '../../shared/managed-agent-hook-targets'
-import { normalizeDisabledTuiAgents } from '../../shared/tui-agent-selection'
+import { normalizeDisabledTuiAgents } from '../../shared/agent-launch/catalog/tui-agent-selection'
 import type { GlobalSettings } from '../../shared/global-settings-types'
 import {
  isAgentStatusHooksEnabled,
@@ -4,9 +4,9 @@ import {
  isSafeOverrideExecutableToken
 } from '../../shared/managed-agent-command-token'
 import { MANAGED_AGENT_HOOK_TARGETS } from '../../shared/managed-agent-hook-targets'
-import { normalizeDisabledTuiAgents } from '../../shared/tui-agent-selection'
+import { normalizeDisabledTuiAgents } from '../../shared/agent-launch/catalog/tui-agent-selection'
 import type { GlobalSettings } from '../../shared/global-settings-types'
-import type { TuiAgentDetectionCommand } from '../../shared/tui-agent-detection-commands'
+import type { TuiAgentDetectionCommand } from '../../shared/agent-launch/catalog/tui-agent-detection-commands'
 import { parseClaudeCliVersionOutput } from '../claude/claude-hook-event-versions'

 export type ManagedHookDetectionSettings = Partial<
@@ -5,7 +5,7 @@ import { expect, it } from 'vitest'
 import { normalizeHookPayload } from '../../shared/agent-hook-listener'
 import { createHookListenerState } from '../../shared/agent-hook-listener/listener-state'
 import { resumeRecordFromStatus } from '../../shared/agent-resume-record-from-status'
-import { getAgentResumeArgv } from '../../shared/agent-resume-argv'
+import { getAgentResumeArgv } from '../../shared/agent-launch/startup/agent-resume-argv'
 import { TRANSCRIPT_MAX_SCAN_BYTES } from '../../shared/agent-hook-listener/transcript-reader'
 import { AgentHookServer } from './server'
 import { buildBody, PANE } from './server.test-fixtures'
@@ -5,7 +5,7 @@ import { expect, it } from 'vitest'
 import { normalizeHookPayload } from '../../shared/agent-hook-listener'
 import { createHookListenerState } from '../../shared/agent-hook-listener/listener-state'
 import { resumeRecordFromStatus } from '../../shared/agent-resume-record-from-status'
-import { getAgentResumeArgv } from '../../shared/agent-resume-argv'
+import { getAgentResumeArgv } from '../../shared/agent-launch/startup/agent-resume-argv'
 import { AgentHookServer } from './server'
 import { type Body, buildBody, PANE, postHookEvent } from './server.test-fixtures'

@@ -5,7 +5,7 @@ import { expect, it } from 'vitest'
 import { normalizeHookPayload } from '../../shared/agent-hook-listener'
 import { createHookListenerState } from '../../shared/agent-hook-listener/listener-state'
 import { resumeRecordFromStatus } from '../../shared/agent-resume-record-from-status'
-import { getAgentResumeArgv } from '../../shared/agent-resume-argv'
+import { getAgentResumeArgv } from '../../shared/agent-launch/startup/agent-resume-argv'
 import type { AgentHookRelayEnvelope } from '../../shared/agent-hook-relay'
 import { RelayAgentHookServer } from '../../wsl-guest/agent-hook-server'
 import { AgentHookServer } from './server'
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { AgentHookServer } from './server'
 import { buildBody, PANE, postHookEvent } from './server.test-fixtures'
 import { buildRuntimeMobileAgentStatus } from '../runtime/runtime-mobile-agent-status-builder'
-import { getAgentResumeArgv } from '../../shared/agent-resume-argv'
+import { getAgentResumeArgv } from '../../shared/agent-launch/startup/agent-resume-argv'
 import type { probeAgentProcessPresence } from '../../shared/agent-process-presence-probe'

 vi.mock('../telemetry/client', () => ({ track: vi.fn() }))
@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { AgentHookServer } from './server'
 import { parseAgentHookEndpointFile } from '../../shared/agent-hook-endpoint-file'
-import { OPENCODE_STARTUP_PROMPT_CLAIM_PATH } from '../../shared/opencode-startup-prompt'
+import { OPENCODE_STARTUP_PROMPT_CLAIM_PATH } from '../../shared/agent-launch/startup/opencode-startup-prompt'
 import { PANE } from './server.test-fixtures'

 describe('startup prompt control with status hooks disabled', () => {
@@ -4,7 +4,7 @@ import { IncomingMessage, ServerResponse } from 'node:http'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { HookTransportInterferenceReport } from '../../shared/agent-hook-transport-interference'
 import { AgentHookServer } from './server'
-import { OPENCODE_STARTUP_PROMPT_CLAIM_PATH } from '../../shared/opencode-startup-prompt'
+import { OPENCODE_STARTUP_PROMPT_CLAIM_PATH } from '../../shared/agent-launch/startup/opencode-startup-prompt'
 import { HOOK_REQUEST_SLOWLORIS_MS } from '../../shared/agent-hook-listener/listener-limits'

 async function postTruncatedHook(
@@ -15,7 +15,7 @@ import { isHookRequestTruncatedError } from '../../../shared/agent-hook-transpor
 import { clearAllListenerCaches } from '../../../shared/agent-hook-listener/listener-state'
 import { trackEmptyPaneKeyHook } from './server-transport-rules'
 import { AgentHookServerStatusHookLifecycle } from './server-status-hook-lifecycle'
-import { OPENCODE_STARTUP_PROMPT_CLAIM_PATH } from '../../../shared/opencode-startup-prompt'
+import { OPENCODE_STARTUP_PROMPT_CLAIM_PATH } from '../../../shared/agent-launch/startup/opencode-startup-prompt'
 import { CLAUDE_AGENT_VIEW_PATH } from '../../../shared/claude-agent-view'
 import { respondAfterAgentToolPluginHooks } from '../agent-tool-plugin-hooks'

@@ -1,5 +1,5 @@
 import type { AgentKind } from '../../../shared/telemetry-events'
-import { getAgentResumeArgv } from '../../../shared/agent-resume-argv'
+import { getAgentResumeArgv } from '../../../shared/agent-launch/startup/agent-resume-argv'
 import type { AgentProviderSessionMetadata } from '../../../shared/agent-session/lifecycle/agent-session-resume'
 import { parseLegacyNumericPaneKey, parsePaneKey } from '../../../shared/stable-pane-id'
 import {
@@ -1,4 +1,4 @@
-import { getAgentLaunchExecutableName } from '../../shared/agent-command-line-intent'
+import { getAgentLaunchExecutableName } from '../../shared/agent-launch/startup/agent-command-line-intent'
 import {
  isAgentStatusHooksEnabledForAgent,
  type AgentStatusHooksSettings
@@ -9,7 +9,7 @@ import {
  isPiCompatibleAgentType,
  type PiAgentKind
 } from '../../shared/pi-agent-kind'
-import type { TuiAgent } from '../../shared/tui-agent'
+import type { TuiAgent } from '../../shared/agent-launch/catalog/tui-agent'
 import { wslHookRelayManager, type WslHookRelayManager } from './wsl-hook-relay-manager'
 import { blockedWslDistroForExec } from '../wsl/discovery/wsl-background-exec-gate'

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, expect, it, vi } from 'vitest'
 import { mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import type { TuiAgent } from '../../shared/tui-agent'
+import type { TuiAgent } from '../../shared/agent-launch/catalog/tui-agent'
 import { RelayDispatcher } from '../../wsl-guest/dispatcher'
 import { PluginOverlayManager } from '../../wsl-guest/plugin-overlay'
 import { createInstallPluginsHandler } from '../../wsl-guest/wsl-install-plugins-handler'
--- a/Show More
+++ b/Show More