processes: queryable guest process-tree plugin + bulk OSI walk (epic B slice 1)

[lacraig2]

What

Slice 1 of the "system cartography" epic (epic B): a genuinely usable way for both users and the MCP agent to engage with the guest's process tree. Inspired by #699 (Proctree) but a cleaner, DB-backed design.

Two surfaces

AI / MCP — stable, documented, JSON-serializable live query API (portal generators, yield from):

• processes.get(pid) → flat record or None
• processes.tree() → {"roots": [node, …]} (nested)
• processes.snapshot() → {"processes": […], "tree": {…}}

These read the whole process set in one kernel-side bulk walk (osi.get_all_procs → HYPER_OP_OSI_PROC_ALL) — one RCU-consistent snapshot instead of 1 + N per-pid get_proc reads that could tear.

Users — a legible artifact. Lifecycle is recorded to the event DB and system_map.yaml is materialized at teardown: structured per-process records plus an embedded ASCII tree.

schema_version: 1
generated_by: processes
process_count: 72
processes: [{pid, ppid, name, create_time, uid…, exec_count, exit}, …]
tree: |
  init (1)
  `- httpd (400)
     `- status.cgi (517)  [exit: 0]

Persistence (DB-backed)

• exec_event → ProcStart (identity/genealogy: pid, ppid, create_time, comm, ids). argv/env stay on the existing Exec event.
• exit / exit_group → ProcExit. Identity comes off syscall.pid / syscall.create_time (denormalized by the driver) — zero portal round-trips, no read of the dying task.
• system_map.yaml = ProcStart LEFT JOIN ProcExit on (pid, create_time), re-exec coalesced. Because plugins unload in reverse load order (this plugin's uninit runs before the DB's final flush), teardown calls a new synchronous DB.flush() then DB.query().

Supporting changes

• osi.get_all_procs() — paginated decode of the slim osi_proc_node array.
• pengutils.events — lean ProcStart / ProcExit.
• loggers/db.py — synchronous flush() + query().

Driver-side safety

Live walk + exit path touch only kernel task_struct (comm, skip !mm); never access_remote_vm on userspace, so nothing faults on an exiting/stopped context.

Tests (host-side, penguin.testing; no PANDA/guest)

• tests/unit/test_processes.py — event→DB emission, DB→render, live tree/get/snapshot join (via doubles).
• tests/unit/test_osi_bulk.py — real-ISF ABI roundtrip of get_all_procs (skips unless pointed at a driver build carrying the op).
• tests/unit/test_db.py — flush() / query().

Full tests/unit suite green.

Live validation

Booted an armel/6.13 guest with the driver from rehosting/igloo_driver#88: system_map.yaml captured 72 real processes with correct genealogy, re-exec, and exit codes (proving the syscall_event.pid path), and a probe exercised get_all_procs/snapshot() live through HYPER_OP_OSI_PROC_ALL.

Dependency

Requires rehosting/igloo_driver#88 (HYPER_OP_OSI_PROC_ALL + syscall_event.pid). The live query API needs that driver; the DB-backed system_map.yaml works today. Follow-up: bump IGLOO_DRIVER_VERSION once #88 is released (then test_osi_bulk runs unskipped in CI).

Scope / follow-ons

Slice 1 only. Deferred: thread/kernel-thread enumeration, fd/peer graph, maps/lib inventory, CPU/scheduling, get_ptregs.