@wjarka/cezarion 0.15.1 → 0.16.0

package/README.md

@@ -5,10 +5,10 @@
 **Parallel coding agents orchestrator** — a local cockpit for running and
 tracking AI coding-agent tasks in your repo.
 
-Type a task, pick a workflow and an agent — **Claude Code, Codex, OpenCode or pi
-(the latter two experimental), or a mix of them per step** — and watch it work live: steps, tool calls,
+Type a task, pick a workflow and an agent — **Claude Code, Codex, OpenCode, pi or OMP
+(OpenCode, pi and OMP experimental), or a mix of them per step** — and watch it work live: steps, tool calls,
 tokens, diffs, in a browser cockpit that runs entirely on your machine.
-Your CLI logins, your `gh`, your files. No accounts, no database, no cloud.
+Your CLI logins, your `gh`, your files. No accounts, no database server, no cloud.
 
 🔥 **Fire and forget.** Queue a stack of autonomous coding and maintenance
 tasks and let them run — cezar orchestrates them across isolated worktrees,
@@ -20,10 +20,10 @@ your phone, working your backlog while you're away.
 [A look inside](#a-look-inside) · [What cezar does best](#what-cezar-does-best) · [What it solves](#what-it-solves) · [Who it's for](#who-its-for) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Core concepts](#core-concepts) · [Cockpit tour](#cockpit-tour) · [Agent backends](#coding-agent-backends) · [Remote access](#remote-access-host-cezar-on-a-server)
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-![Node 20+](https://img.shields.io/badge/Node-20%2B-339933)
+![Node 24.15+](https://img.shields.io/badge/Node-24.15%2B-339933)
 ![TypeScript 7.x](https://img.shields.io/badge/TypeScript-7.x-3178c6)
 ![Zero config](https://img.shields.io/badge/config-zero-success)
-![No database](https://img.shields.io/badge/database-none-success)
+![Embedded SQLite](https://img.shields.io/badge/database-embedded%20SQLite-success)
 
 </div>
 
@@ -36,7 +36,9 @@ npx cezarion         # → cockpit at http://localhost:4321
 
 That's the whole setup. If your `claude` CLI is logged in (Pro/Max) and `gh` is
 authenticated, there is nothing else to configure. State lives in `.ai/cezar/`
-inside your repo — plain JSON, NDJSON and Markdown you can `cat` and fix by hand.
+inside your repo: your runs in one embedded SQLite file (`runs.db`, built into
+Node: no server, no install, no config), event logs in NDJSON and journals in
+Markdown. Everything except the run file you can `cat` and fix by hand.
 
 Local npm installations have a workspace update API. `POST
 /api/v1/workspace/application-update/apply` with `{}` prepares the release
@@ -72,8 +74,8 @@ conductor-style app, one-agent front-ends. cezar's bet is different. Three thing
 it does better than any of them:
 
 - 🪶 **Genuinely zero config.** `npx cezarion` in your repo and you're running —
-  no wizard, no API keys, no env vars, no schema, no database. It rides the
-  `claude` / `codex` / `opencode` / `pi` logins and the `gh` you already have, and every
+  no wizard, no API keys, no env vars, no schema, no database server. It rides the
+  `claude` / `codex` / `opencode` / `pi` / `omp` logins and the `gh` you already have, and every
   missing piece degrades gracefully instead of blocking you.
 - 🖥️ **Built for a server (VPS mode).** cezar is made to live on a **VPS, cloud,
   or dedicated box** as an always-on janitor for your repo — headless-first, with
@@ -151,7 +153,7 @@ and an orchestrator keeps a whole queue of them moving.
 
 ## Quick start
 
-**Prerequisites:** Node 20+, at least one logged-in agent CLI — the
+**Prerequisites:** Node 24.15+, at least one logged-in agent CLI — the
 [`claude` CLI](https://github.com/anthropics/claude-code) (Pro/Max subscription),
 the [`codex` CLI](https://github.com/openai/codex), or
 [OpenCode](https://opencode.ai) — and, optionally, `git` and the `gh` CLI.
@@ -162,10 +164,15 @@ npx cezarion               # start the cockpit for the current repo
 #   or: npx @wjarka/cezarion
 ```
 
-The cockpit opens at `http://localhost:4321` (auto-picks the next free port if
-busy). If another cockpit already serves this repository, the command prints its
-URL and exits with an error. Different repositories can run side by side; after
-a cockpit exits or crashes, its repository can start again without cleanup.
+The cockpit opens at `http://localhost:4321`. If the requested port is occupied,
+startup exits with an actionable error before recovering tasks. Automatic port
+bounce has been removed (hearsay-tools/cezarion#722): open the existing cockpit,
+stop the process using that port, or choose `cez --port <free-port>` deliberately.
+Use `cez --port 0` to ask the OS for an ephemeral port. If another cockpit already
+serves this repository, the command prints its URL and exits with an error,
+even with a different port. Different repositories can run side by side on
+explicitly different ports; after a cockpit exits or crashes, its repository
+can start again without cleanup.
 Type a task, pick a workflow, hit **Start**. That's it.
 
 ```bash
@@ -255,7 +262,7 @@ event live and parks the run at a review gate when there's a diff to inspect.
         ▼
    ┌─────────────┐   SSE (replay + live)   ┌──────────────────────────┐
    │ .ai/cezar/  │ ──────────────────────► │  cockpit  localhost:4321 │
-   │ JSON·NDJSON │                         │  Tasks · Git · GitHub ·  │
+   │SQLite·NDJSON│                         │  Tasks · Git · GitHub ·  │
    │ ·Markdown   │                         │  Skills · Workflows      │
    └─────────────┘                         └──────────────────────────┘
                                                   │
@@ -371,7 +378,16 @@ Every view is project-scoped:
 `<projectId>` is a slug derived from the folder name (`my-app`, then `my-app-2`
 on a collision), and `/p/default/…` always means the project cezar was started
 in. The desktop rail selects the project. Its sidebar shows the project header,
-view tabs and task list, with Needs you before Pinned, Working and Recent.
+view tabs and task list, ordered **Needs you → Finished → Working**.
+Pins stay first within their status section and do not spend the default ten-row
+budget; Finished takes priority over Working when that budget fills up. Each
+section starts expanded and folds independently using its heading (click, Enter
+or Space). Folding is remembered per browser, project and section, separately
+from folding a project. Folded headings keep full task counts and attention
+indicators, including tasks outside the visible row limit. These controls work
+in the mobile drawer too. **Archive all** appears only on Finished and archives
+all eligible unpinned tasks, including hidden rows; individual archive actions
+and Undo remain available. Archived keeps its existing history view.
 Inbox and Automations appear in More views when enabled. The project menu
 offers Mark all read and project settings; local mode also offers Open in and
 Copy path. Active/Archived remains below the Tasks heading. The new-task
@@ -411,11 +427,23 @@ server stopped, and `CEZ_HOME` selects which workspace they operate on.
 
 Settings split along the same line: **General** (the project's folder, its
 registry facts, its parallel-task ceiling, and Remove), **Agents**, **Agent config**,
-**Worktrees**, **Bookmarklets** and **Prompt templates** describe one
+**Worktrees**, **Sidebar**, **Bookmarklets** and **Prompt templates** describe one
 repo and live under `/p/<projectId>/settings`; **Appearance**,
 **Notifications**, **Resources**, **Skills**, **Agent accounts** and **Projects**
 are yours or the machine's and live at `/settings/global`.
 
+**Settings → Sidebar** controls this project's task rows on desktop and mobile.
+Set **Overall**, **Needs You**, **Finished**, and **Working** to a positive whole
+number or **Unlimited**. Defaults are 10 overall and Unlimited for each section.
+The overall budget is allocated in section order (Needs You, Finished, Working),
+and each section must also fit its own limit. Unlimited removes only its selected
+constraint. Pinned rows and groups containing pins bypass both budgets; a grouped
+task counts as one row. Archived uses only the overall limit, with no pin exemption.
+Save applies the preferences to this project and keeps them after a reload.
+Refreshed preferences update an untouched form; unsaved edits stay in place.
+Malformed stored sidebar limits fall back field by field to these defaults,
+while valid limits and unrelated preferences are preserved.
+
 On desktop, Settings replaces the sidebar task list with two groups: **This project**
 and **Global · every project**. Each group includes General and its available sections;
 the current section is highlighted, and the main page shows its content. On mobile,
@@ -432,6 +460,11 @@ tasks, excluding references to other repositories. Counts show a `+` when the
 underlying list or search reaches its result limit; an unavailable count is not
 shown as zero. Views without their own navigation still show tasks in the sidebar.
 
+Open an issue to see **Linked tasks (N)** beneath its heading. Each row opens a task
+in the current project and shows its title, status and date, newest first. Archived
+tasks remain listed with an **Archived** label, so diagnosis and implementation
+sessions are both reachable.
+
 The Git sidebar lists **Task worktrees** that still exist on disk, including retained
 worktrees from finished tasks. Each row shows its branch, task title, status and
 available diff counts, and opens that task's Changes tab. Reclaimed worktrees disappear
@@ -482,7 +515,10 @@ Each row shows **every** PR and issue it references — a task opened on an issu
 that landed a PR shows both — plus its cost and live CPU/memory, and can be
 marked **read/unread** (the eye) or **archived** (or restored) right there. Every task title, project name and project group heading links into that
 project, so the thread, its diff and its worktree are one click away and stay
-exactly where they were.
+exactly where they were. Returning to a long thread restores its saved row measurements
+once the replay has rebuilt the same ordered messages, keeping the same content in view.
+Scrolling, jumping to the latest message, or loading different history takes ownership
+from that restoration; a thread left at its live tail follows the current tail.
 
 There is deliberately **no project filter**: narrowing this page to one project
 is that project's own Tasks page, which is a better version of the same answer
@@ -529,8 +565,10 @@ its existing automatic-check schedule when no CI wait is registered.
 
 Cezar reports passed, failed, cancelled or skipped checks, no checks, changed head,
 timeout or an operational error. It watches the registered commit: a new PR head
-is reported separately, and the agent decides whether to wait again. Four watchers
-run concurrently; queued waits retain their original deadline. Results are bounded
+is reported separately, and the agent decides whether to wait again. The first
+observation runs immediately. Later check-status and PR-head polls run every 30
+seconds, and no setting changes that interval. Four watchers run concurrently;
+queued waits retain their original deadline. Results are bounded
 observations, not merge approval or evidence that every expected workflow appeared.
 The agent still decides its next action; CI success never completes the task or
 accepts review. A human message cancels the current wait, and CI never answers a
@@ -538,7 +576,7 @@ pending human question. Controller recovery can replay an observation after an
 ambiguous delivery checkpoint, identified by its stable lifecycle input ID.
 
 The adapters are bundled for Claude (including `claude-cli`), Codex, OpenCode,
-Cursor and Pi. Internal socket/capability environment values are runtime wiring,
+Cursor, Pi and OMP. Internal socket/capability environment values are runtime wiring,
 not settings to create or share. If the tool is unavailable or denied, its error
 is surfaced while ordinary tasks continue. See [the CI-wait protocol](AGENT_PROTOCOL.md#ci-wait-tool-contract-474)
 for limits and the executable harness verification required before release.
@@ -589,7 +627,7 @@ cez worker stop <worker-id>
 cez worker destroy <worker-id>
 ```
 
-Use `cez worker --help` to list operations and flags, or `cez worker <operation> --help` for one operation. Explicit help prints human-readable text and exits successfully without an active delegation session. Commands otherwise return bounded JSON and a nonzero exit on failure or incomplete cleanup. Spawn requires a committed baseline (`parent-head` or an explicit ref) and pins its SHA at acceptance; dirty parent edits are excluded. Optional `--context '<text>'` or `--context-file <UTF-8-file>` supplies selected context, not the parent's conversation. The two flags are mutually exclusive, and combined task/context text is limited to 100,000 characters. The API also accepts up to 32 pinned-baseline file or parent-attachment references, with at most 8 MiB of copied attachments. Inspect reports worker-local input locations. Reuse a request ID only with the same task, baseline, context, backend, model, effort and workflow when retrying a lost response. There are at most 32 accepted creations per parent, counting destroyed workers, and 32 undelivered steering messages per worker.
+Use `cez worker --help` to list operations and flags, or `cez worker <operation> --help` for one operation. Explicit help prints human-readable text and exits successfully without an active delegation session. Commands otherwise return bounded JSON and a nonzero exit on failure or incomplete cleanup. Spawn requires a committed baseline (`parent-head` or an explicit ref) and pins its SHA at acceptance; dirty parent edits are excluded. Optional `--context '<text>'` or `--context-file <UTF-8-file>` supplies selected context, not the parent's conversation. The two flags are mutually exclusive, and combined task/context text is limited to 100,000 characters. The API also accepts up to 32 pinned-baseline file or parent-attachment references, with at most 8 MiB of copied attachments. Inspect reports worker-local input locations. Reuse a request ID only with the same task, baseline, context, backend, model, effort and workflow when retrying a lost response. A parent holds at most 32 outstanding workers: accepted, live, or not yet verifiably destroyed. A verified destroy (`cez worker destroy`, or **Clean up** on a finished worker in the cockpit's Workers list) frees a slot; incomplete cleanup keeps its slot until a retry completes. A parent can create at most 1,024 workers in total; past that, start a new task. These limits bound disk resources and runaway spawning, not spending: a worker can be resumed with Continue, and destroying it does not undo charges already made. Cost stays bounded by `maxParallel` and by stopping the parent. There are at most 32 undelivered steering messages per worker.
 
 An incomplete destroy reports the remaining resources and a reason. Cezar retries that recorded request after a delay, including after the project's context recovers on server restart. It removes the owned checkout only after process termination and ownership are verified. If the reason persists, inspect the worker process, Git worktree lock and ownership receipt; correct the blocker and use `cez worker destroy <worker-id>` or the cockpit Destroy action to retry immediately. Cezar leaves ambiguous or replaced resources in place for operator review.
 
@@ -597,7 +635,7 @@ An incomplete destroy reports the remaining resources and a reason. Cezar retrie
 
 Explicit default-account model pins are checked against a fresh, nonempty host catalog after account/model resolution and before a worker is created. Named accounts retain existing validation because a default-account catalog cannot disprove their model access. A miss returns `invalid_input`, available models with advertised efforts, and other runners listing the requested ID in `modelChoices`. Empty, stale, or unavailable discovery leaves existing selection validation in place. Accepted retries and omitted model defaults are unchanged.
 
-Omitted `--backend` inherits the parent's active backend. Same-backend workers inherit omitted model/account/effort; `--backend <claude|codex|opencode|pi|cursor>` selecting another backend resolves that backend's project/default account and model without forwarding another provider's settings. `--model <model>` selects a supported model, subject to existing locks. `--effort <low|medium|high|xhigh|max>` pins reasoning effort on same-backend and mixed-backend spawn; omitted `--effort` still inherits the parent pin on same-backend spawn and drops it on mixed-backend spawn. Accepted identity and grants remain fixed across queuing, restart and Continue, including explicit empty grants. Changing or deleting an account registry entry does not rebind a worker. Missing accepted identity evidence or account homes, incompatible Claude state-file layouts, and conflicting later model locks refuse execution explicitly. Credentials and vendor configuration are never copied; each worker receives its own delegation credential, and unspecified native models stay unspecified.
+Omitted `--backend` inherits the parent's active backend. Same-backend workers inherit omitted model/account/effort; `--backend <claude|codex|opencode|pi|cursor|omp>` selecting another backend resolves that backend's project/default account and model without forwarding another provider's settings. `--model <model>` selects a supported model, subject to existing locks. `--effort <low|medium|high|xhigh|max>` pins reasoning effort on same-backend and mixed-backend spawn; omitted `--effort` still inherits the parent pin on same-backend spawn and drops it on mixed-backend spawn. Accepted identity and grants remain fixed across queuing, restart and Continue, including explicit empty grants. Changing or deleting an account registry entry does not rebind a worker. Missing accepted identity evidence or account homes, incompatible Claude state-file layouts, and conflicting later model locks refuse execution explicitly. Credentials and vendor configuration are never copied; each worker receives its own delegation credential, and unspecified native models stay unspecified.
 
 Wait registers immediately. End the parent turn to release scheduler capacity; Cezar resumes it on a selected settled outcome or the finite deadline. `any` is the default, `one` requires exactly one worker, and `all` waits for every selected worker. Review, completion, failure, cancellation with proven termination, and destruction are outcomes. Timeout defaults to 600 seconds (1–1800 accepted). `cancel-wait` is idempotent for the retained wait ID and cannot cancel a newer wait. Timeout and wait cancellation report partial outcomes and unresolved workers, never cancel workers, and never automatically re-wait. Steering is attributed agent input and cannot answer a pending human question.
 
@@ -605,7 +643,7 @@ Parents and owned workers can converse in both directions; a worker may address
 
 Messages allow 100,000 characters each, with at most 32 undelivered inputs per recipient, 1,024 messages per family, and 32 pending requests. Request deadlines default to 600 seconds, configurable per message with `--timeout-seconds 1–1800`. Request waits use the same limits and `one`/`any`/`all` modes as worker waits, and each run has one active wait. Incoming conversation can interrupt a parked wait without settling its requests. `cancel-request` cancels an obligation; `cancel-wait` only stops waiting. Completion without a reply, failure, cancellation, destruction, timeout, or sender closure settle obligations distinctly. Late replies remain visible without reopening them.
 
-Messages reach a live recipient as soon as they are accepted, including mid-turn: Claude, Codex, Pi and OpenCode steer them into the running turn, and the model reads them at its next step. Cursor delivers at the turn boundary, because a second prompt would cancel its running turn. Pending conversations go together, in order, up to 32 messages and 100,000 formatted characters per batch; a single valid message is never split. Every message keeps its ID, sender, delivery receipt and request outcome; receipts show queued, delivered and read (when the agent's harness can tell) separately. A pending human question holds messages until it is answered, then they follow right behind the answer. The thread's Details distinguish creation, delivery confirmation and event-recording times.
+Messages reach a live recipient as soon as they are accepted, including mid-turn: Claude, Codex, Pi, OMP and OpenCode steer them into the running turn, and the model reads them at its next step. Cursor delivers at the turn boundary, because a second prompt would cancel its running turn. Pending conversations go together, in order, up to 32 messages and 100,000 formatted characters per batch; a single valid message is never split. Every message keeps its ID, sender, delivery receipt and request outcome; receipts show queued, delivered and read (when the agent's harness can tell) separately. A pending human question holds messages until it is answered, then they follow right behind the answer. The thread's Details distinguish creation, delivery confirmation and event-recording times.
 
 Sending to a review or terminal participant without `--resume` reports `not-delivered` and `continuation-required`, with the reason and next command; the CLI exits 1. An active parent can use `worker send --resume` (request or progress) to continue its settled done/review/failed worker with that message as the new instruction. No human Continue is needed for this parent-controlled action. A retry with the same payload and ID never creates another continuation; changing a rejected send to use `--resume` requires a new ID. Stopped or destroyed workers need a new worker. Workers cannot resume parents, and conversation never answers a pending human question. Durable IDs deduplicate accepted queue entries and event replay, but a crash between provider acceptance and its durable delivery checkpoint can leave transport delivery ambiguous; this is not an exactly-once execution guarantee.
 
@@ -633,11 +671,23 @@ Fix the `cez task` docs. Keep $(example) and "quotes" literal.
 EOF
 )
 cez task wait "$id" --timeout-seconds 900                     # 0 done/review/needs you · 1 failed · 3 timeout
-cez task status "$id"                                         # slim JSON: status, attention, question, branch…
-cez task send "$id" 'Use the retry helper instead'            # queued, delivered, or --resume to reopen
+cez task list                                                # currentStepId (running), pullRequestUrl (done/review), capped error (failed)
+cez task status "$id"                                       # slim JSON: status, attention, question, branch, handoffUrl…
+cez task send "$id" 'Use the retry helper instead'            # delivered live, queued before start
+cez task send "$id" --resume 'Continue with the next step'    # resumed: reopen a settled session
 cez task log "$id" --follow --timeout-seconds 300             # JSON lines until it ends
 ```
 
+`list --status` accepts comma-separated values: `queued`, `running`, `waiting`, `review`,
+`done`, `failed`, `cancelled`. Default rows include only the next-action field for their status
+when defined; errors use the first line, at most 200 characters including `…` when cut.
+Default `status` includes `handoffUrl`, a URL to the existing handoff endpoint even before
+contents are seeded, and keeps the full error. `--full` still prints the contract unchanged.
+To answer a pending `question`, use the same `send` with the answer text. Without `--resume`,
+a closed session returns `delivery: not-delivered` and the `next` command. For multi-line or
+shell-sensitive messages use `send <id> --text-file <path|->` (`-` reads stdin); the quoting
+rules below apply to messages too.
+
 Use `--task-file PATH` to read a saved task (for example, `cez task start --task-file task.md`),
 or `--task-file -` to read stdin as above. The quoted heredoc delimiter (`<<'EOF'`) keeps
 backticks and `$()` literal in the task text.
@@ -663,8 +713,8 @@ instead of starting a second. Also: `list`, `stop`, `finish`, `diff [--stat]`, `
 Use `archive <id>` to hide a task from `list`, `unarchive <id>` to restore it, and
 `list --all` to include archived tasks. `list` never shows owned workers, with or without
 `--all`: they are steer targets of their parent task. Id-addressed commands (`status`, `wait`,
-`send`, `log`, `stop`, …) still accept a worker's id. `archive-finished` sweeps finished tasks and prints
-`{"archived": count}`. The single-task commands print `{"id": "…", "archived": true|false}`.
+`send`, `log`, `stop`, …) still accept a worker's id. `archive-finished` sweeps finished tasks (not scheduled runs waiting on a usage limit, and not owned workers, which leave with their parent) and prints
+`{"archived": count, "ids": [...], "pinnedIds": [...]}`. The single-task commands print `{"id": "…", "archived": true|false}`.
 Exit codes:
 `0` ok (`wait`/`start --wait`: the task ended `done`/`review` or stopped for attention), `1` task
 failed/cancelled or a message was not delivered, `2` no cockpit or the cockpit refused (its `error`
@@ -801,12 +851,15 @@ Useful environment variables:
 | `CEZ_CLAUDE_PERMISSION_MODE` | Claude agent-run permission flag: `dontAsk` (default), `acceptEdits`, or `bypass`. `bypass` passes `--dangerously-skip-permissions` and omits `--permission-mode`. Unset or unknown keeps today's `dontAsk` / `CEZ_APPROVAL_GATE` path. Provider verification commands are never given this flag. |
 | `CEZ_CLAUDE_SETTING_SOURCES` | When set, Claude agent runs also pass `--setting-sources <value>` (e.g. `user,project,local`). Unset or empty omits the flag. Provider verification is never given this flag. |
 | `CEZ_FOLLOWUPS=1` | Turn on the global follow-up **Inbox**: agents are asked to leave follow-ups in `todos.json` when they finish, and the Inbox view appears. Off by default — each task's own **Notes** handoff journal runs either way. |
-| `CEZ_AUTOMATIONS=1` | Turn on **GitHub automations**: the Automations view appears and cezar polls GitHub on each enabled automation's interval, launching tasks from what it finds. Off by default, and only the exact value `1` enables it — without it no automation polls GitHub, the automations endpoints answer `409`, and the nav item is absent. Read at boot, so restart after changing it; definitions, receipts and high-watermarks are retained, so unsetting it and restarting restores the feature without migration or data loss. |
-| `CEZ_AUTOSAVE=1` | Re-enable the periodic (90 s) autosave commit in task worktrees. Off by default (#471) — turn-end and pre-PR flushes always run, so branches still end complete. Every autosave names its trigger in the commit subject (`cezar autosave (periodic)` vs `(turn end)` / `(run finalize)` / `(pre-PR)`), so the flushes you keep are distinguishable from the timer you disabled. |
+| `CEZ_AUTOMATIONS=1` | Turn on **automations** (GitHub polls and schedules): the Automations view appears and cezar runs each enabled automation while it is open, launching an ordinary task per match or per occurrence. A schedule (daily, weekdays, weekly, every N hours, in the server's time zone) needs no GitHub remote; a GitHub automation polls on its interval. Off by default, and only the exact value `1` enables it — without it nothing polls or fires, the automations endpoints answer `409`, and the nav item is absent. Read at boot, so restart after changing it; definitions, receipts and high-watermarks are retained, so unsetting it and restarting restores the feature without migration or data loss. |
+| `CEZ_PREVIEW=1` | Turn on **live preview** (experimental): agents register a dev server with the `cezar_preview_serve` tool, and the cockpit opens it in a headless Chromium on the host, docked next to the task. cezar first runs a registered command after you press Run and open. Agents can then use `cezar_preview_stop({ port, restart?: boolean })` to stop or restart their own Cezar-started server with that unchanged approval; changed command, cwd or path needs Run and open again. Adopted servers cannot be stopped by this tool. Off by default, and only the exact value `1` enables it — without it the tool is not listed, its route and the preview WebSocket refuse, and `capabilities.preview` is `false`. Read at boot, so restart after changing it. |
+| `CEZ_PREVIEW_NO_SANDBOX=1` | Launch the preview's Chromium with `--no-sandbox`. Off by default and never added automatically, not even for root or in a container; use it only where Chromium's sandbox cannot start, and only for pages you trust. Only the exact value `1` applies. Read at boot. |
+| `CEZ_AUTOSAVE=1` | Re-enable the periodic (90 s) autosave commit in task worktrees. Off by default (open-mercato/cezar#471) — turn-end and pre-PR flushes always run, so branches still end complete. Every autosave names its trigger in the commit subject (`cezar autosave (periodic)` vs `(turn end)` / `(run finalize)` / `(pre-PR)`), so the flushes you keep are distinguishable from the timer you disabled. |
 | `CEZ_CLAUDE_BIN=/path/to/claude` | Override which `claude` binary is used. |
 | `CEZ_CODEX_BIN=/path/to/codex` | Override which `codex` binary is used. |
 | `CEZ_OPENCODE_BIN=/path/to/opencode` | Override which `opencode` binary is used. |
 | `CEZ_PI_BIN=/path/to/pi` | Override which `pi` binary is used. |
+| `CEZ_OMP_BIN=/path/to/omp` | Override which `omp` (Oh My Pi) binary is used. |
 | `CEZ_CURSOR_BIN=/path/to/agent` | Override the Cursor CLI (`agent`) executable. |
 | `CLAUDE_CONFIG_DIR`, `CODEX_HOME` | The agents' **own** variables, honoured where the vendor documents one. Setting one moves that agent's **default account** — the config folder cezar discovers. A *second* login of the same CLI is deliberately not an environment setting, since one process-wide value cannot differ per project: add it under **Settings → Agent accounts** and pick it per project. |
 | `CEZ_BROWSE_ROOT=~/` | Default root for **Add project → Open local folder…**. The picker cannot navigate above it; a saved workspace value overrides the environment default and must name an existing folder. |
@@ -820,13 +873,13 @@ Useful environment variables:
 | `CEZ_HIDE_COST=1` | Hide backend-reported monetary cost throughout the browser cockpit while leaving raw input/output token counts visible. Only the exact value `1` enables it; telemetry and API payloads are unchanged, and a restart is required after changing it. |
 | `CEZ_HIDE_TOKEN_METRICS=1` | Legacy master switch that hides both token usage and cost. It takes precedence over the two independent flags; only the exact value `1` enables it, payloads are unchanged, and a restart is required. |
 | `GITHUB_TOKEN` | Fallback for GitHub reads/PRs when `gh` isn't authenticated. |
-| `CEZ_ENV_PASSTHROUGH=A,B` | Forward these extra host env vars to spawned agents. By default agents get a least-privilege env (safe shell/toolchain vars + the backend's own auth + `GITHUB_TOKEN` + `CEZ_*`), not your full environment — use this to add a var an agent needs. |
-| `CEZ_AGENT_ENV_FULL=1` | Escape hatch: give spawned agents the full host environment (pre-hardening behavior). Off by default; only set it if you understand that this hands every host secret to the agent process. |
-| `CEZ_AGENT_TMPDIR=0` | Stop giving each task its own temp directory and hand agents the host `TMPDIR` again (pre-#785 behavior). On by default: every run gets `TMPDIR`/`TEMP`/`TMP` pointing at `.ai/cezar/tmp/<task-id>`, created and write-probed before the agent spawns, kept across session close, Continue, and restart while the task is live, and reaped at terminal completion or history deletion (#515) — and kept short enough for unix-socket paths: a checkout so deep that `.ai/cezar/tmp/<task-id>` would cross the kernel's socket-path limit resolves it to a `cez-agent-…` directory under the system temp dir instead (#387), with its location recorded so host temp-environment changes cannot move live scratch. So concurrent tasks stop sharing one directory and a task refuses to start rather than run against a temp directory that silently swallows its shell output (see Troubleshooting below). Only an exact `0` disables it, and it disables the whole thing — the pre-spawn check included, so this stays an escape hatch you can actually take. |
-| `CEZ_REDACT_SECRETS=0` | Disable scrubbing of credential values/token shapes from the on-disk state (the NDJSON transcript and the free-text fields of `runs.json`). On by default; leave it on. Controller-generated delegation tokens are always scrubbed. Best-effort defense-in-depth, not a guarantee: it catches known token shapes and the values of your own secret-named env vars, so a credential in neither category can still get through. |
+| `CEZ_ENV_PASSTHROUGH=A,B` | Forward these extra host env vars to spawned agents. By default agents get a least-privilege env (safe shell/toolchain vars + the backend's own auth + `GITHUB_TOKEN` + `CEZ_*`), not your full environment — use this to add a var an agent needs. A dev server live preview starts gets the same env without the backend's auth and `GITHUB_TOKEN`, plus these names. |
+| `CEZ_AGENT_ENV_FULL=1` | Escape hatch: give spawned agents, and dev servers live preview starts, the full host environment (pre-hardening behavior). Off by default; only set it if you understand that this hands every host secret to the agent process. |
+| `CEZ_AGENT_TMPDIR=0` | Stop giving each task its own temp directory and hand agents the host `TMPDIR` again (pre-open-mercato/cezar#785 behavior). On by default: every run gets `TMPDIR`/`TEMP`/`TMP` pointing at `.ai/cezar/tmp/<task-id>`, created and write-probed before the agent spawns, kept across session close, Continue, and restart while the task is live, and reaped at terminal completion or history deletion (hearsay-tools/cezarion#515) — and kept short enough for unix-socket paths: a checkout so deep that `.ai/cezar/tmp/<task-id>` would cross the kernel's socket-path limit resolves it to a `cez-agent-…` directory under the system temp dir instead (hearsay-tools/cezarion#387), with its location recorded so host temp-environment changes cannot move live scratch. So concurrent tasks stop sharing one directory and a task refuses to start rather than run against a temp directory that silently swallows its shell output (see Troubleshooting below). Only an exact `0` disables it, and it disables the whole thing — the pre-spawn check included, so this stays an escape hatch you can actually take. |
+| `CEZ_REDACT_SECRETS=0` | Disable scrubbing of credential values/token shapes from the on-disk state (the NDJSON transcript and the free-text fields of the run records in `runs.db`). On by default; leave it on. Controller-generated delegation tokens are always scrubbed. Best-effort defense-in-depth, not a guarantee: it catches known token shapes and the values of your own secret-named env vars, so a credential in neither category can still get through. |
 | `CEZ_TITLE_UPDATES=0` | Turn off the live task-title refresh (namer re-runs on each turn end). The Settings → Agents toggle overrides this default. |
 | `CEZ_AUTONAME=0` | Disable ALL LLM task naming (creation + live) — titles stay heuristic (`437: /om-auto-review-pr`). Under `CEZ_DRY_RUN=1` naming is already off unless forced with `CEZ_AUTONAME=1`. |
-| `CEZ_REVIEW_GATE=1` | Turn ON the optional diff-first review gate (#489): a successful, non-autonomous run with changes parks at `review` (Accept / Send back / Draft PR) instead of finishing. Off by default — changed runs settle to `done` with the diff left in the worktree. Only `1` enables. The Settings → Agents toggle overrides this; autonomous runs always skip it. |
+| `CEZ_REVIEW_GATE=1` | Turn ON the optional diff-first review gate (open-mercato/cezar#489): a successful, non-autonomous run with changes parks at `review` (Accept / Send back / Draft PR) instead of finishing. Off by default — changed runs settle to `done` with the diff left in the worktree. Only `1` enables. The Settings → Agents toggle overrides this; autonomous runs always skip it. |
 | `CEZ_NO_BANNER=1` | Skip the `open-mercato/skills` banner on `cez serve` startup. (The cockpit no longer shows a banner — its skills now live on the Skills page's Manage panel — so this env var is the terminal banner's only switch.) |
 | `VITE_CEZ_API_BASE=http://localhost:4321` | **Build time only**, and only when the cockpit bundle is deployed apart from the service it talks to. Empty (the default) means "the origin that served this page", which is right for both normal cases: the CLI serves the bundle itself, and `npm run dev` proxies `/api` to the local service. A deployment that must be configured without a rebuild can put `<meta name="cez-api-base" content="…">` in the served HTML instead, which wins over this. |
 | `VITE_CEZ_E2E=1` | **Build time only.** The cockpit e2e suite sets this when it builds the bundle it drives. It pins `useNow` and every `refetchInterval` so a wait cannot span a 30s tick or a 4s poll. Leave unset for production. |
@@ -851,7 +904,7 @@ df -i "${TMPDIR:-/tmp}"                # a tmpfs can exhaust inodes long before
 Under quota the file is *created* and the write then fails, so the backend reads
 back a zero-byte capture file and hands the agent an empty result.
 
-**Fix.** Since #785 cezar gives each task its own `TMPDIR` under
+**Fix.** Since open-mercato/cezar#785 cezar gives each task its own `TMPDIR` under
 `.ai/cezar/tmp/<task-id>` and write-probes it before spawning, so a broken temp
 directory fails the task with `agent temp directory is not writable: …` on the
 task thread instead of corrupting its work. If you see that error, free space on
@@ -869,7 +922,7 @@ with `TMPDIR=/tmp` set by hand, the same commands succeed. Tools like `tsx` bind
 `<tmpdir>/tsx-<uid>/<pid>.pipe`), and the kernel caps a socket path at 104–108
 bytes — a temp directory near that length leaves no room for the name.
 
-**Fix.** Since #387 cezar keeps each task's temp directory at most 78 bytes. A
+**Fix.** Since hearsay-tools/cezarion#387 cezar keeps each task's temp directory at most 78 bytes. A
 checkout deep enough to push `.ai/cezar/tmp/<task-id>` past that limit gets a
 short `cez-agent-…` directory under the system temp directory instead — still
 per-task, still write-probed before the agent spawns, still reaped when the run
@@ -881,7 +934,7 @@ ends. Checkouts whose path already fits keep the repo-local directory.
 ## Coding agent backends
 
 cezar is not married to one vendor. Every agent step runs through a single
-`AgentRunner` seam with five built-in backends:
+`AgentRunner` seam with six built-in backends:
 
 | Backend | CLI | How cezar drives it | Tool access |
 |---|---|---|---|
@@ -890,14 +943,15 @@ cezar is not married to one vendor. Every agent step runs through a single
 | **OpenCode** _(experimental)_ | [`opencode`](https://opencode.ai) | `opencode serve` — a local HTTP server with an SSE event stream. | Ignores `allowedTools` entirely; every permission is auto-approved. |
 | **Cursor** | [`agent`](https://cursor.com/docs/cli/installation) | Persistent ACP over stdio. | Uses `--force` and approves ACP allow-once requests; Cursor’s native deny rules still apply. Per-run `allowedTools` and `bashAllowlist` are unsupported. |
 | **pi** _(experimental)_ | [`pi`](https://github.com/badlogic/pi-mono) | Persistent `--mode rpc` over JSONL; models are picked with the `provider/model` convention. | Maps `allowedTools` onto pi's `--tools` allowlist; default sessions also pass harness extras (`Subagent`, `SubagentSupervisor`, `SubagentWait`) through `--tools`, and an explicit `allowedTools` still restricts. A configured `bashAllowlist` disables Bash because pi cannot express command-prefix rules. |
+| **OMP** _(experimental)_ | [`omp`](https://github.com/can1357/oh-my-pi) | Persistent `--mode rpc` over JSONL (Oh My Pi, a pi fork); models use the `provider/model` convention and are discovered from `omp models --json`. | Maps `allowedTools` onto OMP's `--tools` allowlist (`[]` becomes `--no-tools`); default sessions also pass `todo`, `lsp`, `ast_edit`, `task` and `wait`. A configured `bashAllowlist` disables `bash` because OMP cannot express command-prefix rules. |
 
-> ⚠️ **OpenCode and pi support are experimental.** Both runners work but are less
+> ⚠️ **OpenCode, pi and OMP support are experimental.** These runners work but are less
 > battle-tested than the Claude Code and Codex backends, and OpenCode auto-approves
 > every permission (it ignores `allowedTools`). Treat them as previews and expect
 > rough edges.
 
 On startup cezar probes which CLIs are installed and the cockpit only offers
-the backends it found — install any one of the five and you're operational.
+the backends it found — install any one of the six and you're operational.
 
 ### Cursor CLI
 
@@ -921,6 +975,19 @@ These select configuration; Cezar does not offer alternate Cursor account profil
 because a complete credential-and-session home override has not been verified.
 
 
+### OMP (Oh My Pi)
+
+Install [OMP](https://github.com/can1357/oh-my-pi) (`curl -fsSL https://omp.sh/install | sh`
+installs a prebuilt binary; Bun is needed only for `--source`) and run `omp login`. Cezar discovers `omp` on PATH;
+`CEZ_OMP_BIN` overrides its location. `omp` is a separate backend from `pi`: a host with
+both binaries keeps both, and `CEZ_PI_BIN` never selects OMP. Select **OMP** in the runner
+picker to use a persistent `--mode rpc` session. A missing CLI leaves the other backends
+available and shows OMP as unavailable. `CEZ_DRY_RUN=1` uses the mock.
+
+Agents ask questions through cezar's `CEZ:ASK` marker, and OMP's own sub-agents appear in the
+Agents drawer. Settings → Agent config exposes OMP's `config.yml`, `mcp.json` and
+`AGENTS.md` files. Named OMP profiles and accounts are not supported yet.
+
 **Pick a backend at three levels** (most specific wins):
 
 1. **Config default** — `"defaultRunner": "codex"` in `.ai/cezar/config.json`.
@@ -1033,9 +1100,11 @@ cez artifact publish /tmp/decision.md
 
 Cezar supplies the bundled command and task context to agent sessions automatically
 (`CEZ_TASK_ID` and `CEZ_ARTIFACTS_DIR`; do not configure these yourself). The command
-returns JSON with a Markdown link for the agent to share. The Files tab also lists
-published artifacts. It previews text, Markdown and raster images; other formats
-can be downloaded. HTML/scripts never execute inside the cockpit, and embedded
+returns JSON with a Markdown link for the agent to share. When the owning project
+is registered, the link keeps that project when copied or opened from another
+project. If ownership cannot be discovered, publication keeps the legacy task link.
+The Files tab also lists published artifacts. It previews text, Markdown and raster
+images; other formats can be downloaded. HTML/scripts never execute inside the cockpit, and embedded
 images in Markdown documents do not load automatically.
 
 Snapshots do not change when the original file changes. They survive worktree
@@ -1064,7 +1133,8 @@ never blocks startup):
   "defaultRunner": "claude", // agent backend: "claude" (default) · "codex" · "opencode" · "pi"
   "modelsLocked": true,      // optional: native per-runner model is fixed/read-only; runner stays selectable
   "plannerModel": "sonnet",  // model the "Plan first" button uses to draft chains
-  "baseBranch": "develop"    // branch worktrees fork from + PRs target (also settable in the Git tab)
+  "baseBranch": "develop",   // branch worktrees fork from + PRs target (also settable in the Git tab)
+  "worktreeSetup": { "commands": ["npm ci"] } // prepare each new worktree before the agent starts (below)
 }
 ```
 
@@ -1075,8 +1145,9 @@ selector uses that runner's discovered model list. While locked, the model is
 shown read-only and follows the selected runner's native settings; the runner
 itself remains selectable.
 
-Run data (`runs.json`, NDJSON event logs, worktrees, `todos.json`) is
-git-ignored automatically; your workflows and skills stay committable.
+Run data (`runs.db` and its `-wal`/`-shm` files, the `runs.json.pre-sqlite*.bak`
+backups, NDJSON event logs, worktrees, `todos.json`) is git-ignored
+automatically; your workflows and skills stay committable.
 
 Settings that belong to *you* rather than to a repo — the parallel cap
 (`maxParallel`, default **2**), the per-task memory ceiling and the checkout
@@ -1086,6 +1157,56 @@ root — live once in `~/.cezar/config.json`, alongside the
 in a repo's `.ai/cezar/config.json` is imported into the workspace file the
 first time cezar boots there, and ignored afterwards.
 
+### Preparing new worktrees
+
+Every task and worker runs in a fresh worktree, and a fresh worktree has nothing installed. Give
+the project a `worktreeSetup` and cezar runs those commands in each new worktree before the
+agent's first turn, so the agent (and anything that runs beside it, such as a test watcher)
+starts in a ready tree:
+
+```jsonc
+// .ai/cezar/config.json
+"worktreeSetup": {
+  "commands": ["npm ci", "cp \"$CEZ_PROJECT_ROOT/.env\" .env"],
+  "timeoutSeconds": 900 // optional, per command; default 900, max 7200
+}
+```
+
+Or edit it in **Settings → Worktrees → Prepare new worktrees**, one command per line. Only a
+cockpit on the machine running cezar can change it: a hosted cockpit (`CEZ_REMOTE=1`) shows it
+read-only, because these are commands the host runs.
+
+- **When it runs.** In every new task worktree and every worker worktree, and again when Continue
+  rebuilds a worktree that retention reclaimed. Never for a task that runs in the repo working
+  tree (worktree off), and never for a non-git directory.
+- **How it runs.** Each command runs as `bash -lc '<command>'` in the worktree root, in order,
+  and the setup stops at the first command that fails or times out. Up to 20 commands.
+- **What it can see.** The same curated environment the live preview gives a dev server: your
+  `PATH`, `HOME` and the shell basics, but no agent API keys and no GitHub token. A private
+  registry token reaches it through `CEZ_ENV_PASSTHROUGH=NPM_TOKEN` (or the tool's own config
+  file under `HOME`). It also gets `CEZ_PROJECT_ROOT` (the main checkout, for copying untracked
+  files like `.env`) and `CEZ_TASK_ID`.
+- **What you see.** The task thread shows a "Ran `<command>`" card per command with its output
+  (the last 20 KB) and a line with the outcome and duration, which also goes into the handoff
+  file.
+- **What the agent sees.** Its first message says what ran, so it doesn't repeat the install.
+  If a command fails or times out, the agent still starts and its first message names the
+  command, the exit code and the end of the output, so it can fix the cause or work around it.
+- **Keep generated files gitignored.** Autosave commits whatever Git doesn't ignore, so anything
+  setup creates outside `.gitignore` becomes part of the task's changes. `node_modules/` and
+  `.venv/` are usually ignored already.
+
+Without the key nothing runs, exactly as before. Examples:
+
+| Project | `commands` |
+| --- | --- |
+| npm | `["npm ci"]` |
+| pnpm | `["pnpm install --frozen-lockfile"]` |
+| Python (uv) | `["uv sync --frozen"]` |
+| Go | `["go mod download"]` |
+| Rust | `["cargo fetch"]` |
+| Copy local env | `["cp \"$CEZ_PROJECT_ROOT/.env\" .env"]` |
+
 ### Editing the agents' own config (Settings → Agent config)
 
 cezar picks *which* agent runs; **Settings → Agent config** lets you edit *how* it
@@ -1106,7 +1227,7 @@ hosted cockpit (`CEZ_REMOTE=1`) is read-only and never serves home-file contents
 End-to-end, from a fresh clone to a global `cez` command you can run in **any**
 repo on your machine — no npm publish required.
 
-**1. Prerequisites** — Node 20+ and `git` (plus at least one logged-in agent CLI,
+**1. Prerequisites** — Node 24.15+ and `git` (plus at least one logged-in agent CLI,
 as in [Quick start](#quick-start)).
 
 **2. Clone & install**

package/dist/agent-config/catalog.d.ts

@@ -11,9 +11,11 @@ import type { RunnerId } from '../core/agent-runner.ts';
  * A raw editor cannot drift on a vendor's *schema*; it can drift on *paths and
  * precedence strings*, so every entry carries a `docsUrl` and this table is the
  * single maintenance surface. Facts verified against primary docs 2026-07-16;
- * the Pi entries against Pi's README and docs/settings.md on 2026-09-15 (#322).
+ * the Pi entries against Pi's README and docs/settings.md on 2026-09-15 (#322);
+ * the OMP entries against OMP's docs/config-usage.md and docs/mcp-config.md at
+ * main @ 7318a70cf4ed on 2026-10-05 (#595).
  */
-export type ConfigFormat = 'json' | 'jsonc' | 'toml' | 'markdown';
+export type ConfigFormat = 'json' | 'jsonc' | 'toml' | 'yaml' | 'markdown';
 export type ConfigScope = 'user' | 'project' | 'local';
 /** `settings` = behavior knobs; `memory` = instruction/markdown; `mcp` = a dedicated MCP file. */
 export type ConfigKind = 'settings' | 'memory' | 'mcp';
@@ -34,6 +36,8 @@ export interface AgentHomePaths {
     pi: string;
     /** Cursor CLI configuration directory; not an account home. */
     cursor: string;
+    /** `$PI_CODING_AGENT_DIR` or `~/${PI_CONFIG_DIR || '.omp'}/agent` — OMP's default profile. */
+    omp: string;
 }
 export interface ConfigFileDef {
     /** Stable, opaque, URL-safe. The ONLY thing a client may name (traversal-proof). */

package/dist/agent-config/catalog.js

@@ -8,6 +8,8 @@ const OPENCODE_CONFIG_DOCS = 'https://opencode.ai/docs/config/';
 const OPENCODE_RULES_DOCS = 'https://opencode.ai/docs/rules/';
 const PI_SETTINGS_DOCS = 'https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/settings.md';
 const PI_CONTEXT_FILES_DOCS = 'https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md#context-files';
+const OMP_CONFIG_DOCS = 'https://github.com/can1357/oh-my-pi/blob/main/docs/config-usage.md';
+const OMP_MCP_DOCS = 'https://github.com/can1357/oh-my-pi/blob/main/docs/mcp-config.md';
 /**
  * The table. Order is presentation order: per runner, then user → project →
  * local so each scope ladder reads top (broad) to bottom (specific).
@@ -245,6 +247,79 @@ export const CONFIG_FILES = [
         precedence: 'Global context file, loaded first. Every AGENTS.md (or CLAUDE.md) from the parent directories down to the current one is concatenated after it; an AGENTS.override.md replaces that directory’s file only.',
         docsUrl: PI_CONTEXT_FILES_DOCS,
     },
+    // ---- OMP: verified 2026-10-02 against v18.4.11 ----
+    // Oh My Pi (`can1357/oh-my-pi`, docs at main @ 7318a70cf4ed). The user layer lives in
+    // `AgentHomePaths.omp` (`$PI_CODING_AGENT_DIR` or `~/${PI_CONFIG_DIR || '.omp'}/agent`, the default
+    // profile; a named profile relocates it and is not modelled). Project files always live in
+    // `<repo>/.omp/`. Settings are YAML (`config.yml`); no `modelKey`, because OMP has no native-default
+    // strategy cezar reads (spec § Model selection). Precedence strings quote the docs in doc order;
+    // a numbered doc list is joined with "; ", its wording untouched. Not listed, by the spec's
+    // scope: `.omp/AGENTS.md` (OMP's native project context file; project memory is the shared root
+    // `AGENTS.md` row) and the `.omp/.mcp.json` / user `.mcp.json` compatibility spellings.
+    {
+        id: 'omp.user.settings',
+        runners: ['omp'],
+        kind: 'settings',
+        scope: 'user',
+        resolve: (_repo, home) => join(home.omp, 'config.yml'),
+        label: '~/.omp/agent/config.yml',
+        format: 'yaml',
+        tracked: 'outside-repo',
+        precedence: 
+        // config-usage.md § Layers, the six-tier list.
+        'Effective precedence, highest first: 1. Environment variable declared on the definition (`env: "NAME"`), parsed by the setting\'s type; unparseable text counts as unset. Booleans follow `parseFlag`: empty is unset, `1`/`y`/`true`/`yes`/`on` (lower or upper case) is true, any other text is false; 2. Runtime overrides: in-memory, non-persistent; 3. Config overlays: `PI_CONFIG_FILES` (platform path-list), followed by repeated `omp --config <path>` files; all are loaded as `config.yml`-style YAML for this process only; 4. Project settings: discovered via the settings capability (`settings.json` and `config.yml` from providers); 5. Global settings: the first present file among `~/.omp/agent/config.yml` and `config.yaml`; 6. Definition default',
+        docsUrl: OMP_CONFIG_DOCS,
+    },
+    {
+        id: 'omp.project.settings',
+        runners: ['omp'],
+        kind: 'settings',
+        scope: 'project',
+        resolve: (repo) => join(repo, '.omp', 'config.yml'),
+        label: '.omp/config.yml',
+        format: 'yaml',
+        tracked: 'tracked',
+        precedence: 'Project settings: discovered via the settings capability (`settings.json` and `config.yml` from providers). Within the native provider, project `config.yml` follows and overrides `settings.json`. Runs read the committed copy.',
+        docsUrl: OMP_CONFIG_DOCS,
+    },
+    {
+        id: 'omp.user.mcp',
+        runners: ['omp'],
+        kind: 'mcp',
+        scope: 'user',
+        resolve: (_repo, home) => join(home.omp, 'mcp.json'),
+        label: '~/.omp/agent/mcp.json',
+        format: 'json',
+        tracked: 'outside-repo',
+        holdsMcp: true,
+        precedence: 'Across providers, the first definition wins. Duplicate names are not merged; OpenCode\'s internal config layers are the exception described above. Within OMP native config, project `.omp/mcp.json` precedes `.omp/.mcp.json`, then the active profile\'s user `mcp.json` and `.mcp.json`.',
+        docsUrl: OMP_MCP_DOCS,
+    },
+    {
+        id: 'omp.project.mcp',
+        runners: ['omp'],
+        kind: 'mcp',
+        scope: 'project',
+        resolve: (repo) => join(repo, '.omp', 'mcp.json'),
+        label: '.omp/mcp.json',
+        format: 'json',
+        tracked: 'tracked',
+        holdsMcp: true,
+        precedence: 'Across providers, the first definition wins. Duplicate names are not merged; OpenCode\'s internal config layers are the exception described above. Within OMP native config, project `.omp/mcp.json` precedes `.omp/.mcp.json`, then the active profile\'s user `mcp.json` and `.mcp.json`. Runs read the committed copy.',
+        docsUrl: OMP_MCP_DOCS,
+    },
+    {
+        id: 'omp.user.memory',
+        runners: ['omp'],
+        kind: 'memory',
+        scope: 'user',
+        resolve: (_repo, home) => join(home.omp, 'AGENTS.md'),
+        label: '~/.omp/agent/AGENTS.md',
+        format: 'markdown',
+        tracked: 'outside-repo',
+        precedence: '`SYSTEM.md`, `SYSTEM_TEMPLATE.md`, `RULES.md`, and `.omp/AGENTS.md` read user-level files directly and use the nearest non-empty ancestor `.omp` directory for project files. Context files: `.omp/AGENTS.md`; standalone ancestor `AGENTS.md` files are loaded separately by the low-priority `agents-md` provider',
+        docsUrl: OMP_CONFIG_DOCS,
+    },
     // ---- Cursor — verified against vendor docs 2026-09-16 ----
     {
         id: 'cursor.user.settings',
@@ -283,17 +358,17 @@ export const CONFIG_FILES = [
         precedence: 'MCP in the CLI uses the same configuration as the editor.',
         docsUrl: 'https://cursor.com/docs/cli/mcp',
     },
-    // ---- Shared: <repo>/AGENTS.md is read by Codex, OpenCode AND Pi ----
+    // ---- Shared: <repo>/AGENTS.md is read by Codex, OpenCode, Pi, Cursor AND OMP ----
     {
         id: 'project.agents',
-        runners: ['codex', 'opencode', 'pi', 'cursor'],
+        runners: ['codex', 'opencode', 'pi', 'cursor', 'omp'],
         kind: 'memory',
         scope: 'project',
         resolve: (repo) => join(repo, 'AGENTS.md'),
         label: 'AGENTS.md',
         format: 'markdown',
         tracked: 'tracked',
-        precedence: 'Read by Codex, OpenCode, Pi and Cursor (Claude ignores it). Codex concatenates it root-down; OpenCode uses the first match and prefers it over CLAUDE.md; Pi concatenates every AGENTS.md (or CLAUDE.md) from the parent directories down, after its global file. Runs read the committed copy.',
+        precedence: 'Read by Codex, OpenCode, Pi, Cursor and OMP (Claude ignores it). Codex concatenates it root-down; OpenCode uses the first match and prefers it over CLAUDE.md; Pi concatenates every AGENTS.md (or CLAUDE.md) from the parent directories down, after its global file; OMP loads standalone ancestor AGENTS.md files through its low-priority `agents-md` provider. Runs read the committed copy.',
         docsUrl: OPENCODE_RULES_DOCS,
     },
 ];