From 8c6597eeaa34db6264ae6da394a7c4941e58a656 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Tue, 15 Sep 2026 01:38:55 -0700
Subject: [PATCH] docs(agent-launch): stop the executor comment claiming a
 migration that has not happened

The header asserted two things the tree does not support: that every launch
surface routes through the executor, and that the mode decision "already lived"
in `agent-launch-mode`. `agent.launch` is the executor's only consumer, and
`orchestration-worker-start-mode.ts` is byte-identical (blob 92dc5c644a89, 217
lines) at the merge base and all three stack heads, still used by workers.ts.
Describe the two live copies and leave the cutover to later stack work.
---
 src/main/agent-launch/agent-launch-executor.ts | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/main/agent-launch/agent-launch-executor.ts b/src/main/agent-launch/agent-launch-executor.ts
index c9ca168f2bc..df07803f12a 100644
--- a/src/main/agent-launch/agent-launch-executor.ts
+++ b/src/main/agent-launch/agent-launch-executor.ts
@@ -1,10 +1,13 @@
 /**
- * The one place an agent is actually started.
+ * The one place an agent is actually started — for the surfaces moved onto it, which today is
+ * `agent.launch` alone. Orchestration dispatch, mobile create, CLI create and the desktop agent
+ * tab each still start agents their own way; moving them here is later stack work.
  *
- * Every launch surface routes through here: an orchestration dispatch, a mobile create, a CLI
- * create, and (once the renderer stops deciding for itself) a desktop agent tab. What those
- * surfaces duplicated was never the decision — that already lived in `agent-launch-mode` — but the
- * *sequencing* around it, and the sequencing is where the bug was:
+ * The mode decision is duplicated rather than shared: `agent-launch-mode` is a surface-neutral
+ * second copy of orchestration's `orchestration-worker-start-mode`, which is unchanged and still
+ * the one orchestration uses, with nothing enforcing agreement between them. That cutover is later
+ * stack work too. What this module adds is the *sequencing*, and the sequencing is where the bug
+ * was:
  *
  *   create the worktree agent-first  ->  its startup terminal IS the agent
  *                                    ->  the structured branch below it is unreachable