Skip to content

feat: add the Process View - #238

Merged
luanAfons0 merged 41 commits into
mainfrom
feat/process-view
Oct 27, 2026
Merged

luanAfons0 merged 41 commits into
mainfrom
feat/process-view

Conversation

@luanAfons0

@luanAfons0 luanAfons0 commented Oct 26, 2026 •

Copy link
Copy Markdown
Owner

What this changes

Adds the Process View: the App's own page that shows every Plugin's state and Usage (CPU of one core, fair-share memory), and FirstMate's own Usage first. The Host reads Usage when asked and keeps none of it (ADR-0032). The same numbers come from GET /processes.json and the new firstmate usage command.

Spec: #228.

Closes #228
Closes #229
Closes #230
Closes #231
Closes #232
Closes #233
Closes #234
Closes #235
Closes #236
Closes #237

Before you ask for a review

  • pnpm check is green: types, lint, format, knip and every test.
  • README.md is updated: new variable FIRSTMATE_PLUGIN, new address /processes.json, new command firstmate usage.
  • No ADR is contradicted in silence: ADR-0021 is amended for the env FIRSTMATE_PLUGIN=<name> ./mcp start in a wsl Place.

ADRs this touches

  • ADR-0032 (new): the Host reads Usage when asked.
  • ADR-0021 (Places): amended, the wsl start now carries the FIRSTMATE_PLUGIN mark.
  • ADR-0004 (no scheduler in the Host), ADR-0005 (no history), ADR-0008 (App pages are data addresses): agreed with.

Also in this branch

  • Check whether killTree leaves a Plugin Server's children running on Linux #237: on Linux each Plugin Server leads its own process group. When it stops or ends, the rest of its group gets SIGTERM, then SIGKILL after the same 5 s grace.
  • firstmate logs -f now starts from the last byte it printed. A line written between the print and the size check was lost; it made logs-command.test.ts flaky under load. No ticket asked for it.
  • AGENTS.md Testing: a test may look at the OS process table to prove which processes run or end, never at a Host module.
  • When Linux seals a process's smaps_rollup (not dumpable), the Host counts its resident memory (VmRSS) instead of 0. This over-counts shared memory; ADR-0032 says so.
  • The packaged App test waits up to 20 s for the App's GPU process to connect before it compares counts. On the Linux runner, the software GPU process can take seconds to show in app.getAppMetrics() after /proc shows it. Two diagnostic commits and their revert (af4316c) are in the history: squash on merge.

Known gaps

  • No test proves that a Plugin Page is not counted in FirstMate's row: the App test cannot open a Plugin Page.
  • A detached Plugin Server that ignores the end of stdin survives a SIGKILL of the Host.
  • FirstMate's row counts the Index Page's renderer, by choice.
  • The full suite is green in CI on Linux and Windows. The Process View was checked by hand on Linux (WSLg) only: it still needs a look on Windows, and the stop on minimize needs a check on a desktop that sends minimize.
  • The commit subjects follow Conventional Commits, which main takes with docs: follow Conventional Commits in every commit message #239.

… on linux

A Plugin Server was not started in a process group of its own, so killTree
could not end its group and ended the Plugin Server alone. A child it
started kept running after a restart and after the Host stopped. The test
with the stubborn-parent fixture showed it, and now proves the whole tree
ends.
…n's facts

Every Plugin Server starts with FIRSTMATE_PLUGIN set to its Plugin's name.
In a wsl Place the start is env FIRSTMATE_PLUGIN=<name> ./mcp, because
Windows hands no variable across. The Supervisor keeps each run's PID,
start time and the reason it stopped, and gives them out through runOf.
…linux

A Plugin Server that ended on SIGTERM, or on its own, left a child that
ignored SIGTERM running. The Host now sends SIGTERM to the whole group, and
kills what is left of the group once the Plugin Server has ended. The
parting-parent fixture proves it after a restart, a Host stop, and an end
of its own.
logs -f took its start from the size of the log after it printed it, so a
line written in between was counted as printed and never shown. Under load
this made the logs -f test fail.
… firstmate usage

GET /processes.json gives FirstMate's own row, then one row per Plugin in
the Plugin Order: state, Place, PID, process count, CPU against one core,
fair-share memory (PSS), start time, and why when Stopped. Only the App and
a terminal may read it. The Host reads /proc when asked, finds a Plugin's
processes from its Plugin Server and by FIRSTMATE_PLUGIN, and keeps only the
last reading of each process, to count CPU between two readings. With no
reading younger than 5 seconds it reads twice, half a second apart.

firstmate usage [--json] prints the same rows. The Mate's primer names it.
Once a Plugin Server ends, the Host sends SIGTERM to what is left of its
process group, and SIGKILL only to what is still there five seconds later.
A restart and a Host stop wait for it. The Plugin guide says so.

A start hook that names the App's own PIDs and throws is said once in the
log, and again only after it has worked (ADR-0022).

Usage takes the home its readers compare against from start.ts, and names
whose processes a row counts instead of a null flag.

Tests: the tree test matches the child's line on the output after the
restart, with no stateful /g pattern; tests share isRunning and untilTrue
in tests/helpers/processes.ts; the fake wsl.exe reads only the processes
that name a Plugin.
…count only plugins for the place column

- /processes.json gets its own 25 s limit, above the Host's own, so the
  first reading on Windows is not cut off. The other asks keep 5 s.
- A fault while a reading is shown is said once, and the polling goes on.
- The Place column shows only when the Plugins are in more than one Place,
  as firstmate usage has it: FirstMate's own row does not count.
- The sort asks are escaped in their attribute, as the restart ask is.
- The page script runs the source of core's cpuText and memoryText
  instead of a copy of them.
- One type for the sort asks, ProcessesAnswer for what /processes.json
  said, Polling for the reading's timer, one function for the cells of a
  Plugin with no Plugin Server, and one list of the App's own views and
  one map of the views an aside shows.
…ss table

ADR-0021 gets a dated note: a wsl Plugin Server starts as
env FIRSTMATE_PLUGIN=<name> ./mcp (ADR-0032), and ADR-0032 names ADR-0021.
AGENTS.md "Testing" says a test may look at the process table to prove
which processes run or end, never at a module of the Host, and names the
shared helper.
@luanAfons0
luanAfons0 marked this pull request as ready for review October 26, 2026 19:22
@luanAfons0
luanAfons0 merged commit 76e840a into main Oct 27, 2026
2 checks passed
@luanAfons0
luanAfons0 deleted the feat/process-view branch October 27, 2026 13:10
@luanAfons0 luanAfons0 mentioned this pull request Oct 28, 2026
2 of 3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment