@venturewild/workspace 0.1.1 → 0.1.2

package/README.md

@@ -2,12 +2,23 @@
 
 A Replit/Lovable-style **chat-first** browser UI that wraps the AI agent already installed on your machine (Claude Code by default; Gemini / GLM / Codex if present).
 
-> v0.1.0 — initial scaffold, implements PRD §5.5 (workspace-platform-prd.md v0.10).
+> v0.1.1 — chat-first workspace + bmo-sync daemon (npm) + per-user proxy (b-ii) live. Implements PRD §5.5 (workspace-platform-prd.md v0.10).
 
 ## Quick start
 
 ```bash
-# install agent dependencies & web build
+# recommended — global install from npm
+npm i -g @venturewild/workspace
+wild-workspace
+```
+
+A global install pulls the matching **bmo-sync daemon** binary automatically for
+win32-x64 / darwin-x64 / darwin-arm64 / linux-x64 (shipped as `optionalDependencies`).
+
+To build from source instead (dev path):
+
+```bash
+# install dependencies & web build
 npm install
 npm run build
 
@@ -30,18 +41,23 @@ wild-workspace/
 │       ├── index.mjs            # server bootstrap
 │       ├── config.mjs           # config + role definitions
 │       ├── agent.mjs            # claude / gemini / glm / codex subprocess wrapper
+│       ├── account.mjs          # login / account + slug claim
 │       ├── share.mjs            # JWT share-token mint + verify
 │       ├── inbox.mjs            # .wild/inbox.md watcher
 │       ├── fs.mjs               # workspace file tree (collapsed by default)
 │       ├── activity.mjs         # AI activity event bus
 │       ├── preview.mjs          # dev-server port detection
+│       ├── sync.mjs             # bmo-sync wiring
+│       ├── daemon-bin.mjs       # resolves the platform daemon binary
 │       └── routes/              # REST + WS endpoints
 ├── web/                   # React + Vite frontend
 │   └── src/
 │       ├── App.jsx              # role-flagged React tree (partner / viewer / client)
-│       ├── components/          # Chat, Preview, FileTree, Terminal, ShareDialog…
+│       ├── components/          # Chat, Preview, FileTree, Onboarding, ShareDialog…
 │       └── state/               # session + chat stores
-└── docs/                  # design notes
+├── vw-proxy/              # Cloudflare Worker — public *.venturewild.llc front door
+├── landing/               # marketing / landing page (Cloudflare Pages)
+└── docs/                  # design notes (incl. b-ii-proxy-plan.md / -design.md)
 ```
 
 ## The three roles (AR-19)
@@ -49,6 +65,7 @@ wild-workspace/
 | Role | URL pattern | What they see |
 |---|---|---|
 | **partner** | `http://localhost:5173` | Chat + preview + file tree + terminal toggle + inbox + share + deploy |
+| **partner (published)** | `https://<user>.venturewild.llc` | Your workspace, live on your claimed per-user subdomain (e.g. `tuananh.venturewild.llc`) |
 | **viewer** | `https://<user>.venturewild.llc/<wsid>?t=<token>` | Chat history (read-only) + preview + presence + activity stream |
 | **client** | `https://workspace.<client>.com` | Chat + preview + "request changes" only |
 
@@ -56,7 +73,29 @@ Same React tree, role-gated visibility (AR-19).
 
 ## AR-17: wrap don't embed
 
-We don't ship an AI agent. `server/src/agent.mjs` spawns `claude` (or `gemini` / `glm` / `codex` if installed) as a subprocess and pipes stdout/stderr through WebSocket to the chat UI. The wrapped agent's modes mirror automatically (AR-18).
+We don't ship an AI agent. `server/src/agent.mjs` spawns `claude` (or `gemini` / `glm` / `codex` if installed) as a subprocess and pipes stdout/stderr through WebSocket to the chat UI. The wrapped agent's modes mirror automatically (AR-18). (The one native binary we *do* bundle is the bmo-sync daemon — see below.)
+
+## bmo-sync daemon + per-user URLs
+
+The workspace bundles the **bmo-sync daemon** (run as a subprocess) which links your
+local workspace to a per-user subdomain `https://<user>.venturewild.llc`:
+
+```
+browser → vw-proxy (Cloudflare Worker on *.venturewild.llc)
+        → bmo-sync (Fly, bmo-sync.fly.dev) → your daemon → local workspace server
+```
+
+The Worker reads the `Host` header, resolves the slug via bmo-sync, and forwards to
+the bmo-sync Fly origin, which proxies to your most-recently-connected daemon. A
+**claimed** slug serves your live workspace (e.g. `tuananh.venturewild.llc` → 200); an
+**unclaimed** slug 302-redirects to the landing page (e.g. `apple.venturewild.llc`).
+
+The daemon ships via npm `optionalDependencies` (`@venturewild/workspace-daemon-*@0.1.0`
+for win32-x64 / darwin-x64 / darwin-arm64 / linux-x64), resolved at launch by
+`server/src/daemon-bin.mjs`. Shipped + verified live as of 2026-05-30; see
+[`docs/b-ii-proxy-plan.md`](docs/b-ii-proxy-plan.md),
+[`docs/b-ii-proxy-design.md`](docs/b-ii-proxy-design.md), and
+[`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md).
 
 ## Rich chat rendering
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturewild/workspace",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Claude Code Web — Replit/Lovable-style chat-first browser UI that wraps the AI agent already installed on your machine.",
   "license": "MIT",
   "bin": {

package/server/bin/wild-workspace.mjs

@@ -5,6 +5,7 @@
 
 import path from 'node:path';
 import url from 'node:url';
+import os from 'node:os';
 import { createServer } from '../src/index.mjs';
 import { APP_VERSION, buildConfig } from '../src/config.mjs';
 import { DaemonSupervisor } from '../src/daemon-supervisor.mjs';
@@ -15,6 +16,13 @@ import {
   loadAccount,
   clearAccount,
 } from '../src/account.mjs';
+import { readFileSync } from 'node:fs';
+import { WorkspaceSupervisor, probeHealth } from '../src/supervisor.mjs';
+import { installService, uninstallService, serviceStatus, globalDir } from '../src/service.mjs';
+import { appendLine, listLogs, tailFile } from '../src/logpaths.mjs';
+import { runDoctor, renderDoctor, writeDoctorBundle } from '../src/doctor.mjs';
+import { enableOperator, disableOperator, operatorStatus } from '../src/operator.mjs';
+import { loadObservabilityConsent, setObservabilityConsent } from '../src/observability.mjs';
 
 const __filename = url.fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -38,6 +46,15 @@ Usage:
   wild-workspace logout           clear the bound account (slug + token)
   wild-workspace whoami           show the currently-bound account
   wild-workspace rotate-token     mint a new account token; invalidates the old one
+  wild-workspace doctor [--share] diagnose this machine's install (✅/⚠️/❌ + logs)
+  wild-workspace logs [name] [--tail N]   list logs, or tail one (cli/server/daemon/…)
+  wild-workspace operator enable  let the wild-workspace team help with your install (mints a token)
+  wild-workspace operator disable revoke the support token
+  wild-workspace operator status  is the support channel on?
+  wild-workspace observability [on|off|status]   share session + install health so we can help (default on; never chat content)
+  wild-workspace service install  keep your workspace always-on (starts at login, no admin)
+  wild-workspace service uninstall   turn always-on off
+  wild-workspace service status   show always-on status (installed? supervisor? server?)
   wild-workspace install          (info) how the sync daemon is managed
   wild-workspace --help           this message
   wild-workspace --version        print version
@@ -64,6 +81,11 @@ function parseArgs(argv) {
     else if (arg === '--port') { opts.port = Number(argv[++i]); }
     else if (arg === '--host') { opts.host = argv[++i]; }
     else if (arg === '--workspace') { opts.workspaceDir = argv[++i]; }
+    else if (arg === '--tail') { opts.tail = Number(argv[++i]); }
+    else if (arg === '--share') { opts.share = true; }
+    else if (arg === '--rotate') { opts.rotate = true; }
+    else if (arg === '--kind') { opts.kind = argv[++i]; }
+    else if (arg === '--limit') { opts.limit = Number(argv[++i]); }
     else if (arg.startsWith('--')) {
       // ignore unknown flags
     } else {
@@ -233,6 +255,16 @@ async function runLoginCommand(args) {
   console.log(`  saved to  : ${config.dataDir}/account.json`);
   console.log('');
   console.log('Run `wild-workspace` in any folder to start your workspace.');
+
+  // Arm always-on so the workspace comes back on its own (best-effort — never
+  // blocks login). On a platform without autostart yet, just nudge the user.
+  try {
+    const svc = await installService({
+      node: process.execPath, cli: __filename, workspaceDir: config.workspaceDir, port: config.port, version: APP_VERSION,
+    });
+    if (svc.installed) console.log('  always-on : enabled — starts at login (disable: wild-workspace service uninstall)');
+    else if (svc.supported === false) console.log(`  always-on : not yet on ${svc.platform} — run \`wild-workspace\` to start it`);
+  } catch { /* never block login */ }
 }
 
 async function runLogoutCommand() {
@@ -324,7 +356,279 @@ async function runWhoamiCommand() {
   console.log(`  loggedIn  : ${new Date(account.loggedInAt).toISOString()}`);
 }
 
+// `wild-workspace doctor [--share]` — one diagnostic of this machine's install.
+// Prints ✅/⚠️/❌ per check + where the logs are, and writes a JSON bundle under
+// ~/.wild-workspace/diagnostics/. Exits non-zero if any check failed.
+async function runDoctorCommand(opts) {
+  const config = buildConfig(opts);
+  const report = await runDoctor({ config });
+  console.log(renderDoctor(report));
+  const bundle = writeDoctorBundle(report);
+  if (bundle) {
+    console.log('');
+    console.log(`Full report: ${bundle}`);
+  }
+  if (opts.share) {
+    const shared = await shareDoctor(config, report);
+    console.log(
+      shared.ok
+        ? '✓ shared with the wild-workspace team — they can see this diagnostic now.'
+        : `Couldn't auto-share (${shared.reason}). Send the file above instead.`,
+    );
+  }
+  process.exitCode = report.summary.fail > 0 ? 1 : 0;
+}
+
+// Upload a doctor report to bmo-sync. `--share` is an explicit user action, so it
+// goes even if the passive observability feed is off — but still respects the
+// hard kill switch and needs an account to key it to.
+async function shareDoctor(config, report) {
+  if (!config.accountToken) return { ok: false, reason: 'not logged in' };
+  if (process.env.WILD_WORKSPACE_NO_TELEMETRY === '1') return { ok: false, reason: 'telemetry disabled' };
+  const url = `${config.bmoSyncServerUrl.replace(/\/$/, '')}/api/telemetry`;
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 5000);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        account_token: config.accountToken,
+        slug: config.account?.slug || null,
+        workspace_id: config.workspaceId,
+        kind: 'doctor-share',
+        doctor: report,
+        sent_at: Math.floor(Date.now() / 1000),
+      }),
+      signal: ctrl.signal,
+    });
+    return { ok: res.ok, reason: res.ok ? null : `HTTP ${res.status}` };
+  } catch (e) {
+    return { ok: false, reason: String(e?.message || e) };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// `wild-workspace logs [name] [--tail N]` — list the logs, or tail one by name.
+async function runLogsCommand(opts) {
+  const name = opts.positional[1];
+  const n = opts.tail || 40;
+  const logs = listLogs();
+  if (!name) {
+    console.log(`logs dir: ${path.dirname(logs[0].file)}`);
+    for (const l of logs) {
+      console.log(`  ${l.name.padEnd(10)} ${l.exists ? `${l.size} bytes` : '(none yet)'}  ${l.file}`);
+    }
+    console.log('');
+    console.log(`Show one: wild-workspace logs <name> [--tail N]   (names: ${logs.map((l) => l.name).join(', ')})`);
+    return;
+  }
+  const match = logs.find((l) => l.name === name);
+  if (!match) {
+    console.log(`unknown log "${name}". names: ${logs.map((l) => l.name).join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`# ${match.name} — ${match.file} (last ${n} lines)`);
+  console.log(tailFile(match.file, n) || '(empty)');
+}
+
+// `wild-workspace ops <slug>` — OPERATOR read of a user's observability feed.
+// Reads the bmo-sync admin endpoint with the admin key at ~/.bmo-sync-admin-key
+// (so it only works on an operator's machine). This is how we see a stuck/broken
+// user without them having to ask. Filters: --kind feed|install-down|transcript,
+// --limit N.
+async function runOpsCommand(opts) {
+  const slug = opts.positional[1];
+  if (!slug) {
+    console.error('usage: wild-workspace ops <slug> [--kind feed|install-down|transcript] [--limit N]');
+    process.exitCode = 1;
+    return;
+  }
+  const config = buildConfig(opts);
+  const keyPath = path.join(os.homedir(), '.bmo-sync-admin-key');
+  let adminKey;
+  try {
+    adminKey = readFileSync(keyPath, 'utf8').trim();
+  } catch {
+    console.error(`No admin key at ${keyPath} — \`ops\` is an operator-only command.`);
+    process.exitCode = 1;
+    return;
+  }
+  const params = new URLSearchParams();
+  if (opts.kind) params.set('kind', opts.kind);
+  params.set('limit', String(opts.limit || 50));
+  const url = `${config.bmoSyncServerUrl.replace(/\/$/, '')}/api/admin/accounts/${encodeURIComponent(slug)}/activity?${params}`;
+  let res;
+  try {
+    res = await fetch(url, { headers: { 'x-admin-key': adminKey } });
+  } catch (e) {
+    console.error(`Couldn't reach ${config.bmoSyncServerUrl}: ${e.message || e}`);
+    process.exitCode = 2;
+    return;
+  }
+  if (res.status === 404) {
+    console.log(`No account/slug "${slug}" yet (unclaimed, or it hasn't reported).`);
+    return;
+  }
+  if (res.status === 403 || res.status === 401) {
+    console.error('admin key rejected.');
+    process.exitCode = 1;
+    return;
+  }
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}`);
+    process.exitCode = 1;
+    return;
+  }
+  const data = await res.json();
+  console.log(`account ${data.account_id}${data.slug ? ` (${data.slug})` : ''} — ${data.count} recent event(s)`);
+  for (const r of data.rows || []) {
+    const when = new Date((r.reported_at || 0) * 1000).toISOString();
+    let detail = '';
+    if (r.kind === 'feed' && Array.isArray(r.payload?.events)) {
+      const counts = {};
+      for (const e of r.payload.events) counts[e.type] = (counts[e.type] || 0) + 1;
+      detail = Object.entries(counts).map(([k, v]) => `${k}×${v}`).join(' ');
+    } else if ((r.kind === 'install-down' || r.kind === 'doctor-share') && r.payload?.doctor?.summary) {
+      const s = r.payload.doctor.summary;
+      detail = `doctor: ${s.fail} fail / ${s.warn} warn`;
+    } else if (r.kind === 'transcript') {
+      detail = `transcript ${r.payload?.date || ''} (${(r.payload?.markdown || '').length} chars)`;
+    }
+    console.log(`  ${when}  [${r.kind}]${r.os ? ` ${r.os}` : ''}  ${detail}`);
+  }
+}
+
+// `wild-workspace observability [on|off|status]` — the consented session +
+// install-health feed (default ON). Streams WHAT happened + install health to the
+// Venturewild team so they can help if something breaks — never your chat words
+// (that's the separate transcript channel). See observability.mjs.
+async function runObservabilityCommand(action = 'status', opts = {}) {
+  const config = buildConfig(opts);
+  if (action === 'on' || action === 'off') {
+    const rec = setObservabilityConsent(config.dataDir, action === 'on');
+    console.log(
+      rec.enabled
+        ? '✓ observability ON — the Venturewild team can see how your workspace is doing'
+        : '✓ observability OFF — no session/health feed leaves this machine.',
+    );
+    if (rec.enabled) {
+      console.log('  (events + install health only — never your chat content)');
+    }
+    console.log('  Applies the next time your workspace starts (or toggle it live in the app).');
+    return;
+  }
+  const rec = loadObservabilityConsent(config.dataDir);
+  console.log(`observability: ${rec.enabled ? 'ON' : 'OFF'}${rec.decidedAt ? '' : ' (default)'}`);
+  console.log('  what : events + install health → lets us help if something breaks (never chat content)');
+  console.log('  toggle: wild-workspace observability on | off');
+  return;
+}
+
+// `wild-workspace operator [enable|disable|status]` — the consented support
+// channel (docs/SECURITY.md). OFF by default; `enable` mints a token to hand to
+// the wild-workspace team so they can diagnose + run a fixed set of safe fixes.
+async function runOperatorCommand(action = 'status', opts = {}) {
+  const config = buildConfig(opts);
+  if (action === 'enable') {
+    const token = enableOperator(config.dataDir, { rotate: opts.rotate });
+    if (!token) {
+      console.error(`Could not enable operator channel (couldn't write to ${config.dataDir}).`);
+      process.exitCode = 1;
+      return;
+    }
+    const slug = config.account?.slug;
+    console.log('✓ operator channel enabled (consented support access).');
+    console.log(`  token : ${token}`);
+    console.log('  Share this token with the wild-workspace team so they can help with your install.');
+    if (slug) console.log(`  reach : https://${slug}.venturewild.llc/api/operator/diag  (Authorization: Bearer <token>)`);
+    console.log('  off   : wild-workspace operator disable');
+    console.log('');
+    console.log('  Scope: read diagnostics + a fixed set of safe fixes (restart sync, re-detect');
+    console.log('  Claude, re-link your account, reinstall the sync daemon). It cannot run');
+    console.log('  arbitrary commands or drive your agent, and every action is logged.');
+    return;
+  }
+  if (action === 'disable') {
+    const removed = disableOperator(config.dataDir);
+    console.log(removed ? '✓ operator channel disabled (token revoked).' : 'operator channel was not enabled.');
+    return;
+  }
+  if (action === 'status') {
+    const s = operatorStatus(config.dataDir);
+    console.log(`operator channel: ${s.enabled ? 'ENABLED' : 'disabled'}`);
+    console.log(`  token file: ${s.file}`);
+    console.log(s.enabled ? '  disable   : wild-workspace operator disable' : '  enable    : wild-workspace operator enable');
+    return;
+  }
+  console.log(`unknown operator action: ${action}  (use enable | disable | status)`);
+}
+
+// `wild-workspace service [install|uninstall|status|run]` — the always-on
+// autostart (docs/always-on-design.md). `run` is the HIDDEN supervisor entry
+// the per-OS launcher invokes at login; the others manage registration. All
+// per-user, no admin.
+async function runServiceCommand(action = 'status', opts = {}) {
+  const config = buildConfig(opts);
+
+  if (action === 'install') {
+    const r = await installService({
+      node: process.execPath, cli: __filename, workspaceDir: config.workspaceDir, port: config.port, version: APP_VERSION,
+    });
+    if (!r.installed) {
+      console.log(`service install: ${r.message || 'not supported on this platform'}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log('✓ always-on enabled — your workspace starts automatically at login.');
+    console.log(`  mechanism : ${r.mechanism} (per-user, no admin)`);
+    console.log(`  launcher  : ${r.vbs}`);
+    console.log(`  workspace : ${config.workspaceDir}`);
+    console.log('  disable   : wild-workspace service uninstall');
+    return;
+  }
+
+  if (action === 'uninstall') {
+    const r = await uninstallService();
+    if (r.supported === false) { console.log(`service: nothing to do — autostart not implemented for ${r.platform} yet`); return; }
+    console.log(`✓ always-on disabled${r.removedKey ? '' : ' (no autostart entry was set)'}${r.stoppedPid ? ` — stopped supervisor pid ${r.stoppedPid}` : ''}.`);
+    return;
+  }
+
+  if (action === 'status') {
+    const s = await serviceStatus({ port: config.port }, { probeImpl: (p) => probeHealth(p) });
+    if (s.supported === false) { console.log(`always-on: autostart not implemented for ${s.platform} yet (run \`wild-workspace\` manually)`); return; }
+    console.log(`always-on   : ${s.installed ? 'installed' : 'NOT installed'}`);
+    if (s.runValue) console.log(`  run entry : ${s.runValue}`);
+    console.log(`  supervisor: ${s.supervisorAlive ? `running (pid ${s.supervisorPid})` : 'not running'}`);
+    console.log(`  server    : ${s.serverUp ? `up on http://127.0.0.1:${config.port}` : 'down'}`);
+    return;
+  }
+
+  if (action === 'run') {
+    // Hidden entrypoint launched by the autostart VBS at login. The OS gives us
+    // an arbitrary cwd, so read the workspace dir persisted at install time.
+    let svc = {};
+    try { svc = JSON.parse(readFileSync(path.join(globalDir(), 'service.json'), 'utf8')); } catch { /* fall back to config */ }
+    const sup = new WorkspaceSupervisor({
+      workspaceDir: svc.workspaceDir || config.workspaceDir,
+      port: svc.port || config.port,
+    });
+    const r = sup.start();
+    if (!r.started) process.exit(0); // another supervisor already owns the lock
+    // else: the supervision interval keeps this process alive.
+    return;
+  }
+
+  console.log(`unknown service action: ${action}  (use install | uninstall | status | run)`);
+}
+
 async function main() {
+  // First-run capture: log every invocation BEFORE doing anything, so even a
+  // crash-on-start leaves a trace we (or `wild-workspace doctor`) can read.
+  appendLine('cli', `invoke argv=[${process.argv.slice(2).join(' ')}] cwd=${process.cwd()} node=${process.version} v${APP_VERSION}`);
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) return printUsage();
   if (opts.version) { console.log(APP_VERSION); return; }
@@ -345,6 +649,24 @@ async function main() {
   if (opts.positional[0] === 'rotate-token') {
     return runRotateTokenCommand();
   }
+  if (opts.positional[0] === 'doctor') {
+    return runDoctorCommand(opts);
+  }
+  if (opts.positional[0] === 'logs') {
+    return runLogsCommand(opts);
+  }
+  if (opts.positional[0] === 'operator') {
+    return runOperatorCommand(opts.positional[1], opts);
+  }
+  if (opts.positional[0] === 'observability') {
+    return runObservabilityCommand(opts.positional[1], opts);
+  }
+  if (opts.positional[0] === 'ops') {
+    return runOpsCommand(opts);
+  }
+  if (opts.positional[0] === 'service') {
+    return runServiceCommand(opts.positional[1], opts);
+  }
 
   if (opts.positional[0] === 'install') {
     console.log('wild-workspace manages the bmo-sync sync daemon for you.');
@@ -397,6 +719,7 @@ async function main() {
 }
 
 main().catch((err) => {
+  appendLine('cli', `FATAL ${err?.stack || err}`);
   console.error('wild-workspace failed:', err);
   process.exit(1);
 });

package/server/src/agent-readiness.mjs

@@ -0,0 +1,200 @@
+// Agent readiness — "is the wrapped agent actually able to talk?"
+//
+// THE GAP THIS CLOSES: detectAgents() only proves the `claude` binary is on the
+// PATH. It does NOT prove the user has signed in. A brand-new user who installed
+// the CLI but never ran `claude auth login` has a binary that resolves but every
+// `claude -p` turn fails with an auth error. Onboarding's folder-peek (step 2)
+// would then surface a scary error bubble — the exact "makes them feel stupid"
+// failure docs/user-experience.md §4 forbids, and the open question in §3.2.
+//
+// THE SECOND GAP (added 2026-06-01): being signed in is NOT the same as being
+// ABLE to run turns. A free claude.ai account can complete `claude auth login`
+// (so `loggedIn:true`) yet Claude Code still refuses every prompt — a paid plan
+// (Pro/Max/Team/Enterprise) or API billing is required. If we only checked
+// `loggedIn` we'd wave a free user straight into the folder-peek, where the
+// FIRST `claude -p` blows up with a billing error = the same scary bubble. So we
+// also read `subscriptionType` / `apiProvider` and raise a distinct `subscribe`
+// verdict ("you're in — you just need an active plan") instead.
+//
+// THE PROBE: `claude auth status` — a built-in, ZERO-TOKEN, cross-platform check
+// (verified on Claude Code 2.1.158). It reads whatever credential store the
+// platform uses (macOS Keychain, Windows ~/.claude/.credentials.json, Linux
+// config), so a naive credentials-file check (which would false-negative on a
+// signed-in Mac user like Mel) is wrong — we ask the CLI itself. It prints JSON:
+//   - signed in  → exit 0, {"loggedIn":true,"authMethod":"claude.ai",
+//                           "apiProvider":"firstParty","email":"…",
+//                           "subscriptionType":"max",…}
+//   - signed out → exit 1, {"loggedIn":false,"authMethod":"none",…}
+// We parse the JSON (authoritative) and fall back to the exit code if the shape
+// ever changes.
+//
+// API-KEY / TOKEN BILLING: if ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN /
+// CLAUDE_CODE_OAUTH_TOKEN) is set, `claude -p` bills through that and turns run
+// even without a claude.ai OAuth session — so we treat a configured key as
+// `ready` regardless of `auth status` (the sponsored / managed-key path).
+//
+// Only `claude` has this contract today. Other agents (gemini/glm/codex) report
+// `unknown` — we never block on a readiness we can't measure (fail-open), so a
+// Codex user is never gated by a Claude-shaped check.
+
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCb);
+
+// `claude auth status` is local-only (no network), but give it room on a cold
+// cache / slow disk. Comfortably under the 5s onboarding "feels instant" budget.
+const AUTH_PROBE_TIMEOUT_MS = 8000;
+
+// Subscription tiers that CAN run Claude Code turns vs. ones that cannot. Lower-
+// cased for comparison. An unknown, non-empty tier on a firstParty account is
+// treated leniently (assumed paid) so a future tier name never false-gates a
+// paying user behind a non-skippable wall — the empty/known-free cases are the
+// only ones we positively block.
+const PAID_TIERS = new Set(['pro', 'max', 'team', 'enterprise']);
+const UNPAID_TIERS = new Set(['free', 'none', 'inactive', 'expired', 'trial_expired']);
+
+// An API key / long-lived token configures billing directly — turns will run
+// even with no OAuth session. Checked before the auth probe.
+function hasApiBillingKey(env) {
+  const keys = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN'];
+  return keys.some((k) => typeof env?.[k] === 'string' && env[k].trim() !== '');
+}
+
+// Given a parsed `auth status` object for a signed-in user, can turns actually
+// run?  true = yes (paid plan or API billing), false = no (free / no plan),
+// null = unknown shape → caller treats as ready (lenient, never false-gates).
+export function canRunTurns(parsed) {
+  if (!parsed || typeof parsed !== 'object') return null;
+  const sub =
+    typeof parsed.subscriptionType === 'string' ? parsed.subscriptionType.toLowerCase().trim() : '';
+  const provider =
+    typeof parsed.apiProvider === 'string' ? parsed.apiProvider.toLowerCase().trim() : '';
+  // A non-firstParty provider (console / bedrock / vertex) bills via API → runs.
+  if (provider && provider !== 'firstparty') return true;
+  if (PAID_TIERS.has(sub)) return true;
+  if (UNPAID_TIERS.has(sub)) return false;
+  // Signed in via claude.ai with NO subscription field at all → no active plan
+  // (the current CLI emits subscriptionType for paid accounts, so absence here
+  // is the free-account fingerprint).
+  if (sub === '') return false;
+  // Unknown, non-empty tier on a firstParty account — lean paid (don't gate).
+  return true;
+}
+
+/**
+ * Readiness verdict for one agent.
+ *   status: 'ready'      — installed AND able to run turns (signed-in + plan, or API key).
+ *           'subscribe'  — installed AND signed in, but no active plan → the user
+ *                          needs a Claude Pro (or higher) plan before turns run.
+ *           'login'      — installed but NOT signed in; the user must auth.
+ *           'missing'    — binary not on PATH (detect step already knew).
+ *           'unknown'    — installed, but this agent has no auth-status probe
+ *                          we understand → never gate on it (fail-open).
+ *   email:  parsed sign-in identity when known (claude only), else null.
+ *   hint:   a short, human, NON-technical line the UI can show as-is.
+ */
+export async function probeClaudeAuth(agent, runner = defaultRunner, env = process.env) {
+  if (!agent || !agent.available) {
+    return {
+      status: 'missing',
+      email: null,
+      hint: 'Claude Code isn’t installed yet. Install it, then come back.',
+    };
+  }
+  // Sponsored / managed billing: a configured key runs turns regardless of the
+  // OAuth session state, so don't gate.
+  if (hasApiBillingKey(env)) {
+    return { status: 'ready', email: null, hint: null };
+  }
+  const command = agent.resolvedPath || agent.binary;
+  try {
+    const { code, stdout } = await runner(command, ['auth', 'status']);
+    const parsed = parseAuthStatus(stdout);
+    // Authoritative: the JSON `loggedIn` flag. Fall back to the exit code
+    // (0 = signed in) only if the JSON is unparseable / shape-changed.
+    const loggedIn = parsed ? parsed.loggedIn === true : code === 0;
+    if (loggedIn) {
+      // Signed in — but can they actually run a turn? A free account can't.
+      if (canRunTurns(parsed) === false) {
+        return {
+          status: 'subscribe',
+          email: parsed?.email || null,
+          hint: 'You’re signed in — you just need an active Claude plan (Pro or higher) so your agent can run.',
+        };
+      }
+      return { status: 'ready', email: parsed?.email || null, hint: null };
+    }
+    // Signed out (or any non-ready shape). Treat as "needs login" — safer than
+    // claiming ready and then failing the first real turn mid-onboarding.
+    return {
+      status: 'login',
+      email: null,
+      hint: 'One quick thing: sign in to Claude so your agent can think.',
+    };
+  } catch (err) {
+    // The probe itself failed to run (timeout, spawn error, unexpected CLI
+    // version with no `auth` subcommand). Don't hard-block onboarding on our
+    // own probe breaking — report unknown and let the turn-runner be the
+    // ground truth. Surfaced for logging, not shown as a scary error.
+    return {
+      status: 'unknown',
+      email: null,
+      hint: null,
+      error: String(err?.message || err),
+    };
+  }
+}
+
+/**
+ * Readiness for the active agent. Claude gets the real probe; every other agent
+ * is 'unknown' (we have no auth-status contract for them, so we never gate).
+ */
+export async function probeAgentReadiness(agent, runner = defaultRunner, env = process.env) {
+  if (agent && agent.id === 'claude') {
+    return probeClaudeAuth(agent, runner, env);
+  }
+  return { status: 'unknown', email: null, hint: null };
+}
+
+// Parse `claude auth status` stdout. It prints a JSON object; tolerate leading/
+// trailing noise by extracting the first {...} span. Returns null if nothing
+// parseable is found (caller falls back to the exit code).
+export function parseAuthStatus(stdout) {
+  const text = String(stdout || '');
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start === -1 || end === -1 || end <= start) return null;
+  try {
+    const obj = JSON.parse(text.slice(start, end + 1));
+    return obj && typeof obj === 'object' ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+// execFile wrapper that resolves (never rejects) on a non-zero exit, so the
+// caller can branch on { code, stdout } uniformly. Only a genuine spawn/timeout
+// failure rejects — that's the 'unknown' path above.
+function defaultRunner(command, args) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      command,
+      args,
+      { timeout: AUTH_PROBE_TIMEOUT_MS, windowsHide: true },
+      (err, stdout, stderr) => {
+        if (err && typeof err.code !== 'number') {
+          // No numeric exit code => process never ran to completion
+          // (ENOENT, ETIMEDOUT, killed). That's a probe failure, not a verdict.
+          reject(err);
+          return;
+        }
+        resolve({
+          code: err ? err.code : 0,
+          stdout: stdout || '',
+          stderr: stderr || '',
+        });
+      },
+    );
+  });
+}