From 88bc0671eca20d3c90bd3d81de1d8363dde59cd2 Mon Sep 17 00:00:00 2001
From: AviationNerd <davidlin2008@outlook.com>
Date: Fri, 13 Nov 2026 00:42:28 +0000
Subject: [PATCH 1/4] fix(dashboard): make agent sign-in terminals usable

Opening agent setup ran its login command before the user chose to run
it, and forced the terminal back to main after every tab change.

Leave the shell available for typing and provide an explicit login or
install action. Keep new tabs selected, prevent alt-click cursor moves
into output, and expose terminal sizing controls on desktop.
---
 docs/dashboard-frontend.md                    | 11 ++-
 docs/terminal.md                              | 10 ++-
 web/src/components/agents/agent-setup.tsx     | 12 ++-
 web/src/components/dock.test.ts               | 57 +++++++++++++-
 web/src/components/dock.tsx                   | 19 +++--
 web/src/components/xterm-host.test.tsx        | 11 +++
 web/src/components/xterm-host.tsx             |  1 +
 .../routes/environment/terminal-dock.test.tsx | 44 +++++++++++
 web/src/routes/environment/terminal-dock.tsx  | 74 +++++++++++++++----
 9 files changed, 202 insertions(+), 37 deletions(-)

diff --git a/docs/dashboard-frontend.md b/docs/dashboard-frontend.md
index cf66da07e..508dbd5b3 100644
--- a/docs/dashboard-frontend.md
+++ b/docs/dashboard-frontend.md
@@ -6077,10 +6077,13 @@ else `default_mode`.
 **Install and log in** calls `agent.install` with `enhanced` set when Enhanced
 is chosen and shows the answer: the log tail in an **Install output**
 disclosure, open when `error` is set, and **Install failed** with the error.
-Once the agent is installed it mounts an Environment dock with the agent's
-login command typed. A gateway without `agent.install` types the
-install command there instead, and one without a terminal socket prints the
-`aether terminal` commands. **Check** re-reads `agent.list` and lists
+Once the agent is installed it mounts an Environment dock. The login or
+install command appears above the dock. Its Run button becomes available
+when the main terminal is ready; selecting another tab disables it. Resize
+the dock by dragging its visible top grip or using the expand/shrink button;
+both stop at the space available to the dock. A gateway without a terminal
+socket prints the `aether terminal` commands.
+**Check** re-reads `agent.list` and lists
 **Installed**, **Enhanced installed** and **Login found** or **No login
 found**, or **Signed out:** or **Sign-in refused:** with `login_problem` when
 the server reports one;
diff --git a/docs/terminal.md b/docs/terminal.md
index f75d62c64..f87c57719 100644
--- a/docs/terminal.md
+++ b/docs/terminal.md
@@ -127,6 +127,10 @@ text size** (on a phone, **Fit to width** in its place), **Copy selection**, **C
 image…**. Sessions add **Captures…**. **Copy screen** copies the visible rows, which
 is how to copy on a touch screen.
 
+During agent sign-in, resize the Environment terminal by dragging its visible
+top grip or using its expand/shrink button. It stops at the height available
+to it.
+
 ### Messages and notes
 
 Talk to the agent in the **Chat** view's composer. Press **Enter** or
@@ -310,9 +314,9 @@ by UNKNOWN port 65535`:
 
 ## Sign in to agents and set up GitHub
 
-The Agents page and onboarding embed the environment terminal with the agent's
-login command typed in. Press Enter to run it. Login state lives in your home,
-so you do not save the environment. See
+The Agents page and onboarding show the login or install command above the
+terminal. Use its Run button when the main terminal is ready.
+Login state lives in your home, so you do not save the environment. See
 [environment-home.md](environment-home.md#set-up-an-agent) and
 [GitHub](environment-home.md#connect-github).
 
diff --git a/web/src/components/agents/agent-setup.tsx b/web/src/components/agents/agent-setup.tsx
index 5c75c87a4..eb7f1f961 100644
--- a/web/src/components/agents/agent-setup.tsx
+++ b/web/src/components/agents/agent-setup.tsx
@@ -148,7 +148,7 @@ export function AgentSetup({
         ) : (
           <p className="text-ui text-text">
             {typedInstall
-              ? 'The install command is typed into your Environment terminal below. Press Enter to run it.'
+              ? <>Run <Code>{typedInstall}</Code> in your Environment terminal below.</>
               : `Install the ${agent.executable ?? agent.name} executable into ~/.local/bin from your Environment terminal below.`}
           </p>
         )}
@@ -172,10 +172,16 @@ export function AgentSetup({
             <>
               {login && (
                 <p className="text-ui text-text">
-                  Log in once: <Code>{login.command}</Code> is typed into your environment terminal. {login.hint}
+                  Log in once by running <Code>{login.command}</Code> in your environment terminal. {login.hint}
                 </p>
               )}
-              <TerminalDock client={client} openOnMount initialLine={canInstall ? login?.command : typedInstall} />
+              <TerminalDock
+                client={client}
+                openOnMount
+                runCommand={canInstall
+                  ? login?.command ? { label: 'Run login command', command: login.command } : undefined
+                  : typedInstall ? { label: 'Run install command', command: typedInstall } : undefined}
+              />
             </>
           ) : (
             <>
diff --git a/web/src/components/dock.test.ts b/web/src/components/dock.test.ts
index 0de198bb4..6f6989e7e 100644
--- a/web/src/components/dock.test.ts
+++ b/web/src/components/dock.test.ts
@@ -36,7 +36,56 @@ describe('Dock controls', () => {
     expect(screen.getByRole('status')).toHaveProperty('textContent', 'At most 2 tabs')
   })
 
-  it('trades the drag separator for half and full heights on a touch screen', () => {
+  it('shows desktop resize affordances and sizes within the available height', () => {
+    atViewport(1440, { height: 900, pointer: 'fine' })
+    const onHeightChange = vi.fn()
+    const props = (height: number) => ({
+      tabs: [{ id: 't1', label: 't1' }],
+      activeTab: 't1',
+      onSelectTab: vi.fn(),
+      maxTabs: 1,
+      height,
+      onHeightChange,
+      collapsed: false,
+      onToggleCollapse: vi.fn(),
+      children: createElement('div'),
+    })
+
+    const view = render(createElement(Dock, props(240)))
+    screen.getByRole('separator', { name: 'Resize terminal' })
+    fireEvent.click(
+      screen.getByRole('button', { name: 'Expand terminal to its available height' }),
+    )
+    expect(onHeightChange).toHaveBeenLastCalledWith(700)
+
+    view.rerender(createElement(Dock, props(700)))
+    fireEvent.click(
+      screen.getByRole('button', { name: 'Shrink terminal to half its available height' }),
+    )
+    expect(onHeightChange).toHaveBeenLastCalledWith(350)
+  })
+
+  it('keeps fill docks free of resize and collapse controls', () => {
+    atViewport(1440, { height: 900, pointer: 'fine' })
+    render(createElement(Dock, {
+      tabs: [{ id: 't1', label: 't1' }],
+      activeTab: 't1',
+      onSelectTab: vi.fn(),
+      maxTabs: 1,
+      height: 240,
+      onHeightChange: vi.fn(),
+      collapsed: false,
+      onToggleCollapse: vi.fn(),
+      containment: 'fill',
+      children: createElement('div'),
+    }))
+
+    expect(screen.queryByRole('separator')).toBeNull()
+    expect(screen.queryByRole('button', { name: /available height/ })).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Collapse terminal' })).toBeNull()
+  })
+
+  it('trades the drag separator for half and maximum heights on a touch screen', () => {
     // A phone: the separator is a drag, and a finger has no drag to give it.
     atViewport(390, { height: 844, pointer: 'coarse' })
     const onHeightChange = vi.fn()
@@ -55,13 +104,13 @@ describe('Dock controls', () => {
     const view = render(createElement(Dock, props(240)))
     expect(screen.queryByRole('separator')).toBeNull()
 
-    // Half and full are measured from the room the dock has, which here is
+    // Half and maximum are measured from the room the dock has, which here is
     // the viewport less the shell's own chrome.
-    fireEvent.click(screen.getByRole('button', { name: /full screen/ }))
+    fireEvent.click(screen.getByRole('button', { name: /available height/ }))
     expect(onHeightChange).toHaveBeenLastCalledWith(644)
 
     view.rerender(createElement(Dock, props(644)))
-    fireEvent.click(screen.getByRole('button', { name: /half the screen/ }))
+    fireEvent.click(screen.getByRole('button', { name: /half its available height/ }))
     expect(onHeightChange).toHaveBeenLastCalledWith(322)
   })
 
diff --git a/web/src/components/dock.tsx b/web/src/components/dock.tsx
index e84c41d94..fb71aa6ac 100644
--- a/web/src/components/dock.tsx
+++ b/web/src/components/dock.tsx
@@ -115,7 +115,6 @@ export function Dock({
           )
   const min = Math.min(requiredMinimum, max)
   const currentHeight = Math.min(max, Math.max(min, height))
-  // A finger cannot drag the edge, so touch toggles between half and full height.
   const halfHeight = Math.min(max, Math.max(min, Math.round(max / 2)))
   const full = currentHeight >= max
   const index = Math.max(
@@ -254,10 +253,16 @@ export function Dock({
           className={cn(
             focusRing,
             // Without `touch-none` the browser claims a pen or trackpad drag
-            // as a pan and cancels the pointer stream this listens to.
-            'absolute inset-x-0 -top-px z-10 h-1 cursor-row-resize touch-none bg-transparent transition-colors hover:bg-accent/20 focus-visible:bg-accent/20',
+            // as a pan and cancels the pointer stream this listens to. The
+            // strip ends at the dock edge so it cannot cover header controls.
+            'group absolute inset-x-0 -top-1.5 z-10 flex h-1.5 cursor-row-resize touch-none items-center justify-center bg-transparent transition-colors hover:bg-accent/20 focus-visible:bg-accent/20',
           )}
-        />
+        >
+          <span
+            aria-hidden="true"
+            className="h-1 w-8 rounded-full bg-icon-faint/70 transition-colors group-hover:bg-accent group-focus-visible:bg-accent"
+          />
+        </div>
       )}
       <div
         ref={headerRef}
@@ -379,7 +384,7 @@ export function Dock({
             {actions}
           </div>
         )}
-        {!collapsed && coarse && !fill && (
+        {!collapsed && !fill && (
           <Button
             className="max-[640px]:order-2"
             type="button"
@@ -387,8 +392,8 @@ export function Dock({
             size="icon"
             label={
               full
-                ? 'Shrink terminal to half the screen'
-                : 'Expand terminal to the full screen'
+                ? 'Shrink terminal to half its available height'
+                : 'Expand terminal to its available height'
             }
             aria-controls={dockID}
             onClick={() => onHeightChange(full ? halfHeight : max)}
diff --git a/web/src/components/xterm-host.test.tsx b/web/src/components/xterm-host.test.tsx
index 140ac769a..4305ed4d6 100644
--- a/web/src/components/xterm-host.test.tsx
+++ b/web/src/components/xterm-host.test.tsx
@@ -81,6 +81,17 @@ describe('xterm links', () => {
   })
 })
 
+describe('xterm input', () => {
+  it('keeps Alt-click from moving the shell cursor', async () => {
+    let ready: Terminal | null = null
+    const view = render(<Probe onReady={(terminal) => (ready = terminal)} />)
+    await waitFor(() => expect(ready).not.toBeNull())
+
+    expect((ready as Terminal | null)?.options.altClickMovesCursor).toBe(false)
+    view.unmount()
+  })
+})
+
 describe('server-owned protocol responses', () => {
   it('suppresses actual parser queries while preserving mixed color setters, Unicode and real input', async () => {
     let ready: Terminal | null = null
diff --git a/web/src/components/xterm-host.tsx b/web/src/components/xterm-host.tsx
index 08ccb3dce..17308356e 100644
--- a/web/src/components/xterm-host.tsx
+++ b/web/src/components/xterm-host.tsx
@@ -542,6 +542,7 @@ export function useXterm({
       scrollback: Math.max(0, Math.floor(scrollback)),
       scrollOnEraseInDisplay: true,
       cursorBlink: false,
+      altClickMovesCursor: false,
       linkHandler: { activate: (_event, uri) => openLink(uri) },
     })
     const disposeResponder = installServerResponder(
diff --git a/web/src/routes/environment/terminal-dock.test.tsx b/web/src/routes/environment/terminal-dock.test.tsx
index 3ce752082..2eb56f817 100644
--- a/web/src/routes/environment/terminal-dock.test.tsx
+++ b/web/src/routes/environment/terminal-dock.test.tsx
@@ -803,6 +803,50 @@ describe('environment terminal dock', () => {
     expect(useStore.getState().envTerminal.collapsed).toBe(true)
   })
 
+  it('keeps a newly opened tab selected when mounted open', async () => {
+    vi.mocked(api.terminalStatus).mockResolvedValue({ running: true, tabs: ['main'] })
+    render(<TerminalDock openOnMount />)
+    await waitFor(() => expect(useStore.getState().envTerminal.activeTab).toBe('main'))
+
+    fireEvent.click(await screen.findByRole('button', { name: 'Add terminal tab' }))
+
+    await waitFor(() => expect(useStore.getState().envTerminal.activeTab).toBe('t2'))
+  })
+
+  it('waits for replay and runs setup commands only on request', async () => {
+    vi.mocked(api.terminalStatus).mockResolvedValue({ running: true, tabs: ['main'] })
+    render(<TerminalDock openOnMount runCommand={{ label: 'Run login command', command: 'claude' }} />)
+    await waitFor(() => expect(attach.handlers).not.toBeNull())
+    const run = await screen.findByRole('button', { name: 'Run login command' })
+
+    act(() => attach.handlers?.onAttached(true, standardGeometry))
+    expect((run as HTMLButtonElement).disabled).toBe(true)
+    expect(attach.send).not.toHaveBeenCalled()
+
+    act(() => {
+      attach.handlers?.onReplayStart?.(0, true)
+    })
+    await waitFor(() => expect((run as HTMLButtonElement).disabled).toBe(false))
+    fireEvent.click(run)
+    expect(attach.send).toHaveBeenCalledWith('claude\n')
+    expect(xterm.focusTerminal).toHaveBeenCalled()
+  })
+
+  it('enables setup commands after a resumed delta replay settles', async () => {
+    vi.mocked(api.terminalStatus).mockResolvedValue({ running: true, tabs: ['main'] })
+    render(<TerminalDock openOnMount runCommand={{ label: 'Run login command', command: 'claude' }} />)
+    await waitFor(() => expect(attach.handlers).not.toBeNull())
+    const run = await screen.findByRole('button', { name: 'Run login command' })
+
+    act(() => attach.handlers?.onAttached(true, standardGeometry, true))
+    expect((run as HTMLButtonElement).disabled).toBe(true)
+    act(() => attach.handlers?.onReplayStart?.(0, false))
+
+    await waitFor(() => expect((run as HTMLButtonElement).disabled).toBe(false))
+    fireEvent.click(run)
+    expect(attach.send).toHaveBeenCalledWith('claude\n')
+  })
+
   it('opens the dock when a collapsed strip is asked for a tab', async () => {
     vi.mocked(api.terminalStatus).mockResolvedValue({ running: true, tabs: ['main'] })
     useStore.setState({ envTerminal: initialEnvTerminal })
diff --git a/web/src/routes/environment/terminal-dock.tsx b/web/src/routes/environment/terminal-dock.tsx
index 68bf0e3b8..e259e8390 100644
--- a/web/src/routes/environment/terminal-dock.tsx
+++ b/web/src/routes/environment/terminal-dock.tsx
@@ -65,8 +65,8 @@ interface StructuralReplayState {
 interface TerminalDockProps {
   client?: Api
   openOnMount?: boolean
-  /** A line to type into the main tab after its first attach. */
   initialLine?: string
+  runCommand?: { label: string; command: string }
   /** Embedded intrinsic sections use the viewport cap; fixed flex layouts opt into 'parent'. */
   containment?: DockContainment
   header?: (actions: ReactNode, hint?: string) => ReactNode
@@ -76,6 +76,7 @@ export function TerminalDock({
   client = api,
   openOnMount = false,
   initialLine,
+  runCommand,
   containment = 'viewport',
   header,
 }: TerminalDockProps) {
@@ -103,6 +104,7 @@ export function TerminalDock({
   const [resetError, setResetError] = useState<string | null>(null)
   const [statusAttempt, setStatusAttempt] = useState(0)
   const [attachedTab, setAttachedTab] = useState<string | null>(null)
+  const [inputReadyTab, setInputReadyTab] = useState<string | null>(null)
   const [replaying, setReplaying] = useState(false)
   const actionsTrigger = useRef<HTMLButtonElement>(null)
   const openTrigger = useRef<HTMLButtonElement>(null)
@@ -117,12 +119,17 @@ export function TerminalDock({
   const activeTab = dock.activeTab
   const activeTabRef = useRef(activeTab)
   activeTabRef.current = activeTab
+  const inputReadyTabRef = useRef<string | null>(null)
+  const setInputReady = (tab: string | null) => {
+    inputReadyTabRef.current = tab
+    setInputReadyTab(tab)
+  }
   const terminalRef = useRef<XtermController['terminal']>(null)
   const controllerRef = useRef<XtermController | null>(null)
   const attachmentGenerationRef = useRef(0)
   const replayRevisionRef = useRef(0)
   const structuralReplayRef = useRef<StructuralReplayState | null>(null)
-  const fullReplaySettlingGenerationRef = useRef<number | null>(null)
+  const replaySettlingGenerationRef = useRef<number | null>(null)
   const gate = useRef(
     replayGate(
       (chunk, done) => terminalRef.current?.write(chunk, done),
@@ -132,16 +139,18 @@ export function TerminalDock({
           return
         }
         if (!full) {
+          if (replaySettlingGenerationRef.current === attachmentGenerationRef.current) {
+            replaySettlingGenerationRef.current = null
+            setInputReady(activeTabRef.current)
+          }
           setReplaying(false)
           return
         }
         const replay = structuralReplayRef.current
         if (!replay) {
-          if (
-            fullReplaySettlingGenerationRef.current !== null &&
-            attachmentGenerationRef.current === fullReplaySettlingGenerationRef.current
-          ) {
-            fullReplaySettlingGenerationRef.current = null
+          if (replaySettlingGenerationRef.current === attachmentGenerationRef.current) {
+            replaySettlingGenerationRef.current = null
+            setInputReady(activeTabRef.current)
           }
           setReplaying(false)
           return
@@ -157,10 +166,11 @@ export function TerminalDock({
             replayRevisionRef.current !== replay.revision ||
             attachmentGenerationRef.current !== replay.attachmentGeneration
           ) return
-          if (fullReplaySettlingGenerationRef.current === replay.attachmentGeneration) {
-            fullReplaySettlingGenerationRef.current = null
+          if (replaySettlingGenerationRef.current === replay.attachmentGeneration) {
+            replaySettlingGenerationRef.current = null
           }
           structuralReplayRef.current = null
+          setInputReady(activeTabRef.current)
           setReplaying(false)
         })()
       },
@@ -176,7 +186,7 @@ export function TerminalDock({
       if (
         !activeTab ||
         activeTabRef.current !== activeTab ||
-        fullReplaySettlingGenerationRef.current !== null ||
+        replaySettlingGenerationRef.current !== null ||
         gate.current.muted()
       ) return
       getEnvTerminalSocket(activeTab)?.send(data)
@@ -218,6 +228,9 @@ export function TerminalDock({
   }, [terminal])
   const setFindOpen = controller.setFindOpen
   const focusTerminal = controller.focusTerminal
+  const canRunCommand = Boolean(
+    runCommand && activeTab === 'main' && inputReadyTab === 'main' && attachedTab === 'main',
+  )
   useEffect(() => {
     setFindOpen(false)
   }, [activeTab, setFindOpen])
@@ -263,8 +276,10 @@ export function TerminalDock({
     setCollapsed(false)
   }, [openOnMount, setCollapsed])
 
+  const selectedOnMount = useRef(false)
   useEffect(() => {
-    if (!openOnMount) return
+    if (!openOnMount || selectedOnMount.current) return
+    selectedOnMount.current = true
     if (!dock.tabs.includes('main')) {
       openTab()
     } else if (dock.activeTab !== 'main') {
@@ -294,8 +309,8 @@ export function TerminalDock({
         replayRevisionRef.current++
         void replay.controller.cancelStructuralReplay?.(replay.controllerGeneration)
       }
-      if (fullReplaySettlingGenerationRef.current === attachmentGeneration) {
-        fullReplaySettlingGenerationRef.current = null
+      if (replaySettlingGenerationRef.current === attachmentGeneration) {
+        replaySettlingGenerationRef.current = null
       }
     }
     const handlers = {
@@ -305,11 +320,13 @@ export function TerminalDock({
         if (isCurrent()) {
           setEnvTerminalSocketReady(socketKey, true)
           setAttachedTab(socketKey)
+          setInputReady(null)
           replayAccepted = true
           if (resumed) {
             cancelStructuralReplay()
+            replaySettlingGenerationRef.current = attachmentGeneration
           } else {
-            fullReplaySettlingGenerationRef.current = attachmentGeneration
+            replaySettlingGenerationRef.current = attachmentGeneration
             const replayController = controllerRef.current
             const controllerGeneration = replayController?.beginStructuralReplay?.()
             const revision = ++replayRevisionRef.current
@@ -338,7 +355,7 @@ export function TerminalDock({
         if (!isCurrent()) return
         if (!replayAccepted) return
         replayAccepted = false
-        if (full) fullReplaySettlingGenerationRef.current = attachmentGeneration
+        replaySettlingGenerationRef.current = attachmentGeneration
         gate.current.start(full ? 'full' : 'delta')
         if (bytes === 0) void gate.current.write(emptyReplay, 'replay-end')
       },
@@ -347,22 +364,26 @@ export function TerminalDock({
         if (connection !== 'live') {
           setEnvTerminalSocketReady(socketKey, false)
           setAttachedTab(null)
+          setInputReady(null)
         }
       },
       onRefused: (detail: string) => {
         if (!isCurrent()) return
         setAttachedTab(null)
+        setInputReady(null)
         setStatus(useStore.getState().envTerminal.status, detail)
       },
       onWriteDenied: () => {
         if (!isCurrent()) return
         setAttachedTab(null)
+        setInputReady(null)
         setStatus(useStore.getState().envTerminal.status, 'Terminal input was denied')
       },
       onExit: () => {
         if (isCurrent()) {
           setEnvTerminalSocketReady(socketKey, false)
           setAttachedTab(null)
+          setInputReady(null)
           if (socketKey === 'main') {
             const status = useStore.getState().envTerminal.status
             reset()
@@ -390,6 +411,7 @@ export function TerminalDock({
 
     setEnvTerminalSocketReady(socketKey, false)
     setAttachedTab(null)
+    setInputReady(null)
     const unsubscribe = subscribeEnvTerminalSocket(socketKey, gate.current.write)
     return () => {
       unsubscribe()
@@ -444,8 +466,28 @@ export function TerminalDock({
   }
 
   const actions = (
-    (!empty || !!dock.status?.saved_image) && (
+    (!empty || !!dock.status?.saved_image || !!runCommand) && (
       <div className="flex max-w-full items-center justify-end gap-1">
+        {runCommand && (
+          <Button
+            type="button"
+            size="sm"
+            variant="secondary"
+            disabled={!canRunCommand}
+            onClick={() => {
+              const socket = getEnvTerminalSocket('main')
+              if (
+                !socket || !canRunCommand || activeTabRef.current !== 'main' ||
+                inputReadyTabRef.current !== 'main' || replaySettlingGenerationRef.current !== null ||
+                gate.current.muted()
+              ) return
+              socket.send(`${runCommand.command}\n`)
+              focusTerminal()
+            }}
+          >
+            {runCommand.label}
+          </Button>
+        )}
         {dock.status?.running && (
           <Button
             type="button"

From 4d2bef7ff1c78a11596e6c604e9aed76673e8521 Mon Sep 17 00:00:00 2001
From: AviationNerd <davidlin2008@outlook.com>
Date: Fri, 13 Nov 2026 00:54:30 +0000
Subject: [PATCH 2/4] fix(dashboard): copy setup commands without submitting
 terminal input

A live terminal may hold pending shell input or a foreground program.
Copy the setup command for the user to paste and review at a shell
prompt, so the action cannot execute combined input or answer a prompt.
---
 docs/dashboard-frontend.md                    |  6 +-
 docs/terminal.md                              |  2 +-
 web/src/components/agents/agent-setup.tsx     | 22 ++++--
 .../routes/environment/terminal-dock.test.tsx | 34 ---------
 web/src/routes/environment/terminal-dock.tsx  | 70 ++++---------------
 5 files changed, 34 insertions(+), 100 deletions(-)

diff --git a/docs/dashboard-frontend.md b/docs/dashboard-frontend.md
index 508dbd5b3..c705ce992 100644
--- a/docs/dashboard-frontend.md
+++ b/docs/dashboard-frontend.md
@@ -6078,9 +6078,9 @@ else `default_mode`.
 is chosen and shows the answer: the log tail in an **Install output**
 disclosure, open when `error` is set, and **Install failed** with the error.
 Once the agent is installed it mounts an Environment dock. The login or
-install command appears above the dock. Its Run button becomes available
-when the main terminal is ready; selecting another tab disables it. Resize
-the dock by dragging its visible top grip or using the expand/shrink button;
+install command appears above the dock. Use **Copy login command** or
+**Copy install command**, paste at a shell prompt, review the command, then
+press Enter. Resize the dock by dragging its visible top grip or using the expand/shrink button;
 both stop at the space available to the dock. A gateway without a terminal
 socket prints the `aether terminal` commands.
 **Check** re-reads `agent.list` and lists
diff --git a/docs/terminal.md b/docs/terminal.md
index f87c57719..f91112f7c 100644
--- a/docs/terminal.md
+++ b/docs/terminal.md
@@ -315,7 +315,7 @@ by UNKNOWN port 65535`:
 ## Sign in to agents and set up GitHub
 
 The Agents page and onboarding show the login or install command above the
-terminal. Use its Run button when the main terminal is ready.
+terminal. Copy the command, paste at a shell prompt, review it, then press Enter.
 Login state lives in your home, so you do not save the environment. See
 [environment-home.md](environment-home.md#set-up-an-agent) and
 [GitHub](environment-home.md#connect-github).
diff --git a/web/src/components/agents/agent-setup.tsx b/web/src/components/agents/agent-setup.tsx
index eb7f1f961..aaec381be 100644
--- a/web/src/components/agents/agent-setup.tsx
+++ b/web/src/components/agents/agent-setup.tsx
@@ -10,6 +10,7 @@ import { Spinner } from '@/components/ui/spinner'
 import { StatusDot } from '@/components/ui/status-dot'
 import type { Api } from '@/lib/api'
 import { message } from '@/lib/format'
+import { copyText } from '@/lib/clipboard'
 import type { AgentInfo, AgentInstallResult } from '@/lib/types'
 import { TerminalDock } from '@/routes/environment/terminal-dock'
 import { useStore } from '@/store'
@@ -69,6 +70,7 @@ export function AgentSetup({
   const hasTerminal = caps.hasWS('terminal')
   const login = loginFor(agent)
   const typedInstall = enhanced ? agent.enhanced_install_script ?? agent.install_script : agent.install_script
+  const setupCommand = canInstall ? login?.command : typedInstall
 
   const check = async () => {
     setChecking(true)
@@ -175,13 +177,19 @@ export function AgentSetup({
                   Log in once by running <Code>{login.command}</Code> in your environment terminal. {login.hint}
                 </p>
               )}
-              <TerminalDock
-                client={client}
-                openOnMount
-                runCommand={canInstall
-                  ? login?.command ? { label: 'Run login command', command: login.command } : undefined
-                  : typedInstall ? { label: 'Run install command', command: typedInstall } : undefined}
-              />
+              {setupCommand && (
+                <>
+                  <p className="text-ui text-text">Paste the command at a shell prompt, review it, then press Enter.</p>
+                  <Button
+                    type="button"
+                    variant="secondary"
+                    onClick={() => void copyText(setupCommand, null)}
+                  >
+                    {canInstall ? 'Copy login command' : 'Copy install command'}
+                  </Button>
+                </>
+              )}
+              <TerminalDock client={client} openOnMount />
             </>
           ) : (
             <>
diff --git a/web/src/routes/environment/terminal-dock.test.tsx b/web/src/routes/environment/terminal-dock.test.tsx
index 2eb56f817..74ab5fd5c 100644
--- a/web/src/routes/environment/terminal-dock.test.tsx
+++ b/web/src/routes/environment/terminal-dock.test.tsx
@@ -813,40 +813,6 @@ describe('environment terminal dock', () => {
     await waitFor(() => expect(useStore.getState().envTerminal.activeTab).toBe('t2'))
   })
 
-  it('waits for replay and runs setup commands only on request', async () => {
-    vi.mocked(api.terminalStatus).mockResolvedValue({ running: true, tabs: ['main'] })
-    render(<TerminalDock openOnMount runCommand={{ label: 'Run login command', command: 'claude' }} />)
-    await waitFor(() => expect(attach.handlers).not.toBeNull())
-    const run = await screen.findByRole('button', { name: 'Run login command' })
-
-    act(() => attach.handlers?.onAttached(true, standardGeometry))
-    expect((run as HTMLButtonElement).disabled).toBe(true)
-    expect(attach.send).not.toHaveBeenCalled()
-
-    act(() => {
-      attach.handlers?.onReplayStart?.(0, true)
-    })
-    await waitFor(() => expect((run as HTMLButtonElement).disabled).toBe(false))
-    fireEvent.click(run)
-    expect(attach.send).toHaveBeenCalledWith('claude\n')
-    expect(xterm.focusTerminal).toHaveBeenCalled()
-  })
-
-  it('enables setup commands after a resumed delta replay settles', async () => {
-    vi.mocked(api.terminalStatus).mockResolvedValue({ running: true, tabs: ['main'] })
-    render(<TerminalDock openOnMount runCommand={{ label: 'Run login command', command: 'claude' }} />)
-    await waitFor(() => expect(attach.handlers).not.toBeNull())
-    const run = await screen.findByRole('button', { name: 'Run login command' })
-
-    act(() => attach.handlers?.onAttached(true, standardGeometry, true))
-    expect((run as HTMLButtonElement).disabled).toBe(true)
-    act(() => attach.handlers?.onReplayStart?.(0, false))
-
-    await waitFor(() => expect((run as HTMLButtonElement).disabled).toBe(false))
-    fireEvent.click(run)
-    expect(attach.send).toHaveBeenCalledWith('claude\n')
-  })
-
   it('opens the dock when a collapsed strip is asked for a tab', async () => {
     vi.mocked(api.terminalStatus).mockResolvedValue({ running: true, tabs: ['main'] })
     useStore.setState({ envTerminal: initialEnvTerminal })
diff --git a/web/src/routes/environment/terminal-dock.tsx b/web/src/routes/environment/terminal-dock.tsx
index e259e8390..f1348ff47 100644
--- a/web/src/routes/environment/terminal-dock.tsx
+++ b/web/src/routes/environment/terminal-dock.tsx
@@ -65,8 +65,8 @@ interface StructuralReplayState {
 interface TerminalDockProps {
   client?: Api
   openOnMount?: boolean
+  /** A line to type into the main tab after its first attach. */
   initialLine?: string
-  runCommand?: { label: string; command: string }
   /** Embedded intrinsic sections use the viewport cap; fixed flex layouts opt into 'parent'. */
   containment?: DockContainment
   header?: (actions: ReactNode, hint?: string) => ReactNode
@@ -76,7 +76,6 @@ export function TerminalDock({
   client = api,
   openOnMount = false,
   initialLine,
-  runCommand,
   containment = 'viewport',
   header,
 }: TerminalDockProps) {
@@ -104,7 +103,6 @@ export function TerminalDock({
   const [resetError, setResetError] = useState<string | null>(null)
   const [statusAttempt, setStatusAttempt] = useState(0)
   const [attachedTab, setAttachedTab] = useState<string | null>(null)
-  const [inputReadyTab, setInputReadyTab] = useState<string | null>(null)
   const [replaying, setReplaying] = useState(false)
   const actionsTrigger = useRef<HTMLButtonElement>(null)
   const openTrigger = useRef<HTMLButtonElement>(null)
@@ -119,17 +117,12 @@ export function TerminalDock({
   const activeTab = dock.activeTab
   const activeTabRef = useRef(activeTab)
   activeTabRef.current = activeTab
-  const inputReadyTabRef = useRef<string | null>(null)
-  const setInputReady = (tab: string | null) => {
-    inputReadyTabRef.current = tab
-    setInputReadyTab(tab)
-  }
   const terminalRef = useRef<XtermController['terminal']>(null)
   const controllerRef = useRef<XtermController | null>(null)
   const attachmentGenerationRef = useRef(0)
   const replayRevisionRef = useRef(0)
   const structuralReplayRef = useRef<StructuralReplayState | null>(null)
-  const replaySettlingGenerationRef = useRef<number | null>(null)
+  const fullReplaySettlingGenerationRef = useRef<number | null>(null)
   const gate = useRef(
     replayGate(
       (chunk, done) => terminalRef.current?.write(chunk, done),
@@ -139,18 +132,16 @@ export function TerminalDock({
           return
         }
         if (!full) {
-          if (replaySettlingGenerationRef.current === attachmentGenerationRef.current) {
-            replaySettlingGenerationRef.current = null
-            setInputReady(activeTabRef.current)
-          }
           setReplaying(false)
           return
         }
         const replay = structuralReplayRef.current
         if (!replay) {
-          if (replaySettlingGenerationRef.current === attachmentGenerationRef.current) {
-            replaySettlingGenerationRef.current = null
-            setInputReady(activeTabRef.current)
+          if (
+            fullReplaySettlingGenerationRef.current !== null &&
+            attachmentGenerationRef.current === fullReplaySettlingGenerationRef.current
+          ) {
+            fullReplaySettlingGenerationRef.current = null
           }
           setReplaying(false)
           return
@@ -166,11 +157,10 @@ export function TerminalDock({
             replayRevisionRef.current !== replay.revision ||
             attachmentGenerationRef.current !== replay.attachmentGeneration
           ) return
-          if (replaySettlingGenerationRef.current === replay.attachmentGeneration) {
-            replaySettlingGenerationRef.current = null
+          if (fullReplaySettlingGenerationRef.current === replay.attachmentGeneration) {
+            fullReplaySettlingGenerationRef.current = null
           }
           structuralReplayRef.current = null
-          setInputReady(activeTabRef.current)
           setReplaying(false)
         })()
       },
@@ -186,7 +176,7 @@ export function TerminalDock({
       if (
         !activeTab ||
         activeTabRef.current !== activeTab ||
-        replaySettlingGenerationRef.current !== null ||
+        fullReplaySettlingGenerationRef.current !== null ||
         gate.current.muted()
       ) return
       getEnvTerminalSocket(activeTab)?.send(data)
@@ -228,9 +218,6 @@ export function TerminalDock({
   }, [terminal])
   const setFindOpen = controller.setFindOpen
   const focusTerminal = controller.focusTerminal
-  const canRunCommand = Boolean(
-    runCommand && activeTab === 'main' && inputReadyTab === 'main' && attachedTab === 'main',
-  )
   useEffect(() => {
     setFindOpen(false)
   }, [activeTab, setFindOpen])
@@ -309,8 +296,8 @@ export function TerminalDock({
         replayRevisionRef.current++
         void replay.controller.cancelStructuralReplay?.(replay.controllerGeneration)
       }
-      if (replaySettlingGenerationRef.current === attachmentGeneration) {
-        replaySettlingGenerationRef.current = null
+      if (fullReplaySettlingGenerationRef.current === attachmentGeneration) {
+        fullReplaySettlingGenerationRef.current = null
       }
     }
     const handlers = {
@@ -320,13 +307,11 @@ export function TerminalDock({
         if (isCurrent()) {
           setEnvTerminalSocketReady(socketKey, true)
           setAttachedTab(socketKey)
-          setInputReady(null)
           replayAccepted = true
           if (resumed) {
             cancelStructuralReplay()
-            replaySettlingGenerationRef.current = attachmentGeneration
           } else {
-            replaySettlingGenerationRef.current = attachmentGeneration
+            fullReplaySettlingGenerationRef.current = attachmentGeneration
             const replayController = controllerRef.current
             const controllerGeneration = replayController?.beginStructuralReplay?.()
             const revision = ++replayRevisionRef.current
@@ -355,7 +340,7 @@ export function TerminalDock({
         if (!isCurrent()) return
         if (!replayAccepted) return
         replayAccepted = false
-        replaySettlingGenerationRef.current = attachmentGeneration
+        if (full) fullReplaySettlingGenerationRef.current = attachmentGeneration
         gate.current.start(full ? 'full' : 'delta')
         if (bytes === 0) void gate.current.write(emptyReplay, 'replay-end')
       },
@@ -364,26 +349,22 @@ export function TerminalDock({
         if (connection !== 'live') {
           setEnvTerminalSocketReady(socketKey, false)
           setAttachedTab(null)
-          setInputReady(null)
         }
       },
       onRefused: (detail: string) => {
         if (!isCurrent()) return
         setAttachedTab(null)
-        setInputReady(null)
         setStatus(useStore.getState().envTerminal.status, detail)
       },
       onWriteDenied: () => {
         if (!isCurrent()) return
         setAttachedTab(null)
-        setInputReady(null)
         setStatus(useStore.getState().envTerminal.status, 'Terminal input was denied')
       },
       onExit: () => {
         if (isCurrent()) {
           setEnvTerminalSocketReady(socketKey, false)
           setAttachedTab(null)
-          setInputReady(null)
           if (socketKey === 'main') {
             const status = useStore.getState().envTerminal.status
             reset()
@@ -411,7 +392,6 @@ export function TerminalDock({
 
     setEnvTerminalSocketReady(socketKey, false)
     setAttachedTab(null)
-    setInputReady(null)
     const unsubscribe = subscribeEnvTerminalSocket(socketKey, gate.current.write)
     return () => {
       unsubscribe()
@@ -466,28 +446,8 @@ export function TerminalDock({
   }
 
   const actions = (
-    (!empty || !!dock.status?.saved_image || !!runCommand) && (
+    (!empty || !!dock.status?.saved_image) && (
       <div className="flex max-w-full items-center justify-end gap-1">
-        {runCommand && (
-          <Button
-            type="button"
-            size="sm"
-            variant="secondary"
-            disabled={!canRunCommand}
-            onClick={() => {
-              const socket = getEnvTerminalSocket('main')
-              if (
-                !socket || !canRunCommand || activeTabRef.current !== 'main' ||
-                inputReadyTabRef.current !== 'main' || replaySettlingGenerationRef.current !== null ||
-                gate.current.muted()
-              ) return
-              socket.send(`${runCommand.command}\n`)
-              focusTerminal()
-            }}
-          >
-            {runCommand.label}
-          </Button>
-        )}
         {dock.status?.running && (
           <Button
             type="button"

From b6c2bb53c38eb5675ff65d64f9d67fb49d5175d8 Mon Sep 17 00:00:00 2001
From: AviationNerd <davidlin2008@outlook.com>
Date: Fri, 13 Nov 2026 00:56:28 +0000
Subject: [PATCH 3/4] docs: explain copying the dashboard login command

---
 docs/harnesses.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/harnesses.md b/docs/harnesses.md
index 511af66f0..bfa18ba6d 100644
--- a/docs/harnesses.md
+++ b/docs/harnesses.md
@@ -94,8 +94,8 @@ You do this once per agent, per person.
    `--enhanced` to install the Enhanced adapter too (see
    [Enhanced adapters](#enhanced-adapters)). In the dashboard, **Set up** on the
    **Agents** page or onboarding's **Agent** step does the same: it lets you
-   pick Standard or Enhanced, installs the agent, and opens a terminal with the
-   login command typed.
+   pick Standard or Enhanced, installs the agent, and opens a terminal. Use
+   **Copy login command**, paste at a shell prompt, review it, then press Enter.
 
    The environment has no `aether` command (only `aether-internal`), so run
    `aether` commands on your computer, never in this shell.

From 9ba0123672175ef56fbf0ac938ba1d9410f637cf Mon Sep 17 00:00:00 2001
From: AviationNerd <davidlin2008@outlook.com>
Date: Fri, 13 Nov 2026 01:09:42 +0000
Subject: [PATCH 4/4] fix(dashboard): select setup commands when clipboard
 access fails

---
 .../components/agents/agent-setup.test.tsx    | 41 ++++++++++++++++++-
 web/src/components/agents/agent-setup.tsx     |  9 ++--
 2 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/web/src/components/agents/agent-setup.test.tsx b/web/src/components/agents/agent-setup.test.tsx
index 989367d93..fe6968ebf 100644
--- a/web/src/components/agents/agent-setup.test.tsx
+++ b/web/src/components/agents/agent-setup.test.tsx
@@ -1,4 +1,4 @@
-import { fireEvent, render, screen, within } from '@testing-library/react'
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react'
 import { AgentSetup } from '@/components/agents/agent-setup'
 import { ModeComparison } from '@/components/agents/mode-comparison'
 import type { Api } from '@/lib/api'
@@ -6,6 +6,9 @@ import type { AgentInfo, GatewayCapabilities } from '@/lib/types'
 import { useStore } from '@/store'
 import { agentInfo, fakeApi } from '@/test/fixtures'
 
+const { terminalDock } = vi.hoisted(() => ({ terminalDock: vi.fn(() => null) }))
+vi.mock('@/routes/environment/terminal-dock', () => ({ TerminalDock: terminalDock }))
+
 const caps: GatewayCapabilities = { gateway: 'local', methods: ['*'], ws: ['events', 'attach'] }
 
 const claude = agentInfo({ display_name: 'Claude Code', installed: false, enhanced: 'adapter', default_mode: 'tui' })
@@ -21,6 +24,7 @@ const codex = agentInfo({
 const custom = agentInfo({ name: 'mycli', display_name: 'mycli', source: 'member', glyph: 'custom', enhanced: 'none', install_script: undefined })
 
 beforeEach(() => {
+  terminalDock.mockClear()
   useStore.setState(useStore.getInitialState(), true)
   useStore.setState({ capabilities: caps })
 })
@@ -225,3 +229,38 @@ describe('agent setup', () => {
     expect(screen.getByText(/aether terminal/).textContent).toContain('curl -fsSL https://claude.ai/install.sh | bash')
   })
 })
+
+
+describe('copying setup commands', () => {
+  afterEach(() => vi.unstubAllGlobals())
+
+  it.each([
+    ['login', codex, 'Copy login command', 'codex login --device-auth', ['*']],
+    ['install', { ...codex, installed: false, enhanced_installed: false }, 'Copy install command', codex.install_script!, []],
+  ] as const)('copies the exact %s command without submitting terminal input', async (_kind, agent, label, command, methods) => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    vi.stubGlobal('navigator', { clipboard: { writeText } })
+    useStore.setState({ capabilities: { ...caps, methods: [...methods], ws: ['terminal'] } })
+    setUp(agent)
+    expect(writeText).not.toHaveBeenCalled()
+
+    fireEvent.click(screen.getByRole('button', { name: label }))
+
+    await waitFor(() => expect(writeText).toHaveBeenCalledWith(command))
+    expect(terminalDock).toHaveBeenCalled()
+    for (const [props] of terminalDock.mock.calls as unknown as [{ initialLine?: string; runCommand?: unknown }][]) {
+      expect(props.initialLine).toBeUndefined()
+      expect(props.runCommand).toBeUndefined()
+    }
+  })
+
+  it('selects the displayed login command when clipboard access fails', async () => {
+    vi.stubGlobal('navigator', { clipboard: { writeText: vi.fn().mockRejectedValue(new Error('Clipboard denied')) } })
+    useStore.setState({ capabilities: { ...caps, ws: ['terminal'] } })
+    setUp(codex)
+
+    fireEvent.click(screen.getByRole('button', { name: 'Copy login command' }))
+
+    await waitFor(() => expect(window.getSelection()?.toString()).toBe('codex login --device-auth'))
+  })
+})
diff --git a/web/src/components/agents/agent-setup.tsx b/web/src/components/agents/agent-setup.tsx
index aaec381be..aa9160ce1 100644
--- a/web/src/components/agents/agent-setup.tsx
+++ b/web/src/components/agents/agent-setup.tsx
@@ -1,4 +1,4 @@
-import { type ReactNode, useState } from 'react'
+import { type ReactNode, useRef, useState } from 'react'
 import { enhancedSupported, label, loginFor, ready, setupMode, signedOutState } from '@/components/agents/agent-copy'
 import { ModeComparison, type SetupMode } from '@/components/agents/mode-comparison'
 import { AgentGlyph } from '@/components/ui/agent-glyph'
@@ -52,6 +52,7 @@ export function AgentSetup({
   /** Pins Enhanced for a caller that cannot work without its adapter, so the mode choice is skipped. */
   requireEnhanced?: boolean
 }) {
+  const commandSource = useRef<HTMLElement>(null)
   const caps = useCapability()
   const [agent, setAgent] = useState(initial)
   const [mode, setMode] = useState<SetupMode>(() => requireEnhanced ? 'acp' : setupMode(initial, useStore.getState().launchDefaults[initial.name]?.mode))
@@ -150,7 +151,7 @@ export function AgentSetup({
         ) : (
           <p className="text-ui text-text">
             {typedInstall
-              ? <>Run <Code>{typedInstall}</Code> in your Environment terminal below.</>
+              ? <>Run <Code ref={commandSource}>{typedInstall}</Code> in your Environment terminal below.</>
               : `Install the ${agent.executable ?? agent.name} executable into ~/.local/bin from your Environment terminal below.`}
           </p>
         )}
@@ -174,7 +175,7 @@ export function AgentSetup({
             <>
               {login && (
                 <p className="text-ui text-text">
-                  Log in once by running <Code>{login.command}</Code> in your environment terminal. {login.hint}
+                  Log in once by running <Code ref={canInstall ? commandSource : undefined}>{login.command}</Code> in your environment terminal. {login.hint}
                 </p>
               )}
               {setupCommand && (
@@ -183,7 +184,7 @@ export function AgentSetup({
                   <Button
                     type="button"
                     variant="secondary"
-                    onClick={() => void copyText(setupCommand, null)}
+                    onClick={() => void copyText(setupCommand, commandSource.current)}
                   >
                     {canInstall ? 'Copy login command' : 'Copy install command'}
                   </Button>