# RFD 024: Detached Query Execution - **Status**: Abandoned - **Category**: Design - **Authors**: Jean Mertz - **Date**: 2025-07-19 > [!IMPORTANT] > This RFD is **Abandoned**. > > Superseded by [RFD 027: Client-Server Query Architecture][RFD 027], which > unifies detached execution, live attachment, and foreground queries under a > single client-server model. The process registry and `queue` policy from this > RFD are carried forward into RFD 027 (the `queue` policy is renamed to > `defer`). > > The original text below is preserved for historical context. ## Summary This RFD introduces `jp query --detach` for running conversations in the background, a process registry for visibility into running queries, and the `queue` detached policy that persists an incomplete turn and exits when an inquiry requires user input. Resumption after exit uses `--continue` from [RFD 023]. This RFD depends on [RFD 023] (Resumable Conversation Turns) for incomplete turn persistence and the `--continue` flag, on [RFD 020] (Parallel Conversations) for conversation locks and the `--id` flag, and on [RFD 019] (Non-Interactive Mode) for detached prompt policies. ## Motivation Each `jp query` invocation occupies a terminal for its entire duration. A long-running query with multiple tool call cycles keeps a terminal tab busy until it completes. If the user closes the terminal, the query dies. With per-session conversation tracking ([RFD 020]) and resumable turns ([RFD 023]), the foundations exist for a query to run independently of a terminal session: conversations can be targeted by ID, locks prevent concurrent mutations, and incomplete turns can be persisted and resumed. What's missing is the ability to say "run this in the background" and the policy for what happens when a backgrounded query needs user input. ## Design ### `--detach` `jp query --detach` spawns a background process for the conversation and exits immediately. The background process runs the query to completion — streaming the LLM response, executing tool calls, and cycling through follow-up rounds — without a terminal. ```sh jp query --detach "Refactor the auth module" jp query --detach --id=jp-c17528832001 "Continue in the background" jp query --detach --new "Start something new in the background" ``` All conversation targeting flags from [RFD 020] combine with `--detach`. All lock errors apply — if the conversation is locked, `--detach` fails the same way a foreground query would. `--detach` is an explicit opt-in. Piped execution (`echo foo | jp query | cat`) is **not** detached — the process runs in the foreground, owned by the pipeline. `--detach` means "spawn a background process and exit." The absence of a TTY does not imply detachment. ### Stopping Points A detached process runs until it reaches a **stopping point**: | Stopping point | What happens | |--------------------------|------------------------------------------| | Turn completes | Process persists the conversation and | | | exits cleanly. | | Inquiry needs user input | Process persists the incomplete turn | | | ([RFD 023]) and exits. | | Unrecoverable error | Process persists what it can and exits | | | with an error. | The key insight: a detached process never idles. It either does useful work (streaming, executing tools) or it exits. There is no "paused waiting for input" state — that state is represented by the persisted `IncompleteTurn` on disk, not by a running process. ### The `queue` Detached Policy This RFD adds a fourth detached policy mode to the three defined in [RFD 019]: | Mode | Behavior | |-------------|------------------------------------------| | `auto` | Auto-approve or route to LLM. | | `defaults` | Use default values. | | `deny` | Fail the tool call. | | **`queue`** | **Persist the incomplete turn and exit** | | | **the process.** | When `queue` is active and an inquiry arrives: 1. The tool coordinator lets all other running tools in the batch complete. 2. Each completed tool's `ToolCallResponse` is persisted incrementally ([RFD 023]). 3. The `InquiryRequest` for the tool that needs input is persisted. 4. The process exits cleanly. The conversation is now in an incomplete turn state. The user resumes it later with `jp query --continue --id=`, which prompts for the inquiry answer and continues the turn ([RFD 023]). With `queue` available, it becomes the **default detached policy** — replacing `deny` from [RFD 019] as the default for detached processes. Nothing runs unattended unless explicitly configured. Users who want automation set `detached = "auto"` in their config. The default for non-detached non-interactive contexts (piped execution without `--detach`) remains `deny` as defined in [RFD 019]. `queue` only applies when the process was started with `--detach`. #### Integration with prompt routing The `route_prompt` function from [RFD 019] is extended: ```rust fn route_prompt( inquiry: &Inquiry, has_client: bool, policy: DetachedMode, config_exclusive: Option, ) -> PromptAction { if has_client { return PromptAction::PromptClient; } let exclusive = config_exclusive.unwrap_or_else(|| inquiry.exclusive()); match policy { DetachedMode::Queue => PromptAction::PersistAndExit, DetachedMode::Auto if exclusive => PromptAction::Fail, DetachedMode::Auto => match inquiry { Inquiry::RunTool { .. } => PromptAction::AutoApprove, Inquiry::DeliverToolResult { .. } => PromptAction::AutoDeliver, Inquiry::ToolQuestion { .. } => PromptAction::LlmInquiry, }, DetachedMode::Defaults => PromptAction::UseDefault, DetachedMode::Deny => PromptAction::Fail, } } ``` `PromptAction::PersistAndExit` signals the tool coordinator to let other tools finish, persist the incomplete turn, and initiate a clean shutdown. ### Process Registry Running detached processes register in the user-local data directory: ``` ~/.local/share/jp/workspace//processes/ └── .json ``` The workspace ID scopes the registry to avoid collisions between projects. The conversation ID is the key — at most one running process per conversation, enforced by the conversation lock ([RFD 020]). #### Process Entry Format ```json { "conversation_id": "jp-c17528832001", "pid": 12345, "started_at": "2025-07-19T14:30:00.000Z" } ``` The entry is minimal: it records that a process is running and which conversation it operates on. There is no `status` or `pending_inquiry` field — the "waiting for input" state lives in the conversation's `IncompleteTurn` on disk, not in the process registry. By the time an inquiry is pending, the process has already exited. The registry entry is written when the detached process starts and deleted when it exits. #### Stale Entry Cleanup `jp conversation ls` checks PID liveness for each entry. If the process is dead, the entry is removed. This handles crashes, SIGKILL, and machine reboots. PID liveness is checked via `kill(pid, 0)` on Unix. This uses the same background task cleanup approach as [RFD 020]'s lock and session file cleanup. ### CLI Interface #### `jp query --detach` Spawns a background process and exits immediately. Prints the conversation ID so the user can target it later: ```sh $ jp query --detach "Refactor the auth module" Detached: jp-c17528832001 ``` #### `jp conversation ls` (extended) Shows process status alongside conversation metadata: | Status | Meaning | |---------------------------------|------------------------------------------| | `running (pid NNN)` | Detached process is active | | `waiting-for-input (tool_name)` | No process; incomplete turn with pending | | | inquiry | | `interrupted (...)` | No process; incomplete turn without | | | pending inquiry | | (no status) | Idle, last turn complete | The `running` status comes from the process registry (PID liveness check). The `waiting-for-input` and `interrupted` statuses come from the conversation's last event ([RFD 023]). ```sh $ jp conversation ls ID TITLE STATUS jp-c17528832001 Refactor auth waiting-for-input (fs_modify_file) jp-c17528831500 Fix tests running (pid 12345) jp-c17528831000 Debug service idle ``` #### `jp conversation kill ` Sends SIGTERM to the detached process, cleans up the registry entry. The conversation data remains intact — this only terminates the process, which releases the conversation lock ([RFD 020]). ```sh $ jp conversation kill jp-c17528831500 Killed process 12345 for conversation jp-c17528831500. ``` If the process has already exited (stale entry), the entry is cleaned up silently. ### Daemonization `--detach` needs to create a process that outlives the parent terminal. The re-exec strategy is cleanest: 1. `jp query --detach "message"` validates arguments, resolves the conversation, acquires the lock. 2. It re-executes itself with an internal flag (`--_detached`) and the resolved conversation ID, redirecting stdout/stderr to `/dev/null` (or a log file if `-v` is set). 3. The child process starts in a new process group (`setsid`), writes its PID to the process registry, and runs the query. 4. The parent confirms the child started, prints the conversation ID, and exits. The internal `--_detached` flag is hidden from `--help`. It signals that the process is already detached and should not attempt to daemonize again. #### Output handling A detached process has no terminal. Output channels: | Channel | Destination | |------------|------------------------------------------| | stdout | `/dev/null` (assistant output has no | | | consumer) | | stderr | `/dev/null` or log file | | `/dev/tty` | Not available (`has_client = false`) | | Tracing | Log file (if `-v` specified on the | | | original command) | The `Printer` is initialized with sink writers. Renderers still run (they maintain state for event building) but their output is discarded. ### Relationship to Conversation Locks A detached process holds the conversation lock ([RFD 020]) for its entire execution. This prevents other sessions from writing to the same conversation. Lock contention from a detached process produces a clear error: ```sh $ jp query --id=jp-c17528832001 "follow-up" Error: Conversation jp-c17528832001 is locked by pid 12345 (detached). jp conversation kill jp-c17528832001 Terminate the detached process. --fork Branch from this conversation. --new Start a new conversation. ``` When the detached process exits (turn complete or inquiry hit), it releases the lock. The conversation is then available for `--continue` or a new query. ### End-to-End Workflow A typical detached workflow: ```sh # 1. Start a detached query $ jp query --detach "Refactor auth to use the new token format" Detached: jp-c17528832001 # 2. Check on it later $ jp conversation ls ID TITLE STATUS jp-c17528832001 Refactor auth waiting-for-input (fs_modify_file) # 3. Resume and answer the inquiry $ jp query --continue --id=jp-c17528832001 Resuming incomplete turn for jp-c17528832001... ⏳ Incomplete turn (waiting for input) ✓ cargo_check — completed ✓ fs_read_file — completed ⏸ fs_modify_file — "Overwrite existing file?" > Overwrite existing file? [y/n]: y [continues tool execution, sends follow-up to LLM, completes turn] ``` If the detached process completes without hitting an inquiry: ```sh $ jp query --detach "Run cargo check on all crates" Detached: jp-c17528832001 $ jp conversation ls ID TITLE STATUS jp-c17528832001 Run cargo check idle $ jp conversation print --id=jp-c17528832001 --last [shows the completed turn] ``` ## Drawbacks **Process lifecycle management.** Daemonization (re-exec, setsid, signal handling, output redirection) is non-trivial to implement correctly on Unix. Edge cases around process groups, controlling terminals, and signal inheritance require careful handling. **Platform constraints.** `setsid`, `/dev/null`, and `kill(pid, 0)` are Unix-specific. Windows support requires different daemonization and PID liveness mechanisms. The initial implementation targets macOS and Linux only. **No live output.** A detached process discards all rendered output. If the user wants to see what's happening, they must wait for completion and use `conversation print`. Live re-attachment to a running process is deferred to a separate RFD. **Two-step for inquiries.** When a detached query hits an inquiry, the user must run a separate command (`--continue`) to answer it. This is more friction than an interactive terminal where the prompt appears immediately. The trade-off is intentional: the terminal is freed for other work. ## Alternatives ### Keep the process alive at inquiries (original RFD 022 design) When a detached process hits an inquiry, keep the process running and use IPC (Unix domain sockets) to deliver the answer when the user attaches. Rejected because keeping a process alive to wait for input is wasteful. The conversation state is already persisted. The `IncompleteTurn` from [RFD 023] captures everything needed to resume. Exiting and resuming via `--continue` is simpler, uses no IPC, requires no socket infrastructure, and works across machine reboots. ### `nohup` wrapper instead of re-exec Tell users to run `nohup jp query "..." &` instead of building daemonization into JP. Rejected because it's fragile (output handling, signal masking, lock cleanup depend on the user's shell configuration), undiscoverable, and doesn't integrate with the process registry or `conversation ls`. ### Tmux/screen session instead of daemonization Spawn the query inside a tmux session for detachment. Rejected because it adds a hard dependency on an external tool, doesn't integrate with `conversation ls`, and requires the user to know tmux. ### Store process registry in `.jp/` Put process entries in `.jp/processes/` alongside conversations. Rejected because `.jp/` is typically committed to version control. Process state is ephemeral, machine-local, and user-local. The user data directory (`~/.local/share/jp/workspace/`) is the correct location. ## Non-Goals - **Live re-attachment.** Connecting to a still-running detached process to see live output and answer inquiries interactively is a separate concern. This RFD covers detaching and running to a stopping point; re-attachment is deferred to a future RFD. - **Sub-agent support.** The process model is compatible with future sub-agents but this RFD does not propose agent infrastructure. - **Cross-machine visibility.** Process registry is local. No network protocol. - **Non-query commands.** Only `jp query` creates detached processes. ## Risks and Open Questions ### Lock handoff timing The re-exec daemonization strategy has a timing question: who holds the conversation lock? Option A: The parent acquires the lock, passes the lock file descriptor to the child via fd inheritance, and the child holds it for the duration. The parent exits after confirming the child started. The lock is never released between parent and child. Option B: The parent does not acquire the lock. The child acquires it after starting. There is a window where no process holds the lock — another session could sneak in. This is unlikely but possible. Option A is safer. `flock` file descriptors survive `exec`, so the child inherits the lock. ### Multiple inquiries in one batch If two tools in the same batch both need user input while in `queue` mode, both `InquiryRequest` events are persisted. On `--continue`, the user answers both sequentially before any tool re-executes. The turn state reconstruction in [RFD 023] handles this — it finds all pending inquiries and prompts for each. ### Interaction with `--non-interactive` `--detach` implies `--non-interactive` ([RFD 019]). A detached process has no TTY and cannot prompt. The detached policy (`queue` by default) governs what happens at inquiries. `--detach --non-interactive` is redundant but not an error. ### Process registry race conditions Two terminals running `jp query --detach --new` simultaneously create two conversations with two processes. Each writes its own registry entry (keyed by conversation ID). No race — different conversations, different entries. The conversation lock prevents two detached processes on the *same* conversation. ### Detached process logging When a detached process encounters errors (LLM provider down, tool failure), the errors are lost if no log file is configured. Consider defaulting to a log file when `--detach` is used, even without `-v`: ```txt ~/.local/share/jp/workspace//processes/.log ``` This log would be cleaned up alongside the registry entry on process exit. ## Implementation Plan ### Phase 1: Process Registry Every `jp query` writes a process entry on start and removes it on exit. `jp conversation ls` reads the registry and displays `running (pid NNN)` alongside conversation metadata. Stale entries are cleaned up via PID liveness checks. No `--detach` yet. Just visibility into running foreground queries. Can be merged independently. ### Phase 2: `queue` Detached Policy Add `DetachedMode::Queue` and `PromptAction::PersistAndExit` to the prompt routing ([RFD 019]). When the tool coordinator receives `PersistAndExit`, it waits for other tools to finish, persists the incomplete turn, and initiates shutdown. `queue` is not yet the default — it requires `--detach` (Phase 3) to be useful. For now it can be activated via config (`detached = "queue"`) for testing with `--non-interactive`. Depends on [RFD 023] Phase 2 (incremental persistence) and [RFD 019] Phase 2 (routing integration). ### Phase 3: `--detach` Flag and Daemonization Implement `jp query --detach`. Re-exec daemonization with `setsid`, lock handoff via fd inheritance, output redirection to sink/log. Implement `jp conversation kill `. Set `queue` as the default detached policy for `--detach`. Depends on Phase 1 and Phase 2. Unix-only initially. ## References - [RFD 023: Resumable Conversation Turns][RFD 023] — incomplete turn persistence and `--continue` flag; prerequisite for the exit-and-resume model. - [RFD 020: Parallel Conversations][RFD 020] — conversation locks and per-session targeting; prerequisite for detached execution. - [RFD 019: Non-Interactive Mode][RFD 019] — detached prompt policies (`auto`, `defaults`, `deny`); this RFD adds `queue`. - [RFD 018: Typed Inquiry System][RFD 018] — the `Inquiry` enum used in prompt routing. - [RFD 005: First-Class Inquiry Events][RFD 005] — persisted inquiry events that appear in the incomplete turn. [RFD 005]: 005-first-class-inquiry-events.md [RFD 018]: 018-typed-prompt-routing-enum.md [RFD 019]: 019-non-interactive-mode.md [RFD 020]: 020-parallel-conversations.md [RFD 023]: 023-resumable-conversation-turns.md [RFD 027]: 027-client-server-query-architecture.md