@agentshouse/kit 0.0.1 → 0.1.0-alpha.2

package/bin/kit.js

@@ -0,0 +1,1023 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { connectHouse, storedEnvironment, storedHouse } from "../src/login.js";
+import { apply } from "../src/apply.js";
+import { captureSource, resetSource, retrySourceOriginals, sourceStatus } from "../src/source.js";
+import { setupEnvironment } from "../src/setup.js";
+import { signInConnector } from "../src/connector-login.js";
+import { attachSession } from "../src/attach.js";
+import { runResident, runWorkers } from "../src/worker.js";
+import { openSession, releaseControl } from "../src/house.js";
+import { GOOGLE_OAUTH_CLIENT } from "../src/instance/google.js";
+import { reportHost } from "../src/host.js";
+import { signInAgent, updateAgents } from "../src/agents.js";
+import { serveWorkspaces } from "../src/workspace.js";
+import { captureRepository } from "../src/repository.js";
+import { bootstrap, pull, rebootstrap, submit } from "../src/sync.js";
+import { formatMount, formatUnmount, mountPackage, unmountSubtree } from "../src/mount.js";
+import { emitMigratorPackage, readMigratorPackage } from "../src/migrator.js";
+import { declaredMigrator, readConfiguration } from "../src/configuration.js";
+import { resolveEnvironment } from "../src/command.js";
+import { formatAttachmentGet, formatAttachmentUpload, getAttachment, uploadAttachment } from "../src/original.js";
+import {
+  connectPersonalBot,
+  disconnectPersonalBot,
+  serveTelegramGateway,
+} from "../src/telegram.js";
+import { formatCommandError, KitRefusal } from "../src/refusal.js";
+
+const USAGE =
+  "usage: kit <login|resident|credential|setup|apply|agents|source|repository|worker|sync|migrate|attachment|host|workspace|telegram> ...";
+const LOGIN_USAGE =
+  "usage: kit login [--house <url>] [--environment <uuid>] [--manual|--host-browser]";
+const HOST_USAGE = "usage: kit host report [--house <url>] [--config <path>]";
+const AGENTS_USAGE =
+  "usage: kit agents update [--house <url>] [--config <path>] | kit agents sign-in <kind> [--house <url>] [--config <path>]";
+const WORKSPACE_USAGE = "usage: kit workspace host [--house <url>] [--config <path>] [--passes <count>]";
+const SOURCE_USAGE =
+  "usage: kit source <capture|reset|retry-files> <instance> [service] [--house <url>] [--config <path>]\n" +
+  "       kit source status <instance> [service] [--config <path>]\n" +
+  "       kit source sign-in <instance> [--config <path>]";
+const SETUP_USAGE = "usage: kit setup [--house <url>] [--config <path>]";
+const REPOSITORY_USAGE =
+  "usage: kit repository capture <checkout> --room <room> --source-handle <handle> [--house <url>]";
+const WORKER_USAGE =
+  "usage: kit worker run [--house <url>] [--config <path>] | kit worker attach [<session>]";
+const SYNC_USAGE =
+  "usage: kit sync <bootstrap|pull|rebootstrap|submit> ...";
+const SYNC_BOOTSTRAP_USAGE =
+  "usage: kit sync bootstrap <directory> [--house <url>] --prefix <path> [--prefix <path> ...]";
+const SYNC_PULL_USAGE = "usage: kit sync pull <directory> [--house <url>]";
+const SYNC_REBOOTSTRAP_USAGE = "usage: kit sync rebootstrap <directory> [--house <url>]";
+const SYNC_SUBMIT_USAGE =
+  "usage: kit sync submit <directory> [--house <url>] [--changes <path>]";
+const MIGRATE_USAGE = "usage: kit migrate <emit|mount|unmount|run> ...";
+const MIGRATE_EMIT_USAGE =
+  "usage: kit migrate emit <migrator> --package <directory> [--config <path>]";
+const MIGRATE_MOUNT_USAGE =
+  "usage: kit migrate mount <package> [--house <url>] --subtree <path>";
+const MIGRATE_UNMOUNT_USAGE =
+  "usage: kit migrate unmount <subtree> [--house <url>] [--confirm <subtree>]";
+const MIGRATE_RUN_USAGE =
+  "usage: kit migrate run <migrator> [--house <url>] --subtree <path> --package <directory> [--config <path>]";
+const ATTACHMENT_USAGE = "usage: kit attachment <upload|get> ...";
+const ATTACHMENT_UPLOAD_USAGE =
+  "usage: kit attachment upload <file> [--house <url>] (--room <ref> | --private) [--name <name>] [--media-type <type>]";
+const ATTACHMENT_GET_USAGE =
+  "usage: kit attachment get [--house <url>] --attachment <at_ref> (--room <ref> | --private) [--output <path>]";
+const TELEGRAM_USAGE =
+  "usage: kit telegram <connect|disconnect> [--house <url>]\n" +
+  "       kit telegram serve [--house <url>] [--passes <count>]";
+
+function declared(argv, accepted, positionals, options = {}) {
+  const repeated = options.repeated ?? [];
+  const exact = options.exact === true;
+  const values = {};
+  const lists = {};
+  for (const name of repeated) lists[name] = [];
+  const rest = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (!argument.startsWith("--")) {
+      rest.push(argument);
+      continue;
+    }
+    if (!accepted.includes(argument)) throw new Error(`unknown argument: ${argument}`);
+    if (argument === "--manual" || (options.flags ?? []).includes(argument)) {
+      values[argument] = true;
+      continue;
+    }
+    index += 1;
+    if (argv[index] === undefined) throw new Error(`${argument} expects a value`);
+    if (repeated.includes(argument)) lists[argument].push(argv[index]);
+    else values[argument] = argv[index];
+  }
+  if (exact) {
+    if (rest.length !== positionals) {
+      throw new Error(`unknown argument: ${rest[positionals] ?? "missing directory"}`);
+    }
+  } else if (rest.length > positionals) {
+    throw new Error(`unknown argument: ${rest[positionals]}`);
+  }
+  return { values, lists, rest };
+}
+
+function write(line) {
+  process.stdout.write(`${line}\n`);
+}
+
+function builtGoogleOAuthClient() {
+  if (GOOGLE_OAUTH_CLIENT === null) {
+    throw new KitRefusal("google_oauth_client_unconfigured", "run npm run build");
+  }
+  return GOOGLE_OAUTH_CLIENT;
+}
+
+async function selectedHouse(values, directory) {
+  return storedHouse(directory, false, values["--house"]);
+}
+
+async function runLogin(args, directory) {
+  const { values } = declared(args, ["--house", "--manual", "--host-browser", "--environment"], 0, { flags: ["--host-browser"] });
+  if (values["--manual"] && values["--host-browser"]) throw new Error(LOGIN_USAGE);
+  const house = await storedHouse(directory, true, values["--house"]);
+  const presentation = values["--manual"] === true ? "manual" : "loopback";
+  await connectHouse({
+    house,
+    presentation,
+    directory,
+    hostBrowser: values["--host-browser"] === true,
+    hostname: process.env.HOUSE_KIT_HOSTNAME,
+    ...(values["--environment"] === undefined ? {} : { environment: values["--environment"] }),
+  });
+}
+
+async function runCredentialCheck(args, directory) {
+  const { values } = declared(args, ["--house"], 0, { exact: true });
+  if (await storedEnvironment(directory) === null) throw new KitRefusal("kit_environment_invalid", "no enrolled Environment id");
+  const house = await selectedHouse(values, directory);
+  let session;
+  try {
+    session = await openSession({ house, directory });
+  } catch (error) {
+    if (error instanceof KitRefusal && error.code === "environment_control_lease_active") {
+      write("Stored Kit authority is accepted; its Environment already has an active control lease.");
+      return;
+    }
+    throw error;
+  }
+  await releaseControl(session, { required: true });
+  write("Stored Kit authority is accepted.");
+}
+
+async function runResidentCommand(args, directory) {
+  const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
+  const house = await selectedHouse(values, directory);
+  const cancellation = new AbortController();
+  const stop = () => cancellation.abort();
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  try {
+    await runResident({ house, directory, configuration: values["--config"] ?? join(directory, "kit.json"), signal: cancellation.signal });
+  } finally {
+    process.removeListener("SIGINT", stop);
+    process.removeListener("SIGTERM", stop);
+  }
+}
+
+async function runSetup(args, directory) {
+  const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(SETUP_USAGE);
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  let setup;
+  try {
+    setup = await setupEnvironment(
+      {
+        house,
+        directory,
+        configuration: values["--config"] ?? join(directory, "kit.json"),
+        signal: cancellation.signal,
+      },
+      { googleOAuthClient: builtGoogleOAuthClient },
+    );
+  } finally {
+    process.removeListener("SIGINT", cancel);
+  }
+  if (setup === null) {
+    write("House requests no setup for this Environment.");
+    return;
+  }
+  for (const module of setup.modules) {
+    write(
+      `${module.category} ${module.name}: ${module.status}${module.reason === null ? "" : ` (${module.reason})`}`,
+    );
+  }
+  if (setup.modules.some((module) => module.status === "needs_attention")) process.exitCode = 1;
+}
+
+async function runSourceSignIn(args, directory) {
+  const { values, rest } = declared(args, ["--config"], 1);
+  const [instance] = rest;
+  if (!instance) throw new Error(SOURCE_USAGE);
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  let status;
+  try {
+    status = await signInConnector({
+      directory,
+      instance,
+      configuration: values["--config"] ?? join(directory, "kit.json"),
+      signal: cancellation.signal,
+    });
+  } finally {
+    process.removeListener("SIGINT", cancel);
+  }
+  write(`${instance}: ${status}`);
+  if (status === "needs_attention") process.exitCode = 1;
+}
+
+async function runApply(args, directory) {
+  const { values } = declared(args, ["--house", "--config"], 0);
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error("usage: kit apply --house <url> [--config <path>]");
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  let result;
+  try {
+    result = await apply({
+      house,
+      configuration: values["--config"] ?? join(directory, "kit.json"),
+      directory,
+      signal: cancellation.signal,
+    });
+  } finally {
+    process.removeListener("SIGINT", cancel);
+  }
+  write(`Applied the Environment configuration with ${result.schedules} schedules.`);
+  for (const hook of result.hooks) {
+    write(
+      `Installed the ${hook.id} SessionStart hook ${hook.version} for ${hook.kind} in ${hook.settings}.`,
+    );
+  }
+  for (const settings of result.removed) {
+    write(`Removed this installation's SessionStart hook from ${settings}.`);
+  }
+}
+
+async function runSourceCapture(args, directory) {
+  const { values, rest } = declared(args, ["--house", "--config"], 2);
+  const house = await selectedHouse(values, directory);
+  if (!house || rest.length === 0) throw new Error(SOURCE_USAGE);
+  const cancellation = new AbortController();
+  process.once("SIGINT", () => cancellation.abort());
+  const result = await captureSource(
+    {
+      house,
+      directory,
+      configuration: values["--config"] ?? join(directory, "kit.json"),
+      instance: rest[0],
+      service: rest[1] ?? null,
+      signal: cancellation.signal,
+    },
+    { googleOAuthClient: builtGoogleOAuthClient },
+  );
+  for (const delivered of result.services) {
+    const category =
+      delivered.health.category === null ? "" : ` (${delivered.health.category})`;
+    write(
+      `Delivered ${delivered.delivered} items for ${result.instance}/${delivered.service} in ${delivered.batches} batches; health ${delivered.health.state}${category}.`,
+    );
+    if (delivered.refused !== null) {
+      write(
+        `House refused ${result.instance}/${delivered.service} with ${delivered.refused.code}: ${JSON.stringify(delivered.refused.payload)}`,
+      );
+    }
+    writeSourceOriginals(result.instance, delivered);
+  }
+  if (result.services.some((delivered) => delivered.health.state !== "ok")) process.exitCode = 1;
+}
+
+function writeSourceOriginals(instance, service) {
+  for (const reference of service.originals) {
+    const failure = reference.error ?? reference.save.failure;
+    write(
+      `Original ${instance}/${service.service} ${reference.native_object_id} attachment ${reference.position} in ${reference.room} record ${reference.record}: ` +
+        `${reference.save.status}${failure === null ? "" : ` (${failure})`}` +
+        `${reference.version === null ? "" : ` version ${reference.version}`}.`,
+    );
+    if (reference.save.status !== "saved") process.exitCode = 1;
+  }
+}
+
+async function runSourceRetryFiles(args, directory) {
+  const { values, rest } = declared(args, ["--house", "--config"], 2);
+  const house = await selectedHouse(values, directory);
+  if (!house || rest.length === 0) throw new Error(SOURCE_USAGE);
+  const cancellation = new AbortController();
+  process.once("SIGINT", () => cancellation.abort());
+  const result = await retrySourceOriginals({
+    house,
+    directory,
+    configuration: values["--config"] ?? join(directory, "kit.json"),
+    instance: rest[0],
+    service: rest[1] ?? null,
+    signal: cancellation.signal,
+  });
+  for (const retried of result.services) {
+    if (retried.originals.length === 0) {
+      write(`No unsaved originals for ${result.instance}/${retried.service}.`);
+    }
+    writeSourceOriginals(result.instance, retried);
+  }
+}
+
+async function runSourceStatus(args, directory) {
+  const { values, rest } = declared(args, ["--config"], 2);
+  if (rest.length === 0) throw new Error(SOURCE_USAGE);
+  const result = await sourceStatus({
+    directory,
+    configuration: values["--config"] ?? join(directory, "kit.json"),
+    instance: rest[0],
+    service: rest[1] ?? null,
+  });
+  for (const reported of result.services) {
+    const category = reported.health.category === null ? "" : ` (${reported.health.category})`;
+    const observed =
+      reported.health.observed_at === null ? "never observed" : reported.health.observed_at;
+    write(
+      `${result.instance}/${reported.service} -> ${reported.source_ref} in ${reported.rooms.join(", ")}: ` +
+        `${reported.health.state}${category} at ${observed}; ` +
+        `cursor ${reported.checkpoint?.cursor ?? "none"}, ${reported.gaps.length} gaps, ` +
+        `${reported.dropped.length} dropped items, ${reported.originals.length} unsaved originals.`,
+    );
+  }
+  if (result.services.some((reported) => reported.health.state !== "ok")) process.exitCode = 1;
+}
+
+async function runSourceReset(args, directory) {
+  const { values, rest } = declared(args, ["--house", "--config"], 2);
+  const house = await selectedHouse(values, directory);
+  if (!house || rest.length === 0) throw new Error(SOURCE_USAGE);
+  const result = await resetSource({
+    house,
+    directory,
+    configuration: values["--config"] ?? join(directory, "kit.json"),
+    instance: rest[0],
+    service: rest[1] ?? null,
+  });
+  write(
+    result.services.length === 0
+      ? `No checkpoint to reset for ${result.instance}.`
+      : `Reset ${result.services.join(", ")} for ${result.instance}; the next capture restarts at the configured backfill boundary.`,
+  );
+}
+
+async function runRepositoryCapture(args, directory) {
+  const { values, rest } = declared(args, ["--house", "--room", "--source-handle"], 1);
+  const house = await selectedHouse(values, directory);
+  const room = values["--room"];
+  const sourceHandle = values["--source-handle"];
+  if (!house || !room || !sourceHandle || rest.length !== 1) throw new Error(REPOSITORY_USAGE);
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  let result;
+  try {
+    result = await captureRepository({
+      house,
+      directory,
+      checkout: rest[0],
+      room,
+      sourceHandle,
+      signal: cancellation.signal,
+    });
+  } finally {
+    process.removeListener("SIGINT", cancel);
+  }
+  const refused =
+    result.refused.length === 0
+      ? ""
+      : ` ${result.refused.length} refused (${result.refused
+          .map((item) => `${item.path}: ${item.outcome}`)
+          .join(", ")}).`;
+  write(
+    `Publication ${result.publication} of ${result.sourceRef} is ${result.ending};` +
+      ` delivered ${result.delivered} Repository paths.${refused}`,
+  );
+}
+
+function writeConversationFiles(supervised) {
+  const originals = [...(supervised.inbound?.originals ?? []), ...supervised.files.originals];
+  for (const original of originals) {
+    const failure = original.error ?? original.save.failure;
+    write(
+      `Conversation original for attachment ${original.attachment}: ${original.save.status}` +
+        `${failure === null ? "" : ` (${failure})`}${original.version === null ? "" : ` version ${original.version}`}.`,
+    );
+  }
+  for (const failure of supervised.files.failures) {
+    write(`Conversation originals could not be retried (${failure}).`);
+  }
+  const settled = new Map(originals.map((original) => [original.attachment, original.save.status]));
+  if ([...settled.values()].some((status) => status !== "saved") || supervised.files.failures.length > 0) {
+    process.exitCode = 1;
+  }
+}
+
+async function runWorkerRun(args, directory) {
+  const { values } = declared(args, ["--house", "--config"], 0);
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(WORKER_USAGE);
+  const supervised = await runWorkers(
+    {
+      house,
+      directory,
+      configuration: values["--config"] ?? join(directory, "kit.json"),
+    },
+    { googleOAuthClient: builtGoogleOAuthClient },
+  );
+  write(`Worker runtime ready on tmux ${supervised.tmux} in namespace ${supervised.namespace}.`);
+  if (supervised.epochReport !== null) {
+    write(`House started a new log epoch; reported ${supervised.epochReport.length} held Runs and House settled each.`);
+  }
+  writeConversationFiles(supervised);
+  for (const stop of supervised.stopped) {
+    write(`Run ${stop.run} stopped at its owner's request; House settled it.`);
+  }
+  for (const bound of supervised.unresolved) {
+    write(
+      bound.refused === null
+        ? `Run ${bound.run} stays bound to this installation and House did not answer.`
+        : `Run ${bound.run} stays bound to this installation; House refused its reported outcome (${bound.refused.code}).`,
+    );
+  }
+  if (supervised.unresolved.length > 0) {
+    write("Nothing was acquired while a bound WorkerSession stays unresolved.");
+    process.exitCode = 1;
+  }
+  const run = supervised.run;
+  if (run === null) {
+    if (supervised.stopped.length === 0 && supervised.unresolved.length === 0) {
+      write("No WorkerRun was waiting for this Environment.");
+    }
+    return;
+  }
+  if (run.stopped !== null) {
+    write(`Run ${run.run} stopped at its owner's request; House settled it.`);
+    return;
+  }
+  const reported = run.reported;
+  const outcome =
+    reported === null
+      ? "stopped with its Provider continuation retained for owner resumption"
+      : reported.outcome === "completed"
+        ? "reported completed"
+        : `reported failed (${reported.cause})`;
+  write(`Run ${run.run} ${outcome} after ${run.assistant.length} User-visible assistant messages.`);
+  if (!run.settled) {
+    write(
+      `Run ${run.run} stays bound to this installation until House accepts that report` +
+        `${run.refused === null ? "" : ` (${run.refused.code})`}.`,
+    );
+  }
+  if (!run.settled || reported?.outcome === "failed") process.exitCode = 1;
+}
+
+function syncCancellation() {
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  return {
+    signal: cancellation.signal,
+    done() {
+      process.removeListener("SIGINT", cancel);
+    },
+  };
+}
+
+async function runSyncBootstrap(args, directory) {
+  const { values, lists, rest } = declared(args, ["--house", "--prefix"], 1, {
+    repeated: ["--prefix"],
+    exact: true,
+  });
+  const house = await selectedHouse(values, directory);
+  if (!house || lists["--prefix"].length === 0) throw new Error(SYNC_BOOTSTRAP_USAGE);
+  const run = syncCancellation();
+  try {
+    const result = await bootstrap({
+      house,
+      directory,
+      replica: resolve(rest[0]),
+      prefixes: lists["--prefix"],
+      signal: run.signal,
+    });
+    write(
+      `Bootstrapped ${rest[0]} at ${result.positions.map((entry) => `${entry.authority}=${entry.position}`).join(", ")}.`,
+    );
+  } finally {
+    run.done();
+  }
+}
+
+async function runSyncPull(args, directory) {
+  const { values, rest } = declared(args, ["--house"], 1, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(SYNC_PULL_USAGE);
+  const run = syncCancellation();
+  try {
+    const result = await pull({
+      house,
+      directory,
+      replica: resolve(rest[0]),
+      signal: run.signal,
+    });
+    write(
+      `Pulled ${rest[0]} at ${result.positions.map((entry) => `${entry.authority}=${entry.position}`).join(", ")}.`,
+    );
+  } finally {
+    run.done();
+  }
+}
+
+async function runSyncRebootstrap(args, directory) {
+  const { values, rest } = declared(args, ["--house"], 1, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(SYNC_REBOOTSTRAP_USAGE);
+  const run = syncCancellation();
+  try {
+    const result = await rebootstrap({
+      house,
+      directory,
+      replica: resolve(rest[0]),
+      signal: run.signal,
+    });
+    write(
+      `Rebootstrapped ${rest[0]} at ${result.positions.map((entry) => `${entry.authority}=${entry.position}`).join(", ")}.`,
+    );
+  } finally {
+    run.done();
+  }
+}
+
+async function readChanges(path) {
+  const parsed = JSON.parse(await readFile(path, "utf8"));
+  if (Array.isArray(parsed)) return parsed;
+  if (Array.isArray(parsed?.changes)) return parsed.changes;
+  throw new KitRefusal("kit_sync_changes_invalid", path);
+}
+
+async function runSyncSubmit(args, directory) {
+  const { values, rest } = declared(args, ["--house", "--changes"], 1, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(SYNC_SUBMIT_USAGE);
+  const run = syncCancellation();
+  try {
+    const result = await submit({
+      house,
+      directory,
+      replica: resolve(rest[0]),
+      changes: values["--changes"] === undefined ? undefined : await readChanges(values["--changes"]),
+      signal: run.signal,
+    });
+    write(
+      result?.submitted === false
+        ? `Submitted no changes for ${rest[0]}.`
+        : `Submitted to ${result.authority} at position ${result.position}.`,
+    );
+  } finally {
+    run.done();
+  }
+}
+
+function migrateCancellation() {
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  return {
+    signal: cancellation.signal,
+    done() {
+      process.removeListener("SIGINT", cancel);
+    },
+  };
+}
+
+async function emitPackage(migrator, packagePath, configuration, directory, signal) {
+  const declaration = declaredMigrator(
+    await readConfiguration(configuration ?? join(directory, "kit.json")),
+    migrator,
+  );
+  return emitMigratorPackage(declaration, {
+    package: resolve(packagePath),
+    environment: await resolveEnvironment(declaration),
+    signal,
+  });
+}
+
+async function runMigrateEmit(args, directory) {
+  const { values, rest } = declared(args, ["--package", "--config"], 1, { exact: true });
+  if (rest.length !== 1 || values["--package"] === undefined) throw new Error(MIGRATE_EMIT_USAGE);
+  const run = migrateCancellation();
+  try {
+    const emitted = await emitPackage(
+      rest[0],
+      values["--package"],
+      values["--config"],
+      directory,
+      run.signal,
+    );
+    const held = await readMigratorPackage(emitted);
+    write(
+      `Emitted ${Object.keys(held.content).length} documents and ${held.attachments.size} attachments for ${held.manifest.migrator} into ${emitted}.`,
+    );
+  } finally {
+    run.done();
+  }
+}
+
+async function mountEmitted(packagePath, options, run) {
+  const held = await readMigratorPackage(resolve(packagePath));
+  const result = await mountPackage(held, { ...options, signal: run.signal });
+  for (const line of formatMount(result)) write(line);
+  if (!result.reportSaved || result.transfers.some((transfer) => transfer.save.status !== "saved")) process.exitCode = 1;
+}
+
+async function runMigrateMount(args, directory) {
+  const { values, rest } = declared(args, ["--house", "--subtree"], 1, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house || rest.length !== 1 || values["--subtree"] === undefined) {
+    throw new Error(MIGRATE_MOUNT_USAGE);
+  }
+  const run = migrateCancellation();
+  try {
+    await mountEmitted(rest[0], { house, directory, subtree: values["--subtree"] }, run);
+  } finally {
+    run.done();
+  }
+}
+
+async function runMigrateRun(args, directory) {
+  const { values, rest } = declared(args, ["--house", "--subtree", "--package", "--config"], 1, {
+    exact: true,
+  });
+  const house = await selectedHouse(values, directory);
+  if (
+    !house ||
+    rest.length !== 1 ||
+    values["--subtree"] === undefined ||
+    values["--package"] === undefined
+  ) {
+    throw new Error(MIGRATE_RUN_USAGE);
+  }
+  const run = migrateCancellation();
+  try {
+    const emitted = await emitPackage(
+      rest[0],
+      values["--package"],
+      values["--config"],
+      directory,
+      run.signal,
+    );
+    await mountEmitted(emitted, { house, directory, subtree: values["--subtree"] }, run);
+  } finally {
+    run.done();
+  }
+}
+
+async function runMigrateUnmount(args, directory) {
+  const { values, rest } = declared(args, ["--house", "--confirm"], 1, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house || rest.length !== 1) throw new Error(MIGRATE_UNMOUNT_USAGE);
+  const run = migrateCancellation();
+  try {
+    const result = await unmountSubtree({
+      house,
+      directory,
+      subtree: rest[0],
+      signal: run.signal,
+      ...(values["--confirm"] === undefined ? {} : { confirm: values["--confirm"] }),
+    });
+    for (const line of formatUnmount(result)) write(line);
+  } finally {
+    run.done();
+  }
+}
+
+async function runMigrate(args, directory) {
+  const [action, ...rest] = args;
+  if (action === "emit") return runMigrateEmit(rest, directory);
+  if (action === "mount") return runMigrateMount(rest, directory);
+  if (action === "unmount") return runMigrateUnmount(rest, directory);
+  if (action === "run") return runMigrateRun(rest, directory);
+  throw new Error(MIGRATE_USAGE);
+}
+
+async function runSync(args, directory) {
+  const [action, ...rest] = args;
+  if (action === "bootstrap") return runSyncBootstrap(rest, directory);
+  if (action === "pull") return runSyncPull(rest, directory);
+  if (action === "rebootstrap") return runSyncRebootstrap(rest, directory);
+  if (action === "submit") return runSyncSubmit(rest, directory);
+  throw new Error(SYNC_USAGE);
+}
+
+async function runWorkerAttach(args, directory) {
+  const { rest } = declared(args, [], 1);
+  const attached = await attachSession({ directory, session: rest[0] ?? null });
+  write(`Detached from the supervised session ${attached.session}.`);
+  if (attached.status !== 0) process.exitCode = attached.status;
+}
+
+function attachmentCancellation() {
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  return {
+    signal: cancellation.signal,
+    done() {
+      process.removeListener("SIGINT", cancel);
+    },
+  };
+}
+
+async function runAttachmentUpload(args, directory) {
+  const { values, rest } = declared(
+    args,
+    ["--house", "--room", "--private", "--name", "--media-type"],
+    1,
+    { flags: ["--private"] },
+  );
+  const house = await selectedHouse(values, directory);
+  if (!house || rest.length !== 1) throw new Error(ATTACHMENT_UPLOAD_USAGE);
+  const run = attachmentCancellation();
+  try {
+    const result = await uploadAttachment({
+      house,
+      directory,
+      file: rest[0],
+      room: values["--room"],
+      private: values["--private"] === true,
+      name: values["--name"],
+      mediaType: values["--media-type"],
+      signal: run.signal,
+    });
+    for (const line of formatAttachmentUpload(result)) write(line);
+  } finally {
+    run.done();
+  }
+}
+
+async function runAttachmentGet(args, directory) {
+  const { values } = declared(
+    args,
+    ["--house", "--attachment", "--room", "--private", "--output"],
+    0,
+    { flags: ["--private"] },
+  );
+  const house = await selectedHouse(values, directory);
+  const attachment = values["--attachment"];
+  if (!house || !attachment) throw new Error(ATTACHMENT_GET_USAGE);
+  const run = attachmentCancellation();
+  try {
+    const result = await getAttachment({
+      house,
+      directory,
+      attachment,
+      room: values["--room"],
+      private: values["--private"] === true,
+      output: values["--output"],
+      signal: run.signal,
+    });
+    for (const line of formatAttachmentGet(result)) write(line);
+  } finally {
+    run.done();
+  }
+}
+
+async function runAttachment(args, directory) {
+  const [action, ...rest] = args;
+  if (action === "upload") return runAttachmentUpload(rest, directory);
+  if (action === "get") return runAttachmentGet(rest, directory);
+  throw new Error(ATTACHMENT_USAGE);
+}
+
+async function runHostReport(args, directory) {
+  const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(HOST_USAGE);
+  const observed = await reportHost({
+    house,
+    directory,
+    configuration: values["--config"] ?? join(directory, "kit.json"),
+  });
+  write(
+    `Reported ${observed.cpu.available} of ${observed.cpu.total} millicores, ${observed.memory.available} of ${observed.memory.total} memory bytes, and ${observed.disk.available} of ${observed.disk.total} bytes on ${observed.disk.path}, measured at ${observed.observed_at}.`,
+  );
+}
+
+async function runAgentsUpdate(args, directory) {
+  const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(AGENTS_USAGE);
+  const { updated } = await updateAgents({
+    house,
+    directory,
+    configuration: values["--config"] ?? join(directory, "kit.json"),
+  });
+  if (updated.length === 0) write("This Environment declares no agent CLI.");
+  for (const agent of updated) {
+    if (agent.acted === "installed-release") {
+      write(`Installed ${agent.kind} release ${agent.release} and reported it to House.`);
+    } else if (agent.acted === "update-failed") {
+      write(
+        `Could not update ${agent.kind} (${agent.failure}); kept it at release ${agent.release ?? "none"}.`,
+      );
+      process.exitCode = 1;
+    } else if (agent.acted === "held-candidate") {
+      write(
+        `Held ${agent.kind} at ${agent.release ?? "no installed release"}: release ${agent.held} did not pass the contract's conformance check.`,
+      );
+    } else {
+      write(`Kept ${agent.kind} at release ${agent.release ?? "none"}.`);
+    }
+  }
+}
+
+async function runAgentsSignIn(args, directory) {
+  const { values, rest } = declared(args, ["--house", "--config"], 1, { exact: true });
+  const house = await selectedHouse(values, directory);
+  const [kind] = rest;
+  if (!house || !kind) throw new Error(AGENTS_USAGE);
+  const { status, reported } = await signInAgent({
+    house,
+    directory,
+    kind,
+    configuration: values["--config"] ?? join(directory, "kit.json"),
+  });
+  const signedIn = reported.find((agent) => agent.kind === kind)?.signed_in === true;
+  write(
+    signedIn
+      ? `Signed ${kind} in and reported it to House.`
+      : `The ${kind} sign-in command exited ${status} and House holds that CLI as not signed in.`,
+  );
+  if (!signedIn) process.exitCode = 1;
+}
+
+async function runWorkspaceHost(args, directory) {
+  const { values } = declared(args, ["--house", "--config", "--passes"], 0, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(WORKSPACE_USAGE);
+  const passes = values["--passes"] === undefined ? undefined : Number(values["--passes"]);
+  if (passes !== undefined && (!Number.isSafeInteger(passes) || passes < 1)) {
+    throw new Error(WORKSPACE_USAGE);
+  }
+  const served = await serveWorkspaces({
+    house,
+    directory,
+    configuration: values["--config"] ?? join(directory, "kit.json"),
+    passes,
+  });
+  for (const name of served.reconciled) {
+    write(`Stopped ${name}; House authorizes no running workspace for it.`);
+  }
+  for (const settlement of served.settled) {
+    write(
+      `Settled ${settlement.kind} for ${settlement.workspace ?? "an uncreated workspace"} as ${settlement.outcome}${settlement.refusal === undefined ? "" : `: ${settlement.refusal}`}.`,
+    );
+  }
+  for (const operation of served.withdrawn) {
+    write(`House withdrew the ${operation.kind} it had handed this host; its outcome was dropped.`);
+  }
+}
+
+async function runTelegramConnect(args, directory) {
+  const { values } = declared(args, ["--house"], 0, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(TELEGRAM_USAGE);
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", cancel);
+  let connected;
+  try {
+    connected = await connectPersonalBot({ house, directory, signal: cancellation.signal });
+  } finally {
+    process.removeListener("SIGINT", cancel);
+    process.removeListener("SIGTERM", cancel);
+  }
+  write(
+    `Connected @${connected.bot_username} (bot ${connected.telegram_bot_user_id}) for owner ${connected.owner_telegram_user_id}; this Environment is now the gateway.`,
+  );
+}
+
+async function runTelegramDisconnect(args, directory) {
+  const { values } = declared(args, ["--house"], 0, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(TELEGRAM_USAGE);
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", cancel);
+  let disconnected;
+  try {
+    disconnected = await disconnectPersonalBot({ house, directory, signal: cancellation.signal });
+  } finally {
+    process.removeListener("SIGINT", cancel);
+    process.removeListener("SIGTERM", cancel);
+  }
+  write(
+    disconnected.revoked
+      ? "Deleted the webhook, removed the local bot token and offset, and told House this Environment is no longer the gateway."
+      : "Completed an interrupted disconnect; the local bot token was already gone and House was told.",
+  );
+}
+
+async function runTelegramServe(args, directory) {
+  const { values } = declared(args, ["--house", "--passes"], 0, { exact: true });
+  const house = await selectedHouse(values, directory);
+  if (!house) throw new Error(TELEGRAM_USAGE);
+  const passes = values["--passes"] === undefined ? undefined : Number(values["--passes"]);
+  if (passes !== undefined && (!Number.isSafeInteger(passes) || passes < 1)) {
+    throw new Error(TELEGRAM_USAGE);
+  }
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", cancel);
+  let served;
+  try {
+    served = await serveTelegramGateway({ house, directory, passes, signal: cancellation.signal });
+  } finally {
+    process.removeListener("SIGINT", cancel);
+    process.removeListener("SIGTERM", cancel);
+  }
+  write(`Recovered ${served.abandoned} abandoned deliveries before serving.`);
+  for (const update of served.submitted) {
+    write(`Submitted ${update.kind} update ${update.update}: ${update.outcome}.`);
+  }
+  for (const file of served.relayed) {
+    write(`Relayed ${file.bytes} inbound bytes for attachment ${file.attachment}.`);
+  }
+  for (const settled of served.deliveries) {
+    write(`Delivery ${settled.delivery} settled ${settled.outcome}.`);
+  }
+  for (const settled of served.uploads) {
+    write(
+      `File send ${settled.upload} settled ${settled.outcome}${settled.reason === null ? "" : ` (${settled.reason})`}.`,
+    );
+  }
+  for (const failure of served.failures) {
+    write(
+      `The ${failure.activity} pass${failure.item === null ? "" : ` for ${failure.item}`} could not finish (${failure.code}).`,
+    );
+  }
+  if (served.failures.length > 0) process.exitCode = 1;
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  const directory = process.env.HOUSE_KIT_HOME ?? join(homedir(), ".house-kit");
+  if (command === "login") return runLogin(args, directory);
+  if (command === "credential" && args[0] === "check") return runCredentialCheck(args.slice(1), directory);
+  if (command === "resident") return runResidentCommand(args, directory);
+  if (command === "setup") return runSetup(args, directory);
+  if (command === "apply") return runApply(args, directory);
+  if (command === "worker") {
+    const [action, ...rest] = args;
+    if (action === "run") return runWorkerRun(rest, directory);
+    if (action === "attach") return runWorkerAttach(rest, directory);
+    throw new Error(WORKER_USAGE);
+  }
+  if (command === "source") {
+    const [action, ...rest] = args;
+    if (action === "capture") return runSourceCapture(rest, directory);
+    if (action === "status") return runSourceStatus(rest, directory);
+    if (action === "sign-in") return runSourceSignIn(rest, directory);
+    if (action === "reset") return runSourceReset(rest, directory);
+    if (action === "retry-files") return runSourceRetryFiles(rest, directory);
+    throw new Error(SOURCE_USAGE);
+  }
+  if (command === "repository") {
+    const [action, ...rest] = args;
+    if (action === "capture") return runRepositoryCapture(rest, directory);
+    throw new Error(REPOSITORY_USAGE);
+  }
+  if (command === "host") {
+    const [action, ...rest] = args;
+    if (action === "report") return runHostReport(rest, directory);
+    throw new Error(HOST_USAGE);
+  }
+  if (command === "agents") {
+    const [action, ...rest] = args;
+    if (action === "update") return runAgentsUpdate(rest, directory);
+    if (action === "sign-in") return runAgentsSignIn(rest, directory);
+    throw new Error(AGENTS_USAGE);
+  }
+  if (command === "workspace") {
+    const [action, ...rest] = args;
+    if (action === "host") return runWorkspaceHost(rest, directory);
+    throw new Error(WORKSPACE_USAGE);
+  }
+  if (command === "telegram") {
+    const [action, ...rest] = args;
+    if (action === "connect") return runTelegramConnect(rest, directory);
+    if (action === "disconnect") return runTelegramDisconnect(rest, directory);
+    if (action === "serve") return runTelegramServe(rest, directory);
+    throw new Error(TELEGRAM_USAGE);
+  }
+  if (command === "sync") return runSync(args, directory);
+  if (command === "migrate") return runMigrate(args, directory);
+  if (command === "attachment") return runAttachment(args, directory);
+  throw new Error(USAGE);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${formatCommandError(error)}\n`);
+  process.exitCode = 1;
+});