ADR-0012: Job persistence and orphans
Records what the harness keeps about background jobs and agents, what happens to them when the harness exits or restarts, and how no process is left running unknown to it.
Status: accepted (2026-11-01).
Context
The harness runs long commands (builds, test suites, training runs) and sub-agents in the background while the conversation goes on, and reports their results when they finish. A session can end on purpose, by a crash or a reboot. Without a policy, background processes either die silently with the harness, losing work the user expected, or survive it unseen, holding resources and writing files nobody follows.
Decision
- Journal. Each session has a job journal,
.oklm/jobs/<session>.jsonl, append-only: one line per event (started, output rotated, finished, killed, interrupted) with the job's id, kind (command or agent), command or prompt, working directory, process id, the process's start time (from/proc/<pid>/stat, orGetProcessTimes), the output file and, at the end, the exit status. A job's output goes to.oklm/jobs/<session>/<id>.log, never only to memory. - Owned by default. A job belongs to the harness that
started it: it runs in its own process group (Linux) or Job Object
(Windows, kill on close). When the harness exits normally, it stops its
running jobs (the group gets SIGTERM, then SIGKILL after 5 seconds;
Windows terminates the Job Object) and records them as
killed. A crash takes them down with it on Windows (the Job Object's handle closes); on Linux the harness setsPR_SET_PDEATHSIGon each job's leader so the group is signalled when the harness dies. That signal follows the thread that forked, not the process, so every child is forked by one thread of the harness's own that lives as long as the process (proc_fork()): a job a background sub-agent starts does not die with the sub-agent's thread. - A sub-agent's own. A job started by a background
sub-agent records it as its owner. When the sub-agent ends, its jobs
still running are stopped, except those started with
keep_alive(handed to the session, the journal records it) and detached ones; its report lists both. - Detached on request. A job started with
detach(a tool argument the permission rules can deny, ADR-0010) is not killed at exit: it runs in its own session (setsid) or a Job Object without kill-on-close, and the journal says so. Only detached jobs survive the harness. - Restart. A harness opening a session reads its
journal. A job with no end event is checked by process id and start time
(a reused pid does not match): still running and detached, it is
re-attached (its log is followed and its end recorded when its process
is gone; the exit status is then unknown unless the job wrote it to its
status file); otherwise it is recorded as
interrupted. Interrupted jobs are listed to the user and to the model; none is restarted automatically, since a half-run command may not be safe to repeat. - Agents are jobs of kind agent: their transcript is their log, and an interrupted agent can be resumed from it by an explicit request, not automatically.
- Retention. Journals and logs of sessions older than 30 days (a setting) are removed when a harness starts, except those of jobs still running.
Consequences
Nothing the harness starts runs unseen: a process is either owned
(and dies with its harness) or detached (and recorded, with its log, for
the next harness to find). The cost is a journal write per job event and
the platform code for process groups, death signals and Job Objects,
which the sandbox (ADR-0011) needs anyway. A detached job whose machine
reboots ends as interrupted with whatever its log
holds.
Amendments
2026-11-03, with the process specification's P1 and P2 (process-design.md):
- The stop's grace is 5 s, as decided above (the code had 2 s), a
setting (
processes.defaultGraceMs) and a parameter per job. - The journal records each job's kind, directory, label and owner, the
signal that ended it,
rotatedandrestartedevents; the retention is a setting (processes.logRetentionDays), 30 days by default. - A job may have a restart policy (started again after failing, with a growing delay); "nothing is restarted" holds for jobs without one.
- Logs are rotated past a size cap by copy and truncation (jobs append to their log), offsets counting the rotated bytes.