## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Remote environments realize the workspace at a provider-owned path.
> - Run startup probes Git and network context before it starts the
agent.
> - The probe used the controller path inside the remote environment.
> - A missing directory stopped the run before any provider work began.
> - This pull request uses the remote execution target's working
directory.
## Linked Issues or Issue Description
Refs #13094, which introduced this probe. Related: #8997 and #10419
address other workspace-directory handoffs; this patch fixes the newer
Git-context probe.
**What happened?**
Remote runs failed with `setup_failed: Could not read execution-target
Git context`, including tasks that did not use Git. The provider shell
could not enter the controller's workspace directory.
**Expected behavior**
Startup must inspect Git and network context in the realized remote
workspace.
**Steps to reproduce**
1. Select a remote sandbox whose workspace is
`/home/daytona/paperclip-workspace`.
2. Start a task whose controller workspace is under
`/paperclip/instances/default/workspaces/`.
3. The startup probe exits when the controller directory does not exist
in the sandbox.
**Paperclip version or commit**
Reproduced on `622376e99` and in the regression test before this patch.
**Deployment mode**
Docker controller with a remote Daytona sandbox. The same helper also
serves SSH targets.
## What Changed
- Use `remote.remoteCwd` for the remote Git-context probe.
- Cover a missing controller directory in both credential modes.
- Verify that SSH reads Git metadata from the remote workspace even when
the caller directory exists.
## Verification
- Before the fix, both new missing-directory tests failed with the
reported error.
- The launcher environment suite passes: 18 tests.
- The adapter-utils suite passes: 1,085 passed, 11 skipped.
- Adapter-utils typecheck passes.
- A disposable sandbox with the affected deployment's image reproduced
the old `cd` failure and passed with the corrected helper. The sandbox
was deleted afterward.
- Full repository typecheck and build pass locally. All CI gates pass at
`61b522c`: regular test shards, serialized server suites, browser
shards, Runner verification, build, policy, and security checks.
- The first CI Build attempt hit a Runner suspension-acknowledgment
timeout outside the changed code. The affected 13-case recovery group
passes locally with its Rust fixtures built, and the unchanged CI job
passed on its single retry.
- The full serial local test run was stopped in favor of the complete CI
matrix; it is not claimed as a local pass.
## Risks
The probe now uses the provider-resolved target directory for sandbox
and SSH execution. Local execution keeps its existing directory. There
are no schema or API changes. Existing local credential and Git metadata
tests pass.
## Model Used
OpenAI GPT-6 in Codex, with tool-assisted code analysis, implementation,
and live and automated testing. The exact model identifier and
context-window size are not exposed by this session.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip runs agents for people with different GitHub accounts.
> - Managed operations must use the intended person's eligible
connection.
> - A failed duplicate connection must not hide a healthy grant for the
same account.
> - Legacy hosts also need their existing Git configuration when managed
access is not configured.
> - Runner networking and local Git operations must not depend on GitHub
broker availability.
> - This pull request separates those policies and improves failure
diagnostics.
## Linked Issues or Issue Description
**What happened?** New runs always cleared host Git credentials and
installed managed launchers. Network permission depended on GitHub
environment variables. A launcher failure could stop even local `git
status`. A newer unhealthy duplicate could take precedence over a
healthy connection, and generic health errors were shown as reconnect
requirements.
**Expected behavior:** Use a healthy eligible managed connection for the
intended account. Preserve host authentication only for unconfigured
standard-trust local or SSH execution. Permit local Git during broker
failures and keep network permission independent of GitHub credentials.
**Steps to reproduce:** Configure healthy and unhealthy grants for one
GitHub account, dispatch an agent, and execute Git commands. Separately
run an unconfigured legacy host with existing GitHub CLI authentication.
Stop the broker and run local `git status`.
**Paperclip version or commit:** Master at 668110469. **Deployment
mode:** Self-hosted. **Installation method:** Git checkout. **Agent
adapters involved:** Native Codex runner and shared adapter execution
setup. **Database mode:** Existing instance database; no migration.
**Access context:** Responsible person's managed grant, or explicitly
unconfigured legacy host. **Node.js version:** 26.4.0 locally.
**Operating system:** macOS development and Linux execution hosts.
**Relevant logs or output:** Previously `GitHub credential context
unavailable` hid configuration, transport, and capability errors. New
diagnostics identify these categories without credential values.
**Additional context:** Refs #13005 and #13022. Dependency provisioning
is addressed separately in #13093.
## What Changed
- Prefer healthy eligible grants and retry credential acquisition once
for the same principal and account before starting an operation.
- Preserve host Git configuration only when managed access is
unconfigured on a standard-trust local or SSH target.
- Project authentication mode and validated Git metadata into native
runner boundaries; refresh resumed provider settings when modes change.
- Enable network access through an explicit standard-trust controller
decision, independently of GitHub. Omitted or restricted decisions stay
disabled; replace warm providers when that decision changes.
- Run local Git with cleared credentials when the managed broker fails,
with specific redacted diagnostics.
- Retry access-refresh conflicts once without treating concurrency as
expired authorization.
- Show retry instead of reconnect for transient GitHub health failures.
Add optional authorization and run-diagnostic fields without a database
migration.
## Verification
- All latest-head CI gates are green, including typecheck, general and
serialized suites, browser tests, canary, native runner verification,
and build. Greptile is 5/5 with no remaining findings; the security scan
passed.
- Full recursive typecheck and build passed. UI token gates passed.
- Full general server run: 7,110 passed, one transient socket hangup;
that file passed on retry. All remaining workspace groups passed,
including 5,552 UI and 478 CLI tests. The complete serialized rerun
passed all 144 suites / 2,179 tests after the initial isolated timeout
passed on retry.
- 195 final launcher and native session tests passed, including
host/managed transitions, local/remote warm network-policy changes,
broker rotation, and attempts to override validated controller
filesystem roots.
- GitHub gateway fallback, duplicate connection selection, refresh
conflicts, per-user reauthorization, and native transport/security
suites passed.
- Additional live native fixtures passed SSH public-key authentication
and a Git credential helper in fresh and resumed host-mode sessions. An
unwritable managed configuration directory preserved local Git (exit 0)
while GitHub CLI failed with `configuration_directory_unavailable` (exit
4). The temporary SSH listener and keys were removed.
- Applicable Rust suites passed except two timing failures under load;
each failed case passed in isolation. The final environment contract
test passed.
- Linux native runner acceptance passed in both managed and legacy host
modes: DNS, HTTPS, npm package download, fresh-worktree Git status,
authenticated GitHub user lookup, repository read, and a new run
continuing the same provider conversation. Managed broker outage
preserved local Git and rejected authenticated access without host
fallback.
- Matching Linux server/runner artifacts and the separate provisioning
repair are deployed to the development instance. A fresh UI-dispatched
task and a new run after a server restart both passed all six shell
checks through the live controller and credential broker. Both runs
selected the expected healthy connection/grant and retained the same
provider conversation. Neither connection was repaired or reconnected.
The sandbox roots are assigned from the validated execution-target probe
**after** ordinary bindings are merged. Regression coverage supplies
forged roots and verifies they cannot override the controller paths.
Networking is enabled only for an explicit
`PAPERCLIP_RUNNER_NETWORK_ACCESS=enabled` controller decision; omitted
values remain disabled.
## Risks
Unconfigured standard-trust local and SSH runs regain access to host Git
authentication resources. Managed, sandbox, plugin, and low-trust runs
do not gain this fallback. Revoked managed access never falls back to
another account. Deploy server and runner artifacts together;
already-started operations retain their captured identity. An
unauthenticated command can still fail when it requires GitHub access.
## Model Used
OpenAI GPT-6 through Codex, with code editing, shell execution, tests,
and browser inspection. The exact model variant and context-window size
are not exposed in this session.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip lets people manage AI agents and their work.
> - Remote agents need both their installed tools and managed GitHub
credentials.
> - The GitHub launcher replaces a missing remote PATH with a small
system path.
> - Legacy images install agent CLIs outside that path, so those agents
cannot start.
> - This pull request preserves the remote toolchain and puts managed
GitHub commands first.
> - Command checks now use the same environment as execution.
## Linked Issues or Issue Description
Refs #13005. Related: #10239 fixes a separate Cursor environment path
issue.
Searched open issues and PRs for sandbox PATH and GitHub launcher
changes. No duplicate of this launcher fix was found.
**What happened?**
A remote Claude or Codex run passes command discovery, then fails with
`command not found` and exit code 127. Managed GitHub launchers use only
their own directory and `/usr/local/bin:/usr/bin:/bin`. This drops NVM
and other toolchain directories from the sandbox path.
**Expected behavior**
Agent CLIs remain available on legacy and current sandbox images.
Managed `git` and `gh` still resolve first and use the responsible
person's credentials.
**Steps to reproduce**
1. Use a sandbox whose agent CLI is installed in an NVM or other
non-system bin directory.
2. Start an agent run with managed GitHub launchers and no explicit PATH
override.
3. Observe that command discovery succeeds but the agent command exits
with code 127.
**Paperclip version or commit**
Observed on `b97101893f0926f57ed0ce9ef1f8d3e4780c62c2`. The same
launcher behavior remains on the base commit `be6bb768b`.
**Deployment mode**
Hosted server with remote sandbox execution. The shared launcher also
supports SSH targets.
## What Changed
- Read the remote target's effective PATH when no remote override is
set. Do not copy an inherited controller PATH.
- Prepend the managed launcher directory and retain the combined path in
shell startup files.
- Stop startup if path discovery fails. Frame the response so login
banners cannot contaminate PATH.
- Pass the sanitized launch environment to sandbox command checks,
installation, and the second check.
- Add real shell tests for legacy and current CLI layouts, quoted paths,
managed GitHub command execution, explicit overrides, SSH, and failure
cases.
- Document the remote path contract.
## Verification
- Four focused adapter utility suites passed: 153 tests.
- The regression suite passed: 13 tests, including the Linux stdin
handling fix.
- `pnpm --filter @paperclipai/adapter-utils typecheck` passed.
- Full workspace `pnpm -r typecheck` and `pnpm build` passed.
- The regression suite fails on the unchanged base revision (12
failures, 1 pass) and passes with this change (13 passes). The baseline
ran in an isolated scratch copy.
- Full local test coverage was attempted using the official CI shards.
The run was stopped after macOS Postgres shared-memory exhaustion and
CLI timeouts under load. The affected server database suite passed in
isolation (31 tests), as did the five affected DB/CLI suites (89 tests).
- [Full Linux
CI](https://github.com/paperclipai/paperclip/actions/runs/34258333833)
passed on `4e1426f5b`: all general and serialized test shards, all
browser shards, typecheck and release registry checks, native runner
verification, application build, and release canary dry run.
- Greptile scored the latest commit 5/5 with no unresolved findings.
- Shell tests use isolated local fixtures and make no provider or model
requests. No live sandbox qualification is claimed.
## Risks
- Remote startup adds one bounded path query when no explicit override
exists. A failed query stops startup.
- Explicit remote path overrides still control which tools are
available. Invalid overrides now fail the command check earlier.
- Credential selection and GitHub broker policy are unchanged. Tests
verify managed wrappers stay first and can invoke underlying commands.
- No database migration or sandbox image replacement is required.
## Model Used
OpenAI GPT-6 through Codex, with reasoning, repository editing, and
terminal tools. The exact serving model ID and context-window size are
not exposed in this session.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Dotta