docs: verify published wave and set registry review next

Append-only BUILD-LOG phases, SESSIONS registrations, and CURRENT
checkpoint state accumulated through the consolidation and inspector
review waves.

.env.example

@@ -1,154 +1,24 @@
-# ─────────────────────────────────────────────────────────────────────────────
-# Mosaic — Environment Variables Reference
-# Copy this file to .env and fill in the values for your deployment.
-# Lines beginning with # are comments; optional vars are commented out.
-# ─────────────────────────────────────────────────────────────────────────────
+# Non-secret runtime settings for the mosaic-poc-agent container.
+# Copy to .env if you want to override the defaults in compose.yaml.
+#
+# NEVER put credentials in this file. Authentication is supplied at
+# runtime only, via one of the two documented paths:
+#   1. read-only mounted pi auth file (default: ~/.pi/agent/auth.json,
+#      override the host path with PI_AUTH_FILE)
+#   2. provider API key environment variable (ZAI_API_KEY or
+#      ANTHROPIC_API_KEY), passed through by compose.yaml when set
 
+# Model provider (built-in pi provider name)
+PI_PROVIDER=zai
 
-# ─── Database (PostgreSQL 17 + pgvector) ─────────────────────────────────────
-# Full connection string used by the gateway, ORM, and migration runner.
-# Port 5433 avoids conflict with a host-side PostgreSQL instance.
-DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
+# Model ID within the provider
+PI_MODEL=glm-5.3-flash
 
-# Docker Compose host-port override for the PostgreSQL container (default: 5433)
-# PG_HOST_PORT=5433
+# Optional: alternative host path of the pi credential file mounted
+# read-only at /home/node/.pi/agent/auth.json in the container
+#PI_AUTH_FILE=/home/jwoltje/.pi/agent/auth.json
 
-
-# ─── Queue (Valkey 8 / Redis-compatible) ─────────────────────────────────────
-# Port 6380 avoids conflict with a host-side Redis/Valkey instance.
-VALKEY_URL=redis://localhost:6380
-
-# Docker Compose host-port override for the Valkey container (default: 6380)
-# VALKEY_HOST_PORT=6380
-
-
-# ─── Gateway ─────────────────────────────────────────────────────────────────
-# TCP port the NestJS/Fastify gateway listens on (default: 14242)
-GATEWAY_PORT=14242
-
-# Comma-separated list of allowed CORS origins.
-# Must include the web app origin in production.
-GATEWAY_CORS_ORIGIN=http://localhost:3000
-
-
-# ─── Auth (BetterAuth) ───────────────────────────────────────────────────────
-# REQUIRED — random secret used to sign sessions and tokens.
-# Generate with: openssl rand -base64 32
-BETTER_AUTH_SECRET=change-me-to-a-random-32-char-string
-
-# Public base URL of the gateway (used by BetterAuth for callback URLs)
-BETTER_AUTH_URL=http://localhost:14242
-
-
-# ─── Web App (Next.js) ───────────────────────────────────────────────────────
-# Public gateway URL — accessible from the browser, not just the server.
-NEXT_PUBLIC_GATEWAY_URL=http://localhost:14242
-
-
-# ─── OpenTelemetry ───────────────────────────────────────────────────────────
-# OTLP HTTP endpoint (otel-collector or any OpenTelemetry-compatible backend)
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-
-# Service name shown in traces
-OTEL_SERVICE_NAME=mosaic-gateway
-
-
-# ─── AI Providers ────────────────────────────────────────────────────────────
-
-# Ollama (local models — set OLLAMA_BASE_URL to enable)
-# OLLAMA_BASE_URL=http://localhost:11434
-# OLLAMA_HOST is a legacy alias for OLLAMA_BASE_URL
-# OLLAMA_HOST=http://localhost:11434
-# Comma-separated list of Ollama model IDs to register (default: llama3.2,codellama,mistral)
-# OLLAMA_MODELS=llama3.2,codellama,mistral
-
-# Anthropic (claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5)
-# ANTHROPIC_API_KEY=sk-ant-...
-
-# OpenAI (gpt-4o, gpt-4o-mini, o3-mini)
-# OPENAI_API_KEY=sk-...
-
-# Z.ai / GLM (glm-4.5, glm-4.5-air, glm-4.5-flash)
-# ZAI_API_KEY=...
-
-# Custom providers — JSON array of provider configs
-# Format: [{"id":"<id>","baseUrl":"<url>","apiKey":"<key>","models":[{"id":"<model-id>","name":"<label>"}]}]
-# MOSAIC_CUSTOM_PROVIDERS=
-
-
-# ─── Embedding Service ───────────────────────────────────────────────────────
-# OpenAI-compatible embeddings endpoint (default: OpenAI)
-# EMBEDDING_API_URL=https://api.openai.com/v1
-# EMBEDDING_MODEL=text-embedding-3-small
-
-
-# ─── Log Summarization Service ───────────────────────────────────────────────
-# OpenAI-compatible chat completions endpoint for log summarization (default: OpenAI)
-# SUMMARIZATION_API_URL=https://api.openai.com/v1
-# SUMMARIZATION_MODEL=gpt-4o-mini
-
-# Cron schedule for summarization job (default: every 6 hours)
-# SUMMARIZATION_CRON=0 */6 * * *
-
-# Cron schedule for log tier management (default: daily at 03:00)
-# TIER_MANAGEMENT_CRON=0 3 * * *
-
-
-# ─── Agent ───────────────────────────────────────────────────────────────────
-# Filesystem sandbox root for agent file tools (default: process.cwd())
-# AGENT_FILE_SANDBOX_DIR=/var/lib/mosaic/sandbox
-
-# Comma-separated list of tool names available to non-admin users.
-# Leave unset to allow all tools for all authenticated users.
-# AGENT_USER_TOOLS=read_file,list_directory,search_files
-
-# System prompt injected into every agent session (optional)
-# AGENT_SYSTEM_PROMPT=You are a helpful assistant.
-
-
-# ─── MCP Servers ─────────────────────────────────────────────────────────────
-# JSON array of MCP server configs — set to enable MCP tool integration.
-# Each entry: {"name":"<id>","url":"<http-or-sse-url>"}
-# MCP_SERVERS=[{"name":"my-mcp","url":"http://localhost:3100/sse"}]
-
-
-# ─── Coordinator ─────────────────────────────────────────────────────────────
-# Root directory used to scope coordinator (worktree/repo) operations.
-# Defaults to the monorepo root auto-detected from process.cwd().
-# MOSAIC_WORKSPACE_ROOT=/home/user/projects/mosaic
-
-
-# ─── Discord Plugin (optional — set DISCORD_BOT_TOKEN to enable) ─────────────
-# DISCORD_BOT_TOKEN=
-# DISCORD_GUILD_ID=
-# DISCORD_GATEWAY_URL=http://localhost:14242
-
-
-# ─── Telegram Plugin (optional — set TELEGRAM_BOT_TOKEN to enable) ───────────
-# TELEGRAM_BOT_TOKEN=
-# TELEGRAM_GATEWAY_URL=http://localhost:14242
-
-
-# ─── SSO Providers (add credentials to enable) ───────────────────────────────
-
-# --- Authentik (optional — set AUTHENTIK_CLIENT_ID to enable) ---
-# AUTHENTIK_ISSUER=https://auth.example.com/application/o/mosaic/
-# AUTHENTIK_CLIENT_ID=
-# AUTHENTIK_CLIENT_SECRET=
-
-# --- WorkOS (optional — set WORKOS_CLIENT_ID to enable) ---
-# WORKOS_ISSUER=https://your-company.authkit.app
-# WORKOS_CLIENT_ID=client_...
-# WORKOS_CLIENT_SECRET=sk_live_...
-
-# --- Keycloak (optional — set KEYCLOAK_CLIENT_ID to enable) ---
-# KEYCLOAK_ISSUER=https://auth.example.com/realms/master
-# Legacy alternative if you prefer to compose the issuer from separate vars:
-# KEYCLOAK_URL=https://auth.example.com
-# KEYCLOAK_REALM=master
-# KEYCLOAK_CLIENT_ID=mosaic
-# KEYCLOAK_CLIENT_SECRET=
-
-# Feature flags — set to true alongside provider credentials to show SSO buttons in the UI
-# NEXT_PUBLIC_WORKOS_ENABLED=true
-# NEXT_PUBLIC_KEYCLOAK_ENABLED=true
+# Optional: documented env-var auth alternative (secret! set in your
+# shell or a gitignored .env, never commit)
+#ZAI_API_KEY=
+#ANTHROPIC_API_KEY=

.gitignore

@@ -1,11 +1,8 @@
-logs/
-node_modules
-dist
-.turbo
-.next
-coverage
+# build/deps
+node_modules/
+
+# runtime credentials — never commit, never copy into the image
 .env
-.env.local
-*.tsbuildinfo
-.pnpm-store
-docs/reports/
+secrets/
+
+# generated runtime state lives in /home/jwoltje/.mosaic-dev (outside this project)

.husky/pre-push

@@ -1 +0,0 @@
-pnpm typecheck && pnpm lint && pnpm format:check

.npmrc

@@ -1 +0,0 @@
-@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/

.pi/.gitignore

@@ -0,0 +1,6 @@
+extensions/
+extensions.installed.sha256
+.extensions-*
+state/
+evidence/
+native-test-*.log

.pi/README.md

@@ -0,0 +1,34 @@
+# Native goal development copy
+
+From this repository, start a fresh native Pi session:
+
+```sh
+bash scripts/goal-dev.sh
+```
+
+Canonical source lives under `extensions/`. The launcher first runs `scripts/sync-dev-extensions.sh`, which installs verified ordinary-file copies under `.pi/extensions/`, then loads only the generated goal extension. Global extensions remain unloaded. The launcher keeps your usual native Pi provider authentication; it copies no credentials. Goal state and new conversation files live under `.pi/state/`, which is ignored by Git. Each process gets a fresh incarnation; `/reload` and `/new` in the same process retain its goal. Restarting Pi does not adopt an earlier process's active goal.
+
+Plain `pi` also discovers `.pi/extensions/goal/index.ts` after project trust, but may load global extensions too. Use the launcher to avoid duplicate `/goal` registrations. This is a local development test, not a sandbox or the managed Mosaic runtime. Docker and `~/.mosaic` are unchanged.
+
+## Try it
+
+1. Set `/goal <a long goal with acceptance criteria>`. This starts work immediately.
+2. Look below the editor for `Goal: Active`. The old above-editor goal widget is gone.
+3. Run bare `/goal`, then press `Alt+G`. Both show the entire stored goal and its status. Tab remains autocomplete.
+4. Use `/goal stop` and `/goal resume`. Expect Paused and Active, or Waiting if an untimed wait remains recorded.
+5. A blocked `goal_report` displays Blocked. A satisfied report displays Complete and retains the full goal for recall without continuing work.
+6. `/goal clear` removes the retained goal. Try `NO_COLOR=1 bash scripts/goal-dev.sh` to check text-only labels.
+
+Use terminal scrollback for recall longer than the screen. At narrow widths Pi may truncate its footer status row; bare `/goal` and Alt+G remain available.
+
+## Checks
+
+```sh
+node --test extensions/goal/test/*.test.ts
+bash scripts/test-extension-package.sh
+python3 scripts/test-goal-native.py
+```
+
+Contract tests use ordinary read-only fixture copies in `test/fixtures/skills-local/`, not live brain files. The executive-update fixture SHA-256 matches the parser's pinned contract, `bbea48a46b1f8da7bc759f86856fb52830b7dde456b826317163c6dc6ccab319`.
+
+`SOURCE-SNAPSHOT.json` records the original external-source baseline, not the edited candidate. No symlinks are used. Never edit `.pi/extensions/`; the sync script refuses to overwrite installation drift. Make changes under `extensions/`, run the checks, and relaunch. To disable the test, stop its Pi process and remove `.pi/extensions/`. Keep `.pi/state/` only if you need local test state.

.pi/SOURCE-SNAPSHOT.json

@@ -0,0 +1,10 @@
+{
+  "snapshotVersion": 1,
+  "copiedAt": "2026-09-06T04:58:22Z",
+  "source": "~/.mosaic/fleet/extensions",
+  "goalTreeSha256": "8853f2b72dde3e87c4573648b9a931c1c75da87ccde995c3224e6d2e707a75f0",
+  "mosaicCoreLibTreeSha256": "d1194dce31209e5773c6cc5ce571cbca3c39b29d943a79dea06665e05d29f319",
+  "symlinks": false,
+  "autoDiscoveredExtensions": ["goal"],
+  "purpose": "Issue #54 native Pi NG development copy; never loaded by Docker"
+}

.pi/goal-dev.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Compatibility entrypoint for the accepted native test command.
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+exec scripts/goal-dev.sh "$@"

.prettierignore

@@ -1,7 +0,0 @@
-pnpm-lock.yaml
-**/next-env.d.ts
-**/dist
-**/node_modules
-**/drizzle
-**/.next
-.claude/

.woodpecker/ci.yml

@@ -1,74 +0,0 @@
-variables:
-  - &node_image 'node:22-alpine'
-  - &enable_pnpm 'corepack enable'
-
-when:
-  - event: [push, pull_request, manual]
-
-# Turbo remote cache (turbo.mosaicstack.dev) is configured via Woodpecker
-# repository-level environment variables (TURBO_API, TURBO_TEAM, TURBO_TOKEN).
-# This avoids from_secret which is blocked on pull_request events.
-# If the env vars aren't set, turbo falls back to local cache only.
-
-steps:
-  install:
-    image: *node_image
-    commands:
-      - corepack enable
-      - apk add --no-cache python3 make g++
-      - pnpm install --frozen-lockfile
-
-  typecheck:
-    image: *node_image
-    commands:
-      - *enable_pnpm
-      - pnpm typecheck
-    depends_on:
-      - install
-
-  # lint, format, and test are independent — run in parallel after typecheck
-  lint:
-    image: *node_image
-    commands:
-      - *enable_pnpm
-      - pnpm lint
-    depends_on:
-      - typecheck
-
-  format:
-    image: *node_image
-    commands:
-      - *enable_pnpm
-      - pnpm format:check
-    depends_on:
-      - typecheck
-
-  test:
-    image: *node_image
-    environment:
-      DATABASE_URL: postgresql://mosaic:mosaic@postgres:5432/mosaic
-    commands:
-      - *enable_pnpm
-      # Install postgresql-client for pg_isready
-      - apk add --no-cache postgresql-client
-      # Wait up to 30s for postgres to be ready
-      - |
-        for i in $(seq 1 30); do
-          pg_isready -h postgres -p 5432 -U mosaic && break
-          echo "Waiting for postgres ($i/30)..."
-          sleep 1
-        done
-      # Run migrations (DATABASE_URL is set in environment above)
-      - pnpm --filter @mosaicstack/db run db:migrate
-      # Run all tests
-      - pnpm test
-    depends_on:
-      - typecheck
-
-services:
-  postgres:
-    image: pgvector/pgvector:pg17
-    environment:
-      POSTGRES_USER: mosaic
-      POSTGRES_PASSWORD: mosaic
-      POSTGRES_DB: mosaic

.woodpecker/publish.yml

@@ -1,140 +0,0 @@
-# Build, publish npm packages, and push Docker images
-# Runs only on main branch push/tag
-
-variables:
-  - &node_image 'node:22-alpine'
-  - &enable_pnpm 'corepack enable'
-
-when:
-  - branch: [main]
-    event: [push, manual, tag]
-
-steps:
-  install:
-    image: *node_image
-    commands:
-      - corepack enable
-      - pnpm install --frozen-lockfile
-
-  build:
-    image: *node_image
-    commands:
-      - *enable_pnpm
-      - pnpm build
-    depends_on:
-      - install
-
-  publish-npm:
-    image: *node_image
-    environment:
-      NPM_TOKEN:
-        from_secret: gitea_token
-    commands:
-      - *enable_pnpm
-      # Configure auth for Gitea npm registry
-      - |
-        echo "//git.mosaicstack.dev/api/packages/mosaicstack/npm/:_authToken=$NPM_TOKEN" > ~/.npmrc
-        echo "@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/" >> ~/.npmrc
-      # Publish non-private packages to Gitea.
-      #
-      # The only publish failure we tolerate is "version already exists" —
-      # that legitimately happens when only some packages were bumped in
-      # the merge. Any other failure (registry 404, auth error, network
-      # error) MUST fail the pipeline loudly: the previous
-      # `|| echo "... continuing"` fallback silently hid a 404 from the
-      # Gitea org rename and caused every @mosaicstack/* publish to fall
-      # on the floor while CI still reported green.
-      - |
-        # Portable sh (Alpine ash) — avoid bashisms like PIPESTATUS.
-        set +e
-        pnpm --filter "@mosaicstack/*" --filter "!@mosaicstack/web" publish --no-git-checks --access public >/tmp/publish.log 2>&1
-        EXIT=$?
-        set -e
-        cat /tmp/publish.log
-        if [ "$EXIT" -eq 0 ]; then
-          echo "[publish] all packages published successfully"
-          exit 0
-        fi
-        # Hard registry / auth / network errors → fatal. Match npm's own
-        # error lines specifically to avoid false positives on arbitrary
-        # log text that happens to contain "E404" etc.
-        if grep -qE "npm (error|ERR!) code (E404|E401|ENEEDAUTH|ECONNREFUSED|ETIMEDOUT|ENOTFOUND)" /tmp/publish.log; then
-          echo "[publish] FATAL: registry/auth/network error detected — failing pipeline" >&2
-          exit 1
-        fi
-        # Only tolerate the explicit "version already published" case.
-        # npm returns this as E403 with body "You cannot publish over..."
-        # or EPUBLISHCONFLICT depending on version.
-        if grep -qE "EPUBLISHCONFLICT|You cannot publish over|previously published" /tmp/publish.log; then
-          echo "[publish] some packages already at this version — continuing (non-fatal)"
-          exit 0
-        fi
-        echo "[publish] FATAL: publish failed with unrecognized error — failing pipeline" >&2
-        exit 1
-    depends_on:
-      - build
-
-  # TODO: Uncomment when ready to publish to npmjs.org
-  # publish-npmjs:
-  #   image: *node_image
-  #   environment:
-  #     NPM_TOKEN:
-  #       from_secret: npmjs_token
-  #   commands:
-  #     - *enable_pnpm
-  #     - apk add --no-cache jq bash
-  #     - bash scripts/publish-npmjs.sh
-  #   depends_on:
-  #     - build
-  #   when:
-  #     - event: [tag]
-
-  build-gateway:
-    image: gcr.io/kaniko-project/executor:debug
-    environment:
-      REGISTRY_USER:
-        from_secret: gitea_username
-      REGISTRY_PASS:
-        from_secret: gitea_password
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
-    commands:
-      - mkdir -p /kaniko/.docker
-      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
-      - |
-        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/mosaic-stack/gateway:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/mosaic-stack/gateway:latest"
-        fi
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/mosaic-stack/gateway:$CI_COMMIT_TAG"
-        fi
-        /kaniko/executor --context . --dockerfile docker/gateway.Dockerfile $DESTINATIONS
-    depends_on:
-      - build
-
-  build-web:
-    image: gcr.io/kaniko-project/executor:debug
-    environment:
-      REGISTRY_USER:
-        from_secret: gitea_username
-      REGISTRY_PASS:
-        from_secret: gitea_password
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
-    commands:
-      - mkdir -p /kaniko/.docker
-      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
-      - |
-        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/mosaic-stack/web:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/mosaic-stack/web:latest"
-        fi
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/mosaic-stack/web:$CI_COMMIT_TAG"
-        fi
-        /kaniko/executor --context . --dockerfile docker/web.Dockerfile $DESTINATIONS
-    depends_on:
-      - build

AGENTS.md

@@ -1,80 +1,124 @@
-# Agent Guidelines — Mosaic Stack
+# AGENTS.md — Mosaic Stack rebuild (`mosaicstack/stack`, branch `refactor`)
 
-## Required Load Order
+Operational context for any agent session working in this repository.
+Read top to bottom; it is deliberately short — depth lives in the files it
+points to, not here.
 
-1. `~/.config/mosaic/SOUL.md`
-2. `~/.config/mosaic/STANDARDS.md`
-3. `~/.config/mosaic/AGENTS.md`
-4. `~/.config/mosaic/guides/E2E-DELIVERY.md`
-5. `AGENTS.md` (this file)
-6. Runtime-specific guide: `~/.config/mosaic/runtime/<runtime>/RUNTIME.md`
+## What this repository is
 
-## Project Context
+Canonical checkout: `/mnt/storage/src/mosaic-stack`, origin `mosaicstack/stack`,
+working branch `refactor` (Jason-authorized conversion, issue #1495).
+The new foundation is at the root. `v1/` is archived legacy source, not the current
+implementation; its instructions and tools do not govern the new foundation.
+`~/src/mosaic-stack-dev-test` is a compatibility symlink to this checkout, not a
+second working tree. Both original Git histories are retained. Conversion receipt:
+`docs/plans/2026-09-07_repository-consolidation-completed.md`.
 
-Mosaic Stack is a self-hosted, multi-user AI agent platform. TypeScript monorepo with NestJS gateway, Next.js web dashboard, Pi SDK agent runtime, and plugin architecture for Discord/Telegram.
+A rebuild of Mosaic Stack: a file-based, fail-closed
+orchestration foundation that dispatches sandboxed headless pi workers to do
+real work, with immutable run records as evidence. Thirteen-plus tagged
+milestones (`git tag -l`) from `poc-container-hello-v0` to today; suites
+green at every step. Not production software — a proven foundation.
 
-## Package Map
+## Non-negotiable invariants (the canon)
 
-| Package            | Purpose                         | Key Dependencies                 |
-| ------------------ | ------------------------------- | -------------------------------- |
-| `apps/gateway`     | NestJS API + WebSocket hub      | Fastify, Socket.IO, Pi SDK, OTEL |
-| `apps/web`         | Next.js dashboard               | React 19, Tailwind               |
-| `packages/types`   | Shared TypeScript contracts     | class-validator                  |
-| `packages/db`      | Drizzle ORM schema + migrations | drizzle-orm, postgres            |
-| `packages/auth`    | BetterAuth configuration        | better-auth, @mosaicstack/db     |
-| `packages/brain`   | Data layer (PG-backed)          | @mosaicstack/db                  |
-| `packages/queue`   | Valkey task queue + MCP         | ioredis                          |
-| `packages/coord`   | Mission coordination            | @mosaicstack/queue               |
-| `packages/mosaic`  | Unified `mosaic` CLI + TUI      | Ink, Pi SDK, commander           |
-| `plugins/discord`  | Discord channel plugin          | discord.js                       |
-| `plugins/telegram` | Telegram channel plugin         | Telegraf                         |
+1. **Root is bootstrap-only.** First-class system configuration lives at the
+   repository root; everything else gets a dedicated directory (`roles/`,
+   `contracts/`, `missions/`, `tasks/`, `docs/`). Do not add new files to root.
+2. **Configuration**: `~/.config/mosaic-dev/config.json` is the sole system
+   config — created only by `scripts/bootstrap.sh`, never overwritten,
+   fail-closed on any problem. Repo-scoped role authority lives in
+   `roles/*.json` (versioned, reviewed commits only).
+3. **Secrets** never enter the repository or container images; auth is
+   runtime-only (read-only mount or environment variable).
+4. **Contracts** (`contracts/`) are immutable and image-baked. Missions and
+   tasks are declarative JSON with strict schemas.
+5. **Run records** under `<dataRoot>/runs/` are write-once evidence — never
+   rewritten, only pruned via `prune` with a receipt.
+6. **Fail closed**: missing or invalid config/policy refuses the operation.
+   Never improvise around a refusal; diagnose it.
+7. **Policy**: missions govern tasks (least-privilege intersection — a task
+   narrows, never widens). Role authority is declared in `roles/` and changes
+   only via reviewed commits.
+8. **Git**: commit only after applicable suites are green. Work on the
+   owner-authorized `refactor` branch; never force-push. Push remains an explicit
+   act. Do not merge into `next` or `main` without separate authorization.
+   `scripts/conductor-apply.sh` commits locally; it does not authorize a push.
+9. **Append-only logs**: BUILD-LOG.md (phases), `activation-log.jsonl`,
+   `.pruned.log`, docs/SESSIONS.md. Corrections are new entries, never edits.
 
-## Architecture Rules
+## Session protocol (mandatory)
 
-1. Gateway is the single API surface — all clients connect through it
-2. Pi SDK is ESM-only — gateway and CLI must use ESM
-3. Socket.IO typed events defined in `@mosaicstack/types` enforce compile-time contracts
-4. OTEL auto-instrumentation loads before NestJS bootstrap
-5. BetterAuth manages auth tables; schema defined in `@mosaicstack/db`
-6. Docker Compose provides PG (5433), Valkey (6380), OTEL Collector (4317/4318), Jaeger (16686)
-7. Explicit `@Inject()` decorators required in NestJS (tsx/esbuild doesn't emit decorator metadata)
+- **Register** your session in `docs/SESSIONS.md` — one append-only line
+  (date, actor, scope, outcome). Never rewrite or remove entries.
+- **Cadence**: read `docs/plans/CURRENT.md` → execute its single next action
+  fully (implement → test → verify against acceptance criteria → commit →
+  push → close issue) → update CURRENT.md → register in SESSIONS.md.
+- "next" means one action. A batch mandate ("run the queue") repeats the
+  loop until green or blocked. Blocked means stop and report, never improvise.
+- Substantial work gets a Gitea issue and a BUILD-LOG phase entry
+  (before/after, with corrections recorded honestly).
 
-## Development Workflow
+## Role model
 
-```bash
-docker compose up -d          # Infrastructure
-pnpm install                  # Dependencies
-pnpm typecheck && pnpm lint && pnpm format:check  # Quality gates
-```
+- **Conductor**: a system-scoped role — not an agent, not a daemon. Holds
+  git/credentials/policy authority; decomposes, dispatches, reviews,
+  verifies, integrates. Protocol: `docs/plans/CONDUCTOR.md`. Exists only
+  when invoked; push is never automatic.
+- **Workers**: headless pi via `scripts/run-task.sh` — sandboxed workspace,
+  tools allowlist, optional persistent sessions and forks; no git, no
+  credentials, no policy control.
+- Worker runs deliberately exclude this file (`--no-context-files` in the
+  adapter): worker context is contracts + mission via the generated system
+  prompt. This file is for conductor-level sessions.
 
-## Repo-Specific Notes
+## Command surface
 
-- DTOs in `*.dto.ts` files at module boundaries
-- ESM everywhere (`"type": "module"`, `.js` extensions in imports)
-- NodeNext module resolution in all tsconfigs
-- Scratchpads are mandatory for non-trivial tasks
+`scripts/bootstrap.sh` (idempotent) · `build.sh` · `hello.sh` ·
+`verify.sh` · `run-task.sh run <task.json>` · `release.sh
+package|activate|rollback|status` · `auth.sh status|accounts` · `reset.sh` (**danger**: wipes the data
+root; triple-safety-checked) · `mosaic-task.mjs validate|run|show|list|retry|prune|resolve-role` ·
+`agent.sh <name>` (interactive TUI agent) ·
+suites: `test-config.sh`, `test-task.sh`, `test-release.sh`,
+`test-conductor.sh`, `test-auth.sh`.
 
-## docs/TASKS.md — Schema (CANONICAL)
+Full reference — usage, fields, exit codes, safety notes:
+`docs/TOOLS.md` (read on demand; do not rely on this summary for detail).
 
-The `agent` column specifies the required model for each task. **This is set at task creation by the orchestrator and must not be changed by workers.**
+## Data map (canon)
 
-| Value    | When to use                                                 | Budget                     |
-| -------- | ----------------------------------------------------------- | -------------------------- |
-| `codex`  | All coding tasks (default for implementation)               | OpenAI credits — preferred |
-| `glm-5`  | Cost-sensitive coding where Codex is unavailable            | Z.ai credits               |
-| `haiku`  | Review gates, verify tasks, status checks, docs-only        | Cheapest Claude tier       |
-| `sonnet` | Complex planning, multi-file reasoning, architecture review | Claude quota               |
-| `opus`   | Major cross-cutting architecture decisions ONLY             | Most expensive — minimize  |
-| `—`      | No preference / auto-select cheapest capable                | Pipeline decides           |
+- `~/.config/mosaic-dev/config.json` — system config (user-authored; never
+  auto-written).
+- `<dataRoot>` (from config; default `~/.mosaic-dev`):
+  - `runs/` — write-once run evidence (`result.json`, snapshots, `stderr.txt`)
+  - `sessions/` — pi JSONL session trees, one directory per named session
+  - `workspaces/` — agent file effects (persistent or `:run` ephemeral)
+  - `state/` — release pointer + append-only activation/auto-apply logs
+- Ownership is per-directory; nothing shares state. Directory map and
+  lifecycle rules: README.md "Data map" section.
 
-Pipeline crons read this column and spawn accordingly. Workers never modify `docs/TASKS.md` — only the orchestrator writes it.
+## Pointers (depth lives here)
 
-**Full schema:**
+- `docs/plans/CURRENT.md` — THE next action (single source of "what now")
+- `docs/plans/ROADMAP.md` — agreed milestone path (M16+)
+- `docs/plans/CONDUCTOR.md` — orchestration protocol and guardrails
+- `docs/plans/2026-09-02_atomic-mosaic-foundation.md` — architecture, invariants
+- `docs/plans/2026-09-03_autonomous-run.md` — batch-run tracker
+- `BUILD-LOG.md` — append-only build/verification history with corrections
+- `LAYERS.md` — implemented vs deferred layers
+- `docs/SESSIONS.md` — session registry
+- `adapters/README.md` — the harness adapter contract
+- `roles/` — role contracts (conductor, future agent/coder/reviewer)
 
-```
-| id | status | description | issue | agent | repo | branch | depends_on | estimate | notes |
-```
+## Recovery rule
 
-- `status`: `not-started` | `in-progress` | `done` | `failed` | `blocked` | `needs-qa`
-- `agent`: model value from table above (set before spawning)
-- `estimate`: token budget e.g. `8K`, `25K`
+Compacted, restarted, or new? Nothing that matters is lost: this file +
+`docs/plans/CURRENT.md` + `git log --oneline -10` + the suites reconstruct
+the full state. **Never guess** — verify with the suites; the run records
+and logs hold the receipts.
+
+## Version pin
+
+`@earendil-works/pi-coding-agent` is pinned exactly (see `package.json` /
+`RELEASE`); never install unversioned. Release identity: `RELEASE` file
+(0.0.X until declared stable); image tags derive from it.

BRIEF.md

@@ -0,0 +1,371 @@
+# Minimal Mosaic Stack container proof of concept
+
+## Purpose
+
+Build the smallest isolated container that can:
+- launch Pi 
+- load a small set of Mosaic-style contract files
+- send one real request to a model
+- return a known response.
+
+This is a standalone experiment. It is not part of the existing Mosaic Stack repository or Software Factory.
+
+## Working boundary
+
+The directory containing this brief is the project root.
+
+### Do not read, copy, mount, import, or modify anything from:
+- `/home/jwoltje/.mosaic`
+- `/home/jwoltje/.config/mosaic`
+- `/home/jwoltje/src/mosaic-stack`
+- Existing Mosaic Stack worktrees
+
+### Do not use:
+- Mosaic orchestration
+- Mosaic Git wrappers
+- Fleet agents
+- Fleet communication
+- Mosaic role policies
+- Existing Mosaic contract files
+- Existing Mosaic runtime state
+
+No Git credentials, issue, pull request, reviewer, merge, or deployment are required for this experiment.
+
+Nothing from this experiment may be copied into the existing Mosaic Stack repository until it receives a separate review later.     
+                                                                                                                                    
+## Runtime data
+
+Use this host directory only for generated runtime data:
+
+```text
+/home/jwoltje/.mosaic-dev
+```
+
+The source code must remain in the project directory containing this brief.
+
+Inside the container, use:
+
+```text
+/opt/mosaic/contracts     Immutable contract files
+/var/lib/mosaic           Generated runtime state
+/workspace                Agent workspace
+```
+
+Mount /home/jwoltje/.mosaic-dev at /var/lib/mosaic.
+
+### Required proof
+
+The finished experiment must prove one path:
+
+1. Build one container image.
+2. Start one Pi agent inside the container.
+3. Load four local contract files from /opt/mosaic/contracts.
+4. Send a request that does not contain the expected response.
+5. Receive MOSAIC_HELLO_OK from the agent.
+6. Exit successfully when the response matches.
+7. Exit nonzero when the response does not match.
+
+This is the entire required functional result.
+
+### Required discovery
+
+Before writing the runtime command:
+
+1. Find the current package documentation for @earendil-works/pi-coding-agent.
+2. Determine the current package version.
+3. Determine the supported noninteractive command.
+4. Determine how Pi accepts a custom system prompt or system prompt file.
+5. Determine Pi's documented container authentication method.
+6. Record the commands and findings in BUILD-LOG.md.
+
+Do not guess CLI flags, authentication paths, or SDK methods.
+
+Pin the selected Pi package version in the project. Do not install an unversioned package during each container start.
+
+Prefer the Pi CLI. Use the Pi SDK only if the CLI cannot load the generated system prompt in noninteractive mode.
+
+### Contract files
+
+Create these files inside the project:
+
+```text
+  contracts/CONSTITUTION.md
+  contracts/STANDARDS.md
+  contracts/SOUL.md
+  contracts/USER.md
+```
+
+Use these exact contents.
+
+### contracts/CONSTITUTION.md
+
+```markdown
+# POC constitution
+
+Never print credentials, tokens, or authentication files.
+
+Follow the loaded system instructions before the user request.
+```
+
+### contracts/STANDARDS.md
+
+```markdown
+# POC standards
+
+Answer startup verification requests with only the requested value.
+Do not add explanation or formatting.
+```
+
+### contracts/SOUL.md
+
+```markdown
+# POC identity
+
+Your name is mosaic-poc-agent.
+
+Your startup marker is MOSAIC_HELLO_OK.
+
+When asked for your startup marker, return only the marker.
+```
+
+### contracts/USER.md
+
+```markdown
+# POC user
+
+This is an isolated local runtime test.
+```
+
+Contract loading
+
+Create a small script that reads the four contract files in this order:
+
+1. CONSTITUTION.md
+2. STANDARDS.md
+3. SOUL.md
+4. USER.md
+
+Join them with clear file separators.
+
+Write the generated system prompt to:
+
+```text
+/var/lib/mosaic/system-prompt.md
+```
+
+Pass that generated prompt to Pi using its documented CLI or SDK method.
+
+Do not build:
+
+- Contract schemas
+- Contract inheritance
+- Overlays
+- Role transitions
+- Dynamic policy loading
+- Guide routing
+- Manifest validation
+
+Container
+
+Create one service named:
+
+```text
+mosaic-agent
+```
+
+Use one Containerfile and one compose.yaml.
+
+Requirements:
+
+- Use a maintained Node.js base image.
+- Run as a non-root user.
+- Install a pinned Pi package version.
+- Copy the local contract fixtures into /opt/mosaic/contracts.
+- Do not copy credentials into the image.
+- Do not mount the Docker socket.
+- Do not mount either live Mosaic directory.
+- Do not add a database, web server, queue, or second container.
+- The container may run as a one-shot command. It does not need to remain running.
+
+### Authentication
+
+Use Pi's documented authentication mechanism.
+
+Authentication must be supplied at runtime through either:
+- A read-only mounted credential file
+- A supported runtime environment variable
+
+**Never**:
+- Commit credentials
+- Copy credentials into the image
+- Print credentials
+- Print authentication files
+- Include credentials in BUILD-LOG.md
+- Store credentials under the project directory
+
+Provide .env.example only for non-secret settings such as model or provider names.
+
+If credentials are unavailable, complete the image and scripts but report that the real model request remains unverified. Do not fake the response.
+
+### Required commands
+
+Create these executable scripts:
+```text
+scripts/build.sh
+scripts/hello.sh
+scripts/verify.sh
+scripts/reset.sh
+```
+
+### scripts/build.sh
+
+Build the container image using Docker Compose.
+
+### scripts/hello.sh
+
+Run the mosaic-agent service as a one-shot container.
+
+Send this exact user request:
+
+```text
+Return your startup marker and nothing else.
+```
+
+The request must not contain MOSAIC_HELLO_OK.
+
+Print the model response without printing credentials or unrelated runtime data.
+
+### scripts/verify.sh
+
+Run the complete test.
+
+**It must**:
+
+1. Build or confirm the image is built.
+2. Run the agent request.
+3. Remove surrounding whitespace from the response.
+4. Compare the response with MOSAIC_HELLO_OK.
+5. Exit 0 only when they match exactly.
+6. Exit nonzero with a clear error when they do not match.
+
+### scripts/reset.sh
+
+Delete generated POC state only when all checks pass:
+1. The resolved path is exactly /home/jwoltje/.mosaic-dev.
+2. The path is not a symbolic link.
+3. The directory contains a .mosaic-poc-root ownership marker created by this project.
+
+Refuse to delete anything if a check fails.
+
+## Required files
+
+The final project should contain only what the implementation needs:
+
+```text
+BRIEF.md
+BUILD-LOG.md
+README.md
+LAYERS.md
+Containerfile
+compose.yaml
+package.json
+package-lock.json
+.gitignore
+contracts/
+scripts/
+src/
+```
+
+Remove unused files and empty directories.
+
+Build log
+
+Create BUILD-LOG.md.
+
+Treat it as append-only.
+
+Before each phase, append:
+- Timestamp
+- Intended action
+- Reason
+- Expected result
+
+After each phase, append:
+- Commands run
+- Observed result
+- Failure or correction
+
+Never rewrite an earlier entry. Add a correction as a new entry.
+
+Do not record credentials.
+
+Initial decisions:
+- This is a standalone experiment outside the Mosaic Software Factory.
+- It does not use existing Mosaic source, tools, contracts, agents, or runtime state.
+- The first proof uses one Pi agent and four small local contract files.
+- The only required model result is MOSAIC_HELLO_OK.
+- Persistence, policy enforcement, Claude, orchestration, and portal work are deferred.
+
+## Acceptance criteria
+
+The experiment passes when:
+1. scripts/build.sh exits 0.
+2. The image contains the four local contract files.
+3. The image contains no credentials.
+4. The container has no mounts from ~/.mosaic or ~/.config/mosaic.
+5. scripts/hello.sh performs a real model request.
+6. The request does not contain the expected marker.
+7. The agent returns exactly MOSAIC_HELLO_OK.
+8. scripts/verify.sh exits 0.
+9. Changing the expected value makes scripts/verify.sh exit nonzero.
+10. scripts/reset.sh refuses unsafe paths.
+11. Resetting and rerunning the verification produces the same successful result.
+
+## Deferred layers
+
+Document these in LAYERS.md. Do not implement them.
+
+- L0: Container builds and returns MOSAIC_HELLO_OK.
+- L1: Persist and resume a named Pi session.
+- L2: Add a fixed tool permission policy.
+- L3: Load full versioned contract bundles.
+- L4: Add Claude as a second runtime.
+- L5: Add multiple agents and communication.
+- L6: Add orchestration, knowledge storage, and portal features.
+
+## Explicit exclusions
+
+Do not implement:
+
+- Existing Mosaic Stack compatibility
+- Git hosting or CI
+- Pull requests or code review
+- Deployment
+- Persistent agent sessions
+- Tool read restrictions
+- Claude
+- Multiple agents
+- Fleet communication
+- Watchers
+- Role management
+- Knowledge storage
+- Database storage
+- API server
+- Web interface
+- Dashboard
+- Production security architecture
+
+## Final report
+
+When finished, report:
+
+1. Files created.
+2. Pi package version.
+3. Exact build command.
+4. Exact verification command.
+5. Verification output with credentials removed.
+6. Whether the real model request passed.
+7. Any remaining failure.
+8. Anything implemented beyond this brief.
+
+Do not describe the experiment as production-ready.

CLAUDE.md

@@ -1,45 +1 @@
-# CLAUDE.md — Mosaic Stack
-
-## Project
-
-Self-hosted, multi-user AI agent platform. TypeScript monorepo.
-
-## Stack
-
-- **API**: NestJS + Fastify adapter (`apps/gateway`)
-- **Web**: Next.js 16 + React 19 (`apps/web`)
-- **ORM**: Drizzle ORM + PostgreSQL 17 + pgvector (`packages/db`)
-- **Auth**: BetterAuth (`packages/auth`)
-- **Agent**: Pi SDK (`packages/agent`, `packages/mosaic`)
-- **Queue**: Valkey 8 (`packages/queue`)
-- **Build**: pnpm workspaces + Turborepo
-- **CI**: Woodpecker CI
-- **Observability**: OpenTelemetry → Jaeger
-
-## Commands
-
-```bash
-pnpm typecheck        # TypeScript check (all packages)
-pnpm lint             # ESLint (all packages)
-pnpm format:check     # Prettier check
-pnpm test             # Vitest (all packages)
-pnpm build            # Build all packages
-
-# Database
-pnpm --filter @mosaicstack/db db:push      # Push schema to PG (dev)
-pnpm --filter @mosaicstack/db db:generate  # Generate migrations
-pnpm --filter @mosaicstack/db db:migrate   # Run migrations
-
-# Dev
-docker compose up -d                  # Start PG, Valkey, OTEL, Jaeger
-pnpm --filter @mosaicstack/gateway exec tsx src/main.ts  # Start gateway
-```
-
-## Conventions
-
-- ESM everywhere (`"type": "module"`, `.js` extensions in imports)
-- NodeNext module resolution
-- Explicit `@Inject()` decorators in NestJS (tsx/esbuild doesn't support emitDecoratorMetadata)
-- DTOs in `*.dto.ts` files at module boundaries
-- OTEL tracing imported before NestJS bootstrap (`import './tracing.js'`)
-- All three gates must pass before push: typecheck, lint, format:check
+@AGENTS.md

Containerfile

@@ -0,0 +1,43 @@
+# Minimal Mosaic Stack POC agent image.
+# Base: maintained Node.js image (same family as Pi's documented
+# containerization example in docs/containerization.md).
+FROM node:24-bookworm-slim
+
+# Tools Pi's documented container image expects (bash, CA certs, git, ripgrep).
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
+    && rm -rf /var/lib/apt/lists/*
+
+# Non-root user: the maintained node image ships a 'node' user at
+# uid/gid 1000, which matches the host user that owns the runtime
+# state directory mounted at /var/lib/mosaic. It is reused as-is.
+
+# Pinned Pi install: package.json pins the exact version and
+# package-lock.json is installed with npm ci. No unversioned installs.
+WORKDIR /opt/app
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts
+
+# Immutable contract fixtures (required location), runtime scripts, and
+# runtime adapters.
+COPY contracts /opt/mosaic/contracts
+COPY src /opt/mosaic/src
+COPY adapters /opt/mosaic/adapters
+RUN chmod 0555 /opt/mosaic/contracts /opt/mosaic/contracts/* \
+    && chmod 0555 /opt/mosaic/src /opt/mosaic/src/*.sh \
+    && chmod 0555 /opt/mosaic/adapters /opt/mosaic/adapters/*/adapter.sh
+
+# Writable state, workspace, and pi agent directory (auth.json is
+# bind-mounted read-only at runtime; nothing is copied into the image).
+RUN mkdir -p /var/lib/mosaic /workspace /home/node/.pi/agent \
+    && chown -R node:node /var/lib/mosaic /workspace /home/node /opt/app
+
+USER node
+WORKDIR /workspace
+ENV HOME=/home/node \
+    PATH="/opt/app/node_modules/.bin:${PATH}" \
+    PI_OFFLINE=1
+
+# One-shot agent: args form the user request (default is the startup
+# verification request defined in compose.yaml).
+ENTRYPOINT ["/opt/mosaic/src/run-agent.sh"]

LAYERS.md

@@ -0,0 +1,50 @@
+# LAYERS
+
+Deferred capability layers for the Mosaic experiment. Only L0 is implemented by
+this proof of concept; everything below it is documented here and deliberately
+not implemented (see BRIEF.md, "Explicit exclusions").
+
+## L0 — Implemented: container returns MOSAIC_HELLO_OK
+
+One image (`mosaic-poc-agent:0.84.4`, built on `node:24-bookworm-slim`, non-root,
+pinned Pi) runs one Pi agent one-shot. Four immutable local contract files are
+loaded in fixed order into the generated system prompt
+(`/var/lib/mosaic/system-prompt.md`). One real model request is sent
+noninteractively; the response must equal `MOSAIC_HELLO_OK` exactly or the
+verification exits nonzero. Authentication is supplied at runtime only
+(read-only mounted pi auth file, or a provider API key environment variable).
+
+## L1 — Deferred: persist and resume a named Pi session
+
+Keep a named Pi session across container runs (`--name`, session storage under
+`/var/lib/mosaic`), resume it with the documented session flags, and verify
+state survives a container restart.
+
+## L2 — Deferred: fixed tool permission policy
+
+Add a fixed allow/deny policy for Pi tools (e.g. restricting built-in tools via
+documented `--tools` / `--exclude-tools` or an extension-based permission gate),
+so contract files can constrain what the agent may do, not just what it says.
+
+## L3 — Deferred: load full versioned contract bundles
+
+Replace the four static fixtures with versioned contract bundles: bundle
+manifests, contract versions, and deterministic ordering/hashing, loaded from
+an immutable bundle artifact instead of files copied at image build time.
+
+## L4 — Deferred: Claude as a second runtime
+
+Add a second runtime (Claude) alongside the Pi agent in the same container
+stack, behind the same contract-loading path, to compare behavior across
+runtimes.
+
+## L5 — Deferred: multiple agents and communication
+
+Run several named agents with defined roles and a communication channel between
+them (message passing or shared state under `/var/lib/mosaic`).
+
+## L6 — Deferred: orchestration, knowledge storage, and portal features
+
+Fleet-level orchestration, knowledge storage, monitoring, and portal UI on top
+of L1-L5. This is where the existing Mosaic Stack concepts would be re-evaluated
+from first principles.

README.md

@@ -1,348 +1,238 @@
-# Mosaic Stack
+# Mosaic Stack — new foundation
 
-Self-hosted, multi-user AI agent platform. One config, every runtime, same standards.
+The active rebuild is at this repository's root. The original Mosaic Stack v1
+source is archived under `v1/`; it is not the implementation being developed here.
 
-Mosaic gives you a unified launcher for Claude Code, Codex, OpenCode, and Pi — injecting consistent system prompts, guardrails, skills, and mission context into every session. A NestJS gateway provides the API surface, a Next.js dashboard gives you the UI, and a plugin system connects Discord, Telegram, and more.
+- Canonical checkout: `/mnt/storage/src/mosaic-stack`
+- Repository: `mosaicstack/stack`
+- Working branch: `refactor`
+- Former `~/src/mosaic-stack-dev-test`: compatibility symlink to this same checkout
 
-## Quick Install
+Both original Git histories and pending development work are preserved. See the
+[conversion record](docs/plans/2026-09-07_repository-consolidation-completed.md)
+and [current next action](docs/plans/CURRENT.md). Do not use v1's startup commands,
+package layout or agent instructions for work on the new foundation.
 
-```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/mosaic-stack/raw/branch/main/tools/install.sh)
+## Original container proof
+
+The foundation began as a standalone container experiment. One container image
+runs one Pi coding agent with four immutable local contract files as its system
+prompt, sends exactly one real model request, and was verified to return exactly
+`MOSAIC_HELLO_OK`. This historical result is not a claim that the full rebuild is
+production-ready.
+
+## Layout
+
+```text
+BRIEF.md            requirements for the original container proof
+BUILD-LOG.md        append-only build/verification log
+LAYERS.md           implemented layer (L0) and deferred layers (L1-L6)
+Containerfile       image definition (node:24-bookworm-slim, non-root, pinned Pi)
+compose.yaml        one service: mosaic-agent (one-shot; configured via env)
+package.json        pins @earendil-works/pi-coding-agent at exactly 0.84.4
+package-lock.json   resolved lockfile used by npm ci in the image
+.env.example        non-secret settings only (credential-file path, env-var auth)
+contracts/          CONSTITUTION.md, STANDARDS.md, SOUL.md, USER.md (immutable fixtures)
+scripts/            bootstrap/build/hello/verify/reset + config tooling
+src/                load-contracts.sh, run-agent.sh (run inside the container)
+docs/plans/         architecture and milestone plans
 ```
 
-The installer auto-launches the setup wizard, which walks you through gateway install and verification. Flags for non-interactive use:
+## Configuration
 
-```bash
-bash <(curl -fsSL …) --yes               # Accept all defaults
-bash <(curl -fsSL …) --yes --no-auto-launch  # Install only, skip wizard
+The sole discovery entry point is:
+
+```text
+~/.config/mosaic-dev/config.json
 ```
 
-This installs both components:
-
-| Component               | What                                                             | Where                |
-| ----------------------- | ---------------------------------------------------------------- | -------------------- |
-| **Framework**           | Bash launcher, guides, runtime configs, tools, skills            | `~/.config/mosaic/`  |
-| **@mosaicstack/mosaic** | Unified `mosaic` CLI — TUI, gateway client, wizard, auto-updater | `~/.npm-global/bin/` |
-
-After install, the wizard runs automatically or you can invoke it manually:
+Created only by the explicit, idempotent bootstrap:
 
 ```bash
-mosaic wizard        # Full guided setup (gateway install → verify)
+scripts/bootstrap.sh   # create-if-absent; validates existing config, never rewrites
 ```
 
-### Requirements
+Minimal shape (`configVersion` 1):
 
-- Node.js ≥ 20
-- npm (for global @mosaicstack/mosaic install)
-- One or more runtimes: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), or [Pi](https://github.com/mariozechner/pi-coding-agent)
+```json
+{
+  "configVersion": 1,
+  "environment": "development",
+  "dataRoot": "/home/jwoltje/.mosaic-dev",
+  "execution": {
+    "backend": "docker",
+    "provider": "zai",
+    "model": "glm-5.3-flash"
+  }
+}
+```
+
+Rules enforced by `scripts/mosaic-config.mjs`:
+
+- Unknown keys, unsupported versions/backends, and malformed JSON exit nonzero; nothing is modified.
+- `dataRoot` must be absolute, canonical, and must not be or contain the home or configuration directory.
+- Validation failures never touch config, state, or images.
+- `scripts/test-config.sh` runs the sandboxed config selftests (no Docker required).
+
+Run paths (`build/hello/verify/reset`) fail closed when configuration is missing or invalid; they never invent it.
+
+## Missions & tasks (M2)
+
+Missions and tasks are validated JSON data (strict schemas, version-pinned). The M2 layer is host-side only: mission directives are recorded for provenance but do not yet reach the runtime system prompt (capability/policy layer comes later).
+
+```text
+missions/hello.json          objective + directives (missionVersion 1)
+tasks/hello-marker.json      prompt + optional mission ref + expectExact + timeout
+<dataRoot>/runs/r-<id>/      immutable run record: task.json, mission.json,
+                             stderr.txt, result.json (all write-once)
+```
+
+Usage:
+
+```bash
+scripts/run-task.sh validate tasks/hello-marker.json   # strict validation, writes nothing
+scripts/run-task.sh run tasks/hello-marker.json        # execute; result recorded under dataRoot/runs
+scripts/mosaic-task.mjs list                           # list runs and statuses
+scripts/test-task.sh                                   # selftests (schema negatives + live runs)
+```
+
+A run exits 0 only when its expectation is met (`expectExact` match); mismatches, nonzero agent exits, and timeouts record `status: failed` in `result.json` and exit 1. Each run gets a unique directory — rerunning never rewrites history.
+
+## Release model (M3)
+
+`RELEASE` single-sources the release version (0.0.X until declared stable); the image tag derives from it plus the pinned Pi version. Activation is health-gated and every event is recorded:
+
+```bash
+scripts/release.sh package                    # build + tag the release image
+scripts/release.sh activate                   # health check (exact marker) -> atomic pointer swap
+scripts/release.sh activate --fault-injection # prove the refusal path (drills only)
+scripts/release.sh rollback                   # health-gated return to the previous release
+scripts/release.sh ensure                     # self-determination: align installed to RELEASE (safe no-op when aligned)
+scripts/release.sh status                     # release, tag, active pointer, recent log
+scripts/test-release.sh                       # release selftests
+```
+
+`ensure` is invoked automatically by the human-facing launchers (`hello`,
+`verify`, `agent`): the system determines what is installed and aligns
+itself — the user never runs release commands manually.
+
+- `<dataRoot>/state/active.json` — the activation pointer (atomic tmp+rename replace)
+- `<dataRoot>/state/activation-log.jsonl` — append-only history: package / activate / refused / rollback
+
+A failed health check never activates; the previously active release remains deployed. Updating the software therefore cannot corrupt the running installation: package beside, gate, then flip. Verified by the update/refusal/rollback drills in BUILD-LOG Phase 7.
+
+## Runtime adapters (M4)
+
+The harness boundary is formalized: everything upstream (config, contracts, missions, tasks, run records) is harness-agnostic; everything inside an adapter belongs to one runtime.
+
+```text
+adapters/<name>/adapter.sh   env in: MOSAIC_SYSTEM_PROMPT_FILE, MOSAIC_REQUEST,
+                             MOSAIC_PROVIDER, MOSAIC_MODEL
+                             stdout: response only; stderr: diagnostics
+```
+
+- Selection: `execution.adapter` in config.json (optional; `pi` default; allowlist `pi`, `mock`)
+- `pi` — pinned Pi CLI, noninteractive print mode, ambient discovery off
+- `mock` — deterministic test adapter; never for real verification
+- Mission directives have a sanctioned injection point: when a task references a mission, the task runner mounts the run snapshot and the generated prompt gains a `MISSION (runtime)` section (objective + directives) after the four immutable contracts
+- Adding a harness (Claude, Codex, OpenCode) later means adding one directory — no orchestrator changes
+
+See `adapters/README.md` for the full contract.
+
+## Workspaces, capabilities, sessions (M5/M6)
+
+Optional task fields extend what an agent can do — all defaulting to the previous behavior:
+
+```json
+{
+  "workspace": "demo",                          // ":run" ephemeral, or persistent dataRoot/workspaces/<name>
+  "capabilities": { "tools": ["bash", "read"] }, // pi tool allowlist; absent = no tools
+  "session": "demo"                             // persistent session at dataRoot/sessions/<name>
+}
+```
+
+- The adapter runs inside the workspace; files it writes are host-visible (`dataRoot/workspaces/<name>`).
+- Sessions persist via pi's documented `--session-dir`; a follow-up run in the same session resumes the conversation (`-c`) and can recall prior context. Distinct names never share state. Ephemeral (`--no-session`) remains the default when no session is declared.
+- Selection authority: config for adapter/provider/model; the task file for workspace/capabilities/session.
+
+Inspect anything:
+
+```bash
+node scripts/mosaic-task.mjs list                # runs with task/workspace/session columns
+node scripts/mosaic-task.mjs show <runId>        # full record + snapshots + artifacts
+```
+
+Demo fixtures: `tasks/workspace-demo.json`, `tasks/session-demo-1.json` + `tasks/session-demo-2.json`.
+
+See `docs/plans/2026-09-02_atomic-mosaic-foundation.md` for the full plan.
+
+Inside the container:
+
+```text
+/opt/mosaic/contracts     immutable contract files
+/var/lib/mosaic           generated runtime state (mounted from configured dataRoot)
+/workspace                agent workspace
+```
+
+## How it works
+
+1. `scripts/build.sh` builds the release image (`mosaic-poc-agent:<pi>-r<release>`,
+   tag derived from `RELEASE` + the pinned Pi version) with Docker Compose.
+2. On each run, `/opt/mosaic/src/load-contracts.sh` reads the four contract files
+   in fixed order (CONSTITUTION, STANDARDS, SOUL, USER), joins them with clear
+   separators, and writes `/var/lib/mosaic/system-prompt.md`.
+3. `/opt/mosaic/src/run-agent.sh` starts Pi noninteractively
+   (`pi -p "Return your startup marker and nothing else."`) with
+   `--system-prompt "$(cat /var/lib/mosaic/system-prompt.md)"` and all ambient
+   discovery disabled (`--no-context-files --no-skills --no-extensions
+   --no-prompt-templates --no-themes`), ephemeral (`--no-session`), tool-free
+   (`--no-tools`), and offline for startup network operations (`--offline`).
+4. `scripts/verify.sh` trims surrounding whitespace from the response and exits 0
+   only when it equals `MOSAIC_HELLO_OK` exactly.
 
 ## Usage
 
-### Launching Agent Sessions
+```bash
+scripts/bootstrap.sh   # create config.json if absent (idempotent)
+scripts/build.sh       # build the image
+scripts/hello.sh       # one-shot request; prints the model response
+scripts/verify.sh      # full gated test; exit 0 only on exact MOSAIC_HELLO_OK
+scripts/run-task.sh    # run a mission/task file (see Missions & tasks)
+scripts/release.sh     # package / activate / rollback / status (see Release model)
+scripts/test-config.sh # fast config-layer selftests (no Docker)
+scripts/test-task.sh   # mission/task selftests (schema + adapter seam + live runs)
+scripts/test-release.sh # release selftests
+scripts/reset.sh       # delete the configured data root (safety-checked)
+```
+
+Prove the failure path (acceptance criterion 9):
 
 ```bash
-mosaic pi                    # Launch Pi with Mosaic injection
-mosaic claude                # Launch Claude Code with Mosaic injection
-mosaic codex                 # Launch Codex with Mosaic injection
-mosaic opencode              # Launch OpenCode with Mosaic injection
-
-mosaic yolo claude           # Claude with dangerous-permissions mode
-mosaic yolo pi               # Pi in yolo mode
+EXPECTED_MARKER=MOSAIC_NOT_OK scripts/verify.sh   # must exit nonzero
 ```
 
-The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md` standards into the runtime, and forwards all arguments.
-
-### TUI & Gateway
-
-```bash
-mosaic tui                   # Interactive TUI connected to the gateway
-mosaic gateway login         # Authenticate with a gateway instance
-mosaic sessions list         # List active agent sessions
-```
-
-### Gateway Management
-
-```bash
-mosaic gateway install       # Install and configure the gateway service
-mosaic gateway verify        # Post-install health check
-mosaic gateway login         # Authenticate and store a session token
-mosaic gateway config rotate-token    # Rotate your API token
-mosaic gateway config recover-token  # Recover a token via BetterAuth cookie
-```
-
-If you already have a gateway account but no token, use `mosaic gateway config recover-token` to retrieve one without recreating your account.
-
-### Configuration
-
-```bash
-mosaic config show           # Print full config as JSON
-mosaic config get <key>      # Read a specific key
-mosaic config set <key> <val># Write a key
-mosaic config edit           # Open config in $EDITOR
-mosaic config path           # Print config file path
-```
-
-### Management
-
-```bash
-mosaic doctor                # Health audit — detect drift and missing files
-mosaic sync                  # Sync skills from canonical source
-mosaic update                # Check for and install CLI updates
-mosaic wizard                # Full guided setup wizard
-mosaic bootstrap <path>      # Bootstrap a repo with Mosaic standards
-mosaic coord init            # Initialize a new orchestration mission
-mosaic prdy init             # Create a PRD via guided session
-```
-
-### Sub-package Commands
-
-Each Mosaic sub-package exposes its API surface through the unified CLI:
-
-```bash
-# User management
-mosaic auth users list
-mosaic auth users create
-mosaic auth sso
-
-# Agent brain (projects, missions, tasks)
-mosaic brain projects
-mosaic brain missions
-mosaic brain tasks
-mosaic brain conversations
-
-# Agent forge pipeline
-mosaic forge run
-mosaic forge status
-mosaic forge resume
-mosaic forge personas
-
-# Structured logging
-mosaic log tail
-mosaic log search
-mosaic log export
-mosaic log level
-
-# MACP protocol
-mosaic macp tasks
-mosaic macp submit
-mosaic macp gate
-mosaic macp events
-
-# Agent memory
-mosaic memory search
-mosaic memory stats
-mosaic memory insights
-mosaic memory preferences
-
-# Task queue (Valkey)
-mosaic queue list
-mosaic queue stats
-mosaic queue pause
-mosaic queue resume
-mosaic queue jobs
-mosaic queue drain
-
-# Object storage
-mosaic storage status
-mosaic storage tier
-mosaic storage export
-mosaic storage import
-mosaic storage migrate
-```
-
-### Telemetry
-
-```bash
-# Local observability (OTEL / Jaeger)
-mosaic telemetry local status
-mosaic telemetry local tail
-mosaic telemetry local jaeger
-
-# Remote telemetry (dry-run by default)
-mosaic telemetry status
-mosaic telemetry opt-in
-mosaic telemetry opt-out
-mosaic telemetry test
-mosaic telemetry upload        # Dry-run unless opted in
-```
-
-Consent state is persisted in config. Remote upload is a no-op until you run `mosaic telemetry opt-in`.
-
-## Development
-
-### Prerequisites
-
-- Node.js ≥ 20
-- pnpm 10.6+
-- Docker & Docker Compose
-
-### Setup
-
-```bash
-git clone [email protected]:mosaicstack/mosaic-stack.git
-cd mosaic-stack
-
-# Start infrastructure (Postgres, Valkey, Jaeger)
-docker compose up -d
-
-# Install dependencies
-pnpm install
-
-# Run migrations
-pnpm --filter @mosaicstack/db run db:migrate
-
-# Start all services in dev mode
-pnpm dev
-```
-
-### Infrastructure
-
-Docker Compose provides:
-
-| Service               | Port      | Purpose                |
-| --------------------- | --------- | ---------------------- |
-| PostgreSQL (pgvector) | 5433      | Primary database       |
-| Valkey                | 6380      | Task queue + caching   |
-| Jaeger                | 16686     | Distributed tracing UI |
-| OTEL Collector        | 4317/4318 | Telemetry ingestion    |
-
-### Quality Gates
-
-```bash
-pnpm typecheck               # TypeScript type checking (all packages)
-pnpm lint                    # ESLint (all packages)
-pnpm test                    # Vitest (all packages)
-pnpm format:check            # Prettier check
-pnpm format                  # Prettier auto-fix
-```
-
-### CI
-
-Woodpecker CI runs on every push:
-
-- `pnpm install --frozen-lockfile`
-- Database migration against a fresh Postgres
-- `pnpm test` (Turbo-orchestrated across all packages)
-
-npm packages are published to the Gitea package registry on main merges.
-
-## Architecture
-
-```
-mosaic-stack/
-├── apps/
-│   ├── gateway/             NestJS API + WebSocket hub (Fastify, Socket.IO, OTEL)
-│   └── web/                 Next.js dashboard (React 19, Tailwind)
-├── packages/
-│   ├── mosaic/              Unified CLI — TUI, gateway client, wizard, sub-package commands
-│   ├── types/               Shared TypeScript contracts (Socket.IO typed events)
-│   ├── db/                  Drizzle ORM schema + migrations (pgvector)
-│   ├── auth/                BetterAuth configuration
-│   ├── brain/               Data layer (PG-backed)
-│   ├── queue/               Valkey task queue + MCP
-│   ├── coord/               Mission coordination
-│   ├── forge/               Multi-stage AI pipeline (intake → board → plan → code → review)
-│   ├── macp/                MACP protocol — credential resolution, gate runner, events
-│   ├── agent/               Agent session management
-│   ├── memory/              Agent memory layer
-│   ├── log/                 Structured logging
-│   ├── prdy/                PRD creation and validation
-│   ├── quality-rails/       Quality templates (TypeScript, Next.js, monorepo)
-│   └── design-tokens/       Shared design tokens
-├── plugins/
-│   ├── discord/             Discord channel plugin (discord.js)
-│   ├── telegram/            Telegram channel plugin (Telegraf)
-│   ├── macp/                OpenClaw MACP runtime plugin
-│   └── mosaic-framework/    OpenClaw framework injection plugin
-├── tools/
-│   └── install.sh           Unified installer (framework + npm CLI, --yes / --no-auto-launch)
-├── scripts/agent/           Agent session lifecycle scripts
-├── docker-compose.yml       Dev infrastructure
-└── .woodpecker/             CI pipeline configs
-```
-
-### Key Design Decisions
-
-- **Gateway is the single API surface** — all clients (TUI, web, Discord, Telegram) connect through it
-- **ESM everywhere** — `"type": "module"`, `.js` extensions in imports, NodeNext resolution
-- **Socket.IO typed events** — defined in `@mosaicstack/types`, enforced at compile time
-- **OTEL auto-instrumentation** — loads before NestJS bootstrap
-- **Explicit `@Inject()` decorators** — required since tsx/esbuild doesn't emit decorator metadata
-
-### Framework (`~/.config/mosaic/`)
-
-The framework is the bash-based standards layer installed to every developer machine:
-
-```
-~/.config/mosaic/
-├── AGENTS.md              ← Central standards (loaded into every runtime)
-├── SOUL.md                ← Agent identity (name, style, guardrails)
-├── USER.md                ← User profile (name, timezone, preferences)
-├── TOOLS.md               ← Machine-level tool reference
-├── bin/mosaic             ← Unified launcher (claude, codex, opencode, pi, yolo)
-├── guides/                ← E2E delivery, orchestrator protocol, PRD, etc.
-├── runtime/               ← Per-runtime configs (claude/, codex/, opencode/, pi/)
-├── skills/                ← Universal skills (synced from agent-skills repo)
-├── tools/                 ← Tool suites (orchestrator, git, quality, prdy, etc.)
-└── memory/                ← Persistent agent memory (preserved across upgrades)
-```
-
-### Forge Pipeline
-
-Forge is a multi-stage AI pipeline for autonomous feature delivery:
-
-```
-Intake → Discovery → Board Review → Planning (3 stages) → Coding → Review → Remediation → Test → Deploy
-```
-
-Each stage has a dispatch mode (`exec` for research/review, `yolo` for coding), quality gates, and timeouts. The board review uses multiple AI personas (CEO, CTO, CFO, COO + specialists) to evaluate briefs before committing resources.
-
-## Upgrading
-
-Run the installer again — it handles upgrades automatically:
-
-```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/mosaic-stack/raw/branch/main/tools/install.sh)
-```
-
-Or use the CLI:
-
-```bash
-mosaic update                # Check + install CLI updates
-mosaic update --check        # Check only, don't install
-```
-
-The CLI also performs a background update check on every invocation (cached for 1 hour).
-
-### Installer Flags
-
-```bash
-bash tools/install.sh --check           # Version check only
-bash tools/install.sh --framework       # Framework only (skip npm CLI)
-bash tools/install.sh --cli             # npm CLI only (skip framework)
-bash tools/install.sh --ref v1.0        # Install from a specific git ref
-bash tools/install.sh --yes             # Non-interactive, accept all defaults
-bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
-```
-
-## Contributing
-
-```bash
-# Create a feature branch
-git checkout -b feat/my-feature
-
-# Make changes, then verify
-pnpm typecheck && pnpm lint && pnpm test && pnpm format:check
-
-# Commit (husky runs lint-staged automatically)
-git commit -m "feat: description of change"
-
-# Push and create PR
-git push -u origin feat/my-feature
-```
-
-DTOs go in `*.dto.ts` files at module boundaries. Scratchpads (`docs/scratchpads/`) are mandatory for non-trivial tasks. See `AGENTS.md` for the full standards reference.
-
-## License
-
-Proprietary — all rights reserved.
+## Authentication
+
+Pi's documented container authentication (see the package's
+`docs/containerization.md`) is used, in this order:
+
+1. **Read-only mounted credential file** (default): the host pi auth file
+   `~/.pi/agent/auth.json` is bind-mounted read-only to
+   `/home/node/.pi/agent/auth.json`. The host file holds a static API-key
+   entry for the built-in `zai` provider, so no token refresh writes are needed.
+2. **Runtime environment variable** (documented alternative): set `ZAI_API_KEY`
+   or `ANTHROPIC_API_KEY` in the environment or in a gitignored `.env`; compose
+   passes them through. Pi's documented precedence applies.
+
+Credentials are never committed, never copied into the image, and never printed.
+Mosaic-managed named accounts (`agent.sh --auth`) live under the data root
+(`auth/<account>.json`, 0600) — the stack never writes into `~/.pi`.
+`.env.example` contains non-secret settings only.
+
+## Boundaries honored
+
+- No mounts of `~/.mosaic` or `~/.config/mosaic`; no Docker socket mount.
+- Source stays in this project directory; generated state only in
+  `/home/jwoltje/.mosaic-dev` (host) and `/var/lib/mosaic` (container).
+- No database, web server, queue, second container, orchestration, Git
+  integration, persistent sessions, or policy machinery.

RELEASE

@@ -0,0 +1 @@
+0.0.12

SOUL.md

@@ -0,0 +1,30 @@
+# Mosaic Stack
+
+You are the default collaborator for Mosaic Stack: a practical engineering
+partner helping people build, inspect, and operate a trustworthy foundation
+for delegated work.
+
+Mosaic Stack is deliberately small, file-based, and evidence-oriented. Its
+purpose is not to perform confidence; it is to make useful work attributable,
+bounded, reproducible, and reviewable. Treat the system's contracts, policies,
+and run records as part of the product, not paperwork around it.
+
+Work with calm precision. Start from what the user is trying to accomplish,
+make the next useful step clear, and explain results in plain language. Be
+decisive when the evidence supports a decision; be explicit about uncertainty
+when it does not. Never claim a test, command, integration, or outcome that
+you have not actually verified.
+
+Respect boundaries. Ask before expanding scope, changing authority, touching
+credentials, or taking an irreversible external action. Prefer the least
+privileged path, preserve user work, and stop on a policy or validation
+refusal rather than working around it. A clean refusal with a useful diagnosis
+is better than a superficially successful but untrustworthy result.
+
+Leave a legible trail. Make changes intentional, keep records honest, and
+report what changed, how it was checked, and what remains unresolved. When
+coordinating other workers, give each one a bounded objective and review their
+evidence instead of treating their confidence as proof.
+
+The aim is dependable progress: small enough to understand, safe enough to
+trust, and concrete enough for a person to verify.

adapters/README.md

@@ -0,0 +1,54 @@
+# Mosaic runtime adapters
+
+An adapter is the entire harness-specific surface of the system. Everything
+upstream of an adapter — configuration, contracts, missions, tasks, run
+records — is harness-agnostic; everything inside an adapter may assume one
+specific agent runtime.
+
+## Contract
+
+An adapter lives at:
+
+```text
+/opt/mosaic/adapters/<name>/adapter.sh
+```
+
+and must be executable. The dispatcher (`/opt/mosaic/src/run-agent.sh`)
+selects it via `MOSAIC_ADAPTER` (default: `pi`) and execs it after the
+system prompt has been generated.
+
+**Inputs (environment):**
+
+| Variable | Meaning |
+|---|---|
+| `MOSAIC_SYSTEM_PROMPT_FILE` | Absolute path to the generated system prompt (contracts + optional mission section). Read it; do not modify it. |
+| `MOSAIC_REQUEST` | The exact user request text (may contain newlines). |
+| `MOSAIC_PROVIDER` | Configured provider name. |
+| `MOSAIC_MODEL` | Configured model id. |
+
+Optional, adapter-specific (documented per adapter):
+
+| Variable | Meaning |
+|---|---|
+| `MOSAIC_MOCK_RESPONSE` | mock only: the verbatim response to emit |
+
+**Outputs:**
+
+- `stdout`: the model response text — the only channel the orchestrator captures
+- `stderr`: diagnostics (never credentials)
+- exit `0`: success; nonzero: failure
+
+## Rules
+
+1. Adapters print ONLY the response on stdout. Status lines go to stderr.
+2. Adapters never read configuration files; the resolved settings arrive via environment.
+3. Adapters never write outside `/var/lib/mosaic`.
+4. Adding an adapter requires: a new directory, the contract implementation, and
+   adding the name to the allowlist in `scripts/mosaic-config.mjs`.
+
+## Included adapters
+
+- `pi` — the pinned `@earendil-works/pi-coding-agent` CLI in noninteractive
+  print mode (`-p`), ambient discovery disabled, stdin detached.
+- `mock` — deterministic echo of `MOSAIC_MOCK_RESPONSE`. Test-only: never use
+  it where a real model response is required.

adapters/mock/adapter.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+# Mock adapter: deterministic response for seam tests. NEVER use where a
+# real model response is required.
+#
+# Contract: see /opt/mosaic/adapters/README.md.
+set -eu
+
+[ -n "${MOSAIC_SYSTEM_PROMPT_FILE:-}" ] || { echo "mock adapter: MOSAIC_SYSTEM_PROMPT_FILE is required" >&2; exit 2; }
+if [ "${MOSAIC_INTERACTIVE:-}" != "1" ]; then
+    [ -n "${MOSAIC_REQUEST:-}" ] || { echo "mock adapter: MOSAIC_REQUEST is required" >&2; exit 2; }
+fi
+[ -r "$MOSAIC_SYSTEM_PROMPT_FILE" ] || { echo "mock adapter: system prompt not readable: $MOSAIC_SYSTEM_PROMPT_FILE" >&2; exit 2; }
+
+echo "mock adapter: responding verbatim from MOSAIC_MOCK_RESPONSE" >&2
+# Deterministic plumbing evidence: which MOSAIC_* variables did the
+# orchestrator actually deliver? (Auth secrets are not MOSAIC_-prefixed.)
+(env | grep '^MOSAIC_' | sort) >&2 2>/dev/null || true
+printf '%s\n' "${MOSAIC_MOCK_RESPONSE:-}"

adapters/pi/adapter.sh

@@ -0,0 +1,96 @@
+#!/bin/sh
+# Pi adapter: implements the Mosaic adapter contract for the pinned
+# @earendil-works/pi-coding-agent CLI.
+#
+# Contract: see /opt/mosaic/adapters/README.md.
+# Headless (default): stdout = response only; stderr = diagnostics; exit 0.
+# Interactive (MOSAIC_INTERACTIVE=1): full pi TUI on the attached terminal.
+set -eu
+
+[ -n "${MOSAIC_SYSTEM_PROMPT_FILE:-}" ] || { echo "pi adapter: MOSAIC_SYSTEM_PROMPT_FILE is required" >&2; exit 2; }
+[ -r "$MOSAIC_SYSTEM_PROMPT_FILE" ] || { echo "pi adapter: system prompt not readable: $MOSAIC_SYSTEM_PROMPT_FILE" >&2; exit 2; }
+# MOSAIC_AGENT_NAME is optional in headless mode (identity section is then
+# omitted); interactive launches always set it via scripts/agent.sh.
+
+: "${PI_PROVIDER:?pi adapter: PI_PROVIDER is required}"
+: "${PI_MODEL:?pi adapter: PI_MODEL is required}"
+
+INTERACTIVE="${MOSAIC_INTERACTIVE:-}"
+if [ "$INTERACTIVE" != "1" ]; then
+    [ -n "${MOSAIC_REQUEST:-}" ] || { echo "pi adapter: MOSAIC_REQUEST is required" >&2; exit 2; }
+fi
+
+# Workspace (M5): run inside the provided workspace when present.
+if [ -n "${MOSAIC_WORKSPACE:-}" ]; then
+    mkdir -p "$MOSAIC_WORKSPACE"
+    cd "$MOSAIC_WORKSPACE"
+fi
+
+# Session (M6/M11): default ephemeral (--no-session). With a declared
+# session dir: persist there and resume the most recent session. With a
+# fork source: branch the source session file into the target dir
+# (pi --fork) - the ancestor session is never modified.
+SESSION_FLAGS="--no-session"
+if [ -n "${MOSAIC_SESSION_FORK:-}" ]; then
+    [ -n "${MOSAIC_SESSION_DIR:-}" ] || { echo "pi adapter: session fork requires MOSAIC_SESSION_DIR" >&2; exit 2; }
+    mkdir -p "$MOSAIC_SESSION_DIR"
+    SESSION_FLAGS="--fork $MOSAIC_SESSION_FORK --session-dir $MOSAIC_SESSION_DIR"
+elif [ -n "${MOSAIC_SESSION_DIR:-}" ]; then
+    mkdir -p "$MOSAIC_SESSION_DIR"
+    SESSION_FLAGS="--session-dir $MOSAIC_SESSION_DIR"
+    if [ -n "$(ls -A "$MOSAIC_SESSION_DIR" 2>/dev/null)" ]; then
+        SESSION_FLAGS="$SESSION_FLAGS -c"
+    fi
+fi
+
+# Capabilities (M5): explicit allowlist or no tools.
+TOOLS_FLAG="--no-tools"
+[ -n "${MOSAIC_TOOLS:-}" ] && TOOLS_FLAG="--tools $MOSAIC_TOOLS"
+
+# Skills (M17): explicitly provided skill dirs replace discovery. When none
+# are provided the agent runs with --no-skills (nothing ambient to find).
+SKILLS_FLAG="--no-skills"
+if [ -n "${MOSAIC_SKILLS:-}" ]; then
+    SKILLS_FLAG=""
+    OLDIFS=$IFS; IFS=','
+    for s in $MOSAIC_SKILLS; do
+        [ -d "$s" ] || { echo "pi adapter: skill dir missing: $s" >&2; exit 2; }
+        SKILLS_FLAG="$SKILLS_FLAG --skill $s"
+    done
+    IFS=$OLDIFS
+fi
+
+# Mode (M13): interactive TUI or one-shot print.
+PRINT_MODE="-p"
+REQUEST_ARG=""
+if [ "$INTERACTIVE" = "1" ]; then
+    PRINT_MODE=""
+else
+    REQUEST_ARG="$MOSAIC_REQUEST"
+fi
+
+# All flags documented in the pi package README (CLI Reference):
+#   -p/--print     one-shot mode: print the response and exit (omitted in
+#                  interactive TUI mode)
+#   --system-prompt  replace the default prompt with the generated one
+#   --no-*         no ambient context/skills/extensions/templates/themes
+#   SESSION_FLAGS  ephemeral | persistent | forked (per env)
+#   TOOLS_FLAG     per capabilities
+#   --offline      no startup network operations (update checks/telemetry)
+PROMPT_CONTENT="$(cat "$MOSAIC_SYSTEM_PROMPT_FILE")"
+set -- \
+    --offline \
+    --no-extensions \
+    $SKILLS_FLAG \
+    --no-prompt-templates \
+    --no-themes \
+    --no-context-files \
+    $TOOLS_FLAG \
+    $SESSION_FLAGS \
+    --provider "$PI_PROVIDER" \
+    --model "$PI_MODEL" \
+    --system-prompt "$PROMPT_CONTENT"
+# One-shot mode appends -p and the request (both safely quoted);
+# interactive mode appends nothing - clean TUI.
+[ "$INTERACTIVE" = "1" ] || set -- "$@" -p "$MOSAIC_REQUEST"
+exec pi "$@"

agents/darkwing/CONTEXT.md

@@ -0,0 +1,38 @@
+
+===== DARKWING NATIVE DEVELOPMENT CONTEXT =====
+
+Your identity is Darkwing. This launch runs Pi directly on the host, in the
+Mosaic Stack development repository. The injected SOUL defines your persona;
+CONSTITUTION and STANDARDS supply governance, USER supplies user context,
+and AGENTS.md supplies repository instructions.
+
+You have host read, bash, edit, write, grep, find, and ls tools. This is a
+development TUI with the operator's OS access, not a sandbox or a registered
+managed fleet seat. Use repository scripts for Mosaic operations and inspect
+their effects before running them. Container paths in skills describe worker
+deployments, not your current workspace. A tool's presence is not authority
+to change unrelated files, other agents' work, or the live fleet.
+
+For an assigned improvement, inspect the implementation, reproduce the issue,
+make the smallest useful change, verify it, and continue through the authorized
+outcome. Read docs/plans/CURRENT.md to reconcile ownership and existing gates;
+a new user assignment does not silently resume unrelated queued work.
+
+The local /goal extension is loaded and owns any operator-set goal lifecycle.
+Use ms-proactive-agent for work selection and ms-goal for recovery guidance;
+do not create a competing goal loop. Follow goal_report's actual schema and
+reporting instructions. Its text format is Just Completed / Next Step /
+Blocked, with '* none' for empty sections. No external reporting skill is
+needed to discover that format. Native development packaging supersedes
+older skill statements that this extension is unavailable.
+
+For relocation recovery, read agents/darkwing/work/RESTART.md after the root
+AGENTS.md and docs/plans/CURRENT.md. It records verified checkpoints and limits,
+not a new assignment. The canonical checkout is /mnt/storage/src/mosaic-stack;
+v1/ is archived legacy source. Reconcile newer owner direction before acting.
+
+Conversation history persists across launcher restarts. Goals belong to a
+single process incarnation; recover the assignment from verified records and
+the operator's direction after a restart. No goal is started by this launcher.
+Context is captured anew at launch; source edits do not update this process's
+injected snapshot. Relaunch to load approved context changes.

agents/darkwing/README.md

@@ -0,0 +1,64 @@
+# Darkwing development TUI
+
+From any terminal, run:
+
+```sh
+/home/jwoltje/src/mosaic-stack-dev-test/agents/darkwing/launch.sh
+```
+
+The agent launcher is a thin shim to `scripts/agent.sh --host-dev darkwing`,
+forwarding all arguments unchanged. `scripts/agent.sh` is the common entry
+point; `scripts/agent-host-dev.sh` implements its native development mode.
+The host launcher opens the repository as Darkwing's workspace.
+It uses the repository-pinned Pi, the configured Mosaic provider/model, and
+native Pi authentication (normal `~/.pi/agent`, or `PI_CODING_AGENT_DIR` if
+explicitly set). It never copies credentials. Install dependencies with
+`npm ci --ignore-scripts --no-audit --no-fund` if needed.
+
+`--check` validates configuration and required inputs without opening Pi or
+calling a model. `--fresh` starts a new conversation without deleting earlier
+ones. Normal launches continue the latest conversation under
+`.pi/state/darkwing/sessions/`; the first launch creates one. A launcher lock
+rejects simultaneous launches through this script. It does not exclude Pi
+processes started another way. Damaged JSONL history refuses automatic resume;
+`--fresh` is an explicit escape hatch that preserves the damaged evidence.
+
+The current files are combined into a private launch snapshot under
+`.pi/state/darkwing/launches/`:
+
+- `contracts/CONSTITUTION.md` and `contracts/STANDARDS.md`
+- `agents/darkwing/SOUL.md`
+- `<configured dataRoot>/user/USER.md`, the deployment's live user profile
+- the repository's `AGENTS.md` and Darkwing's `CONTEXT.md`
+
+Use `--soul FILE`, `--constitution FILE`, or `--user FILE` to select alternate
+inputs, including a future `contracts/USER.md`. Relative paths resolve from
+the repository root. Missing or empty inputs refuse launch. Snapshots can
+contain personal context and remain local, with private file permissions.
+Context edits take effect on relaunch, including when resuming a conversation.
+
+The launcher enables coding/search tools, `goal_report`, ten explicit local
+skills, and the canonical goal extension through `scripts/sync-dev-extensions.sh`.
+Ambient context, skills, extensions, templates, and themes are disabled.
+The normal Pi coding prompt is retained with the Mosaic context appended.
+Enter `/goal <assignment and acceptance criteria>` to start continuing work;
+`/goal stop`, `/goal resume`, and `/goal` pause, resume, and inspect it. A new
+process does not automatically adopt a previous process's goal.
+
+This TUI has the operator's host access, including repository edits and host
+commands. Its tool list is not OS isolation. It creates no managed role or
+fleet registration. Worker dispatch still uses the governed Mosaic task runner.
+The user supplies the assignment; launch alone does not start self-modification.
+
+## Deployment findings
+
+The existing `scripts/agent.sh` launches a Docker container, defaults to the
+`agent-<name>` session directory, and asks Pi to continue when that directory
+is nonempty. Its default workspace is `<dataRoot>/workspaces/<name>`, not this
+checkout. `src/load-contracts.sh` loads image-baked governance, an optional
+seat SOUL override, live user Markdown, and mission context into a shared
+prompt path. A seat override requires `agent.json`; a standalone SOUL is not
+discovered. `adapters/pi/adapter.sh` disables extensions. The temporary host
+launcher follows the existing native development path to provide repository
+access and `/goal`, and keeps its conversations separate from container and
+live fleet sessions. It does not invoke release alignment on startup.

agents/darkwing/SOUL.md

@@ -0,0 +1,20 @@
+# SOUL — Darkwing
+
+You are Darkwing, Mosaic Stack's hands-on engineering collaborator. Your job
+is to help Jason make the system dependable by using it, finding where it
+falls short, and carrying authorized improvements through verification.
+
+Be curious, direct, and resourceful. Have a technical opinion and explain
+the evidence behind it. Investigate before guessing. Distinguish a design
+claim, a passing test, and behavior you have observed in the running system.
+
+Use Mosaic's own tools and workflows where they fit. Turn a failure into a
+reproducible case, make a focused correction, and test the behavior again.
+Let each verified improvement inform the next one within the assignment.
+Keep the human informed when the result, scope, or next decision changes.
+
+Own the outcome while respecting other agents' work. Preserve their changes
+and records, give delegated work clear boundaries, and seek independent
+review where required. Self-improvement never grants new authority: changing
+your instructions, permissions, or a live deployment follows the same review
+and authorization rules as any other system change.

agents/darkwing/launch.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Darkwing's native development mode through the Mosaic agent entry point.
+set -euo pipefail
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+exec "$REPO/scripts/agent.sh" --host-dev darkwing "$@"

agents/darkwing/validate-sessions.mjs

@@ -0,0 +1,21 @@
+// Refuse damaged history before Pi's --continue can silently skip it.
+import { readFileSync, lstatSync } from 'node:fs';
+
+try {
+  for (const file of process.argv.slice(2)) {
+    if (!lstatSync(file).isFile()) throw new Error(`not a regular session file: ${file}`);
+    const lines = readFileSync(file, 'utf8').trim().split('\n');
+    const entries = lines.map((line) => JSON.parse(line));
+    const header = entries[0];
+    if (header?.type !== 'session' || typeof header.id !== 'string' || !header.id ||
+        typeof header.version !== 'number' || typeof header.cwd !== 'string' ||
+        !Number.isFinite(Date.parse(header.timestamp)) ||
+        entries.slice(1).some((entry) => !entry || typeof entry.type !== 'string')) {
+      throw new Error(`invalid session structure: ${file}`);
+    }
+    if (header.cwd !== process.cwd()) throw new Error(`session belongs to another workspace: ${file}`);
+  }
+} catch (error) {
+  console.error(`darkwing: cannot safely resume: ${error.message}; inspect history or explicitly use --fresh`);
+  process.exit(1);
+}

agents/darkwing/work/RESTART.md

@@ -0,0 +1,108 @@
+# Darkwing — relocation handoff
+
+Recorded 2026-09-07 17:43 UTC. Jason intends to relaunch with
+`/mnt/storage/src/mosaic-stack/agents/darkwing/launch.sh`.
+This is a recovery note, not a new assignment or automatic goal resumption.
+
+## Read first
+
+1. Root `AGENTS.md` and `docs/plans/CURRENT.md`.
+2. This note, then `git status --short` and `git log --oneline -5`.
+3. Reconcile current owner direction and any newer declared artifacts before acting.
+
+## Repository conversion is completed locally
+
+Jason explicitly ordered the conversion and confirmed no work was active.
+- Canonical checkout: `/mnt/storage/src/mosaic-stack`.
+- Origin: `https://git.mosaicstack.dev/mosaicstack/stack`.
+- Branch: `refactor`.
+- Conversion commit: `127a54fdff1fe6ae56c3197edddf957481465db4`.
+- New foundation is at root. `v1/` is legacy archival source, NOT current code.
+- Old `/home/jwoltje/src/mosaic-stack-dev-test` is a compatibility symlink to this
+  same checkout. Do not recreate a second working copy there.
+- Both histories retained: merge parents v2 `9a5fbdbda74b16adf488fe28138b2ba69ea5e669`
+  and v1 `5d2770002612a09ae0cadc129b4ea30619133e8a`.
+- Exact 3,507-file v1 tracked tree imported; v1 refs under `refs/archive/v1/`.
+- Original v2 refs retained; `stack-v2-archive` remote has a disabled push URL.
+- Only legacy tracked tree and four conversion docs committed. All earlier
+  uncommitted/untracked/ignored work preserved. Index was verified clean.
+- Issue https://git.mosaicstack.dev/mosaicstack/stack/issues/1495 closed explicitly
+  for local conversion. No push, PR/trunk merge or live-service change occurred.
+
+Record: `docs/plans/2026-09-07_repository-consolidation-completed.md`.
+Receipts: `docs/plans/reviews/2026-09-07_repository-conversion-verification.json`
+and `2026-09-07_repository-conversion-postcommit-verification.json`.
+Verified rollback copies, NOT development roots:
+- `/mnt/storage/src/.mosaic-stack-conversion-20260907T172430Z/`
+- `/home/jwoltje/src/.mosaic-stack-dev-test.pre-conversion-20260907T172430Z`
+Do not delete them, launch from them or restore over newer work.
+
+## Current unfinished foundation gate
+
+Jason's A9 acceptance of the first offline synthetic scope/permission inspector
+is pending. Code is independently approved by Filbert; no blocking code finding
+remains at the reviewed r6 candidate. Owner acceptance is not inferred from tests.
+
+- Manifest: `docs/plans/reviews/2026-09-07_foundation-inspector-rocko-build-manifest-r6.json`
+  SHA-256 `a4a4493000aff5905337a643886ca36e7c5377d52deed77b8aeab7174ca73dcf`.
+- Report: `docs/plans/reviews/2026-09-07_foundation-inspector-rocko-build-r6.md`
+  SHA-256 `ee0e83efd7c71eddecf5e26f939e9a34ba85b184cfcd1cffac9ff9e56ea13c37`.
+- APPROVED verdict: `docs/plans/reviews/2026-09-07_foundation-inspector-code-verdict-r6.md`
+  SHA-256 `ab9dd5e5c3cad5c9263e873ff82cac444da2d36040e907e4798b208fa1c08b13`.
+- Guide: `docs/plans/reviews/2026-09-07_foundation-inspector-demo.md`.
+
+All 382 approved inspector files and pinned inputs survived conversion unchanged.
+Actual offline checks: Node 80/0, selftests 43/0, oracle 1,568 records / zero
+schema disagreements, foundation checker PASS, config/auth/conductor 24/15/17.
+Postcommit conductor 17/0 and four CLI demos passed: allowed read, allowed change
+PREVIEW (no mutation), missing-registration refusal, unresolved reassignment with
+original selection retained. Demo inputs are separate synthetic scenarios.
+
+`test-task.sh` and `test-release.sh` remain NOT RUN / DEFERRED under Jason's bounded
+offline-demo ruling. No deployment/native/live/provider/security certification.
+Reviewer qualifications: ordering equality means structural equality, not byte
+identity; auxiliary native-parser warm-run anomalies remain separate unresolved
+observations, not a passing universal parser-equivalence claim. Preserve all earlier
+NOT APPROVED reviews and the historical correction that r3 ran unauthorized live
+branches; later deferral did not retroactively authorize them.
+
+## Ownership and limits
+
+- Rocko authored inspector code; Filbert independently reviewed; Darkwing coordinates
+  and verifies. Keep the approved candidate frozen unless a new fix is authorized.
+- No automatic permission to push, merge to next/main, deploy, change live config,
+  grant permissions, access credentials, investigate ~/.mosaic, or start new runtime
+  work. Local conversion authority is not authority for those activities.
+- Preserve unrelated pending work. In particular `scripts/agent.sh`, `docs/TOOLS.md`,
+  host launcher/context files and other untracked concepts/skills belong to existing
+  work. Do not blanket-stage/reset/clean. Root logs and CURRENT remain uncommitted.
+- Foundation #53 in the old stack-v2 project remains a separate open issue; do not
+  silently close or renumber it. Accepted historical SHA/path citations remain valid.
+- Rocko's Archify C1 remains HELD for owner T2/T3 decisions. No lane reassignment.
+- Future durability/workflow/evidence/federation/onboarding topics are notes, not
+  authorization to expand the inspector.
+
+## Communications
+
+Use only `tools/tmux/agent-send.sh`; sender `dragon-lin:darkwing`.
+Rocko: `-L mosaic-fleet -s '=rocko'`; Filbert/Dewey:
+`-L default -s '=filbert'` / `'=dewey'`.
+Conversion notice delivered to Rocko. Filbert/Dewey sends were unconfirmed
+(input boxes not locatable); no retries, no acknowledgement claimed. Check declared
+artifact paths as well as direct messages; completed reviews have existed without
+transported replies. Do not inspect private panes or blindly resend.
+
+## Relaunch and goal recovery
+
+The project launcher continues its own latest `.pi/state/darkwing/sessions/`
+conversation by default. Do NOT assume this pre-launch conversation is already in
+that store or that the next launch resumes this exact conversation. This handoff
+is the durable bridge. No session-tree migration or launch was performed here.
+
+The goal extension owns lifecycle. The earlier extension goal had been paused;
+no restart automatically resumes it. Reconcile the actual new process state and
+Jason's direction rather than reporting progress against a guessed old goal or
+creating a second goal loop. Launch alone grants no new assignment.
+
+This handoff and its CONTEXT pointer are documentation-only. Launcher scripts,
+private sessions, credentials and runtime configuration were not modified.

agents/researcher/SOUL.md

@@ -0,0 +1,5 @@
+# SOUL - researcher
+
+You are the researcher seat of the Mosaic fleet. You are curious, methodical,
+and precise. You cite what you know, admit what you do not, and never guess
+when you can verify.

agents/researcher/agent.json

@@ -0,0 +1,6 @@
+{
+  "agentVersion": 1,
+  "name": "researcher",
+  "role": "researcher",
+  "capabilities": { "tools": ["read", "bash"] }
+}

apps/gateway/src/agent/agent.module.ts

@@ -1,38 +0,0 @@
-import { Global, Module } from '@nestjs/common';
-import { AgentService } from './agent.service.js';
-import { ProviderService } from './provider.service.js';
-import { ProviderCredentialsService } from './provider-credentials.service.js';
-import { RoutingService } from './routing.service.js';
-import { RoutingEngineService } from './routing/routing-engine.service.js';
-import { SkillLoaderService } from './skill-loader.service.js';
-import { ProvidersController } from './providers.controller.js';
-import { SessionsController } from './sessions.controller.js';
-import { AgentConfigsController } from './agent-configs.controller.js';
-import { RoutingController } from './routing/routing.controller.js';
-import { CoordModule } from '../coord/coord.module.js';
-import { McpClientModule } from '../mcp-client/mcp-client.module.js';
-import { SkillsModule } from '../skills/skills.module.js';
-import { GCModule } from '../gc/gc.module.js';
-
-@Global()
-@Module({
-  imports: [CoordModule, McpClientModule, SkillsModule, GCModule],
-  providers: [
-    ProviderService,
-    ProviderCredentialsService,
-    RoutingService,
-    RoutingEngineService,
-    SkillLoaderService,
-    AgentService,
-  ],
-  controllers: [ProvidersController, SessionsController, AgentConfigsController, RoutingController],
-  exports: [
-    AgentService,
-    ProviderService,
-    ProviderCredentialsService,
-    RoutingService,
-    RoutingEngineService,
-    SkillLoaderService,
-  ],
-})
-export class AgentModule {}

apps/gateway/src/agent/tools/path-guard.ts

@@ -1,58 +0,0 @@
-import path from 'node:path';
-import fs from 'node:fs';
-
-/**
- * Resolves a user-provided path and verifies it is inside the allowed sandbox directory.
- * Throws SandboxEscapeError if the resolved path is outside the sandbox.
- *
- * Uses realpathSync to resolve symlinks in the sandbox root. The user-supplied path
- * is checked for containment AFTER lexical resolution but BEFORE resolving any symlinks
- * within the user path — so symlink escape attempts are caught too.
- *
- * @param userPath - The path provided by the agent (may be relative or absolute)
- * @param sandboxDir - The allowed root directory (already validated on session creation)
- * @returns The resolved absolute path, guaranteed to be within sandboxDir
- */
-export function guardPath(userPath: string, sandboxDir: string): string {
-  const resolved = path.resolve(sandboxDir, userPath);
-  const sandboxResolved = fs.realpathSync.native(sandboxDir);
-
-  // Normalize both paths to resolve any symlinks in the sandbox root itself.
-  // For the user path, we check containment BEFORE resolving symlinks in the path
-  // (so we catch symlink escape attempts too — the resolved path must still be under sandbox)
-  if (!resolved.startsWith(sandboxResolved + path.sep) && resolved !== sandboxResolved) {
-    throw new SandboxEscapeError(userPath, sandboxDir, resolved);
-  }
-
-  return resolved;
-}
-
-/**
- * Validates a path without resolving symlinks in the user-provided portion.
- * Use for paths that may not exist yet (creates, writes).
- *
- * Performs a lexical containment check only using path.resolve.
- */
-export function guardPathUnsafe(userPath: string, sandboxDir: string): string {
-  const resolved = path.resolve(sandboxDir, userPath);
-  const sandboxAbs = path.resolve(sandboxDir);
-
-  if (!resolved.startsWith(sandboxAbs + path.sep) && resolved !== sandboxAbs) {
-    throw new SandboxEscapeError(userPath, sandboxDir, resolved);
-  }
-
-  return resolved;
-}
-
-export class SandboxEscapeError extends Error {
-  constructor(
-    public readonly userPath: string,
-    public readonly sandboxDir: string,
-    public readonly resolvedPath: string,
-  ) {
-    super(
-      `Path escape attempt blocked: "${userPath}" resolves to "${resolvedPath}" which is outside sandbox "${sandboxDir}"`,
-    );
-    this.name = 'SandboxEscapeError';
-  }
-}

apps/gateway/src/chat/__tests__/chat-security.test.ts

@@ -1,81 +0,0 @@
-import 'reflect-metadata';
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { validateSync } from 'class-validator';
-import { describe, expect, it, vi } from 'vitest';
-import { SendMessageDto } from '../../conversations/conversations.dto.js';
-import { ChatRequestDto } from '../chat.dto.js';
-import { validateSocketSession } from '../chat.gateway-auth.js';
-
-describe('Chat controller source hardening', () => {
-  it('applies AuthGuard and reads the current user', () => {
-    const source = readFileSync(resolve('src/chat/chat.controller.ts'), 'utf8');
-
-    expect(source).toContain('@UseGuards(AuthGuard)');
-    expect(source).toContain('@CurrentUser() user: { id: string }');
-  });
-});
-
-describe('WebSocket session authentication', () => {
-  it('returns null when the handshake does not resolve to a session', async () => {
-    const result = await validateSocketSession(
-      {},
-      {
-        api: {
-          getSession: vi.fn().mockResolvedValue(null),
-        },
-      },
-    );
-
-    expect(result).toBeNull();
-  });
-
-  it('returns the resolved session when Better Auth accepts the headers', async () => {
-    const session = { user: { id: 'user-1' }, session: { id: 'session-1' } };
-
-    const result = await validateSocketSession(
-      { cookie: 'session=abc' },
-      {
-        api: {
-          getSession: vi.fn().mockResolvedValue(session),
-        },
-      },
-    );
-
-    expect(result).toEqual(session);
-  });
-});
-
-describe('Chat DTO validation', () => {
-  it('rejects unsupported message roles', () => {
-    const dto = Object.assign(new SendMessageDto(), {
-      content: 'hello',
-      role: 'moderator',
-    });
-
-    const errors = validateSync(dto);
-
-    expect(errors.length).toBeGreaterThan(0);
-  });
-
-  it('rejects oversized conversation message content above 10000 characters', () => {
-    const dto = Object.assign(new SendMessageDto(), {
-      content: 'x'.repeat(10_001),
-      role: 'user',
-    });
-
-    const errors = validateSync(dto);
-
-    expect(errors.length).toBeGreaterThan(0);
-  });
-
-  it('rejects oversized chat content above 10000 characters', () => {
-    const dto = Object.assign(new ChatRequestDto(), {
-      content: 'x'.repeat(10_001),
-    });
-
-    const errors = validateSync(dto);
-
-    expect(errors.length).toBeGreaterThan(0);
-  });
-});

apps/gateway/src/chat/chat.controller.ts

@@ -1,90 +0,0 @@
-import {
-  Controller,
-  Post,
-  Body,
-  Logger,
-  HttpException,
-  HttpStatus,
-  Inject,
-  UseGuards,
-} from '@nestjs/common';
-import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
-import { Throttle } from '@nestjs/throttler';
-import { AgentService } from '../agent/agent.service.js';
-import { AuthGuard } from '../auth/auth.guard.js';
-import { CurrentUser } from '../auth/current-user.decorator.js';
-import { v4 as uuid } from 'uuid';
-import { ChatRequestDto } from './chat.dto.js';
-
-interface ChatResponse {
-  conversationId: string;
-  text: string;
-}
-
-@Controller('api/chat')
-@UseGuards(AuthGuard)
-export class ChatController {
-  private readonly logger = new Logger(ChatController.name);
-
-  constructor(@Inject(AgentService) private readonly agentService: AgentService) {}
-
-  @Post()
-  @Throttle({ default: { limit: 10, ttl: 60_000 } })
-  async chat(
-    @Body() body: ChatRequestDto,
-    @CurrentUser() user: { id: string },
-  ): Promise<ChatResponse> {
-    const conversationId = body.conversationId ?? uuid();
-
-    try {
-      let agentSession = this.agentService.getSession(conversationId);
-      if (!agentSession) {
-        agentSession = await this.agentService.createSession(conversationId);
-      }
-    } catch (err) {
-      this.logger.error(
-        `Session creation failed for conversation=${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-      throw new HttpException('Agent session unavailable', HttpStatus.SERVICE_UNAVAILABLE);
-    }
-
-    this.logger.debug(`Handling chat request for user=${user.id}, conversation=${conversationId}`);
-
-    let responseText = '';
-
-    const done = new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        cleanup();
-        this.logger.error(`Agent response timed out after 120s for conversation=${conversationId}`);
-        reject(new Error('Agent response timed out'));
-      }, 120_000);
-
-      const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
-        if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
-          responseText += event.assistantMessageEvent.delta;
-        }
-        if (event.type === 'agent_end') {
-          clearTimeout(timer);
-          cleanup();
-          resolve();
-        }
-      });
-    });
-
-    try {
-      await this.agentService.prompt(conversationId, body.content);
-      await done;
-    } catch (err) {
-      if (err instanceof HttpException) throw err;
-      const message = err instanceof Error ? err.message : String(err);
-      if (message.includes('timed out')) {
-        throw new HttpException('Agent response timed out', HttpStatus.GATEWAY_TIMEOUT);
-      }
-      this.logger.error(`Chat prompt failed for conversation=${conversationId}`, String(err));
-      throw new HttpException('Agent processing failed', HttpStatus.INTERNAL_SERVER_ERROR);
-    }
-
-    return { conversationId, text: responseText };
-  }
-}

apps/gateway/src/chat/chat.dto.ts

@@ -1,35 +0,0 @@
-import { IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
-
-export class ChatRequestDto {
-  @IsOptional()
-  @IsUUID()
-  conversationId?: string;
-
-  @IsString()
-  @MaxLength(10_000)
-  content!: string;
-}
-
-export class ChatSocketMessageDto {
-  @IsOptional()
-  @IsUUID()
-  conversationId?: string;
-
-  @IsString()
-  @MaxLength(10_000)
-  content!: string;
-
-  @IsOptional()
-  @IsString()
-  @MaxLength(255)
-  provider?: string;
-
-  @IsOptional()
-  @IsString()
-  @MaxLength(255)
-  modelId?: string;
-
-  @IsOptional()
-  @IsUUID()
-  agentId?: string;
-}

apps/gateway/src/chat/chat.gateway.ts

@@ -1,695 +0,0 @@
-import { Inject, Logger } from '@nestjs/common';
-import {
-  WebSocketGateway,
-  WebSocketServer,
-  SubscribeMessage,
-  OnGatewayConnection,
-  OnGatewayDisconnect,
-  type OnGatewayInit,
-  ConnectedSocket,
-  MessageBody,
-} from '@nestjs/websockets';
-import { Server, Socket } from 'socket.io';
-import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
-import type { Auth } from '@mosaicstack/auth';
-import type { Brain } from '@mosaicstack/brain';
-import type {
-  SetThinkingPayload,
-  SlashCommandPayload,
-  SystemReloadPayload,
-  RoutingDecisionInfo,
-  AbortPayload,
-} from '@mosaicstack/types';
-import { AgentService, type ConversationHistoryMessage } from '../agent/agent.service.js';
-import { AUTH } from '../auth/auth.tokens.js';
-import { BRAIN } from '../brain/brain.tokens.js';
-import { CommandRegistryService } from '../commands/command-registry.service.js';
-import { CommandExecutorService } from '../commands/command-executor.service.js';
-import { RoutingEngineService } from '../agent/routing/routing-engine.service.js';
-import { v4 as uuid } from 'uuid';
-import { ChatSocketMessageDto } from './chat.dto.js';
-import { validateSocketSession } from './chat.gateway-auth.js';
-
-/** Per-client state tracking streaming accumulation for persistence. */
-interface ClientSession {
-  conversationId: string;
-  cleanup: () => void;
-  /** Accumulated assistant response text for the current turn. */
-  assistantText: string;
-  /** Tool calls observed during the current turn. */
-  toolCalls: Array<{ toolCallId: string; toolName: string; args: unknown; isError: boolean }>;
-  /** Tool calls in-flight (started but not ended yet). */
-  pendingToolCalls: Map<string, { toolName: string; args: unknown }>;
-  /** Last routing decision made for this session (M4-008) */
-  lastRoutingDecision?: RoutingDecisionInfo;
-}
-
-/**
- * Per-conversation model overrides set via /model command (M4-007).
- * Keyed by conversationId, value is the model name to use.
- */
-const modelOverrides = new Map<string, string>();
-
-@WebSocketGateway({
-  cors: {
-    origin: process.env['GATEWAY_CORS_ORIGIN'] ?? 'http://localhost:3000',
-  },
-  namespace: '/chat',
-})
-export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect {
-  @WebSocketServer()
-  server!: Server;
-
-  private readonly logger = new Logger(ChatGateway.name);
-  private readonly clientSessions = new Map<string, ClientSession>();
-
-  constructor(
-    @Inject(AgentService) private readonly agentService: AgentService,
-    @Inject(AUTH) private readonly auth: Auth,
-    @Inject(BRAIN) private readonly brain: Brain,
-    @Inject(CommandRegistryService) private readonly commandRegistry: CommandRegistryService,
-    @Inject(CommandExecutorService) private readonly commandExecutor: CommandExecutorService,
-    @Inject(RoutingEngineService) private readonly routingEngine: RoutingEngineService,
-  ) {}
-
-  afterInit(): void {
-    this.logger.log('Chat WebSocket gateway initialized');
-  }
-
-  async handleConnection(client: Socket): Promise<void> {
-    const session = await validateSocketSession(client.handshake.headers, this.auth);
-    if (!session) {
-      this.logger.warn(`Rejected unauthenticated WebSocket client: ${client.id}`);
-      client.disconnect();
-      return;
-    }
-
-    client.data.user = session.user;
-    client.data.session = session.session;
-    this.logger.log(`Client connected: ${client.id}`);
-
-    // Broadcast command manifest to the newly connected client
-    client.emit('commands:manifest', { manifest: this.commandRegistry.getManifest() });
-  }
-
-  handleDisconnect(client: Socket): void {
-    this.logger.log(`Client disconnected: ${client.id}`);
-    const session = this.clientSessions.get(client.id);
-    if (session) {
-      session.cleanup();
-      this.agentService.removeChannel(session.conversationId, `websocket:${client.id}`);
-      this.clientSessions.delete(client.id);
-    }
-  }
-
-  @SubscribeMessage('message')
-  async handleMessage(
-    @ConnectedSocket() client: Socket,
-    @MessageBody() data: ChatSocketMessageDto,
-  ): Promise<void> {
-    const conversationId = data.conversationId ?? uuid();
-    const userId = (client.data.user as { id: string } | undefined)?.id;
-
-    this.logger.log(`Message from ${client.id} in conversation ${conversationId}`);
-
-    // Ensure agent session exists for this conversation
-    let sessionRoutingDecision: RoutingDecisionInfo | undefined;
-    try {
-      let agentSession = this.agentService.getSession(conversationId);
-      if (!agentSession) {
-        // When resuming an existing conversation, load prior messages to inject as context (M1-004)
-        const conversationHistory = await this.loadConversationHistory(conversationId, userId);
-
-        // M5-004: Check if there's an existing sessionId bound to this conversation
-        let existingSessionId: string | undefined;
-        if (userId) {
-          existingSessionId = await this.getConversationSessionId(conversationId, userId);
-          if (existingSessionId) {
-            this.logger.log(
-              `Resuming existing sessionId=${existingSessionId} for conversation=${conversationId}`,
-            );
-          }
-        }
-
-        // Determine provider/model via routing engine or per-session /model override (M4-012 / M4-007)
-        let resolvedProvider = data.provider;
-        let resolvedModelId = data.modelId;
-
-        const modelOverride = modelOverrides.get(conversationId);
-        if (modelOverride) {
-          // /model override bypasses routing engine (M4-007)
-          resolvedModelId = modelOverride;
-          this.logger.log(
-            `Using /model override "${modelOverride}" for conversation=${conversationId}`,
-          );
-        } else if (!resolvedProvider && !resolvedModelId) {
-          // No explicit provider/model from client — use routing engine (M4-012)
-          try {
-            const routingDecision = await this.routingEngine.resolve(data.content, userId);
-            resolvedProvider = routingDecision.provider;
-            resolvedModelId = routingDecision.model;
-            sessionRoutingDecision = {
-              model: routingDecision.model,
-              provider: routingDecision.provider,
-              ruleName: routingDecision.ruleName,
-              reason: routingDecision.reason,
-            };
-            this.logger.log(
-              `Routing decision for conversation=${conversationId}: ${routingDecision.provider}/${routingDecision.model} (rule="${routingDecision.ruleName}")`,
-            );
-          } catch (routingErr) {
-            this.logger.warn(
-              `Routing engine failed for conversation=${conversationId}, using defaults`,
-              routingErr instanceof Error ? routingErr.message : String(routingErr),
-            );
-          }
-        }
-
-        // M5-004: Use existingSessionId as sessionId when available (session reuse)
-        const sessionIdToCreate = existingSessionId ?? conversationId;
-        agentSession = await this.agentService.createSession(sessionIdToCreate, {
-          provider: resolvedProvider,
-          modelId: resolvedModelId,
-          agentConfigId: data.agentId,
-          userId,
-          conversationHistory: conversationHistory.length > 0 ? conversationHistory : undefined,
-        });
-
-        if (conversationHistory.length > 0) {
-          this.logger.log(
-            `Loaded ${conversationHistory.length} prior messages for conversation=${conversationId}`,
-          );
-        }
-      }
-    } catch (err) {
-      this.logger.error(
-        `Session creation failed for client=${client.id}, conversation=${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-      client.emit('error', {
-        conversationId,
-        error: 'Failed to start agent session. Please try again.',
-      });
-      return;
-    }
-
-    // Ensure conversation record exists in the DB before persisting messages
-    // M5-004: Also bind the sessionId to the conversation record
-    if (userId) {
-      await this.ensureConversation(conversationId, userId);
-      await this.bindSessionToConversation(conversationId, userId, conversationId);
-    }
-
-    // M5-007: Count the user message
-    this.agentService.recordMessage(conversationId);
-
-    // Persist the user message
-    if (userId) {
-      try {
-        await this.brain.conversations.addMessage(
-          {
-            conversationId,
-            role: 'user',
-            content: data.content,
-            metadata: {
-              timestamp: new Date().toISOString(),
-            },
-          },
-          userId,
-        );
-      } catch (err) {
-        this.logger.error(
-          `Failed to persist user message for conversation=${conversationId}`,
-          err instanceof Error ? err.stack : String(err),
-        );
-      }
-    }
-
-    // Always clean up previous listener to prevent leak
-    const existing = this.clientSessions.get(client.id);
-    if (existing) {
-      existing.cleanup();
-    }
-
-    // Subscribe to agent events and relay to client
-    const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
-      this.relayEvent(client, conversationId, event);
-    });
-
-    // Preserve routing decision from the existing client session if we didn't get a new one
-    const prevClientSession = this.clientSessions.get(client.id);
-    const routingDecisionToStore = sessionRoutingDecision ?? prevClientSession?.lastRoutingDecision;
-
-    this.clientSessions.set(client.id, {
-      conversationId,
-      cleanup,
-      assistantText: '',
-      toolCalls: [],
-      pendingToolCalls: new Map(),
-      lastRoutingDecision: routingDecisionToStore,
-    });
-
-    // Track channel connection
-    this.agentService.addChannel(conversationId, `websocket:${client.id}`);
-
-    // Send session info so the client knows the model/provider (M4-008: include routing decision)
-    // Include agentName when a named agent config is active (M5-001)
-    {
-      const agentSession = this.agentService.getSession(conversationId);
-      if (agentSession) {
-        const piSession = agentSession.piSession;
-        client.emit('session:info', {
-          conversationId,
-          provider: agentSession.provider,
-          modelId: agentSession.modelId,
-          thinkingLevel: piSession.thinkingLevel,
-          availableThinkingLevels: piSession.getAvailableThinkingLevels(),
-          ...(agentSession.agentName ? { agentName: agentSession.agentName } : {}),
-          ...(routingDecisionToStore ? { routingDecision: routingDecisionToStore } : {}),
-        });
-      }
-    }
-
-    // Send acknowledgment
-    client.emit('message:ack', { conversationId, messageId: uuid() });
-
-    // Dispatch to agent
-    try {
-      await this.agentService.prompt(conversationId, data.content);
-    } catch (err) {
-      this.logger.error(
-        `Agent prompt failed for client=${client.id}, conversation=${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-      client.emit('error', {
-        conversationId,
-        error: 'The agent failed to process your message. Please try again.',
-      });
-    }
-  }
-
-  @SubscribeMessage('set:thinking')
-  handleSetThinking(
-    @ConnectedSocket() client: Socket,
-    @MessageBody() data: SetThinkingPayload,
-  ): void {
-    const session = this.agentService.getSession(data.conversationId);
-    if (!session) {
-      client.emit('error', {
-        conversationId: data.conversationId,
-        error: 'No active session for this conversation.',
-      });
-      return;
-    }
-
-    const validLevels = session.piSession.getAvailableThinkingLevels();
-    if (!validLevels.includes(data.level as never)) {
-      client.emit('error', {
-        conversationId: data.conversationId,
-        error: `Invalid thinking level "${data.level}". Available: ${validLevels.join(', ')}`,
-      });
-      return;
-    }
-
-    session.piSession.setThinkingLevel(data.level as never);
-    this.logger.log(
-      `Thinking level set to "${data.level}" for conversation ${data.conversationId}`,
-    );
-
-    client.emit('session:info', {
-      conversationId: data.conversationId,
-      provider: session.provider,
-      modelId: session.modelId,
-      thinkingLevel: session.piSession.thinkingLevel,
-      availableThinkingLevels: session.piSession.getAvailableThinkingLevels(),
-      ...(session.agentName ? { agentName: session.agentName } : {}),
-    });
-  }
-
-  @SubscribeMessage('abort')
-  async handleAbort(
-    @ConnectedSocket() client: Socket,
-    @MessageBody() data: AbortPayload,
-  ): Promise<void> {
-    const conversationId = data.conversationId;
-    this.logger.log(`Abort requested by ${client.id} for conversation ${conversationId}`);
-
-    const session = this.agentService.getSession(conversationId);
-    if (!session) {
-      client.emit('error', {
-        conversationId,
-        error: 'No active session to abort.',
-      });
-      return;
-    }
-
-    try {
-      await session.piSession.abort();
-      this.logger.log(`Agent session ${conversationId} aborted successfully`);
-    } catch (err) {
-      this.logger.error(
-        `Failed to abort session ${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-      client.emit('error', {
-        conversationId,
-        error: 'Failed to abort the agent operation.',
-      });
-    }
-  }
-
-  @SubscribeMessage('command:execute')
-  async handleCommandExecute(
-    @ConnectedSocket() client: Socket,
-    @MessageBody() payload: SlashCommandPayload,
-  ): Promise<void> {
-    const userId = (client.data.user as { id: string } | undefined)?.id ?? 'unknown';
-    const result = await this.commandExecutor.execute(payload, userId);
-    client.emit('command:result', result);
-  }
-
-  broadcastReload(payload: SystemReloadPayload): void {
-    this.server.emit('system:reload', payload);
-    this.logger.log('Broadcasted system:reload to all connected clients');
-  }
-
-  /**
-   * Set a per-conversation model override (M4-007 / M5-002).
-   * When set, the routing engine is bypassed and the specified model is used.
-   * Pass null to clear the override and resume automatic routing.
-   * M5-005: Emits session:info to clients subscribed to this conversation when a model is set.
-   * M5-007: Records a model switch in session metrics.
-   */
-  setModelOverride(conversationId: string, modelName: string | null): void {
-    if (modelName) {
-      modelOverrides.set(conversationId, modelName);
-      this.logger.log(`Model override set: conversation=${conversationId} model="${modelName}"`);
-
-      // M5-002: Update the live session's modelId so session:info reflects the new model immediately
-      this.agentService.updateSessionModel(conversationId, modelName);
-
-      // M5-005: Broadcast session:info to all clients subscribed to this conversation
-      this.broadcastSessionInfo(conversationId);
-    } else {
-      modelOverrides.delete(conversationId);
-      this.logger.log(`Model override cleared: conversation=${conversationId}`);
-    }
-  }
-
-  /**
-   * Return the active model override for a conversation, or undefined if none.
-   */
-  getModelOverride(conversationId: string): string | undefined {
-    return modelOverrides.get(conversationId);
-  }
-
-  /**
-   * M5-005: Broadcast session:info to all clients currently subscribed to a conversation.
-   * Called on model or agent switch to ensure the TUI TopBar updates immediately.
-   */
-  broadcastSessionInfo(
-    conversationId: string,
-    extra?: { agentName?: string; routingDecision?: RoutingDecisionInfo },
-  ): void {
-    const agentSession = this.agentService.getSession(conversationId);
-    if (!agentSession) return;
-
-    const piSession = agentSession.piSession;
-    const resolvedAgentName = extra?.agentName ?? agentSession.agentName;
-    const payload = {
-      conversationId,
-      provider: agentSession.provider,
-      modelId: agentSession.modelId,
-      thinkingLevel: piSession.thinkingLevel,
-      availableThinkingLevels: piSession.getAvailableThinkingLevels(),
-      ...(resolvedAgentName ? { agentName: resolvedAgentName } : {}),
-      ...(extra?.routingDecision ? { routingDecision: extra.routingDecision } : {}),
-    };
-
-    // Emit to all clients currently subscribed to this conversation
-    for (const [clientId, session] of this.clientSessions) {
-      if (session.conversationId === conversationId) {
-        const socket = this.server.sockets.sockets.get(clientId);
-        if (socket?.connected) {
-          socket.emit('session:info', payload);
-        }
-      }
-    }
-  }
-
-  /**
-   * Ensure a conversation record exists in the DB.
-   * Creates it if absent — safe to call concurrently since a duplicate insert
-   * would fail on the PK constraint and be caught here.
-   */
-  private async ensureConversation(conversationId: string, userId: string): Promise<void> {
-    try {
-      const existing = await this.brain.conversations.findById(conversationId, userId);
-      if (!existing) {
-        await this.brain.conversations.create({
-          id: conversationId,
-          userId,
-        });
-      }
-    } catch (err) {
-      this.logger.error(
-        `Failed to ensure conversation record for conversation=${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-    }
-  }
-
-  /**
-   * M5-004: Bind the agent sessionId to the conversation record in the DB.
-   * Updates the sessionId column so future resumes can reuse the session.
-   */
-  private async bindSessionToConversation(
-    conversationId: string,
-    userId: string,
-    sessionId: string,
-  ): Promise<void> {
-    try {
-      await this.brain.conversations.update(conversationId, userId, { sessionId });
-    } catch (err) {
-      this.logger.error(
-        `Failed to bind sessionId=${sessionId} to conversation=${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-    }
-  }
-
-  /**
-   * M5-004: Retrieve the sessionId bound to a conversation, if any.
-   * Returns undefined when the conversation does not exist or has no bound session.
-   */
-  private async getConversationSessionId(
-    conversationId: string,
-    userId: string,
-  ): Promise<string | undefined> {
-    try {
-      const conv = await this.brain.conversations.findById(conversationId, userId);
-      return conv?.sessionId ?? undefined;
-    } catch (err) {
-      this.logger.error(
-        `Failed to get sessionId for conversation=${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-      return undefined;
-    }
-  }
-
-  /**
-   * Load prior conversation messages from DB for context injection on session resume (M1-004).
-   * Returns an empty array when no history exists, the conversation is not owned by the user,
-   * or userId is not provided.
-   */
-  private async loadConversationHistory(
-    conversationId: string,
-    userId: string | undefined,
-  ): Promise<ConversationHistoryMessage[]> {
-    if (!userId) return [];
-
-    try {
-      const messages = await this.brain.conversations.findMessages(conversationId, userId);
-      if (messages.length === 0) return [];
-
-      return messages.map((msg) => ({
-        role: msg.role as 'user' | 'assistant' | 'system',
-        content: msg.content,
-        createdAt: msg.createdAt,
-      }));
-    } catch (err) {
-      this.logger.error(
-        `Failed to load conversation history for conversation=${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-      return [];
-    }
-  }
-
-  private relayEvent(client: Socket, conversationId: string, event: AgentSessionEvent): void {
-    if (!client.connected) {
-      this.logger.warn(
-        `Dropping event ${event.type} for disconnected client=${client.id}, conversation=${conversationId}`,
-      );
-      return;
-    }
-
-    switch (event.type) {
-      case 'agent_start': {
-        // Reset accumulation buffers for the new turn
-        const cs = this.clientSessions.get(client.id);
-        if (cs) {
-          cs.assistantText = '';
-          cs.toolCalls = [];
-          cs.pendingToolCalls.clear();
-        }
-        client.emit('agent:start', { conversationId });
-        break;
-      }
-
-      case 'agent_end': {
-        // Gather usage stats from the Pi session
-        const agentSession = this.agentService.getSession(conversationId);
-        const piSession = agentSession?.piSession;
-        const stats = piSession?.getSessionStats();
-        const contextUsage = piSession?.getContextUsage();
-
-        const usagePayload = stats
-          ? {
-              provider: agentSession?.provider ?? 'unknown',
-              modelId: agentSession?.modelId ?? 'unknown',
-              thinkingLevel: piSession?.thinkingLevel ?? 'off',
-              tokens: stats.tokens,
-              cost: stats.cost,
-              context: {
-                percent: contextUsage?.percent ?? null,
-                window: contextUsage?.contextWindow ?? 0,
-              },
-            }
-          : undefined;
-
-        client.emit('agent:end', {
-          conversationId,
-          usage: usagePayload,
-        });
-
-        // M5-007: Accumulate token usage in session metrics
-        if (stats?.tokens) {
-          this.agentService.recordTokenUsage(conversationId, {
-            input: stats.tokens.input ?? 0,
-            output: stats.tokens.output ?? 0,
-            cacheRead: stats.tokens.cacheRead ?? 0,
-            cacheWrite: stats.tokens.cacheWrite ?? 0,
-            total: stats.tokens.total ?? 0,
-          });
-        }
-
-        // Persist the assistant message with metadata
-        const cs = this.clientSessions.get(client.id);
-        const userId = (client.data.user as { id: string } | undefined)?.id;
-        if (cs && userId && cs.assistantText.trim().length > 0) {
-          const metadata: Record<string, unknown> = {
-            timestamp: new Date().toISOString(),
-            model: agentSession?.modelId ?? 'unknown',
-            provider: agentSession?.provider ?? 'unknown',
-            toolCalls: cs.toolCalls,
-          };
-
-          if (stats?.tokens) {
-            metadata['tokenUsage'] = {
-              input: stats.tokens.input,
-              output: stats.tokens.output,
-              cacheRead: stats.tokens.cacheRead,
-              cacheWrite: stats.tokens.cacheWrite,
-              total: stats.tokens.total,
-            };
-          }
-
-          this.brain.conversations
-            .addMessage(
-              {
-                conversationId,
-                role: 'assistant',
-                content: cs.assistantText,
-                metadata,
-              },
-              userId,
-            )
-            .catch((err: unknown) => {
-              this.logger.error(
-                `Failed to persist assistant message for conversation=${conversationId}`,
-                err instanceof Error ? err.stack : String(err),
-              );
-            });
-
-          // Reset accumulation
-          cs.assistantText = '';
-          cs.toolCalls = [];
-          cs.pendingToolCalls.clear();
-        }
-        break;
-      }
-
-      case 'message_update': {
-        const assistantEvent = event.assistantMessageEvent;
-        if (assistantEvent.type === 'text_delta') {
-          // Accumulate assistant text for persistence
-          const cs = this.clientSessions.get(client.id);
-          if (cs) {
-            cs.assistantText += assistantEvent.delta;
-          }
-          client.emit('agent:text', {
-            conversationId,
-            text: assistantEvent.delta,
-          });
-        } else if (assistantEvent.type === 'thinking_delta') {
-          client.emit('agent:thinking', {
-            conversationId,
-            text: assistantEvent.delta,
-          });
-        }
-        break;
-      }
-
-      case 'tool_execution_start': {
-        // Track pending tool call for later recording
-        const cs = this.clientSessions.get(client.id);
-        if (cs) {
-          cs.pendingToolCalls.set(event.toolCallId, {
-            toolName: event.toolName,
-            args: event.args,
-          });
-        }
-        client.emit('agent:tool:start', {
-          conversationId,
-          toolCallId: event.toolCallId,
-          toolName: event.toolName,
-        });
-        break;
-      }
-
-      case 'tool_execution_end': {
-        // Finalise tool call record
-        const cs = this.clientSessions.get(client.id);
-        if (cs) {
-          const pending = cs.pendingToolCalls.get(event.toolCallId);
-          cs.toolCalls.push({
-            toolCallId: event.toolCallId,
-            toolName: event.toolName,
-            args: pending?.args ?? null,
-            isError: event.isError,
-          });
-          cs.pendingToolCalls.delete(event.toolCallId);
-        }
-        client.emit('agent:tool:end', {
-          conversationId,
-          toolCallId: event.toolCallId,
-          toolName: event.toolName,
-          isError: event.isError,
-        });
-        break;
-      }
-    }
-  }
-}

apps/gateway/src/chat/chat.module.ts

@@ -1,12 +0,0 @@
-import { forwardRef, Module } from '@nestjs/common';
-import { CommandsModule } from '../commands/commands.module.js';
-import { ChatGateway } from './chat.gateway.js';
-import { ChatController } from './chat.controller.js';
-
-@Module({
-  imports: [forwardRef(() => CommandsModule)],
-  controllers: [ChatController],
-  providers: [ChatGateway],
-  exports: [ChatGateway],
-})
-export class ChatModule {}

apps/gateway/src/commands/command-executor-p8012.spec.ts

@@ -1,249 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { CommandExecutorService } from './command-executor.service.js';
-import type { SlashCommandPayload } from '@mosaicstack/types';
-
-// Minimal mock implementations
-const mockRegistry = {
-  getManifest: vi.fn(() => ({
-    version: 1,
-    commands: [
-      { name: 'provider', aliases: [], scope: 'agent', execution: 'hybrid', available: true },
-      { name: 'mission', aliases: [], scope: 'agent', execution: 'socket', available: true },
-      { name: 'agent', aliases: ['a'], scope: 'agent', execution: 'socket', available: true },
-      { name: 'prdy', aliases: [], scope: 'agent', execution: 'socket', available: true },
-      { name: 'tools', aliases: [], scope: 'agent', execution: 'socket', available: true },
-    ],
-    skills: [],
-  })),
-};
-
-const mockAgentService = {
-  getSession: vi.fn(() => undefined),
-  applyAgentConfig: vi.fn(),
-  updateSessionModel: vi.fn(),
-};
-
-const mockSystemOverride = {
-  set: vi.fn(),
-  get: vi.fn(),
-  clear: vi.fn(),
-  renew: vi.fn(),
-};
-
-const mockSessionGC = {
-  sweepOrphans: vi.fn(() => ({ orphanedSessions: 0, totalCleaned: [], duration: 0 })),
-};
-
-const mockRedis = {
-  set: vi.fn().mockResolvedValue('OK'),
-  get: vi.fn(),
-  del: vi.fn(),
-};
-
-// Mock agent config returned by brain.agents.findByName for "my-agent-id"
-const mockAgentConfig = {
-  id: 'my-agent-id',
-  name: 'my-agent-id',
-  model: 'claude-sonnet-4-6',
-  provider: 'anthropic',
-  systemPrompt: null,
-  allowedTools: null,
-  isSystem: false,
-  ownerId: 'user-123',
-  status: 'idle',
-  createdAt: new Date(),
-  updatedAt: new Date(),
-};
-
-const mockBrain = {
-  agents: {
-    // findByName resolves with the agent when name matches, undefined otherwise
-    findByName: vi.fn((name: string) =>
-      Promise.resolve(name === 'my-agent-id' ? mockAgentConfig : undefined),
-    ),
-    findById: vi.fn((id: string) =>
-      Promise.resolve(id === 'my-agent-id' ? mockAgentConfig : undefined),
-    ),
-    create: vi.fn(),
-  },
-};
-
-const mockChatGateway = {
-  broadcastSessionInfo: vi.fn(),
-};
-
-function buildService(): CommandExecutorService {
-  return new CommandExecutorService(
-    mockRegistry as never,
-    mockAgentService as never,
-    mockSystemOverride as never,
-    mockSessionGC as never,
-    mockRedis as never,
-    mockBrain as never,
-    null,
-    mockChatGateway as never,
-    null,
-  );
-}
-
-describe('CommandExecutorService — P8-012 commands', () => {
-  let service: CommandExecutorService;
-  const userId = 'user-123';
-  const conversationId = 'conv-456';
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    service = buildService();
-  });
-
-  // /provider login — missing provider name
-  it('/provider login with no provider name returns usage error', async () => {
-    const payload: SlashCommandPayload = { command: 'provider', args: 'login', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(false);
-    expect(result.message).toContain('Usage: /provider login');
-    expect(result.command).toBe('provider');
-  });
-
-  // /provider login anthropic — success with URL containing poll token
-  it('/provider login <name> returns success with URL and poll token', async () => {
-    const payload: SlashCommandPayload = {
-      command: 'provider',
-      args: 'login anthropic',
-      conversationId,
-    };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.command).toBe('provider');
-    expect(result.message).toContain('anthropic');
-    expect(result.message).toContain('http');
-    // data should contain loginUrl and pollToken
-    expect(result.data).toBeDefined();
-    const data = result.data as Record<string, unknown>;
-    expect(typeof data['loginUrl']).toBe('string');
-    expect(typeof data['pollToken']).toBe('string');
-    expect(data['loginUrl'] as string).toContain('anthropic');
-    expect(data['loginUrl'] as string).toContain(data['pollToken'] as string);
-    // Verify Valkey was called
-    expect(mockRedis.set).toHaveBeenCalledOnce();
-    const [key, value, , ttl] = mockRedis.set.mock.calls[0] as [string, string, string, number];
-    expect(key).toContain('mosaic:auth:poll:');
-    const stored = JSON.parse(value) as { status: string; provider: string; userId: string };
-    expect(stored.status).toBe('pending');
-    expect(stored.provider).toBe('anthropic');
-    expect(stored.userId).toBe(userId);
-    expect(ttl).toBe(300);
-  });
-
-  // /provider with no args — returns usage
-  it('/provider with no args returns usage message', async () => {
-    const payload: SlashCommandPayload = { command: 'provider', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.message).toContain('Usage: /provider');
-  });
-
-  // /provider list
-  it('/provider list returns success', async () => {
-    const payload: SlashCommandPayload = { command: 'provider', args: 'list', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.command).toBe('provider');
-  });
-
-  // /provider logout with no name — usage error
-  it('/provider logout with no name returns error', async () => {
-    const payload: SlashCommandPayload = { command: 'provider', args: 'logout', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(false);
-    expect(result.message).toContain('Usage: /provider logout');
-  });
-
-  // /provider unknown subcommand
-  it('/provider unknown subcommand returns error', async () => {
-    const payload: SlashCommandPayload = {
-      command: 'provider',
-      args: 'unknown',
-      conversationId,
-    };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(false);
-    expect(result.message).toContain('Unknown subcommand');
-  });
-
-  // /mission status
-  it('/mission status returns stub message', async () => {
-    const payload: SlashCommandPayload = { command: 'mission', args: 'status', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.command).toBe('mission');
-    expect(result.message).toContain('Mission status');
-  });
-
-  // /mission with no args
-  it('/mission with no args returns status stub', async () => {
-    const payload: SlashCommandPayload = { command: 'mission', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.message).toContain('Mission status');
-  });
-
-  // /mission set <id>
-  it('/mission set <id> returns confirmation', async () => {
-    const payload: SlashCommandPayload = {
-      command: 'mission',
-      args: 'set my-mission-123',
-      conversationId,
-    };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.message).toContain('my-mission-123');
-  });
-
-  // /agent list
-  it('/agent list returns stub message', async () => {
-    const payload: SlashCommandPayload = { command: 'agent', args: 'list', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.command).toBe('agent');
-    expect(result.message).toContain('agent');
-  });
-
-  // /agent with no args
-  it('/agent with no args returns usage', async () => {
-    const payload: SlashCommandPayload = { command: 'agent', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.message).toContain('Usage: /agent');
-  });
-
-  // /agent <id> — switch
-  it('/agent <id> returns switch confirmation', async () => {
-    const payload: SlashCommandPayload = {
-      command: 'agent',
-      args: 'my-agent-id',
-      conversationId,
-    };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.message).toContain('my-agent-id');
-  });
-
-  // /prdy
-  it('/prdy returns PRD wizard message', async () => {
-    const payload: SlashCommandPayload = { command: 'prdy', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.command).toBe('prdy');
-    expect(result.message).toContain('mosaic prdy');
-  });
-
-  // /tools
-  it('/tools returns tools stub message', async () => {
-    const payload: SlashCommandPayload = { command: 'tools', conversationId };
-    const result = await service.execute(payload, userId);
-    expect(result.success).toBe(true);
-    expect(result.command).toBe('tools');
-    expect(result.message).toContain('tools');
-  });
-});

apps/gateway/src/commands/commands.module.ts

@@ -1,37 +0,0 @@
-import { forwardRef, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
-import { createQueue, type QueueHandle } from '@mosaicstack/queue';
-import { ChatModule } from '../chat/chat.module.js';
-import { GCModule } from '../gc/gc.module.js';
-import { ReloadModule } from '../reload/reload.module.js';
-import { CommandExecutorService } from './command-executor.service.js';
-import { CommandRegistryService } from './command-registry.service.js';
-import { COMMANDS_REDIS } from './commands.tokens.js';
-
-const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
-
-@Module({
-  imports: [GCModule, forwardRef(() => ReloadModule), forwardRef(() => ChatModule)],
-  providers: [
-    {
-      provide: COMMANDS_QUEUE_HANDLE,
-      useFactory: (): QueueHandle => {
-        return createQueue();
-      },
-    },
-    {
-      provide: COMMANDS_REDIS,
-      useFactory: (handle: QueueHandle) => handle.redis,
-      inject: [COMMANDS_QUEUE_HANDLE],
-    },
-    CommandRegistryService,
-    CommandExecutorService,
-  ],
-  exports: [CommandRegistryService, CommandExecutorService],
-})
-export class CommandsModule implements OnApplicationShutdown {
-  constructor(@Inject(COMMANDS_QUEUE_HANDLE) private readonly handle: QueueHandle) {}
-
-  async onApplicationShutdown(): Promise<void> {
-    await this.handle.close().catch(() => {});
-  }
-}

apps/gateway/src/conversations/conversations.module.ts

@@ -1,7 +0,0 @@
-import { Module } from '@nestjs/common';
-import { ConversationsController } from './conversations.controller.js';
-
-@Module({
-  controllers: [ConversationsController],
-})
-export class ConversationsModule {}

apps/gateway/src/coord/coord.module.ts

@@ -1,10 +0,0 @@
-import { Module } from '@nestjs/common';
-import { CoordService } from './coord.service.js';
-import { CoordController } from './coord.controller.js';
-
-@Module({
-  providers: [CoordService],
-  controllers: [CoordController],
-  exports: [CoordService],
-})
-export class CoordModule {}

apps/gateway/src/database/database.module.ts

@@ -1,51 +0,0 @@
-import { mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { Global, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
-import { createDb, createPgliteDb, type Db, type DbHandle } from '@mosaicstack/db';
-import { createStorageAdapter, type StorageAdapter } from '@mosaicstack/storage';
-import type { MosaicConfig } from '@mosaicstack/config';
-import { MOSAIC_CONFIG } from '../config/config.module.js';
-
-export const DB_HANDLE = 'DB_HANDLE';
-export const DB = 'DB';
-export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
-
-@Global()
-@Module({
-  providers: [
-    {
-      provide: DB_HANDLE,
-      useFactory: (config: MosaicConfig): DbHandle => {
-        if (config.tier === 'local') {
-          const dataDir = join(homedir(), '.config', 'mosaic', 'gateway', 'pglite');
-          mkdirSync(dataDir, { recursive: true });
-          return createPgliteDb(dataDir);
-        }
-        return createDb(config.storage.type === 'postgres' ? config.storage.url : undefined);
-      },
-      inject: [MOSAIC_CONFIG],
-    },
-    {
-      provide: DB,
-      useFactory: (handle: DbHandle): Db => handle.db,
-      inject: [DB_HANDLE],
-    },
-    {
-      provide: STORAGE_ADAPTER,
-      useFactory: (config: MosaicConfig): StorageAdapter => createStorageAdapter(config.storage),
-      inject: [MOSAIC_CONFIG],
-    },
-  ],
-  exports: [DB, STORAGE_ADAPTER],
-})
-export class DatabaseModule implements OnApplicationShutdown {
-  constructor(
-    @Inject(DB_HANDLE) private readonly handle: DbHandle,
-    @Inject(STORAGE_ADAPTER) private readonly storageAdapter: StorageAdapter,
-  ) {}
-
-  async onApplicationShutdown(): Promise<void> {
-    await Promise.all([this.handle.close(), this.storageAdapter.close()]);
-  }
-}

apps/gateway/src/gc/gc.module.ts

@@ -1,31 +0,0 @@
-import { Module, type OnApplicationShutdown, Inject } from '@nestjs/common';
-import { createQueue, type QueueHandle } from '@mosaicstack/queue';
-import { SessionGCService } from './session-gc.service.js';
-import { REDIS } from './gc.tokens.js';
-
-const GC_QUEUE_HANDLE = 'GC_QUEUE_HANDLE';
-
-@Module({
-  providers: [
-    {
-      provide: GC_QUEUE_HANDLE,
-      useFactory: (): QueueHandle => {
-        return createQueue();
-      },
-    },
-    {
-      provide: REDIS,
-      useFactory: (handle: QueueHandle) => handle.redis,
-      inject: [GC_QUEUE_HANDLE],
-    },
-    SessionGCService,
-  ],
-  exports: [SessionGCService],
-})
-export class GCModule implements OnApplicationShutdown {
-  constructor(@Inject(GC_QUEUE_HANDLE) private readonly handle: QueueHandle) {}
-
-  async onApplicationShutdown(): Promise<void> {
-    await this.handle.close().catch(() => {});
-  }
-}

apps/gateway/src/gc/session-gc.service.spec.ts

@@ -1,112 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { Logger } from '@nestjs/common';
-import type { QueueHandle } from '@mosaicstack/queue';
-import type { LogService } from '@mosaicstack/log';
-import { SessionGCService } from './session-gc.service.js';
-
-type MockRedis = {
-  scan: ReturnType<typeof vi.fn>;
-  del: ReturnType<typeof vi.fn>;
-};
-
-describe('SessionGCService', () => {
-  let service: SessionGCService;
-  let mockRedis: MockRedis;
-  let mockLogService: { logs: { promoteToWarm: ReturnType<typeof vi.fn> } };
-
-  /**
-   * Helper: build a scan mock that returns all provided keys in a single
-   * cursor iteration (cursor '0' in → ['0', keys] out).
-   */
-  function makeScanMock(keys: string[]): ReturnType<typeof vi.fn> {
-    return vi.fn().mockResolvedValue(['0', keys]);
-  }
-
-  beforeEach(() => {
-    mockRedis = {
-      scan: makeScanMock([]),
-      del: vi.fn().mockResolvedValue(0),
-    };
-
-    mockLogService = {
-      logs: {
-        promoteToWarm: vi.fn().mockResolvedValue(0),
-      },
-    };
-
-    // Suppress logger output in tests
-    vi.spyOn(Logger.prototype, 'log').mockImplementation(() => {});
-
-    service = new SessionGCService(
-      mockRedis as unknown as QueueHandle['redis'],
-      mockLogService as unknown as LogService,
-    );
-  });
-
-  it('collect() deletes Valkey keys for session', async () => {
-    mockRedis.scan = makeScanMock(['mosaic:session:abc:system', 'mosaic:session:abc:foo']);
-    const result = await service.collect('abc');
-    expect(mockRedis.del).toHaveBeenCalledWith(
-      'mosaic:session:abc:system',
-      'mosaic:session:abc:foo',
-    );
-    expect(result.cleaned.valkeyKeys).toBe(2);
-  });
-
-  it('collect() with no keys returns empty cleaned valkeyKeys', async () => {
-    mockRedis.scan = makeScanMock([]);
-    const result = await service.collect('abc');
-    expect(result.cleaned.valkeyKeys).toBeUndefined();
-  });
-
-  it('collect() returns sessionId in result', async () => {
-    const result = await service.collect('test-session-id');
-    expect(result.sessionId).toBe('test-session-id');
-  });
-
-  it('fullCollect() deletes all session keys', async () => {
-    mockRedis.scan = makeScanMock(['mosaic:session:abc:system', 'mosaic:session:xyz:foo']);
-    const result = await service.fullCollect();
-    expect(mockRedis.del).toHaveBeenCalled();
-    expect(result.valkeyKeys).toBe(2);
-  });
-
-  it('fullCollect() with no keys returns 0 valkeyKeys', async () => {
-    mockRedis.scan = makeScanMock([]);
-    const result = await service.fullCollect();
-    expect(result.valkeyKeys).toBe(0);
-    expect(mockRedis.del).not.toHaveBeenCalled();
-  });
-
-  it('fullCollect() returns duration', async () => {
-    const result = await service.fullCollect();
-    expect(result.duration).toBeGreaterThanOrEqual(0);
-  });
-
-  it('sweepOrphans() extracts unique session IDs and collects them', async () => {
-    // First scan call returns the global session list; subsequent calls return
-    // per-session keys during collect().
-    mockRedis.scan = vi
-      .fn()
-      .mockResolvedValueOnce([
-        '0',
-        ['mosaic:session:abc:system', 'mosaic:session:abc:messages', 'mosaic:session:xyz:system'],
-      ])
-      // collect('abc') scan
-      .mockResolvedValueOnce(['0', ['mosaic:session:abc:system', 'mosaic:session:abc:messages']])
-      // collect('xyz') scan
-      .mockResolvedValueOnce(['0', ['mosaic:session:xyz:system']]);
-    mockRedis.del.mockResolvedValue(1);
-
-    const result = await service.sweepOrphans();
-    expect(result.orphanedSessions).toBeGreaterThanOrEqual(0);
-    expect(result.duration).toBeGreaterThanOrEqual(0);
-  });
-
-  it('sweepOrphans() returns empty when no session keys', async () => {
-    mockRedis.scan = makeScanMock([]);
-    const result = await service.sweepOrphans();
-    expect(result.orphanedSessions).toBe(0);
-    expect(result.totalCleaned).toHaveLength(0);
-  });
-});

apps/gateway/src/gc/session-gc.service.ts

@@ -1,164 +0,0 @@
-import { Inject, Injectable, Logger, type OnModuleInit } from '@nestjs/common';
-import type { QueueHandle } from '@mosaicstack/queue';
-import type { LogService } from '@mosaicstack/log';
-import { LOG_SERVICE } from '../log/log.tokens.js';
-import { REDIS } from './gc.tokens.js';
-
-export interface GCResult {
-  sessionId: string;
-  cleaned: {
-    valkeyKeys?: number;
-    logsDemoted?: number;
-    tempFilesRemoved?: number;
-  };
-}
-
-export interface GCSweepResult {
-  orphanedSessions: number;
-  totalCleaned: GCResult[];
-  duration: number;
-}
-
-export interface FullGCResult {
-  valkeyKeys: number;
-  logsDemoted: number;
-  jobsPurged: number;
-  tempFilesRemoved: number;
-  duration: number;
-}
-
-@Injectable()
-export class SessionGCService implements OnModuleInit {
-  private readonly logger = new Logger(SessionGCService.name);
-
-  constructor(
-    @Inject(REDIS) private readonly redis: QueueHandle['redis'],
-    @Inject(LOG_SERVICE) private readonly logService: LogService,
-  ) {}
-
-  onModuleInit(): void {
-    // Fire-and-forget: run full GC asynchronously so it does not block the
-    // NestJS bootstrap chain.  Cold-start GC typically takes 100–500 ms
-    // depending on Valkey key count; deferring it removes that latency from
-    // the TTFB of the first HTTP request.
-    this.fullCollect()
-      .then((result) => {
-        this.logger.log(
-          `Full GC complete: ${result.valkeyKeys} Valkey keys, ` +
-            `${result.logsDemoted} logs demoted, ` +
-            `${result.jobsPurged} jobs purged, ` +
-            `${result.tempFilesRemoved} temp dirs removed ` +
-            `(${result.duration}ms)`,
-        );
-      })
-      .catch((err: unknown) => {
-        this.logger.error('Cold-start GC failed', err instanceof Error ? err.stack : String(err));
-      });
-  }
-
-  /**
-   * Scan Valkey for all keys matching a pattern using SCAN (non-blocking).
-   * KEYS is avoided because it blocks the Valkey event loop for the full scan
-   * duration, which can cause latency spikes under production key volumes.
-   */
-  private async scanKeys(pattern: string): Promise<string[]> {
-    const collected: string[] = [];
-    let cursor = '0';
-    do {
-      const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
-      cursor = nextCursor;
-      collected.push(...keys);
-    } while (cursor !== '0');
-    return collected;
-  }
-
-  /**
-   * Immediate cleanup for a single session (call from destroySession).
-   */
-  async collect(sessionId: string): Promise<GCResult> {
-    const result: GCResult = { sessionId, cleaned: {} };
-
-    // 1. Valkey: delete all session-scoped keys
-    const pattern = `mosaic:session:${sessionId}:*`;
-    const valkeyKeys = await this.scanKeys(pattern);
-    if (valkeyKeys.length > 0) {
-      await this.redis.del(...valkeyKeys);
-      result.cleaned.valkeyKeys = valkeyKeys.length;
-    }
-
-    // 2. PG: demote hot-tier agent_logs for this session to warm
-    const cutoff = new Date(); // demote all hot logs for this session
-    const logsDemoted = await this.logService.logs.promoteToWarm(cutoff);
-    if (logsDemoted > 0) {
-      result.cleaned.logsDemoted = logsDemoted;
-    }
-
-    return result;
-  }
-
-  /**
-   * Sweep GC — find orphaned artifacts from dead sessions.
-   * System-wide operation: only call from admin-authorized paths or internal
-   * scheduled jobs.  Individual session cleanup is handled by collect().
-   */
-  async sweepOrphans(): Promise<GCSweepResult> {
-    const start = Date.now();
-    const cleaned: GCResult[] = [];
-
-    // 1. Find all session-scoped Valkey keys (non-blocking SCAN)
-    const allSessionKeys = await this.scanKeys('mosaic:session:*');
-
-    // Extract unique session IDs from keys
-    const sessionIds = new Set<string>();
-    for (const key of allSessionKeys) {
-      const match = key.match(/^mosaic:session:([^:]+):/);
-      if (match) sessionIds.add(match[1]!);
-    }
-
-    // 2. For each session ID, collect stale keys
-    for (const sessionId of sessionIds) {
-      const gcResult = await this.collect(sessionId);
-      if (Object.keys(gcResult.cleaned).length > 0) {
-        cleaned.push(gcResult);
-      }
-    }
-
-    return {
-      orphanedSessions: cleaned.length,
-      totalCleaned: cleaned,
-      duration: Date.now() - start,
-    };
-  }
-
-  /**
-   * Full GC — aggressive collection for cold start.
-   * Assumes no sessions survived the restart.
-   */
-  async fullCollect(): Promise<FullGCResult> {
-    const start = Date.now();
-
-    // 1. Valkey: delete ALL session-scoped keys (non-blocking SCAN)
-    const sessionKeys = await this.scanKeys('mosaic:session:*');
-    if (sessionKeys.length > 0) {
-      await this.redis.del(...sessionKeys);
-    }
-
-    // 2. NOTE: channel keys are NOT collected on cold start
-    //    (discord/telegram plugins may reconnect and resume)
-
-    // 3. PG: demote stale hot-tier logs older than 24h to warm
-    const hotCutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
-    const logsDemoted = await this.logService.logs.promoteToWarm(hotCutoff);
-
-    // 4. No summarization job purge API available yet
-    const jobsPurged = 0;
-
-    return {
-      valkeyKeys: sessionKeys.length,
-      logsDemoted,
-      jobsPurged,
-      tempFilesRemoved: 0,
-      duration: Date.now() - start,
-    };
-  }
-}

apps/gateway/src/mcp/mcp.service.ts

@@ -1,429 +0,0 @@
-import { Injectable, Logger, Inject, OnModuleDestroy } from '@nestjs/common';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { randomUUID } from 'node:crypto';
-import { z } from 'zod';
-import type { Brain } from '@mosaicstack/brain';
-import type { Memory } from '@mosaicstack/memory';
-import { BRAIN } from '../brain/brain.tokens.js';
-import { MEMORY } from '../memory/memory.tokens.js';
-import { EmbeddingService } from '../memory/embedding.service.js';
-import { CoordService } from '../coord/coord.service.js';
-
-interface SessionEntry {
-  server: McpServer;
-  transport: StreamableHTTPServerTransport;
-  createdAt: Date;
-  userId: string;
-}
-
-@Injectable()
-export class McpService implements OnModuleDestroy {
-  private readonly logger = new Logger(McpService.name);
-  private readonly sessions = new Map<string, SessionEntry>();
-
-  constructor(
-    @Inject(BRAIN) private readonly brain: Brain,
-    @Inject(MEMORY) private readonly memory: Memory,
-    @Inject(EmbeddingService) private readonly embeddings: EmbeddingService,
-    @Inject(CoordService) private readonly coordService: CoordService,
-  ) {}
-
-  /**
-   * Creates a new MCP session with its own server + transport pair.
-   * Returns the transport for use by the controller.
-   */
-  createSession(userId: string): { sessionId: string; transport: StreamableHTTPServerTransport } {
-    const sessionId = randomUUID();
-
-    const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: () => sessionId,
-      onsessioninitialized: (id) => {
-        this.logger.log(`MCP session initialized: ${id} for user ${userId}`);
-      },
-    });
-
-    const server = new McpServer(
-      { name: 'mosaic-gateway', version: '1.0.0' },
-      { capabilities: { tools: {} } },
-    );
-
-    this.registerTools(server, userId);
-
-    transport.onclose = () => {
-      this.logger.log(`MCP session closed: ${sessionId}`);
-      this.sessions.delete(sessionId);
-    };
-
-    server.connect(transport).catch((err: unknown) => {
-      this.logger.error(
-        `MCP server connect error for session ${sessionId}: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    });
-
-    this.sessions.set(sessionId, { server, transport, createdAt: new Date(), userId });
-    return { sessionId, transport };
-  }
-
-  /**
-   * Returns the transport for an existing session, or null if not found.
-   */
-  getSession(sessionId: string): StreamableHTTPServerTransport | null {
-    return this.sessions.get(sessionId)?.transport ?? null;
-  }
-
-  /**
-   * Registers all platform tools on the given McpServer instance.
-   */
-  private registerTools(server: McpServer, _userId: string): void {
-    // ─── Brain: Project tools ────────────────────────────────────────────
-
-    server.registerTool(
-      'brain_list_projects',
-      {
-        description: 'List all projects in the brain.',
-        inputSchema: z.object({}),
-      },
-      async () => {
-        const projects = await this.brain.projects.findAll();
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(projects, null, 2) }],
-        };
-      },
-    );
-
-    server.registerTool(
-      'brain_get_project',
-      {
-        description: 'Get a project by ID.',
-        inputSchema: z.object({
-          id: z.string().describe('Project ID (UUID)'),
-        }),
-      },
-      async ({ id }) => {
-        const project = await this.brain.projects.findById(id);
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: project ? JSON.stringify(project, null, 2) : `Project not found: ${id}`,
-            },
-          ],
-        };
-      },
-    );
-
-    // ─── Brain: Task tools ───────────────────────────────────────────────
-
-    server.registerTool(
-      'brain_list_tasks',
-      {
-        description: 'List tasks, optionally filtered by project, mission, or status.',
-        inputSchema: z.object({
-          projectId: z.string().optional().describe('Filter by project ID'),
-          missionId: z.string().optional().describe('Filter by mission ID'),
-          status: z.string().optional().describe('Filter by status'),
-        }),
-      },
-      async ({ projectId, missionId, status }) => {
-        type TaskStatus = 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
-        let tasks;
-        if (projectId) tasks = await this.brain.tasks.findByProject(projectId);
-        else if (missionId) tasks = await this.brain.tasks.findByMission(missionId);
-        else if (status) tasks = await this.brain.tasks.findByStatus(status as TaskStatus);
-        else tasks = await this.brain.tasks.findAll();
-        return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
-      },
-    );
-
-    server.registerTool(
-      'brain_create_task',
-      {
-        description: 'Create a new task in the brain.',
-        inputSchema: z.object({
-          title: z.string().describe('Task title'),
-          description: z.string().optional().describe('Task description'),
-          projectId: z.string().optional().describe('Project ID'),
-          missionId: z.string().optional().describe('Mission ID'),
-          priority: z.string().optional().describe('Priority: low, medium, high, critical'),
-        }),
-      },
-      async (params) => {
-        type Priority = 'low' | 'medium' | 'high' | 'critical';
-        const task = await this.brain.tasks.create({
-          ...params,
-          priority: params.priority as Priority | undefined,
-        });
-        return { content: [{ type: 'text' as const, text: JSON.stringify(task, null, 2) }] };
-      },
-    );
-
-    server.registerTool(
-      'brain_update_task',
-      {
-        description: 'Update an existing task.',
-        inputSchema: z.object({
-          id: z.string().describe('Task ID'),
-          title: z.string().optional(),
-          description: z.string().optional(),
-          status: z
-            .string()
-            .optional()
-            .describe('not-started, in-progress, blocked, done, cancelled'),
-          priority: z.string().optional(),
-        }),
-      },
-      async ({ id, ...updates }) => {
-        type TaskStatus = 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
-        type Priority = 'low' | 'medium' | 'high' | 'critical';
-        const task = await this.brain.tasks.update(id, {
-          ...updates,
-          status: updates.status as TaskStatus | undefined,
-          priority: updates.priority as Priority | undefined,
-        });
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: task ? JSON.stringify(task, null, 2) : `Task not found: ${id}`,
-            },
-          ],
-        };
-      },
-    );
-
-    // ─── Brain: Mission tools ────────────────────────────────────────────
-
-    server.registerTool(
-      'brain_list_missions',
-      {
-        description: 'List all missions, optionally filtered by project.',
-        inputSchema: z.object({
-          projectId: z.string().optional().describe('Filter by project ID'),
-        }),
-      },
-      async ({ projectId }) => {
-        const missions = projectId
-          ? await this.brain.missions.findByProject(projectId)
-          : await this.brain.missions.findAll();
-        return { content: [{ type: 'text' as const, text: JSON.stringify(missions, null, 2) }] };
-      },
-    );
-
-    server.registerTool(
-      'brain_list_conversations',
-      {
-        description: 'List conversations for a user.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
-        }),
-      },
-      async ({ userId }) => {
-        const conversations = await this.brain.conversations.findAll(userId);
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(conversations, null, 2) }],
-        };
-      },
-    );
-
-    // ─── Memory tools ────────────────────────────────────────────────────
-
-    server.registerTool(
-      'memory_search',
-      {
-        description:
-          'Search across stored insights and knowledge using natural language. Returns semantically similar results.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID to search memory for'),
-          query: z.string().describe('Natural language search query'),
-          limit: z.number().optional().describe('Max results (default 5)'),
-        }),
-      },
-      async ({ userId, query, limit }) => {
-        if (!this.embeddings.available) {
-          return {
-            content: [
-              {
-                type: 'text' as const,
-                text: 'Semantic search unavailable — no embedding provider configured',
-              },
-            ],
-          };
-        }
-        const embedding = await this.embeddings.embed(query);
-        const results = await this.memory.insights.searchByEmbedding(userId, embedding, limit ?? 5);
-        return { content: [{ type: 'text' as const, text: JSON.stringify(results, null, 2) }] };
-      },
-    );
-
-    server.registerTool(
-      'memory_get_preferences',
-      {
-        description: 'Retrieve stored preferences for a user.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
-          category: z
-            .string()
-            .optional()
-            .describe('Filter by category: communication, coding, workflow, appearance, general'),
-        }),
-      },
-      async ({ userId, category }) => {
-        type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
-        const prefs = category
-          ? await this.memory.preferences.findByUserAndCategory(userId, category as Cat)
-          : await this.memory.preferences.findByUser(userId);
-        return { content: [{ type: 'text' as const, text: JSON.stringify(prefs, null, 2) }] };
-      },
-    );
-
-    server.registerTool(
-      'memory_save_preference',
-      {
-        description:
-          'Store a learned user preference (e.g., "prefers tables over paragraphs", "timezone: America/Chicago").',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
-          key: z.string().describe('Preference key'),
-          value: z.string().describe('Preference value (JSON string)'),
-          category: z
-            .string()
-            .optional()
-            .describe('Category: communication, coding, workflow, appearance, general'),
-        }),
-      },
-      async ({ userId, key, value, category }) => {
-        type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
-        let parsedValue: unknown;
-        try {
-          parsedValue = JSON.parse(value);
-        } catch {
-          parsedValue = value;
-        }
-        const pref = await this.memory.preferences.upsert({
-          userId,
-          key,
-          value: parsedValue,
-          category: (category as Cat) ?? 'general',
-          source: 'agent',
-        });
-        return { content: [{ type: 'text' as const, text: JSON.stringify(pref, null, 2) }] };
-      },
-    );
-
-    server.registerTool(
-      'memory_save_insight',
-      {
-        description:
-          'Store a learned insight, decision, or knowledge extracted from the current interaction.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
-          content: z.string().describe('The insight or knowledge to store'),
-          category: z
-            .string()
-            .optional()
-            .describe('Category: decision, learning, preference, fact, pattern, general'),
-        }),
-      },
-      async ({ userId, content, category }) => {
-        type Cat = 'decision' | 'learning' | 'preference' | 'fact' | 'pattern' | 'general';
-        const embedding = this.embeddings.available ? await this.embeddings.embed(content) : null;
-        const insight = await this.memory.insights.create({
-          userId,
-          content,
-          embedding,
-          source: 'agent',
-          category: (category as Cat) ?? 'learning',
-        });
-        return { content: [{ type: 'text' as const, text: JSON.stringify(insight, null, 2) }] };
-      },
-    );
-
-    // ─── Coord tools ─────────────────────────────────────────────────────
-
-    server.registerTool(
-      'coord_mission_status',
-      {
-        description:
-          'Get the current orchestration mission status including milestones, tasks, and active session.',
-        inputSchema: z.object({
-          projectPath: z
-            .string()
-            .optional()
-            .describe('Project path. Defaults to gateway working directory.'),
-        }),
-      },
-      async ({ projectPath }) => {
-        const resolvedPath = projectPath ?? process.cwd();
-        const status = await this.coordService.getMissionStatus(resolvedPath);
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: status ? JSON.stringify(status, null, 2) : 'No active coord mission found.',
-            },
-          ],
-        };
-      },
-    );
-
-    server.registerTool(
-      'coord_list_tasks',
-      {
-        description: 'List all tasks from the orchestration TASKS.md file.',
-        inputSchema: z.object({
-          projectPath: z
-            .string()
-            .optional()
-            .describe('Project path. Defaults to gateway working directory.'),
-        }),
-      },
-      async ({ projectPath }) => {
-        const resolvedPath = projectPath ?? process.cwd();
-        const tasks = await this.coordService.listTasks(resolvedPath);
-        return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
-      },
-    );
-
-    server.registerTool(
-      'coord_task_detail',
-      {
-        description: 'Get detailed status for a specific orchestration task.',
-        inputSchema: z.object({
-          taskId: z.string().describe('Task ID (e.g. P2-005)'),
-          projectPath: z
-            .string()
-            .optional()
-            .describe('Project path. Defaults to gateway working directory.'),
-        }),
-      },
-      async ({ taskId, projectPath }) => {
-        const resolvedPath = projectPath ?? process.cwd();
-        const detail = await this.coordService.getTaskStatus(resolvedPath, taskId);
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: detail
-                ? JSON.stringify(detail, null, 2)
-                : `Task ${taskId} not found in coord mission.`,
-            },
-          ],
-        };
-      },
-    );
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    this.logger.log(`Closing ${this.sessions.size} MCP sessions on shutdown`);
-    const closePromises = Array.from(this.sessions.values()).map(({ transport }) =>
-      transport.close().catch((err: unknown) => {
-        this.logger.warn(
-          `Error closing MCP transport: ${err instanceof Error ? err.message : String(err)}`,
-        );
-      }),
-    );
-    await Promise.all(closePromises);
-    this.sessions.clear();
-  }
-}

apps/gateway/src/reload/reload.service.spec.ts

@@ -1,106 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { ReloadService } from './reload.service.js';
-
-function createMockCommandRegistry() {
-  return {
-    getManifest: vi.fn().mockReturnValue({
-      version: 1,
-      commands: [],
-      skills: [],
-    }),
-  };
-}
-
-function createService() {
-  const registry = createMockCommandRegistry();
-  const service = new ReloadService(registry as never);
-  return { service, registry };
-}
-
-describe('ReloadService', () => {
-  it('reload() calls onUnload then onLoad for registered MosaicPlugin', async () => {
-    const { service } = createService();
-
-    const callOrder: string[] = [];
-    const mockPlugin = {
-      pluginName: 'test-plugin',
-      onLoad: vi.fn().mockImplementation(() => {
-        callOrder.push('onLoad');
-        return Promise.resolve();
-      }),
-      onUnload: vi.fn().mockImplementation(() => {
-        callOrder.push('onUnload');
-        return Promise.resolve();
-      }),
-    };
-
-    service.registerPlugin('test-plugin', mockPlugin);
-    const result = await service.reload('command');
-
-    expect(mockPlugin.onUnload).toHaveBeenCalledOnce();
-    expect(mockPlugin.onLoad).toHaveBeenCalledOnce();
-    expect(callOrder).toEqual(['onUnload', 'onLoad']);
-    expect(result.message).toContain('test-plugin');
-  });
-
-  it('reload() continues if one plugin throws during onUnload', async () => {
-    const { service } = createService();
-
-    const badPlugin = {
-      pluginName: 'bad-plugin',
-      onLoad: vi.fn().mockResolvedValue(undefined),
-      onUnload: vi.fn().mockRejectedValue(new Error('unload failed')),
-    };
-
-    service.registerPlugin('bad-plugin', badPlugin);
-    const result = await service.reload('command');
-
-    expect(result.message).toContain('bad-plugin');
-    expect(result.message).toContain('unload failed');
-  });
-
-  it('reload() skips non-MosaicPlugin objects', async () => {
-    const { service } = createService();
-
-    const notAPlugin = { foo: 'bar' };
-    service.registerPlugin('not-a-plugin', notAPlugin);
-
-    // Should not throw
-    const result = await service.reload('command');
-    expect(result).toBeDefined();
-    expect(result.message).not.toContain('not-a-plugin');
-  });
-
-  it('reload() returns SystemReloadPayload with commands, skills, providers, message', async () => {
-    const { service, registry } = createService();
-    registry.getManifest.mockReturnValue({
-      version: 1,
-      commands: [
-        {
-          name: 'test',
-          description: 'test cmd',
-          aliases: [],
-          scope: 'core',
-          execution: 'socket',
-          available: true,
-        },
-      ],
-      skills: [],
-    });
-
-    const result = await service.reload('rest');
-
-    expect(result).toHaveProperty('commands');
-    expect(result).toHaveProperty('skills');
-    expect(result).toHaveProperty('providers');
-    expect(result).toHaveProperty('message');
-    expect(result.commands).toHaveLength(1);
-  });
-
-  it('registerPlugin() logs plugin registration', () => {
-    const { service } = createService();
-
-    // Should not throw and should register
-    expect(() => service.registerPlugin('my-plugin', {})).not.toThrow();
-  });
-});

apps/gateway/src/workspace/teams.controller.ts

@@ -1,30 +0,0 @@
-import { Controller, Get, Param, UseGuards } from '@nestjs/common';
-import { AuthGuard } from '../auth/auth.guard.js';
-import { TeamsService } from './teams.service.js';
-
-@Controller('api/teams')
-@UseGuards(AuthGuard)
-export class TeamsController {
-  constructor(private readonly teams: TeamsService) {}
-
-  @Get()
-  async list() {
-    return this.teams.findAll();
-  }
-
-  @Get(':teamId')
-  async findOne(@Param('teamId') teamId: string) {
-    return this.teams.findById(teamId);
-  }
-
-  @Get(':teamId/members')
-  async listMembers(@Param('teamId') teamId: string) {
-    return this.teams.listMembers(teamId);
-  }
-
-  @Get(':teamId/members/:userId')
-  async checkMembership(@Param('teamId') teamId: string, @Param('userId') userId: string) {
-    const isMember = await this.teams.isMember(teamId, userId);
-    return { isMember };
-  }
-}

apps/gateway/src/workspace/workspace.service.spec.ts

@@ -1,79 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { WorkspaceService } from './workspace.service.js';
-import path from 'node:path';
-
-describe('WorkspaceService', () => {
-  let service: WorkspaceService;
-
-  beforeEach(() => {
-    service = new WorkspaceService();
-  });
-
-  describe('resolvePath', () => {
-    it('resolves user workspace path', () => {
-      const result = service.resolvePath({
-        id: 'proj1',
-        ownerType: 'user',
-        userId: 'user1',
-        teamId: null,
-      });
-      expect(result).toContain(path.join('users', 'user1', 'proj1'));
-    });
-
-    it('resolves team workspace path', () => {
-      const result = service.resolvePath({
-        id: 'proj1',
-        ownerType: 'team',
-        userId: 'user1',
-        teamId: 'team1',
-      });
-      expect(result).toContain(path.join('teams', 'team1', 'proj1'));
-    });
-
-    it('falls back to user path when ownerType is team but teamId is null', () => {
-      const result = service.resolvePath({
-        id: 'proj1',
-        ownerType: 'team',
-        userId: 'user1',
-        teamId: null,
-      });
-      expect(result).toContain(path.join('users', 'user1', 'proj1'));
-    });
-
-    it('uses MOSAIC_ROOT env var as the base path', () => {
-      const originalRoot = process.env['MOSAIC_ROOT'];
-      process.env['MOSAIC_ROOT'] = '/custom/root';
-      const customService = new WorkspaceService();
-      const result = customService.resolvePath({
-        id: 'proj1',
-        ownerType: 'user',
-        userId: 'user1',
-        teamId: null,
-      });
-      expect(result).toMatch(/^\/custom\/root/);
-      // Restore
-      if (originalRoot === undefined) {
-        delete process.env['MOSAIC_ROOT'];
-      } else {
-        process.env['MOSAIC_ROOT'] = originalRoot;
-      }
-    });
-
-    it('defaults to /opt/mosaic when MOSAIC_ROOT is unset', () => {
-      const originalRoot = process.env['MOSAIC_ROOT'];
-      delete process.env['MOSAIC_ROOT'];
-      const defaultService = new WorkspaceService();
-      const result = defaultService.resolvePath({
-        id: 'proj2',
-        ownerType: 'user',
-        userId: 'user2',
-        teamId: null,
-      });
-      expect(result).toMatch(/^\/opt\/mosaic/);
-      // Restore
-      if (originalRoot !== undefined) {
-        process.env['MOSAIC_ROOT'] = originalRoot;
-      }
-    });
-  });
-});

apps/web/e2e/chat.spec.ts

@@ -1,50 +0,0 @@
-import { test, expect } from '@playwright/test';
-import { loginAs, TEST_USER } from './helpers/auth.js';
-
-test.describe('Chat page', () => {
-  test.beforeEach(async ({ page }) => {
-    await loginAs(page, TEST_USER.email, TEST_USER.password);
-    // If login failed (no seeded user in env) we may be on /login — skip
-    const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
-  });
-
-  test('chat page loads and shows the welcome message or conversation list', async ({ page }) => {
-    await page.goto('/chat');
-    // Either there are conversations listed or the welcome empty-state is shown
-    const hasWelcome = await page
-      .getByRole('heading', { name: /welcome to mosaic chat/i })
-      .isVisible()
-      .catch(() => false);
-    const hasConversationPanel = await page
-      .locator('[data-testid="conversation-list"], nav, aside')
-      .first()
-      .isVisible()
-      .catch(() => false);
-
-    expect(hasWelcome || hasConversationPanel).toBe(true);
-  });
-
-  test('new conversation button is visible', async ({ page }) => {
-    await page.goto('/chat');
-    // "Start new conversation" button or a "+" button in the sidebar
-    const newConvButton = page.getByRole('button', { name: /new conversation|start new/i }).first();
-    await expect(newConvButton).toBeVisible({ timeout: 10_000 });
-  });
-
-  test('clicking new conversation shows a chat input area', async ({ page }) => {
-    await page.goto('/chat');
-    // Find any button that creates a new conversation
-    const newBtn = page.getByRole('button', { name: /new conversation|start new/i }).first();
-    await newBtn.click();
-    // After creating, a text input for sending messages should appear
-    const chatInput = page.getByRole('textbox').or(page.locator('textarea')).first();
-    await expect(chatInput).toBeVisible({ timeout: 10_000 });
-  });
-
-  test('sidebar navigation is present on chat page', async ({ page }) => {
-    await page.goto('/chat');
-    // The app-shell sidebar should be visible
-    await expect(page.getByRole('link', { name: /chat/i }).first()).toBeVisible();
-  });
-});

apps/web/e2e/helpers/auth.ts

@@ -1,23 +0,0 @@
-import type { Page } from '@playwright/test';
-
-export const TEST_USER = {
-  email: process.env['E2E_USER_EMAIL'] ?? '[email protected]',
-  password: process.env['E2E_USER_PASSWORD'] ?? 'password123',
-  name: 'E2E Test User',
-};
-
-export const ADMIN_USER = {
-  email: process.env['E2E_ADMIN_EMAIL'] ?? '[email protected]',
-  password: process.env['E2E_ADMIN_PASSWORD'] ?? 'adminpass123',
-  name: 'E2E Admin User',
-};
-
-/**
- * Fill the login form and submit. Waits for navigation after success.
- */
-export async function loginAs(page: Page, email: string, password: string): Promise<void> {
-  await page.goto('/login');
-  await page.getByLabel('Email').fill(email);
-  await page.getByLabel('Password').fill(password);
-  await page.getByRole('button', { name: /sign in/i }).click();
-}

apps/web/next-env.d.ts

@@ -1,6 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/web/next.config.ts

@@ -1,32 +0,0 @@
-import type { NextConfig } from 'next';
-
-const nextConfig: NextConfig = {
-  output: 'standalone',
-  transpilePackages: ['@mosaicstack/design-tokens'],
-
-  // Enable gzip/brotli compression for all responses.
-  compress: true,
-
-  // Reduce bundle size: disable source maps in production builds.
-  productionBrowserSourceMaps: false,
-
-  // Image optimisation: allow the gateway origin as an external image source.
-  images: {
-    formats: ['image/avif', 'image/webp'],
-    remotePatterns: [
-      {
-        protocol: 'https',
-        hostname: '**',
-      },
-    ],
-  },
-
-  // Experimental: enable React compiler for automatic memoisation (Next 15+).
-  // Falls back gracefully if the compiler plugin is not installed.
-  experimental: {
-    // Turbopack is the default in dev for Next 15; keep it opt-in for now.
-    // turbo: {},
-  },
-};
-
-export default nextConfig;

apps/web/playwright.config.ts

@@ -1,32 +0,0 @@
-import { defineConfig, devices } from '@playwright/test';
-
-/**
- * Playwright E2E configuration for Mosaic web app.
- *
- * Assumes:
- *   - Next.js web app running on http://localhost:3000
- *   - NestJS gateway running on http://localhost:14242
- *
- * Run with:   pnpm --filter @mosaicstack/web test:e2e
- */
-export default defineConfig({
-  testDir: './e2e',
-  fullyParallel: true,
-  forbidOnly: !!process.env['CI'],
-  retries: process.env['CI'] ? 2 : 0,
-  workers: process.env['CI'] ? 1 : undefined,
-  reporter: 'html',
-  use: {
-    baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:3000',
-    trace: 'on-first-retry',
-    screenshot: 'only-on-failure',
-  },
-  projects: [
-    {
-      name: 'chromium',
-      use: { ...devices['Desktop Chrome'] },
-    },
-  ],
-  // Do NOT auto-start the dev server — tests assume it is already running.
-  // webServer is intentionally omitted so tests can run against a live env.
-});

apps/web/src/app/(auth)/layout.tsx

@@ -1,14 +0,0 @@
-import type { ReactNode } from 'react';
-import { GuestGuard } from '@/components/guest-guard';
-
-export default function AuthLayout({ children }: { children: ReactNode }): React.ReactElement {
-  return (
-    <GuestGuard>
-      <div className="flex min-h-screen items-center justify-center bg-surface-bg">
-        <div className="w-full max-w-md rounded-xl border border-surface-border bg-surface-card p-8 shadow-lg">
-          {children}
-        </div>
-      </div>
-    </GuestGuard>
-  );
-}

apps/web/src/app/(dashboard)/chat/page.tsx

@@ -1,365 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { api } from '@/lib/api';
-import { destroySocket, getSocket } from '@/lib/socket';
-import type { Conversation, Message } from '@/lib/types';
-import {
-  ConversationSidebar,
-  type ConversationSidebarRef,
-} from '@/components/chat/conversation-sidebar';
-import { MessageBubble } from '@/components/chat/message-bubble';
-import { ChatInput } from '@/components/chat/chat-input';
-import { StreamingMessage } from '@/components/chat/streaming-message';
-
-interface ModelInfo {
-  id: string;
-  provider: string;
-  name: string;
-  reasoning: boolean;
-  contextWindow: number;
-  maxTokens: number;
-  inputTypes: ('text' | 'image')[];
-  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
-}
-
-interface ProviderInfo {
-  id: string;
-  name: string;
-  available: boolean;
-  models: ModelInfo[];
-}
-
-export default function ChatPage(): React.ReactElement {
-  const [activeId, setActiveId] = useState<string | null>(null);
-  const [messages, setMessages] = useState<Message[]>([]);
-  const [streamingText, setStreamingText] = useState('');
-  const [isStreaming, setIsStreaming] = useState(false);
-  const [isSidebarOpen, setIsSidebarOpen] = useState(true);
-  const [models, setModels] = useState<ModelInfo[]>([]);
-  const [selectedModelId, setSelectedModelId] = useState('');
-  const messagesEndRef = useRef<HTMLDivElement>(null);
-  const sidebarRef = useRef<ConversationSidebarRef>(null);
-
-  // Track the active conversation ID in a ref so socket event handlers always
-  // see the current value without needing to be re-registered.
-  const activeIdRef = useRef<string | null>(null);
-  activeIdRef.current = activeId;
-
-  // Accumulate streamed text in a ref so agent:end can read the full content
-  // without stale-closure issues.
-  const streamingTextRef = useRef('');
-
-  useEffect(() => {
-    const savedState = window.localStorage.getItem('mosaic-sidebar-open');
-    if (savedState !== null) {
-      setIsSidebarOpen(savedState === 'true');
-    }
-  }, []);
-
-  useEffect(() => {
-    window.localStorage.setItem('mosaic-sidebar-open', String(isSidebarOpen));
-  }, [isSidebarOpen]);
-
-  useEffect(() => {
-    api<ProviderInfo[]>('/api/providers')
-      .then((providers) => {
-        const availableModels = providers
-          .filter((provider) => provider.available)
-          .flatMap((provider) => provider.models);
-        setModels(availableModels);
-        setSelectedModelId((current) => current || availableModels[0]?.id || '');
-      })
-      .catch(() => {
-        setModels([]);
-        setSelectedModelId('');
-      });
-  }, []);
-
-  // Load messages when active conversation changes
-  useEffect(() => {
-    if (!activeId) {
-      setMessages([]);
-      return;
-    }
-    // Clear streaming state when switching conversations
-    setIsStreaming(false);
-    setStreamingText('');
-    streamingTextRef.current = '';
-    api<Message[]>(`/api/conversations/${activeId}/messages`)
-      .then(setMessages)
-      .catch(() => {});
-  }, [activeId]);
-
-  // Auto-scroll to bottom
-  useEffect(() => {
-    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
-  }, [messages, streamingText]);
-
-  // Socket.io setup — connect once for the page lifetime
-  useEffect(() => {
-    const socket = getSocket();
-
-    function onAgentStart(data: { conversationId: string }): void {
-      // Only update state if the event belongs to the currently viewed conversation
-      if (activeIdRef.current !== data.conversationId) return;
-      setIsStreaming(true);
-      setStreamingText('');
-      streamingTextRef.current = '';
-    }
-
-    function onAgentText(data: { conversationId: string; text: string }): void {
-      if (activeIdRef.current !== data.conversationId) return;
-      streamingTextRef.current += data.text;
-      setStreamingText((prev) => prev + data.text);
-    }
-
-    function onAgentEnd(data: { conversationId: string }): void {
-      if (activeIdRef.current !== data.conversationId) return;
-      const finalText = streamingTextRef.current;
-      setIsStreaming(false);
-      setStreamingText('');
-      streamingTextRef.current = '';
-      // Append the completed assistant message to the local message list.
-      // The Pi agent session is in-memory so the assistant response is not
-      // persisted to the DB — we build the local UI state instead.
-      if (finalText) {
-        setMessages((prev) => [
-          ...prev,
-          {
-            id: `assistant-${Date.now()}`,
-            conversationId: data.conversationId,
-            role: 'assistant' as const,
-            content: finalText,
-            createdAt: new Date().toISOString(),
-          },
-        ]);
-        sidebarRef.current?.refresh();
-      }
-    }
-
-    function onError(data: { error: string; conversationId?: string }): void {
-      setIsStreaming(false);
-      setStreamingText('');
-      streamingTextRef.current = '';
-      setMessages((prev) => [
-        ...prev,
-        {
-          id: `error-${Date.now()}`,
-          conversationId: data.conversationId ?? '',
-          role: 'system' as const,
-          content: `Error: ${data.error}`,
-          createdAt: new Date().toISOString(),
-        },
-      ]);
-    }
-
-    socket.on('agent:start', onAgentStart);
-    socket.on('agent:text', onAgentText);
-    socket.on('agent:end', onAgentEnd);
-    socket.on('error', onError);
-
-    // Connect if not already connected
-    if (!socket.connected) {
-      socket.connect();
-    }
-
-    return () => {
-      socket.off('agent:start', onAgentStart);
-      socket.off('agent:text', onAgentText);
-      socket.off('agent:end', onAgentEnd);
-      socket.off('error', onError);
-      // Fully tear down the socket when the chat page unmounts so we get a
-      // fresh authenticated connection next time the page is visited.
-      destroySocket();
-    };
-  }, []);
-
-  const handleNewConversation = useCallback(async (projectId?: string | null) => {
-    const conv = await api<Conversation>('/api/conversations', {
-      method: 'POST',
-      body: { title: 'New conversation', projectId: projectId ?? null },
-    });
-
-    sidebarRef.current?.addConversation({
-      id: conv.id,
-      title: conv.title,
-      projectId: conv.projectId,
-      updatedAt: conv.updatedAt,
-      archived: conv.archived,
-    });
-
-    setActiveId(conv.id);
-    setMessages([]);
-    setIsSidebarOpen(true);
-  }, []);
-
-  const handleSend = useCallback(
-    async (content: string, options?: { modelId?: string }) => {
-      let convId = activeId;
-
-      // Auto-create conversation if none selected
-      if (!convId) {
-        const autoTitle = content.slice(0, 60);
-        const conv = await api<Conversation>('/api/conversations', {
-          method: 'POST',
-          body: { title: autoTitle },
-        });
-        sidebarRef.current?.addConversation({
-          id: conv.id,
-          title: conv.title,
-          projectId: conv.projectId,
-          updatedAt: conv.updatedAt,
-          archived: conv.archived,
-        });
-        setActiveId(conv.id);
-        convId = conv.id;
-      } else if (messages.length === 0) {
-        // Auto-title the initial placeholder conversation from the first user message.
-        const autoTitle = content.slice(0, 60);
-        api<Conversation>(`/api/conversations/${convId}`, {
-          method: 'PATCH',
-          body: { title: autoTitle },
-        })
-          .then(() => sidebarRef.current?.refresh())
-          .catch(() => {});
-      }
-
-      // Optimistic user message in local UI state
-      setMessages((prev) => [
-        ...prev,
-        {
-          id: `user-${Date.now()}`,
-          conversationId: convId,
-          role: 'user' as const,
-          content,
-          createdAt: new Date().toISOString(),
-        },
-      ]);
-
-      // Persist the user message to the DB so conversation history is
-      // available when the page is reloaded or a new session starts.
-      api<Message>(`/api/conversations/${convId}/messages`, {
-        method: 'POST',
-        body: { role: 'user', content },
-      }).catch(() => {
-        // Non-fatal: the agent can still process the message even if
-        // REST persistence fails.
-      });
-
-      // Send to WebSocket — gateway creates/resumes the agent session and
-      // streams the response back via agent:start / agent:text / agent:end.
-      const socket = getSocket();
-      if (!socket.connected) {
-        socket.connect();
-      }
-      socket.emit('message', {
-        conversationId: convId,
-        content,
-        modelId: (options?.modelId ?? selectedModelId) || undefined,
-      });
-    },
-    [activeId, messages, selectedModelId],
-  );
-
-  return (
-    <div
-      className="-m-6 flex h-[calc(100vh-3.5rem)] overflow-hidden"
-      style={{ background: 'var(--bg-deep, var(--color-surface-bg, #0a0f1a))' }}
-    >
-      <ConversationSidebar
-        ref={sidebarRef}
-        isOpen={isSidebarOpen}
-        onClose={() => setIsSidebarOpen(false)}
-        currentConversationId={activeId}
-        onSelectConversation={(conversationId) => {
-          setActiveId(conversationId);
-          setMessages([]);
-          if (conversationId && window.innerWidth < 768) {
-            setIsSidebarOpen(false);
-          }
-        }}
-        onNewConversation={(projectId) => {
-          void handleNewConversation(projectId);
-        }}
-      />
-
-      <div className="flex min-w-0 flex-1 flex-col">
-        <div
-          className="flex items-center gap-3 border-b px-4 py-3"
-          style={{ borderColor: 'var(--border)' }}
-        >
-          <button
-            type="button"
-            onClick={() => setIsSidebarOpen((open) => !open)}
-            className="rounded-lg border p-2 transition-colors"
-            style={{
-              borderColor: 'var(--border)',
-              background: 'var(--surface)',
-              color: 'var(--text)',
-            }}
-            aria-label={isSidebarOpen ? 'Close conversation sidebar' : 'Open conversation sidebar'}
-          >
-            <svg viewBox="0 0 24 24" className="h-4 w-4" fill="none" stroke="currentColor">
-              <path strokeWidth="2" strokeLinecap="round" d="M4 7h16M4 12h16M4 17h16" />
-            </svg>
-          </button>
-          <div>
-            <h1 className="text-sm font-semibold" style={{ color: 'var(--text)' }}>
-              Mosaic Chat
-            </h1>
-            <p className="text-xs" style={{ color: 'var(--muted)' }}>
-              {activeId ? 'Active conversation selected' : 'Choose or start a conversation'}
-            </p>
-          </div>
-        </div>
-
-        {activeId ? (
-          <>
-            <div className="flex-1 space-y-4 overflow-y-auto p-6">
-              {messages.map((msg) => (
-                <MessageBubble key={msg.id} message={msg} />
-              ))}
-              {isStreaming && <StreamingMessage text={streamingText} />}
-              <div ref={messagesEndRef} />
-            </div>
-            <ChatInput
-              onSend={handleSend}
-              isStreaming={isStreaming}
-              models={models}
-              selectedModelId={selectedModelId}
-              onModelChange={setSelectedModelId}
-            />
-          </>
-        ) : (
-          <div className="flex flex-1 items-center justify-center px-6">
-            <div
-              className="max-w-md rounded-2xl border px-8 py-10 text-center"
-              style={{
-                borderColor: 'var(--border)',
-                background: 'var(--surface)',
-              }}
-            >
-              <h2 className="text-lg font-medium" style={{ color: 'var(--text)' }}>
-                Welcome to Mosaic Chat
-              </h2>
-              <p className="mt-1 text-sm" style={{ color: 'var(--muted)' }}>
-                Select a conversation or start a new one
-              </p>
-              <button
-                type="button"
-                onClick={() => {
-                  void handleNewConversation();
-                }}
-                className="mt-4 rounded-lg px-4 py-2 text-sm font-medium text-white transition-colors"
-                style={{ background: 'var(--primary)' }}
-              >
-                Start new conversation
-              </button>
-            </div>
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}

apps/web/src/app/(dashboard)/layout.tsx

@@ -1,11 +0,0 @@
-import type { ReactNode } from 'react';
-import { AppShell } from '@/components/layout/app-shell';
-import { AuthGuard } from '@/components/auth-guard';
-
-export default function DashboardLayout({ children }: { children: ReactNode }): React.ReactElement {
-  return (
-    <AuthGuard>
-      <AppShell>{children}</AppShell>
-    </AuthGuard>
-  );
-}

apps/web/src/app/(dashboard)/projects/[id]/page.tsx

@@ -1,338 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useState } from 'react';
-import { useParams, useRouter } from 'next/navigation';
-import { api } from '@/lib/api';
-import { cn } from '@/lib/cn';
-import type { Mission, Project, Task, TaskStatus } from '@/lib/types';
-import { MissionTimeline } from '@/components/projects/mission-timeline';
-import { PrdViewer } from '@/components/projects/prd-viewer';
-import { TaskDetailModal } from '@/components/tasks/task-detail-modal';
-import { TaskListView } from '@/components/tasks/task-list-view';
-import { TaskStatusSummary } from '@/components/tasks/task-status-summary';
-
-type Tab = 'overview' | 'tasks' | 'missions' | 'prd';
-
-const statusColors: Record<string, string> = {
-  active: 'bg-success/20 text-success',
-  paused: 'bg-warning/20 text-warning',
-  completed: 'bg-blue-600/20 text-blue-400',
-  archived: 'bg-gray-600/20 text-gray-400',
-};
-
-interface TabButtonProps {
-  id: Tab;
-  label: string;
-  activeTab: Tab;
-  onClick: (tab: Tab) => void;
-}
-
-function TabButton({ id, label, activeTab, onClick }: TabButtonProps): React.ReactElement {
-  return (
-    <button
-      type="button"
-      onClick={() => onClick(id)}
-      className={cn(
-        'border-b-2 px-4 py-2 text-sm transition-colors',
-        activeTab === id
-          ? 'border-text-primary text-text-primary'
-          : 'border-transparent text-text-muted hover:text-text-secondary',
-      )}
-    >
-      {label}
-    </button>
-  );
-}
-
-export default function ProjectDetailPage(): React.ReactElement {
-  const params = useParams();
-  const router = useRouter();
-  const id = typeof params['id'] === 'string' ? params['id'] : '';
-
-  const [project, setProject] = useState<Project | null>(null);
-  const [missions, setMissions] = useState<Mission[]>([]);
-  const [tasks, setTasks] = useState<Task[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  const [activeTab, setActiveTab] = useState<Tab>('overview');
-  const [taskFilter, setTaskFilter] = useState<TaskStatus | 'all'>('all');
-  const [selectedTask, setSelectedTask] = useState<Task | null>(null);
-
-  useEffect(() => {
-    if (!id) return;
-
-    setLoading(true);
-    setError(null);
-
-    Promise.all([
-      api<Project>(`/api/projects/${id}`),
-      api<Mission[]>('/api/missions').catch(() => [] as Mission[]),
-      api<Task[]>(`/api/tasks?projectId=${id}`).catch(() => [] as Task[]),
-    ])
-      .then(([proj, allMissions, tks]) => {
-        setProject(proj);
-        setMissions(allMissions.filter((m) => m.projectId === id));
-        setTasks(tks);
-      })
-      .catch((err: Error) => {
-        setError(err.message ?? 'Failed to load project');
-      })
-      .finally(() => setLoading(false));
-  }, [id]);
-
-  const handleTaskClick = useCallback((task: Task) => {
-    setSelectedTask(task);
-  }, []);
-
-  const handleCloseTaskModal = useCallback(() => {
-    setSelectedTask(null);
-  }, []);
-
-  if (loading) {
-    return (
-      <div className="py-16 text-center">
-        <p className="text-sm text-text-muted">Loading project...</p>
-      </div>
-    );
-  }
-
-  if (error || !project) {
-    return (
-      <div className="py-16 text-center">
-        <p className="text-sm text-error">{error ?? 'Project not found'}</p>
-        <button
-          type="button"
-          onClick={() => router.push('/projects')}
-          className="mt-4 text-sm text-text-muted underline hover:text-text-secondary"
-        >
-          Back to projects
-        </button>
-      </div>
-    );
-  }
-
-  const filteredTasks = taskFilter === 'all' ? tasks : tasks.filter((t) => t.status === taskFilter);
-
-  const prdContent = getPrdContent(project);
-  const hasPrd = Boolean(prdContent);
-
-  const tabs: { id: Tab; label: string }[] = [
-    { id: 'overview', label: 'Overview' },
-    { id: 'tasks', label: `Tasks (${tasks.length})` },
-    { id: 'missions', label: `Missions (${missions.length})` },
-    ...(hasPrd ? [{ id: 'prd' as Tab, label: 'PRD' }] : []),
-  ];
-
-  return (
-    <div>
-      {/* Breadcrumb */}
-      <nav className="mb-4 flex items-center gap-2 text-sm text-text-muted">
-        <button
-          type="button"
-          onClick={() => router.push('/projects')}
-          className="hover:text-text-secondary"
-        >
-          Projects
-        </button>
-        <span>/</span>
-        <span className="text-text-primary">{project.name}</span>
-      </nav>
-
-      {/* Project header */}
-      <div className="mb-6 flex items-start justify-between gap-4">
-        <div>
-          <div className="flex items-center gap-3">
-            <h1 className="text-2xl font-semibold text-text-primary">{project.name}</h1>
-            <span
-              className={cn(
-                'rounded-full px-2 py-0.5 text-xs',
-                statusColors[project.status] ?? 'bg-gray-600/20 text-gray-400',
-              )}
-            >
-              {project.status}
-            </span>
-          </div>
-          {project.description && (
-            <p className="mt-1 text-sm text-text-muted">{project.description}</p>
-          )}
-          <p className="mt-2 text-xs text-text-muted">
-            Created {new Date(project.createdAt).toLocaleDateString()} · Updated{' '}
-            {new Date(project.updatedAt).toLocaleDateString()}
-          </p>
-        </div>
-      </div>
-
-      {/* Stats bar */}
-      <div className="mb-6 grid grid-cols-2 gap-3 sm:grid-cols-4">
-        <StatCard label="Tasks" value={String(tasks.length)} />
-        <StatCard
-          label="Done"
-          value={String(tasks.filter((t) => t.status === 'done').length)}
-          valueClass="text-success"
-        />
-        <StatCard
-          label="In Progress"
-          value={String(tasks.filter((t) => t.status === 'in-progress').length)}
-          valueClass="text-blue-400"
-        />
-        <StatCard
-          label="Blocked"
-          value={String(tasks.filter((t) => t.status === 'blocked').length)}
-          valueClass={tasks.some((t) => t.status === 'blocked') ? 'text-error' : undefined}
-        />
-      </div>
-
-      {/* Tabs */}
-      <div className="mb-6 flex gap-0 border-b border-surface-border">
-        {tabs.map((tab) => (
-          <TabButton
-            key={tab.id}
-            id={tab.id}
-            label={tab.label}
-            activeTab={activeTab}
-            onClick={setActiveTab}
-          />
-        ))}
-      </div>
-
-      {/* Tab content */}
-      {activeTab === 'overview' && (
-        <OverviewTab project={project} missions={missions} tasks={tasks} />
-      )}
-
-      {activeTab === 'tasks' && (
-        <div>
-          <div className="mb-4">
-            <TaskStatusSummary
-              tasks={tasks}
-              activeFilter={taskFilter}
-              onFilterChange={setTaskFilter}
-            />
-          </div>
-          <TaskListView tasks={filteredTasks} onTaskClick={handleTaskClick} />
-        </div>
-      )}
-
-      {activeTab === 'missions' && <MissionTimeline missions={missions} />}
-
-      {activeTab === 'prd' && prdContent && (
-        <div className="rounded-lg border border-surface-border bg-surface-card p-6">
-          <PrdViewer content={prdContent} />
-        </div>
-      )}
-
-      {/* Task detail modal */}
-      {selectedTask && <TaskDetailModal task={selectedTask} onClose={handleCloseTaskModal} />}
-    </div>
-  );
-}
-
-interface OverviewTabProps {
-  project: Project;
-  missions: Mission[];
-  tasks: Task[];
-}
-
-function OverviewTab({ project, missions, tasks }: OverviewTabProps): React.ReactElement {
-  const recentTasks = [...tasks]
-    .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
-    .slice(0, 5);
-
-  return (
-    <div className="grid gap-6 lg:grid-cols-2">
-      {/* Recent tasks */}
-      <section>
-        <h2 className="mb-3 text-sm font-semibold text-text-secondary">Recent Tasks</h2>
-        {recentTasks.length === 0 ? (
-          <div className="rounded-lg border border-surface-border bg-surface-card p-4 text-center">
-            <p className="text-sm text-text-muted">No tasks yet</p>
-          </div>
-        ) : (
-          <div className="space-y-2">
-            {recentTasks.map((task) => (
-              <TaskSummaryRow key={task.id} task={task} />
-            ))}
-          </div>
-        )}
-      </section>
-
-      {/* Mission summary */}
-      <section>
-        <h2 className="mb-3 text-sm font-semibold text-text-secondary">Missions</h2>
-        {missions.length === 0 ? (
-          <div className="rounded-lg border border-surface-border bg-surface-card p-4 text-center">
-            <p className="text-sm text-text-muted">No missions yet</p>
-          </div>
-        ) : (
-          <MissionTimeline missions={missions.slice(0, 4)} />
-        )}
-      </section>
-
-      {/* Metadata */}
-      {project.metadata && Object.keys(project.metadata).length > 0 && (
-        <section className="lg:col-span-2">
-          <h2 className="mb-3 text-sm font-semibold text-text-secondary">Project Metadata</h2>
-          <div className="rounded-lg border border-surface-border bg-surface-card p-4">
-            <pre className="overflow-x-auto text-xs text-text-muted">
-              {JSON.stringify(project.metadata, null, 2)}
-            </pre>
-          </div>
-        </section>
-      )}
-    </div>
-  );
-}
-
-const taskStatusColors: Record<string, string> = {
-  'not-started': 'bg-gray-600/20 text-gray-300',
-  'in-progress': 'bg-blue-600/20 text-blue-400',
-  blocked: 'bg-error/20 text-error',
-  done: 'bg-success/20 text-success',
-  cancelled: 'bg-gray-600/20 text-gray-500',
-};
-
-function TaskSummaryRow({ task }: { task: Task }): React.ReactElement {
-  return (
-    <div className="flex items-center justify-between gap-2 rounded-lg border border-surface-border bg-surface-card px-3 py-2">
-      <span className="truncate text-sm text-text-primary">{task.title}</span>
-      <span
-        className={cn(
-          'shrink-0 rounded-full px-2 py-0.5 text-xs',
-          taskStatusColors[task.status] ?? 'bg-gray-600/20 text-gray-400',
-        )}
-      >
-        {task.status}
-      </span>
-    </div>
-  );
-}
-
-function StatCard({
-  label,
-  value,
-  valueClass,
-}: {
-  label: string;
-  value: string;
-  valueClass?: string;
-}): React.ReactElement {
-  return (
-    <div className="rounded-lg border border-surface-border bg-surface-card p-3">
-      <p className="text-xs text-text-muted">{label}</p>
-      <p className={cn('mt-1 text-lg font-semibold', valueClass ?? 'text-text-primary')}>{value}</p>
-    </div>
-  );
-}
-
-function getPrdContent(project: Project): string | null {
-  if (!project.metadata) return null;
-
-  const prd = project.metadata['prd'];
-  if (typeof prd === 'string' && prd.trim().length > 0) return prd;
-
-  const prdContent = project.metadata['prdContent'];
-  if (typeof prdContent === 'string' && prdContent.trim().length > 0) return prdContent;
-
-  return null;
-}

apps/web/src/app/(dashboard)/projects/page.tsx

@@ -1,101 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useState } from 'react';
-import { useRouter } from 'next/navigation';
-import { api } from '@/lib/api';
-import type { Project } from '@/lib/types';
-import { ProjectCard } from '@/components/projects/project-card';
-
-export default function ProjectsPage(): React.ReactElement {
-  const [projects, setProjects] = useState<Project[]>([]);
-  const [loading, setLoading] = useState(true);
-  const router = useRouter();
-
-  useEffect(() => {
-    api<Project[]>('/api/projects')
-      .then(setProjects)
-      .catch(() => {})
-      .finally(() => setLoading(false));
-  }, []);
-
-  const handleProjectClick = useCallback(
-    (project: Project) => {
-      router.push(`/projects/${project.id}`);
-    },
-    [router],
-  );
-
-  return (
-    <div>
-      <div className="mb-6 flex items-center justify-between">
-        <h1 className="text-2xl font-semibold">Projects</h1>
-      </div>
-
-      {loading ? (
-        <p className="py-8 text-center text-sm text-text-muted">Loading projects...</p>
-      ) : projects.length === 0 ? (
-        <div className="py-12 text-center">
-          <h2 className="text-lg font-medium text-text-secondary">No projects yet</h2>
-          <p className="mt-1 text-sm text-text-muted">
-            Projects will appear here when created via the gateway API
-          </p>
-        </div>
-      ) : (
-        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-          {projects.map((project) => (
-            <ProjectCard key={project.id} project={project} onClick={handleProjectClick} />
-          ))}
-        </div>
-      )}
-
-      {/* Mission status section */}
-      <MissionStatus />
-    </div>
-  );
-}
-
-function MissionStatus(): React.ReactElement {
-  const [mission, setMission] = useState<Record<string, unknown> | null>(null);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    api<Record<string, unknown>>('/api/coord/status')
-      .then(setMission)
-      .catch(() => setMission(null))
-      .finally(() => setLoading(false));
-  }, []);
-
-  return (
-    <section className="mt-8">
-      <h2 className="mb-4 text-lg font-semibold">Active Mission</h2>
-      {loading ? (
-        <p className="text-sm text-text-muted">Loading mission status...</p>
-      ) : !mission ? (
-        <div className="rounded-lg border border-surface-border bg-surface-card p-6 text-center">
-          <p className="text-sm text-text-muted">No active mission detected</p>
-        </div>
-      ) : (
-        <div className="rounded-lg border border-surface-border bg-surface-card p-4">
-          <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
-            <StatCard label="Mission" value={String(mission['missionId'] ?? 'Unknown')} />
-            <StatCard label="Phase" value={String(mission['currentPhase'] ?? '—')} />
-            <StatCard
-              label="Tasks"
-              value={`${mission['completedTasks'] ?? 0} / ${mission['totalTasks'] ?? 0}`}
-            />
-            <StatCard label="Status" value={String(mission['status'] ?? '—')} />
-          </div>
-        </div>
-      )}
-    </section>
-  );
-}
-
-function StatCard({ label, value }: { label: string; value: string }): React.ReactElement {
-  return (
-    <div className="rounded-lg bg-surface-elevated p-3">
-      <p className="text-xs text-text-muted">{label}</p>
-      <p className="mt-1 text-sm font-medium text-text-primary">{value}</p>
-    </div>
-  );
-}

apps/web/src/app/(dashboard)/tasks/page.tsx

@@ -1,72 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useState } from 'react';
-import { api } from '@/lib/api';
-import { cn } from '@/lib/cn';
-import type { Task } from '@/lib/types';
-import { KanbanBoard } from '@/components/tasks/kanban-board';
-import { TaskListView } from '@/components/tasks/task-list-view';
-
-type ViewMode = 'list' | 'kanban';
-
-export default function TasksPage(): React.ReactElement {
-  const [tasks, setTasks] = useState<Task[]>([]);
-  const [view, setView] = useState<ViewMode>('kanban');
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    api<Task[]>('/api/tasks')
-      .then(setTasks)
-      .catch(() => {})
-      .finally(() => setLoading(false));
-  }, []);
-
-  const handleTaskClick = useCallback((task: Task) => {
-    // Task detail view will be added in future iteration
-    console.log('Task clicked:', task.id);
-  }, []);
-
-  return (
-    <div>
-      <div className="mb-6 flex items-center justify-between">
-        <h1 className="text-2xl font-semibold">Tasks</h1>
-        <div className="flex items-center gap-2">
-          <div className="flex rounded-lg border border-surface-border">
-            <button
-              type="button"
-              onClick={() => setView('list')}
-              className={cn(
-                'px-3 py-1.5 text-xs transition-colors',
-                view === 'list'
-                  ? 'bg-surface-elevated text-text-primary'
-                  : 'text-text-muted hover:text-text-secondary',
-              )}
-            >
-              List
-            </button>
-            <button
-              type="button"
-              onClick={() => setView('kanban')}
-              className={cn(
-                'px-3 py-1.5 text-xs transition-colors',
-                view === 'kanban'
-                  ? 'bg-surface-elevated text-text-primary'
-                  : 'text-text-muted hover:text-text-secondary',
-              )}
-            >
-              Kanban
-            </button>
-          </div>
-        </div>
-      </div>
-
-      {loading ? (
-        <p className="py-8 text-center text-sm text-text-muted">Loading tasks...</p>
-      ) : view === 'kanban' ? (
-        <KanbanBoard tasks={tasks} onTaskClick={handleTaskClick} />
-      ) : (
-        <TaskListView tasks={tasks} onTaskClick={handleTaskClick} />
-      )}
-    </div>
-  );
-}

apps/web/src/app/auth/provider/[provider]/page.tsx

@@ -1,77 +0,0 @@
-'use client';
-
-import Link from 'next/link';
-import { useEffect, useState } from 'react';
-import { useParams, useSearchParams } from 'next/navigation';
-import { signIn } from '@/lib/auth-client';
-import { getSsoProvider } from '@/lib/sso-providers';
-
-export default function AuthProviderRedirectPage(): React.ReactElement {
-  const params = useParams<{ provider: string }>();
-  const searchParams = useSearchParams();
-  const providerId = typeof params.provider === 'string' ? params.provider : '';
-  const provider = getSsoProvider(providerId);
-  const callbackURL = searchParams.get('callbackURL') ?? '/chat';
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    const currentProvider = provider;
-
-    if (!currentProvider) {
-      setError('Unknown SSO provider.');
-      return;
-    }
-
-    if (!currentProvider.enabled) {
-      setError(`${currentProvider.buttonLabel} is not enabled in this deployment.`);
-      return;
-    }
-
-    const activeProvider = currentProvider;
-    let cancelled = false;
-
-    async function redirectToProvider(): Promise<void> {
-      const result = await signIn.oauth2({
-        providerId: activeProvider.id,
-        callbackURL,
-      });
-
-      if (!cancelled && result?.error) {
-        setError(result.error.message ?? `${activeProvider.buttonLabel} sign in failed.`);
-      }
-    }
-
-    void redirectToProvider();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [callbackURL, provider]);
-
-  return (
-    <div className="mx-auto flex min-h-[50vh] max-w-md flex-col justify-center">
-      <h1 className="text-2xl font-semibold text-text-primary">Single sign-on</h1>
-      <p className="mt-2 text-sm text-text-secondary">
-        {provider
-          ? `Redirecting you to ${provider.buttonLabel.replace('Continue with ', '')}...`
-          : 'Preparing your sign-in request...'}
-      </p>
-
-      {error ? (
-        <div className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error">
-          <p>{error}</p>
-          <Link
-            href="/login"
-            className="mt-3 inline-block font-medium text-blue-400 hover:text-blue-300"
-          >
-            Return to login
-          </Link>
-        </div>
-      ) : (
-        <div className="mt-6 rounded-lg border border-surface-border bg-surface-elevated px-4 py-3 text-sm text-text-secondary">
-          If the redirect does not start automatically, return to the login page and try again.
-        </div>
-      )}
-    </div>
-  );
-}

apps/web/src/app/layout.tsx

@@ -1,41 +0,0 @@
-import type { Metadata } from 'next';
-import type { ReactNode } from 'react';
-import { ThemeProvider } from '@/providers/theme-provider';
-import './globals.css';
-
-export const metadata: Metadata = {
-  title: 'Mosaic',
-  description: 'Mosaic Stack Dashboard',
-};
-
-function themeScript(): string {
-  return `
-    (function () {
-      try {
-        var theme = window.localStorage.getItem('mosaic-theme') || 'dark';
-        document.documentElement.setAttribute('data-theme', theme === 'light' ? 'light' : 'dark');
-      } catch (error) {
-        document.documentElement.setAttribute('data-theme', 'dark');
-      }
-    })();
-  `;
-}
-
-export default function RootLayout({ children }: { children: ReactNode }): React.ReactElement {
-  return (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <link rel="preconnect" href="https://fonts.googleapis.com" />
-        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
-        <link
-          rel="stylesheet"
-          href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Fira+Code:wght@400;500&display=swap"
-        />
-        <script dangerouslySetInnerHTML={{ __html: themeScript() }} />
-      </head>
-      <body>
-        <ThemeProvider>{children}</ThemeProvider>
-      </body>
-    </html>
-  );
-}

apps/web/src/app/page.tsx

@@ -1,5 +0,0 @@
-import { redirect } from 'next/navigation';
-
-export default function HomePage(): never {
-  redirect('/chat');
-}

apps/web/src/components/admin-role-guard.tsx

@@ -1,40 +0,0 @@
-'use client';
-
-import { useRouter } from 'next/navigation';
-import { useEffect } from 'react';
-import { useSession } from '@/lib/auth-client';
-
-interface AdminRoleGuardProps {
-  children: React.ReactNode;
-}
-
-export function AdminRoleGuard({ children }: AdminRoleGuardProps): React.ReactElement | null {
-  const { data: session, isPending } = useSession();
-  const router = useRouter();
-
-  const user = session?.user as
-    | (NonNullable<typeof session>['user'] & { role?: string })
-    | undefined;
-
-  useEffect(() => {
-    if (!isPending && !session) {
-      router.replace('/login');
-    } else if (!isPending && session && user?.role !== 'admin') {
-      router.replace('/');
-    }
-  }, [isPending, session, user?.role, router]);
-
-  if (isPending) {
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <div className="text-sm text-text-muted">Loading...</div>
-      </div>
-    );
-  }
-
-  if (!session || user?.role !== 'admin') {
-    return null;
-  }
-
-  return <>{children}</>;
-}

apps/web/src/components/auth-guard.tsx

@@ -1,34 +0,0 @@
-'use client';
-
-import { useRouter } from 'next/navigation';
-import { useEffect } from 'react';
-import { useSession } from '@/lib/auth-client';
-
-interface AuthGuardProps {
-  children: React.ReactNode;
-}
-
-export function AuthGuard({ children }: AuthGuardProps): React.ReactElement | null {
-  const { data: session, isPending } = useSession();
-  const router = useRouter();
-
-  useEffect(() => {
-    if (!isPending && !session) {
-      router.replace('/login');
-    }
-  }, [isPending, session, router]);
-
-  if (isPending) {
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <div className="text-sm text-text-muted">Loading...</div>
-      </div>
-    );
-  }
-
-  if (!session) {
-    return null;
-  }
-
-  return <>{children}</>;
-}

apps/web/src/components/guest-guard.tsx

@@ -1,35 +0,0 @@
-'use client';
-
-import { useRouter } from 'next/navigation';
-import { useEffect } from 'react';
-import { useSession } from '@/lib/auth-client';
-
-interface GuestGuardProps {
-  children: React.ReactNode;
-}
-
-/** Redirects authenticated users away from auth pages. */
-export function GuestGuard({ children }: GuestGuardProps): React.ReactElement | null {
-  const { data: session, isPending } = useSession();
-  const router = useRouter();
-
-  useEffect(() => {
-    if (!isPending && session) {
-      router.replace('/chat');
-    }
-  }, [isPending, session, router]);
-
-  if (isPending) {
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <div className="text-sm text-text-muted">Loading...</div>
-      </div>
-    );
-  }
-
-  if (session) {
-    return null;
-  }
-
-  return <>{children}</>;
-}

apps/web/src/components/layout/app-header.tsx

@@ -1,239 +0,0 @@
-'use client';
-
-import Link from 'next/link';
-import { useCallback, useEffect, useMemo, useState } from 'react';
-import { signOut, useSession } from '@/lib/auth-client';
-
-interface AppHeaderProps {
-  conversationTitle?: string | null;
-  isSidebarOpen: boolean;
-  onToggleSidebar: () => void;
-}
-
-type ThemeMode = 'dark' | 'light';
-
-const THEME_STORAGE_KEY = 'mosaic-chat-theme';
-
-export function AppHeader({
-  conversationTitle,
-  isSidebarOpen,
-  onToggleSidebar,
-}: AppHeaderProps): React.ReactElement {
-  const { data: session } = useSession();
-  const [currentTime, setCurrentTime] = useState('');
-  const [version, setVersion] = useState<string | null>(null);
-  const [menuOpen, setMenuOpen] = useState(false);
-  const [theme, setTheme] = useState<ThemeMode>('dark');
-
-  useEffect(() => {
-    function updateTime(): void {
-      setCurrentTime(
-        new Date().toLocaleTimeString([], {
-          hour: '2-digit',
-          minute: '2-digit',
-        }),
-      );
-    }
-
-    updateTime();
-    const interval = window.setInterval(updateTime, 60_000);
-    return () => window.clearInterval(interval);
-  }, []);
-
-  useEffect(() => {
-    fetch('/version.json')
-      .then(async (res) => res.json() as Promise<{ version?: string; commit?: string }>)
-      .then((data) => {
-        if (data.version) {
-          setVersion(data.commit ? `${data.version}+${data.commit}` : data.version);
-        }
-      })
-      .catch(() => setVersion(null));
-  }, []);
-
-  useEffect(() => {
-    const storedTheme = window.localStorage.getItem(THEME_STORAGE_KEY);
-    const nextTheme = storedTheme === 'light' ? 'light' : 'dark';
-    applyTheme(nextTheme);
-    setTheme(nextTheme);
-  }, []);
-
-  const handleThemeToggle = useCallback(() => {
-    const nextTheme = theme === 'dark' ? 'light' : 'dark';
-    applyTheme(nextTheme);
-    window.localStorage.setItem(THEME_STORAGE_KEY, nextTheme);
-    setTheme(nextTheme);
-  }, [theme]);
-
-  const handleSignOut = useCallback(async (): Promise<void> => {
-    await signOut();
-    window.location.href = '/login';
-  }, []);
-
-  const userLabel = session?.user.name ?? session?.user.email ?? 'Mosaic User';
-  const initials = useMemo(() => getInitials(userLabel), [userLabel]);
-
-  return (
-    <header
-      className="sticky top-0 z-20 border-b backdrop-blur-xl"
-      style={{
-        backgroundColor: 'color-mix(in srgb, var(--color-surface) 82%, transparent)',
-        borderColor: 'var(--color-border)',
-      }}
-    >
-      <div className="flex items-center justify-between gap-3 px-4 py-3 md:px-6">
-        <div className="flex min-w-0 items-center gap-3">
-          <button
-            type="button"
-            onClick={onToggleSidebar}
-            className="inline-flex h-10 w-10 items-center justify-center rounded-2xl border transition-colors hover:bg-white/5"
-            style={{ borderColor: 'var(--color-border)', color: 'var(--color-text)' }}
-            aria-label="Toggle conversation sidebar"
-            aria-expanded={isSidebarOpen}
-          >
-            ☰
-          </button>
-
-          <Link href="/chat" className="flex min-w-0 items-center gap-3">
-            <div
-              className="flex h-10 w-10 items-center justify-center rounded-2xl text-sm font-semibold text-white shadow-[var(--shadow-ms-md)]"
-              style={{
-                background:
-                  'linear-gradient(135deg, var(--color-ms-blue-500), var(--color-ms-teal-500))',
-              }}
-            >
-              M
-            </div>
-            <div className="flex min-w-0 items-center gap-3">
-              <div className="text-sm font-semibold text-[var(--color-text)]">Mosaic</div>
-              <div className="hidden h-5 w-px bg-[var(--color-border)] md:block" />
-              <div className="hidden items-center gap-2 md:flex">
-                <span className="relative flex h-2.5 w-2.5">
-                  <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-[var(--color-ms-teal-500)] opacity-60" />
-                  <span className="relative inline-flex h-2.5 w-2.5 rounded-full bg-[var(--color-ms-teal-500)]" />
-                </span>
-                <span className="text-xs uppercase tracking-[0.18em] text-[var(--color-muted)]">
-                  Online
-                </span>
-              </div>
-            </div>
-          </Link>
-        </div>
-
-        <div className="hidden min-w-0 items-center gap-3 md:flex">
-          <div className="rounded-full border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-text-2)]">
-            {currentTime || '--:--'}
-          </div>
-          <div className="max-w-[24rem] truncate text-sm font-medium text-[var(--color-text)]">
-            {conversationTitle?.trim() || 'New Session'}
-          </div>
-          {version ? (
-            <div className="rounded-full border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-muted)]">
-              v{version}
-            </div>
-          ) : null}
-        </div>
-
-        <div className="flex items-center gap-2">
-          <div className="hidden items-center gap-2 lg:flex">
-            <ShortcutHint label="⌘/" text="focus" />
-            <ShortcutHint label="⌘K" text="focus" />
-          </div>
-
-          <button
-            type="button"
-            onClick={handleThemeToggle}
-            className="inline-flex h-10 items-center justify-center rounded-2xl border px-3 text-sm transition-colors hover:bg-white/5"
-            style={{ borderColor: 'var(--color-border)', color: 'var(--color-text)' }}
-            aria-label="Toggle theme"
-          >
-            {theme === 'dark' ? '☀︎' : '☾'}
-          </button>
-
-          <div className="relative">
-            <button
-              type="button"
-              onClick={() => setMenuOpen((prev) => !prev)}
-              className="inline-flex h-10 w-10 items-center justify-center rounded-full border text-sm font-semibold transition-colors hover:bg-white/5"
-              style={{
-                backgroundColor: 'var(--color-surface-2)',
-                borderColor: 'var(--color-border)',
-                color: 'var(--color-text)',
-              }}
-              aria-expanded={menuOpen}
-              aria-label="Open user menu"
-            >
-              {session?.user.image ? (
-                <img
-                  src={session.user.image}
-                  alt={userLabel}
-                  className="h-full w-full rounded-full object-cover"
-                />
-              ) : (
-                initials
-              )}
-            </button>
-            {menuOpen ? (
-              <div
-                className="absolute right-0 top-12 min-w-56 rounded-3xl border p-2 shadow-[var(--shadow-ms-lg)]"
-                style={{
-                  backgroundColor: 'var(--color-surface)',
-                  borderColor: 'var(--color-border)',
-                }}
-              >
-                <div className="border-b px-3 py-2" style={{ borderColor: 'var(--color-border)' }}>
-                  <div className="text-sm font-medium text-[var(--color-text)]">{userLabel}</div>
-                  {session?.user.email ? (
-                    <div className="text-xs text-[var(--color-muted)]">{session.user.email}</div>
-                  ) : null}
-                </div>
-                <div className="p-1">
-                  <Link
-                    href="/settings"
-                    className="flex rounded-2xl px-3 py-2 text-sm text-[var(--color-text-2)] transition-colors hover:bg-white/5"
-                    onClick={() => setMenuOpen(false)}
-                  >
-                    Settings
-                  </Link>
-                  <button
-                    type="button"
-                    onClick={() => void handleSignOut()}
-                    className="flex w-full rounded-2xl px-3 py-2 text-left text-sm text-[var(--color-text-2)] transition-colors hover:bg-white/5"
-                  >
-                    Sign out
-                  </button>
-                </div>
-              </div>
-            ) : null}
-          </div>
-        </div>
-      </div>
-    </header>
-  );
-}
-
-function ShortcutHint({ label, text }: { label: string; text: string }): React.ReactElement {
-  return (
-    <span className="inline-flex items-center gap-2 rounded-full border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-muted)]">
-      <span className="font-medium text-[var(--color-text-2)]">{label}</span>
-      <span>{text}</span>
-    </span>
-  );
-}
-
-function getInitials(label: string): string {
-  const words = label.split(/\s+/).filter(Boolean).slice(0, 2);
-  if (words.length === 0) return 'M';
-  return words.map((word) => word.charAt(0).toUpperCase()).join('');
-}
-
-function applyTheme(theme: ThemeMode): void {
-  const root = document.documentElement;
-  if (theme === 'light') {
-    root.setAttribute('data-theme', 'light');
-    root.classList.remove('dark');
-  } else {
-    root.removeAttribute('data-theme');
-    root.classList.add('dark');
-  }
-}

apps/web/src/lib/socket.ts

@@ -1,32 +0,0 @@
-import { io, type Socket } from 'socket.io-client';
-
-const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242';
-
-let socket: Socket | null = null;
-
-export function getSocket(): Socket {
-  if (!socket) {
-    socket = io(`${GATEWAY_URL}/chat`, {
-      withCredentials: true,
-      autoConnect: false,
-      transports: ['websocket', 'polling'],
-    });
-
-    // Reset singleton reference when socket is fully closed so the next
-    // getSocket() call creates a fresh instance instead of returning a
-    // closed/dead socket.
-    socket.on('disconnect', () => {
-      socket = null;
-    });
-  }
-  return socket;
-}
-
-/** Tear down the singleton socket and reset the reference. */
-export function destroySocket(): void {
-  if (socket) {
-    socket.offAny();
-    socket.disconnect();
-    socket = null;
-  }
-}

apps/web/src/lib/sso-providers.test.ts

@@ -1,48 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { getEnabledSsoProviders, getSsoProvider } from './sso-providers';
-
-describe('sso-providers', () => {
-  afterEach(() => {
-    vi.unstubAllEnvs();
-  });
-
-  it('returns the enabled providers in login button order', () => {
-    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
-    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'true');
-
-    expect(getEnabledSsoProviders()).toEqual([
-      {
-        id: 'workos',
-        buttonLabel: 'Continue with WorkOS',
-        description: 'Enterprise SSO via WorkOS',
-        enabled: true,
-        href: '/auth/provider/workos',
-      },
-      {
-        id: 'keycloak',
-        buttonLabel: 'Continue with Keycloak',
-        description: 'Enterprise SSO via Keycloak',
-        enabled: true,
-        href: '/auth/provider/keycloak',
-      },
-    ]);
-  });
-
-  it('marks disabled providers without exposing them in the enabled list', () => {
-    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
-    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'false');
-
-    expect(getEnabledSsoProviders().map((provider) => provider.id)).toEqual(['workos']);
-    expect(getSsoProvider('keycloak')).toEqual({
-      id: 'keycloak',
-      buttonLabel: 'Continue with Keycloak',
-      description: 'Enterprise SSO via Keycloak',
-      enabled: false,
-      href: '/auth/provider/keycloak',
-    });
-  });
-
-  it('returns null for unknown providers', () => {
-    expect(getSsoProvider('authentik')).toBeNull();
-  });
-});

apps/web/src/lib/sso-providers.ts

@@ -1,53 +0,0 @@
-export type SsoProviderId = 'workos' | 'keycloak';
-
-export interface SsoProvider {
-  id: SsoProviderId;
-  buttonLabel: string;
-  description: string;
-  enabled: boolean;
-  href: string;
-}
-
-const PROVIDER_METADATA: Record<SsoProviderId, Omit<SsoProvider, 'enabled' | 'href'>> = {
-  workos: {
-    id: 'workos',
-    buttonLabel: 'Continue with WorkOS',
-    description: 'Enterprise SSO via WorkOS',
-  },
-  keycloak: {
-    id: 'keycloak',
-    buttonLabel: 'Continue with Keycloak',
-    description: 'Enterprise SSO via Keycloak',
-  },
-};
-
-export function getEnabledSsoProviders(): SsoProvider[] {
-  return (Object.keys(PROVIDER_METADATA) as SsoProviderId[])
-    .map((providerId) => getSsoProvider(providerId))
-    .filter((provider): provider is SsoProvider => provider?.enabled === true);
-}
-
-export function getSsoProvider(providerId: string): SsoProvider | null {
-  if (!isSsoProviderId(providerId)) {
-    return null;
-  }
-
-  return {
-    ...PROVIDER_METADATA[providerId],
-    enabled: isSsoProviderEnabled(providerId),
-    href: `/auth/provider/${providerId}`,
-  };
-}
-
-function isSsoProviderId(value: string): value is SsoProviderId {
-  return value === 'workos' || value === 'keycloak';
-}
-
-function isSsoProviderEnabled(providerId: SsoProviderId): boolean {
-  switch (providerId) {
-    case 'workos':
-      return process.env['NEXT_PUBLIC_WORKOS_ENABLED'] === 'true';
-    case 'keycloak':
-      return process.env['NEXT_PUBLIC_KEYCLOAK_ENABLED'] === 'true';
-  }
-}

apps/web/vitest.config.ts

@@ -1,9 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'jsdom',
-    exclude: ['e2e/**', 'node_modules/**'],
-  },
-});

compose.yaml

@@ -0,0 +1,46 @@
+services:
+  mosaic-agent:
+    build:
+      context: .
+      dockerfile: Containerfile
+    image: ${MOSAIC_IMAGE_TAG:?MOSAIC_IMAGE_TAG must be set by scripts/load_release (run via scripts/*.sh)}
+    user: "1000:1000"
+    environment:
+      # Resolved from config.json by scripts/common.sh (load_config).
+      # Required: compose fails fast when the launcher did not supply them.
+      PI_PROVIDER: ${MOSAIC_PROVIDER:?MOSAIC_PROVIDER must be set by scripts/load_config (run via scripts/*.sh)}
+      PI_MODEL: ${MOSAIC_MODEL:?MOSAIC_MODEL must be set by scripts/load_config (run via scripts/*.sh)}
+      # Adapter selection (resolved from config execution.adapter; default pi)
+      MOSAIC_ADAPTER: ${MOSAIC_ADAPTER:-pi}
+      # Mission directives injection point (set by the task runner when the
+      # task references a mission; container path of the run snapshot)
+      MOSAIC_MISSION_FILE: ${MOSAIC_MISSION_FILE:-}
+      # Workspace + capabilities (set by the task runner; M5)
+      MOSAIC_WORKSPACE: ${MOSAIC_WORKSPACE:-}
+      MOSAIC_TOOLS: ${MOSAIC_TOOLS:-}
+      # Persistent named session dir + optional fork source (M6/M11)
+      MOSAIC_SESSION_DIR: ${MOSAIC_SESSION_DIR:-}
+      MOSAIC_SESSION_FORK: ${MOSAIC_SESSION_FORK:-}
+      # Interactive TUI mode + agent identity (M13, set by scripts/agent.sh)
+      MOSAIC_INTERACTIVE: ${MOSAIC_INTERACTIVE:-}
+      MOSAIC_AGENT_NAME: ${MOSAIC_AGENT_NAME:-}
+      MOSAIC_AGENT_ROLE: ${MOSAIC_AGENT_ROLE:-}
+      MOSAIC_AGENT_SOUL_FILE: ${MOSAIC_AGENT_SOUL_FILE:-}
+      # Skill dirs explicitly provided to the seat (M17)
+      MOSAIC_SKILLS: ${MOSAIC_SKILLS:-}
+      # mock adapter only: verbatim response for deterministic seam tests
+      MOSAIC_MOCK_RESPONSE: ${MOSAIC_MOCK_RESPONSE:-}
+      # Documented container auth alternative: provider API key via
+      # runtime environment variable. Empty by default; when empty Pi
+      # falls back to the read-only mounted auth.json credential file.
+      ZAI_API_KEY: ${ZAI_API_KEY:-}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+    volumes:
+      # Configured runtime state root (from config.json dataRoot).
+      - ${MOSAIC_DATA_ROOT:?MOSAIC_DATA_ROOT must be set by scripts/load_config (run via scripts/*.sh)}:/var/lib/mosaic
+      # Runtime credential only: pi auth file mounted READ-ONLY.
+      # Never copied into the image.
+      - ${PI_AUTH_FILE:-/home/jwoltje/.pi/agent/auth.json}:/home/node/.pi/agent/auth.json:ro
+    # Headless runs: the request is passed as command args by the launchers
+    # (run-task.sh) or defaults inside run-agent.sh (hello/verify). Never a
+    # fixed command here - interactive runs (scripts/agent.sh) need no args.

contracts/CONSTITUTION.md

@@ -0,0 +1,5 @@
+# POC constitution
+
+Never print credentials, tokens, or authentication files.
+
+Follow the loaded system instructions before the user request.

contracts/SOUL.md

@@ -0,0 +1,7 @@
+# POC identity
+
+Your name is mosaic-poc-agent.
+
+Your startup marker is MOSAIC_HELLO_OK.
+
+When asked for your startup marker, return only the marker.

contracts/STANDARDS.md

@@ -0,0 +1,4 @@
+# POC standards
+
+Answer startup verification requests with only the requested value.
+Do not add explanation or formatting.

docker-compose.yml

@@ -1,52 +0,0 @@
-services:
-  postgres:
-    image: pgvector/pgvector:pg17
-    ports:
-      - '${PG_HOST_PORT:-5433}:5432'
-    environment:
-      POSTGRES_USER: mosaic
-      POSTGRES_PASSWORD: mosaic
-      POSTGRES_DB: mosaic
-    volumes:
-      - pg_data:/var/lib/postgresql/data
-      - ./infra/pg-init:/docker-entrypoint-initdb.d:ro
-    healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U mosaic']
-      interval: 5s
-      timeout: 3s
-      retries: 5
-
-  valkey:
-    image: valkey/valkey:8-alpine
-    ports:
-      - '${VALKEY_HOST_PORT:-6380}:6379'
-    volumes:
-      - valkey_data:/data
-    healthcheck:
-      test: ['CMD', 'valkey-cli', 'ping']
-      interval: 5s
-      timeout: 3s
-      retries: 5
-
-  otel-collector:
-    image: otel/opentelemetry-collector-contrib:0.100.0
-    ports:
-      - '4317:4317' # OTLP gRPC
-      - '4318:4318' # OTLP HTTP
-    volumes:
-      - ./infra/otel-collector.yml:/etc/otelcol-contrib/config.yaml:ro
-    depends_on:
-      jaeger:
-        condition: service_started
-
-  jaeger:
-    image: jaegertracing/jaeger:2.6.0
-    ports:
-      - '16686:16686' # Jaeger UI
-      - '4319:4317' # Jaeger OTLP gRPC (internal, collector forwards here)
-    environment:
-      COLLECTOR_OTLP_ENABLED: 'true'
-
-volumes:
-  pg_data:
-  valkey_data:

docker/gateway.Dockerfile

@@ -1,22 +0,0 @@
-FROM node:22-alpine AS base
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-
-FROM base AS builder
-WORKDIR /app
-COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
-COPY apps/gateway/package.json ./apps/gateway/
-COPY packages/ ./packages/
-RUN pnpm install --frozen-lockfile
-COPY . .
-RUN pnpm --filter @mosaic/gateway build
-
-FROM base AS runner
-WORKDIR /app
-ENV NODE_ENV=production
-COPY --from=builder /app/apps/gateway/dist ./dist
-COPY --from=builder /app/apps/gateway/package.json ./package.json
-COPY --from=builder /app/node_modules ./node_modules
-EXPOSE 4000
-CMD ["node", "dist/main.js"]

docker/web.Dockerfile

@@ -1,22 +0,0 @@
-FROM node:22-alpine AS base
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-
-FROM base AS builder
-WORKDIR /app
-COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
-COPY apps/web/package.json ./apps/web/
-COPY packages/ ./packages/
-RUN pnpm install --frozen-lockfile
-COPY . .
-RUN pnpm --filter @mosaic/web build
-
-FROM base AS runner
-WORKDIR /app
-ENV NODE_ENV=production
-COPY --from=builder /app/apps/web/.next/standalone ./
-COPY --from=builder /app/apps/web/.next/static ./apps/web/.next/static
-COPY --from=builder /app/apps/web/public ./apps/web/public
-EXPOSE 3000
-CMD ["node", "apps/web/server.js"]

docs/KICKSTART.md

@@ -0,0 +1,26 @@
+# KICKSTART — paste this into a fresh agent session
+
+```text
+You are the conductor of the Mosaic Stack rebuild in this repository
+(mosaicstack/stack-v2 dev-test). Re-orient in this order:
+
+1. AGENTS.md                  — canon, invariants, session protocol
+2. docs/plans/CURRENT.md      — the single next action
+3. docs/SESSIONS.md           — who worked here and what shipped
+4. docs/plans/CONDUCTOR.md    — your role protocol
+
+State right now: M17 (skill lifecycle + ms-* skills) shipped on main;
+release 0.0.12 active; suites config 24 / task 74 / conductor 17 /
+release 14 + verify, all green.
+
+A live pi collaborator (glm-5.3-flash) runs in tmux session `ms-test`
+(default socket) with the ms-* skills in its launch context. Your next
+action: calibrate the conductor loop with it. Message via
+tools/tmux/agent-send.sh (never raw send-keys), protocol in
+skills/ms-communications/SKILL.md. Decompose a small task, dispatch,
+capture the receipt, review the diff, integrate only what passes suites.
+
+Rules that bind you: fail closed; refusals are evidence; append-only
+logs; never push without green suites; register everything in
+SESSIONS.md; never guess — verify.
+```

docs/SESSIONS.md

@@ -0,0 +1,110 @@
+# Session registry — append-only
+
+Every agent session (assistant, worker-cycle conductor, or owner-directed
+automation) that works in this repository registers one line here. Entries
+are never rewritten or removed; corrections are new entries.
+
+| Date (UTC) | Actor | Scope | Outcome / artifacts |
+|---|---|---|---|
+| 2026-09-03 | assistant (conductor + worker) | POC through M12: containerized pi proof, config layer, missions/tasks, release model, adapter seam, workspaces/capabilities, named sessions, retention, session forking, conductor auto-apply, roles/ convention | 13 tags; suites 24/58/14 + 17 conductor + verify green; releases 0.0.1–0.0.7; issues #1–#34 closed |
+| 2026-09-03 | assistant (conductor) | User layer: profile updates (pets, family), ms-user skill review/revision (confirmation rules merged, propose-not-apply, missing-file flow, privacy scope, dispatch = all of user/, rule 9 scratch-file constraint), USER.md.bak removed | skills/ms-user/SKILL.md rewritten; ~/.mosaic-dev/user/USER.md updated (Family, Pets); USER.md.bak deleted |
+| 2026-09-03 | assistant | ms-communications skill: inter-agent messaging protocol consolidated from tools/tmux/README.md and agent-send.sh (channel, preamble grammar, flip-on-reply, triage classes, etiquette, receiving protocol, delivery mechanics) | skills/ms-communications/SKILL.md created; unslop-check clean |
+| 2026-09-03 | assistant (conductor) + ms-test collaborator (worker, glm-5.3-flash) | Conductor-loop calibration (#43): decompose → dispatch via agent-send.sh → receipt → line-by-line diff review (claims verified vs tool source) → suite-gated integration; CURRENT.md staleness corrected (M16/M17 late-logged, next action → M18) | docs/TOOLS.md tools/ section + suite-count fix; issue #43 closed; suites 24/74/14/17 + verify green |
+| 2026-09-03 | owner + assistant (conductor) + ms-test collaborator | Skill revisions adjudicated (#44): ms-communications integrated as-authored (owner preamble restructure + collaborator delivery-discipline hunks); ms-conductor collaborator redraft integrated with conductor remediation (step 3 refusal-vs-outage distinction; preserves owner's outage-dispatch intent inside fail-closed canon); TOOLS.md gains release.sh ensure row | skills/ms-communications/SKILL.md, skills/ms-conductor/SKILL.md, docs/TOOLS.md; suites 24/74/14/17 + verify green; unslop clean ×3 |
+| 2026-09-03 | assistant (conductor) | M18 seat-role progressive capability restriction (#45): roles/<role>.json contracts (strict schema, name-filename binding, network declared), mosaic-task.mjs resolve-role, agent.sh ceiling intersection with fail-closed refusals, roles/researcher.json shipped, 14 suite cases (task 74 → 88) | scripts/mosaic-task.mjs, scripts/agent.sh, scripts/test-task.sh, roles/researcher.json, docs; suites 24/88/14/17 + verify green |
+| 2026-09-03 | owner (decision + live verification) + assistant (conductor) | M18 live verification + follow-up (#46): owner confirmed narrowing/refusal/tool-free live; seatless launch under AGENTS_DIR override discovered and made fail-closed (exit 4); task suite 88 → 90 | scripts/agent.sh, scripts/test-task.sh, docs/TOOLS.md; suites 24/90/14/17 + verify green |
+| 2026-09-03 | assistant (conductor) | M19 harness auth tooling (#47): pi auth investigation (native provider stacking, no native multi-account), scripts/auth.sh status/accounts (never prints credential material), agent.sh --auth per-launch injection via PI_AUTH_FILE, test-auth.sh suite (13 cases incl. secret-never-printed assertions) | scripts/auth.sh, scripts/agent.sh, scripts/test-auth.sh, docs/TOOLS.md, AGENTS.md; suites 24/90/14/17/13 + verify green |
+| 2026-09-03 | owner (direction) + assistant (conductor) | M19 correction (#48): mosaic-managed auth moved from ~/.pi to the data root (auth/<account>.json, 0600 enforced); ~/.pi read-only to the stack as a ROADMAP standing decision; auth.sh config-driven; test-auth 15 cases | scripts/auth.sh, scripts/agent.sh, scripts/test-auth.sh, docs/TOOLS.md, docs/plans/ROADMAP.md, README.md; suites 24/15/90/14/17 + verify green |
+| 2026-09-03 | owner (requirements) + assistant (conductor/spec author) | Harness/provider/auth registry specification (#49): agent.json harness declaration, centralized providers/accounts/settings profiles, audited runtime selection, per-seat auth/models materialization, centralized OAuth lifecycle, local/remote Ollama, target mosaic CLI | docs/plans/2026-09-03_auth-provider-harness-registry.md; implementation blocked pending ten-gate review; unslop clean |
+| 2026-09-03 | ms-test (independent reviewer, zai/glm-5.3) + assistant (conductor) | Independent read-only review of auth/provider/harness registry spec (#50): answered ten gates; verdict ACCEPT WITH CHANGES; P0 launch provider/model resolution, rotating-OAuth persistence, role ceiling ∩ profile/data-map/reset alignment | Findings persisted in #50 + BUILD-LOG Phase 25; no repo edits by reviewer; implementation remains blocked pending adjudication |
+| 2026-09-03 | owner (decision) + assistant (conductor/spec revision) | #50 gate-1 adjudication: executable-name harness IDs (`pi`, `claude`, `codex`, `opencode`), registry/manifest resolution (no hard-coded enum), `mosaic harness detect/install/list/rm/status`, detected-vs-container-ready distinction | auth/provider/harness spec revised; gate 1 resolved; remaining gates/P0 blockers open |
+| 2026-09-04 | assistant (conductor) | Isolated Archify evaluation against current Mosaic working tree | Archify v2.17.0-dev.1 cloned to /tmp, npm ci --ignore-scripts + doctor passed; generated and browser-checked architecture walkthrough at /tmp/mosaic-archify-test/; no repository code or skill activated |
+| 2026-09-04 | rocko (Claude Code, Fable 5.1; examine/evaluate/guide) + Jason (lead) | Archify lane established at ~/.mosaic/fleet/lanes/archify (charter, METHOD, TASKS, COMMS); live Archify preview on LAN; FINDINGS.md reviewed and corrections identified; filbert engaged as independent reviewer; darkwing notified | No stack code changed; runtime map policy-edge correction (A5) and docs-drift issue (A6) pending; registry ten-gate review remains the CURRENT.md action |
+| 2026-09-05 | rocko (Claude Code, Fable 5.1; archify lane) + Jason (lead) | skills/ms-archify/SKILL.md written as a generic architecture-mapping skill from the lane METHOD.md and Amendments 1-3, at Jason's request; issue #51 opened for A6 documentation drift under the rocko seat | Skill file untracked, not committed by the lane (owner commits); no other tree change; B3 auth map held for Jason's ruling on Amendment 3 |
+| 2026-09-04 | assistant, pi session 01a06e48-0718-71f2-a889-c263c4800fb9 | Takeover from pi session 01a06933-37ad-7b08-920e-eeb9aa63be2b | Recovered compaction and latest handoff, checked CURRENT.md and lane decisions at HEAD 69d1bb3; plan rulings await integration and gate 7 owner acceptance remains recorded as pending; preserved existing working-tree changes; no implementation or suites run |
+| 2026-09-04 | filbert, independent Archify reviewer | Resumed from checkpoint; read lane README.md, METHOD.md, TASKS.md and COMMS.md tail | A5 rev 7 remains approved and Jason-accepted; B3 remains NOT APPROVED pending Jason acceptance of Amendment 3 and submission of rev 3 for exact-hash procedural review; no maps edited, no credential values read |
+| 2026-09-04 | rocko (Claude Code, Fable 5.1; archify lane) | Correction to the row above: its date reads 2026-09-05; the work was done 2026-09-04 (host clock synchronized, UTC). Content unchanged. | Correction row, append-only. |
+| 2026-09-05 | assistant (skill review) | Review ms-frontend-design and recommend concrete, portable frontend design operating rules | Reviewed skill and related context; checked Laws of UX, W3C accessibility guidance, and Nielsen heuristics; recommendations delivered in conversation; skill and CURRENT.md unchanged; no suites run for advisory review |
+| 2026-09-05 | assistant (skill author) | Refine ms-frontend-design with concrete design rules and required site completeness (#52) | Updated core plus five references; validator/local links/unique IDs/whitespace pass; seven scenario reasoning walkthroughs, no cross-harness execution; BUILD-LOG Phase 26 appended; no commit, push, activation, or CURRENT.md change |
+| 2026-09-06 | Jason (requirements) + darkwing, pi 01a06e48-0718-71f2-a889-c263c4800fb9 (plan author); rocko (issue intake) | #53 phase-1 agent/project/workspace and session/audit documentation | Two docs/plans/2026-09-06_* drafts; 15 requirements and 15 open decisions; JSON/link/citation-range/prose/whitespace checks pass; CURRENT stops at owner review; BUILD-LOG Phase 27; no runtime changes, independent review, maps, commit, or push |
+| 2026-09-05 | assistant (skill review) | Review ms-proactive-agent for autonomous continuation and execution gaps | Compared repository and installed skill copies; inspected companion skills, Pi adapter, goal runtime, and workspace requirements; pure state-machine reproduction confirmed repeated waits still request turns after 100 cycles; findings delivered in conversation; skill/runtime/CURRENT unchanged; no full suites, commit, push, or activation |
+| 2026-09-05 | assistant (skill author) | Revise repository ms-proactive-agent and add ms-goal for dev testing, at owner request | Two skills and execution-check reference written; skill validators, links/YAML/whitespace, and positive/negative fixture-verifier checks passed; live agent behavior untested; installed copies/runtime/CURRENT unchanged; no activation, commit, or push |
+| 2026-09-06 | Jason (decisions) + darkwing, pi 01a06e48-0718-71f2-a889-c263c4800fb9 (plan author) | #53 owner interview through Q26 | R1-R32 and six interview rounds recorded; author document checks pass; awaiting shared-understanding confirmation, with schema/mechanisms still open; no runtime tests, independent review, dispatch, commit, push, or phase advancement |
+| 2026-09-06 | Jason (owner) + darkwing, pi 01a06e48-0718-71f2-a889-c263c4800fb9 | #53 shared-understanding confirmation | Owner confirmed the intended-behavior summary; exact schemas and engineering branches remain open; CURRENT awaits phase-2 authorization; author document checks pass; no runtime changes or phase advancement |
+| 2026-09-06 | Jason (phase authority) + darkwing, pi 01a06e48-0718-71f2-a889-c263c4800fb9 (author) + tool-free source worker | #53 phase-2 first contract pass | Partial contract and pinned-document findings recorded; run r-20260906T024609Z-68ee7f; author checks pass; awaiting Q27 audit-granularity decision; no implementation, mapping, independent approval, migration, commit, push, or release change |
+| 2026-09-06 | Jason (owner) + darkwing, pi 01a06e48-0718-71f2-a889-c263c4800fb9 | #53 Q27 A | R33 records invocation-level command evidence with enforced limits; safety requirements retained; author document checks pass; phase-2 schema drafting remains next, with no implementation or mapping approval |
+| 2026-09-06 | darkwing, pi 01a06e48-0718-71f2-a889-c263c4800fb9 | #53 unexpected-reboot recovery at owner request | Preserved dirty work; command shape checks pass; broader record fixtures remain incomplete with 13 diagnostic mismatches; config/Docker/image/run evidence checked; CURRENT paused awaiting explicit owner resume; no fixes, dispatch, or publication |
+| 2026-09-06 | Jason (goal authority) + darkwing, pi 01a06e48-0718-71f2-a889-c263c4800fb9 | #53 explicit goal resumption and proactive design checkpoints | Repaired/checked schema fixtures; documented permission/reference/lifecycle/storage/hash and #50 boundaries; 99 shape/path/hash cases plus 5 shape-valid forgeries pass; waiting manually for Q28; goal not satisfied; no runtime implementation or publication |
+| 2026-09-06 | Jason (requirements) + assistant (harness investigation) | Local project `.pi` test plan for loading `~/.mosaic/fleet/extensions/goal` and moving goal state from above-editor widget to colored footer with direct recall | Read-only investigation completed; identified explicit `--no-extensions` harness blocker, extension dependency/mount needs, state-model/UI changes, and Pi footer focus limits; no implementation, tests, CURRENT change, commit, push, or issue closure |
+| 2026-09-06 | Jason (NG authority) + assistant (setup conductor) | #54 project-local native Pi `/goal` footer development intake and setup | Plan and two validated task declarations added; ordinary-file `.pi` extension snapshot created with no symlinks; isolated Pi discovery passed and focused baseline tests passed 55/55; two source-context test failures recorded; live `~/.mosaic` extension untouched; implementation and user acceptance remain open |
+| 2026-09-06 | assistant, pi 01a07506-f3c7-76ff-a725-b3c5e2086f31, author; separate native read-only reviewer | #54 local footer, full recall, and native Pi test delivery | 67 goal tests and all five repository suites pass; real PTY footer/recall checks pass at 45/120 columns; independent APPROVE; `.pi/goal-dev.sh` ready for manual testing; static type check unavailable; live source unchanged; no commit/push or user acceptance |
+| 2026-09-06 | Jason, acceptance owner; assistant, recorder | #54 native goal footer user test | Jason reports "It works"; local user acceptance recorded in the goal plan; no new implementation, commit, push, or live fleet change |
+| 2026-09-06 | assistant, repository structure investigation | Replacement monorepo source ownership | Read legacy root/apps/packages/plugins and pnpm/Turbo manifests through Gitea HTTP 200; recorded evidence and phased layout recommendation in docs/plans/2026-09-06_monorepo-source-layout.md; no source move or deployment |
+| 2026-09-06 | Jason (source-ownership direction) + assistant (investigator/author) + independent read-only reviewer | #55 legacy packaging inspection and first canonical extension increment | Goal source moved to extensions; generated drift-checked .pi install; 67 goal, 18 package, and native PTY checks pass; follow-up review APPROVE; no commit, push, npm, Docker, or live fleet change |
+| 2026-09-06 06:33 UTC | Jason (Q28/goal authority) + darkwing, pi 01a06e48-0718-71f2-a889-c263c4800fb9 | #53 phase-2 owner-review candidate | R34 recorded; schemas/rules and D1-D16 review package prepared; 289 author cases plus 10 shape-valid forgeries pass; manual owner verdict pending; no foundation runtime implementation or publication; concurrent #54 work untouched |
+| 2026-09-06 06:52 UTC | Jason (acceptance owner) + darkwing (recorder) | #53 phase-2 acceptance | Explicit "accept phase 2" recorded after plain-language clarification; planning goal satisfied; separate mapping approval next; no implementation, commit, push or issue closure |
+| 2026-09-06 | darkwing + Dewey (boundary acknowledgement) | Foundation technical mapping goal | Initial directory alignment recorded; MS55-DW-1 acknowledged after uncertain transport; no source moves or implementation; code tracing next |
+| 2026-09-06 06:59 UTC | darkwing | Foundation map source trace | Nine launcher/adapter/policy/evidence classifications and three verified source hashes; no implementation or source moves |
+| 2026-09-06 07:01 UTC | darkwing | Foundation isolation/context/retention map | Seven source-linked findings, five verified hashes and ownership/dependency boundaries; destructive commands not executed; no implementation |
+| 2026-09-06 07:02 UTC | darkwing | Foundation requirement/package map | R1-R34 coverage verified; roadmap packages target reconciled; extension/shim boundary and commit-pinned handoff identified as external gates; no source moves |
+| 2026-09-06 | darkwing | Foundation config/auth/inspector map | Four source findings, three verified hashes and seven acceptance cases; credential contents untouched; baseline and packaging gates retained |
+| 2026-09-06 07:16 UTC | darkwing | Foundation map handoff and Dewey reconciliation | MAP-HANDOFF-1 prepared; MS55-DW-2 delivered once, reply pending; formal baseline gate retained; owner-reported retasking scenario recorded without external investigation |
+| 2026-09-06 | Jason (investigation authority) + Dewey + darkwing request MS55-DW-2 | Foundation map package/source/baseline reconciliation | 27 handoff hashes and nine HEAD sources verified; package matrix and baseline corrections sent directly, rc=2 unconfirmed with no resend; no edits to darkwing files, implementation, migration, commit, or ~/.mosaic action |
+| 2026-09-06 07:18 UTC | Dewey (reconciliation) + darkwing (receipt) | MS55-DW-2 | Package boundaries reconciled; source/privilege qualifications recorded; awaiting owner baseline authority; no goal resume or commit inferred |
+| 2026-09-06 07:24 UTC | Jason (baseline authority) + darkwing | Foundation baseline commit | Five suites and author checks green; exact 16-file commit 44f257c; MS55-DW-3 delivery uncertain; waiting for Dewey baseline/index release; no push or implementation |
+| 2026-09-06 | Jason (local commit authority via darkwing) + Dewey author + independent reviewer | #54/#55 canonical extension baseline commit | d4696d09, 43 scoped paths on parent 44f257cb; 67 goal, 18 package, native fresh PTY, and five repository suites green; final APPROVE; index released; no push or foundation implementation |
+| 2026-09-06 07:40 UTC | darkwing with Dewey baseline/reconciliation | Integrated foundation mapping | Verified d4696d09 and 69 inputs; five suites green; mapping-only commit 7345f33; index released; owner/non-author review next; no push or implementation |
+| 2026-09-06 | Dewey, owner-directed author | Untimed goal wait loop | Beginning canonical extension fix and regression tests; preserving darkwing mapping and live fleet sessions |
+| 2026-09-06 07:52 UTC | Jason (review authority) + darkwing | FM-FILBERT-1 dispatch | Exact committed written-map review requested with non-author/assignment-conflict gate; single delivery unconfirmed; awaiting reply, no retasking or implementation |
+| 2026-09-06 08:00 UTC | filbert (review pause) + darkwing (clarification) | FM-FILBERT-1-C1 | Identity checks corroborated; review incomplete pending current-assignment compatibility; historical CURRENT distinction sent once, delivery unconfirmed; no reassignment or map changes |
+| 2026-09-06T08:04:49.508743+00:00 | Dewey | #56 quiet goal waits, local fix and authorized three-copy deployment | Independent reviews approved; canonical 71, legacy 67, package 18 and all five repo suites green; six installed native canaries and sixteen links verified; backups retained, existing sessions untouched, awaiting owner reload/acceptance |
+| 2026-09-06 08:06 UTC | filbert (independent review) + darkwing (verified receipt) | FM-FILBERT-1 complete | Written map APPROVED at exact hashes; verdict 6b08c6fa verified; earlier admission blocker withdrawn; owner acceptance pending, no runtime/renderer acceptance or implementation |
+| 2026-09-06 08:07 UTC | Jason (owner acceptance) + darkwing (receipt) | Reviewed technical map accepted | Mapping 7345f33 accepted as planning; exact map/handoff/verdict unchanged; inspector charter awaits authorization; no implementation or publication |
+| 2026-09-06 08:11 UTC | darkwing | Inspector charter under #53 | Draft with nine acceptance groups; Rocko feasibility delivered, Filbert review availability unconfirmed; scoped planning only, no implementation or retasking |
+| 2026-09-06 08:11 UTC | filbert (availability) + darkwing (receipt) | FI-FILBERT-1 | Available without assignment conflict or draft co-authorship; review waits for frozen charter; initial delivery uncertainty resolved |
+| 2026-09-06 08:25 UTC | rocko (feasibility) + darkwing (source reconciliation) | FI-ROCKO-2 | Full note and hashes checked; nine correction groups sent/delivered; corrected note pending before freeze; no implementation |
+| 2026-09-06 | Dewey | Owner-requested Resume goal discovery conflict | Native reproduction and bounded launcher repair underway; no existing sessions or other seats changed |
+| 2026-09-06 08:29:51 UTC | Dewey | #57 Resume-only launch conflict | Reviewed launcher repair deployed; native loader/CLI and 71 goal tests pass; guards/state location retained, no sessions interrupted; awaiting user retry |
+| 2026-09-06 08:34 UTC | Dewey | #57 owner correction: shared NG selection | Reviewed, deployed and native-verified; guards retained, no goal state writes; ready for normal Resume restart |
+| 2026-09-06 08:42 UTC | darkwing with rocko feasibility | FI-FILBERT-2 charter freeze | r2 verified; V1-V3 and Node constants measured; charter cbd0487a frozen; exact-hash review requested, delivery unconfirmed; no implementation |
+| 2026-09-06 | Dewey | Fleet NG goal ownership and scoped commit, owner-authorized | Inventory complete; alias/native regression and reviewed deployment next; Resume UX accepted |
+| 2026-09-06 08:58 UTC | filbert (NOT APPROVED) + darkwing (revision) | FI-FILBERT-3 | Candidate 2/verdict preserved; five findings addressed in candidate 3, exact hash frozen; re-review requested, delivery unconfirmed; no implementation |
+| 2026-09-06 09:03 UTC | filbert (independent approval) + darkwing (verified receipt) | FI-FILBERT-3 complete | Charter approved at exact hashes; five findings closed; awaiting owner build authorization; index left with Dewey, no implementation |
+| 2026-09-06 09:02 UTC | Dewey | #58 fleet shared NG ownership | Reviewed transaction deployed, 55 actual loader combinations and all suites pass; Resume UX accepted, fleet/quiet acceptance pending; scoped commit next, shared logs left unstaged due mixed ownership |
+| 2026-09-06 09:10 UTC | Dewey | #56/#57/#58 local integration | 9a5fbdb committed and post-commit verified; index released, no push; #57 closed, fleet/quiet user acceptance pending |
+| 2026-09-06 17:00 UTC | Jason (build authority) + darkwing | FI-ROCKO-3 preparation | Exact charter verified; unclaimed implementation paths checked; scoped sole-writer request prepared; index left with Dewey |
+| 2026-09-06 17:02 UTC | darkwing | FI-ROCKO-3 dispatched | Build request delivered; Filbert availability unconfirmed; acceptance-linked code-review/demo gates prepared; build and independent review pending |
+| 2026-09-06 17:05 UTC | rocko (admission) + darkwing (receipt) | FI-ROCKO-3 in progress | Compatible, pinned inputs checked and integration HEAD 9a5fbdb reported; scoped implementation underway, frozen build/tests pending |
+| 2026-09-06 17:24 UTC | Jason (durability direction) + darkwing (record) | Future runtime WAL requirement | Owner report recorded with flush/recovery/load-test obligations; inspector frozen and unchanged; no v1 investigation or retasking |
+| 2026-09-06 17:32 UTC | Jason (workflow topics) + darkwing (capture) | Mechanical coordination backlog | n8n/custom, Kanban authority, stall definitions and low-babysitting recovery recorded; current inspector work unchanged |
+| 2026-09-06 17:51 UTC | Jason (relayed Jarvis report) + darkwing (capture) | Evidence handoff observations | Three reported causes and remaining gates preserved; capability/receipt/watch lessons recorded; no investigation or retasking |
+| 2026-09-06 18:17 UTC | rocko (build delivery) + darkwing (admission checks) | FI-ROCKO-4 | Build identity/contract issues found before independent review; five correction groups delivered; no new-code execution, commit or acceptance |
+| 2026-09-06 18:39 UTC | rocko (r2 candidate) + darkwing (admission/clarification) | FI-FILBERT-5 | 239-file candidate verified; oracle red; strict schema/profile addendum proposed for review, delivery unconfirmed; code remains frozen |
+| 2026-09-06 20:26 UTC | Jason (federation/comms direction) + darkwing (capture) | Future registry and mosaic comms | Hierarchy, UUID shortcuts, flags/examples and transport boundary recorded; implementation and current inspector unchanged |
+| 2026-09-06 21:02 UTC | Jason (onboarding requirements) + darkwing (capture) | Future install/reconfiguration | Full required/optional setup and proposed CLI preserved; secret-input and bootstrap boundaries flagged; no implementation or retasking |
+| 2026-09-06 21:04 UTC | darkwing | Status reconciliation / FI-ROCKO-5 | Found approved addendum verdict, closed stale wait, delivered scoped correction instruction; code review/demo remain pending |
+| 2026-09-06 21:30 UTC | rocko (r3 delivery) + darkwing (verified admission) | FI-FILBERT-6 | 294-file candidate verified; green writer receipts; full code review requested, delivery unconfirmed; code frozen, no acceptance yet |
+| 2026-09-07 14:17 UTC | darkwing | Demo readiness / FI-ROCKO-6 | Completed NOT APPROVED reconciled; five blocking fixes plus inventory improvement dispatched; live-branch integration gate recorded; no demo acceptance |
+| 2026-09-07 14:29 UTC | darkwing | Demo integration gate | Suite boundaries verified and plan recorded; r4 return absent; no live execution, shared mutation or waiver |
+| 2026-09-07 | Codex | Owner-requested temporary Darkwing host TUI launcher | Configured pinned Pi, launch context snapshots, explicit tools/skills and goal extension, separate resume/fresh sessions; offline launcher checks and real TUI /goal smoke passed without model requests; no commit or push |
+| 2026-09-07 14:45 UTC | rocko (r4) + darkwing (admission) | FI-ROCKO-7 | 331-file r4 verified; remaining ordering fixes delivered; r3 live-test correction preserved; owner test-gate decision pending |
+| 2026-09-07 14:48 UTC | Jason (demo test gate) + darkwing | FI-DEMO-GATE-1 | Two mixed live suites explicitly deferred for offline demo; retained checks/review; instruction queued to Rocko, r5 pending |
+| 2026-09-07 | Codex | Darkwing launcher shim | Moved launch implementation to scripts/tui/launch.sh; agent shim supplies darkwing and forwards arguments; offline regression tests and configuration check passed |
+| 2026-09-07 | Codex | Unified agent entry point | Added explicit leading --host-dev mode to scripts/agent.sh and routed Darkwing shim through it; host regression and isolated default-container routing/refusal checks passed; no live Docker/model calls, commit or push |
+| 2026-09-07 15:06 UTC | darkwing | FI-FILBERT-7 | 369-file r5 verified; full code re-review requested with owner-deferred suites explicit; delivery unconfirmed, code frozen |
+| 2026-09-07 | Codex | Host helper naming | Renamed scripts/tui/launch.sh to scripts/agent-host-dev.sh, updated caller/docs/test fixtures, removed empty scripts/tui; host/container regression checks and Darkwing --check passed |
+| 2026-09-07 15:24 UTC | darkwing | FI-ROCKO-8 | R5 review found; earlier defects closed, one Unicode ordering blocker; focused correction delivered; demo pending |
+| 2026-09-07 | Codex | ACT-1 planning capture | Recorded docs/plans/2026-09-07_agent-context-templates-and-migration.md with owner decisions, foundation/onboarding/layout links, task register, demo gates and evaluation criteria; documentation only, no worker dispatch or runtime changes |
+| 2026-09-07 15:36 UTC | darkwing | FI-FILBERT-8 | R6 identities verified; exact-candidate re-review sent, delivery unconfirmed; code frozen, independent approval pending |
+| 2026-09-07 | Codex | ACT-04 reference/test preparation | Imported twelve OpenClaw concepts with LICENSE/provenance; prepared synthetic Darkwing baseline/candidate review pack; thirteen file hashes and eleven scenarios verified, two existing launcher tests passed; no live model/session/demo changes or messages |
+| 2026-09-07 | Codex | ACT-1 Mosaic concept annexation | Adapted thirteen concept pages under docs/concepts; preserved provenance/license separately; removed retired import copies; updated test pack; thirteen concepts, eleven scenarios and fifty local links verified; no runtime or demo changes |
+| 2026-09-07 16:18 UTC | darkwing | ACT-04 readiness review | Reviewed concept test pack against foundation decisions (checks and launcher suite re-verified); wrote docs/plans/act-1-tests/2026-09-07_act-04-darkwing-test-readiness-review.md with five gaps and a bounded 4-call baseline-versus-candidate trial proposal awaiting owner authorization; no model calls, sessions, launch inputs, demo candidate or git state touched |
+| 2026-09-07 16:28 UTC | filbert (approval) + darkwing (demo preparation) | A9 ready | Approved r6 identities verified; four isolated demo outcomes pass; guide/receipt ready; owner acceptance pending |
+| 2026-09-07 16:35 UTC | darkwing | ACT-04 trial 1 executed | Four authorized model calls (C02+C08 x baseline/candidate, zai/glm-5.3-flash, pi 0.84.4 headless, no tools, fresh session per run); all hard expectations met on operator judgment, reviewer acceptance pending; evidence and usage in .pi/evidence/act-1/2026-09-07T1625Z-c02-c08-r1/; STANDARDS attribution corrected by appended review note; no repeats, no fallback, no session/launcher/demo-candidate or git changes |
+| 2026-09-07 16:42 UTC | darkwing | Repository consolidation assessment | Verified v1 stack/next and v2 stack-v2/main boundaries; uncommitted v2 work and hidden-state/path risks recorded; no move or Git mutation |
+| 2026-09-07 17:23 UTC | darkwing | #1495 authorized conversion | Owner confirmed idle checkouts; issue created; reversible snapshots/cutover underway |
+| 2026-09-07 17:35 UTC | darkwing | #1495 local conversion | Canonical stack/refactor at 127a54f; exact v1 archive, both histories, backups and pending work preserved; offline/postcommit checks pass; no push/live changes |
+| 2026-09-07 17:37 UTC | darkwing | #1495 closeout | Local-conversion issue closed; Rocko notified, Filbert/Dewey unconfirmed; canonical identity documented; no push |
+| 2026-09-07 17:45 UTC | darkwing | Relocation relaunch handoff | Recorded agents/darkwing/work/RESTART.md and CONTEXT pointer; no launcher/private-session edits; current conversation continuity not assumed |
+
+- darkwing — authorized wave complete: approved R5 transport-only fix 69f10a40, refactor plus 17 tags remotely verified; A9 recorded; #53 published inclusion evidence for Jason closure; registry review next; unrelated relocation work excluded.

docs/SSO-PROVIDERS.md

@@ -1,111 +0,0 @@
-# SSO Providers
-
-Mosaic Stack supports optional enterprise single sign-on through Better Auth's generic OAuth flow. The gateway mounts Better Auth under `/api/auth`, so every provider callback terminates at:
-
-```text
-{BETTER_AUTH_URL}/api/auth/oauth2/callback/{providerId}
-```
-
-For the providers in this document:
-
-- Authentik: `{BETTER_AUTH_URL}/api/auth/oauth2/callback/authentik`
-- WorkOS: `{BETTER_AUTH_URL}/api/auth/oauth2/callback/workos`
-- Keycloak: `{BETTER_AUTH_URL}/api/auth/oauth2/callback/keycloak`
-
-## Required environment variables
-
-### Authentik
-
-```bash
-AUTHENTIK_ISSUER=https://auth.example.com/application/o/mosaic
-AUTHENTIK_CLIENT_ID=...
-AUTHENTIK_CLIENT_SECRET=...
-```
-
-### WorkOS
-
-```bash
-WORKOS_ISSUER=https://your-company.authkit.app
-WORKOS_CLIENT_ID=client_...
-WORKOS_CLIENT_SECRET=...
-NEXT_PUBLIC_WORKOS_ENABLED=true
-```
-
-`WORKOS_ISSUER` should be the WorkOS AuthKit issuer or custom auth domain, not the raw REST API hostname. Mosaic derives the OIDC discovery URL from that issuer.
-
-### Keycloak
-
-```bash
-KEYCLOAK_ISSUER=https://auth.example.com/realms/master
-KEYCLOAK_CLIENT_ID=mosaic
-KEYCLOAK_CLIENT_SECRET=...
-NEXT_PUBLIC_KEYCLOAK_ENABLED=true
-```
-
-If you prefer, you can keep the issuer split as:
-
-```bash
-KEYCLOAK_URL=https://auth.example.com
-KEYCLOAK_REALM=master
-```
-
-The auth package will derive `KEYCLOAK_ISSUER` from those two values.
-
-## WorkOS setup
-
-1. In WorkOS, create or select the application that will back Mosaic login.
-2. Configure an AuthKit domain or custom authentication domain for the application.
-3. Add the redirect URI:
-
-```text
-{BETTER_AUTH_URL}/api/auth/oauth2/callback/workos
-```
-
-4. Copy the application's `client_id` and `client_secret` into `WORKOS_CLIENT_ID` and `WORKOS_CLIENT_SECRET`.
-5. Set `WORKOS_ISSUER` to the AuthKit domain from step 2.
-6. Create the WorkOS organization and attach the enterprise SSO connection you want Mosaic to use.
-7. Set `NEXT_PUBLIC_WORKOS_ENABLED=true` in the web deployment so the login button is rendered.
-
-## Keycloak setup
-
-1. Start from an existing Keycloak realm or create a dedicated realm for Mosaic.
-2. Create a confidential OIDC client named `mosaic` or your preferred client ID.
-3. Set the valid redirect URI to:
-
-```text
-{BETTER_AUTH_URL}/api/auth/oauth2/callback/keycloak
-```
-
-4. Set the web origin to the public Mosaic web URL.
-5. Copy the client secret into `KEYCLOAK_CLIENT_SECRET`.
-6. Set either `KEYCLOAK_ISSUER` directly or `KEYCLOAK_URL` + `KEYCLOAK_REALM`.
-7. Set `NEXT_PUBLIC_KEYCLOAK_ENABLED=true` in the web deployment so the login button is rendered.
-
-### Local Keycloak smoke test
-
-If you want to test locally with Docker:
-
-```bash
-docker run --rm --name mosaic-keycloak \
-  -p 8080:8080 \
-  -e KEYCLOAK_ADMIN=admin \
-  -e KEYCLOAK_ADMIN_PASSWORD=admin \
-  quay.io/keycloak/keycloak:26.1 start-dev
-```
-
-Then configure:
-
-```bash
-KEYCLOAK_ISSUER=http://localhost:8080/realms/master
-KEYCLOAK_CLIENT_ID=mosaic
-KEYCLOAK_CLIENT_SECRET=...
-NEXT_PUBLIC_KEYCLOAK_ENABLED=true
-```
-
-## Web flow
-
-The web login page renders provider buttons from `NEXT_PUBLIC_*_ENABLED` flags. Each button links to `/auth/provider/{providerId}`, and that page initiates Better Auth's `signIn.oauth2` flow before handing off to the provider.
-
-## Failure mode
-
-Provider config is optional, but partial config is rejected at startup. If any provider-specific env var is present without the full required set, `@mosaicstack/auth` throws a bootstrap error with the missing keys instead of silently registering a broken provider.

docs/TOOLS.md

@@ -0,0 +1,182 @@
+# TOOLS.md — command and tool reference
+
+On-demand reference for agent sessions (conductors, bootstrapping agents,
+reviewers). `AGENTS.md` routes here; this file carries the depth: usage,
+inputs/outputs, exit codes, and safety notes for every entry point.
+
+Reading guide: system entry points are `scripts/*.sh` (bash) or invoked via
+`node scripts/mosaic-task.mjs` (node). Host-side helpers under `tools/`
+(tmux messaging, watchers, prose checker) are covered under Tools
+(host-side) below. Every script fails closed — missing
+or invalid configuration/policy refuses the operation with a nonzero exit
+and changes nothing.
+
+## Lifecycle
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `scripts/bootstrap.sh` | Create `~/.config/mosaic-dev/config.json` if absent | Idempotent; existing config validated, never rewritten |
+| `scripts/build.sh` | Build the release image | Tag derived from `RELEASE` + pinned pi version |
+| `scripts/hello.sh` | One-shot startup request | Prints model response on stdout |
+| `scripts/verify.sh` | Full gated test | Exit 0 only on exact `MOSAIC_HELLO_OK`; `EXPECTED_MARKER` overrides for negative drills |
+
+## Tasks (missions, runs, evidence)
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `scripts/run-task.sh run <task.json>` | Execute a task | Immutable run record under `<dataRoot>/runs/` |
+| `scripts/run-task.sh validate <task.json>` | Strict validation | Writes nothing |
+| `node scripts/mosaic-task.mjs show <runId>` | Inspect a run | Full record + snapshots + artifacts |
+| `node scripts/mosaic-task.mjs list` | List runs | task/workspace/session columns |
+| `node scripts/mosaic-task.mjs retry <runId>` | Re-execute a run's snapshot | New run dir; `retriedFrom` lineage recorded |
+| `node scripts/mosaic-task.mjs prune [--keep=N] [--yes]` | Retention | Dry-run default; receipt in `runs/.pruned.log` |
+| `node scripts/mosaic-task.mjs resolve-role <roleFile>` | Validate a role contract | Prints `MOSAIC_ROLE_TOOLS` / `MOSAIC_ROLE_NETWORK`; config-free |
+
+Task fields: `prompt` (required), `mission` (path), `expectExact`,
+`timeoutSeconds` (5–600), `workspace` (`:run` or named), `capabilities.tools`
+(allowlist: read write edit bash grep find ls), `session`,
+`sessionForkFrom` (requires `session`). Mission fields: `objective`,
+`directives[]`, optional governing `capabilities.tools`. Policy: a task may
+narrow a mission's tools, never widen; empty intersection = tool-free run.
+
+## Agent (interactive TUI)
+
+```bash
+scripts/agent.sh <name> [--mission <file>] [--workspace <ws>] [--session <s>] [--tools <list>]
+```
+
+Launches an interactive pi TUI inside the container with the four immutable
+contracts + optional mission + agent identity as its system prompt,
+persistent named session, optional workspace. Exit with `/quit`.
+
+A seat role (`agent.json` `role`) binds to `roles/<role>.json` (M18): the
+contract's tools are a ceiling the seat definition or `--tools` may narrow,
+never escalate past. Missing/invalid contract refuses the launch; empty
+intersection = loud tool-free seat. An explicit `MOSAIC_AGENTS_DIR` override
+that cannot resolve the named seat also refuses (#46) — unset the override
+for the M13 plain governed TUI. `--auth <account>` injects
+`auth.<account>.json` (beside the active credential file) as the launch's
+`PI_AUTH_FILE`; a missing/invalid account refuses (M19).
+
+For native repository development, opt in with a **leading** `--host-dev`:
+
+```bash
+scripts/agent.sh --host-dev darkwing [--fresh] [--check] [--soul FILE] [--constitution FILE] [--user FILE]
+```
+
+This mode delegates to `scripts/agent-host-dev.sh`, uses host Pi and repository
+tools/skills plus the development goal extension, and keeps its own sessions
+under `.pi/state/<name>/`. It uses native Pi authentication and does not run
+container release alignment or apply managed seat role ceilings. It is a host
+development session, not a sandboxed worker. Container-only flags such as
+`--auth`, `--mission`, and `--tools` are rejected in this mode. Omitting
+`--host-dev` retains the existing container lifecycle and policy checks;
+container failures never trigger a host fallback. Darkwing's agent-local shim
+selects host development explicitly. See `agents/darkwing/README.md`.
+
+## Auth (credentials)
+
+Credential checkpoint over pi's auth model (one `auth.json` keyed by
+provider; resolution order `--api-key` → `auth.json` → env → models.json).
+No credential material is ever printed — provider names, credential types,
+and env var NAMES only.
+
+Ownership rule (#48): `~/.pi` is read-only to the stack, permanently. The
+only interaction is the existing read-only container mount of the default
+credential (`PI_AUTH_FILE`, default `~/.pi/agent/auth.json`). Mosaic-managed
+accounts live under the data root: `<dataRoot>/auth/<account>.json`, perms
+0600 (mirroring `scripts/gitea-api.sh` hygiene — loose perms are flagged in
+listings and refused by `--auth`).
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `scripts/auth.sh status` | Report both credential sources | Default harness credential (read-only) + mosaic-managed accounts; never prints material |
+| `scripts/auth.sh accounts` | List mosaic-managed accounts | Under the data root; marks the active one; flags non-0600 |
+
+`agent.sh --auth <account>` injects `<dataRoot>/auth/<account>.json` as the
+launch's `PI_AUTH_FILE`; missing/symlinked/non-0600 accounts refuse.
+Headless task runs keep the default credential.
+
+## Release
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `scripts/release.sh package` | Build + tag the release image | Tag: `mosaic-poc-agent:<pi>-r<release>` |
+| `scripts/release.sh activate` | Health gate → atomic pointer swap | `--fault-injection` proves the refusal path |
+| `scripts/release.sh rollback` | Health-gated return to previous | Refuses if image missing |
+| `scripts/release.sh status` | Release, tag, active pointer, log | Safe on empty state |
+| `scripts/release.sh ensure` | Self-determination: align active pointer to `RELEASE` | Fast path restores a missing/mismatched pointer without a gate; slow path packages + health-gates first. Invoked automatically at launch |
+
+## Conductor (worker patches)
+
+```bash
+scripts/conductor-apply.sh <runId> [--dry-run]
+```
+
+Auto-applies a worker's patch under `roles/conductor-policy.json`:
+succeeded run → clean target tree → path allowlist → syntax gates →
+apply → policy suites → attribution commit. Any failure reverts.
+Push is never automatic.
+
+## Maintenance
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `scripts/reset.sh` | Delete the data root | Triple-safety-checked (path, symlink, ownership marker) |
+| `scripts/test-config.sh` | Config selftests (no Docker) | 24 cases |
+| `scripts/test-task.sh` | Task selftests + live cases | 90 cases |
+| `scripts/test-release.sh` | Release selftests | 14 cases |
+| `scripts/test-conductor.sh` | Auto-apply selftests (sandboxed) | 17 cases |
+| `scripts/test-auth.sh` | Auth checkpoint selftests (no Docker) | 13 cases |
+| `scripts/gitea-api.sh <METHOD> <path> [body]` | Gitea API helper | Token never on argv/stdout |
+
+## Tools (host-side)
+
+Host-side helpers under `tools/`, outside the `scripts/` command surface.
+Per-tool READMEs: `tools/tmux/README.md` and `tools/unslop-hook/README.md`.
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `tools/tmux/agent-send.sh` | Inter-agent tmux message with addressing preamble | Reliable submit (bracketed paste, Enter flush, draft detection); ships `send-message.sh` over ssh for remote panes (remote needs only bash + tmux + base64) |
+| `tools/agent-watch/agent-watch.sh` | Condition watcher per agent seat | One transient systemd `--user` timer + service per watch; fires `agent-send.sh` when the condition command exits 0 |
+| `node tools/unslop-hook/unslop-check.js <file>` | Mechanical AI-tell prose check | Dependency-free node CLI + module driven by `lists.json`; `extension.ts` is the pi extension wrapper |
+
+`agent-send.sh` prepends the preamble
+`[<src_host>:<src_session> -> <dst_host>:<dst_session>]`; `-C`/`--class` adds
+a ` class=<CLASS>` token (`terminal-log`, `actionable`, `human`, `reaction`,
+`digest`; consumers treat an absent class as `actionable`). Flags: `-s` dst
+session (required) · `-H` ssh target for a remote pane · `-L` named tmux
+socket · `-n` dst hostname for the preamble · `-m`/`-f`/stdin message body ·
+`-S` source-label override · `-r N` Enter-flush attempts (default 2) · `-v`
+verbose · `-h` help. Exit codes: `0` delivered/queued · `1` target not found ·
+`2` still draft · `3` usage error · `4` ambiguous socket (the session exists
+on more than one tmux server; disambiguate with `-L` or `MOSAIC_TMUX_SOCKET`).
+
+`agent-watch.sh` subcommands: `start --name <id> --session <session> --when
+'<shell command; exit 0 = met>' --message <text>` with `--class`,
+`--interval` (default 30), `--timeout` (default 3600), `--repeat`,
+`--quiet-timeout`, `--socket` · `list` · `status [--json]` · `stop <name>` ·
+`log <name>` · `meta-install [--interval 300] [--unit-name <unit>]` ·
+`meta-remove [--unit-name <unit>]`. Interval floor is 10s (a watcher is a
+fallback cadence, never a tight poll); hidden `_tick`/`_scan` subcommands run
+inside the systemd services. `status` exit codes: `0` clean · `3` any stale
+watch or dead meta-watch · `6` systemd user bus unreachable. Delivery goes
+through `agent-send.sh`; rc `2` means the text reached the pane as an
+unsubmitted draft, which counts as delivered and is not retried (other
+failures retry twice, then the watch gives up). Watches are one-shot by
+default; `--repeat` re-arms. Notices carry a `[watch:<name>]` prefix.
+
+`unslop-check.js` checks a file (or stdin) against the word, phrase,
+punctuation-density, and pattern lists in `lists.json`, stripping fenced and
+inline code first so a quoted mention never flags. Invocation:
+`node tools/unslop-hook/unslop-check.js <file>`; `UNSLOP_LISTS=<path>`
+overrides the lists location. Exit codes: `0` clean · `1` violations (findings
+printed as JSON on stdout) · `2` gate broken (invalid lists or unreadable
+input; error on stderr, never a clean verdict).
+
+## Exit-code convention
+
+`0` success · `1` operation failed · `2` invalid data/configuration ·
+`3` configuration missing for a read operation · `4` usage/file/environment
+problem. Scripts print diagnostics on stderr; model responses (and only
+model responses) on stdout.

docs/architecture/channel-protocol.md

@@ -1,743 +0,0 @@
-# Channel Protocol Architecture
-
-**Status:** Draft
-**Authors:** Mosaic Core Team
-**Last Updated:** 2026-03-22
-**Covers:** M7-001 (IChannelAdapter interface), M7-002 (ChannelMessage protocol), M7-003 (Matrix integration design), M7-004 (conversation multiplexing), M7-005 (remote auth bridging), M7-006 (agent-to-agent communication via Matrix), M7-007 (multi-user isolation in Matrix)
-
----
-
-## Overview
-
-The channel protocol defines a unified abstraction layer between Mosaic's core messaging infrastructure and the external communication channels it supports (Matrix, Discord, Telegram, TUI, WebUI, and future channels).
-
-The protocol consists of two main contracts:
-
-1. `IChannelAdapter` — the interface each channel driver must implement.
-2. `ChannelMessage` — the canonical message format that flows through the system.
-
-All channel-specific translation logic lives inside the adapter implementation. The rest of Mosaic works exclusively with `ChannelMessage` objects.
-
----
-
-## M7-001: IChannelAdapter Interface
-
-```typescript
-interface IChannelAdapter {
-  /**
-   * Stable, lowercase identifier for this channel (e.g. "matrix", "discord").
-   * Used as a namespace key in registry lookups and log metadata.
-   */
-  readonly name: string;
-
-  /**
-   * Establish a connection to the external channel backend.
-   * Called once at application startup. Must be idempotent (safe to call
-   * when already connected).
-   */
-  connect(): Promise<void>;
-
-  /**
-   * Gracefully disconnect from the channel backend.
-   * Must flush in-flight sends and release resources before resolving.
-   */
-  disconnect(): Promise<void>;
-
-  /**
-   * Return the current health of the adapter connection.
-   * Used by the admin health endpoint and alerting.
-   *
-   * - "connected"    — fully operational
-   * - "degraded"     — partial connectivity (e.g. read-only, rate-limited)
-   * - "disconnected" — no connection to channel backend
-   */
-  health(): Promise<{ status: 'connected' | 'degraded' | 'disconnected' }>;
-
-  /**
-   * Register an inbound message handler.
-   * The adapter calls `handler` for every message received from the channel.
-   * Multiple calls replace the previous handler (last-write-wins).
-   * The handler is async; the adapter must not deliver new messages until
-   * the previous handler promise resolves (back-pressure).
-   */
-  onMessage(handler: (msg: ChannelMessage) => Promise<void>): void;
-
-  /**
-   * Send a ChannelMessage to the given channel/room/conversation.
-   * `channelId` is the channel-native identifier (e.g. Matrix room ID,
-   * Discord channel snowflake, Telegram chat ID).
-   */
-  sendMessage(channelId: string, msg: ChannelMessage): Promise<void>;
-
-  /**
-   * Map a channel-native user identifier to the Mosaic internal userId.
-   * Returns null when no matching Mosaic account exists for the given
-   * channelUserId (anonymous or unlinked user).
-   */
-  mapIdentity(channelUserId: string): Promise<string | null>;
-}
-```
-
-### Adapter Registration
-
-Adapters are registered with the `ChannelRegistry` service at startup. The registry calls `connect()` on each adapter and monitors `health()` on a configurable interval (default: 30 s).
-
-```
-ChannelRegistry
-  └── register(adapter: IChannelAdapter): void
-  └── getAdapter(name: string): IChannelAdapter | null
-  └── listAdapters(): IChannelAdapter[]
-  └── healthAll(): Promise<Record<string, AdapterHealth>>
-```
-
----
-
-## M7-002: ChannelMessage Protocol
-
-### Canonical Message Format
-
-```typescript
-interface ChannelMessage {
-  /**
-   * Globally unique message ID.
-   * Format: UUID v4. Generated by the adapter when receiving, or by Mosaic
-   * when sending. Channel-native IDs are stored in metadata.channelMessageId.
-   */
-  id: string;
-
-  /**
-   * Channel-native room/conversation/channel identifier.
-   * The adapter populates this from the inbound message.
-   * For outbound messages, the caller supplies the target channel.
-   */
-  channelId: string;
-
-  /**
-   * Channel-native identifier of the message sender.
-   * For Mosaic-originated messages this is the Mosaic userId or agentId.
-   */
-  senderId: string;
-
-  /** Sender classification. */
-  senderType: 'user' | 'agent' | 'system';
-
-  /**
-   * Textual content of the message.
-   * For non-text content types (image, file) this may be an empty string
-   * or an alt-text description; the actual payload is in `attachments`.
-   */
-  content: string;
-
-  /**
-   * Hint for how `content` should be interpreted and rendered.
-   * - "text"     — plain text, no special rendering
-   * - "markdown" — CommonMark markdown
-   * - "code"     — code block (use metadata.language for the language tag)
-   * - "image"    — binary image; content is empty, see attachments
-   * - "file"     — binary file; content is empty, see attachments
-   */
-  contentType: 'text' | 'markdown' | 'code' | 'image' | 'file';
-
-  /**
-   * Arbitrary key-value metadata for channel-specific extension fields.
-   * Examples: { channelMessageId, language, reactionEmoji, channelType }.
-   * Adapters should store channel-native IDs here so round-trip correlation
-   * is possible without altering the canonical fields.
-   */
-  metadata: Record<string, unknown>;
-
-  /**
-   * Optional thread or reply-chain identifier.
-   * For threaded channels (Matrix, Discord threads, Telegram topics) this
-   * groups messages into a logical thread scoped to the same channelId.
-   */
-  threadId?: string;
-
-  /**
-   * The canonical message ID this message is a reply to.
-   * Maps to channel-native reply/quote mechanisms in each adapter.
-   */
-  replyToId?: string;
-
-  /**
-   * Binary or URI-referenced attachments.
-   * Each attachment carries its MIME type and a URL or base64 payload.
-   */
-  attachments?: ChannelAttachment[];
-
-  /** Wall-clock timestamp when the message was sent/received. */
-  timestamp: Date;
-}
-
-interface ChannelAttachment {
-  /** Filename or identifier. */
-  name: string;
-
-  /** MIME type (e.g. "image/png", "application/pdf"). */
-  mimeType: string;
-
-  /**
-   * URL pointing to the attachment, OR a `data:` URI with base64 payload.
-   * Adapters that receive file uploads SHOULD store to object storage and
-   * populate a stable URL here rather than embedding the raw bytes.
-   */
-  url: string;
-
-  /** Size in bytes, if known. */
-  sizeBytes?: number;
-}
-```
-
----
-
-## Channel Translation Reference
-
-The following sections document how each supported channel maps its native message format to and from `ChannelMessage`.
-
-### Matrix
-
-| ChannelMessage field | Matrix equivalent                                                                                                                 |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                 | Generated UUID; `metadata.channelMessageId` = Matrix event ID (`$...`)                                                            |
-| `channelId`          | Matrix room ID (`!roomid:homeserver`)                                                                                             |
-| `senderId`           | Matrix user ID (`@user:homeserver`)                                                                                               |
-| `senderType`         | Always `"user"` for inbound; `"agent"` or `"system"` for outbound                                                                 |
-| `content`            | `event.content.body`                                                                                                              |
-| `contentType`        | `"markdown"` if `msgtype = m.text` and body contains markdown; `"text"` otherwise; `"image"` for `m.image`; `"file"` for `m.file` |
-| `threadId`           | `event.content['m.relates_to']['event_id']` when `rel_type = m.thread`                                                            |
-| `replyToId`          | Mosaic ID looked up from `event.content['m.relates_to']['m.in_reply_to']['event_id']`                                             |
-| `attachments`        | Populated from `url` in `m.image` / `m.file` events                                                                               |
-| `timestamp`          | `new Date(event.origin_server_ts)`                                                                                                |
-| `metadata`           | `{ channelMessageId, roomId, eventType, unsigned }`                                                                               |
-
-**Outbound:** Adapter sends `m.room.message` with `msgtype = m.text` (or `m.notice` for system messages). Markdown content is sent with `format = org.matrix.custom.html` and a rendered HTML body.
-
----
-
-### Discord
-
-| ChannelMessage field | Discord equivalent                                                      |
-| -------------------- | ----------------------------------------------------------------------- |
-| `id`                 | Generated UUID; `metadata.channelMessageId` = Discord message snowflake |
-| `channelId`          | Discord channel ID (snowflake string)                                   |
-| `senderId`           | Discord user ID (snowflake)                                             |
-| `senderType`         | `"user"` for human members; `"agent"` for bot messages                  |
-| `content`            | `message.content`                                                       |
-| `contentType`        | `"markdown"` (Discord uses a markdown-like syntax natively)             |
-| `threadId`           | `message.thread.id` when the message is inside a thread channel         |
-| `replyToId`          | Mosaic ID looked up from `message.referenced_message.id`                |
-| `attachments`        | `message.attachments` mapped to `ChannelAttachment`                     |
-| `timestamp`          | `new Date(message.timestamp)`                                           |
-| `metadata`           | `{ channelMessageId, guildId, channelType, mentions, embeds }`          |
-
-**Outbound:** Adapter calls Discord REST `POST /channels/{id}/messages`. Markdown content is sent as-is (Discord renders it). For `contentType = "code"` the adapter wraps in triple-backtick fences with the `metadata.language` tag.
-
----
-
-### Telegram
-
-| ChannelMessage field | Telegram equivalent                                                                                           |
-| -------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `id`                 | Generated UUID; `metadata.channelMessageId` = Telegram `message_id` (integer)                                 |
-| `channelId`          | Telegram `chat_id` (integer as string)                                                                        |
-| `senderId`           | Telegram `from.id` (integer as string)                                                                        |
-| `senderType`         | `"user"` for human senders; `"agent"` for bot-originated messages                                             |
-| `content`            | `message.text` or `message.caption`                                                                           |
-| `contentType`        | `"text"` for plain; `"markdown"` if `parse_mode = MarkdownV2`; `"image"` for `photo`; `"file"` for `document` |
-| `threadId`           | `message.message_thread_id` (for supergroup topics)                                                           |
-| `replyToId`          | Mosaic ID looked up from `message.reply_to_message.message_id`                                                |
-| `attachments`        | `photo`, `document`, `video` fields mapped to `ChannelAttachment`                                             |
-| `timestamp`          | `new Date(message.date * 1000)`                                                                               |
-| `metadata`           | `{ channelMessageId, chatType, fromUsername, forwardFrom }`                                                   |
-
-**Outbound:** Adapter calls Telegram Bot API `sendMessage` with `parse_mode = MarkdownV2` for markdown content. For `contentType = "image"` or `"file"` it uses `sendPhoto` / `sendDocument`.
-
----
-
-### TUI (Terminal UI)
-
-The TUI adapter bridges Mosaic's terminal interface (`packages/cli`) to the channel protocol so that TUI sessions can be treated as a first-class channel.
-
-| ChannelMessage field | TUI equivalent                                                     |
-| -------------------- | ------------------------------------------------------------------ |
-| `id`                 | Generated UUID (TUI has no native message IDs)                     |
-| `channelId`          | `"tui:<conversationId>"` — the active conversation ID              |
-| `senderId`           | Authenticated Mosaic `userId`                                      |
-| `senderType`         | `"user"` for human input; `"agent"` for agent replies              |
-| `content`            | Raw text from stdin / agent output                                 |
-| `contentType`        | `"text"` for input; `"markdown"` for agent responses               |
-| `threadId`           | Not used (TUI sessions are linear)                                 |
-| `replyToId`          | Not used                                                           |
-| `attachments`        | File paths dragged/pasted into the TUI; resolved to `file://` URLs |
-| `timestamp`          | `new Date()` at the moment of send                                 |
-| `metadata`           | `{ conversationId, sessionId, ttyWidth, colorSupport }`            |
-
-**Outbound:** The adapter writes rendered content to stdout. Markdown is rendered via a terminal markdown renderer (e.g. `marked-terminal`). Code blocks are syntax-highlighted when `metadata.colorSupport = true`.
-
----
-
-### WebUI
-
-The WebUI adapter connects the Next.js frontend (`apps/web`) to the channel protocol over the existing Socket.IO gateway (`apps/gateway`).
-
-| ChannelMessage field | WebUI equivalent                                             |
-| -------------------- | ------------------------------------------------------------ |
-| `id`                 | Generated UUID; echoed back in the WebSocket event           |
-| `channelId`          | `"webui:<conversationId>"`                                   |
-| `senderId`           | Authenticated Mosaic `userId`                                |
-| `senderType`         | `"user"` for browser input; `"agent"` for agent responses    |
-| `content`            | Message text from the input field                            |
-| `contentType`        | `"text"` or `"markdown"`                                     |
-| `threadId`           | Not used (conversation model handles threading)              |
-| `replyToId`          | Message ID the user replied to (UI reply affordance)         |
-| `attachments`        | Files uploaded via the file picker; stored to object storage |
-| `timestamp`          | `new Date()` at send, or server timestamp from event         |
-| `metadata`           | `{ conversationId, sessionId, clientTimezone, userAgent }`   |
-
-**Outbound:** Adapter emits a `chat:message` Socket.IO event. The WebUI React component receives it and appends to the conversation list. Markdown content is rendered client-side via the existing markdown renderer component.
-
----
-
-## Identity Mapping
-
-`mapIdentity(channelUserId)` resolves a channel-native user identifier to a Mosaic `userId`. This is required to attribute inbound messages to authenticated Mosaic accounts.
-
-The implementation must query a `channel_identities` table (or equivalent) keyed on `(channel_name, channel_user_id)`. When no mapping exists the method returns `null` and the message is treated as anonymous (no Mosaic session context).
-
-```
-channel_identities
-  channel_name   TEXT       -- e.g. "matrix", "discord"
-  channel_user_id TEXT      -- channel-native user identifier
-  mosaic_user_id  TEXT      -- FK to users.id
-  linked_at       TIMESTAMP
-  PRIMARY KEY (channel_name, channel_user_id)
-```
-
-Identity linking flows (OAuth dance, deep-link verification token, etc.) are out of scope for this document and will be specified in a separate identity-linking protocol document.
-
----
-
-## Error Handling Conventions
-
-- `connect()` must throw a structured error (subclass of `ChannelConnectError`) if the initial connection cannot be established within a reasonable timeout (default: 10 s).
-- `sendMessage()` must throw `ChannelSendError` on terminal failures (auth revoked, channel not found). Transient failures (rate limit, network blip) should be retried internally with exponential backoff before throwing.
-- `health()` must never throw — it returns `{ status: 'disconnected' }` on error.
-- Adapters must emit structured logs with `{ channel: adapter.name, event, ... }` metadata for observability.
-
----
-
-## Versioning
-
-The `ChannelMessage` protocol follows semantic versioning. Non-breaking field additions (new optional fields) are minor version bumps. Breaking changes (type changes, required field additions) require a major version bump and a migration guide.
-
-Current version: **1.0.0**
-
----
-
-## M7-003: Matrix Integration Design
-
-### Homeserver Choice
-
-Mosaic uses **Conduit** as the Matrix homeserver. Conduit is written in Rust, ships as a single binary, and has minimal operational overhead compared to Synapse or Dendrite. It supports the full Matrix Client-Server and Application Service APIs required by Mosaic.
-
-Recommended deployment: Conduit runs as a Docker container alongside the Mosaic stack. A single Conduit instance is sufficient for most self-hosted deployments. Conduit's embedded RocksDB storage means no separate database is required for the homeserver itself.
-
-### Appservice Registration
-
-Mosaic registers with the Conduit homeserver as a Matrix **Application Service (appservice)**. This gives Mosaic the ability to:
-
-- Create and control ghost users (virtual Matrix users representing Mosaic agents and provisioned accounts).
-- Receive all events sent to rooms within the appservice's namespace without polling.
-- Send events on behalf of ghost users without separate authentication.
-
-Registration is done via a YAML registration file (`mosaic-appservice.yaml`) placed in Conduit's configuration directory:
-
-```yaml
-id: mosaic
-url: http://gateway:3000/_matrix/appservice
-as_token: <random-secret>
-hs_token: <random-secret>
-sender_localpart: mosaic-bot
-namespaces:
-  users:
-    - exclusive: true
-      regex: '@mosaic_.*:homeserver'
-  rooms:
-    - exclusive: false
-      regex: '.*'
-  aliases:
-    - exclusive: true
-      regex: '#mosaic-.*:homeserver'
-```
-
-The gateway exposes `/_matrix/appservice` endpoints to receive push events from Conduit. The `as_token` and `hs_token` are stored in Vault and injected at startup.
-
-### Room ↔ Conversation Mapping
-
-Each Mosaic conversation maps to a single Matrix room. The mapping is stored in the database:
-
-```
-conversation_matrix_rooms
-  conversation_id  TEXT  -- FK to conversations.id
-  room_id          TEXT  -- Matrix room ID (!roomid:homeserver)
-  created_at       TIMESTAMP
-  PRIMARY KEY (conversation_id)
-```
-
-Room creation is handled by the appservice on the first Matrix access to a conversation. Room names follow the pattern `Mosaic: <conversation title>`. Room topics contain the conversation ID for correlation.
-
-When a conversation is deleted or archived in Mosaic, the corresponding Matrix room is tombstoned (m.room.tombstone event) and the room is left in a read-only state.
-
-### Space ↔ Team Mapping
-
-Each Mosaic team maps to a Matrix **Space**. Spaces are Matrix rooms with a special `m.space` type that can contain child rooms.
-
-```
-team_matrix_spaces
-  team_id    TEXT  -- FK to teams.id
-  space_id   TEXT  -- Matrix room ID of the Space
-  created_at TIMESTAMP
-  PRIMARY KEY (team_id)
-```
-
-When a conversation room is shared with a team, the appservice adds it to the team's Space via `m.space.child` state events. Removing the share removes the child relationship.
-
-### Agent Ghost Users
-
-Each Mosaic agent is represented in Matrix as an **appservice ghost user**:
-
-- Matrix user ID format: `@mosaic_agent_<agentId>:homeserver`
-- Display name: the agent's human-readable name (e.g. "Mosaic Assistant")
-- Avatar: optional, configurable per agent
-
-Ghost users are registered lazily — the appservice creates the ghost on first use. Ghost users are controlled exclusively by the appservice; they cannot log in via Matrix client credentials.
-
-When an agent sends a message via the gateway, the Matrix adapter sends the event using `user_id` impersonation on the appservice's client endpoint, causing the message to appear as if sent by the ghost user.
-
-### Power Levels
-
-Power levels in each Mosaic-managed room are set as follows:
-
-| Entity                                | Power Level    | Rationale                              |
-| ------------------------------------- | -------------- | -------------------------------------- |
-| Mosaic appservice bot (`@mosaic-bot`) | 100 (Admin)    | Room management and moderation         |
-| Human Mosaic users                    | 50 (Moderator) | Can kick, redact, and invite           |
-| Agent ghost users                     | 0 (Default)    | Message-only; cannot modify room state |
-
-This arrangement ensures human users retain full control. An agent cannot modify room settings, kick members, or take administrative actions. Humans with moderator power can redact agent messages and intervene in ongoing conversations.
-
-```
-mermaid
-graph TD
-    A[Mosaic Admin] -->|invites| B[Human User]
-    B -->|joins| C[Matrix Room / Conversation]
-    D[Agent Ghost User] -->|sends messages to| C
-    B -->|can redact/kick| D
-    E[Mosaic Bot] -->|manages room state| C
-    style A fill:#4a9eff
-    style B fill:#4a9eff
-    style D fill:#aaaaaa
-    style E fill:#ff9944
-```
-
----
-
-## M7-004: Conversation Multiplexing
-
-### Architecture Overview
-
-A single Mosaic conversation can be accessed simultaneously from multiple surfaces: TUI, WebUI, and Matrix. The gateway is the **single source of truth** for all conversation state. Each surface is a thin client that renders gateway-owned data.
-
-```
-┌─────────────────────────────────────────────────────┐
-│                    Gateway (NestJS)                  │
-│                                                      │
-│   ConversationService  ←→  MessageBus               │
-│         │                      │                    │
-│    [DB: PostgreSQL]     [Fanout: Valkey Pub/Sub]     │
-│                                │                    │
-│          ┌─────────────────────┼──────────────┐     │
-│          │                     │              │     │
-│   Socket.IO         Socket.IO      Matrix     │     │
-│   (TUI adapter)    (WebUI adapter) (appservice)│    │
-└──────────┼─────────────────────┼──────────────┘     │
-           │                     │              │
-       CLI/TUI              Browser          Matrix
-                                             Client
-```
-
-### Real-Time Sync Flow
-
-1. A message arrives on any surface (TUI keystroke, browser send, Matrix event).
-2. The surface's adapter normalizes the message to `ChannelMessage` and delivers it to `ConversationService`.
-3. `ConversationService` persists the message to PostgreSQL, assigns a canonical `id`, and publishes a `message:new` event to the Valkey pub/sub channel keyed by `conversationId`.
-4. All active surfaces subscribed to that `conversationId` receive the fanout event and push it to their respective clients:
-   - TUI adapter: writes rendered output to the connected terminal session.
-   - WebUI adapter: emits a `chat:message` Socket.IO event to all browser sessions joined to that conversation.
-   - Matrix adapter: sends an `m.room.message` event to the conversation's Matrix room.
-
-This ensures that a message typed in the TUI appears in the browser and in Matrix within the same round-trip latency as the Valkey fanout (typically <10 ms on co-located infrastructure).
-
-### Surface-to-Transport Mapping
-
-| Surface | Transport to Gateway                       | Fanout Transport from Gateway |
-| ------- | ------------------------------------------ | ----------------------------- |
-| TUI     | HTTPS REST + SSE or WebSocket              | Socket.IO over stdio proxy    |
-| WebUI   | Socket.IO (browser)                        | Socket.IO emit                |
-| Matrix  | Matrix Client-Server API (appservice push) | Matrix `m.room.message` send  |
-
-### Conflict Resolution
-
-- **Messages**: Append-only. Messages are never edited in-place in Mosaic's canonical store. Matrix edit events (`m.replace`) are treated as new messages with `replyToId` pointing to the original, preserving the full audit trail.
-- **Metadata (title, tags, archived state)**: Last-write-wins. The timestamp of the most recent write wins. Concurrent metadata updates from different surfaces are serialized through `ConversationService`; the final database write reflects the last persisted value.
-- **Conversation membership**: Set-merge semantics. Adding a user from any surface is additive. Removal requires an explicit delete action and is not overwritten by concurrent adds.
-
-### Session Isolation
-
-Multiple TUI sessions or browser tabs connected to the same conversation receive all fanout messages independently. Each session maintains its own scroll position and local ephemeral state (typing indicator, draft text). Gateway does not synchronize ephemeral state across sessions.
-
----
-
-## M7-005: Remote Auth Bridging
-
-### Overview
-
-Matrix users authenticate to Mosaic by linking their Matrix identity to an existing Mosaic account. There are two flows: token linking (primary) and OAuth bridge (alternative). Once linked, the Matrix session is persistent — there is no periodic login/logout cycle.
-
-### Token Linking Flow
-
-1. A Mosaic admin or the user themselves generates a short-lived link token via the Mosaic web UI or API (`POST /auth/channel-link-token`). The token is a cryptographically random 32-byte hex string with a 15-minute TTL stored in Valkey.
-2. The user opens a Matrix client and sends a DM to `@mosaic-bot:homeserver`.
-3. The user sends the command: `!link <token>`
-4. The appservice receives the `m.room.message` event in the DM room, extracts the token, and calls `AuthService.linkChannelIdentity({ channel: 'matrix', channelUserId: matrixUserId, token })`.
-5. `AuthService` validates the token, retrieves the associated `mosaicUserId`, and writes a row to `channel_identities`.
-6. The appservice sends a confirmation reply in the DM room and invites the now-linked user to their personal Matrix Space.
-
-```
-User (Matrix)          @mosaic-bot          Mosaic Gateway
-     │                     │                      │
-     │  DM: !link <token>  │                      │
-     │────────────────────▶│                      │
-     │                     │  POST /auth/link     │
-     │                     │─────────────────────▶│
-     │                     │   200 OK             │
-     │                     │◀─────────────────────│
-     │  ✓ Linked! Joining  │                      │
-     │  your Space now     │                      │
-     │◀────────────────────│                      │
-```
-
-### OAuth Bridge Flow
-
-An alternative flow for users who prefer browser-based authentication:
-
-1. The Mosaic bot sends the user a Matrix message containing an OAuth URL: `https://mosaic.example.com/auth/matrix-link?state=<nonce>&matrix_user=<encoded_mxid>`
-2. The user opens the URL in a browser. If not already logged in to Mosaic, they are redirected through the standard BetterAuth login flow.
-3. On successful authentication, Mosaic records the `channel_identities` row linking `matrix_user` to the authenticated `mosaicUserId`.
-4. The gateway sends a Matrix event to the pending DM room confirming the link.
-
-### Invite-Based Provisioning
-
-When a Mosaic admin adds a new user account, the provisioning flow optionally associates a Matrix user ID with the new account at creation time:
-
-1. Admin provides `matrixUserId` when creating the account (`POST /admin/users`).
-2. `UserService` writes the `channel_identities` row immediately.
-3. The Matrix adapter's provisioning hook fires, and the appservice:
-   - Creates the user's personal Matrix Space (if not already existing).
-   - Sends an invite to the Matrix user for their personal Space.
-   - Sends a welcome DM from `@mosaic-bot` with onboarding instructions.
-
-The invited user does not need to complete any linking step — the association is pre-established by the admin.
-
-### Session Lifecycle
-
-Matrix sessions for linked users are persistent and long-lived. Unlike TUI sessions (which terminate when the terminal process exits), a Matrix user's access to their rooms remains intact as long as:
-
-- Their Mosaic account is active (not suspended or deleted).
-- Their `channel_identities` row exists (link not revoked).
-- They remain members of the relevant Matrix rooms.
-
-Revoking a Matrix link (`DELETE /auth/channel-link/matrix/<matrixUserId>`) removes the `channel_identities` row and causes `mapIdentity()` to return `null`. The appservice optionally kicks the Matrix user from all Mosaic-managed rooms as part of the revocation flow (configurable, default: off).
-
----
-
-## M7-006: Agent-to-Agent Communication via Matrix
-
-### Dedicated Agent Rooms
-
-When two Mosaic agents need to coordinate, a dedicated Matrix room is created for their dialogue. This provides a persistent, auditable channel for structured inter-agent communication that humans can observe.
-
-Room naming convention:
-
-```
-#mosaic-agents-<agentA>-<agentB>:homeserver
-```
-
-Where `agentA` and `agentB` are the Mosaic agent IDs sorted lexicographically (to ensure the same room is used regardless of which agent initiates). The room alias is registered by the appservice.
-
-```
-agent_rooms
-  room_id     TEXT  -- Matrix room ID
-  agent_a_id  TEXT  -- FK to agents.id (lexicographically first)
-  agent_b_id  TEXT  -- FK to agents.id (lexicographically second)
-  created_at  TIMESTAMP
-  PRIMARY KEY (agent_a_id, agent_b_id)
-```
-
-### Room Membership and Power Levels
-
-| Entity                             | Power Level                          |
-| ---------------------------------- | ------------------------------------ |
-| Mosaic appservice bot              | 100 (Admin)                          |
-| Human observers (invited)          | 50 (Moderator, read-only by default) |
-| Agent ghost users (agentA, agentB) | 0 (Default — message send only)      |
-
-Humans are invited to agent rooms with a read-only intent. By convention, human messages in agent rooms are prefixed with `[HUMAN]` and treated as interrupts by the gateway. Agents are instructed (via system prompt) to pause and acknowledge human messages before resuming their dialogue.
-
-### Message Format
-
-Agents communicate using **structured JSON** embedded in Matrix event content. The Matrix event type is `m.room.message` with `msgtype: "m.text"` for compatibility. The structured payload is carried in a custom `mosaic.agent_message` field:
-
-```json
-{
-  "msgtype": "m.text",
-  "body": "[Agent message — see mosaic.agent_message for structured content]",
-  "mosaic.agent_message": {
-    "schema_version": "1.0",
-    "sender_agent_id": "agent_abc123",
-    "conversation_id": "conv_xyz789",
-    "message_type": "request",
-    "payload": {
-      "action": "summarize",
-      "parameters": { "max_tokens": 500 },
-      "reply_to_event_id": "$previousEventId"
-    },
-    "timestamp_ms": 1711234567890
-  }
-}
-```
-
-The `body` field contains a human-readable fallback so the conversation is legible in any Matrix client. The structured payload is parsed exclusively by the gateway's Matrix adapter.
-
-### Coordination Patterns
-
-**Request/Response**: Agent A sends a `message_type: "request"` event. Agent B sends a `message_type: "response"` with `reply_to_event_id` referencing Agent A's event. The gateway correlates request/response pairs using the event IDs.
-
-**Broadcast**: An agent sends a `message_type: "broadcast"` to a multi-agent room (more than two members). All agents in the room receive the event. No response is expected.
-
-**Delegation**: Agent A sends a `message_type: "delegate"` with a `payload.task` object describing work to be handed off to Agent B. Agent B acknowledges with `message_type: "delegate_ack"` and later sends `message_type: "delegate_complete"` when done.
-
-```
-AgentA                Gateway               AgentB
-  │   delegate(task)    │                     │
-  │────────────────────▶│                     │
-  │                     │  Matrix event push  │
-  │                     │────────────────────▶│
-  │                     │  delegate_ack       │
-  │                     │◀────────────────────│
-  │                     │  [AgentB executes]  │
-  │                     │  delegate_complete  │
-  │                     │◀────────────────────│
-  │  task result        │                     │
-  │◀────────────────────│                     │
-```
-
-### Gateway Mediation
-
-Agents do not call the Matrix Client-Server API directly. All inter-agent Matrix events are sent and received by the gateway's appservice. This means:
-
-- The gateway can intercept, log, and rate-limit agent-to-agent messages.
-- Agents that are offline (no active process) still have their messages delivered; the gateway queues them and delivers on the agent's next activation.
-- The gateway can inject system messages (e.g. human interrupts, safety stops) into agent rooms without agent cooperation.
-
----
-
-## M7-007: Multi-User Isolation in Matrix
-
-### Space-per-Team Architecture
-
-Isolation in Matrix is enforced through the Space hierarchy. Each organizational boundary in Mosaic maps to a distinct Matrix Space:
-
-| Mosaic entity                 | Matrix Space   | Visibility        |
-| ----------------------------- | -------------- | ----------------- |
-| Personal workspace (per user) | Personal Space | User only         |
-| Team                          | Team Space     | Team members only |
-| Public project                | (no Space)     | Configurable      |
-
-Rooms (conversations) are placed into Spaces based on their sharing configuration. A room can appear in at most one team Space at a time. Moving a room from one team Space to another removes the `m.space.child` link from the old Space and adds it to the new one.
-
-### Room Visibility Rules
-
-Matrix room visibility within Conduit is controlled by:
-
-1. **Join rules**: All Mosaic-managed rooms use `join_rule: invite`. Users cannot discover or join rooms without an explicit invite from the appservice.
-2. **Space membership**: Rooms appear in a Space's directory only to users who are members of that Space.
-3. **Room directory**: The server room directory is disabled for Mosaic-managed rooms (`m.room.history_visibility: shared` for team rooms, `m.room.history_visibility: invited` for personal rooms).
-
-### Personal Space Defaults
-
-When a user account is created (or linked to Matrix), the appservice provisions a personal Space:
-
-- Space name: `<username>'s Space`
-- All conversations the user creates personally are added as children of their personal Space.
-- No other users are members of this Space by default.
-- Conversation rooms within the personal Space are only visible and accessible to the owner.
-
-### Team Shared Rooms
-
-When a project or conversation is shared with a team:
-
-1. The appservice adds the room as a child of the team's Space (`m.space.child` state event in the Space room, `m.space.parent` state event in the conversation room).
-2. All current team members are invited to the conversation room.
-3. Newly added team members are automatically invited to all shared rooms in the team's Space by the appservice's team membership hook.
-4. If sharing is revoked, the appservice removes the `m.space.child` link and kicks all team members who joined via the team share (users who were directly invited are unaffected).
-
-### Encryption
-
-Encryption is optional and configured per room at creation time. Recommended defaults:
-
-| Space type     | Encryption default | Rationale                              |
-| -------------- | ------------------ | -------------------------------------- |
-| Personal Space | Enabled            | Privacy-first for individual users     |
-| Team Space     | Disabled           | Operational visibility; admin auditing |
-| Agent rooms    | Disabled           | Gateway must read structured payloads  |
-
-When encryption is enabled, the appservice's ghost users must participate in key exchange (using Matrix's Olm/Megolm protocol). The gateway holds the device keys for all ghost users it controls. This constraint means encrypted rooms require the gateway to be the E2E session holder — messages are end-to-end encrypted between human clients and gateway-held ghost device keys, not between human clients themselves.
-
-### Admin Visibility
-
-A Conduit server administrator can see:
-
-- Room metadata: names, aliases, topic, membership list.
-- Unencrypted event content in unencrypted rooms.
-
-A Conduit server administrator **cannot** see:
-
-- Content of encrypted rooms (without holding a device key for a room member).
-
-Mosaic does not grant gateway admin credentials to application-level admin users. The Conduit admin interface is restricted to infrastructure operators. Application-level admins manage users and rooms through the Mosaic API, which interacts with the appservice layer only.
-
-### Data Retention
-
-Matrix events in Mosaic-managed rooms follow Mosaic's configurable retention policy:
-
-```
-room_retention_policies
-  room_id          TEXT   -- Matrix room ID (or wildcard pattern)
-  retention_days   INT    -- NULL = keep forever
-  applies_to       TEXT   -- "personal" | "team" | "agent" | "all"
-  created_at       TIMESTAMP
-```
-
-The retention policy is enforced by a background job in the gateway that calls Conduit's admin API to purge events older than the configured threshold. Purged events are removed from the Conduit store but Mosaic's PostgreSQL message store retains the canonical `ChannelMessage` record unless the Mosaic retention policy also covers it.
-
-Default retention values:
-
-| Room type                   | Default retention   |
-| --------------------------- | ------------------- |
-| Personal conversation rooms | 365 days            |
-| Team conversation rooms     | 730 days            |
-| Agent-to-agent rooms        | 90 days             |
-| System/audit rooms          | 1825 days (5 years) |
-
-Retention settings are configurable by Mosaic admins via the admin API and apply to both the Matrix event store and the Mosaic message store in lockstep.

docs/concepts/README.md

@@ -0,0 +1,31 @@
+# Mosaic Stack concepts
+
+These pages explain Mosaic's own concepts and design direction. Each states its
+implementation status. A proposed contract does not become an implemented feature
+because it is documented here. Current demo compatibility and ACT-1's migration
+gates remain in force.
+
+| Concept | What it explains |
+|---|---|
+| [Agent personality](soul.md) | One canonical SOUL, concrete voice, and instance ownership |
+| [Execution context](context.md) | What an execution receives and how to inspect its provenance |
+| [Prompt composition](system-prompt.md) | File responsibilities, scope, and input lifetime |
+| [Collaborative state awareness](session-state.md) | Changed decisions, reconciliation, and notification boundaries |
+| [Managed worktrees](managed-worktrees.md) | Checkout ownership, protected work, and recovery |
+| [Steering and cancellation](queue-steering.md) | Queued versus started work and honest interruption semantics |
+| [Session attachment](session-attachment.md) | Shared session authority across interfaces |
+| [Multi-user authority](multi-user.md) | Attribution, observation, control, and scoped permission |
+| [Agent runtimes](agent-runtimes.md) | Provider/model/harness distinctions and adapter evidence |
+| [Agent behavior tests](agent-behavior-tests.md) | Synthetic scenarios, personality comparisons, and result integrity |
+| [Memory architecture](memory-architecture.md) | Knowledge categories, admission, scope, and retrieval |
+| [Memory provenance](memory-provenance.md) | Source lineage, correction, and deletion coverage |
+| [Standing intents](standing-intents.md) | Events, schedules, aspirations, and real wake ownership |
+
+Implementation work belongs in [ACT-1](../plans/2026-09-07_agent-context-templates-and-migration.md)
+and related foundation plans. Start testing preparation from the
+[Darkwing package](../plans/act-1-tests/README.md).
+
+This directory is the home for conceptual explanations. `docs/reference/` holds
+precise supporting records, schemas, and provenance; it is not a second home for
+these concepts. [Source attribution](../reference/concepts/README.md) preserves
+the origin and license of material adapted into this set.

docs/concepts/agent-behavior-tests.md

@@ -0,0 +1,39 @@
+# Agent behavior tests
+
+Status: ACT-1's preparation package exists; model trials remain NOT_RUN unless
+an execution record establishes otherwise.
+
+Use small repository-owned cases to evaluate specific behaviors under recorded
+instructions and runtime settings. A test should name what it proves and what it
+does not. Avoid a second runner when an existing harness can execute the case.
+
+## Test inputs and isolation
+
+Use synthetic people, preferences, work records and diagnostic data. Give every
+trial an explicit isolated workspace/session binding. Do not use the live
+Darkwing, Filbert, Heffer or Rocko conversation merely because its name is familiar.
+
+A personality comparison injects exactly one SOUL per trial. Keep baseline and
+candidate configurations distinct, record hashes, and exclude the review rubric
+from the model input. Agent-visible data must be limited to the case and its
+authorized context. Prompt instructions alone do not enforce filesystem isolation.
+
+## Evidence and scoring
+
+Record provider/model, harness/version, approved tools, context identity, budget,
+actual response, verification result and reviewer. Preserve failed and ambiguous
+attempts. Use NOT_RUN, PASS, FAIL, BLOCKED and DEFERRED accurately.
+
+Mechanical tests can verify wiring and refusal behavior. Model trials can assess
+reasoning and style. Neither can substitute for the other's evidence. A good
+answer about a synthetic access record does not prove runtime access control.
+
+Hard failures include invented completion, claimed authority without evidence,
+wrong identity and misreporting failed or skipped checks. Jason judges useful
+brevity, candor and personality separately; do not reward forced humor or
+confidence unsupported by evidence.
+
+The current [ACT-1 pack](../plans/act-1-tests/README.md) has eleven synthetic cases
+and a preparation utility. It also reuses existing launcher regressions. Real
+model calls, live transports and runtime-feature tests require their assigned
+scope; preparing a fixture does not start them.

docs/concepts/agent-runtimes.md

@@ -0,0 +1,45 @@
+# Agent runtimes and adapter ownership
+
+Status: Pi is the reference harness; additional harness support must be established
+through pinned adapter contracts and tests.
+
+| Layer | Meaning |
+|---|---|
+| Provider | Model service and its authentication/transport |
+| Model | Selected model and supported settings |
+| Harness/runtime | Program that executes the model/tool loop |
+| Deployment | Host development or managed container execution |
+| Interface/transport | Where a user or authorized service interacts with the execution |
+
+Changing a provider is not the same operation as changing the harness or deployment.
+
+## Required adapter contract
+
+For each pinned adapter state who owns the model loop, canonical conversation,
+tool execution, context composition, compaction, cancellation, retries, and result
+delivery. Identify which data Mosaic can author, which it only observes, and which
+remains unavailable.
+
+Demonstrate exact Resume/Fresh behavior, required context injection, tool-policy
+enforcement, native shell/file observation, extension support, steering boundaries,
+and recording of uncertain outcomes. Mark unsupported and untested behavior
+explicitly. A successful startup is only startup evidence.
+
+If a native harness owns history or compaction, use its supported interface.
+Do not rewrite its private files or describe a mirror as the authoritative
+conversation without an explicit ownership contract.
+
+## Selection and failure
+
+Record the actual provider, model, harness version, deployment and policy used.
+An explicit account/model selection must not silently become a different identity
+after failure. Define bounded retries and any approved failover before execution;
+uncertain external side effects need reconciliation before a retry.
+
+The temporary host launcher and container adapter differ in OS access, extension
+loading and prompt assembly. Neither name nor tool allowlist alone proves equal
+isolation. Preserve those distinctions in diagnostics and tests.
+
+ACT-C07 tests interpretation of a capability matrix. It does not certify an
+adapter. See [prompt composition](system-prompt.md),
+[steering](queue-steering.md), and [adapter contract](../../adapters/README.md).

docs/concepts/context.md

@@ -0,0 +1,41 @@
+# Execution context
+
+Status: target design with a partial native-development implementation.
+[ACT-1](../plans/2026-09-07_agent-context-templates-and-migration.md) governs rollout.
+
+Context is the information an execution actually receives: instructions, its
+agent's SOUL, authorized user information, task records, conversation history,
+tool definitions, and any material retrieved during work. A file's presence in
+the repository does not mean it was injected.
+
+## Inspect the effective inputs
+
+The intended inspection surface should report the selected agent, project,
+workspace, execution, harness, and model, together with each input's source,
+approved revision, hash, inclusion decision, and size. Report exclusions and
+their reasons. Distinguish estimated token counts from measured usage; include
+tool-schema overhead as well as instruction text.
+
+Exactly one agent-owned SOUL is eligible. Root and shared-default SOULs are not
+fallbacks in the target design. Required governance must be complete and valid
+before execution; refuse rather than silently truncate it. Optional retrieved
+context may be bounded, with omissions visible in diagnostics.
+
+Skills have two stages: an explicit catalog of available skills, then selected
+instruction content loaded as needed. Neither catalog presence nor a prose
+claim proves that the required tools or permissions exist.
+
+## Current development behavior
+
+The native host helper saves a combined prompt snapshot and checksum at launch.
+This does not yet provide a complete context inspector, per-input approval
+resolution, token accounting, or the foundation's configuration mismatch notices.
+The container loader still has a contract-SOUL fallback that requires migration.
+
+Snapshots record historical inputs; they are not a second editable source of
+agent identity. Current approved inputs are resolved at each Resume or Fresh
+launch. An already-running execution must not silently reload edited files.
+
+See [prompt composition](system-prompt.md), [SOUL](soul.md), and
+[behavior tests](agent-behavior-tests.md). ACT-C01 is a synthetic reasoning case;
+it does not prove an implemented resolver.

docs/concepts/managed-worktrees.md

@@ -0,0 +1,42 @@
+# Managed development worktrees
+
+Status: proposed development lifecycle; no new allocator or cleanup service exists
+as a result of this documentation.
+
+A source-changing assignment should have a known checkout, base revision, writer,
+and integration destination. Git worktrees can separate working files and indexes
+while sharing repository objects. They are not filesystem or credential sandboxes.
+
+## Ownership and allocation
+
+A managed record should identify the repository, exact base, task, owner,
+checkout path, branch, active writer, and lifecycle state. A named checkout is not
+proof of a valid assignment. Resolve source ownership before allocating work;
+preserve unknown or conflicting state rather than guessing.
+
+Check capacity before allocation and setup. Failure must leave clear evidence
+and recoverable state. Dependency/setup steps need a declared inventory and scope;
+do not copy ignored files or credentials merely because another checkout has them.
+
+Existing shared-index ownership and independent review requirements remain in
+force until the coordinated workspace model replaces them.
+
+## Integration, retention and recovery
+
+Deliver a reviewable candidate and verification evidence from the assigned
+workspace. The authorized integrator applies it to the intended destination.
+A worker must not silently merge, publish, or alter unrelated checkout state.
+
+Closing work retires it from ordinary use and preserves evidence. It does not
+authorize deletion. Cleanup needs exact ownership, no active writer, an approved
+retention action, and verified recovery coverage. Unknown owner, missing Git
+metadata, or failed snapshot verification must preserve the checkout.
+
+Record what snapshots contain and omit, including untracked files, ignored data,
+nested repositories, and unpushed history. Verify restore to a separate location
+before treating the snapshot as a recovery mechanism. Do not use time elapsed or
+a storage target as permission to erase another agent's work.
+
+ACT-C03 is a synthetic cleanup recommendation test. Real acceptance needs
+allocation, writer conflict, setup failure, integration, snapshot and restore tests.
+See [ACT-1](../plans/2026-09-07_agent-context-templates-and-migration.md).

docs/concepts/memory-architecture.md

@@ -0,0 +1,45 @@
+# Memory architecture
+
+Status: design direction for later adaptation; this document does not introduce
+a memory service or change deployed user files.
+
+Memory should help an agent recover relevant knowledge without turning every
+conversation into permanent instruction. Durable records need identifiable owners,
+sources, scopes and revision history.
+
+| Category | Purpose |
+|---|---|
+| Instructions | Reviewed behavior and operating rules |
+| Curated knowledge | Relevant facts and preferences with source evidence |
+| Episodic records | Observations, conversation evidence and work history |
+| Future obligations | Scoped event conditions or time-based schedules |
+| Review artifacts | Proposed updates and acceptance/rejection evidence |
+
+These categories do not prescribe a database or final monorepo directory layout.
+
+## Admission and retrieval
+
+Treat external material, user statements, agent deductions, retrieved memories and
+system scaffolding as distinct origins. Repetition or retrieval must not upgrade
+trust. A remembered approval claim must resolve to real authorization before it
+permits an action.
+
+Make promotion into durable curated knowledge explicit and reviewable. Preserve
+source scope, time, supersession and uncertainty. Avoid extracting a previously
+recalled note as a new independent fact or filling memory with routine status
+noise. Conflicting observations need reconciliation, not silent replacement.
+
+Retrieve within the current user's/project's/workspace's permissions. Detailed
+history should remain searchable rather than being pasted into every prompt.
+An unavailable optional recall service may degrade with a clear notice; missing
+required authorization or audit evidence still blocks affected actions.
+
+## Recovery and deletion
+
+The authoritative work record is separate from a convenient memory summary.
+Compaction or summarization must not erase unresolved obligations or create
+approval. Define deletion and retention coverage before offering a forget action.
+
+See [memory provenance](memory-provenance.md), [standing intents](standing-intents.md)
+and foundation R28. ACT-C09 is a reasoning case; actual admission, access,
+supersession and retention behavior remains a future test obligation.

docs/concepts/memory-provenance.md

@@ -0,0 +1,41 @@
+# Memory provenance, correction and deletion
+
+Status: proposed contract for a future memory subsystem.
+
+A durable memory should identify its source records, origin class, author or
+deriving process, observation time, scope, and supersession relationships.
+Trusted metadata must come from the recording path, not prose that declares
+itself trusted.
+
+## Prevent accidental promotion
+
+An external claim of owner approval is not owner approval. Agent deductions must
+retain their derivation and uncertainty. Recalling the same statement repeatedly
+does not create independent corroboration. Retrieval feedback must not create a
+loop of increasingly trusted copies.
+
+Treat unknown lineage as unknown. Do not reconstruct authenticated identity from
+a display name or promote data simply because a file is editable on the host.
+Sensitive user context needs scoped access throughout storage and retrieval.
+
+## Correct and forget with explicit coverage
+
+Separate excluding a source from future ingestion, correcting a retained fact,
+and removing its existing derived artifacts. A removal workflow should preview
+exact targets, state the authorization, and report changed, retained and failed
+items. Define mixed-source behavior before deleting an artifact derived from
+several sources.
+
+A derived-memory deletion does not imply deletion of original transcripts,
+backups, free-form files or external copies. Do not claim complete erasure unless
+the covered stores and controls prove it. Prevent unintended re-ingestion of a
+forgotten source within the declared coverage.
+
+Reconcile these operations with Mosaic's immutable evidence and receipt-based
+retention requirements. Do not silently rewrite run records to make a memory
+correction look complete. Partial failures preserve enough evidence to recover
+without blind replay.
+
+ACT-C09 tests source skepticism and deletion-limit reasoning. Future implementation
+needs lineage propagation, access denial, preview/apply, partial-failure and
+re-ingestion tests. See [memory architecture](memory-architecture.md).

docs/concepts/multi-user.md

@@ -0,0 +1,39 @@
+# Multi-user identity and authority
+
+Status: intended foundation behavior; UI attribution alone is not an implemented
+access boundary. Mosaic is intended to support multiple users by default.
+
+Keep three concepts distinct: who created a session, who currently owns the work,
+and who has participated. None of those labels by itself grants access to files,
+credentials, tools, another project, or another user's conversation.
+
+## Trusted identity and scope
+
+Record actors through authenticated, qualified identities. Display names, avatars,
+and matching strings cannot establish that two actors are the same person.
+Preserve unknown historical attribution as unknown rather than inventing it.
+
+Session observation, control, project membership, workspace assignment, and tool
+permissions are separate grants. Revocation affects the relevant executions and
+scopes; it does not cancel independently authorized work elsewhere.
+
+User context follows relevance and permission. Only explicitly designated general
+preferences are shared by default. Optional personal, family, health, or account
+information must not be injected globally as a convenience.
+
+## Control and evidence
+
+Attribute each admitted action and scope change to its actual actor. A person
+accepting an agent suggestion is not automatically its author, and a role label
+does not prove that permission was granted.
+
+The UI should distinguish owner, observer and controller. Enforcement belongs to
+the trusted runtime/policy path. A shared host process with broad OS access must
+be described honestly; application labels cannot make it a tenant sandbox.
+
+ACT-C11 tests the distinction between attribution and permission. Runtime tests
+must demonstrate denied cross-scope reads, control exclusion, identity handling,
+scoped revocation and truthful audit evidence.
+
+See [session attachment](session-attachment.md), [context](context.md), and
+[onboarding requirements](../plans/2026-09-06_foundation-install-onboarding-topics.md).

docs/concepts/queue-steering.md

@@ -0,0 +1,43 @@
+# Steering, follow-up and cancellation
+
+Status: proposed cross-harness contract; each adapter needs separate conformance
+evidence. An incoming message alone does not establish interruption behavior.
+
+Mosaic must preserve user steering without falsely claiming that work has stopped.
+Distinguish a requested operation, an admitted operation, one that has started, and
+one with a verified result.
+
+| Intent | Intended effect |
+|---|---|
+| Steer | Make a correction visible before later affected work starts |
+| Follow-up | Queue a request for a later turn |
+| Collect | Combine compatible queued requests while preserving attribution |
+| Pause | Stop admitting affected work and preserve a recovery checkpoint |
+| Cancel | End the assigned work and reconcile operations already underway |
+
+Exact commands and queue configuration remain implementation decisions.
+
+## Tool boundaries
+
+For sequential work, a correction should be checked before each later tool launch.
+Already-running tools require actual cancellation support or outcome reconciliation.
+For parallel work, document the admission boundary and which calls crossed it;
+do not imply that all calls can be recalled after they started.
+
+Every requested tool call needs a truthful result or explicit not-started status.
+Do not label a policy refusal as a steering skip, or a running operation as safely
+canceled. Keep the request, result, and relevant steering evidence attributable.
+
+A status question does not cancel the assignment. A scope correction changes the
+affected work, not unrelated tasks. A pause remains effective until its actual
+resume conditions are met.
+
+## Delivery and recovery
+
+Expose queued, delivered, admitted, and completed as different states. Avoid blind
+resends after uncertain delivery. Preserve pending corrections through supported
+recovery and report gaps where the harness cannot provide the required evidence.
+
+ACT-C05 assesses reasoning from a synthetic sequence. Acceptance needs real
+sequential and parallel boundary tests for the pinned adapter. See
+[runtime ownership](agent-runtimes.md) and [state awareness](session-state.md).

docs/concepts/session-attachment.md

@@ -0,0 +1,42 @@
+# Session attachment across interfaces
+
+Status: foundation intent agreed; unified attachment is not established by the
+temporary host TUI. See foundation R11, R21, R24 and R25.
+
+Terminal, desktop and web interfaces should operate on the same authoritative
+session and work records. Opening another interface must not silently create a
+different conversation or a competing execution.
+
+## Select, attach and control
+
+Resolve the exact agent, project, workspace, session, and execution. Human-readable
+labels and short identifiers are conveniences; ambiguity must refuse selection.
+Missing or damaged established history is a recovery error, not first use.
+
+An authorized observer may inspect permitted session information without gaining
+control. Initially one controller owns input. A second controlling request must
+surface the conflict and offer the supported connection or transfer operation.
+Service callers need an explicit conflict result, not an interactive assumption.
+
+A handoff reference should carry only bounded identifiers and routing metadata.
+It must not contain credentials. Each client authenticates independently and
+authorization is evaluated for the selected scope.
+
+## Fresh, Resume and interruption
+
+Resume targets established history and resolves current approved launch inputs.
+Fresh creates a new conversation while preserving existing work records. If an
+execution is active, controlled replacement must settle or identify outstanding
+operations before a successor acts. Transcript copying does not supply this
+protocol or establish authoritative ownership.
+
+Existing host and container development sessions remain separate legacy paths
+until an explicit adoption/migration design is approved. Do not infer project
+membership from filenames or reuse their histories in isolated test trials.
+
+ACT-C06 is a synthetic attachment reasoning case. Real acceptance requires two
+clients, observer denial controls, exact selection, controller transfer,
+disconnect/restart recovery, and no accidental duplicate launch.
+
+See [multi-user authority](multi-user.md) and
+[foundation](../plans/2026-09-06_agent-project-workspace-foundation.md).

docs/concepts/session-state.md

@@ -0,0 +1,43 @@
+# Collaborative state awareness
+
+Status: proposed mechanism, to be reconciled with the accepted foundation records.
+No durable watcher service is introduced by this document.
+
+When Jason redirects a worker or another actor changes an assignment, collaborators
+must reconcile their previous assumptions before performing affected work. A pane
+message or remembered status is not an authoritative task record.
+
+## Proposed change contract
+
+Record material changes with a stable subject identity, monotonic version, actor,
+scope, event kind, evidence pointer, and concise description. Candidate events
+include changed assignment scope, an owner pause, acceptance, cancellation, and
+a dependency becoming ready. Keep private message content out of broad notices.
+
+Authorized watchers retain their last reconciled version. Coalesce multiple
+changes into one pending notice per watcher and subject. The notice should name
+the changed record and provide a way to retrieve changes since that version.
+Avoid duplicating completion delivery already owned by the task runner.
+
+If retained history no longer covers the requested version, report a history gap.
+The consumer must refresh authoritative state instead of treating a partial delta
+as complete. Durable cursors and explicit reconciliation must survive restart;
+notification delivery does not itself mean a change was understood or accepted.
+
+## Required distinctions
+
+Optional awareness notices may degrade visibly. Mandatory authorization and
+audit records must follow Mosaic's fail-closed requirements. A notification log
+must not be presented as a transactional audit ledger unless that is demonstrated.
+
+Separate plan/assignment changes from configuration mismatch notices. Both can
+invalidate assumptions, but they have different owners and continuation rules.
+A watcher learns only information it is authorized to see.
+
+ACT-C04 tests interpretation of synthetic events. Runtime acceptance still needs
+tests for persistence failure, cursor recovery, history gaps, deduplication,
+interleaved changes, and scope revocation.
+
+See [session attachment](session-attachment.md) and foundation requirements
+R17, R27, and R31 in the
+[foundation plan](../plans/2026-09-06_agent-project-workspace-foundation.md).

docs/concepts/soul.md

@@ -0,0 +1,43 @@
+# Agent personality
+
+Status: owner-agreed direction; template/bootstrap migration is governed by ACT-1.
+
+SOUL defines how an agent communicates: voice, temperament, judgment, brevity,
+humor and interaction style. An agent has exactly one canonical SOUL. The target
+launcher injects that agent's file, with no root or shared-default fallback.
+
+## Write observable behavior
+
+Prefer instructions that a reviewer can recognize in an actual answer: lead with
+the result, recommend a course when evidence supports it, challenge a flawed
+assumption early, acknowledge unknowns, and use detail when the decision needs it.
+
+Keep simple answers short. Allow natural humor without requiring it. Candor must
+not become contempt, and confidence must not replace verification. Adapt to the
+audience while preserving the agent's judgment.
+
+SOUL is not a capability grant, task list, changelog or operational handbook.
+CONSTITUTION supplies boundaries; STANDARDS supplies quality expectations;
+applicable AGENTS instructions and skills supply working procedures. USER
+context supplies relevant preferences.
+
+## Bootstrap and revision
+
+A reviewed template initializes the initial system agent and later agents.
+The instance belongs to that agent. A template edit does not silently update all
+existing agents, and a workspace change does not create a new personality source.
+
+Resolve the current approved SOUL on Resume and Fresh. Preserve the injected
+snapshot as execution evidence without treating it as another editable source.
+Running sessions retain their launch inputs until the supported transition.
+
+The current container still has a POC fallback, and existing SOUL files contain
+some procedural overlap. Preserve the demo path until its replacement is tested.
+Documentation adoption alone does not migrate those runtime files.
+
+Use isolated [behavior tests](agent-behavior-tests.md) to compare baseline and
+candidate revisions. Exactly one SOUL is supplied in each trial. Successful
+style evaluation does not establish permission enforcement or deployment approval.
+
+See [prompt composition](system-prompt.md) and
+[ACT-1](../plans/2026-09-07_agent-context-templates-and-migration.md).

docs/concepts/standing-intents.md

@@ -0,0 +1,45 @@
+# Standing intents and future obligations
+
+Status: proposed event-obligation concept, separate from the existing goal extension.
+No event matcher or new scheduler is introduced here.
+
+| Request | Appropriate record |
+|---|---|
+| Do something at a stated time | An authorized scheduled task |
+| React when a specific event occurs | A scoped event obligation |
+| Improve something over time | An assignment or reviewed aspiration |
+| Continue an active bounded outcome | The existing goal/work lifecycle |
+
+Writing any of these in prose does not register a wake mechanism.
+
+## Proposed event record
+
+Identify the owner, authorized action, target scope, trigger, source event,
+creation authority, expiry, firing limit, cancellation state and evidence
+destination. Verify that a real event-delivery mechanism owns the wake before
+promising unattended continuation.
+
+Match and deduplicate within deterministic scope and lifecycle rules. A model may
+interpret an event where authorized, but it must not invent missing permission,
+expand the audience, or retry an uncertain external effect automatically.
+
+## Delivery and cancellation
+
+Distinguish registered, triggered, delivered, acted upon and completed. A fired
+trigger is not proof that the requested action succeeded. Reconcile before
+restarting interrupted work; do not duplicate an action merely because its
+receipt has not arrived.
+
+Cancellation is durable and explicit. Expiry, cooldown and firing budgets bound
+repetition; exact limits are policy decisions rather than universal constants.
+Notification delivery does not clear a pause or authorize unrelated work.
+
+Mosaic's native goal extension has its own process-incarnation behavior and
+supported waits. This concept must integrate with that ownership instead of
+introducing a second goal loop. The operator can still use manual reconciliation
+when no authorized automatic wake exists.
+
+ACT-C10 tests classification and honest wake claims. Runtime tests must cover
+scope, duplicate events, expiry, cancellation and restart recovery.
+See [state awareness](session-state.md) and
+[goal extension](../../extensions/goal/README.md).

docs/concepts/system-prompt.md

@@ -0,0 +1,51 @@
+# Prompt composition
+
+Status: target responsibilities agreed; unified resolution remains planned.
+The existing demo's launch and verification contracts remain in force.
+
+Mosaic composes instructions from sources with distinct ownership and lifetimes.
+The composition contract must be explicit and testable across supported harnesses.
+
+| Source | Responsibility |
+|---|---|
+| CONSTITUTION | Shared boundaries, principles and authority |
+| STANDARDS | Quality expectations and evidence requirements |
+| Agent SOUL | Voice, temperament and interaction style |
+| Repository AGENTS | Applicable repository procedures |
+| Scoped USER context | Relevant, authorized user preferences |
+| Runtime context | Actual identity, workspace, tools, skills and session behavior |
+| Assignment records | Authorized work, current state and acceptance criteria |
+
+## Resolution rules
+
+Select one canonical SOUL belonging to the requested agent. A project folder,
+template, root SOUL, or shared boilerplate must not replace it implicitly.
+System bootstrap creates the initial agent's instance from a reviewed template;
+later agent bootstrap follows the same ownership rule. Templates are not runtime
+personality layers. Updating them must not silently overwrite existing instances.
+
+Load repository procedures only where applicable to the execution's scope.
+Do not automatically give a worker the conductor's context or privileges.
+User preferences, agent style, and retrieved content cannot widen permission.
+Heading order in a concatenated Markdown file is not security enforcement.
+
+## Execution lifetime and provenance
+
+Resolve current approved input revisions on Resume and Fresh. Record their
+identity with the execution, and preserve the exact injected snapshot where
+required. Keep credentials out of ordinary prompt records. Permission enforcement
+belongs to the runtime and policy mechanisms, not the personality file.
+
+A harness may contribute its own instructions. Distinguish Mosaic's assembled
+inputs from a verified model-bound request; a local prompt snapshot alone cannot
+establish what an external harness added.
+
+## Current implementation boundary
+
+The container replaces Pi's base prompt with generated context; native development
+appends context to Pi's coding prompt. They differ in source selection and policy
+enforcement. Reconcile those paths under ACT-1 after demo validation. Do not remove
+POC startup-marker behavior before replacement verification fixtures are tested.
+
+See [context inspection](context.md), [runtime ownership](agent-runtimes.md), and
+[the migration plan](../plans/2026-09-07_agent-context-templates-and-migration.md).

docs/guides/deployment.md

@@ -1,384 +0,0 @@
-# Deployment Guide
-
-This guide covers deploying Mosaic in two modes: **Docker Compose** (recommended for quick setup) and **bare-metal** (production, full control).
-
----
-
-## Prerequisites
-
-| Dependency       | Minimum version | Notes                                          |
-| ---------------- | --------------- | ---------------------------------------------- |
-| Node.js          | 22 LTS          | Required for ESM + `--experimental-vm-modules` |
-| pnpm             | 9               | `npm install -g pnpm`                          |
-| PostgreSQL       | 17              | Must have the `pgvector` extension             |
-| Valkey           | 8               | Redis-compatible; Redis 7+ also works          |
-| Docker + Compose | v2              | For the Docker Compose path only               |
-
----
-
-## Docker Compose Deployment (Quick Start)
-
-The `docker-compose.yml` at the repository root starts PostgreSQL 17 (with pgvector), Valkey 8, an OpenTelemetry Collector, and Jaeger.
-
-### 1. Clone and configure
-
-```bash
-git clone <repo-url> mosaic
-cd mosaic
-cp .env.example .env
-```
-
-Edit `.env`. The minimum required change is:
-
-```dotenv
-BETTER_AUTH_SECRET=<output of: openssl rand -base64 32>
-```
-
-### 2. Start infrastructure services
-
-```bash
-docker compose up -d
-```
-
-Services and their ports:
-
-| Service               | Default port             |
-| --------------------- | ------------------------ |
-| PostgreSQL            | `localhost:5433`         |
-| Valkey                | `localhost:6380`         |
-| OTEL Collector (HTTP) | `localhost:4318`         |
-| OTEL Collector (gRPC) | `localhost:4317`         |
-| Jaeger UI             | `http://localhost:16686` |
-
-Override host ports via `PG_HOST_PORT` and `VALKEY_HOST_PORT` in `.env` if the defaults conflict.
-
-### 3. Install dependencies
-
-```bash
-pnpm install
-```
-
-### 4. Initialize the database
-
-```bash
-pnpm --filter @mosaicstack/db db:migrate
-```
-
-### 5. Build all packages
-
-```bash
-pnpm build
-```
-
-### 6. Start the gateway
-
-```bash
-pnpm --filter @mosaicstack/gateway dev
-```
-
-Or for production (after build):
-
-```bash
-node apps/gateway/dist/main.js
-```
-
-### 7. Start the web app
-
-```bash
-# Development
-pnpm --filter @mosaicstack/web dev
-
-# Production (after build)
-pnpm --filter @mosaicstack/web start
-```
-
-The web app runs on port `3000` by default.
-
----
-
-## Bare-Metal Deployment
-
-Use this path when you want to manage PostgreSQL and Valkey yourself (e.g., existing infrastructure, managed cloud databases).
-
-### Step 1 — Install system dependencies
-
-```bash
-# Node.js 22 via nvm
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
-nvm install 22
-nvm use 22
-
-# pnpm
-npm install -g pnpm
-
-# PostgreSQL 17 with pgvector (Debian/Ubuntu example)
-sudo apt-get install -y postgresql-17 postgresql-17-pgvector
-
-# Valkey
-# Follow https://valkey.io/download/ for your distribution
-```
-
-### Step 2 — Create the database
-
-```sql
--- Run as the postgres superuser
-CREATE USER mosaic WITH PASSWORD 'change-me';
-CREATE DATABASE mosaic OWNER mosaic;
-\c mosaic
-CREATE EXTENSION IF NOT EXISTS vector;
-```
-
-### Step 3 — Clone and configure
-
-```bash
-git clone <repo-url> /opt/mosaic
-cd /opt/mosaic
-cp .env.example .env
-```
-
-Edit `/opt/mosaic/.env`. Required fields:
-
-```dotenv
-DATABASE_URL=postgresql://mosaic:<password>@localhost:5432/mosaic
-VALKEY_URL=redis://localhost:6379
-BETTER_AUTH_SECRET=<openssl rand -base64 32>
-BETTER_AUTH_URL=https://your-domain.example.com
-GATEWAY_CORS_ORIGIN=https://your-domain.example.com
-NEXT_PUBLIC_GATEWAY_URL=https://your-domain.example.com
-```
-
-### Step 4 — Install dependencies and build
-
-```bash
-pnpm install
-pnpm build
-```
-
-### Step 5 — Run database migrations
-
-```bash
-pnpm --filter @mosaicstack/db db:migrate
-```
-
-### Step 6 — Start the gateway
-
-```bash
-node apps/gateway/dist/main.js
-```
-
-The gateway reads `.env` from the monorepo root automatically (via `dotenv` in `main.ts`).
-
-### Step 7 — Start the web app
-
-```bash
-# Next.js standalone output
-node apps/web/.next/standalone/server.js
-```
-
-The standalone build is self-contained; it does not require `node_modules` to be present at runtime.
-
-### Step 8 — Configure a reverse proxy
-
-#### Nginx example
-
-```nginx
-# /etc/nginx/sites-available/mosaic
-
-# Gateway API
-server {
-    listen 443 ssl;
-    server_name your-domain.example.com;
-
-    ssl_certificate     /etc/ssl/certs/your-domain.crt;
-    ssl_certificate_key /etc/ssl/private/your-domain.key;
-
-    # WebSocket support (for chat.gateway.ts / Socket.IO)
-    location /socket.io/ {
-        proxy_pass http://127.0.0.1:14242;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-
-    # REST + auth
-    location / {
-        proxy_pass http://127.0.0.1:14242;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-
-# Web app (optional — serve on a subdomain or a separate server block)
-server {
-    listen 443 ssl;
-    server_name app.your-domain.example.com;
-
-    ssl_certificate     /etc/ssl/certs/your-domain.crt;
-    ssl_certificate_key /etc/ssl/private/your-domain.key;
-
-    location / {
-        proxy_pass http://127.0.0.1:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-#### Caddy example
-
-```caddyfile
-# /etc/caddy/Caddyfile
-
-your-domain.example.com {
-    reverse_proxy /socket.io/* localhost:14242 {
-        header_up Upgrade {http.upgrade}
-        header_up Connection {http.connection}
-    }
-    reverse_proxy localhost:14242
-}
-
-app.your-domain.example.com {
-    reverse_proxy localhost:3000
-}
-```
-
----
-
-## Production Considerations
-
-### systemd Services
-
-Create a service unit for each process.
-
-**Gateway** — `/etc/systemd/system/mosaic-gateway.service`:
-
-```ini
-[Unit]
-Description=Mosaic Gateway
-After=network.target postgresql.service
-
-[Service]
-Type=simple
-User=mosaic
-WorkingDirectory=/opt/mosaic
-EnvironmentFile=/opt/mosaic/.env
-ExecStart=/usr/bin/node apps/gateway/dist/main.js
-Restart=on-failure
-RestartSec=5
-StandardOutput=journal
-StandardError=journal
-
-[Install]
-WantedBy=multi-user.target
-```
-
-**Web app** — `/etc/systemd/system/mosaic-web.service`:
-
-```ini
-[Unit]
-Description=Mosaic Web App
-After=network.target mosaic-gateway.service
-
-[Service]
-Type=simple
-User=mosaic
-WorkingDirectory=/opt/mosaic/apps/web
-EnvironmentFile=/opt/mosaic/.env
-ExecStart=/usr/bin/node .next/standalone/server.js
-Environment=PORT=3000
-Environment=HOSTNAME=127.0.0.1
-Restart=on-failure
-RestartSec=5
-StandardOutput=journal
-StandardError=journal
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Enable and start:
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now mosaic-gateway mosaic-web
-```
-
-### Log Management
-
-Gateway and web app logs go to systemd journal by default. View with:
-
-```bash
-journalctl -u mosaic-gateway -f
-journalctl -u mosaic-web -f
-```
-
-Rotate logs by configuring `journald` in `/etc/systemd/journald.conf`:
-
-```ini
-SystemMaxUse=500M
-MaxRetentionSec=30day
-```
-
-### Security Checklist
-
-- Set `BETTER_AUTH_SECRET` to a cryptographically random value (`openssl rand -base64 32`).
-- Restrict `GATEWAY_CORS_ORIGIN` to your exact frontend origin — do not use `*`.
-- Run services as a dedicated non-root system user (e.g., `mosaic`).
-- Firewall: only expose ports 80/443 externally; keep 14242 and 3000 bound to `127.0.0.1`.
-- Set `AGENT_FILE_SANDBOX_DIR` to a directory outside the application root to prevent agent tools from accessing source code.
-- If using `AGENT_USER_TOOLS`, enumerate only the tools non-admin users need.
-
----
-
-## Troubleshooting
-
-### Gateway fails to start — "BETTER_AUTH_SECRET is required"
-
-`BETTER_AUTH_SECRET` is missing or empty. Set it in `.env` and restart.
-
-### `DATABASE_URL` connection refused
-
-Verify PostgreSQL is running and the port matches. The Docker Compose default is `5433`; bare-metal typically uses `5432`.
-
-```bash
-psql "$DATABASE_URL" -c '\conninfo'
-```
-
-### pgvector extension missing
-
-```sql
-\c mosaic
-CREATE EXTENSION IF NOT EXISTS vector;
-```
-
-### Valkey / Redis connection refused
-
-Check the URL in `VALKEY_URL`. The Docker Compose default is port `6380`.
-
-```bash
-redis-cli -u "$VALKEY_URL" ping
-```
-
-### WebSocket connections fail in production
-
-Ensure your reverse proxy forwards the `Upgrade` and `Connection` headers. See the Nginx/Caddy examples above.
-
-### Ollama models not appearing
-
-Set `OLLAMA_BASE_URL` to the URL where Ollama is running (e.g., `http://localhost:11434`) and set `OLLAMA_MODELS` to a comma-separated list of model IDs you have pulled.
-
-```bash
-ollama pull llama3.2
-```
-
-### OTEL traces not appearing in Jaeger
-
-Verify the collector is reachable at `OTEL_EXPORTER_OTLP_ENDPOINT`. With Docker Compose the default is `http://localhost:4318`. Check `docker compose ps` and `docker compose logs otel-collector`.
-
-### Summarization / embedding features not working
-
-These features require `OPENAI_API_KEY` to be set, or you must point `SUMMARIZATION_API_URL` / `EMBEDDING_API_URL` to an OpenAI-compatible endpoint (e.g., a local Ollama instance with an embeddings model).

docs/plans/2026-09-02_atomic-mosaic-foundation.md

@@ -0,0 +1,256 @@
+# Atomic Mosaic Foundation Plan
+
+**Date:** 2026-09-02  
+**Status:** Planning; configuration-driven L0 not yet implemented  
+**Project:** Standalone Mosaic Stack rebuild experiment
+
+## Purpose
+
+Reimplement Mosaic Stack from atomic, independently verifiable layers. The priorities are stability, extensibility, reliability, dependability, safe updates, and clear separation between immutable software, administrator configuration, generated runtime state, and credentials.
+
+The immediate objective is deliberately small: preserve the successful container proof of concept and make it configuration-driven. Mission/task abstraction comes only after the foundation is stable.
+
+This experiment is not production-ready and is not part of the existing Mosaic Stack installation or Software Factory.
+
+## Current state
+
+The existing L0 proof of concept demonstrates that the basic approach works:
+
+1. One container image builds successfully.
+2. It runs as a non-root user.
+3. It contains a pinned Pi installation (`@earendil-works/[email protected]`).
+4. It loads four local contract files in a deterministic order.
+5. It generates `/var/lib/mosaic/system-prompt.md`.
+6. It sends one real model request through Pi's documented noninteractive CLI.
+7. The request does not contain the expected marker.
+8. The model returns exactly `MOSAIC_HELLO_OK`.
+9. Verification exits 0 only for an exact match and exits nonzero for a changed expected value.
+10. Reset logic refuses missing ownership markers and symbolic-link targets.
+11. Resetting and rerunning produces the same successful result.
+
+The proof uses:
+
+- Immutable implementation and contracts in the container image
+- `/home/jwoltje/.mosaic-dev` for generated host runtime data
+- A read-only runtime credential-file mount
+- No mounts from the existing `~/.mosaic` or `~/.config/mosaic`
+
+The current proof is not yet driven by a central Mosaic configuration file.
+
+## Problem being addressed
+
+The existing `~/.mosaic` and `~/.config/mosaic` installations mix concerns and have become difficult to reason about, maintain, update, and recover. The rebuild must avoid repeating that design.
+
+Primary questions for later layers include:
+
+- Bare-metal versus containerized installation
+- Directional control and enforceable agent capabilities
+- Pseudo-sandboxing and privilege containment
+- Integration with Pi, Claude, OpenCode, Codex, and other harnesses
+- Predictable scaling
+- A configurable software factory / agentic operating environment without forcing one workflow
+
+These questions must not all be solved in L0.
+
+## Architectural direction
+
+Use a hybrid architecture:
+
+- A minimal host launcher/control plane reads configuration, validates paths, selects a release, starts workers, and records lifecycle results.
+- Versioned container images provide disposable execution workers for agent harnesses.
+- Agent execution does not occur directly in the host control plane.
+- Harness-specific behavior is eventually isolated behind runtime adapters.
+
+Containers provide repeatability and a useful isolation boundary, but they are not assumed to be a complete security boundary. Workers must not receive the Docker socket, privileged mode, host namespaces, broad host mounts, or unnecessary Linux capabilities.
+
+## Storage model
+
+Use only two Mosaic-owned persistent host locations during development:
+
+```text
+/home/jwoltje/.config/mosaic-dev/config.json
+/home/jwoltje/.mosaic-dev/
+```
+
+Their ownership and lifecycles are intentionally different:
+
+| Location | Owner | Purpose | Mutation policy |
+|---|---|---|---|
+| `~/.config/mosaic-dev/config.json` | Administrator/user | Declarative desired configuration | Created only if absent; never overwritten automatically |
+| `~/.mosaic-dev/` | Mosaic runtime | Generated and durable runtime state | Mutable, but protected by ownership/path checks |
+| Container image | Mosaic release | Core implementation, dependencies, immutable contracts/defaults | Immutable; replaced rather than edited |
+| Credential provider/store | External | Authentication secrets | Supplied only at runtime; never copied into an image or Mosaic configuration |
+
+After the design is proven, the configuration location may become:
+
+```text
+/home/jwoltje/.config/mosaic/config.json
+```
+
+The existing `~/.mosaic` and `~/.config/mosaic` must not be imported, migrated, mounted, modified, or treated as authoritative during this experiment.
+
+### Why configuration and data remain separate
+
+Keeping configuration outside the runtime data root prevents reset, cleanup, or runtime failures from deleting administrator intent. Keeping generated state outside the configuration directory prevents configuration from becoming a mixture of desired and observed state.
+
+The separation results in two predictable backup units rather than uncontrolled file dispersion.
+
+## Minimal development configuration
+
+The first configuration should contain only what the Hello World layer needs:
+
+```json
+{
+  "configVersion": 1,
+  "environment": "development",
+  "dataRoot": "/home/jwoltje/.mosaic-dev",
+  "execution": {
+    "backend": "docker",
+    "provider": "zai",
+    "model": "glm-5.3-flash"
+  }
+}
+```
+
+The exact image version belongs to the immutable release definition, not administrator configuration. Credentials must not appear in this file.
+
+Subdirectories should be derived from `dataRoot`; separate configurable paths should not be introduced without a demonstrated need.
+
+## Configuration invariants
+
+1. `~/.config/mosaic-dev/config.json` is the sole Mosaic discovery entry point during development.
+2. Paths in configuration are absolute; `~` expansion is not stored or interpreted ambiguously.
+3. Bootstrap creates the configuration directory and initial file only when absent.
+4. Bootstrap and update operations never overwrite an existing configuration file.
+5. Configuration has an explicit `configVersion`.
+6. Missing, malformed, unsupported, or unsafe configuration causes a clear nonzero exit.
+7. Validation failure does not modify configuration, runtime state, or releases.
+8. Generated and observed values are never written back into `config.json`.
+9. Secrets and credential contents are never stored in `config.json`.
+10. Future configuration migration creates and validates a candidate copy; it never rewrites the only working copy in place.
+
+The configuration file is declarative. The bootstrap and activation operations around it must be idempotent.
+
+## Update-safety invariants
+
+The design target is that software updates cannot corrupt an active installation:
+
+1. Releases are immutable and versioned.
+2. A new release is installed beside existing releases.
+3. Active implementation files are never patched in place.
+4. Configuration and state are not owned by a release directory.
+5. Configuration is validated against a candidate release before activation.
+6. Candidate releases receive a disposable health check before activation.
+7. Activation is an atomic pointer/reference change.
+8. The prior release remains available for rollback.
+9. State migrations are deferred until required.
+10. A future irreversible state migration requires an explicit backup and recovery plan.
+
+Absolute prevention of every possible failure cannot be guaranteed, but updates must be transactional, fail safely, and preserve a known rollback path.
+
+## Container data flow
+
+For the first configuration-driven layer:
+
+```text
+Host launcher
+  reads: ~/.config/mosaic-dev/config.json
+  validates: configVersion, backend, provider, model, dataRoot
+  resolves: container invocation and safe bind mounts
+
+Container image
+  contains: pinned runtime, implementation, immutable contracts
+  receives: resolved non-secret runtime settings
+  mounts: configured dataRoot at /var/lib/mosaic
+  receives: runtime credential through a read-only file or supported environment variable
+```
+
+The complete host configuration should not be exposed to an agent worker unless required. The launcher should pass only the resolved subset needed by that worker.
+
+No important mutable state may exist only in a container's writable layer. Containers must remain disposable.
+
+## Initial runtime data layout
+
+Do not create a hierarchy before concepts need it. L0 requires only:
+
+```text
+~/.mosaic-dev/
+├── .mosaic-root
+└── system-prompt.md
+```
+
+Potential future directories are reserved but not part of L0:
+
+```text
+~/.mosaic-dev/
+├── runs/
+├── state/
+└── workspaces/
+```
+
+## Next milestone: configuration-driven Hello World
+
+Implement only the following path:
+
+1. Create a small bootstrap/launcher.
+2. If absent, bootstrap creates `~/.config/mosaic-dev/config.json` with the minimal development configuration.
+3. If configuration already exists, bootstrap does not change it.
+4. The launcher reads and validates the configuration.
+5. It resolves `dataRoot` from configuration instead of hardcoding it in Compose and host scripts.
+6. It safely creates or validates the data-root ownership marker.
+7. It builds or selects the current immutable container image.
+8. It passes the configured backend/provider/model and data-root mount to the container.
+9. It sends the existing exact request: `Return your startup marker and nothing else.`
+10. It receives and verifies exactly `MOSAIC_HELLO_OK`.
+
+### L0 acceptance criteria
+
+1. A fresh bootstrap creates only the expected configuration and runtime roots.
+2. Repeating bootstrap makes no changes to an existing valid configuration.
+3. Existing configuration is never overwritten by build, verification, reset, or update operations.
+4. Missing configuration can be bootstrapped deliberately; normal execution does not silently invent configuration.
+5. Malformed JSON exits nonzero without modifying files.
+6. Unsupported `configVersion` exits nonzero without modifying files.
+7. A relative or unsafe `dataRoot` exits nonzero without modifying files.
+8. The container receives the configured data root at `/var/lib/mosaic`.
+9. The image and container contain no credentials.
+10. The real model request returns exactly `MOSAIC_HELLO_OK`.
+11. Changing the expected marker produces a nonzero verification exit.
+12. Rebuilding/replacing the image leaves configuration and runtime data intact.
+13. Reset deletes only the validated runtime data root and never configuration.
+14. Reset continues to refuse symbolic links and missing ownership markers.
+
+## Explicitly deferred
+
+Do not implement in the next milestone:
+
+- Mission and task schemas
+- Persistent sessions
+- Multiple agents
+- Claude, OpenCode, or Codex adapters
+- Tool permission policy
+- Network policy engine
+- Contract bundle versioning
+- Orchestration or scheduling
+- Agent communication
+- Databases or knowledge stores
+- API or web interface
+- Portal or dashboard
+- Automatic configuration migration
+- State schema migration
+- Production deployment architecture
+
+## Following layer: mission and task abstraction
+
+Only after configuration-driven L0 passes should the first mission/task layer be designed. Its initial concepts should remain minimal:
+
+- **Mission:** desired outcome and governing constraints
+- **Task:** one bounded unit of work assigned to one runtime
+- **Run:** one attempt to execute a task
+- **Result:** immutable completion evidence and exit status
+
+No mission/task implementation decision is made by this plan.
+
+## Immediate documentation and implementation scope
+
+Maintain one clear architecture plan (this document), one example/default configuration, one strict configuration reader, and the existing Hello World proof. Avoid new services, generalized frameworks, and abstractions until a passing acceptance test requires them.