@hraness/ghostget 0.18.12 → 0.18.14

package/src/beeper-client-types.ts

@@ -96,7 +96,7 @@ export type BeeperContactInteractionExportReceipt = Readonly<{
   implementation: Readonly<{
     producer: Readonly<{
       package: "@hraness/ghostget";
-      version: "0.18.12";
+      version: "0.18.14";
     }>;
     officialCli: Readonly<{
       implementation: "github.com/beeper/cli";

package/src/control/menubar-cli.ts

@@ -0,0 +1,570 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, readdirSync, type BigIntStats } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { handleCompanionCommand, openBrowser, type CompanionOptions, type MenuItem } from "@hraness/desktop-foundation";
+import { createSupportOffer } from "@hraness/support-foundation";
+import { ghostgetSupportProfile } from "../support-profile";
+import { TRAY_ICON } from "./menubar-icon";
+import { ghostgetStateHome } from "../storage";
+import { CONTROL_PROTOCOL, type ActivityRow, type ApprovalView, type CapabilityView, type ControlRequest, type ControlResponse, type ControlSnapshot } from "./protocol";
+import type { ControlEnvironment } from "./web-policy";
+
+const WEBSITE = "https://ghostget.com/getting-started";
+const SUPPORT_ACTIONS = createSupportOffer(ghostgetSupportProfile, "desktop").actions;
+const MAX_FRAME = 4_194_304;
+const HELPER_TIMEOUT_MS = 15_000;
+const OUTPUTS_LIMIT = 12;
+const OUTPUTS_SCAN_BOUND = 512;
+const OPENABLE_EXTENSIONS = new Set(["pdf", "txt", "md", "csv", "json", "png", "jpg", "jpeg", "gif", "webp", "tiff"]);
+const BROWSERS = [
+  { key: "safari", label: "Safari", browser: "safari", profile: null },
+  { key: "chrome-default", label: "Chrome · Default", browser: "chrome", profile: "Default" },
+  { key: "chrome-profile-1", label: "Chrome · Profile 1", browser: "chrome", profile: "Profile 1" },
+  { key: "chrome-profile-2", label: "Chrome · Profile 2", browser: "chrome", profile: "Profile 2" },
+] as const;
+type Output = { readonly stdout: (text: string) => unknown; readonly stderr: (text: string) => unknown };
+
+/** Presentation never lets control data add lines, bidi overrides or unbounded menus. */
+export function menuLabel(text: string, limit = 72): string {
+  const clean = [...text]
+    .map((character) => (/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u.test(character) ? " " : character))
+    .join("").split(/\s+/u).filter((part) => part.length > 0).join(" ");
+  const scalars = [...clean];
+  return scalars.length > limit ? `${scalars.slice(0, Math.max(0, limit - 1)).join("")}…` : clean;
+}
+
+function detailItems(detail: string): MenuItem[] {
+  const words = menuLabel(detail, 216).split(" ");
+  const rows: string[] = [];
+  let current = "";
+  for (const word of words) {
+    const next = current ? `${current} ${word}` : word;
+    if ([...next].length <= 72) current = next;
+    else { if (current !== "") rows.push(current); current = word; }
+  }
+  if (current !== "") rows.push(current);
+  const bounded = rows.slice(0, 3);
+  return bounded.length > 0 ? bounded.map((line) => ({ kind: "label" as const, label: menuLabel(line, 72) })) : [{ kind: "label" as const, label: "No additional detail." }];
+}
+
+/** One output file that passed ownership, type and permission checks. The
+ * identity fields revalidate the same file at dispatch time. */
+export interface OutputEntry {
+  readonly name: string;
+  readonly size: number;
+  readonly modifiedMs: number;
+  readonly identity: { readonly dev: bigint; readonly ino: bigint; readonly size: bigint; readonly mtimeNs: bigint; readonly mode: bigint };
+}
+export interface OutputsView {
+  readonly directory: { readonly dev: bigint; readonly ino: bigint } | null;
+  readonly entries: readonly OutputEntry[];
+  readonly message: string | null;
+  readonly truncated: boolean;
+}
+const EMPTY_OUTPUTS: OutputsView = { directory: null, entries: [], message: null, truncated: false };
+const UNAVAILABLE_OUTPUTS: OutputsView = { directory: null, entries: [], message: "Outputs unavailable", truncated: false };
+
+/** Bounded newest-first listing of the product outputs directory. Reads never
+ * create the directory and never follow symlinks; entries must be regular
+ * files owned by the current user without group or other write bits. */
+export function readOutputs(directory: string): OutputsView {
+  const uid = process.getuid?.();
+  const dirInfo = (() => { try { return lstatSync(directory, { bigint: true }); } catch { return null; } })();
+  if (dirInfo === null || uid === undefined || !dirInfo.isDirectory() || dirInfo.isSymbolicLink() || dirInfo.uid !== BigInt(uid) || (dirInfo.mode & 0o777n) !== 0o700n) return UNAVAILABLE_OUTPUTS;
+  const entry = (name: string): OutputEntry | null => {
+    if (name.startsWith(".") || name.includes("/") || name.includes("\u0000")) return null;
+    let info: BigIntStats;
+    try { info = lstatSync(join(directory, name), { bigint: true }); } catch { return null; }
+    if (!info.isFile() || info.isSymbolicLink() || info.uid !== BigInt(uid) || (info.mode & 0o022n) !== 0n) return null;
+    return { name, size: Number(info.size), modifiedMs: Number(info.mtimeMs), identity: { dev: info.dev, ino: info.ino, size: info.size, mtimeNs: info.mtimeNs, mode: info.mode } };
+  };
+  let names: readonly string[];
+  try { names = readdirSync(directory).slice(0, OUTPUTS_SCAN_BOUND); } catch { return UNAVAILABLE_OUTPUTS; }
+  const entries = names.flatMap((name) => { const found = entry(name); return found === null ? [] : [found]; });
+  const truncated = names.length === OUTPUTS_SCAN_BOUND || entries.length > OUTPUTS_LIMIT;
+  entries.sort((a, b) => b.identity.mtimeNs === a.identity.mtimeNs ? a.name.localeCompare(b.name) : b.identity.mtimeNs > a.identity.mtimeNs ? 1 : -1);
+  return { directory: { dev: dirInfo.dev, ino: dirInfo.ino }, entries: entries.slice(0, OUTPUTS_LIMIT), message: entries.length === 0 ? "No output files" : null, truncated };
+}
+
+/** Wire action ids carry only entry indices; file names never enter the wire
+ * contract, and dispatch revalidates identity against the stored listing. */
+
+/** Revalidate directory and entry identity at dispatch. An OS open remains a
+ * handoff; this refuses stale or swapped targets. */
+function validatedOutputPath(directory: string, expected: OutputsView, name: string): string | null {
+  const uid = process.getuid?.();
+  if (expected.directory === null || uid === undefined) return null;
+  const dirInfo = (() => { try { return lstatSync(directory, { bigint: true }); } catch { return null; } })();
+  if (dirInfo === null || !dirInfo.isDirectory() || dirInfo.isSymbolicLink() || dirInfo.dev !== expected.directory.dev || dirInfo.ino !== expected.directory.ino) return null;
+  const expectedEntry = expected.entries.find((item) => item.name === name);
+  if (expectedEntry === undefined) return null;
+  const fresh = (() => { try { return lstatSync(join(directory, name), { bigint: true }); } catch { return null; } })();
+  if (fresh === null || !fresh.isFile() || fresh.isSymbolicLink() || fresh.uid !== BigInt(uid) || (fresh.mode & 0o022n) !== 0n
+    || fresh.dev !== expectedEntry.identity.dev || fresh.ino !== expectedEntry.identity.ino
+    || fresh.size !== expectedEntry.identity.size || fresh.mtimeNs !== expectedEntry.identity.mtimeNs || fresh.mode !== expectedEntry.identity.mode) return null;
+  return join(directory, name);
+}
+
+function outputSize(size: number): string {
+  if (size < 1024) return `${size} B`;
+  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`;
+  return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}
+function outputItems(outputs: OutputsView): MenuItem[] {
+  const items: MenuItem[] = [];
+  if (outputs.message !== null) items.push({ kind: "label", label: menuLabel(outputs.message) });
+  outputs.entries.forEach((entry, index) => {
+    const detail: MenuItem[] = [{ kind: "label", label: menuLabel(`${outputSize(entry.size)} · ${new Date(entry.modifiedMs).toLocaleString()}`) }];
+    const extension = entry.name.includes(".") ? entry.name.slice(entry.name.lastIndexOf(".") + 1).toLowerCase() : "";
+    if (OPENABLE_EXTENSIONS.has(extension)) detail.push({ kind: "action", id: `output:open:${index}`, label: "Open file" });
+    detail.push({ kind: "action", id: `output:reveal:${index}`, label: "Reveal in file manager" });
+    detail.push({ kind: "action", id: `output:copy:${index}`, label: "Copy file path" });
+    items.push({ kind: "submenu", label: menuLabel(entry.name), items: detail });
+  });
+  if (outputs.truncated) items.push({ kind: "label", label: `Showing up to ${OUTPUTS_LIMIT} files from a bounded scan` });
+  if (outputs.directory !== null && outputs.entries.length > 0) items.push({ kind: "action", id: "output:folder", label: "Reveal outputs folder" });
+  if (items.length === 0) items.push({ kind: "label", label: "No output files" });
+  return items;
+}
+
+const CLI_COMMANDS = ["ghostget --help", "ghostget menubar --help", "ghostget menubar status"] as const;
+function cliHelpItems(): MenuItem[] {
+  return [
+    { kind: "action", id: "clip:0", label: "CLI help" },
+    { kind: "action", id: "clip:1", label: "Menu-bar help" },
+    { kind: "action", id: "clip:2", label: "Menu-bar installation status" },
+  ];
+}
+
+/** OS open/reveal handoff for one validated path. Explorer exit codes are not
+ * meaningful, so only spawn failure degrades the menu. */
+function openPath(path: string, reveal: boolean): void {
+  const command = process.platform === "darwin"
+    ? (reveal ? ["open", "-R", path] : ["open", path])
+    : process.platform === "win32"
+      ? (reveal ? ["explorer", `/select,${path}`] : ["explorer", path])
+      : (reveal ? ["xdg-open", dirname(path)] : ["xdg-open", path]);
+  try { const child = Bun.spawnSync(command, { stdout: "ignore", stderr: "ignore" }); if (process.platform !== "win32" && child.exitCode !== 0) throw new Error("exit"); }
+  catch { throw new Error("ghostget-open-unavailable"); }
+}
+function copyText(text: string): void {
+  const command = process.platform === "darwin" ? ["pbcopy"] : process.platform === "win32" ? ["clip"] : ["xclip", "-selection", "clipboard"];
+  try { const child = Bun.spawnSync(command, { stdin: Buffer.from(text, "utf8"), stdout: "ignore", stderr: "ignore" }); if (child.exitCode !== 0) throw new Error("exit"); }
+  catch { throw new Error("ghostget-clipboard-unavailable"); }
+}
+
+/** Bounded administrative client over the helper's private stdio channel. The
+ * menu companion owns the helper process; agent requests stay on the socket. */
+interface HelperClient { request(request: ControlRequest, timeoutMs?: number): Promise<ControlResponse>; close(): void }
+function spawnHelper(environment: ControlEnvironment): HelperClient {
+  const script = fileURLToPath(new URL("./helper.ts", import.meta.url));
+  const env: Record<string, string> = { ...process.env } as Record<string, string>;
+  for (const [key, value] of Object.entries(environment)) if (value !== undefined) env[key] = value;
+  const child = Bun.spawn([process.execPath, "--no-env-file", "--no-install", script], { cwd: dirname(script), env, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  const pending = new Map<string, { resolve: (response: ControlResponse) => void; timer: ReturnType<typeof setTimeout> }>();
+  let buffer = Buffer.alloc(0);
+  let closed = false;
+  void new Response(child.stderr).text();
+  const settle = (response: ControlResponse | null): void => {
+    const slots = [...pending.values()]; pending.clear();
+    for (const slot of slots) {
+      clearTimeout(slot.timer);
+      slot.resolve(response ?? { ok: false, code: "CONTROL_DISCONNECTED", message: "The Ghostget control helper disconnected." });
+    }
+  };
+  const read = (async () => {
+    const reader = child.stdout.getReader();
+    try {
+      for (;;) {
+        const next = await reader.read(); if (next.done) break;
+        buffer = Buffer.concat([buffer, next.value]);
+        if (buffer.length > MAX_FRAME) throw new Error("oversized helper response");
+        let end: number;
+        while ((end = buffer.indexOf(10)) >= 0) {
+          const line = buffer.subarray(0, end); buffer = buffer.subarray(end + 1);
+          let frame: Record<string, unknown>;
+          try { frame = JSON.parse(line.toString("utf8")) as Record<string, unknown>; } catch { continue; }
+          const id = typeof frame.id === "string" ? frame.id : null;
+          if (id === null || frame.protocol !== CONTROL_PROTOCOL) continue;
+          const slot = pending.get(id); if (slot === undefined) continue;
+          pending.delete(id); clearTimeout(slot.timer);
+          slot.resolve(frame as unknown as ControlResponse);
+        }
+      }
+    } catch { /* a dead or oversized channel degrades the menu, it never retries */ }
+    finally { closed = true; settle(null); }
+  })();
+  void read;
+  void child.exited.then(() => { closed = true; settle(null); });
+  return {
+    request: (request, timeoutMs = HELPER_TIMEOUT_MS) => new Promise<ControlResponse>((resolve) => {
+      if (closed) { resolve({ ok: false, code: "CONTROL_DISCONNECTED", message: "The Ghostget control helper is not running." }); return; }
+      const id = randomUUID();
+      const timer = setTimeout(() => { pending.delete(id); resolve({ ok: false, code: "CONTROL_TIMEOUT", message: "The Ghostget control helper did not answer in time." }); }, timeoutMs);
+      pending.set(id, { resolve, timer });
+      try { child.stdin.write(`${JSON.stringify({ id, protocol: CONTROL_PROTOCOL, request })}\n`); }
+      catch { pending.delete(id); clearTimeout(timer); resolve({ ok: false, code: "CONTROL_DISCONNECTED", message: "The Ghostget control helper disconnected." }); }
+    }),
+    close: () => { try { child.stdin.end(); } catch { /* already closed */ } },
+  };
+}
+
+function accountItems(snapshot: ControlSnapshot, enabled: boolean): MenuItem[] {
+  const accounts = snapshot.accounts;
+  const rows: MenuItem[] = accounts.slice(0, 20).map((account) => {
+    const status = account.status === "verified" ? "Verified" : account.status === "configured" ? "Configured" : "Reconnect required";
+    const items: MenuItem[] = [
+      { kind: "label", label: status },
+      ...detailItems([account.provider, account.kind, account.subject].filter((part): part is string => part !== null).join(" · ") || "No subject recorded"),
+    ];
+    if (enabled && account.status === "reconnect-required") {
+      items.push({
+        kind: "submenu",
+        label: "Reconnect",
+        items: snapshot.connectionProviders.map((provider) => ({
+          kind: "submenu" as const,
+          label: menuLabel(provider.title) || "Provider",
+          items: BROWSERS.map((choice) => ({ kind: "action" as const, id: `reconnect:${account.id}:${provider.id}:${choice.key}`, label: choice.label })),
+        })),
+      });
+    }
+    if (enabled) items.push({ kind: "action", id: `disconnect:${account.id}`, label: "Disconnect this account" });
+    return { kind: "submenu" as const, label: menuLabel(`${account.id} · ${status}`) || "Account", items };
+  });
+  if (accounts.length === 0) rows.push({ kind: "label", label: "No accounts connected" });
+  if (accounts.length > 20) rows.push({ kind: "label", label: `${accounts.length - 20} more accounts` });
+  return rows;
+}
+
+function approvalItems(approvals: readonly ApprovalView[], enabled: boolean): MenuItem[] {
+  const rows: MenuItem[] = approvals.slice(0, 10).map((approval) => ({
+    kind: "submenu" as const,
+    label: menuLabel(approval.title) || "Approval request",
+    items: [
+      ...detailItems([approval.kind, approval.account ?? "no account", approval.effect, approval.preview].join(" · ")),
+      { kind: "label", label: menuLabel(`Expires ${approval.expiresAt}`) },
+      { kind: "action", id: `approval:allow:${approval.id}`, label: "Allow once", enabled },
+      { kind: "action", id: `approval:deny:${approval.id}`, label: "Deny", enabled },
+    ],
+  }));
+  if (approvals.length === 0) rows.push({ kind: "label", label: "No pending approvals" });
+  if (approvals.length > 10) rows.push({ kind: "label", label: `${approvals.length - 10} more approvals` });
+  return rows;
+}
+
+export interface Attempt { readonly attemptId: string; readonly title: string; status: "awaiting-sign-in" | "verified"; subject: string | null }
+function connectItems(snapshot: ControlSnapshot, attempts: ReadonlyMap<string, Attempt>, enabled: boolean): MenuItem[] {
+  const rows: MenuItem[] = [];
+  for (const attempt of [...attempts.values()].slice(0, 8)) {
+    const items: MenuItem[] = attempt.status === "verified"
+      ? [
+          { kind: "label", label: menuLabel(`Signed in as ${attempt.subject ?? "unknown"}`) },
+          { kind: "action", id: `attempt:commit:${attempt.attemptId}`, label: `Connect ${menuLabel(attempt.subject ?? "this account", 40)}`, enabled },
+        ]
+      : [
+          { kind: "label", label: "Finish sign-in in the opened browser, then verify." },
+          { kind: "action", id: `attempt:verify:${attempt.attemptId}`, label: "Verify sign-in", enabled },
+        ];
+    items.push({ kind: "action", id: `attempt:cancel:${attempt.attemptId}`, label: "Cancel", enabled });
+    rows.push({ kind: "submenu", label: menuLabel(`${attempt.title} · ${attempt.status === "verified" ? "verified" : "awaiting sign-in"}`), items });
+  }
+  for (const provider of snapshot.connectionProviders.slice(0, 12)) {
+    rows.push({
+      kind: "submenu",
+      label: menuLabel(provider.title) || "Provider",
+      items: BROWSERS.map((choice) => ({ kind: "action" as const, id: `connect:${provider.id}:${choice.key}`, label: choice.label, enabled })),
+    });
+  }
+  if (rows.length === 0) rows.push({ kind: "label", label: "No connection providers" });
+  return rows;
+}
+
+function capabilityItems(capabilities: readonly CapabilityView[]): MenuItem[] {
+  if (capabilities.length === 0) return [{ kind: "label", label: "No capabilities discovered" }];
+  const counts = new Map<string, number>();
+  for (const capability of capabilities) counts.set(capability.state, (counts.get(capability.state) ?? 0) + 1);
+  const rows: MenuItem[] = [...counts.entries()].map(([state, count]) => ({ kind: "label" as const, label: `${count} ${state}` }));
+  for (const capability of capabilities.slice(0, 15)) {
+    rows.push({ kind: "label", label: menuLabel(`${capability.adapterId} · ${capability.operationId} · ${capability.permission}`) });
+  }
+  if (capabilities.length > 15) rows.push({ kind: "label", label: `${capabilities.length - 15} more capabilities` });
+  return rows;
+}
+
+function permissionItems(snapshot: ControlSnapshot, enabled: boolean): MenuItem[] {
+  const rows: MenuItem[] = [];
+  if (!snapshot.policy.managed) rows.push({ kind: "action", id: "permission:enable", label: "Enable operation permissions", enabled });
+  else rows.push({ kind: "label", label: "Operation permissions are managed per account." });
+  const unmanaged = snapshot.capabilities.filter((capability) => capability.permission === "unmanaged");
+  for (const capability of unmanaged.slice(0, 15)) {
+    rows.push({
+      kind: "submenu",
+      label: menuLabel(`${capability.adapterId} · ${capability.operationId}`),
+      items: [
+        ...detailItems(`${capability.surface} · ${capability.effect} · risk ${capability.risk}`),
+        { kind: "action", id: `permission:allow:${capability.adapterId}:${capability.operationId}`, label: "Allow", enabled },
+        { kind: "action", id: `permission:ask:${capability.adapterId}:${capability.operationId}`, label: "Ask each time", enabled },
+        { kind: "action", id: `permission:deny:${capability.adapterId}:${capability.operationId}`, label: "Deny", enabled },
+      ],
+    });
+  }
+  if (unmanaged.length > 15) rows.push({ kind: "label", label: `${unmanaged.length - 15} more operations need review` });
+  if (!snapshot.policy.managed && unmanaged.length === 0) rows.push({ kind: "label", label: "All operations already have a decision." });
+  return rows;
+}
+
+function webItems(snapshot: ControlSnapshot): MenuItem[] {
+  const rules = snapshot.web.rules;
+  const rows: MenuItem[] = [{ kind: "label", label: snapshot.web.gatewayOnly ? "Gateway-only mode" : "Direct retrieval allowed" }];
+  for (const rule of rules.slice(0, 10)) {
+    rows.push({ kind: "label", label: menuLabel(`${rule.origin}${rule.path.value} · ${rule.decision}`) });
+  }
+  if (rules.length > 10) rows.push({ kind: "label", label: `${rules.length - 10} more rules` });
+  return rows;
+}
+
+function interfaceItems(snapshot: ControlSnapshot): MenuItem[] {
+  const interfaces = snapshot.interfaces;
+  if (interfaces.length === 0) return [{ kind: "label", label: "No interfaces installed" }];
+  const rows: MenuItem[] = interfaces.slice(0, 10).map((entry) => ({
+    kind: "submenu" as const,
+    label: menuLabel(`${entry.title} · ${entry.state}`),
+    items: detailItems(`${entry.operationCount} operations · ${entry.adapterIds.join(", ") || "no adapters"}${entry.issues.length > 0 ? ` · ${entry.issues.length} issue(s)` : ""}`),
+  }));
+  if (interfaces.length > 10) rows.push({ kind: "label", label: `${interfaces.length - 10} more interfaces` });
+  return rows;
+}
+
+function activityItems(rows: readonly ActivityRow[]): MenuItem[] {
+  if (rows.length === 0) return [{ kind: "label", label: "No recent gateway activity" }];
+  return rows.slice(0, 8).map((row) => ({
+    kind: "label" as const,
+    label: menuLabel(`${row.method} ${row.origin ?? row.endpoint ?? "request"} · ${row.outcome}${row.httpStatus === null ? "" : ` · ${row.httpStatus}`}`),
+  }));
+}
+
+/** Map one control snapshot onto the shared menu contract. The helper stays
+ * the authority; rows are display-only except the bounded actions below. */
+export function snapshotItems(
+  snapshot: ControlSnapshot | null,
+  attempts: ReadonlyMap<string, Attempt>,
+  status: { confirmedAgeSeconds: number | null; fresh: boolean; detail?: string | undefined },
+  activity: readonly ActivityRow[] = [],
+  outputs: OutputsView = EMPTY_OUTPUTS,
+  notice: string | null = null,
+): MenuItem[] {
+  const confirmed = snapshot !== null;
+  const age = status.confirmedAgeSeconds;
+  const ageText = age !== null && age < 60 ? `${age}s ago` : `${Math.floor((age ?? 0) / 60)}m ago`;
+  const updated = age === null ? "Control status not confirmed" : status.fresh ? `Updated ${ageText}` : `Last confirmed ${ageText}`;
+  const tail: MenuItem[] = [
+    { kind: "separator" },
+    { kind: "submenu", label: `Outputs · ${outputs.entries.length}`, items: outputItems(outputs) },
+    ...(notice === null ? [] : [{ kind: "label" as const, label: menuLabel(notice) }]),
+    { kind: "label", label: menuLabel(updated) },
+    { kind: "action", id: "refresh", label: "Refresh status" },
+    { kind: "action", id: "open-website", label: "Open Ghostget…" },
+    { kind: "action", id: "support:updates", label: "Get Ghostget updates (free)…" },
+    { kind: "action", id: "support:paid", label: "Support Ghostget development (optional paid)…" },
+    { kind: "submenu", label: "Copy CLI command", items: cliHelpItems() },
+    { kind: "separator" },
+    { kind: "quit", label: "Quit Ghostget" },
+  ];
+  if (!confirmed) {
+    return [
+      { kind: "label", label: "Ghostget control unavailable" },
+      { kind: "label", label: menuLabel(status.detail ?? "The control helper is not running. Requests need the companion open.") },
+      ...tail,
+    ];
+  }
+  const pending = snapshot.approvals.length;
+  const reconnect = snapshot.accounts.filter((account) => account.status === "reconnect-required").length;
+  return [
+    { kind: "label", label: menuLabel(`Ghostget ${snapshot.version}`) },
+    { kind: "label", label: menuLabel(`${snapshot.accounts.length} account${snapshot.accounts.length === 1 ? "" : "s"}${reconnect > 0 ? ` · ${reconnect} need reconnect` : ""} · ${pending} pending approval${pending === 1 ? "" : "s"}`) },
+    { kind: "separator" },
+    { kind: "submenu", label: `Approvals · ${pending}`, items: approvalItems(snapshot.approvals, confirmed) },
+    { kind: "submenu", label: `Accounts · ${snapshot.accounts.length}`, items: accountItems(snapshot, confirmed) },
+    { kind: "submenu", label: "Connect account", items: connectItems(snapshot, attempts, confirmed) },
+    { kind: "submenu", label: "Permissions", items: permissionItems(snapshot, confirmed) },
+    { kind: "submenu", label: `Capabilities · ${snapshot.capabilities.length}`, items: capabilityItems(snapshot.capabilities) },
+    { kind: "submenu", label: `Web rules · ${snapshot.web.rules.length}`, items: webItems(snapshot) },
+    { kind: "submenu", label: `Interfaces · ${snapshot.interfaces.length}`, items: interfaceItems(snapshot) },
+    { kind: "submenu", label: "Recent activity", items: activityItems(activity) },
+    { kind: "label", label: menuLabel(`Vault · 1Password ${snapshot.vault.available ? "available" : "unavailable"}`) },
+    ...tail,
+  ];
+}
+
+/** The Ghostget menu companion owns the control helper's stdio channel and is
+ * a disposable client of it. All reads and mutations use bounded control
+ * requests; the shared runner renders state and enforces revision-checked
+ * dispatch. Failed or indeterminate mutations are never retried. */
+export function companionOptions(
+  environment: ControlEnvironment,
+  openAccountPage: (url: string) => Promise<void> = openBrowser,
+): CompanionOptions {
+  let helper: HelperClient | null = null;
+  let lastSnapshot: ControlSnapshot | null = null;
+  let confirmedAt: number | null = null;
+  let lastOutputs: OutputsView = EMPTY_OUTPUTS;
+  let notice: string | null = null;
+  let openingAccountPage = false;
+  const attempts = new Map<string, Attempt>();
+  const outputsDirectory = join(ghostgetStateHome(environment), "outputs");
+  const client = (): HelperClient => {
+    if (helper === null) helper = spawnHelper(environment);
+    return helper;
+  };
+  const drop = (): void => { helper?.close(); helper = null; };
+  process.once("exit", drop);
+  const request = async (body: ControlRequest, timeoutMs?: number): Promise<ControlResponse> => {
+    const response = await client().request(body, timeoutMs);
+    if (!response.ok && (response.code === "CONTROL_DISCONNECTED" || response.code === "CONTROL_TIMEOUT")) drop();
+    return response;
+  };
+  return {
+    appId: "ghostget",
+    name: "Ghostget",
+    title: "\u{1f47b}",
+    icon: TRAY_ICON,
+    tooltip: "Ghostget · control, outputs and CLI help",
+    stateDir: join(ghostgetStateHome(environment), "menubar"),
+    refreshMs: 5_000,
+    timeoutMs: 90_000,
+    snapshot: async () => {
+      let fresh = false;
+      const response = await request({ action: "snapshot", accountId: null });
+      if (response.ok && response.data.kind === "snapshot") {
+        if (lastSnapshot !== null && response.data.snapshot.policy.revision < lastSnapshot.policy.revision) {
+          // A late or replayed response must never undo newer owner state.
+        } else {
+          lastSnapshot = response.data.snapshot;
+          confirmedAt = Date.now();
+          fresh = true;
+        }
+      }
+      let activity: readonly ActivityRow[] = [];
+      if (fresh) {
+        const page = await request({ action: "activity.query", query: { search: "", method: "all", outcome: "all", origin: null, since: null, order: "newest", cursor: null, limit: 8 } });
+        if (page.ok && page.data.kind === "activity") activity = page.data.page.rows;
+      }
+      lastOutputs = readOutputs(outputsDirectory);
+      return snapshotItems(lastSnapshot, attempts, { confirmedAgeSeconds: confirmedAt === null ? null : Math.max(0, Math.floor((Date.now() - confirmedAt) / 1000)), fresh, detail: response.ok ? undefined : response.message }, activity, lastOutputs, notice);
+    },
+    onAction: async (id) => {
+      if (id === "refresh") { notice = null; return; } // the runner re-reads state after every action
+      if (id === "open-website") { await openBrowser(WEBSITE); return; }
+      if (id === "support:updates" || id === "support:paid") {
+        if (openingAccountPage) return;
+        const action = SUPPORT_ACTIONS.find((item) => item.kind === (id === "support:updates" ? "updates" : "support"));
+        if (action === undefined) return;
+        openingAccountPage = true;
+        notice = null;
+        try { await openAccountPage(action.url); }
+        catch { notice = "Could not open Accounts. Try again from the menu."; }
+        finally { openingAccountPage = false; }
+        return;
+      }
+      if (id === "output:folder") {
+        const expected = lastOutputs.directory;
+        const fresh = (() => { try { return lstatSync(outputsDirectory, { bigint: true }); } catch { return null; } })();
+        if (expected !== null && fresh !== null && fresh.isDirectory() && !fresh.isSymbolicLink() && fresh.dev === expected.dev && fresh.ino === expected.ino) openPath(outputsDirectory, true);
+        return;
+      }
+      if (id.startsWith("output:open:") || id.startsWith("output:reveal:") || id.startsWith("output:copy:")) {
+        const entry = lastOutputs.entries[Number(id.slice(id.indexOf(":", 7) + 1))];
+        const path = entry === undefined ? null : validatedOutputPath(outputsDirectory, lastOutputs, entry.name);
+        if (path === null) { notice = "File changed or unavailable; refresh outputs"; return; }
+        notice = null;
+        if (id.startsWith("output:copy:")) copyText(path);
+        else openPath(path, id.startsWith("output:reveal:"));
+        return;
+      }
+      if (id.startsWith("clip:")) { const command = CLI_COMMANDS[Number(id.slice(5))]; if (command !== undefined) copyText(command); return; }
+      const snapshot = lastSnapshot;
+      if (snapshot === null) return;
+      const parts = id.split(":");
+      const fail = (response: ControlResponse): void => { if (!response.ok) throw new Error(`ghostget-${response.code}`); };
+      if (id === "permission:enable") { fail(await request({ action: "permission.enable", expectedRevision: snapshot.policy.revision })); return; }
+      if (parts[0] === "approval" && parts.length === 3 && (parts[1] === "allow" || parts[1] === "deny")) {
+        const approval = snapshot.approvals.find((item) => item.id === parts[2]);
+        if (approval === undefined) return;
+        fail(await request({ action: "approval.decide", id: approval.id, digest: approval.digest, decision: parts[1] === "allow" ? "allow-once" : "deny" }));
+        return;
+      }
+      if (parts[0] === "disconnect" && parts.length === 2) {
+        const account = snapshot.accounts.find((item) => item.id === parts[1]);
+        if (account === undefined) return;
+        fail(await request({ action: "connection.disconnect", id: account.id, expectedRevision: account.revision }));
+        return;
+      }
+      if (parts[0] === "connect" && parts.length === 3) {
+        const provider = snapshot.connectionProviders.find((item) => item.id === parts[1]);
+        const choice = BROWSERS.find((item) => item.key === parts[2]);
+        if (provider === undefined || choice === undefined) return;
+        const response = await request({ action: "connection.begin", id: `${provider.id}-${randomUUID().slice(0, 8)}`, provider: provider.id, browser: choice.browser, profile: choice.profile, expectedRevision: null });
+        fail(response);
+        if (response.ok && response.data.kind === "connection") attempts.set(response.data.attemptId, { attemptId: response.data.attemptId, title: provider.title, status: "awaiting-sign-in", subject: null });
+        return;
+      }
+      if (parts[0] === "reconnect" && parts.length === 4) {
+        const account = snapshot.accounts.find((item) => item.id === parts[1]);
+        const provider = snapshot.connectionProviders.find((item) => item.id === parts[2]);
+        const choice = BROWSERS.find((item) => item.key === parts[3]);
+        if (account === undefined || provider === undefined || choice === undefined) return;
+        const response = await request({ action: "connection.begin", id: account.id, provider: provider.id, browser: choice.browser, profile: choice.profile, expectedRevision: account.revision });
+        fail(response);
+        if (response.ok && response.data.kind === "connection") attempts.set(response.data.attemptId, { attemptId: response.data.attemptId, title: provider.title, status: "awaiting-sign-in", subject: null });
+        return;
+      }
+      if (parts[0] === "attempt" && parts.length === 3) {
+        const attempt = attempts.get(parts[2]!);
+        if (attempt === undefined) return;
+        if (parts[1] === "cancel") { await request({ action: "connection.cancel", attemptId: attempt.attemptId }); attempts.delete(attempt.attemptId); return; }
+        if (parts[1] === "verify") {
+          const response = await request({ action: "connection.verify", attemptId: attempt.attemptId }, 75_000);
+          if (!response.ok) { attempts.delete(attempt.attemptId); throw new Error(`ghostget-${response.code}`); }
+          if (response.data.kind === "connection" && response.data.status === "verified") attempts.set(attempt.attemptId, { ...attempt, status: "verified", subject: response.data.subject });
+          return;
+        }
+        if (parts[1] === "commit") {
+          if (attempt.status !== "verified" || attempt.subject === null) return;
+          const response = await request({ action: "connection.commit", attemptId: attempt.attemptId, expectedSubject: attempt.subject });
+          attempts.delete(attempt.attemptId);
+          fail(response);
+          return;
+        }
+        return;
+      }
+      if (parts[0] === "permission" && parts.length === 4 && (parts[1] === "allow" || parts[1] === "ask" || parts[1] === "deny")) {
+        const capability = snapshot.capabilities.find((item) => item.adapterId === parts[2] && item.operationId === parts[3]);
+        if (capability === undefined) return;
+        fail(await request({ action: "permission.set", adapterId: capability.adapterId, operationId: capability.operationId, accountId: snapshot.accountId, decision: parts[1], expectedRevision: snapshot.policy.revision, expectedCapabilityDigest: capability.digest }));
+      }
+    },
+  };
+}
+
+/** Delegate the product `menubar` command family to the shared lifecycle. */
+export async function runMenubarCommand(args: readonly string[], environment: ControlEnvironment = process.env, output: Output): Promise<number> {
+  const rest = args.slice(1);
+  if (rest[0] === "--help" || rest[0] === "help" || rest[0] === "-h") {
+    output.stdout("Usage: ghostget menubar [start|stop|status|doctor|install|uninstall]\nRuns the shared menu-bar companion; install registers login startup.\n");
+    return 0;
+  }
+  if (rest.length > 1 || (rest[0] !== undefined && !["start", "stop", "status", "doctor", "install", "uninstall", "--foreground", "--background"].includes(rest[0]))) {
+    output.stderr("Usage: ghostget menubar [start|stop|status|doctor|install|uninstall]\n");
+    return 1;
+  }
+  const mapped = rest[0] === "--background" ? [] : rest;
+  const cli = fileURLToPath(new URL("../cli.ts", import.meta.url));
+  const binary = environment.GHOSTGET_MENUBAR;
+  return await handleCompanionCommand(companionOptions(environment), {
+    args: mapped,
+    ...(binary === undefined || binary === "" ? {} : { binary }),
+    foreground: { executable: process.execPath, args: [cli, "menubar", "--foreground"] },
+    write: (result) => output.stdout(`${JSON.stringify(result)}\n`),
+  });
+}

package/src/control/menubar-icon.ts

@@ -0,0 +1,4 @@
+/** Ghost status mark (U+1F47B), pre-rendered at 32px from Twemoji
+ * (CC-BY 4.0 — https://twemoji.twitter.com). macOS renders the emoji title
+ * natively; icon-only tray surfaces use this art. */
+export const TRAY_ICON = { width: 32, height: 32, rgba: "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" } as const;

package/src/messaging-automation-descriptors.ts

@@ -10,8 +10,15 @@ export function automationPermissionOperation(operation: string): string {
   throw new Error("This messaging action has no admitted host permission.");
 }
 
+const AUTOMATION_SEND_KINDS: Readonly<Record<AutomationProviderId, readonly string[]>> = Object.freeze({
+  imessage: Object.freeze(["text", "attachment", "reaction", "sticker", "link", "poll"]),
+  whatsapp: Object.freeze(["text", "attachment", "reaction", "sticker", "link", "poll"]),
+  // The pinned Beeper local transport admits exact text sends only.
+  beeper: Object.freeze(["text"]),
+});
+
 export function automationOperationDefinitions(provider: AutomationProviderId): readonly LocalCliPluginOperationDefinitionV1[] {
-  const names = ["messaging.automation.read", ...(provider === "whatsapp" ? ["messaging.automation.sync"] : []), ...["text", "attachment", "reaction", "sticker", "link", "poll"].map(kind => `messaging.automation.send.${kind}`)];
+  const names = ["messaging.automation.read", ...(provider === "whatsapp" ? ["messaging.automation.sync"] : []), ...AUTOMATION_SEND_KINDS[provider].map(kind => `messaging.automation.send.${kind}`)];
   return names.map(name => ({
     name, contractVersion: 1, risk: name.endsWith(".read") ? "R1" : name.endsWith(".sync") ? "R2" : "R3",
     input: { properties: {}, required: [] },
@@ -27,3 +34,4 @@ export function automationOperationDefinitions(provider: AutomationProviderId):
 // pinned runtime. The owner permission kernel stays outside provider plugins.
 export function loadImsgAutomationRuntime() { return import("./providers/imessage-automation"); }
 export function loadWhatsAppAutomationRuntime() { return import("./providers/whatsapp-automation"); }
+export function loadBeeperAutomationRuntime() { return import("./providers/beeper-automation"); }