mercury-agent 0.4.26 → 0.4.28

package/README.md

@@ -19,7 +19,7 @@ Mercury is a personal AI assistant that lives where you chat. It connects to Wha
 
 - **[Node.js](https://nodejs.org/)** >= 18 — Required for `npm install -g mercury-agent`
 - **[Bun](https://bun.sh)** >= 1.0 — JavaScript runtime used by Mercury
-- **[Docker](https://docs.docker.com/get-docker/)** — Required for running agent containers
+- **[Docker](https://docs.docker.com/get-docker/)** — Required for running agent containers. On Linux, also install `docker-buildx` (`apt-get install docker-buildx`) — Docker Desktop includes it, but Docker Engine on Linux does not.
 - **Windows users:** Mercury runs best under [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install). Install WSL2 with `wsl --install`, then install Bun and Docker inside it.
 
 ## Quick Start
@@ -131,6 +131,7 @@ Each space is a user-defined memory boundary with its own workspace and pi sessi
 | **Media** | Images, documents, voice notes | [docs/media/overview.md](docs/media/overview.md) |
 | **KB Distillation** | Extract lasting knowledge from chats | [docs/kb-distillation.md](docs/kb-distillation.md) |
 | **Extensions** | TypeScript plugins for CLIs, skills, jobs, hooks | [docs/extensions.md](docs/extensions.md) |
+| **DM Auto-Space** | Auto-create isolated spaces per customer DM | [docs/rate-limiting.md](docs/rate-limiting.md) |
 
 ---
 
@@ -377,6 +378,28 @@ Supported OAuth providers: Anthropic, GitHub Copilot, Google Gemini CLI, Antigra
 | `MERCURY_TRIGGER_PATTERNS` | `@Mercury,Mercury` | Trigger patterns |
 | `MERCURY_ADMINS` | — | Pre-seeded admin user IDs |
 
+### DM Auto-Space
+
+Auto-create isolated spaces for each customer who DMs your bot. Each customer gets their own space with persistent context, configurable permissions, and rate limits.
+
+```yaml
+# mercury.yaml
+dm_auto_space:
+  enabled: true
+  admin_ids:                                    # platform IDs — auto-link to "main" space
+    - "24417056866472"                          # WhatsApp LID, Telegram user ID, etc.
+  default_system_prompt: "You are a helpful assistant."
+  default_member_permissions: "prompt,prefs.get"  # restrict customers to chat only
+
+runtime:
+  rate_limit_daily_member: 20                   # global daily cap for members (0 = unlimited)
+  rate_limit_daily_admin: 0                     # global daily cap for admins (0 = unlimited)
+```
+
+`admin_ids` values are platform-specific identifiers — check the dashboard Conversations page to see the format (e.g. WhatsApp LID digits, Telegram numeric user ID).
+
+Auto-created spaces are seeded with `trigger.match=always`, `context.mode=context`, and the configured member permissions. Per-space rate limits are manageable from the dashboard.
+
 ### Per-space Config
 
 Conversations are discovered from incoming traffic. Unlinked conversations stay idle until you attach them to a space via `mercury link <conversation-id> <space-id>` or the dashboard.

package/docs/ROADMAP.md

@@ -10,7 +10,7 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 
 | Item | Doc | Notes |
 |------|-----|-------|
-| — | — | — |
+| **business-extensions** | [doc](ideas/business-extensions.md) | Dedicated business extensions wrapping raw capabilities with deterministic logic |
 
 ## Now
 
@@ -26,7 +26,8 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 |---|------|-----|-----------|---------|
 | 1 | **autonomous-planning-tier** | [doc](backlog/autonomous-planning-tier.md) | — | Let agents decompose ideas, keep human gate |
 | 2 | **dm-auto-space** | [doc](backlog/dm-auto-space.md) | — | Auto-create space per customer DM |
-| 3 | **applicative-profiles** | [doc](backlog/applicative-profiles.md) | — | Generic profile layer for business logic scoping |
+| 3 | **applicative-profiles** | [doc](backlog/applicative-profiles.md) | caller-bound-capability-token | Generic profile layer; host-side broker keeps secrets off customer containers |
+| 4 | **caller-bound-capability-token** | [doc](backlog/caller-bound-capability-token.md) | — | Per-turn token so brokers can trust callerId; also hardens TradeStation |
 
 ## Later
 

package/docs/backlog/applicative-profiles.md

@@ -9,199 +9,184 @@
 
 ## Goal
 
-Mercury's existing profile system (`src/core/profiles.ts`) is a static provisioning mechanism — it bundles extensions, AGENTS.md, env vars, and config defaults into a deployable template. But it has no runtime behavior: it can't scope which capabilities members access, enforce data isolation (ownership), or declare capability dependencies. Business workflows (appointment booking, customer management) require deterministic logic that can't be reliably delegated to the LLM.
+Mercury's existing profile system (`src/core/profiles.ts`) is a static provisioning mechanism — it bundles extensions, AGENTS.md, env vars, and config defaults into a deployable template. It has no runtime behavior: it can't scope which capabilities members access, keep secrets out of an untrusted member's container, or enforce per-user ownership. Business workflows (appointment booking, customer management) require deterministic logic that the LLM cannot be trusted to enforce.
 
-Applicative Profiles extend the existing profile system with a **runtime contract** — a profile declares what capabilities it wraps, what commands it exposes to members, and what isolation rules it enforces. Mercury provides the schema, loader, and runtime enforcement; profiles live in external repos. The barber-appointments profile is the first implementation to validate the design.
+Applicative Profiles extend the profile system with a **runtime contract**: a profile declares the capabilities it wraps, the commands it exposes to members, and its member permission set — and its privileged work runs **host-side**, behind an authenticated broker, so credentials never enter a customer-controlled container. Mercury (public repo) provides the schema, permission scoping, and broker mechanism; the actual business profiles live in a **separate private repo**. The barber-appointments profile is the first implementation and the design driver.
+
+### Security framing (why the naive design fails)
+
+Mercury's security model today **trusts whoever it hands a tool to** — appropriate because tool-callers have historically been admins. Two facts make a naive "wrap GWS in an extension" approach unsafe for customer-facing profiles:
+
+1. **The permission guard is bypassable.** It's a regex denylist on CLI names (`src/extensions/permission-guard.ts`) that the project documents as defense-in-depth only (`docs/TODOS.md` TODO-2). It cannot stop `printenv`, `cat /proc/self/environ`, `curl`, `python -c`, etc.
+2. **Member role does not remove bash.** Role only controls which CLIs are denied and which env vars are injected (`src/core/runtime.ts:1343-1376`); whether bash exists is decided by *model capability*, not role. So a member on a tool-capable model can read any env var in their container.
+
+Therefore **any credential injected into a customer's container is readable by that customer.** The only safe design keeps the credential on the host — which Mercury already does for TradeStation (see Architecture).
 
 ## User Stories
 
-- As a Mercury operator, I want to install a profile package from an external repo so my bot gains domain-specific business logic without modifying Mercury core.
-- As a barber shop owner, I want my customers (DM members) to book and cancel only their own appointments through the bot, without seeing other customers' schedules.
-- As a barber shop owner, I want my customers to have zero access to my Gmail, even though the profile uses my GWS credentials for calendar access internally.
-- As a profile developer, I want a clear schema/contract for defining profiles so I know what to implement (commands, permissions, capability dependencies, data isolation rules).
-- As a Mercury admin, I want raw capability extensions (GWS, web search) to remain admin-only while the profile's scoped commands are member-facing.
+- As a Mercury operator, I want to install a profile from an external repo so my bot gains domain-specific business logic without modifying Mercury core.
+- As a barber shop owner, I want customers (DM members) to book and cancel only their **own** appointments, never seeing others' schedules.
+- As a barber shop owner, I want customers to have **zero** access to my Gmail/Google account, even though the profile uses my Google credentials for Calendar internally.
+- As a profile developer, I want a clear schema + a host-side broker pattern so I can enforce ownership on the host where the real `callerId` is trustworthy.
+- As a Mercury admin, I want raw capability extensions (GWS, web search) to stay admin-only while the profile's scoped commands are member-facing.
 
 ## MVP Scope
 
-**In scope:**
-- Extend `mercury-profile.yaml` schema with runtime fields: `capabilities` (required extensions), `member_permissions` (exhaustive permission list for members), and `system_prompt` (profile-specific agent persona)
+**In scope (all in `mercury-public`):**
+- Extend `mercury-profile.yaml` schema with runtime fields: `capabilities` (required host-side extensions), `member_permissions` (exhaustive member permission set), `system_prompt` (agent persona)
 - Profile-aware permission resolution — when a profile is active, member permissions come from the profile, not from extension defaults
-- Capability dependency validation — profile apply fails if required extensions aren't installed
-- Profile activation per space — a space can have an active profile that governs its runtime behavior
-- `CALLER_ID` injection — profile extensions receive the caller's identity so they can enforce ownership in their CLI code
-- Barber-appointments profile (separate repo) as the first implementation to validate the design
+- Capability-dependency validation — activation fails if a required capability isn't installed
+- A **host-side capability broker** convention: profile capabilities execute on the host (credentials in host storage), invoked from the container via the existing `mrctl`→control-plane-API channel — following the proven TradeStation pattern
+- Depends on [[caller-bound-capability-token]] so the broker can trust `callerId` for ownership checks
 
 **Out of scope (deferred):**
-- Profile marketplace/registry — profiles are installed manually (npm/bun add or git clone) for now
-- Profile versioning/migration — no schema version negotiation yet
-- Multi-profile per space — one profile per space for MVP
+- The actual barber business logic (availability rules, 2-barber support, per-number appointment limits) — lives in the **private profiles repo**, not here
+- Profile marketplace/registry — profiles are installed manually (git clone / package) for now
+- Profile versioning/migration — no schema-version negotiation yet
+- Multi-profile per space — one active profile per deployment for MVP
 - Profile UI in dashboard — managed via config/YAML only
-- Declarative data isolation rules — ownership enforcement is in profile extension code, not a schema declaration (too domain-specific for a generic schema in v1)
+- Declarative ownership rules — ownership is enforced in the profile's host-side route code using the trusted `callerId`, not a generic schema (too domain-specific for v1)
 
 ---
 
 ## Context for Claude
 
-> Key files to read before touching anything.
-
-- `src/core/profiles.ts` — Existing profile system: `profileSchema`, `loadProfileFromDir()`, `applyProfile()`, `resolveProfileSource()`. Bundles extensions + AGENTS.md + env + defaults into `.mercury/`
-- `src/extensions/types.ts` — Extension type system: `MercuryExtensionAPI`, `ExtensionMeta`, `PermissionDef`, `CliDef`, `EnvDef`. The API surface extensions use during setup
-- `src/core/permissions.ts` — Permission resolution: `getRolePermissions()`, `registerPermission()`, `resolveRole()`. Role-based (admin/member) per space with extension-registered defaults
-- `src/extensions/permission-guard.ts` — Container-side enforcement: reads `MERCURY_DENIED_CLIS` env var and blocks unauthorized CLI calls
-- `src/extensions/loader.ts` — `ExtensionRegistry` class: scans `.mercury/extensions/`, validates, runs setup functions, collects `ExtensionMeta`
+- `src/core/profiles.ts` — Existing profile system: `profileSchema`, `loadProfileFromDir()`, `applyProfile()` (project-level, no DB/space). Extended here
+- `src/core/permissions.ts` — `getRolePermissions()`, `registerPermission()`, `resolveRole()`. Role-based (admin/member) per space
+- `src/core/runtime.ts` — Container spawn: denied-CLI computation + per-permission env injection at 1343-1376
+- `src/extensions/permission-guard.ts` — Bypassable CLI-name denylist (see `docs/TODOS.md` TODO-2)
+- `src/core/routes/tradestation.ts` + `src/tradestation/host-api.ts` — **The reference broker.** Container calls `mrctl tradestation order` → host route executes with a token from `db.getExtState(...)`, never exposing it to the container ("keeps order placement off the agent container"). Includes a caller-bound confirm guard (153-158, 245-254)
+- `src/core/api.ts` — Control-plane API + auth middleware (35-75) that broker routes mount onto
+- `src/cli/mrctl.ts` — In-container CLI that calls the host API (the container→host transport)
 
 ---
 
 ## Architecture & Data
 
-### Data Models
+### The four parts (and where each lives)
+
+| Part | Repo | What |
+|------|------|------|
+| 1. Profile schema + permission scoping | `mercury-public` | New `mercury-profile.yaml` fields; profile-aware member permissions |
+| 2. Host-side capability broker | `mercury-public` | Profile capabilities run host-side via `mrctl`→API, à la TradeStation; secrets stay on host |
+| 3. Per-turn caller token | `mercury-public` | [[caller-bound-capability-token]] — trustworthy `callerId` on the host (dependency) |
+| 4. Barber business logic | **private profiles repo** | Availability, 2 barbers, per-number limits, ownership rules — the moat |
 
-Extend the existing `profileSchema` in `src/core/profiles.ts`:
+### Part 1 — Schema + permission scoping
+
+Extend `profileSchema` in `src/core/profiles.ts` (all new fields optional → backward compatible):
 
 ```typescript
-// New fields added to profileSchema
 const profileSchema = z.object({
-  // ... existing fields ...
-  name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
-  description: z.string().optional(),
-  version: z.string().default("0.1.0"),
-  agents_md: z.string().optional(),
-  extensions: z.array(profileExtensionSchema).default([]),
-  env: z.array(profileEnvVarSchema).default([]),
-  defaults: profileDefaultsSchema.optional(),
-
-  // NEW — runtime applicative fields
-  capabilities: z.array(z.string()).default([]),          // required raw extensions (e.g. ["gws"])
-  member_permissions: z.array(z.string()).optional(),     // exhaustive member permission list when profile is active
-  system_prompt: z.string().optional(),                   // profile-specific agent persona
+  // ... existing: name, description, version, agents_md, extensions, env, defaults ...
+  capabilities: z.array(z.string()).default([]),        // required host-side capability extensions, e.g. ["gws"]
+  member_permissions: z.array(z.string()).optional(),   // EXHAUSTIVE member permission set when active
+  system_prompt: z.string().optional(),                 // profile persona
 });
 ```
 
-New DB storage — per-space active profile tracking via existing `space_config`:
-- Key: `profile.active` — value: profile name (e.g. `"barber-appointments"`)
-- Key: `profile.member_permissions` — value: comma-separated permission list from the profile manifest
+Activation is **project-wide** (a deployment runs one profile — the "app"), stored in `space_config` on `main` / applied to member-facing spaces:
+- `profile.active` — profile name
+- `profile.member_permissions` — comma-separated list from the manifest
+
+Permission resolution (`getRolePermissions()`): when `profile.member_permissions` is set, that is the **complete** member set — no extension defaults merged in. Admin/system unchanged (all). Consequence: raw `gws` is absent from the member set, so its CLI is denied **and** its env vars are withheld from member containers (`runtime.ts:1360`).
 
-No new tables or migrations needed.
+**`system_prompt` precedence** (highest wins): per-space `system_prompt` override → profile `system_prompt` → global AGENTS.md.
 
-### How it works at runtime
+### Part 2 — Host-side capability broker (the core security mechanism)
 
-1. **Profile apply** (`applyProfile()` extended): copies extensions + AGENTS.md (existing behavior), then validates that all `capabilities` are installed as extensions, and stores the profile's `member_permissions` in a resolvable location.
+This is the crux, and it reuses an existing, production-proven pattern rather than inventing one.
 
-2. **Permission resolution** (`getRolePermissions()` extended): when a space has `profile.active` set, member permissions come from `profile.member_permissions` instead of the default `prompt + prefs.get + extension defaults`. Admin permissions are unchanged (all). This means raw capabilities (e.g., `gws`) stay admin-only unless the profile explicitly lists them in `member_permissions`.
+**How TradeStation already does it (the template):**
+- Container runs `mrctl tradestation order …` → `POST /api/tradestation/orders`
+- The route runs **on the host** (`src/core/routes/tradestation.ts`) using an OAuth token read from host storage (`db.getExtState(...)`, `src/tradestation/host-api.ts:27`) — the token **never enters the container**
 
-3. **Capability scoping**: the profile's own extensions call `mercury.permission({ defaultRoles: ["member"] })` to make their commands member-accessible. Raw capability extensions (e.g., `gws`) are NOT in `member_permissions`, so their CLIs are denied by `permission-guard.ts`. The profile extension uses the raw capability internally (server-side hooks, or by passing credentials via env vars that only the extension code — not the container — can access).
+**The barber broker is the same shape, Calendar-flavored:**
+- New host routes (e.g. `POST /api/barber/availability|book|cancel`, `GET /api/barber/my-appointments`) mounted on the existing API (`src/core/api.ts`)
+- New `mrctl` (or thin profile-CLI) subcommands the member agent invokes
+- Host route calls Google Calendar using credentials in **host storage** (`extension_state` / host env) — never injected into the customer container
+- Ownership enforced host-side: the route filters/authorizes by the **token-derived** `callerId` (Part 3), so a customer can only see/cancel their own appointments
 
-4. **Data isolation / ownership**: handled in the profile extension's CLI code. The container already receives `CALLER_ID` (the platform user ID). The profile's CLI checks the caller against the data before acting (e.g., "does this appointment belong to this caller?"). This is intentionally not a generic schema — it's too domain-specific.
+**Why Gmail is safe:** the customer container gets neither the `gws` CLI nor any Google credential. Even if the customer reads every env var in their container, there is no secret there — only a per-turn token scoped to themselves. Calendar access happens on the host; Gmail is never wired into the broker at all.
 
-5. **Gmail protection**: the `gws` extension exposes both Calendar and Gmail CLIs. When the barber profile is active, `member_permissions` does NOT include `gws`, so the permission guard blocks all `gws` CLI calls for members. The barber extension accesses Calendar server-side (via hooks or its own env vars) — members never touch GWS directly.
+### Part 3 — Trustworthy caller identity (dependency)
 
-### Example: barber-appointments profile
+The broker's ownership checks require a `callerId` the customer cannot forge. Today `callerId` arrives as a spoofable header gated only by a shared `API_SECRET` (`api.ts:50-72`). [[caller-bound-capability-token]] mints a per-turn token bound to `{callerId, spaceId}` at spawn and makes it authoritative host-side. **This feature depends on that one landing** (or shipping together).
+
+### Part 4 — Barber business logic (private repo)
+
+Lives in `tagula-agent-profiles` (or similar). Contains the `mercury-profile.yaml`, the agent persona, and the host-side route implementations' business rules (availability windows, 2-barber scheduling, per-number booking limits, double-booking prevention). Consumes Parts 1-3 as the public contract; never touches `mercury-public`.
+
+### Example manifest (in the private repo)
 
 ```yaml
-# mercury-profile.yaml (in separate repo)
 name: barber-appointments
 description: Appointment booking for a barber shop
 version: 0.1.0
-
 agents_md: ./AGENTS.md
-
-capabilities:
-  - gws                    # requires GWS extension installed (for Calendar)
-
-extensions:
-  - name: barber
-    source: ./extensions/barber
-
-member_permissions:
-  - prompt
-  - prefs.get
-  - barber                 # only the barber extension — NOT gws
-
-env:
-  - key: MERCURY_BARBER_BUSINESS_HOURS
-    description: "Business hours (e.g. 09:00-18:00)"
-    default: "09:00-18:00"
-  - key: MERCURY_BARBER_SLOT_DURATION
-    description: "Appointment slot duration in minutes"
-    default: "30"
-
+capabilities: [gws]                 # Calendar via host-side broker
+member_permissions: [prompt, prefs.get, barber]   # barber only — NOT gws
 system_prompt: |
-  You are a barber shop assistant. Help customers book, view, and cancel
-  their appointments. You can only help each customer with their own
-  appointments — never reveal other customers' schedules.
-
+  You are a barber shop assistant. Help each customer book, view, and cancel
+  ONLY their own appointments. Never reveal other customers' schedules.
 defaults:
-  trigger_patterns: "always"
+  trigger_patterns: always
 ```
 
-The barber extension (`./extensions/barber/index.ts`):
-- Calls `mercury.cli({ name: "barber", ... })` — installs a CLI with subcommands: `barber book`, `barber availability`, `barber cancel`, `barber my-appointments`
-- Calls `mercury.permission({ defaultRoles: ["member"] })` — members can use the `barber` CLI
-- The CLI internally uses GWS Calendar API (via env var credentials) but filters results by `CALLER_ID`
-- Members NEVER see the `gws` CLI — it's blocked by the permission guard
-
-### API Contracts
-
-No new HTTP API endpoints. Profile activation is done via:
-1. `mercury.yaml` — `profile: barber-appointments` (static config)
-2. `space_config` — `profile.active: barber-appointments` (per-space override)
-
 ### File & Folder Structure
 
 | Path | New / Modified | Purpose |
 |------|---------------|---------|
-| `src/core/profiles.ts` | Modified | Extend `profileSchema` with `capabilities`, `member_permissions`, `system_prompt`. Add validation in `applyProfile()` |
-| `src/core/permissions.ts` | Modified | Profile-aware `getRolePermissions()` — check `profile.member_permissions` for the space |
-| `src/config.ts` | Modified | Add `profile` config key for static profile activation |
-| `src/config-file.ts` | Modified | Add `profile` to YAML schema and env mapping |
-| `tests/applicative-profiles.test.ts` | New | Tests for profile permission scoping and capability validation |
+| `src/core/profiles.ts` | Modified | Extend `profileSchema`; validate `capabilities`; write `profile.*` to `space_config` |
+| `src/core/permissions.ts` | Modified | Profile-aware `getRolePermissions()` |
+| `src/config.ts` / `src/config-file.ts` | Modified | `profile` config key for activation |
+| `src/core/api.ts` | Modified | Mount profile broker routes (generic mounting point) |
+| `src/core/routes/` | New (per profile capability) | Host-side broker routes — pattern mirrors `tradestation.ts` |
+| `tests/applicative-profiles.test.ts` | New | Permission scoping + capability validation tests |
 
 ### Implementation Sequence
 
-1. **Extend profile schema** — Add `capabilities`, `member_permissions`, `system_prompt` to `profileSchema` in `profiles.ts`. These are optional fields so existing profiles remain valid.
+1. **Extend profile schema** — add `capabilities`, `member_permissions`, `system_prompt` (optional).
    - Read first: `src/core/profiles.ts`
-   - Verify: `bun run typecheck` passes
-
-2. **Add capability validation** — In `applyProfile()`, after copying extensions, check that every entry in `capabilities` has a matching directory in `.mercury/extensions/`. Throw a clear error if a required capability is missing.
+   - Verify: `bun run typecheck`; existing profiles still parse
+2. **Capability validation** — in `applyProfile()`, fail loudly if any `capabilities` entry has no matching extension.
    - Read first: `src/core/profiles.ts`, `src/extensions/loader.ts`
-   - Verify: `bun run typecheck` passes
+   - Verify: apply throws on missing capability; passes when present
    - Blocker: Step 1
-
-3. **Store profile activation in space_config** — When `applyProfile()` runs for a space, write `profile.active` and `profile.member_permissions` to `space_config`. Add `profile` config key to `config.ts` / `config-file.ts` for static activation.
+3. **Activation + config** — write `profile.active` / `profile.member_permissions` to `space_config`; add `profile` config key.
    - Read first: `src/config.ts`, `src/config-file.ts`, `src/storage/db.ts`
-   - Verify: `bun run typecheck` passes
+   - Verify: `space_config` reflects active profile
    - Blocker: Step 1
-
-4. **Profile-aware permission resolution** — In `getRolePermissions()`, when the space has `profile.member_permissions` set, use that as the member permission set instead of the default. Admin/system roles unchanged.
+4. **Profile-aware permissions** — `getRolePermissions()` uses `profile.member_permissions` as the exhaustive member set.
    - Read first: `src/core/permissions.ts`
-   - Verify: `bun run typecheck` passes
-   - Blocker: Step 3
-
-5. **System prompt injection** — When a profile has `system_prompt`, inject it via the existing `before_container` hook mechanism or config seeding (same pattern as `dm-auto-space`'s `default_system_prompt`).
-   - Read first: `src/core/runtime.ts`, `src/extensions/hooks.ts`
-   - Verify: `bun run typecheck` passes
+   - Verify: member gets only profile perms; admin unchanged; `gws` CLI denied + env withheld for members
    - Blocker: Step 3
-
-6. **Write tests** — Profile permission scoping: member gets only profile-declared permissions; admin gets all; raw capability blocked for members. Capability validation: apply fails when required extension missing. Profile activation: space_config correctly set.
+5. **Caller token dependency** — land [[caller-bound-capability-token]] (or ship together) so brokers can trust `callerId`.
+   - Verify: broker route reads token-derived caller; spoofed header ignored
+   - Blocker: separate doc
+6. **Broker route pattern** — document + provide the mounting point and a reference so a profile's host-side routes follow `tradestation.ts` (host-held creds, caller-bound authorization).
+   - Read first: `src/core/routes/tradestation.ts`, `src/tradestation/host-api.ts`, `src/core/api.ts`
+   - Verify: a sample broker route executes host-side, credential never injected into the container
+   - Blocker: Steps 4, 5
+7. **Tests** — scoping (member/admin/raw-capability), capability validation, activation.
    - Read first: `tests/permissions.test.ts`
-   - Verify: `bun test` passes
-   - Blocker: Steps 1-5
-
-7. **Update example config** — Add commented `profile` section to `mercury.example.yaml`.
-   - Read first: `resources/templates/mercury.example.yaml`
-   - Verify: file contains the new section
+   - Verify: `bun test`
+   - Blocker: Steps 1-6
+8. **Example config** — commented `profile` section in `mercury.example.yaml`.
+   - Verify: file contains the section
 
 ---
 
 ## Non-Negotiable Rules
 
-- **Profiles are external** — Mercury core provides the schema, loader, and runtime. No specific profile (barber, etc.) lives in this repo.
-- **Member permissions are exhaustive** — When a profile declares `member_permissions`, that is the COMPLETE set. No extension defaults are merged in. This prevents capability leakage.
-- **Admin permissions unchanged** — Admins always get all permissions regardless of profile. Profiles scope members only.
-- **Capability validation is strict** — `applyProfile()` must fail loudly if a required capability extension is not installed. Silent degradation is not acceptable.
-- **Data isolation is code, not config** — Ownership enforcement happens in the profile extension's CLI code, not in a declarative schema. The extension checks `CALLER_ID` before acting.
-- **Backward compatible** — Existing profiles without the new fields continue to work exactly as before. All new fields are optional.
-- **No Gmail exposure** — When a profile wraps GWS for Calendar access, the raw `gws` CLI (which includes Gmail) must be blocked for members via permission scoping.
+- **Profiles are external** — no specific business profile (barber, etc.) lives in `mercury-public`. Only schema, scoping, and broker mechanism.
+- **Credentials never enter a member container** — capability credentials live in host storage and are used only by host-side broker routes. This is the whole point; violating it re-opens the Gmail leak.
+- **Member permissions are exhaustive** — a profile's `member_permissions` is the COMPLETE set; no extension defaults merged. Prevents capability leakage.
+- **Ownership is enforced host-side with the trusted `callerId`** — never with a container-supplied argument, never by prompting the LLM.
+- **Admin permissions unchanged** — admins always get all permissions; profiles scope members only.
+- **Capability validation is strict** — activation fails loudly if a required capability extension is missing.
+- **Backward compatible** — existing profiles and existing brokers keep working; all new fields optional; token path is additive.
+- **Do not rely on the permission guard as a security boundary** — it is bypassable (TODO-2). Security comes from *not putting secrets in the container*, not from blocking CLIs.
 
 ---
 
@@ -209,36 +194,37 @@ No new HTTP API endpoints. Profile activation is done via:
 
 | Scenario | Handling |
 |----------|---------|
-| Profile declares `member_permissions: ["nonexistent"]` | `isValidPermission()` filters invalid names. Log a warning but don't crash — the invalid permission is silently dropped. |
-| Profile requires capability `gws` but it's not installed | `applyProfile()` throws with a clear error listing missing capabilities. |
-| Admin manually overrides `role.member.permissions` per space | Per-space override in `space_config` takes precedence over profile defaults (existing behavior). Profile sets the baseline; admin can further restrict or expand. |
-| Profile is removed/changed but space_config still references it | `profile.active` becomes stale. Permission resolution still works from the stored `profile.member_permissions`. On next `applyProfile()` the values are updated. |
-| Two extensions declare the same CLI name | Existing loader behavior: second registration throws. No change needed. |
-| Profile extension tries to call raw capability CLI in container | Allowed only if the extension is running as admin (hooks run on host, not in container). Container CLI calls go through permission guard. |
-| Caller ID not available (e.g., system-triggered task) | `CALLER_ID` is already `"system"` for scheduled tasks. Profile extension should handle this gracefully (e.g., skip ownership check for system callers). |
-| Existing deployment upgrades Mercury with profiles feature | No behavioral change. `member_permissions` is optional; when absent, existing permission resolution applies. |
+| Customer asks the agent to `printenv` / read files | Allowed — but the container holds no capability secret, only a self-scoped per-turn token. Nothing sensitive to leak. |
+| Customer tries to `curl` the broker spoofing another `callerId` | Rejected — broker authorizes by the token-derived caller ([[caller-bound-capability-token]]), not the header. |
+| Profile requires `gws` but it isn't installed | `applyProfile()` throws listing missing capabilities. |
+| `member_permissions` lists an invalid permission | Filtered by `isValidPermission()`; warn, don't crash. |
+| Admin overrides `role.member.permissions` per space | Per-space override still wins (existing behavior); profile sets the baseline. |
+| Broker route needs Calendar but customer has no appointment yet | Ownership filter returns empty; booking creates a record keyed to `callerId`. |
+| System-triggered task (`callerId = "system"`) hits a broker | Broker skips per-customer ownership for system caller (or per Part 3's system-token decision). |
+| Existing deployment upgrades to this version | No behavior change: `member_permissions` optional; brokers additive. |
 
 ---
 
 ## Implementation Checklist
 
-### Phase 1 — Goal (fill before asking for approval)
+### Phase 1 — Goal
 - [x] Goal, User Stories, and MVP Scope written and reviewed
 
-### Phase 2 — Architecture (fill after Goal approved)
+### Phase 2 — Architecture
 - [x] Architecture & Data section complete
 - [x] Non-Negotiable Rules defined
 - [x] Edge Cases covered
 - [x] Context for Claude pointers filled in
 
-### Implementation (tick off as you go)
+### Implementation
 - [ ] Step 1 — Extend profile schema
-- [ ] Step 2 — Add capability validation
-- [ ] Step 3 — Store profile activation in space_config
-- [ ] Step 4 — Profile-aware permission resolution
-- [ ] Step 5 — System prompt injection
-- [ ] Step 6 — Write tests
-- [ ] Step 7 — Update example config
+- [ ] Step 2 — Capability validation
+- [ ] Step 3 — Activation + config
+- [ ] Step 4 — Profile-aware permissions
+- [ ] Step 5 — Caller token dependency ([[caller-bound-capability-token]])
+- [ ] Step 6 — Broker route pattern (mirror `tradestation.ts`)
+- [ ] Step 7 — Tests
+- [ ] Step 8 — Example config
 - [ ] `bun run check` passes
 - [ ] No secrets or `.env` files committed
 - [ ] No unrelated files modified
@@ -248,17 +234,17 @@ No new HTTP API endpoints. Profile activation is done via:
 
 ## Open Questions
 
-- [ ] Should `dm_auto_space` auto-activate a profile for new customer spaces? (Likely yes — `dm_auto_space.profile: barber-appointments` config key) — owner: TBD
-- [ ] How does `CALLER_ID` map to appointment ownership? Phone number? Display name? A registration step? — owner: profile developer (barber repo)
+- [ ] Should `dm_auto_space` auto-activate the profile for new customer spaces (`dm_auto_space.profile: barber-appointments`)? — owner: TBD
+- [ ] How does `callerId` map to appointment ownership — phone number as-is, or a registration/name step? — owner: profile developer (private repo)
+- [ ] Broker routes: generic `POST /api/profile/:capability/:action` mounting vs per-profile route files? — owner: TBD
 
 ---
 
 ## Retrospective
 
-> Fill this section when archiving.
-
 **Residual risks / follow-ups:**
-- none
+- Per-turn caller token is a hard dependency for safe ownership → backlog/caller-bound-capability-token.md
+- Barber business logic tracked in the private profiles repo (out of this repo's scope) — accepted
 
 **What changed from the plan:**
 - ...