@nledford/omp-coord 0.4.0 → 0.4.2

package/.omp-plugin/marketplace.json

@@ -7,7 +7,7 @@
       "name": "omp-coord",
       "source": "./",
       "description": "Shared subagent caps, build and test queues, claims, pause, a decision log and messages across omp sessions working in one project on one machine.",
-      "version": "0.4.0",
+      "version": "0.4.2",
       "author": { "name": "Nathaniel Ledford" },
       "homepage": "https://github.com/nledford/omp-coord",
       "repository": "https://github.com/nledford/omp-coord",

package/CHANGELOG.md

@@ -6,6 +6,20 @@ Add each user-visible change under Unreleased as it lands, in one of: Added, Cha
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-11-02
+
+### Added
+
+- `omp-coord run --meta k=v` (repeatable, at most 8; the key matches `[a-z][a-z0-9_-]{0,31}`, the value is at most 200 characters on one line) tags a job. The tags go into the `job_queued` and `job_ended` events as `meta`, and `job_ended` now also carries the job's `key`. A script can detect support with `omp-coord --help 2>&1 | grep -q -- '--meta'`. The jobs table gains a nullable `meta` column (no schema version bump).
+- `omp-coord stats` and `/coord stats` add `; of the failures: N repeat an unchanged failure, M intended` to a queue's line when a failed job of that day had tags: a repeat is a failed job whose `fp` tag equals that of an earlier failed job in the same queue, with no successful job of that `fp` in between; intended is `intent=failfirst`.
+
+## [0.4.1] - 2026-10-30
+
+### Added
+
+- `protect` in `.omp-coord.json`: the extension refuses `edit`, `write`, `ast_edit` and `apply_patch` calls (also through `xd://`) whose target lies in a protected checkout and not in a linked worktree below it, and a bash command whose state-changing `git` (`checkout`, `reset`, `commit`, `clean`, `rebase` and the like) runs there, naming the resolved path or folder. A relative path in the file tools resolves against omp's own folder, not the `cwd` of an agent's bash calls, and a bash call without a `cwd` runs there too, so an agent told to work in a worktree edited or reset the main checkout. Known gaps, in [protect](docs/protect.md#what-it-cannot-see): a shell command's file writes (`cat >`, `cp`, `mv`) and `eval`, the `eval` tool and `lsp` write without a file-tool call to judge; a git folder the shell computes (`cd "$W"`, `git -C $(pwd)`) is not judged; the guard fails open when its own check throws. Subagents only unless `protect.agents` is `"all"`; each refusal is a `write_refused` event naming the agent. Without `protect` nothing changes. The guard reads paths and command text, so it stops the usual forms, not a determined dodge; what it cannot see is listed in [protect](docs/protect.md).
+- A `commands` rule may set `"agents": "sub"` to apply to subagents' commands only (default `"all"`). `examples/omp-coord.json` has three such `refuse` rules for in-place rewrites (`sed -i`, `perl -i`, an inline Python script that writes a file), which agents used instead of the edit tool; copy them into your file to use them.
+
 ## [0.4.0] - 2026-10-28
 
 ### Added
@@ -106,7 +120,9 @@ Add each user-visible change under Unreleased as it lands, in one of: Added, Cha
 - An SQLite event log per scope, with retention.
 - Packaging as an omp plugin, with a marketplace catalog; queued commands run on omp's own Bun.
 
-[Unreleased]: https://github.com/nledford/omp-coord/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/nledford/omp-coord/compare/v0.4.2...HEAD
+[0.4.2]: https://github.com/nledford/omp-coord/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/nledford/omp-coord/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/nledford/omp-coord/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/nledford/omp-coord/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/nledford/omp-coord/compare/v0.3.0...v0.3.1

package/docs/README.md

@@ -10,6 +10,7 @@ How it works:
 - [Agent slots and the line](agent-slots.md): caps, holds, revivals, agents started by subagents.
 - [Build and test queues](queues.md): `omp-coord run`, order, lanes, time limits, agents' commands.
 - [Working across sessions](coordination.md): messages, claims, pause, the decision log, ports, crash recovery.
+- [Protected checkouts](protect.md): refusing file-tool writes into the main checkout, and in-place rewrites by shell commands.
 
 Reference:
 

package/docs/commands.md

@@ -26,7 +26,7 @@
 ## `omp-coord`
 
 ```sh
-omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command> [args…]
+omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] [--meta k=v]... -- <command> [args…]
 omp-coord status [--agents | --json] | stats [days] | interrupted [hours] | notes [count] | note <text…>
 omp-coord pause [reason…] | resume | doctor [--fix]
 ```

package/docs/configuration.md

@@ -14,7 +14,8 @@
 | `agents.startTimeoutSeconds` | `120` | How long an approved spawn may take to start before its slot frees. |
 | `agents.queueSpawns` | `true` | While the session is the only one in the scope, keep omp's per-session spawn queue (`task.maxConcurrency`) at what the caps allow it, so spawns past the cap wait and start by themselves instead of being refused ([agent slots](agent-slots.md#spawns-wait-their-turn)); with other sessions, or paused, spawns over the cap are refused as before. A `task.maxConcurrency` you set yourself stays the ceiling. `false` keeps the refusals always. |
 | `messages.perMinute` | `10` | Messages one session may send per minute. It slows two sessions that keep answering each other; it does not stop them. Each delivered message starts a turn in an idle session. |
-| `commands` | `[]` | Rules for agents' bash commands, first match wins: `{ "pattern": "<regex>", "action": "refuse", "reason": "…" }`, or `{ "pattern", "action": "queue", "queue": "<name>", "lane"? }`. The user's own `!` commands are not affected. Nothing is refused unless a rule is listed; `examples/omp-coord.json` has ready-made `refuse` rules, including two that protect git's rerere cache ([queues](queues.md#example-protecting-gits-rerere-cache)). |
+| `commands` | `[]` | Rules for agents' bash commands, first match wins: `{ "pattern": "<regex>", "action": "refuse", "reason": "…" }`, or `{ "pattern", "action": "queue", "queue": "<name>", "lane"? }`; `"agents": "sub"` on a rule applies it to subagents' commands only (default `"all"`). The user's own `!` commands are not affected. Nothing is refused unless a rule is listed; `examples/omp-coord.json` has ready-made `refuse` rules, including two that protect git's rerere cache ([queues](queues.md#example-protecting-gits-rerere-cache)) and three that refuse in-place rewrites by `sed -i`, `perl -i` and inline Python ([protect](protect.md#in-place-rewrites-by-shell)). |
+| `protect` | none | `{ "roots": ["."], "allow": [], "agents": "sub" }`: checkouts the file tools (`edit`, `write`, `ast_edit`, `apply_patch`) may not write to and where a bash command's state-changing `git` (`checkout`, `reset`, `commit`, `clean`, `rebase` and the like) may not run, so an agent that types a relative path does not change the main checkout instead of its worktree ([protect](protect.md)). `roots` are relative to the config file's folder; `allow` entries are files or folders below a root, relative to it (no leading `/`, no `..`); `agents` is `"sub"` (default) or `"all"`. |
 | `queues.<name>.slots` | required | How many jobs of this queue run at once, across all processes in the scope. Queue names use letters, digits, `.`, `_`, `-`. |
 | `queues.<name>.order` | `"fifo"` | `"fifo"`, `"fair-share"` or `"priority"` (see [queues](queues.md#order)). |
 | `queues.<name>.lanes` | `["normal"]` | Lane names, first served first; the last is the default. |

package/docs/event-log.md

@@ -25,8 +25,8 @@ These tables are rebuilt as sessions come and go; their layout is not part of th
 `events` is an append-only log: `at` (ms since epoch), `type`, `session_id` (null for jobs from outside omp), `label`, and `data` (JSON). Types:
 
 - Sessions and agents: `session_joined`, `session_left`, `spawn_approved`, `spawn_refused` (with `position`, `used`, `cap`, or `nested` and `reason`), `run_started` (with `revived`), `run_ended` (with `ranMs`), `start_expired`, `hold_granted`, `hold_used` and `hold_expired` (with `waitedMs` since the first refusal), `message_sent` (recipients and length, never the text).
-- Jobs: `job_queued` (with `queue`, `lane`, `priority`, `key`, and `agent` when recorded), `job_refused` (with `reason`), `job_started` (with `waitedMs`), `job_ended` (with `exitCode`, `ranMs`, and `timedOut` when the time limit stopped it), `job_withdrawn` (left the line before starting), `job_superseded`, `job_lost` (its runner died), `job_reprioritized`.
-- Control: `paused` (with `reason`), `resumed` (with `pausedMs`), `claimed`, `released`, `claim_refused` (with `holder`), `note_added` (note number and length).
+- Jobs: `job_queued` (with `queue`, `lane`, `priority`, `key`, and `agent` and `meta` when recorded), `job_refused` (with `reason`), `job_started` (with `waitedMs`), `job_ended` (with `exitCode`, `ranMs`, `key` and `meta` when the job had them, and `timedOut` when the time limit stopped it), `job_withdrawn` (left the line before starting), `job_superseded`, `job_lost` (its runner died), `job_reprioritized`.
+- Control: `paused` (with `reason`), `resumed` (with `pausedMs`), `claimed`, `released`, `claim_refused` (with `holder`), `write_refused` (a file-tool write or a state-changing `git` command refused in a protected checkout: `agentId`, `tool` (`bash` for git), `paths` as the agent wrote them, empty for git), `note_added` (note number and length).
 
 `notes` is the decision log: `id`, `at`, `label`, `author`, `text`.
 

package/docs/protect.md

@@ -0,0 +1,43 @@
+# Protected checkouts
+
+Agents are told to work in a worktree of their own and to leave the project's main checkout alone, but nothing stops them: **a relative path in `edit`, `write`, `ast_edit` and `read` resolves against omp's own folder, not against the `cwd` an agent gives its bash calls, and a bash call without a `cwd` runs in that same folder.** An agent whose brief says "work in `/repo/.claude/worktrees/fix`" and who types `crates/a.rs` into `edit` changes `/repo/crates/a.rs`, the main checkout, while its `git status` in the worktree shows nothing; one that runs `git checkout -- .` without a `cwd` resets it. A `protect` section makes omp-coord refuse both before they happen.
+
+```json
+"protect": { "roots": ["."], "allow": ["notes"], "agents": "sub" }
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `protect.roots` | required | Folders of the checkouts to protect, relative to the config file's folder (`"."` is the folder holding `.omp-coord.json`) or absolute. |
+| `protect.allow` | `[]` | Files and folders below a root, relative to it, that stay writable. |
+| `protect.agents` | `"sub"` | Whose writes are judged: `"sub"` for subagents only (the main agent edits the checkout as before), or `"all"`. |
+
+## What is refused
+
+A call of `edit`, `write`, `ast_edit` or `apply_patch` whose target, after `~` and `..` are resolved against omp's folder and symbolic links are followed, lies inside a root and is not inside a linked worktree below it (a folder with a `.git` of its own, such as `<root>/.claude/worktrees/<name>`, including the worktree's top folder), nor under an `allow` entry. A target that holds a root (`ast_edit` on `..` or `/`) is refused too. One protected target refuses the whole call. The refusal names the resolved path, says that a relative path resolves against omp's folder, and gives the path relative to the root to put after the worktree's own path, so the agent corrects the call instead of finding the change later. Failing to write the event below never lets a refused call through.
+
+- A symbolic link is judged by where it points: `AGENTS.local.md` in the checkout, a link to a file of another repository, is writable; a link from elsewhere into the checkout is not.
+- `write` to `xd://edit`, `xd://write`, `xd://ast_edit` and `xd://apply_patch` (any case) is judged as the tool whose arguments it carries.
+- Every way `edit` names a file counts: a `[path#TAG]` header (the path runs to the last `]`, so `[slug]` folders work), an `MV` destination (resolved like a header), `path`, `rename` and `move_to` (also in `edits`), and the `*** Update File:`, `*** Add File:`, `*** Delete File:`, `*** Move to:` and `*** Edit File:` lines of the patch modes.
+- omp reads a path differently per tool (it unquotes a header but not a `write` path, drops a `[…#TAG]` wrapper or a copied `Update File:` and a leading `@`), so each path is judged as written and with those decorations removed, and the call is refused when either lies in the checkout. A decorated path to a worktree can therefore be refused (`write` with `"/repo/.claude/worktrees/x/a.rs"` in quotes): write it plainly.
+- For `ast_edit`, a glob is judged by what comes before its first wildcard.
+- Each refusal is a `write_refused` event (`agentId`, `tool`, `paths`), so the log names the agent that tried ([event log](event-log.md)).
+
+## State-changing git
+
+A bash command whose `git` runs in a protected checkout is refused when its subcommand changes files, the index, HEAD or a branch: `checkout`, `switch`, `reset`, `restore`, `clean`, `rebase`, `merge`, `commit`, `pull`, `cherry-pick`, `revert`, `am`, `add`, `rm`, `mv` and `apply`. Reading (`status`, `diff`, `log`, `show`, `branch`), `fetch`, `push` and `worktree` stay allowed. Where a command runs follows the call's `cwd` (omp's folder when none is given), then each `cd` and `pushd`, `git -C <dir>` and `--work-tree`, through `&&`, `||`, `;`, `|` and subshells; a folder it cannot work out (`cd "$W"`, `cd -`) is not judged. Heredoc bodies are skipped. So `cd /repo && git checkout -q -- .` is refused from any folder, and `cd /repo/.claude/worktrees/x && git checkout -- a.rs` or `git -C /repo/.claude/worktrees/x reset` is not. An agent that really must run git there passes a worktree as `cwd`.
+
+`read` is not refused: reading the main checkout is harmless, but it is the first step of the mistake, because the agent sees a file and edits what it just read. The refusal of the edit is what corrects it.
+
+## What it cannot see
+
+- **Bash writes.** A shell command's file writes are not parsed: `cat > crates/a.rs`, `cp`, `mv`, `awk` with redirects and a script all get through (the `commands` rules below refuse the in-place rewriters); the rest is for [claims](coordination.md) and the agent's own `git status`. Git commands whose folder the shell computes (`cd "$W"`, `git -C $(pwd)`, a `cd` to a substitution's output, an `xargs -I{}` placeholder) and `eval` are not judged; a substitution's own commands are, quotes inside a double-quoted `$(…)` included. `xargs git …`, `sh -c '…'` (`-c`, `-lc`, `-ec`…), `sudo`/`env`/`nice`/`timeout` wrappers (also by path), `env -C`/`--chdir` and `sudo -D` are followed. Not handled: `$'…'` strings with escaped quotes, a stray `)` in a `case` pattern, and the cost of resolving folders on a real disk is not cached.
+- **Eval and `lsp`.** Python and JavaScript run by the `eval` tool, and the `lsp` tool's renames and code actions, write files without a file-tool call to judge.
+- A worktree that does not exist yet is the checkout's own folder to this guard (a folder below the root without a `.git` of its own), and a worktree outside every root is never judged.
+- The guard fails open: a check that throws lets the call run, with a notice.
+
+## In-place rewrites by shell
+
+A related slip: an agent that holds the text to change makes the edit with `sed -i`, `perl -pi` or an inline Python script (`python3 - <<'E' … open(p,'w') …`) instead of the edit tool. Nothing shows what the command matched, whether the file is the one meant, or that it changed at all. `examples/omp-coord.json` has three `refuse` rules for them (`sed -i` and `gsed -i`, `perl -i`, and Python run inline with `-c`, `-` or a heredoc whose code opens a file for writing, appending or creating, or calls `write_text` or `write_bytes`), each with `"agents": "sub"` so the main agent is not judged. A `commands` rule with `agents: "sub"` applies to subagents' commands only; the default is `"all"`.
+
+The way out is deliberate and visible: a script saved to a file with the write tool and run from a short command (`python3 /path/script.py`, `bash script.sh`) is not judged, and neither is anything a `just` recipe or other program writes. The rules read command text like every rule here ([agents' commands](queues.md#agents-commands)), so `echo "sed -i is refused"` and a commit message that mentions it are refused too, and `awk` with redirects, `tee`, `ed`, `cat <<'PY' | python3` and `perl -pe '…' -i file` get through.

package/docs/queues.md

@@ -3,7 +3,7 @@
 `omp-coord run <queue> -- <command>` waits for one of the queue's slots, shared by everything on this machine in the same scope, then runs the command. `just` recipes, scripts and terminals call it; agents' matching bash commands are rewritten to go through it. Queues are set under `queues` in the [configuration](configuration.md).
 
 ```sh
-omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command> [args…]
+omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] [--meta k=v]... -- <command> [args…]
 ```
 
 ## Running a job
@@ -14,6 +14,7 @@ The command runs in its own process group and session, so a time limit stops eve
 
 - **Exit codes**: the command's own, `75` when the job was not run (a refused or superseded duplicate), `124` when its time limit stopped it, `2` for a usage or configuration error.
 - **Owner**: jobs belong to the omp session in `OMP_COORD_SESSION` (set by the extension, so commands an agent runs inherit it) or `--owner`; otherwise to no session ("outside omp").
+- **Tags**: `--meta k=v` (repeatable, at most 8; a repeated key: the last wins) records tags on the job's `job_queued` and `job_ended` events. A key matches `[a-z][a-z0-9_-]{0,31}`; a value is at most 200 characters on one line. Scripts can tag a job with a fingerprint of the code state (`fp`) and mark a deliberate failure (`intent=failfirst`); `omp-coord stats` then adds `; of the failures: N repeat an unchanged failure, M intended` to the queue's line. A repeat is a failed job whose `fp` equals that of an earlier failed job in the same queue inside the stats window, with no successful job of that `fp` in between. Detect support with `omp-coord --help 2>&1 | grep -q -- '--meta'`.
 - **Duplicates**: jobs with the same `--key` (for example `"<checkout> ci"`) are duplicates. One that duplicates a running job is refused; one that duplicates a waiting job is refused or, with `onDuplicate: "supersede"`, replaces it in its place in line.
 
 ## Order

package/examples/omp-coord.json

@@ -32,6 +32,24 @@
       "action": "refuse",
       "reason": "git's rerere cache is shared by every worktree and session, and deleting it loses other sessions' recorded resolutions: to keep a throwaway build's resolutions out, run that command with `git -c rerere.enabled=false …`"
     },
+    {
+      "pattern": "(?<![\\w.-])g?sed(?:\\s+-\\S+){0,8}?\\s+(?:-[A-Za-z]*i\\S*|--in-place\\S*)(?=\\s|$)",
+      "action": "refuse",
+      "agents": "sub",
+      "reason": "sed -i rewrites files in place without showing what changed: use the edit tool (read the lines first). For one rewrite across many files, save a script with the write tool and run it from a short command. If the text only mentions it (a commit message, a PR body), put it in a file with the write tool and pass the file"
+    },
+    {
+      "pattern": "(?<![\\w.-])perl(?:\\s+-\\S+){0,8}?\\s+-(?![IMmdDwWxX])\\w*i\\S*(?=\\s|$)",
+      "action": "refuse",
+      "agents": "sub",
+      "reason": "perl -i rewrites files in place without showing what changed: use the edit tool (read the lines first). For one rewrite across many files, save a script with the write tool and run it from a short command. If the text only mentions it (a commit message, a PR body), put it in a file with the write tool and pass the file"
+    },
+    {
+      "pattern": "(?<![\\w.-])python[0-9.]*(?=((?:\\s+-(?![c-]\\b)(?![\\s<])\\S*(?:\\s+(?![-<])[A-Za-z][\\w.]*)?){0,8}))\\1\\s+(?:-c\\b|-(?=\\s*<<)|<<|-\\s)(?=[\\s\\S]*?(?:\\.write_(?:text|bytes)\\(|\\bopen\\((?:[^,()\\n]|\\([^()\\n]*\\))*,\\s*(?:mode\\s*=\\s*)?['\"][wax]))",
+      "action": "refuse",
+      "agents": "sub",
+      "reason": "an inline Python script that writes a file edits it without showing what changed: use the edit tool (read the lines first). For one rewrite across many files, save the script with the write tool and run it from a short command (`python3 /path/script.py`). If the text only mentions it (a commit message, a PR body), put it in a file with the write tool and pass the file"
+    },
     { "pattern": "(^|[;&|(\\s])(npm|pnpm|yarn|bun)\\s+(run\\s+)?test\\b", "action": "queue", "queue": "test" },
     { "pattern": "(^|[;&|(\\s])(npm|pnpm|yarn|bun)\\s+run\\s+build\\b", "action": "queue", "queue": "build" },
     {
@@ -49,6 +67,7 @@
     "ports": { "from": 20000, "to": 20999, "perSession": 200, "perAgent": 10 },
     "scratch": ".omp-coord-scratch"
   },
+  "protect": { "roots": ["."], "allow": [], "agents": "sub" },
   "messages": { "perMinute": 10 },
   "history": { "retentionDays": 30, "maxEvents": 100000 }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nledford/omp-coord",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "files": [
     "src",
     "docs",

package/src/adapters/cli/cli.ts

@@ -4,7 +4,7 @@
  * terminals, or agents' bash calls (which the extension rewrites to go through here when a rule queues them), and
  * reports on the scope.
  *
- *   omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command> [args…]
+ *   omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] [--meta k=v]... -- <command> [args…]
  *   omp-coord status [--agents | --json] | stats [days] | interrupted [hours] | notes [count] | note <text…>
  *   omp-coord pause [reason…] | resume | doctor [--fix]
  *
@@ -24,7 +24,7 @@ import { doctor } from "../../app/doctor.ts";
 import { EXIT_TIMED_OUT, runJob } from "../../app/job-runner.ts";
 import { type Config, ConfigError, findConfigFile, loadConfig } from "../../config.ts";
 import { statusView } from "../../domain/overview.ts";
-import { MAX_PRIORITY } from "../../domain/queues.ts";
+import { MAX_PRIORITY, parseMeta } from "../../domain/queues.ts";
 import { agentOfOmpSession } from "../../domain/sessions.ts";
 import { osLoad } from "../os/load.ts";
 import { groupRunning } from "../os/process-group.ts";
@@ -45,7 +45,7 @@ const KILL_GRACE_MS = 10_000;
 const DAY = 86_400_000;
 
 const USAGE = `usage:
-  omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command…>
+  omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] [--meta k=v]... -- <command…>
   omp-coord status [--agents | --json] | stats [days] | interrupted [hours] | notes [count] | note <text…>
   omp-coord pause [reason…] | resume | doctor [--fix]`;
 
@@ -206,6 +206,12 @@ async function run(args: string[]): Promise<number> {
   if (!Number.isSafeInteger(priority) || Math.abs(priority) > MAX_PRIORITY) {
     throw new UsageError(`omp-coord run: --priority must be a whole number from -${MAX_PRIORITY} to ${MAX_PRIORITY}`);
   }
+  let meta: ReturnType<typeof parseMeta>;
+  try {
+    meta = parseMeta(values.meta ?? []);
+  } catch (error) {
+    throw new UsageError(`omp-coord run: ${error instanceof Error ? error.message : String(error)}`);
+  }
   const timeoutMs = values.timeout === undefined ? undefined : parseDuration(values.timeout);
   const command = args.slice(split + 1);
 
@@ -258,6 +264,7 @@ async function run(args: string[]): Promise<number> {
         ...(values.lane === undefined ? {} : { lane: values.lane }),
         priority,
         ...(values.key === undefined ? {} : { key: values.key }),
+        ...(meta === undefined ? {} : { meta }),
         command: command.join(" "),
         pid: process.pid,
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
@@ -293,6 +300,7 @@ function parseRunFlags(args: string[]) {
       key: { type: "string" },
       owner: { type: "string" },
       timeout: { type: "string" },
+      meta: { type: "string", multiple: true },
     },
   });
 }

package/src/adapters/omp/extension.ts

@@ -10,15 +10,25 @@
  * one registration, and every binding is kept so a message can reach the subagent it is for.
  */
 import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { Coordinator } from "../../app/coordinator.ts";
 import type { Listener } from "../../app/ports.ts";
 import { type Config, ConfigError, findConfigFile, loadConfig } from "../../config.ts";
 import { spawnAllowance } from "../../domain/agents.ts";
-import { decideCommand } from "../../domain/commands.ts";
+import { decideCommand, MAX_CHECKED_COMMAND } from "../../domain/commands.ts";
 import type { Claim } from "../../domain/model.ts";
+import {
+  canonicalWith,
+  decideWrite,
+  type GuardFacts,
+  gitChange,
+  resolveCwd,
+  type WriteDecision,
+  type WriteGuard,
+  writeTargets,
+} from "../../domain/protect.ts";
 import { osLoad } from "../os/load.ts";
 import { BoardStore, stateDir } from "../sqlite/store.ts";
 import {
@@ -31,7 +41,7 @@ import {
   formatStatus,
 } from "../text/report.ts";
 import { startBeacon, unixLiveness } from "../unix/beacon.ts";
-import type { ExtensionAPI, ExtensionContext, Timer, ToolResult } from "./api.ts";
+import type { ExtensionAPI, ExtensionContext, Timer, ToolCallEvent, ToolResult } from "./api.ts";
 import { loadSettingHandle, type SpawnQueue, spawnQueue } from "./spawn-queue.ts";
 
 /**
@@ -194,14 +204,15 @@ export default function ompCoord(pi: ExtensionAPI): void {
 
   pi.on("tool_call", (event, ctx) => {
     const rt = shared.runtime;
-    if (!rt || event.toolName !== "bash") return undefined;
-    const command = event.input.command;
+    if (!rt) return undefined;
+    if (event.toolName !== "bash") return guardWrite(rt, event, ctx);
+    const command = event.input?.command;
     if (typeof command !== "string") return undefined;
     // the id must be on the board before the command can reach `omp-coord run`, whatever event announced a switch
     if (ctx.agent.kind === "main") syncMainSession(rt, ctx);
 
     try {
-      const cwd = typeof event.input.cwd === "string" ? resolve(ctx.cwd, event.input.cwd) : ctx.cwd;
+      const cwd = typeof event.input?.cwd === "string" ? resolve(ctx.cwd, event.input.cwd) : ctx.cwd;
       const held = rt.coordinator.checkCommand({
         sessionId: rt.sessionId,
         command,
@@ -220,12 +231,15 @@ export default function ompCoord(pi: ExtensionAPI): void {
     } catch (error) {
       notify(rt, `omp-coord could not check claims: ${describe(error)}`, "error");
     }
-
-    const decision = decideCommand(rt.config.commands, command, {
-      ...RUNNER,
-      owner: rt.sessionId,
-      config: rt.config.source,
-    });
+    const gitHeld = guardGit(rt, ctx, command, event.input?.cwd);
+    if (gitHeld) return gitHeld;
+
+    const decision = decideCommand(
+      rt.config.commands,
+      command,
+      { ...RUNNER, owner: rt.sessionId, config: rt.config.source },
+      ctx.agent.kind,
+    );
     if (decision.kind === "refuse") return { block: true, reason: `omp-coord: ${decision.reason}` };
     // Only a queued command is rewritten. Which agent runs it needs no rewrite: omp gives every bash call its agent's
     // session id (`PI_SESSION_ID`), and the board maps that id to the agent (`session_start`, `agent_start`).
@@ -709,6 +723,85 @@ function notify(rt: Runtime, message: string, type: "info" | "warning" | "error"
   if (rt.ctx.hasUI) rt.ctx.ui.notify(message, type);
 }
 
+/**
+ * The `protect` guard for the file tools (`edit`, `write`, `ast_edit`, `apply_patch`): a write into a protected
+ * checkout is blocked with a reason naming the resolved path.
+ */
+function guardWrite(
+  rt: Runtime,
+  event: ToolCallEvent,
+  ctx: ExtensionContext,
+): { block: true; reason: string } | undefined {
+  if (!rt.config.protect) return undefined;
+  let targets: string[] | undefined;
+  try {
+    targets = writeTargets(event.toolName, event.input ?? {});
+  } catch (error) {
+    notify(rt, `omp-coord could not read a ${event.toolName} call: ${describe(error)}`, "error");
+    return undefined;
+  }
+  if (!targets || targets.length === 0) return undefined;
+  return refuseProtected(rt, ctx, event.toolName, targets, ctx.cwd, (guard, facts) =>
+    decideWrite(guard, ctx.agent.kind, event.toolName, targets, facts),
+  );
+}
+
+/**
+ * The `protect` guard for a bash command's state-changing `git`: it must not run in a protected checkout. A command
+ * over the length cap is left to `decideCommand`, which refuses it while a refuse rule exists.
+ */
+function guardGit(
+  rt: Runtime,
+  ctx: ExtensionContext,
+  command: string,
+  inputCwd: unknown,
+): { block: true; reason: string } | undefined {
+  if (!rt.config.protect || command.length > MAX_CHECKED_COMMAND || !/\bgit\b/.test(command)) return undefined;
+  const cwd = typeof inputCwd === "string" ? resolveCwd(ctx.cwd, inputCwd, homedir()) : ctx.cwd;
+  return refuseProtected(rt, ctx, "bash", [], cwd, (guard, facts) =>
+    gitChange(guard, ctx.agent.kind, command, cwd, facts),
+  );
+}
+
+/**
+ * Judges a call with the disk's facts and blocks it on a refusal. Like every guard here it fails open: a check that
+ * throws lets the call run; but once the decision is "refuse", failing to log it never lets the call through.
+ */
+function refuseProtected(
+  rt: Runtime,
+  ctx: ExtensionContext,
+  tool: string,
+  shown: string[],
+  cwd: string,
+  judge: (guard: WriteGuard, facts: GuardFacts) => WriteDecision,
+): { block: true; reason: string } | undefined {
+  const guard = rt.config.protect;
+  if (!guard) return undefined;
+  let decision: WriteDecision;
+  try {
+    decision = judge(guard, {
+      cwd,
+      home: homedir(),
+      canonical: canonicalWith(p => {
+        try {
+          return realpathSync(p);
+        } catch {
+          return undefined;
+        }
+      }),
+      hasGitEntry: dir => existsSync(join(dir, ".git")),
+    });
+  } catch (error) {
+    notify(rt, `omp-coord could not check a ${tool} call: ${describe(error)}`, "error");
+    return undefined;
+  }
+  if (decision.kind === "allow") return undefined;
+  guarded(rt, "record a refused call", () =>
+    rt.coordinator.recordWriteRefused(rt.sessionId, ctx.agent.id, tool, decision.shown ?? shown),
+  );
+  return { block: true, reason: `omp-coord: ${decision.reason}` };
+}
+
 function claimKind(word: string): Claim["kind"] | undefined {
   const k = word.trim().toLowerCase();
   return CLAIM_KINDS.find(x => x === k);

package/src/adapters/sqlite/store.ts

@@ -81,6 +81,7 @@ CREATE TABLE jobs (
   key        TEXT,
   command    TEXT NOT NULL,
   agent      TEXT,
+  meta       TEXT,
   socket     TEXT NOT NULL,
   pid        INTEGER NOT NULL,
   state      TEXT NOT NULL CHECK (state IN ('waiting', 'running', 'superseded')),
@@ -258,6 +259,7 @@ export class BoardStore implements BoardRepository {
         .all()
         .some(c => c.name === column);
     if (!has("jobs", "agent")) this.#db.exec("ALTER TABLE jobs ADD COLUMN agent TEXT");
+    if (!has("jobs", "meta")) this.#db.exec("ALTER TABLE jobs ADD COLUMN meta TEXT");
     if (!has("slots", "unqueued"))
       this.#db.exec("ALTER TABLE slots ADD COLUMN unqueued TEXT CHECK (unqueued IN ('revived', 'eval'))");
     if (!has("sessions", "omp_session")) this.#db.exec("ALTER TABLE sessions ADD COLUMN omp_session TEXT");
@@ -369,6 +371,7 @@ export class BoardStore implements BoardRepository {
             key: string | null;
             command: string;
             agent: string | null;
+            meta: string | null;
             socket: string;
             pid: number;
             state: "waiting" | "running" | "superseded";
@@ -387,6 +390,7 @@ export class BoardStore implements BoardRepository {
           key: r.key ?? undefined,
           command: r.command,
           agent: r.agent ?? undefined,
+          meta: r.meta === null ? undefined : (JSON.parse(r.meta) as Record<string, string>),
           socket: r.socket,
           pid: r.pid,
           state: r.state,
@@ -499,7 +503,7 @@ export class BoardStore implements BoardRepository {
     const sent = db.query("INSERT INTO sent (session_id, at) VALUES (?, ?)");
     for (const x of board.sent) sent.run(x.sessionId, x.at);
     const job = db.query(
-      "INSERT INTO jobs (id, queue, owner, lane, priority, key, command, agent, socket, pid, state, since, started_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      "INSERT INTO jobs (id, queue, owner, lane, priority, key, command, agent, meta, socket, pid, state, since, started_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
     );
     for (const j of board.jobs) {
       job.run(
@@ -511,6 +515,7 @@ export class BoardStore implements BoardRepository {
         j.key ?? null,
         j.command,
         j.agent ?? null,
+        j.meta === undefined ? null : JSON.stringify(j.meta),
         j.socket,
         j.pid,
         j.state,

package/src/adapters/text/report.ts

@@ -212,7 +212,7 @@ export function formatStats(days: DayStats[]): string {
     );
     for (const [q, s] of Object.entries(d.queues)) {
       lines.push(
-        `  ${q}: ${s.started} started, wait avg ${minutes(s.avgWaitMs)} / max ${minutes(s.maxWaitMs)}; ${s.ended} ended, ${s.failed} failed${s.timedOut ? ` (${s.timedOut} timed out)` : ""}`,
+        `  ${q}: ${s.started} started, wait avg ${minutes(s.avgWaitMs)} / max ${minutes(s.maxWaitMs)}; ${s.ended} ended, ${s.failed} failed${s.timedOut ? ` (${s.timedOut} timed out)` : ""}${s.ofFailures ? `; of the failures: ${s.ofFailures.repeats} repeat an unchanged failure, ${s.ofFailures.intended} intended` : ""}`,
       );
     }
   }

package/src/app/coordinator.ts

@@ -30,6 +30,7 @@ import { type SendResult, sendMessage, takeInbox } from "../domain/messages.ts";
 import type { Board, Claim, Note } from "../domain/model.ts";
 import { addNote, type NoteResult } from "../domain/notes.ts";
 import { type AgentPortsResult, agentPorts } from "../domain/ports.ts";
+import { writeRefused } from "../domain/protect.ts";
 import { dropJobs, type EnqueueResult, schedule, setJobPriority } from "../domain/queues.ts";
 import { bindOmpSession, registerSession, removeSession } from "../domain/sessions.ts";
 import type { BoardRepository, Clock, Liveness, LoadProbe } from "./ports.ts";
@@ -137,6 +138,11 @@ export class Coordinator {
     return conflict;
   }
 
+  /** Records that a file tool's write was refused by the `protect` guard (for the event log). */
+  recordWriteRefused(sessionId: string, agentId: string, tool: string, paths: string[]): void {
+    this.repo.transact(b => writeRefused(b, sessionId, { agentId, tool, paths, now: this.clock.now() }));
+  }
+
   note(sessionId: string | null, author: string, text: string): NoteResult {
     return this.repo.transact(b => addNote(b, { sessionId, author, text, now: this.clock.now() }));
   }
@@ -155,7 +161,7 @@ export class Coordinator {
   }
 
   stats(sinceMs: number): DayStats[] {
-    return stats(this.repo.events(this.clock.now() - sinceMs), 0).days;
+    return stats(this.repo.events(), this.clock.now() - sinceMs).days;
   }
 
   requestSpawn(req: Omit<SpawnRequest, "now">): SpawnDecision {

package/src/app/job-runner.ts

@@ -22,6 +22,8 @@ export interface JobSpec {
   lane?: string;
   priority: number;
   key?: string;
+  /** Tags for the event log. */
+  meta?: Record<string, string>;
   /** For display. */
   command: string;
   pid: number;

package/src/config.ts

@@ -5,11 +5,12 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, posix, resolve } from "node:path";
 import type { CommandRule } from "./domain/commands.ts";
 import type { LoadLimit } from "./domain/limits.ts";
 import type { AgentPolicy } from "./domain/model.ts";
 import type { PortPolicy } from "./domain/ports.ts";
+import type { WriteGuard } from "./domain/protect.ts";
 import type { QueuePolicy, Queues } from "./domain/queues.ts";
 
 export const CONFIG_FILE = ".omp-coord.json";
@@ -24,6 +25,8 @@ export interface Config {
   agents: AgentPolicy;
   /** Rules for agents' bash commands, first match wins. */
   commands: CommandRule[];
+  /** Checkouts the agents' file tools may not write to; undefined when no `protect` is configured. */
+  protect: WriteGuard | undefined;
   /** Build and test queues, machine-wide within the scope. */
   queues: Queues;
   /** Port ranges and scratch folders handed to sessions and their agents. */
@@ -135,8 +138,11 @@ export function parseConfig(raw: unknown, source: string, hash = "none"): Config
     } catch (e) {
       return fail(`${field}.pattern`, `is not a valid regular expression (${e instanceof Error ? e.message : e})`);
     }
+    const agentsText = rule.agents ?? "all";
+    if (agentsText !== "all" && agentsText !== "sub") fail(`${field}.agents`, `must be "all" or "sub"`);
+    const agents = agentsText as "all" | "sub";
     if (rule.action === "refuse")
-      return { pattern, action: "refuse", reason: str(rule.reason, `${field}.reason`, fail) };
+      return { pattern, action: "refuse", reason: str(rule.reason, `${field}.reason`, fail), agents };
     if (rule.action !== "queue") return fail(`${field}.action`, `must be "refuse" or "queue"`);
     const queue = str(rule.queue, `${field}.queue`, fail);
     const policy = queues[queue];
@@ -144,9 +150,40 @@ export function parseConfig(raw: unknown, source: string, hash = "none"): Config
     const lane = rule.lane === undefined ? undefined : str(rule.lane, `${field}.lane`, fail);
     if (lane !== undefined && !policy.lanes.includes(lane))
       fail(`${field}.lane`, `names no lane of queue ${queue} (${policy.lanes.join(", ")})`);
-    return { pattern, action: "queue", queue, lane };
+    return { pattern, action: "queue", queue, lane, agents };
   });
 
+  let protect: WriteGuard | undefined;
+  if (root.protect !== undefined) {
+    const p = obj(root.protect, "protect", fail);
+    const roots = strList(p.roots, "protect.roots", fail);
+    if (roots.length === 0) fail("protect.roots", "must list at least one folder");
+    const agentsText = p.agents ?? "sub";
+    if (agentsText !== "sub" && agentsText !== "all") fail("protect.agents", `must be "sub" or "all"`);
+    protect = {
+      roots: roots.map(r => resolve(dirname(source), r)),
+      allow: strList(p.allow ?? [], "protect.allow", fail).map((a, i) => {
+        const entry = a.replace(/^(?:\.\/)+/, "");
+        const bare = entry.replace(/\/+$/, "");
+        if (
+          bare === "" ||
+          bare.startsWith("/") ||
+          bare.includes("\\") ||
+          posix.normalize(bare) !== bare ||
+          bare === "." ||
+          bare.startsWith("../") ||
+          bare === ".."
+        )
+          fail(
+            `protect.allow[${i}]`,
+            "must be a file or folder below a root, written relative to it with / separators (no leading /, no .. or . parts, no doubled /)",
+          );
+        return entry;
+      }),
+      agents: agentsText as WriteGuard["agents"],
+    };
+  }
+
   const resources = obj(root.resources ?? {}, "resources", fail);
   let ports: PortPolicy | undefined;
   if (resources.ports !== undefined) {
@@ -185,6 +222,7 @@ export function parseConfig(raw: unknown, source: string, hash = "none"): Config
       messagesPerMinute: count(messages.perMinute ?? 10, "messages.perMinute", fail),
     },
     commands,
+    protect,
     queues,
     resources: { ports, scratch },
     history: {