@taewooopark/agent-blackbox 0.44.0 → 0.46.0

package/dist/cli.js

@@ -61,6 +61,9 @@ function validateTraceEvent(event) {
   requireEnum(event, "host", traceHosts, errors);
   requireString(event, "runId", errors);
   requireString(event, "sessionId", errors);
+  if (event.cwd !== void 0 && typeof event.cwd !== "string") {
+    errors.push("cwd must be a string when present");
+  }
   requireEnum(event, "kind", traceEventKinds, errors);
   requireEnum(event, "sensitivity", dataSensitivities, errors);
   if (!isRecord(event.payload)) {
@@ -134,6 +137,9 @@ function replayWorkflowGraphAtSeq(events, seq) {
 }
 function replayWorkflowGraphAtTime(events, at) {
   const atTime = new Date(at).getTime();
+  if (Number.isNaN(atTime)) {
+    throw new Error("replayWorkflowGraphAtTime: invalid time");
+  }
   return materializeWorkflowGraph(events.filter((event) => new Date(event.ts).getTime() <= atTime));
 }
 function applyTraceEvent(graph, event) {
@@ -248,7 +254,8 @@ function ensureSession(graph, event) {
     status: "ACTIVE",
     at: event.ts,
     eventId: event.id,
-    data: { sessionId: event.sessionId, parentSessionId: event.parentSessionId ?? null }
+    data: { sessionId: event.sessionId, parentSessionId: event.parentSessionId ?? null },
+    keepStatusIfExists: true
   });
   ensureEdge(graph, {
     from: runNodeId(event.runId),
@@ -270,7 +277,8 @@ function ensureAgent(graph, event) {
     status: "ACTIVE",
     at: event.ts,
     eventId: event.id,
-    data: { agentId: event.agentId, agentRole: event.agentRole ?? "unknown" }
+    data: { agentId: event.agentId, agentRole: event.agentRole ?? "unknown" },
+    keepStatusIfExists: true
   });
   ensureEdge(graph, {
     from: sessionNodeId(event.sessionId),
@@ -292,7 +300,8 @@ function ensureTurn(graph, event) {
     status: "ACTIVE",
     at: event.ts,
     eventId: event.id,
-    data: { turnId: event.turnId }
+    data: { turnId: event.turnId },
+    keepStatusIfExists: true
   });
   ensureEdge(graph, {
     from: event.agentId ? agentNodeId(event.agentId) : sessionNodeId(event.sessionId),
@@ -360,7 +369,9 @@ function ensureNode(graph, input) {
   const existing = graph.nodes.get(input.id);
   if (existing) {
     existing.updatedAt = input.at;
-    existing.status = input.status;
+    if (!input.keepStatusIfExists) {
+      existing.status = input.status;
+    }
     existing.data = { ...existing.data, ...input.data ?? {} };
     if (input.eventId && !existing.eventIds.includes(input.eventId)) {
       existing.eventIds.push(input.eventId);
@@ -514,7 +525,8 @@ function eventNodeIdFromEventId(eventId) {
   return `event:${stablePart(eventId)}`;
 }
 function workflowEdgeId(from, to, type) {
-  return `edge:${type}:${stablePart(from)}:${stablePart(to)}`;
+  const enc = (s) => s.replace(/:/g, "__");
+  return `edge:${type}:${enc(stablePart(from))}:${enc(stablePart(to))}`;
 }
 function stablePart(value) {
   return value.replace(/[^a-zA-Z0-9_.:-]/g, "_");
@@ -842,7 +854,7 @@ function computeEfficiencyReport(events) {
         label: "Large context injections",
         value: biggest,
         unit: "tokens",
-        display: biggest >= 2e3 ? formatTokens(biggest) : "none",
+        display: biggest >= 5e3 ? formatTokens(biggest) : "none",
         score,
         status,
         detail: over5k.length === 0 ? "No single tool output flooded the context." : `${over5k.length} output(s) added 5k+ tokens (largest ${formatTokens(biggest)}) \u2014 scope greps/reads or summarise.`,
@@ -979,7 +991,7 @@ function stringAt(event, key) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
 function readTokenSnapshot(event) {
-  const present = deepNumber(event.payload, "properties.info.tokens") !== void 0 || deepNumber(event.payload, "properties.tokens") !== void 0 || deepNumber(event.payload, "tokens") !== void 0 || isRecordAtPath(event.payload, "properties.info.tokens") || isRecordAtPath(event.payload, "properties.tokens") || isRecordAtPath(event.payload, "tokens");
+  const present = isRecordAtPath(event.payload, "properties.info.tokens") || isRecordAtPath(event.payload, "properties.tokens") || isRecordAtPath(event.payload, "tokens");
   if (!present) return void 0;
   return {
     input: deepNumber(event.payload, ["properties.info.tokens.input", "properties.tokens.input", "tokens.input"]) ?? 0,
@@ -1082,13 +1094,13 @@ function buildEfficiencyMemory(report, options = {}) {
   ].join("\n");
 }
 var escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-var managedBlockRegExp = () => new RegExp(`${escapeRegExp(EFFICIENCY_MEMORY_START)}[\\s\\S]*?${escapeRegExp(EFFICIENCY_MEMORY_END)}`);
+var managedBlockRegExp = () => new RegExp(`${escapeRegExp(EFFICIENCY_MEMORY_START)}[\\s\\S]*?${escapeRegExp(EFFICIENCY_MEMORY_END)}`, "g");
 function hasManagedBlock(content) {
   return managedBlockRegExp().test(content);
 }
 function upsertManagedBlock(content, block) {
   if (hasManagedBlock(content)) {
-    return content.replace(managedBlockRegExp(), block);
+    return content.replace(managedBlockRegExp(), () => block);
   }
   const base = content.trimEnd();
   return base.length === 0 ? `${block}
@@ -1107,8 +1119,9 @@ function removeManagedBlock(content) {
 // apps/daemon/dist/cli.js
 import { spawn as spawn2 } from "node:child_process";
 import { existsSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { dirname as dirname4, resolve } from "node:path";
+import { dirname as dirname5, join as join6, resolve } from "node:path";
 
 // apps/daemon/dist/dashboardServer.js
 import { createReadStream } from "node:fs";
@@ -1138,7 +1151,14 @@ async function startDashboardServer(options) {
   const injected = indexHtml.replace("</head>", `  <script>window.AGENT_BLACKBOX_DAEMON_URL=${JSON.stringify(options.daemonUrl)};</script>
   </head>`);
   const server = createServer((request, response) => {
-    const rawPath = decodeURIComponent((request.url ?? "/").split("?")[0] ?? "/");
+    let rawPath;
+    try {
+      rawPath = decodeURIComponent((request.url ?? "/").split("?")[0] ?? "/");
+    } catch {
+      response.writeHead(400);
+      response.end("Bad Request");
+      return;
+    }
     if (rawPath === "/" || rawPath === "/index.html") {
       response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
       response.end(injected);
@@ -1156,15 +1176,21 @@ async function startDashboardServer(options) {
         throw new Error("not a file");
       }
       response.writeHead(200, { "content-type": mimeTypes[extname(filePath)] ?? "application/octet-stream" });
-      createReadStream(filePath).pipe(response);
+      const rs = createReadStream(filePath);
+      rs.on("error", () => response.destroy());
+      rs.pipe(response);
     }).catch(() => {
       response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
       response.end(injected);
     });
   });
   const port = options.port ?? 5173;
-  await new Promise((resolve2) => {
-    server.listen(port, "127.0.0.1", resolve2);
+  await new Promise((resolve2, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve2();
+    });
   });
   const address = server.address();
   const actualPort = typeof address === "object" && address ? address.port : port;
@@ -1179,7 +1205,7 @@ async function startDashboardServer(options) {
 
 // apps/daemon/dist/index.js
 import { readFileSync } from "node:fs";
-import { dirname as dirname3, join as join5 } from "node:path";
+import { dirname as dirname4, join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // packages/storage/src/ndjson.ts
@@ -1196,7 +1222,19 @@ function parseTraceEventLine(line) {
   return parsed;
 }
 function parseTraceEvents(input) {
-  return input.split(/\r?\n/).filter((line) => line.trim().length > 0).map((line) => parseTraceEventLine(line));
+  const lines = input.split(/\r?\n/).filter((line) => line.trim().length > 0);
+  const lastIsPossiblyTorn = lines.length > 0 && !/\r?\n$/.test(input);
+  const completeCount = lastIsPossiblyTorn ? lines.length - 1 : lines.length;
+  const events = lines.slice(0, completeCount).map((line) => parseTraceEventLine(line));
+  if (lastIsPossiblyTorn) {
+    const lastLine = lines[lines.length - 1];
+    try {
+      events.push(parseTraceEventLine(lastLine));
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+    }
+  }
+  return events;
 }
 async function appendTraceEvent(filePath, event) {
   await mkdir(dirname(filePath), { recursive: true });
@@ -1225,10 +1263,11 @@ async function runOptimize(options) {
 }
 async function computeOptimize(options) {
   const eventsFile = options.eventsFile ?? join2(options.projectDir, ".agent-blackbox", "events.ndjson");
-  const agentsMdPath = join2(options.projectDir, "AGENTS.md");
-  const statePath = join2(options.projectDir, ".agent-blackbox", "optimization.json");
   const events = await loadTraceEvents(eventsFile);
   const { runId, events: runEvents } = latestRun(events);
+  const targetDir = runEvents.find((e) => typeof e.cwd === "string" && e.cwd.length > 0)?.cwd ?? options.projectDir;
+  const agentsMdPath = join2(targetDir, "AGENTS.md");
+  const statePath = join2(targetDir, ".agent-blackbox", "optimization.json");
   const latestTs = runEvents.reduce((max, e) => e.ts > max ? e.ts : max, "");
   const report = runEvents.length > 0 ? computeEfficiencyReport(runEvents) : null;
   const score = report ? report.overallScore : null;
@@ -1254,15 +1293,17 @@ async function computeOptimize(options) {
     }
     const prior = await readMaybe(agentsMdPath);
     const next = upsertManagedBlock(prior ?? "", block);
-    await writeFile(agentsMdPath, next, "utf8");
-    await writeState(statePath, {
-      runId: runId ?? "",
-      baselineScore: score,
-      baselineLatestTs: latestTs,
-      baselineFlagged: flaggedIds(report),
-      fileExisted: prior !== null,
-      appliedAt: (/* @__PURE__ */ new Date()).toISOString()
-    });
+    if (prior === null || next !== prior) {
+      await writeFile(agentsMdPath, next, "utf8");
+      await writeState(statePath, {
+        runId: runId ?? "",
+        baselineScore: score,
+        baselineLatestTs: latestTs,
+        baselineFlagged: flaggedIds(report),
+        fileExisted: prior !== null,
+        appliedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
     return {
       mode: "apply",
       action: `Wrote efficiency memory to AGENTS.md \u2014 targets ~${report.reclaimableTokens} reclaimable tokens on similar future runs (no re-run needed). Optional: re-run the same task + \`optimize --check\` to benchmark the gain.`,
@@ -1469,7 +1510,7 @@ function buildDigest(report) {
       id: m.id,
       label: m.label,
       status: m.status,
-      value: Number(m.value.toFixed(3)),
+      value: Number((typeof m.value === "number" && Number.isFinite(m.value) ? m.value : 0).toFixed(3)),
       display: m.display,
       detail: m.detail,
       ...m.reclaimableTokens ? { reclaimableTokens: m.reclaimableTokens } : {},
@@ -1491,6 +1532,8 @@ var freeCooldownUntil = /* @__PURE__ */ new Map();
 function orderFreePool(pool, cooldownUntil, cursor, now) {
   const fresh = pool.filter((entry) => (cooldownUntil.get(entry.model) ?? 0) <= now);
   const list = fresh.length > 0 ? fresh : pool;
+  if (list.length === 0)
+    return [];
   const start = (cursor % list.length + list.length) % list.length;
   return [...list.slice(start), ...list.slice(0, start)];
 }
@@ -1635,7 +1678,10 @@ async function fetchJson(url, body, extraHeaders = {}) {
 }
 function runCommand(command, args2) {
   return new Promise((resolve2, reject) => {
-    const child = spawn(command, args2, { stdio: ["ignore", "pipe", "ignore"] });
+    const child = spawn(command, args2, {
+      stdio: ["ignore", "pipe", "ignore"],
+      env: { ...process.env, AGENT_BLACKBOX_DISABLE: "1" }
+    });
     let out = "";
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
@@ -1662,10 +1708,24 @@ function extractJsonObject(text) {
   if (start === -1)
     return void 0;
   let depth = 0;
+  let inString = false;
+  let escaped = false;
   for (let i = start; i < text.length; i += 1) {
-    if (text[i] === "{")
+    const ch = text[i];
+    if (inString) {
+      if (escaped)
+        escaped = false;
+      else if (ch === "\\")
+        escaped = true;
+      else if (ch === '"')
+        inString = false;
+      continue;
+    }
+    if (ch === '"')
+      inString = true;
+    else if (ch === "{")
       depth += 1;
-    else if (text[i] === "}") {
+    else if (ch === "}") {
       depth -= 1;
       if (depth === 0) {
         try {
@@ -1703,8 +1763,12 @@ async function startTraceDaemon(options) {
     });
   });
   const port = options.port ?? 47831;
-  await new Promise((resolve2) => {
-    server.listen(port, "127.0.0.1", resolve2);
+  await new Promise((resolve2, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve2();
+    });
   });
   const address = server.address();
   const actualPort = typeof address === "object" && address ? address.port : port;
@@ -1713,8 +1777,12 @@ async function startTraceDaemon(options) {
     port: actualPort,
     eventsFile,
     close: () => new Promise((resolve2, reject) => {
+      for (const client of clients) {
+        client.terminate();
+      }
+      clients.clear();
+      streamServer.close();
       server.close((error) => {
-        streamServer.close();
         if (error) {
           reject(error);
         } else {
@@ -1768,11 +1836,11 @@ async function buildTraceSnapshot(eventsFile, replay = {}) {
 async function handleRequest(request, response, eventsFile, clients, suggestConfig, projectDir) {
   try {
     const url = new URL(request.url ?? "/", "http://127.0.0.1");
-    const replay = parseReplayQuery(url);
     if (request.method === "OPTIONS") {
       sendEmpty(response, 204);
       return;
     }
+    const replay = parseReplayQuery(url);
     if (request.method === "GET" && url.pathname === "/health") {
       sendJson(response, 200, { ok: true, data: { status: "ok", eventsFile } });
       return;
@@ -1867,13 +1935,27 @@ async function sendSnapshot(client, eventsFile) {
     }
   }
 }
+var MAX_BODY_BYTES = 5e7;
 async function readJsonBody(request) {
   const chunks = [];
+  let total = 0;
   for await (const chunk of request) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += buffer.length;
+    if (total > MAX_BODY_BYTES) {
+      throw new BadRequestError("Request body too large");
+    }
+    chunks.push(buffer);
   }
   const raw = Buffer.concat(chunks).toString("utf8");
-  return raw.length > 0 ? JSON.parse(raw) : {};
+  if (raw.length === 0) {
+    return {};
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new BadRequestError("Invalid JSON body");
+  }
 }
 function sendJson(response, statusCode, payload) {
   response.writeHead(statusCode, {
@@ -1917,10 +1999,39 @@ function isNodeError(error) {
 }
 
 // apps/daemon/dist/initOpenCode.js
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join4 } from "node:path";
+import { mkdir as mkdir3, readFile as readFile4, rm as rm2, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname as dirname3, join as join4 } from "node:path";
 var defaultAdapterPackage = "@agent-blackbox/opencode-adapter";
 var defaultDaemonUrl = "http://127.0.0.1:47831";
+function globalOpenCodeDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  return xdg && xdg.length > 0 ? join4(xdg, "opencode") : join4(homedir(), ".config", "opencode");
+}
+function globalRecorderPath() {
+  return join4(globalOpenCodeDir(), "plugins", "agent-blackbox.js");
+}
+async function installGlobalRecorder(options) {
+  if (!await pathExists(options.pluginBundlePath)) {
+    throw new Error("Self-contained recorder bundle not found. Use the published npx package, or build it from source with `npm run build:cli`.");
+  }
+  const pluginPath = globalRecorderPath();
+  const bundle = (await readFile4(options.pluginBundlePath, "utf8")).replaceAll("__ABB_DAEMON_URL__", options.daemonUrl);
+  await mkdir3(dirname3(pluginPath), { recursive: true });
+  await writeFile2(pluginPath, bundle, "utf8");
+  return { pluginPath };
+}
+async function uninstallGlobalRecorder() {
+  const pluginPath = globalRecorderPath();
+  try {
+    await rm2(pluginPath);
+    return { pluginPath, removed: true };
+  } catch (error) {
+    if (isNodeError2(error) && error.code === "ENOENT")
+      return { pluginPath, removed: false };
+    throw error;
+  }
+}
 async function initOpenCodeProject(options) {
   const adapterPackage = options.adapterPackage ?? defaultAdapterPackage;
   const adapterImport = inferAdapterImport(adapterPackage);
@@ -1998,7 +2109,7 @@ function isNodeError2(error) {
 
 // apps/daemon/dist/index.js
 function resolvePackageVersion() {
-  let dir = dirname3(fileURLToPath(import.meta.url));
+  let dir = dirname4(fileURLToPath(import.meta.url));
   for (let i = 0; i < 6; i += 1) {
     try {
       const pkg = JSON.parse(readFileSync(join5(dir, "package.json"), "utf8"));
@@ -2006,7 +2117,7 @@ function resolvePackageVersion() {
         return pkg.version;
     } catch {
     }
-    const parent = dirname3(dir);
+    const parent = dirname4(dir);
     if (parent === dir)
       break;
     dir = parent;
@@ -2020,12 +2131,19 @@ function describeDaemon() {
 
 // apps/daemon/dist/cli.js
 var args = process.argv.slice(2);
-var cliDir = dirname4(fileURLToPath2(import.meta.url));
+var cliDir = dirname5(fileURLToPath2(import.meta.url));
 var repoRoot = resolve(cliDir, "../../..");
 var firstExisting = (paths) => paths.find((p) => existsSync(p));
 var dashboardDistDir = firstExisting([resolve(cliDir, "dashboard"), resolve(repoRoot, "apps/dashboard/dist")]) ?? resolve(repoRoot, "apps/dashboard/dist");
 var pluginBundlePath = firstExisting([resolve(cliDir, "agent-blackbox.plugin.mjs")]);
-void main(args);
+function globalDataDir() {
+  const xdg = process.env.XDG_DATA_HOME;
+  return xdg && xdg.length > 0 ? join6(xdg, "agent-blackbox") : join6(homedir2(), ".local", "share", "agent-blackbox");
+}
+void main(args).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});
 async function main(argv) {
   if (argv.includes("--version") || argv.includes("-v")) {
     console.log(AGENT_BLACKBOX_DAEMON_VERSION);
@@ -2034,19 +2152,48 @@ async function main(argv) {
   const command = argv[0] ?? "help";
   if (command === "daemon") {
     const projectDir = readFlag(argv, "--project") ?? process.cwd();
-    const port = Number(readFlag(argv, "--port") ?? "47831");
+    const port = portArg(readFlag(argv, "--port"), 47831);
     const daemon = await startTraceDaemon({ projectDir, port });
     console.log(`Agent-Blackbox daemon listening on http://127.0.0.1:${daemon.port}`);
     console.log(`Trace file: ${daemon.eventsFile}`);
     return;
   }
   if (command === "up") {
-    const projectDir = resolve(readFlag(argv, "--project") ?? process.cwd());
-    const port = Number(readFlag(argv, "--port") ?? "47831");
-    const uiPort = Number(readFlag(argv, "--ui-port") ?? "5173");
+    const projectFlag = readFlag(argv, "--project");
+    const global = projectFlag === void 0;
+    const port = portArg(readFlag(argv, "--port"), 47831);
+    const uiPort = portArg(readFlag(argv, "--ui-port"), 5173);
     const daemonUrl = `http://127.0.0.1:${port}`;
-    const adapterPackage = readFlag(argv, "--adapter-package") ?? `file:${resolve(repoRoot, "packages/opencode-adapter")}`;
     const suggest = readSuggestConfig(argv);
+    let daemon;
+    if (global) {
+      if (!pluginBundlePath) {
+        throw new Error("Global install needs the self-contained recorder bundle. Use the published npx package, or `npm run build:cli` then `node packages/cli/dist/cli.js up`.\n(Or scope to one project with: agent-blackbox up --project <dir>.)");
+      }
+      const { pluginPath } = await installGlobalRecorder({ daemonUrl, pluginBundlePath });
+      const dataDir = globalDataDir();
+      const eventsFile = join6(dataDir, "events.ndjson");
+      daemon = await startTraceDaemon({ projectDir: dataDir, port, eventsFile, suggest });
+      const ui2 = await startDashboardServer({ distDir: dashboardDistDir, port: uiPort, daemonUrl });
+      const dashboardUrl2 = `http://127.0.0.1:${ui2.port}`;
+      console.log(`\u2713 Global OpenCode recorder installed: ${pluginPath}`);
+      console.log(`\u2713 Agent-Blackbox is up (recording all OpenCode sessions)`);
+      console.log(`  Dashboard:  ${dashboardUrl2}`);
+      console.log(`  Daemon API: ${daemonUrl}  (trace: ${daemon.eventsFile})`);
+      console.log(`  Suggestions: ${suggest.mode}${suggest.model ? ` (${suggest.model})` : ""}`);
+      console.log("");
+      if (!argv.includes("--no-open"))
+        openInBrowser(dashboardUrl2);
+      console.log("Now use OpenCode however you already do \u2014 the dashboard fills in live:");
+      console.log("  opencode                 # in any folder (terminal), or");
+      console.log("  the OpenCode desktop app # open any project");
+      console.log("");
+      console.log("Stop recording any time with:  agent-blackbox uninstall");
+      console.log("Press Ctrl+C to stop the daemon + dashboard.");
+      return;
+    }
+    const projectDir = resolve(projectFlag);
+    const adapterPackage = readFlag(argv, "--adapter-package") ?? `file:${resolve(repoRoot, "packages/opencode-adapter")}`;
     try {
       const result = await initOpenCodeProject({
         projectDir,
@@ -2064,7 +2211,7 @@ async function main(argv) {
         throw error;
       }
     }
-    const daemon = await startTraceDaemon({ projectDir, port, suggest });
+    daemon = await startTraceDaemon({ projectDir, port, suggest });
     const ui = await startDashboardServer({ distDir: dashboardDistDir, port: uiPort, daemonUrl });
     const dashboardUrl = `http://127.0.0.1:${ui.port}`;
     console.log("");
@@ -2076,11 +2223,29 @@ async function main(argv) {
     if (!argv.includes("--no-open"))
       openInBrowser(dashboardUrl);
     console.log("Now run your agent in that project, e.g.:");
-    console.log(`  AGENT_BLACKBOX_DAEMON_URL=${daemonUrl} opencode run --dir ${projectDir} "Read the code, run tests, summarize."`);
+    console.log(`  opencode    # in ${projectDir} (the project-local recorder streams here)`);
     console.log("");
     console.log("Press Ctrl+C to stop.");
     return;
   }
+  if (command === "install") {
+    const port = portArg(readFlag(argv, "--port"), 47831);
+    const daemonUrl = `http://127.0.0.1:${port}`;
+    if (!pluginBundlePath) {
+      throw new Error("Global install needs the self-contained recorder bundle. Use the published npx package, or `npm run build:cli` first.");
+    }
+    const { pluginPath } = await installGlobalRecorder({ daemonUrl, pluginBundlePath });
+    console.log(`\u2713 Global OpenCode recorder installed: ${pluginPath}`);
+    console.log(`  Every OpenCode session (any folder, terminal, or the app) now streams to ${daemonUrl}.`);
+    console.log(`  Start the dashboard with:  agent-blackbox up`);
+    console.log(`  Remove with:               agent-blackbox uninstall`);
+    return;
+  }
+  if (command === "uninstall") {
+    const { pluginPath, removed } = await uninstallGlobalRecorder();
+    console.log(removed ? `\u2713 Removed global OpenCode recorder: ${pluginPath}` : `Nothing to remove \u2014 ${pluginPath} is not present.`);
+    return;
+  }
   if (command === "replay") {
     const eventsFile = argv[1];
     if (!eventsFile) {
@@ -2138,8 +2303,11 @@ function printHelp() {
   console.log(describeDaemon());
   console.log("");
   console.log("Usage:");
-  console.log("  agent-blackbox up [--project <dir>] [--port <port>] [--ui-port <port>]   # plugin + daemon + dashboard, one command");
-  console.log("       [--suggest auto|free|off|ollama|opencode|openai-compat] [--suggest-model <id>] [--suggest-base-url <url>] [--optimize] [--no-open]");
+  console.log("  agent-blackbox up                       # GLOBAL: record every OpenCode session (any folder / the app) + daemon + dashboard");
+  console.log("  agent-blackbox up --project <dir>        # scope the recorder to one project instead");
+  console.log("       [--port <port>] [--ui-port <port>] [--suggest auto|free|off|ollama|opencode|openai-compat] [--suggest-model <id>] [--optimize] [--no-open]");
+  console.log("  agent-blackbox install [--port <port>]   # install the global recorder only (no daemon)");
+  console.log("  agent-blackbox uninstall                 # remove the global recorder");
   console.log("  agent-blackbox daemon [--project <dir>] [--port <port>]");
   console.log("  agent-blackbox init-opencode [--project <dir>] [--daemon-url <url>] [--adapter-package <specifier>] [--force] [--optimize]");
   console.log("  agent-blackbox optimize [--project <dir>] [--apply | --check | --revert]   # write/measure/rollback AGENTS.md efficiency memory");
@@ -2163,6 +2331,10 @@ function readFlag(argv, flag) {
   }
   return argv[index + 1];
 }
+function portArg(raw, fallback) {
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 0 && n <= 65535 ? n : fallback;
+}
 function readSuggestConfig(argv) {
   const modes = ["auto", "off", "free", "ollama", "opencode", "openai-compat"];
   const raw = readFlag(argv, "--suggest") ?? process.env.AGENT_BLACKBOX_SUGGEST ?? "auto";