[brennanb2025]

	Files	Added	Deleted	Net
Test	11	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​805	$\color{#cf222e}{\Huge{\mathbf{−}}}$​434	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​371
Prod	12	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​303	$\color{#cf222e}{\Huge{\mathbf{−}}}$​253	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​50

The problem

When Orca starts an agent, it types the agent's launch line into a shell that is often still starting.

A long or multi-line launch line breaks there: lines go missing, the shell sits at a quote> prompt, or the agent starts with half its text.

Why: macOS keeps at most 1,024 bytes of a line typed into a terminal that is still starting, and a newline inside the line is read as Enter, so bash 3.2 runs each line of a multi-line prompt as its own command and fish drops an early multi-line write.

Today Orca avoids this only by keeping long or multi-line prompts off the launch line (#24257 pastes them once the agent is ready), so any launch line that still gets long or multi-line (a resume line, an SSH background launch, a terminal created with a long command, a multi-line zsh prompt up to 8 KB) is typed raw and can be cut or run in pieces.

Before and after, for the agent

What the agent receives does not change. The agent gets the same command and the same prompt text as before; nothing is added to or removed from the prompt. What changes is how that command reaches the shell, and only when the command is long or multi-line.
Before: Orca typed the whole launch command into the terminal, often while the shell was still starting. A multi-line prompt's newlines were read as Enter (bash 3.2 ran each line as its own shell command), and a line over ~1,024 bytes typed into a still-starting macOS terminal lost the rest. So the agent started with half its prompt, or never started and the shell sat at a quote> prompt.
After: Orca writes the exact same command into a private, self-deleting script (mode 0600) and types one short line that runs it, e.g. . '/…/orca-launch-a1b2.sh'. The shell runs exactly the bytes Orca meant to type, so the agent starts with its full prompt.
Unchanged: a launch command of 512 bytes or less with no newline or control character is typed exactly as today, so most launches look and behave the same.

What changes for you

A long or multi-line launch line on a macOS or Linux host (local, SSH, background) now reaches the agent whole, in bash, zsh, sh, dash, fish, ksh and mksh.

What you see in the terminal is one short line instead of the long one: . '/…/orca-launch-<random>.sh' in bash, zsh, sh and dash, eval (string collect < '…') in fish, and /bin/sh '…' for Orca's own long agent lines in ksh and mksh. The agent runs as a normal foreground job, so Ctrl-Z and Ctrl-C behave as if the line had been typed.

If Orca cannot write the launch script (disk full, unwritable temp dir), the terminal prints [orca] Could not stage the launch command (...) and types the line as before, so you see why it may fail instead of a silent quote> prompt.

In tcsh, nu and other shells whose quoting Orca does not speak, Orca's own agent launch line runs through /bin/sh when it is long, has a control character, or holds a character those shells do not read literally inside Orca's quoting (!, backslash, ", $, backtick); a plain line is typed as before, and commands you wrote yourself are always typed exactly as before.

Lines of 512 bytes or less with no control character are typed exactly as today.

Known limit: the shell's history holds the short line, and the script deletes itself when it runs, so pressing up-arrow and Enter does not relaunch the agent.

Scope

In scope: the places Orca types a startup line into a terminal on a macOS or Linux shell through the terminal daemon, the SSH relay or the in-process terminal provider, for local, SSH and background launches.

Not in scope:

• Windows hosts, in every shell there (cmd, PowerShell, Git Bash, WSL panes): cmd and PowerShell cannot run the script, and Git Bash and WSL panes go through the Windows host's own launch path. Step 3 routes those prompts to a launch file.
• The SSH fallback without the relay (plain shell over SSH), which still types the line as soon as the channel opens.
• Anything typed into an already-running terminal, and which prompts ride the launch line at all (that rule stays feat(agent-launch): keep long prompts off the launch line and paste them after readiness (step 1 of 7) #24257's until step 3 relaxes it).

The plan, and where this PR sits

This is step 2 of 7 of the agent launch plan:

1. feat(agent-launch): keep long prompts off the launch line and paste them after readiness (step 1 of 7) #24257 (merged): the host owns prompt delivery; a prompt the command line can't safely carry is pasted only once the agent is ready, and only when the agent is proven to be in front.
2. This PR (Stage long agent launch lines where they are typed, so they arrive whole (step 2 of 7) #23962): long launch lines arrive whole.
3. Carry an agent's first prompt on its command line instead of pasting it (step 3 of 7) #24080: the first prompt rides the agent's command line, with a "prompt wasn't sent" notice and Copy prompt on five launch surfaces.
4. Start orchestration workers with their brief on the launch command line (step 4 of 7) #24081: orchestration workers get their brief on the launch line.
5. feat(agent-launch): host-assigned caller identity and a launch record written when the tab exists (unification 1 of 3) #24934: Orca assigns each caller its identity and keeps a launch record, so after a restart mid-launch a retry finds the running agent instead of "couldn't confirm".
6. feat(agent-launch): show an agent's tab at once, where the caller asked #25430: the agent's tab appears at once, in the split you asked for.
7. feat(agent-launch): the desktop AI buttons start their agent through agent.launch #25624: the desktop AI buttons (Fix checks, Resolve conflicts, commit/push recovery, Explain commit) go through agent.launch (supersedes feat(source-control): start the AI buttons' agents through agent.launch (step 2 of 2) #23748).

How it works

1. When it accepts a spawn, the host that owns the terminal looks at the line it is about to type; a line over 512 bytes (half of macOS's limit) or with a control character is written to a private (0600) script whose first command deletes the script. The 512-byte limit and the control-character check are feat(agent-launch): keep long prompts off the launch line and paste them after readiness (step 1 of 7) #24257's, imported rather than copied.
2. The host then types one short line that runs the script as the shell's own foreground job: . '<script>' in bash, zsh, sh and dash; eval (string collect < '<script>') in fish, because fish runs a sourced file without job control; and /bin/sh '<script>' for Orca's own long agent lines in ksh and mksh, because ksh runs a sourced file inside the shell's own process group. In tcsh, nu and other shells Orca's quoting does not cover, an Orca-built line also goes through /bin/sh when it holds !, backslash, ", $ or a backtick, which those shells would not read literally.
3. The host removes a script the shell never ran when the terminal exits. Once per app start, at the first staged launch, it also sweeps leftovers older than an hour from the temp dir.
4. SSH background launches now let the relay type the line, as SSH terminals already did, so the renderer's separate writer (which never staged) is gone.
5. The terminal daemon protocol moves to 40 (main took 39 for fish panes in fix(terminal): give plain fish tabs Orca's codex function without changing fish's startup #24284). New terminals are never placed on a v39 or older daemon, so it is never sent a staged line; its existing sessions keep running. A respawn that reuses a session id still owned by an old daemon goes to that daemon, as before.

Why this approach

The decision is made where the bytes are written, by the host that owns the terminal, so one rule covers daemon, relay and in-process terminals instead of a check on every launch path.

A script the shell runs executes the exact bytes Orca quoted; no escaping trick survives every shell's line editor.

Alternatives considered: passing the agent line through an environment variable (Orca already does this for setup-sequenced startup, but for agent lines the value stays in the shell's environment, is inherited by every child, and needs shell-specific syntax to read) and making the agent the terminal's first process (it skips Orca's shell wrappers, setup sequencing and the "tab stays a shell" behaviour).

How this differs from the common pattern (comparison from the first architecture review of this change):

• Same mechanism: the common pattern also stages a startup command in a script the shell runs.
• Intended difference: Windows hosts never stage, because cmd and PowerShell cannot run a POSIX script; step 3 routes those prompts to a launch file.
• Intended difference: in shells whose quoting Orca does not speak, only Orca's own agent lines go through /bin/sh, and only when they need it; a user's command is never rewritten.
• Intended difference: a failed stage types the full line with a visible notice rather than refusing the launch, so bookkeeping never blocks the user's action.

How this differs from the previous version of this PR

The previous version sat on #23748 (desktop AI buttons); this version sits on #24257 and contains none of #23748's changes. The daemon protocol bump is 40 instead of 39, because main took 39.

Changed in this round's review:

• In fish and ksh, the staged agent used to run inside the shell's own process group, so Ctrl-Z could not stop it and feat(agent-launch): keep long prompts off the launch line and paste them after readiness (step 1 of 7) #24257's "is the agent in front" check could misread the terminal. Fish now runs the script with eval, and ksh/mksh run Orca's long agent lines through /bin/sh; a new real-shell test checks that the agent gets its own process group in every shell.
• The 512-byte limit and the control-character check now come from feat(agent-launch): keep long prompts off the launch line and paste them after readiness (step 1 of 7) #24257 instead of a copy.
• In tcsh and nu, every Orca agent line used to run through /bin/sh, so the agent was sh's child; live on a loaded Mac, feat(agent-launch): keep long prompts off the launch line and paste them after readiness (step 1 of 7) #24257's paste guard then reported a pasted prompt as not delivered. A plain agent line is now typed directly there, so the agent is the shell's own job.
• feat(agent-launch): keep long prompts off the launch line and paste them after readiness (step 1 of 7) #24257's newer heads are merged in (its crash guard, the long-poll agent.launch, and its check that finds an agent behind a wrapper such as /bin/sh).

Size

23 files, +1,108/−688 against #24257's branch.

Testing

• The PR's own test files plus every changed feat(agent-launch): keep long prompts off the launch line and paste them after readiness (step 1 of 7) #24257 test file: 15 files, 219 tests pass. They include real-shell tests that launch bash, zsh, sh, dash, fish, ksh and tcsh through a pseudo-terminal and check the agent gets its argument byte for byte and runs in its own foreground process group (that check fails for every fish and ksh case without this round's fix).
• tc:node, tc:web and tc:cli pass; oxlint and check:code-quality:changed are clean.
• Live QA on a Mac (zsh, bash 3.2, fish 4.9, tcsh) and on Windows (cmd, PowerShell 5.1 and 7, Git Bash, WSL), main vs this PR, is in the status comment.

Visual Proof

N/A: no UI changes; this only changes whether a long launch line arrives whole. Live QA evidence is in the status comment.

Notes

Author X handle: @BrennanKB5

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 53db116a-a09d-4510-a146-fb13465228f4

📥 Commits

Reviewing files that changed from the base of the PR and between 853545d and 031bcc4.

📒 Files selected for processing (3)

• src/main/daemon/daemon-pty-startup-delivery.test.ts
• src/main/daemon/terminal-host-startup-staging.test.ts
• src/main/providers/local-pty-provider-shell-readiness.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds shared startup-command staging and uses it in daemon, local PTY, and relay delivery paths. Staged scripts are removed during cleanup, and staging failures produce terminal notices while the original command is delivered. SSH background launches now request provider command delivery and shell-ready startup delivery instead of using renderer-side marker and fallback handling. The daemon protocol and local-build compatibility contract advance to version 41.

Priority: ➖ Normal

Merge Risk: 🟡 Moderate · up to 031bc

An SSH launch using fish may lose its startup command if the shell is slow to become ready. Confirm delivery or add a readiness gate before merging.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 031bc

Launch delivery now stores eligible commands in private temporary files. Restrictive permissions limit exposure, but a partially failed write can leave command text behind without normal cleanup. Remote startup timing and mixed-version operation remain only partly established.

Retained concerns

• Low · security · inferred: If an exclusive script write creates the file and then fails after writing command bytes, the failure result drops the script path without removing the file. Session cleanup consequently cannot find it, and the one-time sweep skips fresh leftovers. This introduces potentially prolonged retention of sensitive launch text. Mode 0600 limits access to the owning account and privileged readers; no cross-user disclosure was demonstrated.

Security review details

Security Blast Radius

• inferred — The identified retention concern applies to eligible launches across all three staging callers, on the local or selected SSH execution host. Restrictive file permissions bound ordinary filesystem access to the owning account; same-account processes and privileged readers remain relevant. The inspected change does not establish a new cross-tenant or privilege-escalation path.

Security Findings and Attack Paths

• inferred — A failure after file creation and partial payload writing can strand launch text: the catch branch returns no cleanup identity, discard ignores results without a script path, and the initial sweep excludes fresh files. Disclosure would additionally require filesystem access permitted by the owning account's controls; no actual disclosure or fault-injection result was supplied.

Trust Boundaries and Controls

• observed — Exclusive creation resists pre-existing filename substitution, mode 0600 restricts script access, and portable quoting treats script paths as shell arguments. Staging transports an already-authorized command; it does not sandbox or validate that command's execution authority.

Resilience and Maintainability Implications

• observed — Successful staging retains a cleanup path. Daemon and local exits discard it, relay disposal discards it, and repeated removal tolerates an already-unlinked file. Daemon cancellation checked immediately after spawn precedes staging, avoiding a staged file on that cancellation branch. These controls do not cover a failed write whose result lacks the path.

Hardening Proposals

• proposed — Retain ownership of a newly created script through write completion and remove it on subsequent write failure. Distinguish creation failure from failure after creation so cleanup never removes a pre-existing collision target. Validate this with partial-write fault injection and explicitly define recovery retention bounds.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 19.05% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 21 functions across 20 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: staging long agent launch lines so they reach the shell intact. The step number adds context without obscuring the purpose.
Description check	✅ Passed	The description gives detailed context on the problem, behavior, scope, implementation, alternatives, and testing. However, it says the protocol changes to version 40, while the changeset updates it t…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pullfrog]

Important

The origin/main merge left several of this PR's own staging tests asserting the old LF terminator, so seven tests are red. Main's #23672 made buildStartupCommandSubmission submit with CR; the merge updated the pre-existing tests but not this PR's newly-added ones in terminal-host-startup-staging.test.ts, local-pty-provider-shell-readiness.test.ts, and daemon-pty-startup-delivery.test.ts. I reproduced all seven failures locally.

Reviewed changes

• Merged origin/main (853545d6d8): main took daemon protocol v40 (#25291), so this PR's staging moves to v41 with v40 attachable (version file, local-build contract JSON + TS, pinned tests).
• Adopted main's CR startup-command submission (#23672): dropped the submit option from the daemon and relay buildStartupCommandSubmission calls; the relay now types managed.stagedStartupCommand?.command ?? startup.command.
• Updated the pre-existing staging assertions to CR (terminal-host.test.ts, pty-handler-startup-command-*.test.ts, the older cases of daemon-pty-startup-delivery.test.ts, startup-command-staging.node-pty.test.ts).

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

Main's #23672 now submits startup commands with \r, but this PR-added file still asserts ; sub.write receives claude 'fix it'\r, so this test and the expectations at lines 72, 79 and 116 all fail. Update the four expectations to \r (and the regex at line 79 to /^\. '.*orca-launch-[0-9a-f]+\.sh'\r$/).

[pullfrog]

Same stale LF terminator: after #23672 mockProc.write gets . '<script>'\r, so this and line 263 fail. Change both to \r.

[pullfrog]

This new assertion expects , but the merged buildStartupCommandSubmission emits \r, so the write is . '<script>'\r and the test fails. Change to \r (matching the CR you already applied to this file's earlier expectations).

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

🟡 Minor · Preserve the no-output grace for SSH startup. · launch-agent-background-session.ts:180-185

src/renderer/src/lib/launch-agent-background-session.ts:180-185
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Preserve the no-output grace for SSH startup.

When the relay supports shell-ready markers but the shell stays silent and the prompt probe does not identify readiness, it submits the command after 1.5 seconds. The previous path allowed 15 seconds for a silent shell because startup can still be running. Sending bracketed paste before readline is ready can cause the background agent launch to fail. Keep the 15-second grace while the shell is silent, then shorten it after output arrives.

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: bd7a169f-d2c9-45b0-9188-0cb332d33a0c

📥 Commits

Reviewing files that changed from the base of the PR and between 83de487 and 853545d.

📒 Files selected for processing (12)

• src/main/daemon/daemon-foreground-confirmation-protocol.test.ts
• src/main/daemon/daemon-protocol-version.test.ts
• src/main/daemon/daemon-protocol-version.ts
• src/main/daemon/daemon-pty-startup-delivery.test.ts
• src/main/daemon/terminal-host-session-create.ts
• src/main/daemon/terminal-host.test.ts
• src/relay/pty-handler-startup-command-staging.test.ts
• src/relay/pty-handler.ts
• src/renderer/src/lib/ssh-background-startup-delivery.ts
• src/shared/local-build-compatibility-contract.json
• src/shared/local-build-compatibility-contract.ts
• src/shared/startup-command-staging.node-pty.test.ts

💤 Files with no reviewable changes (1)

• src/renderer/src/lib/ssh-background-startup-delivery.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Stage before new Session(...), or discard the script when the session has already exited.

The exit closure at Line 167 reads staging before the assignment at Line 208 runs. If the shell exits before the listener is attached, the pre-listener exit replays synchronously and discards undefined. The code then writes the staged script, and session.write does nothing. No later step deletes the script, which contains the prompt.

After staging, check session.isAlive. If the session has exited, call discardStagedStartupCommand(staging).