Skip to content

test(relay): pin folder-workspace PTY cwd across paired and SSH topologies (STA-4746) - #15385

Closed
Jinwoo-H wants to merge 6 commits into
mainfrom
aug18-p1-sta-4746-folder-remote-cwd-claude
Closed

Jinwoo-H wants to merge 6 commits into
mainfrom
aug18-p1-sta-4746-folder-remote-cwd-claude

Conversation

@Jinwoo-H

@Jinwoo-H Jinwoo-H commented Aug 18, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 5 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​609 0 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​609
Prod 0 0 0 0

Summary

STA-4746 is invalid — on current main and on the reported v1.4.184. This PR contains no production change, only the regression coverage that proves it and guards the contract.

The report claimed that in a paired/remote setup a folder workspace (ORCA_WORKTREE_ID=folder:<uuid>) makes the relay spawn its PTY in a fallback cwd, because "relay cwd resolution only consults ORCA_WORKTREE_ID, parses it as repoId::path, and never falls back to ORCA_WORKSPACE_ROOT."

That is not how the relay resolves cwd. PtyHandler.spawnAfterAdmission takes cwd from the spawn request (params.cwd); splitWorktreeId(worktreeId) feeds only the beginPtyCreation admission key. The client side already resolves folder:<uuid> through resolveTerminalStartupCwdForWorkspace → store.getFolderWorkspace(id).folderPath.

What actually produces the reported symptom

On every POSIX relay branch the host's login startup chain runs after the PTY is placed, so a remote startup file that cds wins after the shell already started in the workspace root. Two mechanisms get there:

  • zsh and other POSIX shells launch with POSIX_LOGIN_ARGS = ['-l'] (src/relay/pty-shell-launch.ts:12), so /etc/profile, /etc/profile.d/* and ~/.zprofile are sourced.
  • bash is normally wrapped (--rcfile, not -l), but the relay's own wrapper explicitly sources /etc/profile, then ~/.bash_profile / ~/.bash_login / ~/.profile (src/relay/pty-shell-overlay-wrappers.ts:63-70).

That is exactly the reporter's own evidence:

OLDPWD=/opt/tiger/workspace          # shell started here
PWD=/opt/tiger/rh2/rh2/init          # then cd'd away

OLDPWD is only ever set by cd. Phase B of the SSH spec reproduces that byte-shape by adding one /etc/profile.d entry to the container. Phase C shows the same cd moves a plain repoId::/path git worktree identically, so this mechanism is not folder-specific. That establishes a non-folder-specific cause for the reported signature; combined with the topology table below finding no folder-specific defect, it is why this closes as invalid.

Evidence (all on clean main @ 1b5cc00)

Topology Result
Headed paired desktop server + paired desktop client (primary) folder PTY lands on host folderPath; filesystem marker written into folderPath; git-worktree + host-local controls green
Headless orca serve paired host terminal.create(folder:<uuid>) → pwd == folderPath
Real Docker SSH relay (~/.orca-remote/relay-0.1.0+…) shell $PWD and remote /proc/<pid>/cwd both == folder path

Version oracle

The cwd-resolution logic is behaviourally identical at v1.4.184: src/shared/terminal-startup-cwd.ts and src/shared/workspace-scope.ts differ only by import-path moves (shared/worktree-id → shared/worktree/id, shared/types → shared/folder-workspace-types), and src/relay/pty-handler.ts still takes cwd from params.cwd. Those files carry unrelated changes since the tag — the equivalence claim is about the cwd path, not the whole diff. v1.4.184 also did not send worktreeId as a spawn param at all (added later in ssh-pty-spawn-request.ts for shell-history isolation), so the relay could not have derived cwd from it there either. Nothing was "already fixed".

Separately, on node-pty's POSIX implementation a nonexistent cwd makes the child exit 1 rather than silently inheriting the parent's cwd (node_modules/node-pty/src/unix/pty.cc), ruling out the "fell back to the container's CMD directory" mechanism as well. Windows uses a different spawn path and was not measured.

Why the proposed fix is not implemented

The proposed ORCA_WORKSPACE_ROOT fallback would change nothing for the reporter — cwd is already correct at spawn — and it would make the relay adopt an unvalidated client-supplied path for a request that named no working directory.

cwd is optional on the wire (PtySpawnOptions.cwd, src/main/providers/pty-provider-contract.ts:42), and the relay's default-cwd branch exists for requests that genuinely name none. But every relay-bound caller for a folder workspace resolves a path first via resolveTerminalStartupCwdForWorkspace; the one in-repo caller that can omit cwd (codex-detached-pane-restart.ts:210) is local-only and never reaches the relay. So the fallback has no relay caller to serve, and promoting an env var into it would only widen what the relay trusts.

Coverage added

  • src/relay/pty-handler-folder-workspace-cwd.test.ts — 5 deterministic cases: folder id honours request cwd, folder id with no ORCA_WORKSPACE_ROOT, worktree-id precedence unchanged, legacy/mixed-version client (env-only ORCA_WORKTREE_ID), and the default-cwd fallback pinned to not adopt ORCA_WORKSPACE_ROOT.
  • tests/e2e/sta4746-folder-remote-cwd.spec.ts — headless paired orca serve host.
  • tests/e2e/sta4746-paired-desktop-folder-cwd.spec.ts — headed paired desktop server + client (@headful), with git-worktree and local-only controls.
  • tests/e2e/sta4746-ssh-folder-cwd.spec.ts — real Docker SSH relay, 3 phases (clean / login-profile cd / git-worktree control), gated on ORCA_E2E_SSH_DOCKER=1 like the sibling docker specs.

Guard is non-vacuous: injecting the alleged id-derived cwd into pty-handler.ts turns 4 of the 5 relay cases red; reverting the injection returns 5/5 green.

Commands

npx vitest run --config config/vitest.config.ts src/relay/pty-handler-folder-workspace-cwd.test.ts
npx playwright test tests/e2e/sta4746-folder-remote-cwd.spec.ts --config tests/playwright.config.ts --project electron-headless
npx playwright test tests/e2e/sta4746-paired-desktop-folder-cwd.spec.ts --config tests/playwright.config.ts --project electron-headful
ORCA_E2E_SSH_DOCKER=1 npx playwright test tests/e2e/sta4746-ssh-folder-cwd.spec.ts --config tests/playwright.config.ts --project electron-headless

Gaps

CI runs all three specs on Linux runners (the changed-e2e job picked them up and all 3 passed), and the SSH phases were additionally exercised against a Linux container from a macOS host. Windows and WSL hosts were not exercised.

Closes STA-4746 as invalid.

…ogies (STA-4746)

STA-4746 reported that a remote/paired agent under a folder workspace
(ORCA_WORKTREE_ID=folder:<uuid>) spawns its relay PTY in a fallback cwd
because relay cwd resolution only parses repoId::path worktree ids.

The relay has always taken cwd from the spawn request; splitWorktreeId()
feeds only the beginPtyCreation admission key. The reported symptom comes
from the remote host's own login startup files: the relay spawns POSIX
login shells, so an /etc/profile.d entry that cd's wins after the shell
already started in the workspace root (hence OLDPWD=<workspace> in the
report). The same cd moves a plain git worktree identically.

Test-only; no behavior change. Injecting the alleged id-derived cwd into
pty-handler turns 4 of the 5 relay cases red.
@coderabbitai

coderabbitai Bot commented Aug 18, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 09393323-1f38-4b32-b7bd-2fa171260f7d

📥 Commits

Reviewing files that changed from the base of the PR and between b35943b and b0f469f.

📒 Files selected for processing (5)
  • src/relay/pty-handler-folder-workspace-cwd.test.ts
  • tests/e2e/helpers/sta4746-cwd-probe.ts
  • tests/e2e/sta4746-folder-remote-cwd.spec.ts
  • tests/e2e/sta4746-paired-desktop-folder-cwd.spec.ts
  • tests/e2e/sta4746-ssh-folder-cwd.spec.ts

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


📝 Walkthrough

Walkthrough

Adds unit and end-to-end tests for terminal cwd behavior in folder workspaces. The tests cover local PTY cwd precedence, headless remote runtimes, paired desktop clients, and SSH relay hosts. They verify working directories, workspace-root and worktree environment variables, PTY ownership, login-profile directory changes, process cwd, marker commands, Git worktree behavior, and resource cleanup.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the test-only regression coverage for folder-workspace PTY cwd behavior across paired and SSH topologies.
Description check ✅ Passed The description clearly explains the test-only scope, rationale, linked issue, coverage, commands, platform gaps, and out-of-scope follow-ups.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

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

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🧹 Nitpick comments (2)
tests/e2e/sta4746-folder-remote-cwd.spec.ts (1)

14-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Remove the temporary directory in the finally block.

The test creates parent under the OS temp directory but never removes it. Each run leaves a workspace tree behind. The paired-desktop spec removes its temp tree with rmSync; apply the same cleanup here.

♻️ Proposed cleanup
-import { mkdtempSync, mkdirSync } from 'node:fs'
-import { realpathSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, realpathSync, rmSync } from 'node:fs'
 test('STA-4746: folder-workspace terminal on a headless paired host', async () => {
   test.setTimeout(240_000)
   const host = await launchHeadlessPairedRuntimeHost()
+  let parent: string | undefined
   try {
-    const parent = realpathSync(mkdtempSync(path.join(os.tmpdir(), 'sta4746-')))
+    parent = realpathSync(mkdtempSync(path.join(os.tmpdir(), 'sta4746-')))
     const folderPath = path.join(parent, 'workspace')
   } finally {
     await host.dispose()
+    if (parent) {
+      rmSync(parent, { recursive: true, force: true })
+    }
   }
 })

Also applies to: 69-71

tests/e2e/sta4746-paired-desktop-folder-cwd.spec.ts (1)

21-64: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Duplicated probeWorkspaceTerminal in two specs. Both specs contain a near-identical store-activation, keyboard-probe, and poll implementation. Only the probe token, the printf format, and the poll timeout differ.

  • tests/e2e/sta4746-paired-desktop-folder-cwd.spec.ts#L21-L64: move this implementation into tests/e2e/helpers/terminal.ts with parameters for the probe token, printf fields, and timeout, then import it here.
  • tests/e2e/sta4746-ssh-folder-cwd.spec.ts#L25-L68: delete the local copy and call the shared helper with the SSH probe token and the 90-second timeout.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d6f1c832-5c90-456b-a783-eb12d4065934

📥 Commits

Reviewing files that changed from the base of the PR and between 1b5cc00 and 236db85.

📒 Files selected for processing (4)
  • src/relay/pty-handler-folder-workspace-cwd.test.ts
  • tests/e2e/sta4746-folder-remote-cwd.spec.ts
  • tests/e2e/sta4746-paired-desktop-folder-cwd.spec.ts
  • tests/e2e/sta4746-ssh-folder-cwd.spec.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

Independent review flagged that the specs could pass without proving the
claim. Assert exact parsed probe fields instead of substring matches (a
sibling path with the expected path as a prefix would have passed), pin
the PTY owner shape per topology (folder:/remote:/ssh:) so a client-local
or daemon-local fallback cannot satisfy the path assertions, read
/proc/$$/cwd from the probed shell itself rather than scanning every
remote bash, and have the injected login profile record where each shell
started so the profile-cd phases no longer rest on OLDPWD alone.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 96323276-1fd2-4104-90de-c12c70e63e15

📥 Commits

Reviewing files that changed from the base of the PR and between 22b11ba and b5583ea.

📒 Files selected for processing (5)
  • src/relay/pty-handler-folder-workspace-cwd.test.ts
  • tests/e2e/helpers/sta4746-cwd-probe.ts
  • tests/e2e/sta4746-folder-remote-cwd.spec.ts
  • tests/e2e/sta4746-paired-desktop-folder-cwd.spec.ts
  • tests/e2e/sta4746-ssh-folder-cwd.spec.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • src/relay/pty-handler-folder-workspace-cwd.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review.

Comment on lines +146 to +148
expect(profiledWorktree.pwd).toBe(REMOTE_PROFILE_CD_PATH)
expect(profiledWorktree.oldpwd).toBe(DOCKER_SSH_RELAY_REMOTE_REPO_PATH)
expect(profiledWorktree.root).toBe('')

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Assert the Git-worktree process cwd and worktree ID.

Phase C emits selfcwd and wt, but does not check them. A regression can leave ORCA_WORKTREE_ID unset or report an incorrect shell process cwd while these assertions pass.

Proposed fix
 expect(profiledWorktree.pwd).toBe(REMOTE_PROFILE_CD_PATH)
+expect(profiledWorktree.selfcwd).toBe(REMOTE_PROFILE_CD_PATH)
 expect(profiledWorktree.oldpwd).toBe(DOCKER_SSH_RELAY_REMOTE_REPO_PATH)
 expect(profiledWorktree.root).toBe('')
+expect(profiledWorktree.wt).toBe(gitWorktreeKey)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
expect(profiledWorktree.pwd).toBe(REMOTE_PROFILE_CD_PATH)
expect(profiledWorktree.oldpwd).toBe(DOCKER_SSH_RELAY_REMOTE_REPO_PATH)
expect(profiledWorktree.root).toBe('')
expect(profiledWorktree.pwd).toBe(REMOTE_PROFILE_CD_PATH)
expect(profiledWorktree.selfcwd).toBe(REMOTE_PROFILE_CD_PATH)
expect(profiledWorktree.oldpwd).toBe(DOCKER_SSH_RELAY_REMOTE_REPO_PATH)
expect(profiledWorktree.root).toBe('')
expect(profiledWorktree.wt).toBe(gitWorktreeKey)

CI's narrower terminal wraps the probe line, so xterm leaves cursor-motion
sequences inside the rendered row and the last field arrived as
`<path>ESC[1BESC[29D`. Strip escapes with the shared
stripAnsiEscapeSequences, and terminate the probe with `end=1` so a
half-rendered row is retried instead of asserted as the real cwd.
@Jinwoo-H

Copy link
Copy Markdown
Contributor Author

Do not merge without review — this PR is test-only and the ticket it documents is already closed as invalid.

Two follow-ups from the independent review pass, both out of scope here and unverified end to end, recorded so they are not lost:

  1. src/renderer/src/components/terminal-pane/codex-detached-pane-restart.ts:210 respawns through window.api.pty.spawn with no connectionId. getProvider(undefined) returns the local provider (src/main/ipc/pty.ts:978), and this path bypasses pty-connection.ts, so it also bypasses the unresolved-owner guard added in fix(ssh): stop remote terminals fail-opening to local PTY #10778. A Codex account-switch restart in an SSH workspace would then respawn locally with a remote-only cwd. Not folder-specific, and I did not reproduce it.

  2. launchWorktreeBackgroundTerminals (src/renderer/src/lib/launch-worktree-background-terminals.ts:271) looks up store.allWorktrees(), which excludes folder-workspace projections, so a folder:<uuid> key would throw "The target workspace is no longer available." Its only caller (useAutomationDispatchEvents.ts:315) passes a freshly created git worktree id, so this is not currently reachable — noting it only as a latent trap if a folder key ever reaches that function.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d8881534-f65f-488e-bdfa-9e8324ad1685

📥 Commits

Reviewing files that changed from the base of the PR and between b5583ea and b35943b.

📒 Files selected for processing (2)
  • tests/e2e/helpers/sta4746-cwd-probe.ts
  • tests/e2e/sta4746-folder-remote-cwd.spec.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.

Comment thread tests/e2e/helpers/sta4746-cwd-probe.ts Resolved
Independent review found the specs could pass on the wrong host and left
state behind. Bind the PTY-owner assertions to the actual SSH connection
id and paired environment id instead of any `ssh:`/`remote:` prefix; bound
the joined-row probe parse at its own `end=1` terminator so it cannot
splice fields from unrelated rows, and delimit the phase so one phase name
cannot match another's prefix.

Also: share one probeWorkspaceTerminal in the helper instead of three
near-copies, reuse the hardened parser in the headless spec, remove the
temp dirs and the per-phase tabs in finally, skip on win32 like sibling
POSIX specs, and compute the default-cwd expectation instead of reading
process.env.HOME, which is unset on some CI images.
@Jinwoo-H

Copy link
Copy Markdown
Contributor Author

CI note: the 4 red unit shards are inherited from main, not from this PR.

main advanced by one commit while this was open — #15381 (WSL transcript fs quarantine) — and it turns 4 tests red in src/main/ai-vault/. This branch now merges that commit, so the PR's checks show them.

Evidence that they are not mine:

  • This branch was fully green (47 pass / 0 fail) at b35943b79f, before the merge.
  • The diff here touches no file under src/main/.
  • Running only the two affected files — so nothing from this PR is even loaded — reproduces the failure at 4ec6bbf588 and passes at its parent 1b5cc00870.

Reported with a repro at #15381 (comment). This PR's own coverage is green: relay unit 5/5, and the changed-e2e lane ran all three specs (headless paired, headful paired, Docker SSH relay) on Linux runners.

@OrcaWin

OrcaWin commented Oct 11, 2026

Copy link
Copy Markdown
Collaborator

Thank you @Jinwoo-H for proving STA-4746 invalid. These tests pin the relay's PTY handler, which was deleted with the relay (#27215); SSH terminals now spawn through Orca's managed remote server. Closing as no longer applicable.

@OrcaWin OrcaWin closed this Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants