agy-worker-mcp 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to agy-worker-mcp. Dates are the day the version landed on
+`main`. Measurements against the real `agy` CLI are noted with the agy version
+they were taken on.
+
+## 0.3.1 — 2026-09-09
+
+Pre-publish audit. The gate is a string classifier; this release makes it
+reject what it does not model instead of passing it, and says so in the docs.
+
+- **Chain and wrapper parsing** — newline, `\r\n`, single `&` and `|&` split
+  segments; `<( )` / `>( )` are judged like `$( )`; `bash -lc`-style clusters
+  count as `-c`; only `bash`, `sh`, `env` act as wrappers (`zsh -c` needs its own
+  rule); a head token carrying `\`, `$`, quotes or non-ASCII is a parse error.
+- **`rm`, `git`, `find`, `xargs`** — `rm` denies on any `-r`/`-R` + `-f`
+  combination; `git -c` / `-C` / `--git-dir` / `--work-tree` / `--exec-path` /
+  `--config-env` and `git config` writes to executable keys are always denied;
+  `find -exec` / `-execdir` / `-ok` / `-delete` are denied; `xargs` left the
+  `general_worker` allow list and `xargs <cmd>` is judged as `<cmd>`.
+- **Containment** — every path is resolved against the pinned workspace, never
+  the model's `Cwd`; a leading `~/` expands to the real home, any other `~`,
+  `$VAR` or backtick in a path is refused (`unexpanded_path`); globs are
+  contained by their literal directory prefix; `sed -i`, `sort -o`, `tee`,
+  `dd of=`, `tar -C`, `unzip -d`, `git clone/archive/init/worktree`, … count
+  as writers; read utilities and script paths (`cat`, `grep`, `node x.js`, …)
+  must stay inside the workspace or `read_roots` (`read_outside_workspace`).
+- **Credential `HARD_DENY` for commands** — `~/.ssh`, `~/.aws`, `~/.gnupg`,
+  `~/.netrc`, `~/.npmrc`, `~/.git-credentials`, `~/.config/gh`,
+  `~/.config/gcloud`, `~/.docker/config.json`, `~/.kube`, `~/.gemini`,
+  `~/.antigravity`, `~/.agy-worker` are refused as command arguments and
+  redirection targets, not only through file tools; the file-tool list gained
+  the same entries; the home directory is canonicalised before matching.
+- **Self-protection** — `agy_start` refuses a workspace that contains the state
+  home or the gate binary, and a ceiling `write_roots` entry of `/`, the home
+  directory or the state home.
+- **Hygiene** — job output files `0600`, job and project directories `0700`,
+  `index.db` and its WAL/SHM `0600`.
+- **Docs** — README carries an unofficial/trademark notice and a
+  "Trademarks and terms" section on how the official `agy` binary is used;
+  `docs/permissions.md` gains "What the gate deliberately does not see"
+  (threat model, what allowed programs can do, sandbox default, local trust,
+  where the string match ends).
+
+## 0.3.0 — 2026-09-09
+
+Two walls, kept apart: the profile (code) and the project ceiling (a human).
+
+- **Ceiling file version 2** — `allow` / `deny` / `exceptions` / `read_roots` /
+  `write_roots` / `sandbox` / `command_policy`. A version 1 file
+  (`extra_allow`, `extra_deny`, `additional_dirs`, `sandboxed`) is still read,
+  converted, and warned about; it stops loading in 0.4.
+- **`HARD_DENY` narrowed** to what protects the gate itself (credential reads,
+  writes into `{workspace}/.agents`). Everything else `general_worker` denies —
+  `git push`, `curl`, `wget`, `ssh`, `scp`, `sudo`, `docker`, `rm -rf`,
+  `git reset --hard`, `npm install`, `pip install`, … — can be lifted by a
+  project through `exceptions`. By a human editing the file, never by a request.
+- **`sandbox: "seatbelt"`** — our own write-only `sandbox-exec` profile (macOS):
+  an allowed command runs with writes confined to the workspace and the
+  ceiling's `write_roots`, even through interpreters, and still does the work.
+  `"agy"` keeps agy's own sandbox; `"none"` stays the default. Strictest of
+  profile / ceiling / request wins; the request's `sandbox` replaces the old
+  boolean `sandboxed` (still accepted, means `"agy"`).
+- **`agy_ceiling`** — a tenth tool. Read-only: the ceiling file as loaded, the
+  effective policy, the project's denial history, a review of a draft (risk
+  class per rule, `HARD_DENY` conflicts, duplicates of the profile) and how
+  `expected_commands` would be judged. It has no write path.
+- **`agy-ceiling` skill and `/agy-ceiling` slash command** (Claude Code),
+  shipped in the package under `skills/` and `commands/`; both stop for the
+  user's approval before the file is written. `agy-worker-setup` copies them
+  into `./.claude` or `~/.claude`.
+- **No-ceiling hint** — when a project has no ceiling file, `agy_capabilities`,
+  `agy_start` and a blocked job's `verification.warnings` say so once, name
+  the file, and point at the three ways to propose one.
+- **`agy_logs({ stream: "digest" })`** — what a job actually ran and touched:
+  commands with allow/deny, files written, denials, in order.
+- **Denial policy** — `max_denials` aborts after N gate denials regardless of
+  `on_denial`; an `unsupported` tool call no longer aborts a job on its own
+  (subagent tools still do); `schedule` is a control tool; the environment-block
+  detector reads only the last five lines of a tool's output, so a `git diff`
+  that quotes an error message is no longer a "sandbox block".
+- **Read roots that carry their own `.agents/hooks.json` are refused** at
+  `agy_start` — agy loads hooks from every `--add-dir`, and a foreign deny runs
+  ahead of our gate (measured, agy 1.1.27).
+- Release workflow (`.github/workflows/release.yml`): tag `v*.*.*` matching
+  `package.json`, or manual dispatch with `dry_run` (default true).
+
+## 0.2.2 — 2026-09-08
+
+From a usage audit of 35 real jobs.
+
+- The broker no longer misjudges a job as `process_error` while its
+  `verify_command` is still running; `duration_ms` is the runner's real end.
+- The gate parses `ENV=… cmd`, `env`, `export`, `&&` / `|` / `;` chains and
+  `bash -c` instead of denying them wholesale.
+- The ceiling's read roots apply to every job by default; a request names
+  them only to pick a subset.
+- `general_worker` allows the ordinary POSIX utilities and inline
+  interpreters, with `git` under a denylist; containment still bounds `rm`,
+  `mv`, `cp`, `touch`, `mkdir` to the workspace.
+- A ceiling can opt into `command_policy: "denylist"`.
+- `agy_start` warns up front when a job has nothing checkable, judges
+  `expected_commands` on a `dry_run`, and checks `model` / `effort` against
+  what agy 1.1.27 accepts.
+- `agy_wait` on a running job shows the tail of the log, not its head.
+
+## 0.2.1 — 2026-09-03
+
+- Allowed commands on `general_worker` run **without** agy's OS sandbox.
+  Measured on agy 1.1.24, that sandbox refuses every write a shell command
+  makes inside the workspace — `npm test`, `./gradlew build`, `git commit` all
+  fail with `Operation not permitted` after the gate said yes. The gate's
+  allow list is the boundary, as in Claude Code; `research_readonly` stays
+  sandboxed; a ceiling can force the sandbox back on.
+- The `unsandboxed` ceiling key was removed (a file carrying it fails closed
+  with a migration message).
+
+## 0.2.0 — 2026-09-02
+
+- Permission enforcement rebuilt around a single `PreToolUse` gate that is the
+  sole approval authority for every job; agy's own approval engine is disabled
+  (`--dangerously-skip-permissions`). A bound job's gate never answers "ask".
+- Human-owned per-project ceiling file, `~/.agy-worker/projects/<hash>/policy.json`,
+  outside the workspace.
+- `verify_command`: a command the runner runs once after agy exits, against
+  the final tree; the job cannot skip or narrow it.
+- The `network` permission field was dropped.
+- Subagent tools are always denied; the runner kills a job whose gate never
+  confirmed itself.
+
+## 0.1.1 — 2026-09-02
+
+- Build commands (`./gradlew`, `mvn`, `npm test`, `npm run`, `javac`, `java`)
+  added to the `general_worker` ceiling so they stop bouncing.
+
+## 0.1.0 — 2026-09-01
+
+- MVP: detached `agy` jobs with state in a project-local SQLite database,
+  `agy_start` / `agy_wait` / `agy_result` / `agy_logs` / `agy_send` /
+  `agy_cancel` / `agy_list_jobs` / `agy_sessions` / `agy_capabilities`, and a
+  broker-computed `outcome` kept separate from agy's self-report.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siwoo Ryu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,309 @@
+> [!WARNING]
+> Under active development (0.3.x). The permission model is a string classifier over
+> tool calls — the same kind of boundary Claude Code and Codex use, not a kernel
+> boundary. Allowed shell commands run **without** an OS sandbox by default since 0.2.1
+> (can be enabled with `sandbox: "seatbelt"`). What the gate deliberately does not
+> see is documented in [`docs/permissions.md`](./docs/permissions.md#what-the-gate-deliberately-does-not-see);
+> read it before starting. Point it only at projects you would let Claude Code work on unattended.
+
+# agy-worker-mcp
+
+An MCP server that runs the Google Antigravity CLI (`agy`) as an asynchronous
+worker agent, callable from Claude Code, Codex, and any other MCP client.
+
+> [!NOTE]
+> **Unofficial.** agy-worker-mcp is an independent, third-party MCP server. It is not affiliated with, endorsed by, or supported by Google. "Google", "Antigravity", "Gemini", and the `agy` command name are trademarks or product names of Google LLC and are used here only to identify the CLI this server drives. See [Trademarks and terms](#trademarks-and-terms).
+
+Jobs are detached from the client that started them: a job's process outlives
+the MCP connection, its stdout/stderr are redirected to files rather than
+piped, and its state lives in a project-local SQLite database. Any client
+connected to the same project can start a job, watch it, take it over after its
+original caller disconnected, or resume its conversation later.
+
+How it keeps a job honest: every tool call `agy` makes passes through our own
+`PreToolUse` gate, which is the sole approval authority (`agy`'s own engine is
+off). What a job may do is set by two walls — the shipped profile, and a
+human-owned per-project ceiling file that lives outside the workspace — and a
+client request can only narrow within them. Allowed shell commands run without
+an OS sandbox by default, as under Claude Code; a project can put a write-only
+kernel boundary back with `sandbox: "seatbelt"`. `agy_ceiling`, the shipped
+`agy-ceiling` skill and the `/agy-ceiling` slash command let an agent or a user
+propose that ceiling from the project's denial history — and nothing writes
+the file without your approval. Version-by-version detail is in
+[`CHANGELOG.md`](./CHANGELOG.md).
+
+## Why detached jobs
+
+`agy` runs turns that take minutes to an hour. A plain stdio MCP server tied to
+one client's process would lose the job the moment that client disconnects, and
+would give a second client (Codex checking on a job Claude Code started) no way
+to see it. Detaching the process, redirecting its output to disk, and
+coordinating through SQLite makes the job durable and visible independent of
+who is currently connected.
+
+## The one fact that matters most
+
+**`agy`'s own exit code and status cannot be trusted.** A permission denial —
+and, on a job that runs sandboxed, an OS-sandbox block — surfaces as `exit 0`
+/ `status: SUCCESS`. `agy` itself does not know it was blocked, and will often
+report success after quietly failing or working around the block.
+
+Every result this server returns carries a broker-computed `outcome`, derived
+from actual events, exit status, and filesystem checks, kept deliberately
+separate from `agy`'s self-report (`agent_report`). Read `outcome` and
+`contract_status`; never `agent_report.status`.
+
+## Requirements
+
+- Node.js ≥ 22.5
+- The `agy` CLI on `PATH` (developed and measured against agy 1.1.24–1.1.27).
+  `agy_capabilities` tells you whether the server can find it.
+
+## Install
+
+```bash
+npm install -g agy-worker-mcp
+```
+
+That puts `agy-worker-mcp`, `agy-worker-setup` and the two helper binaries
+(`agy-worker-runner`, `agy-worker-gate`) on your `PATH`. No global install:
+`npx -y agy-worker-mcp@latest` runs the server and
+`npx -y -p agy-worker-mcp agy-worker-setup` runs the setup below.
+
+Register it — Claude Code, project-scoped, which is easy to undo and affects
+nothing else:
+
+```bash
+claude mcp add agy --scope project -- agy-worker-mcp
+```
+
+Then, in the project where you use it, drop in the Claude Code pieces (the
+`agy-ceiling` skill and the `/agy-ceiling` slash command — npm cannot put
+files into `.claude/` for you, and this package refuses to write there
+unasked):
+
+```bash
+agy-worker-setup                # → ./.claude/skills, ./.claude/commands
+agy-worker-setup --scope user   # → ~/.claude/…, once for every project
+```
+
+It never overwrites an existing file unless you pass `--force`, and `--dry-run`
+shows the plan.
+
+Codex (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.agy]
+command = "agy-worker-mcp"
+```
+
+<details>
+<summary>From GitHub or a clone instead</summary>
+
+```bash
+npm install -g github:thezoot3/agy-worker-mcp   # builds on install (prepare)
+```
+
+```bash
+git clone https://github.com/thezoot3/agy-worker-mcp.git
+cd agy-worker-mcp
+npm install          # `prepare` builds dist/ for you
+claude mcp add agy --scope project -- node "$PWD/dist/server.js"
+```
+
+Registering by absolute path means the server runs whatever is in `dist/` —
+re-run `npm run build` after editing `src/`.
+</details>
+
+Check the registration with `claude mcp list`, and remove it with
+`claude mcp remove agy --scope project`.
+
+The server discovers the project root by walking up from its `cwd` to a git
+root, or honors `AGY_WORKER_PROJECT` as an override. Per-project state lives
+under `~/.agy-worker/projects/<hash>/` — never inside your repository, so
+nothing here needs a `.gitignore` entry.
+
+## Quick start
+
+```
+agy_capabilities                       -- profiles, models, discovered root
+agy_start { prompt, profile }          -- returns job_id immediately
+agy_wait  { job_id, wait_ms }          -- loop until lifecycle == "finished"
+agy_result { job_id, section }         -- verdict, verification, response text
+agy_logs  { job_id }                   -- only if you want the stream itself
+```
+
+`agy_start` with `dry_run: true` resolves configuration and policy without
+spawning `agy`, so you can settle permissions before spending quota.
+
+Need a job to see a toolchain that lives outside the workspace — `./gradlew`
+reading `~/.jdks`, say? Add it to the project's own permission ceiling file
+(`~/.agy-worker/projects/<hash>/policy.json`, `agy_capabilities.ceiling.path`
+tells you the exact path), then ask for it in `agy_start`:
+
+```json
+// ~/.agy-worker/projects/<hash>/policy.json
+{ "version": 2, "read_roots": ["~/.jdks"] }
+```
+
+```
+agy_start { profile: "general_worker", permissions: { read_roots: ["~/.jdks"] }, ... }
+```
+
+Without the matching ceiling entry, `read_roots` in the request is
+dropped and reported in `rejected_read_roots` — see
+[`docs/permissions.md`](./docs/permissions.md) for the full model.
+
+When a job comes back `blocked`, `agy_result`'s `verification.blockers[]` says
+who refused. Each entry carries `actionable` (can a different `agy_start` lift
+it) and `remedy` (what to change — for our own gate, the rule string the
+effective allow list was missing). `actionable: false` means no `agy_start`
+argument will help: the command tried to leave the workspace, the rule is not
+in the project ceiling, or the ceiling forces the sandbox on — each of those is
+a human editing `policy.json`, or a different command.
+
+## Tools
+
+| Tool | Role |
+| --- | --- |
+| `agy_start` | Start a job, return `job_id` immediately. |
+| `agy_wait` | Long-poll until the job **finishes** or `wait_ms` runs out. Returns a compact judgement packet, not logs. |
+| `agy_result` | Full, paged result: broker verdict, agent self-report, verification. |
+| `agy_logs` | Raw or normalized event stream, by byte cursor or tail. |
+| `agy_send` | Queue a follow-up turn on a session-mode job. Cannot interrupt a running turn. |
+| `agy_cancel` | Kill a running job and its whole process group. |
+| `agy_list_jobs` | Running and recently finished jobs in this project. |
+| `agy_sessions` | List, inspect, or close `agy` conversations. |
+| `agy_capabilities` | Models, profiles, the project ceiling as loaded, limits, discovered project root, server version. |
+| `agy_ceiling` | Read-only: the ceiling, the effective policy, denial history, and a review of a draft ceiling. Never writes. |
+
+Parameter-level detail, the `outcome` vocabulary, and the two "blocked" classes
+are in [`docs/tools.md`](./docs/tools.md).
+
+## Permissions
+
+Every tool call `agy` makes passes through our own `PreToolUse` hook, which
+decides allow/deny and OS-sandbox bypass on every single call — `agy`'s own
+approval engine is disabled for every job (0.2.0), so our gate is the sole
+authority. Three owners set the rules, each able to do one thing to the layer
+below it: **code** (hard denies, the two shipped profiles — fixed), the
+**project's own ceiling file** (`~/.agy-worker/projects/<hash>/policy.json`,
+outside the workspace — widens what a job may ever ask for), and **the parent
+agent's `agy_start.permissions`** (narrows within that ceiling, never widens
+it).
+
+Two profiles ship today:
+
+- **`research_readonly`** (default) — read-only workspace access and shallow
+  `git` inspection. No writes, no interpreters.
+- **`general_worker`** — read/write inside the workspace, `git`, `pytest`, and
+  the common build commands (`./gradlew`, `gradle`, `mvn`, `npm test`,
+  `npm run`, `javac`, `java`). `git push`, `curl`, package installs, `rm -rf`, and `sudo`
+  are denied by default — a project ceiling's `exceptions` can lift them, a
+  client request never can — and an action that
+  matches nothing is **denied**, never delegated to `agy`'s own engine — a
+  bound job's gate never answers "ask".
+
+Client-requested permissions can only **narrow** the ceiling: `allow` is
+intersected with it, `deny` always wins, `sandbox: "seatbelt" | "agy"` raises the OS
+sandbox on for the job, and `read_roots` (extra `--add-dir` roots for a
+toolchain outside the workspace) is intersected with the ceiling's own list.
+
+The OS sandbox is **off** for allowed commands on `general_worker` (0.2.1) —
+the gate's string match, not the kernel, is what bounds an allowed command,
+same as Claude Code. It stays on for `research_readonly`, and a project can
+force it on for every job with `sandbox: "agy"` in its ceiling file; expect
+in-workspace builds, tests, and `git commit` to fail there on agy 1.1.24.
+
+`agy_start` reports what the ceiling did to your request —
+`policy_summary` (`allow_count`, `bypass_sandbox`, `sandbox_forced_by`) and a
+`source: "policy_ceiling"` blocker per rejected rule. Watch for
+`allow_count: 0`: a fully rejected `allow` request collapses the effective
+list to empty and takes the profile's own defaults with it.
+
+Full model — the three owners, the ceiling file schema, the gate's decision
+order, containment, `verify_command`, and denial recovery — is in
+[`docs/permissions.md`](./docs/permissions.md).
+
+### Proposing a ceiling (skill)
+
+The package ships a Claude Code skill, `skills/agy-ceiling/SKILL.md`, that
+walks the parent agent through drafting a project ceiling from denial history
+and the repository, validating it with `agy_ceiling`, and showing it to you —
+and that forbids writing the file without your explicit approval of that
+draft. The server has no code path that writes the ceiling at all; the skill is
+the second wall.
+
+For the case where *you* want the ceiling, not the agent, there is a slash
+command, `commands/agy-ceiling.md`: `/agy-ceiling cargo build, git push` runs
+the same procedure on demand, seeded with the commands you name, and still
+stops for your answer before writing. `agy-worker-setup` installs both (see
+[Install](#install)); by hand it is a copy:
+
+```bash
+cp -R "$(npm root -g)/agy-worker-mcp/skills/agy-ceiling" .claude/skills/
+cp "$(npm root -g)/agy-worker-mcp/commands/agy-ceiling.md" .claude/commands/
+```
+
+## Documentation
+
+- [`docs/tools.md`](./docs/tools.md) — the ten tools, parameter by parameter,
+  and the result vocabulary
+- [`docs/permissions.md`](./docs/permissions.md) — the three-owner permission
+  model, the ceiling file, the gate's decision order, containment,
+  `verify_command`, denial recovery
+- [`docs/operations.md`](./docs/operations.md) — state layout, lifecycle, locks,
+  timeouts, retention, test suites
+- [`CHANGELOG.md`](./CHANGELOG.md) — what changed in each version
+
+## Development
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # vitest, against test/fake-agy — never the real agy binary
+npm run build       # emits dist/server.js, dist/runner.js, dist/gate.js, dist/setup.js
+```
+
+`npm test` and CI run exclusively against the scripted fake in
+[`test/fake-agy/`](./test/fake-agy); the real `agy` CLI is never invoked there,
+since every invocation spends real quota. The real binary is exercised only by
+the opt-in live suite:
+
+```bash
+npm run test:live   # spends real agy quota
+```
+
+## Trademarks and terms
+
+agy-worker-mcp is an unofficial third-party integration; the name describes what
+it drives, not who made it. Google, Antigravity, Gemini, and `agy` are Google LLC
+trademarks; no license to those marks is granted or implied by this package.
+
+This package launches the unmodified, officially installed `agy` binary as a
+local subprocess on the user's own machine, using documented command-line flags
+only (`--print`, `--output-format`, `--add-dir`, `--model`, `--effort`,
+`--print-timeout`, `--dangerously-skip-permissions`) and the documented
+`.agents/hooks.json` PreToolUse hook mechanism. Authentication stays entirely
+inside `agy` (the user's own `agy` login); this package never reads, stores,
+proxies, or forwards Antigravity credentials or tokens and never calls
+Antigravity or Gemini backends itself. Model calls run inside agy's own harness,
+and every job is charged to the user's own Antigravity plan quota. Multiple jobs
+in parallel (limit `max_running_jobs`) consume quota faster than an interactive
+session; keep parallelism modest.
+
+Using this package means running agy under your own account. You are responsible
+for complying with the [Google Antigravity Additional Terms of Service](https://antigravity.google/terms/)
+and the [Antigravity FAQ on third-party tools](https://antigravity.google/docs/faq/).
+Google's terms forbid using third-party software with an Antigravity login to
+reach the models outside the official product, and Google has suspended accounts
+for that. This package is designed to stay on the "spawn the official CLI" side
+of that line, but the authors make no representation that Google agrees, and
+Google may change its terms. Users needing a different harness should use a
+Vertex AI or AI Studio API key as Google's FAQ suggests.
+
+Provided "as is" under the [MIT license](#license); no warranty regarding
+compliance with any third-party terms.
+
+## License
+
+MIT

package/commands/agy-ceiling.md

@@ -0,0 +1,31 @@
+---
+description: Draft this project's agy-worker permission ceiling (policy.json) from denial history and the repo, review it with me, and write it only after I approve
+argument-hint: [commands the jobs will need, e.g. "cargo build, make test, git push"]
+---
+
+Draft the agy-worker-mcp project ceiling for this repository and write it only after I approve the draft you show me.
+
+Context I am giving you: $ARGUMENTS
+
+Do this, in order:
+
+1. Call `agy_ceiling` with no arguments. Note `path`, whether the file is `present`, the current `ceiling`, the `effective` allow/deny/hard_deny lists, and `history.denied_rules` (what past jobs were refused, how often).
+2. Read this repository to learn what a job here actually runs: build files, test runners, `package.json` scripts, `Makefile`, `Cargo.toml`, `build.gradle*`, `pyproject.toml`, CI config. Fold in the commands I listed above, if any.
+3. Write a `version: 2` draft:
+   - `allow`: build/test/read commands the profile does not already allow (`agy_ceiling` marks duplicates).
+   - `exceptions`: only rules the profile denies that the task genuinely needs (`git push`, `npm install`, `curl`, …). One line of rationale each. Never `HARD_DENY` rules.
+   - `read_roots`: toolchains outside the workspace a job must read (`~/.gradle`, `~/.jdks`, …).
+   - `write_roots`: only if a sandboxed build must write outside the workspace.
+   - `sandbox`: leave `"none"` unless I asked for `"seatbelt"` or `"agy"`.
+   - Never set `command_policy: "denylist"` unless I explicitly asked for it.
+4. Call `agy_ceiling({ draft, expected_commands })` with the draft and the commands from steps 1–2. Fix it until `review.ok` is true and every `expected_commands` entry you expect to run is `allow`. Keep the `review.rules[].risk` classes.
+5. Show me the complete file as a fenced JSON block (a diff against the current file if one exists), with one line of rationale per rule and the risk class beside every `exceptions` entry and every `network` / `install` / `destructive` / `privilege` rule.
+6. Ask me, in one line, whether to write it to `path`. Do not write before I answer. If I say yes, write exactly the shown JSON to that path and re-run `agy_ceiling()` to confirm it loads with no `warnings`. If I say no or change something, revise and show it again. If I want to write it myself, give me:
+
+```sh
+cat > <path> <<'JSON'
+<the approved JSON>
+JSON
+```
+
+Rules that do not bend: the server has no code path that writes this file, and neither do you without my in-conversation "yes" to the exact draft shown. `exceptions` and `command_policy: "denylist"` widen what an unattended job can do to the network, remote repositories, and the filesystem — call that out when you show them.

package/dist/broker/blockers.d.ts

@@ -0,0 +1,86 @@
+import type { ArtifactCheck, Blocker, DenialClass1, DenialClass2, EffectivePolicy, GateLogEntry, PolicySummary } from '../contract/types.js';
+/**
+ * Whether a non-gate refusal came from agy's own permission engine.
+ *
+ * Substring match against measured wording, the same technique `detectClass2`
+ * uses on environment blocks and for the same reason: agy emits no structured
+ * field saying who refused.
+ */
+export declare function isAgyEngineRefusal(message: string): boolean;
+/**
+ * A Class 1 event → the blocker it actually is.
+ *
+ * Three outcomes, because three different next actions: our gate refused
+ * (fixable with a rule), agy's own engine refused (nothing of ours applies), or
+ * a command simply failed (not a permission matter at all).
+ */
+export declare function blockerFromDenial(d: DenialClass1): Blocker;
+/** A Class 2 signature match. Recovery depends on whether and why the job ran sandboxed. */
+export declare function blockerFromEnvironmentBlock(b: DenialClass2, policy?: EffectivePolicy | null): Blocker;
+/**
+ * I4: the runner's own gate watchdog
+ * killed the job because `jobs/<id>/gate-log.jsonl` never received a line
+ * within 3s of the first tool step — our PreToolUse hook never actually ran,
+ * so nothing before the kill was policy-checked at all. Never actionable — no
+ * `permissions.allow` entry fixes a hook that never loaded — and
+ * `decideOutcome` forces `outcome: 'process_error'` for this directly, not
+ * merely `blocked`, since `blocked` would imply the gate ran and refused.
+ */
+export declare function blockerFromGateMissing(): Blocker;
+/** A broker-side check that failed. Today that is only a missing expected artifact. */
+export declare function blockerFromMissingArtifact(a: ArtifactCheck): Blocker;
+/**
+ * Build blockers from gate-log entries.
+ *
+ * When an entry carries `abort_reason: 'max_denials'`, emit an extra blocker
+ * reporting that the job was aborted after reaching the denial limit.
+ */
+export declare function blockersFromGateLog(log: string | readonly GateLogEntry[]): Blocker[];
+/**
+ * The "no project ceiling" line for a finished job, or null. Said only when a
+ * gate blocker's remedy is a rule string — exactly what a ceiling `allow` /
+ * `exceptions` entry would open — and the policy recorded that no ceiling
+ * file existed. A foreign hook's denial (no rule), containment, unsupported
+ * tools and sandbox blocks are not the ceiling's business, so they stay quiet.
+ * Legacy job files without `ceiling_present` never trigger it.
+ */
+export declare function ceilingAbsenceWarning(policy: EffectivePolicy | null | undefined, blockers: readonly Blocker[]): string | null;
+/**
+ * Pre-flight blockers from a resolved policy: every `permissions.allow` entry
+ * the profile ceiling refused, every `permissions.read_roots` entry the
+ * human ceiling refused, plus the collapse case.
+ *
+ * `blocks_outcome` is false throughout — there is no job yet, so there is no
+ * outcome to block; these never reach `verification`.
+ */
+export declare function policyCeilingBlockers(policy: EffectivePolicy): Blocker[];
+/**
+ * One warning line per blocker. The only renderer — a caller must never have to
+ * infer "can I fix this" from prose wording.
+ */
+export declare function renderBlocker(b: Blocker): string;
+export declare function renderBlockers(blockers: Blocker[]): string[];
+/**
+ * `1 gate denial (actionable), 1 sandbox block` — grouped by source, in first
+ * appearance order, so a headline says who refused without listing everything.
+ */
+export declare function summarizeBlockers(blockers: Blocker[]): string;
+export declare function countActionable(blockers: Blocker[]): number;
+/** The single predicate `outcome` is decided by. */
+export declare function hasOutcomeBlocker(blockers: Blocker[]): boolean;
+/** What `agy_start` reports back about the policy it just resolved. */
+export interface PolicyDescription {
+    policy_summary: PolicySummary;
+    blockers: Blocker[];
+    warnings: string[];
+}
+/**
+ * Describe a resolved policy in the same vocabulary a finished job is judged
+ * in, for both the `dry_run` and the real `agy_start` reply.
+ *
+ * Built in one place so the two replies cannot drift: before 0.1.1 the real
+ * reply said nothing at all about permissions, and a caller whose
+ * `permissions.allow` had been rejected wholesale had no way to notice.
+ */
+export declare function describePolicy(policy: EffectivePolicy): PolicyDescription;
+//# sourceMappingURL=blockers.d.ts.map

package/dist/broker/blockers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockers.d.ts","sourceRoot":"","sources":["../../src/broker/blockers.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,aAAa,EACb,OAAO,EAEP,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EACd,MAAM,sBAAsB,CAAA;AA6C7B;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3D;AAMD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CA2D1D;AAED,4FAA4F;AAC5F,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CA6DrG;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAUhD;AAED,uFAAuF;AACvF,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAWpE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,YAAY,EAAE,GAAG,OAAO,EAAE,CAoCpF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,GAAG,IAAI,CAI7H;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,EAAE,CA8CxE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAMhD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAE5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAoB7D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAE3D;AAED,oDAAoD;AACpD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAE9D;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,aAAa,CAAA;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CAgBzE"}