pitroom 0.6.9 → 0.7.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.6.9",
+  "version": "0.7.0",
   "author": {
     "name": "TahaAtas"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pitroom",
-  "version": "0.6.9",
+  "version": "0.7.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"
@@ -19,6 +19,7 @@
     "workflow"
   ],
   "skills": "./skills/",
+  "hooks": "./hooks/codex-hooks.json",
   "interface": {
     "displayName": "Pitroom",
     "shortDescription": "Cheap workers for your agent",

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.7.0
+
+### Codex
+- The Codex plugin registers hooks (`hooks/codex-hooks.json`, named in `.codex-plugin/plugin.json`): Pitroom is introduced at session start, so the agent knows it even when Codex drops skill descriptions because many skills are installed, and a job card follows each `pitroom` command. Codex asks you to trust the plugin's hooks once. The hooks go through `pitroom` on PATH (`pitroom hook-start` is new) and stay silent when it is missing. Checked against Codex 0.159.
+
+### CLI
+- `pitroom init` proposes a starter config from the worker CLIs and OpenCode models you have: a fallback chain from your free models, tiers when more than one CLI is installed. It never picks your model, and writes only with `--yes` (`--force` to replace a file, which is kept as `.bak`).
+- `pitroom doctor` groups its checks (Setup, Worker chain, one section per worker CLI, Skills and agents), ends with one verdict line and a Next list of the commands the findings point to, and warns when the first `node` on PATH is too old. Colour only on a terminal (`NO_COLOR` and `FORCE_COLOR` are honoured); `ls`, `status`, `history` and run reports colour the state too.
+- The `pitroom` command is now a small launcher that finds a Node 22.13+ (`PITROOM_NODE`, nvm, Homebrew, `/usr/local`) when the shell's own `node` is old, instead of crashing with a syntax error; without one it says how to fix it.
+- A timed-out run's report says what to do: raise the limit with `-t` (or `PITROOM_TIMEOUT`) for a long job, or `--continue`.
+
+### One figure for savings
+- The Stats tab (and `pitroom history stats`) takes its saved figures, total, per worker and per day, from the ledger, the same ones the Live tab, `pitroom savings` and the status line add up. They used to be calculated twice and could differ.
+- A run that finished while another process was marking it as crashed no longer loses its usage and savings.
+
+### Dashboard
+- Cards name the model the worker really ran (what the CLI reported), not just `opencode`; terminal cards do too.
+- The close button closes the card (its click used to bubble into the card's open handler and re-open it). The step list scrolls by hand while a worker runs and follows new steps only while you are at the bottom.
+- A `#run-id` link opens that run as the same expandable card the lists use, pinned above the page, and clears the link when closed; `/api/run/:id` carries the card. A page opened in a background tab fetched nothing until shown: fixed.
+- The state icons explain themselves on hover and focus (a clock is a timeout).
+- No `NaN%` for a worker the history has no run for.
+
+## 0.6.10
+
+### Verified answers
+- A reference written as a bare file name or a partial path (`ipc.ts:218`, `src/main/ipc.ts:218`) is now looked up in the project, so it no longer counts as "file not found" just because the worker left out the directory. If several files match, one that holds up is enough.
+- A call written like a reference (`Schema.parse:432`, `orchestrator.start:638`) is not a file reference and is no longer counted. On a real run this turned "7/18 verified" into "13/13"; the references that really did not match are still reported.
+
+### Safety
+- A run warns when the directory its worker runs in holds `.env` files, private keys (`*.pem`, `id_rsa`…) or `credentials.json`: the worker is told not to read them, but nothing stops it. The warning is on the report and when a run starts with `--bg`. For `-i` it names only the files the isolated copy would contain (a git-ignored `.env` is not copied). `PITROOM_NO_SECRET_WARNING=1` silences it.
+
+### Smaller
+- OpenCode with no pinned model no longer warns about `--effort` on every run: there is nothing to attach the level to, so it is left out quietly.
+- A detached dashboard stops after an hour without a request (it was four hours).
+- Every run card shows its worker's logo, and its animated mascot while it runs; the skills tell the agent to open the dashboard in the app's own browser pane (not with `--open`, which launches the system browser).
+
 ## 0.6.9
 
 ### Dashboard

package/README.md

@@ -11,7 +11,7 @@ Model-agnostic · Verified answers · Receipts, not vibes · OpenCode / Codex /
 <br />
 
 [![Release](https://img.shields.io/github/v/release/ATASTECH/pitroom?label=release)](https://github.com/ATASTECH/pitroom/releases/latest)
-[![Downloads](https://img.shields.io/github/downloads/ATASTECH/pitroom/total?label=downloads)](https://github.com/ATASTECH/pitroom/releases)
+[![Downloads](https://img.shields.io/npm/dm/pitroom?label=npm%20downloads)](https://www.npmjs.com/package/pitroom)
 [![npm](https://img.shields.io/npm/v/pitroom?label=npm)](https://www.npmjs.com/package/pitroom)
 [![Stars](https://img.shields.io/github/stars/ATASTECH/pitroom?style=flat&label=stars)](https://github.com/ATASTECH/pitroom/stargazers)
 [![CI](https://github.com/ATASTECH/pitroom/actions/workflows/ci.yml/badge.svg)](https://github.com/ATASTECH/pitroom/actions/workflows/ci.yml)
@@ -82,7 +82,7 @@ One group can mix them, and a fallback chain can cross them ([how adapters work]
 
 ### Verified answers
 
-Every `path:line` a worker cites is checked on disk.
+Every `path:line` a worker cites is checked on disk. A cite without its directory (`ipc.ts:218`, `src/main/ipc.ts:218`) is found in the project, and a call such as `Schema.parse:432` is not mistaken for a file.
 
 Your agent trusts what checks out and skips re-reading it.
 
@@ -270,7 +270,7 @@ pitroom install
 | Path | You get |
 |---|---|
 | Claude Code plugin | The 14 skills, the session-start hook that introduces Pitroom, and a card after each `pitroom` command. |
-| Codex plugin | The 14 skills. Codex has no session-start hook, so Pitroom is not introduced on its own: the skills load when a task matches, or name one. `pitroom` itself comes from npm. |
+| Codex plugin | The 14 skills, a session-start hook that introduces Pitroom (so it is known even when Codex drops skill descriptions because many are installed), and a card after each `pitroom` command. Codex asks you to trust the plugin's hooks once. The hooks call `pitroom`, which comes from npm (`npm i -g pitroom`). |
 | npm + `pitroom install` | The CLI, and the skills linked into `~/.agents/skills` and `~/.claude/skills`. |
 
 Pick one path, not several: `doctor` warns if the skills load twice. The plugins alone do not put `pitroom` on your PATH, so install it from npm too if you want to run it yourself (`watch`, `models`, `savings`, the status line).
@@ -442,7 +442,7 @@ pitroom ls [--running] [-g NAME] · pitroom clean [--days 14] [--yes]
 pitroom savings [--since 7d|30d|all] [--models] [--card file.svg] [--badge]
 pitroom models [worker] [--all] [--json]      models, effort levels, your costs, your usage
 pitroom statusline [--then CMD] · pitroom hook-card
-pitroom doctor [--probe] · pitroom config · pitroom install [--copy] [--force] · pitroom uninstall
+pitroom doctor [--probe] · pitroom config · pitroom init [--model ID] [--fallback A,B] [--yes] [--force] · pitroom install [--copy] [--force] · pitroom uninstall
 ```
 
 Exit codes: `0` ok · `1` worker failed · `2` usage · `3` refused/setup · `4` timeout · `5` read-only violation · `6` verify failed · `75` still running.
@@ -476,7 +476,7 @@ Two settings make every delegation visible, whether or not the agent mentions it
 
 The Claude Code and Codex **apps** show neither hook messages nor a status line. For them there are two things that need no setup:
 
-- `pitroom dash --detach` prints the address of a live dashboard with three tabs: **Live** (every running and recent run as an animated card; click one for the task, what the worker did step by step, its result, the diff and the details), **History** (search and filter everything Pitroom ever ran; every run opens as the same card) and **Stats** (success rate, time, tokens and savings per worker and model). It is read-only, listens on `127.0.0.1` only and stops itself after four idle hours (`pitroom dash --stop` ends it sooner). Open it in a browser or in the app's own browser pane. The skills tell the agent to start it and give you the address when it runs workers in the background.
+- `pitroom dash --detach` prints the address of a live dashboard with three tabs: **Live** (every running and recent run as an animated card; click one for the task, what the worker did step by step, its result, the diff and the details), **History** (search and filter everything Pitroom ever ran; every run opens as the same card) and **Stats** (success rate, time, tokens and savings per worker and model). It is read-only, listens on `127.0.0.1` only and stops itself after an hour without a request (`pitroom dash --stop` ends it sooner). Open it in a browser or in the app's own browser pane. The skills tell the agent to start it and give you the address when it runs workers in the background.
 - `pitroom watch -g NAME --brief` prints one card line when a worker starts and one when it ends. In Claude Code, the agent runs it through the Monitor tool and the lines appear in the app; in Codex the command's output block fills as it goes.
 
 ---
@@ -546,11 +546,12 @@ Fallbacks cross backends (e.g. `"fallback": ["codex:#low", "opencode"]`): a work
 | `PITROOM_PRIMARY` | `sonnet` | Pricing preset for the savings estimate: `sonnet`, `opus`, `haiku`, `gpt-5` |
 | `PITROOM_PRICE` | | Custom primary price, USD per 1M tokens: `"in,out[,cachedIn]"` |
 | `PITROOM_HOME` | `~/.local/state/pitroom` | Where run records and the ledger live |
+| `PITROOM_NO_SECRET_WARNING` | | Set to `1` to stop the warning about `.env` files and private keys in the worker's directory |
 | `PITROOM_<WORKER>_BIN` | on PATH | Path to a worker CLI, e.g. `PITROOM_OPENCODE_BIN` |
 
 </details>
 
-Or put defaults in `~/.config/pitroom/config.json` (flags and env still win); `pitroom config` shows every effective value and where it came from. `models` gives each worker a default model for targets that name none (`-W codex`, a `"codex"` fallback); a model in the target or `-m` still wins. `tiers` names workers for `--tier` and for plan tasks' `**Worker:**` lines:
+Or put defaults in `~/.config/pitroom/config.json` (flags and env still win); `pitroom config` shows every effective value and where it came from. `pitroom init` proposes a starter config from the worker CLIs and OpenCode models you have (a fallback chain of your free models, tiers when more than one CLI is installed) and writes it only with `--yes`; it never picks your model for you. `models` gives each worker a default model for targets that name none (`-W codex`, a `"codex"` fallback); a model in the target or `-m` still wins. `tiers` names workers for `--tier` and for plan tasks' `**Worker:**` lines:
 
 ```json
 {
@@ -581,6 +582,8 @@ Or put defaults in `~/.config/pitroom/config.json` (flags and env still win); `p
 
 **Can the worker break my repo?** It can't touch git history, refs or your index (permission profile + git guard), can't run bulk deletes, and write-mode edits are revertible with one command. The guard is not an OS sandbox: git called by absolute path from inside a script, or non-git tools, are outside its reach, which is why `--isolate` exists: nothing reaches your tree until you apply it.
 
+**Can the worker read my `.env`?** In the directory it runs in, yes: its prompt says not to, and nothing stops it, and a free model may be hosted by a third party. Pitroom warns when it sees `.env` files, private keys or `credentials.json` there (`PITROOM_NO_SECRET_WARNING=1` silences it). An isolated copy (`-i`) leaves out git-ignored files, so a git-ignored `.env` is not in it; a clean checkout is the safest place for a first try.
+
 **What if the worker fails?** Pitroom exits non-zero with the real cause (for example a default model that no longer exists) and your agent simply continues on its own. `pitroom doctor` diagnoses setup problems.
 
 ---

package/bin/pitroom.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+'use strict';
+// The `pitroom` command. Plain ES5 so that even an old Node can run it: it finds a Node.js of 22.13 or newer
+// and runs dist/pitroom.mjs with it. Agent apps often run commands in a shell whose first `node` is an old one
+// (an installer's Node 14 in /usr/local/bin, say), where the real CLI would only crash with a syntax error.
+var cp = require('child_process');
+var fs = require('fs');
+var path = require('path');
+
+var MIN = [22, 13];
+var cli = path.join(__dirname, '..', 'dist', 'pitroom.mjs');
+
+function ok(v) {
+  return v[0] > MIN[0] || (v[0] === MIN[0] && v[1] >= MIN[1]);
+}
+function parse(text) {
+  var m = /(\d+)\.(\d+)\.(\d+)/.exec(String(text));
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function versionOf(bin) {
+  var r = cp.spawnSync(bin, ['-p', 'process.versions.node'], { encoding: 'utf8', timeout: 5000 });
+  return r.status === 0 ? parse(r.stdout) : null;
+}
+function newer(a, b) {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+// PITROOM_TEST_NODE_VERSION only lets the tests pretend this Node is old.
+var current = parse(process.env.PITROOM_TEST_NODE_VERSION || process.versions.node) || [0, 0, 0];
+var node = process.execPath;
+
+if (!ok(current)) {
+  node = null;
+  var candidates = [];
+  if (process.env.PITROOM_NODE) candidates.push(process.env.PITROOM_NODE);
+  // PITROOM_NODE_SEARCH (a path-delimited list) replaces the places searched below; the tests use it.
+  var nvm = path.join(process.env.NVM_DIR || path.join(process.env.HOME || '', '.nvm'), 'versions', 'node');
+  try {
+    candidates = candidates.concat(
+      fs.readdirSync(nvm).filter(function (d) { return /^v\d+\.\d+\.\d+$/.test(d); })
+        .sort(function (a, b) { return newer(parse(b), parse(a)); })
+        .map(function (d) { return path.join(nvm, d, 'bin', 'node'); }),
+    );
+  } catch (e) { /* no nvm */ }
+  candidates.push('/opt/homebrew/bin/node', '/usr/local/bin/node', '/usr/bin/node');
+  if (process.env.PITROOM_NODE_SEARCH !== undefined) candidates = process.env.PITROOM_NODE_SEARCH.split(path.delimiter).filter(Boolean);
+  for (var i = 0; i < candidates.length && !node; i++) {
+    if (!fs.existsSync(candidates[i])) continue;
+    var v = versionOf(candidates[i]);
+    if (v && ok(v)) node = candidates[i];
+  }
+  if (!node) {
+    process.stderr.write(
+      'pitroom needs Node.js ' + MIN.join('.') + ' or newer, but this shell runs Node.js v' + current.join('.') + ' (' + process.execPath + ').\n' +
+      'Install a current one and make it the default, for example:  nvm install 24 && nvm alias default 24\n' +
+      '(or put a newer node first on PATH, or set PITROOM_NODE=/path/to/node)\n',
+    );
+    process.exit(1);
+  }
+}
+
+var r = cp.spawnSync(node, [cli].concat(process.argv.slice(2)), { stdio: 'inherit' });
+if (r.error) {
+  process.stderr.write('pitroom: could not run ' + node + ': ' + r.error.message + '\n');
+  process.exit(1);
+}
+if (r.signal) process.kill(process.pid, r.signal);
+process.exit(r.status === null ? 1 : r.status);

package/dist/lib.mjs

@@ -1040,6 +1040,11 @@ var describeTarget = (t) => t.model ? formatTarget(t) : `${t.backend} (default m
 // src/core/refs.ts
 import fs5 from "node:fs";
 import path5 from "node:path";
+var FILE_EXTENSIONS = new Set(
+  "ts tsx mts cts js jsx mjs cjs json jsonc json5 md mdx txt rst py pyi rb go rs java kt kts swift c h cc cpp cxx hpp hh cs fs php lua r jl sh bash zsh fish ps1 bat yml yaml toml ini cfg conf env html htm css scss sass less vue svelte astro sql graphql gql proto lock xml svg csv tsv gradle tf hcl dart ex exs erl hs ml scala clj vim el mk cmake dockerfile gitignore gitattributes editorconfig npmrc nvmrc".split(" ")
+);
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", "target", "vendor", ".venv", "venv", "__pycache__", "coverage", ".turbo", ".cache"]);
+var MAX_INDEXED = 6e4;
 var EXTENSIONLESS = "Makefile|Dockerfile|Containerfile|Gemfile|Rakefile|Procfile|Justfile|Vagrantfile|BUILD|WORKSPACE";
 var REF = new RegExp(
   String.raw`(?<![\w/:.-])(\.{0,2}/?(?:[\w@.+-]+/)*(?:[\w@+-][\w@.+-]*\.[A-Za-z][A-Za-z0-9]{0,7}|${EXTENSIONLESS})):(\d+)(?:[-–](\d+))?`,
@@ -1097,23 +1102,36 @@ function verifyRefs(refs, dirs) {
     }
     return lineCache.get(file);
   };
+  let index;
+  const byName = () => index ??= indexFiles(roots);
+  const candidates = (ref) => {
+    const direct = resolve(ref.file, roots);
+    if (direct) return [direct];
+    if (path5.isAbsolute(ref.file)) return [];
+    const wanted = ref.file.replace(/^(\.{1,2}\/)+/, "");
+    return (byName().get(path5.basename(wanted)) ?? []).filter((f) => f.endsWith(`/${wanted}`) || path5.basename(f) === wanted).slice(0, 20);
+  };
+  const check = (file, ref) => {
+    const lines = load(file);
+    if (!lines) return void 0;
+    if (ref.end > lines.length) return `file has ${lines.length} lines`;
+    if (ref.symbol && !mentions(lines, ref) && !enclosedBy(lines, ref)) return `\`${ref.symbol}\` not near line ${ref.start}`;
+    return void 0;
+  };
+  let total = 0;
   for (const ref of refs) {
-    const file = resolve(ref.file, roots);
-    if (!file) {
+    const files = candidates(ref);
+    if (!files.length) {
+      if (!ref.file.includes("/") && !isFileName(ref.file)) continue;
+      total++;
       invalid.push({ ref: ref.text, reason: path5.isAbsolute(ref.file) && !inside(ref.file, roots) ? "outside the project" : "file not found" });
       continue;
     }
-    const lines = load(file);
-    if (!lines) continue;
-    if (ref.end > lines.length) {
-      invalid.push({ ref: ref.text, reason: `file has ${lines.length} lines` });
-      continue;
-    }
-    if (ref.symbol && !mentions(lines, ref) && !enclosedBy(lines, ref)) {
-      invalid.push({ ref: ref.text, reason: `\`${ref.symbol}\` not near line ${ref.start}` });
-    }
+    total++;
+    const reasons = files.map((f) => check(f, ref));
+    if (!reasons.some((r) => r === void 0)) invalid.push({ ref: ref.text, reason: files.length > 1 ? `${reasons[0]} (${files.length} files match)` : reasons[0] });
   }
-  return { total: refs.length, valid: refs.length - invalid.length, invalid };
+  return { total, valid: total - invalid.length, invalid };
 }
 function mentions(lines, ref) {
   const near = lines.slice(Math.max(0, ref.start - 1 - WINDOW), ref.end + WINDOW).join("\n");
@@ -1126,6 +1144,35 @@ function enclosedBy(lines, ref) {
   );
   return lines.slice(Math.max(0, ref.start - 1 - DEFINITION_LOOKBACK), ref.start).some((l) => def.test(l));
 }
+var isFileName = (name) => {
+  const base = path5.basename(name);
+  return !base.includes(".") || new RegExp(`^(${EXTENSIONLESS})$`).test(base) || FILE_EXTENSIONS.has(base.split(".").pop().toLowerCase());
+};
+function indexFiles(roots) {
+  const index = /* @__PURE__ */ new Map();
+  let count = 0;
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs5.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (count >= MAX_INDEXED) return;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(path5.join(dir, e.name));
+      } else if (e.isFile()) {
+        count++;
+        const list = index.get(e.name);
+        if (list) list.push(path5.join(dir, e.name));
+        else index.set(e.name, [path5.join(dir, e.name)]);
+      }
+    }
+  };
+  for (const r of roots) walk(r);
+  return index;
+}
 function resolve(ref, roots) {
   const candidates = path5.isAbsolute(ref) ? inside(ref, roots) ? [ref] : [] : roots.map((r) => path5.join(r, ref));
   return candidates.find((c) => {