@birdybeep/cli 0.3.0 → 0.6.0

package/dist/{chunk-U4EIHC5C.js → chunk-BY5MNQE3.js}

@@ -78,11 +78,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,
@@ -164,7 +170,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;
   }
@@ -217,7 +227,7 @@ async function dispatch(argv, deps) {
 }
 
 // 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/agent.ts
 import { claudeCodeAdapter } from "@birdybeep/claude-code";
@@ -225,6 +235,200 @@ import { codexAdapter } from "@birdybeep/codex";
 import { copilotAdapter } from "@birdybeep/copilot";
 import { cursorAdapter } from "@birdybeep/cursor";
 import { opencodeAdapter } from "@birdybeep/opencode";
+
+// src/diagnostics.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import {
+  getMachineIdentity,
+  getToken,
+  LocalEventQueue,
+  readFilteredActivity,
+  readObservedBuilds,
+  readUnpairedNotice
+} from "@birdybeep/agent-core";
+import {
+  BIRDYBEEP_HOOK_EVENTS as CLAUDE_HOOK_EVENTS,
+  claudeSettingsPath,
+  isBirdyBeepEntry as isClaudeEntry
+} from "@birdybeep/claude-code";
+import {
+  BIRDYBEEP_HOOK_EVENTS as CURSOR_HOOK_EVENTS,
+  cursorHooksPath,
+  detectCursor,
+  isBirdyBeepEntry as isCursorEntry
+} from "@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 getToken(tokenOptions) !== null;
+}
+function localQueueDepth() {
+  return new LocalEventQueue().size();
+}
+function localQueueOverflowDrops() {
+  return new LocalEventQueue().overflowDropCount();
+}
+function unpairedActivity() {
+  return 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 (!existsSync(path)) return 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(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 ?? homedir();
+  const detection = await (opts.detect ?? (() => detectCursor({ home })))();
+  if (!detection.detected) return false;
+  const claude = birdyBeepHookCount(claudeSettingsPath(home), CLAUDE_HOOK_EVENTS, isClaudeEntry);
+  if (claude === null || claude === 0) return false;
+  return birdyBeepHookCount(cursorHooksPath(home), CURSOR_HOOK_EVENTS, isCursorEntry) === 0;
+}
+function filteredActivity() {
+  return 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 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 = 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/commands/agent.ts
 var DEFAULT_ADAPTERS = [
   claudeCodeAdapter,
   codexAdapter,
@@ -253,7 +457,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") {
@@ -280,8 +487,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)) {
@@ -289,13 +497,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) {
@@ -334,6 +549,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",
@@ -343,7 +559,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",
@@ -357,7 +573,8 @@ function createAgentCommand(deps = {}) {
 
 // src/commands/doctor.ts
 import {
-  createSender as defaultCreateSender
+  createSender as defaultCreateSender,
+  DEFAULT_QUEUE_MAX_ENTRIES as QUEUE_CAP
 } from "@birdybeep/agent-core";
 import { claudeCodeAdapter as claudeCodeAdapter2 } from "@birdybeep/claude-code";
 import { codexAdapter as codexAdapter2 } from "@birdybeep/codex";
@@ -366,7 +583,7 @@ import { cursorAdapter as cursorAdapter2 } from "@birdybeep/cursor";
 import { opencodeAdapter as opencodeAdapter2 } from "@birdybeep/opencode";
 
 // src/config.ts
-import { mkdirSync as mkdirSync2, readFileSync, writeFileSync } from "fs";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { join } from "path";
 import { birdyBeepConfigDir as birdyBeepConfigDir2 } from "@birdybeep/agent-core";
 var DEFAULT_API_URL = "https://api.birdybeep.com";
@@ -376,7 +593,7 @@ function cliConfigPath() {
 }
 function readCliConfig() {
   try {
-    const parsed = JSON.parse(readFileSync(cliConfigPath(), "utf8"));
+    const parsed = JSON.parse(readFileSync2(cliConfigPath(), "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : {};
   } catch {
     return {};
@@ -405,31 +622,6 @@ function resolveRegistryUrl() {
   return DEFAULT_REGISTRY_URL;
 }
 
-// src/diagnostics.ts
-import {
-  getMachineIdentity,
-  getToken,
-  LocalEventQueue
-} from "@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 getToken(tokenOptions) !== null;
-}
-function localQueueDepth() {
-  return new LocalEventQueue().size();
-}
-function machineIdentity() {
-  return getMachineIdentity();
-}
-
 // src/commands/doctor.ts
 var DEFAULT_ADAPTERS2 = [
   claudeCodeAdapter2,
@@ -472,6 +664,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) {
@@ -482,14 +700,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 ${QUEUE_CAP} entry cap` : "")
       });
       const reachable = await probeNetwork(apiUrl);
       checks.push(
@@ -505,7 +735,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) {
@@ -529,14 +762,15 @@ import {
   createSender as defaultCreateSender2,
   resolveOnPath
 } from "@birdybeep/agent-core";
-import { runClaudeHook } from "@birdybeep/claude-code";
-import { runCodexHook } from "@birdybeep/codex";
+import { isClaudeCodeHookPayload, runClaudeHook } from "@birdybeep/claude-code";
+import { isCodexHookPayload, runCodexHook } from "@birdybeep/codex";
 import {
   isCopilotHookEventName,
+  isCopilotHookPayload,
   runCopilotHook
 } from "@birdybeep/copilot";
-import { runCursorHook } from "@birdybeep/cursor";
-import { runOpenCodeHook } from "@birdybeep/opencode";
+import { isCursorHookEventName, isCursorHookPayload, runCursorHook } from "@birdybeep/cursor";
+import { isOpenCodeEventPayload, runOpenCodeHook } from "@birdybeep/opencode";
 var RUNNERS = {
   claude: runClaudeHook,
   codex: runCodexHook,
@@ -568,12 +802,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" && isCursorHookPayload(payload) ? "cursor" : harness;
+}
+function recognizesPayload(harness, payload) {
+  switch (harness) {
+    case "claude":
+      return isClaudeCodeHookPayload(payload);
+    case "cursor":
+      return isCursorHookEventName(asRecord2(payload)["hook_event_name"]);
+    case "codex":
+      return isCodexHookPayload(payload);
+    case "opencode":
+      return isOpenCodeEventPayload(payload);
+    case "copilot":
+      return 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 runCopilotHook(copilotEventName, payload, { sender });
   }
-  return RUNNERS[harness](payload, { sender });
+  return RUNNERS[handler](payload, { sender });
 }
 function readStdinDefault() {
   return new Promise((resolve) => {
@@ -660,10 +925,16 @@ function createHookCommand(deps = {}) {
         return EXIT.OK;
       }
       const copilotEventName = harness === "copilot" && 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 && dirname(notifyStdinFile) === tmpdir() && basename(notifyStdinFile).startsWith("birdybeep-notify-")) {
@@ -672,23 +943,58 @@ function createHookCommand(deps = {}) {
         } 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;
     }
   };
@@ -748,9 +1054,12 @@ function createUnpairCommand(deps = {}) {
 // src/commands/pair.ts
 import { closeSync as closeSync2, openSync as openSync2 } from "fs";
 import {
+  clearUnpairedNotice,
   deriveCodeChallengeS256,
   generateCodeVerifier,
-  getMachineIdentity as getMachineIdentity2,
+  getMachineIdentity as getMachineIdentity3,
+  getToken as getToken3,
+  LocalEventQueue as LocalEventQueue2,
   setToken
 } from "@birdybeep/agent-core";
 import { renderUnicodeCompact } from "uqr";
@@ -829,6 +1138,280 @@ async function pairTokenPoll(apiUrl, deviceCode, fetchImpl, machineFingerprint,
   return { status: "error", code: code ?? "unknown", message, retryable: true };
 }
 
+// src/commands/setup.ts
+import { claudeCodeAdapter as claudeCodeAdapter3 } from "@birdybeep/claude-code";
+import { codexAdapter as codexAdapter3 } from "@birdybeep/codex";
+import { copilotAdapter as copilotAdapter3 } from "@birdybeep/copilot";
+import { cursorAdapter as cursorAdapter3 } from "@birdybeep/cursor";
+import { opencodeAdapter as opencodeAdapter3 } from "@birdybeep/opencode";
+
+// src/commands/test.ts
+import { randomUUID } from "crypto";
+import {
+  createSender as defaultCreateSender3,
+  getMachineIdentity as getMachineIdentity2,
+  normalizeEvent
+} from "@birdybeep/agent-core";
+function buildTestEvent(opts = {}) {
+  const machine = getMachineIdentity2();
+  return 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-${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) => defaultCreateSender3(
+    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 = [
+  claudeCodeAdapter3,
+  codexAdapter3,
+  opencodeAdapter3,
+  cursorAdapter3,
+  copilotAdapter3
+];
+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;
 var HEARTBEAT_MS = 15e3;
@@ -836,11 +1419,15 @@ function renderQrMatrix(qrPayload) {
   return 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];
@@ -960,7 +1547,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());
@@ -973,9 +1571,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",
@@ -986,16 +1585,41 @@ 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 getToken3(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 = getMachineIdentity2();
+      const identity = getMachineIdentity3();
       const codeVerifier = generateCodeVerifier();
       const codeChallenge = deriveCodeChallengeS256(codeVerifier);
       const start = await pairStart(
@@ -1095,19 +1719,50 @@ function createPairCommand(deps = {}) {
       }
       await setToken(paired.machineToken, deps.tokenOptions ?? {});
       writeCliConfig({ apiUrl });
+      const discarded = new LocalEventQueue2().discardBefore(clock());
+      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
-import { LocalEventQueue as LocalEventQueue2 } from "@birdybeep/agent-core";
+import { LocalEventQueue as LocalEventQueue3 } from "@birdybeep/agent-core";
 function createQueueCommand() {
   return {
     name: "queue",
@@ -1119,7 +1774,7 @@ function createQueueCommand() {
         summary: "Clear the local offline event queue (debug)",
         usage: "birdybeep queue clear",
         run: (ctx) => {
-          const cleared = new LocalEventQueue2().clear();
+          const cleared = new LocalEventQueue3().clear();
           ctx.io.emit(`Cleared ${cleared} queued event(s).`, { cleared });
           return EXIT.OK;
         }
@@ -1131,20 +1786,20 @@ function createQueueCommand() {
 // src/commands/report-status.ts
 import {
   errorEnvelopeSchema as errorEnvelopeSchema2,
-  getToken as getToken3,
+  getToken as getToken4,
   integrationStatusResponseSchema
 } from "@birdybeep/agent-core";
-import { CLAUDE_CODE_ADAPTER_VERSION, claudeCodeAdapter as claudeCodeAdapter3 } from "@birdybeep/claude-code";
-import { CODEX_ADAPTER_VERSION, codexAdapter as codexAdapter3 } from "@birdybeep/codex";
-import { COPILOT_ADAPTER_VERSION, copilotAdapter as copilotAdapter3 } from "@birdybeep/copilot";
-import { CURSOR_ADAPTER_VERSION, cursorAdapter as cursorAdapter3 } from "@birdybeep/cursor";
-import { OPENCODE_ADAPTER_VERSION, opencodeAdapter as opencodeAdapter3 } from "@birdybeep/opencode";
+import { CLAUDE_CODE_ADAPTER_VERSION, claudeCodeAdapter as claudeCodeAdapter4 } from "@birdybeep/claude-code";
+import { CODEX_ADAPTER_VERSION, codexAdapter as codexAdapter4 } from "@birdybeep/codex";
+import { COPILOT_ADAPTER_VERSION, copilotAdapter as copilotAdapter4 } from "@birdybeep/copilot";
+import { CURSOR_ADAPTER_VERSION, cursorAdapter as cursorAdapter4 } from "@birdybeep/cursor";
+import { OPENCODE_ADAPTER_VERSION, opencodeAdapter as opencodeAdapter4 } from "@birdybeep/opencode";
 var DEFAULT_ADAPTERS3 = [
-  claudeCodeAdapter3,
-  codexAdapter3,
-  opencodeAdapter3,
-  cursorAdapter3,
-  copilotAdapter3
+  claudeCodeAdapter4,
+  codexAdapter4,
+  opencodeAdapter4,
+  cursorAdapter4,
+  copilotAdapter4
 ];
 var ADAPTER_VERSIONS = {
   claude_code: CLAUDE_CODE_ADAPTER_VERSION,
@@ -1174,7 +1829,7 @@ function createReportStatusCommand(deps = {}) {
     summary: "Internal: report integration status to the backend",
     usage: "birdybeep report-status [--json]",
     run: async (ctx) => {
-      const token = await getToken3(deps.tokenOptions ?? {});
+      const token = await getToken4(deps.tokenOptions ?? {});
       if (token === null) {
         ctx.io.errline("No machine token \u2014 run `birdybeep pair` first.");
         return EXIT.ERROR;
@@ -1237,23 +1892,23 @@ function createReportStatusCommand(deps = {}) {
 
 // src/commands/status.ts
 import {
-  createSender as defaultCreateSender3
+  createSender as defaultCreateSender4
 } from "@birdybeep/agent-core";
-import { claudeCodeAdapter as claudeCodeAdapter4 } from "@birdybeep/claude-code";
-import { codexAdapter as codexAdapter4 } from "@birdybeep/codex";
-import { copilotAdapter as copilotAdapter4 } from "@birdybeep/copilot";
-import { cursorAdapter as cursorAdapter4 } from "@birdybeep/cursor";
-import { opencodeAdapter as opencodeAdapter4 } from "@birdybeep/opencode";
+import { claudeCodeAdapter as claudeCodeAdapter5 } from "@birdybeep/claude-code";
+import { codexAdapter as codexAdapter5 } from "@birdybeep/codex";
+import { copilotAdapter as copilotAdapter5 } from "@birdybeep/copilot";
+import { cursorAdapter as cursorAdapter5 } from "@birdybeep/cursor";
+import { opencodeAdapter as opencodeAdapter5 } from "@birdybeep/opencode";
 var DEFAULT_ADAPTERS4 = [
-  claudeCodeAdapter4,
-  codexAdapter4,
-  opencodeAdapter4,
-  cursorAdapter4,
-  copilotAdapter4
+  claudeCodeAdapter5,
+  codexAdapter5,
+  opencodeAdapter5,
+  cursorAdapter5,
+  copilotAdapter5
 ];
 function createStatusCommand(deps = {}) {
   const adapters = deps.adapters ?? DEFAULT_ADAPTERS4;
-  const makeSender = deps.createSender ?? ((baseUrl) => defaultCreateSender3(
+  const makeSender = deps.createSender ?? ((baseUrl) => defaultCreateSender4(
     deps.tokenOptions ? { baseUrl, tokenOptions: deps.tokenOptions } : { baseUrl }
   ));
   return {
@@ -1264,14 +1919,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);
@@ -1279,89 +1941,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
-import { randomUUID } from "crypto";
-import {
-  createSender as defaultCreateSender4,
-  getMachineIdentity as getMachineIdentity3,
-  normalizeEvent
-} from "@birdybeep/agent-core";
-function buildTestEvent(opts = {}) {
-  const machine = getMachineIdentity3();
-  return 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-${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) => defaultCreateSender4(
-    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(),
@@ -1376,7 +1978,7 @@ function buildCommands() {
 }
 
 // src/update-check.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
 import { join as join3 } from "path";
 import { birdyBeepConfigDir as birdyBeepConfigDir3 } from "@birdybeep/agent-core";
 var PACKAGE_NAME = "@birdybeep/cli";
@@ -1436,7 +2038,7 @@ function updateCachePath() {
 }
 function readUpdateCache() {
   try {
-    const parsed = JSON.parse(readFileSync2(updateCachePath(), "utf8"));
+    const parsed = JSON.parse(readFileSync3(updateCachePath(), "utf8"));
     if (typeof parsed !== "object" || parsed === null) return null;
     const { checkedAt, latest } = parsed;
     if (typeof checkedAt !== "number") return null;
@@ -1536,4 +2138,4 @@ export {
   buildCommands,
   runCli
 };
-//# sourceMappingURL=chunk-U4EIHC5C.js.map
+//# sourceMappingURL=chunk-BY5MNQE3.js.map