@gleapai/kai-bridge 0.2.0

package/src/preview.mjs

@@ -0,0 +1,337 @@
+// Preview tier A — run the app's real dev servers next to the session.
+//
+// Each repo may commit a `.gleap/dev.yaml`:
+//
+//   services:
+//     api: { cwd: Server,   run: "npm run dev", port: 9000, health: /health }
+//     web: { cwd: Frontend, run: "npm start",   port: 3000, env: { API_URL: "http://localhost:9000" } }
+//   preview: web
+//
+// Worktree mode: every service gets a FREE port (the user's own dev server
+// may already own the declared one) — `PORT` is set and `${port:<name>}`
+// placeholders in `env`/`run` are substituted, so `API_URL: http://localhost:${port:api}`
+// follows the re-assignment. Local mode: a service whose declared port is
+// already listening is adopted as "your running dev server" instead of
+// started twice.
+//
+// Logs go to `~/.kai/logs/services/<session>/<service>.log` so Kai can
+// `tail` them; the timeline only gets one line per start/stop/failure.
+// The preview URL is local (`http://localhost:<port>`) plus the LAN
+// address for the phone on the same network — a public tunnel is a
+// later tier (needs relay infra).
+
+import { spawn } from "node:child_process";
+import { createServer, connect } from "node:net";
+import { existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { networkInterfaces } from "node:os";
+import { join, resolve } from "node:path";
+import YAML from "yaml";
+
+export const DEV_CONFIG_PATHS = [".gleap/dev.yaml", ".gleap/dev.yml"];
+
+export function readDevConfig(repoRoot) {
+  for (const rel of DEV_CONFIG_PATHS) {
+    const p = join(repoRoot, rel);
+    if (!existsSync(p)) continue;
+    try {
+      const parsed = YAML.parse(readFileSync(p, "utf8")) || {};
+      return normalizeDevConfig(parsed);
+    } catch (err) {
+      return { services: {}, preview: null, companions: [], error: `${rel}: ${err?.message || err}` };
+    }
+  }
+  return null;
+}
+
+export function normalizeDevConfig(raw) {
+  const services = {};
+  for (const [name, s] of Object.entries(raw?.services || {})) {
+    if (!s || typeof s !== "object" || !s.run) continue;
+    services[name] = {
+      name,
+      cwd: typeof s.cwd === "string" ? s.cwd : ".",
+      run: String(s.run),
+      port: Number.isFinite(Number(s.port)) ? Number(s.port) : null,
+      health: typeof s.health === "string" ? s.health : null,
+      env: s.env && typeof s.env === "object" ? Object.fromEntries(Object.entries(s.env).map(([k, v]) => [k, String(v)])) : {},
+      readyTimeoutMs: Number.isFinite(Number(s.readyTimeoutMs)) ? Number(s.readyTimeoutMs) : 90_000,
+    };
+  }
+  const preview = typeof raw?.preview === "string" && services[raw.preview] ? raw.preview : Object.keys(services)[0] || null;
+  // Companion repos this preview needs running alongside (an API for a
+  // frontend, etc). Entries are repo keys as reported by the device scan
+  // ("github.com/owner/name") — strings, or {repo, optional} objects.
+  // Optional companions degrade to a warning when they can't boot.
+  const companions = [];
+  for (const entry of Array.isArray(raw?.companions) ? raw.companions : []) {
+    const repo = typeof entry === "string" ? entry : typeof entry?.repo === "string" ? entry.repo : null;
+    if (!repo) continue;
+    companions.push({ repo: repo.toLowerCase().trim(), optional: !!(entry && typeof entry === "object" && entry.optional) });
+  }
+  return { services, preview, companions, error: null };
+}
+
+/**
+ * No-config fallback: infer a single dev service from the repo's root
+ * package.json. `.gleap/dev.yaml` stays the durable override — callers
+ * check `readDevConfig` first. Returns null when nothing runnable is
+ * found (no package.json, or no dev/start/serve script).
+ */
+export function detectDevConfig(repoRoot) {
+  const pkgPath = join(repoRoot, "package.json");
+  if (!existsSync(pkgPath)) return null;
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf8")) || {};
+  } catch {
+    return null;
+  }
+  const scripts = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  const script = ["dev", "start", "serve"].find((s) => typeof scripts[s] === "string" && scripts[s].trim());
+  if (!script) return null;
+  const pm = existsSync(join(repoRoot, "pnpm-lock.yaml"))
+    ? "pnpm"
+    : existsSync(join(repoRoot, "yarn.lock"))
+      ? "yarn"
+      : "npm";
+  return normalizeDevConfig({
+    services: {
+      // No declared port: ServiceRunner assigns a free one and exports
+      // PORT; readiness falls back to the port-listen probe.
+      app: { cwd: ".", run: `${pm} run ${script}`, readyTimeoutMs: 90_000 },
+    },
+    preview: "app",
+  });
+}
+
+function probePort(port, host) {
+  return new Promise((resolveP) => {
+    const sock = connect({ port, host });
+    const done = (v) => {
+      sock.destroy();
+      resolveP(v);
+    };
+    sock.once("connect", () => done(true));
+    sock.once("error", () => done(false));
+    sock.setTimeout(500, () => done(false));
+  });
+}
+
+export async function isPortListening(port, host) {
+  if (host) return probePort(port, host);
+  // Node 17+ resolves `localhost` to ::1 first, so dev servers often
+  // bind IPv6-only — an IPv4-only probe then reports "not ready" for a
+  // perfectly running server (bit us with Docusaurus). Check both.
+  const [v4, v6] = await Promise.all([probePort(port, "127.0.0.1"), probePort(port, "::1")]);
+  return v4 || v6;
+}
+
+export function getFreePort() {
+  return new Promise((resolveP, reject) => {
+    const srv = createServer();
+    srv.unref();
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const { port } = srv.address();
+      srv.close(() => resolveP(port));
+    });
+  });
+}
+
+export function lanAddress() {
+  for (const list of Object.values(networkInterfaces())) {
+    for (const i of list || []) if (i.family === "IPv4" && !i.internal) return i.address;
+  }
+  return null;
+}
+
+/** `${port:api}` → assigned port of service `api`. */
+export function substitutePorts(value, ports) {
+  return String(value).replace(/\$\{port:([\w-]+)\}/g, (_, name) => String(ports[name] ?? ""));
+}
+
+async function waitForReady({ port, health, timeoutMs }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (health) {
+      try {
+        // `localhost`, not 127.0.0.1 — the server may be IPv6-only (see
+        // isPortListening); Node's fetch tries both families.
+        const res = await fetch(`http://localhost:${port}${health.startsWith("/") ? health : `/${health}`}`, { signal: AbortSignal.timeout(2000) });
+        if (res.ok || (res.status >= 300 && res.status < 500)) return true;
+      } catch {
+        /* not yet */
+      }
+    } else if (await isPortListening(port)) {
+      return true;
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return false;
+}
+
+/**
+ * Runs the services of one repo binding for the lifetime of a turn (or
+ * longer — the daemon keeps them per session until the session ends).
+ */
+export class ServiceRunner {
+  constructor({ kaiHome, sessionId, log = () => {}, onStatus = () => {} }) {
+    this.kaiHome = kaiHome;
+    this.sessionId = sessionId;
+    this.log = log;
+    this.onStatus = onStatus;
+    this.processes = new Map(); // name → child
+    this.ports = {}; // name → port
+    this.adopted = new Set();
+    this.logDir = join(kaiHome, "logs", "services", String(sessionId).replace(/[^\w.-]/g, "_"));
+  }
+
+  /**
+   * Start (or adopt) every service in `config` relative to `repoRoot`.
+   * Returns `{ services: [{name, port, url, logPath, adopted, ready}], preview: {name, url, lanUrl} | null }`.
+   */
+  async start(repoRoot, config, { mode = "worktree" } = {}) {
+    mkdirSync(this.logDir, { recursive: true });
+    const out = [];
+    // Assign ports first so cross-references resolve.
+    for (const svc of Object.values(config.services)) {
+      if (this.ports[svc.name]) continue;
+      const declared = svc.port;
+      if (mode === "local" && declared && (await isPortListening(declared))) {
+        this.ports[svc.name] = declared;
+        this.adopted.add(svc.name);
+      } else if (declared && !(await isPortListening(declared))) {
+        this.ports[svc.name] = declared;
+      } else {
+        this.ports[svc.name] = await getFreePort();
+      }
+    }
+    for (const svc of Object.values(config.services)) {
+      const port = this.ports[svc.name];
+      const logPath = join(this.logDir, `${svc.name}.log`);
+      if (this.adopted.has(svc.name)) {
+        out.push({ name: svc.name, port, url: `http://localhost:${port}`, logPath: null, adopted: true, ready: true });
+        this.onStatus(`Using your running ${svc.name} on :${port}`);
+        continue;
+      }
+      if (this.processes.has(svc.name)) {
+        out.push({ name: svc.name, port, url: `http://localhost:${port}`, logPath, adopted: false, ready: true });
+        continue;
+      }
+      const cwd = resolve(repoRoot, svc.cwd);
+      const env = {
+        ...process.env,
+        PORT: String(port),
+        ...Object.fromEntries(Object.entries(svc.env).map(([k, v]) => [k, substitutePorts(v, this.ports)])),
+        KAI_SESSION_ID: String(this.sessionId),
+        BROWSER: "none",
+      };
+      const fd = openSync(logPath, "a");
+      // Fresh worktrees have no node_modules — running the dev command
+      // straight into `command not found` was the #1 preview failure.
+      await this.ensureDeps(cwd, { env, fd, logPath });
+      const cmd = substitutePorts(svc.run, this.ports);
+      // Under launchd the daemon's PATH is frozen at install time
+      // (service.mjs), so nvm/pnpm shims don't resolve with a bare
+      // `shell: true`. A login shell rebuilds the user's real PATH.
+      const child =
+        process.platform === "darwin"
+          ? spawn("/bin/zsh", ["-lc", cmd], { cwd, env, stdio: ["ignore", fd, fd], detached: true })
+          : spawn(cmd, { cwd, env, shell: true, stdio: ["ignore", fd, fd], detached: true });
+      child.on("exit", (code) => {
+        this.processes.delete(svc.name);
+        this.log("info", "service.exit", { name: svc.name, code });
+        if (code && code !== 0) this.onStatus(`${svc.name} exited with code ${code} — see ${logPath}`);
+      });
+      this.processes.set(svc.name, child);
+      this.onStatus(`Starting ${svc.name} (${svc.run}) on :${port}`);
+      // Bail as soon as the process dies (command not found, crash on
+      // boot) instead of polling a dead port for the full timeout.
+      const ready = await Promise.race([
+        waitForReady({ port, health: svc.health, timeoutMs: svc.readyTimeoutMs }),
+        new Promise((resolveP) => child.once("exit", () => setTimeout(() => resolveP(false), 300))),
+      ]);
+      this.onStatus(ready ? `${svc.name} ready on http://localhost:${port}` : `${svc.name} did not become ready within ${Math.round(svc.readyTimeoutMs / 1000)}s — see ${logPath}`);
+      out.push({ name: svc.name, port, url: `http://localhost:${port}`, logPath, adopted: false, ready });
+    }
+    const previewSvc = config.preview ? out.find((s) => s.name === config.preview) : null;
+    const lan = lanAddress();
+    return {
+      services: out,
+      preview: previewSvc ? { name: previewSvc.name, url: previewSvc.url, lanUrl: lan ? `http://${lan}:${previewSvc.port}` : null, adopted: !!previewSvc.adopted } : null,
+    };
+  }
+
+  /**
+   * Install JS dependencies when the service dir has a package.json but
+   * no node_modules (fresh worktree). Package manager by lockfile; up
+   * to 5 minutes; output goes to the service log. No-op otherwise.
+   */
+  async ensureDeps(cwd, { env, fd, logPath }) {
+    if (!existsSync(join(cwd, "package.json")) || existsSync(join(cwd, "node_modules"))) return;
+    const pm = existsSync(join(cwd, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(cwd, "yarn.lock")) ? "yarn" : "npm";
+    const installCmd = `${pm} install`;
+    this.onStatus(`Installing dependencies (${installCmd}) — first preview in this workspace…`);
+    this.log("info", "service.install", { cwd, pm });
+    const code = await new Promise((resolveP) => {
+      const child =
+        process.platform === "darwin"
+          ? spawn("/bin/zsh", ["-lc", installCmd], { cwd, env, stdio: ["ignore", fd, fd] })
+          : spawn(installCmd, { cwd, env, shell: true, stdio: ["ignore", fd, fd] });
+      const timer = setTimeout(() => {
+        try {
+          child.kill("SIGTERM");
+        } catch {}
+        resolveP(-1);
+      }, 5 * 60_000);
+      child.on("exit", (c) => {
+        clearTimeout(timer);
+        resolveP(c ?? -1);
+      });
+      child.on("error", () => {
+        clearTimeout(timer);
+        resolveP(-1);
+      });
+    });
+    if (code !== 0) this.onStatus(`${installCmd} exited with code ${code} — see ${logPath}`);
+  }
+
+  stopAll() {
+    for (const [name, child] of this.processes) {
+      try {
+        process.kill(-child.pid, "SIGTERM");
+      } catch {
+        try {
+          child.kill("SIGTERM");
+        } catch {
+          /* gone */
+        }
+      }
+      this.log("info", "service.stop", { name });
+    }
+    this.processes.clear();
+  }
+
+  /** Prompt section telling the agent what is running + how to verify. */
+  describeForAgent(started) {
+    if (!started || started.services.length === 0) return "";
+    const lines = started.services.map(
+      (s) => `- ${s.name}: ${s.url}${s.adopted ? " (your already-running dev server)" : ""}${s.logPath ? ` · logs: ${s.logPath}` : ""}${s.ready ? "" : " (NOT ready — check the log)"}`,
+    );
+    return (
+      `\n\nDev services running for this session:\n${lines.join("\n")}\n` +
+      `Use the \`gleap_preview\` browser tools (navigate, snapshot, screenshot, console messages) to verify your change in ${started.preview?.url || "the app"} before you finish. ` +
+      `Tail the service logs with the Read/Bash tools if something fails.`
+    );
+  }
+}
+
+/** The Playwright MCP server registration for the turn (stdio, headless). */
+export function previewMcpServer(runnerDir) {
+  return {
+    id: "gleap_preview",
+    name: "gleap_preview",
+    command: process.execPath,
+    args: [join(runnerDir, "..", "node_modules", "@playwright", "mcp", "cli.js"), "--headless", "--isolated"],
+  };
+}

package/src/profiles.mjs

@@ -0,0 +1,250 @@
+// Harness profiles = which login a session runs under.
+//
+//   ambient  — the user's own `~/.claude` / `~/.codex`. Read-only: the
+//              bridge never writes there, it only points the harness at it.
+//   managed  — an isolated config dir under `~/.kai/accounts/<harness>/<id>/`
+//              seeded from ambient (settings, skills) and logged in
+//              separately (`kai-bridge profile login <id>`), so a second
+//              Claude/ChatGPT account lives side by side. Claude Code honours
+//              CLAUDE_CONFIG_DIR, Codex honours CODEX_HOME — that's the whole
+//              trick (same model as Traycer's provider profiles).
+//   gleap-key — no login on the device; the Server hands the bridge an API
+//              key per turn and bills credits as in the cloud.
+
+import { execFileSync, spawn } from "node:child_process";
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { HARNESS_IDS as REGISTRY_IDS, harnessBinary, harnessLoginCommand, probeHarnessAuth } from "./harnesses.mjs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const HARNESSES = REGISTRY_IDS;
+const HOME = homedir();
+
+export function ambientConfigDir(harness, home = HOME) {
+  if (harness === "claude") return process.env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+  if (harness === "codex") return process.env.CODEX_HOME || join(home, ".codex");
+  if (harness === "cursor") return join(home, ".cursor"); // informational — Cursor has no per-profile config dir
+  throw new Error(`unknown harness ${harness}`);
+}
+
+export function managedConfigDir(harness, profileId, kaiHome) {
+  return join(kaiHome, "accounts", harness, profileId);
+}
+
+const PKG_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "node_modules", ".bin");
+
+/**
+ * Where the harness binary is. `codex` prefers the build bundled with the
+ * bridge (codex-acp's own @openai/codex — the same one the ACP adapter
+ * spawns, so auth probes and turns agree); `claude` is the user's install.
+ */
+export function findBinary(name) {
+  if (name === "claude" || name === "codex" || name === "cursor") {
+    const bundled = harnessBinary(name, process.env.KAI_HOME || join(HOME, ".kai"));
+    if (bundled) return bundled;
+  }
+  try {
+    return execFileSync(process.platform === "win32" ? "where" : "which", [name], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+      .split(/\r?\n/)[0]
+      .trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function run(cmd, args, env, timeoutMs = 15000) {
+  return new Promise((resolve) => {
+    let out = "";
+    let err = "";
+    let done = false;
+    const child = spawn(cmd, args, { env, stdio: ["ignore", "pipe", "pipe"] });
+    const t = setTimeout(() => {
+      if (!done) child.kill("SIGKILL");
+    }, timeoutMs);
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("error", () => {
+      done = true;
+      clearTimeout(t);
+      resolve({ code: -1, out, err });
+    });
+    child.on("close", (code) => {
+      done = true;
+      clearTimeout(t);
+      resolve({ code, out, err });
+    });
+  });
+}
+
+/**
+ * Probe a profile's auth state without touching it.
+ *   claude: `claude auth status` exits 0 when logged in (ported from the
+ *           retired desktop runtime's discovery.mjs).
+ *   codex:  `auth.json` with `tokens` (ChatGPT) or `OPENAI_API_KEY`.
+ * Returns `{ state: 'signed_in'|'signed_out'|'missing_binary', account?, version? }`.
+ */
+export async function probeAuth(harness, configDir, kaiHome = process.env.KAI_HOME || join(HOME, ".kai")) {
+  const bin = harnessBinary(harness, kaiHome);
+  if (!bin) return { state: "missing_binary" };
+  const auth = probeHarnessAuth(harness, configDir, kaiHome);
+  const version = (await run(bin, ["--version"], { ...process.env })).out.trim().split(/\r?\n/)[0] || undefined;
+  return { ...auth, version, binary: bin };
+}
+
+/** Create a managed profile dir seeded from ambient (settings/skills only, never credentials). */
+export function createManagedProfile(harness, profileId, kaiHome) {
+  const dir = managedConfigDir(harness, profileId, kaiHome);
+  mkdirSync(dir, { recursive: true });
+  const ambient = ambientConfigDir(harness);
+  const seedable = harness === "claude" ? ["settings.json", "skills", "plugins", "CLAUDE.md"] : ["config.toml", "skills"];
+  for (const name of seedable) {
+    const src = join(ambient, name);
+    if (existsSync(src) && !existsSync(join(dir, name))) {
+      try {
+        cpSync(src, join(dir, name), { recursive: true });
+      } catch {
+        /* best-effort seed */
+      }
+    }
+  }
+  return dir;
+}
+
+/** Interactive login for a profile (opens the harness's own flow). */
+export function loginCommand(harness, configDir, kaiHome = process.env.KAI_HOME || join(HOME, ".kai")) {
+  const c = harnessLoginCommand(harness, configDir, kaiHome);
+  if (!c) return null;
+  return { cmd: c.cmd, args: c.args, env: { ...process.env, ...c.env } };
+}
+
+/**
+ * Both harness logins are interactive (claude prints "Please run /login"
+ * when headless), so a remote "Sign in" opens a terminal window ON THE
+ * DEVICE running the login under the profile's config dir. Returns the
+ * spawned process or null when no terminal could be opened.
+ */
+export function openLoginTerminal(harness, configDir) {
+  const c = loginCommand(harness, configDir);
+  if (!c) return null;
+  // Ambient claude must log in with the env untouched so credentials land
+  // in the keychain, where the (equally untouched) probe and turns look.
+  const claudeAmbient = harness === "claude" && resolve(configDir) === resolve(ambientConfigDir("claude"));
+  const envPrefix =
+    harness === "claude"
+      ? claudeAmbient
+        ? ""
+        : `CLAUDE_CONFIG_DIR=${shellQuote(configDir)} `
+      : harness === "codex"
+        ? `CODEX_HOME=${shellQuote(configDir)} `
+        : "NO_OPEN_BROWSER=0 ";
+  const line = `${envPrefix}${shellQuote(c.cmd)} login`;
+  if (process.platform === "darwin") {
+    return spawn("osascript", ["-e", `tell application "Terminal" to activate`, "-e", `tell application "Terminal" to do script ${JSON.stringify(line)}`], { stdio: "ignore", detached: true });
+  }
+  if (process.platform === "win32") {
+    return spawn("cmd", ["/c", "start", "cmd", "/k", line.replace(/^([A-Z_]+)=('[^']*') /, "set $1=$2 && ")], { stdio: "ignore", detached: true, shell: true });
+  }
+  for (const term of ["x-terminal-emulator", "gnome-terminal", "konsole", "xterm"]) {
+    if (findBinary(term)) {
+      const args = term === "gnome-terminal" ? ["--", "bash", "-lc", line] : ["-e", `bash -lc ${shellQuote(line)}`];
+      return spawn(term, args, { stdio: "ignore", detached: true });
+    }
+  }
+  return null;
+}
+
+const shellQuote = (v) => `'${String(v).replace(/'/g, `'\\''`)}'`;
+
+/** Shape reported to the Server in `hello`. */
+export async function describeProfiles(profiles, usageByProfile = null) {
+  const out = [];
+  for (const p of profiles) {
+    const auth = await probeAuth(p.harness, p.configDir);
+    out.push({
+      id: p.id,
+      harness: p.harness,
+      kind: p.kind,
+      label: p.label,
+      authState: auth.state,
+      account: auth.account ?? null,
+      version: auth.version ?? null,
+      rateLimit: p.rateLimit ?? null,
+      usageLimits: usageByProfile?.get?.(p.id) ?? null,
+    });
+  }
+  return out;
+}
+
+// ── Plan-usage limits (Claude Code) ──────────────────────────────────
+//
+// `claude -p "/usage"` prints the same windows the CLI's own usage
+// panel shows (5-hour session, weekly all-models, weekly per-model),
+// ~2s with --strict-mcp-config since no MCP servers spawn. Subscription
+// logins only — an API-key login prints no window lines and parses to
+// null. Codex has no equivalent surface today.
+//
+//   Current session: 3% used · resets Aug 24 at 4:50pm (Europe/Vienna)
+//   Current week (all models): 0% used · resets Aug 27 at 8am (…)
+//   Current week (Fable): 0% used · resets Aug 27 at 8am (…)
+export function parseClaudeUsageOutput(text) {
+  const windows = [];
+  const push = (id, label, line) => {
+    const m = /:\s*(?:(<?\s*\d+(?:\.\d+)?)%\s*used)\s*(?:·\s*resets\s*(.+?))?\s*$/i.exec(line);
+    if (!m) return;
+    const percent = Number(String(m[1]).replace("<", "").trim());
+    if (!Number.isFinite(percent)) return;
+    windows.push({
+      id,
+      label,
+      usedPercent: Math.max(0, Math.min(100, percent)),
+      // Keep the CLI's own phrasing, minus the timezone parenthesis —
+      // parsing "Aug 24 at 4:50pm" into a Date is locale quicksand.
+      resetsText: (m[2] || "").replace(/\s*\([^)]*\)\s*$/, "").trim() || null,
+    });
+  };
+  for (const raw of String(text || "").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (/^current session:/i.test(line)) push("session", "5-hour limit", line);
+    else if (/^current week \(all models\):/i.test(line)) push("week-all", "Weekly · all models", line);
+    else {
+      const m = /^current week \(([^)]+)\):/i.exec(line);
+      if (m && m[1].toLowerCase() !== "all models") push("week-model", `Weekly · ${m[1]}`, line);
+    }
+  }
+  return windows;
+}
+
+const SUBSCRIPTION_LABELS = { pro: "Pro", max: "Max", team: "Team", enterprise: "Enterprise" };
+
+/**
+ * Fetch the plan-usage windows for one profile. Returns
+ * `{ plan, windows, fetchedAt }` or null (not claude, signed out,
+ * API-key login, or the CLI changed its output). Never throws.
+ */
+export async function probeUsageLimits(harness, configDir, kaiHome = process.env.KAI_HOME || join(HOME, ".kai")) {
+  if (harness !== "claude") return null;
+  const bin = harnessBinary(harness, kaiHome);
+  if (!bin) return null;
+  const env = { ...process.env };
+  delete env.ANTHROPIC_API_KEY;
+  // Ambient = the CLI's own default dir; the env must stay untouched so
+  // macOS keychain credentials resolve (same rule as probes and turns).
+  if (resolve(configDir) === resolve(ambientConfigDir("claude"))) delete env.CLAUDE_CONFIG_DIR;
+  else env.CLAUDE_CONFIG_DIR = configDir;
+  const res = await run(bin, ["-p", "/usage", "--strict-mcp-config"], env, 30_000);
+  if (res.code !== 0) return null;
+  const windows = parseClaudeUsageOutput(res.out);
+  if (windows.length === 0) return null;
+  let plan = null;
+  const status = await run(bin, ["auth", "status", "--json"], env, 15_000);
+  if (status.code === 0) {
+    try {
+      const type = String(JSON.parse(status.out)?.subscriptionType || "").toLowerCase();
+      plan = SUBSCRIPTION_LABELS[type] ?? (type ? type[0].toUpperCase() + type.slice(1) : null);
+    } catch {
+      /* label is cosmetic */
+    }
+  }
+  return { source: "subscription", plan, windows, fetchedAt: new Date().toISOString() };
+}