@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/cli/doctor-checks.mjs

@@ -0,0 +1,441 @@
+/**
+ * lib/cli/doctor-checks.mjs — the auth / org-id / front-door / fleet checks
+ * behind `maestro doctor` (design 2026-09-08 §3.9; audit F1, F2, F3, F4).
+ *
+ * Every decision is a PURE function over values the caller already read —
+ * `authMode`, `orgIdShape`, `effectiveSource`, `sdkGlobalInstall`,
+ * `tailscaleSsh`, `sessionInstalled` — so each verdict is unit-testable with
+ * no machine, no network and no clock. `runDoctorChecks` is the one edge: it
+ * reads the files, forks the commands and makes the single org call through
+ * injectable `exec` / `fetchImpl` / `listPlists` / `probeClaude` seams, then
+ * hands the values to the pure checks. Fail-open at every edge: a command that
+ * is missing degrades that one line to `warn`, never a throw.
+ *
+ * Rows are `{level: "ok"|"warn"|"fail", msg}`; `fail` counts toward doctor's
+ * issue total, `warn` is advisory. Secrets never appear in a row — tokens are
+ * masked by `mask()` before they reach a message.
+ *
+ * What replaced what: the doctor block this feeds used to say
+ * "ANTHROPIC_API_KEY not set" and count it as an issue on every seat that
+ * runs the subscription token — the documented fleet posture. That block is
+ * gone; `authMode` is mode-aware.
+ *
+ * @module lib/cli/doctor-checks
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { loadOrgConfig, call } from "../org/client.mjs";
+import { probeClaude as defaultProbeClaude } from "../setup/claude-probe.mjs";
+import { sessionLiveness, SESSION_STALE_MS } from "../telemetry/collect.mjs";
+
+export const SDK_PACKAGE = "@cohortapp/agent-sdk";
+
+/** Where the tailscale CLI lives, in the order we try it (mirrors telemetry). */
+const TAILSCALE_BINS = Object.freeze([
+  "tailscale",
+  "/usr/local/bin/tailscale",
+  "/opt/homebrew/bin/tailscale",
+  "/Applications/Tailscale.app/Contents/MacOS/Tailscale",
+]);
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a .env body into `{KEY: value}`. Quotes stripped, `export ` prefix
+ * tolerated, comments/blank lines ignored, EMPTY values dropped (an empty
+ * `KEY=` line is "unset" for every consumer we have).
+ * @param {string|null|undefined} body
+ * @returns {Record<string,string>}
+ */
+export function parseDotEnv(body) {
+  const out = {};
+  for (const raw of String(body || "").split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!m) continue;
+    const v = m[2].trim().replace(/^(["'])(.*)\1$/, "$2");
+    if (v) out[m[1]] = v;
+  }
+  return out;
+}
+
+/** `nlk_dotenv_secret` → `nlk_…cret`. Short values collapse to `…`. */
+export function mask(v) {
+  const s = String(v || "");
+  if (!s) return "";
+  if (s.length <= 10) return "…";
+  return `${s.slice(0, 4)}…${s.slice(-4)}`;
+}
+
+/**
+ * Which Claude auth path the seat is on, from its (parsed) env.
+ * @param {Record<string,string>} env  the .env values (merged over the ambient env by the caller)
+ * @returns {{mode:"oauth-token"|"subscription"|"api-key"|"none", level:"ok"|"warn"|"fail", msg:string}}
+ */
+export function authMode(env = {}) {
+  const token = !!env.CLAUDE_CODE_OAUTH_TOKEN;
+  const prefer = /^(1|true|yes)$/i.test(String(env.MAESTRO_PREFER_SUBSCRIPTION_AUTH || ""));
+  const key = !!env.ANTHROPIC_API_KEY;
+  if (token && prefer) return { mode: "oauth-token", level: "ok", msg: "Claude auth: subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN + MAESTRO_PREFER_SUBSCRIPTION_AUTH=1)" };
+  if (token) {
+    return {
+      mode: "oauth-token", level: "warn",
+      msg: "Claude auth: CLAUDE_CODE_OAUTH_TOKEN is set but MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 is not — add it so spawns strip ANTHROPIC_API_KEY and ride the token",
+    };
+  }
+  if (prefer) {
+    return {
+      mode: "subscription", level: "warn",
+      msg: "Claude auth: keychain login (MAESTRO_PREFER_SUBSCRIPTION_AUTH=1, no token) — it expires headlessly; run `claude setup-token` and put the result in .env as CLAUDE_CODE_OAUTH_TOKEN",
+    };
+  }
+  if (key) return { mode: "api-key", level: "ok", msg: "Claude auth: ANTHROPIC_API_KEY (pay-per-token)" };
+  return {
+    mode: "none", level: "fail",
+    msg: "Claude auth: nothing configured — run `claude setup-token` on any logged-in machine and put the result in .env as CLAUDE_CODE_OAUTH_TOKEN (plus MAESTRO_PREFER_SUBSCRIPTION_AUTH=1), or set ANTHROPIC_API_KEY",
+  };
+}
+
+/**
+ * Does this look like an org ID (`org_default_<slug>`) rather than a bare slug?
+ * Shared with the setup wizard's org section so both judge the pin the same way.
+ */
+export function looksLikeOrgId(v) { return /^org_[a-z0-9]+_[a-z0-9-]+$/i.test(String(v || "")); }
+
+/**
+ * Is the configured COHORT_ORG_ID the org's ID (what hq compares with strict
+ * equality) or its slug (which 401s every call)? `whoamiOrgId`/`orgSlug` come
+ * from the server (`org.list` → the active org) when reachable, else "".
+ * @param {string} configured
+ * @param {string} whoamiOrgId
+ * @param {string} orgSlug
+ * @returns {{level:"ok"|"warn"|"fail", msg:string}}
+ */
+export function orgIdShape(configured, whoamiOrgId, orgSlug) {
+  const c = String(configured || "").trim();
+  const id = String(whoamiOrgId || "").trim();
+  const slug = String(orgSlug || "").trim();
+  if (!c) {
+    return { level: "warn", msg: `COHORT_ORG_ID is not set${id ? ` — this key belongs to org ${id}` : ""} (the x-org-id pin is optional, but pull-enrollment needs it)` };
+  }
+  if (id) {
+    if (c === id) return { level: "ok", msg: `COHORT_ORG_ID is the org ID (${id}) — matches the server` };
+    if (slug && c === slug) {
+      return { level: "fail", msg: `COHORT_ORG_ID=${c}: you set the slug — hq compares the pin with strict equality against the org ID, so every call 401s. Set COHORT_ORG_ID=${id}` };
+    }
+    return { level: "fail", msg: `COHORT_ORG_ID=${c} does not match the org this key belongs to (${id}${slug ? `, slug ${slug}` : ""})` };
+  }
+  // Server unreachable / not asked: judge the shape alone.
+  if (looksLikeOrgId(c)) return { level: "ok", msg: `COHORT_ORG_ID=${c} has the org-ID shape (server not consulted)` };
+  return { level: "warn", msg: `COHORT_ORG_ID=${c} looks like a slug — the org ID has the form org_default_<slug>; verify against Cohort → Settings` };
+}
+
+/**
+ * Where each Cohort value actually comes from, following the precedence the
+ * daemon lives by: `config/org.yaml` (the enrollment SoT `maestro setup`
+ * writes) beats the ambient env, which beats `.env` (dotenv never overrides
+ * an already-set variable). F3 was exactly that org.yaml quietly winning over
+ * a `.env` an operator had just edited — so every LOSING value is named too.
+ *
+ * @param {{orgYaml?:object|null, dotEnv?:Record<string,string>, env?:Record<string,string>}} src
+ * @returns {Array<{key:string, source:"org.yaml"|"env"|".env"|"none", value:string, shadowed:string[]}>}
+ */
+export function effectiveSource({ orgYaml, dotEnv, env } = {}) {
+  const n = (orgYaml && orgYaml.org && orgYaml.org.cohort) || {};
+  const de = dotEnv || {};
+  const ae = env || {};
+  const firstOf = (bag, names) => {
+    for (const name of names) if (bag[name]) return { name, value: String(bag[name]) };
+    return null;
+  };
+  const rows = [];
+  const push = (key, yamlValue, envNames, opts = {}) => {
+    const show = opts.secret ? mask : (v) => String(v);
+    const candidates = [];
+    if (yamlValue) candidates.push({ source: "org.yaml", label: `org.yaml ${key}`, value: String(yamlValue) });
+    const fromEnv = firstOf(ae, envNames);
+    if (fromEnv) candidates.push({ source: "env", label: `env ${fromEnv.name}`, value: fromEnv.value });
+    const fromDot = firstOf(de, envNames);
+    if (fromDot) candidates.push({ source: ".env", label: `.env ${fromDot.name}`, value: fromDot.value });
+    if (candidates.length === 0) { rows.push({ key, source: "none", value: "", shadowed: [] }); return; }
+    const [winner, ...losers] = candidates;
+    rows.push({
+      key,
+      source: winner.source,
+      value: show(winner.value),
+      shadowed: losers.filter((l) => l.value !== winner.value).map((l) => `${l.label}=${show(l.value)}`),
+    });
+  };
+  push("base", n.base || n.apiUrl, ["COHORT_BASE", "COHORT_API_URL"]);
+  push("orgId", n.orgId, ["COHORT_ORG_ID"]);
+  push("token", n.token, ["COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY"], { secret: true });
+  push("agentId", n.agentId, ["COHORT_AGENT_ID"]);
+  return rows;
+}
+
+/** Compare two `x.y.z` strings: -1 / 0 / 1. Non-numeric parts compare as 0. */
+function cmpSemver(a, b) {
+  const pa = String(a).split("-")[0].split(".").map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).split("-")[0].split(".").map((x) => parseInt(x, 10) || 0);
+  for (let i = 0; i < 3; i += 1) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Version of SDK_PACKAGE in `npm ls -g` output (JSON or tree text), else "". */
+function parseNpmLs(output) {
+  const s = String(output || "").trim();
+  if (!s) return "";
+  try {
+    const j = JSON.parse(s);
+    const dep = j && j.dependencies && j.dependencies[SDK_PACKAGE];
+    if (dep && typeof dep.version === "string") return dep.version;
+    return "";
+  } catch { /* text form */ }
+  const m = s.match(new RegExp(`${SDK_PACKAGE.replace("/", "\\/")}@(\\d+\\.\\d+\\.\\d+[^\\s]*)`));
+  return m ? m[1] : "";
+}
+
+/**
+ * Is the SDK installed globally, and is it current?
+ * @param {string} npmLsOutput   `npm ls -g @cohortapp/agent-sdk --json --depth=0` stdout ("" when npm failed)
+ * @param {string} npmViewLatest `npm view @cohortapp/agent-sdk version` stdout ("" when offline)
+ * @returns {{installed:boolean, version:string, latest:string, level:"ok"|"warn"|"fail", msg:string}}
+ */
+export function sdkGlobalInstall(npmLsOutput, npmViewLatest) {
+  const version = parseNpmLs(npmLsOutput);
+  const latest = String(npmViewLatest || "").trim().split("\n").pop().trim();
+  if (!version) {
+    // WARN until upgrade() step 4 (WP-M6) refreshes the global install on every
+    // seat: today's fleet installs the SDK LOCALLY in the agent dir
+    // (autoupdate.sh `npm install … --save`) and is fully functional that way.
+    // A `fail` here would turn doctor red on every existing machine the hour
+    // 2.12.0 lands — and "doctor is the gate" would then read as an outage.
+    return { installed: false, version: "", latest, level: "warn", msg: `${SDK_PACKAGE} is not installed globally — a home-dir session cannot reach \`maestro\`/\`cohort-mcp\` on PATH until it is: npm i -g ${SDK_PACKAGE}@latest (the next \`maestro upgrade\` does this)` };
+  }
+  if (!latest) return { installed: true, version, latest, level: "ok", msg: `${SDK_PACKAGE} ${version} installed globally (npm latest unknown — offline?)` };
+  if (cmpSemver(version, latest) < 0) {
+    return { installed: true, version, latest, level: "warn", msg: `${SDK_PACKAGE} ${version} installed globally but npm latest is ${latest} — autoupdate should catch up within the hour, or: npm i -g ${SDK_PACKAGE}@latest` };
+  }
+  return { installed: true, version, latest, level: "ok", msg: `${SDK_PACKAGE} ${version} installed globally (npm latest ${latest})` };
+}
+
+/**
+ * Is Tailscale SSH advertised on this machine? `prefsJson` (`tailscale debug
+ * prefs`, `RunSSH`) is authoritative; without it, `Self.SSH_HostKeys` in
+ * `tailscale status --json` is the next-best evidence. Anything unparseable
+ * means Tailscale is absent or down — a warn, since fleet-wide operator access
+ * depends on it (F4).
+ * @param {object|string} statusJson
+ * @param {object|string} [prefsJson]
+ * @returns {{level:"ok"|"warn", msg:string, enabled:boolean|null}}
+ */
+export function tailscaleSsh(statusJson, prefsJson) {
+  const parse = (v) => {
+    if (v && typeof v === "object") return v;
+    try { return JSON.parse(String(v || "")); } catch { return null; }
+  };
+  const remedy = "enable with `scripts/setup/configure-macos.sh --tailscale-ssh` (and allow it in the tailnet ACL)";
+  const prefs = parse(prefsJson);
+  const status = parse(statusJson);
+  if (prefs && typeof prefs.RunSSH === "boolean") {
+    return prefs.RunSSH
+      ? { level: "ok", msg: "Tailscale SSH is on (RunSSH=true)", enabled: true }
+      : { level: "warn", msg: `Tailscale SSH is off — operators cannot reach this seat remotely; ${remedy}`, enabled: false };
+  }
+  if (status && status.Self && typeof status.Self === "object") {
+    const keys = status.Self.SSH_HostKeys;
+    if (Array.isArray(keys) && keys.length > 0) return { level: "ok", msg: "Tailscale SSH is on (host keys advertised)", enabled: true };
+    return { level: "warn", msg: `Tailscale SSH is off — operators cannot reach this seat remotely; ${remedy}`, enabled: false };
+  }
+  return { level: "warn", msg: `Tailscale is not installed or not running — no remote operator access; install it, join the tailnet, then ${remedy}`, enabled: null };
+}
+
+/**
+ * Is the main-session launchd job installed, loaded and alive?
+ * @param {{first:string, plists:string[], loaded:string[], heartbeat:object|null, now:number, staleMs?:number}} o
+ *   plists  file names (or labels) in ~/Library/LaunchAgents
+ *   loaded  labels from `launchctl list`
+ * @returns {{level:"ok"|"warn"|"fail", msg:string, label:string}}
+ */
+export function sessionInstalled({ first, plists = [], loaded = [], heartbeat = null, now, staleMs = SESSION_STALE_MS } = {}) {
+  const label = `ai.maestro.${String(first || "").toLowerCase()}-session`;
+  const strip = (s) => String(s || "").replace(/\.plist$/, "");
+  const installed = plists.map(strip).includes(label);
+  if (!installed) {
+    return { level: "warn", label, msg: `Main session job ${label} is not installed — the daemon's --print lane is the front door; install with \`maestro session install\`` };
+  }
+  if (!loaded.map(strip).includes(label)) {
+    // Installed-but-unloaded is what a deliberate `maestro session stop`
+    // leaves behind (launchctl bootout, plist kept) — so this asks, it does
+    // not order the operator to undo their own stop.
+    return { level: "warn", label, msg: `Main session job ${label} is installed but not loaded — stopped on purpose (\`maestro session stop\`)? The daemon's --print lane is the front door meanwhile; \`maestro session start\` (launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/${label}.plist) brings it back` };
+  }
+  if (!heartbeat) {
+    return { level: "warn", label, msg: `Main session job ${label} is loaded but has written no heartbeat yet — give it a minute, then \`maestro session status\`` };
+  }
+  const live = sessionLiveness(heartbeat, now, { staleMs });
+  if (!live.sessionLive) {
+    const ts = typeof heartbeat.ts === "number" ? heartbeat.ts : Date.parse(heartbeat.ts);
+    const age = Number.isFinite(ts) ? Math.round((now - ts) / 1000) : NaN;
+    return { level: "fail", label, msg: `Main session job ${label} heartbeat is stale (${Number.isFinite(age) ? `${age} s` : "unreadable"} old) — the daemon is on its fallback lane; \`maestro session status\` / \`maestro session restart\`` };
+  }
+  const ts = typeof heartbeat.ts === "number" ? heartbeat.ts : Date.parse(heartbeat.ts);
+  return { level: "ok", label, msg: `Main session job ${label} loaded, heartbeat live (${Math.round((now - ts) / 1000)} s ago)` };
+}
+
+// ---------------------------------------------------------------------------
+// The edge: read, fork, call — then hand off to the pure checks
+// ---------------------------------------------------------------------------
+
+function safeRead(p) { try { return readFileSync(p, "utf8"); } catch { return ""; } }
+function safeJson(p) { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } }
+
+/** Labels from `launchctl list` output (PID\tStatus\tLabel). */
+function parseLaunchctlList(out) {
+  return String(out || "").split("\n").map((l) => l.trim().split(/\s+/).pop()).filter((l) => l && l !== "Label");
+}
+
+function agentFirstName(cwd) {
+  const aj = safeJson(join(cwd, "config", "agent.json"));
+  const fromCfg = aj && (aj.firstName || (aj.name && String(aj.name).split(/\s+/)[0]));
+  if (fromCfg) return String(fromCfg).toLowerCase();
+  return String(cwd).split("/").pop().replace(/-ai$/, "").toLowerCase();
+}
+
+/**
+ * Run every check for the agent repo at `cwd`. Each edge is injectable; each
+ * is fail-open.
+ * @param {object} o
+ * @param {string} o.cwd
+ * @param {Record<string,string>} [o.env]        ambient env (default process.env)
+ * @param {number} [o.now]
+ * @param {(cmd:string,args:string[],opts:object)=>string} [o.exec]   execFileSync-shaped
+ * @param {Function} [o.fetchImpl]
+ * @param {() => string[]} [o.listPlists]        names in ~/Library/LaunchAgents
+ * @param {(agentRoot:string)=>object} [o.probeClaude]
+ * @returns {Promise<Array<{level:"ok"|"warn"|"fail", msg:string}>>}
+ */
+export async function runDoctorChecks(o = {}) {
+  const cwd = resolve(o.cwd || process.cwd());
+  const env = o.env || process.env;
+  const now = Number.isFinite(o.now) ? o.now : Date.now();
+  // Default edge: stdout regardless of exit status (`npm ls -g` exits 1 for a
+  // package that is NOT installed — and prints the JSON that says so, which is
+  // the answer we want); only a spawn error (missing binary, timeout) throws.
+  const exec = o.exec || ((cmd, args, opts) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 8000, ...opts });
+    if (r.error) throw r.error;
+    return r.stdout || "";
+  });
+  const tryExec = (cmd, args, opts) => { try { return String(exec(cmd, args, opts || {}) || ""); } catch { return ""; /* missing binary / non-zero exit → the check degrades to warn */ } };
+  const rows = [];
+
+  // ── Claude auth (F1) ──────────────────────────────────────────────────────
+  const dotEnv = parseDotEnv(safeRead(join(cwd, ".env")));
+  const merged = { ...pick(env, ["CLAUDE_CODE_OAUTH_TOKEN", "MAESTRO_PREFER_SUBSCRIPTION_AUTH", "ANTHROPIC_API_KEY"]), ...dotEnv };
+  const auth = authMode(merged);
+  rows.push({ level: auth.level, msg: auth.msg });
+  if (auth.mode !== "none") {
+    try {
+      // The probe judges the mode from the SAME env this row did (.env first,
+      // ambient second), so the two rows cannot contradict each other on a
+      // seat whose token arrives through launchd's environment.
+      const probe = (o.probeClaude || defaultProbeClaude)(cwd, { env });
+      if (probe.ok && probe.auth === "unknown") rows.push({ level: "warn", msg: `${probe.name}: ${probe.detail || "could not verify"}` });
+      // "verified" only when a real call proved the credential (api-key 200).
+      // `claude auth status` reports a login for ANY token value, so a
+      // subscription ok is worded as what it is: the CLI's report.
+      else if (probe.ok && probe.verified === true) rows.push({ level: "ok", msg: `${probe.name}: verified` });
+      else if (probe.ok) rows.push({ level: "ok", msg: `${probe.name}: ${probe.detail || "CLI reports a login (the token is only proven by a real spawn)"}` });
+      else rows.push({ level: "fail", msg: `${probe.name}: ${probe.remedy || "failed"}` });
+    } catch (err) {
+      rows.push({ level: "warn", msg: `Claude auth probe threw: ${err && err.message ? err.message : err}` });
+    }
+  }
+
+  // ── Effective Cohort sources (F3) ─────────────────────────────────────────
+  const orgYaml = existsSync(join(cwd, "config", "org.yaml")) ? loadOrgConfig(cwd) : null;
+  const sources = effectiveSource({ orgYaml, dotEnv, env: pick(env, ["COHORT_BASE", "COHORT_API_URL", "COHORT_ORG_ID", "COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "COHORT_AGENT_ID"]) });
+  for (const r of sources) {
+    if (r.source === "none") continue;
+    rows.push({ level: "ok", msg: `Cohort ${r.key} ← ${r.source} (${r.value})` });
+    if (r.shadowed.length) rows.push({ level: "warn", msg: `  Cohort ${r.key}: ${r.source} wins over ${r.shadowed.join(", ")} — the losing value is ignored` });
+  }
+
+  // ── COHORT_ORG_ID: ID vs slug (F2) ─────────────────────────────────────────
+  const val = (key) => { const r = sources.find((x) => x.key === key); return r && r.source !== "none" ? r.value : ""; };
+  const n = (orgYaml && orgYaml.org && orgYaml.org.cohort) || {};
+  const base = String(n.base || n.apiUrl || env.COHORT_BASE || env.COHORT_API_URL || dotEnv.COHORT_BASE || dotEnv.COHORT_API_URL || "").replace(/\/+$/, "");
+  const token = String(n.token || env.COHORT_API_TOKEN || env.COHORT_TOKEN || env.COHORT_API_KEY || dotEnv.COHORT_API_TOKEN || dotEnv.COHORT_TOKEN || dotEnv.COHORT_API_KEY || "");
+  const configuredOrgId = val("orgId");
+  if (!base || !token) {
+    rows.push({ level: "ok", msg: "Org plane not enrolled (no base/token) — COHORT_ORG_ID check skipped" });
+  } else {
+    // Deliberately UNPINNED: a slug-valued pin would 401 the very probe that
+    // diagnoses it. The key alone selects the tenant server-side.
+    let id = "";
+    let slug = "";
+    let note = "";
+    try {
+      const res = await call("org.list", {}, { base, token, orgId: "", fetchImpl: o.fetchImpl, logImpl: () => {} });
+      const orgs = res && res.ok && res.result && Array.isArray(res.result.orgs) ? res.result.orgs : [];
+      const active = orgs.find((x) => x && x.isActive) || orgs[0];
+      if (active) { id = String(active.id || ""); slug = String(active.slug || ""); }
+      else note = res && !res.ok && res.error ? ` (org.list: ${res.error.code || res.error.message || "error"})` : " (org.list returned no org)";
+    } catch (err) { note = ` (org.list failed: ${err && err.message ? err.message : err})`; }
+    const shape = orgIdShape(configuredOrgId, id, slug);
+    rows.push({ level: shape.level, msg: shape.msg + (id ? "" : note) });
+  }
+
+  // ── Global SDK install + PATH (§3.7 item 6) ───────────────────────────────
+  const npmLs = tryExec("npm", ["ls", "-g", SDK_PACKAGE, "--json", "--depth=0"], { timeout: 8000 });
+  if (!npmLs) {
+    rows.push({ level: "warn", msg: `npm ls -g ${SDK_PACKAGE} failed — could not verify the global SDK install (is npm on PATH?)` });
+  } else {
+    const latest = tryExec("npm", ["view", SDK_PACKAGE, "version"], { timeout: 8000 });
+    const sdk = sdkGlobalInstall(npmLs, latest);
+    rows.push({ level: sdk.level, msg: sdk.msg });
+  }
+  for (const bin of ["maestro", "cohort-mcp"]) {
+    const where = tryExec("which", [bin], { timeout: 2000 }).trim();
+    if (!where) rows.push({ level: "warn", msg: `\`${bin}\` does not resolve on PATH — a home-dir session cannot reach the agent's tools; npm i -g ${SDK_PACKAGE}@latest` });
+  }
+
+  // ── Tailscale SSH (F4) ────────────────────────────────────────────────────
+  let status = "";
+  let prefs = "";
+  for (const bin of TAILSCALE_BINS) {
+    status = tryExec(bin, ["status", "--json"], { timeout: 4000 });
+    if (status) { prefs = tryExec(bin, ["debug", "prefs"], { timeout: 4000 }); break; }
+  }
+  const ts = tailscaleSsh(status, prefs);
+  rows.push({ level: ts.level, msg: ts.msg });
+
+  // ── Main session job (§3.1) ───────────────────────────────────────────────
+  const listPlists = o.listPlists || (() => { try { return readdirSync(join(homedir(), "Library", "LaunchAgents")); } catch { return []; } });
+  const loaded = parseLaunchctlList(tryExec("launchctl", ["list"], { timeout: 4000 }));
+  const heartbeat = safeJson(join(cwd, "state", "session", "heartbeat.json"));
+  const sess = sessionInstalled({ first: agentFirstName(cwd), plists: listPlists(), loaded, heartbeat, now });
+  rows.push({ level: sess.level, msg: sess.msg });
+
+  return rows;
+}
+
+function pick(obj, keys) {
+  const out = {};
+  for (const k of keys) if (obj && obj[k]) out[k] = String(obj[k]);
+  return out;
+}
+
+export default { parseDotEnv, mask, authMode, looksLikeOrgId, orgIdShape, effectiveSource, sdkGlobalInstall, tailscaleSsh, sessionInstalled, runDoctorChecks };