Skip to content

[Bug]: Remote/paired agent PTY spawns in fallback cwd instead of the workspace path when the workspace context is folder:<uuid> (relay ignores ORCA_WORKSPACE_ROOT) #15296

Closed

Description

@lyksdu

Operating system

macOS

Orca version

1.4.184

Details

Summary

In a paired/remote setup, when an agent is launched under a folder-type workspace
(ORCA_WORKTREE_ID=folder:<uuid>), the relay spawns the agent's PTY in a fallback
working directory instead of the configured workspace path. The correct path is
available to the relay the whole time via ORCA_WORKSPACE_ROOT, but it is never used
when resolving the PTY's cwd.

Environment

  • Orca desktop app version 1.4.184, paired to a remote Linux box via
    --pairing-address (headless AppRun serve).
  • Relay running on the remote box (version 0.1.0+a02497db1fab).
  • Workspace configured in the desktop UI as a folder workspace with an explicit path.
  • Agent: Claude Code, launched from the desktop into the remote box through the relay.

Steps to reproduce

  1. In the desktop app, create a folder workspace and set its path to some directory
    (e.g. /opt/tiger/workspace).
  2. Pair to a remote box and start an agent/terminal in that workspace.
  3. Inspect the working directory of the spawned shell/agent on the remote box.

Expected behavior

The agent's PTY starts in the configured workspace path (/opt/tiger/workspace).

Actual behavior

The PTY starts in an unrelated fallback directory (on our box, the container's default
CMD directory /opt/tiger/rh2/rh2/init), not the workspace path.

Root cause (evidence)

The configured path is delivered to the remote shell — it is present in the spawned
process environment as ORCA_WORKSPACE_ROOT. The environment of the mis-placed shell
looks like this:

ORCA_WORKSPACE_ID=folder:b1706d92-9d05-4932-8360-01e00b54305a
ORCA_WORKTREE_ID=folder:b1706d92-9d05-4932-8360-01e00b54305a
ORCA_WORKSPACE_ROOT=/opt/tiger/workspace     # configured path — delivered correctly
OLDPWD=/opt/tiger/workspace                  # cwd was briefly here during startup
PWD=/opt/tiger/rh2/rh2/init                  # final cwd — the fallback directory

When the relay resolves the PTY's cwd, it only consults ORCA_WORKTREE_ID. That value
is parsed as a worktree:<repoId>::<path>-style identifier (split on ::). A folder
workspace's id has the form folder:<uuid> with no ::, so the parse yields no path,
and the relay falls back to a default cwd.

Crucially, ORCA_WORKSPACE_ROOT=/opt/tiger/workspace is right there in the same
environment but is never used as a fallback when the worktree-id does not resolve to a
path. (OLDPWD shows the cwd passed through the workspace root during startup before
being overridden by the fallback.)

For comparison, agents launched through the non-relay path (no ORCA_* context) start
directly in the correct workspace directory — the problem is specific to the relay's
cwd resolution for folder:<uuid> contexts.

Proposed fix

When resolving the PTY's spawn cwd, if the ORCA_WORKTREE_ID does not resolve to a
worktree path (e.g. it is a folder:<uuid> context), fall back to
ORCA_WORKSPACE_ROOT when it is set and points to an existing directory, before
falling back to the generic default:

worktreePath(ORCA_WORKTREE_ID)
  ?? (isDir(ORCA_WORKSPACE_ROOT) ? ORCA_WORKSPACE_ROOT : undefined)
  ?? requestCwd
  ?? default

This keeps existing worktree:<repoId>::<path> behavior unchanged and only adds a
sensible fallback for folder workspaces, which today have no way to convey their path
to the relay's cwd resolver despite ORCA_WORKSPACE_ROOT already carrying it.

Notes

Activity

  1. added theissue type on Aug 18, 2026
  2. AmethystLiang commented on Aug 18, 2026

    @AmethystLiang
    Contributor

    thanks for reporting. looking into it

  3. Jinwoo-H commented on Aug 18, 2026

    @Jinwoo-H
    Contributor

    Closing as invalid — the relay never derives PTY cwd from ORCA_WORKTREE_ID

    Thanks for the detailed write-up; the environment dump is what made this diagnosable. I reproduced your symptom exactly, but the cause is not the one in the report, and there is nothing to fix in Orca.

    The reported root cause does not exist in the code

    PtyHandler.spawnAfterAdmission takes the PTY's cwd from the spawn request (params.cwd). splitWorktreeId(worktreeId) is used only to build the beginPtyCreation admission key and the worktree-removal shutdown scope — never for cwd. On the client side resolveTerminalStartupCwdForWorkspace already resolves folder:<uuid> through the folder-workspace record's folderPath, so the correct path is sent explicitly on every spawn.

    This is also true at the version you reported. The cwd chain at v1.4.184 differs from main only by import-path moves. In fact v1.4.184 did not even send worktreeId as a relay spawn parameter (it was added later, for shell-history isolation), so the relay could not have parsed it for cwd there either.

    What actually moves the shell

    The relay spawns POSIX login shells (POSIX_LOGIN_ARGS = ['-l']). A login shell sources /etc/profile and /etc/profile.d/*, so a remote startup file that cds wins after the shell has already started in the workspace root. Your own dump says exactly that:

    OLDPWD=/opt/tiger/workspace     <- the shell started here (only `cd` sets OLDPWD)
    PWD=/opt/tiger/rh2/rh2/init     <- something cd'd afterwards
    

    If the relay had fallen back to a default cwd, the shell would never have been in /opt/tiger/workspace at all and OLDPWD would not hold it. Relatedly, node-pty fails the spawn outright when the requested cwd does not exist — it does not silently inherit the parent process's directory — so "fell back to the container's CMD dir" is not a mechanism either.

    Evidence

    Verified on clean main, three live topologies:

    Topology Result
    Headed paired desktop server + paired desktop client folder PTY lands on the host folderPath; a file created from that shell appears in folderPath; git-worktree and local-only 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 the kernel's /proc/<pid>/cwd both == the folder path

    Then, adding one /etc/profile.d/99-cd.sh to the container reproduces your signature byte-for-byte — PWD=<other>, OLDPWD=<workspace>, ORCA_WORKSPACE_ROOT=<workspace> — with no Orca change. The decisive control: the same profile cd moves a plain repoId::/path git worktree identically. So the behaviour is not specific to folder:<uuid> workspaces, which is the load-bearing claim in the report.

    Why the proposed fix is not being made

    Falling back to ORCA_WORKSPACE_ROOT would not change your outcome — the cwd is already correct at spawn, and the cd happens afterwards inside the shell. It would also have the relay adopt an unvalidated client-supplied path for requests that named no working directory, with no legitimate caller (every Orca client version sends an explicit cwd).

    What to check on your box

    Look for a cd in the remote host's login startup files, in this order: /etc/profile, /etc/profile.d/*.sh, ~/.bash_profile / ~/.profile (or ~/.zprofile for zsh). In a container image whose default CMD runs from /opt/tiger/rh2/rh2/init, a profile entry pinning that directory is the likely culprit. Quick confirmation from an Orca terminal in that workspace:

    echo "$OLDPWD"                              # should be your workspace path
    bash -lc 'pwd'                              # reproduces the jump outside Orca
    bash --noprofile --norc -c 'pwd'            # should stay put
    grep -rn '^[[:space:]]*cd ' /etc/profile /etc/profile.d/ ~/.bash_profile ~/.profile 2>/dev/null
    

    One caveat worth naming: if the agent was resumed from AI Vault rather than launched fresh, Orca does prepend cd <the session's recorded cwd> && to the resume command by design, so a session previously run in /opt/tiger/rh2/rh2/init would land there again. That is intended resume behaviour, not the reported parsing bug — but it is a second explanation consistent with your dump, and the ticket data cannot distinguish the two. If you were resuming, that is the one to check first.

    Regression coverage for all of the above is in #15385 (test-only, no behaviour change). Happy to reopen with a fresh dump if bash --noprofile --norc -c 'pwd' also lands outside your workspace — that would point somewhere new.

  4. Jinwoo-H commented on Aug 19, 2026

    @Jinwoo-H
    Contributor

    Correction to my previous comment — where to look depends on your shell

    A follow-up review caught that I overstated one thing above. I said the relay "spawns POSIX login shells". That is true for zsh and other POSIX shells, but bash is normally launched with --rcfile, not -l (src/relay/pty-shell-launch.ts).

    The conclusion is unchanged, because Orca's bash wrapper reproduces the login chain by hand — it explicitly sources /etc/profile, then the first of ~/.bash_profile / ~/.bash_login / ~/.profile (src/relay/pty-shell-overlay-wrappers.ts:63-70). So on every POSIX branch, your host's login startup files still run after the PTY has been placed in the workspace, and a cd in any of them still wins.

    The practical difference is the file list, so here it is precisely:

    • bash (wrapped): /etc/profile, /etc/profile.d/*.sh, then whichever of ~/.bash_profile, ~/.bash_login, ~/.profile exists first. Note ~/.bashrc is not sourced directly by the wrapper — only if one of the above sources it.
    • zsh (-l): /etc/zshenv, ~/.zshenv, /etc/zprofile, ~/.zprofile, then the rc/login files.
    grep -rn '^[[:space:]]*cd ' /etc/profile /etc/profile.d/ ~/.bash_profile ~/.bash_login ~/.profile ~/.zprofile ~/.bashrc 2>/dev/null
    

    Two smaller corrections for the record: the "no client sends a cwd-less spawn" line was too absolute — cwd is optional on the wire, and one local-only caller can omit it; it just never reaches the relay. And the nonexistent-cwd behaviour I cited was measured on macOS; it holds for node-pty's shared POSIX implementation, but Windows uses a different spawn path I did not test.

    None of this changes the verdict, and the falsifier still stands: if bash --noprofile --norc -c 'pwd' also lands outside your workspace, reopen and I'll dig further.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingos:macosIssues affecting macOS

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions