overlord-cli 0.2606091312.0 → 0.2607081118.0

package/README.md

@@ -1,194 +1,315 @@
-# Overlord CLI
+# CLI Module
 
-`overlord-cli` is the packaged command-line interface for Overlord. It lets you launch agents on tickets, create new tickets, and manage the ticket lifecycle from the terminal.
+The `ovld` command-line surface — Overlord's primary, CLI-first product.
+This module is the home for everything a user or agent invokes as `ovld …`.
 
-Website: [ovld.ai](https://ovld.ai)
+## Table of Contents
 
-## Install
+- [For Users](#for-users)
+  - [Setup](#setup)
+  - [First run](#first-run)
+  - [How the published CLI works](#how-the-published-cli-works)
+  - [Point the CLI at a backend](#point-the-cli-at-a-backend)
+  - [Headless / container setup](#headless--container-setup)
+  - [What requires the backend](#what-requires-the-backend)
+- [For Developers](#for-developers)
+  - [Contract Components](#contract-components)
+  - [Documentation](#documentation)
+  - [Code & Tests](#code--tests)
+  - [In-repo build vs installed CLI](#in-repo-build-vs-installed-cli)
+  - [Interaction Boundaries](#interaction-boundaries)
 
-Note: Use Node.js 20 or newer for every CLI install or update.
+## For Users
 
-Install it globally so the `ovld` and `overlord` commands are available on your `PATH`:
+### Setup
 
-```bash
-npm install -g overlord-cli
-
-#After installing, run
-ovld setup all #to configure every supported connector (`ovld setup` alone is interactive)
+The CLI is **client-only**. Management commands, protocol sessions, and runner
+queue operations all reach persistence through the backend URL you configure — only
+`help` and `version` work without one. First-time setup is about **pointing
+`ovld` at a backend** and verifying it is reachable.
 
-#for individual connectors, run `ovld setup <connector>`.
-ovld setup cursor
-ovld setup claude
-ovld setup codex
-ovld setup all
-```
+### First run
 
+Install the published package:
 ```bash
-# To update the CLI to the latest release, run:
-ovld update
+npm install -g --no-fund overlord-cli
 ```
 
-## Usage
+After installing the published package:
 
 ```bash
-ovld help
-overlord help
+ovld auth login
 ```
 
-### Auth
+Login verifies that a backend is configured. If none is set yet, it walks through
+`ovld config` first — local setup offers `http://127.0.0.1:4310` as the default
+backend URL; cloud setup accepts a hosted backend URL.
+
+Then confirm the connection and continue with projects, missions, and agents:
 
 ```bash
-# No account yet? Create one entirely from the terminal with just an email.
-ovld auth signup --email agent@example.com --name "Build Agent" # emails an 8-digit code, then mints a durable oat_ agent token by default
-ovld onboard --email agent@example.com --project-name Repo       # same signup, plus org/project/cwd setup
-
-# Repair shared credentials first when a session already exists
-ovld auth repair # mirror and chmod shared Desktop/CLI credentials when possible
-
-# Login to Overlord if repair does not restore access
-ovld auth login #opens a browser when possible and also prints a verification URL/code so login can be completed from another machine over SSH.
-ovld auth login --email agent@example.com # log back in after logout with an emailed code (no browser)
-ovld auth status # show current login status (use --verbose for redacted diagnostics)
-ovld auth logout # remove stored credentials
+ovld doctor
+ovld config list
 ```
 
-#### Terminal-native account creation
+See [Getting Started](https://github.com/cooperativ-labs/OpenOverlord/blob/main/docs/getting-started.md) for the full walkthrough from
+install through first delivered mission.
 
-`ovld auth signup` creates an Overlord account without a browser: it emails an
-8-digit confirmation code, you enter it in the terminal, and the CLI stores valid
-credentials. Pass `--password` to set a password-manager-generated password;
-without one, signup is passwordless and you log back in later with
-`ovld auth login --email`. By default a durable `oat_…` agent token is minted and
-saved for headless use — pass `--no-agent-token` to skip it. For agents that read
-email out of band, the split flow is available:
+### How the published CLI works
 
-```bash
-ovld auth signup request --email agent@example.com --name "Build Agent" --json
-ovld auth signup verify  --email agent@example.com --code 12345678 --json
-ovld onboard --use-current-auth --project-name Repo --directory "$PWD" --yes
+The npm package ships command parsing, config/auth onboarding, connector setup,
+an HTTP backend client, and the local runner/agent launcher. Production builds
+bundle the shared `@overlord/core` runtime into `dist/index.js`, so the tarball
+does not depend on other Overlord packages at install time. It still does **not**
+ship SQLite, `better-sqlite3`, migrations, or the service-layer database runtime.
+
+```mermaid
+flowchart LR
+  cli["ovld npm CLI"] -->|"HTTP /api/*"| local["Desktop or local backend"]
+  cli -->|"HTTP /api/*"| cloud["Hosted backend"]
+  local --> sqlite["SQLite"]
+  cloud --> postgres["Postgres"]
+  cli -->|"spawn"| agent["Local agent CLI"]
 ```
 
-Desktop-installed wrappers default `OVERLORD_URL` to `https://www.ovld.ai` unless you override it explicitly.
-For local dev against the web app on port 3000, export the override before running auth or protocol commands:
+Local mode means `ovld` talks to a backend already running on your machine,
+normally Desktop or a future db-only local backend. Cloud mode means `ovld`
+talks to a hosted Overlord backend. In both modes, the backend owns persistence
+and migrations; the CLI is a client of that backend.
+
+### Point the CLI at a backend
+
+Configuration lives in `overlord.toml` — a per-instance, uncommitted file
+(gitignored; generate it with `ovld init`, or copy `overlord.toml.example`),
+discovered from the current directory upward, or in `~/.ovld/overlord.toml` for a
+global install.
+
+| Mode | Config key | How to set it |
+| ---- | ---------- | ------------- |
+| **Local backend** | `backend_url` | `ovld config set local [url]` — defaults to `http://127.0.0.1:4310` |
+| **Hosted backend** | `backend_url` | `ovld config set cloud <url>` |
+
+`ovld config set` without arguments opens the interactive backend selector.
+`ovld config list` shows the resolved target; `ovld doctor` checks that the
+backend is reachable.
+
+Environment overrides (useful in scripts and CI):
+
+- `OVLD_HOME` — relocate the entire global `~/.ovld` data directory (SQLite, object storage, VCS baselines, native-session caches)
+- `OVERLORD_BACKEND_URL` — production/global backend target; an *explicit* runtime value (shell export, container/launcher injection) takes precedence over the resolved `overlord.toml` `backend_url`
+- `OVERLORD_BACKEND_URL_DEV` — **development-only** backend target, read solely by the in-repo source build and the dev/test tooling that runs it (`yarn dev`, the test harness). An installed/published `ovld` never reads it, and nothing aliases it into the production `OVERLORD_BACKEND_URL`
+- `OVERLORD_WEB_PORT` — port the local backend binds when launched
+- `OVERLORD_USER_TOKEN` / `OVLD_USER_TOKEN` / `USER_TOKEN` — bearer token sent to the backend when set (checked in that order; takes precedence over stored credentials)
+- `DATABASE_URL` — Postgres connection string read by a backend you run yourself (service layer + Better Auth); the client-only CLI does not open it
+
+Each `ovld` invocation resolves its own config and backend target
+independently — it is **not** a single shared connection. Resolution order,
+highest precedence first: an explicit runtime export of the channel variable
+(`OVERLORD_BACKEND_URL`, or `OVERLORD_BACKEND_URL_DEV` for the dev build) set
+before the CLI loads any env file → the per-instance `overlord.toml` `backend_url`
+(what `ovld config set` writes) → the env-file default next to that `overlord.toml`
+(`OVERLORD_BACKEND_URL_DEV` from `.env.local` for the source/dev build,
+`OVERLORD_BACKEND_URL` from `.env.prod` for production/package builds) → a
+hardcoded fallback. `overlord.toml` is a per-instance, **uncommitted** file
+(gitignored like `.env.*`; generate it with `ovld init` / `ovld config set`, see
+`overlord.toml.example`), so there is no shared config file to keep host-neutral.
+A context-specific target — a Docker-internal host alias, another machine's
+address — belongs in an explicit `OVERLORD_BACKEND_URL` set when that process is
+launched. The dev-only `OVERLORD_BACKEND_URL_DEV` is read **only** by the source
+build; an installed `ovld` resolves as production and ignores it (and `.env.local`)
+even inside a dev checkout.
+
+The local backend/Desktop package owns SQLite and migrations. The published npm
+CLI only stores the backend URL and sends HTTP requests.
+
+### Desktop and CLI authentication
+
+Both the desktop app and the CLI authenticate to `/api/*` with a bearer token:
+
+- **Session bearer** — from `ovld auth login` (email/password) or a desktop
+  sign-in on the **local** backend. Stored in `~/.ovld/auth.json` for the CLI
+  and in the desktop shell's encrypted settings for each backend profile.
+- **USER_TOKEN** (`out_…`) — long-lived token from Settings → Tokens. Works for
+  headless/CI use via `OVERLORD_USER_TOKEN` or `ovld auth login --token`. On
+  cloud backends, interactive email/password login creates and stores a full
+  `USER_TOKEN` automatically so runner/protocol CLI surfaces can authenticate.
+
+For the **local** backend, desktop and CLI share `~/.ovld/auth.json`:
+
+- Signing in through the desktop app writes the session bearer to `auth.json`, so
+  `ovld` can use the same credentials without a second login.
+- Running `ovld auth login` for the local backend writes `auth.json`; the desktop
+  app imports that token on the next launch (or when switching back to Local) if
+  it has no saved session for that profile.
+
+**Cloud backends are separate.** Adding or switching to a cloud backend in the
+desktop app updates `~/.ovld/overlord.toml` with the new `backend_url`, but it
+does **not** update CLI auth. After switching backends in either surface, run
+`ovld auth status` to confirm the CLI is pointed at the same URL and still
+logged in. If `credentialSource` is `stored_mismatch` or `loggedIn` is false, run
+`ovld config set cloud <url>` (if needed) and `ovld auth login`. Email/password
+login on a cloud backend uses the session only once to create a 90-day full
+`USER_TOKEN`, then stores that token in `auth.json`.
+
+When a stored CLI credential is rejected with HTTP 401, `ovld` clears
+`auth.json` and tells you to run `ovld auth login` again.
+
+### Headless / container setup
+
+In a container, CI job, or any non-TTY environment, configure `ovld` entirely
+through environment variables and non-interactive flags — no interactive prompts
+are required. Each item below is a single command:
 
 ```bash
-export OVERLORD_URL=http://localhost:3000
+# 1. Database URL — Postgres persistence for a backend you run in the same
+#    container (consumed by the service layer + Better Auth). Omit if the CLI
+#    only talks to an already-running remote backend.
+export DATABASE_URL="postgres://user:password@host:5432/overlord"
+
+# 2. Backend URL — where the CLI sends HTTP /api/* requests.
+export OVERLORD_BACKEND_URL="https://overlord.example.com"
+
+# 3. Auth token — bearer USER_TOKEN sent with every backend request.
+#    Generate one in Overlord Desktop: Settings > Tokens.
+export OVERLORD_USER_TOKEN="out_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
+# 4. Agent connector — write the local agent connector config (non-interactive).
+ovld agent-setup claude            # one of: claude | codex | cursor | all
 ```
 
-Common commands:
+Then verify the backend is reachable and authenticated:
 
 ```bash
-ovld auth login
-ovld auth status
-ovld attach
-ovld claude "Refactor the auth middleware" --model opus --thinking high
-ovld codex "Investigate the memory leak" -- --search --full-auto
-ovld create "Investigate the failing build" --agent codex
-ovld prompt "Draft a fix for the onboarding flow"
-ovld version
-ovld update
-ovld protocol discover-project
-ovld protocol discover-project --project-id <project-id>
-ovld protocol discover-project --working-directory /path/to/repo --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"
-ovld protocol attach --ticket-id <ticket_id>
-ovld protocol search-tickets --query "auth refactor" --status next-up,execute
-ovld protocol update --session-key <session-key> --ticket-id <ticket_id> --summary "Working on it" --phase execute
-ovld protocol heartbeat --session-key <session-key> --ticket-id <ticket_id> --phase execute --percent 50 --note "Running tests"
-ovld runner start
-ovld runner status
-ovld runner clear <objective_id>
-ovld runner clear-all
-ovld setup
-ovld setup codex
-ovld setup claude
-ovld setup cursor
-ovld setup antigravity
-ovld setup all
-ovld launch antigravity --ticket-id <ticket_id>
 ovld doctor
 ```
 
-**Antigravity:** Gemini CLI is deprecated. Use `ovld setup antigravity` and `ovld launch antigravity --ticket-id <ticket_id>`. Antigravity manages model selection internally.
+Notes for headless use:
+
+- **No `ovld auth login` needed.** The token env vars (`OVERLORD_USER_TOKEN`,
+  `OVLD_USER_TOKEN`, or `USER_TOKEN`) are read directly and take precedence over
+  stored credentials. To persist a token to `~/.ovld/auth.json` instead, run the
+  non-interactive `ovld auth login --token out_...` (works without a TTY).
+- `ovld agent-setup` accepts `--home <dir>` to target a specific `OVLD_HOME`,
+  `--dry-run` to preview, and `--json` for machine-readable output. List
+  installable connectors with `ovld agent-setup --json`.
+- Set `OVLD_HOME=/some/writable/dir` if the default `~/.ovld` is not writable in
+  your container; it relocates the entire CLI data directory.
+- Interactive `ovld auth login` / `ovld config set` (no args) and `ovld setup`
+  require a TTY; use the env vars and explicit flags above in their place.
 
-The CLI is organization-agnostic: `ovld auth login` stores your identity only and never a default organization. Your identity (OAuth session or agent token) resolves to the list of organizations you belong to — see `ovld auth status --verbose`. Each command resolves its organization from the `ticket_id` (values such as `1:899` carry the organization id), then an explicit `--organization-id`, otherwise from your membership. Commands that browse or search — `ovld add-cwd`, `ovld create`/`ovld prompt`, `ovld tickets list`, and `ovld protocol search-tickets` — span every organization you belong to. Actions against an organization you are not a member of return a clear permission error rather than silently falling back to another org.
+### What requires the backend
 
-When `ovld launch` has an explicit `--working-directory`, or when you run it from a registered project directory containing `.overlord/project.json`, it exports `TMPDIR`, `TMP`, `TEMP`, and `OVERLORD_TMPDIR` to that project's `.overlord/tmp/` directory before spawning the agent. Otherwise it falls back to the system temp directory.
+These commands work without a backend: `ovld help`, `ovld version`,
+`ovld update`, `ovld config ...`, `ovld prune`, and connector setup/inspection commands that only touch local
+files. `ovld update --check` compares the installed package version with the latest
+published npm version, and `ovld update` upgrades the global `overlord-cli`
+install through npm. Commands that read or mutate Overlord state — projects, missions,
+protocol calls, runner queue operations, and launch context assembly — call the
+configured backend URL.
 
-## Requirements
+`ovld runner` is still local in the important sense: it claims work through the
+backend API, then spawns the selected agent process on your machine in the
+resolved project directory. The queue state remains in the backend.
 
-- Node.js 20 or newer
-- Access to an Overlord instance when using authenticated commands
+## For Developers
 
-## Commands for Humans
+### Contract Components
 
-Find full CLI docs here: https://www.ovld.ai/docs/surfaces/cli
+This module is the developer-facing home for three components defined in
+[`CONTRACT.md`](https://github.com/cooperativ-labs/OpenOverlord/blob/main/CONTRACT.md):
 
-Top-level commands (see `ovld help`):
+| Component      | Stable id  | What it owns                                                                                                                                                                        |
+| -------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CLI Layer      | `cli`      | Management command names/shapes, project linking & discovery, config file locations (`overlord.toml`, `.overlord/project.json`), human-readable output conventions                  |
+| Protocol Layer | `protocol` | `ovld protocol` subcommands and flags, session lifecycle (`attach → (update\|heartbeat)* → (ask\|deliver)`), context-assembly format, delivery payload + change-rationale recording |
+| Runner Layer   | `runner`   | `execution_requests` queue claiming and launch, working-directory resolution, `ovld runner` commands, execution-target selection                                                    |
 
-- `<agent> "<prompt>"` - create a ticket from the prompt (project inferred from the current directory) and launch the agent on it in one step, e.g. `ovld claude "fix the flaky login test" --model opus`. Built-in agents need an installed connector (`ovld setup <agent>`, override with `--allow-uninstalled`); your custom agents launch by id. Flags after a standalone `--` pass through to the agent binary.
-- `attach` - search tickets and launch an agent interactively (`ovld attach [ticketId] [agent]`)
-- `create` - create a ticket with numbered project selection; supports `--agent`, `--model`, `--delegate` (same delegate flags as `ovld protocol create`)
-- `create-project` - create a project, registering the current directory (or `--directory`) as its primary resource in one step; `--no-directory` makes a bare project (alias for `ovld protocol create-project`)
-- `prompt` - create a ticket, then launch an agent on it
-- `auth` - `login`, `status`, `repair` (shared Desktop/CLI credentials), or `logout`
-- `tickets` - `create` or `list` (optional `--status`)
-- `ticket` - `context <ticketId>` to print context for one ticket
-- `launch`, `restart` - launch or resume an agent session
-- `runner` - claim queued execution requests and launch assigned agents with `ovld launch`
-- `connect`, `run`, `resume` - legacy aliases for `launch` and `restart`
-- `setup` - install the Overlord connector for an agent; `ovld setup [agent|all]` (interactive with no args). `ovld setup claude` also performs the one-time v3.25.0 to v4 Claude plugin migration
-- `update` - install the latest CLI release from npm
-- `doctor` - validate installed connectors and check for CLI updates
-- `version` - print the installed CLI version
+These stay distinct components in the contract (separate interaction surfaces
+and ownership). They are grouped into one developer module because they are all
+the `ovld` command surface and tend to be worked on together.
 
-## Commands for agents
+### Documentation
 
-Agents can find docs here: https://www.ovld.ai/docs/for-agents
+Requirements and behavior specs are colocated in this module's
+[`docs/`](https://github.com/cooperativ-labs/OpenOverlord/tree/main/cli/docs) folder (see the root [README](https://github.com/cooperativ-labs/OpenOverlord/blob/main/README.md#modules) for the
+colocation convention):
 
-`ovld protocol <subcommand>` is the surface agents and hooks use for ticket lifecycle work. Run `ovld protocol help` for flags, env fallbacks, and examples.
+- [01 — Command Reference](https://github.com/cooperativ-labs/OpenOverlord/blob/main/cli/docs/01-command-reference.md): exhaustive tables of `ovld` commands, subcommands, and flags.
+- [02 — CLI-First Product Surface](https://github.com/cooperativ-labs/OpenOverlord/blob/main/cli/docs/02-cli-first-product-surface.md): management commands, configuration, project linking, output contracts.
+- [03 — Agent Protocol](https://github.com/cooperativ-labs/OpenOverlord/blob/main/cli/docs/03-agent-protocol.md): `ovld protocol` lifecycle, context assembly, updates, delivery, attachments.
+- [04 — Runner and Launch Execution](https://github.com/cooperativ-labs/OpenOverlord/blob/main/cli/docs/04-runner-and-launch-execution.md): execution requests, local runner, launch command generation, auto-advance.
+- [06 — Core Domain and Lifecycle](https://github.com/cooperativ-labs/OpenOverlord/blob/main/cli/docs/06-core-domain-and-lifecycle.md): projects, missions, objectives, sessions, events, statuses, state transitions.
+- [11 — Review, Artifacts, and Change Tracking](https://github.com/cooperativ-labs/OpenOverlord/blob/main/cli/docs/11-review-artifacts-and-change-tracking.md): delivery review records, artifacts, rationale coverage, local diff support.
+- [Test Plan](https://github.com/cooperativ-labs/OpenOverlord/blob/main/cli/docs/testing.md): test plan for the `cli`, `protocol`, and `runner` components — management commands, protocol lifecycle/attach-shape/validation conformance, runner queue atomicity, and surface smoke tests. Part of the root [TEST_PLAN.md](https://github.com/cooperativ-labs/OpenOverlord/blob/main/TEST_PLAN.md).
 
-- `auth-status` - return machine-readable auth status for agent runtimes
-- `discover-project` - resolve a project from the current (or given) working directory
-- `attach` - start a ticket session, create a local git checkpoint per executing objective, and return full working context
-- `connect` - start a lightweight session without full context
-- `load-context` - read ticket context without creating a session
-- `revert` - restore the local working tree to an objective checkpoint after fetching its checkpoint row
-- `search-tickets` - find tickets by keyword, status, project, creator, or update date
-- `add-objectives` - append ordered objectives to an existing ticket (`--objectives-json` / `--objectives-file`)
-- `create` - create a draft ticket without attaching (standalone or follow-up; `--project-id` can override the inherited project during follow-up creation)
-- `prompt` - create a ticket and attach to it immediately (`spawn` is a backward-compatible alias)
-- `record-work` - record already-completed chat work as a ticket in review with a completed objective and trigger feed-post generation
-- `update` - post progress, discussion/decision events, optional change rationales, and explicit `--begin-follow-up-work` transitions
-- `heartbeat` - send a lightweight liveness ping plus optional transient `phase` / `percent` / `note` telemetry without creating a ticket event
-- `record-change-rationales` - persist structured change rationales without a normal progress update
-- `ask` - post a blocking question and move the ticket to review
-- `permission-request` - notify Overlord that the agent is requesting tool permission
-- `hook-event` - record lifecycle hook events such as `UserPromptSubmit` / Cursor `beforeSubmitPrompt` without a session key; optionally persist a native resume/session id onto the active Overlord session
-- `read-context` - read shared persistent context for this ticket
-- `write-context` - write shared persistent context for future sessions
-- `deliver` - send artifacts/rationales and move the ticket to review
-- `attachment-prepare-upload` - get a signed upload URL for an objective attachment
-- `attachment-finalize-upload` - finalize an uploaded objective attachment row after storage upload
-- `attachment-download-url` - get a signed download URL for an existing objective attachment
-- `attachment-upload-file` - prepare, upload, and finalize a local objective attachment in one command
-- `get-device` / `update-device` - register the caller machine (per organization + user + fingerprint) and rename its label
-- `create-project` - create a project and, when a `--directory` + `--device-fingerprint` are given, register it as the project's primary resource in one step
-- `list-project-resources` / `add-project-resource` / `update-project-resource` - manage filesystem directories tied to a project device
-- `request-execution` / `claim-execution` / `list-execution-requests` / `clear-execution-requests` / `complete-execution-launch` / `fail-execution-launch` - durable runner queue operations used by auto-advance and manual Run
-- `list-organizations` - list every organization the authenticated user (or agent token) belongs to; the runner uses this to poll all of your organizations, not just the one stored at login
+### Code & Tests
 
-Devices are keyed by **(organization, user, fingerprint)** so the same physical workstation can appear once per org session.
+The packaged CLI lives in this module as a self-contained Yarn sub-project:
 
-`ovld runner start` keeps a foreground runner alive for CLI-only or remote hosts. It claims compatible execution requests for the current device and launches the assigned agent/model with `ovld launch`; `ovld runner once` claims at most one request and exits. `ovld runner status` now prints the local device record plus the active queue visible to that runner. `ovld runner clear <objective_id>` clears one queued objective, and `ovld runner clear-all` clears every active queue row visible to the caller. By default a single runner drains queued requests from **every organization you belong to**, so you do not need one runner per org. Pin it to a single org with `--organization-id <id>` or `OVERLORD_ORGANIZATION_ID`.
+```bash
+yarn build:cli:prod       # tsc emit + esbuild bundle to cli/dist/index.js
+yarn test:cli             # unit + subprocess smoke tests
+yarn pack:cli:prod        # produce an installable tarball
+node cli/bin/ovld.mjs version
+```
+
+Layout:
+
+```
+cli/
+  bin/ovld.mjs            # published bin entry (imports bundled dist/index.js)
+  src/                    # TypeScript implementation
+  scripts/build.mjs       # tsc emit for tests + esbuild bundle for runtime
+  dist/                   # build output (gitignored; index.js is self-contained)
+  test/                   # colocated tests, including cli/test/e2e/
+  package.json            # bin map, build scripts, pack metadata
+```
+
+The CLI ships command parsing, config/auth onboarding, connector setup, backend
+client calls, and local runner/agent launch logic. Run `yarn build:cli:prod` before using
+the compiled CLI (`node cli/bin/ovld.mjs …`).
 
-If you are troubleshooting "why is `ovld runner` randomly executing", the runner is usually claiming a request that was already queued by manual Run or auto-advance. Inspect the queue with `ovld runner status`, then clear the specific objective with `ovld runner clear 8974e557-bec4-4984-b12c-be46bd63207c` or `ovld protocol clear-execution-requests --objective-id 8974e557-bec4-4984-b12c-be46bd63207c`.
+### In-repo build vs installed CLI
 
-Use `create` for future work you want to track, `prompt` for work that should start immediately, and `record-work` for work that was already completed in chat and now needs a review ticket plus feed post. Use multiple tickets when prompts represent different features or goals; use `add-objectives` or `--objectives-json '[{"objective":"Step one"},{"objective":"Step two"}]'` when prompts are sequential steps toward the same feature or goal.
+Project-management work (`ovld protocol attach/update/deliver`, mission creation,
+launching) uses the **installed** `ovld` so those calls hit the installed
+Desktop instance and real mission data. Bare `ovld` on `PATH` always resolves to
+the global install — keep it that way.
 
-`ovld protocol deliver` accepts either discrete flags like `--summary` / `--artifacts-json`, an inline full payload with `--payload-json '{"summary":"...","artifacts":[...],"changeRationales":[...]}'`, or a file/stdin payload with `--payload-file <path|->`.
+The two builds also choose their env profile by origin (`detectCliEnvProfile`):
+the **installed** CLI (under `node_modules`) runs as **production** — it never
+auto-loads `.env.local` or reads `OVERLORD_BACKEND_URL_DEV`, even when invoked
+inside this repo — while the **source** build (`node cli/bin/ovld.mjs`, `yarn
+ovld:dev`, the test harness) runs as **development** and reads `.env.local`. So
+in-repo dev work must go through the source build, never bare `ovld`.
+
+Testing in-repo CLI/Desktop changes must never touch the installed instance
+(`~/.ovld`, `:4310`). Copy `.env.local.example` to `.env.local` so source
+workflows use a repo-local dev home (`database/.local/dev-home`) and API on
+`:4320` while Desktop keeps `~/.ovld` and `:4310`.
+
+- `yarn dev` / `yarn db:*` / `yarn ovld:dev` read `.env.local` and share the
+  persistent in-repo dev instance.
+- `yarn test` runs under `scripts/with-ovld-home.mjs` with a throwaway temp
+  home so tests never read or write `~/.ovld` or the dev-home database.
+
+For a one-off isolated shell without `.env.local`:
+
+```bash
+export OVLD_HOME="$(mktemp -d)"
+export OVERLORD_WEB_PORT=4320
+export OVERLORD_BACKEND_URL_DEV=http://127.0.0.1:4320
+yarn workspace @overlord/webapp start
+node cli/bin/ovld.mjs doctor
+```
 
-After delivery, follow-up messages are recorded as discussion by default. To start implementation again on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving back to `--phase execute`. Use `--event-type discussion_summary` or `--event-type decision` for important non-file outcomes. Once follow-up execution records a real work signal, such as an execution update, git snapshot, change rationales, deliverables, or explicit `pending_delivery` intent, Overlord marks the objective `pending_delivery` so redelivery is only required for actual post-delivery work. Use `ovld protocol heartbeat` during long-running mechanical work when you need liveness without adding activity-feed noise.
+**Never `yarn link` / `npm link` the workspace CLI** (there is deliberately no
+`load:cli` script): linking shadows the global `ovld`, so `ovld protocol` calls
+would run untested working-tree code against your real mission data.
 
-## License
+### Interaction Boundaries
 
-Permission is granted to use this software for any purpose, free of charge. You may not modify, distribute, sublicense, or sell copies of the software without explicit permission from the author.
+Per the contract, the CLI/protocol/runner surfaces reach persistence only
+through the configured **REST/backend API** — never direct table writes.
+See the Interaction Surfaces section of [`CONTRACT.md`](https://github.com/cooperativ-labs/OpenOverlord/blob/main/CONTRACT.md) before
+making any cross-module change.

package/bin/ovld.mjs

@@ -1,13 +1,8 @@
 #!/usr/bin/env node
 
-/**
- * Canonical CLI entrypoint. Used by both the npm package and the Electron app.
- * All CLI source files live in _cli/ alongside this file.
- */
+import { redactSecrets, runCli } from '../dist/index.js';
 
-import { runCli } from './_cli/index.mjs';
-
-runCli({ primaryCommand: 'ovld' }).catch((error) => {
-  console.error(error instanceof Error ? error.message : error);
+runCli({ primaryCommand: 'ovld' }).catch(error => {
+  console.error(redactSecrets(error instanceof Error ? error.message : error));
   process.exit(1);
 });

package/dist/connectors/AGENTS.md

@@ -0,0 +1,148 @@
+# Connectors Module — Agent Extension Guide
+
+This file tells agents how to extend the Connectors module to add new agent harness connectors for users. Read [`CONTRACT.md`](../CONTRACT.md) and the [component-contract skill](../.claude/skills/component-contract/SKILL.md) before making any cross-module change.
+
+---
+
+## What "extending connectors" means
+
+A connector lets an AI coding harness (Claude Code, Codex, Cursor, etc.) speak the `ovld protocol` and inherit mission context. Extensions in this module fall into four categories:
+
+| Extension type | Example user request |
+| --- | --- |
+| New agent connector | "Add a connector for OpenCode / Windsurf / Zed" |
+| New hook type | "Add a Stop hook for pending-delivery checks" |
+| Extend connector core | "Add a new canonical instruction to all connectors" |
+| New capability flag | "Connectors can now declare `supports-multi-session`" |
+
+Each type has a different procedure below.
+
+---
+
+## Before You Start
+
+1. Read `CONTRACT.md` — Connector Layer section (stable id: `connector`).
+2. Read [`connectors/docs/05-connectors-and-agent-plugins.md`](docs/05-connectors-and-agent-plugins.md) for the four-layer model: connector core, plugins, adapters, and prompt wrappers.
+3. Read [`connectors/docs/agent-harness-configuration-architecture.md`](docs/agent-harness-configuration-architecture.md) for ownership boundaries.
+4. Check `contract/extension-points.yaml` for approved capability flags and hook types before adding new ones.
+5. After connector edits, follow the [connector-versions skill](../.claude/skills/connector-versions/SKILL.md) and run `yarn connectors:version:bump`.
+
+---
+
+## Adding a New Agent Connector
+
+A new connector is the primary sanctioned extension point for this module. It requires a conformance manifest but does not require a contract version bump unless it introduces new capability flags or hook types.
+
+**Steps:**
+
+1. **Create the connector directory**: `connectors/adapters/<agent-name>/`.
+
+2. **Write the connector plugin** — a Markdown (or native plugin format) file that extends the connector core. Adapter `skills/overlord-mission/SKILL.md` templates must include `<!-- @connector-core -->`; `ovld agent-setup` interpolates `connectors/core/overlord-mission/SKILL.md` at that marker. Required canonical instructions (from the core):
+   - Attach first (`ovld protocol attach`)
+   - Treat the mission prompt as authoritative
+   - Post meaningful progress updates
+   - Use heartbeat during long work with no meaningful update
+   - Ask exactly one blocking question and stop when blocked
+   - Deliver last with summary, artifacts, and change rationales
+   - Record all meaningful file changes as structured rationales
+   - Use stdin/file flags for shell-special content
+   - Do not continue after delivery unless explicitly asked
+   - Run local repair before asking the user to fix setup
+
+3. **Write the plugin adapter** — packaging/install glue for the agent's native plugin system. Adapters must:
+   - Be idempotent (re-running setup produces the same result)
+   - Not clobber existing user settings
+   - Be detectable by `ovld doctor` as stale, missing, or partially installed
+
+4. **List managed files** in the adapter's manifest so `ovld doctor` can verify them.
+
+5. **Write a prompt wrapper** if the agent needs mission context prepended at launch time. The wrapper receives a context file path and emits the final prompt text.
+
+6. **Create `connectors/adapters/<agent-name>/conformance-manifest.yaml`** declaring:
+   ```yaml
+   contractVersion: "0"
+   componentType: connector
+   componentKey: <agent-name>
+   capabilities:
+     - <only approved flags from contract/extension-points.yaml>
+   hookTypes:
+     - <only approved types from contract/extension-points.yaml>
+   ```
+
+7. **Validate**: run `ovld contract check connectors/adapters/<agent-name>/conformance-manifest.yaml`.
+
+8. **Document** the connector's launch flags, managed files, and hook scripts in `connectors/adapters/<agent-name>/README.md`.
+
+---
+
+## Adding a New Hook Type
+
+Hook types (`UserPromptSubmit`, `PermissionRequest`, `Stop`) are **stable interfaces** listed in `contract/extension-points.yaml`. Adding a new type requires a contract update first.
+
+**Steps:**
+
+1. **Update `contract/extension-points.yaml`**: add the new hook name to `approvedHookTypes`.
+2. **Update `CONTRACT.md`** Connector Layer section with the new hook's event contract.
+3. **Increment the contract version** in `contract/components.yaml` and add a changelog entry to `CONTRACT.md`.
+4. **Implement the hook script** in `connectors/adapters/<agent-name>/hooks/` (or the connector-specific hook location).
+5. **Hook scripts must not write to the database directly** — use `ovld protocol hook-event` or `ovld protocol update` only.
+6. **Update affected conformance manifests** to declare the new hook type.
+
+---
+
+## Extending the Connector Core
+
+The connector core is the set of canonical Markdown workflow instructions every plugin extends. Changes to the core affect all connectors.
+
+**Steps:**
+
+1. **Check `connectors/docs/05-connectors-and-agent-plugins.md`** to confirm the instruction belongs in the core (universal to all agents) rather than a per-agent plugin.
+2. **Draft the new canonical instruction** following the imperative, agent-readable style of the existing core instructions.
+3. **Update all existing connector plugins** that extend the core if the new instruction changes agent behavior at session start/end.
+4. **Document the change** in `connectors/docs/05-connectors-and-agent-plugins.md` under "Canonical Connector Core."
+
+---
+
+## Adding a New Capability Flag
+
+Capability flags (e.g. `supports-checkpointing`, `supports-multi-session`) are listed in `contract/extension-points.yaml` under `approvedConnectorCapabilities`. New flags require a contract update.
+
+**Steps:**
+
+1. **Add the flag** to `approvedConnectorCapabilities` in `contract/extension-points.yaml`.
+2. **Add a description** of what the flag means in `CONTRACT.md` Connector Layer section.
+3. **Increment contract version** if the flag represents a breaking stable-interface change.
+4. **Declare the flag** in the conformance manifests of connectors that support it.
+
+---
+
+## File Placement Convention
+
+```
+connectors/
+  adapters/
+    claude/              ← Claude Code adapter (reference implementation)
+      conformance-manifest.yaml
+      README.md
+      hooks/
+        user-prompt-submit.sh
+        permission-request.sh
+    codex/               ← Codex adapter
+    cursor/              ← Cursor adapter
+    <new-agent>/         ← New connector goes here
+  docs/                  ← Module-level specs
+  AGENTS.md              ← this file
+  README.md              ← architectural overview
+```
+
+No adapter implementations have landed yet. When they do, the Claude and Codex adapters serve as the reference implementations.
+
+---
+
+## Cross-Module Checklist
+
+- [ ] Read `CONTRACT.md` Connector Layer section
+- [ ] New hook type or capability flag → update `contract/extension-points.yaml` first
+- [ ] Hook scripts → use `ovld protocol` commands only, no direct DB writes
+- [ ] Conformance manifest created and validated for every new connector
+- [ ] `ovld agent-setup <agent>` and `ovld doctor` behavior documented