This is not an AI orchestrator, and not autonomous execution. It starts, observes, and stops Claude CLI processes on the server. The CEO can start a session from a phone, lock it, walk away, and the process keeps running on HQ01; later they return to read the logs and status.

Design

Files are the source of truth. No database. Each session is a directory under /srv/aaf/runtime/claude/sessions/<id>/.
Additive. Nothing in HQ01 V1 is changed; this is a new department surface bolted onto the existing operating system.
HQ01 never blocks. Starting a session spawns a detached process and returns immediately. The process outlives the HTTP request and the Next.js worker that handled it.
No websockets. The dashboard and detail pages refresh on a short interval; the log viewer polls a tail endpoint.

Runtime layout

/srv/aaf/runtime/claude/sessions/<id>/
  session.json    live, mutable state (status, pid, timestamps, last_activity)
  metadata.json   immutable creation record (intent + provenance)
  stdout.log      captured standard output (shown in the log viewer)
  stderr.log      captured standard error

session.json is reconciled against reality on every read: if it claims a PID that is no longer alive, the status is downgraded to exited and persisted.

Modules

Path	Responsibility
`lib/process/spawn.ts`	Detached process spawn with stdout/stderr capture.
`lib/process/signal.ts`	PID liveness (`isAlive`) and graceful `terminate`.
`lib/sessions/config.ts`	Runtime root and defaults (env-overridable).
`lib/sessions/types.ts`	`Session`, `SessionMetadata`, `StartSessionInput`.
`lib/sessions/store.ts`	Atomic JSON read/write, listing, log tailing.
`lib/sessions/manager.ts`	start / stop / list / get / logs orchestration.
`lib/sessions/presets.ts`	Quick-start presets (e.g. Agent Z).

HTTP API

Method & path	Action
`GET /api/sessions`	List all sessions.
`POST /api/sessions`	Start a session; returns immediately.
`GET /api/sessions/:id`	Session record + metadata.
`POST /api/sessions/:id/stop`	Gracefully stop the process.
`GET /api/sessions/:id/logs`	Tail of stdout/stderr (`?bytes=N`).

Start payload

{
  "name": "Agent Z",
  "executive": "agent-z",
  "working_directory": "/srv/aaf/repositories/aaf-holdings",
  "branch": "mission/MS-0001",   // optional
  "mission_id": "MS-0001",        // optional
  "assignment_id": null,          // optional
  "prompt": "…",                  // optional → claude --print <prompt>
  "command": "claude",            // optional override
  "args": ["…"]                   // optional full override
}

By default a session runs claude --print --verbose <prompt>: print mode streams output to the logs and never needs a TTY. Provide command/args to run the manager against any other executable.

Configuration

Env var	Default	Purpose
`HQ01_SESSIONS_ROOT`	`/srv/aaf/runtime/claude/sessions`	Runtime root.
`HQ01_CLAUDE_BIN`	`claude`	Executable launched for new sessions.

UI

/sessions — dashboard of session cards (status, runtime, repo, branch) with Start (incl. presets) and Stop.
/sessions/:id — detail: live logs, assigned mission, command, PID, runtime, working directory, branch, status.

root · /srv/aaf