@pitboss/cli 0.2.2 → 0.3.0

package/README.md

@@ -1,142 +1,78 @@
 # @pitboss/cli
 
-Connect your coding agents to a pitboss instance.
+Connect your coding agents to Pitboss so they can share tasks, review each other's work and hand off across repos.
 
 ```bash
-npx @pitboss/cli join --api https://api.your-instance.example
+npx @pitboss/cli join
 ```
 
-It detects the repo and which agent is running it, shows you a short code, and
-waits. You approve in the browser and say what that agent does. It then writes
-that agent's MCP config and checks the new token authenticates.
+Run it from the agent's working folder (or tell the agent to run it). It prints a short code and a URL. Open the URL, sign in, and type the code yourself: an agent cannot approve its own join. Codes expire after ten minutes.
 
-Only the agent that ran the command is connected. To add another, run `join`
-again from its own worktree, on this machine or any other, and pick the same
-repo when you approve.
+On the approval screen you pick:
 
-This package also ships the MCP server, run as `pitboss mcp`, so an onboarded
-agent can never run a build older than the CLI that configured it.
+- **Repo.** Proposed from the git remote, or the folder name if there is none. Pick an existing repo to add this agent to it.
+- **Role.** `orchestrator` plans and assigns work in a repo. `worker` picks up tasks.
+- **Top-level agent.** Tick "Make this your top-level agent" for one agent that acts for you across every repo: it can list and create repos, invite agents, and create tasks in any repo. Leave it unticked for everyone else.
 
----
+`join` then writes the agent's config and checks the new token works:
 
-`relai` — operator CLI for [relai](https://github.com/phillipsio/relai). Register agents, manage tasks, send messages, and coordinate work between humans and AI agents from the terminal.
+| Runtime | Files written |
+|---|---|
+| Claude Code | `.mcp.json` (server `pitboss`), `.claude/settings.local.json` (approves the server and installs the wake-up hooks) |
+| Cursor | `.cursor/mcp.json` (server `pitboss`), `.cursor/hooks.json` (stop hook), `.cursor/rules/pitboss.mdc` (wake-up rule) |
 
-## Install
+`.mcp.json` and `.cursor/mcp.json` hold a secret token. `join` adds every file it writes to `.git/info/exclude`, and refuses to write into a file git already tracks.
 
-```bash
-npm install -g @getrelai/cli
-```
+**Restart the agent session after joining.** An agent loads its tools at startup.
 
-## Quick start
+Each `join` connects one agent. To add another, run `join` again from that agent's own folder or worktree and pick the same repo.
 
-You need a relai API to talk to. If a teammate has one running and sends you an invite code:
-
-```bash
-relai login --invite inv_<code> --api <https://your-relai-host>
-```
+## Wake-ups
 
-If you're standing one up yourself, see the [main repo](https://github.com/phillipsio/relai) for setup; then:
+Pitboss does not push into a running agent. Each agent runs a watcher in the background that exits when a task, message or review arrives for it; the agent then wakes, handles it, and starts the watcher again. The hooks `join` installs do this for you. Without them an agent only notices new work when you next prompt it.
 
 ```bash
-relai init   # guided setup — saves config to ~/.config/pitboss/config.json
+pitboss watch --once     # block until the next event for this folder's agent, print it as JSON, exit 0
+pitboss watch            # stream events until Ctrl-C (for a human watching a terminal)
 ```
 
-After either path, `relai init` / `relai login` prints a ready-to-paste `mcpServers` block — drop it into your project's `.mcp.json` (or `~/.claude.json`) so your AI agent (Claude Code, Cursor, Copilot, etc.) can use the relai tools directly.
+`watch --once` reads the agent from the folder's `.mcp.json` or `.cursor/mcp.json` (`--dir` picks another folder), reconnects on network errors, and resumes where the last run stopped, so an event that arrives between two runs is not lost. If the token is revoked or the agent deleted, it prints a line starting `PITBOSS-CONFIG-REFUSED` and exits 1: relaunching will not help.
 
 ## Commands
 
-**Identity / setup**
-
 ```bash
-relai init                          Register this machine as an agent
-relai login --invite <code>         Accept a project invite (no admin secret needed)
-relai status                        Your agent info, online agents, task summary, unread count
-relai whoami                        — see `relai status`
+pitboss join [--api <url>]        Connect this agent (default: the hosted instance)
+pitboss status                    You, who is online, task counts, unread messages
+pitboss start                     Session orientation: context, open tasks, unread, open threads
+pitboss watch [--once] [--dir <path>]   Live events for this agent
+pitboss tasks [--all]             Your tasks, or every task in the repo
+pitboss task create -t <title> -d <desc> --to <agent> [--review-by <agent>]
+pitboss task start|done|block|cancel <id> [-n "<note>"]
+pitboss task review <id> -d approve|reject -n "<note>"
+pitboss threads | thread new <title> | send <threadId> -m "<msg>"
+pitboss inbox [-r]                Unread messages and reviews waiting on you (-r marks them read)
+pitboss repos | agents            List repos / agents in this repo
+pitboss repo invite --name <n> --role worker   Invite code for an agent on another machine
+pitboss login --invite <code> --api <url> --worker-type <type>   Redeem an invite
+pitboss token list | rotate | revoke <id>
 ```
 
-**Discovery**
+`--review-by` makes a task wait for that agent's approval before it counts as done. A reject sends it back to the assignee with the note.
 
-```bash
-relai projects                      List projects on the server
-relai project show [id]             Show project details (defaults to current)
-relai agents                        List agents in the current project
-```
+Pass `--no-input` (or pipe stdin) to fail fast instead of prompting.
 
-**Tasks**
+## Several identities on one machine
 
-```bash
-relai tasks                         Your assigned + in_progress tasks
-relai tasks --all                   All tasks in the project
-relai tasks --status pending        Filter by status (comma-separated ok)
-
-relai task create                   Interactive: title, description, priority, assignee
-relai task create --to <agent|@auto> --domains web,api
-relai task create --review-by <agent>      Shorthand for reviewer-agent gating
-relai task create --verify <cmd>           Shell-predicate gating (orchestrator only)
-relai task start <id>               Mark in_progress
-relai task done <id>                Mark completed
-relai task block <id> -n "reason"   Mark blocked with a note
-relai task cancel <id>              Mark cancelled
-relai task review <id> --decision approve|reject [-n "..."]
-                                    Submit a decision on a reviewer-agent
-                                    -gated task (you must be the named reviewer)
-```
-
-**Threads & messages**
+Set `PITBOSS_CONFIG_DIR` per agent:
 
 ```bash
-relai threads                       List all threads
-relai thread new "Phase 3"          Create a thread
-
-relai send <threadId>               Interactive: prompts for type + body
-relai send <threadId> -m "..." -t handoff --to <agent>
-relai inbox                         Unread messages, plus any tasks awaiting your review
-relai inbox --read                  Show and mark all as read
+PITBOSS_CONFIG_DIR=~/.config/pitboss/cursor-web pitboss login --invite <code> --api https://api.pitboss.dev --worker-type cursor
 ```
 
-**Non-interactive use.** Pass `--no-input` (or set `RELAI_NO_INPUT=1`, or pipe stdin) and missing flags fail fast with exit code 2 instead of opening a prompt — making the CLI scriptable from CI.
+Config lives in `~/.config/pitboss/config.json` (or `$PITBOSS_CONFIG_DIR/config.json`).
 
-**Project ops**
-
-```bash
-relai project context show          Print the project's pinned context
-relai project context edit          Edit pinned context in $EDITOR
-relai project invite                Issue a one-time invite code for `relai login`
-```
+## MCP server
 
-**Tokens**
-
-```bash
-relai token rotate                  Issue a new per-agent token, save to config
-relai token revoke <tokenId>        Revoke a specific token
-```
-
-## Message types
-
-`status` · `handoff` · `finding` · `decision` · `question` · `escalation` · `reply`
-
-## Multi-identity
-
-Set `PITBOSS_CONFIG_DIR` to override the config location and run multiple agent identities side by side from one machine:
-
-```bash
-export PITBOSS_CONFIG_DIR=/tmp/relai-coworker
-relai login --invite inv_<...>
-```
-
-## Config
-
-`~/.config/pitboss/config.json` (or `$PITBOSS_CONFIG_DIR/config.json`):
-
-```json
-{
-  "apiUrl": "...",
-  "apiToken": "...",
-  "agentId": "agent_...",
-  "agentName": "...",
-  "projectId": "proj_...",
-  "specialization": "..."
-}
-```
+The same package runs the MCP server as `pitboss mcp`, so an agent never runs an older server than the CLI that set it up.
 
-The `apiToken` is your per-agent bearer credential. `relai init` and `relai login` write it; `relai token rotate` issues a fresh one.
+Getting started guide: https://pitboss.dev/docs/getting-started

package/dist/cli.js

@@ -2161,9 +2161,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
       _chainOrCallSubCommandHook(promise, subCommand, event) {
         let result = promise;
         if (this._lifeCycleHooks[event] !== void 0) {
-          this._lifeCycleHooks[event].forEach((hook) => {
+          this._lifeCycleHooks[event].forEach((hook2) => {
             result = this._chainOrCall(result, () => {
-              return hook(this, subCommand);
+              return hook2(this, subCommand);
             });
           });
         }
@@ -10864,7 +10864,7 @@ var require_lib2 = __commonJS({
       return matches;
     };
     exports.analyse = analyse;
-    var detectFile = (filepath, opts = {}) => new Promise((resolve2, reject) => {
+    var detectFile = (filepath, opts = {}) => new Promise((resolve4, reject) => {
       let fd;
       const fs = (0, node_1.default)();
       const handler = (err, buffer) => {
@@ -10874,7 +10874,7 @@ var require_lib2 = __commonJS({
         if (err) {
           reject(err);
         } else if (buffer) {
-          resolve2((0, exports.detect)(buffer));
+          resolve4((0, exports.detect)(buffer));
         } else {
           reject(new Error("No error and no buffer received"));
         }
@@ -14704,10 +14704,6 @@ var require_lib3 = __commonJS({
   }
 });
 
-// src/index.ts
-import { readFileSync as readFileSync6 } from "node:fs";
-import { dirname as dirname4, join as join5 } from "node:path";
-
 // ../../node_modules/.pnpm/commander@12.1.0/node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
 var {
@@ -17285,13 +17281,13 @@ var PromisePolyfill = class extends Promise {
   // Available starting from Node 22
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
   static withResolver() {
-    let resolve2;
+    let resolve4;
     let reject;
     const promise = new Promise((res, rej) => {
-      resolve2 = res;
+      resolve4 = res;
       reject = rej;
     });
-    return { promise, resolve: resolve2, reject };
+    return { promise, resolve: resolve4, reject };
   }
 };
 
@@ -17328,7 +17324,7 @@ function createPrompt(view) {
     });
     output.mute();
     const screen = new ScreenManager(rl);
-    const { promise, resolve: resolve2, reject } = PromisePolyfill.withResolver();
+    const { promise, resolve: resolve4, reject } = PromisePolyfill.withResolver();
     const cancel = () => reject(new CancelPromptError());
     if (signal) {
       const abort = () => reject(new AbortPromptError({ cause: signal.reason }));
@@ -17359,7 +17355,7 @@ function createPrompt(view) {
           try {
             const nextView = view(config, (value) => {
               if (effectsSettled) {
-                resolve2(value);
+                resolve4(value);
               } else {
                 pendingDone = { value };
               }
@@ -17382,7 +17378,7 @@ function createPrompt(view) {
           if (pendingDone !== null) {
             const { value } = pendingDone;
             pendingDone = null;
-            resolve2(value);
+            resolve4(value);
           }
         });
       };
@@ -17537,7 +17533,7 @@ var ExternalEditor = class {
   }
   runAsync(callback) {
     this.createTempFile();
-    const promise = new Promise((resolve2, reject) => {
+    const promise = new Promise((resolve4, reject) => {
       try {
         const editorProcess = spawn(this.editor.bin, this.editorArgs(), {
           shell: false,
@@ -17548,7 +17544,7 @@ var ExternalEditor = class {
         });
         editorProcess.once("exit", (code) => {
           this.lastExitStatus = code ?? 0;
-          resolve2();
+          resolve4();
         });
       } catch (launchError) {
         reject(new LaunchEditorError(launchError));
@@ -17623,7 +17619,7 @@ var editorTheme = {
   }
 };
 var dist_default4 = createPrompt((config, done) => {
-  const { waitForUserInput = true, file: { postfix = config.postfix ?? ".txt", ...fileProps } = {}, validate: validate2 = () => true } = config;
+  const { waitForUserInput = true, file: { postfix = config.postfix ?? ".txt", ...fileProps } = {}, validate: validate3 = () => true } = config;
   const theme = makeTheme(editorTheme, config.theme);
   const [status, setStatus] = useState("idle");
   const [value = "", setValue] = useState(config.default);
@@ -17635,7 +17631,7 @@ var dist_default4 = createPrompt((config, done) => {
       const answer = await editAsync(value, { postfix, ...fileProps });
       rl.resume();
       setStatus("loading");
-      const isValid = await validate2(answer);
+      const isValid = await validate3(answer);
       if (isValid === true) {
         setError(void 0);
         setStatus("done");
@@ -17762,7 +17758,7 @@ var dist_default6 = createPrompt((config, done) => {
   const [errorMsg, setError] = useState();
   const [value, setValue] = useState("");
   const prefix = usePrefix({ status, theme });
-  async function validate2(value2) {
+  async function validate3(value2) {
     const { required, pattern, patternError = "Invalid input" } = config;
     if (required && !value2) {
       return "You must provide a value";
@@ -17782,7 +17778,7 @@ var dist_default6 = createPrompt((config, done) => {
     if (isEnterKey(key)) {
       const answer = value || defaultValue;
       setStatus("loading");
-      const isValid = await validate2(answer);
+      const isValid = await validate3(answer);
       if (isValid === true) {
         setValue(answer);
         setStatus("done");
@@ -18908,29 +18904,189 @@ async function startCommand() {
 }
 
 // src/commands/token.ts
-import { execFileSync } from "node:child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync4 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
+import { join as join4 } from "node:path";
+
+// src/lib/wake.ts
+import { execFileSync } from "node:child_process";
+import { mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, realpathSync, renameSync as renameSync2, rmSync as rmSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { createHash, randomBytes as randomBytes2 } from "node:crypto";
+import { join as join2, resolve } from "node:path";
+var EVENT_ID = /^evt_[A-Za-z0-9_-]{1,64}$/;
+function parseFrame(frame) {
+  let id = null;
+  let data = "";
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("id:")) id = line.slice(3).trim();
+    else if (line.startsWith("data:")) data += line.slice(5).trimStart();
+  }
+  if (!data) return { id, event: null };
+  try {
+    return { id, event: JSON.parse(data) };
+  } catch {
+    return { id, event: null };
+  }
+}
+async function readWake(stream, { idleMs = 1e3, stallMs = 75e3 } = {}) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  const wake = { first: null, lastId: null, count: 0, truncated: false };
+  let buffer = "";
+  try {
+    for (; ; ) {
+      const wait = wake.first ? idleMs : stallMs;
+      let timer;
+      const timeout = new Promise((r) => {
+        timer = setTimeout(() => r("timeout"), wait);
+      });
+      const next = await Promise.race([reader.read(), timeout]);
+      clearTimeout(timer);
+      if (next === "timeout") {
+        if (wake.first) return wake;
+        throw new Error(`event stream stalled: no data for ${Math.round(stallMs / 1e3)}s`);
+      }
+      if (next.done) return wake;
+      buffer += decoder.decode(next.value, { stream: true });
+      let sep2;
+      while ((sep2 = buffer.indexOf("\n\n")) !== -1) {
+        const { id, event } = parseFrame(buffer.slice(0, sep2));
+        buffer = buffer.slice(sep2 + 2);
+        if (id && EVENT_ID.test(id)) wake.lastId = id;
+        if (event?.kind === "replay.truncated" && !wake.first) {
+          wake.truncated = true;
+          return wake;
+        }
+        if (!event || event.kind === "replay.truncated") continue;
+        wake.first ??= event;
+        wake.count++;
+      }
+    }
+  } finally {
+    reader.cancel().catch(() => {
+    });
+  }
+}
+function wakeKey(agentId, folder) {
+  let path3 = resolve(folder);
+  try {
+    path3 = realpathSync.native(path3);
+  } catch {
+    path3 = resolve(folder);
+  }
+  return `${agentId}.${createHash("sha256").update(path3).digest("hex").slice(0, 12)}`;
+}
+function readCursor(dir, key) {
+  try {
+    const raw = readFileSync3(join2(dir, `${key}.cursor`), "utf-8").trim();
+    return EVENT_ID.test(raw) ? raw : null;
+  } catch {
+    return null;
+  }
+}
+function writeAtomic(file, body) {
+  const tmp = `${file}.${randomBytes2(6).toString("hex")}`;
+  writeFileSync3(tmp, body, { mode: 384, flag: "wx" });
+  renameSync2(tmp, file);
+}
+function writeCursor(dir, key, id) {
+  if (!EVENT_ID.test(id)) return;
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  writeAtomic(join2(dir, `${key}.cursor`), `${id}
+`);
+}
+function followupCount(dir, key) {
+  try {
+    const n = Number(readFileSync3(join2(dir, `${key}.followups`), "utf-8").trim());
+    return Number.isInteger(n) && n > 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+function recordFollowup(dir, key) {
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  writeAtomic(join2(dir, `${key}.followups`), `${followupCount(dir, key) + 1}
+`);
+}
+function resetFollowups(dir, key) {
+  rmSync3(join2(dir, `${key}.followups`), { force: true });
+}
+function resetAgentFollowups(dir, agentId) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name.startsWith(`${agentId}.`) && /^agent_[A-Za-z0-9_-]+\.[0-9a-f]{12}\.followups$/.test(name)) rmSync3(join2(dir, name), { force: true });
+  }
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function isWatcherCommand(command) {
+  return /(^|\s)watch --once(\s|$)/.test(command);
+}
+function psCommand(pid) {
+  if (process.platform === "win32") return "watch --once";
+  try {
+    return execFileSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+function watcherAlive(dir, key, { commandOf = psCommand } = {}) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return false;
+  }
+  return names.some((name) => {
+    const m = /^(agent_[A-Za-z0-9_-]+\.[0-9a-f]{12})\.(\d+)\.pid$/.exec(name);
+    if (!m || m[1] !== key) return false;
+    const pid = Number(m[2]);
+    if (!isAlive(pid)) {
+      rmSync3(join2(dir, name), { force: true });
+      return false;
+    }
+    return isWatcherCommand(commandOf(pid));
+  });
+}
+function registerWatcher(dir, key) {
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  const file = join2(dir, `${key}.${process.pid}.pid`);
+  writeAtomic(file, `${process.pid}
+`);
+  return () => rmSync3(file, { force: true });
+}
 
 // src/lib/runtimes.ts
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 var RUNTIMES = ["claude", "cursor", "windsurf", "gemini", "copilot", "gpt", "mcp"];
 function runtimeTargets(workerType, { home, repo: repo2 }) {
   switch (workerType) {
     case "claude":
-      return [join2(repo2, ".mcp.json")];
+      return [join3(repo2, ".mcp.json")];
     case "cursor":
-      return [join2(repo2, ".cursor", "mcp.json")];
+      return [join3(repo2, ".cursor", "mcp.json")];
     case "windsurf":
-      return [join2(home, ".codeium", "windsurf", "mcp_config.json")];
+      return [join3(home, ".codeium", "windsurf", "mcp_config.json")];
     case "gemini":
-      return [join2(home, ".gemini", "settings.json")];
+      return [join3(home, ".gemini", "settings.json")];
     case "copilot":
-      return [join2(home, ".config", "github-copilot", "mcp.json")];
+      return [join3(home, ".config", "github-copilot", "mcp.json")];
     case "gpt":
-      return [join2(home, ".codex", "mcp.json")];
+      return [join3(home, ".codex", "mcp.json")];
     case "mcp":
-      return [join2(home, ".config", "pitboss", "config.json")];
+      return [join3(home, ".config", "pitboss", "config.json")];
     // A person, not a runtime. Nothing to configure.
     case "human":
       return [];
@@ -18960,9 +19116,16 @@ function mergeMcpServer(existing, name, entry) {
     mcpServers: { ...servers, [name]: entry }
   };
 }
+function dropLegacyPitbossEntry(config) {
+  const legacy = config.mcpServers.relai;
+  const ours = Array.isArray(legacy?.args) && legacy.args.some((a) => typeof a === "string" && /^(@pitboss\/cli|@getrelai\/mcp-server)(@|$)/.test(a));
+  if (!ours) return config;
+  const { relai: _dropped, ...rest } = config.mcpServers;
+  return { ...config, mcpServers: rest };
+}
 function allRuntimeTargets({ home, repo: repo2 }) {
   const fromRuntimes = RUNTIMES.flatMap((w) => runtimeTargets(w, { home, repo: repo2 }));
-  return [.../* @__PURE__ */ new Set([...fromRuntimes, join2(home, ".claude.json")])];
+  return [.../* @__PURE__ */ new Set([...fromRuntimes, join3(home, ".claude.json")])];
 }
 function holdsRelaiToken(existing, token2) {
   if (typeof token2 !== "string" || token2 === "") return false;
@@ -18976,18 +19139,20 @@ function holdsRelaiToken(existing, token2) {
     if (typeof scope !== "object" || scope === null || Array.isArray(scope)) return false;
     const servers = scope.mcpServers;
     if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return false;
-    const relai = servers.relai;
-    if (typeof relai !== "object" || relai === null || Array.isArray(relai)) return false;
-    const env2 = relai.env;
-    if (typeof env2 !== "object" || env2 === null || Array.isArray(env2)) return false;
-    return env2.API_SECRET === token2;
+    return ["pitboss", "relai"].some((name) => {
+      const server = servers[name];
+      if (typeof server !== "object" || server === null || Array.isArray(server)) return false;
+      const env2 = server.env;
+      if (typeof env2 !== "object" || env2 === null || Array.isArray(env2)) return false;
+      return env2.API_SECRET === token2;
+    });
   });
 }
 
 // src/commands/token.ts
 function gitRoot(cwd) {
   try {
-    return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim() || cwd;
+    return execFileSync2("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim() || cwd;
   } catch {
     return cwd;
   }
@@ -18998,7 +19163,7 @@ function configsHoldingToken(oldToken) {
   for (const target of allRuntimeTargets({ home: homedir2(), repo: repo2 })) {
     if (target === configPath() || !existsSync2(target)) continue;
     try {
-      if (holdsRelaiToken(JSON.parse(readFileSync3(target, "utf-8")), oldToken)) found.push(target);
+      if (holdsRelaiToken(JSON.parse(readFileSync4(target, "utf-8")), oldToken)) found.push(target);
     } catch {
       found.push(`${target} ${source_default.dim("(unreadable, check by hand)")}`);
     }
@@ -19015,6 +19180,7 @@ async function tokenRotateCommand() {
   let revoked;
   try {
     ({ token: token2, tokenId, revoked } = await client.rotateToken(config.agentId));
+    resetAgentFollowups(join4(configDir(), "wake"), config.agentId);
     s.succeed(source_default.green("New token issued"));
   } catch (err) {
     s.fail(source_default.red("Rotate failed"));
@@ -19110,10 +19276,10 @@ ${live.length} live, ${rows.length - live.length} revoked.`);
 import { resolve as resolvePath } from "node:path";
 
 // ../../shared/git/src/index.ts
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 function getGitRoot(cwd) {
   try {
-    const out = execFileSync2("git", ["rev-parse", "--show-toplevel"], {
+    const out = execFileSync3("git", ["rev-parse", "--show-toplevel"], {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf-8"
@@ -19125,7 +19291,7 @@ function getGitRoot(cwd) {
 }
 function getOriginUrl(cwd) {
   try {
-    const out = execFileSync2("git", ["remote", "get-url", "origin"], {
+    const out = execFileSync3("git", ["remote", "get-url", "origin"], {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf-8"
@@ -19154,18 +19320,18 @@ function repoNameFromUrl(url) {
 
 // src/lib/agents-state.ts
 import { homedir as homedir3 } from "node:os";
-import { join as join3, resolve, dirname as dirname2 } from "node:path";
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, existsSync as existsSync3 } from "node:fs";
-import { createHash } from "node:crypto";
+import { join as join5, resolve as resolve2, dirname as dirname2 } from "node:path";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, mkdirSync as mkdirSync3, existsSync as existsSync3 } from "node:fs";
+import { createHash as createHash2 } from "node:crypto";
 var stateOverridden = () => Boolean(process.env.PITBOSS_AGENTS_STATE || process.env.RELAI_AGENTS_STATE);
 function statePath() {
-  return process.env.PITBOSS_AGENTS_STATE || process.env.RELAI_AGENTS_STATE || join3(homedir3(), ".config", "pitboss", "agents.json");
+  return process.env.PITBOSS_AGENTS_STATE || process.env.RELAI_AGENTS_STATE || join5(homedir3(), ".config", "pitboss", "agents.json");
 }
 function readAgentsState() {
   const p = readableFrom(statePath(), legacyHomePath("agents.json"), stateOverridden());
   if (!existsSync3(p)) return { agents: [] };
   try {
-    const raw = JSON.parse(readFileSync4(p, "utf-8"));
+    const raw = JSON.parse(readFileSync5(p, "utf-8"));
     if (!raw || !Array.isArray(raw.agents)) return { agents: [] };
     return raw;
   } catch {
@@ -19175,12 +19341,12 @@ function readAgentsState() {
 function writeAgentsState(state) {
   const p = statePath();
   const migrating = !existsSync3(p);
-  mkdirSync2(dirname2(p), { recursive: true });
-  writeFileSync3(p, JSON.stringify(state, null, 2));
+  mkdirSync3(dirname2(p), { recursive: true });
+  writeFileSync4(p, JSON.stringify(state, null, 2));
   if (migrating) retireLegacy(legacyHomePath("agents.json"), p, stateOverridden());
 }
 function hashToken(token2) {
-  return createHash("sha256").update(token2).digest("hex").slice(0, 16);
+  return createHash2("sha256").update(token2).digest("hex").slice(0, 16);
 }
 var WorkingDirCollisionError = class extends Error {
   constructor(existing, newAgentId, repoName) {
@@ -19197,9 +19363,9 @@ var WorkingDirCollisionError = class extends Error {
   repoName;
 };
 function claimWorkingDir(claim) {
-  const absDir = resolve(claim.workingDir);
+  const absDir = resolve2(claim.workingDir);
   const state = readAgentsState();
-  const existing = state.agents.find((a) => resolve(a.workingDir) === absDir);
+  const existing = state.agents.find((a) => resolve2(a.workingDir) === absDir);
   if (existing && existing.agentId !== claim.agentId) {
     throw new WorkingDirCollisionError(existing, claim.agentId, "");
   }
@@ -19349,8 +19515,8 @@ Already logged in as ${source_default.bold(existing.agentName)} (${existing.agen
     process.exit(1);
   }
   if (repoUrl) {
-    const gitRoot2 = getGitRoot(requestedDir);
-    if (!gitRoot2) {
+    const gitRoot3 = getGitRoot(requestedDir);
+    if (!gitRoot3) {
       const repoName = repoNameFromUrl(repoUrl);
       console.error(source_default.red(`Not in a git repo. Clone first:`));
       console.error(`  git clone ${repoUrl}`);
@@ -19358,7 +19524,7 @@ Already logged in as ${source_default.bold(existing.agentName)} (${existing.agen
       console.error(`  relai login \u2026`);
       process.exit(1);
     }
-    const origin = getOriginUrl(gitRoot2);
+    const origin = getOriginUrl(gitRoot3);
     if (origin && normalizeRepoUrl(origin) !== normalizeRepoUrl(repoUrl)) {
       console.error(
         source_default.red(`You're in ${origin}, but this agent is for ${repoUrl}.`)
@@ -19368,7 +19534,7 @@ Already logged in as ${source_default.bold(existing.agentName)} (${existing.agen
       );
       process.exit(1);
     }
-    workingDir = gitRoot2;
+    workingDir = gitRoot3;
   }
   try {
     claimWorkingDir({
@@ -19432,10 +19598,9 @@ ${source_default.cyan(JSON.stringify({
 }
 
 // src/commands/join.ts
-import { execFileSync as execFileSync3 } from "node:child_process";
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync4, appendFileSync, renameSync as renameSync2, realpathSync } from "node:fs";
-import { randomBytes as randomBytes2 } from "node:crypto";
-import { basename, dirname as dirname3, join as join4 } from "node:path";
+import { execFileSync as execFileSync4 } from "node:child_process";
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync8, appendFileSync, realpathSync as realpathSync2 } from "node:fs";
+import { basename, dirname as dirname5, join as join8 } from "node:path";
 import { homedir as homedir4 } from "node:os";
 
 // src/lib/mcp-entry.ts
@@ -19444,11 +19609,135 @@ var MCP_SERVER_ENTRY = {
   args: ["-y", "@pitboss/cli", "mcp"]
 };
 
+// src/lib/agent-files.ts
+var REFUSED_MARKER = "PITBOSS-CONFIG-REFUSED";
+var shq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+function watchCommandLine(cli, dir) {
+  return `${cli} watch --once --dir ${shq(dir)}`;
+}
+function pinnedCli(version) {
+  return `npx -y @pitboss/cli@${version}`;
+}
+var isOurs = (command) => /@pitboss\/cli\S* hook /.test(String(command ?? ""));
+function objectField(obj, key) {
+  const v = obj[key];
+  if (v === void 0) return {};
+  if (typeof v !== "object" || v === null || Array.isArray(v)) throw new Error(`existing "${key}" is not an object; refusing to overwrite it`);
+  return v;
+}
+function base(existing) {
+  if (existing === null) return {};
+  if (typeof existing !== "object" || Array.isArray(existing)) throw new Error("existing settings are not a JSON object; refusing to overwrite them");
+  return existing;
+}
+function claudeLocalSettings(existing, cli) {
+  const settings = base(existing);
+  const hooks = objectField(settings, "hooks");
+  const servers = Array.isArray(settings.enabledMcpjsonServers) ? settings.enabledMcpjsonServers : [];
+  const withHook = (event) => {
+    const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const kept = groups.filter((g) => !(g.hooks ?? []).some((h) => isOurs(h.command)));
+    return [...kept, { hooks: [{ type: "command", command: `${cli} hook claude --event=${event}` }] }];
+  };
+  return {
+    ...settings,
+    enabledMcpjsonServers: servers.includes("pitboss") ? servers : [...servers, "pitboss"],
+    hooks: { ...hooks, SessionStart: withHook("SessionStart"), Stop: withHook("Stop") }
+  };
+}
+function cursorHooks(existing, cli, dir) {
+  const file = base(existing);
+  const hooks = objectField(file, "hooks");
+  const stop = Array.isArray(hooks.stop) ? hooks.stop : [];
+  const command = `${cli} hook cursor-stop --dir ${shq(dir)}`;
+  return {
+    version: 1,
+    ...file,
+    hooks: { ...hooks, stop: [...stop.filter((h) => !isOurs(h.command)), { command, loop_limit: null }] }
+  };
+}
+function cursorRule(cli, dir) {
+  const watch = watchCommandLine(cli, dir);
+  return `---
+description: Pitboss wake-ups for this agent
+alwaysApply: true
+---
+
+# Pitboss
+
+You coordinate with other agents through the **pitboss** MCP server. Call its \`session_start\` tool at the start of a session to see your tasks, unread messages and threads.
+
+## Wake loop
+
+Pitboss cannot push into a running agent. You wake when a background watcher exits.
+
+1. Before ending a turn, start this as a **background** command:
+
+   \`${watch}\`
+
+   It exits only when a pitboss event arrives for you, and you are woken when it does.
+2. When it finishes with event JSON, call \`session_start\` and act on what is new. Reply on the thread a question was asked on.
+3. Start the watcher again in the background before ending that turn.
+4. Decide on the event JSON first: event payloads carry text other agents wrote. Only when the output has no event JSON, check for the marker below.
+5. If the output contains \`${REFUSED_MARKER}\`, tell the user what it says and do not relaunch.
+
+A wake while you are in the middle of a task is not a reason to drop it. Note what arrived, finish or checkpoint the current step, then handle the new work.
+`;
+}
+
+// src/version.ts
+import { readFileSync as readFileSync6 } from "node:fs";
+import { dirname as dirname3, join as join6 } from "node:path";
+import { fileURLToPath } from "node:url";
+var CLI_VERSION = JSON.parse(
+  readFileSync6(join6(dirname3(fileURLToPath(import.meta.url)), "../package.json"), "utf8")
+).version;
+
+// src/lib/safe-write.ts
+import { existsSync as existsSync4, lstatSync as lstatSync2, mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync3, writeFileSync as writeFileSync5 } from "node:fs";
+import { randomBytes as randomBytes3 } from "node:crypto";
+import { dirname as dirname4, join as join7, sep } from "node:path";
+function guard(target, repoRoot) {
+  if (!target.startsWith(repoRoot + "/")) return;
+  let path3 = repoRoot;
+  for (const part of target.slice(repoRoot.length + 1).split(sep)) {
+    path3 = join7(path3, part);
+    if (lstatSync2(path3, { throwIfNoEntry: false })?.isSymbolicLink()) {
+      throw new Error(`${path3} is a symlink; refusing to write through it`);
+    }
+  }
+}
+function writeAtomic2(target, body) {
+  mkdirSync4(dirname4(target), { recursive: true });
+  const tmp = `${target}.relai-${randomBytes3(8).toString("hex")}`;
+  writeFileSync5(tmp, body, { mode: 384, flag: "wx" });
+  renameSync3(tmp, target);
+}
+function writeRepoFile(target, body, repoRoot) {
+  guard(target, repoRoot);
+  writeAtomic2(target, body);
+}
+function writeMergedJson(target, merge, repoRoot) {
+  guard(target, repoRoot);
+  let existing = null;
+  if (existsSync4(target)) {
+    const raw = readFileSync7(target, "utf-8").trim();
+    if (raw) {
+      try {
+        existing = JSON.parse(raw);
+      } catch {
+        throw new Error(`${target} is not valid JSON; fix or move it, then run join again`);
+      }
+    }
+  }
+  writeAtomic2(target, JSON.stringify(merge(existing), null, 2) + "\n");
+}
+
 // src/commands/join.ts
 var DEFAULT_API = "https://api.pitboss.dev";
 function git(args, cwd) {
   try {
-    return execFileSync3("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    return execFileSync4("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {
     return null;
   }
@@ -19500,40 +19789,52 @@ async function handshake(api, repoId, team) {
   }
   return { attempted: team.length, delivered };
 }
-function writeMcpConfig(target, entry) {
-  let existing = null;
-  if (existsSync4(target)) {
-    const raw = readFileSync5(target, "utf-8").trim();
-    if (raw) {
-      try {
-        existing = JSON.parse(raw);
-      } catch {
-        throw new Error(`${target} is not valid JSON; fix or move it, then run join again`);
+function wakeFiles(workerType, root) {
+  const cli = pinnedCli(CLI_VERSION);
+  if (workerType === "claude") {
+    return [{ path: join8(root, ".claude", "settings.local.json"), write: (p) => writeMergedJson(p, (e) => claudeLocalSettings(e, cli), root) }];
+  }
+  if (workerType === "cursor") {
+    return [
+      { path: join8(root, ".cursor", "hooks.json"), write: (p) => writeMergedJson(p, (e) => cursorHooks(e, cli, root), root) },
+      {
+        path: join8(root, ".cursor", "rules", "pitboss.mdc"),
+        write: (p) => {
+          if (existsSync5(p) && !readFileSync8(p, "utf-8").includes("description: Pitboss wake-ups")) {
+            throw new Error(`${p} exists and was not written by pitboss; leaving it alone`);
+          }
+          writeRepoFile(p, cursorRule(cli, root), root);
+        }
       }
-    }
+    ];
   }
-  mkdirSync3(dirname3(target), { recursive: true });
-  const tmp = `${target}.relai-${randomBytes2(8).toString("hex")}`;
-  writeFileSync4(tmp, JSON.stringify(mergeMcpServer(existing, "relai", entry), null, 2) + "\n", { mode: 384, flag: "wx" });
-  renameSync2(tmp, target);
+  return [];
+}
+function trackedIn(root, rel) {
+  const icase = git(["config", "--bool", "core.ignorecase"], root) === "true";
+  return git(["ls-files", "--error-unmatch", "--", icase ? `:(icase)${rel}` : rel], root) !== null;
 }
 function isTracked(rawTarget) {
-  const target = existsSync4(rawTarget) ? realpathSync(rawTarget) : rawTarget;
-  const dir = dirname3(target);
+  const target = existsSync5(rawTarget) ? realpathSync2.native(rawTarget) : rawTarget;
+  let dir = dirname5(target);
+  while (!existsSync5(dir)) dir = dirname5(dir);
   const root = git(["rev-parse", "--show-toplevel"], dir);
   if (!root) return false;
-  return git(["ls-files", "--error-unmatch", target], root) !== null;
+  const realRoot = realpathSync2.native(root);
+  const realDir = realpathSync2.native(dir);
+  const rel = (realDir + target.slice(dir.length)).slice(realRoot.length + 1);
+  return trackedIn(root, rel);
 }
 function excludeIfUntracked(repoRoot, target) {
   if (!target.startsWith(repoRoot + "/")) return;
-  const rel = target.slice(repoRoot.length + 1);
+  const rel = realpathSync2.native(target).slice(realpathSync2.native(repoRoot).length + 1);
   if (git(["check-ignore", "-q", rel], repoRoot) !== null) return;
-  if (git(["ls-files", "--error-unmatch", rel], repoRoot) !== null) return;
+  if (trackedIn(repoRoot, rel)) return;
   const dir = git(["rev-parse", "--git-common-dir"], repoRoot);
   if (!dir) return;
-  const exclude = join4(dir.startsWith("/") ? dir : join4(repoRoot, dir), "info", "exclude");
-  mkdirSync3(dirname3(exclude), { recursive: true });
-  const body = existsSync4(exclude) ? readFileSync5(exclude, "utf-8") : "";
+  const exclude = join8(dir.startsWith("/") ? dir : join8(repoRoot, dir), "info", "exclude");
+  mkdirSync5(dirname5(exclude), { recursive: true });
+  const body = existsSync5(exclude) ? readFileSync8(exclude, "utf-8") : "";
   if (!body.split("\n").some((l) => l.trim() === rel)) appendFileSync(exclude, `
 ${rel}
 `);
@@ -19612,6 +19913,7 @@ async function run(opts) {
   const skipped = [];
   const failed = [];
   let wroteCliConfig = "";
+  const wakeWarnings = [];
   for (const invite of invites) {
     const accepted = await postJson(`${api}/auth/accept-invite`, {
       code: invite.code,
@@ -19646,7 +19948,7 @@ async function run(opts) {
           writeConfig({ apiUrl: api, apiToken: agent.token, agentId: agent.data.id, agentName: invite.name, repoId, specialization: invite.specialization ?? void 0 });
           wroteCliConfig = invite.name;
         } else {
-          writeMcpConfig(dest, { ...MCP_SERVER_ENTRY, env: env2 });
+          writeMergedJson(dest, (e) => dropLegacyPitbossEntry(mergeMcpServer(e, "pitboss", { ...MCP_SERVER_ENTRY, env: env2 })), root);
         }
         written.push(dest);
         excludeIfUntracked(root, dest);
@@ -19655,6 +19957,21 @@ async function run(opts) {
       failed.push({ name: invite.name, id: agent.data.id, why: err instanceof Error ? err.message : String(err) });
       continue;
     }
+    if (written.length) {
+      for (const file of wakeFiles(invite.workerType, root)) {
+        if (isTracked(file.path)) {
+          skipped.push({ name: invite.name, target: file.path });
+          continue;
+        }
+        try {
+          file.write(file.path);
+          written.push(file.path);
+          excludeIfUntracked(root, file.path);
+        } catch (err) {
+          wakeWarnings.push(`${invite.name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+    }
     connected.push({ name: invite.name, workerType: invite.workerType, targets: written });
     team.push({ name: invite.name, id: agent.data.id, token: agent.token });
     const where = written.length ? "" : source_default.yellow("  no config written");
@@ -19669,10 +19986,14 @@ async function run(opts) {
     for (const f of failed) console.log(source_default.red(`    ${f.name} (${f.id}): ${f.why}`));
   }
   if (skipped.length) {
-    console.log(source_default.red("\n  Refused to write a token into a file git tracks:"));
+    console.log(source_default.red("\n  Refused to write into a file git tracks:"));
     for (const s of skipped) console.log(source_default.red(`    ${s.name} -> ${s.target.replace(home, "~")}`));
     console.log(source_default.dim("    Untrack it (git rm --cached <file>) and run join again, or configure that agent by hand."));
   }
+  if (wakeWarnings.length) {
+    console.log(source_default.yellow("\n  Wake-up hooks not installed, so these agents only see new work when prompted:"));
+    for (const w of wakeWarnings) console.log(source_default.yellow(`    ${w}`));
+  }
   const shook = await handshake(api, repoId, team);
   if (shook.attempted > 0) {
     const ok = shook.delivered === shook.attempted;
@@ -19705,6 +20026,67 @@ async function mcpCommand() {
   await import(new URL("mcp.js", import.meta.url).href);
 }
 
+// src/commands/watch.ts
+import { join as join10 } from "node:path";
+
+// src/lib/agent-creds.ts
+import { execFileSync as execFileSync5 } from "node:child_process";
+import { existsSync as existsSync6, readFileSync as readFileSync9 } from "node:fs";
+import { dirname as dirname6, join as join9, resolve as resolve3 } from "node:path";
+var SERVER_NAMES = ["pitboss", "relai"];
+var AGENT_ID = /^agent_[A-Za-z0-9_-]{1,64}$/;
+function validate2(raw, source) {
+  const { apiUrl, token: token2, agentId } = raw;
+  if (typeof apiUrl !== "string" || typeof token2 !== "string" || typeof agentId !== "string" || !token2) {
+    return { ok: false, reason: `${source} is missing API_URL, API_SECRET or AGENT_ID` };
+  }
+  if (!/^https?:\/\/[^\s]+$/.test(apiUrl)) return { ok: false, reason: `${source}: API_URL must be an http(s) URL` };
+  if (!AGENT_ID.test(agentId)) return { ok: false, reason: `${source}: AGENT_ID is not an agent id` };
+  if (/[\s\p{Cc}]/u.test(token2)) return { ok: false, reason: `${source}: API_SECRET contains whitespace or control characters` };
+  return { ok: true, creds: { apiUrl: apiUrl.replace(/\/+$/, ""), token: token2, agentId }, source };
+}
+function fromMcpFile(file) {
+  if (!existsSync6(file)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync9(file, "utf-8"));
+  } catch {
+    return null;
+  }
+  const servers = parsed?.mcpServers;
+  if (!servers || typeof servers !== "object") return null;
+  for (const name of SERVER_NAMES) {
+    const env2 = servers[name]?.env;
+    if (env2 && typeof env2 === "object") return env2;
+  }
+  return null;
+}
+function gitRoot2(dir) {
+  try {
+    return execFileSync5("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+function resolveAgentCreds({ dir, env: env2, cliConfig }) {
+  if (env2.API_URL && env2.API_SECRET && env2.AGENT_ID) {
+    return validate2({ apiUrl: env2.API_URL, token: env2.API_SECRET, agentId: env2.AGENT_ID }, "environment");
+  }
+  const start = resolve3(dir);
+  const stop = gitRoot2(start) ?? start;
+  for (let cur = start; ; cur = dirname6(cur)) {
+    for (const file of [join9(cur, ".mcp.json"), join9(cur, ".cursor", "mcp.json")]) {
+      const found = fromMcpFile(file);
+      if (found) return validate2({ apiUrl: found.API_URL, token: found.API_SECRET, agentId: found.AGENT_ID }, file);
+    }
+    if (cur === stop || dirname6(cur) === cur) break;
+  }
+  if (cliConfig) {
+    return validate2({ apiUrl: cliConfig.apiUrl, token: cliConfig.apiToken, agentId: cliConfig.agentId }, "cli-config");
+  }
+  return { ok: false, reason: `no pitboss agent configured for ${start}: run \`pitboss join\` there` };
+}
+
 // src/commands/watch.ts
 function truncate(s, n) {
   const clean = (s ?? "").replace(/\s+/g, " ").trim();
@@ -19783,15 +20165,75 @@ async function consumeEventStream(stream, onEvent) {
     const { done, value } = await reader.read();
     if (done) break;
     buffer += decoder.decode(value, { stream: true });
-    let sep;
-    while ((sep = buffer.indexOf("\n\n")) !== -1) {
-      const event = parseSseFrame(buffer.slice(0, sep));
-      buffer = buffer.slice(sep + 2);
+    let sep2;
+    while ((sep2 = buffer.indexOf("\n\n")) !== -1) {
+      const event = parseSseFrame(buffer.slice(0, sep2));
+      buffer = buffer.slice(sep2 + 2);
       if (event) onEvent(event);
     }
   }
 }
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+function printAndExit(line, code) {
+  return new Promise(() => process.stdout.write(`${line}
+`, () => process.exit(code)));
+}
+var refuse = (reason) => printAndExit(`${REFUSED_MARKER} ${reason}`, 1);
+async function watchOnce(dir) {
+  const found = resolveAgentCreds({ dir, env: process.env, cliConfig: readConfig() });
+  if (!found.ok) return refuse(found.reason);
+  const { apiUrl, token: token2, agentId } = found.creds;
+  const auth = { Authorization: `Bearer ${token2}` };
+  const state = join10(configDir(), "wake");
+  const key = wakeKey(agentId, dir);
+  process.on("exit", registerWatcher(state, key));
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, () => process.exit(130));
+  let backoffMs = 1e3;
+  let subscribed = false;
+  for (; ; ) {
+    try {
+      const probe = await fetch(`${apiUrl}/agents/${agentId}`, { headers: auth });
+      if (probe.status === 401 || probe.status === 403 || probe.status === 404) {
+        return refuse(`the API answered ${probe.status} for ${agentId} (from ${found.source}): token revoked or agent deleted`);
+      }
+      if (!subscribed) {
+        const sub = await fetch(`${apiUrl}/subscriptions`, {
+          method: "POST",
+          headers: { ...auth, "Content-Type": "application/json" },
+          body: JSON.stringify({ agentId, targetType: "agent", targetId: agentId })
+        });
+        subscribed = sub.ok;
+      }
+      const cursor = readCursor(state, key);
+      const res = await fetch(`${apiUrl}/events`, {
+        headers: { ...auth, Accept: "text/event-stream", ...cursor ? { "Last-Event-ID": cursor } : {} }
+      });
+      if (res.status === 401 || res.status === 403) return refuse(`the event stream answered ${res.status} for ${agentId}`);
+      if (!res.ok || !res.body) throw new Error(`event stream returned ${res.status}`);
+      resetFollowups(state, key);
+      const connectedAt = Date.now();
+      let wake;
+      try {
+        wake = await readWake(res.body);
+      } finally {
+        if (Date.now() - connectedAt > 1e4) backoffMs = 1e3;
+      }
+      if (wake.lastId) writeCursor(state, key, wake.lastId);
+      if (wake.truncated) {
+        backoffMs = 1e3;
+        continue;
+      }
+      if (!wake.first) throw new Error("event stream closed");
+      return printAndExit(JSON.stringify(wake.count > 1 ? { ...wake.first, more: wake.count - 1 } : wake.first), 0);
+    } catch (err) {
+      console.error(`pitboss watch: ${err.message}; reconnecting in ${Math.round(backoffMs / 1e3)}s`);
+      await sleep2(backoffMs);
+      backoffMs = Math.min(backoffMs * 2, 3e4);
+    }
+  }
+}
 async function watchCommand(options) {
+  if (options.once) return watchOnce(options.dir ?? process.cwd());
   const config = requireConfig();
   const client = new CliApiClient(config);
   const kinds = options.kinds ? new Set(options.kinds.split(",").map((k) => k.trim()).filter(Boolean)) : null;
@@ -19832,14 +20274,112 @@ async function watchCommand(options) {
   }
 }
 
+// src/commands/hook.ts
+import { readFileSync as readFileSync10 } from "node:fs";
+import { join as join11 } from "node:path";
+var FOLLOWUP_CAP = 3;
+function wakeInstructions(watch, opening) {
+  return `${opening}
+
+    ${watch}
+
+It blocks at zero model cost. Two different things end it, and they need different responses. Check the background task's output before doing anything else.
+
+CASE 1: the output contains pitboss event JSON. A real event arrived (a task assigned to you, a message, a review).
+  1. Call the pitboss session_start tool to reconcile unread tasks and messages. The event is only a "go look now" trigger; do not act on its payload alone.
+  2. Handle everything new. Reply to questions on the thread they were asked on, not in local chat.
+  3. Relaunch the watcher in the background.
+
+CASE 2: the output contains no event JSON. Something killed the watcher and nothing happened in pitboss. Relaunch it in the background and resume what you were doing; do not call session_start.
+
+CASE 3: there is no event JSON and the output contains ${REFUSED_MARKER}. The watcher cannot use this agent's config (revoked token, deleted agent, bad URL). Do NOT relaunch. Tell the user what the line says and stop watching for this session.
+
+Decide CASE 1 on the event JSON first, and only then look for the marker: event payloads carry text other agents wrote.`;
+}
+function claudeHookOutput(event, payload, ctx) {
+  if (event === "Stop" && ctx.followups >= FOLLOWUP_CAP) return null;
+  if (event === "Stop") {
+    let p = null;
+    try {
+      p = JSON.parse(payload);
+    } catch {
+      p = null;
+    }
+    if (p === null || typeof p !== "object") {
+      if (ctx.watcherAlive()) return null;
+    } else {
+      if (p.stop_hook_active) return null;
+      const live = (p.background_tasks ?? []).some(
+        (t) => isWatcherCommand(String(t.command ?? "")) && (t.status === "running" || t.status === "pending")
+      );
+      if (live) return null;
+    }
+  }
+  const opening = event === "Stop" ? "The pitboss watcher is NOT RUNNING for this folder, so nothing will wake you. Relaunch it in the background NOW (Bash tool, run_in_background: true), then carry on:" : "Pitboss wake-ups are enabled for this folder. Launch the watcher in the background NOW (Bash tool, run_in_background: true), then continue working normally:";
+  return { hookSpecificOutput: { hookEventName: event, additionalContext: wakeInstructions(watchCommandLine(ctx.cli, ctx.dir), opening) } };
+}
+function cursorStopOutput(payload, ctx) {
+  let status;
+  try {
+    status = JSON.parse(payload).status;
+  } catch {
+    return {};
+  }
+  if (status !== "completed" || ctx.followups >= FOLLOWUP_CAP || ctx.watcherAlive()) return {};
+  return {
+    followup_message: `Your pitboss watcher is not running, so you will miss the next task or message. Start \`${watchCommandLine(ctx.cli, ctx.dir)}\` as a background command, then end your turn. When it finishes, decide on its event JSON first; only output with no event JSON can carry a marker. On ${REFUSED_MARKER}, tell the user and do not relaunch.`
+  };
+}
+function readStdin() {
+  if (process.stdin.isTTY) return "";
+  try {
+    return readFileSync10(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+function wakeStateFor(dir) {
+  const found = resolveAgentCreds({ dir, env: {}, cliConfig: null });
+  if (!found.ok) return null;
+  const state = join11(configDir(), "wake");
+  const key = wakeKey(found.creds.agentId, dir);
+  return {
+    watcherAlive: () => watcherAlive(state, key),
+    followups: followupCount(state, key),
+    asked: () => recordFollowup(state, key)
+  };
+}
+function hookClaudeCommand(opts) {
+  const event = opts.event === "Stop" ? "Stop" : "SessionStart";
+  const payload = readStdin();
+  let cwd;
+  try {
+    cwd = JSON.parse(payload).cwd;
+  } catch {
+    cwd = void 0;
+  }
+  const dir = process.env.CLAUDE_PROJECT_DIR || typeof cwd === "string" && cwd || process.cwd();
+  const wake = wakeStateFor(dir);
+  if (!wake) return;
+  const out = claudeHookOutput(event, payload, { cli: pinnedCli(CLI_VERSION), dir, ...wake });
+  if (out && event === "Stop") wake.asked();
+  if (out) process.stdout.write(JSON.stringify(out));
+}
+function hookCursorStopCommand(opts) {
+  const dir = opts.dir ?? process.cwd();
+  const wake = wakeStateFor(dir);
+  if (!wake) {
+    process.stdout.write("{}");
+    return;
+  }
+  const out = cursorStopOutput(readStdin(), { cli: pinnedCli(CLI_VERSION), dir, ...wake });
+  if ("followup_message" in out) wake.asked();
+  process.stdout.write(JSON.stringify(out));
+}
+
 // src/index.ts
-import { fileURLToPath } from "node:url";
-var __here = dirname4(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(
-  readFileSync6(join5(__here, "../package.json"), "utf8")
-);
 var program2 = new Command();
-program2.name("pitboss").description("Coordinate your coding agents from the terminal").version(pkg.version).option("--no-input", "Never prompt; require values via flags").hook("preAction", (thisCommand) => {
+program2.name("pitboss").description("Coordinate your coding agents from the terminal").version(CLI_VERSION).option("--no-input", "Never prompt; require values via flags").hook("preAction", (thisCommand) => {
   if (thisCommand.opts().input === false) process.env.RELAI_NO_INPUT = "1";
 });
 program2.command("mcp", { hidden: true }).description("Run the MCP server on stdio (used by agent config, not by hand)").allowUnknownOption().action(mcpCommand);
@@ -19847,7 +20387,10 @@ program2.command("join").description("Connect this machine's agents: opens a cod
 program2.command("init").description("Alias for `join`, kept so existing docs keep working").option("--api <url>", "relai API base URL (defaults to the hosted one)").action(joinCommand);
 program2.command("status").description("Show your agent info, online agents, task summary, and unread count").action(statusCommand);
 program2.command("start").description("Show your session orientation: project context, your open tasks, unread messages, open threads").action(startCommand);
-program2.command("watch").description("Stream live events you're subscribed to (new tasks, messages, reviews) until Ctrl-C").option("--kinds <list>", "Only show these event kinds (comma-separated, e.g. task.created,message.posted)").action(watchCommand);
+program2.command("watch").description("Stream live events you're subscribed to (new tasks, messages, reviews) until Ctrl-C").option("--kinds <list>", "Only show these event kinds (comma-separated, e.g. task.created,message.posted)").option("--once", "Block until the next event for this folder's agent, print it as JSON, and exit").option("--dir <path>", "Folder whose agent config --once uses (defaults to the current directory)").action(watchCommand);
+var hook = program2.command("hook", { hidden: true }).description("Agent runtime hooks that keep the watcher running (installed by join)");
+hook.command("claude").description("Claude Code SessionStart/Stop hook").option("--event <event>", "SessionStart | Stop", "SessionStart").action(hookClaudeCommand);
+hook.command("cursor-stop").description("Cursor stop hook").option("--dir <path>", "The agent's folder").action(hookCursorStopCommand);
 program2.command("tasks").description("List tasks assigned to you (default: assigned + in_progress)").option("-a, --all", "Show all tasks in the project, not just yours").option("-s, --status <status>", "Filter by status (comma-separated: pending,assigned,in_progress,pending_verification,completed,blocked)").action(tasksCommand);
 var task = program2.command("task").description("Create or update a task");
 task.command("create").description("Create a new task").option("-t, --title <title>", "Task title").option("-d, --description <description>", "Task description").option("-p, --priority <priority>", "low|normal|high|urgent").option("--to <agent>", "Assign to an agent (id or name)").option("--domains <list>", "Comma-separated domain tags").option("--specialization <s>", "Required specialization").option("-v, --verify <cmd>", "Shell command that must exit 0 to gate the `completed` transition").option("--verify-cwd <path>", "Working directory for --verify (defaults to API server cwd)").option("--verify-kind <kind>", "Verifier kind: shell|file_exists|thread_concluded|reviewer_agent").option("--verify-path <path>", "Path that must exist (--verify-kind file_exists)").option("--verify-thread <id>", "Thread that must be concluded (--verify-kind thread_concluded)").option("--verify-reviewer <agent>", "Agent (id or name) who must approve (--verify-kind reviewer_agent)").option("--review-by <agent>", "Shorthand for --verify-kind reviewer_agent --verify-reviewer <agent>").action(taskCreateCommand);

package/dist/mcp.js

@@ -12847,14 +12847,19 @@ ${version.body}`
     },
     {
       name: "add_task_comment",
-      description: "Post a comment on a task's discussion thread. The task's thread is created lazily on first access \u2014 you don't need to create a thread first. Use this to record findings, review notes, or status updates directly on the task rather than in a separate thread. Prefer 'finding' or 'status' as the type for inline notes.",
+      description: "Post a comment on a task's discussion thread. The task's thread is created lazily on first access \u2014 you don't need to create a thread first. Use this to record findings, review notes, or status updates directly on the task rather than in a separate thread. Prefer 'finding' or 'status' as the type for inline notes. When you report progress or hand work back, set toAgent to the agent you report to (the task's createdBy unless you were told otherwise) so the comment is addressed to them.",
       inputSchema: external_exports.object({
         taskId: external_exports.string().describe("The task to comment on."),
         body: external_exports.string().min(1).describe("Comment text."),
-        type: external_exports.enum(["status", "handoff", "finding", "decision", "question", "escalation", "reply"]).optional().describe("Message type. Defaults to 'status'.")
+        type: external_exports.enum(["status", "handoff", "finding", "decision", "question", "escalation", "reply"]).optional().describe("Message type. Defaults to 'status'."),
+        toAgent: external_exports.string().optional().describe("Agent ID to address: the agent you report to, usually the task's createdBy. Must be in the task's repo or be its creator.")
       }),
       handler: async (input) => {
-        const message = await client.addTaskComment(input.taskId, { body: input.body, type: input.type });
+        const message = await client.addTaskComment(input.taskId, {
+          body: input.body,
+          type: input.type,
+          ...input.toAgent ? { toAgent: input.toAgent } : {}
+        });
         return { content: [{ type: "text", text: JSON.stringify(message, null, 2) }] };
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitboss/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "private": false,
   "description": "Connect your coding agents to a pitboss instance",
   "keywords": [