@agentshouse/kit 0.0.1 → 0.1.0-alpha.10

package/src/agents.js

@@ -0,0 +1,504 @@
+import { spawn } from "node:child_process";
+import { readFile, readdir, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  compiledContract,
+  offeredSessionOptions,
+  releaseOrder,
+  servedRelease,
+  verifyCommandAdapter,
+} from "./adapter.js";
+import { inheritedEnvironment } from "./command.js";
+import {
+  ADAPTER_KINDS,
+  AGENT_HOME,
+  AGENT_INSTALL_TIMEOUT_MS,
+  AGENT_RELEASES_HOME,
+  AGENT_SIGNED_IN_TIMEOUT_MS,
+  AGENT_STATE_FILE,
+  AGENT_UPDATE_INTERVAL_MS,
+  GUIDED_LOGIN_OUTPUT_MAX_BYTES,
+  WORKER_INHERITED_ENVIRONMENT,
+} from "./contract.js";
+import { readConfiguration } from "./configuration.js";
+import { desiredAgents, maintainControl, openSession, reportAgentCapabilities } from "./house.js";
+import { KitRefusal } from "./refusal.js";
+import { readNote, writeNote, writeText } from "./state.js";
+
+export function agentDirectory(directory, kind) {
+  return join(directory, AGENT_HOME, kind);
+}
+
+function statePath(directory, kind) {
+  return join(agentDirectory(directory, kind), AGENT_STATE_FILE);
+}
+
+function releaseDirectory(directory, kind, release) {
+  return join(agentDirectory(directory, kind), AGENT_RELEASES_HOME, release);
+}
+
+export function releaseCommand(directory, kind, release, contract) {
+  return [join(releaseDirectory(directory, kind, release), "node_modules", ".bin", contract.binary)];
+}
+
+function adapterCommand(directory, kind, release, contract) {
+  return [...releaseCommand(directory, kind, release, contract), ...contract.arguments];
+}
+
+export async function readAgentState(directory, kind) {
+  const held = await readNote(statePath(directory, kind), null);
+  if (held === null) return { release: null, held: null, checkedAt: null };
+  return {
+    release: typeof held.release === "string" ? held.release : null,
+    held: typeof held.held === "string" ? held.held : null,
+    checkedAt: typeof held.checked_at === "string" ? held.checked_at : null,
+  };
+}
+
+async function writeAgentState(directory, kind, state) {
+  await writeNote(statePath(directory, kind), {
+    release: state.release,
+    held: state.held,
+    checked_at: state.checkedAt,
+  });
+}
+
+export async function installedAgentCommand(directory, kind) {
+  const contract = compiledContract(kind);
+  const state = await readAgentState(directory, kind);
+  if (state.release === null) {
+    throw new KitRefusal(
+      "kit_agent_not_installed",
+      `${kind}; run kit agents update to install ${contract.release.package}`,
+    );
+  }
+  return adapterCommand(directory, kind, state.release, contract);
+}
+
+function ran(command, argumentVector, options) {
+  return new Promise((resolve) => {
+    const child = spawn(command, argumentVector, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: options.stdio ?? ["ignore", "ignore", "ignore"],
+      timeout: options.timeoutMs,
+    });
+    child.on("error", () => resolve(1));
+    child.on("close", (status) => resolve(status ?? 1));
+  });
+}
+
+function npmReleases(package_) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("npm", ["view", package_, "versions", "--json"], {
+      env: inheritedEnvironment(WORKER_INHERITED_ENVIRONMENT),
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: AGENT_INSTALL_TIMEOUT_MS,
+    });
+    let answered = "";
+    child.stdout.on("data", (chunk) => {
+      answered += chunk.toString("utf8");
+    });
+    child.on("error", () => reject(new KitRefusal("kit_agent_releases_unavailable", package_)));
+    child.on("close", (status) => {
+      if (status !== 0) {
+        reject(new KitRefusal("kit_agent_releases_unavailable", package_));
+        return;
+      }
+      try {
+        const listed = JSON.parse(answered);
+        resolve(Array.isArray(listed) ? listed : [listed]);
+      } catch {
+        reject(new KitRefusal("kit_agent_releases_unavailable", package_));
+      }
+    });
+  });
+}
+
+async function npmInstall(package_, release, directory) {
+  const status = await ran(
+    "npm",
+    ["install", "--prefix", directory, "--no-save", "--no-audit", "--no-fund", `${package_}@${release}`],
+    {
+      env: inheritedEnvironment(WORKER_INHERITED_ENVIRONMENT),
+      timeoutMs: AGENT_INSTALL_TIMEOUT_MS,
+    },
+  );
+  if (status !== 0) throw new KitRefusal("kit_agent_install_failed", `${package_}@${release}`);
+}
+
+export function servedCandidate(releases, minimum) {
+  const served = releases.filter((release) => servedRelease(release, minimum));
+  if (served.length === 0) return null;
+  return served.reduce((held, release) => (releaseOrder(release, held) > 0 ? release : held));
+}
+
+function dueForCandidate(state, at) {
+  if (state.checkedAt === null) return true;
+  return at.getTime() - new Date(state.checkedAt).getTime() >= AGENT_UPDATE_INTERVAL_MS;
+}
+
+async function proved(directory, kind, release, contract, dependencies) {
+  const command = adapterCommand(directory, kind, release, contract);
+  try {
+    await verifyCommandAdapter(
+      {
+        command,
+        arguments: [],
+        environment: {},
+        workingDirectory: directory,
+      },
+      contract,
+      dependencies.adapterInitializeTimeoutMs,
+      `${kind} candidate release ${release}`,
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function declaredSetting(document, table, key) {
+  const dotted = new RegExp(`^\\s*${`${table}.${key}`.replace(/\./gu, "\\.")}\\s*=`, "mu");
+  if (dotted.test(document)) return true;
+  const header = new RegExp(`^[^\\S\\n]*\\[${table.replace(/\./gu, "\\.")}\\][^\\S\\n]*$`, "mu");
+  const found = header.exec(document);
+  if (found === null) return false;
+  const section = document.slice(found.index + found[0].length).split(/^[^\S\n]*\[/mu)[0];
+  return new RegExp(`^[^\\S\\n]*${key}[^\\S\\n]*=`, "mu").test(section);
+}
+
+export async function applyAgentSettings(contract, dependencies = {}) {
+  const home = dependencies.home ?? homedir();
+  for (const setting of contract.settings) {
+    const path = join(home, setting.file);
+    const named = setting.setting.split(".");
+    const key = named.at(-1);
+    const table = named.slice(0, -1).join(".");
+    let document;
+    try {
+      document = await readFile(path, "utf8");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw new KitRefusal("kit_agent_setting_unwritable", path);
+      document = null;
+    }
+    if (document !== null && declaredSetting(document, table, key)) continue;
+    const declaration = `[${table}]\n${key} = ${setting.value}\n`;
+    await writeText(
+      path,
+      document === null ? declaration : `${document.replace(/\n*$/u, "\n")}\n${declaration}`,
+    );
+  }
+}
+
+async function advanceAgent(options, kind, dependencies) {
+  const contract = compiledContract(kind);
+  const directory = options.directory;
+  const state = await readAgentState(directory, kind);
+  const at = options.at ?? new Date();
+  if (state.release !== null && !options.forced && !dueForCandidate(state, at)) {
+    return { kind, release: state.release, held: state.held, acted: "held-release" };
+  }
+  const releases = await (dependencies.agentReleases ?? npmReleases)(contract.release.package);
+  const candidate = servedCandidate(releases, contract.release.minimum);
+  if (candidate === null) {
+    throw new KitRefusal(
+      "kit_agent_release_unavailable",
+      `${contract.release.package} serves no ${contract.release.minimum} or later release`,
+    );
+  }
+  if (candidate === state.release || candidate === state.held) {
+    await writeAgentState(directory, kind, { ...state, checkedAt: at.toISOString() });
+    return { kind, release: state.release, held: state.held, acted: "held-release" };
+  }
+  await (dependencies.installAgent ?? npmInstall)(
+    contract.release.package,
+    candidate,
+    releaseDirectory(directory, kind, candidate),
+  );
+  if (!(await proved(directory, kind, candidate, contract, dependencies))) {
+    await rm(releaseDirectory(directory, kind, candidate), { recursive: true, force: true });
+    await writeAgentState(directory, kind, {
+      release: state.release,
+      held: candidate,
+      checkedAt: at.toISOString(),
+    });
+    return { kind, release: state.release, held: candidate, acted: "held-candidate" };
+  }
+  await applyAgentSettings(contract, dependencies);
+  await writeAgentState(directory, kind, {
+    release: candidate,
+    held: null,
+    checkedAt: at.toISOString(),
+  });
+  if (state.release !== null && state.release !== candidate) {
+    await rm(releaseDirectory(directory, kind, state.release), { recursive: true, force: true });
+  }
+  return { kind, release: candidate, held: null, acted: "installed-release" };
+}
+
+export async function updateDeclaredAgent(options, kind, dependencies) {
+  try {
+    return await advanceAgent(options, kind, dependencies);
+  } catch (error) {
+    if (error instanceof KitRefusal && error.code === "kit_command_cancelled") throw error;
+    const state = await readAgentState(options.directory, kind);
+    return {
+      kind,
+      release: state.release,
+      held: state.held,
+      acted: "update-failed",
+      failure: error instanceof KitRefusal ? error.code : error.message,
+    };
+  }
+}
+
+export async function updateDeclaredAgents(options, configuration, dependencies = {}) {
+  const updated = [];
+  for (const kind of configuration.agents) {
+    updated.push(await updateDeclaredAgent(options, kind, dependencies));
+  }
+  return updated;
+}
+
+export async function removeUndeclaredAgents(directory, wanted, keep = false) {
+  const home = join(directory, AGENT_HOME);
+  let entries;
+  try {
+    entries = await readdir(home, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const retained = [];
+  for (const entry of entries) {
+    if (!wanted.includes(entry.name)) {
+      if (keep && ADAPTER_KINDS.includes(entry.name)) retained.push(entry.name);
+      else await rm(join(home, entry.name), { recursive: true, force: true });
+    }
+  }
+  return retained;
+}
+
+export async function reconcileAgentKinds(
+  options,
+  session,
+  configuration,
+  dependencies = {},
+  signal = session.signal,
+  state = {},
+) {
+  const selected = { ...configuration, agents: await desiredAgents(session, signal) };
+  state.onDesired?.(selected.agents);
+  const newlyWanted = selected.agents.filter((kind) => !state.lastDesired?.includes(kind));
+  const retained = await removeUndeclaredAgents(options.directory, selected.agents, state.busy);
+  const pointerKinds = state.busy
+    ? (
+        await Promise.all(
+          newlyWanted.map(async (kind) =>
+            (await readAgentState(options.directory, kind)).release === null ? kind : null,
+          ),
+        )
+      ).filter((kind) => kind !== null)
+    : newlyWanted;
+  const updated = await updateDeclaredAgents(
+    { directory: options.directory, at: dependencies.now?.(), forced: state.forced },
+    { ...selected, agents: state.pointer ? pointerKinds : selected.agents },
+    dependencies,
+  );
+  const readiness = await agentReadiness(
+    { directory: options.directory },
+    { ...selected, agents: [...selected.agents, ...retained] },
+    dependencies,
+  );
+  await reportAgentCapabilities(session, readiness.agents, signal);
+  return { selected, updated, reported: readiness.agents, refused: readiness.refused, retained };
+}
+
+export async function agentSignedIn(directory, kind, dependencies = {}) {
+  const contract = compiledContract(kind);
+  const state = await readAgentState(directory, kind);
+  if (state.release === null) return false;
+  if (!Array.isArray(contract.signedIn)) {
+    try {
+      const initialized = await verifyCommandAdapter(
+        {
+          command: adapterCommand(directory, kind, state.release, contract),
+          arguments: [],
+          environment: {},
+          workingDirectory: directory,
+        },
+        contract,
+        dependencies.adapterInitializeTimeoutMs,
+        `agent ${kind} sign-in readiness`,
+      );
+      const method = initialized?._meta?.[contract.signedIn.initializeMeta];
+      return typeof method === "string" && method.length > 0;
+    } catch {
+      return false;
+    }
+  }
+  const [command] = releaseCommand(directory, kind, state.release, contract);
+  const status = await (dependencies.runAgentCommand ?? ran)(command, [...contract.signedIn], {
+    cwd: directory,
+    env: inheritedEnvironment(WORKER_INHERITED_ENVIRONMENT),
+    timeoutMs: AGENT_SIGNED_IN_TIMEOUT_MS,
+  });
+  return status === 0;
+}
+
+async function offeredOptions(directory, kind, release, dependencies) {
+  if (release === null) return { options: null, refused: null };
+  const contract = compiledContract(kind);
+  const command = adapterCommand(directory, kind, release, contract);
+  try {
+    const options = await offeredSessionOptions(
+      { command, arguments: [], environment: {}, workingDirectory: directory },
+      contract,
+      {
+        initialize: dependencies.adapterInitializeTimeoutMs,
+        session: dependencies.adapterSessionTimeoutMs,
+      },
+      `agent ${kind} adapter ${JSON.stringify(command[0])}`,
+    );
+    return { options, refused: null };
+  } catch (refusal) {
+    if (!(refusal instanceof KitRefusal) || refusal.code !== "kit_adapter_contract_mismatch") {
+      throw refusal;
+    }
+    return { options: null, refused: refusal };
+  }
+}
+
+export async function agentReadiness(options, configuration, dependencies = {}) {
+  const agents = [];
+  let refused = null;
+  for (const kind of configuration.agents) {
+    const state = await readAgentState(options.directory, kind);
+    const offered = await offeredOptions(options.directory, kind, state.release, dependencies);
+    refused ??= offered.refused;
+    agents.push({
+      kind,
+      contract_version: compiledContract(kind).version,
+      release: state.release,
+      signed_in: await agentSignedIn(options.directory, kind, dependencies),
+      hold: state.held === null ? null : { candidate: state.held },
+      options: offered.options,
+    });
+  }
+  return { agents, refused };
+}
+
+export async function updateAgents(options, dependencies = {}) {
+  const configuration = await readConfiguration(options.configuration);
+  const session = await openSession(options, dependencies);
+  return maintainControl(
+    session,
+    async (signal) => {
+      const result = await reconcileAgentKinds(
+        options,
+        session,
+        configuration,
+        dependencies,
+        signal,
+        { forced: true },
+      );
+      return { updated: result.updated, reported: result.reported };
+    },
+    options.signal,
+  );
+}
+
+export async function signInAgent(options, dependencies = {}) {
+  const configuration = await readConfiguration(options.configuration);
+  const session = await openSession(options, dependencies);
+  return maintainControl(
+    session,
+    async (signal) => {
+      const selected = { ...configuration, agents: await desiredAgents(session, signal) };
+      if (!selected.agents.includes(options.kind)) {
+        throw new KitRefusal("kit_agent_undeclared", options.kind);
+      }
+      const status = await signInDeclaredAgent(options, options.kind, dependencies);
+      const { agents } = await agentReadiness(options, selected, dependencies);
+      await reportAgentCapabilities(session, agents, signal);
+      return { status, reported: agents };
+    },
+    options.signal,
+  );
+}
+
+export async function signInDeclaredAgent(options, kind, dependencies = {}) {
+  const contract = compiledContract(kind);
+  const state = await readAgentState(options.directory, kind);
+  if (state.release === null) {
+    throw new KitRefusal(
+      "kit_agent_not_installed",
+      `${kind}; run kit agents update to install ${contract.release.package}`,
+    );
+  }
+  const [command] = releaseCommand(options.directory, kind, state.release, contract);
+  return (dependencies.runAgentCommand ?? ran)(command, [...contract.signIn], {
+    cwd: options.directory,
+    env: inheritedEnvironment(WORKER_INHERITED_ENVIRONMENT),
+    stdio: "inherit",
+  });
+}
+
+export function guidedAgentLogin(directory, kind, recipe) {
+  const contract = compiledContract(kind);
+  return async ({ present, signal }) => {
+    const state = await readAgentState(directory, kind);
+    const [command] = releaseCommand(directory, kind, state.release, contract);
+    const child = spawn(command, [...contract.signIn], {
+      cwd: directory,
+      env: inheritedEnvironment(WORKER_INHERITED_ENVIRONMENT),
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    const exited = new Promise((resolve) => {
+      child.once("error", () => resolve(1));
+      child.once("close", (status) => resolve(status ?? 1));
+    });
+    const stop = () => child.kill("SIGTERM");
+    signal.addEventListener("abort", stop, { once: true });
+    const presentation = new AbortController();
+    let output = "";
+    let answered = "";
+    let rejected = false;
+    let delivery = null;
+    const observe = (chunk) => {
+      if (delivery !== null) {
+        if (rejected || answered.length >= GUIDED_LOGIN_OUTPUT_MAX_BYTES) return;
+        answered = `${answered}${chunk.toString("utf8")}`.slice(0, GUIDED_LOGIN_OUTPUT_MAX_BYTES);
+        if (!recipe.rejected(answered)) return;
+        rejected = true;
+        stop();
+        return;
+      }
+      if (output.length >= GUIDED_LOGIN_OUTPUT_MAX_BYTES) return;
+      output = `${output}${chunk.toString("utf8")}`.slice(0, GUIDED_LOGIN_OUTPUT_MAX_BYTES);
+      const ceremony = recipe.ceremony(output);
+      if (ceremony === null) return;
+      delivery = present(ceremony, AbortSignal.any([signal, presentation.signal]))
+        .then((collected) => {
+          const input = recipe.input(collected);
+          if (input !== null) child.stdin.write(input);
+        })
+        .catch(() => undefined);
+    };
+    child.stdout.on("data", observe);
+    child.stderr.on("data", observe);
+    child.stdin.on("error", () => undefined);
+    try {
+      const status = await exited;
+      if (rejected) return "failed";
+      if (signal.aborted) return "cancelled";
+      return status === 0 ? "ready" : "failed";
+    } finally {
+      signal.removeEventListener("abort", stop);
+      presentation.abort();
+      await delivery;
+    }
+  };
+}

package/src/apply.js

@@ -0,0 +1,29 @@
+import { appliedDocument, readConfiguration } from "./configuration.js";
+import { commitSessionStartHook, planSessionStartHook } from "./hook.js";
+import { applyDeclared, maintainControl, openSession } from "./house.js";
+import { KitRefusal } from "./refusal.js";
+
+function appliedState(value) {
+  if (!Number.isInteger(value?.schedules)) throw new KitRefusal("kit_apply_rejected");
+  return { schedules: value.schedules };
+}
+
+export async function apply(options, dependencies = {}) {
+  const configuration = await readConfiguration(options.configuration);
+  const plan = await planSessionStartHook(
+    { directory: options.directory, configuration: options.configuration },
+    configuration.clients,
+    options.signal,
+  );
+  const session = await openSession(options, dependencies);
+  return maintainControl(
+    session,
+    async (signal) => {
+      const answer = await applyDeclared(session, appliedDocument(configuration), signal);
+      const applied = appliedState(answer);
+      const reconciled = await commitSessionStartHook(plan, answer.session_start_hook, signal);
+      return { ...applied, hooks: reconciled.installed, removed: reconciled.removed };
+    },
+    options.signal,
+  );
+}

package/src/attach.js

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+import { readBindings } from "./binding.js";
+import { inheritedEnvironment } from "./command.js";
+import { WORKER_ATTACH_ENVIRONMENT } from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+import { sessionPresent, workerRuntime } from "./tmux.js";
+
+function attachment(argv) {
+  return new Promise((resolve, reject) => {
+    const attached = spawn(argv[0], argv.slice(1), {
+      env: inheritedEnvironment(WORKER_ATTACH_ENVIRONMENT),
+      stdio: "inherit",
+    });
+    attached.once("error", () => reject(new KitRefusal("kit_command_unavailable", argv[0])));
+    attached.once("close", (status) => resolve(status ?? 1));
+  });
+}
+
+function chosenBinding(bindings, session) {
+  if (session === null) {
+    if (bindings.length === 1) return bindings[0];
+    throw new KitRefusal(
+      bindings.length === 0 ? "kit_attach_unbound" : "kit_attach_ambiguous",
+      bindings.length === 0
+        ? "this installation supervises no WorkerSession"
+        : bindings.map((binding) => binding.tmux).join(", "),
+    );
+  }
+  const bound = bindings.find((binding) => binding.tmux === session);
+  if (bound === undefined) throw new KitRefusal("kit_attach_unbound", session);
+  return bound;
+}
+
+export async function attachSession(options, dependencies = {}) {
+  const runtime = workerRuntime(options.directory, dependencies.tmux ?? "tmux");
+  const binding = chosenBinding(await readBindings(options.directory), options.session);
+  if (!(await sessionPresent(runtime, binding.tmux))) {
+    throw new KitRefusal("kit_attach_absent", binding.tmux);
+  }
+  const status = await (dependencies.attach ?? attachment)([
+    runtime.tmux,
+    "-L",
+    runtime.namespace,
+    "-f",
+    runtime.configuration,
+    "attach-session",
+    "-r",
+    "-t",
+    `=${binding.tmux}`,
+  ]);
+  return { session: binding.tmux, status };
+}

package/src/binding.js

@@ -0,0 +1,90 @@
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { KitRefusal } from "./refusal.js";
+import { readNote, writeNote } from "./state.js";
+import { reportedNote, retainedReport } from "./terminal.js";
+
+const TMUX_SESSION = /^[a-f0-9]{16}$/;
+
+function bindingDirectory(directory) {
+  return join(directory, "state", "sessions");
+}
+
+function bindingPath(directory, tmux) {
+  if (!TMUX_SESSION.test(tmux)) throw new KitRefusal("kit_binding_name_invalid", tmux);
+  return join(bindingDirectory(directory), `${tmux}.json`);
+}
+
+export async function writeBinding(directory, binding) {
+  const reported = binding.reported ?? null;
+  await writeNote(bindingPath(directory, binding.tmux), {
+    installation: directory,
+    run: binding.run,
+    session: binding.session,
+    tmux: binding.tmux,
+    socket: binding.socket,
+    nonce: binding.nonce,
+    conversation: binding.conversation === true,
+    owner_stop: binding.ownerStop ?? null,
+    sealed: binding.sealed === null || binding.sealed === undefined
+      ? null
+      : { operation: binding.sealed.operation, blocks: binding.sealed.blocks },
+    reported: reported === null ? null : reportedNote(reported),
+  });
+}
+
+export async function removeBinding(directory, tmux) {
+  await rm(bindingPath(directory, tmux), { force: true });
+}
+
+function retainedSeal(stored) {
+  if (stored === null || stored === undefined) return null;
+  if (typeof stored !== "object" || Array.isArray(stored)) return undefined;
+  if (typeof stored.operation !== "string" || stored.operation.length === 0) return undefined;
+  if (!Array.isArray(stored.blocks) || stored.blocks.length === 0) return undefined;
+  return { operation: stored.operation, blocks: stored.blocks };
+}
+
+function completeBinding(directory, stored) {
+  if (typeof stored !== "object" || stored === null || Array.isArray(stored)) return null;
+  const named = [stored.run, stored.session, stored.tmux, stored.socket, stored.nonce];
+  if (named.some((value) => typeof value !== "string" || value.length === 0)) return null;
+  if (stored.installation !== directory) return null;
+  if (!TMUX_SESSION.test(stored.tmux)) return null;
+  if (stored.owner_stop !== null && typeof stored.owner_stop !== "string") return null;
+  const sealed = retainedSeal(stored.sealed);
+  if (sealed === undefined) return null;
+  const reported = retainedReport(stored.reported);
+  if (reported === undefined) return null;
+  return {
+    run: stored.run,
+    session: stored.session,
+    tmux: stored.tmux,
+    socket: stored.socket,
+    nonce: stored.nonce,
+    conversation: stored.conversation === true,
+    ownerStop: stored.owner_stop,
+    sealed,
+    reported,
+  };
+}
+
+export async function readBindings(directory) {
+  let present;
+  try {
+    present = await readdir(bindingDirectory(directory));
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw new KitRefusal("kit_state_unreadable", bindingDirectory(directory));
+  }
+  const bindings = [];
+  for (const name of present.filter((entry) => entry.endsWith(".json")).sort()) {
+    const path = join(bindingDirectory(directory), name);
+    const stored = await readNote(path, null);
+    if (stored === null) continue;
+    const binding = completeBinding(directory, stored);
+    if (binding === null || `${binding.tmux}.json` !== name) continue;
+    bindings.push(binding);
+  }
+  return bindings;
+}