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:
- Timeouts. A foreground command reaching its timeout
is moved to the background (and the model told its id) instead of
killed;
sleepis never moved. Proposed: yes, as the spec says. - 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). - Grace and retention. 5 s and 30 days by default, both settings (amends the code to match ADR-0012).
- 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.