@anhlp/alp-core 0.0.0-beta.1

package/dist/resolver.js

@@ -0,0 +1,240 @@
+// packages/core/src/resolver.js
+import { shippedTemplateRoot } from "./template-path.js";
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { AlpError } from "./errors.js";
+import { validateAgentConfig, validateHook, validateSettings, normalizeMcp, validateResolvedAgent } from "./validation.js";
+import { librarySkills } from "./library.js";
+import { AlpError as AlpError2 } from "./errors.js";
+async function optionalText(file) {
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+async function jsonObject(file, code) {
+  const text = await optionalText(file);
+  if (text === void 0) return {};
+  try {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected a JSON object");
+    return value;
+  } catch (cause) {
+    throw new AlpError(code, `${file}: ${cause.message}`, { cause });
+  }
+}
+async function entries(directory) {
+  try {
+    return (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+var BUILTIN_AGENTS = ["main", "lead", "peer", "oracle", "reviewer", "supervisor"];
+var templateRoot = () => {
+  try {
+    return shippedTemplateRoot();
+  } catch {
+    return void 0;
+  }
+};
+var validName = (name) => typeof name === "string" && /^[\w.-]+$/.test(name) && name !== "." && name !== "..";
+async function builtinText(relative, templates) {
+  if (templates) return templates[relative];
+  const root = templateRoot();
+  if (!root) return void 0;
+  try {
+    return await readFile(new URL(relative, root), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") return void 0;
+    throw error;
+  }
+}
+async function agentSources(root, { library, templates } = {}) {
+  const found = /* @__PURE__ */ new Map();
+  for (const name of BUILTIN_AGENTS) if (await builtinText(`agents/${name}/AGENT.md`, templates) !== void 0) found.set(name, { source: "builtin" });
+  const layer = async (directory, source) => {
+    for (const entry of await entries(directory)) {
+      if (!entry.isDirectory() || !validName(entry.name)) continue;
+      if (source === "library" && await optionalText(path.join(directory, entry.name, "AGENT.md")) === void 0) continue;
+      const previous = found.get(entry.name);
+      found.set(entry.name, { source, directory: path.join(directory, entry.name), ...previous ? { overrides: previous.source } : {} });
+    }
+  };
+  if (library) await layer(path.join(library, "agents"), "library");
+  if (root !== void 0) await layer(path.join(path.resolve(root), ".alp", "agents"), "project");
+  return found;
+}
+async function discoverAgents(root, options = {}) {
+  return [...(await agentSources(root, options)).keys()].sort((a, b) => a.localeCompare(b));
+}
+var KINDS = {
+  skills: (name) => path.join(name, "SKILL.md"),
+  mcp: (name) => `${name}.json`,
+  hooks: (name) => `${name}.json`,
+  // ACP providers (ALPD §46) live only in the library.
+  providers: (name) => `${name}.json`
+};
+var LIBRARY_KINDS = ["agents", ...Object.keys(KINDS)];
+async function libraryEntries(kind, projectRoot, { library, templates } = {}) {
+  const root = projectRoot === void 0 ? void 0 : path.resolve(projectRoot);
+  if (kind === "agents") {
+    const rows = [];
+    for (const [name, source] of await agentSources(root, { library, templates })) {
+      const text = source.directory ? await optionalText(path.join(source.directory, "agent.json")) : await builtinText(`agents/${name}/agent.json`, templates);
+      let description;
+      try {
+        description = text === void 0 ? void 0 : JSON.parse(text).description;
+      } catch {
+      }
+      rows.push({ name, source: source.source, ...source.directory ? { path: source.directory } : {}, ...source.overrides ? { overrides: source.overrides } : {}, ...typeof description === "string" ? { description } : {} });
+    }
+    return rows.sort((a, b) => a.name.localeCompare(b.name));
+  }
+  const file = KINDS[kind];
+  if (!file) throw new AlpError("INVALID_KIND", `Unknown library kind '${kind}'; use one of ${LIBRARY_KINDS.join(", ")}`);
+  const found = /* @__PURE__ */ new Map();
+  const layer = async (directory, source) => {
+    for (const entry of await entries(directory)) {
+      const name = kind === "skills" ? entry.isDirectory() ? entry.name : void 0 : entry.isFile() && entry.name.endsWith(".json") ? entry.name.slice(0, -5) : void 0;
+      if (!name || !validName(name)) continue;
+      const entryPath = path.join(directory, file(name));
+      if (!await stat(entryPath).then((info) => info.isFile(), () => false)) continue;
+      const previous = found.get(name);
+      found.set(name, { name, source, path: entryPath, ...previous ? { overrides: previous.source } : {} });
+    }
+  };
+  if (library) await layer(path.join(library, kind), "library");
+  if (root !== void 0 && kind !== "providers") await layer(path.join(root, ".alp", kind), "project");
+  const users = /* @__PURE__ */ new Map();
+  const use = (name, agent) => users.set(name, [.../* @__PURE__ */ new Set([...users.get(name) ?? [], agent])]);
+  for (const [agent, source] of await agentSources(root, { library, templates })) {
+    const text = source.directory ? await optionalText(path.join(source.directory, "agent.json")) : await builtinText(`agents/${agent}/agent.json`, templates);
+    try {
+      const config = text === void 0 ? {} : JSON.parse(text);
+      for (const name of kind === "providers" ? [config.provider].filter(Boolean) : config[kind] ?? []) use(name, agent);
+    } catch {
+    }
+  }
+  if (kind === "skills" && library) {
+    try {
+      for (const [role, names] of Object.entries(JSON.parse(await optionalText(path.join(library, "role-skills.json")) ?? "{}"))) for (const name of Array.isArray(names) ? names : []) use(name, role);
+    } catch {
+    }
+  }
+  return [...found.values()].map((row) => ({ ...row, ...users.has(row.name) ? { usedBy: users.get(row.name).sort() } : {} })).sort((a, b) => a.name.localeCompare(b.name));
+}
+async function namedEntry(root, library, kind, name, file) {
+  const candidates = [path.join(root, ".alp", kind, file(name)), ...library ? [path.join(library, kind, file(name))] : []];
+  for (const candidate of candidates) if (await stat(candidate).then((info) => info.isFile(), () => false)) return candidate;
+  return void 0;
+}
+async function resolveAgent(projectRoot, { agent, library, templates } = {}) {
+  const root = path.resolve(projectRoot);
+  const settingsPath = path.join(root, ".alp", "settings.json");
+  const settings = await jsonObject(settingsPath, "INVALID_SETTINGS");
+  const projectRuntime = validateSettings(settings, settingsPath);
+  const name = agent ?? settings.defaultAgent ?? "main";
+  if (typeof name !== "string" || !name.trim() || name === "." || name === ".." || /[\\/\x00]/.test(name)) {
+    throw new AlpError("INVALID_AGENT", "Agent name must be a single nonempty directory name");
+  }
+  const source = (await agentSources(root, { library, templates })).get(name);
+  if (!source) throw new AlpError("AGENT_NOT_FOUND", `Agent '${name}' not found: it is not built in, nor under ${library ? `${path.join(library, "agents")} or ` : ""}${path.join(root, ".alp", "agents")}`);
+  const directory = source.directory;
+  const agentPath = directory ? path.join(directory, "AGENT.md") : `built-in agents/${name}/AGENT.md`;
+  const instructions = directory ? await optionalText(agentPath) : await builtinText(`agents/${name}/AGENT.md`, templates);
+  if (instructions === void 0) throw new AlpError("AGENT_INSTRUCTIONS_MISSING", `Missing ${agentPath}`);
+  const configPath = directory ? path.join(directory, "agent.json") : `built-in agents/${name}/agent.json`;
+  const configText = directory ? await optionalText(configPath) : await builtinText(`agents/${name}/agent.json`, templates);
+  let config = {};
+  if (configText !== void 0) {
+    try {
+      config = JSON.parse(configText);
+    } catch (cause) {
+      throw new AlpError("INVALID_AGENT_CONFIG", `${configPath}: ${cause.message}`, { cause });
+    }
+  }
+  validateAgentConfig(config, configPath);
+  const skills = [];
+  for (const skill of library ? await librarySkills(library, name) : []) {
+    skills.push({ name: skill.name, path: await namedEntry(root, void 0, "skills", skill.name, (entry) => path.join(entry, "SKILL.md")) ?? skill.path });
+  }
+  const addSkill = (skillName, skillPath) => {
+    const shadowed = skills.findIndex((skill) => skill.name === skillName);
+    if (shadowed >= 0) skills.splice(shadowed, 1);
+    skills.push({ name: skillName, path: skillPath });
+  };
+  for (const skillName of config.skills ?? []) {
+    const skillPath = await namedEntry(root, library, "skills", skillName, (entry) => path.join(entry, "SKILL.md"));
+    if (!skillPath) throw new AlpError("SKILL_NOT_FOUND", `${configPath}: skill '${skillName}' is neither in ${path.join(root, ".alp", "skills")} nor in the library`);
+    addSkill(skillName, skillPath);
+  }
+  if (directory) {
+    for (const entry of await entries(path.join(directory, "skills"))) {
+      if (!entry.isDirectory()) continue;
+      const skillPath = path.join(directory, "skills", entry.name, "SKILL.md");
+      try {
+        if ((await stat(skillPath)).isFile()) addSkill(entry.name, skillPath);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+  }
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+  const hooks = directory ? (await entries(path.join(directory, "hooks"))).filter((e) => e.isFile()).map((e) => ({ name: e.name, path: path.join(directory, "hooks", e.name) })) : [];
+  for (const hookName of config.hooks ?? []) {
+    const hookPath = await namedEntry(root, library, "hooks", hookName, (entry) => `${entry}.json`);
+    if (!hookPath) throw new AlpError("HOOK_NOT_FOUND", `${configPath}: hook '${hookName}' is neither in ${path.join(root, ".alp", "hooks")} nor in the library`);
+    validateHook(await jsonObject(hookPath, "INVALID_HOOK"), hookPath);
+    hooks.push({ name: hookName, path: hookPath });
+  }
+  const servers = {};
+  for (const serverName of config.mcp ?? []) {
+    const serverPath = await namedEntry(root, library, "mcp", serverName, (entry) => `${entry}.json`);
+    if (!serverPath) throw new AlpError("MCP_NOT_FOUND", `${configPath}: MCP server '${serverName}' is neither in ${path.join(root, ".alp", "mcp")} nor in the library`);
+    const definition = await jsonObject(serverPath, "INVALID_MCP");
+    Object.assign(servers, normalizeMcp({ mcpServers: { [serverName]: definition } }, path.dirname(serverPath), serverPath).mcpServers);
+  }
+  const mcpPath = directory ? path.join(directory, ".mcp.json") : void 0;
+  const own = mcpPath ? normalizeMcp(await jsonObject(mcpPath, "INVALID_MCP"), directory, mcpPath).mcpServers : {};
+  for (const [serverName, server] of Object.entries(own)) {
+    if (Object.hasOwn(servers, serverName)) throw new AlpError("INVALID_MCP", `${mcpPath}: MCP server '${serverName}' is also named in ${configPath}`);
+    servers[serverName] = server;
+  }
+  const runtime = {
+    ...config.provider !== void 0 ? { provider: config.provider } : {},
+    ...config.model !== void 0 ? { model: config.model } : {},
+    ...config.thinking !== void 0 ? { reasoning: config.thinking } : {},
+    ...projectRuntime
+  };
+  return validateResolvedAgent({
+    name,
+    projectRoot: root,
+    source: source.source,
+    instructions: { project: await optionalText(path.join(root, "ALP.md")) ?? "", agent: instructions },
+    skills,
+    hooks,
+    runtime,
+    projectRuntime: { ...projectRuntime },
+    ...config.mode !== void 0 ? { mode: config.mode } : {},
+    ...config.description !== void 0 ? { description: config.description } : {},
+    ...typeof config.context === "number" ? { context: config.context } : {},
+    ...config.autocompact !== void 0 ? { autocompact: config.autocompact } : {},
+    mcp: { mcpServers: servers }
+  });
+}
+export {
+  AlpError2 as AlpError,
+  BUILTIN_AGENTS,
+  LIBRARY_KINDS,
+  agentSources,
+  builtinText,
+  discoverAgents,
+  jsonObject,
+  libraryEntries,
+  optionalText,
+  resolveAgent
+};

package/dist/safe-path.d.ts

@@ -0,0 +1,2 @@
+/** Preflight static repository paths. Does not isolate concurrent same-user processes. */
+export function assertNoSymlinks(directory: any, relative: any): Promise<void>;

package/dist/safe-path.js

@@ -0,0 +1,24 @@
+// packages/core/src/safe-path.js
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { AlpError } from "./errors.js";
+async function assertNoSymlinks(directory, relative) {
+  const root = path.resolve(directory);
+  const target = path.resolve(root, relative);
+  const tail = path.relative(root, target);
+  if (tail === ".." || tail.startsWith(`..${path.sep}`) || path.isAbsolute(tail)) {
+    throw new AlpError("UNSAFE_PATH", "Path escapes its scope");
+  }
+  let current = root;
+  for (const part of ["", ...tail.split(path.sep).filter(Boolean)]) {
+    if (part) current = path.join(current, part);
+    const info = await lstat(current).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+    if (!info) return;
+    if (info.isSymbolicLink()) throw new AlpError("UNSAFE_PATH", `Refusing symlink in scoped path: ${current}`);
+  }
+}
+export {
+  assertNoSymlinks
+};

package/dist/shell.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Starts `command` through the platform's shell: /bin/sh -c in its own process group, or on
+ * Windows cmd.exe /d /s /c with the line quoted whole (cmd strips only the outermost quotes,
+ * and Node would otherwise escape the quotes inside it).
+ * @param {string} command
+ * @param {import('node:child_process').SpawnOptions} options
+ */
+export function spawnShell(command: string, options: import("node:child_process").SpawnOptions): import("child_process").ChildProcess;
+/**
+ * Signals a command `spawnShell` started and everything it started. Windows has no signals and
+ * cmd.exe's children outlive it, so there the whole tree is ended at once by the first signal
+ * and no cleanup runs.
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {NodeJS.Signals} name
+ */
+export function signalShell(child: import("node:child_process").ChildProcess, name: NodeJS.Signals): void;

package/dist/shell.js

@@ -0,0 +1,22 @@
+// packages/core/src/shell.js
+import { execFile, spawn } from "node:child_process";
+function spawnShell(command, options) {
+  if (process.platform !== "win32") return spawn("/bin/sh", ["-c", command], { ...options, detached: true });
+  return spawn(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", `"${command}"`], { ...options, windowsHide: true, windowsVerbatimArguments: true });
+}
+function signalShell(child, name) {
+  if (process.platform === "win32") {
+    if (name === "SIGTERM") execFile("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true }, () => {
+    });
+    return;
+  }
+  try {
+    process.kill(-child.pid, name);
+  } catch {
+    child.kill(name);
+  }
+}
+export {
+  signalShell,
+  spawnShell
+};

package/dist/state-schema.d.ts

@@ -0,0 +1,9 @@
+export const STATE_SCHEMA: number;
+export const OLDEST_STATE_SCHEMA: number;
+export function stateDir(home: string): string;
+export function schemaFile(home: string): string;
+export function migrationFile(home: string): string;
+export type StateSchemaInfo = { schema: number; fresh: boolean; marked: boolean; by?: string };
+export function readStateSchema(home: string): Promise<StateSchemaInfo>;
+export function assertStateSupported(info: StateSchemaInfo, home: string): StateSchemaInfo;
+export function writeStateSchema(home: string, schema: number, by?: string): Promise<void>;

package/dist/state-schema.js

@@ -0,0 +1,54 @@
+// packages/core/src/state-schema.js
+import { readdir, readFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { AlpError } from "./errors.js";
+import { writeAtomic } from "./atomic.js";
+var STATE_SCHEMA = 2;
+var OLDEST_STATE_SCHEMA = 1;
+var stateDir = (home) => path.join(home, "state");
+var schemaFile = (home) => path.join(stateDir(home), "schema.json");
+var migrationFile = (home) => path.join(stateDir(home), "migration.json");
+var DATA = ["sessions", "timeline", "receipts"];
+async function readStateSchema(home) {
+  let text;
+  try {
+    text = await readFile(schemaFile(home), "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    for (const name of DATA) {
+      const entries = await readdir(path.join(stateDir(home), name)).catch((error2) => {
+        if (error2?.code === "ENOENT") return [];
+        throw error2;
+      });
+      if (entries.some((entry) => !entry.endsWith(".tmp"))) return { schema: 1, fresh: false, marked: false };
+    }
+    return { schema: STATE_SCHEMA, fresh: true, marked: false };
+  }
+  let marker;
+  try {
+    marker = JSON.parse(text);
+  } catch {
+  }
+  if (!marker || !Number.isSafeInteger(marker.schema) || marker.schema < 1) {
+    throw new AlpError("STATE_SCHEMA_UNREADABLE", `${schemaFile(home)} does not name a state schema; ALP does not open state whose format it cannot tell. Restore a backup, or put back the file`);
+  }
+  return { schema: marker.schema, fresh: false, marked: true, ...typeof marker.by === "string" ? { by: marker.by } : {} };
+}
+function assertStateSupported(info, home) {
+  if (info.schema <= STATE_SCHEMA) return info;
+  throw new AlpError("STATE_SCHEMA_TOO_NEW", `${stateDir(home)} holds state schema ${info.schema}${info.by ? `, written by ${info.by}` : ""}; this ALP knows schema ${STATE_SCHEMA} at most and leaves it untouched. Run that ALP version or a newer one, or replace it with a backup made for this version: alp restore FILE --replace-newer (docs/alp/data-recovery.md)`);
+}
+async function writeStateSchema(home, schema, by) {
+  await mkdir(stateDir(home), { recursive: true, mode: 448 });
+  await writeAtomic(schemaFile(home), JSON.stringify({ schema, by, at: (/* @__PURE__ */ new Date()).toISOString() }) + "\n");
+}
+export {
+  OLDEST_STATE_SCHEMA,
+  STATE_SCHEMA,
+  assertStateSupported,
+  migrationFile,
+  readStateSchema,
+  schemaFile,
+  stateDir,
+  writeStateSchema
+};

package/dist/task-rows.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A project's tasks as task screens show them (ALPD §22): readiness, what blocks or waits,
+ * approvals for the user, handoffs and progress. Used by the Paseo Tasks panel and the web app.
+ * @param {string} projectRoot
+ */
+export function taskRows(projectRoot: string): Promise<{
+    tasks: {
+        createdAt: string;
+        updatedAt: string;
+        progress?: {
+            done: number;
+            total: number;
+        } | undefined;
+        paths?: string[] | undefined;
+        labels?: string[] | undefined;
+        description?: string | undefined;
+        closed?: {
+            at: string;
+            summary?: string | undefined;
+            reason: import("./tasks.js").CloseReason;
+        } | undefined;
+        handoff?: {
+            agent?: string | undefined;
+            outcome: string;
+            summary: string;
+        } | undefined;
+        approvals?: {
+            gate: string;
+            note: string;
+        }[] | undefined;
+        waits?: string[] | undefined;
+        blockedBy?: string[] | undefined;
+        ready: boolean;
+        assignee?: string | undefined;
+        parent?: string | undefined;
+        id: string;
+        title: string;
+        type: import("./tasks.js").TaskType;
+        priority: number;
+        status: import("./tasks.js").TaskStatus;
+        rev: number;
+    }[];
+    unreadable: {
+        file: string;
+        error: string;
+    }[];
+}>;

package/dist/task-rows.js

@@ -0,0 +1,45 @@
+// packages/core/src/task-rows.js
+import { gatesOf, loadTasks, readyTasks, summarize } from "./tasks.js";
+async function taskRows(projectRoot) {
+  const { tasks, errors } = await loadTasks(projectRoot);
+  const ready = new Set(readyTasks(tasks).map((task) => task.id));
+  const children = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    if (!task.parent) continue;
+    const count = children.get(task.parent) ?? { done: 0, total: 0 };
+    count.total += 1;
+    if (task.status === "closed") count.done += 1;
+    children.set(task.parent, count);
+  }
+  const rows = tasks.map((task) => {
+    const row = summarize(task, tasks);
+    const approvals = task.status === "closed" ? [] : task.gates.filter((gate) => gate.kind === "human" && !gate.resolved).map((gate) => ({ gate: gate.id, note: gate.note ?? "" }));
+    const waits = task.status === "closed" ? [] : gatesOf(task, tasks);
+    return {
+      id: task.id,
+      title: task.title,
+      type: task.type,
+      priority: task.priority,
+      status: task.status,
+      rev: task.rev,
+      ...task.parent ? { parent: task.parent } : {},
+      ...task.assignee ? { assignee: task.assignee.agent } : {},
+      ready: ready.has(task.id),
+      ...row.blockedBy ? { blockedBy: row.blockedBy } : {},
+      ...waits.length ? { waits } : {},
+      ...approvals.length ? { approvals } : {},
+      ...task.handoff ? { handoff: { outcome: String(task.handoff.outcome), summary: String(task.handoff.summary ?? ""), ...typeof task.handoff.agent === "string" ? { agent: task.handoff.agent } : {} } } : {},
+      ...task.closed ? { closed: { reason: task.closed.reason, ...task.closed.summary ? { summary: task.closed.summary } : {}, at: task.closed.at } } : {},
+      ...task.description ? { description: task.description.slice(0, 4e3) } : {},
+      ...task.labels.length ? { labels: task.labels } : {},
+      ...task.paths.length ? { paths: task.paths } : {},
+      ...children.has(task.id) ? { progress: children.get(task.id) } : {},
+      createdAt: task.createdAt,
+      updatedAt: task.updatedAt
+    };
+  });
+  return { tasks: rows, unreadable: errors };
+}
+export {
+  taskRows
+};

package/dist/tasks.d.ts

@@ -0,0 +1,128 @@
+export type TaskType = 'task' | 'bug' | 'feature' | 'chore' | 'epic';
+export type TaskStatus = 'open' | 'in_progress' | 'review' | 'closed';
+export type CloseReason = 'done' | 'wontfix' | 'duplicate' | 'superseded';
+
+export type TaskLogEntry = { at: string; by: string; event: string; [detail: string]: unknown };
+
+export type Task = {
+  id: string;
+  rev: number;
+  title: string;
+  description: string;
+  type: TaskType;
+  priority: number;
+  status: TaskStatus;
+  labels: string[];
+  paths: string[];
+  parent: string | null;
+  blockedBy: string[];
+  discoveredFrom: string | null;
+  related: string[];
+  gates: TaskGate[];
+  assignee: { agent: string; session?: string; assignment?: string; pid?: number; pidStartedAt?: number; epoch?: string; since: string } | null;
+  handoff: Record<string, unknown> | null;
+  /** The last run of the project's verify commands for this task. */
+  verified: TaskVerification | null;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  closed: { at: string; by: string; reason: CloseReason; summary?: string; unverified?: string } | null;
+  log: TaskLogEntry[];
+  compacted?: { at: string; by: string; chars: number };
+  /** Where an imported task came from. */
+  external?: { system: string; id: string };
+  /** The formula step a task was poured from. */
+  step?: { formula: string; id: string; human?: boolean };
+  /** The formula an epic was poured from. */
+  formula?: { name: string; version?: number; vars: Record<string, string> };
+};
+
+export type GateKind = 'human' | 'timer' | 'gh:pr' | 'gh:run';
+export type TaskGate = {
+  id: string;
+  kind: GateKind;
+  note?: string;
+  until?: string;
+  repo?: string;
+  ref?: string;
+  at: string;
+  by: string;
+  resolved?: { at: string; by: string; note?: string };
+};
+
+export type TaskInput = {
+  title?: string;
+  description?: string;
+  type?: TaskType;
+  priority?: number | string;
+  labels?: string[];
+  paths?: string[];
+  parent?: string | null;
+  blockedBy?: string[];
+  related?: string[];
+  discoveredFrom?: string | null;
+};
+
+export type TaskLinks = { blockedBy?: string[]; related?: string[]; parent?: string };
+export type TaskSummary = Pick<Task, 'id' | 'title' | 'type' | 'priority' | 'status'> & { labels?: string[]; parent?: string; blockedBy?: string[]; gates?: string[]; assignee?: string; verified?: 'passed' | 'failed' | 'skipped' };
+type WriteOptions = { ifRev?: number };
+
+export const TASKS_DIR: string;
+export const TASK_TYPES: TaskType[];
+export const TASK_STATUSES: TaskStatus[];
+export const CLOSE_REASONS: CloseReason[];
+export const GATE_KINDS: GateKind[];
+export const MAX_GATES: number;
+export const TITLE_CHARS: number;
+export const DESCRIPTION_CHARS: number;
+export const NOTE_CHARS: number;
+export const MAX_LABELS: number;
+export const MAX_PATHS: number;
+export const MAX_LINKS: number;
+
+export function isTaskId(id: unknown): id is string;
+export function tasksDir(projectRoot: string): string;
+export function loadTasks(projectRoot: string): Promise<{ tasks: Task[]; errors: Array<{ file: string; error: string }> }>;
+export function getTask(projectRoot: string, id: string): Promise<Task>;
+export function blockersOf(task: Task, tasks: Task[]): string[];
+export function readyTasks(tasks: Task[]): Task[];
+export function childrenOf(id: string, tasks: Task[]): Task[];
+export function summarize(task: Task, tasks: Task[]): TaskSummary;
+export function listTasks(tasks: Task[], filter?: { status?: TaskStatus; label?: string; parent?: string; all?: boolean }): Task[];
+export function createTask(projectRoot: string, input: TaskInput & { title: string }, by: string): Promise<Task>;
+export function updateTask(projectRoot: string, id: string, input: TaskInput & { note?: string }, by: string, options?: WriteOptions): Promise<Task>;
+export function linkTask(projectRoot: string, id: string, change: { add?: TaskLinks; remove?: TaskLinks }, by: string, options?: WriteOptions): Promise<Task>;
+export function startTask(projectRoot: string, id: string, assignee: { agent: string; session?: string; assignment?: string; pid?: number; pidStartedAt?: number; epoch?: string }, by: string, options?: WriteOptions): Promise<Task>;
+export function closeTask(projectRoot: string, id: string, close: { reason?: CloseReason; summary?: string; unverified?: string }, by: string, options?: WriteOptions): Promise<Task>;
+export function verificationFailed(task: Task): boolean;
+export function recordVerification(projectRoot: string, id: string, verification: { passed: boolean; where?: string; commands?: Array<{ step: string; command: string; exitCode: number; ms: number; output?: string; timedOut?: boolean }>; skipped?: string }, by: string): Promise<Task>;
+export function reopenTask(projectRoot: string, id: string, reopen: { note?: string }, by: string, options?: WriteOptions): Promise<Task>;
+export function submitTask(projectRoot: string, id: string, submit: { assignment: string; handoff: { outcome: string; summary: string } & Record<string, unknown>; agent: string }, by: string): Promise<Task>;
+export function releaseOrphans(projectRoot: string, isOrphan: (assignee: { agent: string; assignment: string; pid?: number; pidStartedAt?: number; epoch?: string }) => boolean, describe: (assignee: { agent: string; assignment: string }) => Promise<string | undefined>, by: string): Promise<Task[]>;
+export function orphanedEntry(task: Task): { at: string; by: string; event: 'orphaned'; agent: string; assignment: string; note?: string } | undefined;
+export function retakeTask(projectRoot: string, id: string, assignee: { assignment: string; pid?: number; pidStartedAt?: number; epoch?: string }, by: string): Promise<Task>;
+export function releaseTask(projectRoot: string, id: string, release: { assignment: string; handoff?: ({ outcome: string; summary: string } & Record<string, unknown>) | null; agent: string; reason: string }, by: string): Promise<Task>;
+export function taskDigest(tasks: Task[], errors?: Array<{ file: string; error: string }>): string;
+export function startRefusal(task: Task, tasks: Task[]): string | undefined;
+export function gateOpen(gate: TaskGate, now?: number): boolean;
+export function describeGate(gate: TaskGate): string;
+export function gatesOf(task: Task, tasks: Task[]): string[];
+export function addGate(projectRoot: string, id: string, gate: { kind: GateKind; note?: string; until?: string; ref?: string | number }, by: string): Promise<Task>;
+export function resolveGate(projectRoot: string, id: string, gateId: string, resolve: { by: string; note?: string; remove?: boolean; ifRev?: number }): Promise<Task>;
+export function checkGates(projectRoot: string, gh: (args: string[], options: { cwd: string }) => Promise<string>): Promise<{ cleared: Array<{ task: string; gate: string; detail: string }>; pending: Array<{ task: string; gate: string; detail: string }>; errors: Array<{ task: string; gate: string; error: string }> }>;
+export function compactTasks(projectRoot: string, options: { days?: number; dryRun?: boolean }, by: string): Promise<Array<{ id: string; before: number; after: number }>>;
+export type TaskBatch = {
+  tasks: Task[];
+  errors: Array<{ file: string; error: string }>;
+  add(input: TaskInput & { title: string }, by: string, options?: { id?: string; createdAt?: string; event?: string; details?: Record<string, unknown>; extra?: Partial<Task> & Record<string, unknown> }): Task;
+  touch(task: Task, by?: string, event?: string, details?: Record<string, unknown>): void;
+  link(task: Task, kind: 'blockedBy' | 'parent' | 'discoveredFrom' | 'related', other: string): string | undefined;
+};
+export function batch<T>(projectRoot: string, work: (batch: TaskBatch) => T | Promise<T>, options?: { dryRun?: boolean }): Promise<T>;
+
+export type TaskVerification = { at: string; by: string; passed: boolean; where?: string; commands: Array<{ step: string; command: string; exitCode: number; ms: number; output?: string; timedOut?: boolean }>; skipped?: string };
+
+export type EpicReport = { id: string; title: string; status: TaskStatus; tasks: number; closed: number; durationMs: number; reworked: number; verification: { passed: number; failed: number; skipped: number; none: number }; unverified: string[]; lines: string[]; text: string };
+export function epicReport(id: string, tasks: Task[]): EpicReport;
+export function landedParents(tasks: Task[]): Array<{ task: Task; children: number }>;
+export function withTaskLock<T>(projectRoot: string, work: () => Promise<T>): Promise<T>;