@visual-z/xeno 0.1.0

package/src/store/observations.ts

@@ -0,0 +1,181 @@
+/** Store complete observations while keeping only a bounded preview in memory. */
+import { createReadStream } from "node:fs";
+import { open, mkdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import type { ArtifactRef } from "../core/events.ts";
+import { blobFilePath, verifyBlob } from "./blobs.ts";
+
+/** Byte pages keep very large single-line observations retrievable as well. */
+export async function readObservation(dir: string, sha256: string, offset: number, limit: number): Promise<{
+  sha256: string; bytes: number; offset: number; next: number | null; text: string; base64: string;
+}> {
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1) throw new Error("invalid observation page");
+  if (!await verifyBlob(dir, sha256)) throw new Error(`missing observation ${sha256}`);
+  const file = await open(blobFilePath(dir, sha256), "r");
+  try {
+    const bytes = (await file.stat()).size;
+    const buffer = Buffer.alloc(Math.min(limit, Math.max(0, bytes - offset)));
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, offset);
+    const data = buffer.subarray(0, bytesRead);
+    return { sha256, bytes, offset, next: offset + bytesRead < bytes ? offset + bytesRead : null,
+      text: data.toString("utf8"), base64: data.toString("base64") };
+  } finally { await file.close(); }
+}
+
+/**
+ * After the shell exits, how long silence must last before capture stops.
+ *
+ * A background child (`server &`) inherits the pipes, so waiting for EOF
+ * waits for the server -- the call then blocks until the timeout and the
+ * timeout kills the server with the group. Operational choice, not measured:
+ * long enough for buffered output of the exited shell to arrive, short
+ * enough that a background start costs nothing noticeable. pi uses the same
+ * idle-grace shape (`utils/child-process.ts`).
+ */
+const EXIT_IDLE_MS = 100;
+/** Hard bound after exit for a background child that never goes quiet. */
+const EXIT_DRAIN_MS = 1_000;
+
+/**
+ * Both streams into one file in arrival order.
+ *
+ * A build that prints progress on stdout and the error on stderr only makes
+ * sense interleaved; appending all of stderr after all of stdout (the previous
+ * shape) separates each error from the step that produced it. Writes are
+ * serialized on one handle, so interleaving happens at chunk granularity --
+ * the same granularity a terminal shows.
+ *
+ * Capture ends at EOF on both streams, or once `exited` has resolved and the
+ * streams have gone idle. Ending early cancels the readers only; it signals
+ * no process, so a detached background child keeps running.
+ */
+async function spoolMerged(
+  dir: string, streams: readonly ReadableStream<Uint8Array>[], exited: Promise<number>,
+): Promise<string> {
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, `.${randomUUID()}.stream`);
+  const file = await open(path, "wx", 0o600);
+  const readers = streams.map((stream) => stream.getReader());
+  let queue: Promise<unknown> = Promise.resolve();
+  let exitedAt: number | undefined;
+  let idle: ReturnType<typeof setTimeout> | undefined;
+  let drain: ReturnType<typeof setTimeout> | undefined;
+  const stop = () => { for (const reader of readers) reader.cancel().catch(() => {}); };
+  const armIdle = () => {
+    if (exitedAt === undefined) return;
+    clearTimeout(idle);
+    idle = setTimeout(stop, EXIT_IDLE_MS);
+  };
+  void exited.then(() => { exitedAt = performance.now(); armIdle(); drain = setTimeout(stop, EXIT_DRAIN_MS); }, () => {});
+  try {
+    const drained = await Promise.allSettled(readers.map(async (reader) => {
+      for (;;) {
+        const result = await reader.read();
+        if (result.done) return;
+        armIdle();
+        queue = queue.then(() => file.writeFile(result.value));
+        await queue;
+      }
+    }));
+    await queue;
+    for (const result of drained) if (result.status === "rejected") throw result.reason;
+  } catch (error) { await file.close(); await rm(path, { force: true }); throw error; }
+  finally {
+    clearTimeout(idle); clearTimeout(drain);
+    for (const reader of readers) reader.releaseLock();
+  }
+  await file.close();
+  return path;
+}
+
+/** Last `limit` bytes of a stream, in O(limit) memory however long it runs. */
+class TailWindow {
+  private readonly parts: Uint8Array[] = [];
+  private size = 0;
+  private readonly limit: number;
+  constructor(limit: number) { this.limit = limit; }
+  push(chunk: Uint8Array): void {
+    if (this.limit === 0) return;
+    const part = chunk.byteLength > this.limit ? chunk.slice(chunk.byteLength - this.limit) : chunk.slice();
+    this.parts.push(part);
+    this.size += part.byteLength;
+    while (this.size - this.parts[0]!.byteLength >= this.limit) this.size -= this.parts.shift()!.byteLength;
+  }
+  bytes(): Uint8Array {
+    const all = Buffer.concat(this.parts);
+    return all.subarray(Math.max(0, all.byteLength - this.limit));
+  }
+}
+
+export interface ArchivedObservation {
+  ref: ArtifactRef;
+  /** First `previewBytes` bytes, decoded; kept for callers that only page from the start. */
+  preview: string;
+  /** First and last `previewBytes` bytes, for a head-and-tail view. */
+  head: Uint8Array;
+  tail: Uint8Array;
+}
+
+export async function archiveObservation(
+  dir: string, source: AsyncIterable<Uint8Array>, previewBytes: number,
+): Promise<ArchivedObservation> {
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, `.${randomUUID()}.observation`);
+  const file = await open(path, "wx", 0o600);
+  const hash = createHash("sha256");
+  let bytes = 0;
+  let kept = 0;
+  const preview: Uint8Array[] = [];
+  const tail = new TailWindow(previewBytes);
+  try {
+    try {
+      for await (const chunk of source) {
+        hash.update(chunk);
+        bytes += chunk.byteLength;
+        if (kept < previewBytes) {
+          const part = chunk.slice(0, previewBytes - kept);
+          preview.push(part); kept += part.byteLength;
+        }
+        tail.push(chunk);
+        await file.writeFile(chunk);
+      }
+      await file.sync();
+    } finally { await file.close(); }
+    const sha256 = hash.digest("hex");
+    const destination = blobFilePath(dir, sha256);
+    await mkdir(join(dir, sha256.slice(0, 2)), { recursive: true });
+    await rename(path, destination);
+    const shard = await open(join(dir, sha256.slice(0, 2)), "r");
+    try { await shard.sync(); } finally { await shard.close(); }
+    const head = Buffer.concat(preview);
+    return {
+      ref: { sha256, path: destination, bytes },
+      preview: new TextDecoder().decode(head, { stream: kept < bytes }),
+      head, tail: tail.bytes(),
+    };
+  } finally { await rm(path, { force: true }); }
+}
+
+/**
+ * The artifact is `exit N\n` followed by the merged output. Nothing that varies
+ * run to run (wall time) belongs here: the artifact digest is the D9 novelty
+ * key, and a timestamp in it would make every rerun look like new evidence.
+ */
+export async function captureCommandObservation(
+  dir: string, stdout: ReadableStream<Uint8Array>, stderr: ReadableStream<Uint8Array>,
+  exited: Promise<number>, previewBytes: number,
+): Promise<ArchivedObservation & { exit: number; prefixBytes: number }> {
+  const merged = await spoolMerged(dir, [stdout, stderr], exited);
+  try {
+    const exit = await exited;
+    const prefix = new TextEncoder().encode(`exit ${exit}\n`);
+    async function* combined(): AsyncGenerator<Uint8Array> {
+      yield prefix;
+      for await (const chunk of createReadStream(merged)) yield chunk as Uint8Array;
+    }
+    return { ...await archiveObservation(dir, combined(), previewBytes), exit, prefixBytes: prefix.byteLength };
+  } finally {
+    await rm(merged, { force: true });
+  }
+}

package/src/store/query-source.ts

@@ -0,0 +1,44 @@
+/** N.3: bind a complete calculation input to confined files and content digests. */
+import { lstat, open } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+
+// Assumed working-memory safety budget for the synchronous pure query engine.
+// Exceeding it is an explicit refusal, never a truncated calculation.
+export const MAX_QUERY_SOURCE_BYTES = 32 * 1024 * 1024;
+export async function readQuerySources(root: string, paths: unknown): Promise<{
+  text: string; sources: { path: string; sha256: string; bytes: number }[];
+}> {
+  if (!Array.isArray(paths) || paths.length === 0 || paths.length > 1024 || paths.some((p) => typeof p !== "string" || !p)) throw new Error("query paths must contain 1..1024 file paths in concatenation order");
+  const sources: { path: string; sha256: string; bytes: number }[] = [];
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  for (const path of paths as string[]) {
+    const absolute = resolve(root, path), rel = relative(root, absolute);
+    if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) throw new Error("query path escapes workspace");
+    let current = resolve(root);
+    for (const part of rel.split(sep)) {
+      current = resolve(current, part);
+      if ((await lstat(current)).isSymbolicLink()) throw new Error("query does not follow symbolic links");
+    }
+    const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const info = await file.stat();
+      if (!info.isFile()) throw new Error("query source must be a regular file");
+      if (bytes + info.size > MAX_QUERY_SOURCE_BYTES) throw new Error("query source exceeds 32 MiB resource budget; use a smaller input");
+      const hash = createHash("sha256");
+      let sourceBytes = 0;
+      for (;;) {
+        const buffer = Buffer.alloc(Math.min(65536, MAX_QUERY_SOURCE_BYTES - bytes + 1));
+        const result = await file.read(buffer, 0, buffer.length, null);
+        if (result.bytesRead === 0) break;
+        bytes += result.bytesRead; sourceBytes += result.bytesRead;
+        if (bytes > MAX_QUERY_SOURCE_BYTES) throw new Error("query source grew past resource budget");
+        const data = buffer.subarray(0, result.bytesRead); hash.update(data); chunks.push(data);
+      }
+      sources.push({ path: rel.split(sep).join("/"), sha256: hash.digest("hex"), bytes: sourceBytes });
+    } finally { await file.close(); }
+  }
+  return { text: new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)), sources };
+}

package/src/store/recovery.ts

@@ -0,0 +1,39 @@
+/** Complete an explicitly logged cut; never infer a user's chosen branch. */
+import type { Cursor } from "./log.ts";
+import { closeNode, digestNode, initNode, listNodes, nodePath, readNode, readManifest, writeCursor } from "./log.ts";
+import { replayContext } from "./replay.ts";
+import { deriveHandoff } from "../core/derive.ts";
+import { boundHandoff } from "../core/history.ts";
+
+export async function recoverCut(dir: string, cursor: Cursor): Promise<Cursor> {
+  const source = await readNode(dir, cursor.node);
+  const cut = source.events.at(-1);
+  if (cut?.t !== "cut" || cut.next_node === undefined) return cursor;
+  const rebuilt = await replayContext(dir, cursor.node);
+  const manifest = await readManifest(dir);
+  if (!manifest.nodes.some((n) => n.node === cursor.node)) {
+    const handoff = deriveHandoff({
+      prev: rebuilt.fullHandoff, depth: rebuilt.depth, events: rebuilt.events,
+      config: { maxUserTurns: Infinity, maxUserTurnBytes: Infinity },
+      self: { node: cursor.node, log_ref: nodePath(dir, cursor.node), sha256: await digestNode(dir, cursor.node) },
+    });
+    await closeNode(dir, cursor.node,
+      cut.handoff_tokens === undefined ? handoff : boundHandoff(handoff, cut.handoff_tokens), source.events.length, cut.at);
+  }
+  const successor = await readNode(dir, cut.next_node);
+  if (successor.header === null) {
+    await initNode(dir, cut.next_node, {
+      node: cursor.node, log_ref: nodePath(dir, cursor.node), sha256: await digestNode(dir, cursor.node),
+    }, cut.at, "handoff");
+  } else if (successor.header.parent?.node !== cursor.node || successor.header.basis !== "handoff") {
+    throw new Error(`INTEGRITY: cut successor ${cut.next_node} belongs to another transition`);
+  }
+  const nodes = await listNodes(dir);
+  const next: Cursor = {
+    ...cursor, node: cut.next_node,
+    next_node: Math.max(cursor.next_node, cut.next_node + 1, ...nodes.map((n) => n + 1)),
+    model: cut.next_model ?? cursor.model, updated_at: cut.at,
+  };
+  await writeCursor(dir, next);
+  return next;
+}

package/src/store/replay.ts

@@ -0,0 +1,63 @@
+/**
+ * Rebuild the effective context, including every preceding handoff boundary.
+ *
+ * D3/G.5: physical node files are storage units, not context units. Resume,
+ * rewind and cut must agree on inherited events and accumulated state.
+ */
+import { deriveHandoff } from "../core/derive.ts";
+import type { Handoff } from "../core/handoff.ts";
+import type { LogEvent } from "../core/events.ts";
+import { boundHandoff } from "../core/history.ts";
+import { retainedContext } from "../core/context-window.ts";
+import { digestNode, nodePath, readAncestry, readManifest, type Manifest } from "./log.ts";
+
+export interface ReplayedContext {
+  /** Events not already included in fullHandoff; use these for derivation. */
+  events: LogEvent[];
+  /** Model view also includes explicitly retained original exchanges. */
+  contextEvents: LogEvent[];
+  handoff: Handoff | null;
+  /** Full derivation state; only the bounded handoff is sent to the model. */
+  fullHandoff: Handoff | null;
+  depth: number;
+}
+
+export async function replayContext(
+  dir: string, node: number, manifest?: Manifest,
+): Promise<ReplayedContext> {
+  const index = manifest ?? await readManifest(dir);
+  const seen = new Set<number>();
+  // Iterative even across handoff boundaries: a valid long session must not
+  // consume the JS call stack just because it has many compacted segments.
+  const parts: { node: number; events: LogEvent[]; depth: number }[] = [];
+  let current: number | null = node;
+  while (current !== null) {
+    if (seen.has(current)) throw new Error(`CYCLE: handoff ancestry revisits node ${current}`);
+    seen.add(current);
+    const walk = await readAncestry(dir, current, index);
+    if (!walk.ok) throw new Error(`${walk.error.code}: ${walk.error.detail}`);
+    parts.push({ node: current, events: walk.events, depth: walk.visited.length });
+    current = walk.basis?.node ?? null;
+  }
+  let handoff: Handoff | null = null;
+  let depth = 0;
+  let carried: Handoff | null = null;
+  let retained: LogEvent[] = [];
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const part = parts[i]!;
+    depth += part.depth;
+    const contextEvents = [...retained, ...part.events];
+    if (i === 0) return { handoff: carried, fullHandoff: handoff, depth, events: part.events, contextEvents };
+    handoff = deriveHandoff({
+      prev: handoff, depth, events: part.events,
+      config: { maxUserTurns: Infinity, maxUserTurnBytes: Infinity },
+      self: { node: part.node, log_ref: nodePath(dir, part.node), sha256: await digestNode(dir, part.node) },
+    });
+    const tail = part.events.at(-1);
+    carried = tail?.t === "cut" && tail.handoff_tokens !== undefined
+      ? boundHandoff(handoff, tail.handoff_tokens) : handoff;
+    retained = tail?.t === "cut" && tail.retained_from !== undefined
+      ? retainedContext(contextEvents, tail.retained_from) : [];
+  }
+  throw new Error(`MISSING_HEADER: no context for node ${node}`);
+}

package/src/store/resources.ts

@@ -0,0 +1,361 @@
+/**
+ * Discover and read UI resources: settings, theme, keybindings, skills,
+ * prompt templates.
+ *
+ * I/O lives here; validation is core. A corrupt file is a diagnostic plus
+ * a fallback, never a throw -- startup has to survive a missing comma.
+ *
+ * Project-level files follow the same trust rule as `.xeno/settings.json`.
+ * Theme and keymap are UI state and are not logged.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { configDir, readJsonFile, writeJsonFile, settingsPath } from "./config.ts";
+import { projectSettingsPath } from "./trust.ts";
+import { parseSkill, type Skill } from "../core/skills.ts";
+import { parsePromptTemplate, type PromptTemplate } from "../core/prompts.ts";
+import {
+  builtinTheme,
+  parseTheme,
+  type Theme,
+} from "../core/theme.ts";
+import {
+  defaultKeymap,
+  parseKeymap,
+  type Keymap,
+} from "../core/keymap.ts";
+import {
+  defaultSettings,
+  explicitSettings,
+  mergeSettings,
+  parseSettings,
+  settingsToWrite,
+  type Settings,
+} from "../core/settings.ts";
+
+export interface LoadUiOptions {
+  readonly workspace: string;
+  readonly trusted: boolean;
+  /** `--theme <name|path>`, wins over settings. */
+  readonly theme?: string;
+}
+
+export interface UiResources {
+  readonly settings: Settings;
+  readonly theme: Theme;
+  readonly keymap: Keymap;
+  readonly diagnostics: readonly string[];
+  readonly userOverrides: Partial<Settings>;
+}
+
+export function keybindingsPath(): string {
+  return join(configDir(), "keybindings.json");
+}
+
+export function projectKeybindingsPath(workspace: string): string {
+  return join(workspace, ".xeno", "keybindings.json");
+}
+
+export function userThemePath(name: string): string {
+  return join(configDir(), "themes", `${name}.json`);
+}
+
+export async function loadUiResources(opts: LoadUiOptions): Promise<UiResources> {
+  const diagnostics: string[] = [];
+
+  const userRead = await readJsonFile<unknown>(settingsPath());
+  if (userRead.error) diagnostics.push(userRead.error);
+  const userParsed = parseSettings(userRead.value);
+  diagnostics.push(...userParsed.diagnostics);
+  const userOverrides = explicitSettings(userRead.value, userParsed.settings);
+
+  let projectSettings: Settings = {};
+  if (opts.trusted) {
+    const projectRead = await readJsonFile<unknown>(projectSettingsPath(opts.workspace));
+    if (projectRead.error) diagnostics.push(projectRead.error);
+    if (projectRead.value !== null) {
+      const parsed = parseSettings(projectRead.value);
+      diagnostics.push(...parsed.diagnostics);
+      projectSettings = parsed.settings;
+    }
+  }
+
+  const cli: Settings = opts.theme !== undefined && opts.theme.length > 0 ? { theme: opts.theme } : {};
+  const settings = mergeSettings({
+    builtin: defaultSettings(),
+    user: userParsed.settings,
+    project: projectSettings,
+    cli,
+  });
+
+  const theme = await resolveTheme(settings.theme ?? "dark", diagnostics);
+  const keymap = await resolveKeymap(opts.workspace, opts.trusted, diagnostics);
+
+  return { settings, theme, keymap, diagnostics, userOverrides };
+}
+
+export async function writeUserSettings(overrides: Partial<Settings>): Promise<void> {
+  const { value, error } = await readJsonFile<unknown>(settingsPath());
+  const prev =
+    error === null && typeof value === "object" && value !== null && !Array.isArray(value)
+      ? (value as { readonly [k: string]: unknown })
+      : {};
+  const next = { ...prev, ...settingsToWrite(overrides) };
+  await writeJsonFile(settingsPath(), next, false);
+}
+
+async function resolveTheme(spec: string, diagnostics: string[]): Promise<Theme> {
+  if (spec === "dark" || spec === "light") return builtinTheme(spec);
+
+  const path = looksLikePath(spec) ? spec : userThemePath(spec);
+  const { value, error } = await readJsonFile<unknown>(path);
+  if (error) {
+    diagnostics.push(error);
+    return builtinTheme("dark");
+  }
+  if (value === null) {
+    diagnostics.push(`theme "${spec}" not found at ${path}; using dark`);
+    return builtinTheme("dark");
+  }
+  const parsed = parseTheme(value);
+  diagnostics.push(...parsed.diagnostics);
+  return parsed.theme;
+}
+
+async function resolveKeymap(workspace: string, trusted: boolean, diagnostics: string[]): Promise<Keymap> {
+  let map = defaultKeymap();
+
+  const userRead = await readJsonFile<unknown>(keybindingsPath());
+  if (userRead.error) diagnostics.push(userRead.error);
+  if (userRead.value !== null) {
+    map = parseKeymap(userRead.value, map);
+  }
+
+  if (trusted) {
+    const projectRead = await readJsonFile<unknown>(projectKeybindingsPath(workspace));
+    if (projectRead.error) diagnostics.push(projectRead.error);
+    if (projectRead.value !== null) {
+      map = parseKeymap(projectRead.value, map);
+    }
+  }
+
+  diagnostics.push(...map.diagnostics);
+  return map;
+}
+
+function looksLikePath(spec: string): boolean {
+  return spec.includes("/") || spec.includes("\\") || spec.endsWith(".json");
+}
+
+export interface LoadTextOptions {
+  readonly workspace: string;
+  readonly configDir: string;
+  readonly trusted: boolean;
+  readonly noSkills?: boolean;
+  readonly noPromptTemplates?: boolean;
+  /** `--skill <path>`, loaded even when `noSkills` is set. */
+  readonly skillPaths?: readonly string[];
+  /** `--prompt-template <path>`, loaded even when discovery is off. */
+  readonly promptTemplatePaths?: readonly string[];
+}
+
+export interface LoadedTextResources {
+  readonly skills: readonly Skill[];
+  readonly prompts: readonly PromptTemplate[];
+  readonly diagnostics: readonly string[];
+}
+
+/**
+ * Discover skills and prompt templates. Project directories load only when
+ * trusted, matching `.xeno/settings.json`. A bad file is named and skipped.
+ */
+export async function loadTextResources(opts: LoadTextOptions): Promise<LoadedTextResources> {
+  const diagnostics: string[] = [];
+  const skills = new Map<string, Skill>();
+  const prompts = new Map<string, PromptTemplate>();
+
+  const addSkill = (skill: Skill): void => {
+    const prev = skills.get(skill.name);
+    if (prev !== undefined) {
+      diagnostics.push(
+        `skill "${skill.name}" from ${skill.filePath} replaces ${prev.filePath}`,
+      );
+    }
+    skills.set(skill.name, skill);
+  };
+  const addPrompt = (prompt: PromptTemplate): void => {
+    const prev = prompts.get(prompt.name);
+    if (prev !== undefined) {
+      diagnostics.push(
+        `prompt template "${prompt.name}" from ${prompt.filePath} replaces ${prev.filePath}`,
+      );
+    }
+    prompts.set(prompt.name, prompt);
+  };
+
+  if (opts.noSkills !== true) {
+    await loadSkillsFromDir(join(opts.configDir, "skills"), addSkill, diagnostics);
+    if (opts.trusted) {
+      await loadSkillsFromDir(join(opts.workspace, ".xeno", "skills"), addSkill, diagnostics);
+    }
+  }
+  for (const path of opts.skillPaths ?? []) {
+    await loadSkillsFromPath(path, addSkill, diagnostics);
+  }
+
+  if (opts.noPromptTemplates !== true) {
+    await loadPromptsFromDir(join(opts.configDir, "prompts"), addPrompt, diagnostics);
+    if (opts.trusted) {
+      await loadPromptsFromDir(join(opts.workspace, ".xeno", "prompts"), addPrompt, diagnostics);
+    }
+  }
+  for (const path of opts.promptTemplatePaths ?? []) {
+    await loadPromptsFromPath(path, addPrompt, diagnostics);
+  }
+
+  return {
+    skills: [...skills.values()],
+    prompts: [...prompts.values()],
+    diagnostics,
+  };
+}
+
+async function loadSkillsFromDir(
+  dir: string,
+  add: (skill: Skill) => void,
+  diagnostics: string[],
+): Promise<void> {
+  const files: string[] = [];
+  await collectSkillFiles(dir, files, diagnostics);
+  for (const file of files) await absorbSkill(file, add, diagnostics);
+}
+
+async function loadSkillsFromPath(
+  path: string,
+  add: (skill: Skill) => void,
+  diagnostics: string[],
+): Promise<void> {
+  const info = await statKind(path);
+  if (info === "missing") {
+    diagnostics.push(`skill path not found: ${path}`);
+    return;
+  }
+  if (info === "file") {
+    await absorbSkill(path, add, diagnostics);
+    return;
+  }
+  await loadSkillsFromDir(path, add, diagnostics);
+}
+
+async function loadPromptsFromDir(
+  dir: string,
+  add: (prompt: PromptTemplate) => void,
+  diagnostics: string[],
+): Promise<void> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isNotFound(err)) return;
+    diagnostics.push(`${dir}: ${errMessage(err)}`);
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) continue;
+    await absorbPrompt(join(dir, entry.name), add, diagnostics);
+  }
+}
+
+async function loadPromptsFromPath(
+  path: string,
+  add: (prompt: PromptTemplate) => void,
+  diagnostics: string[],
+): Promise<void> {
+  const info = await statKind(path);
+  if (info === "missing") {
+    diagnostics.push(`prompt template not found: ${path}`);
+    return;
+  }
+  if (info === "dir") {
+    await loadPromptsFromDir(path, add, diagnostics);
+    return;
+  }
+  await absorbPrompt(path, add, diagnostics);
+}
+
+async function collectSkillFiles(dir: string, out: string[], diagnostics: string[]): Promise<void> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isNotFound(err)) return;
+    diagnostics.push(`${dir}: ${errMessage(err)}`);
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) await collectSkillFiles(full, out, diagnostics);
+    else if (entry.isFile() && entry.name === "SKILL.md") out.push(full);
+  }
+}
+
+async function absorbSkill(
+  filePath: string,
+  add: (skill: Skill) => void,
+  diagnostics: string[],
+): Promise<void> {
+  const text = await readUtf8(filePath);
+  if (text === null) {
+    diagnostics.push(`${filePath}: could not read`);
+    return;
+  }
+  const parsed = parseSkill({
+    filePath,
+    parentDirName: basename(dirname(filePath)),
+    text,
+  });
+  diagnostics.push(...parsed.diagnostics);
+  if (parsed.skill) add(parsed.skill);
+}
+
+async function absorbPrompt(
+  filePath: string,
+  add: (prompt: PromptTemplate) => void,
+  diagnostics: string[],
+): Promise<void> {
+  const text = await readUtf8(filePath);
+  if (text === null) {
+    diagnostics.push(`${filePath}: could not read`);
+    return;
+  }
+  const parsed = parsePromptTemplate({ filePath, text });
+  diagnostics.push(...parsed.diagnostics);
+  if (parsed.template) add(parsed.template);
+}
+
+async function readUtf8(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+async function statKind(path: string): Promise<"file" | "dir" | "missing"> {
+  try {
+    const info = await stat(path);
+    return info.isDirectory() ? "dir" : "file";
+  } catch {
+    return "missing";
+  }
+}
+
+function isNotFound(err: unknown): boolean {
+  return (err as { code?: string }).code === "ENOENT";
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}