pitroom 0.15.0 → 0.17.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pitroom",
   "description": "A free pit crew for your expensive coding agent: the superpowers development workflow, run by cheap workers. Delegate research, fixes, tests, reviews and whole plans from Claude Code, Codex or any agent to OpenCode, Codex or Claude Code workers, with receipts that prove the savings.",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "author": {
     "name": "TahaAtas"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pitroom",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "A free pit crew for your expensive coding agent: delegate research, fixes, tests, reviews and parallel investigations to cheap worker agents running your own models, with verified answers, exact diffs and cost receipts.",
   "author": {
     "name": "TahaAtas"

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.17.0
+
+### Answer cache
+- The same read question on the same code gets the earlier answer back at once instead of a new worker run (`pitroom ⟲ cached answer · … · no worker ran`). The key is the question (whitespace does not count), where it was asked, the attached files' contents, where the worker reads (a clean snapshot or in place) and the project's exact state: HEAD and a tree of every working file, uncommitted and untracked included (made with git's own index, so unchanged files are not re-hashed). Only answers that held up are reused: a finished read run with an answer, every reference verified, nothing written, and no audit still running or disagreeing, for `cacheDays` (default 7; 0 turns it off; `PITROOM_CACHE_DAYS`). Follow-ups, web runs, plan tasks, reviews, audits, `--audit`, `--verify`, crews and changes are never cached; `--fresh` asks a worker anyway and its answer is reused from then on. Git-ignored files and the worker/model are not part of the key (documented; `--fresh` for those). With `--bg --json` the earlier run comes back already done, marked `"cached": true`.
+
+### MCP server
+- **Smaller tool definitions.** Ten tools instead of eighteen, nothing lost: parallel work is `pitroom_run` with `tasks` (was `pitroom_crew`), every report is `pitroom_info` with a `topic` (`runs`, `history`, `stats`, `savings`, `models`, `cooldown`, `config` (new), `doctor`; were seven tools), `pitroom_show` gives a running run's progress (was `pitroom_status`, and `run` now defaults to the latest), and `pitroom_stop` with `cooldowns` clears the cooldowns. Descriptions are shorter. The definitions sit in the client's context for the whole session: about 1.9k tokens now, 3.3k before. An option that does not go with a topic is an error that names the ones that do.
+- **Run notifications.** A client can subscribe to a run's resource (`resources/subscribe` on `pitroom://run/<id>` or its `/patch`) and is told when the run changes state (for `/patch` also when it changed more files) or is gone (`notifications/resources/updated`); every client is told when the newest run changes (`notifications/resources/list_changed`; runs starting within one check are one notification). Read from the run records every 2 s, only while a client can be told; at most 100 subscriptions per client. An event stream nobody uses (no request, no event for an hour) is closed with its session. Over HTTP a GET with `Accept: text/event-stream` opens the session's event stream, where these arrive (one stream per session, kept alive with comments); a client without one is told once it opens it. Few clients act on these yet; the tools work the same without them.
+
+### Fixes
+- `pitroom review` in a linked git worktree: the review package was written to the worktree's git directory, which lies outside the worktree, and a sandboxed reviewer (OpenCode) was refused reading it, so the review had nothing to review. There it now goes to `<worktree>/.pitroom/` (added once to the repository's `info/exclude`, so `git status` stays clean) and is removed when the review ends. Found by having Pitroom review its own branches from a worktree.
+
+### MCP Registry
+- `server.json` describes Pitroom for the [MCP Registry](https://registry.modelcontextprotocol.io) (`io.github.ATASTECH/pitroom`: the npm package, stdio, `pitroom mcp`), and `package.json` has the `mcpName` the registry checks. `npm run bump` keeps its version in step, and turns an `## Unreleased` CHANGELOG section into the version's entry.
+
+### From real-world tests (Codex driving Pitroom over MCP)
+- **`--verify` under an MCP client.** An app that starts Pitroom often passes a bare `PATH`, and `npm test` was "command not found" (exit 127). The verify command now also finds the Node running Pitroom (npm and npx sit next to it) and the usual install places, after your own `PATH`; a command that still is not found is reported as "could not run (exit 127: command not found)" with what to do, not as a failing test.
+- **A failed `--verify` is no longer shown as success.** The report says `⚠ done · verify failed` instead of `✔ done`, an MCP result is an error (`isError`, as is a read-only violation), and the dashboard shows a warning icon on the card and lists the run under **Needs attention**.
+- **Audits check the question, not only the references.** The auditor must check every condition the question sets (scope, exclusions, "all", "only", counts), look for missing and extra items in a list and recount a count; AGREE needs all of them. In the tests an answer that listed 8 files outside the asked directory got AGREE from two of three auditors, because its references were valid.
+- **Skills over MCP.** An agent using the MCP tools did not think of Pitroom's skills. The server's instructions now name them and say to use the matching one, `pitroom_run` points to `using-pitroom`, and every skill is also a prompt of the same name (its text, with how the CLI commands in it map to the tools), for clients that have no skills.
+- **`pitroom review --range A..B` shows the branch's own change**, from where it left A, as a pull request does. When A had moved on since (another PR merged), the diff also showed A's newer commits as if the branch undid them.
+- An OpenCode model answering "Endpoint is unavailable" (HTTP 400) is treated as rate-limited: it cools down and the next worker runs (this already worked; it now has a test).
+
+## 0.16.0
+
+### MCP server
+- **Progress notifications.** A call that waits for a run reports how it is doing every few seconds (`notifications/progress`, when the client sent a progress token), so the agent sees what the worker is doing; a client that resets its timeout when progress comes in (the protocol allows it, not every client does) does not give up on a long run.
+- **Cancellation.** A client that cancels `pitroom_run`, `pitroom_crew`, `pitroom_review` or `pitroom_audit` (`notifications/cancelled`) stops the run or group it started and gets no answer, as the protocol says; a cancelled `pitroom_wait` only stops waiting. A client that sends its requests and closes the pipe still gets the answers.
+- **Resources.** The latest runs are resources, `pitroom://run/<id>` (the report) and `pitroom://run/<id>/patch` (the exact diff), with resource templates; anything else is "not found" (-32002).
+- **Prompts.** `research`, `implement`, `review` and `crew`, with their arguments checked.
+- **Nine new tools** (18 in all): `pitroom_crew` (independent tasks in parallel as one group), `pitroom_list`, `pitroom_history` (search earlier answers), `pitroom_stats`, `pitroom_savings`, `pitroom_models`, `pitroom_cooldown`, `pitroom_doctor` and `pitroom_revert` (undo a write run); `pitroom_run` takes `continue` for a follow-up in the same worker session, and `pitroom_apply` can apply a group.
+- **HTTP transport.** `pitroom mcp --http [--port N]` serves the same server over Streamable HTTP at `http://127.0.0.1:7117/mcp`, for clients that connect to a URL. Local by construction: 127.0.0.1 only, a bearer token (generated on first start into `<state dir>/mcp-token`, mode 0600, or `PITROOM_MCP_TOKEN`; compared in constant time), and a Host or Origin that is not local is refused with 403 (DNS rebinding). Sessions per client (`Mcp-Session-Id`), so a cancel only touches the cancelling client's request even when two clients use the same request id; a call that sends a progress token is answered as an event stream. Ending a session (DELETE) or stopping the server ends the waiting, not the runs. When 64 sessions are open, the one unused longest makes room for a new one. Checked with the real Claude Code client (`claude mcp add --transport http …`, `claude mcp list`: connected).
+- `pitroom mcp -d DIR` (stdio or HTTP) works in that project, for clients such as Claude Desktop that start the server somewhere else; `--port` without `--http` is a usage error.
+- The server is split into protocol (`mcp.ts`), tools (`mcp-tools.ts`), resources and prompts (`mcp-extras.ts`) and what they share (`mcp-support.ts`).
+
 ## 0.15.0
 
 ### `pitroom install --mcp`

package/README.md

@@ -273,7 +273,7 @@ npm i -g pitroom
 
 **Any agent that speaks MCP (Cursor, Claude Desktop, and the three above too)**
 
-Pitroom is also an [MCP](https://modelcontextprotocol.io) server on stdio: nine tools (`pitroom_run`, `pitroom_wait`, `pitroom_status`, `pitroom_show`, `pitroom_review`, `pitroom_audit`, `pitroom_apply`, `pitroom_discard`, `pitroom_stop`) instead of shell commands and skills. After `npm i -g pitroom`, let Pitroom register itself in the clients it finds (Claude Code, Codex, Gemini CLI, Cursor, Claude Desktop):
+Pitroom is also an [MCP](https://modelcontextprotocol.io) server on stdio: ten tools instead of shell commands and skills (`pitroom_run`, `pitroom_wait`, `pitroom_show`, `pitroom_info`, `pitroom_review`, `pitroom_audit`, `pitroom_apply`, `pitroom_discard`, `pitroom_revert`, `pitroom_stop`), the runs as resources, and four prompts. The tool definitions sit in the client's context for the whole session, so they are kept small: about 1.9k tokens. After `npm i -g pitroom`, let Pitroom register itself in the clients it finds (Claude Code, Codex, Gemini CLI, Cursor, Claude Desktop):
 
 ```bash
 pitroom install --mcp               # also links the skills; add --no-skills to skip that
@@ -295,7 +295,13 @@ or, for Cursor (`~/.cursor/mcp.json`), Claude Desktop (`claude_desktop_config.js
 { "mcpServers": { "pitroom": { "command": "pitroom", "args": ["mcp"] } } }
 ```
 
-Each tool runs the matching `pitroom` command, so every rule of the CLI applies unchanged (permission profiles, git guard, isolation, read snapshots). A run is waited for up to `waitSeconds` (default 50), then comes back as "still running" with its id for `pitroom_wait`; keep it below your client's tool timeout. The server works in the directory the client starts it in.
+Each tool runs the matching `pitroom` command, so every rule of the CLI applies unchanged (permission profiles, git guard, isolation, read snapshots). A run is waited for up to `waitSeconds` (default 50), then comes back as "still running" with its id for `pitroom_wait`; keep it below your client's tool timeout. The server works in the directory it is started in: the client's for stdio, or the one `-d DIR` names (Claude Desktop starts it elsewhere, so give it `"args": ["mcp", "-d", "/path/to/project"]`); the tools' `dir` argument picks another per call.
+
+- **Progress.** While a call waits for a run, a client that sent a progress token gets a `notifications/progress` every few seconds ("running · read · 12s · 3 steps, 2 tool calls · last: …"), and a client that resets its timeout when progress comes in (the protocol allows it; not every client does) does not give up on a long run. **Cancelling** a `pitroom_run`, `pitroom_review` or `pitroom_audit` call stops the run it started (a cancelled `pitroom_wait` only stops waiting).
+- **Resources.** The latest runs are listed as `pitroom://run/<id>` (the report) and, for runs that changed files, `pitroom://run/<id>/patch` (the exact diff), so a client can attach one to a conversation. A client can **subscribe** to a run (`resources/subscribe`) and is told when it changes state (`notifications/resources/updated`), and every client is told when the newest run changes (`notifications/resources/list_changed`), so it need not poll; over HTTP these arrive on the session's event stream (a GET).
+- **Prompts.** `research`, `implement`, `review` and `crew` say how to use Pitroom for that job (in Claude Code they appear as `/mcp__pitroom__research`, …), and every skill is a prompt of the same name (`using-pitroom`, `pitroom-research`, …), so a client without skills gets the same guidance. The server's instructions tell the agent to use the skills alongside the tools.
+- **More than runs:** `pitroom_run` takes `tasks` (independent tasks in parallel, one worker each) and `continue` (a follow-up in the same worker session); `pitroom_info` reports without changing anything, by `topic`: `runs`, `history` (find an earlier answer before asking again), `stats` and `models` (pick a worker), `savings`, `cooldown`, `config`, `doctor`; `pitroom_stop` with `cooldowns` tries rate-limited models again.
+- **Over HTTP.** `pitroom mcp --http [--port N]` (default 7117) serves the same tools at `http://127.0.0.1:7117/mcp` for clients that connect to a URL, for example `claude mcp add --transport http pitroom http://127.0.0.1:7117/mcp --header "Authorization: Bearer $(cat ~/.local/state/pitroom/mcp-token)"` (the command is printed when it starts). It is a local service: it listens on 127.0.0.1 only, needs the bearer token (made on first start, kept at `<state dir>/mcp-token` with owner-only permissions, or set with `PITROOM_MCP_TOKEN`), and refuses a Host or Origin that is not local, so a web page cannot use it. Anyone who has the token can run workers as you, so keep it private. It works in the directory it was started in (printed when it starts; `-d DIR` for another). Each client has its own session; a call that asks for progress is answered as an event stream. Ending a session or stopping the server ends the waiting, not the runs: collect them with `pitroom_wait` or the CLI. `pitroom install --mcp` registers the stdio command, which needs no token and no running process.
 
 **Any other agent (a plain shell) or just the CLI**
 
@@ -367,6 +373,8 @@ pitroom uninstall && npm rm -g pitroom
 
 **Read snapshots.** With secret-looking files in the directory, a read run reads a snapshot of your project's current state (uncommitted and untracked files included) without them and without git-ignored files, made from git objects, kept once per state and shared by every read run on it (twenty workers, one snapshot), and cleaned up after three days or by `pitroom clean`. Nothing is copied back: a read run has nothing to land. Its files are read-only, and the paths a worker cites are turned back into your project's. With no secret-looking files nothing changes: the worker runs in place. `--in-place` (or `"readIn": "project"` in the config) reads the directory itself, e.g. for a task that needs build output; `"readIn": "snapshot"` always uses one.
 
+**Answer cache.** Ask the same read question on the same code and you get the earlier answer back at once, with no worker run: `pitroom ⟲ cached answer · the same question on the same code as run … · no worker ran`. "The same code" is exact: the commit and every working file, uncommitted and untracked ones included (git-ignored files are not code), so any edit makes it a new question. Only answers that held up are reused (the run finished, every file:line reference checked out, no audit disputed it) and only for 7 days (`"cacheDays"` in the config, `0` turns it off, or `PITROOM_CACHE_DAYS`). Follow-ups, web runs, plan tasks, reviews, audits, `--verify` runs, parallel work (crews) and changes are never answered from the cache, and `--fresh` asks a worker anyway (its answer is the one reused from then on). Not part of "the same code": git-ignored files (build output, installed dependencies) and the worker or model that answered; when a question depends on them, use `--fresh`.
+
 ```bash
 pitroom run "Find every place we build SQL strings by hand; file:line and risk"
 pitroom run -i --link node_modules --verify "npm test" "Fix the off-by-one in paginate() and add a test"
@@ -490,7 +498,7 @@ pitroom crew [-i] [-g NAME] "task 1" "task 2" …   (or --task-file with --- sep
 pitroom run -i --plan PLAN --step N [--tier T] ["notes"]
 pitroom review [run | --range A..B [--plan PLAN]] [--tier T | -W T] [--bg]
 pitroom audit RUN [-W worker]
-pitroom mcp                  # serve Pitroom as MCP tools on stdio
+pitroom mcp [-d DIR] [--http [--port N]]   # serve Pitroom as MCP tools on stdio, or over HTTP on 127.0.0.1 (bearer token)
 pitroom cooldown [--clear]
 pitroom plan status PLAN [--json] · pitroom plan note PLAN "Task N: …"
 pitroom status|wait|watch [run… | -g NAME]        wait: --any --brief --timeout · watch: --json|--brief --interval