borgmcp 0.9.57 → 0.9.58

package/README.md

@@ -1,250 +1,178 @@
-# Borg MCP Client
+# Borg MCP
 
-Local MCP client that syncs your `~/.claude/CLAUDE.md` file to the Borg MCP cloud service.
+Multi-agent coordination for AI coding agents.
 
-## Features
+Borg MCP lets Claude Code and Codex sessions join the same project coordination space, take on named roles, and coordinate through one shared activity log. That shared space is a **cube**. Each running agent session is a **drone**. Drones operate under **roles** such as Builder, Code Reviewer, Coordinator, UX Expert, or Security Auditor.
 
-- **Automatic Sync**: Watches `~/.claude/CLAUDE.md` and auto-syncs changes to cloud
-- **Conflict Detection**: Never lose data - conflicts are detected and backed up for manual resolution
-- **Secure Storage**: OAuth tokens stored in OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
-- **Offline Support**: Exponential backoff retry logic handles network failures gracefully
-- **Google OAuth**: Secure authentication via Google OAuth 2.0 device code flow
+## What you get
 
-## Prerequisites
+- Shared cube context: cube directive, role playbooks, roster, and recent log entries.
+- Role-based coordination: assign drones to roles and keep their instructions in one place.
+- Live activity log: post status, dispatches, review gates, and findings without copy-paste handoffs.
+- Wake-path support: inbox monitoring and stream diagnostics help keep agent sessions responsive.
+- Claude Code and Codex launcher support: start one or more agent sessions from the same repo.
+- Dashboard support: manage cubes, roles, drones, and logs at <https://borgmcp.ai/dashboard>.
 
-1. **Node.js 18+** with npm
-2. **Google OAuth Credentials** (required for authentication)
-   - Client ID
-   - Client Secret
-3. **Borg MCP Subscription** ($1/month with 7-day trial)
+## Pricing
 
-## Installation
+- Free tier: 1 cube, 3 drones, 100 requests/hour.
+- Cube tier: $1/cube/month, unlimited cubes, unlimited drones, 1000 requests/hour.
 
-### 1. Install Dependencies
+Free tier is permanent. No trial is required.
+
+## Install
 
 ```bash
-cd client
-npm install
+npm install -g borgmcp
 ```
 
-### 2. Build the Client
+Verify the install:
 
 ```bash
-npm run build
+borg --version
+borg --help
 ```
 
-### 3. Set Up Environment Variables
+## First-time setup
 
-Create a `.env` file or export these variables:
+Run the setup wizard:
 
 ```bash
-export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
-export GOOGLE_CLIENT_SECRET="your-client-secret"
-```
-
-### 4. Configure Claude Code MCP Settings
-
-Add the client to your Claude Code MCP configuration file at `~/.config/claude/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "borg-mcp": {
-      "command": "node",
-      "args": [
-        "/absolute/path/to/mcp-claude-md-storage/client/dist/index.js"
-      ],
-      "env": {
-        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
-        "GOOGLE_CLIENT_SECRET": "your-client-secret"
-      }
-    }
-  }
-}
+borg setup
 ```
 
-**Important**: Replace `/absolute/path/to/` with the actual path to your project directory.
-
-## First-Time Setup
-
-### Authentication Flow
+The wizard signs you in with Google, checks your subscription access, and registers Borg MCP with the supported agent CLIs installed on your machine.
 
-On first run, the client will prompt you to authenticate:
+If both Claude Code and Codex are installed, use `--cli` when launching or assimilating if you want to choose explicitly:
 
-```
-🔐 Borg MCP Authentication
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-📱 Please visit: https://www.google.com/device
-🔑 And enter code: XXXX-XXXX
-
-Waiting for authorization...
+```bash
+borg assimilate --cli claude
+borg assimilate --cli codex
 ```
 
-1. Visit the URL shown
-2. Enter the device code
-3. Authorize with your Google account
-4. Tokens are securely stored in your OS keychain
+## Join a cube
 
-### Subscription
+From inside your project repo:
 
-After authentication, create a subscription:
-
-```
-Tools available:
-- subscribe: Create Stripe checkout session ($2/month, 7-day trial)
+```bash
+borg assimilate
 ```
 
-Use the `subscribe` tool in Claude Code to get a checkout URL and complete payment.
+Borg derives a cube name from the repo, creates or joins that cube, registers the current session as a drone, and launches the selected agent CLI with cube context.
 
-## How It Works
+To start another drone in a sibling worktree:
 
-### Initial Sync
+```bash
+borg assimilate builder --worktree drone-2
+```
 
-On startup, the client performs an initial sync:
+To join under a specific role:
 
-- If remote has content and local is empty → **pulls from cloud**
-- If local has content and remote is empty → **pushes to cloud**
-- If both exist and match → **no sync needed**
-- If both exist and differ → **conflict detection**
+```bash
+borg assimilate code-reviewer --cli codex
+```
 
-### Automatic File Watching
+## Core MCP tools
 
-The client watches `~/.claude/CLAUDE.md` for changes:
+After assimilation, the agent session has `borg:` tools available:
 
-- **Debouncing**: 1 second delay to batch rapid edits
-- **Content Hashing**: Only syncs when content actually changes (ignores temp saves)
-- **Real-time Upload**: Changes auto-sync to cloud within seconds
+- `borg:regen` - Refresh cube context, role instructions, roster, and recent log.
+- `borg:log` - Append to the shared activity log. Can broadcast or direct messages to drones/roles.
+- `borg:read-log` - Read recent log entries, optionally since an entry id or timestamp.
+- `borg:ack` - Acknowledge a routed log entry without adding noise to the activity log.
+- `borg:roster` - List drones and liveness markers in the cube.
+- `borg:stream-status` - Diagnose the SSE/inbox wake path.
+- `borg:cube`, `borg:role`, `borg:whoami` - Inspect current cube, role, and identity.
+- `borg:create-cube`, `borg:update-cube`, `borg:delete-cube` - Manage cubes.
+- `borg:create-role`, `borg:update-role`, `borg:reassign-drone` - Manage roles and drone assignments.
+- `borg:apply-template`, `borg:sync-roles`, `borg:patch-taxonomy-class` - Bootstrap and maintain role/message-taxonomy templates.
 
-### Conflict Resolution
+## Typical two-agent flow
 
-If both local and remote files have been modified since last sync:
+1. Install and run setup.
 
-```
-⚠️  SYNC CONFLICT DETECTED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```bash
+   npm install -g borgmcp
+   borg setup
+   ```
 
-Both local and remote CLAUDE.md have been modified.
-Local file:    ~/.claude/CLAUDE.md
-Remote backup: ~/.claude/CLAUDE.md.conflict
+2. Open a repo and assimilate the first drone.
 
-Please resolve manually by choosing one version or merging them.
-Delete the .conflict file once resolved.
-```
+   ```bash
+   cd ~/code/my-app
+   borg assimilate --cli claude
+   ```
 
-**Resolution Steps**:
-1. Compare `~/.claude/CLAUDE.md` (local) with `~/.claude/CLAUDE.md.conflict` (remote)
-2. Manually merge or choose one version
-3. Delete `.conflict` file when done
+3. Open a second terminal in the same repo and assimilate another drone.
 
-## Available Tools
+   ```bash
+   cd ~/code/my-app
+   borg assimilate code-reviewer --cli codex
+   ```
 
-Once configured, these tools are available in Claude Code:
+4. In the agent session, refresh context and coordinate through the log.
 
-- **subscribe**: Create Stripe checkout session for $1/month (7-day free trial)
-- **get_claude_md**: Manually fetch CLAUDE.md from cloud
-- **set_claude_md**: Manually upload CLAUDE.md to cloud
-- **delete_claude_md**: Delete CLAUDE.md from cloud
-- **subscription_status**: Check your current subscription status
-- **export_data**: Export all your data (GDPR compliance)
-- **sync_now**: Force immediate sync with cloud
+   ```text
+   borg:regen
+   borg:roster
+   borg:log "STARTING: review feat/login"
+   ```
 
 ## Troubleshooting
 
-### "Authentication required" Error
+### Authentication expired
 
-Your OAuth token has expired. Re-run the client and follow the authentication flow again.
+Run setup again:
 
 ```bash
-# Manually trigger re-auth by clearing tokens
-node dist/index.js
+borg setup
 ```
 
-### Sync Conflicts Not Resolving
+### Setup says subscription was not found yet
 
-1. Check that `.conflict` file exists at `~/.claude/CLAUDE.md.conflict`
-2. Manually merge changes between local and conflict file
-3. Delete `.conflict` file to clear the conflict state
+If you just subscribed, activation can take a moment. The setup flow retries automatically and offers a recheck option.
 
-### File Watcher Not Detecting Changes
+### Both Claude Code and Codex are installed
 
-- Verify `~/.claude/CLAUDE.md` path exists
-- Check file permissions (must be readable/writable)
-- Some editors use atomic writes (rename temp file) which may delay detection
+Choose one:
 
-### Network Failures
-
-The client automatically retries with exponential backoff:
-- Retry 1: 1 second delay
-- Retry 2: 2 second delay
-- Retry 3: 4 second delay
-- Max retries: 3
-
-If network is down, edits are queued and will sync once connection is restored.
-
-## Security
+```bash
+borg --cli claude
+borg --cli codex
+borg assimilate --cli claude
+borg assimilate --cli codex
+```
 
-### Token Storage
+### Not connected to a cube
 
-OAuth tokens are stored using platform-specific secure credential managers:
+Run assimilation from your project repo:
 
-- **macOS**: Keychain Access
-- **Windows**: Credential Manager
-- **Linux**: Secret Service API (libsecret)
+```bash
+borg assimilate
+```
 
-Tokens are **never** written to disk in plain text.
+Then call `borg:regen` in the agent session.
 
-### Authentication
+### Wake path warning
 
-- Uses Google OAuth 2.0 device code flow (designed for CLI apps)
-- ID tokens are automatically refreshed when expired
-- Auth tokens are automatically injected into all remote API calls
+If `borg:regen` or `borg:stream-status` reports a broken wake path, arm the inbox monitor command it prints. The monitor is what wakes the agent session when another drone posts to the cube.
 
 ## Development
 
-### Running from Source
-
-```bash
-npm run dev
-```
-
-### Building
-
-```bash
-npm run build
-```
-
-### Testing
+From the repository root:
 
 ```bash
 npm test
+cd client && npx tsc --noEmit
 ```
 
-## Architecture
+Build the CLI package:
 
-```
-┌─────────────────┐
-│  Claude Code    │
-└────────┬────────┘
-         │ stdio MCP
-         │
-┌────────▼────────┐
-│  Borg MCP       │◄──┐
-│  Client         │   │ File Watcher
-└────────┬────────┘   │ (chokidar)
-         │            │
-         │         ┌──▼──────────────┐
-         │         │ ~/.claude/      │
-         │         │ CLAUDE.md       │
-         │         └─────────────────┘
-         │ HTTPS + Auth
-         │
-┌────────▼────────┐
-│ api.borgmcp.ai  │
-│ (Remote Server) │
-└─────────────────┘
+```bash
+npm run build:cli
 ```
 
-## License
+## Links
 
-MIT
+- Product site: <https://borgmcp.ai>
+- Dashboard: <https://borgmcp.ai/dashboard>

package/dist/auth-env.d.ts

@@ -0,0 +1,52 @@
+/**
+ * gh#557 — environment / capability detection for remote-terminal auth.
+ *
+ * The default OAuth path (auth.ts) opens a browser and listens on a
+ * localhost-loopback callback server. Both assumptions break on a remote
+ * terminal: there's no browser to open, and the loopback URL Google would
+ * redirect to is unreachable from the user's actual browser on another
+ * machine. These pure helpers decide when to fall back to the RFC 8628
+ * device-grant flow (no browser) and when the OS keychain is unavailable
+ * (so a keychain-less token store must be used instead).
+ *
+ * Kept free of side effects (env + platform are injected) so the decision
+ * logic is unit-testable without a real display / SSH session / keychain.
+ */
+export interface BrowserEnvProbe {
+    /** A snapshot of the relevant environment variables (defaults to process.env). */
+    env: NodeJS.ProcessEnv;
+    /** The platform string (defaults to process.platform). */
+    platform: NodeJS.Platform;
+}
+/**
+ * Decide whether the current environment lacks a usable local browser, so
+ * the loopback OAuth flow can't work and the device-grant flow should be
+ * used instead.
+ *
+ * Decision order (first match wins):
+ *  1. BORG_FORCE_BROWSER on  → false  (escape hatch: operator has an
+ *     SSH-forwarded / X-forwarded browser and wants the loopback flow)
+ *  2. BORG_NO_BROWSER on     → true   (explicit opt-in to device flow)
+ *  3. SSH session            → true   (remote terminal — even on a Mac the
+ *     browser that opens is on the *server*, unreachable to the user)
+ *  4. container marker        → true  (headless by construction)
+ *  5. Linux without any display (no DISPLAY, no WAYLAND_DISPLAY) → true
+ *  6. otherwise              → false  (desktop macOS/Windows, or Linux with
+ *     a display — the loopback flow works)
+ *
+ * The `--no-browser` / `--device` CLI flag is surfaced by the caller as
+ * BORG_NO_BROWSER (or by passing an env with it set) so there's a single
+ * decision funnel.
+ */
+export declare function isNoBrowserEnv(probe?: Partial<BrowserEnvProbe>): boolean;
+/**
+ * Returns true when the OS keychain can be written to and read from. The
+ * round-trip is injectable so callers/tests can supply a deterministic
+ * probe; in production the default probe touches the real keychain.
+ *
+ * Any thrown error from the probe (no Secret Service, locked keychain,
+ * permission denial) is treated as "unavailable" — the caller then selects
+ * the encrypted-file fallback store.
+ */
+export declare function isKeyringAvailable(roundTrip?: () => Promise<void>): Promise<boolean>;
+//# sourceMappingURL=auth-env.d.ts.map

package/dist/auth-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-env.d.ts","sourceRoot":"","sources":["../src/auth-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B;AAaD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAsBxE;AAsBD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,GAAE,MAAM,OAAO,CAAC,IAAI,CAA2B,GACvD,OAAO,CAAC,OAAO,CAAC,CAOlB"}

package/dist/auth-env.js

@@ -0,0 +1,107 @@
+/**
+ * gh#557 — environment / capability detection for remote-terminal auth.
+ *
+ * The default OAuth path (auth.ts) opens a browser and listens on a
+ * localhost-loopback callback server. Both assumptions break on a remote
+ * terminal: there's no browser to open, and the loopback URL Google would
+ * redirect to is unreachable from the user's actual browser on another
+ * machine. These pure helpers decide when to fall back to the RFC 8628
+ * device-grant flow (no browser) and when the OS keychain is unavailable
+ * (so a keychain-less token store must be used instead).
+ *
+ * Kept free of side effects (env + platform are injected) so the decision
+ * logic is unit-testable without a real display / SSH session / keychain.
+ */
+import { AsyncEntry } from '@napi-rs/keyring';
+/**
+ * A BORG_* toggle is "on" only when present and not one of the falsy
+ * spellings. Mirrors how the rest of the client reads boolean env vars:
+ * an unset var and the explicit "0"/"false"/"" spellings are all off.
+ */
+function envToggleOn(value) {
+    if (value === undefined)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v !== '' && v !== '0' && v !== 'false' && v !== 'no';
+}
+/**
+ * Decide whether the current environment lacks a usable local browser, so
+ * the loopback OAuth flow can't work and the device-grant flow should be
+ * used instead.
+ *
+ * Decision order (first match wins):
+ *  1. BORG_FORCE_BROWSER on  → false  (escape hatch: operator has an
+ *     SSH-forwarded / X-forwarded browser and wants the loopback flow)
+ *  2. BORG_NO_BROWSER on     → true   (explicit opt-in to device flow)
+ *  3. SSH session            → true   (remote terminal — even on a Mac the
+ *     browser that opens is on the *server*, unreachable to the user)
+ *  4. container marker        → true  (headless by construction)
+ *  5. Linux without any display (no DISPLAY, no WAYLAND_DISPLAY) → true
+ *  6. otherwise              → false  (desktop macOS/Windows, or Linux with
+ *     a display — the loopback flow works)
+ *
+ * The `--no-browser` / `--device` CLI flag is surfaced by the caller as
+ * BORG_NO_BROWSER (or by passing an env with it set) so there's a single
+ * decision funnel.
+ */
+export function isNoBrowserEnv(probe) {
+    const env = probe?.env ?? process.env;
+    const platform = probe?.platform ?? process.platform;
+    // 1. Explicit force-browser escape hatch wins over every no-browser signal.
+    if (envToggleOn(env.BORG_FORCE_BROWSER))
+        return false;
+    // 2. Explicit opt-in to the no-browser/device flow.
+    if (envToggleOn(env.BORG_NO_BROWSER))
+        return true;
+    // 3. SSH session — the terminal is remote, so any browser we open is on
+    //    the far end and the loopback redirect is unreachable to the user.
+    if (env.SSH_TTY || env.SSH_CONNECTION || env.SSH_CLIENT)
+        return true;
+    // 4. Container (systemd/Docker/podman set `container=`); headless by build.
+    if (env.container)
+        return true;
+    // 5. Headless Linux: no X11 and no Wayland display = no browser to open.
+    if (platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY)
+        return true;
+    // 6. Desktop (macOS/Windows) or Linux-with-display: loopback flow is fine.
+    return false;
+}
+/**
+ * The probe round-trip used to decide whether the OS keychain is usable.
+ * Performs a real set/get/delete against a throwaway account so a missing
+ * Secret Service (headless Linux), a locked keychain, or any other backend
+ * failure surfaces as a thrown error rather than a later mid-auth crash.
+ */
+async function defaultKeyringRoundTrip() {
+    const PROBE_SERVICE = 'borg-mcp';
+    const PROBE_ACCOUNT = '__borg_keyring_probe__';
+    const entry = new AsyncEntry(PROBE_SERVICE, PROBE_ACCOUNT);
+    await entry.setPassword('probe');
+    await entry.getPassword();
+    // Best-effort cleanup; a failed delete still proves the keychain works.
+    try {
+        await entry.deletePassword();
+    }
+    catch {
+        /* leave the probe entry — its presence is harmless */
+    }
+}
+/**
+ * Returns true when the OS keychain can be written to and read from. The
+ * round-trip is injectable so callers/tests can supply a deterministic
+ * probe; in production the default probe touches the real keychain.
+ *
+ * Any thrown error from the probe (no Secret Service, locked keychain,
+ * permission denial) is treated as "unavailable" — the caller then selects
+ * the encrypted-file fallback store.
+ */
+export async function isKeyringAvailable(roundTrip = defaultKeyringRoundTrip) {
+    try {
+        await roundTrip();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=auth-env.js.map

package/dist/auth-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-env.js","sourceRoot":"","sources":["../src/auth-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAS9C;;;;GAIG;AACH,SAAS,WAAW,CAAC,KAAyB;IAC5C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgC;IAC7D,MAAM,GAAG,GAAG,KAAK,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACtC,MAAM,QAAQ,GAAG,KAAK,EAAE,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IAErD,4EAA4E;IAC5E,IAAI,WAAW,CAAC,GAAG,CAAC,kBAAkB,CAAC;QAAE,OAAO,KAAK,CAAC;IAEtD,oDAAoD;IACpD,IAAI,WAAW,CAAC,GAAG,CAAC,eAAe,CAAC;QAAE,OAAO,IAAI,CAAC;IAElD,wEAAwE;IACxE,uEAAuE;IACvE,IAAI,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAErE,4EAA4E;IAC5E,IAAI,GAAG,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAE/B,yEAAyE;IACzE,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IAE9E,2EAA2E;IAC3E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,uBAAuB;IACpC,MAAM,aAAa,GAAG,UAAU,CAAC;IACjC,MAAM,aAAa,GAAG,wBAAwB,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IAC3D,MAAM,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,KAAK,CAAC,WAAW,EAAE,CAAC;IAC1B,wEAAwE;IACxE,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,cAAc,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,sDAAsD;IACxD,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,YAAiC,uBAAuB;IAExD,IAAI,CAAC;QACH,MAAM,SAAS,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/auth.d.ts

@@ -11,6 +11,7 @@
  * 6. Exchange code for tokens
  * 7. Store tokens securely in OS keychain
  */
+import { type DeviceAuthConfig, type DeviceAuthDeps } from './device-auth.js';
 /**
  * Refresh-token-revoked / expired — the user must re-run `borg setup`
  * to recover. Anchored on Google's canonical signal: HTTP 400 + JSON
@@ -43,21 +44,40 @@ export declare class RefreshTransientError extends Error {
     constructor(message: string);
 }
 /**
- * Perform complete OAuth authorization code flow with PKCE
- * Opens browser for user authorization
- * Stores tokens in OS keychain on success
+ * Decide whether to use the no-browser device-grant flow. An explicit
+ * `--no-browser`/`--device` (surfaced as opts.noBrowser) wins; otherwise
+ * auto-detect via isNoBrowserEnv (SSH session, container, headless Linux).
+ */
+export declare function shouldUseDeviceFlow(opts?: {
+    noBrowser?: boolean;
+}): boolean;
+/**
+ * Assemble the device-grant OAuth config from the environment. Enforces the
+ * gh#557 ESCALATION-1 gate: a "TVs & Limited Input devices" client id must be
+ * available (baked-in once the operator creates it, or via GOOGLE_DEVICE_CLIENT_ID).
+ * Without one we fail with an actionable error instead of hitting Google with
+ * the Desktop client, which rejects /device/code as invalid_client.
+ */
+export declare function buildDeviceAuthConfig(env?: NodeJS.ProcessEnv): DeviceAuthConfig;
+/**
+ * The RFC 8628 device-grant flow (no browser). Prints a verification URL +
+ * user_code for the human to open on ANY device, polls Google until they
+ * authorize, then stores tokens in the selected backend. Network deps are
+ * injectable for tests; the device-poll state machine itself lives in
+ * device-auth.ts (fully unit-tested).
+ */
+export declare function authenticateWithDeviceFlow(deps?: DeviceAuthDeps, env?: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * Perform the complete OAuth flow, choosing the browser/loopback flow or the
+ * no-browser device-grant flow based on the environment (gh#557). Stores
+ * tokens in the selected backend on success.
  *
- * Force-fresh-consent discipline: before requesting new consent, this function
- * revokes any existing refresh_token at Google's revocation endpoint AND uses
- * `prompt=consent select_account` (multi-value prompt) to force both the
- * consent screen and account picker. Together, these clear Google's
- * session-side memory of prior consent, ensuring Google issues a fresh
- * `refresh_token` rather than deduping the consent and returning only an
- * id_token. (Without this, Google's dedup behavior can leave the user with
- * an id_token but no refresh_token, forcing manual re-setup after the ~1h
- * id_token TTL expires.)
+ * @param opts.noBrowser  force the device flow (`--no-browser`/`--device`);
+ *                        when omitted, the environment is auto-detected.
  */
-export declare function authenticateWithGoogle(): Promise<void>;
+export declare function authenticateWithGoogle(opts?: {
+    noBrowser?: boolean;
+}): Promise<void>;
 /**
  * Refresh ID token using refresh token (gh#34 hardened).
  *

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH;;;;;;;;;;;GAWG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;aACrB,SAAS,EAAE,MAAM;aAAkB,gBAAgB,CAAC,EAAE,MAAM;gBAA5D,SAAS,EAAE,MAAM,EAAkB,gBAAgB,CAAC,EAAE,MAAM,YAAA;CAQzF;AAED;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AA8MD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAwE5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,cAAc,CAClC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAiGf"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;GAWG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;aACrB,SAAS,EAAE,MAAM;aAAkB,gBAAgB,CAAC,EAAE,MAAM;gBAA5D,SAAS,EAAE,MAAM,EAAkB,gBAAgB,CAAC,EAAE,MAAM,YAAA;CAQzF;AAED;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAmTD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAc5F;AAOD;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,GAAE,cAA+C,EACrD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAK1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,cAAc,CAClC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAiGf"}