grokbot-control 0.0.0-stage → 0.1.3

package/dist/auth/store.d.ts

@@ -0,0 +1,25 @@
+import { type LockWaitOptions } from "./lock.js";
+import type { AuthKind, PendingLogin, StoredCredential } from "./types.js";
+export declare function credentialsDir(): string;
+export declare function redactCredential(c: StoredCredential): Omit<StoredCredential, "access_token" | "refresh_token"> & {
+    access_token: string;
+    refresh_token?: string;
+};
+export declare class FileCredentialStore {
+    credFile(kind: AuthKind, backend: string): string;
+    pendingFile(kind: AuthKind, backend: string): string;
+    load(kind: AuthKind, backend: string): StoredCredential | undefined;
+    save(cred: StoredCredential): void;
+    /**
+     * CAS save: only write when on-disk revision matches expectedRevision (undefined/0 = absent or legacy).
+     * Returns false without writing when revision diverged (logout / new login / peer refresh).
+     */
+    saveIfRevision(cred: StoredCredential, expectedRevision: number | undefined): boolean;
+    clear(kind: AuthKind, backend: string): boolean;
+    loadPending(kind: AuthKind, backend: string): PendingLogin | undefined;
+    savePending(p: PendingLogin): void;
+    clearPending(kind: AuthKind, backend: string): boolean;
+}
+/** Separate permanent native locks for refresh exchange and short credential mutations. */
+export declare function withCredentialLock<T>(lockKey: string, fn: () => Promise<T>, options?: number | LockWaitOptions): Promise<T>;
+export declare const withRefreshLock: typeof withCredentialLock;

package/dist/auth/store.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { withAdvisoryLock } from "./lock.js";
+export function credentialsDir() {
+    return process.env.GBT_CREDENTIALS_DIR?.trim() || path.join(os.homedir(), ".gbc");
+}
+function key(kind, backend) {
+    return Buffer.from(`${kind}|${backend}`).toString("base64url");
+}
+function ensureDir() {
+    const dir = credentialsDir();
+    fs.mkdirSync(dir, { mode: 0o700, recursive: true });
+    try {
+        fs.chmodSync(dir, 0o700);
+    }
+    catch {
+        /* best effort */
+    }
+    return dir;
+}
+/** Atomic 0600 JSON write (tmp + rename). */
+function writeSecretJson(file, data) {
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, file);
+}
+export function redactCredential(c) {
+    return {
+        ...c,
+        access_token: c.access_token ? "[redacted]" : "",
+        refresh_token: c.refresh_token ? "[redacted]" : undefined,
+    };
+}
+export class FileCredentialStore {
+    credFile(kind, backend) {
+        return path.join(credentialsDir(), `cred-${key(kind, backend)}.json`);
+    }
+    pendingFile(kind, backend) {
+        return path.join(credentialsDir(), `pending-${key(kind, backend)}.json`);
+    }
+    load(kind, backend) {
+        const f = this.credFile(kind, backend);
+        if (!fs.existsSync(f))
+            return undefined;
+        const raw = JSON.parse(fs.readFileSync(f, "utf8"));
+        if (raw.kind !== kind || raw.backend !== backend) {
+            throw new Error("credential kind/backend mismatch — refusing to use");
+        }
+        return raw;
+    }
+    save(cred) {
+        ensureDir();
+        writeSecretJson(this.credFile(cred.kind, cred.backend), cred);
+    }
+    /**
+     * CAS save: only write when on-disk revision matches expectedRevision (undefined/0 = absent or legacy).
+     * Returns false without writing when revision diverged (logout / new login / peer refresh).
+     */
+    saveIfRevision(cred, expectedRevision) {
+        const cur = this.load(cred.kind, cred.backend);
+        const curRev = cur?.revision ?? 0;
+        const exp = expectedRevision ?? 0;
+        if (cur && curRev !== exp)
+            return false;
+        if (!cur && exp !== 0)
+            return false;
+        this.save(cred);
+        return true;
+    }
+    clear(kind, backend) {
+        const f = this.credFile(kind, backend);
+        if (!fs.existsSync(f))
+            return false;
+        fs.unlinkSync(f);
+        return true;
+    }
+    loadPending(kind, backend) {
+        const f = this.pendingFile(kind, backend);
+        if (!fs.existsSync(f))
+            return undefined;
+        const raw = JSON.parse(fs.readFileSync(f, "utf8"));
+        if (raw.v !== 1 || raw.kind !== kind || raw.backend !== backend) {
+            throw new Error("pending login kind/backend mismatch — refusing to use");
+        }
+        return raw;
+    }
+    savePending(p) {
+        ensureDir();
+        writeSecretJson(this.pendingFile(p.kind, p.backend), p);
+    }
+    clearPending(kind, backend) {
+        const f = this.pendingFile(kind, backend);
+        if (!fs.existsSync(f))
+            return false;
+        fs.unlinkSync(f);
+        return true;
+    }
+}
+/** Separate permanent native locks for refresh exchange and short credential mutations. */
+export async function withCredentialLock(lockKey, fn, options = 30_000) {
+    const lock = path.join(ensureDir(), `refresh-${Buffer.from(lockKey).toString("base64url")}.lock`);
+    return withAdvisoryLock(lock, fn, typeof options === "number" ? { waitMs: options } : options);
+}
+export const withRefreshLock = withCredentialLock;

package/dist/auth/types.d.ts

@@ -0,0 +1,138 @@
+export type AuthKind = "cursor" | "xai";
+/** How the local credential was obtained. */
+export type LoginKind = "browser_deep_control" | "static" | "unknown";
+/** Last writer of the stored credential pair. */
+export type CredentialSource = "login_poll" | "refresh" | "migrated" | "static";
+/**
+ * Disk credential. Tokens never leave AuthOps/CLI/MCP envelopes.
+ * Provenance fields bind refresh to a backend/client; old files without them
+ * require GBT_OAUTH_CLIENT_ID and/or GBT_AUTH_CONFIRM_MIGRATE=1.
+ */
+export type StoredCredential = {
+    kind: AuthKind;
+    /** Backend base URL this credential is bound to. */
+    backend: string;
+    access_token: string;
+    refresh_token?: string;
+    /** From JWT `exp` when present and finite. */
+    expires_at_ms?: number;
+    account_label?: string;
+    updated_at_ms: number;
+    /** Monotonic CAS counter; bumps on every successful save under the credential lock. */
+    revision?: number;
+    refresh_cooldown_until_ms?: number;
+    login_kind?: LoginKind;
+    credential_source?: CredentialSource;
+    /** Origin+path of the refresh POST (e.g. https://api2.cursor.sh/oauth/token). */
+    refresh_endpoint?: string;
+    /** Public OAuth client_id bound at login/refresh; never guessed from JWT. */
+    client_id?: string;
+    /** Optional JWT iss (display/binding only; unverified). */
+    issuer?: string;
+    /** Optional JWT sub (account subject binding). */
+    account_subject?: string;
+    /** Local session binding id; changes on each completed login. */
+    session_id?: string;
+};
+/** Pending browser login (0600 file, expires). Contains the secret verifier — never print. */
+export type PendingLogin = {
+    v: 1;
+    kind: AuthKind;
+    backend: string;
+    website: string;
+    uuid: string;
+    verifier: string;
+    redirect_target: string;
+    created_at_ms: number;
+    expires_at_ms: number;
+};
+/** Safe to print: no verifier / tokens. */
+export type AuthBeginResult = {
+    authorization_url: string;
+    uuid: string;
+    expires_at_ms: number;
+    note: string;
+};
+export type AuthCompleteResult = {
+    status: "completed";
+    kind: AuthKind;
+    backend: string;
+    account_label?: string;
+    expires_at_ms?: number;
+    revision?: number;
+    session_id?: string;
+} | {
+    status: "pending";
+    expires_at_ms: number;
+    note: string;
+};
+export type RefreshReason = "forced" | "near_expiry" | "missing_exp" | "illegal_exp" | "already_fresh" | "peer_refreshed";
+/** Non-secret refresh outcome for CLI/MCP/AuthOps. */
+export type RefreshResult = {
+    refreshed: boolean;
+    reason: RefreshReason;
+    kind: AuthKind;
+    backend: string;
+    expires_at_ms?: number;
+    revision: number;
+    account_label?: string;
+    session_id?: string;
+    credential_source?: CredentialSource;
+    login_kind?: LoginKind;
+    client_id_bound: boolean;
+    refresh_endpoint?: string;
+    note?: string;
+};
+export type WhoamiLocal = {
+    kind: AuthKind;
+    backend: string;
+    account_label?: string;
+    has_token: boolean;
+    expires_at_ms?: number;
+    refresh_configured: boolean;
+    pending_login: boolean;
+    revision?: number;
+    session_id?: string;
+    credential_source?: CredentialSource;
+    login_kind?: LoginKind;
+    client_id_bound: boolean;
+    refresh_endpoint?: string;
+    disk_refresh: boolean;
+    static_token: boolean;
+};
+export type AuthProvider = {
+    kind: AuthKind;
+    backend: string;
+    getAccessToken(opts?: {
+        force?: boolean;
+    }): Promise<string | undefined>;
+    /** Start independent browser login; persists pending state (0600). */
+    beginLogin(): Promise<AuthBeginResult>;
+    /** Single poll attempt against the persisted pending login. */
+    pollLogin(): Promise<AuthCompleteResult>;
+    /** Poll until completed, timeout, cancel or 3 consecutive non-404 failures. */
+    completeLogin(opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<AuthCompleteResult>;
+    cancelLogin(): Promise<{
+        had_pending: boolean;
+    }>;
+    /**
+     * Refresh when near expiry / missing exp, or when force=true. Never prints tokens.
+     * `rejectedAccessToken`: on 401 recovery, pass the bearer the server rejected; if disk
+     * already has a different access token, adopt it without another force rotation.
+     */
+    refresh(opts?: {
+        force?: boolean;
+        signal?: AbortSignal;
+        rejectedAccessToken?: string;
+    }): Promise<RefreshResult>;
+    /** Local only: removes this tool's own credential + pending files. Does not revoke server-side. */
+    logout(): Promise<{
+        removed_credential: boolean;
+        removed_pending: boolean;
+    }>;
+    /** Pure: no network. */
+    whoamiLocal(): Promise<WhoamiLocal>;
+};

package/dist/auth/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/config.d.ts

@@ -0,0 +1,26 @@
+import type { AuthKind } from "../auth/types.js";
+import { ControlPlane } from "../ops/plane.js";
+import type { MockState } from "../testing/mock-transport.js";
+export type CliGlobal = {
+    json: boolean;
+    allowWrites: boolean;
+    dryRun: boolean;
+    baseUrl: string;
+    authKind: AuthKind;
+    mock: boolean;
+    trustBackend: boolean;
+};
+export declare function parseGlobals(argv: string[]): {
+    globals: CliGlobal;
+    rest: string[];
+};
+/**
+ * Value flag lookup. `--x=value` always takes value verbatim (use this form for
+ * values beginning with "-"). `--x value` form: a missing value or a next token
+ * starting with "--" is a usage error (exit 2) — never swallow the next flag.
+ */
+export declare function flag(rest: string[], name: string): string | undefined;
+export declare function hasFlag(rest: string[], name: string): boolean;
+export declare function buildPlane(globals: CliGlobal): ControlPlane;
+export declare function persistMockState(): void;
+export declare function getMockState(): MockState | undefined;

package/dist/cli/config.js

@@ -0,0 +1,98 @@
+import { GbcError } from "../errors.js";
+import { createAuthProvider, staticTokenProvider } from "../auth/provider.js";
+import { ControlPlane } from "../ops/plane.js";
+import { createMockTransport } from "../testing/mock-transport.js";
+import { loadMockState, saveMockState } from "../testing/mock-persist.js";
+export function parseGlobals(argv) {
+    const globals = {
+        json: false,
+        allowWrites: false,
+        dryRun: false,
+        baseUrl: process.env.GBT_BASE_URL || "https://api2.cursor.sh",
+        authKind: process.env.GBT_AUTH_KIND || "cursor",
+        mock: process.env.GBT_MOCK === "1",
+        trustBackend: process.env.GBT_TRUST_BACKEND === "1",
+    };
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--json")
+            globals.json = true;
+        else if (a === "--allow-writes")
+            globals.allowWrites = true;
+        else if (a === "--dry-run")
+            globals.dryRun = true;
+        else if (a === "--mock")
+            globals.mock = true;
+        else if (a === "--trust-backend")
+            globals.trustBackend = true;
+        else if (a === "--base-url")
+            globals.baseUrl = argv[++i] || "";
+        else if (a.startsWith("--base-url="))
+            globals.baseUrl = a.slice("--base-url=".length);
+        else if (a === "--auth-kind")
+            globals.authKind = argv[++i] || "cursor";
+        else if (a.startsWith("--auth-kind="))
+            globals.authKind = a.slice("--auth-kind=".length);
+        else
+            rest.push(a);
+    }
+    return { globals, rest };
+}
+/**
+ * Value flag lookup. `--x=value` always takes value verbatim (use this form for
+ * values beginning with "-"). `--x value` form: a missing value or a next token
+ * starting with "--" is a usage error (exit 2) — never swallow the next flag.
+ */
+export function flag(rest, name) {
+    const pref = rest.find((x) => x.startsWith(`${name}=`));
+    if (pref !== undefined)
+        return pref.slice(name.length + 1);
+    const idx = rest.indexOf(name);
+    if (idx < 0)
+        return undefined;
+    const v = rest[idx + 1];
+    if (v === undefined || v.startsWith("--")) {
+        throw new GbcError("usage", `${name} requires a value`, {
+            exitCode: 2,
+            hint: `pass ${name} <value>, or ${name}=<value> for values starting with "-"`,
+        });
+    }
+    return v;
+}
+export function hasFlag(rest, name) {
+    return rest.includes(name) || rest.some((x) => x.startsWith(`${name}=`));
+}
+let sharedMockState;
+export function buildPlane(globals) {
+    if (globals.mock) {
+        sharedMockState ??= loadMockState();
+        return new ControlPlane({
+            baseUrl: "mock://gbc",
+            transport: createMockTransport(sharedMockState),
+            simulated: true,
+            auth: staticTokenProvider({
+                kind: globals.authKind,
+                backend: globals.baseUrl,
+                accessToken: "mock-token",
+            }),
+        });
+    }
+    const auth = createAuthProvider({
+        kind: globals.authKind,
+        backend: globals.baseUrl,
+        trustCustomBackend: globals.trustBackend,
+    });
+    return new ControlPlane({
+        baseUrl: globals.baseUrl,
+        auth,
+        simulated: false,
+    });
+}
+export function persistMockState() {
+    if (sharedMockState)
+        saveMockState(sharedMockState);
+}
+export function getMockState() {
+    return sharedMockState;
+}

package/dist/cli/help.d.ts

@@ -0,0 +1 @@
+export declare const HELP = "gbc \u2014 Grok Bot control CLI (programmable App-equivalent control plane)\n\nUSAGE:\n  gbc [--json] [--mock] [--allow-writes] [--dry-run] [--base-url URL] [--auth-kind cursor|xai] <noun> <verb> [flags]\n\nEXAMPLES:\n  gbc --mock --json bot create --name demo --description \"test\"\n  gbc --mock --json bot list\n  gbc --mock --json bot get --agent-id <id>\n  gbc --mock --json --allow-writes --dry-run bot delete --agent-id <id> --confirm=<id>\n  gbc --mock --json --allow-writes message send --agent-id <id> --session-id <sid> --text \"hi\"\n  gbc --mock --json message status --agent-id <id> --session-id <sid> --message-id <mid>\n  gbc --mock --json message history --agent-id <id>\n  gbc --mock --json session list --agent-id <id>\n  gbc --mock --json bot status --agent-id <id>\n  gbc --mock --json --allow-writes sidebar create --name Work\n  gbc --mock --json --allow-writes sidebar move --agent-id <id> --section-id <sid>\n  gbc --mock --json auth whoami\n  gbc --json auth login-begin            # prints authorization_url; open it in a browser\n  gbc --json auth complete --timeout 300 # polls until signed in (exit 8 auth_pending on timeout)\n  gbc --json auth login --timeout 300    # begin+complete; URL as stderr {\"event\":\"open_browser\"}\n  gbc --json auth whoami | auth poll | auth cancel | auth refresh [--force] | auth logout\n\nSYNC (file-first snapshots; no SQLite):\n  gbc sync pull --agent-id <id> [--session-id <sid>] --dir /absolute/private/root \\\n    --account-id <stable-id> --team-id <stable-team-id|none> --ack-unverified-scope\n  gbc sync status --dir /absolute/private/root [--agent-id <id>] [--session-id <sid>]\n  gbc sync render --dir /absolute/private/root [--agent-id <id>] [--session-id <sid>]\n  gbc sync attachments --dir /absolute/private/root [--agent-id <id>] [--session-id <sid>] [--path <remote>]\n  pull bounds: --page-size 100 --max-pages 100 --max-bytes 33554432 --timeout-ms 30000 (defaults)\n  body hydration: --hydrate off|missing (default off); inline first, exact omitted re-list, store blob reads.\n  hydration bounds: --max-hydrate-requests 32 --hydrate-max-bytes 8388608 --hydrate-max-body-bytes 4194304\n  Hard caps: 256 extra RPCs / 64MiB aggregate / 4MiB body; share pull byte/time budget. Partial -> exit 9.\n  attachments bounds: --max-file-bytes 33554432 --max-bytes 67108864 --timeout-ms 30000\n  --dry-run pull/render/attachments: no RPC or files. --all is not supported in v1.\n  attachments also requires --account-id/--team-id/--ack-unverified-scope.\n  CLI pull/render/attachments authorize local writes; --allow-writes is NOT required.\n  Identity is operator-asserted, NOT verified by auth. Use stable IDs, never email/token hash.\n  Existing roots must be private 0700; files 0600. status/render are local and need no login.\n  Raw bytes/base64 preserved. render exposes known JSON message/text/notice/tool-summary shapes.\n  Raw observed envelopes stay unchanged; recovered bodies carry version-bound provenance/local content hash.\n  Unknown cards/unrecovered bodies remain placeholders; no decryption. JSONL/MD grep works offline.\n  Line coverage and body coverage are separate; completeness/current membership always unknown. No Watch/deletion.\n  attachments: on-demand ResolveGrokBotAttachmentReads for synced user-attachment and send-message attachment App store aliases only.\n  MCP: configure GBT_SYNC_ROOT; sync_status is local. sync_pull/render/attachments require independent\n  GBT_SYNC_ALLOW_LOCAL_WRITES=1 plus GBT_SYNC_ACCOUNT_ID, GBT_SYNC_TEAM_ID,\n  GBT_SYNC_ACK_UNVERIFIED_SCOPE=1 for pull. READONLY excludes sync mutators. No archive path tool argument.\n  Head refresh/backfill alternate; retained observations, NOT a current mirror.\n\nNOTES:\n  - Default transport is live Connect to --base-url (requires auth). Use --mock only for explicit simulation.\n  - Live auth/RPC against production is NOT verified in this build's automated tests.\n  - Remote writes require --allow-writes (or GBT_ALLOW_WRITES=1). --dry-run is pure (no RPC).\n  - bot delete / sidebar delete / interrupt require --confirm=<resource-id> (exact match).\n  - Value flags: \"--flag value\" or \"--flag=value\". A missing value (or a next token starting\n    with \"--\") is a usage error (exit 2); use --text=--literal for values starting with \"-\".\n  - --limit must be an integer 1..1000 (default 50); invalid values exit 2.\n  - Write errors that cannot rule out a side effect (unavailable/internal/deadline/transport)\n    exit 10 (unknown, retryable=false): reconcile before retrying.\n  - Sidebar writes are read back; a semantic mismatch exits 10 with code sidebar_unverified.\n  - GBT_TRUST_BACKEND / --trust-backend: only the exact value \"1\" trusts a custom --base-url.\n  - Auth: independent Cursor browser login (static-RE protocol, not official API). Verifier only in a\n    0600 pending file (15 min); credentials in $GBT_CREDENTIALS_DIR (default ~/.gbc, 0600). Tokens and\n    verifier are never printed. xai kind: unsupported. Refresh needs GBT_OAUTH_CLIENT_ID or a\n    login-persisted client_id binding (never hardcoded / never guessed from JWT). auth refresh\n    without --force may report already_fresh (no network); --force always attempts refresh.\n    whoami/status stay offline. RPC 401 updates creds for next request; write RPCs are never auto-\n    replayed; whitelisted read-only unary may refresh+retry once. logout/login share the credential\n    lock with refresh. Not logged in / pre-RPC refresh failure -> structured auth/retryable error with rpc_dispatched=false.\n  - Native auth lock: fs-native-extensions@1.5.3, Node20+, Linux/macOS/Windows prebuilds.\n    Missing binding fails closed: npm ci; see docs/auth-lock.md. Local filesystem only; Windows\n    ACL privacy requires operator verification. Stop ALL old MCPs before upgrading (lock namespaces differ).\n    Wait deadline 30s, refresh HTTP <=20s; wait cancellation never abandons an acquired exchange.\n  - MCP cancel \u2260 Interrupt. Disconnect does not interrupt runs.\n  - Room commands are not mixed into sidebar.\n\nEXIT CODES:\n  0 success | 2 usage | 4 auth | 5 not_found | 6 conflict | 7 denied\n  8 retryable | 9 known_failure | 10 unknown outcome | 1 other\n\nMCP:\n  gbc-mcp   # stdio MCP server (same SDK ops)\n";

package/dist/cli/help.js

@@ -0,0 +1,83 @@
+export const HELP = `gbc — Grok Bot control CLI (programmable App-equivalent control plane)
+
+USAGE:
+  gbc [--json] [--mock] [--allow-writes] [--dry-run] [--base-url URL] [--auth-kind cursor|xai] <noun> <verb> [flags]
+
+EXAMPLES:
+  gbc --mock --json bot create --name demo --description "test"
+  gbc --mock --json bot list
+  gbc --mock --json bot get --agent-id <id>
+  gbc --mock --json --allow-writes --dry-run bot delete --agent-id <id> --confirm=<id>
+  gbc --mock --json --allow-writes message send --agent-id <id> --session-id <sid> --text "hi"
+  gbc --mock --json message status --agent-id <id> --session-id <sid> --message-id <mid>
+  gbc --mock --json message history --agent-id <id>
+  gbc --mock --json session list --agent-id <id>
+  gbc --mock --json bot status --agent-id <id>
+  gbc --mock --json --allow-writes sidebar create --name Work
+  gbc --mock --json --allow-writes sidebar move --agent-id <id> --section-id <sid>
+  gbc --mock --json auth whoami
+  gbc --json auth login-begin            # prints authorization_url; open it in a browser
+  gbc --json auth complete --timeout 300 # polls until signed in (exit 8 auth_pending on timeout)
+  gbc --json auth login --timeout 300    # begin+complete; URL as stderr {"event":"open_browser"}
+  gbc --json auth whoami | auth poll | auth cancel | auth refresh [--force] | auth logout
+
+SYNC (file-first snapshots; no SQLite):
+  gbc sync pull --agent-id <id> [--session-id <sid>] --dir /absolute/private/root \\
+    --account-id <stable-id> --team-id <stable-team-id|none> --ack-unverified-scope
+  gbc sync status --dir /absolute/private/root [--agent-id <id>] [--session-id <sid>]
+  gbc sync render --dir /absolute/private/root [--agent-id <id>] [--session-id <sid>]
+  gbc sync attachments --dir /absolute/private/root [--agent-id <id>] [--session-id <sid>] [--path <remote>]
+  pull bounds: --page-size 100 --max-pages 100 --max-bytes 33554432 --timeout-ms 30000 (defaults)
+  body hydration: --hydrate off|missing (default off); inline first, exact omitted re-list, store blob reads.
+  hydration bounds: --max-hydrate-requests 32 --hydrate-max-bytes 8388608 --hydrate-max-body-bytes 4194304
+  Hard caps: 256 extra RPCs / 64MiB aggregate / 4MiB body; share pull byte/time budget. Partial -> exit 9.
+  attachments bounds: --max-file-bytes 33554432 --max-bytes 67108864 --timeout-ms 30000
+  --dry-run pull/render/attachments: no RPC or files. --all is not supported in v1.
+  attachments also requires --account-id/--team-id/--ack-unverified-scope.
+  CLI pull/render/attachments authorize local writes; --allow-writes is NOT required.
+  Identity is operator-asserted, NOT verified by auth. Use stable IDs, never email/token hash.
+  Existing roots must be private 0700; files 0600. status/render are local and need no login.
+  Raw bytes/base64 preserved. render exposes known JSON message/text/notice/tool-summary shapes.
+  Raw observed envelopes stay unchanged; recovered bodies carry version-bound provenance/local content hash.
+  Unknown cards/unrecovered bodies remain placeholders; no decryption. JSONL/MD grep works offline.
+  Line coverage and body coverage are separate; completeness/current membership always unknown. No Watch/deletion.
+  attachments: on-demand ResolveGrokBotAttachmentReads for synced user-attachment and send-message attachment App store aliases only.
+  MCP: configure GBT_SYNC_ROOT; sync_status is local. sync_pull/render/attachments require independent
+  GBT_SYNC_ALLOW_LOCAL_WRITES=1 plus GBT_SYNC_ACCOUNT_ID, GBT_SYNC_TEAM_ID,
+  GBT_SYNC_ACK_UNVERIFIED_SCOPE=1 for pull. READONLY excludes sync mutators. No archive path tool argument.
+  Head refresh/backfill alternate; retained observations, NOT a current mirror.
+
+NOTES:
+  - Default transport is live Connect to --base-url (requires auth). Use --mock only for explicit simulation.
+  - Live auth/RPC against production is NOT verified in this build's automated tests.
+  - Remote writes require --allow-writes (or GBT_ALLOW_WRITES=1). --dry-run is pure (no RPC).
+  - bot delete / sidebar delete / interrupt require --confirm=<resource-id> (exact match).
+  - Value flags: "--flag value" or "--flag=value". A missing value (or a next token starting
+    with "--") is a usage error (exit 2); use --text=--literal for values starting with "-".
+  - --limit must be an integer 1..1000 (default 50); invalid values exit 2.
+  - Write errors that cannot rule out a side effect (unavailable/internal/deadline/transport)
+    exit 10 (unknown, retryable=false): reconcile before retrying.
+  - Sidebar writes are read back; a semantic mismatch exits 10 with code sidebar_unverified.
+  - GBT_TRUST_BACKEND / --trust-backend: only the exact value "1" trusts a custom --base-url.
+  - Auth: independent Cursor browser login (static-RE protocol, not official API). Verifier only in a
+    0600 pending file (15 min); credentials in $GBT_CREDENTIALS_DIR (default ~/.gbc, 0600). Tokens and
+    verifier are never printed. xai kind: unsupported. Refresh needs GBT_OAUTH_CLIENT_ID or a
+    login-persisted client_id binding (never hardcoded / never guessed from JWT). auth refresh
+    without --force may report already_fresh (no network); --force always attempts refresh.
+    whoami/status stay offline. RPC 401 updates creds for next request; write RPCs are never auto-
+    replayed; whitelisted read-only unary may refresh+retry once. logout/login share the credential
+    lock with refresh. Not logged in / pre-RPC refresh failure -> structured auth/retryable error with rpc_dispatched=false.
+  - Native auth lock: fs-native-extensions@1.5.3, Node20+, Linux/macOS/Windows prebuilds.
+    Missing binding fails closed: npm ci; see docs/auth-lock.md. Local filesystem only; Windows
+    ACL privacy requires operator verification. Stop ALL old MCPs before upgrading (lock namespaces differ).
+    Wait deadline 30s, refresh HTTP <=20s; wait cancellation never abandons an acquired exchange.
+  - MCP cancel ≠ Interrupt. Disconnect does not interrupt runs.
+  - Room commands are not mixed into sidebar.
+
+EXIT CODES:
+  0 success | 2 usage | 4 auth | 5 not_found | 6 conflict | 7 denied
+  8 retryable | 9 known_failure | 10 unknown outcome | 1 other
+
+MCP:
+  gbc-mcp   # stdio MCP server (same SDK ops)
+`;

package/dist/cli/io.d.ts

@@ -0,0 +1,6 @@
+import type { ResultEnvelope } from "../dto/result.js";
+export declare function writeOut(data: unknown, asJson: boolean): void;
+export declare function writeErrJson(data: unknown): void;
+export declare function emitResult(r: ResultEnvelope, asJson: boolean): number;
+export declare function usageExit(message: string, hint?: string): never;
+export declare function catchToExit(e: unknown, asJson: boolean): number;

package/dist/cli/io.js

@@ -0,0 +1,61 @@
+import { EXIT, GbcError, mapExitCode } from "../errors.js";
+export function writeOut(data, asJson) {
+    if (asJson) {
+        process.stdout.write(JSON.stringify(data) + "\n");
+    }
+    else if (typeof data === "string") {
+        process.stdout.write(data + (data.endsWith("\n") ? "" : "\n"));
+    }
+    else {
+        process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    }
+}
+export function writeErrJson(data) {
+    process.stderr.write(JSON.stringify(data) + "\n");
+}
+export function emitResult(r, asJson) {
+    if (r.ok) {
+        writeOut(asJson ? r : r.data ?? r, asJson || true);
+        // Always machine-friendly for agents: default JSON on stdout for structured data.
+        return EXIT.SUCCESS;
+    }
+    writeErrJson(r);
+    return mapExitCode(r.code, r.outcome, r.retryable);
+}
+export function usageExit(message, hint) {
+    writeErrJson({
+        schema_version: "1.0.0",
+        ok: false,
+        outcome: "known_failure",
+        code: "usage",
+        retryable: false,
+        request_id: crypto.randomUUID(),
+        error: { message, hint },
+    });
+    process.exit(EXIT.USAGE);
+}
+export function catchToExit(e, asJson) {
+    if (e instanceof GbcError) {
+        const r = {
+            schema_version: "1.0.0",
+            ok: false,
+            outcome: e.outcome,
+            code: e.code,
+            retryable: e.retryable,
+            request_id: crypto.randomUUID(),
+            error: { message: e.message, hint: e.hint, details: e.details },
+        };
+        writeErrJson(r);
+        return e.exitCode;
+    }
+    writeErrJson({
+        schema_version: "1.0.0",
+        ok: false,
+        outcome: "known_failure",
+        code: "error",
+        retryable: false,
+        request_id: crypto.randomUUID(),
+        error: { message: String(e) },
+    });
+    return EXIT.ERROR;
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};