Skip to content

Decision record · ADR

ADR-0066: Detach CLI runs as web-console jobs that link their first record

Status: accepted | Date: 2026-10-14

References: RFC-0003, RFC-0012

Operators and agents drive hour-long recipes from sessions that end, so a downstream workspace ran every long command as ssh host 'tmux new-session -d ... inferlab ...'. The web console already launches detached jobs with a job directory, its own session and process group, separate logs, exit status, producer identity, and a validated non-escalating interrupt (ADR-0056), but only from the browser. Every later lifecycle command — status, logs, stop, record reading — takes a record identifier, which a run creates only after resolution.

Detached CLI runs are console jobs. The job’s supervisor names the job directory to the job’s command through the INFERLAB_JOB_DIR environment variable, and the command links there the first top-level record it announces, so the detaching invocation can return the record identifier as soon as it exists and the console can lead from a job to its record. Interruption from the CLI reuses the console’s validated cancel. RFC-0003:C-RUNTIME-WORKFLOWS owns the detach and interrupt contract and RFC-0012:C-ACTIONS the job directory.

Long runs no longer need a tmux session to outlive the caller, and agents can follow and interrupt them through records and job identifiers. A detaching invocation blocks until the first record exists, including any wait for the workspace allocation lock; interrupting that wait leaves the job running and names it. Jobs are visible in the web console whichever entry point launched them. Like the console’s jobs, --detach and job interrupt are Unix-only, and every detached run leaves a job directory under .inferlab/runtime/jobs/ that nothing deletes, so those directories accumulate. The job mechanism moves out of the web module and now has two consumers, the console and the CLI.

Launch the invocation as a console job and hand its first record back through the job directory, which the job’s command writes when it announces the record (accepted)

Section titled “Launch the invocation as a console job and hand its first record back through the job directory, which the job’s command writes when it announces the record (accepted)”
  • Pros: One job contract for the console and the CLI, so the console lists CLI-detached runs, The caller receives the record identifier every later command takes, without parsing logs, The console gains the job-to-record link for free
  • Cons: The detaching invocation waits through resolution and any allocation-lock wait, which is unbounded while another run of the workspace holds the lock

Fork the invocation into the background with its own detach code path (rejected)

Section titled “Fork the invocation into the background with its own detach code path (rejected)”
  • Pros: Smallest code change
  • Cons: Duplicates session, logging, identity, and interrupt handling the console jobs already own, and those runs would be invisible to the console

Return the job identifier at once and let callers find the record identifier in the job’s stderr progress (rejected)

Section titled “Return the job identifier at once and let callers find the record identifier in the job’s stderr progress (rejected)”
  • Pros: Returns immediately
  • Cons: Couples callers to diagnostic text that is not a machine contract

Assign the record identifier before launch and pass it to the job (rejected)

Section titled “Assign the record identifier before launch and pass it to the job (rejected)”
  • Pros: Returns immediately with the final identifier
  • Cons: A recipe creates several records, so pre-assigning the one the caller needs would change identifier derivation for every workflow

Keep running long commands inside tmux or nohup on the host, as downstream workspaces do today (rejected)

Section titled “Keep running long commands inside tmux or nohup on the host, as downstream workspaces do today (rejected)”
  • Pros: No new code
  • Cons: Returns no record identifier, offers no producer-validated interrupt, stays invisible to the console, and needs tmux or a similar tool on every host