Repository navigation
fix(cli,relay): stop reading an unsignalable pid as a dead one (+ unverifiable-collapse sweep result) - #20098
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
Included review availability: Your plan provides up to 10 included reviews per hour; 1 remains after this review. 📝 WalkthroughWalkthroughThe change updates PID liveness checks in CLI status and PTY revival. Priority: ⬇️ Low Merge Risk: ⚪ Minimal · up to The change preserves inaccessible live processes and removes only confirmed-absent ones, with focused coverage for both outcomes. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
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. Comment |
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
- CLI
statuspid fallback —isProcessRunningnow returns(error as NodeJS.ErrnoException)?.code !== 'ESRCH', so a pid that only refuses the probe (EPERM, exists under another uid) reportsrunning: true/state: 'starting'rather thanstale_bootstrap. Reporting-level only: consumers key offruntime.reachable, which staysfalseon both branches. - Relay
pty.revivegate — the hand-rolledprocess.kill(pid, 0)try/catch is replaced with the already-imported sharedisProcessAlive, reusing the ESRCH-only rule; the malformed-pid skip (!Number.isInteger(entry.pid) || entry.pid <= 0) is preserved. - Tests — two CLI cases (EPERM → alive, ESRCH → stale) and one relay case (EPERM pane survives, ESRCH pane drops), each verified to fail under the specific regression it claims to pin.
Both points you flagged for review are sound as-is:
- Relay guard minimality — keeping
!Number.isInteger(entry.pid) || entry.pid <= 0(skip) rather than widening to the!managed.pty.pid ||convention is correct. The two conventions guard opposite directions:reapPtyProvenExited(pty-handler.ts:2464) is destructive, so a missing pid must default to "alive" to avoid retiring something on no evidence;revivere-spawns a shell, so a serialized entry with no usable pid is untrusted client state and skipping it avoids an orphan/duplicate. Both fail safe in their own direction. - Cloud-session
unreadable → reconnect-requiredfold — leaving it out of scope is right; it's toast-level and gates no destructive action.
DeepSeek Pro (free via Pullfrog for OSS) | 𝕏
`orca status` falls back to a `kill(pid, 0)` probe when `status.get` cannot be reached, and a bare catch read every refusal as absence. EPERM means the pid exists under another uid -- an Orca reached via ORCA_USER_DATA_PATH, or one started with sudo -- so a live app was reported `running: false`, `pid: null`, `runtime.state: stale_bootstrap`, `graph.state: not_running`. Only ESRCH proves the pid is gone, which is the rule every other liveness probe in the repo already applies (`isProcessAlive` in relay/pty-shell-utils.ts, pack-refs-lock-ownership.ts, runtime-metadata-ownership-watch.ts, and agent-session-process-identity-probe.ts). See docs/reference/ssh-execution-boundary.md.
…robe `revive` gated each serialized pane on a hand-rolled `process.kill(pid, 0)` in a bare try/catch, so any refusal retired the pane. EPERM means the process exists under another uid; only ESRCH is evidence of absence. The file already imports `isProcessAlive`, whose ESRCH-only contract `reapPtyProvenExited` documents 450 lines earlier -- this call site just did not use it. Reuse it rather than keeping a second implementation of the same concept. Malformed pids still skip, as before. See docs/reference/ssh-execution-boundary.md.
9596160 to
c67a747
Compare
main tightened typescript/consistent-type-assertions to assertionStyle: never, which the rebase brings onto these added lines. The CLI probe narrows instead of casting; the relay test keeps the file's serialize idiom behind a SAFETY-annotated suppression.
…erifiable-collapse sweep result) (stablyai#20098) * fix(cli): stop reporting an unsignalable Orca pid as a stale bootstrap `orca status` falls back to a `kill(pid, 0)` probe when `status.get` cannot be reached, and a bare catch read every refusal as absence. EPERM means the pid exists under another uid -- an Orca reached via ORCA_USER_DATA_PATH, or one started with sudo -- so a live app was reported `running: false`, `pid: null`, `runtime.state: stale_bootstrap`, `graph.state: not_running`. Only ESRCH proves the pid is gone, which is the rule every other liveness probe in the repo already applies (`isProcessAlive` in relay/pty-shell-utils.ts, pack-refs-lock-ownership.ts, runtime-metadata-ownership-watch.ts, and agent-session-process-identity-probe.ts). See docs/reference/ssh-execution-boundary.md. * fix(relay): keep a revived pane whose pid only refuses the liveness probe `revive` gated each serialized pane on a hand-rolled `process.kill(pid, 0)` in a bare try/catch, so any refusal retired the pane. EPERM means the process exists under another uid; only ESRCH is evidence of absence. The file already imports `isProcessAlive`, whose ESRCH-only contract `reapPtyProvenExited` documents 450 lines earlier -- this call site just did not use it. Reuse it rather than keeping a second implementation of the same concept. Malformed pids still skip, as before. See docs/reference/ssh-execution-boundary.md. * fix(lint): clear the casting gate on the pid-probe changes main tightened typescript/consistent-type-assertions to assertionStyle: never, which the rebase brings onto these added lines. The CLI probe narrows instead of casting; the relay test keeps the file's serialize idiom behind a SAFETY-annotated suppression.
…22341) * fix(cli): report a denied runtime connection instead of a dead Orca Inside Codex's macOS Seatbelt sandbox, connect() on the runtime socket fails with EPERM. The CLI dropped the errno and reported "Could not connect ... Restart Orca", appended "Orca is not running. Run 'orca open' first.", and `orca status` answered ok:true with `starting` (its pid probe also gets EPERM). An agent following that advice restarts a healthy app, which cannot help. EPERM/EACCES on the metadata read or the socket/pipe connect now fails with a CLI-local `runtime_access_denied` error: ok:false, non-zero exit, operation/systemCode/processState:"unverifiable"/retryable:false and nextSteps that say to re-run with escalated permissions and not restart. CODEX_SANDBOX only picks the wording. `orca open` stops before launching. The status pid probe is unchanged: a refused or missing socket proves the caller reached the endpoint, so a later EPERM probe is another uid and keeps #20098's `starting`. Missing, refused, stale-pid and timeout paths are unchanged. Adapted from the diagnosis and tests in #20487 (and #19605, #13583). Co-authored-by: lifeodyssey <zhenjiazhou0127@outlook.com> * docs(skills): tell agents runtime_access_denied means escalate, not restart The shared CLI-resolution block told every bundled skill to run `orca open` when a command says Orca is not running. Add the counterpart for the new access-denied code so sandboxed agents re-run with escalated permissions instead of launching or restarting Orca. Regenerated stubs and manifest. * refactor(cli): classify only a denied runtime connect, with a leaner error A denied metadata read was never observed under a sandbox, and it turned an unreadable user-data path (the Linux launch contract's root-owned HOME) into runtime_access_denied instead of "Orca is not running". Keep metadata reads as on main and classify only the socket/pipe connect. One helper now maps a socket errno to the error or null; the error data keeps only systemCode and nextSteps. Tests drop cases already pinned by status.test.ts. * fix(cli): give not-running advice when a denied socket belongs to a dead Orca A crashed Orca leaves its metadata and socket file behind, and a sandbox denies the connect with EPERM before the CLI can see ECONNREFUSED. The sandbox still reports ESRCH for a gone pid, so a denied connect now probes the metadata pid and falls through to the ordinary unavailable path when the pid is proven gone. isProcessRunning moves to its own module so transport and status share it. * refactor(cli): inline the runtime_access_denied code like other CLI error codes --------- Co-authored-by: lifeodyssey <zhenjiazhou0127@outlook.com>

ELI5
Asking "is this process still alive?" can get three answers: yes, no, and I'm not allowed to ask. Two places in the codebase filed the third answer under "no" and acted on it. This fixes both.
More importantly: this PR is the write-up of a sweep for that whole defect class, and the sweep came back mostly clean. That negative result is the main deliverable.
The sweep result (read this first)
I swept for the class behind PRs #20085 / #20095 / #20096: a value meaning "we could not determine this" being read as "this is gone / dead / absent." Those PRs fixed eleven sites of one narrow version (
entry.statusnulled on a non-verified probe). The open question was how much bigger the class is.Answer: not much. Across seven search dimensions, almost everything I checked was already hardened — frequently with the rule stated verbatim in a comment next to the code. The eleven earlier sites were a cluster in one subsystem, not a systemic failure. Nobody could say that before; now it's on the record so the next person doesn't redo it.
Dimensions searched
rg "\.catch\(\(\) => "acrosssrc/rg -U "catch[^\n]*\{\n\s*return (false|null|\[\])"oversrc/,src/cli,mobile/srcwithTimeout/withTimeoutResult/Promise.racecall site enumerated with its fallback argument!== 'running'|'live'|'connected'|'ready'|'present'|'found'|'verified'|'own';Promise<boolean | null>;| 'unknown'type decls?? false/?? []/?? nullfiltered against kill/remove/delete/purge/prune/reap/retire/evictprocess.kill(pid, 0)liveness probessrc/,mobile/,scripts/read with surrounding contextrm,killpg,branch -d/-D, socket unlink, unsubscribeExplicitly ruled out
Each of these reads like the defect and is not:
worktree-removal-safety.ts/worktree-orphan-gitdir-proof.ts— everycatchreturnsfalse(refuse to delete)..catch(() => null)on the stat failsisDirectoryStatand refuses.isMissingPathErrorrequires ENOENT/ENOTDIR; EACCES refuses.branchHasNoUnmergedChangesOnAnyTargetreturnsfalseon every probe failure, and an emptytargetRefspreserves rather than force-deletes.blockers: ['git-status-error']withclean: null; a null unpushed count becomes'unknown-base'. Aterminal-liveness-unknownblocker and anunverified-removal-consentsuite already exist.registered-worktree-roots-cache.ts—isRootGoneFromDisktimes out tofalse("not gone"), and the prune's own doc comment reads "Nothing is retired for want of evidence."daemon-endpoint-probe.ts— four states, withendpointIsProvenDeadas the only licence to replace an endpoint.classifyWindowsTreeKillTarget—own/absent/foreign/unknown, and the caller does.catch(() => 'unknown').OrcaCloudSessionReadResultcarries a distinctunreadablealongsidedecrypt-failedprecisely so a locked file cannot license a replace.readFreshOrcaCloudSessiondoes foldunreadableintoreconnect-requiredfor the toast, but does not callclearCloudSessionIfUnchangedon that path — cosmetic, not destructive, left alone.withTimeoutcall sites — every fallback points the conservative way (ssh-connection.ts:1346falls back totrue= "may restrict";orca-runtime-terminal-create-deduplication.ts:75throwsruntime_unavailablerather than risk a duplicate shell).kill(pid, 0)probe —pty-shell-utils,pack-refs-lock-ownership,codex-app-server-process-teardown,codex-app-server-posix-supervisor,process-tree-termination,runtime-metadata-ownership-watch,runtime-rpc-socket-metadata,agent-session-process-identity-probe,worktree-create-preparation-stale-cleanup,orcad-instance-lock,ensure-virtual-display,grok-hook-owners,configure-process— all already ESRCH-only. After this PR that dimension is exhaustively clean.What Changed
Two commits, both one-liners in the guard plus tests.
1.
orca statuscalls a live Orca dead — reachable, reporting-level, not destructivesrc/cli/runtime/status.ts— whenstatus.getis unreachable, the fallback pid probe used a barecatch { return false }.kill(pid, 0)refusing with EPERM means the pid belongs to another uid. That is not evidence the process is gone; it is "I'm not allowed to ask." The bare catch converted that into "it's dead", so a live app was reported:stale_bootstrapis not a loose synonym here —single-instance-lock.ts:29andruntime-metadata-ownership-watch.ts:8both define it as "metadata points at a dead pid." This publishedunverifiableasexited.Reachable: point the CLI at an Orca running under another account (
ORCA_USER_DATA_PATH, or one started withsudo) during a slowstatus.get.orca statusreports that Orca died. An agent reading that reasonably concludes the runtime is gone.Severity — stated plainly so a reviewer doesn't assume worse: this is reporting-level, not destructive.
runtime.reachableis alreadyfalseon both branches, and every downstream consumer keys offreachable, notapp.running—handlers/core.ts:124,agent-hooks.ts:149,terminal-send.ts:33. Nothing is torn down. It under-reports; it does not kill anything.2.
pty.reviveretires a pane on an unresolvable refusal — latentsrc/relay/pty-handler.tsgated each serialized pane on a hand-rolledprocess.kill(entry.pid, 0)in a bare try/catch, so any refusalcontinued and retired the pane.This is the same shape the three previous PRs fixed, and it's the argument for the shared helper they introduced: the file already imports
isProcessAlive(line 14) and already calls it correctly at lines 1790 and 2464 — wherereapPtyProvenExitedspends nine lines documenting the ESRCH-only rule and citesdocs/reference/ssh-execution-boundary.md. The right answer was nine lines away, with the rule written down, and this one path didn't call it. That is precisely the cost of one concept having more than one implementation.The fix reuses the existing helper. No new predicate.
Latent — I could not construct a caller and am not claiming one.
provider.revive(...)has no caller in shipped code:ssh-pty-provider.ts:70anddaemon-pty-router.ts:200only forward it, and nothing invokes either. It is contract surface exercised by tests. Justified on reuse grounds, not on impact.Why
docs/reference/ssh-execution-boundary.mdfixes the vocabulary atlive/unverifiable/exited, with no synonyms, and states that loss of contact is never evidence of process death.exitedrequires positive evidence of absence from the host that owns the process. Only ESRCH carries that; EPERM carries the opposite — the process exists.Linked Issue
N/A — swept as a defect class following #20085 / #20095 / #20096 rather than from a filed issue. No issue was opened for this.
Visual Proof
N/A— no UI surface. The CLI change alters two fields oforca statusJSON under a fault condition; the relay change alters an RPC guard. Both are covered by assertions below.Testing
macOS. Cross-platform reasoning: the ESRCH/EPERM distinction is POSIX; on Windows libuv maps an
OpenProcessrefusal toUV_EPERM, so the fix is correct there too and strictly widens what counts as alive. The CLI suite's Unix-socket fixture is alreadydescribe.skipIf(win32), and my new block follows it.Mutation table — each assertion was verified to fail when, and only when, the specific regression it claims to catch is reintroduced:
catch { return false }{running: false, pid: null}, expected{running: true, pid: 424242}catch { return true }catch { continue }if (false) { continue }Gates, each proven capable of failing before being believed:
vitest run --config config/vitest.config.ts— 11/11src/cli/runtime/status.test.ts, 20/20src/relay/pty-handler-revive.test.ts, and 172 files / 1695 tests across all ofsrc/relay/.oxlint— exit 0 (it prints nothing on success, so the exit code is the only signal).tsc -p config/tsconfig.tc.cli.jsonandtsc -p config/tsconfig.node.json— empty output. Confirmed live by injecting a type error intostatus.ts(7 errors, exit 1).Note for anyone following:
config/tsconfig.tc.node.jsondoes not exist — that path yieldsTS5058, which reads like "1 error". The real node target isconfig/tsconfig.node.json.I manually tested these changes locally
Automated tests added/updated, or explained why not below
AI Disclosure
Internal contributor.
Review
Two things worth a reviewer's attention:
!Number.isInteger(entry.pid) || entry.pid <= 0). I deliberately did not widen it to the!managed.pty.pid ||convention used at lines 1790/2464, which treats a missing pid as alive. Consistency would argue for widening; minimality argues against changing behaviour on untrusted client state in a fix aimed at one thing. Happy to go either way.unreadable→reconnect-requiredfold described under "ruled out" is a real but cosmetic instance of this class. I left it. Say the word if it should be in scope.Agent skill upstream boundary
Notes
ssh-execution-boundary.md.mobile/srcwas swept (no findings) and is unmodified.pty.revive's request and response are unchanged; only the host-local decision inside it changed.Number.isIntegerper serialized entry on a path that already made a syscall.Checklist
N/Awith reasonRebased onto
main@231e805b1e1e49c765e96b9409f88e09d117346a(2026-09-15).959616039443e160d389887231dc9fab0ea26ec4d6ddf2065c05c54132c5dc11f20b0bf36ea190f7Content unchanged apart from one added commit,
fix(lint): clear the casting gate on the pid-probe changes, whichmain's newly tightenedtypescript/consistent-type-assertionsrequires. Verified withgit range-diff; prior CI results predate this rebase.