@anhlp/alp-client 0.0.0-beta.1

package/dist/doctor.js

@@ -0,0 +1,587 @@
+// 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 { assertPrivateSocket, connect, 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";
+import { readLogTail, scrubText } from "@anhlp/alp-core/log";
+import { STATE_SCHEMA, migrationFile, readStateSchema } from "@anhlp/alp-core/state-schema";
+var firstLine = (text) => text.trim().split("\n")[0] ?? "";
+async function executable(command, env) {
+  const names = process.platform === "win32" ? [command, `${command}.exe`, `${command}.com`] : [command];
+  const candidates = path.isAbsolute(command) ? names : (env.PATH ?? "").split(path.delimiter).filter(Boolean).flatMap((directory) => names.map((name) => path.join(directory, name)));
+  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}` };
+}
+var seconds = (ms) => `${Math.round(ms / 1e3)} s`;
+var STARTUP_CODES = /* @__PURE__ */ new Set(["ALP_HOME_UNUSABLE", "ALP_LOCK_FAILED", "ALP_STARTUP_FAILED", "ALP_IPC_LISTEN_FAILED"]);
+var GROUPS = [
+  { id: "persistence log", match: /^ALP_(PERSISTENCE|STATE|RECORD|TIMELINE)_/, hint: "alpd could not read or write its state; check free space and the permissions of the state directory" },
+  { id: "ipc log", match: /^ALP_(IPC|RPC)_/, hint: "clients had trouble talking to alpd; alp daemon restart reopens the endpoint" },
+  { id: "provider log", match: /^ALP_PROVIDER_/, hint: "a runtime process failed or would not start; the runtime checks above say whether it is installed and logged in" }
+];
+var STATE_FAILURES = { ENOENT: "is missing", EACCES: "is not accessible to you", EPERM: "is not accessible to you", EROFS: "is on a read-only filesystem", ENOSPC: "has no space left" };
+function ipcFailure(error) {
+  if (error?.code === "ALP_IPC_TIMEOUT") return "ALP_IPC_TIMEOUT";
+  if (error?.code === "ENOENT") return "ALP_IPC_SOCKET_MISSING";
+  if (error?.code === "ECONNREFUSED") return "ALP_IPC_REFUSED";
+  if (error?.code === "EACCES" || error?.code === "EPERM") return "ALP_IPC_DENIED";
+  if (/private|owned by|ancestors|symlink/.test(error?.message ?? "")) return "ALP_IPC_SOCKET_UNSAFE";
+  return "ALP_IPC_FAILED";
+}
+async function askDaemon(lock, timeoutMs) {
+  let timer;
+  const attempt = connect(lock.socket, { name: "alp-doctor", version: "1" }).then(async (client) => {
+    try {
+      return await client.request("daemon.status");
+    } finally {
+      client.close();
+    }
+  });
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(Object.assign(new Error(`no answer within ${seconds(timeoutMs)}`), { code: "ALP_IPC_TIMEOUT" })), timeoutMs);
+  });
+  try {
+    return { status: await Promise.race([attempt, timeout]) };
+  } catch (error) {
+    attempt.catch(() => {
+    });
+    return { error };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function daemonHealthChecks(lock, timeoutMs) {
+  if (!lockAlive(lock) || lock.maintenance) return [];
+  const { status, error } = await askDaemon(lock, timeoutMs);
+  if (error) {
+    const code = ipcFailure(error);
+    const starting = !lock.ready && Date.now() - Date.parse(lock.startedAt) < 6e4;
+    return [{
+      id: "ipc",
+      status: starting ? "info" : "fail",
+      summary: `alpd (pid ${lock.pid}) is running but ${starting ? "does not answer yet, it is still starting" : "cannot be reached"} on ${lock.socket}: ${code}, ${error.message}`,
+      details: [`code ${code}`, ...starting ? [] : ["alp daemon restart starts it again; its work is kept and continued"]]
+    }];
+  }
+  const checks = [{ id: "ipc", status: "ok", summary: `alpd answers on ${lock.socket} (protocol ${status.protocolVersion})` }];
+  const health = status.health;
+  if (!health) {
+    checks.push({ id: "readiness", status: "info", summary: `alpd ${status.version} does not report readiness; alp daemon restart updates it` });
+    return checks;
+  }
+  const failing = health.checks.filter((check) => !check.ok);
+  checks.push(health.ready ? { id: "readiness", status: "ok", summary: "alpd is ready: it accepts connections and reads and writes its state" } : {
+    id: "readiness",
+    status: "fail",
+    summary: `alpd is alive but not ready: ${failing.map((check) => check.code ?? check.id).join(", ")}`,
+    details: failing.map((check) => `${check.code ?? check.id}: ${check.message ?? "failed"}`),
+    hint: "new prompts may fail until this clears; alp doctor shows the state directory below"
+  });
+  if (!lock.ready) checks.push({ id: "startup", status: "warn", summary: "alpd answers but has not finished starting" });
+  return checks;
+}
+async function stateCheck(home) {
+  const directory = path.join(home, "state");
+  const info = await lstat(directory).catch(() => void 0);
+  const target = info ? directory : home;
+  if (!info && !await lstat(home).then(() => true, () => false)) return { id: "state", status: "ok", summary: `${directory} is created when alpd first starts` };
+  try {
+    await access(target, constants.R_OK | constants.W_OK | constants.X_OK);
+  } catch (error) {
+    return {
+      id: "state",
+      status: "fail",
+      summary: `${target} ${STATE_FAILURES[error.code] ?? `cannot be used (${error.code ?? error.message})`}: alpd cannot ${error.code === "ENOENT" ? "find" : "write"} its sessions; ALP_STATE_NOT_WRITABLE`,
+      details: [error.message]
+    };
+  }
+  if (!info) return { id: "state", status: "ok", summary: `${directory} is created when alpd first starts` };
+  const unreadable = [];
+  const leftovers = [];
+  let records = 0;
+  for (const name of await readdir(path.join(directory, "sessions")).catch(() => []).then((names) => names.slice(0, 2e3))) {
+    if (name.endsWith(".tmp")) {
+      leftovers.push(name);
+      continue;
+    }
+    if (!name.endsWith(".json")) continue;
+    records++;
+    try {
+      const record = JSON.parse(await readFile(path.join(directory, "sessions", name), "utf8"));
+      if (record?.version !== 1 || typeof record.id !== "string") unreadable.push(name);
+    } catch {
+      unreadable.push(name);
+    }
+  }
+  if (unreadable.length) return {
+    id: "state",
+    status: "warn",
+    summary: `${unreadable.length} of ${records} session record${records > 1 ? "s" : ""} in ${directory} cannot be read; alpd skips ${unreadable.length > 1 ? "them" : "it"} and ${unreadable.length > 1 ? "those sessions are" : "that session is"} not listed (ALP_RECORD_UNREADABLE)`,
+    details: [...unreadable.slice(0, 10), "doctor never deletes them: copy or repair the files by hand"]
+  };
+  return { id: "state", status: "ok", summary: `${directory} is readable and writable; ${records} session record${records === 1 ? "" : "s"}${leftovers.length ? `, ${leftovers.length} temporary file${leftovers.length > 1 ? "s" : ""} left by an interrupted write (alpd removes them)` : ""}` };
+}
+var brief = (record) => `${record.time} ${record.component} ${record.code ?? ""} ${record.msg}${record.sessionId ? ` [session ${record.sessionId}]` : ""}`.replace(/\s+/g, " ").trim();
+async function logChecks(home, running) {
+  const file = daemonPaths(home).log;
+  let records;
+  try {
+    records = (await readLogTail(file)).filter((record) => !record.legacy);
+  } catch (error) {
+    return [{ id: "log", status: "warn", summary: `${file} cannot be read: ${error.message}` }];
+  }
+  if (!records.length) return [];
+  const lastReady = records.findLastIndex((record) => record.event === "ready");
+  const since = records.slice(lastReady + 1);
+  const checks = [];
+  const failure = since.findLast((record) => record.level === "error" && STARTUP_CODES.has(record.code));
+  if (failure) checks.push({
+    id: "startup",
+    status: running ? "info" : "fail",
+    summary: `${running ? "an attempt to start another alpd" : "the last alpd"} failed at ${failure.time}: ${failure.code}, ${failure.msg}`,
+    details: [...failure.error ? [`${failure.error.name ?? "Error"}${failure.error.code ? ` ${failure.error.code}` : ""}: ${failure.error.message}`] : [], `log: ${file}`],
+    ...running ? {} : { hint: "fix the cause and run alp daemon start; its work is kept and continued" }
+  });
+  for (const group of GROUPS) {
+    const found = since.filter((record) => (record.level === "error" || record.level === "warn") && group.match.test(record.code ?? ""));
+    if (!found.length) continue;
+    const counts = /* @__PURE__ */ new Map();
+    for (const record of found) counts.set(record.code, (counts.get(record.code) ?? 0) + 1);
+    checks.push({
+      id: group.id,
+      status: "warn",
+      summary: `${found.length} problem${found.length > 1 ? "s" : ""} logged since alpd was last ready: ${[...counts].map(([code, count]) => `${code} x${count}`).join(", ")}`,
+      details: [...found.slice(-5).map(brief), group.hint]
+    });
+  }
+  return checks;
+}
+async function failedSessionsCheck(home) {
+  const directory = path.join(home, "state", "sessions");
+  const failed = [];
+  for (const name of await readdir(directory).catch(() => []).then((names) => names.slice(0, 2e3))) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const record = JSON.parse(await readFile(path.join(directory, name), "utf8"));
+      if (record?.status === "failed" && record.lastError) failed.push(record);
+    } catch {
+    }
+  }
+  if (!failed.length) return void 0;
+  failed.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+  const recent = failed.filter((record) => Date.now() - Date.parse(record.updatedAt) < 24 * 36e5);
+  return {
+    id: "failed sessions",
+    status: recent.length ? "warn" : "info",
+    summary: `${failed.length} session${failed.length > 1 ? "s" : ""} ended in failure${recent.length ? `, ${recent.length} in the last day` : ""}; kept, nothing is deleted`,
+    details: failed.slice(0, 5).map((record) => `${record.updatedAt} ${record.session?.agent ?? "session"} ${record.id} (${record.session?.runtime ?? "unknown runtime"}) ${record.lastError.code ?? ""} ${String(record.lastError.message).slice(0, 200)}`.replace(/\s+/g, " "))
+  };
+}
+async function daemonCheck(home) {
+  const paths = daemonPaths(home);
+  const lock = await readLock(home);
+  const exists = (file) => lstat(file).then(() => true, () => false);
+  if (lockAlive(lock) && lock.maintenance) return { id: "alpd", status: "info", summary: `not running while alp ${lock.maintenance} runs (pid ${lock.pid})` };
+  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) {
+  if (process.platform === "win32") return { id: "permissions", status: "ok", summary: `${home} follows your Windows profile access rules` };
+  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}, keeping a copy beside it`,
+      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}.dropped-${Date.now()}.json`, JSON.stringify(current.filter((entry) => ids.has(entry?.assignmentId)), null, 2) + "\n", { mode: 384 });
+        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;
+}
+function scrubCheck(check) {
+  const clean = (text) => scrubText(text, { max: 1e3 });
+  return {
+    ...check,
+    summary: clean(check.summary),
+    ...check.details ? { details: check.details.map(clean) } : {},
+    ...check.hint ? { hint: clean(check.hint) } : {}
+  };
+}
+async function schemaChecks(home) {
+  let info;
+  try {
+    info = await readStateSchema(home);
+  } catch (error) {
+    return [{ id: "schema", status: "fail", summary: `${error.message} (ALP_${error.code ?? "STATE_UNUSABLE"})` }];
+  }
+  const checks = [info.schema > STATE_SCHEMA ? { id: "schema", status: "fail", summary: `state schema ${info.schema}${info.by ? ` from ${info.by}` : ""} is newer than this ALP knows (${STATE_SCHEMA}): alpd refuses to start and changes nothing in it (ALP_STATE_SCHEMA_TOO_NEW)`, hint: "run the ALP that wrote it, or a newer one; docs/alp/data-recovery.md says more" } : { id: "schema", status: info.schema < STATE_SCHEMA ? "info" : "ok", summary: info.fresh ? `no state yet; alpd starts it at schema ${STATE_SCHEMA}` : info.schema < STATE_SCHEMA ? `state schema ${info.schema}: alpd migrates it to ${STATE_SCHEMA} at its next start, after saving a backup in ${path.join(home, "backups")}` : `state schema ${info.schema}` }];
+  if (await lstat(migrationFile(home)).then(() => true, () => false)) checks.push({ id: "migration", status: "warn", summary: "a state migration was cut short; alpd continues it at its next start, or puts the state back if it fails" });
+  if (await lstat(path.join(home, "restore-journal.json")).then(() => true, () => false)) checks.push({ id: "restore", status: "warn", summary: "a restore was cut short; alpd or the next alp restore moves the earlier data back first" });
+  return checks;
+}
+async function diagnose({ home, project, env = process.env, run = runCommand, sandbox, daemonEntry, timeoutMs = 3e3 } = {}) {
+  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");
+  checks.push(...await daemonHealthChecks(await readLock(home), timeoutMs));
+  checks.push(await stateCheck(home));
+  const schema = await schemaChecks(home);
+  checks.push(...schema);
+  const unreadable = schema.some((check) => check.id === "schema" && check.status === "fail");
+  checks.push(...await logChecks(home, running));
+  const failedSessions = await failedSessionsCheck(home);
+  if (failedSessions) checks.push(failedSessions);
+  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 && unreadable) delete live.fix;
+  if (live) checks.push(live);
+  if (project) {
+    checks.push(...await projectChecks(project, home));
+    checks.push(...await branchCheck(project, home, run));
+  }
+  return checks.map(scrubCheck);
+}
+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
+};