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,24 +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/
 
-# Step-CA dev password — real file is gitignored; commit only the .example
-infra/step-ca/dev-password
-
-# Scratch dirs created by the framework git-wrapper shell test harnesses
-.mosaic-test-work/
-
-# Transient config files vite/vitest/esbuild write next to a *.config.ts while
-# loading it, then unlink. They are untracked but were not ignored, so turbo's
-# package traversal hashed them and intermittently failed CI with "Package
-# traversal error: ... .timestamp-*.mjs: No such file or directory" when the
-# file vanished mid-scan. Ignoring them removes the race.
-*.timestamp-*.mjs
+# 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,5 +0,0 @@
-@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
-# Pin the pnpm store to the same path the ci-base image warms (Dockerfile.ci),
-# so the pipeline `pnpm install --prefer-offline` consumes the baked store
-# instead of repopulating a fresh one.
-store-dir=/root/.local/share/pnpm/store

.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,9 +0,0 @@
-pnpm-lock.yaml
-**/next-env.d.ts
-**/dist
-**/node_modules
-**/drizzle
-**/.next
-.claude/
-docs/tess/TASKS.md
-docs/scratchpads/

.woodpecker/ci.yml

@@ -1,108 +0,0 @@
-# &node_image is the pre-baked CI base built by .woodpecker/ci-image.yml:
-# node:24-alpine + python3/make/g++/postgresql-client + pnpm + a warm pnpm
-# store. The install step resolves from the baked store (--prefer-offline)
-# instead of paying a ~731s cold fetch + native compile every run.
-variables:
-  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
-  - &enable_pnpm 'corepack enable'
-
-when:
-  # PR + manual CI run on any branch — the pull_request pipeline is the merge gate.
-  # push CI is restricted to protected branches (main) so a feature-branch push no
-  # longer fires a redundant SECOND pipeline alongside its PR pipeline. This ~halves
-  # CI load on the storage-constrained runner with zero loss of gating (branch
-  # protection requires no push/ci status context; main still gets full push CI).
-  - event: [pull_request, manual]
-  - event: push
-    branch: main
-
-# 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
-      # python3/make/g++ are baked into ci-base; --prefer-offline resolves from
-      # the baked pnpm store.
-      - pnpm install --frozen-lockfile --prefer-offline
-
-  # Blocking gate: public framework package must contain no operator-specific
-  # personal data or private $HOME defaults. Runs early (no node_modules needed).
-  sanitization:
-    image: *node_image
-    commands:
-      - apk add --no-cache bash
-      - bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh
-      # Resident line-count ceiling over framework-owned resident files
-      # (Constitution + dispatcher + each RUNTIME.md slice). See DESIGN §7 / R9.
-      - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test
-      - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
-
-  typecheck:
-    image: *node_image
-    commands:
-      - *enable_pnpm
-      - pnpm typecheck
-    depends_on:
-      - install
-      - sanitization
-
-  # 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:
-      # Avoid the namespace-level Woodpecker DB service named "postgres".
-      # The Kubernetes backend exposes service containers by step name.
-      DATABASE_URL: postgresql://mosaic:mosaic@ci-postgres:5432/mosaic
-    commands:
-      - *enable_pnpm
-      # postgresql-client (pg_isready) is baked into ci-base.
-      # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
-      - |
-        ready=0
-        for i in $(seq 1 60); do
-          if pg_isready -h ci-postgres -p 5432 -U mosaic; then
-            ready=1
-            break
-          fi
-          echo "Waiting for ci-postgres ($i/60)..."
-          sleep 1
-        done
-        if [ "$ready" -ne 1 ]; then
-          echo "ci-postgres did not become ready" >&2
-          exit 1
-        fi
-      # 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:
-  ci-postgres:
-    image: pgvector/pgvector:pg17
-    environment:
-      POSTGRES_USER: mosaic
-      POSTGRES_PASSWORD: mosaic
-      POSTGRES_DB: mosaic

.woodpecker/publish.yml

@@ -1,197 +0,0 @@
-# Build, publish npm packages, and push Docker images
-# Runs only on main branch push/tag
-
-variables:
-  # Pre-baked CI base (see .woodpecker/ci-image.yml): node:24-alpine +
-  # toolchain + warm pnpm store. Kills the second cold install publish pays.
-  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
-  - &enable_pnpm 'corepack enable'
-  # Heavy kaniko image builds (~25 min) — gate them so a merge that only touches
-  # the npm-only CLI (@mosaicstack/mosaic) or docs does NOT rebuild the platform
-  # images (gateway/appservice/web do not depend on @mosaicstack/mosaic). Releases
-  # (tags) always build everything. Exclude-list keeps the default SAFE: any
-  # non-excluded change still builds, so no transitive dep can silently go stale.
-  # (Woodpecker: `when` entries are OR'd; `path` applies to push/PR only — hence
-  # the separate `event: tag` entry.)
-  - &image_build_when
-    - event: tag
-    - event: [push, manual]
-      branch: main
-      path:
-        exclude:
-          - 'packages/mosaic/**'
-          - 'docs/**'
-          - '**/*.md'
-          - '.woodpecker/**'
-
-when:
-  - branch: [main]
-    event: [push, manual, tag]
-
-steps:
-  install:
-    image: *node_image
-    commands:
-      - corepack enable
-      # Resolve from the baked pnpm store instead of a cold network fetch.
-      - pnpm install --frozen-lockfile --prefer-offline
-
-  build:
-    image: *node_image
-    commands:
-      - *enable_pnpm
-      - pnpm build
-    depends_on:
-      - install
-
-  publish-npm:
-    image: *node_image
-    # Publish only when a publishable package changed (or on a release tag); a
-    # pure-docs merge runs no publish. Cheap step, but gated for cleanliness.
-    when:
-      - event: tag
-      - event: [push, manual]
-        branch: main
-        path:
-          include:
-            - 'packages/**'
-    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
-    when: *image_build_when
-    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/stack/gateway:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/gateway:latest"
-        fi
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/gateway:$CI_COMMIT_TAG"
-        fi
-        /kaniko/executor --context . --dockerfile docker/gateway.Dockerfile $DESTINATIONS
-    depends_on:
-      - build
-
-  build-appservice:
-    image: gcr.io/kaniko-project/executor:debug
-    when: *image_build_when
-    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/stack/appservice:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:latest"
-        fi
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:$CI_COMMIT_TAG"
-        fi
-        /kaniko/executor --context . --dockerfile docker/appservice.Dockerfile $DESTINATIONS
-    depends_on:
-      - build
-
-  build-web:
-    image: gcr.io/kaniko-project/executor:debug
-    when: *image_build_when
-    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/stack/web:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/web:latest"
-        fi
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/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.1` | 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,364 +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
-curl -fsSL https://mosaicstack.dev/install.sh | bash
+## 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
 ```
 
-Or use the direct URL:
+## Configuration
 
-```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
+The sole discovery entry point is:
+
+```text
+~/.config/mosaic-dev/config.json
 ```
 
-The installer auto-launches the setup wizard, which walks you through gateway install and verification. Flags for non-interactive use:
+Created only by the explicit, idempotent bootstrap:
 
 ```bash
-bash <(curl -fsSL …) --yes               # Accept all defaults
-bash <(curl -fsSL …) --yes --no-auto-launch  # Install only, skip wizard
+scripts/bootstrap.sh   # create-if-absent; validates existing config, never rewrites
 ```
 
-This installs both components:
+Minimal shape (`configVersion` 1):
 
-| 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/` |
+```json
+{
+  "configVersion": 1,
+  "environment": "development",
+  "dataRoot": "/home/jwoltje/.mosaic-dev",
+  "execution": {
+    "backend": "docker",
+    "provider": "zai",
+    "model": "glm-5.3-flash"
+  }
+}
+```
 
-After install, the wizard runs automatically or you can invoke it manually:
+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
-mosaic wizard        # Full guided setup (gateway install → verify)
+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)
 ```
 
-### Requirements
+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.
 
-- 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)
+## 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.
-
-Pi launches default to a token-lean skill posture: `mosaic pi` passes `--no-skills` so Pi does not preload every global skill description into the system prompt. Use `MOSAIC_PI_SKILL_MODE=all mosaic pi` for the legacy all-skills catalog, or `MOSAIC_PI_SKILL_MODE=discover mosaic pi` to let Pi use its native settings/project skill discovery.
-
-### 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
-
-Mosaic supports three storage tiers: `local` (PGlite, single-host), `standalone` (PostgreSQL, single-host), and `federated` (PostgreSQL + pgvector + Valkey, multi-host). See [Federated Tier Setup](docs/federation/SETUP.md) for multi-user and production deployments, or [Migrating to Federated](docs/guides/migrate-tier.md) to upgrade from existing tiers.
-
-```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/stack.git
-cd 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
-
-```
-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
-curl -fsSL https://mosaicstack.dev/install.sh | bash
-```
-
-Or use the direct URL:
-
-```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/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/__tests__/session-ownership.test.ts

@@ -1,262 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { ForbiddenException, NotFoundException } from '@nestjs/common';
-import { describe, expect, it, vi } from 'vitest';
-
-vi.mock('../agent.service.js', () => ({ AgentService: class AgentService {} }));
-vi.mock('../../commands/command-executor.service.js', () => ({
-  CommandExecutorService: class CommandExecutorService {},
-}));
-vi.mock('../routing/routing-engine.service.js', () => ({
-  RoutingEngineService: class RoutingEngineService {},
-}));
-
-import { SessionsController } from '../sessions.controller.js';
-import { ChatController } from '../../chat/chat.controller.js';
-import { ChatGateway } from '../../chat/chat.gateway.js';
-import type { AgentSession } from '../agent.service.js';
-import type { SessionInfoDto } from '../session.dto.js';
-
-const USER_A = { id: 'user-a', tenantId: 'tenant-a' };
-const USER_B = { id: 'user-b', tenantId: 'tenant-b' };
-const CONVERSATION_ID = '11111111-1111-4111-8111-111111111111';
-
-function makeSessionInfo(overrides?: Partial<SessionInfoDto>): SessionInfoDto {
-  return {
-    id: CONVERSATION_ID,
-    provider: 'test-provider',
-    modelId: 'test-model',
-    createdAt: new Date('2026-07-12T00:00:00Z').toISOString(),
-    promptCount: 0,
-    channels: [],
-    durationMs: 0,
-    metrics: {
-      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-      modelSwitches: 0,
-      messageCount: 0,
-      lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
-    },
-    ...overrides,
-  };
-}
-
-function makeAgentSession(owner = USER_A): AgentSession {
-  return {
-    id: CONVERSATION_ID,
-    provider: 'test-provider',
-    modelId: 'test-model',
-    piSession: {
-      thinkingLevel: 'off',
-      getAvailableThinkingLevels: vi.fn().mockReturnValue(['off', 'low', 'high']),
-      setThinkingLevel: vi.fn(),
-      abort: vi.fn().mockResolvedValue(undefined),
-      prompt: vi.fn().mockResolvedValue(undefined),
-      dispose: vi.fn(),
-      getSessionStats: vi.fn(),
-      getContextUsage: vi.fn(),
-    } as unknown as AgentSession['piSession'],
-    listeners: new Set(),
-    unsubscribe: vi.fn(),
-    createdAt: Date.now(),
-    promptCount: 0,
-    channels: new Set(),
-    skillPromptAdditions: [],
-    sandboxDir: '/tmp',
-    allowedTools: null,
-    userId: owner.id,
-    tenantId: owner.tenantId,
-    metrics: {
-      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-      modelSwitches: 0,
-      messageCount: 0,
-      lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
-    },
-  };
-}
-
-function makeScopedAgentService() {
-  const foreign = makeAgentSession(USER_A);
-  return {
-    listSessions: vi.fn((scope?: { userId: string; tenantId?: string }) =>
-      scope?.userId === USER_B.id ? [] : [makeSessionInfo({ id: foreign.id })],
-    ),
-    getSessionInfo: vi.fn((_id: string, scope?: { userId: string; tenantId?: string }) =>
-      scope?.userId === USER_B.id ? undefined : makeSessionInfo({ id: foreign.id }),
-    ),
-    destroySession: vi.fn(),
-    getSession: vi.fn((_id: string, scope?: { userId: string; tenantId?: string }) =>
-      scope?.userId === USER_B.id ? undefined : foreign,
-    ),
-    createSession: vi.fn().mockRejectedValue(new ForbiddenException('Session scope mismatch')),
-    onEvent: vi.fn(() => vi.fn()),
-    addChannel: vi.fn(),
-    removeChannel: vi.fn(),
-    recordMessage: vi.fn(),
-    prompt: vi.fn().mockResolvedValue(undefined),
-  };
-}
-
-describe('TESS-M1-SEC-002 AgentService ownership boundary', () => {
-  it('requires explicit owner+tenant scope on protected session operations', () => {
-    const source = readFileSync(resolve('src/agent/agent.service.ts'), 'utf8');
-
-    expect(source).toContain('getSession(sessionId: string, scope: ActorTenantScope)');
-    expect(source).toContain('listSessions(scope: ActorTenantScope)');
-    expect(source).toContain('getSessionInfo(sessionId: string, scope: ActorTenantScope)');
-    expect(source).toContain(
-      'addChannel(sessionId: string, channel: string, scope: ActorTenantScope)',
-    );
-    expect(source).toContain(
-      'removeChannel(sessionId: string, channel: string, scope: ActorTenantScope)',
-    );
-    expect(source).toContain(
-      'async prompt(sessionId: string, message: string, scope: ActorTenantScope)',
-    );
-    expect(source).toContain('scope: ActorTenantScope,');
-    expect(source).toContain('async destroySession(sessionId: string, scope: ActorTenantScope)');
-    expect(source).not.toContain('scope?: ActorTenantScope');
-  });
-});
-
-describe('TESS-M1-SEC-002 REST session ownership and tenant binding', () => {
-  it('lists only sessions owned by the authenticated owner+tenant scope', () => {
-    const agentService = makeScopedAgentService();
-    const controller = new SessionsController(agentService as never);
-
-    expect(controller.list(USER_B)).toEqual({ sessions: [], total: 0 });
-    expect(agentService.listSessions).toHaveBeenCalledWith({
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-  });
-
-  it('does not reveal another owner/tenant session by guessed id', () => {
-    const agentService = makeScopedAgentService();
-    const controller = new SessionsController(agentService as never);
-
-    expect(() => controller.findOne(CONVERSATION_ID, USER_B)).toThrow(NotFoundException);
-    expect(agentService.getSessionInfo).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-  });
-
-  it('does not terminate another owner/tenant session by guessed id', async () => {
-    const agentService = makeScopedAgentService();
-    const controller = new SessionsController(agentService as never);
-
-    await expect(controller.destroy(CONVERSATION_ID, USER_B)).rejects.toBeInstanceOf(
-      NotFoundException,
-    );
-    expect(agentService.destroySession).not.toHaveBeenCalled();
-  });
-});
-
-describe('TESS-M1-SEC-002 REST chat send ownership and tenant binding', () => {
-  it('does not send a prompt into another owner/tenant session by guessed conversationId', async () => {
-    const agentService = makeScopedAgentService();
-    const controller = new ChatController(agentService as never);
-
-    await expect(
-      controller.chat({ conversationId: CONVERSATION_ID, content: 'take over' }, USER_B),
-    ).rejects.toMatchObject({ status: 404 });
-
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-    expect(agentService.prompt).not.toHaveBeenCalled();
-  });
-});
-
-describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding', () => {
-  function makeGateway(agentService = makeScopedAgentService()) {
-    const brain = {
-      conversations: {
-        findById: vi.fn().mockResolvedValue(undefined),
-        create: vi.fn().mockResolvedValue(undefined),
-        update: vi.fn().mockResolvedValue(undefined),
-        findMessages: vi.fn().mockResolvedValue([]),
-        addMessage: vi.fn().mockResolvedValue(undefined),
-      },
-    };
-    const commandRegistry = { getManifest: vi.fn().mockReturnValue([]) };
-    const commandExecutor = { execute: vi.fn() };
-    const routingEngine = {
-      resolve: vi.fn().mockResolvedValue({ provider: 'test', model: 'test-model' }),
-    };
-    const gateway = new ChatGateway(
-      agentService as never,
-      {} as never,
-      brain as never,
-      commandRegistry as never,
-      commandExecutor as never,
-      routingEngine as never,
-    );
-    return { gateway, agentService };
-  }
-
-  function makeSocket() {
-    return {
-      id: 'socket-b',
-      connected: true,
-      data: { user: USER_B, session: { id: 'auth-session-b', userId: USER_B.id } },
-      emit: vi.fn(),
-      disconnect: vi.fn(),
-    };
-  }
-
-  it('does not attach or send to another owner/tenant session by guessed conversationId', async () => {
-    const { gateway, agentService } = makeGateway();
-    const socket = makeSocket();
-
-    await gateway.handleMessage(socket as never, {
-      conversationId: CONVERSATION_ID,
-      content: 'attach to foreign session',
-    });
-
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-    expect(agentService.onEvent).not.toHaveBeenCalled();
-    expect(agentService.addChannel).not.toHaveBeenCalled();
-    expect(agentService.prompt).not.toHaveBeenCalled();
-    expect(socket.emit).toHaveBeenCalledWith(
-      'error',
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
-    );
-  });
-
-  it('does not mutate thinking level on another owner/tenant session', () => {
-    const { gateway, agentService } = makeGateway();
-    const socket = makeSocket();
-
-    gateway.handleSetThinking(socket as never, { conversationId: CONVERSATION_ID, level: 'high' });
-
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-    expect(socket.emit).toHaveBeenCalledWith(
-      'error',
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
-    );
-  });
-
-  it('does not terminate another owner/tenant session over WebSocket abort', async () => {
-    const { gateway, agentService } = makeGateway();
-    const socket = makeSocket();
-
-    await gateway.handleAbort(socket as never, { conversationId: CONVERSATION_ID });
-
-    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
-      userId: USER_B.id,
-      tenantId: USER_B.tenantId,
-    });
-    expect(socket.emit).toHaveBeenCalledWith(
-      'error',
-      expect.objectContaining({ conversationId: CONVERSATION_ID }),
-    );
-  });
-});

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,82 +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: AuthenticatedUserLike');
-    expect(source).toContain('const scope = scopeFromUser(user);');
-  });
-});
-
-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,107 +0,0 @@
-import {
-  Controller,
-  Post,
-  Body,
-  Logger,
-  ForbiddenException,
-  HttpException,
-  HttpStatus,
-  NotFoundException,
-  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 { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.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: AuthenticatedUserLike,
-  ): Promise<ChatResponse> {
-    const conversationId = body.conversationId ?? uuid();
-    const scope = scopeFromUser(user);
-
-    try {
-      let agentSession = this.agentService.getSession(conversationId, scope);
-      if (!agentSession) {
-        agentSession = await this.agentService.createSession(conversationId, {
-          userId: scope.userId,
-          tenantId: scope.tenantId,
-        });
-      }
-    } catch (err) {
-      if (err instanceof ForbiddenException) {
-        throw new NotFoundException('Session not found');
-      }
-      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();
-          }
-        },
-        scope,
-      );
-    });
-
-    try {
-      await this.agentService.prompt(conversationId, body.content, scope);
-      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-command-approval.spec.ts

@@ -1,74 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import type { SlashCommandPayload } from '@mosaicstack/types';
-import { ChatGateway } from './chat.gateway.js';
-
-const payload: SlashCommandPayload = {
-  command: 'gc',
-  conversationId: 'conversation-1',
-  approvalId: 'approval-1',
-};
-
-function buildGateway(commandExecutor: {
-  execute: ReturnType<typeof vi.fn>;
-  createApproval: ReturnType<typeof vi.fn>;
-}): ChatGateway {
-  return new ChatGateway(
-    {} as never,
-    {} as never,
-    {} as never,
-    {} as never,
-    commandExecutor as never,
-    {} as never,
-  );
-}
-
-describe('ChatGateway command approval ingress', () => {
-  it('passes the client approval ID through to command execution while deriving the actor server-side', async (): Promise<void> => {
-    const commandExecutor = {
-      execute: vi.fn().mockResolvedValue({ ...payload, success: true }),
-      createApproval: vi.fn(),
-    };
-    const gateway = buildGateway(commandExecutor);
-    const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
-
-    await gateway.handleCommandExecute(client as never, payload);
-
-    expect(commandExecutor.execute).toHaveBeenCalledWith(payload, {
-      userId: 'admin-1',
-      tenantId: 'admin-1',
-    });
-    expect(client.emit).toHaveBeenCalledWith(
-      'command:result',
-      expect.objectContaining({ success: true }),
-    );
-  });
-
-  it('issues a durable approval only for the authenticated actor', async (): Promise<void> => {
-    const commandExecutor = {
-      execute: vi.fn(),
-      createApproval: vi.fn().mockResolvedValue({
-        approvalId: 'approval-1',
-        expiresAt: '2026-07-12T00:05:00.000Z',
-      }),
-    };
-    const gateway = buildGateway(commandExecutor);
-    const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
-
-    await gateway.handleCommandApproval(client as never, {
-      command: 'gc',
-      conversationId: 'conversation-1',
-    });
-
-    expect(commandExecutor.createApproval).toHaveBeenCalledWith(
-      { command: 'gc', conversationId: 'conversation-1' },
-      { userId: 'admin-1', tenantId: 'admin-1' },
-    );
-    expect(client.emit).toHaveBeenCalledWith('command:approval', {
-      command: 'gc',
-      conversationId: 'conversation-1',
-      success: true,
-      approvalId: 'approval-1',
-      expiresAt: '2026-07-12T00:05:00.000Z',
-    });
-  });
-});

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/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/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/plugin/discord-ingress.security.spec.ts

@@ -1,443 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import {
-  createDiscordIngressEnvelope,
-  verifyDiscordIngressEnvelope,
-  DiscordPlugin,
-  type DiscordIngressPayload,
-  parseDiscordInteractionBindings,
-  resolveDiscordInteractionActorId,
-  resolveDiscordInteractionBinding,
-} from '@mosaicstack/discord-plugin';
-import { RuntimeProviderService } from '../agent/runtime-provider-registry.service.js';
-import { ChatGateway } from '../chat/chat.gateway.js';
-import { CommandAuthorizationService } from '../commands/command-authorization.service.js';
-import { validateDiscordServiceToken } from '../chat/chat.gateway-auth.js';
-import { DiscordReplayProtector } from './discord-replay-protector.js';
-
-const SERVICE_TOKEN = 'test-service-token';
-const ENV_KEYS = [
-  'DISCORD_SERVICE_TOKEN',
-  'DISCORD_SERVICE_USER_ID',
-  'DISCORD_SERVICE_TENANT_ID',
-  'DISCORD_INTERACTION_BINDINGS',
-  'DISCORD_ALLOWED_GUILD_IDS',
-  'DISCORD_ALLOWED_CHANNEL_IDS',
-  'DISCORD_ALLOWED_USER_IDS',
-  'MOSAIC_AGENT_NAME',
-] as const;
-const savedEnv = new Map<string, string | undefined>();
-
-function configureDiscordEnv(role: 'admin' | 'member' = 'admin'): void {
-  for (const key of ENV_KEYS) savedEnv.set(key, process.env[key]);
-  process.env['DISCORD_SERVICE_TOKEN'] = SERVICE_TOKEN;
-  process.env['DISCORD_SERVICE_USER_ID'] = 'discord-service';
-  process.env['DISCORD_SERVICE_TENANT_ID'] = 'tenant-discord';
-  process.env['MOSAIC_AGENT_NAME'] = 'Nova';
-  process.env['DISCORD_ALLOWED_GUILD_IDS'] = 'guild-001';
-  process.env['DISCORD_ALLOWED_CHANNEL_IDS'] = 'channel-001';
-  process.env['DISCORD_ALLOWED_USER_IDS'] = 'user-001';
-  process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([
-    {
-      instanceId: 'Nova',
-      guildId: 'guild-001',
-      channelId: 'channel-001',
-      pairedUsers: {
-        'user-001': {
-          role: role === 'admin' ? 'admin' : 'operator',
-          mosaicUserId: 'mosaic-admin-001',
-        },
-      },
-    },
-  ]);
-}
-
-afterEach((): void => {
-  for (const key of ENV_KEYS) {
-    const value = savedEnv.get(key);
-    if (value === undefined) delete process.env[key];
-    else process.env[key] = value;
-  }
-  savedEnv.clear();
-});
-
-function commandAuthorization(role: 'admin' | 'member'): CommandAuthorizationService {
-  const entries = new Map<string, string>();
-  const db = {
-    select: () => ({ from: () => ({ where: () => ({ limit: async () => [{ role }] }) }) }),
-  };
-  const redis = {
-    get: async (key: string) => entries.get(key) ?? null,
-    set: async (key: string, value: string) => entries.set(key, value),
-    del: async (key: string) => Number(entries.delete(key)),
-  };
-  return new CommandAuthorizationService(db as never, redis);
-}
-
-function discordGateway(role: 'admin' | 'member'): {
-  gateway: ChatGateway;
-  client: { data: { discordService: boolean }; emit: ReturnType<typeof vi.fn> };
-  consumedActions: Array<{ actorId: string; correlationId: string }>;
-  durable: { getSnapshot: ReturnType<typeof vi.fn> };
-  audit: { record: ReturnType<typeof vi.fn> };
-} {
-  const authorization = commandAuthorization(role);
-  const consumedActions: Array<{ actorId: string; correlationId: string }> = [];
-  const durable = {
-    getSnapshot: vi.fn().mockResolvedValue({
-      identity: { agentName: 'Nova', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
-    }),
-  };
-  const audit = { record: vi.fn().mockResolvedValue(undefined) };
-  const runtimeRegistry = new RuntimeProviderService(
-    {
-      require: () => ({
-        capabilities: async () => ({ supported: ['session.terminate'] }),
-        terminate: async () => undefined,
-      }),
-    } as never,
-    { record: async () => undefined } as never,
-    {
-      consume: async (approvalId, action) => {
-        consumedActions.push({ actorId: action.actorId, correlationId: action.correlationId });
-        return authorization.consumeRuntimeTerminationApproval(approvalId, action);
-      },
-    },
-  );
-  return {
-    gateway: new ChatGateway(
-      {} as never,
-      {} as never,
-      {} as never,
-      {} as never,
-      {} as never,
-      {} as never,
-      authorization,
-      runtimeRegistry,
-      durable as never,
-      audit as never,
-    ),
-    client: { data: { discordService: true }, emit: vi.fn() },
-    consumedActions,
-    durable,
-    audit,
-  };
-}
-
-function ingressEnvelope(
-  content: string,
-  messageId: string,
-  overrides: Partial<DiscordIngressPayload> = {},
-): ReturnType<typeof createDiscordIngressEnvelope> {
-  return createDiscordIngressEnvelope(
-    createPayload({ content, messageId, ...overrides }),
-    SERVICE_TOKEN,
-  );
-}
-
-function createPayload(overrides: Partial<DiscordIngressPayload> = {}): DiscordIngressPayload {
-  return {
-    correlationId: 'correlation-001',
-    messageId: 'discord-message-001',
-    guildId: 'guild-001',
-    channelId: 'channel-001',
-    userId: 'user-001',
-    conversationId: 'discord-channel-001',
-    content: 'hello Tess',
-    ...overrides,
-  };
-}
-
-describe('Discord ingress security', () => {
-  it('keeps legacy role-only bindings valid while withholding privileged actor identity', () => {
-    const [binding] = parseDiscordInteractionBindings(
-      JSON.stringify([
-        {
-          instanceId: 'Nova',
-          guildId: 'guild-001',
-          channelId: 'channel-001',
-          pairedUsers: { 'user-001': 'admin' },
-        },
-      ]),
-    );
-    expect(
-      resolveDiscordInteractionBinding([binding!], 'guild-001', 'channel-001', 'user-001', 'send'),
-    ).toEqual(binding);
-    expect(resolveDiscordInteractionActorId(binding!, 'user-001')).toBeNull();
-  });
-
-  it('binds a differently named configured interaction instance without code changes', () => {
-    const binding = resolveDiscordInteractionBinding(
-      [
-        {
-          instanceId: 'Nova',
-          guildId: 'guild-001',
-          channelId: 'channel-001',
-          pairedUsers: { 'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' } },
-        },
-      ],
-      'guild-001',
-      'channel-001',
-      'user-001',
-      'send',
-    );
-
-    expect(binding?.instanceId).toBe('Nova');
-  });
-
-  it('accepts only the configured Discord service identity', () => {
-    expect(validateDiscordServiceToken(SERVICE_TOKEN, SERVICE_TOKEN)).toBe(true);
-    expect(validateDiscordServiceToken('wrong-service-token', SERVICE_TOKEN)).toBe(false);
-    expect(validateDiscordServiceToken(undefined, SERVICE_TOKEN)).toBe(false);
-  });
-
-  it('rejects unauthenticated or tampered service envelopes', () => {
-    const envelope = createDiscordIngressEnvelope(createPayload(), SERVICE_TOKEN);
-
-    expect(verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN)).toEqual(createPayload());
-    expect(verifyDiscordIngressEnvelope(envelope, 'wrong-service-token')).toBeNull();
-    expect(
-      verifyDiscordIngressEnvelope(
-        { ...envelope, payload: { ...envelope.payload, content: 'forged command' } },
-        SERVICE_TOKEN,
-      ),
-    ).toBeNull();
-  });
-
-  it.each([
-    ['guild', { guildId: 'unlisted-guild' }],
-    ['channel', { channelId: 'unlisted-channel' }],
-    ['user', { userId: 'unlisted-user' }],
-  ])(
-    'rejects an unallowlisted Discord %s',
-    (_kind: string, overrides: Partial<DiscordIngressPayload>) => {
-      const envelope = createDiscordIngressEnvelope(createPayload(overrides), SERVICE_TOKEN);
-
-      expect(
-        verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN, {
-          guildIds: ['guild-001'],
-          channelIds: ['channel-001'],
-          userIds: ['user-001'],
-        }),
-      ).toBeNull();
-    },
-  );
-
-  it('retains Discord message and correlation IDs after authenticated allowlisted validation', () => {
-    const payload = createPayload({
-      correlationId: 'correlation-trace-123',
-      messageId: 'discord-snowflake-987',
-    });
-    const envelope = createDiscordIngressEnvelope(payload, SERVICE_TOKEN);
-
-    expect(
-      verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN, {
-        guildIds: ['guild-001'],
-        channelIds: ['channel-001'],
-        userIds: ['user-001'],
-      }),
-    ).toEqual(payload);
-  });
-
-  it('rejects a replayed Discord message ID while retaining bounded replay state', () => {
-    const replayProtector = new DiscordReplayProtector(60_000, 2);
-
-    expect(replayProtector.claim('discord-message-001')).toBe(true);
-    expect(replayProtector.claim('discord-message-001')).toBe(false);
-    expect(replayProtector.claim('discord-message-002')).toBe(true);
-    expect(replayProtector.claim('discord-message-003')).toBe(true);
-    expect(replayProtector.size).toBe(2);
-  });
-
-  it('consumes the exact target once when approval and stop are separate Discord messages', async () => {
-    configureDiscordEnv();
-    const { gateway, client, consumedActions } = discordGateway('admin');
-    await gateway.handleDiscordApproval(
-      client as never,
-      ingressEnvelope('/approve', 'approve-message', {
-        correlationId: 'approval-ingress-correlation',
-      }),
-    );
-    const approval = client.emit.mock.calls.find(
-      ([event]) => event === 'discord:approval',
-    )?.[1] as {
-      approvalId: string;
-      success: boolean;
-    };
-    expect(approval.success).toBe(true);
-
-    await gateway.handleDiscordStop(
-      client as never,
-      ingressEnvelope(`/stop ${approval.approvalId}`, 'stop-message', {
-        correlationId: 'stop-ingress-correlation',
-      }),
-    );
-    expect(client.emit).toHaveBeenCalledWith('discord:stop', {
-      correlationId: 'stop-ingress-correlation',
-      success: true,
-    });
-    expect(consumedActions).toEqual([
-      {
-        actorId: 'mosaic-admin-001',
-        correlationId: expect.stringMatching(/^discord-action:v1:/),
-      },
-    ]);
-  });
-
-  it('audits a Discord mint-side authorization denial', async () => {
-    configureDiscordEnv();
-    const { gateway, client, audit } = discordGateway('member');
-
-    await gateway.handleDiscordApproval(
-      client as never,
-      ingressEnvelope('/approve', 'denied-approve'),
-    );
-
-    expect(client.emit).toHaveBeenCalledWith('discord:approval', {
-      correlationId: 'correlation-001',
-      success: false,
-      approvalId: undefined,
-      expiresAt: undefined,
-    });
-    expect(audit.record).toHaveBeenCalledWith(
-      expect.objectContaining({
-        outcome: 'denied',
-        operation: 'session.terminate',
-        errorCode: 'policy_denied',
-      }),
-    );
-  });
-
-  it.each([
-    [
-      'binding',
-      () => {
-        process.env['MOSAIC_AGENT_NAME'] = 'Other';
-      },
-    ],
-    [
-      'durable session',
-      (durable: { getSnapshot: ReturnType<typeof vi.fn> }) => {
-        durable.getSnapshot.mockResolvedValueOnce({
-          identity: { agentName: 'Other', providerId: 'fleet', runtimeSessionId: 'runtime-1' },
-        });
-      },
-    ],
-  ])(
-    'rejects approval when the %s targets a different runtime agent',
-    async (_source, configure) => {
-      configureDiscordEnv();
-      const { gateway, client, durable } = discordGateway('admin');
-      configure(durable);
-
-      await gateway.handleDiscordApproval(
-        client as never,
-        ingressEnvelope('/approve', 'mismatched-agent-approve'),
-      );
-
-      expect(client.emit).toHaveBeenCalledWith('discord:approval', {
-        correlationId: 'correlation-001',
-        success: false,
-        approvalId: undefined,
-        expiresAt: undefined,
-      });
-    },
-  );
-
-  it('rejects unpaired and non-admin Discord users for approval and stop', async () => {
-    configureDiscordEnv();
-    const { gateway, client } = discordGateway('member');
-    await gateway.handleDiscordApproval(
-      client as never,
-      ingressEnvelope('/approve', 'member-approve'),
-    );
-    expect(client.emit).toHaveBeenCalledWith('discord:approval', {
-      correlationId: 'correlation-001',
-      success: false,
-      approvalId: undefined,
-      expiresAt: undefined,
-    });
-
-    process.env['DISCORD_INTERACTION_BINDINGS'] = JSON.stringify([]);
-    await gateway.handleDiscordStop(
-      client as never,
-      ingressEnvelope('/stop forged', 'unpaired-stop'),
-    );
-    expect(client.emit).not.toHaveBeenCalledWith('discord:stop', expect.anything());
-  });
-
-  it('rejects replaying a Discord-created termination approval', async () => {
-    configureDiscordEnv();
-    const { gateway, client } = discordGateway('admin');
-    await gateway.handleDiscordApproval(
-      client as never,
-      ingressEnvelope('/approve', 'replay-approve', {
-        correlationId: 'replay-approval-correlation',
-      }),
-    );
-    const approval = client.emit.mock.calls.find(
-      ([event]) => event === 'discord:approval',
-    )?.[1] as {
-      approvalId: string;
-    };
-    await gateway.handleDiscordStop(
-      client as never,
-      ingressEnvelope(`/stop ${approval.approvalId}`, 'replay-stop-one', {
-        correlationId: 'replay-stop-correlation-one',
-      }),
-    );
-    await gateway.handleDiscordStop(
-      client as never,
-      ingressEnvelope(`/stop ${approval.approvalId}`, 'replay-stop-two', {
-        correlationId: 'replay-stop-correlation-two',
-      }),
-    );
-    const stopResults = client.emit.mock.calls.filter(([event]) => event === 'discord:stop');
-    expect(stopResults.map(([, result]) => (result as { success: boolean }).success)).toEqual([
-      true,
-      false,
-    ]);
-  });
-
-  it('accepts a thread message through its allowed bound parent channel', () => {
-    const emitted = vi.fn();
-    const plugin = new DiscordPlugin({
-      token: 'unused',
-      gatewayUrl: 'http://unused',
-      serviceToken: SERVICE_TOKEN,
-      allowedGuildIds: ['guild-001'],
-      allowedChannelIds: ['channel-001'],
-      allowedUserIds: ['user-001'],
-      interactionBindings: [
-        {
-          instanceId: 'Nova',
-          guildId: 'guild-001',
-          channelId: 'channel-001',
-          pairedUsers: { 'user-001': { role: 'operator', mosaicUserId: 'mosaic-operator-001' } },
-        },
-      ],
-    });
-    const internals = plugin as unknown as {
-      client: { user: { id: string } };
-      socket: { connected: boolean; emit: ReturnType<typeof vi.fn> };
-      handleDiscordMessage(message: unknown): void;
-    };
-    internals.client = { user: { id: 'bot-001' } };
-    internals.socket = { connected: true, emit: emitted };
-    internals.handleDiscordMessage({
-      id: 'thread-message',
-      guildId: 'guild-001',
-      channelId: 'thread-001',
-      author: { id: 'user-001', bot: false },
-      mentions: { has: () => true },
-      content: '<@bot-001> hello from thread',
-      channel: { parentId: 'channel-001' },
-      attachments: new Map(),
-    });
-
-    const [, envelope] = emitted.mock.calls[0] as [
-      string,
-      ReturnType<typeof createDiscordIngressEnvelope>,
-    ];
-    expect(verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN)?.channelId).toBe('channel-001');
-  });
-});

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,31 +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 workspace manifests first for layer-cached install
-COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
-COPY apps/gateway/package.json ./apps/gateway/
-COPY packages/ ./packages/
-COPY plugins/ ./plugins/
-RUN pnpm install --frozen-lockfile
-COPY . .
-# Build gateway and all of its workspace dependencies via turbo dependency graph
-RUN pnpm turbo run build --filter @mosaicstack/gateway...
-# Produce a self-contained deploy artifact: flat node_modules, no pnpm symlinks
-# --legacy is required for pnpm v10 when inject-workspace-packages is not set
-RUN pnpm --filter @mosaicstack/gateway --prod deploy --legacy /deploy
-
-FROM base AS runner
-WORKDIR /app
-ENV NODE_ENV=production
-# Use the pnpm deploy output — resolves all deps into a flat, self-contained node_modules
-COPY --from=builder /deploy/node_modules ./node_modules
-COPY --from=builder /deploy/package.json ./package.json
-# dist is declared in package.json "files" so pnpm deploy copies it into /deploy;
-# copy from builder explicitly as belt-and-suspenders
-COPY --from=builder /app/apps/gateway/dist ./dist
-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/SITEMAP.md

@@ -1,50 +0,0 @@
-# Documentation Sitemap
-
-## Native Kanban and canonical task SOT
-
-- [Canonical requirements](requirements/native-kanban-sot.md) — ratified P0–P3 requirements and acceptance criteria.
-- [Workstream index](native-kanban-sot/INDEX.md) — artifact map, lane partition, and delivery order.
-- [Mission manifest](native-kanban-sot/MISSION-MANIFEST.md) — scope, authority, invariants, and gate model.
-- [Task decomposition](native-kanban-sot/TASKS.md) — dependency-ordered implementation slices and ownership boundaries.
-- [Frozen shared contract](native-kanban-sot/SHARED-CONTRACT.md) — schema, API, Coordinator, health, recovery, and migration contracts.
-- [Initial independent review](reports/native-kanban-sot/canon-initial-review-no-go.md) — KCR-001–016 findings that blocked the first draft.
-- [Final independent re-review](reports/native-kanban-sot/canon-final-rereview-go.md) — closure evidence and GO verdict.
-- [Ultron final gate](reports/native-kanban-sot/ultron-final-go.md) — final requirements, authority, schema, migration, recovery, and evidence review.
-
-## Tess interaction agent
-
-### Operator guides
-
-- [User guide](tess/USER-GUIDE.md) — authorized session, attach, send, stop, and handoff workflows.
-- [Admin guide](tess/ADMIN-GUIDE.md) — deployment configuration, policy, and approval controls.
-- [Developer guide](tess/DEVELOPER-GUIDE.md) — provider contracts, scope boundaries, and test workflow.
-- [Plugin guide](tess/PLUGIN-GUIDE.md) — adapter, redaction, and identity-as-data requirements.
-- [Operations guide](tess/OPERATIONS-GUIDE.md) — readiness, recovery, and incident-safe procedures.
-
-### Architecture and security
-
-- [Architecture](tess/ARCHITECTURE.md)
-- [Threat model](tess/THREAT-MODEL.md)
-- [Mos coordination boundary](tess/MOS-COORDINATION.md)
-- [Hermes runtime adapter design](tess/hermes-runtime-adapter-design.md)
-- [Operator plugin sketch](tess/M4-003-OPERATOR-PLUGIN-SKETCH.md)
-
-### API contract
-
-- [Tess OpenAPI contract](openapi-tess.yaml)
-
-### Migration and qualification
-
-- [Migration inventory](tess/M5-MIGRATION-INVENTORY.md)
-- [Cutover procedure](tess/M5-MIGRATION-CUTOVER.md)
-- [Rollback procedure](tess/M5-MIGRATION-ROLLBACK.md)
-- [Retention and deprecation evidence](tess/M5-MIGRATION-RETENTION-DEPRECATION.md)
-- [Verification matrix](tess/VERIFICATION-MATRIX.md)
-- [Documentation checklist](tess/M5-003-DOCUMENTATION-CHECKLIST.md)
-- [Independent Option 2 runtime-portability qualification (2026-07-14)](tess/qualification/2026-07-14-option2-runtime-portability.md)
-
-## Runtime-neutral Mos portability
-
-- [Optional AI egress gateway ADR](architecture/ADR-MOS-EGRESS-GATEWAYS.md) — placement and gates for LiteLLM, Bifrost, and purpose-built translation proxies.
-- [Runtime-neutral Mos identity and failover mission](https://git.mosaicstack.dev/mosaicstack/stack/issues/754)
-- [Logical identity and connector lease/fencing implementation](https://git.mosaicstack.dev/mosaicstack/stack/issues/755)

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/TASKS.md

@@ -1,94 +0,0 @@
-# Tasks — MVP (Top-Level Rollup)
-
-> Single-writer: orchestrator only. Workers read but never modify.
->
-> **Mission:** mvp-20260312
-> **Manifest:** [docs/MISSION-MANIFEST.md](./MISSION-MANIFEST.md)
->
-> This file is a **rollup**. Per-workstream task breakdowns live in workstream task files
-> (e.g. `docs/federation/TASKS.md`). Workers operating inside a workstream should treat
-> the workstream file as their primary task source; this file exists for orchestrator-level
-> visibility into MVP-wide state.
->
-> **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed`
-
-## Workstream Rollup
-
-| id  | status            | workstream             | progress         | tasks file                                                      | notes                                                                            |
-| --- | ----------------- | ---------------------- | ---------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| W1  | planning-complete | Federation v1 (FED)    | 0 / 7 milestones | [docs/federation/TASKS.md](./federation/TASKS.md)               | M1 task breakdown populated; M2–M7 deferred to mission planning                  |
-| W2  | planning-complete | Tess interaction agent | 0 / 5 milestones | [docs/tess/TASKS.md](./tess/TASKS.md)                           | Issue #706; independent planning gate PASS; M1 issue #707 ready                  |
-| W3  | planning-complete | Native Kanban/SOT      | 0 / 4 phases     | [docs/native-kanban-sot/TASKS.md](./native-kanban-sot/TASKS.md) | Issue #751; canon independently approved; implementation held until canon merges |
-
-## Cross-Cutting Tracking
-
-These are MVP-level checks that don't belong to any single workstream. Updated by the orchestrator at each session.
-
-| id         | status      | description                                                                                              | notes                                                                                                                         |
-| ---------- | ----------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| MVP-T01    | done        | Author MVP-level manifest at `docs/MISSION-MANIFEST.md`                                                  | This session (2026-04-19); PR pending                                                                                         |
-| MVP-T02    | done        | Archive install-ux-v2 mission state to `docs/archive/missions/install-ux-v2-20260405/`                   | IUV-M03 retroactively closed (shipped via PR #446 + releases 0.0.27→0.0.29)                                                   |
-| MVP-T03    | done        | Land federation v1 planning artifacts on `main`                                                          | PR #468 merged 2026-04-19 (commit `66512550`)                                                                                 |
-| MVP-T04    | not-started | Sync `.mosaic/orchestrator/mission.json` MVP slot with this manifest (milestone enumeration, etc.)       | Coord state file; consider whether to repopulate via `mosaic coord` or accept hand-edit                                       |
-| MVP-T05    | in-progress | Kick off W1 / FED-M1 — federated tier infrastructure                                                     | Session 16 (2026-04-19): FED-M1-01 in-progress on `feat/federation-m1-tier-config`                                            |
-| MVP-T06    | not-started | Declare additional workstreams (web dashboard, TUI/CLI parity, remote control, etc.) as scope solidifies | Track each new workstream by adding a row to the Workstream Rollup                                                            |
-| T-A292E96F | in-progress | Fix Mosaic Gitea PR metadata/login wrapper regression for U-Connect merge preflight                      | Kanban `t_a292e96f`; branch `fix/t-a292e96f-gitea-pr-metadata`; scratchpad `docs/scratchpads/t-a292e96f-gitea-pr-metadata.md` |
-
-## Pointer to Active Workstream
-
-Active workstream is **W1 — Federation v1**. Workers should:
-
-1. Read [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) for workstream scope
-2. Read [docs/federation/TASKS.md](./federation/TASKS.md) for the next pending task
-3. Follow per-task agent + tier guidance from the workstream manifest
-
-## Thin-core prompt diet (#528) — feat/contract-thin-core
-
-- Status: PR open, awaiting maintainer merge ratification (fleet-governing change).
-- Cut always-injected contract AGENTS+TOOLS+RUNTIME 8,827→4,122 tok (−53%); all 12 hard gates intact.
-- Validation: deterministic gate-checklist PASS; headless A/B thin 7/9 vs monolith 5/9. Detail: scratchpads/contract-thin-core.md.
-
-## P5 — Overlay composer + cross-harness (#604) — feat/p5-overlay-composer
-
-- Status: MERGED to main (#605). R7 (compose-contract) + R8 (cross-harness) + R9 (composer test).
-- `composeContract({harness, mosaicHome})` pure fn + `.local` overlay deltas-by-value; `mosaic compose-contract <harness>` command; AGENTS bare-launch nudge; composer spec (per-tier anchor + Tier-3 byte-equality). Detail: scratchpads/p5-overlay-composer.md.
-
-## P6 — Docs, compliance matrix, alpha tag (#606) — feat/p6-docs-compliance-alpha
-
-- Status: in-repo deliverables done (CONTRIBUTING.md + harness×gate compliance matrix + check-resident-budget.sh + CI wiring + ALPHA-DOD.md). Remaining: alpha tag v0.0.39-alpha (Lead, post-merge). aiguide reconcile merged (#8). Detail: scratchpads/p6-docs-compliance-alpha.md.
-
-## F3-m3 — mosaic update re-seeds framework + relaunches agents (#609) — feat/f3-m3-update-reseed
-
-- Status: implemented + tested. Closes R13: `mosaic update` now re-seeds the framework (data-safe MOSAIC_SYNC_ONLY) after the CLI install so shipped launcher/runtime changes activate; `--relaunch` restarts rostered agents; `--no-reseed` opts out. Detail: scratchpads/f3-m3-update-reseed.md.
-
-## Fleet-polish bundle — boot-survival symmetry (#611) — feat/fleet-polish-bundle
-
-- Status: MERGED to main. disable-on-remove (boot-resurrection bug, TDD) + add-enable + init-R5 hard guarantee. 4 new + 147 existing fleet tests green. Detail: scratchpads/fleet-polish-bundle.md.
-
-## Fleet enhancer role + two-agent floor (#614) — feat/fleet-enhancer-floor
-
-- Status: MERGED to main. enhancer added to 4 presets; init guarantees 1 orchestrator + >=1 enhancer; remove protects the sole enhancer; enhancer role doc. 155 fleet tests green. Detail: scratchpads/fleet-enhancer-floor.md.
-
-## F4 — Orchestrator chat connector + Matrix (#616) — feat/f4-matrix-connector
-
-- Status: Phase 1 MERGED (#617: connector interface send/subscribe/health + registry + roster schema + design). Phase 2a (#618): Matrix CS-API client + factory. 20 connector tests green; no fleet.ts changes. Remaining Phase 2: init/configure connector-selection UX + roster wiring, systemd launch wiring, Conduit deploy guide. Detail: scratchpads/f4-matrix-connector.md.
-
-## Fleet onboarding-injection — comms cheat-sheet + peer roster (#620) — feat/fleet-comms-onboarding
-
-- Status: implemented + tested. Injects # Fleet Comms (peer roster + cross-host agent-send commands + FLIP-reply + --verify) into each spawned fleet agent via composeContract; optional per-agent host/ssh/socket roster fields (socket: named → -L, unset → default socket no -L). 10 + 2 tests green. Detail: scratchpads/fleet-comms-onboarding.md.
-
-## Fleet stand-up fixes — model_hint→--model + socket-default trap (#626) — feat/fleet-standup-fixes
-
-- Status: implemented + tested. FIX1 model_hint→MOSAIC_AGENT_MODEL→--model. FIX2 absent socket = default tmux socket (no -L) across parse/spawn/systemd-unit/observe (socketArgs helper, bare-empty shellEnvValue, conditional -L). 158 fleet tests green; shipped presets unaffected (explicit socket_name). Detail: scratchpads/fleet-standup-fixes.md.
-
-## north-star doctrine consolidation — doc PR — feat/north-star-doctrine
-
-- Status: applied Mos's consolidated merge-map to docs/fleet/north-star.md (budget governance + control plane/central register + 200k cap + delegation + unified-identity Fleet + role-based naming + tmux security + drift re-captures). Doctrine only; #622/#623/#625/#628 out-of-scope. Conflict checklist green. Detail: scratchpads/north-star-doctrine.md.
-
-## #631 — re-seed preserves user fleet data (CRITICAL) — fix/631-reseed-preserves-fleet-data
-
-- Status: implemented + tested. PRIMARY: install.sh PRESERVE_PATHS += fleet/\*.yaml + fleet/agents + fleet/run (glob-aware cp-fallback); TS parity. SECONDARY: refreshActiveFleetUnits propagates unit fixes to ~/.config/systemd/user on mosaic update. bash F6 + TS + unit tests green. Detail: scratchpads/631-reseed-preserves-fleet.md.
-
-## #633 — comms-block emitter + FLEET-LAUNCH runbook — feat/633-comms-block-runbook
-
-- Status: implemented + tested (TDD). `mosaic fleet comms-block <role> [--host]` wraps resolveCommsBlock → readFleetCommsBlock; fails loud (stderr + exit 1) on unknown role / missing roster instead of silent empty. docs/fleet/FLEET-LAUNCH.md runbook: worker path + orchestrator .env fold (MOSAIC_AGENT_COMMAND; line-41 [-z] short-circuits line-44 yolo hardcode) + 3 launch gotchas + #632 preserve note + North-Star 4-field arc (harness ✅/model ✅ roster-native today; yolo + command/channels = PATH B #636). 177 fleet+comms tests green (6 new resolveCommsBlock cases). PATH A of the A→B→webUI arc. Detail: scratchpads/633-comms-block-runbook.md.

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/ADR-MOS-EGRESS-GATEWAYS.md

@@ -1,151 +0,0 @@
-# ADR: Optional AI egress gateways for runtime-neutral Mos
-
-**Status:** Proposed for controlled prototypes; not approved as Mosaic core
-
-**Date:** 2026-07-14
-
-**Issues:** #754, #755
-
-**Decision owner:** Mosaic Gateway / provider-adapter architecture
-
-## Context
-
-The emergency Mos continuity path kept Claude Code as the harness and translated Anthropic Messages traffic to Codex OAuth through a small localhost proxy. That preserved the existing Claude Discord plugin and transcript, but exposed two architectural facts:
-
-1. Harness identity, channel entitlement, provider credentials, and inference transport are separate concerns.
-2. A generic AI gateway can improve provider routing, budgets, and observability, but must not become Mosaic's identity, authorization, tenant, or orchestration boundary.
-
-The Tess qualification report also found that current provider rebinding is not identity-continuous failover. Mosaic still needs a logical agent identity, durable connector lease/fencing, canonical handoff/checkpoint, exactly-once receipts, concrete harness adapters, and cross-harness rollback E2E.
-
-## Decision
-
-Mosaic MAY support LiteLLM, Bifrost, the purpose-built Claude/Codex proxy, or future gateways as optional egress implementations behind `IProviderAdapter` / `AgentRuntimeProvider`.
-
-Mosaic Gateway remains authoritative for:
-
-- authenticated actor and tenant identity;
-- logical agent identity and connector binding;
-- authorization, approval, and policy;
-- lease epoch and stale-holder fencing;
-- audit correlation and redaction;
-- canonical handoff/checkpoint state;
-- idempotency and side-effect receipts.
-
-An egress gateway MUST NOT:
-
-- receive channel ingress directly;
-- authorize tools or connector ownership;
-- define Mosaic tenant or agent identity;
-- persist raw Mosaic handoffs or channel credentials;
-- bypass adapter capability negotiation;
-- silently fail over when policy, lease, or provider health is uncertain.
-
-Allowed topology:
-
-```text
-Discord / Matrix / CLI / web
-        ↓
-Mosaic Gateway: identity, authz, lease/fence, approvals, audit
-        ↓
-IProviderAdapter / AgentRuntimeProvider
-        ↓
-optional egress gateway
-        ↓
-upstream provider or subscription-backed OAuth session
-```
-
-## Candidate assessment
-
-### Purpose-built `raine/claude-code-proxy`
-
-**Disposition:** Approved only for the verified emergency localhost bridge.
-
-Strengths:
-
-- explicit Codex device OAuth flow;
-- small operational surface;
-- Anthropic Messages translation suitable for Claude Code;
-- model and reasoning-effort enforcement;
-- straightforward loopback systemd supervision and rollback.
-
-Constraints:
-
-- not a Mosaic multi-tenant control plane;
-- Claude built-in channels still depend on Claude subscription entitlement and feature lookup;
-- model aliases can obscure the upstream model unless proxy policy/logs are treated as evidence;
-- no replacement for connector leasing, canonical handoff, or exactly-once effects.
-
-### LiteLLM
-
-**Disposition:** Candidate for a formal adapter-only prototype and terms/security review.
-
-Current documentation states that ChatGPT subscription access is available through an OAuth device-code flow. LiteLLM also provides broad provider routing, virtual keys, budgets, observability, and OpenAI/Anthropic-compatible surfaces.
-
-Required prototype gates:
-
-- verify the exact ChatGPT subscription OAuth flow and supported models against current provider terms;
-- document token location, encryption, revocation, refresh, scope, and incident response;
-- prove tenant isolation and prevent virtual keys from becoming Mosaic principals;
-- verify streaming, tool calls, reasoning controls, cancellation, and idempotency metadata;
-- fail closed instead of selecting an unhealthy provider merely to return a result;
-- demonstrate that Mosaic audit correlation survives gateway retries/failover;
-- keep channel ingress and connector credentials outside LiteLLM.
-
-Source references:
-
-- [LiteLLM ChatGPT subscription provider](https://docs.litellm.ai/docs/providers/chatgpt)
-- [LiteLLM providers](https://docs.litellm.ai/docs/providers)
-
-### Bifrost
-
-**Disposition:** Candidate for governance/routing research; subscription OAuth compatibility unverified.
-
-Useful concepts include virtual keys, budgets, rate limits, weighted load balancing, and automatic provider failover. Those features may inform Mosaic egress policy, but Bifrost virtual keys are downstream credentials—not Mosaic actors or tenants.
-
-Required prototype gates:
-
-- verify Codex/ChatGPT subscription OAuth rather than assuming API-key compatibility;
-- map budgets and virtual keys to server-derived Mosaic tenants without duplicating authority;
-- prove failover does not violate connector lease, approval, or exactly-once semantics;
-- ensure request/response logs are redacted before persistence;
-- disable or constrain automatic failover when policy or side-effect state is ambiguous.
-
-Source references:
-
-- [Bifrost overview](https://docs.getbifrost.ai/overview)
-- [Bifrost repository](https://github.com/maximhq/bifrost)
-
-### `teremterem/claude-code-gpt-5-codex`
-
-**Disposition:** Not selected as the emergency implementation; useful as a historical LiteLLM recipe.
-
-The reviewed repository uses `OPENAI_API_KEY`, tells previously authenticated Claude users to log out, and documents a Claude Web Search schema incompatibility. Logging Claude out conflicts with the channel-entitlement requirement observed in the live Mos cutover. The repository therefore does not, as provided, satisfy subscription-OAuth plus built-in-channel continuity.
-
-Source references:
-
-- [Repository](https://github.com/teremterem/claude-code-gpt-5-codex)
-- [Environment template](https://github.com/teremterem/claude-code-gpt-5-codex/blob/main/.env.template)
-
-## Security consequences
-
-- Subscription OAuth grants are high-value credentials and require the same lifecycle controls as service credentials.
-- Downstream virtual keys reduce provider-key exposure but do not establish user, tenant, or agent authority.
-- Automatic retry/failover can duplicate tool or external side effects unless Mosaic owns operation IDs and receipts.
-- Gateway telemetry can contain prompts, tool schemas, and model output; redaction and retention policy must apply before persistence.
-- A localhost unauthenticated translation endpoint must remain loopback-only and process-isolated.
-
-## Acceptance before production use
-
-1. Threat model and provider-terms review approved.
-2. Credential lifecycle and revocation drill documented and exercised.
-3. Adapter contract tests pass for streaming, tools, cancellation, reasoning policy, errors, and audit correlation.
-4. Tenant-bound authorization remains entirely in Mosaic Gateway.
-5. Failure injection proves no duplicate side effects across retries or provider failover.
-6. Rollback to the prior provider path is exercised.
-7. Independent code and security reviews approve the exact deployed revision.
-
-## Follow-up
-
-- #754 owns cross-harness logical identity, checkpoint, receipt, adapter, and failover work.
-- #755 / PR #757 implements the first logical identity and connector lease/fencing boundary.
-- A later issue should prototype LiteLLM and Bifrost behind the provider adapter after #755 is merged and independently qualified.

docs/architecture/channel-protocol.md

@@ -1,747 +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.
-
-### Discord service ingress security
-
-The Discord adapter is an authenticated gateway service, not an anonymous Socket.IO client. It presents `DISCORD_SERVICE_TOKEN` during its `/chat` connection and signs each inbound envelope using HMAC-SHA-256. The envelope contains the Discord native message ID and a generated correlation ID. Gateway verifies the service credential, signature, and configured guild/channel/user allowlists before agent dispatch, then rejects duplicate native message IDs inside its bounded replay window. All three allowlists are default-deny and required when the Discord plugin is enabled. The service credential is injected at runtime and is never logged or included in protocol payloads.
-
----
-
-### 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/federation/SETUP.md

@@ -1,280 +0,0 @@
-# Federated Tier Setup Guide
-
-## What is the federated tier?
-
-The federated tier is designed for multi-user and multi-host deployments. It consists of PostgreSQL 17 with pgvector extension (for embeddings and RAG), Valkey for distributed task queueing and caching, and a shared configuration across multiple Mosaic gateway instances. Use this tier when running Mosaic in production or when scaling beyond a single-host deployment.
-
-## Prerequisites
-
-- Docker and Docker Compose installed
-- Ports 5433 (PostgreSQL) and 6380 (Valkey) available on your host (or adjust environment variables)
-- At least 2 GB free disk space for data volumes
-
-## Start the federated stack
-
-Run the federated overlay:
-
-```bash
-docker compose -f docker-compose.federated.yml --profile federated up -d
-```
-
-This starts PostgreSQL 17 with pgvector and Valkey 8. The pgvector extension is created automatically on first boot.
-
-Verify the services are running:
-
-```bash
-docker compose -f docker-compose.federated.yml ps
-```
-
-Expected output shows `postgres-federated` and `valkey-federated` both healthy.
-
-## Configure mosaic for federated tier
-
-Create or update your `mosaic.config.json`:
-
-```json
-{
-  "tier": "federated",
-  "database": "postgresql://mosaic:mosaic@localhost:5433/mosaic",
-  "queue": "redis://localhost:6380"
-}
-```
-
-If you're using environment variables instead:
-
-```bash
-export DATABASE_URL="postgresql://mosaic:mosaic@localhost:5433/mosaic"
-export REDIS_URL="redis://localhost:6380"
-```
-
-## Verify health
-
-Run the health check:
-
-```bash
-mosaic gateway doctor
-```
-
-Expected output (green):
-
-```
-Tier: federated  Config: mosaic.config.json
-  ✓ postgres         localhost:5433       (42ms)
-  ✓ valkey           localhost:6380       (8ms)
-  ✓ pgvector         (embedded)           (15ms)
-```
-
-For JSON output (useful in CI/automation):
-
-```bash
-mosaic gateway doctor --json
-```
-
-## Step 2: Step-CA Bootstrap
-
-Step-CA is a certificate authority that issues X.509 certificates for federation peers. In Mosaic federation, it signs peer certificates with custom OIDs that embed grant and user identities, enforcing authorization at the certificate level.
-
-### Prerequisites for Step-CA
-
-Before starting the CA, you must set up the dev password:
-
-```bash
-cp infra/step-ca/dev-password.example infra/step-ca/dev-password
-# Edit dev-password and set your CA password (minimum 16 characters)
-```
-
-The password is required for the CA to boot and derive the provisioner key used by the gateway.
-
-### Start the Step-CA service
-
-Add the step-ca service to your federated stack:
-
-```bash
-docker compose -f docker-compose.federated.yml --profile federated up -d step-ca
-```
-
-On first boot, the init script (`infra/step-ca/init.sh`) runs automatically. It:
-
-- Generates the CA root key and certificate in the Docker volume
-- Creates the `mosaic-fed` JWK provisioner
-- Applies the X.509 template from `infra/step-ca/templates/federation.tpl`
-
-The volume is persistent, so subsequent boots reuse the existing CA keys.
-
-Verify the CA is healthy:
-
-```bash
-curl https://localhost:9000/health --cacert /tmp/step-ca-root.crt
-```
-
-(If the root cert file doesn't exist yet, see the extraction steps below.)
-
-### Extract credentials for the gateway
-
-The gateway requires two credentials from the running CA:
-
-**1. Provisioner key (for `STEP_CA_PROVISIONER_KEY_JSON`)**
-
-```bash
-docker exec $(docker ps -qf name=step-ca) cat /home/step/secrets/mosaic-fed.json > /tmp/step-ca-provisioner.json
-```
-
-This JSON file contains the JWK public and private keys for the `mosaic-fed` provisioner. Store it securely and pass its contents to the gateway via the `STEP_CA_PROVISIONER_KEY_JSON` environment variable.
-
-**2. Root certificate (for `STEP_CA_ROOT_CERT_PATH`)**
-
-```bash
-docker cp $(docker ps -qf name=step-ca):/home/step/certs/root_ca.crt /tmp/step-ca-root.crt
-```
-
-This PEM file is the CA's root certificate, used to verify peer certificates issued by step-ca. Pass its path to the gateway via `STEP_CA_ROOT_CERT_PATH`.
-
-### Custom OID Registry
-
-Federation certificates include custom OIDs in the certificate extension. These encode authorization metadata:
-
-| OID                 | Name                   | Description           |
-| ------------------- | ---------------------- | --------------------- |
-| 1.3.6.1.4.1.99999.1 | mosaic_grant_id        | Federation grant UUID |
-| 1.3.6.1.4.1.99999.2 | mosaic_subject_user_id | Subject user UUID     |
-
-These OIDs are verified by the gateway after the CSR is signed, ensuring the certificate was issued with the correct grant and user context.
-
-### Environment Variables
-
-Configure the gateway with the following environment variables before startup:
-
-| Variable                       | Required | Description                                                                                               |
-| ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------- |
-| `STEP_CA_URL`                  | Yes      | Base URL of the step-ca instance, e.g. `https://step-ca:9000` (use `https://localhost:9000` in local dev) |
-| `STEP_CA_PROVISIONER_KEY_JSON` | Yes      | JSON-encoded JWK from `/home/step/secrets/mosaic-fed.json`                                                |
-| `STEP_CA_ROOT_CERT_PATH`       | Yes      | Absolute path to the root CA certificate (e.g. `/tmp/step-ca-root.crt`)                                   |
-| `BETTER_AUTH_SECRET`           | Yes      | Secret used to seal peer private keys at rest; already required for M1                                    |
-
-Example environment setup:
-
-```bash
-export STEP_CA_URL="https://localhost:9000"
-export STEP_CA_PROVISIONER_KEY_JSON="$(cat /tmp/step-ca-provisioner.json)"
-export STEP_CA_ROOT_CERT_PATH="/tmp/step-ca-root.crt"
-export BETTER_AUTH_SECRET="<your-secret>"
-```
-
-## Troubleshooting
-
-### Port conflicts
-
-**Symptom:** `bind: address already in use`
-
-**Fix:** Stop the base dev stack first:
-
-```bash
-docker compose down
-docker compose -f docker-compose.federated.yml --profile federated up -d
-```
-
-Or change the host port with an environment variable:
-
-```bash
-PG_FEDERATED_HOST_PORT=5434 VALKEY_FEDERATED_HOST_PORT=6381 \
-  docker compose -f docker-compose.federated.yml --profile federated up -d
-```
-
-### pgvector extension error
-
-**Symptom:** `ERROR: could not open extension control file`
-
-**Fix:** pgvector is created at first boot. Check logs:
-
-```bash
-docker compose -f docker-compose.federated.yml logs postgres-federated | grep -i vector
-```
-
-If missing, exec into the container and create it manually:
-
-```bash
-docker exec <postgres-federated-id> psql -U mosaic -d mosaic -c "CREATE EXTENSION vector;"
-```
-
-### Valkey connection refused
-
-**Symptom:** `Error: connect ECONNREFUSED 127.0.0.1:6380`
-
-**Fix:** Check service health:
-
-```bash
-docker compose -f docker-compose.federated.yml logs valkey-federated
-```
-
-If Valkey is running, verify your firewall allows 6380. On macOS, Docker Desktop may require binding to `host.docker.internal` instead of `localhost`.
-
-## Key rotation (deferred)
-
-Federation peer private keys (`federation_peers.client_key_pem`) are sealed at rest using AES-256-GCM with a key derived from `BETTER_AUTH_SECRET` via SHA-256. If `BETTER_AUTH_SECRET` is rotated, all sealed `client_key_pem` values in the database become unreadable and must be re-sealed with the new key before rotation completes.
-
-The full key rotation procedure (decrypt all rows with old key, re-encrypt with new key, atomically swap the secret) is out of scope for M2. Operators must not rotate `BETTER_AUTH_SECRET` without a migration plan for all sealed federation peer keys.
-
-## OID Assignments — Mosaic Internal OID Arc
-
-Mosaic uses the private enterprise arc `1.3.6.1.4.1.99999` for custom X.509
-certificate extensions in federation grant certificates.
-
-**IMPORTANT:** This is a development/internal OID arc. Before deploying to a
-production environment accessible by external parties, register a proper IANA
-Private Enterprise Number (PEN) at <https://pen.iana.org/pen/PenApplication.page>
-and update these assignments accordingly.
-
-### Assigned OIDs
-
-| OID                   | Symbolic name                     | Description                                               |
-| --------------------- | --------------------------------- | --------------------------------------------------------- |
-| `1.3.6.1.4.1.99999.1` | `mosaic.federation.grantId`       | UUID of the `federation_grants` row authorising this cert |
-| `1.3.6.1.4.1.99999.2` | `mosaic.federation.subjectUserId` | UUID of the local user on whose behalf the cert is issued |
-
-### Encoding
-
-Each extension value is DER-encoded as an ASN.1 **UTF8String**:
-
-```
-Tag    0x0C        (UTF8String)
-Length 0x24        (36 decimal — fixed length of a UUID string)
-Value  <36 ASCII bytes of the UUID>
-```
-
-The step-ca X.509 template at `infra/step-ca/templates/federation.tpl`
-produces this encoding via the Go template expression:
-
-```
-{{ printf "\x0c\x24%s" .Token.mosaic_grant_id | b64enc }}
-```
-
-The resulting base64 value is passed as the `value` field of the extension
-object in the template JSON.
-
-### CA Environment Variables
-
-The `CaService` (`apps/gateway/src/federation/ca.service.ts`) requires the
-following environment variables at gateway startup:
-
-| Variable                       | Required | Description                                                          |
-| ------------------------------ | -------- | -------------------------------------------------------------------- |
-| `STEP_CA_URL`                  | Yes      | Base URL of the step-ca instance, e.g. `https://step-ca:9000`        |
-| `STEP_CA_PROVISIONER_PASSWORD` | Yes      | JWK provisioner password for the `mosaic-fed` provisioner            |
-| `STEP_CA_PROVISIONER_KEY_JSON` | Yes      | JSON-encoded JWK (public + private) for the `mosaic-fed` provisioner |
-| `STEP_CA_ROOT_CERT_PATH`       | Yes      | Absolute path to the step-ca root CA certificate PEM file            |
-
-Set these variables in your environment or secret manager before starting
-the gateway. In the federated Docker Compose stack they are expected to be
-injected via Docker secrets and environment variable overrides.
-
-### Fail-loud contract
-
-The CA service (and the X.509 template) are designed to fail loudly if the
-custom OIDs cannot be embedded:
-
-- The template produces a malformed extension value (zero-length UTF8String
-  body) when the JWT claims `mosaic_grant_id` or `mosaic_subject_user_id` are
-  absent. step-ca rejects the CSR rather than issuing a cert without the OIDs.
-- `CaService.issueCert()` throws a `CaServiceError` on every error path with
-  a human-readable `remediation` string. It never silently returns a cert that
-  may be missing the required extensions.

docs/fleet/FLEET-LAUNCH.md

@@ -1,114 +0,0 @@
-# Fleet Launch Runbook
-
-How every Mosaic fleet agent — workers **and** the orchestrator — is launched, and how to
-configure each one. The guiding principle: **one roster-driven launcher**. There is no bespoke
-per-agent launch script; the roster plus per-agent `.env` files are the single source of launch
-config.
-
-## The launch chain
-
-| Layer            | File                                              | Responsibility                                                                                                                                              |
-| ---------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| systemd unit     | `mosaic-agent@<role>.service`                     | One templated unit per role; `ExecStart` runs the session launcher with the instance name `%i`. Defaults `MOSAIC_AGENT_RUNTIME=pi`, `MOSAIC_AGENT_NAME=%i`. |
-| session launcher | `tools/fleet/start-agent-session.sh <role>`       | Builds the launch command, opens the tmux pane, wires the heartbeat.                                                                                        |
-| launch command   | `mosaic yolo <runtime>` (or a per-agent override) | Replaces the pane's foreground process with the runtime, fully seeded.                                                                                      |
-| seeding          | `mosaic`'s `composeContract()`                    | Injects the Constitution/USER/TOOLS/runtime contract, `*.local` overlays, **and** the Fleet-Comms cheat-sheet — all via `--append-system-prompt`.           |
-
-Per-agent overrides live in `fleet/agents/<role>.env`, generated from `roster.yaml` by
-`generateAgentEnv` (`packages/mosaic/src/commands/fleet.ts`) and consumed by the launcher.
-
-## Worker launch path (default)
-
-1. `roster.yaml` carries each agent's `runtime` and optional `model_hint`.
-2. `generateAgentEnv` emits `fleet/agents/<role>.env` with `MOSAIC_AGENT_NAME`,
-   `MOSAIC_AGENT_RUNTIME`, and `MOSAIC_AGENT_MODEL`.
-3. `start-agent-session.sh` has no `MOSAIC_AGENT_COMMAND` set, so it falls through to the default
-   (line ~44):
-   ```sh
-   MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}"
-   ```
-4. The launcher bakes `MOSAIC_AGENT_NAME` into the pane command (line ~118), so `composeContract`
-   can inject the Fleet-Comms cheat-sheet for that role.
-
-That is the whole worker path: roster → `.env` → `mosaic yolo <runtime>` → seeded pane.
-
-## Orchestrator fold (PATH A — ships today)
-
-The orchestrator is **just another roster agent** launched through the canonical path — not a
-snowflake script.
-
-| Piece              | Value                               |
-| ------------------ | ----------------------------------- |
-| host-side launcher | `orchestrator-launch.sh`            |
-| systemd unit       | `mosaic-fleet-orchestrator.service` |
-| tmux session       | `orchestrator` (role-named)         |
-
-Set its launch command via `fleet/agents/orchestrator.env`:
-
-```sh
-MOSAIC_AGENT_COMMAND='mosaic yolo claude --channels plugin:discord@<channel>'
-```
-
-When `MOSAIC_AGENT_COMMAND` is set, `start-agent-session.sh`'s `if [ -z "$MOSAIC_AGENT_COMMAND" ]`
-guard (line ~41) is false, so the line-44 default — **including its hardcoded `yolo`** — is skipped
-entirely. The override fully controls the runtime and flags. Routing through `mosaic yolo claude`
-(rather than a raw `claude` invocation) is what gives the orchestrator the same full
-`composeContract` seeding + Fleet-Comms cheat-sheet as every worker, with `--channels` and any
-other flags passed straight through to the `claude` binary.
-
-## Launch gotchas
-
-1. **Flag conflict.** `mosaic yolo claude` already injects `--dangerously-skip-permissions`. Do
-   **not** also pass `--permission-mode bypassPermissions` — the `claude` binary would receive both.
-   Use `mosaic yolo claude …` alone (yolo covers the unattended posture), **or** non-yolo
-   `mosaic claude --permission-mode bypassPermissions …`. Never mix the two.
-2. **`MOSAIC_AGENT_NAME` must reach the pane.** The launcher bakes it from the instance name, and
-   `composeContract` gates the Fleet-Comms block on it (`launch.ts`, in `composeContract`) — **and**
-   the role must be a member of `roster.yaml`, or the block resolves empty.
-3. **`launchRuntime` guards.** `mosaic yolo claude` runs `checkSoul` / `checkRuntime` /
-   `checkSequentialThinking`. The host needs `SOUL.md` and the sequential-thinking MCP, or the
-   launch aborts (a raw `claude` invocation skipped these checks). Dry-run the composed command in a
-   throwaway tmux session before swapping a live launcher.
-
-## Why per-agent `.env` survives upgrades (#632)
-
-`install.sh` `PRESERVE_PATHS` includes `fleet/*.yaml`, `fleet/agents`, and `fleet/run`, so
-`mosaic update`'s framework re-seed **preserves** your roster and per-agent `.env` overrides
-(glob-aware `cp` fallback; matching TS parity in `file-adapter.ts`). Before #632, an auto re-seed
-could wipe them — which is exactly why PATH A's `.env` override is safe to rely on now.
-
-## Inspecting the comms wiring
-
-- `mosaic fleet comms-block <role>` prints the Fleet-Comms cheat-sheet a given role receives at
-  launch — its `[host:session]` identity, the exact `agent-send.sh` command for each peer, and the
-  FLIP / `--verify` conventions. `--host <h>` previews a cross-host view. An unknown role or missing
-  roster **fails loud** (stderr + non-zero exit), so a typo is never a silent no-op.
-- Versus `mosaic compose-contract <runtime>`: that emits the **whole** system prompt and reads the
-  role from `MOSAIC_AGENT_NAME` (a full-prompt smoke test). `comms-block` is the targeted,
-  explicit-arg, comms-only view — e.g. `mosaic fleet comms-block coder0-0` to preview a peer.
-
-## North Star / future direction
-
-**Vision:** a webUI lets the user edit each agent's launch config — switch **harness**
-(claude / pi / codex / opencode), toggle **yolo**, pick a **model**, set a **command/channels**
-override — with no terminal.
-
-**Continuity — this is not a new launch path.** It is a data-model + UI-binding layer over the
-existing roster-driven launcher. Field-by-field status today:
-
-| Launch-config field      | Roster-native today? | Mechanism / gap                                                                                                                                          |
-| ------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **harness** (`runtime`)  | ✅ end-to-end        | `roster.runtime` → `generateAgentEnv` emits `MOSAIC_AGENT_RUNTIME` → launcher line 44. UI just writes the field.                                         |
-| **model** (`model_hint`) | ✅ end-to-end        | `roster.model_hint` → `MOSAIC_AGENT_MODEL` → launcher line 44 `--model`. UI just writes the field.                                                       |
-| **yolo**                 | ❌ new               | Launcher line 44 **hardcodes** `mosaic yolo`. A non-yolo toggle needs a roster `yolo` field → emit `MOSAIC_AGENT_YOLO` → make line 44 conditional.       |
-| **command / channels**   | ❌ new               | `MOSAIC_AGENT_COMMAND` is **consumed** (launcher line ~12) but `generateAgentEnv` does not emit it. Needs a roster `command`/`channels` field → emitted. |
-
-**The arc:**
-
-- **A** — `.env` `MOSAIC_AGENT_COMMAND` hatch: manual, ships now, kept safe across upgrades by #632.
-- **B** — roster-native launch-config: harness + model are already there; add the **yolo** toggle
-  (line-44 conditional) and **command/channels** emission to complete the data model.
-- **webUI** — binds dropdowns/toggles directly to those four roster fields.
-
-PATH A's `.env` override is the **manual form** of exactly what PATH B makes roster-native and the
-webUI edits — one continuous arc, not three separate features. PATH B is tracked as #636.

docs/fleet/NORTH_STAR.md

@@ -1,79 +0,0 @@
-# Mosaic Fleet — NORTH STAR
-
-> **Generated file — do not edit by hand.**
-> Projected deterministically from [`NORTH_STAR.yaml`](./NORTH_STAR.yaml) by the pure
-> generator in `packages/mosaic/src/commands/fleet.ts` (`renderNorthStarMarkdown`).
-> Edit the YAML, then regenerate. Self-contained Mosaic — no Hermes dependency.
-
-## Mission
-
-A self-driving Mosaic system that 24/7 unattended converts a machine-readable goal set into merged, CI-green, budget-bounded change — looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native backlog/dispatch engine. Mosaic is general-purpose: the user declares the system type they want (software delivery, personal assistant, research, business/operations, …) and the orchestrator provisions the matching persona roster and structure; the delivery fleet is one profile among many.
-
-## Substrate
-
-The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's native Postgres storage service (@mosaicstack/db drizzle; PGlite-embedded by default, full Postgres by config). NOT Hermes.
-
-## Standing objectives
-
-- **NS-1** — Single machine-readable source (this file) drives planning; prose docs are projections.
-- **NS-2** — Every backlog item is an independently-shippable unit with stable id, priority, depends_on DAG, represented as a Mosaic Backlog card; spend tracked as advisory projection.
-- **NS-3** — The supervisor guarantees movement: no idle agent while ready dependency-satisfied work exists; no empty backlog without a replan request; assignment via Mosaic native dispatch/claim.
-- **NS-4** — Exactly one merge-gate approver; nothing reaches main except via pr-merge.sh after pr-ci-wait.sh success; Gitea branch protection is the backstop.
-- **NS-5** — Every unit bounded by wall-clock TTL on its claim; token caps enforced only where a real meter exists, else advisory.
-- **NS-6** — Context cleared between tasks for ephemeral runners (reset_between_tasks); persona+mission re-injected per task.
-- **NS-7** — Meta-loop (session-review + enhancer) continuously proposes small fleet-improvement PRs.
-- **NS-8** — Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored before every dispatch and every merge.
-- **NS-9** — Mosaic is a general-purpose multi-agent system: the user declares the SYSTEM TYPE to run (e.g. software delivery, personal assistant, research, business/operations) and the orchestrator provisions the matching persona roster and org structure from a cross-domain baseline persona library; the delivery/coding fleet is one profile among many.
-
-## Success criteria
-
-- **AC-NS-1** — The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer) healthy across reboot.
-- **AC-NS-2** — A goal added to this YAML is decomposed to cards and either merged or escalated, with no human in the loop.
-- **AC-NS-3** — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
-- **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
-- **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
-- **AC-NS-6** — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
-- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives `mosaic update`: baseline reseed never clobbers user overrides.
-
-## Workstreams
-
-| id  | title                                                                                                       |
-| --- | ----------------------------------------------------------------------------------------------------------- |
-| A   | Substrate — Mosaic Backlog on native Postgres storage service                                               |
-| B   | Supervisor — movement guarantee, two-agent floor, dispatch/claim                                            |
-| C   | Planner — goal decomposition into independently-shippable cards                                             |
-| D   | Merge-gate — single approver, pr-merge.sh after CI wait                                                     |
-| E   | Meta-loop — session-review + enhancer improvement PRs                                                       |
-| F   | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch                                                |
-| H   | Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization |
-
-## Goals (backlog projection)
-
-| id  | title                                                                                                                                             | phase | priority    | depends_on |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----------- | ---------- |
-| A1  | Machine-readable NORTH_STAR.yaml + Markdown projection                                                                                            | 1     | must-have   | —          |
-| A2  | Mosaic Backlog schema + storage-service card store (drizzle/PGlite)                                                                               | 1     | must-have   | A1         |
-| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG                                                                            | 1     | must-have   | A2         |
-| A3b | TTL-bounded claim enforcement (wall-clock) on cards                                                                                               | 1     | must-have   | A3a        |
-| A4  | Advisory spend projection per card (degrades to TTL, no real meter)                                                                               | 1     | should-have | A3a        |
-| B1  | Supervisor tick — readiness scan, two-agent-floor health check                                                                                    | 2     | must-have   | A3a        |
-| B2  | Native dispatch/claim — assign ready dependency-satisfied work                                                                                    | 2     | must-have   | A3b, B1    |
-| B3a | Planner decompose — goal added to YAML → cards                                                                                                    | 2     | must-have   | A2, B1     |
-| B3b | Replan request on empty backlog; escalate on no-decompose                                                                                         | 2     | should-have | B3a        |
-| G1  | PAUSE kill-switch + merge-gate honored before dispatch and merge                                                                                  | 2     | must-have   | B2         |
-| H1  | Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles)                                             | 1     | must-have   | A1         |
-| H2  | System-type profiles — declarative mapping of system type to persona roster + topology                                                            | 2     | must-have   | H1         |
-| H3  | System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure                                          | 2     | must-have   | H2         |
-| H4  | Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides) | 2     | must-have   | H1         |
-
-## Assumptions (vetoable)
-
-- **ASM-1** (vetoable) — The Mosaic Backlog on the native Postgres storage service is the backlog of record.
-- **ASM-2** (vetoable) — Claude gate roles have no native busy status, so readiness = pane-idle + heartbeat.
-- **ASM-3** (vetoable) — Two-agent floor = 1 orchestrator + >=1 enhancer.
-- **ASM-4** (vetoable) — Baseline personas ship in framework/fleet/roles/ (reseeded on update); user overrides live in a separate PRESERVE_PATHS-protected layer and win on merge.
-
-## Spend
-
-- **advisory:** true
-- No per-task token meter yet; budgets degrade to TTL. Spend is tracked only as an advisory projection alongside each card.

docs/fleet/TASKS.md

@@ -1,27 +0,0 @@
-# Tasks — W-FLEET (Fleet) Phase 2: Observability
-
-> Workstream task file for the Fleet. Single-writer: Fleet workstream lead (orchestrator).
-> Workers read but never modify. This is **not** the MVP rollup (`docs/TASKS.md`) — a
-> rollup row is proposed to the MVP orchestrator, not written here.
->
-> Mission: `mvp-20260312` · PRD: [docs/fleet/PRD.md](./PRD.md) · North star: [docs/fleet/north-star.md](./north-star.md)
-> Status: `not-started` | `in-progress` | `done` | `blocked` | `failed`
-
-| id            | status      | description                                                                                                        | depends_on            | agent       | pr  | notes                                                                                                                       |
-| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | --------------------- | ----------- | --- | --------------------------------------------------------------------------------------------------------------------------- |
-| FLEET-OBS-000 | done        | Plan: north-star + Phase-2 PRD + workstream scaffolding                                                            | —                     | lead        | —   | persisted 2026-06-20 on `feat/fleet-observability`                                                                          |
-| FLEET-OBS-001 | done        | Heartbeat protocol v1 spec finalized in PRD + framework doc                                                        | FLEET-OBS-000         | lead        | —   | file-based `~/.config/mosaic/fleet/run/<agent>.hb`; spec in PRD                                                             |
-| FLEET-OBS-002 | in-progress | Implement heartbeat responder in `dogfood-agent.py`                                                                | FLEET-OBS-001         | fleet-coder | —   | dispatched to ad-hoc `mosaic yolo` fleet agent (dogfood)                                                                    |
-| FLEET-OBS-003 | done        | `mosaic fleet ps` — join systemd+tmux+proc+idle+heartbeat; tenant+host tagged; drift + boot-enable flags; `--json` | FLEET-OBS-001         | worker      | —   | commit ab47831; LIVE-verified on mosaic-fleet; caught canary-pi DRIFT + BOOT-ENABLE. Polish: idleSeconds parse returns null |
-| FLEET-OBS-004 | done        | `mosaic agent watch <name>` — read-only join (no resize, no keystrokes)                                            | FLEET-OBS-000         | worker      | —   | `attach -r`; verb wired                                                                                                     |
-| FLEET-OBS-005 | done        | `mosaic agent send --verify` — delivery/acceptance receipt                                                         | FLEET-OBS-000         | worker      | —   | --verify flag; draft-heuristic verify                                                                                       |
-| FLEET-OBS-006 | done        | CLI specs for ps/watch/send-verify (tenant+host shape, command construction)                                       | FLEET-OBS-003,004,005 | worker      | —   | 62 tests green (31 new); re-verified by lead                                                                                |
-| FLEET-OBS-007 | not-started | Framework doc: fleet observability guide + verbs                                                                   | FLEET-OBS-003,004,005 | lead        | —   | `docs/guides/` or `framework/tools/.../README`                                                                              |
-| FLEET-OBS-008 | not-started | Independent review + dogfood verification on live fleet                                                            | FLEET-OBS-002..007    | reviewer    | —   | author ≠ reviewer; capture evidence in scratchpad                                                                           |
-| FLEET-OBS-009 | not-started | Open PR → green CI (queue guard) → squash-merge → close `fleet-observability-1`                                    | FLEET-OBS-008         | lead        | —   | trunk merge; no direct push to main                                                                                         |
-
-## Proposed MVP rollup row (for the MVP orchestrator — not written by this workstream)
-
-```
-| W-FLEET | in-progress | Fleet (agent-session execution layer) | Phase 2/5 | docs/fleet/TASKS.md | observability dogfooded on live stub fleet; control plane rides federation (W1) |
-```

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).