GA 1/11 · roadmap, model-router service-token auth, runtime spec plumbing, quota leak, tenant-scoped idempotency

.claude/settings.json

@@ -1,5 +1,15 @@
 {
   "enabledPlugins": {
-    "frontend-design@claude-plugins-official": true
+    "frontend-design@claude-plugins-official": true,
+    "core@compass": true
+  },
+  "extraKnownMarketplaces": {
+    "compass": {
+      "source": {
+        "source": "github",
+        "repo": "dshakes/compass",
+        "ref": "v0.6.0"
+      }
+    }
   }
 }

.env.example

@@ -156,6 +156,115 @@
 # System-prompt augmentation included in every WhatsApp turn.
 #LANTERN_SYSTEM_PROMPT=You are Shekhar's WhatsApp assistant. Be brief.
 
+# ============================================================================
+# WHATSAPP BRIDGE — FUTURISTIC FEATURES
+# ============================================================================
+#
+# These tune the "personal assistant" behavior layer on top of the bridge:
+#
+# Quiet hours: skip auto-reply during sleep hours so contacts don't see
+# replies at 3am — biggest bot-tell short of an instant typing indicator.
+# Inbound notifications still arrive on your phone normally. Both hours
+# are 0..23 (24h). Default: 22..07 (10pm–7am). Set BOTH or neither.
+#LANTERN_OWNER_TIMEZONE=America/Los_Angeles
+#LANTERN_QUIET_START=22
+#LANTERN_QUIET_END=7
+#
+# Voice notes: inbound voice gets transcribed via Whisper and treated
+# as text. Requires OPENAI_API_KEY above. (No outbound voice yet —
+# voice cloning needs per-user training; future ENV flag.)
+#
+# Image understanding: inbound images get described via the vision LLM.
+# Routes through /v1/completions so it uses whatever provider keys the
+# tenant has configured. No additional setup beyond the LLM keys.
+
+# ============================================================================
+# WHATSAPP BRIDGE — STATUS DELIVERY FALLBACKS
+# ============================================================================
+#
+# When WhatsApp's Signal session falls into 'Waiting for this message'
+# limbo, the bridge's /lantern responses + /bot confirmations stop
+# reaching your phone. Configure ONE OR MORE of the channels below and
+# the bridge mirrors every status reply to them. Pick whatever you
+# actually use:
+
+# --- Email mirror (universal, recommended) ---
+# Routes via your already-configured Gmail connector at /connectors.
+# Subject = first line of the reply ("Lantern · 🟢 active"). Throttled
+# to one email per unique-text per 30s and skips short reactions.
+#LANTERN_OWNER_EMAIL=
+
+# --- Telegram bot mirror ---
+#
+# When WhatsApp's Signal session is in a stale-key 'Waiting for this
+# message' loop, bridge replies still need to reach you on your phone.
+# Configure a Telegram bot here and every /lantern reply, /bot
+# confirmation, pairing notification, etc. ALSO arrives via Telegram
+# instantly with no E2E key issues.
+#
+# Setup (90 seconds):
+#   1. On Telegram, message @BotFather → /newbot → follow prompts
+#      → paste the bot token below.
+#   2. Send your new bot any message ("hi") from your account.
+#   3. Get your chat id: open
+#      https://api.telegram.org/bot<TOKEN>/getUpdates and look for
+#      result[0].message.chat.id (an integer). Paste below.
+#
+# Unset = silently disabled; the bridge still tries WhatsApp only.
+#LANTERN_OWNER_TELEGRAM_BOT_TOKEN=
+#LANTERN_OWNER_TELEGRAM_CHAT_ID=
+
+# ============================================================================
+# IMESSAGE BRIDGE (macOS only)
+# ============================================================================
+#
+# Native iMessage bridge — reads ~/Library/Messages/chat.db and sends via
+# AppleScript/JXA on Messages.app. Requires:
+#   1. macOS host signed into iMessage
+#   2. Full Disk Access for the binary that runs `make run-imessage-bridge`
+#      (System Settings → Privacy & Security → Full Disk Access)
+#   3. Automation permission for the same binary, with Messages enabled
+#      (System Settings → Privacy & Security → Automation → enable Messages)
+#
+# Start with: make run-imessage-bridge
+#
+#LANTERN_IMESSAGE_BRIDGE_PORT=3200
+#LANTERN_IMESSAGE_BRIDGE_BIND=127.0.0.1
+#LANTERN_IMESSAGE_BRIDGE_TOKEN=
+#LANTERN_IMESSAGE_BRIDGE_ORIGIN=http://localhost:3001
+#
+# Your own iMessage handle (phone with +country, or email). The
+# control-plane uses this for send-self delivery (Morning Brief etc.).
+#LANTERN_IMESSAGE_OWNER_HANDLE=+15551234567
+#
+# Optional: separate agent name for iMessage vs WhatsApp so style cues
+# can differ. Falls back to LANTERN_AGENT_NAME, then "imessage-assistant".
+#LANTERN_IMESSAGE_AGENT_NAME=imessage-assistant
+
+# ============================================================================
+# PERSONAL DOCS AGENT (macOS only — searches local files via Spotlight)
+# ============================================================================
+#
+# When you text yourself in WhatsApp or iMessage self-chat, the agent
+# can search your Mac for files and answer questions. SECURITY: only
+# fires for owner-sent messages in self-chat. Path-restricted.
+#
+# Colon-separated absolute paths the agent is allowed to search.
+# Defaults: ~/Documents, ~/Desktop, ~/Library/Mobile Documents/com~apple~CloudDocs
+# (iCloud Drive). Override:
+#LANTERN_PERSONAL_DOCS_ROOTS=/Users/you/Documents:/Users/you/Notes:/Users/you/Projects
+#
+# Per-search result cap (default 8).
+#LANTERN_PERSONAL_DOCS_MAX_RESULTS=8
+#
+# Per-read character cap (default 12000 — ~3000 tokens of context).
+#LANTERN_PERSONAL_DOCS_MAX_CHARS=12000
+#
+# Optional: install poppler for full PDF text extraction:
+#   brew install poppler
+# Without it, PDFs fall back to Spotlight-indexed preview text
+# (works but limited to ~1000 chars per file).
+
 # ============================================================================
 # INFRASTRUCTURE (typically set by docker-compose, not .env.local)
 # ============================================================================

.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Copy to .github/CODEOWNERS in your target repo.
+# CODEOWNERS + branch protection = the human merge gate the agents cannot bypass.
+# Require review from these owners on every PR to a protected branch.
+
+*                       @dshakes
+# Tighten high-blast-radius areas so a human MUST review agent changes there:
+/.github/workflows/     @dshakes
+/sdlc/                  @dshakes
+/infra/                 @dshakes
+/**/migrations/         @dshakes

.github/workflows/build-images.yml

@@ -0,0 +1,102 @@
+# build-images — builds, pushes, and cosign-signs the deployable Lantern service images
+# that Helm/Terraform reference (ghcr.io/dshakes/lantern/<name>). Runs on push to master
+# and on demand (workflow_dispatch). Each image is tagged with the git SHA and `latest`.
+#
+# Signing is Sigstore KEYLESS (Fulcio short-lived cert + Rekor), identical in trust to
+# sign-images.yml — the signing identity IS this workflow file. We sign INLINE here
+# (rather than `uses: ./.github/workflows/sign-images.yml`) so we can sign the exact
+# pushed DIGEST that build-push-action returns, which is the tamper-proof thing to sign.
+#
+# Image-name mapping matches what the Helm charts pull (infra/helm/lantern/values.yaml):
+#   control-plane, gateway, model-router, runtime-manager, runtime-scheduler, web (dashboard).
+# Build contexts differ per service:
+#   - Go (control-plane, runtime-scheduler): context = repo root (Dockerfiles COPY gen/go/).
+#   - Rust (gateway, model-router, runtime-manager): context = the service dir (COPY . .).
+#   - dashboard (apps/web): context = apps/web (COPY package*.json ./ then COPY . .).
+#
+# Action SHAs are pinned (same convention as sdlc-qa.yml / sign-images.yml).
+name: "build-images (push + cosign sign)"
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+# Least privilege: read the repo, write packages to ghcr, and mint the OIDC token that
+# keyless cosign signing requires. No long-lived secrets.
+permissions:
+  contents: read
+  packages: write
+  id-token: write
+
+concurrency:
+  group: build-images-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_PREFIX: ghcr.io/dshakes/lantern
+
+jobs:
+  build:
+    name: build (${{ matrix.image }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: control-plane
+            context: .
+            file: services/control-plane/Dockerfile
+          - image: runtime-scheduler
+            context: .
+            file: services/runtime-scheduler/Dockerfile
+          - image: gateway
+            context: services/gateway
+            file: services/gateway/Dockerfile
+          - image: model-router
+            context: services/model-router
+            file: services/model-router/Dockerfile
+          - image: runtime-manager
+            context: .
+            file: services/runtime-manager/Dockerfile
+          - image: web   # dashboard — Helm pulls .../lantern/web (apps/web)
+            context: apps/web
+            file: apps/web/Dockerfile
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@7e8b541eb2e61bf99390e1afd4be13a184e9ebc5 # v3.10.1
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f7ce87c1d6bead3e36075b2ce75da1f6cc28aaca # v3.9.0
+
+      - name: Log in to ghcr
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        id: build
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
+        with:
+          context: ${{ matrix.context }}
+          file: ${{ matrix.file }}
+          push: true
+          tags: |
+            ${{ env.IMAGE_PREFIX }}/${{ matrix.image }}:${{ github.sha }}
+            ${{ env.IMAGE_PREFIX }}/${{ matrix.image }}:latest
+          provenance: false
+          cache-from: type=gha,scope=${{ matrix.image }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.image }}
+
+      # Sign the immutable digest (not a mutable tag) so the signature can't be
+      # re-pointed at a different image later.
+      - name: Sign image (keyless)
+        env:
+          COSIGN_YES: "true"
+          DIGEST_REF: ${{ env.IMAGE_PREFIX }}/${{ matrix.image }}@${{ steps.build.outputs.digest }}
+        run: cosign sign --recursive "$DIGEST_REF"

.github/workflows/deploy-docs.yml

@@ -0,0 +1,56 @@
+# Build the docs site (apps/docs) as a static export and deploy to GitHub Pages.
+# The site is pure static prose (next.config: output "export"), so this produces
+# plain HTML served from Pages — no server, free hosting.
+name: "deploy docs (github pages)"
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "apps/docs/**"
+      - ".github/workflows/deploy-docs.yml"
+  workflow_dispatch: {}
+
+# Pages deploy needs these; least-privilege otherwise.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One in-flight deploy at a time; don't cancel a running deploy.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        with:
+          node-version: "20"
+      - name: Install deps
+        run: cd apps/docs && npm ci
+      - name: Build static export
+        env:
+          # Repo is github.com/dshakes/lantern → Pages at /lantern. Unset for a custom domain.
+          PAGES_BASE_PATH: /lantern
+        run: cd apps/docs && npm run build
+      - name: Disable Jekyll (serve _next/* dirs)
+        run: touch apps/docs/out/.nojekyll
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: apps/docs/out
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.github/workflows/docs-links.yml

@@ -0,0 +1,29 @@
+# Docs links — PR gate that fails when a Markdown link points at a missing file
+# or a non-existent #anchor. Catches doc link-rot (e.g. ADR renumbers, dead
+# in-page anchors) before it ships. Pure Node, no install step → fast.
+#
+# Named job "docs-links" so it can be pinned as a required branch-protection check.
+
+name: "sdlc · docs-links"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-links-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  docs-links:
+    name: docs-links
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+      - name: Check internal documentation links
+        run: node scripts/check-docs-links.mjs