@openparachute/agent 0.1.1 → 0.2.0

package/docs/db-central.md

@@ -1,316 +0,0 @@
-# parachute-agent — Central DB Schema
-
-Complete reference for `~/.parachute/agent/agent.db`, the host-owned admin-plane database. Start with [db.md](db.md) for the three-DB overview, the map, and the cross-mount rules.
-
-Access layer: `src/db/`. Authoritative schema reference: `src/db/schema.ts` (comments only — actual creation runs via migrations in `src/db/migrations/`).
-
----
-
-## 1. Tables
-
-### 1.1 `agent_groups`
-
-Agent workspaces. Each maps 1:1 to a `groups/<folder>/` directory containing `CLAUDE.md`, skills, and `container.json`. Container config lives on disk, not in the DB.
-
-```sql
-CREATE TABLE agent_groups (
-  id               TEXT PRIMARY KEY,
-  name             TEXT NOT NULL,
-  folder           TEXT NOT NULL UNIQUE,
-  agent_provider   TEXT,
-  created_at       TEXT NOT NULL
-);
-```
-
-- **Readers:** `src/session-manager.ts`, `src/delivery.ts`, `src/router.ts`
-- **Writers:** `src/db/agent-groups.ts`
-
-### 1.2 `messaging_groups`
-
-One row per platform chat (one WhatsApp group, one Slack channel, one 1:1 DM, etc.).
-
-```sql
-CREATE TABLE messaging_groups (
-  id                    TEXT PRIMARY KEY,
-  channel_type          TEXT NOT NULL,
-  platform_id           TEXT NOT NULL,
-  name                  TEXT,
-  is_group              INTEGER DEFAULT 0,
-  unknown_sender_policy TEXT NOT NULL DEFAULT 'strict',
-  created_at            TEXT NOT NULL,
-  UNIQUE(channel_type, platform_id)
-);
-```
-
-- `unknown_sender_policy`: `strict` (drop), `request_approval` (ask admin), `public` (allow).
-- **Readers:** `src/router.ts`, `src/delivery.ts`, `src/session-manager.ts`
-- **Writers:** `src/db/messaging-groups.ts`, channel setup flows
-
-### 1.3 `messaging_group_agents`
-
-Wiring: which agent group handles which messaging group. Many-to-many — the same channel can route to multiple agents (see [isolation-model.md](isolation-model.md)).
-
-```sql
-CREATE TABLE messaging_group_agents (
-  id                 TEXT PRIMARY KEY,
-  messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
-  agent_group_id     TEXT NOT NULL REFERENCES agent_groups(id),
-  trigger_rules      TEXT,
-  response_scope     TEXT DEFAULT 'all',
-  session_mode       TEXT DEFAULT 'shared',
-  priority           INTEGER DEFAULT 0,
-  created_at         TEXT NOT NULL,
-  UNIQUE(messaging_group_id, agent_group_id)
-);
-```
-
-- `session_mode`: `shared` (one session per channel), `per-thread` (one per thread), `agent-shared` (one per agent group across all channels).
-- `trigger_rules`: JSON; e.g. regex for native channels.
-- **Side effect:** creating a wiring must also populate `agent_destinations` — don't mutate one without the other (see §1.10).
-
-### 1.4 `users`
-
-Platform user identities. ID is namespaced: `tg:123456`, `discord:abc`, `phone:+1555...`, `email:a@x.com`. One human may own several rows — no cross-channel linking yet.
-
-```sql
-CREATE TABLE users (
-  id           TEXT PRIMARY KEY,
-  kind         TEXT NOT NULL,
-  display_name TEXT,
-  created_at   TEXT NOT NULL
-);
-```
-
-- **Writers/readers:** `src/db/users.ts`; channel auth flows
-
-### 1.5 `user_roles`
-
-Permissions. **Privilege is user-level, never agent-group-level.**
-
-```sql
-CREATE TABLE user_roles (
-  user_id        TEXT NOT NULL REFERENCES users(id),
-  role           TEXT NOT NULL,
-  agent_group_id TEXT REFERENCES agent_groups(id),
-  granted_by     TEXT REFERENCES users(id),
-  granted_at     TEXT NOT NULL,
-  PRIMARY KEY (user_id, role, agent_group_id)
-);
-CREATE INDEX idx_user_roles_scope ON user_roles(agent_group_id, role);
-```
-
-Invariants:
-- `role = 'owner'` → must be global (`agent_group_id IS NULL`). Enforced in `grantRole()`.
-- `role = 'admin'` → global (NULL) or scoped to one agent group.
-- Admin @ A implies membership in A — no `agent_group_members` row required.
-
-Access layer: `src/db/user-roles.ts`, `src/access.ts`.
-
-### 1.6 `agent_group_members`
-
-Explicit membership for non-privileged users. Owner and admins don't need rows here — they're implicit members.
-
-```sql
-CREATE TABLE agent_group_members (
-  user_id        TEXT NOT NULL REFERENCES users(id),
-  agent_group_id TEXT NOT NULL REFERENCES agent_groups(id),
-  added_by       TEXT REFERENCES users(id),
-  added_at       TEXT NOT NULL,
-  PRIMARY KEY (user_id, agent_group_id)
-);
-```
-
-### 1.7 `user_dms`
-
-Cache of DM channel discovery. Lets the host send a cold DM (approval card, pairing code) without hitting the platform's `openConversation` API every time.
-
-```sql
-CREATE TABLE user_dms (
-  user_id            TEXT NOT NULL REFERENCES users(id),
-  channel_type       TEXT NOT NULL,
-  messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
-  resolved_at        TEXT NOT NULL,
-  PRIMARY KEY (user_id, channel_type)
-);
-```
-
-Populated lazily by `ensureUserDm()` in `src/user-dm.ts`.
-
-### 1.8 `sessions`
-
-Session registry. One row per (agent group, messaging group, thread) tuple subject to `session_mode`. Stores lifecycle metadata only — no messages.
-
-```sql
-CREATE TABLE sessions (
-  id                 TEXT PRIMARY KEY,
-  agent_group_id     TEXT NOT NULL REFERENCES agent_groups(id),
-  messaging_group_id TEXT REFERENCES messaging_groups(id),
-  thread_id          TEXT,
-  agent_provider     TEXT,
-  status             TEXT DEFAULT 'active',
-  container_status   TEXT DEFAULT 'stopped',
-  last_active        TEXT,
-  created_at         TEXT NOT NULL
-);
-CREATE INDEX idx_sessions_agent_group ON sessions(agent_group_id);
-CREATE INDEX idx_sessions_lookup     ON sessions(messaging_group_id, thread_id);
-```
-
-- **Resolved by:** `resolveSession()` in `src/session-manager.ts`.
-- Creating a session also provisions the session folder and both session DBs via `initSessionFolder()` — see [db-session.md](db-session.md).
-
-### 1.9 `pending_questions`
-
-The `ask_user_question` MCP tool parks an interactive question here, and the container matches incoming `system` messages back to it by `questionId`.
-
-```sql
-CREATE TABLE pending_questions (
-  question_id    TEXT PRIMARY KEY,
-  session_id     TEXT NOT NULL REFERENCES sessions(id),
-  message_out_id TEXT NOT NULL,
-  platform_id    TEXT,
-  channel_type   TEXT,
-  thread_id      TEXT,
-  title          TEXT NOT NULL,
-  options_json   TEXT NOT NULL,
-  created_at     TEXT NOT NULL
-);
-```
-
-### 1.10 `agent_destinations`
-
-Permission ACL *and* name-resolution map for outbound sending. An agent asking to `send_message(to="dev-channel")` must have a row here with `local_name = 'dev-channel'`, or the send is rejected as `unknown destination`.
-
-```sql
-CREATE TABLE agent_destinations (
-  agent_group_id TEXT NOT NULL REFERENCES agent_groups(id),
-  local_name     TEXT NOT NULL,
-  target_type    TEXT NOT NULL,   -- 'channel' | 'agent'
-  target_id      TEXT NOT NULL,   -- messaging_group_id | agent_group_id
-  created_at     TEXT NOT NULL,
-  PRIMARY KEY (agent_group_id, local_name)
-);
-CREATE INDEX idx_agent_dest_target ON agent_destinations(target_type, target_id);
-```
-
-**Projection invariant (load-bearing).** The central table is the source of truth, but each running container reads from a projection in its own `inbound.db` (see [db-session.md §2.3](db-session.md#23-destinations)). Any code that mutates `agent_destinations` while a container is running must also call `writeDestinations()` (`src/session-manager.ts`) or the container will reject sends with stale data. Known call sites: `createMessagingGroupAgent()` in `src/db/messaging-groups.ts`, the `create_agent` system action in `src/delivery.ts`.
-
-Access layer: `src/db/agent-destinations.ts`.
-
-### 1.11 `pending_approvals`
-
-Session-bound MCP approvals (`install_packages`, `add_mcp_server`) — `session_id` is set; `agent_group_id` + `channel_type` + `platform_id` columns route the admin card and let non-session-bound flows share the table without a schema change.
-
-```sql
-CREATE TABLE pending_approvals (
-  approval_id         TEXT PRIMARY KEY,
-  session_id          TEXT REFERENCES sessions(id),
-  request_id          TEXT NOT NULL,
-  action              TEXT NOT NULL,
-  payload             TEXT NOT NULL,
-  created_at          TEXT NOT NULL,
-  agent_group_id      TEXT REFERENCES agent_groups(id),
-  channel_type        TEXT,
-  platform_id         TEXT,
-  platform_message_id TEXT,
-  expires_at          TEXT,
-  status              TEXT NOT NULL DEFAULT 'pending',
-  title               TEXT NOT NULL DEFAULT '',
-  options_json        TEXT NOT NULL DEFAULT '[]'
-);
-CREATE INDEX idx_pending_approvals_action_status ON pending_approvals(action, status);
-```
-
-- `status`: `pending` | `approved` | `rejected` | `expired`.
-- `platform_message_id` lets the host edit the admin card in place after a decision.
-- Access layer: `src/db/sessions.ts`; sweep + delivery: `src/modules/approvals/`.
-
-### 1.12 `unregistered_senders`
-
-Audit trail: every time a message gets dropped (unknown sender, strict policy), we increment a counter here so admins can see who's been trying to knock.
-
-```sql
-CREATE TABLE unregistered_senders (
-  channel_type       TEXT NOT NULL,
-  platform_id        TEXT NOT NULL,
-  user_id            TEXT,
-  sender_name        TEXT,
-  reason             TEXT NOT NULL,
-  messaging_group_id TEXT,
-  agent_group_id     TEXT,
-  message_count      INTEGER NOT NULL DEFAULT 1,
-  first_seen         TEXT NOT NULL,
-  last_seen          TEXT NOT NULL,
-  PRIMARY KEY (channel_type, platform_id)
-);
-CREATE INDEX idx_unregistered_senders_last_seen ON unregistered_senders(last_seen);
-```
-
-Writer: `recordDroppedMessage()` in `src/db/dropped-messages.ts`. On conflict, bumps `message_count` + `last_seen`.
-
-### 1.13 Chat SDK bridge tables
-
-State backing the `SqliteStateAdapter` used by the Chat SDK bridge (see [api-details.md](api-details.md)). parachute-agent code rarely touches these directly — they're owned by `src/state-sqlite.ts`.
-
-```sql
-CREATE TABLE chat_sdk_kv (
-  key        TEXT PRIMARY KEY,
-  value      TEXT NOT NULL,
-  expires_at INTEGER                    -- unix ts, nullable
-);
-
-CREATE TABLE chat_sdk_subscriptions (
-  thread_id     TEXT PRIMARY KEY,
-  subscribed_at TEXT NOT NULL DEFAULT (datetime('now'))
-);
-
-CREATE TABLE chat_sdk_locks (
-  thread_id  TEXT PRIMARY KEY,
-  token      TEXT NOT NULL,
-  expires_at INTEGER NOT NULL
-);
-
-CREATE TABLE chat_sdk_lists (
-  key        TEXT NOT NULL,
-  idx        INTEGER NOT NULL,
-  value      TEXT NOT NULL,
-  expires_at INTEGER,
-  PRIMARY KEY (key, idx)
-);
-```
-
-### 1.14 `schema_version`
-
-Migration ledger, written by the migration runner (§2).
-
-```sql
-CREATE TABLE schema_version (
-  version INTEGER PRIMARY KEY,
-  name    TEXT NOT NULL,
-  applied TEXT NOT NULL
-);
-```
-
----
-
-## 2. Migration system
-
-Migrations live in `src/db/migrations/`, one file per migration. Runner: `runMigrations()` in `src/db/migrations/index.ts`. It:
-
-1. Creates `schema_version` if absent.
-2. Reads `MAX(version)` — call it `current`.
-3. For each migration with `version > current`, executes `up(db)` inside a transaction and appends a `schema_version` row.
-
-| # | File | Introduces |
-|---|------|------------|
-| 001 | `001-initial.ts` | Core tables: `agent_groups`, `messaging_groups`, `messaging_group_agents`, `users`, `user_roles`, `agent_group_members`, `user_dms`, `sessions`, `pending_questions` |
-| 002 | `002-chat-sdk-state.ts` | `chat_sdk_kv`, `chat_sdk_subscriptions`, `chat_sdk_locks`, `chat_sdk_lists` |
-| 003 | `003-pending-approvals.ts` | `pending_approvals` (session-bound + non-session routing fields) |
-| 004 | `004-agent-destinations.ts` | `agent_destinations` + backfill from existing `messaging_group_agents` wirings |
-| 007 | `007-pending-approvals-title-options.ts` | `ALTER TABLE pending_approvals` add `title`, `options_json` (retrofits DBs created between 003 and 007) |
-| 008 | `008-dropped-messages.ts` | `unregistered_senders` |
-| 009 | `009-drop-pending-credentials.ts` | Drop the defunct `pending_credentials` table |
-
-Numbers 005 and 006 are intentionally absent — migrations were renumbered during early development.
-
-Session DB schemas (`INBOUND_SCHEMA`, `OUTBOUND_SCHEMA`) are **not** versioned here. They're `CREATE TABLE IF NOT EXISTS` so new columns land via the session-DB lazy migration helpers (`migrateDeliveredTable()` etc.) when a session file from an older build is reopened. See [db-session.md](db-session.md).

package/docs/db-session.md

@@ -1,183 +0,0 @@
-# parachute-agent — Per-Session DB Schema
-
-Reference for the two SQLite files each session owns: `inbound.db` (host writes, container reads) and `outbound.db` (container writes, host reads). Start with [db.md](db.md) for the three-DB overview, the single-writer rule, and the cross-mount visibility constraints.
-
-Schemas live in `src/db/schema.ts` as the `INBOUND_SCHEMA` and `OUTBOUND_SCHEMA` constants. Both files are created by `ensureSchema()` in `src/session-manager.ts` when a new session folder is provisioned.
-
----
-
-## 1. Session folder layout
-
-```
-data/sessions/<agent_group_id>/<session_id>/
-  inbound.db              ← host writes, container reads (read-only mount)
-  outbound.db             ← container writes, host reads (read-only open)
-  .heartbeat              ← mtime touched by container (not a DB write)
-  inbox/<message_id>/     ← user attachments, decoded from inbound message content
-  outbox/<message_id>/    ← attachments the agent produced
-```
-
-One session = one folder = one pair of DBs. The `agent_group_id` parent directory also holds per-group state (`.claude-shared/`, `agent-runner-src/`) that is shared across every session of that agent group.
-
-Path helpers in `src/session-manager.ts`: `sessionDir()`, `inboundDbPath()`, `outboundDbPath()`, `heartbeatPath()`.
-
----
-
-## 2. Inbound DB (`inbound.db`)
-
-Host-owned, container-read-only. Schema constant: `INBOUND_SCHEMA` in `src/db/schema.ts`.
-
-### 2.1 `messages_in`
-
-Every message landing in the session: user chat, scheduled task, recurring task, question response, internal system message.
-
-```sql
-CREATE TABLE messages_in (
-  id            TEXT PRIMARY KEY,
-  seq           INTEGER UNIQUE,           -- EVEN only (host assigns) — see §3
-  kind          TEXT NOT NULL,
-  timestamp     TEXT NOT NULL,
-  status        TEXT DEFAULT 'pending',   -- pending|completed|failed|paused
-  process_after TEXT,
-  recurrence    TEXT,                     -- cron expr for recurring
-  series_id     TEXT,                     -- groups occurrences of a recurring task
-  tries         INTEGER DEFAULT 0,
-  platform_id   TEXT,
-  channel_type  TEXT,
-  thread_id     TEXT,
-  content       TEXT NOT NULL             -- JSON; shape depends on kind
-);
-CREATE INDEX idx_messages_in_series ON messages_in(series_id);
-```
-
-Content shapes: see [api-details.md §Session DB Schema Details](api-details.md#session-db-schema-details).
-
-**Writers (host):** `insertMessage()`, `insertTask()`, `insertRecurrence()` — all in `src/db/session-db.ts`. Each calls `nextEvenSeq()`.
-**Reader (container):** `container/agent-runner/src/db/messages-in.ts` — polls `status='pending' AND (process_after IS NULL OR process_after <= now)`.
-
-### 2.2 `delivered`
-
-Host writes here after handing a `messages_out` row to the channel adapter. Container reads `platform_message_id` to target edits and reactions.
-
-```sql
-CREATE TABLE delivered (
-  message_out_id      TEXT PRIMARY KEY,
-  platform_message_id TEXT,
-  status              TEXT NOT NULL DEFAULT 'delivered',  -- delivered|failed
-  delivered_at        TEXT NOT NULL
-);
-```
-
-Writer: `markDelivered()` / `markDeliveryFailed()` in `src/db/session-db.ts`. Older session DBs are brought up to schema lazily by `migrateDeliveredTable()`.
-
-### 2.3 `destinations`
-
-Projection of the central `agent_destinations` table (see [db-central.md §1.10](db-central.md#110-agent_destinations)) for this session's agent. The container resolves `to="name"` against this table; if the row is absent, the send is rejected as `unknown destination`.
-
-```sql
-CREATE TABLE destinations (
-  name           TEXT PRIMARY KEY,
-  display_name   TEXT,
-  type           TEXT NOT NULL,   -- 'channel' | 'agent'
-  channel_type   TEXT,            -- for type='channel'
-  platform_id    TEXT,            -- for type='channel'
-  agent_group_id TEXT             -- for type='agent'
-);
-```
-
-Rewritten wholesale (DELETE + INSERT in a transaction) by `writeDestinations()` on every container wake and on demand when wiring changes mid-session. The comment on the table in `src/db/schema.ts` is the canonical statement of the refresh semantics.
-
-### 2.4 `session_routing`
-
-Single-row (`id=1`) default routing: where outbound messages go when the agent doesn't specify a destination.
-
-```sql
-CREATE TABLE session_routing (
-  id           INTEGER PRIMARY KEY CHECK (id = 1),
-  channel_type TEXT,
-  platform_id  TEXT,
-  thread_id    TEXT
-);
-```
-
-Written by `writeSessionRouting()` on every container wake, derived from `sessions.messaging_group_id` + `sessions.thread_id`.
-
----
-
-## 3. Sequence numbering invariant
-
-Every message (in or out) gets a monotonic integer `seq`, unique *within the session* across both tables.
-
-- **Host writes even seq** (2, 4, 6, …) to `messages_in` — `nextEvenSeq()` at `src/db/session-db.ts:75`.
-- **Container writes odd seq** (1, 3, 5, …) to `messages_out` — logic at `container/agent-runner/src/db/messages-out.ts:54` (`max % 2 === 0 ? max + 1 : max + 2`), reading `MAX(seq)` across *both* tables to preserve global ordering.
-
-Why disjoint? `seq` is the agent-facing message ID. When the agent calls `edit_message(seq=5)` or `add_reaction(seq=6)`, `getMessageIdBySeq()` uses the parity to route the lookup: odd → `messages_out`, even → `messages_in`. The parity alone disambiguates without a join. Collisions would break editing.
-
-If you add a code path that writes to either table, preserve parity — the invariant isn't enforced by a constraint, only by the two helper functions.
-
----
-
-## 4. Outbound DB (`outbound.db`)
-
-Container-owned, host reads only. Schema constant: `OUTBOUND_SCHEMA` in `src/db/schema.ts`.
-
-### 4.1 `messages_out`
-
-Everything the agent produces: chat replies, edits, reactions, cards, question sends, agent-to-agent messages, system actions.
-
-```sql
-CREATE TABLE messages_out (
-  id            TEXT PRIMARY KEY,
-  seq           INTEGER UNIQUE,   -- ODD only (container assigns) — see §3
-  in_reply_to   TEXT,
-  timestamp     TEXT NOT NULL,
-  deliver_after TEXT,
-  recurrence    TEXT,
-  kind          TEXT NOT NULL,    -- chat|chat-sdk|system|…
-  platform_id   TEXT,
-  channel_type  TEXT,
-  thread_id     TEXT,
-  content       TEXT NOT NULL     -- JSON; operation lives inside (edit/reaction/card/…)
-);
-```
-
-Content shapes: see [api-details.md §Session DB Schema Details](api-details.md#session-db-schema-details).
-
-**Writer (container):** `writeMessageOut()` in `container/agent-runner/src/db/messages-out.ts`.
-**Readers (host):** `src/delivery.ts` (polling delivery), `getMessageIdBySeq()` / `getRoutingBySeq()` for edit/reaction targeting.
-
-### 4.2 `processing_ack`
-
-Container-side status for each `messages_in.id` it has touched. The host polls this and syncs status back into `messages_in` — this avoids the container ever writing to `inbound.db`.
-
-```sql
-CREATE TABLE processing_ack (
-  message_id     TEXT PRIMARY KEY,
-  status         TEXT NOT NULL,      -- processing|completed|failed
-  status_changed TEXT NOT NULL
-);
-```
-
-Crash recovery: on container startup, stale `processing` entries get cleared. Host-side sync: `syncProcessingAcks()` in `src/host-sweep.ts`.
-
-### 4.3 `session_state`
-
-Persistent container-owned KV store. Main consumer is the Chat SDK session ID — storing it here lets the agent's conversation resume across container restarts. Cleared by `/clear`.
-
-```sql
-CREATE TABLE session_state (
-  key        TEXT PRIMARY KEY,
-  value      TEXT NOT NULL,
-  updated_at TEXT NOT NULL
-);
-```
-
-Access: `container/agent-runner/src/db/session-state.ts`.
-
----
-
-## 5. Schema evolution
-
-Unlike the central DB, session DBs do **not** go through numbered migrations. Both `INBOUND_SCHEMA` and `OUTBOUND_SCHEMA` use `CREATE TABLE IF NOT EXISTS`, so a fresh session always gets the current shape. For session folders created under older builds, column-level gaps are patched lazily on open — e.g. `migrateDeliveredTable()` in `src/db/session-db.ts` adds `platform_message_id` and `status` to the `delivered` table if missing.
-
-If you add a column to either schema, add a matching lazy migration for existing session folders, and prefer nullable columns or defaulted values so no data backfill is required.

package/docs/db.md

@@ -1,119 +0,0 @@
-# parachute-agent Database Architecture — Overview
-
-Orientation for the data model: the three databases, how they fit together, and the invariants that hold across them. For table-level schemas, follow the links below.
-
-- **[db-central.md](db-central.md)** — every table in the central DB (identity, wiring, approvals, Chat SDK state) plus the migration system.
-- **[db-session.md](db-session.md)** — the per-session `inbound.db` + `outbound.db` pair, seq parity, and session folder layout.
-
-Related: [architecture.md](architecture.md) for the high-level design; [api-details.md](api-details.md) for inbound/outbound message content shapes; [isolation-model.md](isolation-model.md) for channel-to-agent wiring modes.
-
----
-
-## 1. The three databases
-
-parachute-agent uses **three kinds of SQLite database**, all on the host filesystem:
-
-| DB | Location | Writer | Readers | Purpose |
-|----|----------|--------|---------|---------|
-| **Central** | `~/.parachute/agent/agent.db` | host | host | Identity, permissions, routing, wiring — the admin plane |
-| **Session inbound** | `data/sessions/<agent_group_id>/<session_id>/inbound.db` | host | host (sync), container (read-only) | Host → container messages + routing projections |
-| **Session outbound** | `data/sessions/<agent_group_id>/<session_id>/outbound.db` | container | host (poll), container | Container → host messages + processing status |
-
-**Single-writer rule.** Every SQLite file has exactly one writer. Host writes the central DB and every `inbound.db`; container writes only its own `outbound.db`. This eliminates write contention across the Docker/Apple Container mount boundary — SQLite locking across that boundary is unreliable.
-
-**Everything is a message.** There is no IPC, stdin piping, or file watcher between host and container. The two session DBs are the sole IO surface. Heartbeat is a file `touch(2)` on `.heartbeat`, not a DB write.
-
-**Journal mode.** Session DBs use `journal_mode = DELETE` (not WAL). Cross-mount WAL visibility is a bug farm; DELETE mode + open-write-close forces the page cache to flush so the other side sees changes.
-
----
-
-## 2. Database map
-
-```
-~/.parachute/agent/agent.db               ← CENTRAL (host ↔ host)
-data/
-  sessions/
-    <agent_group_id>/
-      .claude-shared/                     ← shared Claude state for the agent group
-      agent-runner-src/                   ← per-group agent-runner overlay
-      <session_id>/
-        inbound.db                        ← host writes, container reads
-        outbound.db                       ← container writes, host reads
-        .heartbeat                        ← mtime touched by container
-        inbox/<message_id>/               ← decoded user attachments
-        outbox/<message_id>/              ← attachments the agent produced
-```
-
-Path helpers: `sessionDir()`, `inboundDbPath()`, `outboundDbPath()`, `heartbeatPath()` — all in `src/session-manager.ts`.
-
----
-
-## 3. Central vs. session: what goes where
-
-| Kind of data | Where | Why |
-|--------------|-------|-----|
-| Identities, roles, memberships | central | Stable, cross-session, rarely written |
-| Channel wiring, routing rules | central | Admin plane |
-| Destination ACL | central (+ projection per session) | Source of truth centrally; fast local lookup per session |
-| Session registry (ids, status) | central | Host orchestrates lifecycle |
-| Approvals & pending questions | central | Survive container restarts, admin-visible |
-| Dropped-message audit | central | Global ops view |
-| Inbound messages, retry state | session `inbound.db` | Per-session workload; host is sole writer |
-| Outbound messages, agent state | session `outbound.db` | Container is sole writer; host polls |
-| Delivery outcome | session `inbound.db` (`delivered`) | Host writes on success; container reads for edit targeting |
-| Processing status | session `outbound.db` (`processing_ack`) | Container can't write to `inbound.db` |
-
-Heuristic: if the value is a message, routing projection, or runtime ack, it goes per-session. Everything else is central.
-
----
-
-## 4. Cross-mount visibility
-
-Session DBs are bind-mounted into the container. A few rules you need to know before touching the DB code:
-
-- **`journal_mode = DELETE`, not WAL.** WAL files don't reliably cross the mount and the container can read stale pages. DELETE mode forces each writer to flush the main file.
-- **Open-write-close on the host.** Host-side writes to `inbound.db` open a connection, write, and close it. Keeping a handle open makes cached pages invisible to the container.
-- **Container reads read-only.** The container opens `inbound.db` with `readonly: true` and never writes — all container→host state goes through `outbound.db` (see `processing_ack` in [db-session.md](db-session.md#52-processing_ack)).
-- **Heartbeat is a file touch.** `.heartbeat` mtime is the liveness signal, not a DB column. A DB write per heartbeat would serialize behind other writers.
-
-These rules are enforced by convention in `src/session-manager.ts` and `container/agent-runner/src/db/`. If you change how the DBs are opened, re-read that code first.
-
----
-
-## 5. Design patterns at a glance
-
-1. **Two-DB session split.** `inbound.db` and `outbound.db` each have one writer, one direction of flow — no cross-mount lock contention.
-2. **Seq parity.** Even = host, odd = container. Disjoint namespace across both tables lets the agent reference any message by `seq` alone. Details in [db-session.md §3](db-session.md#3-sequence-numbering-invariant).
-3. **Projection pattern.** `agent_destinations` and `session_routing` are projected from the central DB into each session's `inbound.db` on container wake — the container gets a fast, local read path without querying across the mount.
-4. **Ack via reverse channel.** Container never writes to `inbound.db`. Status sync happens through `processing_ack` in `outbound.db`, which the host polls and reconciles.
-5. **Heartbeat out of band.** File `touch` on `.heartbeat`, not a DB write, so liveness doesn't serialize behind other writers.
-6. **Lazy session-DB migrations.** Central DB uses numbered migrations; per-session DBs use `IF NOT EXISTS` + ad-hoc `ALTER TABLE` helpers for older session folders.
-7. **ACL = row existence.** `agent_destinations` membership is itself the permission — no separate `permissions` table.
-
----
-
-## 6. Readers & writers — at a glance
-
-| Table | DB | Writer(s) | Reader(s) |
-|-------|----|-----------|-----------|
-| `agent_groups` | central | `src/db/agent-groups.ts` | session resolver, delivery, router |
-| `messaging_groups` | central | `src/db/messaging-groups.ts`, channel setup | router, delivery, session resolver |
-| `messaging_group_agents` | central | `src/db/messaging-groups.ts` | router |
-| `users` | central | `src/db/users.ts`, auth flows | permission checks |
-| `user_roles` | central | `src/db/user-roles.ts` | `src/access.ts`, all permission gates |
-| `agent_group_members` | central | `src/db/agent-group-members.ts` | membership checks |
-| `user_dms` | central | `src/user-dm.ts` (`ensureUserDm`) | approval + pairing delivery |
-| `sessions` | central | `src/db/sessions.ts`, `src/session-manager.ts` | delivery, sweep, container runner |
-| `pending_questions` | central | `src/db/sessions.ts` (via `ask_user_question`) | container response matcher |
-| `agent_destinations` | central | `src/db/agent-destinations.ts`, migration 004 backfill | `writeDestinations()`, delivery ACL |
-| `pending_approvals` | central | `src/db/sessions.ts`, `src/modules/approvals/` | admin-card delivery, sweep |
-| `unregistered_senders` | central | `src/db/dropped-messages.ts` | ops tooling |
-| `chat_sdk_*` | central | `src/state-sqlite.ts` | Chat SDK bridge |
-| `schema_version` | central | `src/db/migrations/index.ts` | migration runner |
-| `messages_in` | inbound | `src/db/session-db.ts` | `container/agent-runner/src/db/messages-in.ts` |
-| `delivered` | inbound | `src/db/session-db.ts` (`markDelivered`) | container edit/reaction targeting |
-| `destinations` | inbound | `writeDestinations()` in `src/session-manager.ts` | container routing / ACL |
-| `session_routing` | inbound | `writeSessionRouting()` in `src/session-manager.ts` | container `send_message` defaults |
-| `messages_out` | outbound | `container/agent-runner/src/db/messages-out.ts` | `src/delivery.ts` poll loop |
-| `processing_ack` | outbound | `container/agent-runner/src/db/messages-in.ts` | `src/host-sweep.ts` (`syncProcessingAcks`) |
-| `session_state` | outbound | `container/agent-runner/src/db/session-state.ts` | container on startup |