docs: agent platform architecture plan — augmentation + task breakdown (#173)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

docs/MISSION-MANIFEST.md

@@ -39,7 +39,7 @@
 | 5   | ms-162 | Phase 5: Remote Control (v0.0.6)        | done        | —      | #99   | 2026-03-14 | 2026-03-14 |
 | 6   | ms-163 | Phase 6: CLI & Tools (v0.0.7)           | done        | —      | #104  | 2026-03-14 | 2026-03-14 |
 | 7   | ms-164 | Phase 7: Feature Completion (v0.0.8)    | done        | —      | —     | 2026-03-15 | 2026-03-15 |
-| 8   | ms-165 | Phase 8: Polish & Beta (v0.1.0)         | not-started | —      | —     | —          | —          |
+| 8   | ms-165 | Phase 8: Polish & Beta (v0.1.0)         | in-progress | —      | —     | 2026-03-15 | —          |
 
 ## Deployment
 

docs/TASKS.md

@@ -3,7 +3,7 @@
 > Single-writer: orchestrator only. Workers read but never modify.
 
 | id     | status      | milestone | description                                                                                        | pr   | notes         |
-| ------ | ----------- | --------- | --------------------------------------------------------------------- | ---- | ------------- |
+| ------ | ----------- | --------- | -------------------------------------------------------------------------------------------------- | ---- | ------------- |
 | P0-001 | done        | Phase 0   | Scaffold monorepo                                                                                  | #60  | #1            |
 | P0-002 | done        | Phase 0   | @mosaic/types — migrate and extend shared types                                                    | #65  | #2            |
 | P0-003 | done        | Phase 0   | @mosaic/db — Drizzle schema and PG connection                                                      | #67  | #3            |
@@ -76,6 +76,19 @@
 | P7-021 | done        | Phase 7   | Verify Phase 7 — feature-complete platform E2E                                                     | —    | #132 W10 done |
 | P8-005 | done        | Phase 8   | CLI command architecture — DB schema + brain repo + gateway endpoints                              | #158 |               |
 | P8-006 | done        | Phase 8   | CLI command architecture — agent, mission, prdy commands + TUI mods                                | #158 |               |
+| P8-007 | not-started | Phase 8   | DB migrations — preferences.mutable + teams + team_members + projects.teamId                       | —    | #160          |
+| P8-008 | not-started | Phase 8   | @mosaic/types — CommandDef, CommandManifest, new socket events                                     | —    | #161          |
+| P8-009 | not-started | Phase 8   | TUI Phase 1 — slash command parsing, local commands, system message rendering, InputBar wiring     | —    | #162          |
+| P8-010 | not-started | Phase 8   | Gateway Phase 2 — CommandRegistryService, CommandExecutorService, socket + REST commands           | —    | #163          |
+| P8-011 | not-started | Phase 8   | Gateway Phase 3 — PreferencesService, /preferences REST, /system Valkey override, prompt injection | —    | #164          |
+| P8-012 | not-started | Phase 8   | Gateway Phase 4 — /agent, /provider (URL+clipboard), /mission, /prdy, /tools commands              | —    | #165          |
+| P8-013 | not-started | Phase 8   | Gateway Phase 5 — MosaicPlugin lifecycle, ReloadService, hot reload, system:reload TUI             | —    | #166          |
+| P8-014 | not-started | Phase 8   | Gateway Phase 6 — SessionGCService (all tiers), /gc command, cron integration                      | —    | #167          |
+| P8-015 | not-started | Phase 8   | Gateway Phase 7 — WorkspaceService, ProjectBootstrapService, teams project ownership               | —    | #168          |
+| P8-016 | not-started | Phase 8   | Security — file/git/shell tool strict path hardening, sandbox escape prevention                    | —    | #169          |
+| P8-017 | not-started | Phase 8   | TUI Phase 8 — autocomplete sidebar, fuzzy match, arg hints, up-arrow history                       | —    | #170          |
+| P8-018 | done        | Phase 8   | Spin-off plan stubs — Gatekeeper, Task Queue Unification, Chroot Sandboxing                        | —    | #171          |
+| P8-019 | not-started | Phase 8   | Verify Platform Architecture — integration + E2E verification                                      | —    | #172          |
 | P8-001 | not-started | Phase 8   | Additional SSO providers — WorkOS + Keycloak                                                       | —    | #53           |
 | P8-002 | not-started | Phase 8   | Additional LLM providers — Codex, Z.ai, LM Studio, llama.cpp                                       | —    | #54           |
 | P8-003 | not-started | Phase 8   | Performance optimization                                                                           | —    | #56           |

docs/plans/chroot-sandboxing.md

@@ -0,0 +1,60 @@
+# Chroot Agent Sandboxing — Process Isolation for Agent Tool Execution
+
+> **Status:** Stub — deferred. Referenced from `2026-03-15-agent-platform-architecture.md` (Phase 7 Workspaces → Chroot Agent Sandboxing).
+> Implement after Workspaces (P8-015) is complete. Requires workspace directory structure and `WorkspaceService` to be operational.
+
+**Date:** 2026-03-15
+**Packages:** `apps/gateway`
+
+---
+
+## Problem Statement
+
+Agent sessions can use file, git, and shell tools. Path validation in tools is defense-in-depth but insufficient alone — an agent with shell access can run `cat /opt/mosaic/.workspaces/other_user/...` and bypass gateway RBAC.
+
+Chroot provides OS-level enforcement: tool processes literally cannot see outside their workspace directory.
+
+---
+
+## Design (Sweet Spot)
+
+Chroot strikes the balance between full container isolation (too heavy per session) and path validation only (escape-prone):
+
+- Gateway spawns tool processes inside a chroot rooted at the session's `sandboxDir`
+- Requires `CAP_SYS_CHROOT` capability on the gateway process (not full root)
+- Chroot environment provisioned by `WorkspaceService` on workspace creation (minimal deps: git, shell utils, language runtimes as needed)
+- Alternative for Docker deployments: Linux `unshare` namespaces (lighter, no chroot env setup)
+
+---
+
+## Scope (To Be Designed)
+
+- [ ] Chroot environment provisioning — `WorkspaceService.provisionChroot(workspacePath)` on project creation
+- [ ] Minimal chroot deps — identify required binaries/libs per tool type (file: none; git: git binary; shell: bash, common utils)
+- [ ] Gateway capability — document `CAP_SYS_CHROOT` requirement; Dockerfile and docker-compose.yml changes
+- [ ] Tool process spawning — modify `createShellTools`, `createFileTools`, `createGitTools` to spawn via chroot wrapper
+- [ ] Docker alternative — `unshare --mount --pid --user` namespace wrapper as fallback for environments without chroot capability
+- [ ] Defense-in-depth layering — chroot + path validation both active; neither alone is sufficient
+- [ ] Chroot cleanup — integrate with `SessionGCService` / workspace deletion
+- [ ] AppArmor/SELinux profiles (v2) — restrict gateway process file access patterns for multi-tenant hardening
+
+---
+
+## Security Constraints
+
+- What lives **inside** the chroot (agent-accessible): workspace files, git repo, language runtimes
+- What lives **outside** the chroot (gateway-only, never agent-accessible): Valkey connection, PG connection, other users' workspaces, gateway config, OTEL endpoint, credentials
+
+---
+
+## Dependencies
+
+- Workspaces (P8-015) — chroot is rooted at workspace directory; workspace must exist first
+- Tool hardening (P8-016) — path validation stays active as defense-in-depth alongside chroot
+
+---
+
+## References
+
+- Original design context: `docs/plans/2026-03-15-agent-platform-architecture.md` → "Chroot Agent Sandboxing" section
+- Current tool implementations: `apps/gateway/src/agent/tools/`

docs/plans/gatekeeper-service.md

@@ -0,0 +1,53 @@
+# Gatekeeper Service — PR Review, Quality Gates & Merge Authority
+
+> **Status:** Stub — deferred. Referenced from `2026-03-15-agent-platform-architecture.md` (Phase 7 Workspaces).
+> Implement after Workspaces (P8-015) is complete and the workspace/git infrastructure is operational.
+
+**Date:** 2026-03-15
+**Packages:** `apps/gateway`, `packages/types`, `packages/agent`
+
+---
+
+## Problem Statement
+
+Project agents create PRs but cannot review or merge their own work. A separate, isolated agent service with read-only code access and quality gate enforcement is needed to act as the authoritative merge authority.
+
+The Gatekeeper existed in the old Mosaic codebase and must be ported/redesigned for mosaic-mono-v1.
+
+---
+
+## Key Design Constraints
+
+- **Isolated trust boundary** — project agents cannot invoke Gatekeeper directly; it listens for PR events from the git provider
+- **`isSystem: true`** — system agent, not editable by users
+- **Read-only code access** — reads diffs and runs checks; cannot commit or push
+- **Quality gates required before merge** — lint, typecheck, test results must pass
+- **Cannot self-approve** — the agent that authored the PR cannot be the Gatekeeper for that PR
+
+---
+
+## Scope (To Be Designed)
+
+- [ ] Gatekeeper agent bootstrap — system agent config, tool set, prompt engineering
+- [ ] PR event listener — Gitea/GitHub webhook integration (PR opened/updated/ready)
+- [ ] Quality gate runner — trigger CI checks, poll for results, enforce pass criteria
+- [ ] Review generation — LLM-driven code review comment generation
+- [ ] Merge execution — approve + merge when gates pass; reject with comments when they fail
+- [ ] Configurable strictness — per-project required checks, review depth
+- [ ] Trust boundary enforcement — gateway rejects Gatekeeper tool calls that exceed read-only scope
+- [ ] Audit trail — OTEL spans for all Gatekeeper decisions (approve/reject/merge)
+
+---
+
+## Dependencies
+
+- Workspaces (P8-015) — Gatekeeper needs project workspace layout to locate code
+- Git provider API tools — PR creation/review/merge API (Gitea/GitHub/GitLab)
+- CI/CD tool integration — Woodpecker pipeline status polling
+
+---
+
+## References
+
+- Original design context: `docs/plans/2026-03-15-agent-platform-architecture.md` → "Gatekeeper Service" section
+- Workspace RBAC and agent trust model: same document → "RBAC & Filesystem Security"

docs/plans/task-queue-unification.md

@@ -0,0 +1,60 @@
+# Task Queue Unification — @mosaic/queue as Unified Orchestration Layer
+
+> **Status:** Stub — deferred. Referenced from `2026-03-15-agent-platform-architecture.md` (Task Queue & Orchestration section).
+> Implement after Workspaces (P8-015) is complete. Requires workspace file structure to be in place.
+
+**Date:** 2026-03-15
+**Packages:** `packages/queue`, `packages/coord`, `packages/db`, `apps/gateway`
+
+---
+
+## Problem Statement
+
+Two disconnected task systems exist:
+
+1. **`@mosaic/coord`** — file-based missions (`mission.json`, `TASKS.md`), file locks, subprocess spawning. Single-machine orchestrator pattern.
+2. **PG tables** (`tasks`, `mission_tasks`, `missions`) — DB-backed CRUD, REST API, Brain repos.
+
+An agent using `coord_mission_status` gets file data. The dashboard shows DB data. They are never in sync.
+
+---
+
+## Vision
+
+`@mosaic/queue` becomes the unified task orchestration service bridging PG, workspace files, and Valkey:
+
+- DB is source of truth for structured state (status, assignees, timestamps)
+- Workspace files (`TASKS.md`, PRDs) are working copies for agent interaction
+- Valkey handles real-time assignment queues and agent claim locks
+- Flatfile fallback for no-DB single-machine deployments (preserves `@mosaic/coord` pattern)
+
+---
+
+## Scope (To Be Designed)
+
+- [ ] `@mosaic/queue` refactor — elevate from ioredis primitive to task orchestration service
+- [ ] DB ↔ file sync layer — writes to PG propagate to `TASKS.md`; file edits by agents sync back
+- [ ] Task assignment queue — Valkey-backed RPUSH/BLPOP for agent task claiming
+- [ ] Agent claim locks — `mosaic:queue:project:{id}:lock:{taskId}` with TTL
+- [ ] `@mosaic/coord` consolidation — file-based ops ported into queue service; `@mosaic/coord` becomes thin adapter or deprecated
+- [ ] Flatfile fallback — queue service writes JSON manifests when PG unavailable
+- [ ] Status pub/sub — real-time task status updates via Valkey pub/sub
+- [ ] Dependency resolution — block task assignment until dependencies are met
+- [ ] Orchestrator monitor — gateway process watches task queue, assigns next based on dependency graph
+- [ ] API surface — queue service exposes typed interface used by agents, gateway, and CLI
+
+---
+
+## Dependencies
+
+- Workspaces (P8-015) — file sync targets the workspace directory structure
+- Teams architecture (P8-007) — project ownership determines queue namespacing
+- DB schema stable — task/mission tables must not change mid-unification
+
+---
+
+## References
+
+- Original design context: `docs/plans/2026-03-15-agent-platform-architecture.md` → "Task Queue & Orchestration" section
+- Current `@mosaic/coord` implementation: `packages/coord/src/`
+- Current `@mosaic/queue` implementation: `packages/queue/src/`

docs/scratchpads/mvp-20260312.md

@@ -238,3 +238,31 @@ Issues closed: #52, #55, #57, #58, #120-#134
 - TUI: --agent and --project flags, agent name display in top bar, agentId in socket payload.
 - Types: agentId added to ChatMessagePayload.
 - Tests: 23/23 gateway tests pass (updated ownership test for user-scoped missions).
+
+### Session 14 — Platform Architecture Plan Augmentation + Task Breakdown
+
+| Session | Date       | Milestone | Tasks Done | Outcome                                                       |
+| ------- | ---------- | --------- | ---------- | ------------------------------------------------------------- |
+| 14      | 2026-03-15 | Phase 8   | P8-018     | Augmented plan, created 13 issues, created Phase 8 milestone. |
+
+**Decisions made:**
+
+- This plan is Phase 7 feature extension work, not Phase 8 beta scope. P8-001–P8-004 (SSO, LLM, perf, release gate) are deferred to far future.
+- `/provider` OAuth in TUI: URL-to-clipboard + Valkey poll token pattern (same as Pi agent)
+- Add `mutable` column to preferences now (P8-007 DB migration)
+- Teams architecture: `teams` + `team_members` tables, `teamId`/`ownerType` on projects. Workspace path branches on owner type: `users/<uid>/` vs `teams/<tid>/`.
+- Phase dependency chain decided: Wave 1 (DB+Types) → Wave 2 (TUI+toolhardening) → Wave 3 (gateway registry, gating) → Wave 4 (prefs+commands) → Wave 5 (reload+GC) → Wave 6 (workspaces) → Wave 7 (autocomplete) → Wave 8 (verify).
+
+**Plan augmentations added:**
+
+- Teams Architecture section (DB schema, workspace paths, RBAC)
+- REST Route Specifications table
+- `/provider` OAuth flow (URL+clipboard+polling)
+- Preferences `mutable` migration spec
+- Test Strategy (per-task test files + key test cases)
+- Phase Execution Order (dependency graph + wave plan)
+
+**Issues created:** #160–#172 (Gitea milestone ms-165)
+**P8-018 closed:** Spin-off stubs created (gatekeeper-service.md, task-queue-unification.md, chroot-sandboxing.md)
+
+**Next:** Begin execution at Wave 1 — P8-007 (DB migrations) + P8-008 (Types) in parallel.