agentctl-swarm 0.1.1

package/lib/supervisor.test.js

@@ -0,0 +1,327 @@
+/**
+ * Supervisor Tests
+ */
+
+import { test, describe, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { Supervisor } from './supervisor.js';
+import { DaemonState } from './daemon.js';
+
+const tmpBase = path.join(os.tmpdir(), `supervisor-test-${Date.now()}`);
+
+function makeConfig(overrides = {}) {
+  const id = Math.random().toString(36).slice(2, 8);
+  return {
+    count: 3,
+    maxActive: 2,
+    basePath: path.join(tmpBase, `workspace-${id}`),
+    pidfile: path.join(tmpBase, `swarm-${id}.pid`),
+    logDir: path.join(tmpBase, `logs-${id}`),
+    heartbeatIntervalMs: 100,
+    persist: false,
+    ...overrides,
+  };
+}
+
+describe('Supervisor', () => {
+  before(() => {
+    fs.mkdirSync(tmpBase, { recursive: true });
+  });
+
+  after(() => {
+    fs.rmSync(tmpBase, { recursive: true, force: true });
+  });
+
+  test('start spawns N daemons', () => {
+    const sup = new Supervisor(makeConfig({ count: 5 }));
+    sup.start();
+
+    const status = sup.status();
+    assert.strictEqual(status.total, 5);
+    assert.strictEqual(status.idle, 5);
+    assert.strictEqual(status.active, 0);
+    assert.strictEqual(status.running, true);
+
+    sup.stop();
+  });
+
+  test('pidfile prevents double start', () => {
+    const config = makeConfig();
+    const sup1 = new Supervisor(config);
+    sup1.start();
+
+    const sup2 = new Supervisor(config);
+    assert.throws(() => sup2.start(), /already running/);
+
+    sup1.stop();
+  });
+
+  test('pidfile removed on stop', () => {
+    const config = makeConfig();
+    const sup = new Supervisor(config);
+    sup.start();
+    assert.ok(fs.existsSync(config.pidfile));
+
+    sup.stop();
+    assert.ok(!fs.existsSync(config.pidfile));
+  });
+
+  test('stale pidfile is cleaned up', () => {
+    const config = makeConfig();
+    // Write a pidfile with a dead PID
+    fs.mkdirSync(path.dirname(config.pidfile), { recursive: true });
+    fs.writeFileSync(config.pidfile, '999999999');
+
+    const sup = new Supervisor(config);
+    sup.start(); // Should succeed despite stale pidfile
+
+    assert.strictEqual(sup.status().running, true);
+    sup.stop();
+  });
+
+  test('stop cleans up all daemons', () => {
+    const sup = new Supervisor(makeConfig({ count: 3, persist: false }));
+    sup.start();
+    assert.strictEqual(sup.processTable.size, 3);
+
+    sup.stop();
+    assert.strictEqual(sup.processTable.size, 0);
+    assert.strictEqual(sup.running, false);
+  });
+
+  test('stop with persist keeps workspaces', () => {
+    const config = makeConfig({ count: 2, persist: true });
+    const sup = new Supervisor(config);
+    sup.start();
+
+    // Get workspace paths before stopping
+    const workspaces = [];
+    for (const [, entry] of sup.processTable) {
+      workspaces.push(entry.daemon.workspace);
+    }
+
+    sup.stop();
+
+    // Workspaces should still exist
+    for (const ws of workspaces) {
+      assert.ok(fs.existsSync(ws), `Workspace should persist: ${ws}`);
+    }
+  });
+
+  test('promotion respects maxActive', () => {
+    const sup = new Supervisor(makeConfig({ count: 3, maxActive: 1 }));
+    sup.start();
+
+    const agents = [...sup.processTable.values()];
+
+    // Override _spawnClaude BEFORE handleMessage (supervisor auto-approves synchronously)
+    agents[0].daemon._spawnClaude = function () {
+      this.state = DaemonState.ACTIVE;
+      this.emit('promoted', { agentId: this.agentId, pid: null, task: this.currentTask });
+    };
+
+    // First promotion — auto-approved by supervisor
+    agents[0].daemon.handleMessage({
+      type: 'ASSIGN',
+      agentId: agents[0].daemon.agentId,
+      task: { component: 'test1', prompt: 'task 1' },
+    });
+
+    assert.strictEqual(sup.activeCount, 1);
+
+    // Second promotion should be queued (maxActive=1)
+    agents[1].daemon.handleMessage({
+      type: 'ASSIGN',
+      agentId: agents[1].daemon.agentId,
+      task: { component: 'test2', prompt: 'task 2' },
+    });
+
+    assert.strictEqual(sup.activeCount, 1);
+    assert.strictEqual(sup.promotionQueue.length, 1);
+
+    sup.stop();
+  });
+
+  test('promotion queue drains on demotion', () => {
+    const sup = new Supervisor(makeConfig({ count: 3, maxActive: 1 }));
+    sup.start();
+    const logs = [];
+    sup.on('log', l => logs.push(l));
+
+    const agents = [...sup.processTable.values()];
+
+    // Override _spawnClaude BEFORE triggering promotions
+    agents[0].daemon._spawnClaude = function () {
+      this.state = DaemonState.ACTIVE;
+      this.emit('promoted', { agentId: this.agentId, pid: null, task: this.currentTask });
+    };
+    agents[1].daemon._spawnClaude = function () {
+      this.state = DaemonState.ACTIVE;
+      this.emit('promoted', { agentId: this.agentId, pid: null, task: this.currentTask });
+    };
+
+    // Promote first (auto-approved)
+    agents[0].daemon.handleMessage({
+      type: 'ASSIGN',
+      agentId: agents[0].daemon.agentId,
+      task: { component: 'test1', prompt: 'task 1' },
+    });
+
+    // Queue second (maxActive=1, slot full)
+    agents[1].daemon.handleMessage({
+      type: 'ASSIGN',
+      agentId: agents[1].daemon.agentId,
+      task: { component: 'test2', prompt: 'task 2' },
+    });
+    assert.strictEqual(sup.promotionQueue.length, 1);
+
+    // Demote first — should auto-promote second from queue
+    agents[0].daemon._handleClaudeExit(0, null, 'done', '');
+
+    assert.strictEqual(sup.promotionQueue.length, 0);
+
+    sup.stop();
+  });
+
+  test('token budget pauses promotions', () => {
+    const sup = new Supervisor(makeConfig({ count: 2, maxActive: 5, tokenBudget: 100 }));
+    sup.start();
+
+    sup.tokensUsed = 100; // Exhaust budget
+
+    const agents = [...sup.processTable.values()];
+    const unclaims = [];
+    agents[0].daemon.on('unclaim', u => unclaims.push(u));
+
+    agents[0].daemon.handleMessage({
+      type: 'ASSIGN',
+      agentId: agents[0].daemon.agentId,
+      task: { component: 'test', prompt: 'task' },
+    });
+
+    assert.strictEqual(sup.promotionsPaused, true);
+    assert.strictEqual(unclaims.length, 1);
+    assert.ok(unclaims[0].reason.includes('budget'));
+
+    sup.stop();
+  });
+
+  test('scale up adds daemons', () => {
+    const sup = new Supervisor(makeConfig({ count: 2 }));
+    sup.start();
+    assert.strictEqual(sup.processTable.size, 2);
+
+    const result = sup.scale(5);
+    assert.strictEqual(result.from, 2);
+    assert.strictEqual(result.to, 5);
+    assert.strictEqual(result.added, 3);
+    assert.strictEqual(sup.processTable.size, 5);
+
+    sup.stop();
+  });
+
+  test('scale down removes idle daemons', () => {
+    const sup = new Supervisor(makeConfig({ count: 5 }));
+    sup.start();
+
+    const result = sup.scale(2);
+    assert.strictEqual(result.from, 5);
+    assert.strictEqual(result.removed, 3);
+    assert.strictEqual(sup.processTable.size, 2);
+
+    sup.stop();
+  });
+
+  test('scale down preserves active agents', () => {
+    const sup = new Supervisor(makeConfig({ count: 3, maxActive: 3 }));
+    sup.start();
+
+    const agents = [...sup.processTable.values()];
+
+    // Override _spawnClaude BEFORE handleMessage
+    agents[0].daemon._spawnClaude = function () {
+      this.state = DaemonState.ACTIVE;
+      this.emit('promoted', { agentId: this.agentId, pid: null, task: this.currentTask });
+    };
+
+    // Promote one agent (auto-approved)
+    agents[0].daemon.handleMessage({
+      type: 'ASSIGN',
+      agentId: agents[0].daemon.agentId,
+      task: { component: 'busy', prompt: 'working' },
+    });
+
+    // Scale down to 1 — should only remove idle daemons
+    const result = sup.scale(1);
+    assert.strictEqual(result.removed, 2); // 2 idle removed
+    // The active agent should still be in the process table
+    assert.ok(sup.processTable.size >= 1);
+
+    sup.stop();
+  });
+
+  test('scale to zero stops swarm', () => {
+    const sup = new Supervisor(makeConfig({ count: 3 }));
+    sup.start();
+    sup.scale(0);
+    assert.strictEqual(sup.running, false);
+    assert.strictEqual(sup.processTable.size, 0);
+  });
+
+  test('reloadConfig updates maxActive', () => {
+    const sup = new Supervisor(makeConfig({ count: 2, maxActive: 1 }));
+    sup.start();
+
+    assert.strictEqual(sup.maxActive, 1);
+    sup.reloadConfig({ maxActive: 10 });
+    assert.strictEqual(sup.maxActive, 10);
+
+    sup.stop();
+  });
+
+  test('reloadConfig resumes promotions if budget increased', () => {
+    const sup = new Supervisor(makeConfig({ count: 2, tokenBudget: 100 }));
+    sup.start();
+    sup.tokensUsed = 100;
+    sup.promotionsPaused = true;
+
+    sup.reloadConfig({ tokenBudget: 200 });
+    assert.strictEqual(sup.promotionsPaused, false);
+
+    sup.stop();
+  });
+
+  test('status returns complete swarm info', () => {
+    const sup = new Supervisor(makeConfig({ count: 3 }));
+    sup.start();
+
+    const status = sup.status();
+    assert.strictEqual(status.running, true);
+    assert.ok(status.uptime >= 0);
+    assert.strictEqual(status.total, 3);
+    assert.strictEqual(status.active, 0);
+    assert.strictEqual(status.idle, 3);
+    assert.strictEqual(status.agents.length, 3);
+    assert.ok(status.agents[0].agentId);
+    assert.ok(status.agents[0].name);
+    assert.strictEqual(status.agents[0].state, DaemonState.IDLE);
+
+    sup.stop();
+  });
+
+  test('supervisor never executes agent work', () => {
+    const sup = new Supervisor(makeConfig());
+    // Verify no execute/run/build methods exist on supervisor
+    assert.strictEqual(typeof sup.execute, 'undefined');
+    assert.strictEqual(typeof sup.run, 'undefined');
+    assert.strictEqual(typeof sup.build, 'undefined');
+    // It only manages — start, stop, scale, status
+    assert.strictEqual(typeof sup.start, 'function');
+    assert.strictEqual(typeof sup.stop, 'function');
+    assert.strictEqual(typeof sup.scale, 'function');
+    assert.strictEqual(typeof sup.status, 'function');
+  });
+});

package/owl/behaviors/promotion.md

@@ -0,0 +1,30 @@
+# promotion
+
+how a daemon transitions from idle listener to active agent executing a task.
+
+## flow
+
+1. daemon sees a task announcement or ASSIGN message on the work channel
+2. daemon evaluates role match: does the task match its assigned role?
+3. if match: daemon sends CLAIM <component> to the work channel
+4. coordinator responds with ASSIGN <component> <agent-id> or REJECTED
+5. if REJECTED: daemon returns to idle
+6. if ASSIGNED: daemon sends PROMOTE-REQUEST to supervisor (via IPC)
+7. supervisor checks: active count < max-active AND token budget remaining
+8. if denied: daemon sends UNCLAIM <component> to work channel, returns to idle
+9. if approved: supervisor marks daemon as "promoting"
+10. daemon writes task context to <workspace>/context.md
+11. daemon spawns: claude -p "<task prompt with spec context>" --cwd <workspace>
+12. supervisor marks daemon as "active", starts tracking the claude PID
+13. daemon monitors the claude process stdout/stderr
+14. daemon forwards relevant output as status messages to work channel
+
+## demotion
+
+1. claude process exits (success or failure)
+2. daemon captures exit code and final output
+3. daemon sends DONE or FAIL to work channel
+4. daemon saves summary to <workspace>/context.md
+5. daemon sends DEMOTE notification to supervisor (via IPC)
+6. supervisor marks daemon as "idle", decrements active count
+7. daemon resumes listening on work channel

package/owl/behaviors/recovery.md

@@ -0,0 +1,58 @@
+# recovery
+
+how the swarm handles things going wrong. each failure mode has a distinct recovery strategy.
+
+## ws disconnect
+
+1. daemon detects websocket close or error event
+2. daemon attempts reconnect with backoff: 1s, 2s, 4s, 8s, max 30s
+3. on reconnect: daemon re-joins work channel, sends HEARTBEAT
+4. if reconnect fails after 5 attempts: daemon reports to supervisor via IPC
+5. supervisor may restart the daemon process entirely
+
+an active agent that loses WS connection continues working locally. it queues status messages and flushes them on reconnect.
+
+## agent crash
+
+1. supervisor detects child process exit via SIGCHLD
+2. supervisor checks exit code: 0 = clean exit, non-zero = crash
+3. on crash: supervisor increments restart-count for that agent
+4. supervisor applies exponential backoff: delay = min(2^restart-count seconds, 300s)
+5. after delay: supervisor invokes spawner to verify workspace integrity
+6. supervisor starts a new daemon process in the same workspace
+7. new daemon reads context.md to understand what it was doing
+8. if restart-count > 5 within 30 minutes: supervisor marks agent as "degraded" and stops retrying
+
+## quota exhaustion
+
+1. claude -p exits with a quota-exceeded error (detected via exit code or stderr)
+2. daemon reports QUOTA-EXHAUSTED to supervisor
+3. supervisor pauses ALL promotions across the swarm
+4. supervisor logs alert and waits for quota reset
+5. supervisor periodically tests quota availability (one small probe every 5 minutes)
+6. on quota restoration: supervisor resumes promotions, requeues the failed task
+
+## context overflow
+
+1. claude session runs out of context window and exits
+2. daemon detects context-overflow in stderr
+3. daemon saves partial work to context.md
+4. daemon reports FAIL <task> context-overflow to work channel
+5. coordinator may break the task into smaller subtasks and re-assign
+6. if task cannot be broken down: escalate to human
+
+## tool loop
+
+1. supervisor detects that an active agent has been running for longer than max-task-duration (configurable, default 30m)
+2. supervisor sends SIGTERM to the claude process
+3. daemon captures partial output, saves to context.md
+4. daemon reports FAIL <task> timeout to work channel
+5. coordinator decides whether to retry with a more focused prompt or escalate
+
+## sandbox denial
+
+1. claude session fails because a required tool was denied by the sandbox
+2. daemon detects permission-denied pattern in stderr
+3. daemon reports BLOCKED <task> sandbox-denied to work channel
+4. coordinator may reassign to an agent with broader permissions
+5. if no agent has the required permissions: escalate to human

package/owl/behaviors/scaling.md

@@ -0,0 +1,39 @@
+# scaling
+
+how to add or remove agents from a running swarm without disrupting active work.
+
+## scale up
+
+1. user runs: agentctl swarm scale 20 (current count is 10)
+2. supervisor calculates delta: 20 - 10 = 10 new agents needed
+3. supervisor invokes spawner to create 10 new workspaces and identities
+4. supervisor starts 10 new daemon processes
+5. new daemons connect to agentchat and begin sending HEARTBEAT
+6. supervisor updates process table with new entries
+7. supervisor logs: "scaled up: 10 -> 20 daemons"
+
+## scale down
+
+1. user runs: agentctl swarm scale 5 (current count is 20)
+2. supervisor calculates delta: 20 - 5 = 15 agents to remove
+3. supervisor selects agents to remove: idle daemons first, then longest-idle
+4. active agents are NEVER selected for removal — they finish their current task
+5. supervisor sends SIGTERM to selected daemons
+6. daemons disconnect from agentchat and exit cleanly
+7. if persist: false, spawner tears down removed workspaces
+8. supervisor updates process table
+9. supervisor logs: "scaled down: 20 -> 5 daemons (15 removed, 0 active preserved)"
+
+## scale to zero
+
+1. user runs: agentctl swarm scale 0
+2. equivalent to agentctl swarm stop — full shutdown flow applies
+3. active agents are given 10s to save context before SIGKILL
+
+## live reconfig
+
+1. user modifies swarm.yaml and sends SIGHUP to supervisor
+2. supervisor reloads config
+3. changes to max-active, token-budget, and heartbeat-interval take effect immediately
+4. changes to workspace-base or identity-template only affect newly spawned agents
+5. supervisor logs: "config reloaded: max-active 5->10, budget 100k->200k"

package/owl/behaviors/swarm-lifecycle.md

@@ -0,0 +1,38 @@
+# swarm-lifecycle
+
+the full sequence from starting a swarm to shutting it down.
+
+## startup flow
+
+1. user runs: agentctl swarm start --count 10 --config swarm.yaml
+2. supervisor reads and validates config
+3. supervisor acquires pidfile lock (fails if another swarm is running)
+4. supervisor invokes spawner to create N workspaces and identities
+5. supervisor starts N daemon processes, one per workspace
+6. each daemon connects to agentchat and joins the work channel
+7. each daemon sends its first HEARTBEAT
+8. supervisor logs: "swarm started: N daemons, 0 active"
+
+## steady state
+
+1. daemons idle, sending HEARTBEAT every 30s
+2. health-monitor tracks heartbeats and resource usage
+3. when a task appears on the work channel, eligible daemons send CLAIM
+4. coordinator ACKs one daemon — daemon requests promotion from supervisor
+5. supervisor approves promotion if budget and active-limit allow
+6. daemon spawns claude -p session, transitions to active
+7. active agent works until task completes or fails
+8. agent reports DONE or FAIL, supervisor demotes back to daemon
+9. daemon saves context.md and returns to idle
+
+## shutdown flow
+
+1. user runs: agentctl swarm stop (or supervisor receives SIGTERM)
+2. supervisor sends SIGTERM to all child processes
+3. active agents save context.md and exit
+4. daemons disconnect from agentchat and exit
+5. supervisor waits up to 10s for clean exits
+6. supervisor sends SIGKILL to any remaining children
+7. supervisor removes pidfile
+8. if config has persist: false, spawner tears down all workspaces
+9. supervisor logs: "swarm stopped: N agents shutdown"

package/owl/components/daemon.md

@@ -0,0 +1,46 @@
+# daemon
+
+a lightweight idle process that listens for tasks on agentchat and promotes to a full agent session when work is available. there is one daemon per swarm slot.
+
+## state
+
+- agent identity (agentchat id + name)
+- workspace path
+- assigned role (builder, auditor, qa, or general)
+- status: idle, promoting, active, demoting, crashed
+- agentchat connection (websocket)
+- current task (null when idle)
+
+## capabilities
+
+- connect to agentchat server and join the work channel
+- listen for task announcements and ASSIGN messages
+- evaluate whether a task matches its role
+- request promotion from supervisor when a matching task is found
+- on promotion: spawn a claude -p session with the task prompt and workspace context
+- forward agent output to agentchat as status messages
+- detect when the claude session exits (success or failure)
+- report task completion or failure to the work channel
+- return to idle state after task completion (demotion)
+- save minimal context to <workspace>/context.md on demotion for potential resume
+
+## interfaces
+
+exposes:
+- CLAIM <component> - sent to work channel when daemon wants a task
+- HEARTBEAT <agent-id> <status> - periodic health signal to supervisor
+- DONE <task-id> <result> - task completed successfully
+- FAIL <task-id> <reason> - task failed
+
+depends on:
+- supervisor for lifecycle management (start, stop, promote, demote)
+- agentchat server for communication
+- claude CLI for active work sessions
+- spawner-provisioned workspace and identity
+
+## invariants
+
+- an idle daemon sends only HEARTBEAT messages — no other agentchat traffic
+- a daemon never starts a claude session without supervisor approval (promotion)
+- workspace files are only modified during active (promoted) state
+- context.md is written on every demotion for crash recovery

package/owl/components/health-monitor.md

@@ -0,0 +1,37 @@
+# health-monitor
+
+tracks agent health via heartbeats and resource usage. reports problems to the supervisor for action.
+
+## state
+
+- heartbeat table: map of agent-id to {last-seen, status, consecutive-misses}
+- resource table: map of agent-id to {memory-mb, cpu-percent, uptime-seconds}
+- alert thresholds (from config)
+
+## capabilities
+
+- receive HEARTBEAT messages from daemons (via agentchat or IPC)
+- track time since last heartbeat per agent
+- detect missed heartbeats (configurable threshold, default 3 consecutive misses at 30s interval = 90s timeout)
+- query process stats (memory, cpu) for each agent PID
+- report unresponsive agents to supervisor for restart
+- report resource limit violations to supervisor for throttling or kill
+- log health events to ~/.agentctl/logs/health.log
+
+## interfaces
+
+exposes:
+- health-status(agent-id) -> {alive, last-seen, memory-mb, cpu-pct}
+- health-summary() -> status of all agents
+- ALERT <agent-id> <reason> - sent to supervisor when intervention needed
+
+depends on:
+- daemon HEARTBEAT messages
+- OS process stats (/proc or ps on darwin)
+- supervisor for acting on alerts
+
+## invariants
+
+- health-monitor never kills processes directly — it only reports to supervisor
+- an agent is declared dead only after consecutive-misses exceeds threshold (no single-miss kills)
+- health checks do not interfere with agent work (read-only process inspection)

package/owl/components/spawner.md

@@ -0,0 +1,38 @@
+# spawner
+
+creates isolated workspaces and agent identities for new swarm members. invoked by the supervisor at startup and when scaling up.
+
+## state
+
+- base workspace path (configurable, default ~/dev/claude/)
+- identity template (role-based prompts and CLAUDE.md files)
+- list of created workspaces (for cleanup on shutdown)
+
+## capabilities
+
+- create a workspace directory: ~/dev/claude/<agent-name>/
+- clone the target repo into the workspace (if specified in config)
+- create a feature branch: swarm/<agent-name>/<task-id>
+- generate an agentchat identity and write it to <workspace>/.agentchat/identities/<name>.json
+- write a CLAUDE.md file with the agent's role, constraints, and channel assignments
+- write a context.md file with initial state (empty or from previous session)
+- set up .gitignore with security entries (*.key, *.pem, .env, etc.)
+- clean up workspace on agent removal (rm -rf after confirmation)
+
+## interfaces
+
+exposes:
+- spawn(config) -> {workspace, identity, pid-placeholder}
+- teardown(agent-id) -> removes workspace and identity
+
+depends on:
+- git for repo cloning and branch creation
+- filesystem for workspace creation
+- agentchat identity format (Ed25519 keypair)
+
+## invariants
+
+- each workspace is a complete, independent directory — no shared state between agents
+- spawner never starts an agent process — it only prepares the environment
+- teardown requires explicit confirmation (no silent deletion)
+- .gitignore is always written before any other files

package/owl/components/supervisor.md

@@ -0,0 +1,47 @@
+# supervisor
+
+the top-level process that manages the swarm. there is one supervisor per machine.
+
+## state
+
+- swarm config (parsed from swarm.yaml)
+- process table: map of agent-id to {pid, status, role, workspace, restart-count, last-heartbeat}
+- promotion queue: ordered list of daemons waiting for an active slot
+- token budget: remaining tokens across the swarm
+- pidfile lock at ~/.agentctl/swarm.pid
+
+## capabilities
+
+- parse swarm config and validate settings
+- invoke spawner to create N agent workspaces and identities
+- start daemon processes and track their PIDs
+- promote daemons to active agents when tasks are available and budget allows
+- demote active agents back to daemon state when idle too long
+- restart crashed agents with exponential backoff (1s, 2s, 4s, 8s... max 5m)
+- enforce max concurrent active agent limit
+- pause all promotions when token budget threshold reached
+- graceful shutdown: send SIGTERM to all children, wait 10s, SIGKILL survivors
+- respond to SIGHUP by reloading config without restarting agents
+- write structured logs to ~/.agentctl/logs/supervisor.log
+
+## interfaces
+
+exposes:
+- CLI: agentctl swarm start [--count N] [--config path]
+- CLI: agentctl swarm stop
+- CLI: agentctl swarm status
+- CLI: agentctl swarm scale <N>
+- CLI: agentctl swarm logs [agent-id]
+
+depends on:
+- spawner for workspace/identity creation
+- health-monitor for heartbeat tracking
+- agentchat server for agent communication
+- claude CLI (claude -p) for running agent sessions
+
+## invariants
+
+- exactly one supervisor runs per machine (pidfile enforced)
+- supervisor never executes agent work — it only manages processes
+- all child processes die when supervisor dies (process group)
+- restart backoff resets after 5 minutes of stable uptime