ai-agentmanager 0.0.0-stage → 1.0.0

package/SECURITY.md

@@ -0,0 +1,44 @@
+# Security
+
+## Reporting a vulnerability
+
+Please report security issues privately through GitHub: **Security → Report a vulnerability** on this repository. Don't open a public issue. You'll get a reply within a few days, and a fix or a plan before anything is disclosed.
+
+## What Agent Manager is, from a security point of view
+
+Agent Manager runs coding agents (Claude Code, Codex, Antigravity) **as your user, on your machine**, in real terminals. Anyone who can drive Agent Manager can run commands as you. The design goal is that only you can drive it, from this machine, unless you deliberately open it up.
+
+### Trust boundaries
+
+| Part | Who can reach it by default | How it is protected |
+| --- | --- | --- |
+| Daemon and web UI (`127.0.0.1:4717`) | Processes on this machine | Listens on loopback only. The `Host` header must be loopback (blocks DNS rebinding), a browser `Origin` must be the UI itself (blocks cross-site requests and WebSockets), and every write needs the `x-agentmgr` header, which a web page on another site can't send without a CORS preflight that is never granted. |
+| Remote access (`https://<ip>:4718`) | Nobody: **off until you run `agentmgr remote on`** | HTTPS with a certificate made on this machine. Every API call needs a signed-in device session (sign-in with the access token or its QR code; sessions last 30 days, can be revoked one by one, and rotating the token signs everyone out). Only this machine's own addresses are accepted as `Host`. Turning remote access on or off, the token, devices and shutdown are local-only. |
+| Hub (`agentmgr hub serve`, port 4720) | This machine and its Tailscale address | One admin token (or Google sign-in limited to listed emails); browsers get a 30-day session cookie. Plain `http://` is accepted only on loopback or Tailscale, which encrypts traffic; anything else must be `https://`. |
+| A machine joined to a hub | The hub, over a connection the machine opens | Ed25519 key per machine (private key in `~/.agentmanager/hub-link.json`, mode 600); each connection signs a fresh challenge. The machine decides what the hub may do (`hub.allow`, default `view` only), checks every request itself, matches agents by exact ID, runs only a fixed list of actions (never deletes) and logs each request and refusal to `~/.agentmanager/hub-audit.log`. |
+| Site relays (browser tabs from another device) | Signed-in remote devices | Never relay to Agent Manager's own ports; its sign-in cookie is stripped before forwarding; sites other than localhost must present a valid certificate; relays close when remote access is turned off. |
+| CLI sign-in callbacks | The UI | Delivered only to the loopback port the sign-in link itself named. |
+
+### What is stored, and where
+
+Everything lives in `~/.agentmanager/` (or `$AGENTMGR_HOME`):
+
+- `remote/state.json`: remote access token and device sessions (mode 600).
+- `hub-link.json`: this machine's hub key (mode 600). `hub/state.json` on the hub: its token and joined machines' public keys (mode 600).
+- `notify.json`: the Slack webhook or bot token, if you set one (mode 600).
+- `config.json`: your settings. Keep the whole folder private to your user.
+- `browser-profile/`: the live browser's Chrome profile. Sites you sign in to there stay signed in, as in any browser.
+- `scrollback/`, `briefs/`, `state.json`: terminal output and agent state. These can contain anything an agent printed, including secrets it read.
+
+Agent Manager sends **no telemetry**. It talks to the network only for what you set up: git remotes, GitHub (`gh`), Slack, a hub you joined, and the agents' own model providers.
+
+### Things to be aware of
+
+- **Agents act as you.** Each agent's permission mode (for Claude: `default`, `acceptEdits`, `plan`, `auto`, `bypassPermissions`) is passed to the engine; Agent Manager doesn't sandbox agents beyond that. Run agents in folders and with modes you'd be comfortable running the engine in by hand.
+- **Other processes running as your user** can call the local API, just as they could run `claude` themselves. Agent Manager doesn't defend against malware already running as you.
+- **The AI judge** sends short summaries of an agent's screen, activity and brief to the same engine the agents use (by default Claude `haiku`), as separate calls. Turn it off with `agentmgr judge off`.
+- **Remote access on an untrusted network** (café Wi-Fi) exposes the sign-in page on your local network. Leave it off there, or use Tailscale and the hub instead.
+
+## Supported versions
+
+Security fixes go into the latest release.

package/bin/agentmgr-hub.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// The hub on its own, for hosts without the rest of Agent Manager (Railway, a container).
+// Locally, "agentmgr hub serve" does the same.
+import { startHub } from '../src/hub.js';
+
+const port = Number(process.env.PORT || 4720);
+const host = process.env.HOST || (process.env.PORT ? '0.0.0.0' : '127.0.0.1');
+const hub = await startHub({ port, host });
+console.log(`[hub] listening on ${hub.url}`);
+if (hub.createdToken) console.log('[hub] generated an access token; set AGENTMGR_HUB_TOKEN instead to choose your own');
+for (const sig of ['SIGINT', 'SIGTERM']) {
+  process.on(sig, async () => {
+    await hub.close();
+    process.exit(0);
+  });
+}

package/bin/agentmgr.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv);

package/docs/architecture.md

@@ -0,0 +1,67 @@
+# Architecture
+
+Agent Manager is one long-running **daemon** per machine. It owns every agent's terminal and state. The **web UI** and the **CLI** are clients of its HTTP and WebSocket API. Optionally, daemons on several machines connect out to a **hub**.
+
+```
+ browser (UI) ──┐                       ┌── claude / codex / agy in PTYs (one per agent, plus shells)
+ phone (HTTPS) ─┼── daemon (server.js) ─┼── git worktrees under ~/.agentmanager
+ agentmgr CLI ──┘        │  manager.js  └── headless Chrome (live browser tabs)
+                         │
+                         └── hub link (outbound WebSocket) ──► hub (hub.js) ◄── other machines
+```
+
+No build step: Node ES modules on the server, plain ES modules in the browser. State is JSON files in `~/.agentmanager` (or `$AGENTMGR_HOME`).
+
+## The daemon
+
+| File | Role |
+| --- | --- |
+| `src/server.js` | Express API and WebSockets on `127.0.0.1:4717`, the optional HTTPS remote listener, and the request checks described in [SECURITY.md](../SECURITY.md). Thin: routes call the manager. |
+| `src/manager.js` | The core. Creates agents (clone or worktree, branch, launch), runs their PTYs (`node-pty`), keeps scrollback, resumes sessions after restarts, and runs a periodic tick that refreshes git, PRs, transcripts, stuck and conflict checks, inbox items and the judge. Emits events the server pushes to clients. |
+| `src/store.js` | `state.json`: agent records, saved atomically and versioned (`STATE_VERSION`, migrations, backups). |
+| `src/config.js` | Paths, defaults and `config.json`. |
+| `src/engines/` | One adapter per agent CLI (Claude Code, Codex, Antigravity): launch and resume arguments, permission modes, where transcripts live and how to read them. See [engines.md](engines.md). |
+| `src/git.js` | Clones (partial), worktrees, branches, diffs, PR lookup through `gh`. |
+| `src/tracker.js` | Reads transcripts: tokens, cost, PR and bug references, activity. |
+| `src/brief.js` | Each agent's living brief (`BRIEF.md` outside the repo), results, explain, insights and review documents. |
+| `src/inbox.js`, `src/stuck.js`, `src/conflicts.js` | The decision inbox (prompts and questions), stuck detection and the conflict radar: the rules that decide *when* to look. |
+| `src/judge.js` | The AI judge: one-shot, tool-less model calls that decide *what is going on* (stuck, waiting, done, collisions, backlog order, alert triage), with a daily cap and feedback examples. Falls back to the rules. |
+| `src/backlog.js`, `src/races.js` | Work orders picked up per project; several agents on one intent, compared. |
+| `src/notify.js` | Slack alerts, triaged by the judge. |
+| `src/preview.js`, `src/livebrowser.js` | Browser tabs: HTTPS relays for remote devices, and a headless Chrome streamed over the Chrome DevTools Protocol (frames, input, sound). |
+| `src/sessions.js` | Finds Claude Code sessions started in a terminal so they can be continued as agents. |
+| `src/remote.js` | Remote access: certificate, token, device sessions. |
+| `src/service.js` | Start at login (launchd or systemd). |
+| `src/trust.js` | Pre-accepts Claude Code's folder trust prompt for agent folders. |
+| `src/plugins.js` | Plugins from a separate package: policies before actions, listeners after, extra routes, engines and hub sign-in. See [plugins.md](plugins.md). |
+
+## The clients
+
+| File | Role |
+| --- | --- |
+| `public/index.html`, `public/app.js`, `public/style.css` | The web UI: agents tree, inbox, backlog, terminals (xterm.js), briefs, browser tabs. |
+| `public/transport.js` | WebSockets locally; over remote HTTPS, server-sent events plus POSTs (works through more networks). |
+| `src/cli.js`, `src/client.js` | The `agentmgr` command: starts the daemon when needed and calls the same API. `attach` pipes your terminal to an agent's PTY. |
+
+## Several machines
+
+| File | Role |
+| --- | --- |
+| `src/hub.js`, `bin/agentmgr-hub.js` | The hub: sign-in, enrolled machines, the fleet view, the shared backlog, terminals relayed from machines. Runs alone in a container (`hub/Dockerfile`). |
+| `src/hublink.js` | A daemon's outbound link to its hub: signed challenge per connection, policy checks on every request, audit log. |
+| `src/hubactions.js` | The fixed list of actions a hub may ask for, and the permission each needs. |
+| `src/fleet.js` | The whitelisted view of agents a machine shares. |
+| `src/hubbacklog.js` | Placing shared backlog items on machines with room. |
+
+Design notes: [distributed.md](distributed.md) (hub) and [engines.md](engines.md) (engines).
+
+## Lifecycle of an agent
+
+1. **Create** (`POST /api/agents`): the manager makes a record, prepares the workspace (clone or worktree and branch, or a folder), and pre-trusts the folder.
+2. **Launch**: the engine adapter builds the command with a session ID chosen up front; the PTY starts in the workspace. Instructions about the brief and questions are passed with the first prompt.
+3. **Track**: the tick reads git, the transcript and the screen; the brief, inbox, stuck, conflicts and the judge update the record; clients get events.
+4. **Close and resume**: closing keeps the session ID; starting again resumes it. On daemon shutdown, scrollback and state are flushed, and running agents come back on the next start.
+
+## Tests
+
+`test/e2e.test.js` starts a real daemon on a temporary home and port, with fake engines that print what the real CLIs print. `test/unit.test.js` covers parsers and pure functions. CI runs both on macOS and Linux, Node 20 and 22.

package/docs/distributed.md

@@ -0,0 +1,147 @@
+# Distributed agent management: design
+
+Status: phases 1–3 built (0.3, branch `v0.3-fleet`) · Phases 4–5: planned
+
+## Problem
+
+Agent Manager runs every agent on the machine its daemon runs on. Once you have agents on more than one machine (a Mac mini that is always on, a laptop, a cloud VM with more cores, a teammate's box), you get one UI per machine, one inbox per machine, and a backlog that can't use spare capacity elsewhere. Overlaps between agents on different machines go unnoticed until merge time.
+
+## Goals
+
+- **One place to see and run everything:** all machines' agents, inbox and backlog in one UI and one CLI.
+- **Use capacity wherever it is:** backlog items go to the machine with room, the repo already cached, and the right labels (OS, GPU, network access).
+- **Keep machines independent:** a machine that loses the hub keeps running its agents and its local UI. No agent state is ever held only by the hub.
+- **Nothing new to open on home networks:** machines connect out; no port forwarding.
+- **At least as safe as today:** a live terminal is remote code execution, so every machine decides what the hub may do there.
+
+## Non-goals (for now)
+
+- Moving a running agent between machines. A fork across machines is in scope for a later phase; a live migration isn't.
+- Several people sharing one hub. The design leaves room for it, but 0.3 is single-user.
+- A multi-user hosted service. The hub will move to Railway, but as a single-user hub with one access token.
+
+## Options considered
+
+| | A. Federation | B. Hub and runners (recommended) | C. Hosted control plane |
+| --- | --- | --- | --- |
+| Shape | Each UI connects to every daemon directly | Daemons connect out to one hub; the UI talks to the hub | Daemons connect to a service on the internet (e.g. Railway) |
+| Reachability | Every machine must be reachable from every client | Only the hub must be reachable, and only by the runners and you | Works anywhere |
+| Shared backlog and scheduling | Hard: no one place decides | Natural: the hub schedules | Natural |
+| Cross-machine inbox and conflicts | Merged in the browser | Computed at the hub | Computed centrally |
+| Blast radius if compromised | One machine | The hub can reach every runner, limited by each runner's policy | An internet-facing service can reach every runner |
+| Effort | Low | Medium | High (accounts, SSO, hardening, hosting) |
+
+A is a fine stopgap but can't schedule. C is where a team product ends up, but it puts terminals behind an internet service before the trust model is proven. **B** gives one UI and real scheduling, works through NAT, and can later move the hub onto the internet without changing the runners.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph You
+    UI[Browser / phone UI]
+    CLI[agentmgr CLI]
+  end
+  subgraph Hub["Hub: a daemon in hub mode"]
+    API[Fleet API + UI]
+    SCHED[Backlog scheduler]
+    VIEW[Fleet view: agents, inbox, conflicts]
+  end
+  subgraph M1["Runner: Mac mini"]
+    D1[agentmgr daemon] --> A1[agents in PTYs]
+  end
+  subgraph M2["Runner: laptop"]
+    D2[agentmgr daemon] --> A2[agents in PTYs]
+  end
+  subgraph M3["Runner: cloud VM"]
+    D3[agentmgr daemon] --> A3[agents in PTYs]
+  end
+  UI --> API
+  CLI --> API
+  D1 -- "wss, outbound" --> Hub
+  D2 -- "wss, outbound" --> Hub
+  D3 -- "wss, outbound" --> Hub
+```
+
+- **Runner:** today's daemon plus a small hub client. It stays the source of truth for its agents: `state.json`, sessions, worktrees and checkpoints stay where they are, and its local UI keeps working.
+- **Hub:** a daemon started with `agentmgr hub`. It can also run agents itself, as its own runner. It holds a cache of what runners report, plus fleet-wide things: the shared backlog and its assignments, enrolled runners, and the conflict view across machines.
+- **One connection per runner:** a single WebSocket from runner to hub carries everything, multiplexed.
+
+### What flows over the connection
+
+| Frame | Direction | Purpose |
+| --- | --- | --- |
+| `challenge` | hub → runner | A fresh nonce the runner signs |
+| `hello` | runner → hub | Runner ID, signature, version, platform, policy, UI addresses (later: labels, capacity, cached repos) |
+| `welcome` | hub → runner | Accepted; the runner sends its state |
+| `state` | runner → hub | The whole fleet view: whitelisted agent fields and inbox items (see `src/fleet.js`), plus, when the runner allows `create`, its projects (with a cross-machine `ref` and whether each is cloned), capacity and labels. Sent at most every 2 s and only when it changed; small enough that deltas aren't worth it yet. Later: change sets for the conflict radar |
+| `leave` | runner → hub | The runner is leaving; the hub forgets it |
+| `rpc` / `rpc-result` | hub → runner → hub | One of a fixed list of actions (`src/hubactions.js`), checked against the runner's policy and audited there; 20 s timeout |
+| `term-open` / `term-in` / `term-resize` / `term-close` | hub → runner | A browser's terminal on channel N |
+| `term-hello` / `term-out` / `term-msg` / `term-error` / `term-end` | runner → hub | Its screen: the last 256 KB of history, then live output batched every 30 ms. A lagging channel drops output, then restarts from a fresh screen |
+| `ping` / `pong` | runner → hub → runner | Liveness every 15 s; a runner is dropped after 45 s without one |
+
+Agent IDs become `runner/agent` (for example `mini/f532b9`) in the hub's UI and CLI. The bare ID still works when it's unique.
+
+### Scheduling the shared backlog
+
+The hub's backlog works like today's, with one extra step: pick a runner. In order:
+
+1. **Hard constraints:** the item's required labels (for example `os:linux`, `gpu`), the runner's policy allows creating agents, and the runner is online.
+2. **Capacity:** the runner's parallel limit per project and in total, as today.
+3. **Warm start:** prefer a runner that already has the repo cloned. A big repo clone can take many minutes; this matters more than load.
+4. **Spread:** otherwise, the runner with the fewest active agents.
+
+Built in `src/hubbacklog.js`. Projects match across runners by `ref`: the repo (`repo:github.com/org/app`) or, without a remote, the name (`name:site`), so local paths never leave a runner. Capacity is the runner's own `hub.maxAgents` and `hub.perProject`, counting hub items it holds plus active items from its local backlog. "Done" is a brief marked done after the brief time the hub last saw, not a timestamp comparison, so clock skew between machines doesn't matter.
+
+The hub sends `rpc create` to the chosen runner, which runs the agent through its normal path. If the runner drops before the item finishes, the item shows as *stalled on mini*. It is not silently re-run elsewhere, because work on that runner's worktree would be lost or duplicated. You decide: wait, or restart it on another runner.
+
+### Fleet-wide features
+
+- **Inbox:** the union of every runner's inbox items, each tagged with its machine. Answers go back as `rpc`.
+- **Conflict radar across machines:** runners send their change sets (files and line ranges, not file contents). The hub runs the same `findConflicts` across runners, keyed by normalized repo URL instead of the local clone path.
+- **Races across machines:** a race may place each attempt on a different runner, for example the same intent on macOS and Linux. Tests run on the attempt's own runner.
+- **Forks across machines (later):** packing the checkpoint as a `git bundle` with the transcript and unpacking it on the target runner. This is the only feature that moves code between machines, so it waits for the trust model to settle.
+
+## Security
+
+The hub can drive terminals on every runner, so a hub compromise must not mean "everything, everywhere".
+
+- **Enrollment:** `agentmgr hub invite` prints a one-time code that is valid for 10 minutes. `agentmgr join <hub-url> <code>` makes an Ed25519 key pair on the runner and sends the hub only the public key. From then on, the runner proves itself by signing a fresh challenge on each connection, and the hub can remove one runner without touching the others. A removed runner stops retrying until it joins again.
+- **The runner decides:** each runner has a local policy the hub can't change:
+
+  ```json
+  { "hub": { "allow": ["view", "inbox", "control", "terminal", "create"], "projects": ["*"] } }
+  ```
+
+  The default is `["view"]` only; `terminal`, `create` and the rest are opt-in per machine. `projects` takes project names or shortcuts. Every hub-initiated action is checked against this list on the runner and written to the runner's local audit log (`hub-audit.log`). Phase 1 runners refuse and log anything but the handshake.
+- **Transport:** `https://` (Railway's certificate, so no self-signed pinning), or plain `http://` only for localhost and Tailscale addresses (100.64.0.0/10, `*.ts.net`), where WireGuard already encrypts. Runners never accept inbound connections from the hub.
+- **You, at the hub:** one access token (`AGENTMGR_HUB_TOKEN` on Railway), a sign-in link, and 30-day HttpOnly, SameSite=Strict session cookies. Failed sign-ins and joins are rate limited. The CLI sends the token as a bearer header. Runner-supplied text is only ever rendered as text, under a strict Content-Security-Policy, so a compromised runner can't script the hub UI and reach the others. SSO is left for a multi-user hub.
+- **Data minimization:** the hub caches agent views and change sets (file names and line ranges). It doesn't store transcripts or code, and terminal data passes through without being kept.
+
+## Failure modes
+
+| Failure | What happens |
+| --- | --- |
+| Hub down | Runners keep running; each local UI still works. On reconnect, runners resend a snapshot. |
+| Runner offline | Its agents show as offline with when they were last seen. Its queued backlog items wait; active ones show as stalled. |
+| Network flap | The runner reconnects with backoff and resumes open terminals from their saved scrollback. |
+| Version skew | `hello` carries versions. The hub refuses calls a runner doesn't support and says so in the UI. |
+
+## Plan
+
+| Phase | Delivers | Size |
+| --- | --- | --- |
+| 1. Fleet view ✅ | `agentmgr hub serve`, `invite`, `join`, `leave`, `fleet`; the hub shows every runner's agents and inbox, read-only, with links to each runner's own UI; `hub/Dockerfile` for Railway | done |
+| 2. Control ✅ | Actions (inbox, control, create) and terminals through the hub; permissions `inbox`, `control`, `create`, `terminal`, `shell` checked on the runner; audit logs on both ends | done |
+| 3. Scheduling ✅ | Shared backlog with labels, warm-start placement, stalled-item handling (`agentmgr fleet backlog`, the hub's Backlog tab) | done |
+| 4. Cross-machine | Conflict radar and races across runners | ~1 week |
+| 5. Later | Forks across machines (git bundles), a hosted hub with SSO, several users | — |
+
+Phase 1 is useful on its own and low-risk, because the hub only reads.
+
+## Decisions (2026-10-18)
+
+1. **Where the hub runs:** eventually Railway. Phase 1 runs on a Mac on the tailnet, and the hub is already standalone (express and ws only, `hub/Dockerfile`) so it can move there. Being internet-facing shaped the security above: a token plus session sign-in, rate limits, CSP, and data minimization.
+2. **Which machines:** Macs only for now. No Linux labels or multi-user work yet.
+3. **Tailscale:** on every machine. Plain `http://` hub addresses are accepted over Tailscale, and **Open** links prefer each Mac's Tailscale address.
+4. **Default policy:** new runners start with `view` only.

package/docs/engines.md

@@ -0,0 +1,177 @@
+# Design: several agent engines (Claude Code, Codex CLI, Gemini CLI)
+
+Status: phase 1, Codex and Antigravity built. Gemini CLI dropped: since June 18, 2026 it no longer serves personal Google accounts, and Antigravity CLI (`agy`, `src/engines/antigravity.js`, checked against 1.4.3, fixtures in `test/fixtures/antigravity/`) replaced it. 0.4 (branch `v0.4-engines`) · 2026-10-18. Targets the current releases of each CLI, checked in phase 1.
+
+Agent Manager runs every agent with Claude Code. If Anthropic has an outage, a rate limit hits, or prices change, every agent stops at once. Running agents on other engines as well makes the fleet resilient across providers, and lets each task use the engine that suits it.
+
+## Goals
+
+- **Same workflow, any engine:** create, watch, answer, message, review and merge agents the same way whether they run Claude Code, OpenAI's Codex CLI or Google's Gemini CLI.
+- **Choose per agent:** a default engine, overridable per agent, per project and per backlog item.
+- **Fail over:** when an engine is down or rate-limited, new work goes to another engine instead of waiting.
+- **Honest UI:** features an engine can't support (for example a cost figure) are hidden for its agents, not faked.
+
+## Non-goals
+
+- **Moving a live conversation between engines.** Conversations stay with their engine. A task can continue on another engine through a handoff (below), which carries the work but not the chat history.
+- **Editor-based agents** (Antigravity, Cursor, and so on). Agent Manager drives command-line agents in a terminal.
+- **Running models directly through APIs.** Each engine keeps its own CLI, sign-in, tools and safety settings.
+
+## What is Claude-specific today
+
+| Area | Where | What it relies on |
+| --- | --- | --- |
+| Launch and resume | `manager.js` `start`, `baseArgs`, `spawnClaude` | `--session-id` (an ID we choose up front), `--resume`, `--name`, `--permission-mode`, `--model`, `--add-dir`, `--allowedTools`, `--append-system-prompt` |
+| Transcripts | `tracker.js`, `stuck.js` | `~/.claude/projects/<cwd>/<session>.jsonl`: tokens, cost, PR and bug links, activity, subagents |
+| Planning handoff | `manager.js` `moveTranscript` | Moving a transcript between folders so the same session continues in the repo |
+| Inbox prompts | `inbox.js` `promptChoices` | The layout of Claude Code's numbered choice prompts on screen |
+| Folder trust | `trust.js` | `~/.claude.json` `hasTrustDialogAccepted` |
+| Brief and questions | `brief.js`, `inbox.js` | Claude writing `BRIEF.md` / `QUESTIONS.md` in a folder outside the repo that it was allowed to write to |
+| Explain, insights, documents | `brief.js` prompts, run through `claude -p` | A tool-less one-shot call |
+| Config | `config.js` | `claudeBin`, `claudeArgs`, `permissionMode` |
+
+Everything else is engine-neutral: clones, worktrees and branches, the backlog, PR tracking, the conflict radar (git diffs), races, checkpoints (git; the transcript copy is engine-specific), terminals and the hub.
+
+## The engine adapter
+
+Each engine is one module in `src/engines/` that implements the same small interface. The manager calls the adapter instead of building Claude flags itself.
+
+```js
+export default {
+  id: 'codex',                       // 'claude' | 'codex' | 'gemini'
+  label: 'Codex',
+  bin: (config) => config.engines?.codex?.bin ?? 'codex',
+
+  // What the UI may offer for this engine's agents.
+  supports: { resume: true, chooseSessionId: false, cost: false, tokens: true, prompts: true,
+              planHandoff: false, fork: false, permissionModes: ['default', 'acceptEdits', 'plan'] },
+
+  /** Arguments for a new session, or for resuming one. */
+  launch({ agent, workdir, sessionId, resume, prompt, instructions, writableDirs }) { /* -> { args, env } */ },
+
+  /** After a new launch: find the session the engine created (for engines that pick their own IDs). */
+  discoverSession({ workdir, startedAt }) { /* -> sessionId | null */ },
+
+  /** Incremental scan of the session log: usage, links, activity events for stuck detection. */
+  scan({ workdir, sessionId, cursor }) { /* -> { cursor, usage, prs, bugs, events, lastActivityAt } */ },
+
+  /** A numbered choice prompt visible on screen, if any: [{ key, label }]. */
+  promptChoices(screenText) {},
+
+  /** Make the folder trusted for the engine, if it asks. */
+  trust(dir) {},
+
+  /** One-shot, tool-less call for Explain and documents. */
+  oneShot({ prompt, model }) { /* -> { args } */ },
+
+  /** Is the engine usable right now? Installed, signed in, not rate-limited. */
+  async health() {},
+};
+```
+
+`claude.js` is today's behaviour moved behind the interface, so nothing changes for existing agents. Each agent gets an `engine` field (default `claude`, so existing state needs no migration).
+
+## The engines
+
+Gemini CLI flags are checked against 0.64.0 (`test/fixtures/gemini/help-0.64.0.txt`) and Codex against codex-cli 0.163.0 (`test/fixtures/codex/`: help texts, a scrubbed session log, and recorded trust and approval screens). Both CLIs change quickly, so adapters check `--version` and the fixtures are refreshed on upgrades.
+
+| | Claude Code | Codex CLI | Gemini CLI |
+| --- | --- | --- | --- |
+| Start with a task | `claude --session-id <id> -- "<task>"` | `codex --no-alt-screen … "<task>"` | `gemini --session-id <uuid> -i "<task>"` (interactive after the first prompt) |
+| Resume | `--resume <id>` | `codex resume [options] <id>` | `--resume <id or index>` |
+| Session ID | Chosen by us | Picked by Codex; adopted from the new session log in the agent's folder (its first line, `session_meta`, records the folder and is often 20+ KB) | Chosen by us (`--session-id <uuid>`, 0.64) |
+| Session logs | `~/.claude/projects/…/*.jsonl` | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | `~/.gemini/tmp/<project hash>/chats/` |
+| Project instructions | `CLAUDE.md` | `AGENTS.md` | `GEMINI.md` |
+| Extra instructions per launch | `--append-system-prompt` | none: config override, or the first message | none: the first message (`GEMINI_SYSTEM_MD` replaces the whole system prompt, so it isn't used) |
+| Extra writable folder | `--add-dir` + `--allowedTools` | `--add-dir` (newer versions) or sandbox `writable_roots` | `--include-directories`, plus a `--policy` file allowing writes there |
+| Folder trust | `~/.claude.json` | `~/.codex/config.toml` trusted projects | `--skip-trust` (this session only) |
+| Model | `--model` | `-m` | `-m` |
+| Cost | Recorded by Claude Code | Tokens only (`token_count` events; cached input is counted inside input, so it is subtracted) | Tokens only |
+| Rate limits | — | In every `token_count` event (`rate_limits.primary.used_percent`, `rate_limit_reached_type`): the input for fail over | — |
+
+### Permission modes
+
+Agent Manager's three modes map to each engine's own approval settings. The hub's rule stays: no mode that skips all prompts can be started from the hub.
+
+| Agent Manager | Claude Code | Codex CLI | Gemini CLI |
+| --- | --- | --- | --- |
+| `default` (ask) | `default` | `--sandbox workspace-write --ask-for-approval on-request` (0.163 only has `on-request` and `never`) | `--approval-mode default` |
+| `acceptEdits` | `acceptEdits` | the same: edits inside the workspace never ask | `--approval-mode auto_edit` |
+| `plan` | `plan` | `--sandbox read-only --ask-for-approval on-request` | `--approval-mode plan` (read-only) |
+| skip all (local only) | `bypassPermissions` | `--dangerously-bypass-approvals-and-sandbox` | `--yolo` |
+
+### Briefs and questions
+
+The brief and questions files are what make an agent reviewable from the inbox, so every engine needs them.
+
+- **Instructions:** today they go in `--append-system-prompt`. Codex and Gemini have no per-launch system prompt flag, so the instructions go in the first message of a new session, and are repeated briefly on resume (in the resume message where the engine accepts one). Writing them into the repo's `AGENTS.md`/`GEMINI.md` is rejected: that would change the user's repo.
+- **Writing outside the repo:** Codex's sandbox only writes inside the workspace by default. Options, in order of preference:
+  1. Allow the brief folder as an extra writable root (`--add-dir` or `writable_roots`).
+  2. Have the agent write `.agentmgr/BRIEF.md` inside its worktree, add `.agentmgr/` to the worktree's local git excludes (`.git/info/exclude` of the worktree, never the repo's `.gitignore`), and have Agent Manager read it from there.
+- **Parsing** (`parseBrief`, `parseQuestions`) is already engine-neutral.
+
+### Usage, activity and stuck detection
+
+`scan()` turns each engine's log into the same events: usage totals, PR and bug links from tool output, and tool-call/result pairs for stuck detection (`stuck.js` takes events, not Claude records). Engines without a cost figure show tokens only. If an engine's log format can't be read, the agent still works, without usage and stuck findings, and the UI says so.
+
+### Inbox prompts
+
+`promptChoices` reads the terminal screen. Each adapter gets its own pattern, backed by recorded screen fixtures in the tests. Pressing a digit or Esc goes through the same `prompt-key` action, so the hub needs no change.
+
+### Explain and documents
+
+These one-shot calls default to the agent's own engine (`oneShot`), and fall back to any healthy engine, since they only need the transcript digest and brief.
+
+## Fail over across providers
+
+- **Engine health:** each daemon checks every configured engine: installed, signed in, and recent failures. A run of authentication errors, rate-limit messages or crashes on launch marks it *degraded* for a cool-down. The adapter supplies the patterns it recognizes.
+- **New work:** an item can ask for one engine, a preference list (`["claude", "codex"]`), or `any`. The local backlog and the hub's shared backlog skip degraded engines, and each machine reports its engines to the hub as labels (`engine:codex`), so placement works as it does for other labels.
+- **Running agents:** never moved automatically. When an agent's engine is degraded, the inbox shows **Continue on Codex** (or another engine), which performs a handoff:
+  1. Checkpoint the worktree (commit on the agent's branch, as checkpoints do today).
+  2. Start a new session of the other engine in the same worktree and branch.
+  3. Its first message says what the task is, points to the brief, the questions and the commit log, and asks it to continue from there.
+  The old session is kept, so the agent can switch back later.
+
+## Config
+
+```json
+{
+  "engine": "claude",
+  "engines": {
+    "claude": { "bin": "claude" },
+    "codex":  { "bin": "codex", "args": [] },
+    "gemini": { "bin": "gemini", "args": [] }
+  },
+  "projects": { "web": { "engine": "codex" } },
+  "failover": ["claude", "codex", "gemini"]
+}
+```
+
+`claudeBin` and `claudeArgs` keep working as aliases of `engines.claude`.
+
+## UI and CLI
+
+- **Engine picker** in New agent, Add to backlog and race variants; a small engine tag on each agent.
+- **Races across engines:** the same intent on Claude, Codex and Gemini, scored the same way. This comes almost for free and is a good way to compare engines on real work.
+- **CLI:** `agentmgr add --engine codex …`, `agentmgr engines` (installed, signed in, healthy), `agentmgr continue <agent> --engine gemini`.
+- **Hub:** `engine` joins the fleet whitelist; machines report their engines; the shared backlog takes an engine preference.
+
+## Testing
+
+The e2e suite uses a fake Claude (`test/fake-claude.js`). Each engine gets its own fake that writes sessions in that engine's log format and draws its prompts, so the adapters are tested without accounts. Phase 1 adds a manual check script that runs each real CLI once, records its flags, log format and prompt screens, and stores them as fixtures.
+
+## Plan
+
+| Phase | Delivers |
+| --- | --- |
+| 1. Adapter seam ✅ | `src/engines/claude.js` with today's behaviour behind the interface; `engine` on agents; real CLIs checked and recorded as fixtures |
+| 2. Antigravity CLI ✅ | Replaces Gemini CLI. `src/engines/antigravity.js`: launch with instructions in the first message, adoption of the conversation agy picks (`cache/last_conversations.json`), resume with `--conversation`, usage, commands and writes from `brain/<id>/.system_generated/logs/transcript_full.jsonl`, command / file / access menus, trust in `settings.json` `trustedWorkspaces`, Explain in print mode (`--mode plan`, prompt attached to `--print=`). Non-Claude engines get a shorter conventions note: a smaller model turned the Claude-specific one into a search of the whole disk. |
+| 3. Codex CLI ✅ | `src/engines/codex.js`: launch and resume, session adoption, brief folder (`--add-dir`), usage, stuck detection, prompts, trust, Explain through `codex exec`; engine pickers in the CLI, the page and the hub; machines report `engine:*` labels for the shared backlog. Not yet: planning while cloning and forks. Built before Gemini, which waits on a sign-in. |
+| 4. Fail over | Engine health, preference lists in both backlogs, engines reported to the hub, **Continue on…** handoff |
+
+## Open questions
+
+1. **Order:** Gemini first (you named it), then Codex?
+2. **Default engine** for new agents stays Claude, with others chosen per agent or project?
+3. **Fail over:** automatic for new work only, with running agents switched only when you click **Continue on…**?
+4. **Accounts:** Gemini CLI signed in with a Google account (free tier limits) or an API key / Vertex AI? Codex with a ChatGPT plan or an API key? This affects rate limits and the health checks.

package/docs/plugins.md

@@ -0,0 +1,81 @@
+# Plugins
+
+A plugin extends Agent Manager from a separate package, without changing its code: add policies that can refuse actions, listen to what happens (for an audit trail), serve extra API routes, add an agent engine, or (on the hub) add a sign-in method.
+
+## Loading
+
+**Daemon:** list modules in `~/.agentmanager/config.json`, or in `$AGENTMGR_PLUGINS` (comma separated):
+
+```json
+{ "plugins": ["@acme/agentmanager-policy", "./plugins/audit.js"] }
+```
+
+Package names are resolved from Agent Manager's install; paths are relative to `~/.agentmanager` (`~` works too).
+
+**Hub:** `AGENTMGR_HUB_PLUGINS=@acme/agentmanager-sso,./plugins/hub-audit.js` (paths relative to the hub's state folder).
+
+If a listed plugin fails to load, the daemon or hub doesn't start. A policy that is silently missing is worse than no start.
+
+## Writing one
+
+```js
+// audit-and-policy.js
+export const name = 'acme'; // routes are served under /api/ext/acme
+
+export default function register(api) {
+  // Refuse an action by returning { allow: false, reason }. Anything else allows it.
+  api.policy((action, details) => {
+    if (action === 'agent.create' && details.input.permissionMode === 'bypassPermissions') {
+      return { allow: false, reason: 'bypassPermissions is not allowed on company machines' };
+    }
+    if (action === 'agent.create' && details.input.repo && !details.input.repo.includes('github.com/acme/')) {
+      return { allow: false, reason: 'Only acme repositories' };
+    }
+  });
+
+  // Hear what happened. Listeners never block or break the action.
+  api.on((event, payload) => fs.appendFileSync('/var/log/agentmanager-audit.jsonl', JSON.stringify({ event, ...payload }) + '\n'));
+
+  // Extra endpoints, behind the same sign-in and request checks as the rest of the API.
+  api.routes((router) => router.get('/status', (req, res) => res.json({ ok: true })));
+}
+```
+
+The API object also has `api.name`, `api.config` (the daemon's config) and `api.log(message)`.
+
+Policies are synchronous so every code path can call them. Keep them fast; do slow lookups ahead of time (on load or on a timer) and check against the result.
+
+## Daemon actions (policies)
+
+| Action | When | `details` |
+| --- | --- | --- |
+| `agent.create` | Before an agent is created (UI, CLI, backlog, races, hub, imports) | `input`: kind, intent, name, repo, dir, worktree, base, permissionMode, model, project, priority, engine, imported |
+| `agent.start` | Before an agent's engine is launched or resumed (including after a restart) | `agent`, `fresh` |
+| `agent.message` | Before a message is typed into an agent (`tell`, inbox replies) | `agent`, `text`, `source` |
+| `agent.remove` | Before an agent is deleted | `agent`, `deleteWorkspace` |
+| `terminal.open` | Before a live terminal is attached (browser, CLI `attach`, hub) | `agent`, `kind` (`claude` or `shell:N`) |
+| `hub.action` | Before an action the hub asked for, after this machine's own `hub.allow` check | `action`, `agent` |
+
+`agent` is a summary: id, name, kind, engine, intent, repo, workdir, branch, permissionMode, model, project, status.
+
+## Daemon events (listeners)
+
+`agent.created`, `agent.starting`, `agent.stopping`, `agent.message`, `agent.removed`, `hub.action`, each with the same `agent` summary and an `at` timestamp.
+
+## Engines
+
+`api.engine(def)` adds an agent engine; `def` has the same shape as the built-in adapters in `src/engines/` (see [engines.md](engines.md)). Built-in engines can't be replaced.
+
+## Hub
+
+| Hook | Use |
+| --- | --- |
+| `api.authenticate((req) => identity \| null)` | A sign-in method next to the access token and Google, for example SSO through a proxy that sets a verified header, or your own API keys. The identity (`{ user, email?, roles? }`) is `req.user` in routes and `details.user` in policies. Browser writes still need the `x-agentmgr` header. |
+| `api.policy` with `hub.request` | Before every signed-in API request: `{ method, path, auth, user }`. `auth` is `bearer` (admin token), `session` (token or Google sign-in) or `plugin`. |
+| `api.policy` with `hub.terminal` | Before a browser terminal to a machine opens: `{ runner, user }`. |
+| `api.on` | `hub.request` for every signed-in write. |
+| `api.routes` | Served under `/api/ext/<name>` after sign-in and policies. |
+
+## What plugins can't do
+
+Plugins add checks and features; they can't loosen the built-in ones. A machine's own `hub.allow`, the local-only routes, the request checks in `server.js`, and remote access sign-in all apply first.

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "ai-agentmanager",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Run background coding agents (Claude Code, Codex) per intent, and keep track of them from a web UI, your phone or the CLI",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "codex",
+    "ai-agents",
+    "coding-agents",
+    "agent-manager",
+    "cli"
+  ],
+  "homepage": "https://github.com/jdmunta/ai-agentmanager-core#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jdmunta/ai-agentmanager-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jdmunta/ai-agentmanager-core/issues"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "agentmgr": "bin/agentmgr.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "public",
+    "scripts",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "start": "node bin/agentmgr.js serve",
+    "test": "node --test --test-concurrency=1 test/*.test.js",
+    "postinstall": "node scripts/fix-pty.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "commander": "^15.0.0",
+    "dompurify": "^3.4.16",
+    "express": "^5.2.1",
+    "marked": "^18.0.14",
+    "mermaid": "^11.17.2",
+    "node-pty": "^1.1.0",
+    "qrcode": "^1.5.4",
+    "ws": "^8.22.0"
+  }
+}