@open-mercato/cezar 0.8.0 → 0.9.0-pr470.650

package/README.md

@@ -5,8 +5,8 @@
 **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 or OpenCode,
-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 or OpenCode
+(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.
 
@@ -21,7 +21,7 @@ your phone, working your backlog while you're away.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)
 ![Node 20+](https://img.shields.io/badge/Node-20%2B-339933)
-![TypeScript 5.x](https://img.shields.io/badge/TypeScript-5.x-3178c6)
+![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)
 
@@ -106,7 +106,7 @@ and an orchestrator keeps a whole queue of them moving.
   Take it over interactively in one click (`claude --resume <id>`), or continue it
   in-process from the cockpit.
 - 🔀 **Locked into one agent vendor.** Most tools wed you to a single CLI. cezar
-  drives **Claude Code, Codex and OpenCode** through one runner seam — set a
+  drives **Claude Code, Codex and OpenCode (experimental)** through one runner seam — set a
   default, pick a backend per task, or mix them inside one workflow (implement
   with one agent, review with another) — and through **OpenCode** you can point
   a run at **open-source or local models**, not just the big vendors. See
@@ -251,7 +251,8 @@ Three words, no jargon — **task**, **skill**, **chain**:
 Five moves that make the cockpit worth the browser tab:
 
 - 🗃️ **Queue + orchestration.** Start as many tasks as you like: cezar runs up to
-  `maxParallel` at once (default **2**; a non-git directory always runs one) and
+  `maxParallel` at once across every project (default **2**; a non-git directory
+  always runs one) and
   holds the rest in a FIFO queue with visible positions (`#1`, `#2`, …). Cancel a
   queued task before it starts; the queue even survives a cockpit restart —
   everything still `queued` is re-enqueued in order. It's the orchestration layer
@@ -303,6 +304,71 @@ a GitHub page.
 
 ---
 
+## Multiple projects, one cockpit
+
+One `cezar serve` hosts **every repo you work in**, not just the one you started
+it in. Each repo cezar boots in registers itself in a per-user registry at
+`~/.cezar/config.json` — the workspace file that also holds the global knobs
+(the parallel cap, the memory ceiling, the browse root, and the checkout root). Nothing is added to
+the repo: per-project state stays exactly where it was, in that repo's
+`.ai/cezar/`.
+
+Every view is project-scoped:
+
+```
+/p/<projectId>/            tasks · git · github · skills · workflows · settings
+```
+
+`<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 sidebar shows one collapsible group per project — each with its own nav
+and task list — and the new-task composer names the project it will run in.
+
+**Adding a project** — the **+** button beside *New task*:
+
+- 📂 **Open local folder…** browses from the configured browse root
+  (**Settings → Projects**, default `~/`) in a folder picker and
+  registers the folder you pick.
+- ⬇️ **Clone from GitHub…** clones with your logged-in `gh` into the checkout
+  root (**Settings → Projects**, default `~/cezar/projects`) with live progress,
+  then registers the clone. Close the dialog and the clone is killed and its
+  partial directory removed.
+
+Removing a project (**Settings → Projects**) drops the registry entry only — the
+repo and its `.ai/cezar/` are never touched, so re-adding it later finds all its
+tasks intact. The project cezar is currently serving can't be removed: it
+re-registers itself at the next start.
+
+**From the terminal** — the same registry, no cockpit required (handy over ssh):
+
+```bash
+cezar projects                    # list: id, branch or status, path
+cezar projects add ~/code/api     # register a folder (defaults to the current repo)
+cezar projects remove api         # drop the registry entry; the repo is untouched
+```
+
+These read and write `~/.cezar/config.json` directly, so they work with the
+server stopped, and `CEZ_HOME` selects which workspace they operate on.
+
+Settings split along the same line: **Agents**, **Worktrees**, **Bookmarklets**,
+**Prompt templates** and **MCP** describe one repo and live under
+`/p/<projectId>/settings`; **Appearance**, **Notifications**, **Resources**,
+**Projects** and **Keyboard** are yours or the machine's and live at
+`/settings/global`.
+
+**Old URLs keep working.** Every unprefixed path — `/`, `/tasks/<id>`,
+`/settings`, and the whole `/api/…` surface — still answers exactly as before,
+bound to the project cezar was started in; the cockpit redirects flat paths to
+their `/p/<boot>/…` twin. Existing bookmarks, bookmarklets and scripts need no
+change.
+
+> **Hosted cockpit?** The folder picker is confined to the independent browse
+> root. Set `CEZ_BROWSE_ROOT` narrowly before first boot (or save it in
+> **Settings → Projects**) when a remote viewer should not enumerate the host's
+> whole home. Clones continue to use the separate checkout root.
+
+---
+
 ## Workflow format
 
 A workflow is a small YAML file in `.ai/cezar/workflows/`:
@@ -316,7 +382,7 @@ steps:
     prompt: "{{task}}"
     skill: project-conventions   # optional — from .ai/skills or .ai/cezar/skills
     # model: opus                # optional per-step model override
-    # runner: codex              # optional per-step backend: claude · codex · opencode
+    # runner: codex              # optional per-step backend: claude · codex · opencode · pi
     # allowedTools: [Read, Edit, Write, Grep, Glob, Bash]
   - id: verify
     name: Verify
@@ -362,10 +428,13 @@ Useful environment variables:
 | `CEZ_DRY_RUN=1` | Use the bundled mock instead of the real `claude` CLI — the entire cockpit works offline, for demos and development. |
 | `CEZ_APPROVAL_GATE=1` | Opt into Claude's interactive approval UI; by default, unapproved tools are denied without interrupting the run. |
 | `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_AUTOSAVE=1` | Re-enable the periodic (90 s) `cezar autosave` commit in task worktrees. Off by default (#471) — turn-end and pre-PR flushes always run, so branches still end complete. |
+| `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_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_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. |
+| `CEZ_PROJECTS_DIR=~/cezar/projects` | Default destination for **Clone from GitHub**. Saved workspace settings override it, and missing directories are created recursively. |
 | `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. |
@@ -373,23 +442,29 @@ Useful environment variables:
 | `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_NO_BANNER=1` | Skip the `open-mercato/skills` banner on `cezar serve` startup. Dismissing the same banner in the cockpit silences the terminal one too. |
+| `CEZ_NO_BANNER=1` | Skip the `open-mercato/skills` banner on `cezar 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.) |
 
 ---
 
 ## Coding agent backends
 
 cezar is not married to one vendor. Every agent step runs through a single
-`AgentRunner` seam with three built-in backends:
+`AgentRunner` seam with four built-in backends:
 
 | Backend | CLI | How cezar drives it | Tool access |
 |---|---|---|---|
 | **Claude Code** (default) | [`claude`](https://github.com/anthropics/claude-code) | Headless `stream-json` mode. | Per-tool `--allowedTools` (`bashAllowlist` scopes `Bash`); `dontAsk` denies unapproved tools without prompting (`CEZ_APPROVAL_GATE=1` → `acceptEdits` + approval UI). |
-| **Codex** | [`codex`](https://github.com/openai/codex) | `codex app-server` — JSON-RPC over stdio, the same transport the Codex IDE extensions use. | Ignores `allowedTools`; runs its own `workspace-write` sandbox with `approvalPolicy: never` and network access on. |
-| **OpenCode** | [`opencode`](https://opencode.ai) | `opencode serve` — a local HTTP server with an SSE event stream. | Ignores `allowedTools` entirely; every permission is auto-approved. |
+| **Codex** | [`codex`](https://github.com/openai/codex) | `codex app-server` — JSON-RPC over stdio, the same transport the Codex IDE extensions use. | Ignores `allowedTools`; the default auto mode uses `danger-full-access` with `approvalPolicy: never` (`CEZ_CODEX_NETWORK=0` opts into the network-blocked `workspace-write` sandbox). |
+| **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. |
+| **pi** _(experimental)_ | `pi` | Headless Claude-compatible `stream-json`; models are picked with the `provider/model` convention. | Same as Claude Code — the runner delegates to the Claude CLI driver, so per-tool `--allowedTools` applies and unapproved tools are denied. |
+
+> ⚠️ **OpenCode and pi support are experimental.** Both 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 three and you're operational.
+the backends it found — install any one of the four and you're operational.
 
 **Pick a backend at three levels** (most specific wins):
 
@@ -473,9 +548,8 @@ never blocks startup):
   // path as `./name`, not a bare `name`. Pin `ref` to a full commit SHA to freeze
   // the source against a moving branch head — cezar verifies it resolves to
   // exactly that commit, and reports it as `team.commit`.
-  "maxParallel": 2,          // how many tasks may run at once (non-git dirs always run 1)
   "worktreeRetention": 10,   // keep the last N finished worktrees on disk; 0 = unlimited (branch always kept)
-  "defaultRunner": "claude", // agent backend: "claude" (default) · "codex" · "opencode"
+  "defaultRunner": "claude", // agent backend: "claude" (default) · "codex" · "opencode" · "pi"
   "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)
 }
@@ -484,6 +558,27 @@ never blocks startup):
 Run data (`runs.json`, 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
+root — live once in `~/.cezar/config.json`, alongside the
+[project registry](#multiple-projects-one-cockpit), and are edited from
+**Settings → Resources** and **Settings → Projects**. A `maxParallel` left over
+in a repo's `.ai/cezar/config.json` is imported into the workspace file the
+first time cezar boots there, and ignored afterwards.
+
+### Editing the agents' own config (Settings → Agent config)
+
+cezar picks *which* agent runs; **Settings → Agent config** lets you edit *how* it
+behaves — the raw config files Claude, Codex and OpenCode read for settings,
+MCP, and memory. In the multi-project cockpit the section is project-scoped:
+repo-relative files resolve from the selected project's root, while user-scope
+files continue to resolve from the agent's home.
+
+Each file keeps its native format and vendor-documented precedence. Tracked
+files reach task worktrees after commit; Claude's gitignored personal layer is
+seeded into each run's worktree. Editing is a local-machine capability, so a
+hosted cockpit (`CEZ_REMOTE=1`) is read-only and never serves home-file contents.
+
 ---
 
 ## Local development

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

@@ -0,0 +1,64 @@
+import type { RunnerId } from '../core/agent-runner.js';
+/**
+ * The catalog of coding-agent config files cezar can surface and edit (spec
+ * `.ai/specs/2026-07-16-agent-config-files.md`). This file is the ONLY place
+ * vendor knowledge lives: where each agent keeps its files, at which scope, in
+ * what format, and — the load-bearing part — the vendor's OWN documented
+ * precedence, quoted so a UI label never claims a merge cezar does not perform.
+ *
+ * Hardcoding is the design. cezar's value here is knowing where the files are
+ * and what the docs say; an unknown file is not shown rather than guessed at.
+ * 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.
+ */
+export type ConfigFormat = 'json' | 'jsonc' | 'toml' | 'markdown';
+export type ConfigScope = 'user' | 'project' | 'local';
+/** `settings` = behavior knobs; `memory` = instruction/markdown; `mcp` = a dedicated MCP file. */
+export type ConfigKind = 'settings' | 'memory' | 'mcp';
+/**
+ * Git status *by convention* — it drives the honest label, it is not read from
+ * git. The seed path re-checks with `git check-ignore` before trusting it.
+ */
+export type ConfigTracked = 'tracked' | 'gitignored' | 'outside-repo';
+/** Resolved home directories per agent, injected so the catalog stays pure and testable. */
+export interface AgentHomePaths {
+    /** `~/.claude` */
+    claude: string;
+    /** `$CODEX_HOME` or `~/.codex` */
+    codex: string;
+    /** `$XDG_CONFIG_HOME/opencode` or `~/.config/opencode` */
+    opencodeConfig: string;
+}
+export interface ConfigFileDef {
+    /** Stable, opaque, URL-safe. The ONLY thing a client may name (traversal-proof). */
+    id: string;
+    /** Every runner that reads this file. `<repo>/AGENTS.md` is one file, two readers. */
+    runners: RunnerId[];
+    kind: ConfigKind;
+    scope: ConfigScope;
+    /** Absolute path, resolved per request so `$CODEX_HOME`/`$XDG_CONFIG_HOME` are honoured. */
+    resolve: (repoRoot: string, home: AgentHomePaths) => string;
+    /** What the user sees, e.g. `~/.claude/settings.json`, `.claude/settings.local.json`. */
+    label: string;
+    format: ConfigFormat;
+    tracked: ConfigTracked;
+    /** True only for Claude's gitignored personal layer — the files seeded into a run's worktree. */
+    seeded?: boolean;
+    /** True when this file holds MCP server definitions (drives the MCP section's filter). */
+    holdsMcp?: boolean;
+    /** VERBATIM from the vendor docs. Never computed, never generic. */
+    precedence: string;
+    /** Documented mid-run reload behaviour, or undefined when the vendor is silent. */
+    hotReload?: string;
+    docsUrl: string;
+}
+/**
+ * The table. Order is presentation order: per runner, then user → project →
+ * local so each scope ladder reads top (broad) to bottom (specific).
+ */
+export declare const CONFIG_FILES: ConfigFileDef[];
+/** The whole catalog. */
+export declare function listConfigFiles(): ConfigFileDef[];
+/** Look up one entry by its stable id, or undefined when the id is unknown. */
+export declare function findConfigFile(id: string): ConfigFileDef | undefined;

package/dist/agent-config/catalog.js

@@ -0,0 +1,205 @@
+import { join } from 'node:path';
+const CLAUDE_SETTINGS_DOCS = 'https://code.claude.com/docs/en/settings';
+const CLAUDE_MEMORY_DOCS = 'https://code.claude.com/docs/en/memory';
+const CLAUDE_MCP_DOCS = 'https://code.claude.com/docs/en/mcp';
+const CODEX_CONFIG_DOCS = 'https://developers.openai.com/codex/config-reference';
+const CODEX_AGENTS_DOCS = 'https://developers.openai.com/codex/guides/agents-md';
+const OPENCODE_CONFIG_DOCS = 'https://opencode.ai/docs/config/';
+const OPENCODE_RULES_DOCS = 'https://opencode.ai/docs/rules/';
+/**
+ * The table. Order is presentation order: per runner, then user → project →
+ * local so each scope ladder reads top (broad) to bottom (specific).
+ */
+export const CONFIG_FILES = [
+    // ---- Claude Code ----
+    {
+        id: 'claude.user.settings',
+        runners: ['claude'],
+        kind: 'settings',
+        scope: 'user',
+        resolve: (_repo, home) => join(home.claude, 'settings.json'),
+        label: '~/.claude/settings.json',
+        format: 'json',
+        tracked: 'outside-repo',
+        precedence: 'Lowest priority. Project and local settings override it key by key — except permission rules, which merge across all scopes.',
+        hotReload: 'Edits to most keys — including permissions and hooks — apply to a running session without a restart.',
+        docsUrl: CLAUDE_SETTINGS_DOCS,
+    },
+    {
+        id: 'claude.project.settings',
+        runners: ['claude'],
+        kind: 'settings',
+        scope: 'project',
+        resolve: (repo) => join(repo, '.claude', 'settings.json'),
+        label: '.claude/settings.json',
+        format: 'json',
+        tracked: 'tracked',
+        precedence: 'Overrides user settings key by key (permission rules merge). Local settings override this.',
+        hotReload: 'Edits to most keys — including permissions and hooks — apply to a running session without a restart.',
+        docsUrl: CLAUDE_SETTINGS_DOCS,
+    },
+    {
+        id: 'claude.local.settings',
+        runners: ['claude'],
+        kind: 'settings',
+        scope: 'local',
+        resolve: (repo) => join(repo, '.claude', 'settings.local.json'),
+        label: '.claude/settings.local.json',
+        format: 'json',
+        tracked: 'gitignored',
+        seeded: true,
+        precedence: 'Highest of the file scopes — overrides project and user (permission rules merge). Git-ignored; copied into each run’s worktree so it takes effect immediately.',
+        hotReload: 'Edits to most keys — including permissions and hooks — apply to a running session without a restart.',
+        docsUrl: CLAUDE_SETTINGS_DOCS,
+    },
+    {
+        id: 'claude.project.mcp',
+        runners: ['claude'],
+        kind: 'mcp',
+        scope: 'project',
+        resolve: (repo) => join(repo, '.mcp.json'),
+        label: '.mcp.json',
+        format: 'json',
+        tracked: 'tracked',
+        holdsMcp: true,
+        precedence: 'Project-scoped MCP servers (key: mcpServers), shared via version control. Each requires approval before use; user- and local-scoped servers live in ~/.claude.json, which cezar does not edit.',
+        docsUrl: CLAUDE_MCP_DOCS,
+    },
+    {
+        id: 'claude.user.memory',
+        runners: ['claude'],
+        kind: 'memory',
+        scope: 'user',
+        resolve: (_repo, home) => join(home.claude, 'CLAUDE.md'),
+        label: '~/.claude/CLAUDE.md',
+        format: 'markdown',
+        tracked: 'outside-repo',
+        precedence: 'Not overridden — every CLAUDE.md that loads is concatenated, this user file first.',
+        docsUrl: CLAUDE_MEMORY_DOCS,
+    },
+    {
+        id: 'claude.project.memory',
+        runners: ['claude'],
+        kind: 'memory',
+        scope: 'project',
+        resolve: (repo) => join(repo, 'CLAUDE.md'),
+        label: 'CLAUDE.md',
+        format: 'markdown',
+        tracked: 'tracked',
+        precedence: 'Concatenated after the user file, not replacing it. Claude does not read AGENTS.md — import it here with @AGENTS.md. Runs read the committed copy.',
+        docsUrl: CLAUDE_MEMORY_DOCS,
+    },
+    {
+        id: 'claude.local.memory',
+        runners: ['claude'],
+        kind: 'memory',
+        scope: 'local',
+        resolve: (repo) => join(repo, 'CLAUDE.local.md'),
+        label: 'CLAUDE.local.md',
+        format: 'markdown',
+        tracked: 'gitignored',
+        seeded: true,
+        precedence: 'Loads alongside CLAUDE.md, concatenated last. Git-ignored; copied into each run’s worktree so it takes effect immediately.',
+        docsUrl: CLAUDE_MEMORY_DOCS,
+    },
+    // ---- Codex ----
+    {
+        id: 'codex.user.config',
+        runners: ['codex'],
+        kind: 'settings',
+        scope: 'user',
+        resolve: (_repo, home) => join(home.codex, 'config.toml'),
+        label: '~/.codex/config.toml',
+        format: 'toml',
+        tracked: 'outside-repo',
+        holdsMcp: true,
+        precedence: 'User-level defaults. A trusted project’s .codex/config.toml overrides these; some keys (provider, auth, telemetry) cannot be overridden at project scope. MCP servers live here under [mcp_servers.<id>].',
+        docsUrl: CODEX_CONFIG_DOCS,
+    },
+    {
+        id: 'codex.project.config',
+        runners: ['codex'],
+        kind: 'settings',
+        scope: 'project',
+        resolve: (repo) => join(repo, '.codex', 'config.toml'),
+        label: '.codex/config.toml',
+        format: 'toml',
+        tracked: 'tracked',
+        holdsMcp: true,
+        precedence: 'Applies only in projects you have trusted. Some keys (provider, auth, telemetry) cannot be overridden here. MCP servers go under [mcp_servers.<id>]. Runs read the committed copy.',
+        docsUrl: CODEX_CONFIG_DOCS,
+    },
+    {
+        id: 'codex.user.memory',
+        runners: ['codex'],
+        kind: 'memory',
+        scope: 'user',
+        resolve: (_repo, home) => join(home.codex, 'AGENTS.md'),
+        label: '~/.codex/AGENTS.md',
+        format: 'markdown',
+        tracked: 'outside-repo',
+        precedence: 'Global instructions, read first (an AGENTS.override.md beside it wins if present). Project AGENTS.md files are concatenated after and override it.',
+        docsUrl: CODEX_AGENTS_DOCS,
+    },
+    // ---- OpenCode ----
+    {
+        id: 'opencode.user.config',
+        runners: ['opencode'],
+        kind: 'settings',
+        scope: 'user',
+        resolve: (_repo, home) => join(home.opencodeConfig, 'opencode.json'),
+        label: '~/.config/opencode/opencode.json',
+        format: 'jsonc',
+        tracked: 'outside-repo',
+        holdsMcp: true,
+        precedence: 'Global config. Merged with the project config, not replaced — later configs override earlier ones only for conflicting keys. MCP servers live under the "mcp" key.',
+        docsUrl: OPENCODE_CONFIG_DOCS,
+    },
+    {
+        id: 'opencode.project.config',
+        runners: ['opencode'],
+        kind: 'settings',
+        scope: 'project',
+        resolve: (repo) => join(repo, 'opencode.json'),
+        label: 'opencode.json',
+        format: 'jsonc',
+        tracked: 'tracked',
+        holdsMcp: true,
+        precedence: 'Merged over the global config per conflicting key (not a wholesale replace). MCP servers live under the "mcp" key. Runs read the committed copy.',
+        docsUrl: OPENCODE_CONFIG_DOCS,
+    },
+    {
+        id: 'opencode.user.memory',
+        runners: ['opencode'],
+        kind: 'memory',
+        scope: 'user',
+        resolve: (_repo, home) => join(home.opencodeConfig, 'AGENTS.md'),
+        label: '~/.config/opencode/AGENTS.md',
+        format: 'markdown',
+        tracked: 'outside-repo',
+        precedence: 'Global rules. First match wins across scopes: if a project AGENTS.md exists, this global file is not read at all.',
+        docsUrl: OPENCODE_RULES_DOCS,
+    },
+    // ---- Shared: <repo>/AGENTS.md is read by BOTH Codex and OpenCode ----
+    {
+        id: 'project.agents',
+        runners: ['codex', 'opencode'],
+        kind: 'memory',
+        scope: 'project',
+        resolve: (repo) => join(repo, 'AGENTS.md'),
+        label: 'AGENTS.md',
+        format: 'markdown',
+        tracked: 'tracked',
+        precedence: 'Read by Codex and OpenCode (Claude ignores it). Codex concatenates it root-down; OpenCode uses the first match and prefers it over CLAUDE.md. Runs read the committed copy.',
+        docsUrl: OPENCODE_RULES_DOCS,
+    },
+];
+/** The whole catalog. */
+export function listConfigFiles() {
+    return CONFIG_FILES;
+}
+/** Look up one entry by its stable id, or undefined when the id is unknown. */
+export function findConfigFile(id) {
+    return CONFIG_FILES.find((f) => f.id === id);
+}
+//# sourceMappingURL=catalog.js.map

package/dist/agent-config/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/agent-config/catalog.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,46 @@
+import { type ConfigFileDef } from './catalog.js';
+/**
+ * Read and write the coding agents' own config files, addressed by catalog id
+ * (never by a client-supplied path, so traversal is impossible by
+ * construction). Every function degrades — a missing file is "absent", an
+ * unreadable one is an honest error — and none throw. Writes validate first,
+ * refuse a stale overwrite via a content hash, write atomically through
+ * symlinks, and never touch a byte the user did not type.
+ */
+/** sha256 of the exact file bytes. mtime is coarse and lies across filesystems. */
+declare function hashBytes(content: string): string;
+export interface ReadResult {
+    id: string;
+    path: string;
+    exists: boolean;
+    content: string;
+    /** sha256 of the bytes, or null when the file does not exist. */
+    version: string | null;
+}
+export type WriteOutcome = {
+    ok: true;
+    read: ReadResult;
+} | {
+    ok: false;
+    status: 400 | 409 | 500;
+    error: string;
+};
+declare function resolvePath(def: ConfigFileDef, repoRoot: string, env: NodeJS.ProcessEnv): string;
+/** Read a config file by id. Unknown id → null; absent file → exists:false; unreadable → thrown-free error string via `error`. */
+export declare function readConfigFile(id: string, repoRoot: string, env?: NodeJS.ProcessEnv): Promise<ReadResult | {
+    error: string;
+} | null>;
+/**
+ * Write a config file by id. Validates the content against the file's format,
+ * refuses when `version` does not match what is on disk (stale / lost-update),
+ * creates the parent dir on demand, and writes atomically through any symlink
+ * rather than replacing the link. `version: null` means "I expect no file to
+ * exist yet" — the create path.
+ */
+export declare function writeConfigFile(id: string, content: string, version: string | null, repoRoot: string, env?: NodeJS.ProcessEnv): Promise<WriteOutcome | null>;
+/** Whether a path currently exists (used by the listing to report `exists`/`size`). */
+export declare function statConfigPath(path: string): Promise<{
+    exists: boolean;
+    size: number;
+}>;
+export { resolvePath, hashBytes };

package/dist/agent-config/files.js

@@ -0,0 +1,119 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, realpath, rename, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { agentHomePaths } from '../paths.js';
+import { findConfigFile } from './catalog.js';
+import { validateConfig } from './validate.js';
+/**
+ * Read and write the coding agents' own config files, addressed by catalog id
+ * (never by a client-supplied path, so traversal is impossible by
+ * construction). Every function degrades — a missing file is "absent", an
+ * unreadable one is an honest error — and none throw. Writes validate first,
+ * refuse a stale overwrite via a content hash, write atomically through
+ * symlinks, and never touch a byte the user did not type.
+ */
+/** sha256 of the exact file bytes. mtime is coarse and lies across filesystems. */
+function hashBytes(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+function resolvePath(def, repoRoot, env) {
+    return def.resolve(repoRoot, agentHomePaths(env));
+}
+/** Read a config file by id. Unknown id → null; absent file → exists:false; unreadable → thrown-free error string via `error`. */
+export async function readConfigFile(id, repoRoot, env = process.env) {
+    const def = findConfigFile(id);
+    if (!def)
+        return null;
+    const path = resolvePath(def, repoRoot, env);
+    try {
+        const content = await readFile(path, 'utf8');
+        return { id, path, exists: true, content, version: hashBytes(content) };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT')
+            return { id, path, exists: false, content: '', version: null };
+        return { error: e.message };
+    }
+}
+/**
+ * Write a config file by id. Validates the content against the file's format,
+ * refuses when `version` does not match what is on disk (stale / lost-update),
+ * creates the parent dir on demand, and writes atomically through any symlink
+ * rather than replacing the link. `version: null` means "I expect no file to
+ * exist yet" — the create path.
+ */
+export async function writeConfigFile(id, content, version, repoRoot, env = process.env) {
+    const def = findConfigFile(id);
+    if (!def)
+        return null;
+    const check = validateConfig(content, def.format);
+    if (!check.ok)
+        return { ok: false, status: 400, error: `Invalid ${def.format}: ${check.error}` };
+    const path = resolvePath(def, repoRoot, env);
+    // Stale-write guard: the version the caller read must still match disk.
+    let current = null;
+    try {
+        current = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            return { ok: false, status: 500, error: err.message };
+        }
+    }
+    // Footgun guard: emptying a populated file passes format validation (empty is
+    // valid TOML/markdown, and JSON just errors) but silently wipes real config —
+    // unrecoverable for the gitignored/home files that aren't in git. Refuse it;
+    // deleting a config file is a deliberate act, not a stray select-all-delete.
+    if (content.trim() === '' && current !== null && current.trim() !== '') {
+        return {
+            ok: false,
+            status: 400,
+            error: 'refusing to overwrite a non-empty config file with empty content — delete the file manually if you mean to remove it',
+        };
+    }
+    const currentVersion = current === null ? null : hashBytes(current);
+    if (currentVersion !== version) {
+        return {
+            ok: false,
+            status: 409,
+            error: currentVersion === null
+                ? 'the file no longer exists on disk — reload before saving'
+                : 'the file changed on disk since you opened it — reload before saving',
+        };
+    }
+    try {
+        // Resolve the real target so an atomic rename writes THROUGH a symlink
+        // (e.g. ~/.claude → a dotfiles repo) instead of replacing the link itself.
+        let target = path;
+        try {
+            target = await realpath(path);
+        }
+        catch {
+            // file/link absent — target stays as the resolved path (the create case)
+        }
+        await mkdir(dirname(target), { recursive: true });
+        // Unique per write (not just per process) so two concurrent saves of the same
+        // file can't rename the same tmp path over each other and tear the bytes.
+        const tmp = `${target}.cez-tmp-${process.pid}-${randomUUID()}`;
+        await writeFile(tmp, content, 'utf8');
+        await rename(tmp, target);
+        const written = await readFile(target, 'utf8');
+        return { ok: true, read: { id, path, exists: true, content: written, version: hashBytes(written) } };
+    }
+    catch (err) {
+        return { ok: false, status: 500, error: err.message };
+    }
+}
+/** Whether a path currently exists (used by the listing to report `exists`/`size`). */
+export async function statConfigPath(path) {
+    try {
+        const s = await stat(path);
+        return { exists: true, size: s.size };
+    }
+    catch {
+        return { exists: false, size: 0 };
+    }
+}
+export { resolvePath, hashBytes };
+//# sourceMappingURL=files.js.map