Skip to content

Windows: agent PTY child processes orphaned on terminal stop/close, blocking worktree removal (Failed to physically stop every PTY) #10004

Closed

Description

@Noobear

Summary

On Windows, removing a worktree that has (or recently had) a TUI agent running in a terminal fails with:

Error invoking remote method 'worktrees:remove': Error: Failed to physically stop every PTY for worktree: <repoId>::<path>

The failure happens from both the desktop UI (right‑click → delete) and the CLI (orca worktree rm --force), because both hit the same runtime precondition ("stop every PTY").

Root cause: when a terminal is stopped/closed, Orca kills the direct PTY child (the shell) but not the shell's descendants. The agent process and its children (node / claude / codex + their MCP‑server node processes) survive as orphans — their parent PID no longer exists — with their working directory still inside the worktree. On Windows there is no automatic process‑group cascade, so the subtree leaks and keeps the worktree "busy" forever.

There is also a secondary reporting bug: terminal stop returns {stopped: N} and terminal close returns ok, but the processes are still alive and terminal list still shows the terminals as connected: true.

Environment

  • OS: Windows 11 Pro (build 26200)
  • Orca daemon-host: 1.4.146 / 1.4.148 / 1.4.150 installed (multiple runtimes live at the time)
  • PTY layer: node-pty + OpenConsole.exe (ConPTY), spawned under …/Orca/daemon-host/<ver>/resources/node_modules/node-pty/…
  • Agents involved (both reproduce):
    • Claude Code — claude --dangerously-skip-permissions
    • OpenAI Codex TUI v0.145.0 — codex --dangerously-bypass-approvals-and-sandbox (YOLO). Process tree: node.exe → codex.exe → pwsh.exe + several node ./mcp/server.mjs children.

Reproduction

  1. In Orca on Windows, open a worktree and start a TUI agent in a terminal (Claude Code or Codex). The agent spawns a shell → node agent → child processes (incl. MCP servers).
  2. Try to remove the worktree — UI delete or orca worktree rm --worktree id:<…> --force --json.
  3. It fails: Failed to physically stop every PTY for worktree: <repoId>::<path>.
  4. Try to clear the PTYs first:
    • orca terminal stop --worktree id:<…> --json → returns { "stopped": 3 } (and { "stopped": 1 } for the other worktree).
    • orca terminal close --terminal <handle> --json → returns ok for every handle.
  5. Re-list: orca terminal list --json still shows those terminals with connected: true, writable: true.
  6. Re-run the removal → identical failure.

Evidence (observed this session)

  • After stop/close reported success, the shell processes (the direct PTY children) were gone, but the agent processes were not. Reading each process's PEB CurrentDirectory showed 6 live processes whose cwd was inside the two target worktrees:
    • catfish worktree: claude.exe ×3
    • request worktree: node.exe → codex.exe → pwsh.exe (+ MCP node children)
  • For every one of those processes, the parent PID no longer existed in the process table → confirmed orphaned/re‑parented, not still under a live shell.
  • Force‑killing exactly those subtrees at the OS level (taskkill /F /T /PID <pid>) and then re‑running orca worktree rm --force returned OK for both worktrees immediately. Branches were removed as part of the same operation.

Root cause analysis

Windows does not cascade a kill from parent to child. When Orca tears down a PTY by terminating only the shell process it directly spawned, any grandchildren (the node‑based agent and its own children, e.g. MCP servers) are left running and re‑parented. Their working directory keeps a handle on the worktree folder, so the runtime's "stop every PTY / free the worktree" step can never succeed, and worktree removal is permanently blocked until the user finds and kills the processes manually.

This is two defects:

  1. Primary — PTY teardown kills only the direct child, not the descendant tree, so agent subtrees leak on Windows.
  2. Secondary — terminal stop / terminal close report success while the processes are still alive and the terminal still lists as connected, hiding the leak from the user and from worktrees:remove.

Impact

  • On Windows, any worktree that ran a long‑lived TUI agent (very common with --dangerously-skip-permissions / YOLO agents) becomes undeletable via both UI and CLI.
  • The only recovery is manual OS‑level process hunting/killing, which is error‑prone (agent processes' command lines don't reveal which worktree they belong to; you have to read each process's cwd from its PEB to avoid killing the wrong agent / your own session).
  • Leaked processes and file handles accumulate over a session.

Suggested fix

  • Place each PTY's spawned process into a Windows Job Object created with JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE, so closing the job deterministically kills the entire subtree; or
  • On stop/close/remove, perform an explicit recursive tree‑kill of the shell PID (e.g. taskkill /F /T /PID <shellPid>, or walk the child snapshot) instead of terminating only the direct child.
  • Make terminal stop / terminal close verify actual process exit before returning success (and reflect it in terminal list connected).
  • As a defensive fallback in worktrees:remove, reap any remaining descendants by matching processes whose working directory is under the worktree path before declaring the PTY‑stop step failed.

Workaround (for other Windows users hitting this)

  1. Find the orphaned processes by their working directory (read each candidate process's PEB CurrentDirectory; command lines alone are not enough to tell worktrees apart).
  2. taskkill /F /T /PID <pid> each subtree rooted in the target worktree — carefully, so you don't kill an agent/session in another worktree.
  3. Re-run orca worktree rm --worktree id:<…> --force.

Activity

  1. Noobear commented on Jul 22, 2026

    @Noobear
    Author

    Reproduction log (captured on Windows 11, daemon-host 1.4.x)

    Two worktrees in repo orca-system (78e9c31d-…), each running TUI agents:
    catfish (3× Claude Code terminals) and request (1× Codex TUI terminal).

    1) Removal fails — worktrees:remove / orca worktree rm --force

    // orca worktree rm --worktree id:78e9c31d-…::…/workspaces/orca-system/catfish --force
    {
      "ok": false,
      "error": {
        "code": "runtime_error",
        "message": "Failed to physically stop every PTY for worktree: 78e9c31d-…::C:/Users/giloh/orca/workspaces/orca-system/catfish"
      }
    }
    // same for …/request

    2) Stopping/closing the terminals reports success…

    // orca terminal stop --worktree …/catfish   →  { "ok": true, "result": { "stopped": 3 } }
    // orca terminal stop --worktree …/request   →  { "ok": true, "result": { "stopped": 1 } }
    // orca terminal close --terminal <handle>    →  ok   (all 4 handles)

    3) …but the terminals are still alive afterward

    // orca terminal list  (after stop + close)
    {"handle":"term_44d91bab…","title":"✳ Claude Code","connected":true}
    {"handle":"term_1e7e8883…","title":"✳ Understand dangerously-skip-permissions flag","connected":true}
    {"handle":"term_1234a52a…","title":"✳ Implement dangerously-skip-permissions flag","connected":true}
    {"handle":"term_803d9c23…","title":"[ ! ] Action Required | request","connected":true}

    Re-running the removal → identical Failed to physically stop every PTY.

    4) The survivors are orphaned agent processes (parent already dead)

    Identified by reading each process's PEB CurrentDirectory (command lines alone don't
    reveal the worktree):

      PID  PPID  Name        CurrentDirectory
    23028 27692  claude.exe  C:\Users\giloh\orca\workspaces\orca-system\catfish\
     2204 20640  claude.exe  C:\Users\giloh\orca\workspaces\orca-system\catfish\
     2424 28996  claude.exe  C:\Users\giloh\orca\workspaces\orca-system\catfish\
    16608 28160  node.exe    C:\Users\giloh\orca\workspaces\orca-system\request\
    13420 16608  codex.exe   C:\Users\giloh\orca\workspaces\orca-system\request\
    28136 13420  pwsh.exe    C:\Users\giloh\orca\workspaces\orca-system\request\
    

    Walking each ancestry chain, the parent PIDs (27692, 20640, 28996, 28160) no longer
    exist
    — i.e. Orca killed the shells (the direct PTY children) but their agent
    descendants were re-parented and left running, still holding the worktree cwd.

    Process tree at time of failure (reconstructed from the PIDs / cwd / parent data above)

    graph TD
      classDef dead fill:#3a1d1d,stroke:#b44,stroke-dasharray:5 4,color:#e8b4b4;
      classDef live fill:#16261b,stroke:#4c9a5e,color:#cdeacd;
    
      S1["✕ shell 27692<br/>(terminated by Orca)"]:::dead
      S2["✕ shell 20640<br/>(terminated by Orca)"]:::dead
      S3["✕ shell 28996<br/>(terminated by Orca)"]:::dead
      S4["✕ shell 28160<br/>(terminated by Orca)"]:::dead
    
      S1 -. orphaned .-> C1["claude.exe 23028"]:::live
      S2 -. orphaned .-> C2["claude.exe 2204"]:::live
      S3 -. orphaned .-> C3["claude.exe 2424"]:::live
      S4 -. orphaned .-> N1["node.exe 16608"]:::live
    
      N1 --> CX["codex.exe 13420"]:::live
      CX --> PW["pwsh.exe 28136"]:::live
      CX --> MCP["node ./mcp/server.mjs ×8<br/>(23376, 11616, 16620, 27292,<br/>27504, 20492, 29412, 5404)"]:::live
    
      subgraph CAT["catfish worktree — cwd handle held"]
        C1
        C2
        C3
      end
      subgraph REQ["request worktree — cwd handle held"]
        N1
        CX
        PW
        MCP
      end
    
    Loading

    5) Manual OS-level tree-kill unblocks removal

    taskkill /F /T /PID 23028   → SUCCESS
    taskkill /F /T /PID 2204    → SUCCESS
    taskkill /F /T /PID 2424    → SUCCESS
    taskkill /F /T /PID 16608   → SUCCESS (also terminated 13420, 28136 and 8 MCP node children)
    
    // orca worktree rm --force  (retried after the kills)
    // catfish → { "ok": true }
    // request → { "ok": true }

    Both worktrees removed, branches gone, orca worktree list clean.

    (The Mermaid diagram above renders the process tree at the time of failure, reconstructed
    from the captured PID / PEB-cwd / parent-PID data.)

  2. innocarpe commented on Jul 23, 2026

    @innocarpe
    Contributor

    I'd like to take this.

    Plan: On Windows, agent PTY teardown currently degrades to shell-only kill because captureDescendantSnapshot returns null on win32 (POSIX ps path). That leaves agent descendants (claude/codex + MCP nodes) holding the worktree cwd after the shell is gone — matching this report and the e2e note that descendant tree-kill is POSIX-only.

    I'll add a Windows tree kill (taskkill /T /F on the PTY root, same pattern used elsewhere in Orca) into the agent descendant-sweep / local PTY agent shutdown paths so worktree removal can physically clear the tree, plus unit coverage. PR shortly.

  3. added a commit that references this issue on Jul 23, 2026
    27da71e
  4. added a commit that references this issue on Jul 24, 2026
    dc18ba9
  5. added 2 commits that reference this issue on Oct 15, 2026
    f4977c0
    e33670d
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions