@dadado/agent-kit-cli 5.15.1 → 5.17.0

package/dist/chunk-F4VMYR7U.js

@@ -0,0 +1,318 @@
+import {
+  assessEnvironment
+} from "./chunk-4IWG5CVE.js";
+import {
+  compareSemver,
+  normalizeSemver
+} from "./chunk-SMGFN3Z4.js";
+import {
+  MANIFEST_RELATIVE_PATH
+} from "./chunk-AW74INUW.js";
+import {
+  KIT_VERSION,
+  pinnedCliSpec
+} from "./chunk-7HDQEK6T.js";
+import {
+  fileExists
+} from "./chunk-77V75A7O.js";
+
+// src/utils/terminal.ts
+import { readdir } from "fs/promises";
+import { homedir } from "os";
+import path from "path";
+import { confirm, isCancel } from "@clack/prompts";
+function isNonInteractive() {
+  if (process.env.CI === "true" || process.env.CI === "1") return true;
+  if (process.env.AGENT_KIT_YES === "1") return true;
+  return !process.stdin.isTTY;
+}
+var NESTED_REPO_AMBIGUITY_THRESHOLD = 2;
+var NESTED_REPO_SCAN_LIMIT = 200;
+async function findNestedRepoChildren(resolved) {
+  let entries;
+  try {
+    entries = await readdir(resolved, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const nested = [];
+  let scanned = 0;
+  for (const entry of entries) {
+    if (nested.length >= NESTED_REPO_AMBIGUITY_THRESHOLD) break;
+    if (scanned >= NESTED_REPO_SCAN_LIMIT) break;
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    scanned += 1;
+    if (await fileExists(path.join(resolved, entry.name, ".git"))) {
+      nested.push(entry.name);
+    }
+  }
+  return nested;
+}
+async function validateProjectRoot(resolved) {
+  const home = path.resolve(homedir());
+  if (resolved === "/" || resolved === home) {
+    return {
+      ok: false,
+      reason: `Refused to use ${resolved} as a project root.`,
+      recovery: "Change into a project directory and re-run. Agent Kit installs per project."
+    };
+  }
+  const hasGit = await fileExists(path.join(resolved, ".git"));
+  const hasManifest = await fileExists(path.join(resolved, MANIFEST_RELATIVE_PATH));
+  if (!hasGit && !hasManifest) {
+    return {
+      ok: false,
+      reason: `Refused ${resolved}: no .git and no ${MANIFEST_RELATIVE_PATH}.`,
+      recovery: [
+        "Starting from an empty folder? Pick one of these:",
+        "  1. git init          - then re-run. Recommended: readiness and the",
+        "                         staging -> prod flow both want Git.",
+        "  2. --force-root      - install without Git. /agent-kit-onboard will",
+        "                         still offer to initialize it later.",
+        "  3. Answer yes to the 'Proceed anyway?' prompt in an interactive terminal.",
+        "Or re-run from the project directory you actually meant."
+      ].join("\n")
+    };
+  }
+  if (hasGit && !hasManifest) {
+    const nested = await findNestedRepoChildren(resolved);
+    if (nested.length >= NESTED_REPO_AMBIGUITY_THRESHOLD) {
+      return {
+        ok: false,
+        reason: `Refused ${resolved}: it has .git but also contains child repositories (${nested.join(", ")}). This looks like a parent-of-repos folder, not a project root.`,
+        recovery: [
+          "L0 belongs in one project, not in the folder that holds several.",
+          "  1. cd into the project you meant, then re-run.",
+          "  2. --force-root - only if this parent folder really is the project root."
+        ].join("\n")
+      };
+    }
+  }
+  return { ok: true };
+}
+async function confirmProjectRoot(cwd, opts) {
+  const resolved = path.resolve(cwd);
+  if (opts.forceRoot) {
+    return resolved;
+  }
+  const validation = await validateProjectRoot(resolved);
+  if (!validation.ok) {
+    if (opts.nonInteractive) {
+      throw new RootRefusedError(resolved, validation.reason, validation.recovery);
+    }
+    const ok2 = await confirm({
+      message: `${validation.reason} Proceed anyway?`,
+      initialValue: false
+    });
+    if (isCancel(ok2) || !ok2) {
+      throw new RootRefusedError(resolved, validation.reason, validation.recovery);
+    }
+    return resolved;
+  }
+  if (opts.nonInteractive) {
+    return resolved;
+  }
+  const ok = await confirm({
+    message: `${opts.command === "install" ? "Install" : "Update"} Agent Kit in: ${resolved}`,
+    initialValue: true
+  });
+  if (isCancel(ok) || !ok) {
+    throw new RootRefusedError(resolved);
+  }
+  return resolved;
+}
+var RootRefusedError = class extends Error {
+  constructor(root, reason, recovery) {
+    super(reason ?? `Refused to write into ${root}. Re-run from the correct project directory.`);
+    this.root = root;
+    this.recovery = recovery;
+    this.name = "RootRefusedError";
+  }
+  root;
+  recovery;
+};
+var NPM_GLOBAL_PREFIX_PATH_RE = /\/lib\/node_modules|Program Files\\nodejs\\node_modules/;
+var NPM_GLOBAL_NODE_MODULES_RE = /node_modules/;
+function isNpmGlobalPrefixError(msg, code) {
+  const isPermissionError = code === "EPERM" || code === "EACCES" || /EPERM|EACCES/.test(msg);
+  if (!isPermissionError) return false;
+  return NPM_GLOBAL_PREFIX_PATH_RE.test(msg) || NPM_GLOBAL_NODE_MODULES_RE.test(msg);
+}
+function classifyInstallError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  const code = err?.code;
+  if (isNpmGlobalPrefixError(msg, code)) {
+    return {
+      kind: "npm-global-eacces",
+      message: `Permission error (root-owned npm prefix): ${msg}`,
+      recovery: [
+        "npm's global install prefix (e.g. /usr/local/lib/node_modules) is owned by root, so global installs fail.",
+        "Recovery options:",
+        "  1. Run: npx @dadado/agent-kit-cli@latest setup-global (relocates npm's prefix to a folder you own, fixes PATH, reinstalls)",
+        '  2. Manual fix: mkdir -p ~/.npm-global && npm config set prefix "~/.npm-global" && export PATH="~/.npm-global/bin:$PATH" (add to your shell profile) && npm i -g @dadado/agent-kit-cli@latest',
+        "  3. Use Port B fallback: drag install.md into the Cursor chat"
+      ].join("\n")
+    };
+  }
+  if (code === "EPERM" || code === "EACCES" || /EPERM|EACCES/.test(msg)) {
+    return {
+      kind: "eperm",
+      message: `Permission error: ${msg}`,
+      recovery: [
+        "The npm cache may have ownership drift (root-written files in a user dir).",
+        "Recovery options:",
+        "  1. npx --cache .npm-cache @dadado/agent-kit-cli@latest install",
+        "  2. npm cache clean --force && npx @dadado/agent-kit-cli@latest install",
+        "  3. Use Port B fallback: drag install.md into the Cursor chat"
+      ].join("\n")
+    };
+  }
+  if (/403|Forbidden|unauthorized|E401|ENEEDAUTH/.test(msg)) {
+    return {
+      kind: "registry-auth",
+      message: `Registry access denied: ${msg}`,
+      recovery: [
+        "The npm registry returned 403/401 for the scoped package.",
+        "Recovery options:",
+        "  1. Check npm auth: npm whoami (login if needed: npm login)",
+        "  2. If using a private registry, verify .npmrc scope config",
+        "  3. Use Port B fallback: drag install.md into the Cursor chat"
+      ].join("\n")
+    };
+  }
+  if (/ENOTFOUND|ETIMEDOUT|ECONNREFUSED|ECONNRESET|EAI_AGAIN|fetch failed/.test(msg) || code === "ENOTFOUND" || code === "ETIMEDOUT") {
+    return {
+      kind: "network",
+      message: `Network error: ${msg}`,
+      recovery: [
+        "Could not reach the registry or git remote.",
+        "Recovery options:",
+        "  1. Check network/proxy/VPN settings",
+        "  2. Retry: npx @dadado/agent-kit-cli@latest install",
+        "  3. Use --registry <local-path> if you have a local checkout"
+      ].join("\n")
+    };
+  }
+  return {
+    kind: "unknown",
+    message: msg,
+    recovery: "Unexpected error. Check the message above and retry, or use Port B fallback."
+  };
+}
+
+// src/lifecycle/path-cli.ts
+import { spawn } from "child_process";
+import path2 from "path";
+function npxPinned(runtimeVersion, subcommand) {
+  return `npx -y ${pinnedCliSpec(runtimeVersion)} ${subcommand}`;
+}
+function isBinUnderPrefix(binPath, prefix) {
+  const bin = path2.resolve(binPath);
+  const root = path2.resolve(prefix);
+  return bin === root || bin.startsWith(`${root}${path2.sep}`);
+}
+function pathCliStatus(env, runtimeVersion) {
+  if (!env.binOnPath || !env.binPath) return "missing";
+  const running = normalizeSemver(runtimeVersion);
+  const pathVer = env.binVersion ? normalizeSemver(env.binVersion) : null;
+  if (!pathVer || !running) return "unknown";
+  try {
+    return compareSemver(pathVer, running) >= 0 ? "current" : "behind";
+  } catch {
+    return "unknown";
+  }
+}
+function driftLines(env, runtimeVersion) {
+  const pathVer = env.binVersion ?? "unknown";
+  const where = env.binPath ?? "(unresolved)";
+  return [
+    `This CLI is v${runtimeVersion}. PATH \`agent-kit\` is v${pathVer} at:`,
+    `  ${where}`,
+    "Do not run bare `agent-kit update` or `init` from that binary. It re-stamps the old version.",
+    "Keep using the pinned npx form until PATH matches:",
+    `  ${npxPinned(runtimeVersion, "update")}`,
+    `  ${npxPinned(runtimeVersion, "status")}`
+  ];
+}
+function isShadow(env) {
+  if (!env.binPath || !env.npmPrefix.prefix) return false;
+  return !isBinUnderPrefix(env.binPath, env.npmPrefix.prefix);
+}
+async function spawnNpmGlobalInstall(spec) {
+  return new Promise((resolve) => {
+    const child = spawn("npm", ["i", "-g", spec], { stdio: "inherit" });
+    child.on("error", (error) => resolve({ ok: false, error }));
+    child.on("close", (code) => {
+      if (code === 0) resolve({ ok: true });
+      else resolve({ ok: false, error: new Error(`npm exited with code ${code ?? "unknown"}`) });
+    });
+  });
+}
+async function syncPathCliToRuntime(options = {}) {
+  const runtimeVersion = options.runtimeVersion ?? KIT_VERSION;
+  const assess = options.assessEnvironmentImpl ?? assessEnvironment;
+  let env = options.env ?? await assess();
+  const autoInstall = options.autoInstall ?? !isNonInteractive();
+  const lines = [];
+  let status = pathCliStatus(env, runtimeVersion);
+  if (status === "current") {
+    return { status, env, upgraded: false, lines };
+  }
+  if (status === "behind" || status === "unknown") {
+    lines.push(...driftLines(env, runtimeVersion));
+    if (isShadow(env)) {
+      lines.push(
+        "That PATH hit is not npm's global bin, so `npm i -g` may not replace it.",
+        "Run `hash -r` and `which -a agent-kit`. Put npm's global bin first, or remove the stale shim."
+      );
+    }
+  }
+  if (!autoInstall) {
+    return { status, env, upgraded: false, lines };
+  }
+  if (status === "missing") {
+    lines.push("No bare `agent-kit` on PATH yet (npx is ephemeral).");
+  }
+  if (!env.npmPrefixWritable) {
+    lines.push(
+      "npm's global prefix is not writable, so this process cannot upgrade PATH.",
+      `Run ${npxPinned(runtimeVersion, "setup-global")} (or fix prefix permissions).`
+    );
+    return { status, env, upgraded: false, lines };
+  }
+  const spec = pinnedCliSpec(runtimeVersion);
+  const install = options.npmInstallImpl ?? spawnNpmGlobalInstall;
+  lines.push(`Installing ${spec} into the writable npm prefix...`);
+  const outcome = await install(spec);
+  if (!outcome.ok) {
+    const detail = outcome.error instanceof Error ? outcome.error.message : "npm i -g failed";
+    lines.push(`Global install failed: ${detail}`);
+    return { status, env, upgraded: false, lines };
+  }
+  env = await assess();
+  status = pathCliStatus(env, runtimeVersion);
+  if (status === "current") {
+    lines.push(
+      `PATH \`agent-kit\` is now v${env.binVersion ?? runtimeVersion}.`,
+      "If this shell still shows the old version, run `hash -r` or open a new terminal."
+    );
+    return { status, env, upgraded: true, lines };
+  }
+  lines.push(
+    `Installed ${spec}, but PATH still resolves to v${env.binVersion ?? "unknown"} at:`,
+    `  ${env.binPath ?? "(unresolved)"}`,
+    "Run `hash -r` and `which -a agent-kit`. Until PATH matches, keep using the npx pin above."
+  );
+  return { status, env, upgraded: true, lines };
+}
+
+export {
+  isNonInteractive,
+  confirmProjectRoot,
+  RootRefusedError,
+  classifyInstallError,
+  npxPinned,
+  pathCliStatus,
+  syncPathCliToRuntime
+};

package/dist/chunk-F6C3GFKV.js

@@ -0,0 +1,57 @@
+// src/types.ts
+var GIT_PLATFORM_META = {
+  github: {
+    cli: "gh",
+    prTerm: "Pull Request",
+    prCommand: "gh pr create",
+    ciDefault: "github-actions"
+  },
+  gitlab: {
+    cli: "glab",
+    prTerm: "Merge Request",
+    prCommand: "glab mr create",
+    ciDefault: "gitlab-ci"
+  },
+  bitbucket: {
+    cli: "bb",
+    prTerm: "Pull Request",
+    prCommand: "bb pr create",
+    ciDefault: "bitbucket-pipelines"
+  },
+  "azure-devops": {
+    cli: "az repos",
+    prTerm: "Pull Request",
+    prCommand: "az repos pr create",
+    ciDefault: "azure-pipelines"
+  },
+  gitea: { cli: "tea", prTerm: "Pull Request", prCommand: "tea pr create", ciDefault: "none" }
+};
+var CI_PLATFORM_FILES = {
+  "github-actions": ".github/workflows",
+  "gitlab-ci": ".gitlab-ci.yml",
+  "azure-pipelines": "azure-pipelines.yml",
+  "bitbucket-pipelines": "bitbucket-pipelines.yml",
+  jenkins: "Jenkinsfile",
+  circleci: ".circleci/config.yml",
+  travis: ".travis.yml"
+};
+var PM_TOOL_LABELS = {
+  clickup: "ClickUp",
+  jira: "Jira",
+  linear: "Linear",
+  asana: "Asana",
+  "github-issues": "GitHub Issues",
+  "github-projects": "GitHub Projects",
+  "azure-boards": "Azure Boards",
+  trello: "Trello",
+  shortcut: "Shortcut",
+  notion: "Notion",
+  youtrack: "YouTrack",
+  none: "None"
+};
+
+export {
+  GIT_PLATFORM_META,
+  CI_PLATFORM_FILES,
+  PM_TOOL_LABELS
+};

package/dist/chunk-HFUH3HVS.js

@@ -0,0 +1,282 @@
+import {
+  logger
+} from "./chunk-ZB43YMHW.js";
+
+// src/commands/dashboard.ts
+import { execFileSync, spawn as spawn2 } from "child_process";
+import { existsSync, readFileSync as readFileSync2, realpathSync } from "fs";
+import { access } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+import { defineCommand } from "citty";
+
+// ../../dashboard/lib/guards.mjs
+import { randomBytes, timingSafeEqual } from "crypto";
+import { networkInterfaces } from "os";
+import { resolve } from "path";
+var REPO_ROOT_ENV = "MISSION_CONTROL_REPO_ROOT";
+var KIT_ROOT_ENV_KEYS = Object.freeze(["MISSION_CONTROL_KIT_ROOT", "AGENT_KIT_HOME"]);
+var CONTEXT_CONFIG_REL = ".cursor/context/config.json";
+var CONFIG_PERSONA_IDS = Object.freeze(["autopilot", "night-shift", "ghost-runner"]);
+var CONFIG_PERSONA_MODES = Object.freeze(["continue-plan", "run-plan", "cli-run-plan"]);
+var CONFIG_REVIEW_BACKENDS = Object.freeze(["auto", "claude", "cursor"]);
+var CONFIG_REVIEW_MODES = Object.freeze(["paste", "autonomous"]);
+var CONFIG_REVIEW_PREFLIGHT = Object.freeze(["off", "warn", "block"]);
+function resolveContextConfigPath(repoRoot, fsHooks = {}) {
+  const exists = fsHooks.existsSync;
+  const realpath = fsHooks.realpathSync;
+  const mkdir = fsHooks.mkdirSync;
+  if (typeof repoRoot !== "string" || !repoRoot) {
+    return { ok: false, error: "invalid repo root" };
+  }
+  const abs = resolve(repoRoot, CONTEXT_CONFIG_REL);
+  const contextDir = resolve(repoRoot, ".cursor", "context");
+  const absNorm = abs.replace(/\\/g, "/");
+  if (!absNorm.endsWith("/.cursor/context/config.json")) {
+    return { ok: false, error: "path escape" };
+  }
+  try {
+    if (typeof mkdir === "function" && typeof exists === "function" && !exists(contextDir)) {
+      mkdir(contextDir, { recursive: true });
+    }
+    if (typeof realpath === "function" && typeof exists === "function" && exists(abs)) {
+      const fileReal = String(realpath(abs)).replace(/\\/g, "/");
+      const rootReal = String(realpath(repoRoot)).replace(/\\/g, "/");
+      if (!fileReal.startsWith(`${rootReal}/`)) {
+        return { ok: false, error: "path escape" };
+      }
+      if (!fileReal.endsWith("/.cursor/context/config.json")) {
+        return { ok: false, error: "path escape" };
+      }
+      return { ok: true, path: realpath(abs) };
+    }
+  } catch {
+    return { ok: false, error: "path escape" };
+  }
+  return { ok: true, path: abs };
+}
+
+// ../../dashboard/lib/open-browser.mjs
+import { spawn, spawnSync } from "child_process";
+import { readFileSync } from "fs";
+import { platform as osPlatform } from "os";
+var OS_DEFAULT_TOKENS = /* @__PURE__ */ new Set(["", "default", "os", "ask"]);
+function isSafePreferredBrowser(value) {
+  if (typeof value !== "string") return false;
+  const s = value.trim();
+  if (!s) return false;
+  if (/[/\\]/.test(s)) return false;
+  if (/[\0-\x1f\x7f]/.test(s)) return false;
+  if (/[$`;&|<>(){}[\]!*?#~"'%^=,+]/.test(s)) return false;
+  if (s.includes(":")) return false;
+  if (/^-/.test(s)) return false;
+  return true;
+}
+function normalizePreferredBrowser(value) {
+  if (value == null) return null;
+  const s = String(value).trim();
+  if (!s || OS_DEFAULT_TOKENS.has(s.toLowerCase())) return null;
+  if (!isSafePreferredBrowser(s)) return null;
+  return s;
+}
+function readPreferredBrowserFromConfig(configPath, fsHooks = {}) {
+  const read = fsHooks.readFileSync ?? readFileSync;
+  try {
+    const raw = read(configPath, "utf8");
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+    const mc = data.missionControl;
+    if (!mc || typeof mc !== "object" || Array.isArray(mc)) return null;
+    return mc.preferredBrowser ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// src/commands/dashboard.ts
+function readPreferredBrowserFromWorkspace(cwd, readFile = readFileSync2) {
+  const resolved = resolveContextConfigPath(path.resolve(cwd), {
+    existsSync,
+    realpathSync
+  });
+  if (!resolved.ok) return null;
+  const value = readPreferredBrowserFromConfig(resolved.path, { readFileSync: readFile });
+  return normalizePreferredBrowser(value);
+}
+function applyDashboardOpenEnv(env, opts) {
+  const next = { ...env };
+  if (opts.noOpen) next.MISSION_CONTROL_NO_OPEN = "1";
+  const flag = opts.browser?.trim();
+  if (flag) {
+    const safe = normalizePreferredBrowser(flag);
+    if (safe) next.MISSION_CONTROL_PREFERRED_BROWSER = safe;
+  } else if (!next.MISSION_CONTROL_PREFERRED_BROWSER && opts.cwd) {
+    const fromConfig = readPreferredBrowserFromWorkspace(opts.cwd);
+    if (fromConfig) next.MISSION_CONTROL_PREFERRED_BROWSER = fromConfig;
+  }
+  return next;
+}
+function dashboardSpawnEnv(env, snapshotRoot, opts) {
+  const root = path.resolve(snapshotRoot);
+  return applyDashboardOpenEnv({ ...env, MISSION_CONTROL_REPO_ROOT: root }, { ...opts, cwd: root });
+}
+function dashboardProcessTitle(snapshotRoot) {
+  const base = path.basename(path.resolve(snapshotRoot)) || "workspace";
+  return `Mission Control \xB7 ${base}`;
+}
+function bundledDashboardCandidates(filename, moduleUrl = import.meta.url) {
+  const here = path.dirname(fileURLToPath(moduleUrl));
+  return [
+    // Published / built: <pkg>/dist/index.js -> <pkg>/dashboard/
+    path.join(here, "..", "dashboard", filename),
+    // Dev source: packages/cli/src/commands/*.ts -> packages/cli/dashboard/ (sync copy)
+    path.join(here, "..", "..", "dashboard", filename),
+    // From src/commands: packages/dashboard/ (unused layout); from dist: two levels above package
+    path.join(here, "..", "..", "..", "dashboard", filename)
+  ];
+}
+async function firstExisting(candidates) {
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return path.resolve(candidate);
+    } catch {
+    }
+  }
+  return null;
+}
+async function findDashboardStart(cwd, env = process.env, options = {}) {
+  let dir = path.resolve(cwd);
+  for (; ; ) {
+    const candidate = path.join(dir, "dashboard", "start.mjs");
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  for (const key of ["MISSION_CONTROL_KIT_ROOT", "AGENT_KIT_HOME"]) {
+    const base = env[key];
+    if (!base || typeof base !== "string" || !base.trim()) continue;
+    const candidate = path.join(path.resolve(base.trim()), "dashboard", "start.mjs");
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  const sibling = path.join(path.resolve(cwd), "..", "agent-kit", "dashboard", "start.mjs");
+  try {
+    await access(sibling);
+    return path.resolve(sibling);
+  } catch {
+  }
+  return firstExisting(
+    bundledDashboardCandidates("start.mjs", options.moduleUrl ?? import.meta.url)
+  );
+}
+function resolveDashboardSnapshotRoot(cwd) {
+  const abs = path.resolve(cwd);
+  let dir = abs;
+  for (; ; ) {
+    if (existsSync(path.join(dir, ".cursor", "agent-kit.json"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  try {
+    const top = execFileSync("git", ["-C", abs, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (top) return path.resolve(top);
+  } catch {
+  }
+  return abs;
+}
+function runStartScript(startPath, env) {
+  return new Promise((resolve2, reject) => {
+    const child = spawn2(process.execPath, [startPath], {
+      cwd: path.dirname(path.dirname(startPath)),
+      env,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve2(code ?? 1));
+  });
+}
+var dashboardCommand = defineCommand({
+  meta: {
+    name: "dashboard",
+    description: "Start Mission Control for this workspace (loopback; opens panel URL)."
+  },
+  args: {
+    cwd: {
+      type: "string",
+      default: process.cwd(),
+      description: "Workspace to snapshot (nearest .cursor/agent-kit.json, else git root); also searched upward for dashboard/start.mjs"
+    },
+    "no-open": {
+      type: "boolean",
+      default: false,
+      description: "Do not open a browser; only ensure the server is up and print the URL"
+    },
+    browser: {
+      type: "string",
+      description: "Preferred browser app/binary for this launch (overrides config missionControl.preferredBrowser)"
+    }
+  },
+  async run({ args }) {
+    const snapshotRoot = resolveDashboardSnapshotRoot(args.cwd);
+    const startPath = await findDashboardStart(args.cwd);
+    if (!startPath) {
+      logger.error("No dashboard/start.mjs found.");
+      console.error(
+        [
+          "",
+          "The dashboard runtime is not available in this workspace.",
+          "L0 install provides the /dashboard command text but not the panel itself.",
+          "",
+          "Recovery (pick one):",
+          "  1. Upgrade the CLI: npx @dadado/agent-kit-cli@latest dashboard",
+          "     (Path C ships dashboard/ from 4.8.2 onward)",
+          "  2. Set an env var pointing to an agent-kit checkout:",
+          "     export MISSION_CONTROL_KIT_ROOT=/path/to/agent-kit",
+          "     agent-kit dashboard",
+          "  3. Place an agent-kit sibling: ../agent-kit/dashboard/start.mjs",
+          "  4. Run directly from a kit tree: node dashboard/start.mjs",
+          "",
+          "Works in Cursor, VS Code, and any Node.js terminal.",
+          ""
+        ].join("\n")
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const env = dashboardSpawnEnv({ ...process.env }, snapshotRoot, {
+      noOpen: Boolean(args["no-open"]),
+      browser: args.browser
+    });
+    process.title = dashboardProcessTitle(snapshotRoot);
+    const code = await runStartScript(startPath, env);
+    if (code !== 0) process.exitCode = code;
+  }
+});
+
+export {
+  REPO_ROOT_ENV,
+  readPreferredBrowserFromWorkspace,
+  applyDashboardOpenEnv,
+  dashboardSpawnEnv,
+  dashboardProcessTitle,
+  bundledDashboardCandidates,
+  findDashboardStart,
+  resolveDashboardSnapshotRoot,
+  dashboardCommand
+};