lastlight 0.1.15 → 0.2.1

package/README.md

@@ -11,7 +11,7 @@
 
 An AI agent that maintains GitHub repositories: triaging issues, reviewing PRs, monitoring repo health, and building features through an Architect → Executor → Reviewer development cycle.
 
-Built on the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) with a lightweight TypeScript harness for webhook ingestion, cron scheduling, and process management.
+Built on [agentic-pi](https://github.com/cliftonc/agentic-pi) (workflow phases) and [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai) (in-process chat) with a lightweight TypeScript harness for webhook ingestion, cron scheduling, and process management. Provider-agnostic — point `LASTLIGHT_MODEL` at any `provider/model` pi-ai supports (defaults to `anthropic/claude-sonnet-4-6`).
 
 ## Production Setup (Clean Server)
 
@@ -24,20 +24,27 @@ npx lastlight setup
 The setup wizard walks you through:
 
 1. **GitHub App** — enter your App ID, Installation ID, and PEM key path
-2. **Anthropic API key** — for the Claude Agent SDK
-3. **Webhook secret** — auto-generated if you don't have one
-4. **Domain & TLS** — optional Caddy config for automatic HTTPS
-5. **Slack** — optional bot token and app token for Slack integration
-6. **Admin dashboard** — optional password protection
-
-It writes `.env`, copies your PEM into the secrets directory, generates
-`docker-compose.yml` and (optionally) a `Caddyfile`, then offers to build
-and start the containers. When it's done you have a running instance ready
-to receive webhooks.
+2. **Domain & TLS** — optional Caddy config for automatic HTTPS
+3. **Managed repositories** — the `owner/repo` list the bot operates on
+4. **Provider API key** — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and/or `OPENROUTER_API_KEY`,
+   whichever your `LASTLIGHT_MODEL` points at
+5. **Webhook secret** — auto-generated if you don't have one
+6. **Slack** — optional bot token and app token for Slack integration
+7. **Admin dashboard** — optional password protection
+
+It scaffolds your private **deployment overlay** at `instance/` — writing
+`instance/config.yaml` (your managed repos), `instance/secrets/.env`, and copying
+your PEM to `instance/secrets/app.pem` (mode 600) — then offers to build and start
+the Docker stack. When it's done you have a running instance ready to receive
+webhooks. Everything deployment-specific lives in `instance/`, which is mounted
+read-only and never baked into the image; edit it and `docker compose restart agent`
+to apply (no rebuild). See [Deployment overlay](#deployment-overlay) for the model.
 
 > **Requires:** Node.js 20+, Docker, and a GitHub App already created
 > (see [Create a GitHub App](#1-create-a-github-app) below).
 
+For a Docker-free production install (systemd unit, gondolin sandbox), see [Native deploy](#native-systemd-deploy) below.
+
 ---
 
 ## Quick Start (Local Dev)
@@ -45,8 +52,10 @@ to receive webhooks.
 ### Prerequisites
 
 - Node.js 20+
-- [Claude Code CLI](https://claude.ai/install.sh) installed and logged in (`claude login`)
+- Docker Desktop (or compatible) — only needed for `LASTLIGHT_SANDBOX=docker`; gondolin runs without it on macOS/Linux
 - A GitHub App (see [Create a GitHub App](#1-create-a-github-app) below)
+- An API key for whichever provider your chosen `LASTLIGHT_MODEL` uses
+  (`OPENAI_API_KEY` for openai/…, `ANTHROPIC_API_KEY` for anthropic/…, `OPENROUTER_API_KEY` for openrouter/…)
 
 ### Setup
 
@@ -72,21 +81,35 @@ GITHUB_APP_INSTALLATION_ID=789012
 
 # Webhook secret (required for webhook mode)
 WEBHOOK_SECRET=your-secret-here
+
+# Model + provider — pick one matching your key
+LASTLIGHT_MODEL=anthropic/claude-sonnet-4-6
+ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# OPENROUTER_API_KEY=sk-or-...
+
+# Sandbox backend (default: gondolin; alternatives: docker, none)
+# LASTLIGHT_SANDBOX=gondolin
 ```
 
 ### Run
 
-`npm run dev` runs the harness on your host but spawns each agent task in a real Docker sandbox container, exactly like production. It is explicitly safe with your personal config:
+`npm run dev` runs the harness on your host. Sandbox mode is selected by `LASTLIGHT_SANDBOX`:
+
+- **`gondolin`** (default) — agentic-pi spawns a per-phase QEMU micro-VM in-process. Uses HVF on macOS, KVM on Linux. No Docker needed.
+- **`docker`** — agentic-pi runs inside a per-phase sibling Docker container (the `lastlight-sandbox:latest` image). Requires Docker. Useful for prod-like smoke testing.
+- **`none`** — agent runs in-process on your host with no isolation. Dev only — never in production.
+
+The dev script is explicitly safe with your personal config:
 
 | | Touched? |
 |---|---|
 | `~/.gitconfig` (your identity, credential helper) | ❌ skipped (`LASTLIGHT_LOCAL_DEV=1`) |
-| `~/.claude/.credentials.json` | ❌ read once on first run, never written |
-| `~/.claude/projects/...` (your session history) | ❌ direct fallback disabled |
-| `./data/sandbox-claude-home/` | ✅ project-local seed of your claude login; sandboxes refresh tokens here, isolated from host |
+| `./data/agent-sessions/` | ✅ project-local; shim envelope jsonls for the dashboard live here |
+| `./data/sandbox-data/` | ✅ project-local bind-mount when using `LASTLIGHT_SANDBOX=docker` |
 | `./data/lastlight.db`, `./data/sandboxes/`, `./data/logs/` | ✅ project-local state, gitignored |
 
-One-time setup — build the sandbox image:
+If you want the Docker sandbox mode locally, build the image once first:
 
 ```bash
 docker compose --profile build-only build sandbox
@@ -101,10 +124,9 @@ npm run dev:dashboard  # dashboard only
 ```
 
 Both server scripts call `scripts/dev-local.sh`, which:
-- Verifies Docker is running and the sandbox image exists
-- Locates your host claude credentials — `~/.claude/.credentials.json` on Linux, or the macOS keychain entry `Claude Code-credentials` on macOS. Run `claude login` first if neither is present.
-- Re-seeds `./data/sandbox-claude-home/.credentials.json` from the host credentials on every start, so a fresh `claude login` is picked up automatically without wiping anything.
-- Sets `LASTLIGHT_LOCAL_DEV=1`, `SANDBOX_DATA_VOLUME=./data/sandbox-claude-home`, `STATE_DIR=./data`, `CLAUDE_HOME_DIR=./data/sandbox-claude-home`, and `ENABLE_DIRECT_FALLBACK=false`
+- Verifies the sandbox image exists when `LASTLIGHT_SANDBOX=docker`
+- Copies your `GITHUB_APP_PRIVATE_KEY_PATH` into `./data/sandbox-data/secrets/app.pem` (mode 600) so the sandbox can authenticate to GitHub
+- Sets `LASTLIGHT_LOCAL_DEV=1`, `STATE_DIR=./data`, `LASTLIGHT_SESSIONS_DIR=./data/agent-sessions`
 - Starts the harness with `tsx watch src/index.ts`
 
 #### Triggering work via the CLI
@@ -129,53 +151,82 @@ The default for a single-issue/PR shorthand is the **cheap** action (triage or r
 
 ### Authentication
 
-Locally, the Agent SDK uses your Claude Code login (subscription). No API key needed — just make sure `claude login` works on your host. `npm run dev` copies the credentials into the project-local sandbox claude-home, so the sandbox is logged in without bind-mounting your real `~/.claude`.
-
-To use an API key instead, set `ANTHROPIC_API_KEY` in `.env`.
+pi-ai picks credentials from `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and/or `OPENROUTER_API_KEY` on the harness env. The harness forwards them into each sandbox container (or VM) so workflow runs can reach the API.
 
 ---
 
 ## Docker Deployment
 
-### Build and Run
-
-```bash
-docker-compose build agent
-docker-compose up -d agent
-```
+The docker-compose stack is useful when you want a single `docker compose up -d` deploy. For gondolin (and a smaller deployment surface area), prefer the [native systemd deploy](#native-systemd-deploy) instead.
 
-### First-Time Auth
+### Build and Run
 
-The container needs Claude Code credentials. Log in interactively once:
+Build both the harness image **and** the sandbox image. The sandbox image is what the harness spawns per phase when `LASTLIGHT_SANDBOX=docker`. The sandbox service is under the `build-only` profile so it is never started — it is only built.
 
 ```bash
-docker exec -it lastlight-agent-1 claude login
+docker compose build agent
+docker compose --profile build-only build sandbox
+docker compose up -d agent
 ```
 
-Follow the URL in your browser to authenticate. The auth token persists in the Docker volume — it survives container restarts and rebuilds.
-
-### Secrets
+Set `LASTLIGHT_SANDBOX=docker` in your `.env`. (Inside the harness container, gondolin's QEMU path isn't available unless you do the nested-virt setup yourself — the docker-sandbox path is the practical default for Docker deployments.)
+
+### Deployment overlay
+
+Everything specific to your deployment — managed repos, model/route/approval
+overrides, agent-context, secrets — lives in a single **`instance/`** folder
+next to `docker-compose.yml`. It's mounted read-only at `/app/instance`
+(`LASTLIGHT_OVERLAY_DIR=/app/instance`) and is **never committed to the public
+repo or baked into the image**, so it's the natural home for a private config
+repo.
+
+```text
+instance/
+  config.yaml            # overlay config — merged over the public config/default.yaml
+  agent-context/*.md     # (optional) persona/rules overrides, merged by filename
+  workflows/*.yaml       # (optional) add or replace workflows by logical name
+  skills/<name>/SKILL.md # (optional) skill overrides
+  secrets/               # host-only, gitignored: .env + GitHub App *.pem
+    .env
+    app.pem
+```
 
-Create a `secrets/` directory with your GitHub App credentials:
+`npx lastlight setup` scaffolds this for you. To do it by hand (or to clone a
+private overlay repo into place):
 
 ```bash
-mkdir -p secrets
-cp .env secrets/
-cp your-app.private-key.pem secrets/
+mkdir -p instance/secrets
+cp deploy/.env.production.example instance/secrets/.env   # then fill it in
+cp your-app.private-key.pem instance/secrets/app.pem
+chmod 600 instance/secrets/.env instance/secrets/app.pem
+# instance/config.yaml — at minimum your managed repos:
+printf 'managedRepos:\n  - your-org/repo-one\n' > instance/config.yaml
 ```
 
-The entrypoint symlinks these into the container at startup.
+Both the `agent` and `caddy` services read `instance/secrets/.env` via
+`env_file`, and the entrypoint also sources it inside the container — so **no
+repo-root `.env` is needed**. Merge rules: maps (`models`, `variants`, `routes`,
+`approval`) deep-merge over the public defaults; arrays (`managedRepos`,
+`disabled.*`) replace; environment variables override both. Overlay files are
+read at startup — edit and `docker compose restart agent` to apply, no rebuild.
+The dashboard **Config** tab shows Default / Overlay / Merged (non-secret) config
+(secret-looking keys are redacted, so a stray secret in `config.yaml` won't leak).
+
+Startup is **fail-fast**: if `LASTLIGHT_OVERLAY_DIR` is set but the folder is
+missing or empty (the common "forgot to populate `instance/`" case), or a cron
+targets a missing workflow, or a phase's prompt/skill can't resolve, the harness
+exits `78` with a clear message instead of booting a broken instance.
 
 ### Expose Webhooks
 
-To receive GitHub webhooks, the server needs to be publicly reachable. The included Caddy config handles HTTPS:
+To receive GitHub webhooks, the server needs to be publicly reachable. The included Caddy config handles HTTPS — set `DOMAIN` in `instance/secrets/.env`:
 
 ```bash
-# Set your domain
-echo "DOMAIN=lastlight.example.com" >> .env
+# In instance/secrets/.env:
+#   DOMAIN=lastlight.example.com
 
 # Start both agent and caddy
-docker-compose up -d
+docker compose up -d
 ```
 
 Or use [ngrok](https://ngrok.com) / [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) for testing.
@@ -186,12 +237,14 @@ All persistent state lives in a single Docker volume (`agent-data`), mounted at
 
 ```
 data/
-  lastlight.db              # SQLite: execution log, rate limits
-  claude-home/              # Claude auth + session JSONL logs
-    projects/-app/*.jsonl   # Full audit trail per agent session
-  sandboxes/                # Cloned repos per task
+  lastlight.db              # SQLite: executions, workflow_runs, approvals, messaging sessions
+  agent-sessions/           # Dashboard JSONL envelope store (written by event-shim.ts)
+    projects/-app/*.jsonl                    # Chat sessions (one per Slack thread)
+    projects/-home-agent-workspace/*.jsonl   # Sandbox-mode workflow sessions
+  sandboxes/                # Cloned repos per task (gondolin or docker)
+  sandbox-data/             # Shared volume mounted into docker-mode sandboxes
   logs/                     # Structured logs
-  sessions/                 # (reserved)
+  secrets/app.pem           # GitHub App PEM (mode 600) for sandbox access
 ```
 
 Mount this volume or bind-mount the directory for monitoring tools to access session logs and the execution database.
@@ -213,6 +266,29 @@ npx tsx src/cli.ts triage owner/repo
 
 ---
 
+## Native (systemd) Deploy
+
+For a Linux production host with KVM available (`/dev/kvm`), the native deploy runs the harness directly under systemd and uses gondolin for sandboxing — no Docker required.
+
+See [deploy/native/README.md](deploy/native/README.md) for the full runbook. The short version:
+
+```bash
+git clone https://github.com/cliftonc/lastlight.git /opt/lastlight
+cd /opt/lastlight
+# (optional) install -m 0600 -o root /path/to/app.pem /etc/lastlight/app.pem
+sudo bash deploy/native/install.sh        # scaffolds /etc/lastlight/lastlight.env
+sudo $EDITOR /etc/lastlight/lastlight.env # fill in secrets
+sudo bash deploy/native/install.sh        # second run: starts the service
+```
+
+Re-deploys: `git pull && sudo bash deploy/native/install.sh` (idempotent — rebuilds and restarts the service).
+
+**Required:** the host kernel must expose `/dev/kvm` (bare-metal Linux or KVM-enabled VM). Hetzner Cloud, Cloud Run, Fly Machines (without `--vm-cpu-class shared`), and most managed container hosts do **not** expose nested virt — see `agentic-pi`'s `SPIKE-gondolin.md` for the full constraint matrix.
+
+If KVM isn't available, fall back to the Docker deploy above with `LASTLIGHT_SANDBOX=docker`.
+
+---
+
 ## Setup Details
 
 ### 1. Create a GitHub App
@@ -227,8 +303,9 @@ npx tsx src/cli.ts triage owner/repo
    - **Issues**: Read & Write
    - **Pull Requests**: Read & Write
    - **Contents**: Read & Write
+   - **Checks**: Read & Write (post the `last-light/review` check; receive its "Re-run" requests)
    - **Metadata**: Read
-4. Subscribe to **events**: `Issues`, `Pull request`, `Issue comment`
+4. Subscribe to **events**: `Issues`, `Pull request`, `Issue comment`, `Check run`, `Check suite` (the last two enable the GitHub "Re-run checks" buttons to re-trigger a review)
 5. Click **Create GitHub App**
 6. Click **Generate a private key** — save the `.pem` file into the project directory
 7. Note the **App ID** from the app settings page
@@ -237,43 +314,96 @@ npx tsx src/cli.ts triage owner/repo
 
 ### 2. Environment Variables
 
+Legacy `OPENCODE_*` names are still read as fallbacks for the corresponding `LASTLIGHT_*` names, so existing `.env` files from the OpenCode era keep working.
+
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `GITHUB_APP_ID` | Yes | GitHub App ID |
 | `GITHUB_APP_PRIVATE_KEY_PATH` | Yes | Path to `.pem` file |
 | `GITHUB_APP_INSTALLATION_ID` | Yes | Installation ID |
 | `WEBHOOK_SECRET` | Yes | GitHub webhook signature secret |
-| `ANTHROPIC_API_KEY` | No | Anthropic API key (uses Claude login if not set) |
-| `CLAUDE_MODEL` | No | Model to use (default: `claude-sonnet-4-6`) |
+| `OPENAI_API_KEY` | One of | API key when using `openai/…` models |
+| `ANTHROPIC_API_KEY` | One of | API key when using `anthropic/…` models |
+| `OPENROUTER_API_KEY` | One of | API key when using `openrouter/…` models |
+| `LASTLIGHT_OVERLAY_DIR` | No | Trusted deployment overlay directory (the docker-compose stack mounts `instance/` here as `/app/instance`). Startup loads `config/default.yaml`, optional `$LASTLIGHT_OVERLAY_DIR/config.yaml`, then env overrides; overlay assets under `workflows/`, `workflows/prompts/`, `skills/`, and `agent-context/` replace built-ins. Secrets live in `$LASTLIGHT_OVERLAY_DIR/secrets/`. Restart required after changes. See [Deployment overlay](#deployment-overlay). |
+| `LASTLIGHT_MODEL` | No | Default model (default: `anthropic/claude-sonnet-4-6`). Legacy: `OPENCODE_MODEL`. |
+| `LASTLIGHT_MODELS` | No | Per-task model overrides as JSON, e.g. `{"chat":"openai/gpt-5.1-mini","architect":"openai/gpt-5.5"}`. Legacy: `OPENCODE_MODELS`. |
+| `LASTLIGHT_THINKING` | No | Reasoning-effort default (`off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh`). pi-ai translates per-provider. Legacy: `OPENCODE_VARIANT`. |
+| `LASTLIGHT_THINKINGS` | No | Per-task thinking-level overrides as JSON, e.g. `{"architect":"high","reviewer":"high","triage":"minimal"}`. Legacy: `OPENCODE_VARIANTS`. |
+| `LASTLIGHT_SANDBOX` | No | Workflow sandbox backend: `gondolin` (default) \| `docker` \| `none`. |
+| `LASTLIGHT_OTEL_ENABLED` | No | Enable OpenTelemetry export (default: `false`). Standard `OTEL_*` env vars alone do not enable telemetry. |
+| `LASTLIGHT_OTEL_SERVICE_NAME` | No | OTEL service name (default: `lastlight`; falls back to `OTEL_SERVICE_NAME`). |
+| `LASTLIGHT_OTEL_INCLUDE_CONTENT` | No | Include prompts/message/tool-result content in telemetry (default: `false`; sensitive, use carefully). |
+| `LASTLIGHT_OTEL_FORWARD_TO_SANDBOX` | No | Forward sandbox telemetry to the backend (default: `true`). On the `docker` backend this routes through an in-network OTEL collector; on `gondolin`/`none` it forwards allowlisted `OTEL_*` env vars directly. |
+| `LASTLIGHT_OTEL_STRICT` | No | Throw on OTEL initialization/export setup failure instead of warn-and-continue (default: `false`). |
+| `LASTLIGHT_OTEL_COLLECTOR_HOSTS` | No | Comma-separated collector hostnames added to the strict sandbox egress allowlist. Used only by the `gondolin` backend (the `docker` backend reaches its collector internally and ignores this). |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_*_ENDPOINT` | No | Standard OTLP HTTP collector endpoints. Used by the harness directly, and by the in-network collector as its re-export target on the `docker` backend. |
+| `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_*_HEADERS` | No | Standard OTLP headers; secret/env-only and never shown in public config. |
+| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | No | Standard OTEL resource configuration. |
+| `LASTLIGHT_SESSIONS_DIR` | No | Where the dashboard reads sessions (default: `$STATE_DIR/agent-sessions`). |
 | `PORT` / `WEBHOOK_PORT` | No | Webhook listener port (default: `8644`) |
 | `STATE_DIR` | No | Persistent state directory (default: `./data`) |
-| `MAX_TURNS` | No | Max agent turns per invocation (default: `200`) |
+| `DB_PATH` | No | SQLite path (default: `$STATE_DIR/lastlight.db`) |
+| `MAX_TURNS` | No | Reserved (kept for API stability) |
 | `BOT_LOGIN` | No | Bot login name for self-event filtering (default: `last-light[bot]`) |
-| `LASTLIGHT_LOCAL_DEV` | No | Set to `1` to skip `git config --global` writes from `git-auth.ts`. Use this on dev machines so the harness doesn't overwrite your personal `~/.gitconfig`. The installation token is still passed to sandboxes via the `GIT_TOKEN` env var. |
-| `SANDBOX_DATA_VOLUME` | No | Either a Docker named volume name (default: `lastlight_agent-data`, used in production) or a host path (starts with `/`, `./`, `../`, or `~`) to bind-mount as `/data` inside each sandbox. Local dev uses `./data/sandbox-claude-home`. |
-| `CLAUDE_HOME_DIR` | No | Directory the dashboard reads sessions from (default: `./data/claude-home`). Local dev points this at `./data/sandbox-claude-home` to match the bind-mounted sandbox volume. |
-| `ENABLE_DIRECT_FALLBACK` | No | If `true`, the harness falls back to in-process Agent SDK execution when the sandbox image is unavailable. Local dev sets this to `false` to keep all agent work isolated in containers. |
+| `LASTLIGHT_LOCAL_DEV` | No | Set to `1` on dev machines to skip `git config --global` writes from `git-auth.ts`. The installation token still reaches sandboxes via `GIT_TOKEN`. |
+| `SANDBOX_DATA_VOLUME` | No | Used only when `LASTLIGHT_SANDBOX=docker`. Either a Docker named volume (default: `lastlight_agent-data`) or a host path (`/`, `./`, `../`, `~`) to bind-mount as `/data` inside each sandbox. Local dev uses `./data/sandbox-data`. |
+
+### OpenTelemetry export
+
+OpenTelemetry is disabled by default. Set `LASTLIGHT_OTEL_ENABLED=true` and configure standard OTEL exporter env vars such as `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, and `OTEL_RESOURCE_ATTRIBUTES` to export harness spans/metrics for workflow runs, phases, agent executions, PI event streams, and chat turns.
+
+By default Last Light exports metadata only: workflow/phase names, repo, sandbox backend, model, success/stop reason, timing, tokens, and cost. Prompt text, message content, tool arguments, and tool outputs are redacted unless `LASTLIGHT_OTEL_INCLUDE_CONTENT=true`; that opt-in can export sensitive data and should only be used with a trusted collector.
+
+When `LASTLIGHT_OTEL_FORWARD_TO_SANDBOX=true` (default), `agentic-pi` workflow sandboxes emit their own telemetry too. How it reaches the backend depends on the sandbox backend:
+
+- **`docker` (production):** sandboxes export OTLP to an **in-network OTEL collector** (a `otel-collector` compose service on the `sandbox-egress` network, reached by a fixed internal IP). That collector re-exports to your real backend over its own outbound network leg. This means the sandbox only ever dials one fixed internal endpoint — collectors on any port or scheme (e.g. `https://collector:4318`) work without special egress rules, and the backend endpoint and auth headers (`OTEL_EXPORTER_OTLP_HEADERS`) stay host-side and are **never** forwarded into the untrusted sandbox. The collector cannot be redirected by sandbox traffic, so it adds no SSRF/exfil surface.
+- **`gondolin` / `none`:** `agentic-pi` runs in the harness process and already inherits the harness OTEL SDK. Allowlisted `OTEL_*` env vars are forwarded into the sandbox shell env directly; `gondolin` adds collector hosts (parsed from `OTEL_EXPORTER_OTLP_ENDPOINT`, signal-specific endpoint env vars, and `LASTLIGHT_OTEL_COLLECTOR_HOSTS`) to its egress allowlist. Private/internal metadata hosts remain blocked.
+
+Set `LASTLIGHT_OTEL_FORWARD_TO_SANDBOX=false` to disable sandbox telemetry entirely and keep collector endpoints/headers in the harness only.
 
 ### 3. Managed Repositories
 
-Edit `agent-context/rules.md` to list repositories the bot manages:
+The public `config/default.yaml` ships an **empty** `managedRepos` list — set
+yours in the overlay (`instance/config.yaml`), which replaces the list wholesale:
 
-```markdown
-## Managed Repositories
-- your-org/repo-one
-- your-org/repo-two
+```yaml
+managedRepos:
+  - your-org/repo-one
+  - your-org/repo-two
 ```
 
+Webhooks for repos not in this list are filtered at the connector level; Slack/CLI
+commands targeting unmanaged repos are rejected. Install the GitHub App on each.
+
 ### 4. Customize Behaviour
 
+Put deployment-specific changes in your overlay (`instance/`) instead of editing
+packaged files — that keeps your config out of the public repo and applies on a
+restart (no rebuild). See [Deployment overlay](#deployment-overlay) for the full
+model and layout.
+
+```text
+instance/
+  config.yaml                 # non-secret config overrides only
+  workflows/*.yaml            # add/replace workflows by logical `name`
+  workflows/prompts/*.md      # prompt overrides/fallbacks
+  skills/<name>/SKILL.md      # skill overrides/fallbacks
+  agent-context/*.md          # merged by filename; overlay replaces built-ins
+  secrets/                    # host-only, gitignored: .env + *.pem
+```
+
+The dashboard Config tab shows Default / Overlay / Merged non-secret config.
+Overlay files are read at startup only; `docker compose restart agent` after changes.
+
 | What | Where |
 |------|-------|
-| Bot personality & communication style | `agent-context/soul.md` |
-| Operational rules, review guidelines, triage rules | `agent-context/rules.md` |
-| Skill definitions | `skills/*/SKILL.md` |
-| Orchestrator phases (Architect/Executor/Reviewer) | `src/engine/orchestrator.ts` |
-| Event routing rules | `src/engine/router.ts` |
-| Cron job schedules | `src/cron/jobs.ts` |
+| Managed repos, routes, models, variants, approvals, disables | overlay `instance/config.yaml` (over `config/default.yaml`) |
+| Bot personality & communication style | `agent-context/soul.md` or overlay `instance/agent-context/` |
+| Operational rules, review guidelines, triage rules | `agent-context/rules.md` or overlay `instance/agent-context/` |
+| Skill definitions | `skills/*/SKILL.md` or overlay `instance/skills/` |
+| Workflow phases (Architect/Executor/Reviewer/PR) | `workflows/*.yaml` + `workflows/prompts/` or overlay equivalents |
+| Cron job schedules | `workflows/cron-*.yaml` or overlay workflows |
 
 ---
 
@@ -282,7 +412,7 @@ Edit `agent-context/rules.md` to list repositories the bot manages:
 ```
 ┌─────────────────────────────────────────┐
 │            Connector Layer              │
-│  GitHub Webhook │ (future: Slack, etc.) │
+│  GitHub Webhook │ Slack Socket Mode     │
 │        ↓        │         ↓             │
 │     Event Normalizer (EventEnvelope)    │
 └────────────────┬────────────────────────┘
@@ -291,10 +421,11 @@ Edit `agent-context/rules.md` to list repositories the bot manages:
 │             Core Engine                 │
 │  Event Router (deterministic)           │
 │        ↓                                │
-│  Agent Executor (Claude Agent SDK)      │
-│  - System prompt from agent-context/    │
-│  - MCP tools (GitHub App)               │
-│  - Skills (SKILL.md)                    │
+│  Workflow Runner (YAML phases)          │
+│  - Sandbox: `agentic-pi run` per phase  │
+│    in a gondolin VM or docker container │
+│  - Chat: in-process pi-ai loop          │
+│    one session per messaging thread     │
 │        ↓                                │
 │  Sandboxes (git clone per task)         │
 │  Cron Scheduler (health reports)        │
@@ -308,9 +439,9 @@ Edit `agent-context/rules.md` to list repositories the bot manages:
 2. **Router** maps event type to skill deterministically (no LLM in the routing loop):
    - `issue.opened` → `issue-triage`
    - `pr.opened` → `pr-review`
-   - `comment.created` with `@last-light` from maintainer → `github-orchestrator`
-3. **Executor** spawns a Claude Agent SDK session with the skill prompt, MCP tools, and agent context
-4. **Orchestrator** (for build requests) runs a multi-phase cycle:
+   - `comment.created` with `@last-light` from a maintainer → routed by intent classifier (build / explore / triage / review / action)
+3. **Workflow runner** loads the matching YAML, dispatches each phase to `executeAgent` (`src/engine/agent-executor.ts`, which invokes agentic-pi) or, for chat, `ChatRunner` (`src/engine/chat-runner.ts`, in-process pi-ai)
+4. **Build workflow** runs a multi-phase cycle:
    - Phase 1: **Architect** — read-only analysis, writes plan to `.lastlight/issue-N/architect-plan.md`
    - Phase 2: **Executor** — TDD implementation following the plan
    - Phase 3: **Reviewer** — independent verification (no shared context with executor)
@@ -343,15 +474,27 @@ lastlight/
       index.ts              # Connector registry
     engine/
       router.ts             # Deterministic event → skill routing
-      executor.ts           # Agent SDK query() wrapper
-      orchestrator.ts       # Architect → Executor → Reviewer cycle
-      agents.ts             # Subagent role definitions
+      agent-executor.ts     # Workflow phase runner: invokes agentic-pi
+                            #   (gondolin / docker / none backends)
+      chat-runner.ts        # In-process pi-ai chat loop; one session per
+                            #   Slack/Discord thread, rehydrated from DB
+      chat.ts               # Chat skill (delegates to ChatRunner)
+      github-tools.ts       # Read-only GitHub tools surfaced to chat
+      event-shim.ts         # Translates agentic-pi events → Claude-SDK
+                            #   envelope jsonl for the dashboard reader
+      profiles.ts           # ExecutorConfig / ExecutionResult types +
+                            #   GITHUB_PERMISSION_PROFILES + loadAgentContext
+      llm.ts                # One-shot LLM helper for screen + classifier
+      screen.ts             # Prompt-injection screener
+      classifier.ts         # Intent classifier (build / explore / triage / …)
       git-auth.ts           # GitHub App git credential setup
-    worktree/
-      manager.ts            # Git worktree per-task isolation
+      github.ts             # Harness-side Octokit client (comments, etc.)
+    workflows/              # YAML workflow runner (see src/workflows/CLAUDE.md)
+    sandbox/                # Per-task workspace + docker-sandbox lifecycle
     cron/
       scheduler.ts          # Cron with overlap protection
-      jobs.ts               # Job definitions
+      jobs.ts               # Cron job registry
+    admin/                  # Dashboard API (Hono) + session readers
     state/
       db.ts                 # SQLite execution tracking
 
@@ -367,15 +510,24 @@ lastlight/
     github/                 # GitHub API workflow skills
     software-development/   # Dev skills (architect, TDD, debugging)
 
-  mcp-github-app/           # MCP server: 28+ GitHub tools via Octokit
-    src/
-      index.js              # MCP server entry (clone_repo, refresh_git_auth, etc.)
-      auth.js               # GitHub App JWT + installation token
-      github.js             # Octokit wrapper with retry/backoff
+  workflows/                # YAML workflow definitions
+    build.yaml              # Architect → Executor → Reviewer → PR
+    issue-triage.yaml
+    pr-review.yaml
+    repo-health.yaml
+    cron-*.yaml             # Cron-kind triggers
+    prompts/                # Per-phase prompt templates
 
   deploy/
-    entrypoint.sh           # Docker entrypoint
-  Dockerfile
+    entrypoint.sh           # Docker entrypoint (harness container)
+    sandbox-entrypoint.sh   # Sandbox container entrypoint (docker-sandbox mode)
+    native/                 # Native (systemd) deploy artifacts
+      lastlight.service     # systemd unit
+      install.sh            # Idempotent provision + redeploy script
+      lastlight.env.example # Env template for /etc/lastlight/lastlight.env
+      README.md             # Native-deploy operator runbook
+  Dockerfile                # Harness image (test-only; prod uses native deploy)
+  sandbox.Dockerfile        # Sandbox image for LASTLIGHT_SANDBOX=docker
   docker-compose.yml
   Caddyfile                 # Reverse proxy for HTTPS
 ```
@@ -390,36 +542,41 @@ npm run dev:server
 # Look for "Required environment variable not set" errors
 ```
 
-### `npm run dev` says the sandbox image is missing
+### `npm run dev` says the sandbox image is missing (docker-sandbox mode)
 
 ```bash
 docker compose --profile build-only build sandbox
 ```
 
-### `npm run dev` says claude is not logged in
+### Workflow run fails with `exit 127: sh: 1: agentic-pi: not found`
+
+The sandbox image needs `agentic-pi` baked in. Rebuild it:
 
 ```bash
-claude login    # then re-run npm run dev
+docker compose --profile build-only build sandbox
 ```
 
-### Agent exits with code 1
+If you're on an old `lastlight-sandbox:latest`, this picks up the install step that the current `sandbox.Dockerfile` performs.
 
-```bash
-# Check if Claude is logged in
-claude --version && claude -p "hello"
+### Workflow hangs forever with no output (gondolin mode on a host without KVM)
 
-# In Docker: check auth persisted
-docker exec lastlight-agent-1 claude -p "hello"
-# If it fails, re-login AS THE LASTLIGHT USER (not root!):
-docker exec -it --user lastlight lastlight-agent-1 claude login
-```
+Gondolin requires `/dev/kvm` on Linux or HVF on macOS. Inside a container with no nested virt, `VM.create()` succeeds but the first `vm.exec()` hangs. Symptoms: phase shows "running" indefinitely with no JSONL events after `sandbox_status`.
+
+Either switch to `LASTLIGHT_SANDBOX=docker` (sibling containers via socket) or move the harness to a KVM-capable host. Full analysis: `agentic-pi/SPIKE-gondolin.md`.
+
+### Agent run fails with a quota / billing error
+
+The runtime surfaces upstream errors as `error_api` with the verbatim provider message in the executions row:
 
-**IMPORTANT**: Always use `--user lastlight` when running `claude login` in Docker. Running as root causes:
-- Permission errors (`.credentials.json` owned by root, session logs unwritable)
-- Config corruption (cached feature flags wiped, MCP auth cache polluted with Claude.ai servers)
-- `bypassPermissions` mode may stop working with MCP servers attached
+- OpenAI: "Quota exceeded. Check your plan and billing details." → top up at https://platform.openai.com/account/billing
+- Anthropic: "Credit balance is too low" → top up at https://console.anthropic.com
 
-If you accidentally logged in as root, rebuild the container: `docker compose build agent && docker compose up -d agent`
+### Chat replies fail with `error_error`
+
+Check the agent logs for the underlying error — common causes:
+
+- **Wrong key for the chat model.** `LASTLIGHT_MODELS={"chat":"anthropic/…"}` but no `ANTHROPIC_API_KEY` set. Fix the override or add the key.
+- **Model id typo.** Watch for `[config] Model: …` in startup logs to confirm what's actually loaded.
 
 ### Webhooks not arriving
 
@@ -431,15 +588,5 @@ curl http://localhost:8644/health
 curl -X POST http://localhost:8644/webhooks/github -d '{}'
 
 # Check Docker port mapping
-docker-compose ps
+docker compose ps
 ```
-
-### Credit balance / rate limit errors
-
-If you see "Credit balance is too low", either:
-- Top up at https://console.anthropic.com (API key mode)
-- Remove `ANTHROPIC_API_KEY` from `.env` to use your Claude subscription instead
-
-### Permission denied on MCP tools
-
-The executor runs with `bypassPermissions` mode. In Docker, this requires running as a non-root user (the Dockerfile handles this automatically).