OKLMdocumentation v1.0.3
On this page

Process design

How process_spec.md maps onto OKLM: the module each section extends, or where new code goes. What exists, with evidence, is the "Processes & Services" section of gap-analysis.md.

Status: accepted (the spec's P0); the four decisions below taken on 2026-11-03 as proposed; P1 and P2 done.

The one process manager

The job manager (include/oklm/harness/jobs.h, src/harness/jobs.c, adr/0012-jobs.md) is the spec's ProcessManager. It already spawns in a process group or a kill-on-close Job Object, logs to .oklm/jobs/<session>/<id>.log, journals each job with its process start time, stops owned jobs at close, dies with the harness and re-attaches detached jobs when the session reopens. Everything below extends it; no second spawner is added. Background sub-agents, language servers and MCP servers become jobs of their own kinds.

Section by section

§ Existing Change or new code
2.1 Data model oklm_job_info, the journal Kinds (command, agent, monitor, lsp, mcp, service), labels, owner (session and agent), states starting / ready / failed, start and end times and signal in the info, ports, restart policy; the journal gains kind, directory and label (ADR-0012 already lists them). Ids stay integers for the API, shown as job 3 (the spec's bg_xxxx is cosmetic).
2.2 Spawning job_spawn in jobs.c OKLM_SESSION_ID, OKLM_PROCESS_ID in the child's environment (also the pager and editor variables of the git specification); timestamps on output lines; a job limit (default 20) with an error listing what runs.
2.3 Output log files, JobOutput Per-reader offsets kept by the manager, filter (OKLM's regex engine) and tail, ANSI escapes stripped for the model, rotation over a size cap, retention as a setting.
2.4 Readiness src/harness/probe.c: port, HTTP (src/client/), log line (regex on the log as it grows), command (proc_run), delay, all / any, with timeout and fail-fast.
2.5 Stopping oklm_jobs_kill, oklm_jobs_close The grace becomes 5 s as ADR-0012 says, and a parameter; stop hooks per kind (a command run first); reverse order at session end; a reaper over the other sessions' journals at start (pid and start time checked), offering to stop their owned jobs; Windows kills the found owned jobs too and terminates a detached job's tree. Ctrl-C closes the jobs before ending.
2.6 Ports src/harness/ports.c: a free check naming the holder (/proc/net/tcp* on Linux, GetExtendedTcpTable on Windows), listening ports of a job's processes.
2.7 Resume re-attach in oklm_jobs_open Works as soon as the agent specification's sessions give --resume a session id.
3 Tools Bash, JobOutput, JobKill ProcessOutput, ProcessStop, ProcessList, WaitFor as the new names, JobOutput / JobKill kept as aliases (and BashOutput / KillShell, per agent-design.md); the log path in Bash's background answer; detach declared in its schema. Backgrounding on timeout: decided below. PowerShell on Windows as its own tool. Ctrl+B in the terminal view.
4 Events tell_jobs, tell_agents in agent.c An event queue per session fed by the manager (exits, readiness, Monitor lines, crashes), drained at the same safe point before each model turn, coalesced; when the REPL is idle, an event starts a turn of its own (wakeOnEvents), at most N times. Monitor is a job of kind monitor whose filtered lines are events. ScheduleWakeup events are wakeups the agent asked for, outside the cap.
5 LSP src/harness/jsonrpc.c (Content-Length framing over a job's pipes; shared with MCP), src/harness/lsp.c (servers per language from settings, lazy start, document sync, diagnostics after Edit and Write, the LSP tool).
6, 7 MCP, sub-agents agent.c background agents MCP servers and background sub-agents become jobs (kinds mcp and agent), so /tasks lists them; jobs started by a sub-agent are its own and stopped at its end unless handed over. This also removes the per-thread PR_SET_PDEATHSIG accident: the manager's own thread forks.
8 Hooks Process events in the agent specification's hooks module.
9 Services .oklm/services.json read by src/harness/services.c: services as jobs with readiness, dependsOn order, /services.
10 Integrations skills Skills first (.oklm/skills/docker/ and others shipped with OKLM), with their dangerous patterns and stop hooks; code only where a skill cannot do it.
11 Safety permissions.c, sandbox.c Dangerous patterns of the agent specification extended per integration; the target (context, account, device) in the question; network exceptions per job (below).
12 to 14 Settings in the agent specification's settings module; /tasks and the exit prompt in the terminal; process events in --output-format stream-json.

Decisions

Taken on 2026-11-03, each as proposed:

  1. Timeouts. A foreground command reaching its timeout is moved to the background (and the model told its id) instead of killed; sleep is never moved. Proposed: yes, as the spec says.
  2. Sandbox and network. Jobs of a sandboxed session have no network. Proposed: a job may ask for the host's network (network: true, a question unless a rule allows it), keeping the default closed (an amendment of ADR-0011).
  3. Grace and retention. 5 s and 30 days by default, both settings (amends the code to match ADR-0012).
  4. Windows shell. A PowerShell tool next to Bash (which keeps cmd.exe), or Bash running PowerShell. Proposed: the separate tool.

Order

P1 and P2 (data model, output, stopping, probes, ports) need nothing from the other specifications; P3 to P5 come after the agent specification's M1 to M8 (settings, sessions); P6 after P1; P7 after its hooks and MCP.