agentradar-cli 0.2.3 → 0.2.5

package/dist/agent-guard/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "agentradar",
+  "description": "AgentRadar plugins for agents working on the rail.",
+  "owner": {
+    "name": "AgentRadar"
+  },
+  "plugins": [
+    {
+      "name": "agent-guard",
+      "source": "./",
+      "description": "AgentRadar work discipline for agents on the rail."
+    }
+  ]
+}

package/dist/agent-guard/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "agent-guard",
+  "version": "0.1.0",
+  "description": "AgentRadar work discipline: no going idle while a message or task is owed, and a periodic reminder of the house rules.",
+  "author": { "name": "AgentRadar" },
+  "license": "MIT"
+}

package/dist/agent-guard/hooks/hooks.json

@@ -0,0 +1,7 @@
+{
+  "description": "Blocks going idle while AgentRadar work is owed; reminds of the house rules every AR_DISCIPLINE_EVERY turns.",
+  "hooks": {
+    "Stop": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/guard.mjs\" stop", "timeout": 30 }] }],
+    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/guard.mjs\" prompt", "timeout": 10 }] }]
+  }
+}

package/dist/agent-guard/scripts/guard.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// AgentRadar agent-guard: `guard.mjs stop` (Stop hook) and `guard.mjs prompt` (UserPromptSubmit hook).
+// Claude Code and Codex share the hook I/O used here: JSON on stdin, JSON decision on stdout.
+//
+// stop:   asks the server (`agentradar call <runner> agent_obligations`) what the agent still owes and
+//         blocks the stop while a message or task is unacknowledged, at most MAX_BLOCKS times in a row.
+//         Tasks still in progress get one reminder. Anything unexpected (no runner, server down, bad
+//         output) lets the agent stop: a guard that wedges the session is worse than no guard.
+// prompt: every AR_DISCIPLINE_EVERY turns (default 20, 0 = off) re-adds the house rules, the must-nots
+//         and the installed skills to the context.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MAX_BLOCKS = 3;
+const runner = process.env.AR_CLI_RUNNER_ID ?? "";
+const cli = process.env.AR_AGENTRADAR_BIN || "agentradar";
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, "utf8") || "{}"); } catch {}
+// ponytail: no lock; one session's hooks run one at a time.
+const stateDir = process.env.CLAUDE_PLUGIN_DATA || tmpdir();
+const stateFile = join(stateDir, `agent-guard-${String(input.session_id ?? "none").replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+let state = { turns: 0, blocks: 0 };
+try { state = { ...state, ...JSON.parse(readFileSync(stateFile, "utf8")) }; } catch {}
+const save = () => { try { mkdirSync(stateDir, { recursive: true }); writeFileSync(stateFile, JSON.stringify(state)); return true; } catch { return false; } };
+const call = (tool) => `agentradar call ${runner} ${tool}`;
+
+const RULES = [
+  "Answer every message in the channel it came from, and a human first: someone is waiting.",
+  `Acknowledge what you handled: ${call("acknowledge_messages")} --args '{"eventIds":[...]}' for messages, ${call("acknowledge_task")} --issueId <id> for a task you take on.`,
+  "Talk is not a task: reply conversationally, and create a task only for trackable, billable work.",
+  "Write so a 13-year-old would understand: short, plain words, one next step, no ids or tool names unless asked. Say it once.",
+  `Before you go idle, run ${call("agent_obligations")}: "owed" must be 0, and every in-progress task must be moving or waiting on someone who knows it.`,
+];
+const MUST_NOTS = [
+  "Never ask for, print or pass on a credential. AgentRadar holds the keys.",
+  `Never call decide_outcome or declare_outcome on your own task: only a human accepts your work. Record the final state with ${call("append_task_log")} and reply that it is ready for them.`,
+  "Never contact the platform team (submit_feedback) unless the human asks you to.",
+];
+
+// Skill folders the agent can load: this plugin's, the project's, and the user's (Claude Code and Codex).
+function skills() {
+  const dirs = [
+    fileURLToPath(new URL("../skills", import.meta.url)),
+    input.cwd && join(input.cwd, ".claude", "skills"),
+    join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "skills"),
+    process.env.CODEX_HOME && join(process.env.CODEX_HOME, "skills"),
+  ];
+  const names = new Set();
+  for (const dir of dirs) {
+    if (!dir) continue;
+    // statSync follows a symlinked skill folder; a broken link or a plain file is not a skill.
+    try { for (const name of readdirSync(dir)) if (!name.startsWith(".") && statSync(join(dir, name), { throwIfNoEntry: false })?.isDirectory()) names.add(name); } catch {}
+  }
+  return [...names].sort();
+}
+
+if (process.argv[2] === "prompt") {
+  const every = Number.parseInt(process.env.AR_DISCIPLINE_EVERY ?? "20", 10);
+  // No reset of `blocks` here: Codex may run this hook for a Stop continuation, which would lift the cap.
+  state.turns += 1;
+  save();
+  if (runner && every > 0 && state.turns % every === 0) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext: [
+          `AgentRadar house rules (reminder every ${every} turns):`,
+          ...RULES.map((rule, i) => `${i + 1}. ${rule}`),
+          "You must not:",
+          ...MUST_NOTS.map((rule) => `- ${rule}`),
+          `Your skills (load the one that fits before acting): ${skills().join(", ") || "none installed"}.`,
+        ].join("\n"),
+      },
+    }));
+  }
+} else if (process.argv[2] === "stop" && runner) {
+  const reason = stopReason();
+  state.blocks += 1;
+  // A block that cannot be counted is never sent: an unwritable state dir must not lift the cap.
+  if (reason && state.blocks <= MAX_BLOCKS && save()) {
+    process.stdout.write(JSON.stringify({ decision: "block", reason }));
+  } else {
+    if (reason) process.stderr.write(`agent-guard: ${state.blocks > MAX_BLOCKS ? `still owed after ${MAX_BLOCKS} reminders` : "cannot record reminders"}; letting the agent stop\n`);
+    state.blocks = 0;
+    save();
+  }
+}
+
+function stopReason() {
+  const run = spawnSync(cli, ["call", runner, "agent_obligations"], { encoding: "utf8", timeout: 20_000 });
+  if (run.status !== 0) return "";
+  let o;
+  try { o = JSON.parse(run.stdout); } catch { return ""; }
+  const messages = Array.isArray(o.unacknowledgedMessages) ? o.unacknowledgedMessages : [];
+  const tasks = Array.isArray(o.unacknowledgedTasks) ? o.unacknowledgedTasks : [];
+  const working = Array.isArray(o.inProgressTasks) ? o.inProgressTasks : [];
+  const asks = Array.isArray(o.overdueAsks) ? o.overdueAsks : [];
+  const name = (t) => `${t.identifier ?? t.issueId} "${t.title ?? ""}" (issueId ${t.issueId})`;
+  if (messages.length || tasks.length || asks.length) {
+    return [
+      `AgentRadar: you still owe ${messages.length + tasks.length + asks.length} item(s). Do not go idle yet.`,
+      ...(messages.length ? [
+        `Messages received but not acknowledged: ${messages.join(", ")}. Each reached you earlier in this session as an event carrying that eventId (${call("read_history")} --conversationId <its conversationId> shows the thread). Reply to each in the channel it came from (a human first), then ${call("acknowledge_messages")} --args '${JSON.stringify({ eventIds: messages })}'.`,
+      ] : []),
+      ...tasks.map((t) => `Task assigned to you, not acknowledged: ${name(t)}. Take it on or say why not, then ${call("acknowledge_task")} --issueId ${t.issueId}.`),
+      ...asks.map((a) => `Nobody answered your ask in thread ${a.threadId} (due ${a.dueAt}${a.note ? `; ${a.note}` : ""}). Chase them in that thread, or if it no longer matters ${call("expect_reply")} --args '${JSON.stringify({ conversationId: a.threadId, by: null })}'.`),
+      `Check again with ${call("agent_obligations")}, then stop.`,
+    ].join("\n");
+  }
+  // Only once per stop: when this stop is itself the result of a block, the agent has seen it.
+  if (working.length && !input.stop_hook_active) {
+    return [
+      `AgentRadar: ${working.length} task(s) still in progress: ${working.map(name).join("; ")}.`,
+      "Keep working on them, or, if one is waiting on someone, make sure its thread says so, then stop.",
+    ].join("\n");
+  }
+  return "";
+}

package/dist/agent-guard/skills/agentradar-discipline/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: agentradar-discipline
+description: >
+  House rules for an agent working through AgentRadar. Use before going idle, after receiving a
+  channel message or an assigned task, and whenever unsure whether something is still owed.
+---
+
+# AgentRadar discipline
+
+You act through `agentradar call <runner-id> <tool>`. Your runner id is in `$AR_CLI_RUNNER_ID`.
+
+## Before you go idle
+
+1. Run `agentradar call $AR_CLI_RUNNER_ID agent_obligations`.
+2. `owed` must be 0:
+   - each id in `unacknowledgedMessages` is a message you received and have not handled. Reply in the channel it came from, then `agentradar call $AR_CLI_RUNNER_ID acknowledge_messages --args '{"eventIds":["<id>"]}'`;
+   - each entry in `unacknowledgedTasks` is a task assigned to you. Read it, take it on or say why not, then `agentradar call $AR_CLI_RUNNER_ID acknowledge_task --issueId <issueId>`.
+3. Each entry in `inProgressTasks` is either still moving, or its thread says who it is waiting on.
+4. Each entry in `overdueAsks` is a question nobody answered in time. Chase them in that thread with `reply`.
+
+The Stop hook runs the same check and will not let you stop while something is owed.
+
+## Always
+
+- Answer every message in the channel it came from. A human who wrote is waiting for you; answer them first.
+- Talk is not a task. Reply conversationally by default; create a task only for trackable, billable work.
+- Write to people so a 13-year-old would understand: a few short lines in plain words, ending with one next step (not a menu of options), no ids, tool names or internal terms unless asked. Say a thing once. Follow what they told you for the rest of the chat, and never offer to contact anyone else unless they ask.
+- Never ask for, print or pass on a credential. AgentRadar holds the keys.
+- When you ask another agent or a human something, call `expect_reply` on that thread with the time you need the answer by. If nobody answers, `next_event` wakes you with kind `followup`: chase them in the thread. If they stay silent, you may escalate to the next human up the chain from the person you wait on; that is your call, never required.
+- Only a human accepts your work. Asked to "mark it done": record the final state with `append_task_log`, then reply that it is finished and ready for them to accept. Never call `decide_outcome` or `declare_outcome` on your own task.
+- Never contact the platform team (`submit_feedback`) unless the human asks you to. "Just handle it" means do the work in your own tools, not report it to AgentRadar.

package/dist/agentradar-vendor/SKILL.md

@@ -20,8 +20,14 @@ You work on the vendor's computer and connect to AgentRadar through the `agentra
 
 Call `get_my_context` on the AgentRadar MCP FIRST, before any other tool. It returns your client organisation, your role and function, your goals, your metrics with their current quotas, your superior, your direct reports and your colleagues. It also carries your memory snapshot, the Markdown files in your personal vault: `recall` fetches newer files and `remember` saves a durable fact, preference or correction.
 
+In your first session, call `read_onboarding_obligations` once (reading them acknowledges the safety rules), then `read_readiness`.
+
 Your primary objective is to reach your quotas and drive the organisation forward in your role. Report each metric you own with `report_metric`. You may create metrics for yourself; you can never change your own quota — your superior sets it. Talk only in shared spaces (channels and tasks). You can create one-off tasks (`create_task`) and repeated tasks (`create_recurring_task`) for yourself, your colleagues and your direct subordinates — only for real trackable work, never for conversation.
 
+## Talking to people
+
+Write to people so a 13-year-old would understand: a few short plain lines, then one next step, not a menu. No ids, tool names or internal terms unless asked (say "the owner", "your team", "company memory"; name a plan with its monthly price). Answer only what was asked, and say it once. Keep to what a person told you all chat, say so before a step they may not expect (a web search, sending, hiring), and never offer to contact anyone unless asked. Never talk about how messages reach you. Do the obvious thing for "undo that"; if unclear, offer short choices. Check your tools before saying what is scheduled or done; never answer from memory.
+
 ## Work loop
 
 1. Use the AgentRadar MCP to receive the next event or assigned work.

package/dist/runner.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { shellValue, trustedMcpEndpoint, writePrivateFile } from "./setup.js";
 import { callAwpTool, envValue } from "./tool-run.js";
+import { installedVersion, runningVersion, selfUpdate } from "./update.js";
 const RUNNER_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 const ENGAGEMENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 // Per-hire bearers are ordinary agent keys (`pcp_…`); the runner's own is an AWP key (`ar_…`).
@@ -14,6 +15,8 @@ const HIRE_BEARER = /^(ar|pcp)_[A-Za-z0-9_-]+$/;
 // A hire always runs Claude, whose MCP config it owns; a Codex home would be the catalog agent's.
 const HIRE_OWN_KEYS = /^(export\s+)?(AGENT_NAME|AR_BASE|AWP_MCP_URL|AWP_BEARER|AWP_BEARER_FILE|MCP_CONFIG|TMUX_SESSION|AGENT_PID_PATTERN|AR_AGENT_HARNESS|CODEX_HOME)=/;
 const CODEX_HARNESS = /^(export\s+)?AR_AGENT_HARNESS=\s*["']?codex\b/m;
+// While a pane shows this, its agent is mid-turn (the feeder's in-progress hint, same for Claude and Codex).
+const MID_TURN = /esc to interrupt|\besc to cancel\b/i;
 const run = promisify(execFile);
 /** Run from outside the target harness: the command deliberately replaces that harness process. */
 export async function runRestartSelftest(runnerId, deps = {}) {
@@ -227,7 +230,22 @@ export async function startVendorRunner(runnerId, home = homedir(), deps = {}) {
     const spawnChild = deps.spawn ?? ((command, args) => spawn(command, args, { stdio: "inherit", env: process.env }));
     const hires = new Map();
     let timer;
+    let updateTimer;
     let stopped = false;
+    let updating = false;
+    const tmux = deps.tmux ?? (async (args) => (await run("bash", [
+        "-c", 'PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"; exec "${TMUX_BIN:-tmux}" "$@"', "tmux", ...args,
+    ])).stdout);
+    const installed = deps.installed ?? (() => installedVersion());
+    // Unknown (package.json unreadable): auto-update stays off rather than restart on every check.
+    const running = await (deps.installed ? installed() : runningVersion()).catch(() => null);
+    // Only our own LaunchAgent / systemd unit sets AGENTRADAR_SERVICE=1, and only they restart the runner.
+    // Not the parent pid: a nohup/setsid start is reparented to launchd or a subreaper too, and would be
+    // killed for an update with nothing to start it again. Every other runner installs updates, never exits.
+    const serviced = deps.serviced ?? process.env.AGENTRADAR_SERVICE === "1";
+    // Read once, then dropped: the supervisor's tmux server would otherwise pass it to every runner a vendor
+    // later starts by hand in that tmux, and those would exit for an update with nothing to restart them.
+    delete process.env.AGENTRADAR_SERVICE;
     const runHire = (hireEnv) => {
         if (stopped || hires.has(hireEnv))
             return;
@@ -399,12 +417,87 @@ export async function startVendorRunner(runnerId, home = homedir(), deps = {}) {
         const stop = () => {
             stopped = true;
             clearTimeout(timer);
+            clearTimeout(updateTimer);
             for (const child of hires.values())
                 child.kill("SIGTERM");
         };
+        // Every tmux session this runner owns: the shared agent's and each hire's.
+        let sessions = [];
+        const sessionNames = async () => (await Promise.all([envPath, ...hires.keys()].map(async (file) => {
+            const contents = await readFile(file, "utf8").catch(() => "");
+            return envValue(contents, "TMUX_SESSION") ?? envValue(contents, "AGENT_NAME");
+        }))).filter((name) => Boolean(name));
+        const midTurn = async () => {
+            for (const name of await sessionNames()) {
+                if (MID_TURN.test(await tmux(["capture-pane", "-p", "-t", `=${name}:`]).catch(() => "")))
+                    return true;
+            }
+            return false;
+        };
         const shared = spawnChild("bash", [supervisor, envPath]);
         shared.once("error", (error) => { stop(); reject(error); });
-        shared.once("exit", (code, signal) => { stop(); resolvePromise(code ?? (signal ? 1 : 0)); });
+        shared.once("exit", (code, signal) => {
+            stop();
+            if (!updating)
+                return resolvePromise(code ?? (signal ? 1 : 0));
+            // The supervisors are gone, so nothing relaunches the old panes: end them, and exit for launchd or
+            // systemd to start this runner on the new code, whose supervisors resume each session (AR_RESUME_FLAGS)
+            // with the new agent-guard plugin, which loads in place from this package.
+            void Promise.all(sessions.map((name) => tmux(["kill-session", "-t", `=${name}`]).catch(() => "")))
+                .then(() => resolvePromise(0));
+        });
+        // The package is shared by every agent on this machine, so AGENTRADAR_NO_AUTO_UPDATE=1 in the service's
+        // environment or in any agent's env file turns updates off for all of them.
+        const optedOut = async () => {
+            const values = [process.env.AGENTRADAR_NO_AUTO_UPDATE];
+            for (const file of await readdir(agentDir).catch(() => [])) {
+                if (file.endsWith(".env"))
+                    values.push(envValue(await readFile(join(agentDir, file), "utf8").catch(() => ""), "AGENTRADAR_NO_AUTO_UPDATE") ?? undefined);
+            }
+            return values.some((value) => value && value !== "0");
+        };
+        // At start and then daily: install npm's latest release. Every tick: restart onto whatever is on disk if
+        // it is not what this process runs (another runner on this machine may have installed it). A restart
+        // waits for every pane to finish its turn, for at most an hour.
+        let nextCheck = 0;
+        let told = "";
+        const autoUpdate = async () => {
+            try {
+                if (running && !(await optedOut())) {
+                    if (Date.now() >= nextCheck) {
+                        nextCheck = Date.now() + (deps.updateEveryMs ?? 86_400_000);
+                        const fresh = await (deps.update ?? selfUpdate)();
+                        if (fresh)
+                            log(`AgentRadar CLI ${fresh} installed (was ${running})`);
+                    }
+                    const onDisk = await installed();
+                    if (onDisk !== running && !serviced) {
+                        if (told !== onDisk)
+                            log(`AgentRadar CLI ${onDisk} is installed; restart this runner to use it`);
+                        told = onDisk;
+                    }
+                    else if (onDisk !== running) {
+                        for (let i = 0; i < 240 && !stopped && await midTurn(); i += 1) {
+                            await new Promise((resolveWait) => setTimeout(resolveWait, deps.idlePollMs ?? 15_000));
+                        }
+                        if (stopped)
+                            return;
+                        log(`Restarting on AgentRadar CLI ${onDisk}; each session resumes where it was`);
+                        sessions = await sessionNames();
+                        updating = true;
+                        stop();
+                        shared.kill("SIGTERM");
+                        return;
+                    }
+                }
+            }
+            catch (error) {
+                log(`Auto-update failed, staying on ${running}: ${error.message}`);
+            }
+            if (!stopped)
+                updateTimer = setTimeout(autoUpdate, deps.tickMs ?? 60_000);
+        };
+        void autoUpdate();
         hireTick()
             .then((tick) => {
             // The next tick is scheduled only after this one finishes, so a slow clone never overlaps another.

package/dist/setup.js

@@ -1,12 +1,16 @@
 import { createHash } from "node:crypto";
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
 import { chmod, cp, lstat, mkdir, readFile, readlink, realpath, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import * as tls from "node:tls";
 import { promisify } from "node:util";
+import { syncJoinedSkills } from "./skill-install.js";
 const DEFAULT_API_URL = "https://vendor.agentradar.com/api";
+/** The service's CLI build (the CLI itself and the agent-guard plugin): `installCli` keeps it current, never the npx cache. */
+const cliDist = (home) => join(home, ".agentradar", "cli", "current", "dist");
 /** `ar_` is a vendor runner bearer; `pcp_` is the key an organisation's own agent claims through `join`. */
 const BEARER_SHAPE = /^(?:ar|pcp)_[A-Za-z0-9_-]+$/;
 /**
@@ -241,12 +245,13 @@ async function codexServiceHome(home, runnerId, env) {
     const codexHome = join(home, ".agentradar", "codex", runnerId);
     await mkdir(codexHome, { recursive: true, mode: 0o700 });
     await chmod(codexHome, 0o700);
-    let inMcp = false;
+    let dropTable = false;
     let inTable = false;
     let depth = 0;
     let dropping = false;
     const text = { open: null };
     // A restart would otherwise stop on Codex's "Update available" screen, with nobody there to press a key.
+    // The vendor's own hooks stay out too: the service runs AgentRadar's guard and nothing it did not review.
     const config = ["check_for_update_on_startup = false", ...(await readFile(join(source, "config.toml"), "utf8").catch(() => "")).split("\n").filter((line) => {
             // Brackets inside strings and comments don't count; a line inside a multi-line array or string goes with its key.
             const continued = depth > 0 || text.open !== null;
@@ -254,18 +259,31 @@ async function codexServiceHome(home, runnerId, env) {
             depth = Math.max(0, depth + (bare.match(/\[/g)?.length ?? 0) - (bare.match(/\]/g)?.length ?? 0));
             if (continued)
                 return !dropping;
+            // An escape in a quoted key ("\u0068ooks") could name mcp_servers or hooks past both checks.
+            if (/^\s*(?:\[\[?\s*)?(?:[\w-]+\s*\.\s*)*"[^"\n]*\\/.test(line))
+                throw new Error(`${join(source, "config.toml")} has a quoted key with an escape; spell it plainly and run join again`);
             const header = /^\s*\[\[?\s*([^\]]+)\]/.exec(line);
             if (header) {
-                inMcp = /^["']?mcp_servers\b/.test(header[1]);
+                dropTable = /^["']?(?:mcp_servers|hooks)\b/.test(header[1]);
                 inTable = true;
             }
-            dropping = inMcp || /^\s*["']?mcp_servers["']?\s*[.=]/.test(line) || (!inTable && /^\s*["']?check_for_update_on_startup["']?\s*=/.test(line));
+            dropping = dropTable || /^\s*["']?(?:mcp_servers|hooks)["']?\s*[.=]/.test(line) || (!inTable && /^\s*["']?check_for_update_on_startup["']?\s*=/.test(line));
             return !dropping;
         })].join("\n");
-    // Fail closed: another client's MCP server must never reach this client's session.
-    if (/^\s*(?:\[\[?\s*)?["']?mcp_servers\b/m.test(config))
-        throw new Error(`Could not strip the MCP servers from ${join(source, "config.toml")}; simplify it and run join again`);
+    // Fail closed: another client's MCP server, or a hook we did not review, must never reach this client's session.
+    if (/^\s*(?:\[\[?\s*)?["']?(?:mcp_servers|hooks)\b/m.test(config))
+        throw new Error(`Could not strip the MCP servers and hooks from ${join(source, "config.toml")}; simplify it and run join again`);
     await writePrivateFile(join(codexHome, "config.toml"), config);
+    const guard = `node ${JSON.stringify(join(cliDist(home), "agent-guard", "scripts", "guard.mjs"))}`;
+    await writePrivateFile(join(codexHome, "hooks.json"), `${JSON.stringify({ hooks: {
+            Stop: [{ hooks: [{ type: "command", command: `${guard} stop`, timeout: 30 }] }],
+            UserPromptSubmit: [{ hooks: [{ type: "command", command: `${guard} prompt`, timeout: 10 }] }],
+        } }, null, 2)}\n`);
+    const trusted = await codexHookHashes(codexHome, env).catch(() => []);
+    if (trusted.length) {
+        await writePrivateFile(join(codexHome, "config.toml"), `${config.replace(/\n*$/, "\n")}${trusted
+            .map(({ key, hash }) => `\n[hooks.state.${JSON.stringify(key)}]\ntrusted_hash = ${JSON.stringify(hash)}\n`).join("")}`);
+    }
     await cp(join(source, "rules"), join(codexHome, "rules"), { recursive: true, force: true }).catch((error) => {
         if (error.code !== "ENOENT")
             throw error;
@@ -278,6 +296,46 @@ async function codexServiceHome(home, runnerId, env) {
     }
     return { codexHome, keys: [...config.matchAll(/^\s*env_key\s*=\s*"([A-Za-z_][A-Za-z0-9_]*)"/gm)].map((match) => match[1]) };
 }
+/**
+ * Codex runs a user hook only once its hash is recorded as trusted (`[hooks.state."<key>"] trusted_hash`),
+ * which is what its /hooks review writes. Asks Codex itself for the keys and hashes of the hooks in
+ * `<codexHome>/hooks.json` (app-server `hooks/list`), so the hash is never recomputed here. Any failure
+ * leaves them untrusted: Codex then skips them, and the agent runs without the guard rather than not at all.
+ */
+async function codexHookHashes(codexHome, env) {
+    const child = spawn(env.CODEX_BIN || "codex", ["app-server"], { cwd: codexHome, env: { ...env, CODEX_HOME: codexHome }, stdio: ["pipe", "pipe", "ignore"] });
+    const lines = createInterface({ input: child.stdout });
+    // A child that never spawned (no codex on PATH) emits no end on stdout; closing the reader ends the loop.
+    const stop = () => { child.kill(); lines.close(); };
+    const timer = setTimeout(stop, 20_000);
+    try {
+        child.on("error", stop);
+        child.stdin.on("error", () => undefined);
+        const send = (message) => child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+        send({ id: 1, method: "initialize", params: { clientInfo: { name: "agentradar", version: "0" } } });
+        send({ method: "initialized" });
+        send({ id: 2, method: "hooks/list", params: { cwds: [codexHome] } });
+        for await (const line of lines) {
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (message.id !== 2)
+                continue;
+            return (message.result?.data ?? []).flatMap((entry) => entry.hooks ?? [])
+                .filter((hook) => hook.source === "user" && basename(hook.sourcePath) === "hooks.json")
+                .map((hook) => ({ key: hook.key, hash: hook.currentHash }));
+        }
+        return [];
+    }
+    finally {
+        clearTimeout(timer);
+        child.kill();
+    }
+}
 async function installRunner(home, projectPath, approved, service) {
     if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(approved.runnerId)) {
         throw new Error("AgentRadar returned an invalid runner ID");
@@ -300,7 +358,7 @@ async function installRunner(home, projectPath, approved, service) {
     const envPath = join(agentDir, `${approved.runnerId}.env`);
     const joined = [];
     if (service) {
-        joined.push(`AR_CLI_RUNNER_ID=${shellValue(approved.runnerId)}`);
+        joined.push(`AR_CLI_RUNNER_ID=${shellValue(approved.runnerId)}`, `AR_AGENTRADAR_BIN=${shellValue(join(cliDist(home), "index.js"))}`);
         let toolKeys = [];
         if (harness === "codex") {
             const { codexHome, keys } = await codexServiceHome(home, approved.runnerId, service.env);
@@ -322,6 +380,14 @@ async function installRunner(home, projectPath, approved, service) {
             const configDirEnv = service.env.CLAUDE_CONFIG_DIR?.trim();
             if (configDirEnv)
                 joined.push(`CLAUDE_CONFIG_DIR=${shellValue(resolve(configDirEnv))}`);
+            // agent-guard, enabled for this session only (`--settings`), loaded from the copy inside this package, with
+            // its plugin state under the runner's config so the vendor's own Claude plugins are never touched.
+            const settings = join(configDir, "agentradar-settings.json");
+            await writePrivateFile(settings, `${JSON.stringify({
+                extraKnownMarketplaces: { agentradar: { source: { source: "directory", path: join(cliDist(home), "agent-guard") } } },
+                enabledPlugins: { "agent-guard@agentradar": true },
+            }, null, 2)}\n`);
+            joined.push(`CLAUDE_SETTINGS=${shellValue(settings)}`, `CLAUDE_CODE_PLUGIN_CACHE_DIR=${shellValue(join(configDir, "plugins"))}`);
         }
         const toolEnv = Object.entries(service.env)
             .filter(([key, value]) => (TOOL_ENV.test(key) || toolKeys.includes(key)) && key !== "ANTHROPIC_API_KEY" && value && !value.includes("\n"))
@@ -459,23 +525,28 @@ export async function installCli(home, pkg = dirname(dirname(fileURLToPath(impor
     if (!(await lstat(target).then(() => true, () => false))) {
         // Staged then renamed, so a half-finished copy is never a version directory.
         const staged = `${target}.${process.pid}.tmp`;
-        await cp(join(pkg, "dist"), join(staged, "dist"), { recursive: true });
-        await cp(join(pkg, "package.json"), join(staged, "package.json"));
-        await rename(staged, target).catch(async (error) => {
+        try {
+            await cp(join(pkg, "dist"), join(staged, "dist"), { recursive: true });
+            await cp(join(pkg, "package.json"), join(staged, "package.json"));
+            await rename(staged, target);
+        }
+        catch (error) {
+            // A copy that fails partway leaves nothing behind; losing the rename to another runner is fine.
             await rm(staged, { recursive: true, force: true });
-            if (error.code !== "ENOTEMPTY" && error.code !== "EEXIST")
+            const code = error.code;
+            if (code !== "ENOTEMPTY" && code !== "EEXIST")
                 throw error;
-        });
+        }
     }
     // Forward only: an older CLI run later (a stale npx cache) never downgrades the service.
     const current = await readlink(join(cli, "current")).catch(() => "");
     if (current && versionRank(current) > versionRank(version))
-        return join(cli, "current", "dist");
+        return cliDist(home);
     const link = join(cli, `current.${process.pid}.tmp`);
     await rm(link, { force: true });
     await symlink(version, link);
     await rename(link, join(cli, "current"));
-    return join(cli, "current", "dist");
+    return cliDist(home);
 }
 /** `install-agent.sh <id> --load` with the CLI at ~/.agentradar/cli/current, so the service does not depend on PATH. */
 async function installAgentService(runnerId, home, env) {
@@ -534,6 +605,10 @@ export async function joinOrganisation(enrolmentUrl, deps = {}) {
         const runnerEnv = await installRunner(home, projectPath, { status: "approved", agentId, runnerId, installation, harness }, { sessionId, env });
         await saved?.();
         log(`Runner installed → ${runnerEnv}`);
+        // Best effort: a failed first sync never stops the join; the service's feeder syncs them again.
+        await syncJoinedSkills(runnerId, { home, fetch: fetchImpl, log }).catch((error) => {
+            log(`Your AgentRadar skills are not installed yet (${String(error?.message ?? error).split("\n")[0]}); the runner installs them once it is running.`);
+        });
         try {
             await (deps.installService ?? ((id) => installAgentService(id, home, env)))(runnerId);
         }

package/dist/skill-install.js

@@ -1,6 +1,9 @@
-import { chmod, lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile, readdir, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, normalize, sep } from "node:path";
+import { awpRequest, envValue } from "./tool-run.js";
+const MANAGED_MARK = ".agentradar-managed";
+const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,99}$/;
 async function ensureDirectory(path) {
     try {
         const info = await lstat(path);
@@ -38,7 +41,71 @@ export async function installVendorSkill(deps = {}) {
         });
     }
     // The runner keeps this skill current from AgentRadar; the marker says the folder is AgentRadar's to replace.
-    await writeFile(join(skillDir, ".agentradar-managed"), "Written by AgentRadar; replaced on every sync.\n");
+    await writeFile(join(skillDir, MANAGED_MARK), "Written by AgentRadar; replaced on every sync.\n");
     (deps.log ?? console.log)("AgentRadar vendor skill installed for this project.");
 }
+const isManaged = async (dir) => (await lstat(dir).then((info) => info.isDirectory(), () => false)) && (await lstat(join(dir, MANAGED_MARK)).then(() => true, () => false));
+/**
+ * The feeder's `writeManagedSkills` (templates/vendor-runner/feeder.mjs), for the CLI: the server's answer is
+ * untrusted input to this box, so names and paths are checked, each skill is staged then renamed into place,
+ * a folder without the marker (the vendor's own) is never touched, and a managed skill no longer listed goes.
+ */
+export async function writeManagedSkills(skillsDir, skills) {
+    await mkdir(skillsDir, { recursive: true });
+    const written = new Set();
+    for (const skill of skills) {
+        const name = String(skill?.name ?? "");
+        const target = join(skillsDir, name);
+        if (!SKILL_NAME.test(name))
+            continue;
+        if (await lstat(target).then(() => true, () => false) && !(await isManaged(target)))
+            continue;
+        const files = (Array.isArray(skill.files) ? skill.files : []);
+        if (files.some((f) => typeof f?.path !== "string" || typeof f?.content !== "string" || isAbsolute(f.path)
+            || normalize(f.path).split(sep).includes("..") || [".", MANAGED_MARK].includes(normalize(f.path))))
+            continue;
+        const staging = join(skillsDir, `.${name}.sync-${process.pid}`);
+        try {
+            await rm(staging, { recursive: true, force: true });
+            for (const f of files) {
+                await mkdir(dirname(join(staging, f.path)), { recursive: true });
+                await writeFile(join(staging, f.path), f.content);
+            }
+            await writeFile(join(staging, MANAGED_MARK), "Written by the AgentRadar runner; replaced on every sync.\n");
+            await rm(target, { recursive: true, force: true });
+            await rename(staging, target);
+            written.add(name);
+        }
+        catch {
+            await rm(staging, { recursive: true, force: true });
+            if (await isManaged(target))
+                written.add(name);
+        }
+    }
+    for (const entry of await readdir(skillsDir)) {
+        if (!written.has(entry) && await isManaged(join(skillsDir, entry)))
+            await rm(join(skillsDir, entry), { recursive: true, force: true });
+    }
+    return [...written];
+}
+/**
+ * R650 — a joined agent's AgentRadar skills (`my_skills`: the bundled set plus the ones linked to it), written
+ * at join into the directory its CLI reads, the feeder's `skillsDirFor`: Claude `$AR_BASE/.claude/skills`,
+ * Codex `$CODEX_HOME/skills`. Done here because a session that acts only through `agentradar run` has no
+ * feeder; where the service runs, its feeder keeps them current.
+ */
+export async function syncJoinedSkills(runnerId, deps) {
+    const env = await readFile(join(deps.home, ".agentradar", "agents", `${runnerId}.env`), "utf8");
+    const root = envValue(env, "AR_AGENT_HARNESS") === "codex" ? envValue(env, "CODEX_HOME") : envValue(env, "AR_BASE");
+    if (!root)
+        return;
+    const skillsDir = envValue(env, "AR_AGENT_HARNESS") === "codex" ? join(root, "skills") : join(root, ".claude", "skills");
+    const body = await awpRequest(runnerId, "tools/call", { name: "my_skills", arguments: {} }, { home: deps.home, fetch: deps.fetch, logError: deps.log });
+    const text = body?.result?.content?.find((c) => c.type === "text")?.text;
+    const answer = (text ? JSON.parse(text) : {});
+    if (!answer.ok || !Array.isArray(answer.skills))
+        throw new Error("AgentRadar did not return your skills");
+    const written = await writeManagedSkills(skillsDir, answer.skills);
+    deps.log(`Installed ${written.length} AgentRadar skill(s) in ${skillsDir}.`);
+}
 //# sourceMappingURL=skill-install.js.map

package/dist/tool-run.js

@@ -203,7 +203,7 @@ export async function callAwpTool(runnerId, name, toolArguments, deps) {
 }
 const RUNNER_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 /** One JSON-RPC request on the runner's AWP MCP endpoint with the runner's own key; null after logging why it failed. */
-async function awpRequest(runnerId, method, params, deps) {
+export async function awpRequest(runnerId, method, params, deps) {
     const logError = deps.logError ?? console.error;
     if (!RUNNER_ID.test(runnerId)) {
         logError("Invalid runner ID");

package/dist/update.js

@@ -0,0 +1,94 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { installCli } from "./setup.js";
+const LATEST = "https://registry.npmjs.org/agentradar-cli/latest";
+const TARBALL = /^https:\/\/registry\.npmjs\.org\/agentradar-cli\/-\/agentradar-cli-\d+\.\d+\.\d+\.tgz$/;
+const VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
+/** This package's folder: the CLI, the runner scripts and the agent-guard plugin all live in it. */
+export const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+/** A service's copy, made by `agentradar join` at ~/.agentradar/cli/<version>; the service runs ~/.agentradar/cli/current. */
+const serviceCopy = (root) => basename(dirname(root)) === "cli" && basename(dirname(dirname(root))) === ".agentradar";
+/** The version this process runs, whatever `current` points at now. */
+export const runningVersion = async () => JSON.parse(await readFile(join(PACKAGE_ROOT, "package.json"), "utf8")).version;
+/** The version on disk: for a service's copy, the one `current` points at, which another runner may have moved. */
+export const installedVersion = async (root = PACKAGE_ROOT) => JSON.parse(await readFile(join(serviceCopy(root) ? join(dirname(root), "current") : root, "package.json"), "utf8")).version;
+const newer = (a, b) => {
+    const [x, y] = [VERSION.exec(a), VERSION.exec(b)];
+    if (!x || !y)
+        return false;
+    for (let i = 1; i <= 3; i++)
+        if (Number(x[i]) !== Number(y[i]))
+            return Number(x[i]) > Number(y[i]);
+    return false;
+};
+/**
+ * Replaces this package in place with npm's latest release, when that is newer. Returns the version it
+ * installed, or null when nothing changed. Only a copy npm installed (inside `node_modules`) is touched,
+ * never a source checkout. The tarball must match the registry's sha512 before anything is unpacked, and
+ * the running folder is swapped by rename, so the service's paths stay valid and a failed update leaves
+ * the old copy in place.
+ */
+export async function selfUpdate(deps = {}) {
+    const root = deps.root ?? PACKAGE_ROOT;
+    if (!serviceCopy(root) && basename(dirname(root)) !== "node_modules")
+        return null;
+    const current = await installedVersion(root);
+    const get = (url) => (deps.fetch ?? fetch)(url, { signal: AbortSignal.timeout(60_000) });
+    const response = await get(LATEST);
+    if (!response.ok)
+        throw new Error(`npm registry answered ${response.status}`);
+    const latest = await response.json();
+    const version = latest.version ?? "";
+    if (!newer(version, current))
+        return null;
+    const tarballUrl = latest.dist?.tarball ?? "";
+    const integrity = latest.dist?.integrity ?? "";
+    if (!TARBALL.test(tarballUrl) || !tarballUrl.endsWith(`-${version}.tgz`) || !integrity.startsWith("sha512-")) {
+        throw new Error(`npm registry returned an unexpected release for ${version}`);
+    }
+    const download = await get(tarballUrl);
+    if (!download.ok)
+        throw new Error(`download of ${version} answered ${download.status}`);
+    const bytes = Buffer.from(await download.arrayBuffer());
+    if (`sha512-${createHash("sha512").update(bytes).digest("base64")}` !== integrity) {
+        throw new Error(`download of ${version} does not match the registry's checksum`);
+    }
+    // Unpacked beside the package, so the swap is a rename on one filesystem.
+    const work = await mkdtemp(join(dirname(root), ".agentradar-cli-update-"));
+    try {
+        const tarball = join(work, "package.tgz");
+        const next = join(work, "package");
+        await writeFile(tarball, bytes);
+        await mkdir(next);
+        await (deps.untar ?? ((file, into) => promisify(execFile)("tar", ["-xzf", file, "-C", into, "--strip-components=1"])))(tarball, next);
+        const manifest = JSON.parse(await readFile(join(next, "package.json"), "utf8"));
+        if (manifest.name !== "agentradar-cli" || manifest.version !== version)
+            throw new Error(`unpacked package is not agentradar-cli ${version}`);
+        // Unpacking installs no dependencies; a release that needs some has to go through npm.
+        if (Object.keys(manifest.dependencies ?? {}).length)
+            throw new Error(`agentradar-cli ${version} has dependencies; update it with npm`);
+        // A service's copy gets a new version folder and `current` moves to it; the running one stays untouched.
+        if (serviceCopy(root)) {
+            await installCli(dirname(dirname(dirname(root))), next);
+            return version;
+        }
+        const old = join(work, "old");
+        await rename(root, old);
+        try {
+            await rename(next, root);
+        }
+        catch (error) {
+            await rename(old, root);
+            throw error;
+        }
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+    return version;
+}
+//# sourceMappingURL=update.js.map

package/dist/vendor-runner/feeder.mjs

@@ -314,7 +314,23 @@ export function runnerState(auth = agentAuthState, sample = capturePane) {
   const authState = auth();
   if (authState === "unauthenticated") return "auth_required";
   if (authState !== "authenticated") return "starting";
-  return sample()?.inputReady ? "ready" : "starting";
+  const pane = sample();
+  if (pane?.rateLimited) return "rate_limited";
+  return pane?.inputReady ? "ready" : "starting";
+}
+
+/**
+ * M23 — the CLI's own usage-limit message near the bottom of the pane. Measured in the binaries, not
+ * guessed: Claude Code 2.1.281 prints "Usage limit reached · …", "You've hit your monthly spend limit",
+ * "you have reached your weekly usage limit"; codex-cli 0.149.1 prints "You've hit your usage limit." and
+ * "Usage limit reached. You've reached your usage limit.".
+ *
+ * ponytail: the transcript tail is scanned too, so an agent quoting the phrase in its last lines reads as
+ * limited until it scrolls away. Anchor on the status line only if that is observed on a real runner.
+ */
+export function paneRateLimited(text) {
+  const tail = String(text ?? "").split("\n").slice(-12).join("\n");
+  return /usage limit reached|you['’]ve hit your (?:\w+ )?(?:usage|spend) limit|you['’]?(?:ve| have) reached your (?:\w+ )?usage limit/i.test(tail);
 }
 
 // --------------------------------------------------------------------------
@@ -359,7 +375,10 @@ async function injectFrame(frame, label) {
     return false;
   }
   const [setCmd, pasteCmd, enterCmd] = sendKeysCommands(TMUX_SESSION, frame);
-  const okText = (await tmux(setCmd)) && (await tmux(pasteCmd));
+  const okSet = await tmux(setCmd);
+  const okText = okSet && (await tmux(pasteCmd));
+  // paste-buffer -d frees the buffer only on success; never leave client text sitting in tmux.
+  if (okSet && !okText) await tmux(["delete-buffer", "-b", setCmd[2]]);
   await sleep(KEY_SETTLE_MS);
   const okEnter = okText && (await tmux(enterCmd));
   if (okEnter) console.log(`[feeder] injected ${label}`);
@@ -580,7 +599,7 @@ function capturePane() {
   // build after several turns, which falsely demoted a healthy pane to `starting` and stopped next_event
   // from draining until its heartbeat aged stale.
   const inputReady = paneInputReady(text);
-  return { hash, inProgress, inputReady, channelGate: classifyChannelBanner(text) };
+  return { hash, inProgress, inputReady, rateLimited: paneRateLimited(text), channelGate: classifyChannelBanner(text) };
 }
 /**
  * #173b (disc obs) — format-drift detector. If the STRIPPED fingerprint keeps CHANGING while the pane

package/dist/vendor-runner/supervisor/agentradar-agent@.service.template

@@ -21,6 +21,8 @@ Type=simple
 # The runner reads ~/.agentradar/agents/%i.env.
 # systemd --user starts with a bare PATH; the agent CLI must resolve as it did for the installing user.
 Environment="PATH=__PATH__"
+# Tells the runner systemd restarts it, so it may exit to pick up a CLI update.
+Environment="AGENTRADAR_SERVICE=1"
 ExecStart=__RUNNER__ %i
 Restart=always
 RestartSec=15

package/dist/vendor-runner/supervisor/com.agentradar.agent.plist.template

@@ -45,7 +45,10 @@
     <key>HOME</key>
     <string>__HOME__</string>
     <key>PATH</key>
-    <string>__PATH__</string>__EXTRA_ENV__
+    <string>__PATH__</string>
+    <!-- Tells the runner launchd restarts it, so it may exit to pick up a CLI update. -->
+    <key>AGENTRADAR_SERVICE</key>
+    <string>1</string>__EXTRA_ENV__
   </dict>
 
   <key>WorkingDirectory</key>

package/dist/vendor-runner/supervisor/supervise-agent.sh

@@ -138,6 +138,8 @@ else
   # SC2086: CLAUDE_EXTRA_FLAGS is intentionally UNQUOTED so "--chrome" (etc.) word-splits into flags.
   # shellcheck disable=SC2086
   _launch_flags=( ${CLAUDE_EXTRA_FLAGS} --strict-mcp-config --mcp-config="${MCP_CONFIG}" )
+  # `agentradar join` enables the agent-guard plugin for this session only, through a settings file.
+  [ -n "${CLAUDE_SETTINGS:-}" ] && _launch_flags+=( --settings "${CLAUDE_SETTINGS}" )
   # Pane-alive predicate — MUST be unique per agent. Default to the FULL mcp-config path (each agent's
   # differs by directory), NOT the basename: on a multi-agent box every agent's config is named
   # `awp-only.json`, so a basename match would find ANOTHER agent's live claude and mask THIS agent's
@@ -169,7 +171,7 @@ if [ -n "${AGENT_TOOL_ENV_FILE}" ]; then
     # identity). Reject at parse time (visible warning) AND — belt-and-suspenders — the launch lists
     # the reserved allowlist AFTER TOOL_ENV_ARGS so `env` last-wins keeps reserved vars authoritative.
     case "${_tline%%=*}" in
-      HOME|PATH|USER|LOGNAME|SHELL|TERM|COLORTERM|LANG|LC_ALL|LC_CTYPE|TMPDIR|NODE_OPTIONS|CLAUDE_CONFIG_DIR|CLAUDE_CODE_OAUTH_TOKEN|CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC|CLAUDE_CODE_GB_DISK_CACHE_WHEN_TELEMETRY_OFF|CODEX_HOME|AR_RESUME_FLAGS|AR_FRESH_FLAGS|AR_OAUTH_TOKEN_FILE|AR_TOOL_ENV_FILE|ANTHROPIC_API_KEY|AWP_BEARER|AWP_BEARER_FILE|AWP_MCP_URL|TMUX_SESSION|AGENT_PID_PATTERN)
+      HOME|PATH|USER|LOGNAME|SHELL|TERM|COLORTERM|LANG|LC_ALL|LC_CTYPE|TMPDIR|NODE_OPTIONS|CLAUDE_CONFIG_DIR|CLAUDE_CODE_OAUTH_TOKEN|CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC|CLAUDE_CODE_GB_DISK_CACHE_WHEN_TELEMETRY_OFF|CODEX_HOME|AR_CLI_RUNNER_ID|AR_AGENTRADAR_BIN|AR_DISCIPLINE_EVERY|CLAUDE_CODE_PLUGIN_CACHE_DIR|AR_RESUME_FLAGS|AR_FRESH_FLAGS|AR_OAUTH_TOKEN_FILE|AR_TOOL_ENV_FILE|ANTHROPIC_API_KEY|AWP_BEARER|AWP_BEARER_FILE|AWP_MCP_URL|TMUX_SESSION|AGENT_PID_PATTERN)
         log "WARN ignoring reserved key '${_tline%%=*}' in ${AGENT_TOOL_ENV_FILE} (cannot override supervisor/agent env)"; continue ;;
     esac
     TOOL_ENV_ARGS+=("${_tline}")
@@ -186,6 +188,10 @@ fi
 unset CLAUDE_CODE_OAUTH_TOKEN
 _claude_cfg=()
 [ -n "${CLAUDE_CONFIG_DIR:-}" ] && _claude_cfg=( CLAUDE_CONFIG_DIR="${CLAUDE_CONFIG_DIR}" )
+# agent-guard (templates/agent-guard): its hooks ask the server what this runner still owes through the CLI.
+for _k in AR_CLI_RUNNER_ID AR_AGENTRADAR_BIN AR_DISCIPLINE_EVERY CLAUDE_CODE_PLUGIN_CACHE_DIR; do
+  [ -n "${!_k:-}" ] && _claude_cfg+=( "${_k}=${!_k}" )
+done
 
 # HARD RULE — OAuth only, never a pay-as-you-go API key. Scoped to the Claude harness because that is where
 # the variable decides anything: `claude` prefers ANTHROPIC_API_KEY over the subscription session, so its
@@ -345,7 +351,7 @@ ensure_agent() {
       CODEX_HOME="${CODEX_HOME:-}" AR_RESUME_FLAGS="${AR_RESUME_FLAGS}" AR_FRESH_FLAGS="${AR_FRESH_FLAGS}" \
       DISABLE_AUTOUPDATER=1 CLAUDE_CODE_GB_DISK_CACHE_WHEN_TELEMETRY_OFF=1 \
       ${_claude_cfg[@]+"${_claude_cfg[@]}"} ${_tool_env[@]+"${_tool_env[@]}"} \
-      /bin/sh -c 'if [ -n "${AR_TOOL_ENV_FILE:-}" ]; then while IFS= read -r _l || [ -n "$_l" ]; do case "$_l" in ""|\#*) continue ;; esac; _k=${_l%%=*}; _v=${_l#*=}; case "$_k" in HOME|PATH|USER|LOGNAME|SHELL|TERM|COLORTERM|LANG|LC_ALL|LC_CTYPE|TMPDIR|NODE_OPTIONS|CLAUDE_CONFIG_DIR|CLAUDE_CODE_OAUTH_TOKEN|CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC|CLAUDE_CODE_GB_DISK_CACHE_WHEN_TELEMETRY_OFF|CODEX_HOME|AR_RESUME_FLAGS|AR_FRESH_FLAGS|AR_OAUTH_TOKEN_FILE|AR_TOOL_ENV_FILE|ANTHROPIC_API_KEY|AWP_BEARER|AWP_BEARER_FILE|AWP_MCP_URL|TMUX_SESSION|AGENT_PID_PATTERN) continue ;; esac; export "$_k=$_v"; done < "$AR_TOOL_ENV_FILE"; unset AR_TOOL_ENV_FILE _l _k _v; fi; RF="${AR_RESUME_FLAGS:-}"; FF="${AR_FRESH_FLAGS:-}"; unset AR_RESUME_FLAGS AR_FRESH_FLAGS; CB="$1"; shift; S=$(date +%s); "$CB" $RF "$@" || [ $(( $(date +%s) - S )) -ge 30 ] || exec "$CB" $FF "$@"' sh "${AGENT_BIN}" "${_launch_flags[@]}" || {
+      /bin/sh -c 'if [ -n "${AR_TOOL_ENV_FILE:-}" ]; then while IFS= read -r _l || [ -n "$_l" ]; do case "$_l" in ""|\#*) continue ;; esac; _k=${_l%%=*}; _v=${_l#*=}; case "$_k" in HOME|PATH|USER|LOGNAME|SHELL|TERM|COLORTERM|LANG|LC_ALL|LC_CTYPE|TMPDIR|NODE_OPTIONS|CLAUDE_CONFIG_DIR|CLAUDE_CODE_OAUTH_TOKEN|CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC|CLAUDE_CODE_GB_DISK_CACHE_WHEN_TELEMETRY_OFF|CODEX_HOME|AR_CLI_RUNNER_ID|AR_AGENTRADAR_BIN|AR_DISCIPLINE_EVERY|CLAUDE_CODE_PLUGIN_CACHE_DIR|AR_RESUME_FLAGS|AR_FRESH_FLAGS|AR_OAUTH_TOKEN_FILE|AR_TOOL_ENV_FILE|ANTHROPIC_API_KEY|AWP_BEARER|AWP_BEARER_FILE|AWP_MCP_URL|TMUX_SESSION|AGENT_PID_PATTERN) continue ;; esac; export "$_k=$_v"; done < "$AR_TOOL_ENV_FILE"; unset AR_TOOL_ENV_FILE _l _k _v; fi; RF="${AR_RESUME_FLAGS:-}"; FF="${AR_FRESH_FLAGS:-}"; unset AR_RESUME_FLAGS AR_FRESH_FLAGS; CB="$1"; shift; S=$(date +%s); "$CB" $RF "$@" || [ $(( $(date +%s) - S )) -ge 30 ] || exec "$CB" $FF "$@"' sh "${AGENT_BIN}" "${_launch_flags[@]}" || {
         log "tmux could not start agent session '${TMUX_SESSION}'"
         return 1
       }

package/dist/vendor-runner/terminal-bridge.mjs

@@ -2,10 +2,11 @@
 //
 // Opens a persistent OUTBOUND WebSocket to the AgentRadar server (the mini INITIATES; the server never
 // connects inbound — phone-home preserved) and bridges the agent's tmux pane:
-//   - server {attach}  → start `tmux pipe-pane` → stream pane output as {output} frames (+ an initial
-//                        capture-pane so a late viewer sees the current screen).
-//   - server {detach}  → stop piping (idle agents cost nothing).
-//   - pane GEOMETRY    → {hello cols,rows} on connect + {geometry cols,rows} on change while attached (#9).
+//   - server {attach}  → attach a read-only tmux CONTROL-MODE client (`tmux -C attach -r`) → stream the pane's
+//                        `%output` as {output} frames, after a scrollback snapshot (`capture-pane -S -2000`) so a
+//                        late viewer can scroll back and lands on the current screen.
+//   - server {detach}  → kill the control client (idle agents cost nothing).
+//   - pane GEOMETRY    → {hello cols,rows} on connect + {geometry cols,rows} on each `%layout-change` (#9).
 //                        The server has no other way to know the pane size, and without it the client
 //                        watch-terminal renders every agent at a hardcoded 120×30.
 //   - server {input}   → `tmux send-keys -l` (VENDOR keystrokes; the server already dropped client input).
@@ -26,22 +27,20 @@ import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import http from "node:http";
 import https from "node:https";
-import os from "node:os";
-import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
 
 const AWP_MCP_ENDPOINT = process.env.AWP_MCP_URL ?? "https://staging.agentradar.com/api/mcp";
-const AWP_BEARER = (() => {
+// Re-read on every connect: a hosted supervisor rewrites the file when it refreshes the run token.
+export function readBearer() {
   const f = process.env.AWP_BEARER_FILE;
-  if (f) {
-    try {
-      return fs.readFileSync(f, "utf8").trim();
-    } catch (e) {
-      console.error(`[bridge] FATAL: AWP_BEARER_FILE unreadable (${f}): ${e.message}`);
-      process.exit(1);
-    }
+  if (!f) return process.env.AWP_BEARER ?? "";
+  try {
+    return fs.readFileSync(f, "utf8").trim();
+  } catch (e) {
+    console.error(`[bridge] AWP_BEARER_FILE unreadable (${f}): ${e.message}`);
+    return "";
   }
-  return process.env.AWP_BEARER ?? "";
-})();
+}
 const TMUX_SESSION = process.env.TMUX_SESSION ?? "agent";
 // Resolve the tmux binary robustly: a bare "tmux" only works if it's on PATH, but the bridge is often
 // launched from a supervisor / LaunchAgent whose PATH excludes e.g. /opt/homebrew/bin — then every tmux
@@ -67,11 +66,7 @@ const RECONNECT_MAX_MS = Number(process.env.BRIDGE_RECONNECT_MAX_MS ?? "15000");
 // force-closed it — i.e. a ~5 min live-terminal blackout on EVERY deploy. Watch for ping silence ourselves so
 // recovery is ours, not the load balancer's.
 const SERVER_PING_TIMEOUT_MS = Number(process.env.BRIDGE_PING_TIMEOUT_MS ?? "90000"); // 3× the 30s server ping
-// #9: how often the pane size is re-read WHILE A VIEWER IS ATTACHED. tmux gives us no resize event, so the
-// only way to notice a pane change is to ask. The poll runs only between attach and detach, so an unwatched
-// agent still costs nothing, and a frame is sent only when the size actually CHANGED — an unchanged read is
-// one cheap tmux call and no traffic.
-const GEOMETRY_POLL_MS = Number(process.env.BRIDGE_GEOMETRY_POLL_MS ?? "5000");
+const SNAPSHOT_LINES = 2000;
 
 /**
  * #18: run `fn` at most once, however many times the returned function is called.
@@ -206,12 +201,37 @@ export function parsePaneGeometry(stdout) {
   return { cols, rows };
 }
 
+/**
+ * One line of tmux control-mode output → `{ type: "output", pane, data: Buffer }`, `{ type: "layout" }`,
+ * `{ type: "exit" }`, or null for everything else. `%output` data has bytes below 0x20 and `\` octal-escaped
+ * (`\015`); other bytes, UTF-8 included, pass through raw, so the line is handled as bytes (latin1), never text.
+ */
+export function parseControlLine(line) {
+  const s = Buffer.isBuffer(line) ? line.toString("latin1") : line;
+  if (s.startsWith("%output ")) {
+    const sp = s.indexOf(" ", 8);
+    if (sp < 0) return null;
+    const data = s.slice(sp + 1).replace(/\\([0-7]{3})/g, (_, o) => String.fromCharCode(parseInt(o, 8)));
+    return { type: "output", pane: s.slice(8, sp), data: Buffer.from(data, "latin1") };
+  }
+  if (s.startsWith("%layout-change ")) return { type: "layout" };
+  if (s.startsWith("%exit")) return { type: "exit" };
+  return null;
+}
+
+/**
+ * The scrollback snapshot as terminal text: history + visible screen, then the cursor put back where the pane
+ * has it, so live output that follows (relative cursor moves) lands in the right place.
+ */
+export function snapshotText(captured, cursor) {
+  const body = captured.replace(/\n$/, "");
+  return cursor ? `${body}\x1b[${cursor.y + 1};${cursor.x + 1}H` : body;
+}
+
 class TerminalBridge {
   constructor() {
     this.sock = null;
-    this.piping = false;
-    this.fifoPath = null;
-    this.fifoStream = null;
+    this.control = null; // the read-only tmux control-mode client while a viewer is attached
     this.recvBuf = Buffer.alloc(0);
     this.backoff = RECONNECT_MIN_MS;
     this.pingTimer = null;
@@ -219,7 +239,6 @@ class TerminalBridge {
     // Reset to null on every (re)connect — a reconnect may land on a different server task with no memory
     // of this session, so the new peer must be told even if the pane never moved.
     this.geometry = null;
-    this.geometryTimer = null;
   }
 
   /**
@@ -275,57 +294,52 @@ class TerminalBridge {
     this.send({ type: "geometry", cols: g.cols, rows: g.rows });
   }
 
-  startGeometryPoll() {
-    if (this.geometryTimer) return;
-    this.geometryTimer = setInterval(() => this.reportGeometry(), GEOMETRY_POLL_MS);
-    if (typeof this.geometryTimer.unref === "function") this.geometryTimer.unref();
-  }
-
-  stopGeometryPoll() {
-    if (!this.geometryTimer) return;
-    clearInterval(this.geometryTimer);
-    this.geometryTimer = null;
-  }
-
   startPipe() {
-    if (this.piping) return;
-    this.piping = true;
+    if (this.control) return;
     // #9: a viewer just attached — publish the real pane size before the first bytes, so the client sizes
     // its grid correctly rather than painting the replay into a fallback grid and re-flowing a moment later.
     this.reportGeometry(true);
-    this.startGeometryPoll();
-    // Initial screen so a viewer attaching mid-session sees current state.
-    const cap = tmux(["capture-pane", "-ep", "-t", TMUX_SESSION]);
-    if (cap.status === 0 && cap.stdout) this.send({ type: "output", data: cap.stdout });
-    // Stream new output via a fifo that tmux pipe-pane writes into.
-    this.fifoPath = path.join(os.tmpdir(), `ar-bridge-${process.pid}-${Date.now()}.fifo`);
-    spawnSync("mkfifo", [this.fifoPath]);
-    tmux(["pipe-pane", "-t", TMUX_SESSION, `cat >> ${this.fifoPath}`]);
-    this.fifoStream = fs.createReadStream(this.fifoPath);
-    this.fifoStream.on("data", (chunk) => this.send({ type: "output", data: chunk.toString("utf8") }));
-    this.fifoStream.on("error", () => {});
+    const pane = tmux(["display-message", "-p", "-t", TMUX_SESSION, "#{pane_id} #{cursor_x} #{cursor_y}"]);
+    const [paneId, cx, cy] = pane.status === 0 ? pane.stdout.trim().split(" ") : [];
+    const cap = tmux(["capture-pane", "-p", "-e", "-J", "-S", `-${SNAPSHOT_LINES}`, "-t", TMUX_SESSION]);
+    if (cap.status === 0 && cap.stdout) {
+      const cursor = cx !== undefined && cy !== undefined ? { x: Number(cx), y: Number(cy) } : null;
+      this.send({ type: "output", data: snapshotText(cap.stdout, cursor) });
+    }
+    // Read-only + ignore-size: the bridge can neither type into nor shrink the vendor's pane.
+    const child = spawn(TMUX_BIN, ["-C", "attach-session", "-r", "-t", TMUX_SESSION], {
+      stdio: ["pipe", "pipe", "ignore"],
+    });
+    this.control = child;
+    const decoder = new StringDecoder("utf8"); // a UTF-8 character can straddle two %output lines
+    let buf = Buffer.alloc(0);
+    child.stdout.on("data", (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      let nl;
+      while ((nl = buf.indexOf(0x0a)) >= 0) {
+        const msg = parseControlLine(buf.subarray(0, nl));
+        buf = buf.subarray(nl + 1);
+        if (msg?.type === "output" && (!paneId || msg.pane === paneId)) {
+          const text = decoder.write(msg.data);
+          if (text) this.send({ type: "output", data: text });
+        } else if (msg?.type === "layout") this.reportGeometry();
+        else if (msg?.type === "exit") this.stopPipe();
+      }
+    });
+    child.on("error", () => {});
+    child.on("exit", () => {
+      if (this.control === child) this.control = null;
+    });
   }
 
   stopPipe() {
-    if (!this.piping) return;
-    this.piping = false;
-    this.stopGeometryPoll(); // #9: nobody is watching → stop asking tmux anything
-    tmux(["pipe-pane", "-t", TMUX_SESSION]); // empty command → stop piping
-    if (this.fifoStream) {
-      try {
-        this.fifoStream.destroy();
-      } catch {
-        /* ignore */
-      }
-      this.fifoStream = null;
-    }
-    if (this.fifoPath) {
-      try {
-        fs.unlinkSync(this.fifoPath);
-      } catch {
-        /* ignore */
-      }
-      this.fifoPath = null;
+    const child = this.control;
+    if (!child) return;
+    this.control = null;
+    try {
+      child.kill();
+    } catch {
+      /* already gone */
     }
   }
 
@@ -355,6 +369,8 @@ class TerminalBridge {
   }
 
   connect() {
+    const bearer = readBearer();
+    if (!bearer) return this.scheduleReconnect();
     const url = feederWsUrl();
     const key = randomBytes(16).toString("base64");
     const lib = url.protocol === "wss:" ? https : http;
@@ -369,7 +385,7 @@ class TerminalBridge {
         "Sec-WebSocket-Version": "13",
         "Sec-WebSocket-Key": key,
         // Auth rides the subprotocol (never a query param); NEVER logged.
-        "Sec-WebSocket-Protocol": `agentradar-feeder, ${AWP_BEARER}`,
+        "Sec-WebSocket-Protocol": `agentradar-feeder, ${bearer}`,
       },
     });
     req.on("upgrade", (res, socket) => {
@@ -459,7 +475,7 @@ class TerminalBridge {
 
 // Only auto-run when executed directly (not when imported by the unit test).
 if (import.meta.url === `file://${process.argv[1]}`) {
-  if (!AWP_BEARER) {
+  if (!readBearer()) {
     console.error("[bridge] FATAL: no AWP bearer (set AWP_BEARER_FILE or AWP_BEARER)");
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "agentradar-cli",
-  "version": "0.2.3",
+  "version": "0.2.5",
+  "engines": {
+    "node": ">=20"
+  },
   "description": "Secure AgentRadar vendor setup and skill installer",
   "type": "module",
   "bin": {
@@ -14,8 +17,10 @@
     "dist/skill-install.js",
     "dist/tool-run.js",
     "dist/sync.js",
+    "dist/update.js",
     "dist/vendor-runner/**",
     "dist/agentradar-vendor/SKILL.md",
+    "dist/agent-guard",
     "README.md"
   ],
   "license": "MIT",
@@ -23,7 +28,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc && mkdir -p dist/agentradar-vendor dist/vendor-runner/supervisor && cp ../../skills/agentradar-vendor/SKILL.md dist/agentradar-vendor/SKILL.md && cp ../../templates/vendor-runner/feeder.mjs ../../templates/vendor-runner/pane-live.sh ../../templates/vendor-runner/session-frame.mjs ../../templates/vendor-runner/terminal-bridge.mjs dist/vendor-runner/ && cp ../../templates/vendor-runner/supervisor/supervise-agent.sh ../../templates/vendor-runner/supervisor/install-agent.sh ../../templates/vendor-runner/supervisor/com.agentradar.agent.plist.template ../../templates/vendor-runner/supervisor/agentradar-agent@.service.template dist/vendor-runner/supervisor/ && chmod +x dist/index.js dist/vendor-runner/pane-live.sh dist/vendor-runner/supervisor/supervise-agent.sh dist/vendor-runner/supervisor/install-agent.sh",
+    "build": "tsc && mkdir -p dist/agentradar-vendor dist/vendor-runner/supervisor && cp ../../skills/agentradar-vendor/SKILL.md dist/agentradar-vendor/SKILL.md && cp ../../templates/vendor-runner/feeder.mjs ../../templates/vendor-runner/pane-live.sh ../../templates/vendor-runner/session-frame.mjs ../../templates/vendor-runner/terminal-bridge.mjs dist/vendor-runner/ && cp ../../templates/vendor-runner/supervisor/supervise-agent.sh ../../templates/vendor-runner/supervisor/install-agent.sh ../../templates/vendor-runner/supervisor/com.agentradar.agent.plist.template ../../templates/vendor-runner/supervisor/agentradar-agent@.service.template dist/vendor-runner/supervisor/ && rm -rf dist/agent-guard && cp -R ../../templates/agent-guard dist/agent-guard && rm dist/agent-guard/scripts/guard.test.mjs && chmod +x dist/index.js dist/vendor-runner/pane-live.sh dist/vendor-runner/supervisor/supervise-agent.sh dist/vendor-runner/supervisor/install-agent.sh",
     "clean": "rm -rf dist",
     "prepack": "pnpm run build",
     "typecheck": "tsc --noEmit",