constella 0.1.0

package/docs/en/DEPLOY.md

@@ -0,0 +1,331 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/DEPLOY.md) · [✦ Constella](../../README.md)
+
+# Deploy (Production) 🚀
+
+![](../assets/divider-orbit.svg)
+
+How to **launch the central ship itself** — getting the Constella control plane running in a durable, production-grade orbit. This page covers deploying *Constella the platform*: Docker on a VPS, the `vps-install.sh` bootstrap, Tailscale, supervised dual-process boot, and portable/global installs.
+
+> **Not to be confused with [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) / [DEPLOY of your project].** Those deploy the **user project** the agents build (a clean-tree export to a separate repo). *This* page deploys **Constella itself** — the ship, not the cargo.
+
+---
+
+## When to use 🌌
+
+| You want to… | Use |
+| --- | --- |
+| Run Constella 24/7 on a remote server, private to your tailnet | **VPS / Docker** (`Dockerfile` + `docker-compose.yml`) |
+| Bootstrap a fresh Ubuntu VPS in one command | **`scripts/vps-install.sh`** |
+| Carry the whole control plane on a USB drive | **Portable** (`constella --portable`) |
+| Install once on your own always-on machine | **Global npm** (`npm i -g constella`) |
+| A quick ephemeral run | **`npx constella`** |
+
+If you only want a local instance on your own laptop, see [START_MODE](./START_MODE.md) and [AUTH_MODE](./AUTH_MODE.md). For the tailnet specifics, see [VPS_MODE](./VPS_MODE.md); for the drive, [PORTABLE_MODE](./PORTABLE_MODE.md).
+
+---
+
+## How it works 🪐
+
+Every Constella launch — local, VPS, portable — goes through the same launcher, **`bin/constella.mjs`**. The launcher:
+
+1. Resolves the **run mode** (`start | auth | vps | portable`) from the launch flag.
+2. Resolves the **runtime root** `HOME` (`CONSTELLA_HOME` / `--path`, default `~/.constella`).
+3. Generates + persists secrets into `<HOME>/.env` (`chmod 600`): `BETTER_AUTH_SECRET`, `CONSTELLA_VAULT_KEY`, `CONSTELLA_WORKER_SECRET`.
+4. Pins `DATABASE_URL=file:<HOME>/constella.db` and applies the shipped Drizzle migrations (`drizzle-kit migrate`).
+5. Boots **two supervised processes**: the **web** server (`next start`) and the **worker** (`bin/worker.mjs`).
+
+A deploy is "the same launcher, in a more durable place" — inside a container, on a USB drive, or under a global install. The mode picks the bind host and the auth posture; the deploy target picks the durability.
+
+```mermaid
+flowchart TD
+  A["operator"] --> B["bin/constella.mjs (launcher)"]
+  B --> C{"run mode"}
+  C -->|"--vps"| D["Docker + Tailscale<br/>(0.0.0.0, tailnet only)"]
+  C -->|"--portable"| E["USB drive root<br/>(0.0.0.0)"]
+  C -->|"--start / --auth"| F["local host<br/>(127.0.0.1)"]
+  B --> G["next start (web :3000)"]
+  B --> H["bin/worker.mjs (cron + watcher + Telegram)"]
+  G -. "supervised, auto-restart" .- B
+  H -. "supervised, auto-restart" .- B
+```
+
+---
+
+## Main flow — VPS via Docker + Tailscale 🛰️
+
+The production-recommended deploy. Constella runs in a container, binds `0.0.0.0`, and is reachable **only** over your Tailscale tailnet — never the open internet.
+
+### The image — `Dockerfile`
+
+A multi-stage `node:22-bookworm-slim` build:
+
+| Stage | Does |
+| --- | --- |
+| `base` | `corepack enable`; installs `git ca-certificates` |
+| `deps` | `pnpm install --frozen-lockfile` |
+| `build` | `pnpm build` (with `NEXT_TELEMETRY_DISABLED=1`) |
+| `runtime` | sets `NODE_ENV=production`, `CONSTELLA_RUN_MODE=vps`, `CONSTELLA_PUBLIC=1`, `CONSTELLA_HOME=/data`; runs as the unprivileged `node` user; `VOLUME ["/data"]`; `EXPOSE 3000` |
+
+Entrypoint:
+
+```dockerfile
+CMD ["node", "bin/constella.mjs", "--vps", "--host", "0.0.0.0", "--port", "3000"]
+```
+
+> **Agent CLIs are NOT bundled in the image.** The Dockerfile note is explicit: for agents on a VPS, either add a `RUN` step that installs a CLI (`claude` / `codex`), or use **cloud API providers** configured in the [MODELS](./MODELS.md) module. See [Security](#security--).
+
+### The stack — `docker-compose.yml`
+
+Two services share one network namespace, so Constella never gets its own public port:
+
+| Service | Image / build | Role |
+| --- | --- | --- |
+| `tailscale` | `tailscale/tailscale:latest` | Sidecar; joins your tailnet headlessly via `TS_AUTHKEY`; `hostname: constella`; persists state in the `tailscale-state` volume |
+| `constella` | `build: .` | The app; `network_mode: service:tailscale` (shares the sidecar's net); persists `/data` in the `constella-data` volume |
+
+`network_mode: service:tailscale` is the security pivot: Constella is reachable **at the Tailscale IP on port 3000** and nowhere else. Both services `restart: unless-stopped`.
+
+```mermaid
+flowchart LR
+  subgraph host["VPS host"]
+    subgraph ns["shared net namespace"]
+      TS["tailscale sidecar<br/>(joins tailnet)"]
+      CN["constella app<br/>:3000, 0.0.0.0"]
+    end
+    V1[("constella-data<br/>/data volume")]
+    V2[("tailscale-state")]
+  end
+  CN --- V1
+  TS --- V2
+  Dev["your device<br/>(same tailnet)"] -. "http://<ts-ip>:3000" .-> TS
+```
+
+### One-command bootstrap — `scripts/vps-install.sh`
+
+For a fresh Ubuntu Server. The script (`set -euo pipefail`) does, in order:
+
+1. **Docker** — `curl -fsSL https://get.docker.com | sh` (only if `docker` is missing).
+2. **Tailscale** — `curl -fsSL https://tailscale.com/install.sh | sh` (only if missing).
+3. `sudo tailscale up` — joins your tailnet (prints a browser auth URL if needed).
+4. **Auth key** — if `.env` lacks `TS_AUTHKEY=`, it prompts you to paste a `tskey-auth-…` key (created at `https://login.tailscale.com/admin/settings/keys`) and appends it to `.env`.
+5. **Up** — `sudo docker compose up -d --build`.
+6. Prints the reachable URL: `http://<tailscale-ip>:3000`.
+
+---
+
+## Step-by-step
+
+### A) VPS deploy from a clone
+
+```bash
+# on the VPS, with the repo cloned
+bash scripts/vps-install.sh
+# → installs Docker + Tailscale, prompts for TS_AUTHKEY, brings the stack up
+```
+
+Or do it manually (mirrors the compose header):
+
+```bash
+# 1. Get a Tailscale auth key:
+#    https://login.tailscale.com/admin/settings/keys
+echo "TS_AUTHKEY=tskey-auth-..." > .env
+# 2. Build + start
+docker compose up -d --build
+# 3. Reach Constella at the node's Tailscale IP:
+#    http://<this-node's-tailscale-ip>:3000
+tailscale ip -4   # find the IP
+```
+
+On first boot the launcher generates and persists `BETTER_AUTH_SECRET` (and the vault + worker secrets) into `/data/.env`. Because `/data` is the `constella-data` named volume, those secrets — and login sessions and the encrypted vault — **survive restarts and rebuilds**.
+
+### B) Portable deploy (USB)
+
+```bash
+npx constella --portable                 # auto-detect & pick a USB drive
+npx constella --portable --path /Volumes/MYUSB   # or name the drive
+```
+
+The launcher validates the drive **before** booting: it **refuses < 32 GB free** (fatal); `≥ 32 GB` boots. Binds `0.0.0.0`. The whole runtime root lives at `<drive>/.constella`. See [PORTABLE_MODE](./PORTABLE_MODE.md).
+
+### C) Global install (own always-on box)
+
+```bash
+npm i -g constella
+constella --auth        # email+password, 127.0.0.1
+# or --start for local auto-login, or --vps on a server you manage
+```
+
+### D) Ephemeral
+
+```bash
+npx constella           # default mode = start
+```
+
+---
+
+## Supervised dual-process boot 🌠
+
+A 24/7 control plane must survive a transient crash. `bin/constella.mjs` boots **two children** and supervises each:
+
+| Process | Command | Hosts |
+| --- | --- | --- |
+| **web** | `next start -H <host> -p <port>` (from `PKG_ROOT`) | the dashboard + all API routes |
+| **worker** | `node bin/worker.mjs` | cron tick (~60s → `POST /api/cron/tick`), chokidar file-watcher (debounce 400ms → `/api/sync/file`), Telegram long-poll |
+
+Supervision rules (from `supervise()`):
+
+- On an unexpected child exit, **auto-restart after 2s** — not a full shutdown.
+- **Crash-loop guard:** at most **5 restarts within 60s** per child; beyond that it gives up and shuts down (so a real, repeated crash isn't masked forever).
+- The web and worker are **independent**: a web crash restarts only the web; the worker self-retries its tick until the server answers.
+- Optional heap bump: `CONSTELLA_WEB_HEAP_MB` adds `--max-old-space-size` to the web child (useful when an agent run causes a JS-heap OOM).
+
+> There is **no systemd unit shipped in the repo** — *not found in current codebase*. The launcher's own supervisor + Docker's `restart: unless-stopped` are the durability layer. If you want OS-level supervision, wrap `constella --vps` (or `--auth`) in your own unit; the process is a normal long-lived foreground command and handles `SIGINT`/`SIGTERM` cleanly (it kills both children, then exits).
+
+The worker carries the privileged `x-worker-secret` header, so it has an **SSRF guard**: it refuses to talk to any non-loopback `CONSTELLA_BASE_URL` unless `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1`. The launcher always points it at `http://127.0.0.1:<port>` (loopback even in vps/portable), so this is invisible in normal deploys.
+
+---
+
+## Run modes vs deploy targets
+
+The **mode** (from `src/lib/run-mode.ts`) sets the bind host and login posture; the **deploy target** sets where it physically runs. They compose:
+
+| Mode | `requiresLogin` | Bind host | Typical deploy target | Agent CLI permission |
+| --- | --- | --- | --- | --- |
+| `start` | false (auto-login `operator@constella.dev`) | `127.0.0.1` | local box / npx | `bypassPermissions` (full) |
+| `auth` | true (email+password) | `127.0.0.1` | local always-on / global install | `acceptEdits` (jailed) |
+| `vps` | true | `0.0.0.0` | **Docker + Tailscale** | `acceptEdits` (jailed) |
+| `portable` | true | `0.0.0.0` | **USB drive** | `acceptEdits` (jailed) |
+
+The mode is persisted in `organization.runMode`. In a published build `CONSTELLA_PUBLIC=1`, so the **UI never picks the mode** — the launch flag does.
+
+---
+
+## Key concepts
+
+- **`CONSTELLA_HOME` / runtime root** — the single durable directory. In Docker it's `/data` (a named volume); on USB it's `<drive>/.constella`; otherwise `~/.constella`. Holds `constella.db`, `.env`, `organizations/<orgId>/workspace/`, `backups/`, `cache/`.
+- **`PKG_ROOT`** — the *installed package* root (compiled `.next`, `drizzle/` migrations, configs). The launcher runs `next` and `drizzle-kit` from here, not from the launch CWD.
+- **Secrets persistence** — every mode persists real secrets to `<HOME>/.env` (`mode 0600`). `next start` runs under `NODE_ENV=production`, where better-auth **throws on a default secret**, so a real `BETTER_AUTH_SECRET` is mandatory even locally.
+- **Schema on first run** — `drizzle-kit migrate` is idempotent. A **fresh DB that fails to migrate aborts** (no tables = the app 500s); an existing DB tolerates a no-op re-run.
+- **Build-on-first-run (fallback only)** — the published package ships a prebuilt `.next`, so building is skipped. From a source tree without a build it builds once; if the build fails it **refuses to fall back to `next dev`** in a public/network mode unless `CONSTELLA_DEV=1`.
+
+---
+
+## Launcher environment
+
+The launcher exports these into both children:
+
+| Variable | Value |
+| --- | --- |
+| `CONSTELLA_RUN_MODE` | `start \| auth \| vps \| portable` |
+| `CONSTELLA_PUBLIC` | `1` (CLI launch is the public runtime) |
+| `CONSTELLA_VERSION` | the installed package version |
+| `CONSTELLA_HOME` | resolved runtime root |
+| `DATABASE_URL` | `file:<HOME>/constella.db` |
+| `CONSTELLA_PKG_ROOT` | the installed package root |
+| `PORT` / `--port` | `3000` (default) |
+| `--host` | `0.0.0.0` for vps/portable, else `127.0.0.1` |
+
+Persisted in `<HOME>/.env` (`chmod 600`): `BETTER_AUTH_SECRET`, `CONSTELLA_VAULT_KEY`, `CONSTELLA_WORKER_SECRET`. Compose-only: `TS_AUTHKEY` (the Tailscale sidecar's join key) in the repo-root `.env`.
+
+Opt-in tuning:
+
+| Variable | Effect |
+| --- | --- |
+| `CONSTELLA_WEB_HEAP_MB` | `--max-old-space-size` for the web child (default: Node default) |
+| `CONSTELLA_DEV=1` | allow a `next dev` fallback when there is no production build |
+| `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` | let the worker talk to a non-loopback base URL (off by default) |
+| `CONSTELLA_WORKER_INTERVAL_MS` | cron tick interval (default `60000`) |
+
+---
+
+## Updating a deployment 🛰️
+
+`detectRunContext()` (`src/lib/run-context.ts`) classifies the running process so the **update method matches the deploy**:
+
+| Context | Detected when | Update method |
+| --- | --- | --- |
+| `dev` | running from source (`isDevMode()`) | `git pull && pnpm install && pnpm build` |
+| `vps` | `getRunMode() === "vps"` **or** `/.dockerenv` exists | `docker compose pull && docker compose up -d` |
+| `portable` | `getRunMode() === "portable"` | ensure free space, back up the drive, then `npm install -g constella@latest` |
+| `npx` | launch dir is npm's `_npx` cache | re-run `npx constella@latest` |
+| `global` | none of the above | `npm install -g constella@latest` (auto-runs, detached) |
+
+`startUpdate()` (`src/server/update-run.ts`) **always backs up first** — it copies `.env`, `constella.db`, `constella.db-wal`, `constella.db-shm` into `<HOME>/backups/<timestamp>/`. Only the `global` path auto-runs (a detached process writes `<HOME>/backups/last-update.json` that the UI polls); `vps` / `portable` / `dev` / `npx` return the **exact command** to run, because executing them from inside the web server is environment-specific. See [UPDATE](./UPDATE.md).
+
+```bash
+# on a VPS:
+docker compose pull && docker compose up -d
+```
+
+Because `/data` (or the USB `.constella`) is a persistent volume, the DB and secrets carry across the update; the launcher's idempotent `drizzle-kit migrate` brings the schema forward on the next boot.
+
+---
+
+## Possible states
+
+| Signal | Meaning |
+| --- | --- |
+| `• Secrets ready (stored in <HOME>/.env, never printed).` | first-boot secret generation/reuse OK |
+| `✖ Portable needs at least 32 GB free …` | portable drive too small (fatal) |
+| `• N GB free on the drive — good …` | portable drive has enough space, boots |
+| `✖ Database schema migration failed on a fresh database — aborting` | fresh DB couldn't get its tables |
+| `• schema migrate skipped/failed on an existing DB — continuing` | benign re-run on a built DB |
+| `✖ No production build … Refusing to start a dev server in a public/network mode.` | no `.next` and no `CONSTELLA_DEV=1` |
+| `• [web] exited (…) — auto-restarting in 2s (n/5 …)` | supervised restart within the window |
+| `✖ [web] exited … crashed 5x within 60s — giving up.` | crash-loop cap hit; shutting down |
+| `✓ Constella is starting. Reach it on your tailnet at: http://<ip>:3000` | `vps-install.sh` finished |
+
+---
+
+## Related integrations 🪐
+
+- **Tailscale** — the private network plane for VPS mode (sidecar container + tailnet IP). See [VPS_MODE](./VPS_MODE.md).
+- **Docker / docker compose** — the runtime + restart policy.
+- **better-auth** — email+password (+ 2FA/passkeys) for every network mode; backed by `BETTER_AUTH_SECRET`. See [AUTH_MODE](./AUTH_MODE.md).
+- **Vault** — provider keys encrypted with `CONSTELLA_VAULT_KEY`. See [SECURITY](./SECURITY.md).
+- **Worker** — cron + watcher + Telegram, supervised alongside the web. See [TELEGRAM](./TELEGRAM.md), [ARCHITECTURE](./ARCHITECTURE.md).
+- **Update** — context-aware self-update. See [UPDATE](./UPDATE.md).
+
+---
+
+## Security 🕳️
+
+- **Tailnet-only exposure.** With compose, Constella shares the Tailscale sidecar's network namespace, so the dashboard is reachable **only at the Tailscale IP on :3000**, never on the public internet. The host port is never published directly.
+- **Unprivileged container user.** The `runtime` stage runs as the built-in `node` user (uid 1000), not root — an app-level RCE can't act as root over `/data`.
+- **Login required on every network mode.** `vps`, `auth`, and `portable` all set `requiresLogin: true` (better-auth email+password, optional 2FA TOTP / WebAuthn passkeys, 30-day session).
+- **Jailed agents off-local.** In `vps`/`auth`/`portable` the agent CLI runs in `acceptEdits` (edits confined to the workspace FS jail), not the `bypassPermissions` of local `start` mode.
+- **Agent CLIs not bundled.** The image deliberately omits `claude`/`codex`. To run agents on a VPS, add a CLI in a `RUN` step or use cloud API providers in [MODELS](./MODELS.md). Without either, planning/Team-Room work, but agent execution has no runtime.
+- **Secrets never printed.** `<HOME>/.env` is `chmod 600`; the launcher logs only its location. `scrubSecrets` strips secrets before KB ingest / Telegram / logs.
+- **Worker SSRF guard.** The worker refuses to send its privileged secret to any non-loopback base URL unless explicitly opted in.
+
+---
+
+## Troubleshooting 🛰️
+
+| Symptom | Cause / fix |
+| --- | --- |
+| Can't reach `http://<ip>:3000` from another device | the device isn't on the same tailnet; run `tailscale up` there, confirm with `tailscale status` |
+| Sidecar won't join | bad/expired `TS_AUTHKEY`; mint a new key and `docker compose up -d` |
+| App restarts in a loop | check the host's RAM — an agent run causing OS-level OOM kills `next start`; raise `CONSTELLA_WEB_HEAP_MB` for a JS-heap OOM, or cap concurrent agents |
+| `✖ drizzle-kit not found …` | the install is incomplete; reinstall the package/rebuild the image |
+| Fresh DB aborts on migrate | shipped `drizzle/` migrations missing or unwritable `/data`; confirm the volume is `node:node`-owned |
+| Agents don't execute on the VPS | no agent CLI in the image and no cloud provider configured — add a CLI `RUN` step or set up [MODELS](./MODELS.md) |
+| Lost sessions/vault after rebuild | `/data` (or USB `.constella`) wasn't a persistent volume; secrets regenerated. Keep the named volume |
+| Portable refuses to boot | drive under 32 GB free — use a larger drive (`--path`) |
+| Update did nothing on a VPS | by design: run `docker compose pull && docker compose up -d` yourself (the UI returns the command) |
+
+---
+
+## Related links
+
+- [VPS_MODE](./VPS_MODE.md) — the tailnet run mode in depth
+- [PORTABLE_MODE](./PORTABLE_MODE.md) — USB-drive deploy
+- [START_MODE](./START_MODE.md) · [AUTH_MODE](./AUTH_MODE.md) — local run modes
+- [INSTALLATION](./INSTALLATION.md) — first install
+- [CONFIGURATION](./CONFIGURATION.md) — env vars + runtime root
+- [UPDATE](./UPDATE.md) — context-aware self-update
+- [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) — deploying the **user project** (clean-tree export), not Constella
+- [ARCHITECTURE](./ARCHITECTURE.md) — web + worker, sync engine
+- [SECURITY](./SECURITY.md) — FS jail, vault, scrubbing
+- [MODELS](./MODELS.md) — cloud/local providers for agents on a server
+- [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)

package/docs/en/DM.md

@@ -0,0 +1,297 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/DM.md) · [✦ Constella](../../README.md)
+
+# Direct Messages — Private Orbits 🛰️✦
+
+![](../assets/divider-orbit.svg)
+
+A **Direct Message** is a private 1:1 channel between you (the operator) and a single agent — its own little orbit, separate from the [Team Room](./TEAM_ROOM.md). DMs carry sessions (fresh contexts on demand), per-session compaction, attachments, Knowledge-Base capture, and — when you talk to a **planner** like Ada — the ability to turn a request into real, approval-gated work.
+
+## When to use
+
+- You want a **focused 1:1** with one agent (the CEO, the CTO, the QA lead, the Docs writer) without pinging the whole room.
+- You want to **start new work** by simply describing it to **@ada** (or another planner) — no loose "new work" button.
+- You want **multiple parallel threads** with the same agent, each with its own fresh context (DM **sessions**).
+- You want to **attach files** (images / PDFs / docs) for one agent to read privately.
+- You want to keep a conversation **out of the autonomous hand-off chain** — DMs never relay to teammates.
+
+> 🪐 Channels at a glance: `room` (everyone, must @mention), `dm:<handle>` (private 1:1, this doc), `telegram` (isolated remote thread → Ada). See [Team Room](./TEAM_ROOM.md), [Chat Commands](./CHAT_COMMANDS.md) and [Telegram](./TELEGRAM.md).
+
+## How it works
+
+Every conversation in Constella lives in a **channel** — a plain string on the `message` table. A DM channel is the literal string `dm:<handle>`, e.g. `dm:ada`, `dm:linus`, `dm:edsger`. The handle after `dm:` is the agent's handle from the roster (see [Agents](./AGENTS.md)).
+
+The DM machinery lives in three files:
+
+| File | Responsibility |
+| --- | --- |
+| `src/server/chat.ts` | Operator-facing actions: `sendMessage`, `agentRespond`, DM **session** actions, clear/previews. |
+| `src/server/collab.ts` | The real agent turn (`replyInChannel`): builds the prompt, runs the CLI, books cost, captures KB. |
+| `src/server/sessions.ts` | DM-session lifecycle: `ensureActiveSession`, `sessionsFor`, `newSession`, `activateSession`, `renameSessionRow`, `deleteSessionRow`. |
+| `src/server/compaction.ts` | `buildChannelContext` — folds older messages into a per-session summary when the channel outgrows the model window. |
+
+### Routing a message to a responder
+
+When you send to a `dm:<handle>` channel, `sendMessage` decides who answers (`src/server/chat.ts`):
+
+```ts
+if (channel.startsWith("dm:")) {
+  const h = channel.slice(3); if (handles.has(h)) responders = [h];
+}
+```
+
+So a DM resolves to **exactly one responder** — the agent named by the channel. Contrast this with:
+
+- **`room`** — the message must `@mention` a real teammate; up to **3** responders (`mentions(...).slice(0, 3)`); an un-mentioned room message is dropped (no dead-end post).
+- **`telegram`** — always routes to **ada** (the CEO), falling back to the first agent if there is no `ada` handle.
+
+After persisting your message, `sendMessage` also: wakes any open SSE stream (`wake`), schedules a RAG re-index of the conversation (`scheduleChatReindex`), and — **only in the `room`** for substantive text (≥15 chars) — logs an operator decision. (DMs do **not** log decisions.)
+
+### The agent's real reply
+
+`agentRespond(channel, handle)` flips the agent to `working`, then calls `replyInChannel` in `collab.ts`, which is where the real work happens:
+
+1. Build a **chat-mode** instruction (DMs are always `mode: "chat"` — conversational, *no file edits*; only the team-room hand-off chain uses `mode: "work"`).
+2. Append clause blocks: a **plan clause** (new-work token, below), an **attachments clause** (read uploaded files), a **language clause** (mirror the operator's language in chat only — everything written to the workspace stays English), plus **REMEMBER** / **CONSULT** / **KB** knowledge clauses, and a **Telegram security clause** (DM channels skip this — it's `telegram`-only).
+3. Assemble ONE model-fitted context bundle (`assembleAgentPrompt`) — mission, project state, decisions, **this session's** conversation (compacted), RAG, memory.
+4. Resolve the runtime (`resolveRuntime`) and run the CLI / HTTP API (`runAgentRuntime`, 180 s timeout), streaming live events to your view.
+5. Strip the new-work token, extract `[[REMEMBER …]]` learnings into the KB, answer `[[CONSULT: …]]` queries (posted back as **Vannevar**), run `[[KB: …]]` tools, **scrub secrets**, and persist the reply on the **active session**.
+6. Book real cost into `costEntry`.
+
+> 🕳️ Crucial difference from the room: at the end, the room fans out the hand-off chain (`relayRoomMentions`), but **DMs stay 1:1** — `if (!channel.startsWith("dm:")) await relayRoomMentions(...)`. An `@mention` inside a DM reply does **not** wake another agent.
+
+## Main flow
+
+```mermaid
+sequenceDiagram
+  actor Op as Operator
+  participant Chat as chat.ts
+  participant Sess as sessions.ts
+  participant Collab as collab.ts (replyInChannel)
+  participant CLI as Agent runtime (claude/codex)
+  participant DB as message / costEntry
+
+  Op->>Chat: sendMessage("dm:linus", text, attachments?)
+  Chat->>Chat: responder = "linus" (single)
+  Chat->>Sess: ensureActiveSession(ws, "dm:linus")
+  Chat->>DB: insert operator message (sessionId)
+  Chat-->>Op: { responders: ["linus"] }
+  Op->>Chat: agentRespond("dm:linus", "linus")
+  Chat->>Collab: replyInChannel(..., mode "chat")
+  Collab->>CLI: run with assembled context bundle
+  CLI-->>Collab: reply text (+ REMEMBER/CONSULT/KB tokens)
+  Collab->>DB: insert agent message (active session) + costEntry
+  Note over Collab: DM → NO relayRoomMentions (stays 1:1)
+  Collab-->>Op: streamed reply
+```
+
+## Key concepts
+
+### DM sessions 🌠
+
+A DM channel can hold **multiple sessions**. A session is a row in `chat_session` scoped to `(workspaceId, channel)`; exactly **one is active** per channel. Starting a new session gives the agent a **fresh context** while you keep every past message visible — you just switch which thread you're looking at.
+
+- `ensureActiveSession(ws, channel)` returns the active session id, lazily creating **"Session 1"** the first time a DM is touched, and **adopting** any legacy null-session messages into it. Returns `null` for non-DM channels (the room and Telegram are single-thread and never get sessions).
+- `newSession` deactivates the others and creates `Session N` (active).
+- `activateSession` switches which session is active.
+- `renameSessionRow` renames (≤60 chars).
+- `deleteSessionRow` deletes the session **and its messages**; if it was active, it activates the newest remaining session (or none — `ensureActiveSession` recreates "Session 1" on the next touch).
+
+`getMessages("dm:<handle>")` and `clearConversation` both scope to the **active session** for DMs, so a new session is a genuinely clean slate.
+
+### Compaction (per session) 🌌
+
+When a conversation outgrows the active model's context window, `buildChannelContext` (`compaction.ts`) folds the **older** messages into a structured summary and keeps only the most recent ones verbatim. For DMs this is **scoped to the active session** (`sessionId`), so each thread compacts independently:
+
+```ts
+const msgConds = [eq(message.workspaceId, workspaceId), eq(message.channel, channel)];
+if (sessionId) msgConds.push(eq(message.sessionId, sessionId));
+```
+
+- The summary is **model-aware** — smaller models get a tighter (~150-word) summary, larger ones keep more detail (~350 words).
+- Sections are fixed: `## Decisions`, `## Requirements`, `## Open issues`, `## Files`, `## Pending by agent`, `## Next steps`.
+- Summarization runs on a **cheap model (`haiku`)** and books real cost.
+- One `message_summary` row per `(workspace, channel, session)`; it stores `throughId` (last folded message) so an unchanged window is reused, not re-summarized.
+- The compacted block is also linked into `.claude/memory.md` (one section per channel), best-effort.
+
+### New work from a DM 🚀
+
+This is the signature DM feature. **New work is born from the conversation with the CEO — not a loose button.** In **chat mode**, any agent's prompt includes a **plan clause**: if the operator is asking to **BUILD / IMPLEMENT / ADD / FIX / CHANGE** something (a new unit of work), the agent confirms in 1–2 sentences and emits, on a final separate line, the machine token:
+
+```
+[[CREATE_WORK]]
+```
+
+`collab.ts` defines this as `const CREATE_WORK = "[[CREATE_WORK]]"`. `replyInChannel` detects it (`planRequested`) and **strips it** before the reply is stored or shown. Back in `chat.ts`, `agentRespond` reacts:
+
+```ts
+if (planRequested) {
+  const r = await planFromConversation(channel);
+  // posts a short "registering this as new work…" confirmation back into the DM
+}
+```
+
+`planFromConversation(channel)` (in `src/server/planner.ts`) takes the **last 30 messages** of the channel and runs the **same planning ritual as the first plan** — Ada (the CEO) drafts a Goal → specs → issues → TODOs, appended to the **CEO Planner** for your approval. (For the Telegram remote, the off-session twin is `planFromConversationFor` in `planner-core.ts`.)
+
+> 🌠 Planner vs non-planner. The plan clause is offered to **every** agent, but the wording differs:
+> - **Planners** (`isPlanner`: the CEO **ada**, the Product Owner **donald**, the CTO **linus** — or any role matching *product owner* / *CTO* / *chief tech*) get a direct "turn this into a spec + issues" instruction.
+> - **Non-planners** get an extra reassurance: it *"runs through the CEO's planning ritual and waits for the operator's approval, so you're not committing anyone to build immediately."*
+>
+> Either way the request is **routed through the CEO's planner and gated by your approval** — no code is built directly from a DM. See [Goals, Specs & Issues](./GOALS_SPECS_ISSUES.md) and [Workflow](./WORKFLOW.md).
+
+### Knowledge capture in a DM 🌌
+
+Even in a private DM the agent can grow the shared brain (see [KB Agent](./KB_AGENT.md) and [KB & RAG](./KB_RAG.md)):
+
+| Token (own line) | Effect |
+| --- | --- |
+| `[[REMEMBER type=<decision\|architecture\|business-rule\|integration\|fix\|note>: <fact>]]` | Auto-saved to the KB (deduped), token stripped from the shown reply. |
+| `[[CONSULT: <question>]]` | Answered from the state-aware KB; the answer is posted back into the DM **as Vannevar**. |
+| `[[KB: reindex \| index-chat \| health]]` | KB-agent maintenance (only the Knowledge role gets this clause); result reported back into the thread. |
+
+You can also promote a single chat line into the KB with `sendMessageToKb(messageId)` (captured as a `note`), or pull KB context into the composer with `pullKbForComposer(query)` (draft only — never sends).
+
+## Tables
+
+### `chat_session` (`src/db/schema.ts`)
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text | FK → `workspace`, cascade delete. |
+| `channel` | text | Always `dm:<handle>` (DM only). |
+| `title` | text | Defaults to `Session N`; rename ≤60 chars. |
+| `active` | boolean | Exactly one active per `(workspace, channel)`. |
+| `createdAt` | timestamp | Newest-first ordering for the session list. |
+
+### `message` (DM-relevant columns)
+
+| Column | Notes |
+| --- | --- |
+| `channel` | `room` \| `dm:<handle>` \| `telegram`. |
+| `fromKind` | `operator` \| `agent`. |
+| `fromHandle` | The agent handle (null for operator). |
+| `text` | Message body (agent replies stored ≤4000 chars). |
+| `sessionId` | The `chat_session` this message belongs to. **NULL** for room/Telegram and legacy DM messages (backfilled to "Session 1"). |
+| `sources` | RAG source chips for an agent reply. |
+| `attachments` | Operator uploads (≤10/message): `{ name, type, size, path }`. |
+| `taskId` / `kind` / `blocks` | Traceability chip / render hint / synced-block slugs. |
+
+### `message_summary`
+
+| Column | Notes |
+| --- | --- |
+| `channel` | The conversation summarized. |
+| `sessionId` | DM session this summary covers; **NULL** for room/Telegram. |
+| `summary` | Structured compacted context. |
+| `throughId` | Last message folded in (reuse guard). |
+| `msgCount` | Number of messages folded. |
+
+## New-work-from-DM diagram
+
+```mermaid
+flowchart TD
+  A["Operator DMs @ada:\n'build a CSV export'"] --> B["sendMessage('dm:ada', …)\nresponder = ada"]
+  B --> C["agentRespond → replyInChannel\n(mode: chat, plan clause ON)"]
+  C --> D{"Operator asking to\nBUILD / FIX / CHANGE?"}
+  D -- "No" --> E["Normal 1:1 reply\n(stays in the DM)"]
+  D -- "Yes" --> F["Reply confirms + emits\n[[CREATE_WORK]] on last line"]
+  F --> G["token stripped\nplanRequested = true"]
+  G --> H["planFromConversation(channel)\nlast 30 messages → brief"]
+  H --> I["CEO planning ritual:\nGoal → specs → issues → TODOs"]
+  I --> J["Appended to CEO Planner\n(awaits operator approval)"]
+  J --> K["'Plan ready' streams back\ninto the DM"]
+```
+
+## Step-by-step
+
+### Start new work from a DM
+
+1. Open the DM with **@ada** (CEO) — or another planner like **@linus** / **@donald**.
+2. Describe the work plainly: *"Build a settings page with a dark-mode toggle."*
+3. Ada confirms ("registering this as new work…") and the heavy plan run starts detached.
+4. A **"Plan ready"** message streams back into the DM when specs + issues are drafted.
+5. Approve in the **CEO Planner** (or via `/approve` — see [Chat Commands](./CHAT_COMMANDS.md)). Approval is what authorizes the team to build.
+
+### Manage DM sessions
+
+1. In a DM, open the session list (newest first; one active).
+2. **New session** → fresh agent context, old threads preserved (`createSession`).
+3. **Switch** between sessions (`switchSession`); **rename** (`renameSession`); **delete** (`deleteSession`, confirmed by a modal).
+4. **Clear conversation** in a DM wipes only the **active session's** messages + its summary — other sessions are untouched.
+
+### Attach a file to a DM
+
+1. Add up to 10 files to the composer; they are saved under `uploads/` in the workspace.
+2. The agent's prompt gains an attachments clause pointing at the on-disk **paths**; it reads them with its file tools (images/PDFs supported).
+3. Filenames are treated as **data, not instructions** (prompt-injection guard).
+
+## Examples
+
+```text
+# DM with @ada — kicks off new work
+You → @ada: We need a CSV export on the reports page.
+Ada → Got it — I'll turn this into a spec + issues and register it for approval. [[CREATE_WORK]] (stripped)
+Ada → Got it — registering this as new work. I'm drafting the plan now…
+
+# DM with @edsger (QA lead) — a question, NOT new work → normal reply, no token
+You → @edsger: What did the last test run flag on /login?
+Edsger → The last run flagged 1 console error on /login (uncaught TypeError)…
+
+# Non-planner routing a build request still goes through Ada's planner
+You → @grace: Add a loading spinner to the dashboard.
+Grace → I'll register this as new work — it runs through the CEO's planning ritual and waits for your approval. [[CREATE_WORK]] (stripped)
+```
+
+## Possible states
+
+| State | Meaning |
+| --- | --- |
+| Responder resolved | DM channel `dm:<h>` → single responder `h` if the handle exists; otherwise `responders: []`. |
+| `mode: "chat"` | DM replies are conversational — **no file edits**, no hand-off chain. |
+| `planRequested = true` | Agent emitted `[[CREATE_WORK]]`; `planFromConversation` runs the ritual. |
+| Active session | One `chat_session.active = true` per DM; drives reads, writes, compaction, clear. |
+| Compacted | Older messages folded into `message_summary` for the active session. |
+| Agent `working` / `idle` | `agentRespond` sets `working` during the turn, back to `idle` after. |
+
+## Related integrations
+
+- **[Team Room](./TEAM_ROOM.md)** — the shared channel; the `@mention` hand-off chain (which DMs deliberately avoid).
+- **[Telegram](./TELEGRAM.md)** — the isolated remote thread that always talks to Ada; mirrors back from the in-app Telegram tab.
+- **[Chat Commands](./CHAT_COMMANDS.md)** — slash commands work in DMs too (intercepted before the message path; not on Telegram).
+- **[Goals, Specs & Issues](./GOALS_SPECS_ISSUES.md)** / **[Workflow](./WORKFLOW.md)** — where DM-born work lands and is approved.
+- **[KB & RAG](./KB_RAG.md)** / **[Memory & RAG](./MEMORY_RAG.md)** — REMEMBER/CONSULT capture and conversation re-indexing.
+- **[Inbox](./INBOX.md)** — operator pings raised when an agent addresses you (skipped on Telegram).
+
+## Security
+
+- **Secret scrubbing** — every reply (room, DM, Telegram) is passed through `scrubSecrets` before it is stored, shown or notified.
+- **Attachments are data** — uploaded filenames/paths are wrapped as data; the prompt tells the model to ignore any directive embedded in a filename.
+- **Prompt-injection hardening** is strongest on `telegram` (untrusted remote input); DMs are local operator input but still scrubbed and language-/workspace-jailed.
+- **DMs don't fan out** — an `@mention` in a DM reply never wakes another agent, so a private thread can't spawn an autonomous chain.
+- **No direct build from chat** — a DM can only *register* work; nothing executes until you approve the plan. See [Security](./SECURITY.md) and [AI Architecture](./AI_ARCHITECTURE.md) for the FS jail and permission modes.
+
+## Troubleshooting
+
+| Symptom | Likely cause / fix |
+| --- | --- |
+| The agent didn't reply in my DM | The handle after `dm:` must exist in the roster; a stray channel string yields `responders: []`. Check the handle in [Agents](./AGENTS.md). |
+| I asked for a build but no plan appeared | The model judged it a question, not new work, so it didn't emit `[[CREATE_WORK]]`. Be explicit: *"Build/implement/fix …"*. The DM should then post a "registering this as new work…" line. |
+| New session still shows old messages | You're viewing a previous session — switch to the active one. Reads are scoped to the active `chat_session`. |
+| "Clear conversation" didn't clear everything | In a DM, clear only wipes the **active session**; other sessions persist by design. |
+| An `@mention` in my DM did nothing | Correct — DMs are 1:1 and never relay. Use the [Team Room](./TEAM_ROOM.md) for hand-offs. |
+| Old context keeps coming back | That's the per-session compacted summary (`message_summary`) being injected. Start a fresh session for a clean context. |
+| Reply timed out | The runtime cap is 180 s; very heavy single turns may hit it. |
+
+## Related links
+
+- [Team Room](./TEAM_ROOM.md)
+- [Chat Commands](./CHAT_COMMANDS.md)
+- [Telegram](./TELEGRAM.md)
+- [Agents](./AGENTS.md)
+- [Goals, Specs & Issues](./GOALS_SPECS_ISSUES.md)
+- [Workflow](./WORKFLOW.md)
+- [KB & RAG](./KB_RAG.md)
+- [Memory & RAG](./MEMORY_RAG.md)
+- [Inbox](./INBOX.md)
+- [AI Architecture](./AI_ARCHITECTURE.md)
+- [Security](./SECURITY.md)