Jobs

Jobs

Background processes that agents start, such as dev servers and watchers, and how to watch and stop them.

A job is a background process an agent started: a dev server, a file watcher, a long build. Agents start one by running bash with background: true; the command keeps running while the agent carries on, and its output goes to a log file.

Jobs belong to the daemon, not to the agent or the terminal: they keep running after the agent's turn ends or the terminal closes, until they exit or someone stops them. They are listed in every client.

What the agent sees

Starting a job returns its id, process id and log file:

● bash npm run dev
  ⎿ Started job 3fa9c210 in the background (pid 48211). Check on it with job_output and stop it with job_kill. Output is written to /Users/you/.malac/jobs/3fa9c210.log

The agent manages jobs with three tools:

Tool	Kind	What it does
job_list	Safe	List jobs, newest first, with status, process id and working directory
job_output	Safe	Show the latest output of a job (tail: lines from the end, default 100, max 2000) and whether it still runs
job_kill	Execute	Stop a job and every process it started: SIGTERM, then SIGKILL after 3 seconds

job_kill follows your permission mode like any command; listing and reading never ask.

Watching jobs

Terminal UI. The status line counts running jobs (2 jobs); click it, choose View → Jobs…, or type /jobs. The jobs view lists every job with its status, pid, folder and run time, over the selected job's log tail. ↑ ↓ select, k (or x, Delete) stops the selected job, Esc closes.

Mark	Status
●	running
○	exited with status 0
✗	exited with an error
■	killed
?	unknown: it ended while no daemon was watching

Web UI. The Jobs page shows the same table (command, status, folder, agent, start time, run time and exit code) with the selected job's output, Refresh output and Stop.

From a script. The daemon's API has GET /api/jobs and GET /api/jobs/<id>/output; see Protocol.

Files and lifetime

Each job has a record ~/.malac/jobs/<id>.json (command, folder, pid, start and end time, exit code, the agent that started it) and its log ~/.malac/jobs/<id>.log.

When the daemon starts, it restores the records: jobs whose processes are gone are marked finished with status unknown, running ones are watched until they end, and finished jobs older than a week are deleted.

malac daemon stop and restart refuse while jobs run, so a restart never kills your dev server by accident; --force stops them.