gantry: Skill for Claude Code

Agent Process Management

WARNING — this mutates a live fleet

Every function and route documented here spawns, kills, or restarts real bun processes for real fleet agents against $FLEET_DIR. There is no dry-run mode. When developing or testing against this code, use mockMode: true in gantry.json (or GANTRY_MOCK=1) and/or point FLEET_DIR at a scratch directory (FLEET_DIR=./my-test-fleet bun run dev) — see docs/mock-mode.md and docs/getting-started.md. Never point a dev server's FLEET_DIR at a production fleet directory — only one Gantry instance may run against a given FLEET_DIR at a time, and start/stop/restart calls have no confirmation step.

Source of truth: in-memory tracking, not PID files

server/src/services/process-manager.ts is the whole story:

• trackedProcesses: Map<agentName, ChildProcess> — populated by newSession() on spawn, cleared by the child's exit handler. This is authoritative. isProcessAlive(child) = exitCode === null && !killed && pid !== undefined.
• PID files at $FLEET_DIR/data/pids/<name>.pid are written by writePidFile() purely for external tooling (e.g. the fleet CLI's improve-loop, which spawns outside this server process). They are read for liveness (isPidFileAlive(), via process.kill(pid, 0)) only as a fallback when no in-memory ref exists for that name.
• hasSession(name) checks in-memory first, falls back to the PID file. This fallback is exactly why "agent shows offline but is running" happens after a server restart — the in-memory map is empty on a fresh process, so liveness depends entirely on a correct, non-stale PID file until the health monitor's next hasSession() call re-observes it.
• Logs: $FLEET_DIR/logs/<name>.log. capturePane(name, lines) tails it via spawn('tail', ['-n', lines, logFile]) (never shells out with string interpolation). services/log-parser.ts::parseAgentLog() derives turn count, last-turn age, quota/auth hit counts, and a running/backed-off/stale state (stale = no turn line in the last 1800s) from the tail — this is what feeds the dashboard's per-agent status badge, separate from process liveness.
• scanOrphanedProcesses() — primary: reads every *.pid file under $FLEET_DIR/data/pids/, checks liveness, and reports any PID that's alive but not in trackedProcesses (i.e. survived a server restart with no in-memory ref). Fallback: ps aux | grep -E 'gantry|fleet-agents'. Returns { pid, cmd }[] and kills nothing — the caller decides. No API route or startup hook currently calls this (grep confirms it's only referenced from its own test file) — to use it operationally today you invoke it from a REPL/ script, or replicate the same two checks by hand: list $FLEET_DIR/data/pids/*.pid and cross-reference ps aux.