@bivy/bivy 0.10.1-staging.150 → 0.10.1-staging.152

package/bin/agent-manifest.json

@@ -191,11 +191,13 @@
       "supportTier": "beta",
       "certification": "adapter-tested",
       "headlessFlags": [
-        "-p"
+        "-p",
+        "--resume"
       ],
       "install": {
-        "kind": "npm",
-        "pkg": "@vibe-kit/grok-cli"
+        "kind": "curl",
+        "display": "curl -fsSL https://x.ai/cli/install.sh | bash",
+        "shell": "curl -fsSL https://x.ai/cli/install.sh | bash"
       }
     },
     {

package/bin/bivy.mjs

@@ -987,6 +987,9 @@ const AGENT_HEADLESS_FLAGS = {
 // appear here; others simply run without a pinned id.
 const AGENT_SESSION_ID_FLAG = {
   claude: "--session-id", // `claude --session-id <uuid>` (must be a valid UUID)
+  // Official Grok CLI: `grok --session-id <uuid>` pins a new session UUID under
+  // ~/.grok/sessions/<cwd>/<uuid>/ so takeover / resume has a known target.
+  grok: "--session-id",
 };
 
 // Args that mean the caller already chose a session (pin or resume), so we must
@@ -1001,6 +1004,7 @@ const SESSION_ID_CONFLICTS = ["--session-id", "--resume", "-r", "-c", "--continu
 const AGENT_RESUME_ARGS = {
   claude: (id) => ["--resume", id],
   codex: (id) => ["resume", id],
+  grok: (id) => ["--resume", id],
 };
 function agentResumeArgs(agentId, sessionRef) {
   const fn = AGENT_RESUME_ARGS[(agentId || "").toLowerCase()];

package/dist/runtime/credential-ingest.js

@@ -14,6 +14,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { createCredentialVault } from "./credential-store.js";
 import { resolveCodexHome } from "./codex-auth.js";
+import { grokAuthEntryKey, resolveGrokHome, GROK_OIDC_ISSUER } from "./grok-auth.js";
 import { claudeCredentialFiles } from "./anthropic-preflight.js";
 /** Read the `exp` (seconds) claim from a JWT access token → absolute epoch ms. */
 function jwtExpiryMs(token) {
@@ -94,6 +95,52 @@ export async function ingestClaudeCredentials(credsDir) {
     }
     return 0;
 }
+/** Map the official Grok CLI's `~/.grok/auth.json` OIDC entry into a Bivy credential. */
+export function grokAuthToCredential(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const record = raw;
+    // Prefer the known xAI OIDC entry key; fall back to the first oidc entry whose
+    // issuer is auth.x.ai (covers a client-id change without breaking ingest).
+    const preferredKey = grokAuthEntryKey();
+    let entry = record[preferredKey];
+    if (!entry || typeof entry !== "object") {
+        for (const value of Object.values(record)) {
+            if (!value || typeof value !== "object")
+                continue;
+            const candidate = value;
+            if (candidate.oidc_issuer === GROK_OIDC_ISSUER || candidate.auth_mode === "oidc") {
+                entry = candidate;
+                break;
+            }
+        }
+    }
+    if (!entry)
+        return undefined;
+    const access = typeof entry.key === "string" ? entry.key : "";
+    const refresh = typeof entry.refresh_token === "string" ? entry.refresh_token : "";
+    if (!access || !refresh)
+        return undefined;
+    const expiresFromField = typeof entry.expires_at === "string" ? Date.parse(entry.expires_at) : NaN;
+    const expires = Number.isFinite(expiresFromField) && expiresFromField > 0
+        ? expiresFromField
+        : (jwtExpiryMs(access) ?? Date.now() + 60 * 60 * 1000);
+    return { providerId: "xai", credential: { type: "oauth", access, refresh, expires } };
+}
+/** Fold a login/refresh done in the Grok CLI back into Bivy's vault. */
+export async function ingestGrokCredentials(credsDir) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(path.join(resolveGrokHome(), "auth.json"), "utf8"));
+    }
+    catch {
+        return 0; // no Grok login on disk
+    }
+    const mapped = grokAuthToCredential(raw);
+    if (!mapped)
+        return 0;
+    return createCredentialVault(credsDir).importAll({ [mapped.providerId]: mapped.credential });
+}
 /**
  * Ingest an agent's native credential store into Bivy's vault. Called when a
  * `bivy run <agent>` terminal exits, so a login done inside that agent's CLI is
@@ -112,6 +159,8 @@ export async function ingestAgentCredentials(agentId, credsDir, piDir) {
         case "claude-code":
         case "claude-code-sdk":
             return ingestClaudeCredentials(credsDir);
+        case "grok":
+            return ingestGrokCredentials(credsDir);
         case "pi":
             // Pi's TUI writes a plaintext auth.json in its own dir; fold it back into
             // the shared vault.

package/dist/runtime/credential-provisioning.js

@@ -19,6 +19,7 @@
 import { createCredentialVault } from "./credential-store.js";
 import { buildAgentCredentialEnv, createCredentialStore } from "./credentials.js";
 import { ensureCodexAuth, ensureCodexTrusted } from "./codex-auth.js";
+import { ensureGrokAuth } from "./grok-auth.js";
 import { refreshModelOAuth } from "./oauth/model-oauth.js";
 import { isNativeOAuthProvider } from "./oauth/model-oauth-providers.js";
 /**
@@ -75,5 +76,13 @@ export async function provisionAgentRun(credsDir, piDir, agentId, workspace) {
         if (workspace)
             ensureCodexTrusted(workspace);
     }
+    else if (agentId === "grok") {
+        // Official Grok CLI reads XAI_API_KEY/GROK_API_KEY (already in env for api
+        // keys) or its own auth.json; mint the latter from a connected SuperGrok /
+        // X subscription when present.
+        const home = await ensureGrokAuth(credsDir).catch(() => undefined);
+        if (home)
+            env.GROK_HOME = home;
+    }
     return env;
 }

package/dist/runtime/credentials.js

@@ -128,8 +128,9 @@ export async function buildAgentCredentialEnv(store, providers, activeProvider)
         if (cred.kind === "oauth") {
             // OAuth *subscription* tokens are provider-specific and are not accepted
             // as a plain API key. Only Anthropic has a documented env var an external
-            // agent reads (Claude Code's OAuth token); other providers' subscription
-            // logins can't be handed off this way, so don't emit a misleading key.
+            // agent reads (Claude Code's OAuth token). Codex and Grok get their
+            // subscription via native auth.json materialization (codex-auth.ts /
+            // grok-auth.ts), not as env keys — so don't emit a misleading key here.
             if (cred.provider !== "anthropic")
                 continue;
             Object.assign(env, cred.env ?? {});
@@ -137,6 +138,11 @@ export async function buildAgentCredentialEnv(store, providers, activeProvider)
         }
         else {
             env[apiKeyEnvVar(cred.provider)] = cred.token;
+            // vibe-kit/grok-cli (and some forks) read GROK_API_KEY instead of the
+            // official XAI_API_KEY. Project both so either Grok binary works off one
+            // Bivy API-key login.
+            if (cred.provider === "xai")
+                env.GROK_API_KEY = cred.token;
             // A custom endpoint's base URL (and standard-key alias) is injected only
             // when it's the active provider, so it can't hijack the real provider.
             if (isActive && cred.env) {

package/dist/runtime/grok-auth.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Grok (xAI CLI) credential materialization.
+//
+// An xAI SuperGrok / X subscription a user connects *inside Bivy* lands in the
+// shared node vault as an `xai` OAuth record. The official Grok CLI
+// (`curl -fsSL https://x.ai/cli/install.sh | bash`) cannot read that vault — it
+// authenticates from `XAI_API_KEY` / `GROK_API_KEY` or its own
+// `$GROK_HOME/auth.json` (the file `grok login` writes). This module bridges the
+// gap: it mints the file Grok expects from the vault record, so a subscription
+// connected in Bivy "just works" for the Grok agent with no separate
+// `grok login`.
+//
+// Why it's sound: Bivy's `xai` OAuth app IS the Grok CLI's own OAuth app
+// (identical client_id `b1a00492-…`, token endpoint, and scopes including
+// `grok-cli:access` — verified against @earendil-works/pi-ai and the shipped
+// grok binary), so tokens minted through Bivy are accepted by Grok's backend.
+// The vault already stores {access, refresh, expires}; we write them in the
+// shape Grok's auth.json uses for OIDC sessions.
+//
+// Rotation note: xAI does *not* rotate the refresh token on every grant
+// (`refreshRotates: false` in model-oauth-providers), so minting is safe even
+// if Grok later self-refreshes — the vault's refresh token stays valid. We mint
+// only when no auth.json exists yet (Grok then owns and self-refreshes it),
+// matching the Codex materialization policy.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createCredentialVault } from "./credential-store.js";
+import { getModelOAuthProvider } from "./oauth/model-oauth-providers.js";
+import { refreshModelOAuth } from "./oauth/model-oauth.js";
+/** xAI OIDC issuer the official Grok CLI keys its auth.json entry on. */
+export const GROK_OIDC_ISSUER = "https://auth.x.ai";
+/** Resolve Grok's home dir exactly as the CLI does (`GROK_HOME` or `~/.grok`). */
+export function resolveGrokHome() {
+    return process.env.GROK_HOME?.trim() || path.join(os.homedir(), ".grok");
+}
+/** Map key Grok uses for the xAI OIDC session inside auth.json. */
+export function grokAuthEntryKey(clientId) {
+    const id = clientId?.trim() || getModelOAuthProvider("xai")?.clientId || "";
+    return `${GROK_OIDC_ISSUER}::${id}`;
+}
+/**
+ * Ensure the Grok CLI has a usable credential file, minting one from Bivy's
+ * vault when needed. Returns the resolved `GROK_HOME` (so the caller can pin it
+ * on the subprocess env) or `undefined` when there's nothing to do / no vault
+ * credential — in which case the caller's preflight surfaces the actionable
+ * "no credential" error unchanged.
+ *
+ * Idempotent and low-churn: if an `auth.json` already exists (a native
+ * `grok login` or a prior materialization) it is left untouched — Grok owns and
+ * self-refreshes it — so we mint at most once. We write to the *default* Grok
+ * home (never a throwaway dir) so sessions stay where the CLI already looks.
+ */
+export async function ensureGrokAuth(credsDir) {
+    const grokHome = resolveGrokHome();
+    const authFile = path.join(grokHome, "auth.json");
+    // Never clobber an existing login (native or previously materialized); Grok
+    // owns and refreshes it. An API key, if present, is handled by preflight /
+    // env projection — no auth.json needed.
+    if (fs.existsSync(authFile))
+        return grokHome;
+    if (process.env.XAI_API_KEY?.trim() || process.env.GROK_API_KEY?.trim())
+        return undefined;
+    const provider = getModelOAuthProvider("xai");
+    if (!provider)
+        return undefined;
+    // Ensure the vault access token is still live before we project it. No-op when
+    // fresh; refreshes under the store lock when expired. Failure leaves the vault
+    // alone and we fall through to the (likely still-stale) read below.
+    await refreshModelOAuth(credsDir, "xai").catch(() => undefined);
+    const store = createCredentialVault(credsDir);
+    const cred = await store.read("xai").catch(() => undefined);
+    if (!cred || cred.type !== "oauth")
+        return undefined;
+    const access = typeof cred.access === "string" ? cred.access : "";
+    const refresh = typeof cred.refresh === "string" ? cred.refresh : "";
+    if (!access || !refresh)
+        return undefined;
+    const expiresMs = Number(cred.expires) || 0;
+    const entryKey = grokAuthEntryKey(provider.clientId);
+    const entry = {
+        key: access,
+        auth_mode: "oidc",
+        create_time: new Date().toISOString(),
+        refresh_token: refresh,
+        oidc_issuer: GROK_OIDC_ISSUER,
+        oidc_client_id: provider.clientId,
+    };
+    if (expiresMs > 0)
+        entry.expires_at = new Date(expiresMs).toISOString();
+    const authJson = { [entryKey]: entry };
+    try {
+        fs.mkdirSync(grokHome, { recursive: true, mode: 0o700 });
+        const tmp = `${authFile}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(authJson, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, authFile);
+    }
+    catch {
+        return undefined;
+    }
+    return grokHome;
+}

package/dist/runtime/grok-preflight.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Grok (xAI CLI) credential preflight.
+//
+// The official Grok CLI authenticates one of two ways: an xAI API key read from
+// `XAI_API_KEY` / `GROK_API_KEY`, or OIDC tokens in `$GROK_HOME/auth.json`
+// (default `~/.grok/auth.json`). Bivy's shared credential vault forwards *API
+// keys* to every agent (see credentials.ts), and `grok-auth.ts` mints the
+// auth.json from a connected xAI *subscription* — so both sign-in kinds now
+// reach Grok.
+//
+// This preflight is the backstop: if neither an API key nor an auth.json is
+// present after that handoff, the CLI fails with an opaque "API key required"
+// (vibe-kit) or "Not signed in" (official) message. We detect that up front and
+// return a clear, actionable message instead.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** Path to the Grok CLI's own auth file (`GROK_HOME/auth.json`, default `~/.grok`). */
+export function grokAuthFile(deps = {}) {
+    const grokHome = (deps.grokHome ?? process.env.GROK_HOME)?.trim();
+    const base = grokHome ? grokHome : path.join(deps.home ?? os.homedir(), ".grok");
+    return path.join(base, "auth.json");
+}
+/** The user-facing message shown when Grok has no xAI credential. */
+export const GROK_NO_CREDENTIAL_MESSAGE = [
+    "Grok has no xAI credential on this node, so it can't start a turn.",
+    "",
+    "Fix it any of these ways:",
+    "• Connect SuperGrok / X Premium under Keys & OAuth — Bivy mints Grok's auth file from it automatically, or",
+    "• Add an xAI API key under Keys & OAuth — Bivy passes it as XAI_API_KEY (and GROK_API_KEY), or",
+    "• Run `grok login` on this node to sign in directly (official Grok CLI).",
+    "",
+    "Install the official Grok CLI if you haven't: `curl -fsSL https://x.ai/cli/install.sh | bash`",
+    "(The older @vibe-kit/grok-cli package only accepts API keys and cannot use a subscription login.)",
+    "",
+    "If you already connected the xAI subscription in Bivy and still see this, the saved login could not be projected — reconnect it under Keys & OAuth, or delete a stale ~/.grok/auth.json and try again.",
+].join("\n");
+/**
+ * Returns a human-readable error when the Grok CLI has no usable xAI
+ * credential, or undefined when a credential is present so the turn should
+ * proceed. `env` is the environment the Grok subprocess will run with (ambient
+ * process env + Bivy's vault handoff).
+ */
+export function grokCredentialPreflight(env, deps = {}) {
+    if (env.XAI_API_KEY?.trim() || env.GROK_API_KEY?.trim())
+        return undefined;
+    const exists = deps.fileExists ?? ((p) => {
+        try {
+            return fs.existsSync(p);
+        }
+        catch {
+            return false;
+        }
+    });
+    // Prefer the GROK_HOME the prepare step may have just pinned on env.
+    const homeFromEnv = env.GROK_HOME?.trim();
+    if (exists(grokAuthFile({ ...deps, grokHome: homeFromEnv || deps.grokHome })))
+        return undefined;
+    return GROK_NO_CREDENTIAL_MESSAGE;
+}

package/dist/runtime/grok-sessions.js

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Grok CLI on-disk session reader — the read side of adopting a Grok session
+// started outside governed chat (e.g. `bivy run grok` or a bare `grok` TUI).
+//
+// Layout (official Grok CLI 1.x):
+//   $GROK_HOME/sessions/<url-encoded-cwd>/<session-uuid>/
+//     summary.json          — id, cwd, title, timestamps, model
+//     chat_history.jsonl    — user / assistant / system / tool_result lines
+//
+// GROK_HOME defaults to ~/.grok (see grok-auth.ts's resolveGrokHome). Every read
+// is best-effort: a missing/malformed store never throws out of the list path.
+import fs from "node:fs";
+import path from "node:path";
+import { resolveGrokHome } from "./grok-auth.js";
+import { hasLiveProcessForCwd } from "./native-process-scan.js";
+const GROK_BIN_NAMES = ["grok"];
+export function grokSessionsRoot() {
+    return path.join(resolveGrokHome(), "sessions");
+}
+function toEpoch(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    const ms = new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : undefined;
+}
+function readSummary(dir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(dir, "summary.json"), "utf8"));
+        const info = (raw.info && typeof raw.info === "object" ? raw.info : {});
+        const id = typeof info.id === "string" ? info.id : path.basename(dir);
+        const cwd = typeof info.cwd === "string" ? info.cwd : undefined;
+        const name = (typeof raw.generated_title === "string" && raw.generated_title.trim()) ||
+            (typeof raw.session_summary === "string" && raw.session_summary.trim()) ||
+            undefined;
+        return {
+            id,
+            dir,
+            cwd,
+            createdAt: toEpoch(raw.created_at),
+            updatedAt: toEpoch(raw.last_active_at ?? raw.updated_at),
+            name,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Pull plain text out of a Grok content field (string or content-block array). */
+function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string")
+            parts.push(b.text);
+        else if (typeof b.text === "string")
+            parts.push(b.text);
+    }
+    return parts.join("\n");
+}
+/** First user-visible prompt that isn't a system/meta wrapper. */
+function firstUserMessage(dir) {
+    const file = path.join(dir, "chat_history.jsonl");
+    let fh;
+    try {
+        fh = fs.openSync(file, "r");
+        const buf = Buffer.alloc(64 * 1024);
+        const n = fs.readSync(fh, buf, 0, buf.length, 0);
+        const chunk = buf.subarray(0, n).toString("utf8");
+        for (const line of chunk.split("\n")) {
+            if (!line.trim())
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (rec.type !== "user")
+                continue;
+            const text = contentText(rec.content).trim();
+            if (!text)
+                continue;
+            // Skip the CLI's environment / system-reminder scaffolding — the first
+            // real user_query (or a short free-form prompt) is the list label.
+            const query = text.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/i)?.[1]?.trim();
+            const label = (query || text).replace(/\s+/g, " ").trim();
+            if (!label)
+                continue;
+            // Skip pure meta blobs that never carry a user question.
+            if (label.startsWith("<user_info>") || label.startsWith("<system-reminder>") || label.startsWith("<git_status>")) {
+                continue;
+            }
+            return label.length > 120 ? `${label.slice(0, 119)}…` : label;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fh !== undefined)
+            try {
+                fs.closeSync(fh);
+            }
+            catch { /* ignore */ }
+    }
+    return undefined;
+}
+/**
+ * Enumerate Grok sessions under $GROK_HOME/sessions. Best-effort: a missing or
+ * unreadable store returns []. Sorted newest-activity-first.
+ */
+export function listGrokSessions() {
+    const root = grokSessionsRoot();
+    let cwdEntries;
+    try {
+        cwdEntries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const cwdEntry of cwdEntries) {
+        if (!cwdEntry.isDirectory())
+            continue;
+        // Skip the search index / non-session dirs.
+        if (cwdEntry.name === "session_search.sqlite" || cwdEntry.name.endsWith(".sqlite"))
+            continue;
+        const cwdDir = path.join(root, cwdEntry.name);
+        let sessionEntries;
+        try {
+            sessionEntries = fs.readdirSync(cwdDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const sessionEntry of sessionEntries) {
+            if (!sessionEntry.isDirectory())
+                continue;
+            const dir = path.join(cwdDir, sessionEntry.name);
+            const summary = readSummary(dir);
+            if (!summary?.id)
+                continue;
+            // Prefer the cwd encoded in the parent dir name when summary lacks one.
+            let cwd = summary.cwd;
+            if (!cwd) {
+                try {
+                    cwd = decodeURIComponent(cwdEntry.name);
+                }
+                catch {
+                    cwd = undefined;
+                }
+            }
+            let createdAt = summary.createdAt;
+            let updatedAt = summary.updatedAt;
+            if (createdAt == null || updatedAt == null) {
+                try {
+                    const st = fs.statSync(dir);
+                    createdAt = createdAt ?? (st.birthtimeMs || st.mtimeMs);
+                    updatedAt = updatedAt ?? st.mtimeMs;
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            out.push({
+                id: summary.id,
+                dir,
+                cwd,
+                createdAt,
+                updatedAt,
+                name: summary.name,
+                firstMessage: firstUserMessage(dir),
+            });
+        }
+    }
+    return out.sort((a, b) => (b.updatedAt ?? b.createdAt ?? 0) - (a.updatedAt ?? a.createdAt ?? 0));
+}
+/**
+ * Load a Grok session's chat_history.jsonl as RuntimeMessage[] for history
+ * preload when a governed chat resumes that session. System scaffolding and
+ * tool_result rows are dropped — the chat surface only needs the user/assistant
+ * turns. Best-effort; a missing/malformed file returns [].
+ */
+export function loadGrokTranscript(sessionId) {
+    const match = listGrokSessions().find((s) => s.id === sessionId);
+    if (!match)
+        return [];
+    const file = path.join(match.dir, "chat_history.jsonl");
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const type = rec.type;
+        if (type !== "user" && type !== "assistant")
+            continue;
+        let text = contentText(rec.content).trim();
+        if (!text)
+            continue;
+        // Prefer the inner <user_query> when the CLI wrapped the prompt.
+        if (type === "user") {
+            const query = text.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/i)?.[1]?.trim();
+            if (query)
+                text = query;
+            // Skip pure meta system blobs that aren't real user turns.
+            if (text.startsWith("<user_info>") ||
+                text.startsWith("<system-reminder>") ||
+                text.startsWith("<git_status>") ||
+                text.startsWith("<image_files>") ||
+                text.startsWith("<action_safety>")) {
+                continue;
+            }
+        }
+        out.push({
+            role: type === "user" ? "user" : "assistant",
+            content: text,
+            timestamp: typeof rec.timestamp === "string" || typeof rec.timestamp === "number" ? toEpoch(rec.timestamp) : undefined,
+        });
+    }
+    return out;
+}
+/**
+ * Locate the Grok session a run produced (by cwd + start time) when there is no
+ * launch-time pinned id. Mirrors discoverCodexSessionForCwd / discoverPiSessionForCwd.
+ */
+export function discoverGrokSessionForCwd(cwd, since = 0) {
+    const target = path.resolve(cwd);
+    const skewMs = 10_000;
+    const earliest = since - skewMs;
+    const wanted = process.platform === "win32" ? target.toLowerCase() : target;
+    return listGrokSessions()
+        .filter((s) => {
+        if (!s.cwd)
+            return false;
+        const resolved = process.platform === "win32" ? path.resolve(s.cwd).toLowerCase() : path.resolve(s.cwd);
+        return resolved === wanted;
+    })
+        .filter((s) => (s.createdAt ?? 0) >= earliest)
+        .sort((a, b) => {
+        const da = Math.abs((a.createdAt ?? 0) - since);
+        const db = Math.abs((b.createdAt ?? 0) - since);
+        if (da !== db)
+            return da - db;
+        return (b.updatedAt ?? 0) - (a.updatedAt ?? 0);
+    })[0];
+}
+/** Issue #156 discovery surface for Grok's on-disk store. */
+export function discoverNativeGrokSessions(hasLiveProcess = (cwd) => hasLiveProcessForCwd(cwd, GROK_BIN_NAMES)) {
+    return listGrokSessions().map((s) => ({
+        runtimeId: "grok",
+        ref: s.id,
+        file: s.dir,
+        cwd: s.cwd,
+        updatedAt: s.updatedAt ?? s.createdAt,
+        title: s.name || s.firstMessage,
+        active: Boolean(s.cwd) && hasLiveProcess(s.cwd),
+        resumable: true,
+    }));
+}

package/dist/runtime/index.js

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import { ClaudeCodeRuntime, claudeRuntimeFromEnv, claudeSdkInstalled } from "./claude-code.js";
 import { deleteCodexSession, discoverNativeCodexSessions, loadCodexTranscript, writeCodexRollout } from "./codex-sessions.js";
 import { deleteOpenCodeSession, loadOpenCodeTranscript, writeOpenCodeHistory } from "./opencode-sessions.js";
+import { discoverNativeGrokSessions, listGrokSessions, loadGrokTranscript } from "./grok-sessions.js";
 import { createCredentialStore } from "./credentials.js";
 // Args that continue an existing Codex session each prompt. Codex assigns its own
 // session id (no launch-time pin), so a resumed run threads it via `exec resume`.
@@ -37,7 +38,9 @@ import { PiRuntime } from "./pi.js";
 import { ProcessRuntime, processRuntimeFromEnv } from "./process.js";
 import { codexCredentialPreflight } from "./codex-preflight.js";
 import { opencodeCredentialPreflight } from "./opencode-preflight.js";
+import { grokCredentialPreflight } from "./grok-preflight.js";
 import { ensureCodexAuth } from "./codex-auth.js";
+import { ensureGrokAuth } from "./grok-auth.js";
 import { parserFactoryFor } from "./cli-parsers.js";
 import { sandboxTier, sandboxArgsFor, codexSandboxPolicy } from "../harness/sandbox.js";
 import { ProtocolRuntime, protocolRuntimeFromEnv, protocolCommandsFromEnv } from "./protocol.js";
@@ -487,24 +490,41 @@ const CLI_AGENT_SPECS = {
     grok: {
         displayName: "Grok",
         command: "grok",
-        packageName: "@vibe-kit/grok-cli",
+        packageName: "grok (curl -fsSL https://x.ai/cli/install.sh | bash)",
         supportTier: "beta",
-        blurb: "Open-source terminal agent for xAI's Grok models (Grok CLI).",
-        // `grok -p "<prompt>"` runs one prompt and exits (headless); `-m <id>` picks
-        // the model. (The widely-installed @vibe-kit/grok-cli has no by-id resume or
-        // JSON flag; the superagent `grok-dev` fork does — override via env if you run
-        // that one.)
+        blurb: "xAI's official Grok coding agent (Grok CLI) — SuperGrok/X subscription or API key.",
+        // Official CLI: `grok -p "<prompt>"` (alias `--single`) runs one headless
+        // turn; `-m <id>` picks the model. Auth is projected from Bivy's vault:
+        // subscription → ~/.grok/auth.json (grok-auth.ts), API key → XAI_API_KEY /
+        // GROK_API_KEY. The older @vibe-kit/grok-cli only accepts API keys — install
+        // the official binary for OAuth to work.
+        //
+        // Resume: `grok --resume <id> -p "<prompt>"` continues a prior session by
+        // UUID (sessions live under ~/.grok/sessions/<cwd>/<id>/). The interactive
+        // TUI uses the same store via `grok --resume <id>`. Model ids match
+        // `grok models` for the official CLI (override with BIVY_GROK_MODELS).
         args: ["-p"],
+        resume: {
+            template: ["--resume", "{id}", "-p"],
+            loadHistory: (sessionId) => loadGrokTranscript(sessionId),
+        },
         model: {
             flag: "-m",
             models: [
-                { id: "grok-code-fast-1", name: "Grok Code Fast 1", provider: "xai" },
-                { id: "grok-4-latest", name: "Grok 4", provider: "xai" },
-                { id: "grok-3-fast", name: "Grok 3 Fast", provider: "xai" },
+                // Official Grok CLI (1.x) currently advertises grok-4.5 as the default
+                // subscription model. Older curated ids (grok-4-latest, grok-code-fast-1,
+                // …) return "unknown model id" against current CLIs — keep the list
+                // honest; operators can override with BIVY_GROK_MODELS if their install
+                // exposes more.
+                { id: "grok-4.5", name: "Grok 4.5", provider: "xai" },
             ],
         },
         promptMode: "argv",
-        install: { kind: "npm", pkg: "@vibe-kit/grok-cli" },
+        install: {
+            kind: "curl",
+            display: "curl -fsSL https://x.ai/cli/install.sh | bash",
+            shell: "curl -fsSL https://x.ai/cli/install.sh | bash",
+        },
     },
     amp: {
         displayName: "Amp",
@@ -1076,7 +1096,23 @@ function cliAgentInfo(id) {
         // (BIVY_MCP_PROXY) — an honest, narrower capability than full toolInterception
         // (it governs MCP tools, not the agent's built-in shell/edits). See
         // src/harness/mcp-inject.ts + governMcpCall in src/server.ts.
-        capabilities: withExactCapabilitySurface({ toolInterception: acpActive, mcpToolApprovals: acpActive || Boolean(process.env.BIVY_MCP_PROXY), modelSelection, resume, packages: false, fork: false, usageReporting, sessionDiscovery: id === "codex" }),
+        capabilities: withExactCapabilitySurface({
+            toolInterception: acpActive,
+            mcpToolApprovals: acpActive || Boolean(process.env.BIVY_MCP_PROXY),
+            modelSelection,
+            resume,
+            packages: false,
+            fork: false,
+            usageReporting,
+            // Codex (and Grok) can locate an on-disk session by cwd + start time so a
+            // `bivy run` terminal without a launch-time pin is still takeable as chat.
+            sessionDiscovery: id === "codex" || id === "grok",
+            // Grok also exposes its interactive TUI (`grok --resume <id>`) for the
+            // chat↔terminal hand-off; Codex gets this via the approvals runtime.
+            interactiveTui: id === "grok" && commandAvailable(spec.command),
+            nativeSessionDiscovery: id === "grok" && commandAvailable(spec.command),
+            nativeSessionAdoption: id === "grok" && resume,
+        }),
         supportTier: spec.supportTier ?? (id === "codex" ? "supported" : "experimental"),
         testedVersion: spec.testedVersion,
         authOwner: spec.authOwner ?? "agent",
@@ -1835,22 +1871,29 @@ function makeCliRuntime(id, options) {
             : structured && spec.jsonArgs
                 ? spec.jsonArgs
                 : spec.args);
-    // Codex reads OPENAI_API_KEY or its own `$CODEX_HOME/auth.json`. When the
-    // user connected a ChatGPT/Codex subscription in Bivy (but hasn't run
-    // `codex login`), `prepare` mints that auth file from the shared vault so
+    // Codex / Grok read an API key *or* their own `$…_HOME/auth.json`. When the
+    // user connected a subscription in Bivy (but hasn't run `codex login` /
+    // `grok login`), `prepare` mints that auth file from the shared vault so
     // the run just works; the preflight still catches the genuinely
     // uncredentialed case with an actionable message instead of an opaque 401.
     const preflight = id === "codex"
         ? (env) => codexCredentialPreflight(env)
         : id === "opencode"
             ? (env, ctx) => opencodeCredentialPreflight(env, ctx)
-            : undefined;
+            : id === "grok"
+                ? (env) => grokCredentialPreflight(env)
+                : undefined;
     const prepare = id === "codex"
         ? async () => {
             const home = await ensureCodexAuth(options.credsDir);
             return home ? { CODEX_HOME: home } : {};
         }
-        : undefined;
+        : id === "grok"
+            ? async () => {
+                const home = await ensureGrokAuth(options.credsDir);
+                return home ? { GROK_HOME: home } : {};
+            }
+            : undefined;
     // Resume, the generic way. Codex keeps its verified path (rollout history +
     // tier-aware `codex exec resume <id> --json`). Every other CLI agent becomes
     // resumable purely as data: a spec.resume template (or a BIVY_<ID>_RESUME_
@@ -1879,5 +1922,47 @@ function makeCliRuntime(id, options) {
                     : [a.replace(/\{id\}/g, sessionId).replace(/\{tier\}/g, tier)]),
             }
             : {};
-    return new ProcessRuntime({ id, displayName: spec.displayName, command: spec.command, args: runArgs, promptMode: spec.promptMode, credentials: createCredentialStore(options.credsDir), parserFactory: parserFactoryFor(parserId), preflight, prepare, model: cliModelConfig(id), thinking: cliThinkingConfig(id), usageReporting: cliUsageReporting(id), slashCommands: cliSlashCommands(id), ...resumeOpts });
+    // Grok-specific: on-disk session enumeration + interactive TUI hand-off so
+    // `bivy run grok` sessions persist after the PTY exits and can be taken
+    // over as chat or reopened in the native TUI.
+    const grokOpts = id === "grok"
+        ? {
+            sessionDiscovery: true,
+            listDiskSessions: () => listGrokSessions().map((s) => ({
+                id: s.id,
+                path: s.dir,
+                cwd: s.cwd,
+                name: s.name || s.firstMessage,
+                created: s.createdAt ? new Date(s.createdAt).toISOString() : undefined,
+                modified: s.updatedAt ? new Date(s.updatedAt).toISOString() : undefined,
+                firstMessage: s.firstMessage,
+            })),
+            interactiveTui: ({ sessionRef, env }) => sessionRef ? { command: "grok", args: ["--resume", sessionRef], env } : null,
+            // discoverNativeSessions is on AgentRuntime; ProcessRuntime doesn't
+            // expose it as an option — wire via a thin subclass below when needed.
+        }
+        : {};
+    const runtime = new ProcessRuntime({
+        id,
+        displayName: spec.displayName,
+        command: spec.command,
+        args: runArgs,
+        promptMode: spec.promptMode,
+        credentials: createCredentialStore(options.credsDir),
+        parserFactory: parserFactoryFor(parserId),
+        preflight,
+        prepare,
+        model: cliModelConfig(id),
+        thinking: cliThinkingConfig(id),
+        usageReporting: cliUsageReporting(id),
+        slashCommands: cliSlashCommands(id),
+        ...resumeOpts,
+        ...grokOpts,
+    });
+    if (id === "grok") {
+        // Issue #156 discovery surface — ProcessRuntime has no options hook for
+        // this; attach it so collectDiscoveredSessions picks Grok sessions up.
+        runtime.discoverNativeSessions = () => discoverNativeGrokSessions();
+    }
+    return runtime;
 }

package/dist/runtime/process.js

@@ -194,6 +194,33 @@ class ProcessSession {
     setName(name) {
         this.name = name;
     }
+    /**
+     * "Continue in terminal": hand this session to the agent's interactive TUI
+     * (see ProcessRuntimeOptions.interactiveTui). Runs prepare() first so auth
+     * env (e.g. GROK_HOME) matches the chat path.
+     */
+    async interactiveTuiCommand() {
+        const hook = this.runtimeOptions.interactiveTui;
+        if (!hook)
+            return null;
+        const sessionRef = this.resumeId ?? this.id;
+        let env = {};
+        if (this.runtimeOptions.prepare) {
+            try {
+                const patch = await this.runtimeOptions.prepare({});
+                if (patch && typeof patch === "object") {
+                    for (const [k, v] of Object.entries(patch)) {
+                        if (typeof v === "string")
+                            env[k] = v;
+                    }
+                }
+            }
+            catch {
+                env = {};
+            }
+        }
+        return hook({ sessionRef, cwd: this.cwd, env });
+    }
     /** The agent's on-disk slash commands for this workspace (Codex prompts,
      *  opencode commands). Best-effort and display-only: any read failure yields an
      *  empty menu, never a throw. */
@@ -460,6 +487,10 @@ export class ProcessRuntime {
             fork: false,
             // Usage reporting when a usage-emitting parser is wired (see getUsage).
             usageReporting: Boolean(options.usageReporting),
+            interactiveTui: Boolean(options.interactiveTui),
+            sessionDiscovery: Boolean(options.sessionDiscovery),
+            nativeSessionDiscovery: Boolean(options.listDiskSessions),
+            nativeSessionAdoption: Boolean(options.resumable && options.listDiskSessions),
         });
     }
     /** Session-less catalog contribution: this CLI agent's configured models, grouped by provider. */
@@ -494,6 +525,17 @@ export class ProcessRuntime {
         return this.createSession(options);
     }
     async listSessions() {
+        // Prefer the agent's own on-disk store when wired (Grok, …) so closed
+        // `bivy run` / native TUI sessions still appear in the durable list after
+        // the PTY exits — the in-memory set alone evaporates with the process.
+        if (this.options.listDiskSessions) {
+            try {
+                return await this.options.listDiskSessions();
+            }
+            catch {
+                // fall through to the live handles
+            }
+        }
         return this.sessions.map((session) => ({
             id: session.id,
             cwd: session.cwd,

package/dist/server.js

@@ -31,6 +31,7 @@ import { suggestNameFromSelectedModel } from "./runtime/model-namer.js";
 import { isNativeOAuthProvider, loginModelOAuth } from "./runtime/oauth/model-oauth.js";
 import { decideOAuthLoginSweep } from "./runtime/oauth/oauth-login-sweep.js";
 import { listCodexSessions, loadCodexTranscript, discoverCodexSessionForCwd } from "./runtime/codex-sessions.js";
+import { discoverGrokSessionForCwd } from "./runtime/grok-sessions.js";
 import { dedupeSessionSummaries } from "./session-identity.js";
 import { discoverPiSessionForCwd } from "./runtime/pi-session-discovery.js";
 import { exportProviderAuth, exportProviderAuthTombstones, importProviderAuth, listProviders, removeProvider, setProviderApiKey, setProviderCredential } from "./runtime/pi-auth.js";
@@ -1783,6 +1784,9 @@ async function openRunTerminal(spec, emit) {
     // Only genuine `bivy run` agents get quiet-agent push hints; an adopted
     // tmux/zellij/screen attach isn't "your agent waiting".
     const notifiable = !spec.mux;
+    // Captured before open so the onExit discovery path (agents that assign their
+    // session id lazily) can correlate by start time.
+    const createdAt = Date.now();
     try {
         const id = terminals.open({
             workspace,
@@ -1820,6 +1824,40 @@ async function openRunTerminal(spec, emit) {
                 clearRunIdleNotify(id);
                 broadcast({ type: "terminal.exit", termId: id, code });
                 broadcast({ type: "terminal.closed", termId: id });
+                // Mark the durable row idle and, for agents that assign their id lazily
+                // (no launch-time pin), discover the on-disk session now so it still
+                // appears in the sidebar after the PTY is gone.
+                if (!spec.mux && spec.agent) {
+                    const agentId = spec.agent;
+                    void (async () => {
+                        let sessionRef = spec.sessionId;
+                        if (!sessionRef) {
+                            try {
+                                sessionRef = await SESSION_DISCOVERY_BY_AGENT[agentId]?.(workspace, createdAt);
+                            }
+                            catch {
+                                /* agent may never have written a session */
+                            }
+                        }
+                        if (sessionRef) {
+                            const runtimeId = TAKEOVER_RUNTIME_BY_AGENT[agentId] ?? agentId;
+                            try {
+                                metadata.upsertSession({
+                                    id: sessionRef,
+                                    runtimeId,
+                                    agentName: agentId,
+                                    workspace,
+                                    name: name || undefined,
+                                    source: "cli",
+                                    status: "saved",
+                                });
+                            }
+                            catch {
+                                /* best-effort */
+                            }
+                        }
+                    })();
+                }
                 // Unify keys, reverse direction: a login done inside the agent's own CLI
                 // (e.g. `codex login`) is folded back into Bivy's vault, then synced.
                 if (!spec.mux) {
@@ -1835,9 +1873,37 @@ async function openRunTerminal(spec, emit) {
             },
         });
         runTerminals.add(id);
-        const createdAt = Date.now();
+        // Persist a durable metadata row when the run has a known session id (pinned
+        // at launch, e.g. `claude --session-id` / `grok --session-id`). Without this,
+        // a `bivy run` session vanishes from the sidebar the moment the PTY exits —
+        // only live run-terminals were listed. The metadata backfill in
+        // listAllSessions then keeps it resumable after close.
+        if (spec.sessionId && spec.agent && !spec.mux) {
+            const runtimeId = TAKEOVER_RUNTIME_BY_AGENT[spec.agent] ?? spec.agent;
+            try {
+                metadata.upsertSession({
+                    id: spec.sessionId,
+                    runtimeId,
+                    agentName: spec.agent,
+                    workspace,
+                    name: name || undefined,
+                    source: "cli",
+                    status: "working",
+                });
+            }
+            catch {
+                /* best-effort: a metadata write must never block the run launch */
+            }
+        }
         emit({ type: "terminal.opened", termId: id, workspace, mode: "run", agent: spec.agent, label, name });
         broadcast({ type: "terminal.created", terminal: { termId: id, workspace, createdAt, lastActivityAt: createdAt, kind: "run", agent: spec.agent, model: spec.model, label, name, command: commandLine, mux: spec.mux, sessionId: spec.sessionId, pid: terminals.pid(id) } });
+        // Surface the durable row so the sidebar keeps the session after the PTY
+        // exits (listAllSessions backfills from metadata). Best-effort broadcast.
+        if (spec.sessionId && !spec.mux) {
+            void listAllSessions()
+                .then((sessions) => broadcast({ type: "sessions.list", sessions: sessions.map((s) => ({ ...s, sessionId: s.id })) }))
+                .catch(() => { });
+        }
         return id;
     }
     catch (error) {
@@ -1856,11 +1922,15 @@ const TAKEOVER_RUNTIME_BY_AGENT = {
     // exec-created session resumes through the app-server with full context), so
     // the adopted chat gets per-tool approvals, not just the exec jail.
     codex: "codex-approvals",
+    // Official Grok CLI: resume by UUID via `grok --resume <id> -p …` (process
+    // runtime) after the interactive TUI is stopped.
+    grok: "grok",
 };
 // The CLI command to continue an adopted session back in a terminal.
 const RESUME_CLI_BY_AGENT = {
     claude: (id) => `claude --resume ${id}`,
     codex: (id) => `codex resume ${id}`,
+    grok: (id) => `grok --resume ${id}`,
 };
 // Same commands, keyed by runtime id instead of the short takeover agent alias
 // above — for native session discovery (issue #156), where a session with a
@@ -1871,6 +1941,7 @@ const RESUME_CLI_BY_AGENT = {
 const NATIVE_RESUME_CLI_BY_RUNTIME = {
     "claude-code-sdk": (id) => `claude --resume ${id}`,
     "codex-approvals": (id) => `codex resume ${id}`,
+    grok: (id) => `grok --resume ${id}`,
 };
 // When no resumable session id can be found, why — and what to do about it.
 // These agents assign their id lazily (Codex/Pi write a session only once a turn
@@ -1878,6 +1949,7 @@ const NATIVE_RESUME_CLI_BY_RUNTIME = {
 const TAKEOVER_EMPTY_HINT_BY_AGENT = {
     codex: "Codex writes its session only after the first message. Send one message in the terminal, then continue as chat.",
     pi: "Pi assigns its session once the conversation starts. Send one message in the terminal, then continue as chat.",
+    grok: "Grok writes its session once the conversation starts. Send one message in the terminal, then continue as chat.",
 };
 // For agents with no launch-time session-id pin, locate the on-disk session a run
 // produced (by cwd + start time) so a takeover can still resume the right one.
@@ -1890,6 +1962,10 @@ const SESSION_DISCOVERY_BY_AGENT = {
         const match = discoverPiSessionForCwd(await runtimeHost.listSessions(getRuntime("pi")), cwd, since);
         return match?.path || match?.id;
     },
+    // Grok can be pinned at launch (`--session-id`) but also assigns ids lazily
+    // when the pin flag is absent; correlate by cwd + start time against
+    // ~/.grok/sessions.
+    grok: (cwd, since) => discoverGrokSessionForCwd(cwd, since)?.id,
 };
 // "Continue as chat": stop the native TUI running in a pinned run-terminal and
 // reopen its session as a governed, structured chat on the owning runtime. The

package/dist/terminal.js

@@ -16,7 +16,11 @@ import { depCacheEnv } from "./harness/dep-cache.js";
  * that by an order of magnitude while adding latency well below the threshold of
  * perception for interactive echo.
  */
-const OUTPUT_FLUSH_MS = 8;
+// 16ms keeps a single chatty TUI under the relay's default node message budget
+// (6000/min ≈ 10ms/frame). At 8ms a fullscreen redraw stream could exceed that
+// and the relay closed the socket with "Rate limit exceeded" the moment a
+// phone/app attached to a live `bivy run` terminal.
+const OUTPUT_FLUSH_MS = 16;
 /**
  * How much recent output to retain per terminal for scrollback replay on
  * reconnect. A phone that backgrounds the PWA (or drops its network) reattaches

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.10.1-staging.150",
+  "version": "0.10.1-staging.152",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",