@anhlp/alp-client 0.0.0-stage → 0.10.0

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @anhlp/alp-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local IPC client, daemon discovery, supervision, services and setup helpers.
+
+`startIntegration` discovers an optional integration's descriptor and starts it detached with `--service`, so the entry writes its own log; discovery and the selected `ALP_HOME` are pinned by tests. Restarting is non-destructive: a daemon left running by an older install is reported as older than the current CLI and is never killed in place.
+
+Build: `npm run build --workspace=@anhlp/alp-client`. Test: `npm run test --workspace=@anhlp/alp-client`.
+
+Public imports use the package root and its explicitly exported subpaths. See [architecture, provider extension, compatibility and release instructions](../../docs/modular-monorepo.md).

package/dist/acp-probe.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Starts an ACP provider once and runs initialize (ALPD §46), for `alp provider test`
+ * and the settings screen. It reports who the agent says it is and what it supports;
+ * a provider that needs a login usually says so here, in authMethods. With `discover`,
+ * it also opens a session in `cwd`, as Paseo does, to read the models and modes the agent
+ * offers (ALPD §65); an agent that offers none leaves them out.
+ * @param {{ command: string, args?: string[], env?: Record<string, string>, label?: string, id?: string }} provider
+ * @param {{ cwd?: string, timeoutMs?: number, discover?: boolean }} [options]
+ * @returns {Promise<{ protocolVersion: number, agent?: { name?: string, title?: string, version?: string }, loadSession: boolean, mcpHttp: boolean, authMethods: string[],
+ *   models?: Array<{ id: string, label: string, description?: string }>, currentModel?: string, modes?: Array<{ id: string, label: string, description?: string }>, currentMode?: string }>}
+ */
+export function probeAcp(provider: {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    label?: string;
+    id?: string;
+}, { cwd, timeoutMs, discover }?: {
+    cwd?: string;
+    timeoutMs?: number;
+    discover?: boolean;
+}): Promise<{
+    protocolVersion: number;
+    agent?: {
+        name?: string;
+        title?: string;
+        version?: string;
+    };
+    loadSession: boolean;
+    mcpHttp: boolean;
+    authMethods: string[];
+    models?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    currentModel?: string;
+    modes?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    currentMode?: string;
+}>;

package/dist/acp-probe.js

@@ -0,0 +1,37 @@
+// packages/client/src/acp-probe.js
+import { stdioSession } from "./mcp-probe.js";
+async function probeAcp(provider, { cwd, timeoutMs = 2e4, discover = false } = {}) {
+  const session = stdioSession({ command: provider.command, args: provider.args ?? [], env: provider.env ?? {} }, cwd, timeoutMs);
+  try {
+    const result = await session.request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo: { name: "alp", title: "ALP", version: "1" }
+    });
+    if (result.protocolVersion !== 1) throw new Error(`${provider.label ?? provider.id} speaks ACP version ${result.protocolVersion}; ALP speaks version 1`);
+    const info = result.agentInfo;
+    const offered = discover ? await session.request("session/new", { cwd, mcpServers: [] }) : void 0;
+    const choices = (list) => Array.isArray(list) ? list.filter((item) => typeof (item?.modelId ?? item?.id) === "string").map((item) => ({ id: item.modelId ?? item.id, label: typeof item.name === "string" && item.name ? item.name : item.modelId ?? item.id, ...typeof item.description === "string" && item.description ? { description: item.description } : {} })) : void 0;
+    const config = offered?.configOptions?.find((option) => option.category === "model" && option.type === "select");
+    const modeConfig = offered?.configOptions?.find((option) => option.category === "mode" && option.type === "select");
+    const flatten = (options) => options?.flatMap((option) => option.options ?? [option]).map((option) => ({ ...option, id: option.value }));
+    const modelState = offered?.models ?? (config ? { availableModels: flatten(config.options), currentModelId: config.currentValue } : void 0);
+    const modeState = offered?.modes ?? (modeConfig ? { availableModes: flatten(modeConfig.options), currentModeId: modeConfig.currentValue } : void 0);
+    const models = choices(modelState?.availableModels);
+    const modes = choices(modeState?.availableModes);
+    return {
+      ...models ? { models, ...typeof modelState.currentModelId === "string" ? { currentModel: modelState.currentModelId } : {} } : {},
+      ...modes ? { modes, ...typeof modeState.currentModeId === "string" ? { currentMode: modeState.currentModeId } : {} } : {},
+      protocolVersion: result.protocolVersion,
+      ...info ? { agent: { ...info.name ? { name: info.name } : {}, ...info.title ? { title: info.title } : {}, ...info.version ? { version: info.version } : {} } } : {},
+      loadSession: Boolean(result.agentCapabilities?.loadSession),
+      mcpHttp: Boolean(result.agentCapabilities?.mcpCapabilities?.http),
+      authMethods: (result.authMethods ?? []).map((method) => method?.name ?? method?.id).filter(Boolean)
+    };
+  } finally {
+    await session.close();
+  }
+}
+export {
+  probeAcp
+};

package/dist/antigravity-probe.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Probes Antigravity CLI for version, status and available models.
+ * @param {{ command?: string, args?: string[], env?: Record<string, string>, label?: string, id?: string, readOnlyMode?: 'instructions' | 'reject' }} [provider]
+ * @param {{ cwd?: string, timeoutMs?: number }} [options]
+ */
+export function probeAntigravity(provider?: {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    label?: string;
+    id?: string;
+    readOnlyMode?: "instructions" | "reject";
+}, { cwd, timeoutMs }?: {
+    cwd?: string;
+    timeoutMs?: number;
+}): Promise<{
+    version: string;
+    agent: {
+        name: string;
+        title: string;
+        version: string;
+    };
+    models: {
+        id: any;
+        label: any;
+    }[];
+    currentModel: any;
+    modes: {
+        id: string;
+        label: string;
+        description: string;
+    }[];
+    currentMode: string;
+}>;

package/dist/antigravity-probe.js

@@ -0,0 +1,95 @@
+// packages/client/src/antigravity-probe.js
+import { spawn } from "node:child_process";
+var DEFAULT_ANTIGRAVITY_MODELS = [
+  { id: "gemini-3.8-flash-high", label: "Gemini 3.8 Flash (High)" },
+  { id: "gemini-3.8-flash-medium", label: "Gemini 3.8 Flash (Medium)" },
+  { id: "gemini-3.8-flash-low", label: "Gemini 3.8 Flash (Low)" },
+  { id: "gemini-2.5-pro", label: "Gemini 2.5 Pro" },
+  { id: "gemini-2.5-flash", label: "Gemini 2.5 Flash" },
+  { id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6 (Thinking)" },
+  { id: "claude-opus-4-6-thinking", label: "Claude Opus 4.6 (Thinking)" },
+  { id: "gpt-oss-120b-medium", label: "GPT-OSS 120B (Medium)" }
+];
+var ANTIGRAVITY_MODES = [
+  {
+    id: "full-access",
+    label: "Full access",
+    description: "Antigravity runs with full access (--dangerously-skip-permissions)."
+  }
+];
+function runCommand(command, args, { env = process.env, cwd, timeoutMs = 2e4 } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error(`${command} ${args.join(" ")} timed out after ${timeoutMs / 1e3}s`));
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve({ stdout, stderr });
+      else reject(new Error(`${command} exited with code ${code}: ${stderr.trim() || stdout.trim()}`));
+    });
+  });
+}
+async function probeAntigravity(provider = {}, { cwd, timeoutMs = 2e4 } = {}) {
+  const command = provider.command || "agy";
+  const args = provider.args ?? [];
+  const env = { ...process.env, ...provider.env ?? {} };
+  let version = "";
+  try {
+    const res = await runCommand(command, [...args, "--version"], { env, cwd, timeoutMs: Math.min(timeoutMs, 5e3) });
+    version = res.stdout.trim().split("\n")[0] ?? "";
+  } catch (error) {
+    throw new Error(`Antigravity command '${command}' is not available: ${error.message}`);
+  }
+  let models = [];
+  try {
+    const res = await runCommand(command, [...args, "models"], { env, cwd, timeoutMs });
+    for (const line of res.stdout.trim().split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      const [id, label] = line.split("	");
+      if (id && label) {
+        models.push({ id: id.trim(), label: label.trim() });
+      } else if (id) {
+        models.push({ id: id.trim(), label: id.trim() });
+      }
+    }
+  } catch {
+    models = [...DEFAULT_ANTIGRAVITY_MODELS];
+  }
+  if (!models.length) {
+    models = [...DEFAULT_ANTIGRAVITY_MODELS];
+  }
+  return {
+    version,
+    agent: { name: "antigravity", title: "Antigravity", version },
+    models,
+    currentModel: models[0]?.id,
+    modes: provider.readOnlyMode === "instructions" ? [...ANTIGRAVITY_MODES, {
+      id: "read-only",
+      label: "Read only (instructions)",
+      description: "For new sessions: prompt-only read-only behavior. agy still runs with full access; no OS sandbox enforces this mode."
+    }] : ANTIGRAVITY_MODES,
+    currentMode: "full-access"
+  };
+}
+export {
+  probeAntigravity
+};

package/dist/command.d.ts

@@ -0,0 +1,5 @@
+/** Runs a command; resolves with its exit code and output, never rejects. */
+export function runCommand(command: any, args: any, { cwd, env, timeoutMs }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    timeoutMs?: number | undefined;
+}): Promise<any>;

package/dist/command.js

@@ -0,0 +1,32 @@
+// packages/client/src/command.js
+import { spawn } from "node:child_process";
+function runCommand(command, args, { cwd, env = process.env, timeoutMs = 15e3 } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) {
+      resolve({ code: -1, stdout: "", stderr: error.message });
+      return;
+    }
+    let stdout = "", stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({ code: -1, stdout, stderr: error.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? -1, stdout, stderr });
+    });
+  });
+}
+export {
+  runCommand
+};

package/dist/doctor.d.ts

@@ -0,0 +1,13 @@
+export type DoctorCheck = {
+  id: string;
+  status: 'ok' | 'info' | 'warn' | 'fail';
+  summary: string;
+  details?: string[];
+  hint?: string;
+  fix?: { describe: string; apply(): Promise<string> };
+};
+export type CommandResult = { code: number; stdout: string; stderr: string };
+export type CommandRunner = (command: string, args: string[], options?: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }) => Promise<CommandResult>;
+export const runCommand: CommandRunner;
+export function diagnose(options?: { home?: string; project?: string; env?: NodeJS.ProcessEnv; run?: CommandRunner; sandbox?: boolean; daemonEntry?: string }): Promise<DoctorCheck[]>;
+export function repair(checks: DoctorCheck[]): Promise<Array<{ id: string; result: string }>>;

package/dist/doctor.js

@@ -0,0 +1,386 @@
+// packages/client/src/doctor.js
+import { access, chmod, constants, lstat, readdir, readFile, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { runCommand } from "./command.js";
+import { daemonPaths, lockAlive, readLock } from "./index.js";
+import { installedProgram, serviceFor } from "./service.js";
+import { jsonObject, agentSources, resolveAgent } from "@anhlp/alp-core/resolver";
+import { loadHooks } from "@anhlp/alp-core/hooks";
+import { isTrusted } from "@anhlp/alp-core/trust";
+import { listProviders } from "@anhlp/alp-core/providers";
+import { settingsWarnings, validateSettings, validateUserSettings } from "@anhlp/alp-core/validation";
+var firstLine = (text) => text.trim().split("\n")[0] ?? "";
+async function executable(command, env) {
+  const candidates = path.isAbsolute(command) ? [command] : (env.PATH ?? "").split(path.delimiter).filter(Boolean).map((directory) => path.join(directory, command));
+  for (const candidate of candidates) {
+    try {
+      await access(candidate, constants.X_OK);
+      if ((await lstat(candidate)).isDirectory()) continue;
+      return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
+var RUNTIMES = [
+  { kind: "codex", variable: "ALP_CODEX_BIN", login: ["login", "status"], loggedIn: (result) => result.code === 0, hint: "codex login" },
+  {
+    kind: "claude",
+    variable: "ALP_CLAUDE_BIN",
+    login: ["auth", "status"],
+    hint: "claude auth login",
+    loggedIn: (result) => {
+      try {
+        return JSON.parse(result.stdout).loggedIn === true;
+      } catch {
+        return result.code === 0;
+      }
+    }
+  },
+  {
+    kind: "antigravity",
+    command: "agy",
+    variable: "ALP_ANTIGRAVITY_BIN",
+    login: ["models"],
+    hint: "agy and sign in",
+    loggedIn: (result) => result.code === 0
+  }
+];
+async function runtimeChecks({ env, run }) {
+  const checks = [];
+  for (const runtime of RUNTIMES) {
+    const command = env[runtime.variable] || runtime.command || runtime.kind;
+    const found = await executable(command, env);
+    if (!found) {
+      checks.push({ id: runtime.kind, status: "warn", summary: `${command} not found on PATH; ${runtime.kind} agents cannot run (set ${runtime.variable} to its path)` });
+      continue;
+    }
+    const version = await run(found, ["--version"], { env });
+    if (version.code !== 0) {
+      checks.push({ id: runtime.kind, status: "fail", summary: `${found} --version failed: ${firstLine(version.stderr || version.stdout) || `exit ${version.code}`}` });
+      continue;
+    }
+    const login = await run(found, runtime.login, { env });
+    checks.push(runtime.loggedIn(login) ? { id: runtime.kind, status: "ok", summary: `${firstLine(version.stdout)} at ${found}, logged in` } : { id: runtime.kind, status: "fail", summary: `${firstLine(version.stdout)} at ${found} is not logged in; run ${runtime.hint}` });
+  }
+  if (checks.every((check) => check.status !== "ok")) {
+    for (const check of checks) if (check.status === "warn") check.status = "fail";
+  }
+  return checks;
+}
+async function serviceCheck(home, env) {
+  const service = serviceFor({ home, env });
+  const program2 = service && await installedProgram(service);
+  if (!program2) return void 0;
+  const missing = [];
+  for (const file of program2) if (!await lstat(file).then(() => true, () => false)) missing.push(file);
+  return missing.length ? { id: "service", status: "fail", summary: `the ${service.kind} service ${service.name} runs files that are gone; run alp daemon install again`, details: missing } : { id: "service", status: "ok", summary: `${service.kind} runs alpd as ${service.name}` };
+}
+async function daemonCheck(home) {
+  const paths = daemonPaths(home);
+  const lock = await readLock(home);
+  const exists = (file) => lstat(file).then(() => true, () => false);
+  if (lockAlive(lock)) return { id: "alpd", status: "ok", summary: `running (pid ${lock.pid}, ${lock.version})${lock.ready ? "" : ", starting"}` };
+  const stale = [];
+  if (await exists(paths.lock)) stale.push(paths.lock);
+  if (await exists(paths.socket)) stale.push(paths.socket);
+  const crashed = await exists(path.join(home, "state", "alpd.running"));
+  const after = crashed ? "; the last alpd stopped unexpectedly, and the next start continues its work" : "";
+  if (!stale.length) return { id: "alpd", status: crashed ? "info" : "ok", summary: `not running${after}` };
+  return {
+    id: "alpd",
+    status: "warn",
+    summary: `not running, and left ${stale.map((file) => path.basename(file)).join(" and ")} behind${after}`,
+    fix: {
+      describe: `remove ${stale.join(", ")}`,
+      async apply() {
+        if (lockAlive(await readLock(home))) return "skipped: alpd started meanwhile";
+        for (const file of stale) await unlink(file).catch(() => {
+        });
+        return `removed ${stale.length} stale file${stale.length > 1 ? "s" : ""}`;
+      }
+    }
+  };
+}
+async function privateEntries(home) {
+  const entries = [home];
+  for (const name of ["settings.json", "alpd.lock", "alpd.json", "role-skills.json"]) entries.push(path.join(home, name));
+  for (const directory of ["state", "runs", "logs", "boards", "worktrees", "copies"]) {
+    const full = path.join(home, directory);
+    entries.push(full);
+    if (directory === "worktrees" || directory === "copies") continue;
+    for (const name of await readdir(full).catch(() => [])) entries.push(path.join(full, name));
+  }
+  return entries;
+}
+async function permissionsCheck(home) {
+  const open = [];
+  for (const entry of await privateEntries(home)) {
+    const info = await lstat(entry).catch(() => void 0);
+    if (!info || info.isSymbolicLink() || !(info.mode & 63)) continue;
+    open.push({ entry, mode: info.mode & 511, directory: info.isDirectory() });
+  }
+  if (!open.length) return { id: "permissions", status: "ok", summary: `${home} is private to you` };
+  return {
+    id: "permissions",
+    status: "warn",
+    summary: `${open.length} entr${open.length > 1 ? "ies" : "y"} under ${home} readable by others; they hold task briefs, results and settings`,
+    details: open.map((item) => `${item.mode.toString(8).padStart(4, "0")} ${item.entry}`),
+    fix: {
+      describe: "remove group and other access from them",
+      async apply() {
+        for (const item of open) await chmod(item.entry, item.mode & 448).catch(() => {
+        });
+        return `tightened ${open.length} entr${open.length > 1 ? "ies" : "y"}`;
+      }
+    }
+  };
+}
+async function userSettingsCheck(home) {
+  const file = path.join(home, "settings.json");
+  try {
+    const text = await readFile(file, "utf8").catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (text === void 0) return { id: "user settings", status: "ok", summary: `none (${file})` };
+    const settings = JSON.parse(text);
+    validateUserSettings(settings, file);
+    const warnings = settingsWarnings(settings, "user");
+    return warnings.length ? { id: "user settings", status: "warn", summary: `${file}: ${warnings.length} key${warnings.length > 1 ? "s" : ""} ALP ignores`, details: warnings } : { id: "user settings", status: "ok", summary: file };
+  } catch (error) {
+    return { id: "user settings", status: "fail", summary: `alpd ignores ${file}: ${error.message.replace(`${file}: `, "")}` };
+  }
+}
+async function projectChecks(project, home) {
+  const checks = [];
+  const file = path.join(project, ".alp", "settings.json");
+  let settings;
+  try {
+    settings = await jsonObject(file, "INVALID_SETTINGS");
+    validateSettings(settings, file);
+    const warnings = settingsWarnings(settings, "project");
+    checks.push(warnings.length ? { id: "settings", status: "warn", summary: `${file}: ${warnings.length} key${warnings.length > 1 ? "s" : ""} ALP ignores`, details: warnings } : { id: "settings", status: "ok", summary: file });
+  } catch (error) {
+    checks.push({ id: "settings", status: "fail", summary: error.message });
+    return checks;
+  }
+  const sources = await agentSources(project, { library: home });
+  const agents = [...sources.keys()].sort((a, b) => a.localeCompare(b));
+  const broken = [];
+  const shadows = [];
+  const hooks = /* @__PURE__ */ new Map();
+  for (const [agent, { source, overrides }] of sources) if (overrides) shadows.push(`${agent}: the ${source}'s copy replaces the ${overrides === "builtin" ? "built-in" : "library"} agent`);
+  for (const agent of agents) {
+    try {
+      const resolved = await resolveAgent(project, { agent, library: home });
+      for (const hook of await loadHooks(resolved)) hooks.set(hook.path, { ...hook, agents: [...hooks.get(hook.path)?.agents ?? [], agent] });
+      for (const skill of resolved.skills) if (!skill.path.startsWith(home + path.sep)) {
+        const library = path.join(home, "skills", skill.name, "SKILL.md");
+        if (await lstat(library).then(() => true, () => false)) shadows.push(`${agent}: ${skill.name} from the project replaces the library's`);
+      }
+    } catch (error) {
+      broken.push(`${agent}: ${error.message}`);
+    }
+  }
+  if (!agents.length) checks.push({ id: "agents", status: "fail", summary: "no agents: neither ALP's built-ins nor the library nor the project define one" });
+  else if (broken.length) checks.push({ id: "agents", status: "fail", summary: `${broken.length} of ${agents.length} agents cannot start`, details: broken });
+  else checks.push({ id: "agents", status: shadows.length ? "info" : "ok", summary: `${agents.length} agents resolve: ${agents.join(", ")}`, ...shadows.length ? { details: shadows } : {} });
+  if (hooks.size) checks.push(await hooksCheck(project, home, [...hooks.values()]));
+  if (settings.defaultAgent && !agents.includes(settings.defaultAgent)) checks.push({ id: "agents", status: "fail", summary: `defaultAgent ${settings.defaultAgent} is not an agent of this project` });
+  return checks;
+}
+var program = (command) => /^\s*([\w./-]+)/.exec(command)?.[1];
+var SHELL_WORDS = /* @__PURE__ */ new Set(["cd", "test", "[", "echo", "exit", "true", "false", "set", "export", "if", "for", "while", "exec", "env", "command", "printf", "read", "source", "."]);
+async function hooksCheck(project, home, hooks) {
+  const missing = [];
+  for (const hook of hooks) {
+    const name = program(hook.command);
+    if (!name || SHELL_WORDS.has(name)) continue;
+    const candidates = name.includes("/") ? [path.resolve(project, name)] : (process.env.PATH ?? "").split(path.delimiter).filter(Boolean).map((directory) => path.join(directory, name));
+    let found = false;
+    for (const candidate of candidates) if (await access(candidate, constants.X_OK).then(() => true, () => false)) {
+      found = true;
+      break;
+    }
+    if (!found) missing.push(`${hook.name} (${hook.event}, used by ${hook.agents.join(", ")}): ${name} is not found`);
+  }
+  const fromProject = hooks.filter((hook) => hook.project);
+  const trusted = fromProject.length ? await isTrusted(home, project) : true;
+  const details = [...missing, ...!trusted ? [`not trusted yet: ${fromProject.map((hook) => hook.name).join(", ")}; alpd asks the first time one runs, or run alp trust`] : []];
+  return {
+    id: "hooks",
+    status: missing.length ? "warn" : trusted ? "ok" : "info",
+    summary: `${hooks.length} hook${hooks.length > 1 ? "s" : ""}${fromProject.length ? `, ${fromProject.length} from the project${trusted ? ", which the user trusts" : ", not trusted yet"}` : ""}${missing.length ? `; ${missing.length} cannot start` : ""}`,
+    ...details.length ? { details } : {}
+  };
+}
+async function providersCheck(home, env) {
+  let providers;
+  try {
+    providers = await listProviders(home);
+  } catch (error) {
+    return { id: "providers", status: "fail", summary: error.message };
+  }
+  if (!providers.length) return void 0;
+  const missing = [];
+  for (const provider of providers) if (!await executable(provider.command, { ...env, ...provider.env })) missing.push(`${provider.id}: ${provider.command} is not found`);
+  return {
+    id: "providers",
+    status: "warn",
+    summary: `${providers.length} ACP provider${providers.length > 1 ? "s" : ""} (${providers.map((provider) => provider.id).join(", ")})${missing.length ? `; ${missing.length} cannot start` : ""}`,
+    details: [
+      ...missing,
+      "ALP has no sandbox around an ACP agent: it holds the session's mode only by answering the permission requests the agent sends, so a command the agent runs without asking runs unchecked",
+      "ALP cannot steer an ACP agent mid-turn (mail waits for the turn to end), resumes its sessions only when it supports session/load, and cannot recall them or give them review copies"
+    ]
+  };
+}
+async function librarySkillsCheck(home) {
+  const file = path.join(home, "role-skills.json");
+  let roles;
+  try {
+    const text = await readFile(file, "utf8").catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (text === void 0) return void 0;
+    roles = JSON.parse(text);
+  } catch (error) {
+    return { id: "skills", status: "fail", summary: `${file}: ${error.message}` };
+  }
+  if (!roles || typeof roles !== "object" || Array.isArray(roles)) return { id: "skills", status: "fail", summary: `${file}: expected an object of role names to skill lists` };
+  const missing = [];
+  for (const [role, names] of Object.entries(roles)) {
+    if (!Array.isArray(names)) {
+      missing.push(`${role}: not a list`);
+      continue;
+    }
+    for (const name of names) {
+      if (typeof name !== "string" || !await lstat(path.join(home, "skills", name, "SKILL.md")).then(() => true, () => false)) missing.push(`${role}: ${name}`);
+    }
+  }
+  return missing.length ? { id: "skills", status: "warn", summary: `${file} lists ${missing.length} skill${missing.length > 1 ? "s" : ""} the library lacks; agents start without them`, details: missing } : { id: "skills", status: "ok", summary: `the library's skills exist (${file})` };
+}
+async function liveCheck(home, running) {
+  const file = path.join(home, "state", "live.json");
+  let entries;
+  try {
+    entries = JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return void 0;
+  }
+  if (!Array.isArray(entries)) return { id: "live work", status: "warn", summary: `${file} is not a list; alpd ignores it` };
+  const gone = [];
+  for (const entry of entries) {
+    if (typeof entry?.project !== "string" || !await lstat(entry.project).then(() => true, () => false)) gone.push(entry);
+  }
+  if (!gone.length) return { id: "live work", status: entries.length && !running ? "info" : "ok", summary: entries.length ? `${entries.length} assignment${entries.length > 1 ? "s" : ""} ${running ? "running" : "waiting for alpd to continue"}` : "no running assignments" };
+  return {
+    id: "live work",
+    status: "warn",
+    summary: `${gone.length} interrupted assignment${gone.length > 1 ? "s" : ""} belong to projects that no longer exist`,
+    details: gone.map((entry) => `${entry?.agent} ${entry?.assignmentId} in ${entry?.project}`),
+    fix: running ? void 0 : {
+      describe: `drop them from ${file}`,
+      async apply() {
+        const current = JSON.parse(await readFile(file, "utf8"));
+        const ids = new Set(gone.map((entry) => entry?.assignmentId));
+        const kept = current.filter((entry) => !ids.has(entry?.assignmentId));
+        await writeFile(file, JSON.stringify(kept, null, 2) + "\n", { mode: 384 });
+        return `dropped ${current.length - kept.length}`;
+      }
+    },
+    ...running ? { hint: "stop alpd to drop them" } : {}
+  };
+}
+async function branchCheck(project, home, run) {
+  const git = (args) => run("git", args, { cwd: project });
+  const top = await git(["rev-parse", "--show-toplevel"]);
+  if (top.code !== 0) return [];
+  const checks = [];
+  const worktrees = (await git(["worktree", "list", "--porcelain"])).stdout.split("\n\n").filter(Boolean);
+  const prunable = worktrees.filter((block) => /^prunable/m.test(block)).map((block) => block.match(/^worktree (.*)$/m)?.[1]).filter(Boolean);
+  if (prunable.length) checks.push({
+    id: "worktrees",
+    status: "warn",
+    summary: `git still lists ${prunable.length} worktree${prunable.length > 1 ? "s" : ""} that no longer exist`,
+    details: prunable,
+    fix: { describe: "git worktree prune", async apply() {
+      await git(["worktree", "prune"]);
+      return "pruned";
+    } }
+  });
+  const checkedOut = new Set(worktrees.map((block) => block.match(/^branch refs\/heads\/(.*)$/m)?.[1]).filter(Boolean));
+  let live = [];
+  try {
+    live = JSON.parse(await readFile(path.join(home, "state", "live.json"), "utf8"));
+  } catch {
+  }
+  const inUse = /* @__PURE__ */ new Set([...checkedOut, ...Array.isArray(live) ? live.map((entry) => entry?.worktree?.branch).filter(Boolean) : []]);
+  const branches = (await git(["for-each-ref", "--format=%(refname:short)", "refs/heads/alp/"])).stdout.split("\n").filter(Boolean);
+  if (!branches.length) return checks;
+  const merged = new Set((await git(["branch", "--format=%(refname:short)", "--merged", "HEAD", "--list", "alp/*"])).stdout.split("\n").filter(Boolean));
+  const spare = branches.filter((branch) => merged.has(branch) && !inUse.has(branch));
+  const kept = branches.filter((branch) => !merged.has(branch) && !inUse.has(branch));
+  if (spare.length) checks.push({
+    id: "branches",
+    status: "warn",
+    summary: `${spare.length} alp/* branch${spare.length > 1 ? "es are" : " is"} already merged into HEAD`,
+    details: spare,
+    fix: {
+      describe: `delete ${spare.length > 1 ? "them" : "it"} with git branch -d`,
+      async apply() {
+        let deleted = 0;
+        for (const branch of spare) if ((await git(["branch", "-d", branch])).code === 0) deleted++;
+        return `deleted ${deleted}`;
+      }
+    }
+  });
+  if (kept.length) checks.push({ id: "branches", status: "info", summary: `${kept.length} alp/* branch${kept.length > 1 ? "es hold" : " holds"} unmerged work from finished or interrupted assignments; merge or delete ${kept.length > 1 ? "them" : "it"} yourself`, details: kept });
+  if (!spare.length && !kept.length) checks.push({ id: "branches", status: "ok", summary: `${branches.length} alp/* branch${branches.length > 1 ? "es" : ""} in use` });
+  return checks;
+}
+async function diagnose({ home, project, env = process.env, run = runCommand, sandbox, daemonEntry } = {}) {
+  const checks = [];
+  if (daemonEntry) {
+    checks.push(await lstat(daemonEntry).then(() => ({ id: "build", status: "ok", summary: daemonEntry }), () => ({ id: "build", status: "fail", summary: `alpd is not built (${daemonEntry}); run npm run build` })));
+  }
+  checks.push(...await runtimeChecks({ env, run }));
+  const daemon = await daemonCheck(home);
+  checks.push(daemon);
+  const service = await serviceCheck(home, env);
+  if (service) checks.push(service);
+  const running = daemon.status === "ok" && daemon.summary.startsWith("running");
+  if (sandbox !== void 0) checks.push(sandbox ? { id: "sandbox", status: "ok", summary: "Claude sessions run Bash in an OS sandbox that holds their mode" } : { id: "sandbox", status: "warn", summary: `no Bash sandbox for Claude (${process.platform === "linux" ? "install bubblewrap and socat" : "Seatbelt is missing"}): read-only Claude agents rely on their permission rules alone, and review copies on Claude cannot start` });
+  checks.push(await permissionsCheck(home));
+  checks.push(await userSettingsCheck(home));
+  const skills = await librarySkillsCheck(home);
+  if (skills) checks.push(skills);
+  const providers = await providersCheck(home, env);
+  if (providers) checks.push(providers);
+  const live = await liveCheck(home, running);
+  if (live) checks.push(live);
+  if (project) {
+    checks.push(...await projectChecks(project, home));
+    checks.push(...await branchCheck(project, home, run));
+  }
+  return checks;
+}
+async function repair(checks) {
+  const done = [];
+  for (const check of checks) {
+    if (!check.fix) continue;
+    try {
+      done.push({ id: check.id, result: await check.fix.apply() });
+    } catch (error) {
+      done.push({ id: check.id, result: `failed: ${error.message}` });
+    }
+  }
+  return done;
+}
+export {
+  diagnose,
+  repair,
+  runCommand
+};