App-server: GET /v1/jobs for GPUI long-running job inspect and stop

[Hmbown]

GPUI Hmbown/codewhale-apps#615 needs Codewhale-owned long-running job inspect/control. Apps probed and named:

• GET /v1/jobs — 404 (or not served for GPUI)

GPUI must fail closed and must not invent a second job registry in the desktop. Reconcile crates/tui/src/runtime_api.rs and TUI /jobs against today's tip before adding routes. If jobs already exist under another path (task/process control plane), name it. Otherwise serve list + bounded output cursor + scoped stop with ownership checks (PID reuse and foreign-session IDs rejected).

Related: Hmbown/codewhale-apps#615, #6160 (terminal bytes — separate from jobs).

[Hmbown]

Doing the reconciliation this issue asks for first, because it changes what the route should be.

Jobs already exist, twice, and neither is /v1/tasks

/v1/tasks, /v1/tasks/{id}, /v1/tasks/{id}/cancel are already served — but they are the runtime task plane, not background processes. They are not what GPUI is asking for.

The thing GPUI wants is the shell job center, reached today only through the TUI /jobs command (commands/groups/utility/jobs.rs, list|show|poll|wait|stdin|cancel, dispatching AppAction::ShellJob). It is backed by ShellManager in tools/shell.rs, and it already has almost everything this issue asks for:

• list_jobs() (shell.rs:3090) and list_jobs_for_session(active_session_id) (:3111) — session scoping exists
• require_session_owner(task_id, active_session_id) — the foreign-session rejection exists
• ShellJobSnapshot (:203) is already Serialize, and carries id, command, cwd, status, exit_code, elapsed_ms, stdout/stderr tails and total lengths (so a bounded cursor has its offsets), linked_task_id, owner_agent_id, and owner_session_id
• ShellJobDetail (:361) is the full-output view /jobs show already uses

So the serving layer really is thin. The blocker is upstream of it.

The blocker: there is no single authoritative registry to serve

SharedShellManager is Arc<Mutex<ShellManager>>, and it is constructed in six places:

Site	What it does
tui/app/init.rs:602	creates the TUI's manager
tui/ui/apply.rs:2742	replaces app.runtime_services.shell_manager with a brand-new one on workspace change
core/engine.rs:1625	takes runtime_services.shell_manager, else creates a fresh one
tui/ui/event_loop.rs:974	same unwrap_or_else fallback
exec_agent.rs:473	headless exec builds its own
runtime_threads.rs:10185	passes None

runtime_api.rs holds no reference to any of them — it reaches nothing shell-related today.

So "serve /v1/jobs" cannot be answered without first answering which manager is the authority. Picking wrong gives GPUI a truthful-looking view of a registry that is not the one running the user's jobs — which is the second job registry this issue is trying to prevent, arriving by a different door.

Worth noting on its own: apply.rs:2742 swapping the manager on workspace change means jobs started before the switch are no longer reachable through the app's handle. That is a code-shape reading, not a reproduced bug — I have not driven a workspace switch with a live background job to confirm what the user sees — but it should be settled before a client surface depends on the handle.

What I would do

1. Decide the authority: hoist one SharedShellManager for the process and make runtime_services.shell_manager non-optional, deleting the unwrap_or_else fallbacks so a missing manager is a construction error rather than a silent second registry.
2. Give RuntimeApiState that handle.
3. Then GET /v1/jobs (session-scoped via list_jobs_for_session), GET /v1/jobs/{id} with ?stdout_from=&stderr_from= cursors off the existing stdout_len/stderr_len, and POST /v1/jobs/{id}/cancel gated on require_session_owner.

Step 1 is the real work and it is a decision, not a patch. Steps 2-3 are small once it is made. Not started tonight rather than guessing at the authority — and tui/ui/event_loop.rs and tui/ui/apply.rs both have another agent's uncommitted changes in this workspace right now, so the hoist would collide.

Related: this overlaps #6142 (two MCP client stacks) and #6143 (config authority) as the same species of defect — one concept, several owners.

[Hmbown]

Correcting my comment above: this is already implemented, and the blocker I described has a better answer than the one I proposed.

060711b2f1 on feat/app-server-routes-0914 serves GET /v1/jobs plus /v1/threads/{id}/jobs, /v1/threads/{id}/jobs/{job_id}, .../output, .../stdin and .../kill. It was sitting unpushed in a local worktree on no remote; it is now pushed and open as draft #6229.

I argued here that the jobs API could not be served because SharedShellManager is constructed in six places with two silent unwrap_or_else fallbacks, so there was no single authority to serve and building over one of the ambient copies would create the second registry this issue forbids.

That diagnosis was right about the problem and wrong about the conclusion. crates/tui/src/runtime_api/jobs.rs opens with:

//! One authority: every job lives on the thread's shared ShellManager

and reaches it through runtime_threads.shell_managers_snapshot() and thread_shell_manager(thread_id, create) — hoisting the manager onto the runtime threads and making that the authority, rather than serving whichever ambient copy happened to be in scope. That is step 1 of the fix order I sketched, already done, and done better: per-thread rather than one process-wide manager, which also handles the case I flagged where tui/ui/apply.rs:2742 swaps the app's handle on workspace change.

It also uses the ownership primitives I noted already existed (ShellJobSnapshot with owner_session_id, require_session_owner), so the session-scoping and foreign-id rejection this issue asks for come from the existing registry rather than a new one.

Caveats, stated plainly: I have not built or tested that branch, it is 53 commits behind main and has 3 conflicts, and CI on #6229 will be its first real check. So "implemented" means the code exists and reads correctly against this issue's requirements — not that it is proven.

Leaving this open until #6229 lands.