@birdybeep/cli 0.3.0 → 0.6.0

package/dist/index.cjs

@@ -43,15 +43,191 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/commands/agent.ts
-var import_claude_code = require("@birdybeep/claude-code");
+var import_claude_code2 = require("@birdybeep/claude-code");
 var import_codex = require("@birdybeep/codex");
 var import_copilot = require("@birdybeep/copilot");
-var import_cursor = require("@birdybeep/cursor");
+var import_cursor2 = require("@birdybeep/cursor");
 var import_opencode = require("@birdybeep/opencode");
 
-// src/framework.ts
+// src/diagnostics.ts
 var import_node_fs = require("fs");
+var import_node_os = require("os");
 var import_agent_core = require("@birdybeep/agent-core");
+var import_claude_code = require("@birdybeep/claude-code");
+var import_cursor = require("@birdybeep/cursor");
+async function gatherIntegrations(adapters) {
+  return Promise.all(
+    adapters.map(async (a) => ({
+      harness: a.id,
+      displayName: a.displayName,
+      status: await a.status()
+    }))
+  );
+}
+async function isPaired(tokenOptions = {}) {
+  return await (0, import_agent_core.getToken)(tokenOptions) !== null;
+}
+function localQueueDepth() {
+  return new import_agent_core.LocalEventQueue().size();
+}
+function localQueueOverflowDrops() {
+  return new import_agent_core.LocalEventQueue().overflowDropCount();
+}
+function unpairedActivity() {
+  return (0, import_agent_core.readUnpairedNotice)();
+}
+function describeUnpairedActivity(notice) {
+  const since = new Date(notice.firstAt).toISOString();
+  const from = notice.harnesses.length > 0 ? ` from ${notice.harnesses.join(", ")}` : "";
+  return `${notice.count} event(s)${from} fired since ${since} and were NOT sent \u2014 this machine is not paired.`;
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function birdyBeepHookCount(path, events, isBirdyBeepEntry) {
+  if (!(0, import_node_fs.existsSync)(path)) return 0;
+  let parsed;
+  try {
+    parsed = JSON.parse((0, import_node_fs.readFileSync)(path, "utf8"));
+  } catch {
+    return null;
+  }
+  const hooks = asRecord(asRecord(parsed)["hooks"]);
+  let present = 0;
+  for (const event of events) {
+    const entries = hooks[event];
+    if (Array.isArray(entries) && entries.some(isBirdyBeepEntry)) present += 1;
+  }
+  return present;
+}
+async function cursorBridgeOnly(opts = {}) {
+  const home = opts.home ?? (0, import_node_os.homedir)();
+  const detection = await (opts.detect ?? (() => (0, import_cursor.detectCursor)({ home })))();
+  if (!detection.detected) return false;
+  const claude = birdyBeepHookCount((0, import_claude_code.claudeSettingsPath)(home), import_claude_code.BIRDYBEEP_HOOK_EVENTS, import_claude_code.isBirdyBeepEntry);
+  if (claude === null || claude === 0) return false;
+  return birdyBeepHookCount((0, import_cursor.cursorHooksPath)(home), import_cursor.BIRDYBEEP_HOOK_EVENTS, import_cursor.isBirdyBeepEntry) === 0;
+}
+function filteredActivity() {
+  return (0, import_agent_core.readFilteredActivity)();
+}
+function describeFilteredActivity(activity) {
+  const types = Object.entries(activity.byType).sort(([, a], [, b]) => b - a).map(([type, n]) => `${type} \xD7${n}`).join(", ");
+  const since = new Date(activity.firstAt).toISOString();
+  return `${activity.count} local-only event(s) since ${since}${types ? ` (${types})` : ""} \u2014 hooks are firing; these types never beep, so they are not sent.`;
+}
+function machineIdentity() {
+  return (0, import_agent_core.getMachineIdentity)();
+}
+var CONFIGURED_STATUSES = /* @__PURE__ */ new Set([
+  "installed",
+  "needs_trust",
+  "needs_restart"
+]);
+function gradeSurfaces(surfaces, status, observation) {
+  const builds = Object.values(observation?.builds ?? {});
+  const configured = CONFIGURED_STATUSES.has(status);
+  const claimedByKind = /* @__PURE__ */ new Map();
+  for (const s of surfaces) {
+    if (s.version === void 0) continue;
+    const versions = claimedByKind.get(s.kind) ?? /* @__PURE__ */ new Set();
+    versions.add(s.version);
+    claimedByKind.set(s.kind, versions);
+  }
+  const graded = surfaces.map((surface) => {
+    const exact = builds.filter(
+      (b) => b.surface === surface.kind && b.version === surface.version && surface.version !== void 0
+    );
+    let soleOfKind = [];
+    if (surface.version === void 0) {
+      const sameKindVersionless = surfaces.filter(
+        (s) => s.version === void 0 && s.kind === surface.kind
+      );
+      const unclaimed = builds.filter(
+        (b) => b.surface === surface.kind && !(claimedByKind.get(surface.kind)?.has(b.version) ?? false)
+      );
+      if (unclaimed.length === 1 && sameKindVersionless.length === 1) soleOfKind = unclaimed;
+    }
+    const unattributed = surface.version === void 0 ? [] : builds.filter((b) => b.surface === "unknown" && b.version === surface.version);
+    const sharesVersion = surface.version !== void 0 && surfaces.some((s) => s !== surface && s.version === surface.version);
+    const ambiguous = unattributed.length > 0 && sharesVersion;
+    const matched = [...exact, ...soleOfKind, ...ambiguous ? [] : unattributed];
+    const events = matched.reduce((total, b) => total + b.count, 0);
+    const lastAt = matched.reduce(
+      (latest, b) => latest === void 0 || b.lastAt > latest ? b.lastAt : latest,
+      void 0
+    );
+    const observedVersion = surface.version === void 0 ? soleOfKind[0]?.version : void 0;
+    return {
+      surface,
+      events,
+      ambiguous,
+      ...lastAt !== void 0 ? { lastAt } : {},
+      ...observedVersion !== void 0 ? { observedVersion } : {}
+    };
+  });
+  const anyActive = graded.some((g) => g.events > 0 && g.surface.shadowed !== true);
+  return graded.map(({ ambiguous, ...g }) => ({
+    ...g,
+    coverage: !configured ? "uncovered" : g.events > 0 ? "active" : anyActive && g.surface.shadowed !== true && !ambiguous ? "uncovered" : "wired"
+  }));
+}
+async function gatherSurfaces(adapters, options = {}) {
+  const observed = (0, import_agent_core.readObservedBuilds)(options.observedBuilds ?? {});
+  return Promise.all(
+    adapters.map(async (adapter) => {
+      const observation = observed[adapter.id];
+      const base4 = {
+        harness: adapter.id,
+        displayName: adapter.displayName,
+        unversionedEvents: observation?.unversioned ?? 0
+      };
+      try {
+        const [detection, status] = await Promise.all([adapter.detect(), adapter.status()]);
+        return {
+          ...base4,
+          status,
+          surfaces: detection.detected ? gradeSurfaces(detection.surfaces ?? [], status, observation) : []
+        };
+      } catch {
+        return { ...base4, status: "unknown", surfaces: [] };
+      }
+    })
+  );
+}
+function describeSurface(state) {
+  const version = state.surface.version ?? state.observedVersion;
+  return version !== void 0 ? `${state.surface.label} ${version}` : state.surface.label;
+}
+function describeSurfaceCoverage(state, group) {
+  if (state.coverage === "active") {
+    const last = state.lastAt !== void 0 ? `, last ${new Date(state.lastAt).toISOString()}` : "";
+    return `covered \u2014 ${state.events} event(s) from this build${last}`;
+  }
+  if (state.coverage === "wired") {
+    return state.surface.shadowed === true ? `${group.displayName}'s hooks are installed and this build shares them, but another install comes first on PATH \u2014 it only runs if that order changes` : `${group.displayName}'s hooks are installed and this build shares them; nothing has fired from it yet`;
+  }
+  if (!CONFIGURED_STATUSES.has(group.status)) {
+    return `not covered \u2014 ${group.displayName} carries no BirdyBeep hooks, so this build cannot beep`;
+  }
+  const active = group.surfaces.filter((s) => s.coverage === "active").map(describeSurface);
+  const delivering = active.join(", ");
+  const verb = active.length === 1 ? "is" : "are";
+  return `not covered \u2014 nothing has ever fired from this build, while ${delivering} ${verb} delivering through the same config`;
+}
+function installTarget(harness) {
+  return harness === "claude_code" ? "claude" : harness;
+}
+function surfaceRemedy(state, group) {
+  if (state.coverage !== "uncovered") return void 0;
+  if (!CONFIGURED_STATUSES.has(group.status)) return void 0;
+  const install = `\`birdybeep agent install ${installTarget(group.harness)}\``;
+  return state.surface.kind === "desktop" ? `Run a turn in ${state.surface.label}. If it stays uncovered, that build cannot run the hook command: a desktop app spawns its engine with your LOGIN shell's PATH, not an interactive shell's, so a bare command is invisible to it. Re-run ${install} from a shell where \`birdybeep\` resolves \u2014 it rewrites the entry with absolute paths that need no PATH at all.` : `Run a turn in ${state.surface.label}. If it stays uncovered, re-run ${install} from a shell where \`birdybeep\` resolves, then check that ${state.surface.enginePath} is the build you are actually running.`;
+}
+
+// src/framework.ts
+var import_node_fs2 = require("fs");
+var import_agent_core2 = require("@birdybeep/agent-core");
 var EXIT = { OK: 0, ERROR: 1, USAGE: 2 };
 function createIo(json, stdout, stderr) {
   return {
@@ -129,11 +305,17 @@ function isUnknownFlag(token, allowed) {
 function renderRootHelp(version, commands) {
   const width = Math.max(...commands.map((c) => c.name.length));
   const lines = commands.map((c) => `  ${c.name.padEnd(width)}  ${c.summary}`);
+  const featured = commands.filter((c) => c.gettingStarted !== void 0);
   return [
     `birdybeep ${version} \u2014 stream coding-agent lifecycle events to BirdyBeep.`,
     "",
     "Usage:",
     "  birdybeep <command> [options]",
+    ...featured.length > 0 ? [
+      "",
+      "Getting started:",
+      ...featured.map((c) => `  birdybeep ${c.name}  ${c.gettingStarted ?? ""}`)
+    ] : [],
     "",
     "Commands:",
     ...lines,
@@ -188,7 +370,7 @@ async function dispatch(argv, deps) {
   const io = createIo(flags.json, deps.stdout, deps.stderr);
   if (deps.ensureConfig !== false) {
     try {
-      (0, import_node_fs.mkdirSync)((0, import_agent_core.birdyBeepConfigDir)(), { recursive: true, mode: 448 });
+      (0, import_node_fs2.mkdirSync)((0, import_agent_core2.birdyBeepConfigDir)(), { recursive: true, mode: 448 });
     } catch {
     }
   }
@@ -215,7 +397,11 @@ async function dispatch(argv, deps) {
   if (rest.length === 0 || flags.help && command === void 0) {
     io.emit(renderRootHelp(deps.version, deps.commands), {
       version: deps.version,
-      commands: deps.commands.map((c) => ({ name: c.name, summary: c.summary }))
+      commands: deps.commands.map((c) => ({
+        name: c.name,
+        summary: c.summary,
+        ...c.gettingStarted !== void 0 ? { gettingStarted: c.gettingStarted } : {}
+      }))
     });
     return EXIT.OK;
   }
@@ -269,10 +455,10 @@ async function dispatch(argv, deps) {
 
 // src/commands/agent.ts
 var DEFAULT_ADAPTERS = [
-  import_claude_code.claudeCodeAdapter,
+  import_claude_code2.claudeCodeAdapter,
   import_codex.codexAdapter,
   import_opencode.opencodeAdapter,
-  import_cursor.cursorAdapter,
+  import_cursor2.cursorAdapter,
   import_copilot.copilotAdapter
 ];
 var TARGET_TO_ID = {
@@ -296,7 +482,10 @@ function selectAdapters(target, adapters) {
   if (id === void 0) return "unknown";
   return adapters.filter((a) => a.id === id);
 }
-async function installSelected(adapters, ctx) {
+function installTarget2(harness) {
+  return harness === "claude_code" ? "claude" : harness;
+}
+async function installSelected(adapters, ctx, tokenOptions) {
   const target = ctx.args[0] ?? "all";
   const selected = selectAdapters(target, adapters);
   if (selected === "unknown") {
@@ -323,8 +512,9 @@ async function installSelected(adapters, ctx) {
       requiredActions: result.requiredActions
     });
   }
+  const paired = await isPaired(tokenOptions);
   if (ctx.flags.json) {
-    ctx.io.result({ target, results: outcomes });
+    ctx.io.result({ target, paired, results: outcomes });
     return EXIT.OK;
   }
   if (outcomes.length === 0 || outcomes.every((o) => !o.detected)) {
@@ -332,13 +522,20 @@ async function installSelected(adapters, ctx) {
   }
   for (const o of outcomes) {
     if (!o.detected) {
-      ctx.io.line(`\u2013  ${o.displayName}: not detected (skipped)`);
+      ctx.io.line(
+        `\u2013  ${o.displayName}: not detected (skipped) \u2014 install it, then run \`birdybeep agent install ${installTarget2(o.harness)}\``
+      );
       continue;
     }
     const changed = (o.changedFiles ?? []).length > 0 ? o.changedFiles.join(", ") : "no changes";
     ctx.io.line(`\u2713  ${o.displayName}: ${o.status} (${changed})`);
     for (const action of o.requiredActions ?? []) ctx.io.line(`     \u2192 ${action}`);
   }
+  if (!paired) {
+    ctx.io.line(
+      "\u26A0  This machine is not paired, so nothing these hooks produce can reach you. Run `birdybeep setup` \u2014 it pairs, wires up every agent, and sends a test Beep."
+    );
+  }
   return EXIT.OK;
 }
 async function uninstallSelected(adapters, ctx) {
@@ -377,6 +574,7 @@ async function uninstallSelected(adapters, ctx) {
 }
 function createAgentCommand(deps = {}) {
   const adapters = deps.adapters ?? DEFAULT_ADAPTERS;
+  const tokenOptions = deps.tokenOptions ?? {};
   return {
     name: "agent",
     summary: "Install or uninstall harness adapters",
@@ -386,7 +584,7 @@ function createAgentCommand(deps = {}) {
         name: "install",
         summary: "Install adapters (all | claude | codex | opencode | cursor | copilot)",
         usage: "birdybeep agent install [all|claude|codex|opencode|cursor|copilot]",
-        run: (ctx) => installSelected(adapters, ctx)
+        run: (ctx) => installSelected(adapters, ctx, tokenOptions)
       },
       {
         name: "uninstall",
@@ -400,24 +598,24 @@ function createAgentCommand(deps = {}) {
 
 // src/commands/doctor.ts
 var import_agent_core4 = require("@birdybeep/agent-core");
-var import_claude_code2 = require("@birdybeep/claude-code");
+var import_claude_code3 = require("@birdybeep/claude-code");
 var import_codex2 = require("@birdybeep/codex");
 var import_copilot2 = require("@birdybeep/copilot");
-var import_cursor2 = require("@birdybeep/cursor");
+var import_cursor3 = require("@birdybeep/cursor");
 var import_opencode2 = require("@birdybeep/opencode");
 
 // src/config.ts
-var import_node_fs2 = require("fs");
+var import_node_fs3 = require("fs");
 var import_node_path = require("path");
-var import_agent_core2 = require("@birdybeep/agent-core");
+var import_agent_core3 = require("@birdybeep/agent-core");
 var DEFAULT_API_URL = "https://api.birdybeep.com";
 var CONFIG_FILE = "config.json";
 function cliConfigPath() {
-  return (0, import_node_path.join)((0, import_agent_core2.birdyBeepConfigDir)(), CONFIG_FILE);
+  return (0, import_node_path.join)((0, import_agent_core3.birdyBeepConfigDir)(), CONFIG_FILE);
 }
 function readCliConfig() {
   try {
-    const parsed = JSON.parse((0, import_node_fs2.readFileSync)(cliConfigPath(), "utf8"));
+    const parsed = JSON.parse((0, import_node_fs3.readFileSync)(cliConfigPath(), "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : {};
   } catch {
     return {};
@@ -430,8 +628,8 @@ function writeCliConfig(patch) {
   if (apiUrl !== void 0) merged.apiUrl = apiUrl;
   const expectEmail = patch.expectEmail ?? current.expectEmail;
   if (expectEmail !== void 0) merged.expectEmail = expectEmail;
-  (0, import_node_fs2.mkdirSync)((0, import_agent_core2.birdyBeepConfigDir)(), { recursive: true, mode: 448 });
-  (0, import_node_fs2.writeFileSync)(cliConfigPath(), `${JSON.stringify(merged, null, 2)}
+  (0, import_node_fs3.mkdirSync)((0, import_agent_core3.birdyBeepConfigDir)(), { recursive: true, mode: 448 });
+  (0, import_node_fs3.writeFileSync)(cliConfigPath(), `${JSON.stringify(merged, null, 2)}
 `, { mode: 384 });
 }
 function resolveApiUrl() {
@@ -446,33 +644,12 @@ function resolveRegistryUrl() {
   return DEFAULT_REGISTRY_URL;
 }
 
-// src/diagnostics.ts
-var import_agent_core3 = require("@birdybeep/agent-core");
-async function gatherIntegrations(adapters) {
-  return Promise.all(
-    adapters.map(async (a) => ({
-      harness: a.id,
-      displayName: a.displayName,
-      status: await a.status()
-    }))
-  );
-}
-async function isPaired(tokenOptions = {}) {
-  return await (0, import_agent_core3.getToken)(tokenOptions) !== null;
-}
-function localQueueDepth() {
-  return new import_agent_core3.LocalEventQueue().size();
-}
-function machineIdentity() {
-  return (0, import_agent_core3.getMachineIdentity)();
-}
-
 // src/commands/doctor.ts
 var DEFAULT_ADAPTERS2 = [
-  import_claude_code2.claudeCodeAdapter,
+  import_claude_code3.claudeCodeAdapter,
   import_codex2.codexAdapter,
   import_opencode2.opencodeAdapter,
-  import_cursor2.cursorAdapter,
+  import_cursor3.cursorAdapter,
   import_copilot2.copilotAdapter
 ];
 async function defaultProbeNetwork(baseUrl) {
@@ -509,6 +686,32 @@ function createDoctorCommand(deps = {}) {
           remedy: "Run `birdybeep pair` to pair this machine."
         }
       );
+      const unpaired = unpairedActivity();
+      if (unpaired !== null) {
+        checks.push({
+          name: "Events lost while unpaired",
+          ok: false,
+          detail: describeUnpairedActivity(unpaired),
+          remedy: "Run `birdybeep pair`. Events that fired before pairing are gone \u2014 a first pairing does not replay them."
+        });
+      }
+      if (await cursorBridgeOnly(deps.detectCursor ? { detect: deps.detectCursor } : {})) {
+        checks.push({
+          name: "Approval beeps from Cursor",
+          ok: false,
+          detail: "Cursor is running your agent through the Claude Code hooks \u2014 that is why Cursor events arrive without a Cursor install. Its bridge drops Notification and PermissionRequest, so approvals never reach you.",
+          remedy: "Run `birdybeep agent install cursor` to get approval beeps from Cursor's own shell and MCP permission prompts. Keeping both installed is safe \u2014 duplicate events are collapsed."
+        });
+      }
+      const filtered = filteredActivity();
+      if (filtered !== null) {
+        checks.push({
+          name: "Local-only events (never notifiable)",
+          ok: true,
+          detail: describeFilteredActivity(filtered)
+        });
+      }
+      const surfaceGroups = await gatherSurfaces(adapters, deps.surfaceOptions ?? {});
       for (const adapter of adapters) {
         const result = await adapter.doctor();
         for (const c of result.checks) {
@@ -519,14 +722,26 @@ function createDoctorCommand(deps = {}) {
             ...c.remedy !== void 0 ? { remedy: c.remedy } : {}
           });
         }
+        const group = surfaceGroups.find((g) => g.harness === adapter.id);
+        if (group === void 0) continue;
+        for (const state of group.surfaces) {
+          const remedy = surfaceRemedy(state, group);
+          checks.push({
+            name: `${adapter.displayName}: ${describeSurface(state)}`,
+            ok: state.coverage !== "uncovered",
+            detail: describeSurfaceCoverage(state, group),
+            ...remedy !== void 0 ? { remedy } : {}
+          });
+        }
       }
       const depthBefore = localQueueDepth();
       const drain = await makeSender(apiUrl).drainNow();
       const depthAfter = localQueueDepth();
+      const overflowDropped = localQueueOverflowDrops();
       checks.push({
         name: "Local queue",
         ok: true,
-        detail: `${depthBefore} queued \u2192 ${drain.delivered} delivered, ${depthAfter} remaining`
+        detail: `${depthBefore} queued \u2192 ${drain.delivered} delivered, ${depthAfter} remaining` + (overflowDropped > 0 ? `; ${overflowDropped} dropped by the ${import_agent_core4.DEFAULT_QUEUE_MAX_ENTRIES} entry cap` : "")
       });
       const reachable = await probeNetwork(apiUrl);
       checks.push(
@@ -542,7 +757,10 @@ function createDoctorCommand(deps = {}) {
         ctx.io.result({
           ok,
           checks,
-          queue: { depthBefore, delivered: drain.delivered, depthAfter }
+          surfaces: surfaceGroups,
+          queue: { depthBefore, delivered: drain.delivered, depthAfter, overflowDropped },
+          ...unpaired !== null ? { unpairedActivity: unpaired } : {},
+          ...filtered !== null ? { filteredActivity: filtered } : {}
         });
       } else {
         for (const c of checks) {
@@ -559,20 +777,20 @@ function createDoctorCommand(deps = {}) {
 // src/commands/hook.ts
 var import_node_child_process = require("child_process");
 var import_node_crypto = require("crypto");
-var import_node_fs3 = require("fs");
-var import_node_os = require("os");
+var import_node_fs4 = require("fs");
+var import_node_os2 = require("os");
 var import_node_path2 = require("path");
 var import_agent_core5 = require("@birdybeep/agent-core");
-var import_claude_code3 = require("@birdybeep/claude-code");
+var import_claude_code4 = require("@birdybeep/claude-code");
 var import_codex3 = require("@birdybeep/codex");
 var import_copilot3 = require("@birdybeep/copilot");
-var import_cursor3 = require("@birdybeep/cursor");
+var import_cursor4 = require("@birdybeep/cursor");
 var import_opencode3 = require("@birdybeep/opencode");
 var RUNNERS = {
-  claude: import_claude_code3.runClaudeHook,
+  claude: import_claude_code4.runClaudeHook,
   codex: import_codex3.runCodexHook,
   opencode: import_opencode3.runOpenCodeHook,
-  cursor: import_cursor3.runCursorHook
+  cursor: import_cursor4.runCursorHook
 };
 var HOOK_HARNESSES = [
   "claude",
@@ -599,12 +817,43 @@ function withTimeout(promise, ms, fallback) {
 function isHarnessName(value) {
   return value === "claude" || value === "codex" || value === "opencode" || value === "cursor" || value === "copilot";
 }
+function resolveHookHarness(harness, payload) {
+  return harness === "claude" && (0, import_cursor4.isCursorHookPayload)(payload) ? "cursor" : harness;
+}
+function recognizesPayload(harness, payload) {
+  switch (harness) {
+    case "claude":
+      return (0, import_claude_code4.isClaudeCodeHookPayload)(payload);
+    case "cursor":
+      return (0, import_cursor4.isCursorHookEventName)(asRecord2(payload)["hook_event_name"]);
+    case "codex":
+      return (0, import_codex3.isCodexHookPayload)(payload);
+    case "opencode":
+      return (0, import_opencode3.isOpenCodeEventPayload)(payload);
+    case "copilot":
+      return (0, import_copilot3.isCopilotHookPayload)(payload);
+  }
+}
+function asRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function describeDiscriminator(payload) {
+  const record = asRecord2(payload);
+  for (const field of ["hook_event_name", "type"]) {
+    const value = record[field];
+    if (typeof value !== "string") continue;
+    const capped = value.length > 64 ? `${value.slice(0, 63)}\u2026` : value;
+    return `${field} ${JSON.stringify(capped)}`;
+  }
+  return "the payload";
+}
 function runHookCommand(harness, payload, sender, copilotEventName) {
-  if (harness === "copilot") {
+  const handler = resolveHookHarness(harness, payload);
+  if (handler === "copilot") {
     if (copilotEventName === void 0) return Promise.resolve({ outcome: "skipped" });
     return (0, import_copilot3.runCopilotHook)(copilotEventName, payload, { sender });
   }
-  return RUNNERS[harness](payload, { sender });
+  return RUNNERS[handler](payload, { sender });
 }
 function readStdinDefault() {
   return new Promise((resolve) => {
@@ -630,10 +879,10 @@ function detachCodexNotifyWorker(payload) {
   try {
     const birdybeep = (0, import_agent_core5.resolveOnPath)("birdybeep");
     if (birdybeep === null) return false;
-    const tmpFile = (0, import_node_path2.join)((0, import_node_os.tmpdir)(), `birdybeep-notify-${(0, import_node_crypto.randomBytes)(16).toString("hex")}.json`);
+    const tmpFile = (0, import_node_path2.join)((0, import_node_os2.tmpdir)(), `birdybeep-notify-${(0, import_node_crypto.randomBytes)(16).toString("hex")}.json`);
     file = tmpFile;
-    (0, import_node_fs3.writeFileSync)(tmpFile, payload, { mode: 384 });
-    fd = (0, import_node_fs3.openSync)(tmpFile, "r");
+    (0, import_node_fs4.writeFileSync)(tmpFile, payload, { mode: 384 });
+    fd = (0, import_node_fs4.openSync)(tmpFile, "r");
     const child = (0, import_node_child_process.spawn)(birdybeep, ["hook", "codex"], {
       cwd: (0, import_node_path2.dirname)(birdybeep),
       // trusted dir, never the inherited/attacker cwd
@@ -647,7 +896,7 @@ function detachCodexNotifyWorker(payload) {
     });
     child.on("error", () => {
       try {
-        (0, import_node_fs3.rmSync)(tmpFile, { force: true });
+        (0, import_node_fs4.rmSync)(tmpFile, { force: true });
       } catch {
       }
     });
@@ -656,7 +905,7 @@ function detachCodexNotifyWorker(payload) {
   } catch {
     if (file !== void 0) {
       try {
-        (0, import_node_fs3.rmSync)(file, { force: true });
+        (0, import_node_fs4.rmSync)(file, { force: true });
       } catch {
       }
     }
@@ -664,7 +913,7 @@ function detachCodexNotifyWorker(payload) {
   } finally {
     if (fd !== void 0) {
       try {
-        (0, import_node_fs3.closeSync)(fd);
+        (0, import_node_fs4.closeSync)(fd);
       } catch {
       }
     }
@@ -691,35 +940,76 @@ function createHookCommand(deps = {}) {
         return EXIT.OK;
       }
       const copilotEventName = harness === "copilot" && (0, import_copilot3.isCopilotHookEventName)(ctx.args[1]) ? ctx.args[1] : void 0;
-      const raw = await withTimeout(
+      if (harness === "copilot" && copilotEventName === void 0) {
+        ctx.io.errline(
+          `birdybeep hook copilot: second argument must be a Copilot hook event name, got ${JSON.stringify(ctx.args[1] ?? "(none)")} \u2014 nothing was sent.`
+        );
+        return EXIT.USAGE;
+      }
+      const read = await withTimeout(
         readHookPayload(ctx.args, readStdin, harness === "copilot"),
         stdinTimeoutMs,
-        ""
+        null
       );
       const notifyStdinFile = process.env[NOTIFY_STDIN_FILE_ENV];
-      if (notifyStdinFile !== void 0 && (0, import_node_path2.dirname)(notifyStdinFile) === (0, import_node_os.tmpdir)() && (0, import_node_path2.basename)(notifyStdinFile).startsWith("birdybeep-notify-")) {
+      if (notifyStdinFile !== void 0 && (0, import_node_path2.dirname)(notifyStdinFile) === (0, import_node_os2.tmpdir)() && (0, import_node_path2.basename)(notifyStdinFile).startsWith("birdybeep-notify-")) {
         try {
-          (0, import_node_fs3.rmSync)(notifyStdinFile, { force: true });
+          (0, import_node_fs4.rmSync)(notifyStdinFile, { force: true });
         } catch {
         }
       }
+      const drop = (reason, detail) => {
+        ctx.io.result({ harness, outcome: "skipped", reason });
+        ctx.io.errline(`birdybeep hook ${harness}: ${detail} \u2014 nothing was sent.`);
+        return EXIT.ERROR;
+      };
+      if (read === null) {
+        return drop(
+          "stdin-timeout",
+          `timed out after ${stdinTimeoutMs}ms waiting for the payload on stdin`
+        );
+      }
+      const raw = read;
+      if (raw.trim().length === 0) {
+        return drop("empty-payload", "the payload was empty");
+      }
       let payload;
       try {
         payload = JSON.parse(raw);
       } catch {
-        ctx.io.result({ harness, outcome: "skipped" });
-        return EXIT.OK;
+        return drop("invalid-json", `the ${raw.length}-byte payload is not valid JSON`);
+      }
+      const handler = resolveHookHarness(harness, payload);
+      const routedFrom = handler !== harness ? { routedFrom: harness } : {};
+      if (!recognizesPayload(handler, payload)) {
+        ctx.io.result({
+          harness: handler,
+          ...routedFrom,
+          outcome: "skipped",
+          reason: "foreign-payload"
+        });
+        const article = handler === "opencode" ? "an" : "a";
+        ctx.io.errline(
+          `birdybeep hook ${harness}: ${describeDiscriminator(payload)} is not ${article} ${handler} hook event \u2014 nothing was sent. Check which tool is running this hook.`
+        );
+        return EXIT.ERROR;
       }
       const sender = makeSender(resolveApiUrl());
       const result = await runHookCommand(harness, payload, sender, copilotEventName);
       ctx.io.result({
-        harness,
+        harness: handler,
+        ...routedFrom,
         ...copilotEventName !== void 0 ? { event: copilotEventName } : {},
         outcome: result.outcome,
         eventType: result.eventType,
         ...result.send?.decision ? { decision: result.send.decision } : {},
         ...result.send?.status !== void 0 ? { status: result.send.status } : {}
       });
+      if (result.outcome === "unpaired") {
+        ctx.io.errline(
+          "birdybeep: this machine is not paired \u2014 the event was not sent and was not queued. Run `birdybeep pair` (or `birdybeep doctor` to see how many events this has cost)."
+        );
+      }
       return EXIT.OK;
     }
   };
@@ -777,8 +1067,8 @@ function createUnpairCommand(deps = {}) {
 }
 
 // src/commands/pair.ts
-var import_node_fs4 = require("fs");
-var import_agent_core8 = require("@birdybeep/agent-core");
+var import_node_fs5 = require("fs");
+var import_agent_core9 = require("@birdybeep/agent-core");
 var import_uqr = require("uqr");
 
 // src/pairing.ts
@@ -852,7 +1142,277 @@ async function pairTokenPoll(apiUrl, deviceCode, fetchImpl, machineFingerprint,
 }
 
 // src/version.ts
-var CLI_VERSION = "0.3.0".length > 0 ? "0.3.0" : "0.0.0";
+var CLI_VERSION = "0.6.0".length > 0 ? "0.6.0" : "0.0.0";
+
+// src/commands/setup.ts
+var import_claude_code5 = require("@birdybeep/claude-code");
+var import_codex4 = require("@birdybeep/codex");
+var import_copilot4 = require("@birdybeep/copilot");
+var import_cursor5 = require("@birdybeep/cursor");
+var import_opencode4 = require("@birdybeep/opencode");
+
+// src/commands/test.ts
+var import_node_crypto2 = require("crypto");
+var import_agent_core8 = require("@birdybeep/agent-core");
+function buildTestEvent(opts = {}) {
+  const machine = (0, import_agent_core8.getMachineIdentity)();
+  return (0, import_agent_core8.normalizeEvent)(
+    {
+      event_type: "test",
+      status: "running",
+      harness: "claude_code",
+      // schema requires a harness; the "test" type distinguishes it
+      // Unique per run: a repeat `birdybeep test` inside the backend's dedupe window must
+      // still beep — a constant id made the second test silently "deduped" (9fh).
+      source_session_id: `birdybeep-cli-test-${(0, import_node_crypto2.randomUUID)()}`,
+      machine: { label: machine.label, os: machine.os },
+      workspace: { cwd: process.cwd() },
+      title: "BirdyBeep test event",
+      body: "If you can see this, your machine is wired up correctly.",
+      metadata: { test: true }
+    },
+    opts
+  );
+}
+function createTestCommand(deps = {}) {
+  const makeSender = deps.createSender ?? ((baseUrl) => (0, import_agent_core8.createSender)(
+    deps.tokenOptions ? { baseUrl, tokenOptions: deps.tokenOptions } : { baseUrl }
+  ));
+  return {
+    name: "test",
+    summary: "Send a test event end-to-end",
+    usage: "birdybeep test [--json]",
+    run: async (ctx) => {
+      const event = buildTestEvent();
+      const result = await makeSender(resolveApiUrl()).send(event);
+      if (ctx.flags.json) {
+        ctx.io.result({
+          outcome: result.outcome,
+          ...result.status ? { status: result.status } : {},
+          ...result.decision ? { decision: result.decision } : {}
+        });
+      } else if (result.outcome === "delivered") {
+        if (result.decision === "notified" || result.decision === void 0) {
+          ctx.io.line("\u2713 Test event delivered \u2014 check your phone for a test Beep.");
+        } else if (result.decision === "suppressed") {
+          ctx.io.line(
+            "\u26A0 The backend accepted the test event but suppressed the push \u2014 this machine or integration is probably muted. Check mutes in the app, or run `birdybeep doctor`."
+          );
+        } else if (result.decision === "deduped") {
+          ctx.io.line(
+            "\u26A0 The backend accepted the test event but folded it into a recent duplicate \u2014 wait ~30s and run `birdybeep test` again."
+          );
+        } else {
+          ctx.io.line(
+            `\u26A0 The backend accepted the test event but decided "${result.decision}" \u2014 no push was sent. Run \`birdybeep doctor\`.`
+          );
+        }
+      } else if (result.outcome === "unpaired") {
+        ctx.io.line(
+          "\u2717 NOT PAIRED \u2014 this machine has no BirdyBeep machine token, so nothing was sent (and nothing was queued). Run `birdybeep pair`."
+        );
+      } else if (result.outcome === "queued") {
+        ctx.io.line("\u2022 Offline \u2014 test event queued; it will deliver when you reconnect.");
+      } else {
+        ctx.io.line("\u2717 Test event was rejected by the backend. Run `birdybeep doctor`.");
+      }
+      return result.outcome === "dropped" || result.outcome === "unpaired" ? EXIT.ERROR : EXIT.OK;
+    }
+  };
+}
+
+// src/commands/setup.ts
+var SETUP_ADAPTERS = [
+  import_claude_code5.claudeCodeAdapter,
+  import_codex4.codexAdapter,
+  import_opencode4.opencodeAdapter,
+  import_cursor5.cursorAdapter,
+  import_copilot4.copilotAdapter
+];
+function failedSetupReport(error) {
+  return {
+    harnesses: [],
+    counts: { installed: 0, needsYou: 0, notInstalled: 0, failed: 0 },
+    error,
+    ok: false
+  };
+}
+var PENDING_STATUSES = /* @__PURE__ */ new Set([
+  "needs_trust",
+  "needs_restart"
+]);
+async function installDetected(adapters) {
+  const installs = [];
+  for (const adapter of adapters) {
+    try {
+      const detection = await adapter.detect();
+      if (!detection.detected) {
+        installs.push({ adapter, detected: false });
+        continue;
+      }
+      installs.push({ adapter, detected: true, result: await adapter.install() });
+    } catch (err) {
+      installs.push({
+        adapter,
+        detected: true,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return installs;
+}
+function rowState(state, group, status) {
+  if (status === "error" || group.status === "error") return "failed";
+  if (status !== void 0 && PENDING_STATUSES.has(status)) return "needs you";
+  if (state.coverage === "active") return "beeping";
+  if (state.coverage === "wired") return "ready";
+  return "not covered";
+}
+function buildHarnessReports(installs, groups) {
+  return installs.map((install) => {
+    const { adapter } = install;
+    const base4 = {
+      harness: adapter.id,
+      displayName: adapter.displayName,
+      detected: install.detected,
+      ...install.result !== void 0 ? {
+        status: install.result.status,
+        changedFiles: install.result.changedFiles,
+        backupFiles: install.result.backupFiles
+      } : {},
+      ...install.error !== void 0 ? { error: install.error } : {}
+    };
+    if (install.error !== void 0) {
+      return {
+        ...base4,
+        actions: [
+          `${adapter.displayName} could not be set up: ${install.error}`,
+          `Run \`birdybeep agent install ${installTarget2(adapter.id)}\` to retry it on its own.`
+        ],
+        rows: [{ harness: adapter.id, displayName: adapter.displayName, state: "failed" }]
+      };
+    }
+    if (!install.detected) {
+      return {
+        ...base4,
+        actions: [],
+        rows: [
+          {
+            harness: adapter.id,
+            displayName: adapter.displayName,
+            state: "not installed"
+          }
+        ]
+      };
+    }
+    const group = groups.find((g) => g.harness === adapter.id);
+    const status = install.result?.status;
+    const surfaces = group?.surfaces ?? [];
+    const rows = group === void 0 || surfaces.length === 0 ? [
+      {
+        harness: adapter.id,
+        displayName: adapter.displayName,
+        state: status !== void 0 && PENDING_STATUSES.has(status) ? "needs you" : "ready"
+      }
+    ] : surfaces.map((state) => {
+      const graded = rowState(state, group, status);
+      const remedy = surfaceRemedy(state, group) ?? (graded === "not covered" ? `${adapter.displayName} carries no BirdyBeep hooks \u2014 re-run \`birdybeep agent install ${installTarget2(adapter.id)}\` from a shell where \`birdybeep\` resolves.` : void 0);
+      return {
+        harness: adapter.id,
+        displayName: adapter.displayName,
+        build: describeSurface(state),
+        kind: state.surface.kind,
+        state: graded,
+        ...remedy !== void 0 ? { remedy } : {}
+      };
+    });
+    return { ...base4, actions: [...install.result?.requiredActions ?? []], rows };
+  });
+}
+function pad(text, width) {
+  return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+var MARKS = {
+  beeping: "\u2713",
+  ready: "\u2713",
+  "needs you": "!",
+  "not covered": "\u2717",
+  "not installed": "\u2013",
+  failed: "\u2717"
+};
+function renderCoverageTable(reports) {
+  const rows = reports.flatMap((r) => r.rows);
+  const nameWidth = Math.max(7, ...rows.map((r) => r.displayName.length));
+  const buildWidth = Math.max(5, ...rows.map((r) => (r.build ?? "\u2014").length));
+  const lines = ["coverage", `   ${pad("harness", nameWidth)}  ${pad("build", buildWidth)}  state`];
+  for (const report of reports) {
+    for (const row of report.rows) {
+      lines.push(
+        `${MARKS[row.state]}  ${pad(row.displayName, nameWidth)}  ${pad(row.build ?? "\u2014", buildWidth)}  ${row.state}`
+      );
+      if (row.remedy !== void 0) lines.push(`     \u2192 ${row.remedy}`);
+    }
+    for (const action of report.actions) lines.push(`     \u2192 ${action}`);
+  }
+  return lines;
+}
+function describeMissing(reports) {
+  const missing = reports.filter((r) => !r.detected && r.error === void 0);
+  if (missing.length === 0) return [];
+  const names = missing.map((r) => r.displayName);
+  if (missing.length === reports.length) {
+    return [
+      "No supported coding agent is installed on this machine, so there was nothing to wire up.",
+      `Install one of ${names.join(", ")}, then run \`birdybeep setup\` again \u2014 pairing is already done, so it picks up from here.`
+    ];
+  }
+  return [
+    `Not installed: ${names.join(", ")}. Install any of them, then run \`birdybeep setup\` again to wire it up.`
+  ];
+}
+async function runHarnessSetup(ctx, options, deps = {}) {
+  const adapters = deps.adapters ?? [...SETUP_ADAPTERS];
+  const installs = await installDetected(adapters);
+  const groups = await gatherSurfaces(adapters, deps.surfaceOptions ?? {});
+  const reports = buildHarnessReports(installs, groups);
+  ctx.io.line("");
+  for (const line of renderCoverageTable(reports)) ctx.io.line(line);
+  const missing = describeMissing(reports);
+  if (missing.length > 0) {
+    ctx.io.line("");
+    for (const line of missing) ctx.io.line(line);
+  }
+  const counts = {
+    installed: reports.filter((r) => r.detected && r.error === void 0).length,
+    needsYou: reports.filter((r) => r.rows.some((row) => row.state === "needs you")).length,
+    notInstalled: reports.filter((r) => !r.detected && r.error === void 0).length,
+    // A row that graded `failed` counts too: an adapter that returned status "error" never threw,
+    // so counting only thrown errors would report a clean run over a harness that is broken.
+    failed: reports.filter((r) => r.error !== void 0 || r.rows.some((x) => x.state === "failed")).length
+  };
+  let beep;
+  let beepOk = true;
+  if (options.sendTest) {
+    ctx.io.line("");
+    const command = createTestCommand({
+      ...deps.createSender !== void 0 ? { createSender: deps.createSender } : {},
+      ...deps.tokenOptions !== void 0 ? { tokenOptions: deps.tokenOptions } : {}
+    });
+    const beepIo = {
+      ...ctx.io,
+      result: (value) => {
+        beep = value;
+      }
+    };
+    beepOk = await command.run?.({ args: [], flags: ctx.flags, io: beepIo }) === 0;
+  }
+  return {
+    harnesses: reports,
+    counts,
+    ...beep !== void 0 ? { beep } : {},
+    ok: counts.failed === 0 && beepOk
+  };
+}
 
 // src/commands/pair.ts
 var DEFAULT_POLL_INTERVAL_MS = 2e3;
@@ -861,11 +1421,15 @@ function renderQrMatrix(qrPayload) {
   return (0, import_uqr.renderUnicodeCompact)(qrPayload, { border: 2 });
 }
 function parsePairFlags(args) {
-  const flags = { yes: false };
+  const flags = { yes: false, noInstall: false, noTest: false };
   for (let i = 0; i < args.length; i += 1) {
     const token = args[i] ?? "";
     if (token === "--yes" || token === "-y") {
       flags.yes = true;
+    } else if (token === "--no-install") {
+      flags.noInstall = true;
+    } else if (token === "--no-test") {
+      flags.noTest = true;
     } else if (token === "--expect-email" || token.startsWith("--expect-email=")) {
       const inline = token.startsWith("--expect-email=") ? token.slice("--expect-email=".length) : void 0;
       const value = inline ?? args[++i];
@@ -932,14 +1496,14 @@ function canOpenControllingTerminal(path = controllingTerminalPath(), platform =
   if (platform === "win32") return false;
   let fd;
   try {
-    fd = (0, import_node_fs4.openSync)(path, "r");
+    fd = (0, import_node_fs5.openSync)(path, "r");
     return true;
   } catch {
     return false;
   } finally {
     if (fd !== void 0) {
       try {
-        (0, import_node_fs4.closeSync)(fd);
+        (0, import_node_fs5.closeSync)(fd);
       } catch {
       }
     }
@@ -953,7 +1517,7 @@ async function promptForAnswer(question, on) {
     input = process.stdin;
   } else {
     const { ReadStream } = await import("tty");
-    ttyFd = (0, import_node_fs4.openSync)(controllingTerminalPath(), "r");
+    ttyFd = (0, import_node_fs5.openSync)(controllingTerminalPath(), "r");
     input = new ReadStream(ttyFd);
   }
   return new Promise((resolve) => {
@@ -973,7 +1537,7 @@ async function promptForAnswer(question, on) {
         }
         if (ttyFd !== void 0) {
           try {
-            (0, import_node_fs4.closeSync)(ttyFd);
+            (0, import_node_fs5.closeSync)(ttyFd);
           } catch {
           }
         }
@@ -985,7 +1549,18 @@ async function promptForAnswer(question, on) {
     input.once?.("error", () => done(""));
   });
 }
-function createPairCommand(deps = {}) {
+async function runSetupChain(ctx, deps, flags) {
+  try {
+    return await runHarnessSetup(ctx, { sendTest: !flags.noTest }, deps);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    ctx.io.errline(
+      `This machine is paired, but wiring up your coding agents failed: ${message}. Run \`birdybeep agent install all\` to do it on its own, then \`birdybeep doctor\`.`
+    );
+    return failedSetupReport(message);
+  }
+}
+function createPairingCommand(verb, deps = {}) {
   const fetchImpl = deps.fetchImpl ?? fetch;
   const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const clock = deps.now ?? (() => Date.now());
@@ -998,9 +1573,10 @@ function createPairCommand(deps = {}) {
     return typeof pinned === "string" && pinned.trim().length > 0 ? pinned : void 0;
   });
   return {
-    name: "pair",
-    summary: "Pair this machine with your BirdyBeep account (QR or manual)",
-    usage: "birdybeep pair [--yes] [--expect-email <addr>] [--json]",
+    name: verb.name,
+    summary: verb.summary,
+    usage: verb.usage,
+    ...verb.gettingStarted !== void 0 ? { gettingStarted: verb.gettingStarted } : {},
     options: [
       {
         flag: "--yes",
@@ -1011,18 +1587,43 @@ function createPairCommand(deps = {}) {
         flag: "--expect-email",
         value: "<addr>",
         summary: "Only trust the pairing if this account approved it (else fail)"
+      },
+      {
+        flag: "--no-install",
+        summary: "Stop after pairing \u2014 don't detect or wire up any coding agent"
+      },
+      {
+        flag: "--no-test",
+        summary: "Don't send the test Beep at the end"
       }
     ],
     run: async (ctx) => {
       const pairFlags = parsePairFlags(ctx.args);
       if (pairFlags.error !== void 0) {
-        ctx.io.errline(`birdybeep pair: ${pairFlags.error}.`);
+        ctx.io.errline(`birdybeep ${verb.name}: ${pairFlags.error}.`);
         return EXIT.USAGE;
       }
+      const chain = deps.setup === false || pairFlags.noInstall ? void 0 : deps.setup ?? {};
+      const setupDeps = {
+        ...deps.tokenOptions !== void 0 ? { tokenOptions: deps.tokenOptions } : {},
+        ...chain
+      };
+      if (verb.skipWhenPaired && await (0, import_agent_core9.getToken)(deps.tokenOptions ?? {}) !== null) {
+        ctx.io.line(
+          chain !== void 0 ? "\u2713 Already paired \u2014 checking which coding agents are wired up." : "\u2713 Already paired. Nothing else to do with --no-install."
+        );
+        const report2 = chain !== void 0 ? await runSetupChain(ctx, setupDeps, pairFlags) : void 0;
+        ctx.io.result({
+          paired: true,
+          alreadyPaired: true,
+          ...report2 !== void 0 ? { setup: report2 } : {}
+        });
+        return report2 !== void 0 && !report2.ok ? EXIT.ERROR : EXIT.OK;
+      }
       const apiUrl = resolveApiUrl();
-      const identity = (0, import_agent_core8.getMachineIdentity)();
-      const codeVerifier = (0, import_agent_core8.generateCodeVerifier)();
-      const codeChallenge = (0, import_agent_core8.deriveCodeChallengeS256)(codeVerifier);
+      const identity = (0, import_agent_core9.getMachineIdentity)();
+      const codeVerifier = (0, import_agent_core9.generateCodeVerifier)();
+      const codeChallenge = (0, import_agent_core9.deriveCodeChallengeS256)(codeVerifier);
       const start = await pairStart(
         apiUrl,
         { machineLabel: identity.label, os: identity.os, cliVersion: CLI_VERSION, codeChallenge },
@@ -1118,21 +1719,52 @@ function createPairCommand(deps = {}) {
         );
         return EXIT.ERROR;
       }
-      await (0, import_agent_core8.setToken)(paired.machineToken, deps.tokenOptions ?? {});
+      await (0, import_agent_core9.setToken)(paired.machineToken, deps.tokenOptions ?? {});
       writeCliConfig({ apiUrl });
+      const discarded = new import_agent_core9.LocalEventQueue().discardBefore(clock());
+      (0, import_agent_core9.clearUnpairedNotice)();
       const humanSuffix = approvedBy !== void 0 ? ` to ${approvedBy}` : "";
-      ctx.io.emit(`\u2713 Paired${humanSuffix}. Run \`birdybeep test\` to send a test Beep.`, {
+      const discardedSuffix = discarded > 0 ? ` Discarded ${discarded} event(s) queued before pairing \u2014 you won't be beeped about them.` : "";
+      const nextStep = chain === void 0 ? " Run `birdybeep setup` to wire up your coding agents." : "";
+      ctx.io.line(`\u2713 Paired${humanSuffix}.${nextStep}${discardedSuffix}`);
+      const report = chain !== void 0 ? await runSetupChain(ctx, setupDeps, pairFlags) : void 0;
+      ctx.io.result({
         paired: true,
         machineId: paired.machineId,
-        ...approvedBy !== void 0 ? { approvedByEmail: approvedBy } : {}
+        discardedPrePairingEvents: discarded,
+        ...approvedBy !== void 0 ? { approvedByEmail: approvedBy } : {},
+        ...report !== void 0 ? { setup: report } : {}
       });
-      return EXIT.OK;
+      return report !== void 0 && !report.ok ? EXIT.ERROR : EXIT.OK;
     }
   };
 }
+function createPairCommand(deps = {}) {
+  return createPairingCommand(
+    {
+      name: "pair",
+      summary: "Pair this machine and wire up every coding agent on it",
+      usage: "birdybeep pair [--yes] [--expect-email <addr>] [--no-install] [--no-test] [--json]",
+      skipWhenPaired: false
+    },
+    deps
+  );
+}
+function createSetupCommand(deps = {}) {
+  return createPairingCommand(
+    {
+      name: "setup",
+      summary: "Set up BirdyBeep here: pair, wire up every coding agent, test",
+      usage: "birdybeep setup [--yes] [--expect-email <addr>] [--no-install] [--no-test] [--json]",
+      gettingStarted: "Pair this machine, wire up every coding agent it finds, and send a test Beep.",
+      skipWhenPaired: true
+    },
+    deps
+  );
+}
 
 // src/commands/queue.ts
-var import_agent_core9 = require("@birdybeep/agent-core");
+var import_agent_core10 = require("@birdybeep/agent-core");
 function createQueueCommand() {
   return {
     name: "queue",
@@ -1144,7 +1776,7 @@ function createQueueCommand() {
         summary: "Clear the local offline event queue (debug)",
         usage: "birdybeep queue clear",
         run: (ctx) => {
-          const cleared = new import_agent_core9.LocalEventQueue().clear();
+          const cleared = new import_agent_core10.LocalEventQueue().clear();
           ctx.io.emit(`Cleared ${cleared} queued event(s).`, { cleared });
           return EXIT.OK;
         }
@@ -1154,25 +1786,25 @@ function createQueueCommand() {
 }
 
 // src/commands/report-status.ts
-var import_agent_core10 = require("@birdybeep/agent-core");
-var import_claude_code4 = require("@birdybeep/claude-code");
-var import_codex4 = require("@birdybeep/codex");
-var import_copilot4 = require("@birdybeep/copilot");
-var import_cursor4 = require("@birdybeep/cursor");
-var import_opencode4 = require("@birdybeep/opencode");
+var import_agent_core11 = require("@birdybeep/agent-core");
+var import_claude_code6 = require("@birdybeep/claude-code");
+var import_codex5 = require("@birdybeep/codex");
+var import_copilot5 = require("@birdybeep/copilot");
+var import_cursor6 = require("@birdybeep/cursor");
+var import_opencode5 = require("@birdybeep/opencode");
 var DEFAULT_ADAPTERS3 = [
-  import_claude_code4.claudeCodeAdapter,
-  import_codex4.codexAdapter,
-  import_opencode4.opencodeAdapter,
-  import_cursor4.cursorAdapter,
-  import_copilot4.copilotAdapter
+  import_claude_code6.claudeCodeAdapter,
+  import_codex5.codexAdapter,
+  import_opencode5.opencodeAdapter,
+  import_cursor6.cursorAdapter,
+  import_copilot5.copilotAdapter
 ];
 var ADAPTER_VERSIONS = {
-  claude_code: import_claude_code4.CLAUDE_CODE_ADAPTER_VERSION,
-  codex: import_codex4.CODEX_ADAPTER_VERSION,
-  opencode: import_opencode4.OPENCODE_ADAPTER_VERSION,
-  cursor: import_cursor4.CURSOR_ADAPTER_VERSION,
-  copilot: import_copilot4.COPILOT_ADAPTER_VERSION
+  claude_code: import_claude_code6.CLAUDE_CODE_ADAPTER_VERSION,
+  codex: import_codex5.CODEX_ADAPTER_VERSION,
+  opencode: import_opencode5.OPENCODE_ADAPTER_VERSION,
+  cursor: import_cursor6.CURSOR_ADAPTER_VERSION,
+  copilot: import_copilot5.COPILOT_ADAPTER_VERSION
 };
 var base3 = (apiUrl) => apiUrl.replace(/\/$/, "");
 async function gatherItems(adapters) {
@@ -1195,7 +1827,7 @@ function createReportStatusCommand(deps = {}) {
     summary: "Internal: report integration status to the backend",
     usage: "birdybeep report-status [--json]",
     run: async (ctx) => {
-      const token = await (0, import_agent_core10.getToken)(deps.tokenOptions ?? {});
+      const token = await (0, import_agent_core11.getToken)(deps.tokenOptions ?? {});
       if (token === null) {
         ctx.io.errline("No machine token \u2014 run `birdybeep pair` first.");
         return EXIT.ERROR;
@@ -1216,7 +1848,7 @@ function createReportStatusCommand(deps = {}) {
         });
         if (res.ok) {
           outcome = "reported";
-          const parsed = import_agent_core10.integrationStatusResponseSchema.safeParse(
+          const parsed = import_agent_core11.integrationStatusResponseSchema.safeParse(
             await res.json().catch(() => void 0)
           );
           if (parsed.success) {
@@ -1226,7 +1858,7 @@ function createReportStatusCommand(deps = {}) {
             }));
           }
         } else {
-          const env = import_agent_core10.errorEnvelopeSchema.safeParse(await res.json().catch(() => void 0));
+          const env = import_agent_core11.errorEnvelopeSchema.safeParse(await res.json().catch(() => void 0));
           errorCode = env.success ? env.data.error.code : void 0;
           const terminal = errorCode !== void 0 ? errorCode === "unauthorized" || errorCode === "forbidden" || errorCode === "token_revoked" : res.status === 401 || res.status === 403;
           outcome = terminal ? "terminal" : "deferred";
@@ -1257,22 +1889,22 @@ function createReportStatusCommand(deps = {}) {
 }
 
 // src/commands/status.ts
-var import_agent_core11 = require("@birdybeep/agent-core");
-var import_claude_code5 = require("@birdybeep/claude-code");
-var import_codex5 = require("@birdybeep/codex");
-var import_copilot5 = require("@birdybeep/copilot");
-var import_cursor5 = require("@birdybeep/cursor");
-var import_opencode5 = require("@birdybeep/opencode");
+var import_agent_core12 = require("@birdybeep/agent-core");
+var import_claude_code7 = require("@birdybeep/claude-code");
+var import_codex6 = require("@birdybeep/codex");
+var import_copilot6 = require("@birdybeep/copilot");
+var import_cursor7 = require("@birdybeep/cursor");
+var import_opencode6 = require("@birdybeep/opencode");
 var DEFAULT_ADAPTERS4 = [
-  import_claude_code5.claudeCodeAdapter,
-  import_codex5.codexAdapter,
-  import_opencode5.opencodeAdapter,
-  import_cursor5.cursorAdapter,
-  import_copilot5.copilotAdapter
+  import_claude_code7.claudeCodeAdapter,
+  import_codex6.codexAdapter,
+  import_opencode6.opencodeAdapter,
+  import_cursor7.cursorAdapter,
+  import_copilot6.copilotAdapter
 ];
 function createStatusCommand(deps = {}) {
   const adapters = deps.adapters ?? DEFAULT_ADAPTERS4;
-  const makeSender = deps.createSender ?? ((baseUrl) => (0, import_agent_core11.createSender)(
+  const makeSender = deps.createSender ?? ((baseUrl) => (0, import_agent_core12.createSender)(
     deps.tokenOptions ? { baseUrl, tokenOptions: deps.tokenOptions } : { baseUrl }
   ));
   return {
@@ -1283,14 +1915,21 @@ function createStatusCommand(deps = {}) {
       const machine = machineIdentity();
       const paired = await isPaired(deps.tokenOptions ?? {});
       const integrations = await gatherIntegrations(adapters);
+      const surfaces = await gatherSurfaces(adapters, deps.surfaceOptions ?? {});
       const depthBefore = localQueueDepth();
+      const unpaired = unpairedActivity();
+      const filtered = filteredActivity();
       const drain = await makeSender(resolveApiUrl()).drainNow();
       const depthAfter = localQueueDepth();
+      const overflowDropped = localQueueOverflowDrops();
       const report = {
         machine,
         paired,
         integrations,
-        queue: { depthBefore, delivered: drain.delivered, depthAfter }
+        surfaces,
+        queue: { depthBefore, delivered: drain.delivered, depthAfter, overflowDropped },
+        ...unpaired !== null ? { unpairedActivity: unpaired } : {},
+        ...filtered !== null ? { filteredActivity: filtered } : {}
       };
       if (ctx.flags.json) {
         ctx.io.result(report);
@@ -1298,85 +1937,29 @@ function createStatusCommand(deps = {}) {
         ctx.io.line(`Machine: ${machine.label} (${machine.os})`);
         ctx.io.line(paired ? "Paired:  yes" : "Paired:  no \u2014 run `birdybeep pair`");
         ctx.io.line("Integrations:");
-        for (const i of integrations) ctx.io.line(`  ${i.displayName}: ${i.status}`);
+        for (const i of integrations) {
+          ctx.io.line(`  ${i.displayName}: ${i.status}`);
+          const group = surfaces.find((g) => g.harness === i.harness);
+          for (const state of group?.surfaces ?? []) {
+            const mark = state.coverage === "active" ? "\u2713" : state.coverage === "wired" ? "\xB7" : "\u2717";
+            ctx.io.line(`    ${mark} ${describeSurface(state)} \u2014 ${state.coverage}`);
+          }
+        }
         ctx.io.line(
-          `Queue:   ${depthBefore} queued \u2192 ${drain.delivered} delivered, ${depthAfter} remaining`
+          `Queue:   ${depthBefore} queued \u2192 ${drain.delivered} delivered, ${depthAfter} remaining` + (overflowDropped > 0 ? `, ${overflowDropped} dropped by the queue cap` : "")
         );
+        if (unpaired !== null) ctx.io.line(`\u26A0 Lost:   ${describeUnpairedActivity(unpaired)}`);
+        if (filtered !== null) ctx.io.line(`Local:   ${describeFilteredActivity(filtered)}`);
       }
       return paired ? EXIT.OK : EXIT.ERROR;
     }
   };
 }
 
-// src/commands/test.ts
-var import_node_crypto2 = require("crypto");
-var import_agent_core12 = require("@birdybeep/agent-core");
-function buildTestEvent(opts = {}) {
-  const machine = (0, import_agent_core12.getMachineIdentity)();
-  return (0, import_agent_core12.normalizeEvent)(
-    {
-      event_type: "test",
-      status: "running",
-      harness: "claude_code",
-      // schema requires a harness; the "test" type distinguishes it
-      // Unique per run: a repeat `birdybeep test` inside the backend's dedupe window must
-      // still beep — a constant id made the second test silently "deduped" (9fh).
-      source_session_id: `birdybeep-cli-test-${(0, import_node_crypto2.randomUUID)()}`,
-      machine: { label: machine.label, os: machine.os },
-      workspace: { cwd: process.cwd() },
-      title: "BirdyBeep test event",
-      body: "If you can see this, your machine is wired up correctly.",
-      metadata: { test: true }
-    },
-    opts
-  );
-}
-function createTestCommand(deps = {}) {
-  const makeSender = deps.createSender ?? ((baseUrl) => (0, import_agent_core12.createSender)(
-    deps.tokenOptions ? { baseUrl, tokenOptions: deps.tokenOptions } : { baseUrl }
-  ));
-  return {
-    name: "test",
-    summary: "Send a test event end-to-end",
-    usage: "birdybeep test [--json]",
-    run: async (ctx) => {
-      const event = buildTestEvent();
-      const result = await makeSender(resolveApiUrl()).send(event);
-      if (ctx.flags.json) {
-        ctx.io.result({
-          outcome: result.outcome,
-          ...result.status ? { status: result.status } : {},
-          ...result.decision ? { decision: result.decision } : {}
-        });
-      } else if (result.outcome === "delivered") {
-        if (result.decision === "notified" || result.decision === void 0) {
-          ctx.io.line("\u2713 Test event delivered \u2014 check your phone for a test Beep.");
-        } else if (result.decision === "suppressed") {
-          ctx.io.line(
-            "\u26A0 The backend accepted the test event but suppressed the push \u2014 this machine or integration is probably muted. Check mutes in the app, or run `birdybeep doctor`."
-          );
-        } else if (result.decision === "deduped") {
-          ctx.io.line(
-            "\u26A0 The backend accepted the test event but folded it into a recent duplicate \u2014 wait ~30s and run `birdybeep test` again."
-          );
-        } else {
-          ctx.io.line(
-            `\u26A0 The backend accepted the test event but decided "${result.decision}" \u2014 no push was sent. Run \`birdybeep doctor\`.`
-          );
-        }
-      } else if (result.outcome === "queued") {
-        ctx.io.line("\u2022 Offline \u2014 test event queued; it will deliver when you reconnect.");
-      } else {
-        ctx.io.line("\u2717 Test event was rejected by the backend. Run `birdybeep doctor`.");
-      }
-      return result.outcome === "dropped" ? EXIT.ERROR : EXIT.OK;
-    }
-  };
-}
-
 // src/commands.ts
 function buildCommands() {
   return [
+    createSetupCommand(),
     createPairCommand(),
     createLogoutCommand(),
     createUnpairCommand(),
@@ -1391,7 +1974,7 @@ function buildCommands() {
 }
 
 // src/update-check.ts
-var import_node_fs5 = require("fs");
+var import_node_fs6 = require("fs");
 var import_node_path3 = require("path");
 var import_agent_core13 = require("@birdybeep/agent-core");
 var PACKAGE_NAME = "@birdybeep/cli";
@@ -1451,7 +2034,7 @@ function updateCachePath() {
 }
 function readUpdateCache() {
   try {
-    const parsed = JSON.parse((0, import_node_fs5.readFileSync)(updateCachePath(), "utf8"));
+    const parsed = JSON.parse((0, import_node_fs6.readFileSync)(updateCachePath(), "utf8"));
     if (typeof parsed !== "object" || parsed === null) return null;
     const { checkedAt, latest } = parsed;
     if (typeof checkedAt !== "number") return null;
@@ -1462,8 +2045,8 @@ function readUpdateCache() {
   }
 }
 function writeUpdateCache(cache) {
-  (0, import_node_fs5.mkdirSync)((0, import_agent_core13.birdyBeepConfigDir)(), { recursive: true, mode: 448 });
-  (0, import_node_fs5.writeFileSync)(updateCachePath(), `${JSON.stringify(cache)}
+  (0, import_node_fs6.mkdirSync)((0, import_agent_core13.birdyBeepConfigDir)(), { recursive: true, mode: 448 });
+  (0, import_node_fs6.writeFileSync)(updateCachePath(), `${JSON.stringify(cache)}
 `, { mode: 384 });
 }
 async function fetchLatestVersion(registryUrl, fetchImpl, timeoutMs) {