@brainervirus/workit-core 2.9.0 → 4.0.0

package/src/core/doctor.ts

@@ -1,1882 +0,0 @@
-// Shared offline doctor (DG-07/CA-09). One host-neutral engine checks the
-// installed Workit surfaces — pins, versions, assets, launchers, runtimes,
-// utilities, registrations, config, workspace match, credential metadata, and
-// log writability — with no network access except the optional registry probe
-// behind the stale-install comparison (CA-04) and fail-open provider CLI
-// identity probes. Credentials are handled by gh/glab; token values never enter
-// the report, any fix text, or any log event.
-import { spawnSync } from "node:child_process";
-import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  readlinkSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { SUPPORT_MATRIX } from "./support-matrix";
-import { inspectMetadataLock } from "./store-lock";
-import { bundleHashOfFile, isEphemeralCachePath } from "./runtime-identity";
-import { EVENT } from "./boundary";
-import { getDiagnosticLogger, isConfigObject } from "./config";
-import { packageRoot } from "./package-root";
-import {
-  CURSOR_RUNTIME_PACKAGE,
-  OPENCODE_NPM_PIN,
-  cursorHookDrift,
-  cursorHooksEntry,
-  cursorMcpServerEntry,
-  isWorkitPlugin,
-} from "./registration";
-import { readWorkspacesResult, resolveWorkspaceFrom } from "./workspaces";
-import {
-  CLAUDE_MARKETPLACE_NAME,
-  claudeWorkitInstalls,
-  type ClaudeWorkitInstall,
-} from "./host-install";
-import { validateCursorSkills, WORKIT_METHOD_SKILLS } from "./skill-manifests";
-import {
-  classifyHostGeneration,
-  digestFile,
-  readCutoverReceipt,
-  readGenerationState,
-  type CutoverHost,
-  type SessionObservation,
-} from "./cutover";
-
-// Mirrors init.ts TOKEN_PLACEHOLDER; kept local so the doctor never needs to
-// import the YouTrack/VCS stack just to label a credential state.
-const TOKEN_PLACEHOLDER = "YOUR_TOKEN_HERE";
-
-export type DoctorHost = "cli" | "opencode" | "cursor";
-
-export type DoctorCheckId =
-  | "runtime"
-  | "versions"
-  | "codex_pin"
-  | "claude_plugin"
-  | "assets"
-  | "launcher"
-  | "utility"
-  | "stale_pin"
-  | "stale_install"
-  | "registry_unreachable"
-  | "duplicate_registration"
-  | "malformed_config"
-  | "workspace_mismatch"
-  | "workspace_lock"
-  | "credential_metadata"
-  | "github_identity"
-  | "gitlab_identity"
-  | "log_writable"
-  | "legacy_component"
-  | "mixed_generation"
-  | "active_old_session"
-  | "managed_content_conflict"
-  | "missing_v1_component";
-
-export type DoctorCheckStatus = "pass" | "warn" | "fail";
-
-export type DoctorCheck = {
-  id: DoctorCheckId;
-  status: DoctorCheckStatus;
-  /** Bounded, path-level detail. Never contains credential values. */
-  detail: string;
-  fix?: string;
-};
-
-export type DoctorFix = { id: DoctorCheckId; fix: string };
-
-export type DoctorSummary = {
-  passed: number;
-  warned: number;
-  failed: number;
-  total: number;
-};
-
-export type DoctorReport = {
-  ok: boolean;
-  exitCode: number;
-  /** False when the doctor consulted the npm registry (local-dist version probe). */
-  offline: boolean;
-  host: DoctorHost;
-  checked_at: string;
-  summary: DoctorSummary;
-  checks: DoctorCheck[];
-  fixes: DoctorFix[];
-};
-
-export type DoctorOptions = {
-  host?: DoctorHost;
-  home?: string;
-  configDir?: string;
-  stateDir?: string;
-  /** Checkout containing packages/ (monorepo or share clone). */
-  dev?: string;
-  cwd?: string;
-  /** Workit store root for the lock check (default: WORKFLOW_WORKSPACE_ROOT, then cwd). */
-  workspaceRoot?: string;
-  opencodeConfig?: string;
-  /** OpenCode npm `@latest` package cache root (test seam). */
-  opencodePackageCacheDir?: string;
-  cursorSettings?: string;
-  cursorMcp?: string;
-  cursorPluginDir?: string;
-  env?: NodeJS.ProcessEnv;
-  /** Installer run: only registration/config checks count toward exitCode. */
-  installer?: boolean;
-  /** Observed host sessions used by generation-aware cutover checks. */
-  sessions?: SessionObservation[];
-};
-
-type Resolved = {
-  host: DoctorHost;
-  home: string;
-  configDir: string;
-  stateDir: string;
-  cwd: string;
-  workspaceRoot: string;
-  dev: string | null;
-  opencodeConfig: string;
-  opencodePackageCacheDir: string;
-  cursorSettings: string;
-  cursorMcp: string;
-  cursorPluginDir: string;
-  env: NodeJS.ProcessEnv;
-  installer: boolean;
-  sessions: SessionObservation[];
-};
-
-const parseSessionsFromEnv = (env: NodeJS.ProcessEnv): SessionObservation[] => {
-  const raw = env.WORKFLOW_TOOLKIT_SESSIONS;
-  if (!raw) return [];
-  try {
-    const parsed = JSON.parse(raw);
-    return Array.isArray(parsed) ? (parsed as SessionObservation[]) : [];
-  } catch {
-    return [];
-  }
-};
-
-const findDevFromCwd = (cwd: string): string | null => {
-  let dir = path.resolve(cwd);
-  while (true) {
-    if (existsSync(path.join(dir, "packages", "workit-core", "package.json"))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-};
-
-const resolve = (options: DoctorOptions): Resolved => {
-  const env = options.env ?? process.env;
-  const home = options.home ?? env.HOME ?? os.homedir();
-  const configDir =
-    options.configDir ??
-    env.WORKFLOW_TOOLKIT_CONFIG ??
-    env.WORKFLOW_TOOLKIT_CONFIG_DIR ??
-    path.join(home, ".config", "workit");
-  const stateDir =
-    options.stateDir ?? env.WORKFLOW_TOOLKIT_STATE ?? path.join(home, ".local", "state", "workit");
-  const cwd = options.cwd ?? process.cwd();
-  const dev = options.dev ?? env.WORKFLOW_TOOLKIT_DEV ?? findDevFromCwd(cwd);
-  return {
-    host: options.host ?? "cli",
-    home,
-    configDir,
-    stateDir,
-    cwd,
-    workspaceRoot: options.workspaceRoot ?? env.WORKFLOW_WORKSPACE_ROOT ?? cwd,
-    dev,
-    opencodeConfig:
-      options.opencodeConfig ?? path.join(home, ".config", "opencode", "opencode.json"),
-    opencodePackageCacheDir:
-      options.opencodePackageCacheDir ??
-      path.join(home, ".cache", "opencode", "packages", "@brainervirus", "workit-opencode@latest"),
-    cursorSettings: options.cursorSettings ?? path.join(home, ".cursor", "settings.json"),
-    cursorMcp: options.cursorMcp ?? path.join(home, ".cursor", "mcp.json"),
-    cursorPluginDir:
-      options.cursorPluginDir ?? path.join(home, ".cursor", "plugins", "local", "workit"),
-    env,
-    installer: options.installer ?? false,
-    sessions: options.sessions ?? parseSessionsFromEnv(env),
-  };
-};
-
-const readJson = (p: string): Record<string, any> | null => {
-  try {
-    const parsed = JSON.parse(readFileSync(p, "utf8"));
-    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, any>)
-      : null;
-  } catch {
-    return null;
-  }
-};
-
-// AR-07/CA-37: a JSON file that parses but is not an object (null, scalar,
-// array) is not a config file — the readers classify it malformed, so the
-// doctor must flag it too (a parse-only gate would call it healthy = fail-open).
-const parsesAsConfigObject = (p: string): boolean => {
-  try {
-    return isConfigObject(JSON.parse(readFileSync(p, "utf8")));
-  } catch {
-    return false;
-  }
-};
-
-// V2 uses plugins; V1 accepts plugin as a string or array. Inspect both.
-const pluginEntries = (cfg: Record<string, any> | null): string[] => {
-  const entries = [cfg?.plugins, cfg?.plugin].flatMap((value) =>
-    Array.isArray(value) ? value : typeof value === "string" ? [value] : [],
-  );
-  return [
-    ...new Set(
-      entries.filter(
-        (entry): entry is string => typeof entry === "string" && isWorkitPlugin(entry),
-      ),
-    ),
-  ];
-};
-
-export const commandOnPath = (name: string, env: NodeJS.ProcessEnv): boolean => {
-  const dirs = (env.PATH ?? process.env.PATH ?? "").split(path.delimiter);
-  // win32 executables carry an .exe suffix (bun.exe, git.exe), so probe both
-  // names — statSync with the bare name would never find them.
-  const names = process.platform === "win32" ? [name, `${name}.exe`] : [name];
-  for (const dir of dirs) {
-    if (!dir) continue;
-    for (const candidateName of names) {
-      const candidate = path.join(dir, candidateName);
-      try {
-        const st = statSync(candidate);
-        if (process.platform !== "win32" && (st.mode & 0o111) === 0) continue;
-        return true;
-      } catch {
-        /* keep scanning */
-      }
-    }
-  }
-  return false;
-};
-
-const versionOf = (bin: string, env: NodeJS.ProcessEnv): string | null => {
-  const r = spawnSync(bin, ["--version"], { encoding: "utf8", env });
-  if (r.error) return null;
-  return (r.stdout ?? "").trim();
-};
-
-const semverAtLeast = (version: string, min: string): boolean => {
-  const a = version
-    .replace(/^v/, "")
-    .split(".")
-    .map((n) => Number(n) || 0);
-  const b = min.split(".").map((n) => Number(n) || 0);
-  for (let i = 0; i < Math.max(a.length, b.length); i++) {
-    const av = a[i] ?? 0;
-    const bv = b[i] ?? 0;
-    if (av !== bv) return av > bv;
-  }
-  return true;
-};
-
-const resolveBun = (env: NodeJS.ProcessEnv): string | null => {
-  if (env.BUN && existsSync(env.BUN)) return env.BUN;
-  for (const candidate of [
-    path.join(os.homedir(), ".bun/bin/bun"),
-    "/usr/local/bin/bun",
-    "/usr/bin/bun",
-  ]) {
-    if (existsSync(candidate)) return candidate;
-  }
-  return commandOnPath("bun", env) ? "bun" : null;
-};
-
-// Installation checks ---------------------------------------------------------
-
-const checkRuntime = (res: Resolved): DoctorCheck => {
-  const node = versionOf("node", res.env);
-  const nodeOk = node !== null && semverAtLeast(node, SUPPORT_MATRIX.node.minimum);
-  const bun = resolveBun(res.env);
-  const bunVersion = bun ? versionOf(bun, res.env) : null;
-  const bunOk = bunVersion !== null;
-  const needsBun = res.dev !== null;
-  if (!nodeOk) {
-    return {
-      id: "runtime",
-      status: "fail",
-      detail: `node ${SUPPORT_MATRIX.node.minimum}+ required (found ${node ?? "none on PATH"})`,
-      fix: `Install Node ${SUPPORT_MATRIX.node.minimum}+ (declared support: ${SUPPORT_MATRIX.node.minimum}/current)`,
-    };
-  }
-  if (!bunOk && needsBun) {
-    return {
-      id: "runtime",
-      status: "fail",
-      detail: `bun not found on PATH (dev checkout requires the pinned toolchain ${SUPPORT_MATRIX.bun})`,
-      fix: `Install bun ${SUPPORT_MATRIX.bun} (curl -fsSL https://bun.sh/install | bash)`,
-    };
-  }
-  if (!bunOk) {
-    return {
-      id: "runtime",
-      status: "warn",
-      detail: "bun not found on PATH — not required for published artifacts",
-      fix: "Install bun for development/installer use",
-    };
-  }
-  return {
-    id: "runtime",
-    status: "pass",
-    detail: `node ${node} (>=${SUPPORT_MATRIX.node.minimum}), bun ${bunVersion ?? "n/a"}`,
-  };
-};
-
-const checkVersions = (res: Resolved): DoctorCheck => {
-  if (!res.dev) {
-    return {
-      id: "versions",
-      status: "warn",
-      detail: "no dev checkout found (WORKFLOW_TOOLKIT_DEV) — skipping version parity",
-    };
-  }
-  const corePkg = readJson(path.join(res.dev, "packages/workit-core/package.json"));
-  if (!corePkg) {
-    return {
-      id: "versions",
-      status: "warn",
-      detail: "dev checkout has no workit-core manifest — skipping version parity",
-    };
-  }
-  const refs = new Set<string>();
-  for (const name of ["workit-opencode", "workit-cursor", "workit-cli"]) {
-    const pkg = readJson(path.join(res.dev, "packages", name, "package.json"));
-    const dep = pkg?.dependencies?.["@brainervirus/workit-core"];
-    if (typeof dep === "string") refs.add(dep);
-  }
-  if (refs.size === 0) {
-    return {
-      id: "versions",
-      status: "warn",
-      detail: "no adapter core references found in the dev checkout",
-    };
-  }
-  const problems: string[] = [];
-  if (refs.size > 1) {
-    problems.push(`adapters pin different core versions: ${[...refs].join(", ")}`);
-  }
-  const opencodePkg = readJson(path.join(res.dev, "packages/workit-opencode/package.json"));
-  const sdk =
-    opencodePkg?.dependencies?.["@opencode-ai/plugin"] ??
-    opencodePkg?.devDependencies?.["@opencode-ai/plugin"];
-  const sdkVersion = typeof sdk === "string" ? (sdk.match(/^\d+(?:\.\d+){0,2}/) ?? [])[0] : null;
-  if (sdkVersion && !semverAtLeast(sdkVersion, SUPPORT_MATRIX.opencode.minimum)) {
-    problems.push(
-      `@opencode-ai/plugin ${sdk} is older than the supported minimum ${SUPPORT_MATRIX.opencode.minimum}`,
-    );
-  }
-  if (problems.length === 0) {
-    return {
-      id: "versions",
-      status: "pass",
-      detail: `adapter core references consistent (${[...refs].join(", ")})`,
-    };
-  }
-  return {
-    id: "versions",
-    status: "fail",
-    detail: problems.join("; "),
-    fix: "Align every adapter to the same @brainervirus/workit-core version (rewrite-workspace-deps.ts) or reinstall",
-  };
-};
-
-// The Codex CLI is a qualification host, not a runtime dependency: evidence
-// covers exactly SUPPORT_MATRIX.codex.cli. A drifted install keeps working,
-// but warns so a fresh install never silently outruns the qualification pin.
-const checkCodexPin = (res: Resolved): DoctorCheck => {
-  const qualified = SUPPORT_MATRIX.codex.cli;
-  if (!commandOnPath("codex", res.env))
-    return {
-      id: "codex_pin",
-      status: "pass",
-      detail: "codex CLI not on PATH — skipping pin check",
-    };
-  const raw = versionOf("codex", res.env);
-  const installed = raw ? ((raw.match(/\d+\.\d+\.\d+/) ?? [])[0] ?? null) : null;
-  if (installed === null)
-    return {
-      id: "codex_pin",
-      status: "warn",
-      detail: `could not parse the installed codex version — cannot confirm the qualified ${qualified}`,
-      fix: `Reinstall the qualified Codex CLI ${qualified} or record fresh qualification evidence`,
-    };
-  if (installed === qualified)
-    return {
-      id: "codex_pin",
-      status: "pass",
-      detail: `codex CLI ${installed} matches the qualified pin`,
-    };
-  return {
-    id: "codex_pin",
-    status: "warn",
-    detail: `codex CLI ${installed} differs from the qualified ${qualified}`,
-    fix: `Reinstall the qualified Codex CLI ${qualified} or record fresh qualification evidence`,
-  };
-};
-
-const detectDevGeneration = (dev: string): "legacy" | "v1" =>
-  existsSync(path.join(dev, "packages/workit-opencode/assets/skills/workit-plan/SKILL.md"))
-    ? "v1"
-    : "legacy";
-
-const effectiveGeneration = (res: Resolved): "legacy" | "v1" => {
-  const configured = readGenerationState(res.configDir).target;
-  if (configured === "v1") return "v1";
-  if (res.dev && detectDevGeneration(res.dev) === "v1") return "v1";
-  return "legacy";
-};
-
-const assetPathsFor = (host: DoctorHost, dev: string, _generation: "legacy" | "v1"): string[] => {
-  const pkg = path.join(dev, "packages", `workit-${host}`);
-  switch (host) {
-    case "opencode":
-      return WORKIT_METHOD_SKILLS.map((skill) =>
-        path.join(pkg, "assets", "skills", skill, "SKILL.md"),
-      );
-    case "cursor":
-      return [
-        path.join(pkg, "assets", "templates", "workit-contract.md"),
-        path.join(pkg, "mcp.json"),
-        path.join(pkg, ".cursor-plugin"),
-      ];
-    case "cli":
-      return [path.join(pkg, "assets", "templates", "spec-template.md")];
-  }
-};
-
-// The CLI doctor is comprehensive: it verifies every host package, while the
-// host tools verify only their own package.
-const hostsFor = (host: DoctorHost): DoctorHost[] =>
-  host === "cli" ? ["opencode", "cursor", "cli"] : [host];
-
-const checkAssets = (res: Resolved): DoctorCheck => {
-  const dev = res.dev;
-  const generation = effectiveGeneration(res);
-  const missing = dev
-    ? hostsFor(res.host).flatMap((h) =>
-        assetPathsFor(h, dev, generation)
-          .filter((p) => !existsSync(p))
-          .map((p) => `${h}: ${p}`),
-      )
-    : [];
-  if (res.host === "cursor" || res.host === "cli") {
-    const cursorError = validateCursorSkills(res.cursorPluginDir, WORKIT_METHOD_SKILLS);
-    if (cursorError) missing.push(`cursor: ${cursorError}`);
-  }
-  if (missing.length === 0) {
-    if (!dev && res.host === "opencode") {
-      return {
-        id: "assets",
-        status: "warn",
-        detail: "no dev checkout found (WORKFLOW_TOOLKIT_DEV) — skipping asset check",
-      };
-    }
-    return {
-      id: "assets",
-      status: "pass",
-      detail: dev ? `${res.host} assets present` : "installed Cursor skills valid",
-    };
-  }
-  return {
-    id: "assets",
-    status: "fail",
-    detail: `missing assets: ${missing.join(", ")}`,
-    fix: "Reinstall or rebuild the workit package (missing assets under packages/workit-<host>)",
-  };
-};
-
-const launcherSlotsFor = (host: DoctorHost, dev: string): string[][] => {
-  const pkg = path.join(dev, "packages", `workit-${host}`);
-  switch (host) {
-    case "opencode":
-      return [[path.join(pkg, "src", "plugin.ts"), path.join(pkg, "dist", "plugin.js")]];
-    case "cursor":
-      // The dist entries are the npm bin targets the npx launcher executes.
-      return [
-        [path.join(pkg, "dist", "mcp-server.js")],
-        [path.join(pkg, "dist", "cursor-session-start.js")],
-      ];
-    case "cli":
-      return [[path.join(pkg, "src", "index.tsx"), path.join(pkg, "dist", "index.js")]];
-  }
-};
-
-const validNodeEntry = (entry: string, runtime: string, env: NodeJS.ProcessEnv): boolean => {
-  try {
-    const stat = statSync(entry);
-    if (
-      !stat.isFile() ||
-      stat.size === 0 ||
-      !readFileSync(entry, "utf8").startsWith("#!/usr/bin/env node\n")
-    ) {
-      return false;
-    }
-    return spawnSync(runtime, ["--check", entry], { encoding: "utf8", env }).status === 0;
-  } catch {
-    return false;
-  }
-};
-
-type CursorLauncher = { kind: "node"; runtime: string; entry: string } | { kind: "npx" };
-
-const registeredCursorLauncher = (res: Resolved): CursorLauncher | null | "invalid" => {
-  if (!existsSync(res.cursorMcp)) return "invalid";
-  const config = readJson(res.cursorMcp);
-  if (!config) return null; // malformed_config owns malformed JSON/object reporting
-  const server = config.mcpServers?.workit;
-  if (!server || typeof server !== "object" || Array.isArray(server)) return "invalid";
-  const command = server.command;
-  const args = server.args;
-  if (typeof command !== "string" || !Array.isArray(args) || typeof args[0] !== "string") {
-    return "invalid";
-  }
-  const executable = path.basename(command).toLowerCase();
-  // CA-17: the canonical launcher runs the published package through npx; the
-  // offline doctor validates its shape (never the registry reachability).
-  // Exact positional tokens — a substring match would accept `@latest-alpha`
-  // or `workit-cursor-mcp-foo`, and any extra/missing token would weaken the
-  // freshness guarantee (`--prefer-online` and the npm release-age workaround
-  // are mandatory).
-  const canonical = cursorMcpServerEntry("").args;
-  if (executable === "npx" || executable === "npx.exe" || executable === "npx.cmd") {
-    if (args.length !== canonical.length || args.some((a, i) => a !== canonical[i]))
-      return "invalid";
-    return { kind: "npx" };
-  }
-  if (executable !== "node" && executable !== "node.exe") return "invalid";
-  return {
-    kind: "node",
-    runtime: command,
-    entry: path.isAbsolute(args[0]) ? args[0] : path.resolve(path.dirname(res.cursorMcp), args[0]),
-  };
-};
-
-// CA-17: the canonical session-start hook runs the published package through
-// npx as a single command string (Cursor's documented hook format). The doctor
-// validates its shape exactly like the MCP launcher — no substring matching,
-// no version abstraction.
-const canonicalCursorHook = cursorHooksEntry("").command;
-
-// Returns the registered hook command, null when absent, or "invalid".
-const registeredCursorHook = (res: Resolved): string | null => {
-  const hooksFile = path.join(res.cursorPluginDir, "hooks", "hooks-cursor.json");
-  if (!existsSync(hooksFile)) return "invalid";
-  const config = readJson(hooksFile);
-  // Unlike mcp.json, the hook file is not covered by checkMalformedConfig, so
-  // an unparseable hook must fail the launcher check rather than slip through.
-  if (!config) return "invalid";
-  const sessionStart = config.hooks?.sessionStart;
-  if (!Array.isArray(sessionStart) || sessionStart.length !== 1) return "invalid";
-  const entry = sessionStart[0];
-  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return "invalid";
-  return typeof entry.command === "string" ? entry.command : "invalid";
-};
-
-// The local-dist install points the session-start hook at the plugin's own
-// built dist (`node <pluginDir>/dist/cursor-session-start.js`) so Cursor runs
-// the checkout's code. Accept that form — validated against the real dist entry
-// — alongside the canonical npx pin, mirroring the MCP launcher's node form.
-const validLocalDistHook = (command: string, res: Resolved): boolean => {
-  const m = /^node\s+(.+)$/.exec(command.trim());
-  if (!m) return false;
-  const entry = m[1].trim();
-  if (!path.isAbsolute(entry)) return false;
-  if (
-    path.resolve(entry) !==
-    path.resolve(path.join(res.cursorPluginDir, "dist", "cursor-session-start.js"))
-  ) {
-    return false;
-  }
-  return validNodeEntry(entry, "node", res.env);
-};
-
-const checkLauncher = (res: Resolved): DoctorCheck => {
-  const dev = res.dev;
-  const hosts = hostsFor(res.host);
-  const registered = hosts.includes("cursor") ? registeredCursorLauncher(res) : null;
-  const runtime =
-    registered && registered !== "invalid" && registered.kind === "node"
-      ? registered.runtime
-      : "node";
-  const missing = hosts.includes("cursor")
-    ? ["dist/mcp-server.js", "dist/cursor-session-start.js"]
-        .map((rel) => path.join(res.cursorPluginDir, rel))
-        .filter((p) => !validNodeEntry(p, runtime, res.env))
-        .map((p) => `cursor: ${p}`)
-    : [];
-  if (hosts.includes("cursor")) {
-    if (registered === "invalid") {
-      missing.push(`cursor: canonical workit MCP launcher in ${res.cursorMcp}`);
-    } else if (
-      registered &&
-      registered.kind === "node" &&
-      !validNodeEntry(registered.entry, registered.runtime, res.env)
-    ) {
-      missing.push(`cursor: registered ${registered.entry}`);
-    }
-    const hook = registeredCursorHook(res);
-    if (hook === "invalid") {
-      missing.push(
-        `cursor: canonical session-start hook in ${path.join(res.cursorPluginDir, "hooks", "hooks-cursor.json")}`,
-      );
-    } else if (hook !== null && hook !== canonicalCursorHook && !validLocalDistHook(hook, res)) {
-      missing.push(
-        `cursor: canonical session-start hook in ${path.join(res.cursorPluginDir, "hooks", "hooks-cursor.json")} (registered ${hook})`,
-      );
-    }
-  }
-  if (dev) {
-    missing.push(
-      ...hosts
-        .filter((h) => h !== "cursor")
-        .flatMap((h) =>
-          launcherSlotsFor(h, dev)
-            .filter((slot) => !slot.some((p) => existsSync(p)))
-            .map((slot) => `${h}: ${slot.join(" or ")}`),
-        ),
-    );
-  }
-  if (missing.length > 0) {
-    return {
-      id: "launcher",
-      status: "fail",
-      detail: `missing or invalid launcher entry: ${missing.join("; ")}`,
-      fix: `Rebuild and reinstall the workit package (bun run build) — dist entries must be non-empty Node launchers`,
-    };
-  }
-  if (!dev && res.host !== "cursor") {
-    return {
-      id: "launcher",
-      status: "warn",
-      detail: "no dev checkout found (WORKFLOW_TOOLKIT_DEV) — skipping non-Cursor launcher checks",
-    };
-  }
-  return {
-    id: "launcher",
-    status: "pass",
-    detail: `${res.host} launcher/hook entries present`,
-  };
-};
-
-const checkUtility = (res: Resolved): DoctorCheck => {
-  const git = commandOnPath("git", res.env);
-  if (!git) {
-    return {
-      id: "utility",
-      status: "fail",
-      detail: "git not found in PATH — installers, PRs and verification require it",
-      fix: "Install git and ensure it is on PATH",
-    };
-  }
-  if (process.platform !== "win32" && !commandOnPath("flock", res.env)) {
-    return {
-      id: "utility",
-      status: "warn",
-      detail: "flock (util-linux) not found — sync-runtime requires it for locking",
-      fix: "Install util-linux (flock)",
-    };
-  }
-  return {
-    id: "utility",
-    status: "pass",
-    detail: "git (and flock where required) on PATH",
-  };
-};
-
-/** file:// pins into package-manager ephemeral caches (pnpm dlx, npx). */
-const isFragileCachePin = (entry: string): boolean => {
-  const n = entry.replaceAll("\\", "/").toLowerCase();
-  if (!n.startsWith("file:")) return false;
-  return isEphemeralCachePath(entry);
-};
-
-const staleEntry = (entry: string): "ok" | "stale" | "missing-file" | "fragile-cache" => {
-  if (!entry) return "stale";
-  if (entry.includes("git+file")) return "stale";
-  if (isFragileCachePin(entry)) return "fragile-cache";
-  if (entry.startsWith("file:")) {
-    const target = entry.replace(/^file:\/\//, "").replace(/^file:/, "");
-    return existsSync(target) ? "ok" : "missing-file";
-  }
-  // Registry package names (e.g. @brainervirus/workit-opencode) are the
-  // published pin shape — OpenCode resolves them; not labelled stale.
-  return "ok";
-};
-
-const checkStalePin = (res: Resolved): DoctorCheck => {
-  if (res.host === "cursor") {
-    return {
-      id: "stale_pin",
-      status: "pass",
-      detail: "opencode pin not inspected on the cursor host",
-    };
-  }
-  if (!existsSync(res.opencodeConfig)) {
-    return {
-      id: "stale_pin",
-      status: "pass",
-      detail: "no opencode config — not registered",
-    };
-  }
-  const cfg = readJson(res.opencodeConfig);
-  const entries = pluginEntries(cfg);
-  if (entries.length === 0) {
-    return {
-      id: "stale_pin",
-      status: "fail",
-      detail: "no workit plugin registered in the opencode config",
-      fix: 'Run `workit init` and select OpenCode — pin "@brainervirus/workit-opencode"',
-    };
-  }
-  const first = staleEntry(entries[0]);
-  if (first === "stale") {
-    return {
-      id: "stale_pin",
-      status: "fail",
-      detail: `stale workit pin: ${entries[0]}`,
-      fix: "Run `workit init` (or install-opencode-plugin.sh for a checkout) — replace git+file pins",
-    };
-  }
-  if (first === "fragile-cache") {
-    return {
-      id: "stale_pin",
-      status: "fail",
-      detail: `workit pin points at a package-manager cache path: ${entries[0]}`,
-      fix: 'Run `workit init` and select OpenCode — pin should be "@brainervirus/workit-opencode"',
-    };
-  }
-  if (first === "missing-file") {
-    return {
-      id: "stale_pin",
-      status: "fail",
-      detail: `workit pin points at a missing file: ${entries[0]}`,
-      fix: "Run `workit init` (or restore the checkout and re-run install-opencode-plugin.sh)",
-    };
-  }
-  return { id: "stale_pin", status: "pass", detail: "opencode pin resolves" };
-};
-
-// Cursor plugin stale-install detection (CA-01/CA-04). Compares the installed
-// `~/.cursor/plugins/local/workit` against the current runtime source of truth
-// (`CURSOR_RUNTIME_PACKAGE` + the canonical entry builders from registration.ts,
-// D-02) and surfaces a structured `stale_install` finding with the exact repair
-// step. A stale install means the plugin's sessionStart hook and MCP entry run
-// an ancient runtime that no longer auto-registers the workflow features.
-//
-// Three independent staleness signals are read from the installed plugin dir:
-//  1. Legacy selectors (offline evidence, checked first): the plugin's own
-//     mcp.json (`--package=...workit-cursor@<exact>` pins other than the
-//     canonical `@latest`) and hooks-cursor.json sessionStart command.
-//  2. Installed version behind the current source release (offline): the dev
-//     checkout's workit-cursor version (or the doctor's own package version)
-//     is the release train the doctor ships with.
-//  3. Local-dist installs behind the published runtime (needs the registry):
-//     the probe is the sole network read in the doctor. A SUCCEEDED probe with
-//     the installed version genuinely behind the published runtime is a hard
-//     `stale_install` fail (the installer self-heals on it); an unreachable
-//     registry fails open (CA-04) as a `registry_unreachable` warning, never a
-//     false `stale_install` and never a hard doctor failure. Canonical
-//     `@latest` installs skip the probe entirely: the selector resolves fresh
-//     at launch, so the installed package.json version is metadata, not a
-//     freshness signal.
-// OpenCode npm pins (`@brainervirus/workit-opencode` / `@…@latest`) are different:
-// OpenCode freezes the first resolved version under
-// `~/.cache/opencode/packages/@brainervirus/workit-opencode@latest` and does not
-// re-resolve on later launches. Doctor compares that cache to the published
-// package (same CA-04 fail-open seam) and tells the user to delete the cache
-// directory so OpenCode can resolve `@latest` again. Exact `@version` pins and
-// `file://` checkout pins skip the comparison.
-// Test seams (no spawns on the canonical path): WORKIT_DOCTOR_STALE_REGISTRY_VERSION
-// short-circuits the probe with the resolved latest version; the optional
-// WORKIT_DOCTOR_STALE_REGISTRY_CMD replaces the `npm view` binary (a
-// nonexistent path deterministically exercises the fail-open path).
-const pluginMcpSelectors = (res: Resolved): string[] | null => {
-  const p = path.join(res.cursorPluginDir, "mcp.json");
-  if (!existsSync(p)) return null;
-  const cfg = readJson(p);
-  const server = cfg?.mcpServers?.workit;
-  if (!server || typeof server !== "object" || Array.isArray(server)) return null;
-  const args = server.args;
-  if (!Array.isArray(args)) return null;
-  return args.map(String).filter((a) => a.startsWith("--package="));
-};
-
-const isFloatingOpenCodeNpmPin = (entry: string): boolean => {
-  const s = entry.trim();
-  return s === OPENCODE_NPM_PIN || s === `${OPENCODE_NPM_PIN}@latest`;
-};
-
-const registryLatestVersion = (
-  res: Resolved,
-  pkgName: string = CURSOR_RUNTIME_PACKAGE,
-): string | null => {
-  const seam = res.env.WORKIT_DOCTOR_STALE_REGISTRY_VERSION;
-  if (typeof seam === "string" && seam) {
-    return /^\d+(?:\.\d+){1,2}$/.test(seam) ? seam : null;
-  }
-  const cmd =
-    res.env.WORKIT_DOCTOR_STALE_REGISTRY_CMD ?? (commandOnPath("npm", res.env) ? "npm" : null);
-  if (!cmd) return null;
-  try {
-    const r = spawnSync(cmd, ["view", pkgName, "version"], {
-      encoding: "utf8",
-      timeout: 20_000,
-      env: res.env,
-    });
-    const v = (r.stdout ?? "").trim().split(/\s+/)[0];
-    return r.status === 0 && /^\d+(?:\.\d+){1,2}$/.test(v) ? v : null;
-  } catch {
-    return null;
-  }
-};
-
-const installedPluginVersion = (res: Resolved): string | null => {
-  const pkg = readJson(path.join(res.cursorPluginDir, "package.json"));
-  return typeof pkg?.version === "string" && pkg.version ? pkg.version : null;
-};
-
-const installedOpenCodeCacheVersion = (res: Resolved): string | null => {
-  const pkg = readJson(
-    path.join(
-      res.opencodePackageCacheDir,
-      "node_modules",
-      "@brainervirus",
-      "workit-opencode",
-      "package.json",
-    ),
-  );
-  return typeof pkg?.version === "string" && pkg.version ? pkg.version : null;
-};
-
-/** OpenCode freezes the first `@latest` resolve in its package cache — detect lag. */
-const checkOpenCodePackageCache = (res: Resolved): DoctorCheck & { registryProbed?: boolean } => {
-  if (!existsSync(res.opencodeConfig)) {
-    return {
-      id: "stale_install",
-      status: "pass",
-      detail: "no opencode config — package cache not inspected",
-    };
-  }
-  const entries = pluginEntries(readJson(res.opencodeConfig));
-  if (entries.length === 0) {
-    return {
-      id: "stale_install",
-      status: "pass",
-      detail: "no workit opencode pin — package cache not inspected",
-    };
-  }
-  const pin = entries[0];
-  if (pin.startsWith("file:") || pin.startsWith("git+file:")) {
-    return {
-      id: "stale_install",
-      status: "pass",
-      detail: "opencode checkout pin — package cache not used for npm resolution",
-    };
-  }
-  if (!isFloatingOpenCodeNpmPin(pin)) {
-    return {
-      id: "stale_install",
-      status: "pass",
-      detail: `opencode pin ${pin} is an exact version — not compared to registry latest`,
-    };
-  }
-  const installed = installedOpenCodeCacheVersion(res);
-  if (installed === null) {
-    return {
-      id: "stale_install",
-      status: "pass",
-      detail: "opencode @latest package cache empty — OpenCode will resolve on next launch",
-    };
-  }
-  const expected = registryLatestVersion(res, OPENCODE_NPM_PIN);
-  if (expected === null) {
-    return {
-      id: "registry_unreachable",
-      status: "warn",
-      registryProbed: true,
-      detail:
-        "registry_unreachable: cannot compare OpenCode @latest cache against published workit-opencode",
-      fix: `Retry when npm is reachable, or remove ${res.opencodePackageCacheDir} and restart OpenCode to re-resolve`,
-    };
-  }
-  if (!semverAtLeast(installed, expected)) {
-    return {
-      id: "stale_install",
-      status: "fail",
-      registryProbed: true,
-      detail: `stale_install: OpenCode @latest cache has workit-opencode ${installed} behind published ${expected}`,
-      fix: `Remove ${res.opencodePackageCacheDir} and restart OpenCode — it re-resolves @latest on the next launch`,
-    };
-  }
-  return {
-    id: "stale_install",
-    status: "pass",
-    registryProbed: true,
-    detail: `OpenCode @latest cache workit-opencode ${installed} matches published ${expected}`,
-  };
-};
-
-const checkStaleInstall = (res: Resolved): DoctorCheck & { registryProbed?: boolean } => {
-  if (res.host === "opencode") {
-    return checkOpenCodePackageCache(res);
-  }
-  if (res.host !== "cursor" && res.host !== "cli") {
-    return {
-      id: "stale_install",
-      status: "pass",
-      detail: "cursor plugin not inspected on this host",
-    };
-  }
-  // Symlink installs into pnpm dlx / _npx caches break when the cache is cleared.
-  // MCP launchers may still be canonical; the plugin dir itself must be real.
-  if (existsSync(res.cursorPluginDir) && lstatSync(res.cursorPluginDir).isSymbolicLink()) {
-    let target = "";
-    try {
-      target = readlinkSync(res.cursorPluginDir);
-    } catch {
-      target = "(unreadable)";
-    }
-    const fragile = isEphemeralCachePath(target);
-    return {
-      id: "stale_install",
-      status: "fail",
-      detail: fragile
-        ? `stale_install: cursor plugin dir is a symlink into a package-manager cache (${target})`
-        : `stale_install: cursor plugin dir is a symlink (${target}) — expected a real directory copy`,
-      fix: "Run `workit init` and select Cursor — install must copy into ~/.cursor/plugins/local/workit",
-    };
-  }
-  const canonicalMcp = cursorMcpServerEntry("").args.find((a) => a.startsWith("--package="));
-  const mcpSelectors = pluginMcpSelectors(res);
-  const legacyPin = (mcpSelectors ?? []).find(
-    (s) => s !== canonicalMcp && s.includes("@brainervirus/workit-cursor@"),
-  );
-  if (legacyPin) {
-    return {
-      id: "stale_install",
-      status: "fail",
-      detail: `stale_install: plugin mcp.json pins a legacy selector ${legacyPin} (canonical: ${canonicalMcp})`,
-      fix: "Re-run install-cursor-plugin.sh — it rewrites the workit MCP entry to the canonical @latest selector",
-    };
-  }
-  const hooksFile = path.join(res.cursorPluginDir, "hooks", "hooks-cursor.json");
-  const hookCmd =
-    (readJson(hooksFile)?.hooks?.sessionStart?.[0]?.command as string | undefined) ?? null;
-  const canonicalHook = canonicalCursorHook;
-  const staleHook =
-    hookCmd !== null &&
-    hookCmd !== canonicalHook &&
-    !hookCmd.startsWith("node ") &&
-    hookCmd.includes("@brainervirus/workit-cursor@");
-  if (staleHook) {
-    return {
-      id: "stale_install",
-      status: "fail",
-      detail: `stale_install: sessionStart hook runs a legacy selector (canonical: ${canonicalHook})`,
-      fix: "Re-run install-cursor-plugin.sh — it rewrites the sessionStart hook to the canonical @latest selector",
-    };
-  }
-  // Enforcement-event drift: a present-but-divergent preToolUse matcher (or
-  // beforeShellExecution command) silently narrows what the hook intercepts.
-  // Absent events are filled by the installer merge, so only divergence fails.
-  const hookDrift = existsSync(hooksFile) ? cursorHookDrift(readJson(hooksFile)) : [];
-  if (hookDrift.length > 0) {
-    return {
-      id: "stale_install",
-      status: "fail",
-      detail: `stale_install: cursor hook drift on ${hookDrift.join(", ")} (differs from the canonical hook entries)`,
-      fix: "Re-run install-cursor-plugin.sh — it rewrites the workit hook entries to canonical",
-    };
-  }
-  const installed = installedPluginVersion(res);
-  const source = res.dev
-    ? ((readJson(path.join(res.dev, "packages/workit-cursor/package.json"))?.version as
-        | string
-        | undefined) ?? null)
-    : ((readJson(path.join(packageRoot(), "package.json"))?.version as string | undefined) ?? null);
-  // A local-dist install (node entry) runs the installed dir's own dist, so its
-  // version is comparable against the current runtime (and the published one
-  // below). Canonical @latest installs resolve fresh at launch — the installed
-  // package.json version is metadata, not a freshness signal (CA-04), so they
-  // skip both version comparisons and never fail stale_install on metadata.
-  const localDist = mcpSelectors === null && hookCmd !== null && hookCmd.startsWith("node ");
-  if (localDist && installed !== null && source !== null && !semverAtLeast(installed, source)) {
-    return {
-      id: "stale_install",
-      status: "fail",
-      detail: `stale_install: installed workit-cursor ${installed} is behind the current runtime ${source}`,
-      fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory and rewrites the workit MCP/hook entries",
-    };
-  }
-  // Same version, different bytes: the install was hand-edited or built from
-  // a dirty tree. Version strings cannot see that; the bundle hash can. The
-  // dev dist is byte-deterministic, so a mismatch heals with reinstall.
-  if (localDist && installed !== null && source !== null && res.dev) {
-    const entry = /^node\s+(.+)$/.exec((hookCmd ?? "").trim())?.[1]?.trim() ?? "";
-    const sourceBundle =
-      entry && path.isAbsolute(entry)
-        ? path.join(res.dev, "packages", "workit-cursor", "dist", path.basename(entry))
-        : "";
-    if (entry && sourceBundle) {
-      const installedHash = bundleHashOfFile(entry);
-      const sourceHash = bundleHashOfFile(sourceBundle);
-      if (installedHash !== null && sourceHash !== null && installedHash !== sourceHash) {
-        return {
-          id: "stale_install",
-          status: "fail",
-          detail: `stale_install: installed workit-cursor ${installed} runs different bytes than the current runtime build (${path.basename(entry)} hash mismatch)`,
-          fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory with the current build",
-        };
-      }
-    }
-  }
-  if (installed !== null && localDist) {
-    const expected = registryLatestVersion(res);
-    if (expected === null) {
-      return {
-        id: "registry_unreachable",
-        status: "warn",
-        registryProbed: true,
-        detail:
-          "registry_unreachable: cannot compare installed workit-cursor against the published runtime",
-        fix: "Retry when the npm registry is reachable, or re-run install-cursor-plugin.sh to refresh the install",
-      };
-    }
-    if (!semverAtLeast(installed, expected)) {
-      // The probe SUCCEEDED and the installed version is genuinely behind the
-      // published runtime: report a hard fail so `doctor-check.ts cursor --stale`
-      // exits 2 and the installer self-heals the local-dist install.
-      return {
-        id: "stale_install",
-        status: "fail",
-        registryProbed: true,
-        detail: `stale_install: local-dist workit-cursor ${installed} is behind the published runtime ${expected}`,
-        fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory with the current build",
-      };
-    }
-    const cursorOk = {
-      id: "stale_install" as const,
-      status: "pass" as const,
-      registryProbed: true,
-      detail: `installed local-dist workit-cursor ${installed} matches the published runtime ${expected}`,
-    };
-    if (res.host === "cli") {
-      const oc = checkOpenCodePackageCache(res);
-      if (oc.status !== "pass") return oc;
-    }
-    return cursorOk;
-  }
-  const cursorOk = {
-    id: "stale_install" as const,
-    status: "pass" as const,
-    detail:
-      installed === null
-        ? "installed workit-cursor selectors are canonical"
-        : `installed workit-cursor ${installed} is metadata on the canonical @latest install (fresh at launch)`,
-  };
-  if (res.host === "cli") {
-    const oc = checkOpenCodePackageCache(res);
-    if (oc.status !== "pass") return oc;
-  }
-  return cursorOk;
-};
-
-const checkDuplicateRegistration = (res: Resolved): DoctorCheck => {
-  const problems: string[] = [];
-  const opencodeHost = res.host !== "cursor";
-  const cursorHost = res.host !== "opencode";
-
-  if (opencodeHost && existsSync(res.opencodeConfig)) {
-    const cfg = readJson(res.opencodeConfig);
-    const entries = pluginEntries(cfg);
-    if (entries.length > 1)
-      problems.push(`opencode registers ${entries.length} workit plugin entries`);
-  }
-  if (cursorHost && existsSync(res.cursorSettings)) {
-    const settings = readJson(res.cursorSettings);
-    const enabled = settings?.enabled_plugins;
-    if (enabled && typeof enabled === "object") {
-      const keys = Object.keys(enabled).filter((k) => isWorkitPlugin(k));
-      if (keys.length > 1)
-        problems.push(
-          `cursor enables ${keys.length} workit plugin identities (${keys.join(", ")})`,
-        );
-    }
-    const dirs = Array.isArray(settings?.plugin_dirs)
-      ? settings.plugin_dirs.map(String).filter((d) => {
-          // Exact local plugin-dir identities only (CA-09): a similarly-named
-          // unrelated dir (e.g. `local/workflow-toolkit-extra`) is preserved
-          // and must never be counted as a Workit entry.
-          const n = d.replaceAll("\\", "/").replace(/\/+$/, "");
-          return (
-            isWorkitPlugin(d) || n.endsWith("local/workit") || n.endsWith("local/workflow-toolkit")
-          );
-        })
-      : [];
-    if (dirs.length > 1) problems.push(`cursor plugin_dirs has ${dirs.length} workit entries`);
-  }
-  if (cursorHost && existsSync(res.cursorMcp)) {
-    const mcp = readJson(res.cursorMcp);
-    const servers = mcp?.mcpServers ?? {};
-    if (servers && typeof servers === "object") {
-      const workitServers = Object.keys(servers).filter(
-        (s) => s === "workit" || s.includes("workflow-toolkit"),
-      );
-      if (workitServers.length > 1)
-        problems.push(
-          `cursor registers ${workitServers.length} workit MCP servers (${workitServers.join(", ")})`,
-        );
-    }
-  }
-  if (problems.length === 0) {
-    return {
-      id: "duplicate_registration",
-      status: "pass",
-      detail: "no duplicate registrations",
-    };
-  }
-  return {
-    id: "duplicate_registration",
-    status: "fail",
-    detail: problems.join("; "),
-    fix: "Re-run install-opencode-plugin.sh / install-cursor-plugin.sh to deduplicate registrations",
-  };
-};
-
-const checkMalformedConfig = (res: Resolved): DoctorCheck => {
-  const files: string[] = [];
-  for (const name of ["config.json", "youtrack.json", "vcs.json", "workspaces.json"]) {
-    const p = path.join(res.configDir, name);
-    if (existsSync(p)) files.push(p);
-  }
-  const opencodeHost = res.host !== "cursor";
-  const cursorHost = res.host !== "opencode";
-  if (opencodeHost && existsSync(res.opencodeConfig)) files.push(res.opencodeConfig);
-  if (cursorHost && existsSync(res.cursorSettings)) files.push(res.cursorSettings);
-  if (cursorHost && existsSync(res.cursorMcp)) files.push(res.cursorMcp);
-  const bad = files.filter((p) => !parsesAsConfigObject(p));
-  if (bad.length === 0)
-    return {
-      id: "malformed_config",
-      status: "pass",
-      detail: "config files parse",
-    };
-  return {
-    id: "malformed_config",
-    status: "fail",
-    detail: `malformed config: ${bad.join(", ")}`,
-    fix: `Repair the malformed config in ${bad[0]}`,
-  };
-};
-
-const checkWorkspaceMismatch = (res: Resolved): DoctorCheck => {
-  const result = readWorkspacesResult(res.configDir);
-  const file = result.path;
-  if (result.status === "missing" || (result.status === "valid" && result.entries.length === 0))
-    return {
-      id: "workspace_mismatch",
-      status: "pass",
-      detail: "no workspaces configured",
-    };
-  if (result.status === "malformed" || result.status === "invalid")
-    return {
-      id: "workspace_mismatch",
-      status: "fail",
-      detail: result.error ?? `${file} has invalid workspace configuration`,
-      fix: `Repair workspace configuration in ${file}`,
-    };
-  let match;
-  try {
-    match = resolveWorkspaceFrom(
-      res.cwd,
-      res.configDir,
-      res.env.WORKFLOW_WORKSPACE_NAME?.trim() || undefined,
-    );
-  } catch (error) {
-    return {
-      id: "workspace_mismatch",
-      status: "fail",
-      detail: error instanceof Error ? error.message : String(error),
-      fix: `Choose a matching workspace with WORKFLOW_WORKSPACE_NAME or repair ${file}`,
-    };
-  }
-  if (match)
-    return {
-      id: "workspace_mismatch",
-      status: "pass",
-      detail: `current directory matches workspace "${match.name}"`,
-    };
-  return {
-    id: "workspace_mismatch",
-    status: "fail",
-    detail: `current directory ${res.cwd} does not match any configured workspace`,
-    fix: `Add a workspace glob matching this directory to ${file} or run /wk-init`,
-  };
-};
-
-// Credential metadata: existence, mode, placeholder — never the value.
-const isPlaceholder = (p: string): boolean => {
-  try {
-    return readFileSync(p, "utf8").trim() === TOKEN_PLACEHOLDER;
-  } catch {
-    return false;
-  }
-};
-
-const checkCredentialMetadata = (res: Resolved): DoctorCheck => {
-  const tokenPaths: string[] = [];
-  const youtrackJson = readJson(path.join(res.configDir, "youtrack.json"));
-  if (youtrackJson) {
-    tokenPaths.push(
-      typeof youtrackJson.tokenFile === "string"
-        ? youtrackJson.tokenFile
-        : path.join(res.configDir, "youtrack.token"),
-    );
-  } else if (existsSync(path.join(res.configDir, "youtrack.token"))) {
-    tokenPaths.push(path.join(res.configDir, "youtrack.token"));
-  }
-
-  if (tokenPaths.length === 0) {
-    return {
-      id: "credential_metadata",
-      status: "pass",
-      detail: "no credentials configured",
-    };
-  }
-  const problems: string[] = [];
-  for (const raw of tokenPaths) {
-    const p = path.isAbsolute(raw) ? raw : path.resolve(res.configDir, raw);
-    if (!existsSync(p)) {
-      problems.push(`${p} is missing`);
-      continue;
-    }
-    if (process.platform !== "win32") {
-      const mode = statSync(p).mode & 0o777;
-      if (mode !== 0o600) problems.push(`${p} must be mode 0600 (found ${mode.toString(8)})`);
-    }
-    if (isPlaceholder(p)) problems.push(`${p} still contains the placeholder token`);
-  }
-  if (problems.length === 0) {
-    return {
-      id: "credential_metadata",
-      status: "pass",
-      detail: "credential files present with safe metadata",
-    };
-  }
-  return {
-    id: "credential_metadata",
-    status: "fail",
-    detail: problems.join("; "),
-    fix: "Create or fix the token file (mode 0600, real value) — see /wk-status for the exact path",
-  };
-};
-
-// Provider CLI and SSH identities are public usernames; Workit never reads a VCS token file.
-export type IdentitySurface = { surface: string; login: string | null };
-
-export type IdentityProbes = {
-  origin: (cwd: string) => string | null;
-  ghLogin: (env: NodeJS.ProcessEnv) => string | null;
-  glabLogin?: (env: NodeJS.ProcessEnv) => string | null;
-  sshLogin: (host: string) => string | null;
-};
-
-export const githubHostFromRemote = (remote: string): string | null => {
-  const rest = (remote || "").trim();
-  if (!rest) return null;
-  const scp = /^[^@/]+@([^:]+):/.exec(rest);
-  if (scp) return scp[1].toLowerCase();
-  try {
-    const url = new URL(rest.includes("://") ? rest : `https://${rest}`);
-    return url.hostname.toLowerCase() || null;
-  } catch {
-    return null;
-  }
-};
-
-const identityProvider = (
-  host: string,
-  config: Record<string, any> | null,
-  workspaceProvider?: unknown,
-): "github" | "gitlab" | null =>
-  workspaceProvider === "github" || workspaceProvider === "gitlab"
-    ? workspaceProvider
-    : host === "github.com"
-      ? "github"
-      : host === "gitlab.com"
-        ? "gitlab"
-        : config?.provider === "github" || config?.provider === "gitlab"
-          ? config.provider
-          : config?.github
-            ? "github"
-            : config?.gitlab
-              ? "gitlab"
-              : null;
-
-const providerIdentityFinding = (
-  provider: "github" | "gitlab",
-  surfaces: IdentitySurface[],
-): DoctorCheck => {
-  const id: "github_identity" | "gitlab_identity" = `${provider}_identity`;
-  const label = provider === "github" ? "GitHub" : "GitLab";
-  const resolved = surfaces.filter(
-    (entry): entry is { surface: string; login: string } => typeof entry.login === "string",
-  );
-  const distinct = [...new Set(resolved.map((entry) => entry.login.toLowerCase()))];
-  if (distinct.length < 2) {
-    return {
-      id,
-      status: "pass",
-      detail:
-        resolved.length === 0
-          ? `no ${label} identities configured`
-          : `single ${label} identity across configured surfaces`,
-    };
-  }
-  return {
-    id,
-    status: "warn",
-    detail: `${label} identities disagree across configured surfaces: ${resolved
-      .map((entry) => `${entry.surface} reports "${entry.login}"`)
-      .join("; ")}. Operations may land under the wrong account.`,
-    fix:
-      provider === "github"
-        ? "Align the effective gh account and SSH identity via gh auth switch/login and your Git configuration"
-        : "Align the effective glab account and SSH identity via glab auth login and your Git configuration",
-  };
-};
-
-export const githubIdentityFinding = (surfaces: IdentitySurface[]): DoctorCheck =>
-  providerIdentityFinding("github", surfaces);
-
-export const gitlabIdentityFinding = (surfaces: IdentitySurface[]): DoctorCheck =>
-  providerIdentityFinding("gitlab", surfaces);
-
-const workspaceProviderForIdentity = (
-  cwd: string,
-  configDir: string,
-  env: NodeJS.ProcessEnv,
-): { provider?: unknown; error?: string } => {
-  try {
-    return {
-      provider: resolveWorkspaceFrom(
-        cwd,
-        configDir,
-        env.WORKFLOW_WORKSPACE_NAME?.trim() || undefined,
-      )?.vcs?.provider,
-    };
-  } catch (error) {
-    return { error: error instanceof Error ? error.message : String(error) };
-  }
-};
-
-const defaultIdentityProbes = (env: NodeJS.ProcessEnv): IdentityProbes => ({
-  origin: (cwd) => {
-    try {
-      const out = spawnSync("git", ["remote", "get-url", "origin"], {
-        cwd,
-        encoding: "utf8",
-        env,
-      });
-      return out.status === 0 ? (out.stdout ?? "").trim() || null : null;
-    } catch {
-      return null;
-    }
-  },
-  ghLogin: (e) => {
-    try {
-      const out = spawnSync("gh", ["api", "user", "--jq", ".login"], { encoding: "utf8", env: e });
-      const login = (out.stdout ?? "").trim();
-      return out.status === 0 && login ? login : null;
-    } catch {
-      return null;
-    }
-  },
-  glabLogin: (e) => {
-    try {
-      const out = spawnSync("glab", ["api", "user", "--jq", ".username"], {
-        encoding: "utf8",
-        env: e,
-      });
-      const login = (out.stdout ?? "").trim();
-      return out.status === 0 && login ? login : null;
-    } catch {
-      return null;
-    }
-  },
-  sshLogin: (host) => {
-    try {
-      const out = spawnSync(
-        "ssh",
-        ["-o", "BatchMode=yes", "-o", "ConnectTimeout=5", "-T", `git@${host}`],
-        {
-          encoding: "utf8",
-          env,
-        },
-      );
-      const text = `${out.stdout ?? ""}${out.stderr ?? ""}`;
-      const match = /^(?:Hi |Welcome to GitLab, @)([^!]+)!/m.exec(text);
-      return match ? match[1].trim() || null : null;
-    } catch {
-      return null;
-    }
-  },
-});
-
-export const checkGithubIdentity = (
-  res: Pick<Resolved, "cwd" | "configDir" | "env">,
-  probes: IdentityProbes = defaultIdentityProbes(res.env),
-): DoctorCheck => {
-  const remoteHost = githubHostFromRemote(probes.origin(res.cwd) ?? "");
-  if (!remoteHost)
-    return { id: "github_identity", status: "pass", detail: "no GitHub remote configured" };
-  const vcsJson = readJson(res.env.WORKFLOW_VCS_CONFIG ?? path.join(res.configDir, "vcs.json"));
-  const workspace = workspaceProviderForIdentity(res.cwd, res.configDir, res.env);
-  if (workspace.error)
-    return {
-      id: "github_identity",
-      status: "fail",
-      detail: workspace.error,
-      fix: "Repair workspace configuration or choose a matching workspace",
-    };
-  const provider = identityProvider(remoteHost, vcsJson, workspace.provider);
-  if (provider !== "github")
-    return { id: "github_identity", status: "pass", detail: "no GitHub remote configured" };
-  const cliHost = String(vcsJson?.github?.host ?? "github.com").toLowerCase();
-  const cliLogin = probes.ghLogin({ ...res.env, GH_HOST: cliHost });
-  if (!cliLogin)
-    return {
-      id: "github_identity",
-      status: "fail",
-      detail: "gh CLI is not authenticated",
-      fix: "Run gh auth login",
-    };
-  const surfaces: IdentitySurface[] = [{ surface: "gh CLI", login: cliLogin }];
-  surfaces.push({ surface: "SSH", login: probes.sshLogin(remoteHost) });
-  return githubIdentityFinding(surfaces);
-};
-
-export const checkGitLabIdentity = (
-  res: Pick<Resolved, "cwd" | "configDir" | "env">,
-  probes: IdentityProbes = defaultIdentityProbes(res.env),
-): DoctorCheck => {
-  const remoteHost = githubHostFromRemote(probes.origin(res.cwd) ?? "");
-  if (!remoteHost)
-    return { id: "gitlab_identity", status: "pass", detail: "no GitLab remote configured" };
-  const vcsJson = readJson(res.env.WORKFLOW_VCS_CONFIG ?? path.join(res.configDir, "vcs.json"));
-  const workspace = workspaceProviderForIdentity(res.cwd, res.configDir, res.env);
-  if (workspace.error)
-    return {
-      id: "gitlab_identity",
-      status: "fail",
-      detail: workspace.error,
-      fix: "Repair workspace configuration or choose a matching workspace",
-    };
-  const provider = identityProvider(remoteHost, vcsJson, workspace.provider);
-  if (provider !== "gitlab")
-    return { id: "gitlab_identity", status: "pass", detail: "no GitLab remote configured" };
-  const cliHost = String(vcsJson?.gitlab?.host ?? "gitlab.com").toLowerCase();
-  const cliLogin = probes.glabLogin?.({ ...res.env, GITLAB_HOST: cliHost }) ?? null;
-  if (!cliLogin)
-    return {
-      id: "gitlab_identity",
-      status: "fail",
-      detail: "glab CLI is not authenticated",
-      fix: "Run glab auth login",
-    };
-  return gitlabIdentityFinding([
-    { surface: "glab CLI", login: cliLogin },
-    { surface: "SSH", login: probes.sshLogin(remoteHost) },
-  ]);
-};
-
-const checkLogWritable = (res: Resolved): DoctorCheck => {
-  const logsDir = path.join(res.stateDir, "logs");
-  // Fixed-name probe: even a killed process leaves at most one bounded file that
-  // the next run overwrites; the finally removes it on any thrown path.
-  const probe = path.join(logsDir, "doctor-probe.tmp");
-  try {
-    mkdirSync(logsDir, { recursive: true, mode: 0o700 });
-    writeFileSync(probe, '{"probe":true}\n', { mode: 0o600 });
-    return {
-      id: "log_writable",
-      status: "pass",
-      detail: "log directory writable",
-    };
-  } catch (err) {
-    return {
-      id: "log_writable",
-      status: "fail",
-      detail: `log directory not writable: ${err instanceof Error ? err.message : String(err)}`,
-      fix: `Fix permissions on ${logsDir} or set WORKFLOW_TOOLKIT_STATE to a writable directory`,
-    };
-  } finally {
-    try {
-      unlinkSync(probe);
-    } catch {
-      /* already gone */
-    }
-  }
-};
-
-const GENERATION_HOSTS: CutoverHost[] = ["opencode", "cursor", "codex", "pi"];
-
-const generationPaths = (res: Resolved) => ({
-  home: res.home,
-  configDir: res.configDir,
-  stateDir: res.stateDir,
-  dev: res.dev,
-  workspace: res.cwd,
-  opencodeConfig: res.opencodeConfig,
-  cursorSettings: res.cursorSettings,
-  cursorMcp: res.cursorMcp,
-  cursorPluginDir: res.cursorPluginDir,
-  piConfig: path.join(res.home, ".pi", "config.json"),
-  piSettings: path.join(
-    res.env.PI_CODING_AGENT_DIR ?? path.join(res.home, ".pi", "agent"),
-    "settings.json",
-  ),
-  sessions: res.sessions,
-});
-
-const checkMixedGeneration = (res: Resolved): DoctorCheck => {
-  const paths = generationPaths(res);
-  const mixed = GENERATION_HOSTS.filter((host) => classifyHostGeneration(host, paths) === "mixed");
-  const target = readGenerationState(res.configDir).target;
-  if (mixed.length === 0) {
-    return {
-      id: "mixed_generation",
-      status: "pass",
-      detail: "no mixed legacy/v1 components detected",
-    };
-  }
-  const detail = `mixed legacy and v1 components: ${mixed.join(", ")}`;
-  if (target === "v1") {
-    return {
-      id: "mixed_generation",
-      status: "fail",
-      detail,
-      fix: "Run the approved v1 cutover preview/apply or remove the conflicting generation",
-    };
-  }
-  return {
-    id: "mixed_generation",
-    status: "warn",
-    detail: `${detail} (legacy target — cutover required before v1 activation)`,
-    fix: "Preview cutover with `workit init` or the CLI cutover flow before activating v1",
-  };
-};
-
-const checkLegacyComponent = (res: Resolved): DoctorCheck => {
-  const target = readGenerationState(res.configDir).target;
-  if (target !== "v1") {
-    return {
-      id: "legacy_component",
-      status: "pass",
-      detail: "legacy target — 0.x components expected",
-    };
-  }
-  const paths = generationPaths(res);
-  const legacy = GENERATION_HOSTS.filter(
-    (host) => classifyHostGeneration(host, paths) === "legacy",
-  );
-  if (legacy.length === 0) {
-    return {
-      id: "legacy_component",
-      status: "pass",
-      detail: "no legacy-only host components on v1 target",
-    };
-  }
-  return {
-    id: "legacy_component",
-    status: "fail",
-    detail: `legacy components remain on: ${legacy.join(", ")}`,
-    fix: "Complete the approved cutover or rollback to legacy before mixing generations",
-  };
-};
-
-const checkMissingV1Component = (res: Resolved): DoctorCheck => {
-  const target = readGenerationState(res.configDir).target;
-  if (target !== "v1") {
-    return { id: "missing_v1_component", status: "pass", detail: "legacy target" };
-  }
-  const paths = generationPaths(res);
-  const missing = GENERATION_HOSTS.filter((host) => {
-    const gen = classifyHostGeneration(host, paths);
-    return gen === "none" || gen === "legacy";
-  });
-  if (missing.length === 0) {
-    return {
-      id: "missing_v1_component",
-      status: "pass",
-      detail: "v1 components present on selected hosts",
-    };
-  }
-  return {
-    id: "missing_v1_component",
-    status: "fail",
-    detail: `missing v1 components on: ${missing.join(", ")}`,
-    fix: "Re-run the cutover apply step or the host install script for the missing target",
-  };
-};
-
-const checkActiveOldSession = (res: Resolved): DoctorCheck => {
-  if (res.sessions.length === 0) {
-    return {
-      id: "active_old_session",
-      status: "pass",
-      detail: "no session observations supplied to doctor",
-    };
-  }
-  const blocking = res.sessions.filter((s) => s.state === "active" || s.state === "unknown");
-  if (blocking.length === 0) {
-    return {
-      id: "active_old_session",
-      status: "pass",
-      detail: "no active or unknown old sessions observed",
-    };
-  }
-  const detail = blocking.map((s) => `${s.host}:${s.handle} (${s.state})`).join(", ");
-  const target = readGenerationState(res.configDir).target;
-  if (target === "v1") {
-    return {
-      id: "active_old_session",
-      status: "fail",
-      detail: `active or unknown sessions block v1 activation: ${detail}`,
-      fix: "Stop or account for old sessions before cutover apply",
-    };
-  }
-  return {
-    id: "active_old_session",
-    status: "warn",
-    detail: `old sessions still observed: ${detail}`,
-    fix: "Stop old sessions before previewing or applying v1 cutover",
-  };
-};
-
-const checkManagedContentConflict = (res: Resolved): DoctorCheck => {
-  const gen = readGenerationState(res.configDir);
-  if (!gen.cutover?.backupId) {
-    return {
-      id: "managed_content_conflict",
-      status: "pass",
-      detail: "no cutover receipt to compare",
-    };
-  }
-  const receipt = readCutoverReceipt(gen.cutover.backupId, res.stateDir);
-  if (!receipt) {
-    return {
-      id: "managed_content_conflict",
-      status: "fail",
-      detail: `cutover receipt missing for backup ${gen.cutover.backupId}`,
-      fix: "Re-run cutover apply or rollback to a known state",
-    };
-  }
-  const conflicts = receipt.managedFiles.filter((entry) => {
-    const current = digestFile(entry.path);
-    return current !== null && current !== entry.installedDigest;
-  });
-  if (conflicts.length === 0) {
-    return {
-      id: "managed_content_conflict",
-      status: "pass",
-      detail: "managed content matches cutover receipt",
-    };
-  }
-  return {
-    id: "managed_content_conflict",
-    status: "fail",
-    detail: `managed content drifted since cutover on: ${conflicts.map((c) => c.path).join(", ")}`,
-    fix: "Reconcile managed files with the cutover receipt or roll back before re-applying",
-  };
-};
-
-// The checkout's `.workit/metadata.lock`. Writes reclaim a stale lock by
-// themselves, so a stale lock is a warning with an explicit cleanup command.
-const BLOCKING_LOCK_WARN_MS = 30_000;
-const checkWorkspaceLock = (res: Resolved): DoctorCheck => {
-  const lock = inspectMetadataLock(res.workspaceRoot);
-  const fix = "workit doctor --fix-lock";
-  if (lock.guard === "abandoned")
-    return {
-      id: "workspace_lock",
-      status: "warn",
-      detail: `abandoned lock reclaim guard at ${lock.path}.reclaim`,
-      fix,
-    };
-  if (lock.state === "absent")
-    return { id: "workspace_lock", status: "pass", detail: "no metadata lock held" };
-  if (lock.state === "stale")
-    return {
-      id: "workspace_lock",
-      status: "warn",
-      detail: `stale metadata lock at ${lock.path}: ${lock.reason}`,
-      fix,
-    };
-  // An unverifiable owner (other host, pid namespace, or an older Workit's
-  // lock) that has blocked writes this long needs an explicit decision.
-  if (lock.state === "unknown" && (lock.ageMs ?? 0) > BLOCKING_LOCK_WARN_MS)
-    return {
-      id: "workspace_lock",
-      status: "warn",
-      detail: `metadata lock at ${lock.path} has blocked writes for ${Math.round((lock.ageMs ?? 0) / 1000)}s and its owner cannot be verified: ${lock.reason}`,
-      fix: "workit doctor --fix-lock --force --yes",
-    };
-  return {
-    id: "workspace_lock",
-    status: "pass",
-    detail: `metadata lock ${lock.reason} (writes retry, then report busy)`,
-  };
-};
-
-const CLAUDE_PLUGIN_PACKAGE = "@brainervirus/workit-claude-code";
-
-const versionBehind = (version: string, latest: string): boolean =>
-  version !== latest && semverAtLeast(latest, version);
-
-/**
- * Claude Code installs the marketplace plugin as a snapshot of the published
- * package (auto-update is off by default), so an install can lag the release.
- * It warns only when a newer plugin version is actually published: a plugin
- * older than this CLI is normal when no plugin payload changed since (the
- * plugin is republished only when its own or its bundled sources change).
- * The plugin keeps working; the fix is one native update. A `--plugin-dir`
- * local pin is per-session, never recorded, and never checked here.
- */
-const checkClaudePlugin = (res: Resolved): DoctorCheck & { registryProbed?: boolean } => {
-  // Only installs Claude loads here: user scope, plus this project's.
-  const installs = claudeWorkitInstalls(res.home, res.env, res.cwd);
-  if (installs.length === 0)
-    return {
-      id: "claude_plugin",
-      status: "pass",
-      detail: "no Workit Claude Code plugin install recorded — skipping",
-    };
-  const fix = (install: ClaudeWorkitInstall) =>
-    `claude plugin marketplace update ${CLAUDE_MARKETPLACE_NAME} && ${
-      install.projectPath ? `cd ${JSON.stringify(install.projectPath)} && ` : ""
-    }claude plugin update ${install.id}${install.scope === "user" ? "" : ` --scope ${install.scope}`}`;
-  const latest = registryLatestVersion(res, CLAUDE_PLUGIN_PACKAGE);
-  const problems: string[] = [];
-  let repair: string | undefined;
-  for (const install of installs) {
-    const label = `${install.id} ${install.version ?? "(unknown version)"}${install.scope === "user" ? "" : ` (${install.scope} scope)`}`;
-    if (latest && install.version && versionBehind(install.version, latest)) {
-      problems.push(`stale_install: ${label} is behind published ${latest}`);
-      repair ??= fix(install);
-    }
-  }
-  const registryProbed = latest !== null && !res.env.WORKIT_DOCTOR_STALE_REGISTRY_VERSION;
-  if (problems.length === 0)
-    return {
-      id: "claude_plugin",
-      status: "pass",
-      detail: `Claude Code plugin ${installs.map((i) => `${i.id} ${i.version ?? "?"}`).join(", ")} is current`,
-      registryProbed,
-    };
-  return {
-    id: "claude_plugin",
-    status: "warn",
-    detail: problems.join("; "),
-    fix: repair,
-    registryProbed,
-  };
-};
-
-const RUN_CHECKS: Array<(res: Resolved) => DoctorCheck> = [
-  checkRuntime,
-  checkVersions,
-  checkCodexPin,
-  checkClaudePlugin,
-  checkAssets,
-  checkLauncher,
-  checkUtility,
-  checkStalePin,
-  checkStaleInstall,
-  checkDuplicateRegistration,
-  checkMalformedConfig,
-  checkWorkspaceMismatch,
-  checkWorkspaceLock,
-  checkCredentialMetadata,
-  checkGithubIdentity,
-  checkGitLabIdentity,
-  checkLogWritable,
-  checkMixedGeneration,
-  checkLegacyComponent,
-  checkMissingV1Component,
-  checkActiveOldSession,
-  checkManagedContentConflict,
-];
-
-// AR-11/CA-40: the installer guarantees the selected host itself — runtime,
-// assets, launchers, registration, and required utilities — plus the config it
-// just wrote. Those defects stay failures with nonzero status; only optional
-// parity checks (versions/workspace/credentials/log) may downgrade to warnings.
-const INSTALLER_REQUIRED = new Set<DoctorCheckId>([
-  "runtime",
-  "assets",
-  "launcher",
-  "utility",
-  "stale_pin",
-  "stale_install",
-  "duplicate_registration",
-  "malformed_config",
-]);
-
-export const runDoctor = (options: DoctorOptions = {}): DoctorReport => {
-  const res = resolve(options);
-  const raw = RUN_CHECKS.map((fn) => fn(res));
-  const checks = res.installer
-    ? raw.map((c) =>
-        c.status === "fail" && !INSTALLER_REQUIRED.has(c.id)
-          ? {
-              ...c,
-              status: "warn" as const,
-              detail: `${c.detail} (not enforced by installer)`,
-            }
-          : c,
-      )
-    : raw;
-
-  const failed = checks.filter((c) => c.status === "fail").length;
-  const warned = checks.filter((c) => c.status === "warn").length;
-  const passed = checks.filter((c) => c.status === "pass").length;
-  const exitCode = failed > 0 ? 1 : 0;
-  const offline = !raw.some((c) => "registryProbed" in c && c.registryProbed);
-  const report: DoctorReport = {
-    ok: failed === 0,
-    exitCode,
-    offline,
-    host: res.host,
-    checked_at: new Date().toISOString(),
-    summary: { passed, warned, failed, total: checks.length },
-    checks,
-    fixes: checks
-      .filter((c) => c.status === "fail" && c.fix)
-      .map((c) => ({ id: c.id, fix: c.fix! })),
-  };
-
-  getDiagnosticLogger()?.info(EVENT.doctor, {
-    host: res.host,
-    exit_code: exitCode,
-    offline,
-    failed: checks.filter((c) => c.status === "fail").map((c) => c.id),
-    total: checks.length,
-  });
-
-  return report;
-};