@birdybeep/cli 0.8.0 → 0.8.2

package/dist/index.cjs

@@ -129,7 +129,7 @@ function filteredActivity() {
 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.`;
+  return `${activity.count} local-only event(s) since ${since}${types ? ` (${types})` : ""}. Hooks are firing; these types never produce notifications, so they are not sent.`;
 }
 function machineIdentity() {
   return (0, import_agent_core.getMachineIdentity)();
@@ -217,18 +217,18 @@ function describeSurface(state) {
 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}`;
+    return `covered: ${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`;
+    return state.surface.shadowed === true ? `${group.displayName}'s hooks are installed and this build shares them, but another install comes first on PATH. This build runs only 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`;
+    return `not covered: ${group.displayName} carries no BirdyBeep hooks, so this build cannot produce notifications`;
   }
   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`;
+  return `not covered: nothing has fired from this build, while ${delivering} ${verb} delivering through the same config`;
 }
 function installTarget(harness) {
   return harness === "claude_code" ? "claude" : harness;
@@ -237,7 +237,7 @@ 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.`;
+  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. This rewrites the entry with absolute paths that do not depend on PATH.` : `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
@@ -322,7 +322,7 @@ function renderRootHelp(version, commands) {
   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.`,
+    `birdybeep ${version}: phone alerts for coding agents.`,
     "",
     "Usage:",
     "  birdybeep <command> [options]",
@@ -354,7 +354,7 @@ function commandFlagTokens(...commands) {
 }
 function renderCommandHelp(path, command) {
   const lines = [
-    `birdybeep ${path} \u2014 ${command.summary}`,
+    `birdybeep ${path}: ${command.summary}`,
     "",
     "Usage:",
     `  ${command.usage ?? `birdybeep ${path} [options]`}`
@@ -533,12 +533,12 @@ async function installSelected(adapters, ctx, tokenOptions) {
     return EXIT.OK;
   }
   if (outcomes.length === 0 || outcomes.every((o) => !o.detected)) {
-    ctx.io.line("No supported harnesses detected \u2014 nothing to install.");
+    ctx.io.line("No supported harnesses detected. Nothing was installed.");
   }
   for (const o of outcomes) {
     if (!o.detected) {
       ctx.io.line(
-        `\u2013  ${o.displayName}: not detected (skipped) \u2014 install it, then run \`birdybeep agent install ${installTarget2(o.harness)}\``
+        `\u2013  ${o.displayName}: not detected (skipped). Install it, then run \`birdybeep agent install ${installTarget2(o.harness)}\`.`
       );
       continue;
     }
@@ -548,7 +548,7 @@ async function installSelected(adapters, ctx, tokenOptions) {
   }
   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."
+      "\u26A0  This machine is not paired. Run `birdybeep setup` before expecting notifications."
     );
   }
   return EXIT.OK;
@@ -739,15 +739,15 @@ function createDoctorCommand(deps = {}) {
           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."
+          remedy: "Run `birdybeep pair`. Events that fired before pairing were not saved and will not be replayed."
         });
       }
       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."
+          detail: "Cursor is running your agent through the Claude Code hooks. This 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; duplicate events are collapsed."
         });
       }
       const filtered = filteredActivity();
@@ -796,7 +796,7 @@ function createDoctorCommand(deps = {}) {
           name: "Backend reachable",
           ok: false,
           detail: `Could not reach ${apiUrl}.`,
-          remedy: "Check your network; queued events will retry automatically."
+          remedy: "Check your network. Queued events retry automatically."
         }
       );
       const ok = checks.every((c) => c.ok);
@@ -821,10 +821,10 @@ function createDoctorCommand(deps = {}) {
         });
       } else {
         for (const c of checks) {
-          ctx.io.line(`${c.ok ? "\u2713" : "\u2717"}  ${c.name}${c.detail ? ` \u2014 ${c.detail}` : ""}`);
+          ctx.io.line(`${c.ok ? "\u2713" : "\u2717"}  ${c.name}${c.detail ? `: ${c.detail}` : ""}`);
           if (!c.ok && c.remedy) ctx.io.line(`     \u2192 ${c.remedy}`);
         }
-        ctx.io.line(ok ? "\nAll checks passed." : "\nSome checks failed \u2014 see fixes above.");
+        ctx.io.line(ok ? "\nAll checks passed." : "\nSome checks failed. See fixes above.");
       }
       return ok ? EXIT.OK : EXIT.ERROR;
     }
@@ -837,6 +837,7 @@ var import_node_crypto = require("crypto");
 var import_node_fs4 = require("fs");
 var import_node_os2 = require("os");
 var import_node_path2 = require("path");
+var import_node_perf_hooks = require("perf_hooks");
 var import_agent_core5 = require("@birdybeep/agent-core");
 var import_claude_code4 = require("@birdybeep/claude-code");
 var import_codex3 = require("@birdybeep/codex");
@@ -857,6 +858,21 @@ var HOOK_HARNESSES = [
   "copilot"
 ];
 var STDIN_READ_TIMEOUT_MS = 3e3;
+var LEGACY_HOOK_RUNTIME_BUDGET_MS = 9e3;
+function hookRuntimeBudgetMs(configuredTimeoutSeconds) {
+  if (configuredTimeoutSeconds === void 0 || !Number.isFinite(configuredTimeoutSeconds) || configuredTimeoutSeconds <= 0) {
+    return LEGACY_HOOK_RUNTIME_BUDGET_MS;
+  }
+  const configuredBudgetMs = Math.max(1, Math.floor(configuredTimeoutSeconds * 1e3) - 1e3);
+  return Math.min(LEGACY_HOOK_RUNTIME_BUDGET_MS, configuredBudgetMs);
+}
+function configuredHookTimeoutSeconds(harness) {
+  if (harness === "claude") return (0, import_claude_code4.configuredClaudeHookTimeoutSeconds)();
+  if (harness === "codex") return (0, import_codex3.configuredCodexHookTimeoutSeconds)();
+  if (harness === "cursor") return (0, import_cursor4.configuredCursorHookTimeoutSeconds)();
+  if (harness === "copilot") return (0, import_copilot3.configuredCopilotHookTimeoutSeconds)();
+  return void 0;
+}
 function withTimeout(promise, ms, fallback) {
   return new Promise((resolve) => {
     let settled = false;
@@ -977,15 +993,22 @@ function detachCodexNotifyWorker(payload) {
   }
 }
 function createHookCommand(deps = {}) {
-  const makeSender = deps.createSender ?? ((baseUrl) => (0, import_agent_core5.createSender)({ baseUrl }));
+  const makeSender = deps.createSender ?? ((baseUrl, budgetMs) => (0, import_agent_core5.createSender)({
+    baseUrl,
+    timeoutMs: Math.min(import_agent_core5.DEFAULT_SEND_TIMEOUT_MS, budgetMs),
+    totalBudgetMs: budgetMs
+  }));
   const readStdin = deps.readStdin ?? readStdinDefault;
   const stdinTimeoutMs = deps.stdinTimeoutMs ?? STDIN_READ_TIMEOUT_MS;
+  const now = deps.now ?? (() => import_node_perf_hooks.performance.now());
+  const readConfiguredHookTimeoutSeconds = deps.configuredHookTimeoutSeconds ?? configuredHookTimeoutSeconds;
   const detachCodexNotify = deps.detachCodexNotify ?? detachCodexNotifyWorker;
   return {
     name: "hook",
     summary: "Internal: normalize + send an event fired by a harness hook",
     usage: "birdybeep hook <claude|codex|opencode|cursor|copilot> [copilot-event]",
     run: async (ctx) => {
+      const hookStartedAt = now();
       const harness = ctx.args[0];
       if (!isHarnessName(harness)) {
         ctx.io.errline(`birdybeep hook: expected one of ${HOOK_HARNESSES.join("|")}`);
@@ -999,7 +1022,7 @@ function createHookCommand(deps = {}) {
       const copilotEventName = harness === "copilot" && (0, import_copilot3.isCopilotHookEventName)(ctx.args[1]) ? ctx.args[1] : void 0;
       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.`
+          `birdybeep hook copilot: second argument must be a Copilot hook event name, got ${JSON.stringify(ctx.args[1] ?? "(none)")}. Nothing was sent.`
         );
         return EXIT.USAGE;
       }
@@ -1017,7 +1040,7 @@ function createHookCommand(deps = {}) {
       }
       const drop = (reason, detail) => {
         ctx.io.result({ harness, outcome: "skipped", reason });
-        ctx.io.errline(`birdybeep hook ${harness}: ${detail} \u2014 nothing was sent.`);
+        ctx.io.errline(`birdybeep hook ${harness}: ${detail}. Nothing was sent.`);
         return EXIT.ERROR;
       };
       if (read === null) {
@@ -1047,11 +1070,14 @@ function createHookCommand(deps = {}) {
         });
         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.`
+          `birdybeep hook ${harness}: ${describeDiscriminator(payload)} is not ${article} ${handler} hook event. Nothing was sent. Check which tool is running this hook.`
         );
         return EXIT.ERROR;
       }
-      const sender = makeSender(resolveApiUrl());
+      const runtimeBudgetMs = hookRuntimeBudgetMs(readConfiguredHookTimeoutSeconds(harness));
+      const elapsedMs = Math.max(0, now() - hookStartedAt);
+      const budgetMs = Math.max(1, Math.min(import_agent_core5.DEFAULT_TOTAL_BUDGET_MS, runtimeBudgetMs - elapsedMs));
+      const sender = makeSender(resolveApiUrl(), budgetMs);
       const result = await runHookCommand(harness, payload, sender, copilotEventName);
       ctx.io.result({
         harness: handler,
@@ -1061,17 +1087,23 @@ function createHookCommand(deps = {}) {
         eventType: result.eventType,
         ...result.send?.decision ? { decision: result.send.decision } : {},
         ...result.send?.status !== void 0 ? { status: result.send.status } : {},
+        ...result.send?.queueCause !== void 0 ? { queueCause: result.send.queueCause } : {},
         ...result.send?.tokenStoreUnavailable !== void 0 ? { tokenStore: "unavailable" } : {}
       });
       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)."
+          "birdybeep: this machine is not paired. The event was not sent or queued. Run `birdybeep pair`, or run `birdybeep doctor` to see how many events were missed."
+        );
+      }
+      if (result.outcome === "failed") {
+        ctx.io.errline(
+          "birdybeep: the event could not be sent or saved locally. It will not retry. Check that BirdyBeep can write to its user data directory, then run `birdybeep doctor`."
         );
       }
-      const unavailable = result.send?.tokenStoreUnavailable;
+      const unavailable = result.outcome === "queued" ? result.send?.tokenStoreUnavailable : void 0;
       if (unavailable !== void 0) {
         ctx.io.errline(
-          `birdybeep: could not read the machine token (${unavailable.reason}) \u2014 the event was QUEUED, not sent. It will deliver once the token store is readable (unlock your keychain); \`birdybeep doctor\` drains the queue.`
+          `birdybeep: the machine token is unreadable (${unavailable.reason}). The event is queued. Restore token-store access; \`birdybeep doctor\` drains the queue.`
         );
       }
       return EXIT.OK;
@@ -1089,7 +1121,7 @@ function createLogoutCommand(deps = {}) {
     usage: "birdybeep logout",
     run: async (ctx) => {
       await (0, import_agent_core6.clearToken)(deps.tokenOptions ?? {});
-      ctx.io.emit("Logged out \u2014 the machine token was removed.", { loggedOut: true });
+      ctx.io.emit("Logged out. The machine token was removed.", { loggedOut: true });
       return EXIT.OK;
     }
   };
@@ -1116,14 +1148,14 @@ function createUnpairCommand(deps = {}) {
   const timeoutMs = deps.timeoutMs ?? 1e4;
   return {
     name: "unpair",
-    summary: "Unpair this machine \u2014 revoke it server-side and remove the local token",
+    summary: "Revoke this machine and remove its local token",
     usage: "birdybeep unpair",
     run: async (ctx) => {
       const token = await (0, import_agent_core6.getToken)(deps.tokenOptions ?? {});
       const outcome = token === null ? "no_token" : await revokeSelf(token, fetchImpl, timeoutMs);
       await (0, import_agent_core6.clearToken)(deps.tokenOptions ?? {});
       const serverRevoked = outcome === "revoked";
-      const human = outcome === "revoked" ? "Unpaired \u2014 the machine was revoked and removed from your account." : outcome === "no_token" ? "Already unpaired \u2014 there was no local token to remove." : outcome === "unreachable" ? "Unpaired locally, but the server was unreachable \u2014 the machine may still show in the app. Open BirdyBeep and revoke it there to fully remove it." : "Unpaired locally, but the server didn't confirm removal \u2014 if the machine still shows in the app, revoke it there.";
+      const human = outcome === "revoked" ? "Unpaired. The machine was revoked and removed from your account." : outcome === "no_token" ? "Already unpaired. There was no local token to remove." : outcome === "unreachable" ? "Unpaired locally, but the server was unreachable. The machine may still appear in the app. Open BirdyBeep and revoke it there." : "Unpaired locally, but the server did not confirm removal. If the machine still appears in the app, revoke it there.";
       ctx.io.emit(human, { unpaired: true, serverRevoked });
       return EXIT.OK;
     }
@@ -1206,7 +1238,7 @@ async function pairTokenPoll(apiUrl, deviceCode, fetchImpl, machineFingerprint,
 }
 
 // src/version.ts
-var CLI_VERSION = "0.8.0".length > 0 ? "0.8.0" : "0.0.0";
+var CLI_VERSION = "0.8.2".length > 0 ? "0.8.2" : "0.0.0";
 
 // src/commands/setup.ts
 var import_claude_code5 = require("@birdybeep/claude-code");
@@ -1231,8 +1263,8 @@ function buildTestEvent(opts = {}) {
       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.",
+      title: "BirdyBeep test",
+      body: "Notifications from this machine are working.",
       metadata: { test: true }
     },
     opts
@@ -1267,43 +1299,43 @@ function createTestCommand(deps = {}) {
           });
           if (reach.state === "ok" && reach.data.active_device_count === 0) {
             ctx.io.line(
-              "\u26A0 The backend accepted the test event, but NO device on this account can receive it \u2014 nothing will arrive. Open the BirdyBeep app on your phone to register it (if it says the device limit is full, free a slot in Settings \u203A devices)."
+              "\u26A0 No active device can receive a Beep. Open BirdyBeep on your phone and sign in to register it. If the device limit is full, free a slot in Settings \u203A devices."
             );
           } else if (reach.state === "ok") {
             ctx.io.line(
-              `\u2713 Test event accepted and queued for ${String(reach.data.active_device_count)} registered device(s) \u2014 check your phone for a test Beep.`
+              `\u2713 Test event accepted for ${String(reach.data.active_device_count)} registered device(s). Check your phone for a test Beep.`
             );
           } else {
-            ctx.io.line("\u2713 Test event accepted by the backend \u2014 check your phone for a test Beep.");
+            ctx.io.line("\u2713 Test event accepted by the backend. 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`."
+            "\u26A0 Test event accepted; push suppressed. Check machine and integration mutes in the app."
           );
         } 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."
-          );
+          ctx.io.line("\u26A0 Test event matched a recent duplicate. Retry in 30 seconds.");
         } else {
           ctx.io.line(
-            `\u26A0 The backend accepted the test event but decided "${result.decision}" \u2014 no push was sent. Run \`birdybeep doctor\`.`
+            `\u26A0 Test event accepted; push decision was "${result.decision}". 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`."
+          "\u2717 This machine is not paired. Run `birdybeep pair`. No event was sent or queued."
         );
-      } else if (result.tokenStoreUnavailable !== void 0) {
+      } else if (result.outcome === "failed") {
         ctx.io.line(
-          `\u2022 Could not read the machine token (${result.tokenStoreUnavailable.reason}) \u2014 the test event was queued and delivers once the token store is readable. If your keychain is locked, unlock it and run \`birdybeep test\` again.`
+          "\u2717 The test event could not be sent or saved locally. Check BirdyBeep's data-directory permissions, then retry."
         );
-      } else if (result.outcome === "queued" && result.queueCause === "backend") {
-        const status = result.status !== void 0 ? ` (HTTP ${String(result.status)})` : "";
+      } else if (result.tokenStoreUnavailable !== void 0) {
         ctx.io.line(
-          result.code === "rate_limited" || result.status === 429 ? `\u2022 Throttled by the backend${status} \u2014 test event queued; it retries on its own. Not your network: the request got through.` : `\u2022 The backend is having trouble${status} \u2014 test event queued; it retries on its own. Not your network: the request got through.`
+          `\u2022 The machine token is unreadable (${result.tokenStoreUnavailable.reason}). The test event is queued. Restore token-store access, then retry.`
         );
+      } else if (result.outcome === "queued" && result.queueCause === "backend") {
+        const status = result.status !== void 0 ? ` HTTP ${String(result.status)}` : " an error";
+        ctx.io.line(`\u2022 Backend returned${status}. The test event is queued for retry.`);
       } else if (result.outcome === "queued") {
-        ctx.io.line("\u2022 Offline \u2014 test event queued; it will deliver when you reconnect.");
+        ctx.io.line("\u2022 Could not reach the backend. The test event is queued.");
       } else if (result.code === "quota_exceeded") {
         const reach = await (0, import_agent_core8.fetchPushReachability)({
           baseUrl,
@@ -1311,18 +1343,18 @@ function createTestCommand(deps = {}) {
           ...deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}
         });
         const quota = reach.state === "ok" ? reach.data.quota : void 0;
-        const exhausted = quota ? (0, import_agent_core8.describeExhaustedQuota)(quota) : void 0;
+        const exhausted = quota !== void 0 && quota.beeps_limit !== null ? (0, import_agent_core8.describeExhaustedQuota)({ ...quota, beeps_limit: quota.beeps_limit }) : void 0;
         ctx.io.line(
-          quota && exhausted ? `\u2717 Test event REJECTED \u2014 this account's monthly beep quota is used up (${String(quota.beeps_accepted)}/${String(quota.beeps_limit)} beeps on the ${quota.plan} plan, period ${exhausted.window}). Every notifiable event is being rejected. ${exhausted.remedy}` : (
+          quota?.beeps_limit === null ? "\u2717 Test event rejected. The backend rejected this event for quota, but this account now reports unlimited beeps on Plus. The plan changed between those requests; run `birdybeep test` again. If it repeats, run `birdybeep doctor`." : quota && exhausted ? `\u2717 Test event rejected. This account's monthly beep quota is used up (${String(quota.beeps_accepted)}/${String(quota.beeps_limit)} beeps on the ${quota.plan} plan, period ${exhausted.window}). Every notifiable event is being rejected. ${exhausted.remedy}` : (
             // An older backend reports no quota, so there is no period and no reset date to
             // give — and `doctor` cannot supply them either, since it reads this same response.
-            "\u2717 Test event REJECTED \u2014 this account's monthly beep quota is used up, so no beep can be sent. This server does not report the period or the reset date; check your usage in the BirdyBeep app."
+            "\u2717 Test event rejected. This account's monthly beep quota is used up, so no Beep can be sent. This server does not report the period or the reset date; check your usage in the BirdyBeep app."
           )
         );
       } 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;
+      return result.outcome === "dropped" || result.outcome === "unpaired" || result.outcome === "failed" ? EXIT.ERROR : EXIT.OK;
     }
   };
 }
@@ -1422,7 +1454,7 @@ function buildHarnessReports(installs, groups) {
       }
     ] : 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);
+      const remedy = surfaceRemedy(state, group) ?? (graded === "not covered" ? `${adapter.displayName} carries no BirdyBeep hooks. Re-run \`birdybeep agent install ${installTarget2(adapter.id)}\` from a shell where \`birdybeep\` resolves.` : void 0);
       return {
         harness: adapter.id,
         displayName: adapter.displayName,
@@ -1468,12 +1500,12 @@ function describeMissing(reports) {
   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.`
+      "No supported coding agent is installed on this machine.",
+      `Install one of ${names.join(", ")}, then run \`birdybeep setup\` again.`
     ];
   }
   return [
-    `Not installed: ${names.join(", ")}. Install any of them, then run \`birdybeep setup\` again to wire it up.`
+    `Not installed: ${names.join(", ")}. Install any of them, then run \`birdybeep setup\` again.`
   ];
 }
 async function runHarnessSetup(ctx, options, deps = {}) {
@@ -1696,7 +1728,7 @@ function createPairingCommand(verb, deps = {}) {
       },
       {
         flag: "--no-install",
-        summary: "Stop after pairing \u2014 don't detect or wire up any coding agent"
+        summary: "Stop after pairing; do not install coding-agent hooks"
       },
       {
         flag: "--no-test",
@@ -1716,7 +1748,7 @@ function createPairingCommand(verb, deps = {}) {
       };
       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."
+          chain !== void 0 ? "\u2713 Already paired. Checking installed coding-agent hooks." : "\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({
@@ -1752,7 +1784,7 @@ function createPairingCommand(verb, deps = {}) {
         ctx.io.line(
           `   Session code (display only; cannot approve by itself):  ${start.user_code}`
         );
-        ctx.io.line("Waiting for you to approve this machine in the app\u2026");
+        ctx.io.line("Waiting for approval in the BirdyBeep app.");
       }
       const deadline = Date.parse(start.expires_at);
       const startedAt = clock();
@@ -1781,7 +1813,7 @@ function createPairingCommand(verb, deps = {}) {
         }
         if (!ctx.flags.json && nowMs - lastBeat >= HEARTBEAT_MS) {
           ctx.io.line(
-            poll.status === "error" ? `   still trying \u2014 the server is busy (${poll.message}). approve in the app when you can\u2026` : "   still waiting \u2014 approve this machine in the BirdyBeep app\u2026"
+            poll.status === "error" ? `   Backend unavailable (${poll.message}); retrying.` : "   Waiting for approval in the BirdyBeep app."
           );
           lastBeat = nowMs;
         }
@@ -1821,7 +1853,7 @@ function createPairingCommand(verb, deps = {}) {
       if (decision.action === "prompt" && !isAffirmative(await promptLine(decision.question, decision.on))) {
         ctx.io.result({ paired: false, reason: "declined" });
         ctx.io.errline(
-          "Pairing declined \u2014 the machine token was NOT stored, and this machine will send no events. The machine may still appear in the BirdyBeep app; revoke it there if you did not intend to pair it."
+          "Pairing declined. The machine token was NOT stored, and this machine will send no events. The machine may still appear in the BirdyBeep app; revoke it there if you did not intend to pair it."
         );
         return EXIT.ERROR;
       }
@@ -1830,8 +1862,8 @@ function createPairingCommand(verb, deps = {}) {
       const discarded = new import_agent_core9.LocalEventQueue().discardBefore(clock());
       (0, import_agent_core9.clearUnpairedNotice)();
       const humanSuffix = approvedBy !== void 0 ? ` to ${approvedBy}` : "";
-      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." : "";
+      const discardedSuffix = discarded > 0 ? ` Discarded ${discarded} event(s) queued before pairing. They will not produce notifications.` : "";
+      const nextStep = chain === void 0 ? " Run `birdybeep setup` to install coding-agent hooks." : "";
       ctx.io.line(`\u2713 Paired${humanSuffix}.${nextStep}${discardedSuffix}`);
       const report = chain !== void 0 ? await runSetupChain(ctx, setupDeps, pairFlags) : void 0;
       ctx.io.result({
@@ -1849,7 +1881,7 @@ function createPairCommand(deps = {}) {
   return createPairingCommand(
     {
       name: "pair",
-      summary: "Pair this machine and wire up every coding agent on it",
+      summary: "Pair this machine and install detected coding-agent hooks",
       usage: "birdybeep pair [--yes] [--expect-email <addr>] [--no-install] [--no-test] [--json]",
       skipWhenPaired: false
     },
@@ -1860,9 +1892,9 @@ function createSetupCommand(deps = {}) {
   return createPairingCommand(
     {
       name: "setup",
-      summary: "Set up BirdyBeep here: pair, wire up every coding agent, test",
+      summary: "Set up BirdyBeep on this machine",
       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.",
+      gettingStarted: "Connect this machine and install hooks for detected coding agents.",
       skipWhenPaired: true
     },
     deps
@@ -1935,7 +1967,7 @@ function createReportStatusCommand(deps = {}) {
     run: async (ctx) => {
       const token = await (0, import_agent_core11.getToken)(deps.tokenOptions ?? {});
       if (token === null) {
-        ctx.io.errline("No machine token \u2014 run `birdybeep pair` first.");
+        ctx.io.errline("No machine token. Run `birdybeep pair` first.");
         return EXIT.ERROR;
       }
       const items = await gatherItems(adapters);
@@ -1980,12 +2012,12 @@ function createReportStatusCommand(deps = {}) {
         });
       } else if (outcome === "terminal") {
         ctx.io.errline(
-          `Report rejected (${errorCode ?? "auth"}) \u2014 your token may be revoked. Re-run \`birdybeep pair\`.`
+          `Report rejected (${errorCode ?? "auth"}). Your token may be revoked. Re-run \`birdybeep pair\`.`
         );
       } else {
         for (const e of effective) {
           ctx.io.line(
-            outcome === "reported" ? `\u2713  ${e.harness}: ${e.status} (reported)` : `\u2022  ${e.harness}: ${e.status} (deferred \u2014 backend unreachable)`
+            outcome === "reported" ? `\u2713  ${e.harness}: ${e.status} (reported)` : `\u2022  ${e.harness}: ${e.status} (deferred; backend unreachable)`
           );
         }
       }
@@ -2045,7 +2077,7 @@ function createStatusCommand(deps = {}) {
       } else {
         ctx.io.line(`Machine: ${machine.label} (${machine.os})`);
         ctx.io.line(
-          pairing.state === "paired" ? "Paired:  yes" : pairing.state === "unpaired" ? "Paired:  no \u2014 run `birdybeep pair`" : `Paired:  unknown \u2014 ${describeTokenStoreUnavailable(pairing)}`
+          pairing.state === "paired" ? "Paired:  yes" : pairing.state === "unpaired" ? "Paired:  no. Run `birdybeep pair`." : `Paired:  unknown. ${describeTokenStoreUnavailable(pairing)}`
         );
         ctx.io.line("Integrations:");
         for (const i of integrations) {
@@ -2053,7 +2085,7 @@ function createStatusCommand(deps = {}) {
           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(`    ${mark} ${describeSurface(state)}: ${state.coverage}`);
           }
         }
         ctx.io.line(