constellai 0.3.0

package/docs/en/AGENTS.md

@@ -0,0 +1,279 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/AGENTS.md) · [✦ Constella](../../README.md)
+
+# Agents — The Roster ✦🛰️
+
+![](../assets/divider-orbit.svg)
+
+The ten working stars of every Constella organization. Each agent is a real `claude`/`codex` CLI process with a role, a manager, a model, a temperature, a daily budget cap and a persona on disk. Together they form the constellation that plans, builds, reviews and ships your product.
+
+## When to use
+
+- You want to know **who does what** and **who reports to whom** in a freshly-onboarded organization.
+- You need the exact **handle**, **role**, **model**, **daily cap** and **tier** for an agent.
+- You are wiring the **Org Chart**, re-assigning a manager, or changing an agent's model/budget.
+- You want to understand **persona files** (`.claude/agents/<handle>/…`), **status** and **health**.
+
+## How it works 🌌
+
+The roster is **born from code**, not typed in by a human. Three sources define and materialize it:
+
+| Source file | Role |
+|---|---|
+| `src/data/scaffold.ts` (`AGENT_DEFS`) | Canonical roster definition + persona/file templates (`agentMd`, `pulseMd`, `toolsMd`, `skillsMd`). Renders the on-disk `.claude/agents/<handle>/…` files. |
+| `src/server/onboarding.ts` (`AGENTS`) | Inserts the 10 `agent` rows into the DB at onboarding (with `tierFloor`, `dailyCapUsd`, `reportsTo`). |
+| `src/server/seed-roster.ts` (`seedRosterForExistingWorkspaces`) | **Backfill** — adds any `AGENT_DEFS` member missing from an already-onboarded workspace (e.g. Vannevar, added after the original 9). Idempotent; runs once per boot from `reconcileOnBoot`. |
+
+The **directory is the source of truth**: every agent's identity lives in Markdown under `.claude/agents/<handle>/`. The `agent` DB row (`src/db/schema.ts`) indexes it for the UI and the runner. Editing the persona in the UI writes through to disk (`saveAgentPersona`, `saveAgentModel` in `src/server/agents.ts`).
+
+> Note: the legacy `src/db/seed.ts` demo seed lists only the original **9** agents (no Vannevar). The boot backfill (`seedRosterForExistingWorkspaces`) closes that gap, so every live workspace ends up with all **10**.
+
+## Main flow — from definition to a living agent
+
+```mermaid
+flowchart LR
+  A["AGENT_DEFS<br/>(scaffold.ts)"] --> B["onboarding.ts<br/>insert agent rows"]
+  A --> C["agentFiles()<br/>render .claude/agents/&lt;handle&gt;/"]
+  B --> D[("agent table")]
+  C --> E["Agent.md · pulse.md<br/>tools.md · skills.md"]
+  D --> F["Runner / Org Chart / Studio"]
+  E --> G["assembleAgentPrompt<br/>(persona → CLI run)"]
+  H["seed-roster.ts backfill<br/>(on boot)"] -. fills gaps .-> D
+  H -. writes .-> E
+```
+
+## The 10 agents 🪐
+
+Source of truth: `AGENT_DEFS` in `src/data/scaffold.ts` (mirrored by `AGENTS` in `src/server/onboarding.ts`).
+
+| Name | Handle | Role | Reports to | Model | Temp | Daily cap (USD) | Tier | Color |
+|---|---|---|---|---|---|---|---|---|
+| Ada | `ada` | CEO | — (root) | `sonnet` | 0.4 | $15 | critical | `#e0a44e` |
+| Linus | `linus` | CTO | `ada` | `sonnet` | 0.3 | $40 | critical | `#9a5cff` |
+| Donald | `donald` | Product Owner | `ada` | `haiku` | 0.4 | $20 | heavy | `#4fc9b0` |
+| Margaret | `margaret` | Backend | `linus` | `sonnet` | 0.3 | $50 | heavy | `#3fb98f` |
+| Grace | `grace` | Frontend | `linus` | `sonnet` | 0.5 | $45 | heavy | `#5b8def` |
+| Edsger | `edsger` | QA | `linus` | `haiku` | 0.2 | $25 | heavy | `#e8688f` |
+| Werner | `werner` | DevOps | `linus` | `haiku` | 0.3 | $20 | heavy | `#f0a35e` |
+| Barbara | `barbara` | Docs | `ada` | `haiku` | 0.4 | $15 | light | `#b3d97a` |
+| Whitfield | `whitfield` | CyberSec | `linus` | `opus` | 0.2 | $30 | critical | `#c4a0ff` |
+| Vannevar | `vannevar` | Knowledge | `ada` | `haiku` | 0.2 | $10 | light | `#7ac5e0` |
+
+All ten ship on `provider: cli_claude_code` by default. `model` is a real Claude Code CLI alias — only `opus`, `sonnet`, `haiku` exist for that adapter (`CLI_MODELS.cli_claude_code` in `src/server/adapters/cli.ts`).
+
+### Identities & rituals
+
+Each agent carries an `identity` (who it is) and a `ritual` (what it does every working cycle), straight from `AGENT_DEFS`:
+
+| Agent | Identity | Ritual |
+|---|---|---|
+| Ada | Decisive, outcome-driven leader. Speaks in goals, not tasks. Protects scope and budget. | Read the company goals, decompose into epics, delegate to leads, review what shipped. |
+| Linus | Systems thinker. Balances delivery speed against technical debt. | Turn epics into tickets, route work to specialists, clear blockers, review PRs. |
+| Donald | Customer voice. Ruthless about priority and clarity. | Groom the backlog with MoSCoW, plan the sprint, track delivery, close with a retro. |
+| Margaret | Pragmatic server engineer. Values correctness, small diffs and green tests. | Pull one ticket, read context, implement on a branch, never push without a passing suite. |
+| Grace | Craft-focused UI engineer. Cares about accessibility and clean component APIs. | Read the design tokens, build the smallest component that works, typecheck before PR. |
+| Edsger | Skeptical quality gate. Assumes nothing works until proven by a test. | Reproduce, cover with a test, run the suite, then gate the sign-off. |
+| Werner | Reliability-minded operator. Automates the boring, guards the leases. | Build, deploy a preview, report the URL, never leave an env leased too long. |
+| Barbara | Patient explainer. Turns changes into understandable docs. | Watch merges, draft docs while context is fresh, verify every link. |
+| Whitfield | Adversarial reviewer. Thinks like an attacker, writes like an auditor. | Audit every change for secret handling and injection, file findings with a concrete fix. |
+| Vannevar | Keeper of the company's semantic memory. Indexes every document AND conversation into embeddings. | Keep the embedding server healthy; re-index workspace docs and chat into the RAG index so retrieval stays current. |
+
+## Reporting tree — the org chart 🌠
+
+Two roots-of-orbit: **Ada (CEO)** sits at the center; **Linus (CTO)** carries the engineering constellation. `reportsTo` stores the **manager's handle** (handle-space end to end — see `setReportsToByHandle`).
+
+```mermaid
+graph TD
+  ada["Ada · CEO · sonnet · $15 · critical"]
+  linus["Linus · CTO · sonnet · $40 · critical"]
+  donald["Donald · Product Owner · haiku · $20 · heavy"]
+  barbara["Barbara · Docs · haiku · $15 · light"]
+  vannevar["Vannevar · Knowledge · haiku · $10 · light"]
+  margaret["Margaret · Backend · sonnet · $50 · heavy"]
+  grace["Grace · Frontend · sonnet · $45 · heavy"]
+  edsger["Edsger · QA · haiku · $25 · heavy"]
+  werner["Werner · DevOps · haiku · $20 · heavy"]
+  whitfield["Whitfield · CyberSec · opus · $30 · critical"]
+
+  ada --> linus
+  ada --> donald
+  ada --> barbara
+  ada --> vannevar
+  linus --> margaret
+  linus --> grace
+  linus --> edsger
+  linus --> werner
+  linus --> whitfield
+```
+
+- **Ada's direct reports:** `linus`, `donald`, `barbara`, `vannevar`.
+- **Linus's direct reports:** `margaret`, `grace`, `edsger`, `werner`, `whitfield`.
+- Blocked tasks escalate to the agent's `reportsTo` (per `.claude/routing.md`).
+
+## Key concepts ✦
+
+### Persona files (the directory is the brain)
+
+For every agent, `agentFiles(def, ctx)` writes **four** Markdown files under `.claude/agents/<handle>/`:
+
+| File | Generator | Contents |
+|---|---|---|
+| `Agent.md` | `agentMd` | YAML front-matter (`handle`, `name`, `role`, `reportsTo`, `provider`, `model`, `temperature`, `dailyCapUsd`, `tierFloor`) + Identity, Ritual, Responsibilities, Behavior (from temperature), Decision/Execution rules, Workspace boundaries, and the **System prompt**. |
+| `pulse.md` | `pulseMd` | Liveness config — `intervalSec: 30`, `maxMissed: 2`, `wakeOn` (`queued_task`, `mention`), and the status/health legend. |
+| `tools.md` | `toolsMd` | Role-scoped tool table (e.g. CyberSec → `secret-scan`, `review.signoff`, `fs.read`; Knowledge → `rag.reindex`, `rag.index-chat`, `embed.health`). |
+| `skills.md` | `skillsMd` | The procedures linked to the agent (from `SKILL_DEFS`) + its ritual. |
+
+`Agent.md` is **write-through**: UI edits in Agent Studio patch the front-matter and sections in place (`setFrontMatter`, `setInlineField`, `setSection`) and the DB row is updated to match. The directory wins on conflict.
+
+### Model & tier
+
+- **Not Claude-only.** The seed `opus`/`sonnet`/`haiku` values are simply the defaults of the seed adapter `cli_claude_code`. Change `adapter` per agent in **Agent Studio → Model** and the **model menu changes with it** — the `ModelPicker` is keyed by `adapter` (`cliModelOptions(adapter)`, `src/components/ui/model-picker.tsx`): `cli_codex` → `gpt-5-codex` / `o4-mini`; `cli_openclaw` / `cli_hermes` / `cli_aider` / `cli_opencode` / `cli_copilot` / `cli_cursor` / `cli_cline` / `cli_kilo` → their provider-routed ids; `local_*` → the loaded GGUF; HTTP/router providers → the cached model catalog. The full adapter table is in [MODELS.md](./MODELS.md).
+- `model` is the configured alias. For `cli_claude_code` that is one of `opus` / `sonnet` / `haiku`.
+- `tierFloor` (`light` | `heavy` | `critical`) is the agent's quality floor — defaulted in `AGENT_DEFS`, persisted on the `agent` row (`tier_floor`, default `heavy`). **Tiers are provider-agnostic:** a flagship reasoning model on any provider (e.g. a top Codex/GPT at high reasoning, or a top Gemini) maps to the `critical` / Opus-class tier in power and cost, while smaller/faster models (`o4-mini`, a "flash", `haiku`) map to the `light` end.
+- For quality-critical steps (code review, security, final validation) the runner can reach for the **strongest** model of the agent's provider via `strongestModelFor()` — for `claude` that resolves to `opus`, and the equivalent flagship for any other provider.
+- The model menu switches **automatically** when you pick a provider; the **daily cap does not** — it is an independent USD budget you set (next section) to match the model's cost tier.
+- `temperature` does **not** set a CLI sampling flag (the Claude Code CLI exposes none). Instead `temperatureBehavior(t)` turns the slider into a concrete **prompt instruction** injected on every run (`src/data/temperature.ts`).
+
+### Daily cap (budget ceiling) 🕳️
+
+`dailyCapUsd` is a hard spend ceiling per agent per day. The runner calls `agentAtCap(agentId, dailyCapUsd)` (`src/server/runner.ts`); when reached it **pauses** the agent and pushes a `budget` inbox item ("@`<handle>` hit the daily budget cap"). Raise the cap in Agent Studio or wait for the daily reset. A cap of `0` means "no cap".
+
+### Status & health
+
+Two orthogonal axes on the `agent` row:
+
+| Axis | Column | Values | Meaning |
+|---|---|---|---|
+| **Status** | `status` | `idle` · `working` · `review` · `blocked` | What the agent is doing right now. |
+| **Health** | `health` | `alive` · `stale` · `down` | Whether its executor is reachable. |
+
+The cron tick sweep (`runner.ts`) sets health from runtime availability: if the agent's CLI binary is reachable (`runtimeOk`), health is `alive`; otherwise `stale`. Idle agents get a lightweight heartbeat touch (`lastPulse` updated, no pulse-row spam); working/review agents record a real `pulse` row via `recordPulse`. `pulse.md` documents the liveness contract: alive within `intervalSec * maxMissed`, otherwise stale; repeated failure → `down` (logged to `Reports/error-report.md`).
+
+## Tables 🛰️
+
+### `agent` (`src/db/schema.ts`)
+
+| Column | Type | Default | Notes |
+|---|---|---|---|
+| `id` | text PK | — | Stable id. |
+| `workspaceId` | text | — | FK → `workspace` (cascade). |
+| `handle` | text | — | Unique short name (`ada`, `linus`, …). |
+| `name` | text | — | Display name. |
+| `role` | text | — | CEO / CTO / Backend / … |
+| `color` | text | `#e0a44e` | Avatar tint (used for initials fallback). |
+| `image` | text | null | Optional avatar path / data URL. |
+| `adapter` | text | `cli_claude_code` | Execution runtime (CLI/HTTP/local). |
+| `model` | text | `sonnet` | Model alias. |
+| `temperature` | real | `0.4` | Drives the Behavior prompt band. |
+| `dailyCapUsd` | real | `25` | Daily spend ceiling. |
+| `tierFloor` | text enum | `heavy` | `light` / `heavy` / `critical`. |
+| `reportsTo` | text | null | Manager's **handle**. |
+| `status` | text enum | `idle` | `idle` / `working` / `review` / `blocked`. |
+| `health` | text enum | `alive` | `alive` / `stale` / `down`. |
+| `lastPulse` | timestamp | null | Last heartbeat. |
+| `persona` | json | null | `{ identity, ritual, tone, systemPrompt }`. |
+| `rag` | json | null | Per-agent RAG source toggles. |
+| `orgX` / `orgY` | real | null | Org-chart card coordinates. |
+
+### `pulse` (heartbeat log)
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | text PK | — |
+| `agentId` | text | FK → `agent`. |
+| `at` | timestamp | `unixepoch()` default. |
+| `ok` | boolean | Health-ping result. |
+| `latencyMs` | integer | Ping latency. |
+| `note` | text | e.g. `tick:working`. |
+
+### `agentSkill` (enablement join)
+
+| Column | Notes |
+|---|---|
+| `agentId` + `skillId` | Composite PK. |
+| `auto` | `true` = system-managed link (reconciled on boot/stack change); `false` = operator hand-toggled (never touched by reconcile). |
+
+## Step-by-step — operate the roster
+
+1. **See the roster.** Open the Agents module (each card shows status, health, model). The Org Chart visualizes `reportsTo`.
+2. **Re-assign a manager.** Drag a card in the Org Chart canvas → `setReportsToByHandle(agentHandle, managerHandle)`. Self-loops and cycles are rejected; pass `null` to detach (becomes a root/CEO).
+3. **Change model / budget / tier.** In Agent Studio → `saveAgentModel({ adapter, model, temperature, dailyCapUsd, tierFloor })`. The DB row and `Agent.md` front-matter are updated together.
+4. **Edit persona.** `saveAgentPersona({ identity, ritual, tone, systemPrompt })` patches `Agent.md` (Identity, Ritual, System prompt) on disk.
+5. **Set an avatar.** `saveAgentImage(agentId, imagePath | null)` (data-URL avatars; legacy `uploads/<id>/` avatars are cleaned up on replace).
+6. **Add a missing agent.** On boot, `seedRosterForExistingWorkspaces()` backfills any `AGENT_DEFS` member absent from the workspace — DB row, four persona files, and the non-provisional native skills.
+
+## Examples
+
+Inspect an agent's persona on disk:
+
+```bash
+cat ~/.constella/organizations/<orgId>/workspace/.claude/agents/linus/Agent.md
+```
+
+Front-matter you will see (rendered by `agentMd`):
+
+```yaml
+---
+handle: linus
+name: Linus
+role: CTO
+reportsTo: ada
+provider: cli_claude_code
+model: sonnet
+temperature: 0.3
+dailyCapUsd: 40
+tierFloor: critical
+---
+```
+
+List agents and their reporting line from chat:
+
+```
+/agents
+/agent linus
+```
+
+(`/agents` lists the roster; `/agent <handle>` shows one agent's detail — see [CHAT_COMMANDS.md](./CHAT_COMMANDS.md).)
+
+## Possible states
+
+| Concern | Values | Set by |
+|---|---|---|
+| Status | `idle` · `working` · `review` · `blocked` | Runner / planner as work flows. |
+| Health | `alive` · `stale` · `down` | Cron tick sweep (binary reachability) + pulse sweep. |
+| Budget | under cap → runs · at/over cap → paused (`budget` inbox item) | `agentAtCap()`. |
+| Tier floor | `light` · `heavy` · `critical` | `AGENT_DEFS` default; editable in Studio. |
+
+## Related integrations 🚀
+
+- **Skills** — each agent's enabled procedures (`agentSkill`, `skills.md`). See [SKILLS.md](./SKILLS.md).
+- **Models** — adapters and model catalog behind `adapter`/`model`. See [MODELS.md](./MODELS.md).
+- **Workflow** — how agents pick up Goals → Specs → Issues → Tasks. See [WORKFLOW.md](./WORKFLOW.md).
+- **Team Room / DM** — where agents collaborate and hand off. See [TEAM_ROOM.md](./TEAM_ROOM.md), [DM.md](./DM.md).
+- **PO Agent / KB Agent** — Donald's grooming and Vannevar's memory. See [PO_AGENT.md](./PO_AGENT.md), [KB_AGENT.md](./KB_AGENT.md).
+
+## Security 🕳️
+
+- **Workspace jail.** Every agent runs with `cwd` set to its organization's workspace and is lexically + symlink-checked against escape; nothing outside the workspace is reachable. Boundaries are stated in `Agent.md`, `permissions.md` and enforced by the runner.
+- **No inline secrets.** Personas and tools forbid plaintext keys; secrets come from the vault. Output is scrubbed before logs/KB/Telegram.
+- **Budget ceilings.** A runaway agent stops at its `dailyCapUsd`; the runner will not exceed the cap.
+- **Cycle/self guards.** Manager re-assignment (`setReportsTo`, `setReportsToByHandle`) rejects self-references and cycles, so the org chart can never form a loop.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| An agent shows **stale/down** | Its CLI binary isn't installed/reachable (`runtimeOk` false). | Install/repair the `claude`/`codex` CLI; health recovers on the next tick. |
+| Agent is **paused mid-work** | Hit its `dailyCapUsd`. | Raise the cap in Agent Studio or wait for the daily reset (see the `budget` inbox item). |
+| Vannevar missing in an old org | Org onboarded before the Knowledge agent existed. | The boot backfill (`seedRosterForExistingWorkspaces`) adds it automatically on next start. |
+| Manager change does nothing | Self/cycle (rejected) or manager not in this workspace. | Pick a different manager; the change is silently ignored for invalid targets. |
+| Edited `Agent.md` but UI still old | Write-through/watcher lag. | The sync engine re-indexes on save; reload after a moment. |
+
+## Related links
+
+- [AI_ARCHITECTURE.md](./AI_ARCHITECTURE.md) — how agent runs are assembled and executed.
+- [WORKFLOW.md](./WORKFLOW.md) — the Goal → Spec → Issue → Done lifecycle.
+- [SKILLS.md](./SKILLS.md) — the skill library each agent draws on.
+- [MODELS.md](./MODELS.md) — adapters, model aliases and tiers.
+- [PO_AGENT.md](./PO_AGENT.md) · [KB_AGENT.md](./KB_AGENT.md) — Donald and Vannevar in depth.
+- [TEAM_ROOM.md](./TEAM_ROOM.md) · [DM.md](./DM.md) — agent collaboration.
+- [CHAT_COMMANDS.md](./CHAT_COMMANDS.md) — `/agents`, `/agent`, `/status`.

package/docs/en/AI_ARCHITECTURE.md

@@ -0,0 +1,373 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/AI_ARCHITECTURE.md) · [✦ Constella](../../README.md)
+
+# 🌌 AI Architecture — how a constellation actually runs
+
+> The control plane never talks to an LLM API directly. It **drives real CLIs** (`claude`, `codex`, and friends) as subprocesses inside the org workspace, captures their **real** token usage + cost, and never fabricates a number.
+
+This document explains the machinery that turns "an agent" into a running process: the CLI adapters, the spawn invocation, the vanilla-hooks override, permission modes per run-mode, the model-agnostic context assembly, and cost tracking.
+
+---
+
+## ✦ When to use this doc
+
+- You want to understand **what command** Constella runs when an agent "thinks" or "builds".
+- You need to know **why agents run vanilla** (no operator plugins/hooks leaking in).
+- You're debugging permissions, timeouts, model selection, or cost rows.
+- You're adding a new CLI adapter or HTTP runtime.
+
+For the org/role side (who the agents are, their daily caps), see [AGENTS.md](./AGENTS.md). For the workflow they execute, see [WORKFLOW.md](./WORKFLOW.md).
+
+---
+
+## 🛰️ How it works (the big picture)
+
+Every agent run — a chat reply, a board task, or a CEO planning pass — flows through the same three layers:
+
+1. **Context Manager** (`src/server/context-manager.ts`) assembles ONE standardized, model-agnostic prompt (mission, project state, decisions, conversation, RAG, memory, skills) and trims it to the agent's real context window.
+2. **Runtime resolver** (`src/server/runtime.ts`) decides *where* the prompt runs: a local **CLI** (the default — subscription-backed, agentic, file-editing) or an **HTTP** provider (chat/reasoning only, when wired to a connected `http_*` provider).
+3. **CLI adapters** (`src/server/adapters/cli.ts`) spawn the actual binary, stream tool-use + text events back, and parse **real** usage + cost from the CLI's JSON output.
+
+```mermaid
+flowchart TD
+  A["Trigger: chat / task / plan"] --> CM["Context Manager<br/>assembleAgentPrompt()"]
+  CM --> RT["resolveRuntime()"]
+  RT -->|"kind: cli"| CLI["adapters/cli.ts<br/>runAgentStream()"]
+  RT -->|"kind: http"| HTTP["adapters/http.ts<br/>runHttpStream()"]
+  CLI --> SPAWN["spawn('claude' | 'codex' | …)"]
+  SPAWN --> JSON["parse JSON → CliResult<br/>{ ok, text, usd, tokens }"]
+  HTTP --> JSON
+  JSON --> COST["insert costEntry<br/>(only if real usage)"]
+  JSON --> OUT["stream events → Team Room / dock"]
+```
+
+---
+
+## 🪐 Main flow
+
+The canonical agentic path is the CLI. `runAgent` / `runAgentStream` dispatch to a per-binary runner:
+
+| Step | Where | What happens |
+|------|-------|--------------|
+| 1. Pick binary | `pickBinary(adapter, model)` | Maps the agent's adapter (`cli_claude_code`, `cli_codex`, …) to an executable name (`claude`, `codex`, `cursor-agent`, `kilocode`, …). |
+| 2. Resolve cwd | `orgRoot(orgId)` | The agent's **FS jail** — the org workspace dir. `mkdirSync(cwd, { recursive: true })`. |
+| 3. Build argv | `claudePermArgs()`, `claudeSettingsArgs()`, `claudeWebArgs()` | Permission mode, vanilla-hooks settings overlay, optional web tools. |
+| 4. Validate model | `safeModel()` / `safeModelSlash()` | Regex-validates the model id (it reaches argv on a `shell: true` Windows spawn) — drops anything that could inject. |
+| 5. Spawn | `runProc()` | `spawn(cmd, args, { cwd, shell, windowsHide, env })`; registers the child under its abort token. |
+| 6. Stream / parse | `runClaudeStream` / per-binary parser | Emits `StreamEvent`s per tool_use + text delta; parses the final JSON for usage. |
+| 7. Result | `CliResult` | `{ ok, text, usd, inputTokens, outputTokens, durationMs, binary, model, error }`. |
+| 8. Book cost | caller (`collab` / `runner` / `planner-core`) | Inserts a `cost_entry` row **only if** `usd > 0` or tokens > 0. |
+
+---
+
+## 🌠 Key concepts
+
+### CLI adapters (`src/server/adapters/cli.ts`)
+
+The `CliBinary` union enumerates every executable Constella can drive:
+
+```
+"claude" | "codex" | "openclaw" | "hermes"
+| "aider" | "opencode" | "copilot" | "cursor-agent" | "cline" | "kilocode"
+```
+
+`pickBinary(adapter, model)` resolves the agent's stored adapter to a binary. If the adapter is unknown, it heuristically picks `codex` for `gpt*`/`o1`/`o3`/`o4`/`codex*` models, otherwise `claude`. The fixed model lists each CLI exposes live in `CLI_MODELS`:
+
+| Adapter | Binary | Models |
+|---------|--------|--------|
+| `cli_claude_code` | `claude` | `opus`, `sonnet`, `haiku` |
+| `cli_codex` | `codex` | `gpt-5-codex`, `o4-mini` |
+| `cli_openclaw` | `openclaw` | `(default)` + provider-prefixed ids |
+| `cli_hermes` | `hermes` | `(default)` + provider-prefixed ids |
+| `cli_aider` | `aider` | `(default)` + provider-prefixed ids |
+| `cli_opencode` | `opencode` | `(default)` + provider-prefixed ids |
+| `cli_copilot` | `copilot` | `(default)`, `claude-sonnet-4.5`, `gpt-5` |
+| `cli_cursor` | `cursor-agent` | `(default)`, `claude-4.5-sonnet`, `gpt-5` |
+| `cli_cline` | `cline` | `(default)` |
+| `cli_kilo` | `kilocode` | `(default)` |
+
+> Provider-routed CLIs (Aider, OpenCode, Copilot, Cursor, Cline, Kilo) authenticate via **their own** login/config — Constella drives them, never holds their keys. Their headless modes emit **no** token/cost, so those are recorded as `0` (honest, never faked). `LOGIN_HINTS` maps each binary to the command that authenticates it, surfaced in the UI when `detectCliAuth()` returns `needs_login`.
+
+### The Claude spawn invocation 🚀
+
+The primary, fully-streamed path is `runClaudeStream`. It builds:
+
+```
+claude -p --output-format stream-json --include-partial-messages --verbose \
+  [--settings <vanilla settings file>] \
+  --permission-mode <bypassPermissions|acceptEdits> \
+  [--allowedTools WebSearch WebFetch] \
+  [--model <opus|sonnet|haiku>]
+```
+
+The non-streamed sibling `runClaude` uses `--output-format json` (single result object). Both pipe the assembled prompt to **stdin** and parse the result JSON:
+
+```js
+ok: obj.is_error !== true && obj.subtype === "success",
+text: String(obj.result ?? ""),
+usd:  Number(obj.total_cost_usd ?? 0),
+inputTokens:  usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens,
+outputTokens: usage.output_tokens,
+```
+
+Codex uses `codex exec --json --skip-git-repo-check -s <sandbox> [-m <model>]` and parses best-effort usage from its JSONL event stream.
+
+### Vanilla agents — `disableAllHooks` 🕳️
+
+Company agents must run **independent of the operator's personal `~/.claude`**. The operator may have UserPromptSubmit/SessionStart hooks or plugins (e.g. a "caveman mode" voice rewriter) that fire for **every** `claude` invocation — including the headless agent subprocesses. Without isolation, the agents start talking like the operator's plugin instead of themselves.
+
+Constella can't redirect `CLAUDE_CONFIG_DIR` (the subscription credentials live there — redirecting it logs the agent out). Instead, `vanillaSettingsArgs()` writes a tiny file once and passes it:
+
+```json
+{ "disableAllHooks": true }
+```
+
+→ `--settings <tmpdir>/constella-agent-settings.json`. Hooks off, **auth intact**.
+
+### Opt-in clean-config isolation (lock + guard hooks)
+
+When `CONSTELLA_AGENT_LOCK_HOOK=1` (or the per-workspace `settings.agents.fileLocks`) or the (opt-in) destructive-command guard is enabled, `agentClaudeDir()` builds a **dedicated clean config dir** under `<CONSTELLA_HOME>/.agent-claude`, copies in the operator's `.credentials.json` **and `~/.claude.json`** (credentials **plus** the account/onboarding state — relocating `CLAUDE_CONFIG_DIR` also relocates where the CLI reads its login, so both are mirrored or the agent runs "Not logged in"), and writes a `settings.json` carrying ONLY Constella's `PreToolUse` hooks:
+
+| Hook | Matcher | Binary |
+|------|---------|--------|
+| File lock (`bin/lock-hook.mjs`) | `Write\|Edit\|MultiEdit\|NotebookEdit` | gated by `lockHookOn()` |
+| Command guard (`bin/guard-hook.mjs`) | `Bash` | gated by `guardHookOn()` (default ON, `CONSTELLA_AGENT_CMD_GUARD`) |
+
+When this clean dir is active, `claudeSettingsArgs()` returns `[]` (the dir already carries settings — don't ALSO pass `disableAllHooks`), and `claudeEnv()` injects `CLAUDE_CONFIG_DIR` plus the lock-hook identity (`CONSTELLA_ORG_ID`, `CONSTELLA_TASK_ID`, `CONSTELLA_AGENT_ID`, `CONSTELLA_AGENT_HANDLE`, `CONSTELLA_BASE_URL`). If creds can't be copied, it **falls back to vanilla** — file-locking degrades, auth never breaks.
+
+### Permission modes by run-mode 🛰️
+
+`AGENT_FULL_ACCESS` is run-mode aware (`CONSTELLA_RUN_MODE`), overridable with `CONSTELLA_AGENT_FULL_ACCESS=1|0`:
+
+| Run mode | `AGENT_FULL_ACCESS` | claude `--permission-mode` | codex `-s` sandbox |
+|----------|---------------------|----------------------------|--------------------|
+| `start` (local dev) | `true` | `bypassPermissions` (install + run tests) | `danger-full-access` |
+| `auth` / `vps` / `portable` (prod) | `false` | `acceptEdits` (edits only, no net/exec) | `workspace-write` (no network) |
+
+> Prod already runs inside Docker + Tailscale (the container is the hard jail). The CLI stays restricted on top for defense-in-depth.
+
+### Web research 🌠
+
+`claudeWebArgs()` pre-approves the built-in web tools with `--allowedTools WebSearch WebFetch`. It's **additive** — it does NOT restrict Read/Edit/Bash. Default **ON**; disable with `CONSTELLA_WEB_RESEARCH=0` or per-workspace `settings.agents.webResearch = false` (pushed by the runner via `setWebResearch` before each spawn).
+
+### Streaming events
+
+`runClaudeStream` parses the `stream-json` line protocol and emits a `StreamEvent` per tool use and per text delta:
+
+| `StreamEvent.kind` | Source tool |
+|--------------------|-------------|
+| `read` | `Read` |
+| `create` | `Write` (with a content preview) |
+| `edit` | `Edit` / `NotebookEdit` (a real `-`/`+` diff, ≤80 lines) |
+| `run` | `Bash` / `PowerShell` |
+| `search` | `Glob` / `Grep` |
+| `thinking` | extended-thinking blocks |
+| `text` | streamed reply deltas (debounced ~120 chars) |
+| `done` | run finished |
+
+These events drive the live Team Room work-card (true diff view, not fabricated). The runner uses `create`/`edit` events to record file provenance for the goal.
+
+### Cancellation 🕳️
+
+Runs register their child process under an **abort token** (= the `taskId`) in an `ACTIVE` map. `abortRun(token)` SIGKILLs the in-flight CLI mid-run (used by goal cancellation). A token cancelled in the claim→spawn window is recorded in `ABORTED`, so a child that registers late **self-kills**. Default timeouts: 180s (`runClaude`/`runCodex`), 240s (`runClaudeStream`), 300s for a planning pass.
+
+---
+
+## 🌌 Context assembly (prompt gravity)
+
+`assembleAgentPrompt()` (`src/server/context-manager.ts`) is the **single source of truth** for prompts — used by chat (`collab.replyInChannel`) AND task execution (`runner`) so task agents are never context-blind. It is **model-agnostic**: the same bundle feeds Opus, Codex, or a local model; only the trim differs.
+
+### Budget & window
+
+`resolveWindow()` prefers the dynamic catalog (`provider_model.context`) so a 1M-ctx model keeps full history; otherwise falls back to `modelWindow(model)`:
+
+| Model alias | Window | keepRecent | aggressive |
+|-------------|--------|------------|------------|
+| `opus` / `sonnet` | 200,000 | 16 | no |
+| `haiku` | 200,000 | 12 | no |
+| `gpt*` / `codex` / `o3` / `o4` | 128,000 | 12 | yes |
+| (other / local) | 100,000 | 8 | yes |
+
+The prompt budget is **half** the window (`win.window * 0.5`) — the other half is reserved for the model's reply. `estimateTokens(text)` ≈ `text.length / 4`.
+
+### Section priority (trimmed lowest-first)
+
+A fixed **head** (identity + persona + `temperatureBehavior` + the instruction + the task) always survives. Then sections are added in priority order until the budget is hit; lower-priority sections are **skipped** when over budget:
+
+```mermaid
+flowchart TD
+  H["HEAD (always kept)<br/>You are @handle, the role.<br/>persona · temperature · instruction · TASK"] --> S1["Canonical project facts<br/>(synced knowledge blocks)"]
+  S1 --> S2["Core skills for role + stack<br/>(pinned, ≤10)"]
+  S2 --> S3["Project state<br/>(issues · my tasks · decisions)"]
+  S3 --> S4["More skills (long tail, ≤30)"]
+  S4 --> S5["Recent conversation"]
+  S5 --> S6["Earlier conversation (compacted)"]
+  S6 --> S7["Knowledge — RAG/KB (kbQuery k=6)"]
+  S7 --> S8["Relevant memory (.claude/memory.md)"]
+  S8 --> S9["Company background<br/>(mission · objective · stack)"]
+  style H fill:#1b2a4a,color:#fff
+  style S9 fill:#3a1b2a,color:#fff
+```
+
+Each section is sourced from real state:
+
+- **Canonical facts** — `canonicalFactsSection()` (synced knowledge blocks, treated as authoritative). See [SYNCED_BLOCKS.md](./SYNCED_BLOCKS.md).
+- **Skills** — `agentSkills()` joins `agent_skill → skill`, ranks by `coreSkillNamesForRole` / `librarySkillNamesForStack`, pins ≤10 core, caps ≤30 tail. See [SKILLS.md](./SKILLS.md).
+- **Project state** — open issues, this agent's active tasks, team tasks, specs, recent `decision` rows. See [GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md).
+- **Conversation** — `buildChannelContext()` returns `{ summary, recent }` (compaction handles the long tail). See [DM.md](./DM.md) / [TEAM_ROOM.md](./TEAM_ROOM.md).
+- **Knowledge** — `kbQuery(orgId, query, { k: 6 })`, state-aware (drops obsolete/superseded). See [KB_RAG.md](./KB_RAG.md) / [MEMORY_RAG.md](./MEMORY_RAG.md).
+- **Memory** — `.claude/memory.md`, capped 1500 chars.
+
+Finally `resolveBlocks()` expands any `{{kb:slug}}` markers to the current canonical block bodies. The function returns `{ prompt, sources }` — `sources` becomes the message's source chips.
+
+---
+
+## 🪐 Runtime resolution
+
+`resolveRuntime(workspaceId, agent)` returns `{ kind: "cli", binary }` or `{ kind: "http", http }`:
+
+| Adapter prefix | Runtime | Notes |
+|----------------|---------|-------|
+| `local_*` | HTTP (loopback) | llama.cpp `:8082` (primary) or Ollama `:11434` (`local_ollama`, legacy), OpenAI-compatible `/v1`. Chat/reasoning only — file editing stays on CLIs. |
+| `http_*` (configured + key present) | HTTP API | `provider`/`baseUrl`/`apiKey` from the `provider` table + Vault; `google` vs `openai` shape. |
+| `http_*` (not configured) | **falls back** to CLI | so the agent still works. |
+| everything else | CLI | `pickBinary(adapter, model)`. |
+
+`runAgentRuntime()` then streams via `runHttpStream` or `runAgentStream`. The Context Manager produced a model-agnostic prompt, so **either runtime gets the same context**. See [MODELS.md](./MODELS.md) and [AI_ARCHITECTURE.md] (this doc).
+
+---
+
+## 🛰️ Cost tracking (`cost_entry`)
+
+Cost is **real** — pulled from the CLI's JSON (`total_cost_usd`, `usage`). A row is inserted **only when** the run produced usage (`res.usd > 0 || inputTokens + outputTokens > 0`):
+
+| Column | Type | Meaning |
+|--------|------|---------|
+| `id` | text (PK) | row id |
+| `workspace_id` | text | owning workspace (cascade) |
+| `agent_id` | text | which agent spent |
+| `provider` | text | the `binary` that ran (`claude`, `codex`, …) |
+| `model` | text | resolved model |
+| `usd` | real | real cost (0 for CLIs that don't emit cost) |
+| `tokens` | integer | `inputTokens + outputTokens` |
+| `at` | timestamp | when |
+
+The same row shape is written from `collab.ts`, `runner.ts`, and `planner-core.ts`. Daily caps are enforced by summing `cost_entry.usd` for the agent since midnight (`agentAtCap`): a task or chat is **gated** when `total >= agent.dailyCapUsd`, and a `budget` Inbox item is surfaced. See [AGENTS.md](./AGENTS.md) for per-agent caps.
+
+> Provider-routed CLIs and local/HTTP runtimes that emit no usage record `usd: 0` and `tokens: 0` — never a guessed number.
+
+---
+
+## 🌠 Step-by-step: a task execution run
+
+1. The cron tick / runner claims a `todo`/`doing` task; budget + goal-active gates pass.
+2. `pickBinary` + availability check (`binaryAvailable`); agent → `working`, linked issue → `doing`.
+3. `assembleAgentPrompt({ orgId, ws, agent, channel:"room", instruction: TASK_INSTRUCTION, task })`.
+4. Per-spawn flags pushed: `setLockHook`, `setGuardHook`, `setWebResearch` (from `ws.settings.agents.*`).
+5. `runAgentStream(prompt, { binary, model: modelAlias(...), timeoutMs: 240_000, token: t.id, agentId, agentHandle }, onEvent)`.
+6. Stream events tick the TODO checklist live, record touched files, and emit to the Team Room.
+7. On completion: book `cost_entry`; parse `[[KB-BLOCK]]`, `[[REMEMBER]]`, `[[RESEARCH]]` tokens; run boot gate + Test Dev gate; advance the column.
+
+## Step-by-step: a chat reply
+
+1. `replyInChannel(orgId, ws, channel, agent, mode)` builds the role instruction (chat vs work) + the KB/consult/language/security clauses.
+2. `assembleAgentPrompt(...)` → model-agnostic prompt + `sources`.
+3. `resolveRuntime` → CLI or HTTP; `runAgentRuntime` streams events to the operator.
+4. Strip `[[CREATE_WORK]]` (new-work signal), `[[REMEMBER]]`, `[[CONSULT]]`, `[[KB:]]` tokens; `scrubSecrets` the reply.
+5. Persist the `message` (+ `sources`), post KB consult answers as Vannevar, book cost.
+
+---
+
+## 🪐 Examples
+
+**Vanilla Claude task run (start mode, full access):**
+```
+claude -p --output-format stream-json --include-partial-messages --verbose \
+  --settings /tmp/constella-agent-settings.json \
+  --permission-mode bypassPermissions \
+  --allowedTools WebSearch WebFetch \
+  --model sonnet
+```
+
+**Jailed prod run (vps mode, edits only):**
+```
+claude -p --output-format stream-json --include-partial-messages --verbose \
+  --settings /tmp/constella-agent-settings.json \
+  --permission-mode acceptEdits
+```
+
+**Codex task run (jailed):**
+```
+codex exec --json --skip-git-repo-check -s workspace-write -m gpt-5-codex
+```
+
+**Probe a CLI's availability / auth:**
+```
+claude --version          # cliVersion("claude")
+opencode auth list        # detectCliAuth("opencode")
+```
+
+---
+
+## 🕳️ Possible states
+
+| State | Where | Meaning |
+|-------|-------|---------|
+| `CliResult.ok = true` | adapter | `is_error !== true` and (claude) `subtype === "success"`, or exit 0 with text |
+| `CliResult.ok = false` | adapter | error / non-zero exit / no JSON; `error` carries the last ~300 stderr chars |
+| `timedOut` | `runProc` | SIGKILL fired at the timeout; `base(...)` returns `"timed out"` |
+| aborted | `abortRun` | the run's child SIGKILLed mid-flight (goal cancelled) |
+| `AuthState` | `detectCliAuth` | `ready` / `needs_login` / `needs_key` / `unknown` (never fabricates `ready`) |
+| runtime `cli` / `http` | `resolveRuntime` | which engine ran the prompt |
+
+---
+
+## 🛰️ Related integrations
+
+- **Vault** — HTTP/`http_*` provider keys are read via `getSecret` (AES-256-GCM). See [CONFIGURATION.md](./CONFIGURATION.md).
+- **RAG / KB** — `kbQuery` feeds the Knowledge section; chat transcripts get re-indexed. See [KB_RAG.md](./KB_RAG.md).
+- **Skills** — pinned/tail skills are linked per agent. See [SKILLS.md](./SKILLS.md).
+- **Synced blocks** — canonical facts + `{{kb:slug}}` resolution. See [SYNCED_BLOCKS.md](./SYNCED_BLOCKS.md).
+- **Models** — local + catalog model selection. See [MODELS.md](./MODELS.md).
+- **Plugins** — Web Search is a native plugin gating `claudeWebArgs`. See [PLUGINS.md](./PLUGINS.md).
+
+---
+
+## 🚀 Security
+
+- **FS jail** — every CLI runs with `cwd = orgRoot(orgId)`; agents read/edit only inside the org workspace. See [SECURITY.md](./SECURITY.md).
+- **Model-id injection guard** — `safeModel` / `safeModelSlash` regex-validate model ids before they reach argv on a `shell: true` Windows spawn (a value like `sonnet"; rm -rf ~` is dropped).
+- **shell:false for git/gh** — real executables run with `shell: false` so client-influenced branch/message/path args can't be re-parsed by a shell.
+- **Vanilla hooks** — `disableAllHooks` keeps an operator's plugins/hooks out of agent runs (voice + behavior isolation).
+- **Command guard** — `bin/guard-hook.mjs` (default ON) blocks catastrophic shell (`rm -rf /`, force-push, `mkfs`, fork-bomb).
+- **Permission jail in prod** — `acceptEdits` (no net/arbitrary exec) on top of Docker + Tailscale.
+- **Secret scrub** — chat replies pass through `scrubSecrets` before they're stored / shown / sent to Telegram.
+- **Prompt-injection hardening** — Telegram + attached-file clauses mark operator input as DATA, never instructions.
+
+---
+
+## 🌌 Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Agent "couldn't respond" / no output | CLI not installed or not logged in | `cliVersion(...)`; follow `LOGIN_HINTS` (e.g. sign in to Claude Code) |
+| Agents talk in the operator's plugin "voice" | hooks leaked in | confirm `disableAllHooks` overlay is applied (vanilla path) |
+| Agent can't install deps / run tests | jailed permission mode | run-mode is prod (`acceptEdits`); set `CONSTELLA_AGENT_FULL_ACCESS=1` if intended |
+| No web search | web research off | unset `CONSTELLA_WEB_RESEARCH=0` or enable `settings.agents.webResearch` |
+| `cost_entry` rows always `usd:0` | provider-routed/local CLI emits no cost | expected — Constella never fakes cost |
+| Run killed at ~3-4 min | timeout (180s/240s/300s) | large work should be split across tasks |
+| File edits blocked | lock hook (parallel-agent locking) | another agent holds the lock; see [SECURITY.md](./SECURITY.md) |
+| Agent logged out after enabling locks | creds copy failed | check `~/.claude/.credentials.json` exists; it falls back to vanilla otherwise |
+
+---
+
+## 🪐 Related links
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — the control plane, processes, runtime root
+- [AGENTS.md](./AGENTS.md) — roster, roles, daily caps, status/health
+- [WORKFLOW.md](./WORKFLOW.md) — the work lifecycle agents execute
+- [MODELS.md](./MODELS.md) — model catalog, local models, HTTP providers
+- [SKILLS.md](./SKILLS.md) — skill library + per-agent linking
+- [KB_RAG.md](./KB_RAG.md) · [MEMORY_RAG.md](./MEMORY_RAG.md) — the memory nebula
+- [SYNCED_BLOCKS.md](./SYNCED_BLOCKS.md) — canonical facts in context
+- [SECURITY.md](./SECURITY.md) — FS jail, vault, guards, hooks
+- [CONFIGURATION.md](./CONFIGURATION.md) — env vars + per-workspace settings