@agentshouse/kit 0.1.0-alpha.4 → 0.1.0-alpha.41

package/bin/kit.js

@@ -2,18 +2,18 @@
 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 { connectHouse, loginHouse, storedEnvironment, storedHouse } from "../src/login.js";
 import { apply } from "../src/apply.js";
 import { captureSource, resetSource, retrySourceOriginals, sourceStatus } from "../src/source.js";
+import { accountEntries, accountStatus, captureAccount } from "../src/google/entries.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 { openSession, releaseControl, requestDrain } from "../src/house.js";
 import { reportHost } from "../src/host.js";
 import { signInAgent, updateAgents } from "../src/agents.js";
-import { serveWorkspaces } from "../src/workspace.js";
+import { serveWorkspaces, updateWorkspaces } 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";
@@ -32,44 +32,44 @@ 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 HOST_USAGE = "usage: kit host report [--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>]";
+  "usage: kit agents update [--config <path>] | kit agents sign-in <kind> [--config <path>]";
+const WORKSPACE_USAGE = "usage: kit workspace host [--config <path>] [--passes <count>] | kit workspace update";
 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" +
+  "usage: kit source <capture|status> <account|instance> [service] [--config <path>]\n" +
+  "       kit source <reset|retry-files> <instance> [service] [--config <path>]\n" +
   "       kit source sign-in <instance> [--config <path>]";
-const SETUP_USAGE = "usage: kit setup [--house <url>] [--config <path>]";
+const SETUP_USAGE = "usage: kit setup [--config <path>]";
 const REPOSITORY_USAGE =
-  "usage: kit repository capture <checkout> --room <room> --source-handle <handle> [--house <url>]";
+  "usage: kit repository capture <checkout> --room <room> --source-handle <handle>";
 const WORKER_USAGE =
-  "usage: kit worker run [--house <url>] [--config <path>] | kit worker attach [<session>]";
+  "usage: kit worker run [--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>]";
+  "usage: kit sync bootstrap <directory> --prefix <path> [--prefix <path> ...]";
+const SYNC_PULL_USAGE = "usage: kit sync pull <directory>";
+const SYNC_REBOOTSTRAP_USAGE = "usage: kit sync rebootstrap <directory>";
 const SYNC_SUBMIT_USAGE =
-  "usage: kit sync submit <directory> [--house <url>] [--changes <path>]";
+  "usage: kit sync submit <directory> [--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>";
+  "usage: kit migrate mount <package> --subtree <path>";
 const MIGRATE_UNMOUNT_USAGE =
-  "usage: kit migrate unmount <subtree> [--house <url>] [--confirm <subtree>]";
+  "usage: kit migrate unmount <subtree> [--confirm <subtree>]";
 const MIGRATE_RUN_USAGE =
-  "usage: kit migrate run <migrator> [--house <url>] --subtree <path> --package <directory> [--config <path>]";
+  "usage: kit migrate run <migrator> --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>]";
+  "usage: kit attachment upload <file> (--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>]";
+  "usage: kit attachment get --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>]";
+  "usage: kit telegram <connect|disconnect>\n" +
+  "       kit telegram serve [--passes <count>]";
 
 function declared(argv, accepted, positionals, options = {}) {
   const repeated = options.repeated ?? [];
@@ -108,21 +108,10 @@ 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 house = await loginHouse(directory, values["--house"]);
   const presentation = values["--manual"] === true ? "manual" : "loopback";
   await connectHouse({
     house,
@@ -130,17 +119,18 @@ async function runLogin(args, directory) {
     directory,
     hostBrowser: values["--host-browser"] === true,
     hostname: process.env.HOUSE_KIT_HOSTNAME,
+    loginPort: process.env.HOUSE_KIT_LOGIN_PORT,
     ...(values["--environment"] === undefined ? {} : { environment: values["--environment"] }),
   });
 }
 
 async function runCredentialCheck(args, directory) {
-  const { values } = declared(args, ["--house"], 0, { exact: true });
+  declared(args, [], 0, { exact: true });
   if (await storedEnvironment(directory) === null) throw new KitRefusal("kit_environment_invalid", "no enrolled Environment id");
-  const house = await selectedHouse(values, directory);
+  const house = await storedHouse(directory);
   let session;
   try {
-    session = await openSession({ house, directory });
+    session = await openSession({ house, directory, acquire: true });
   } 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.");
@@ -153,8 +143,8 @@ async function runCredentialCheck(args, directory) {
 }
 
 async function runResidentCommand(args, directory) {
-  const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
-  const house = await selectedHouse(values, directory);
+  const { values } = declared(args, ["--config"], 0, { exact: true });
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const stop = () => cancellation.abort();
   process.once("SIGINT", stop);
@@ -167,24 +157,37 @@ async function runResidentCommand(args, directory) {
   }
 }
 
+async function runResidentDrain(args, directory) {
+  declared(args, [], 0, { exact: true });
+  const answer = await requestDrain(directory);
+  if (answer.ready === true) {
+    write("House Kit is ready for its update.");
+    return;
+  }
+  write(
+    answer.sessions.length > 0
+      ? `House Kit is draining for its update and waits for Agent Sessions ${answer.sessions.join(", ")}.`
+      : answer.serving === true
+        ? "House Kit is draining for its update and waits for the Kit command it serves."
+        : `House Kit is draining for its update; House refused its lease release (${answer.refused}).`,
+  );
+  process.exitCode = 1;
+}
+
 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 { values } = declared(args, ["--config"], 0, { exact: true });
+  const house = await storedHouse(directory);
   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 },
-    );
+    setup = await setupEnvironment({
+      house,
+      directory,
+      configuration: values["--config"] ?? join(directory, "kit.json"),
+      signal: cancellation.signal,
+    });
   } finally {
     process.removeListener("SIGINT", cancel);
   }
@@ -223,9 +226,8 @@ async function runSourceSignIn(args, directory) {
 }
 
 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 { values } = declared(args, ["--config"], 0);
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);
@@ -252,27 +254,32 @@ async function runApply(args, directory) {
 }
 
 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 { values, rest } = declared(args, ["--config"], 2);
+  if (rest.length === 0) throw new Error(SOURCE_USAGE);
+  const house = await storedHouse(directory);
   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 },
-  );
+  const entries = await accountEntries(directory, rest[0]);
+  const options = {
+    house,
+    directory,
+    service: rest[1] ?? null,
+    signal: cancellation.signal,
+  };
+  const result =
+    entries.length > 0
+      ? await captureAccount({ ...options, account: rest[0], entries })
+      : await captureSource({
+          ...options,
+          configuration: values["--config"] ?? join(directory, "kit.json"),
+          instance: rest[0],
+        });
   for (const delivered of result.services) {
     const category =
       delivered.health.category === null ? "" : ` (${delivered.health.category})`;
+    const cause = delivered.health.cause === undefined ? "" : `, cause ${delivered.health.cause}`;
     write(
-      `Delivered ${delivered.delivered} items for ${result.instance}/${delivered.service} in ${delivered.batches} batches; health ${delivered.health.state}${category}.`,
+      `Delivered ${delivered.delivered} items for ${result.instance}/${delivered.service} in ${delivered.batches} batches; health ${delivered.health.state}${category}${cause}.`,
     );
     if (delivered.refused !== null) {
       write(
@@ -297,9 +304,9 @@ function writeSourceOriginals(instance, service) {
 }
 
 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 { values, rest } = declared(args, ["--config"], 2);
+  if (rest.length === 0) throw new Error(SOURCE_USAGE);
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   process.once("SIGINT", () => cancellation.abort());
   const result = await retrySourceOriginals({
@@ -321,30 +328,40 @@ async function runSourceRetryFiles(args, directory) {
 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,
-  });
+  const entries = await accountEntries(directory, rest[0]);
+  const result =
+    entries.length > 0
+      ? await accountStatus({ directory, account: rest[0], entries, service: rest[1] ?? null })
+      : 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 cause = reported.health.cause === undefined ? "" : `, cause ${reported.health.cause}`;
     const observed =
       reported.health.observed_at === null ? "never observed" : reported.health.observed_at;
+    const signedIn =
+      reported.signed_in === undefined ? "" : reported.signed_in ? "signed in; " : "signed out; ";
     write(
       `${result.instance}/${reported.service} -> ${reported.source_ref} in ${reported.rooms.join(", ")}: ` +
-        `${reported.health.state}${category} at ${observed}; ` +
+        `${signedIn}${reported.health.state}${category}${cause} at ${observed}; ` +
         `cursor ${reported.checkpoint?.cursor ?? "none"}, ${reported.gaps.length} gaps, ` +
         `${reported.dropped.length} dropped items, ${reported.originals.length} unsaved originals.`,
     );
+    if (reported.enable !== null && reported.enable !== undefined) {
+      write(`Enable the ${reported.enable} in the Google Cloud project of ${result.instance}'s OAuth client.`);
+    }
   }
   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 { values, rest } = declared(args, ["--config"], 2);
+  if (rest.length === 0) throw new Error(SOURCE_USAGE);
+  const house = await storedHouse(directory);
   const result = await resetSource({
     house,
     directory,
@@ -360,11 +377,11 @@ async function runSourceReset(args, directory) {
 }
 
 async function runRepositoryCapture(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--room", "--source-handle"], 1);
-  const house = await selectedHouse(values, directory);
+  const { values, rest } = declared(args, ["--room", "--source-handle"], 1);
   const room = values["--room"];
   const sourceHandle = values["--source-handle"];
-  if (!house || !room || !sourceHandle || rest.length !== 1) throw new Error(REPOSITORY_USAGE);
+  if (!room || !sourceHandle || rest.length !== 1) throw new Error(REPOSITORY_USAGE);
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);
@@ -412,17 +429,13 @@ function writeConversationFiles(supervised) {
 }
 
 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 },
-  );
+  const { values } = declared(args, ["--config"], 0);
+  const house = await storedHouse(directory);
+  const supervised = await runWorkers({
+    house,
+    directory,
+    configuration: values["--config"] ?? join(directory, "kit.json"),
+  });
   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.`);
@@ -466,8 +479,10 @@ async function runWorkerRun(args, directory) {
       `Run ${run.run} stays bound to this installation until House accepts that report` +
         `${run.refused === null ? "" : ` (${run.refused.code})`}.`,
     );
+  } else if (run.refused !== null) {
+    write(`House refused that report (${run.refused.code}); this installation no longer holds Run ${run.run}.`);
   }
-  if (!run.settled || reported?.outcome === "failed") process.exitCode = 1;
+  if (!run.settled || run.refused !== null || reported?.outcome === "failed") process.exitCode = 1;
 }
 
 function syncCancellation() {
@@ -483,12 +498,12 @@ function syncCancellation() {
 }
 
 async function runSyncBootstrap(args, directory) {
-  const { values, lists, rest } = declared(args, ["--house", "--prefix"], 1, {
+  const { lists, rest } = declared(args, ["--prefix"], 1, {
     repeated: ["--prefix"],
     exact: true,
   });
-  const house = await selectedHouse(values, directory);
-  if (!house || lists["--prefix"].length === 0) throw new Error(SYNC_BOOTSTRAP_USAGE);
+  if (lists["--prefix"].length === 0) throw new Error(SYNC_BOOTSTRAP_USAGE);
+  const house = await storedHouse(directory);
   const run = syncCancellation();
   try {
     const result = await bootstrap({
@@ -507,9 +522,8 @@ async function runSyncBootstrap(args, directory) {
 }
 
 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 { rest } = declared(args, [], 1, { exact: true });
+  const house = await storedHouse(directory);
   const run = syncCancellation();
   try {
     const result = await pull({
@@ -527,9 +541,8 @@ async function runSyncPull(args, directory) {
 }
 
 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 { rest } = declared(args, [], 1, { exact: true });
+  const house = await storedHouse(directory);
   const run = syncCancellation();
   try {
     const result = await rebootstrap({
@@ -554,9 +567,8 @@ async function readChanges(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 { values, rest } = declared(args, ["--changes"], 1, { exact: true });
+  const house = await storedHouse(directory);
   const run = syncCancellation();
   try {
     const result = await submit({
@@ -629,11 +641,11 @@ async function mountEmitted(packagePath, options, run) {
 }
 
 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) {
+  const { values, rest } = declared(args, ["--subtree"], 1, { exact: true });
+  if (rest.length !== 1 || values["--subtree"] === undefined) {
     throw new Error(MIGRATE_MOUNT_USAGE);
   }
+  const house = await storedHouse(directory);
   const run = migrateCancellation();
   try {
     await mountEmitted(rest[0], { house, directory, subtree: values["--subtree"] }, run);
@@ -643,18 +655,17 @@ async function runMigrateMount(args, directory) {
 }
 
 async function runMigrateRun(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--subtree", "--package", "--config"], 1, {
+  const { values, rest } = declared(args, ["--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 house = await storedHouse(directory);
   const run = migrateCancellation();
   try {
     const emitted = await emitPackage(
@@ -671,9 +682,9 @@ async function runMigrateRun(args, directory) {
 }
 
 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 { values, rest } = declared(args, ["--confirm"], 1, { exact: true });
+  if (rest.length !== 1) throw new Error(MIGRATE_UNMOUNT_USAGE);
+  const house = await storedHouse(directory);
   const run = migrateCancellation();
   try {
     const result = await unmountSubtree({
@@ -729,12 +740,12 @@ function attachmentCancellation() {
 async function runAttachmentUpload(args, directory) {
   const { values, rest } = declared(
     args,
-    ["--house", "--room", "--private", "--name", "--media-type"],
+    ["--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);
+  if (rest.length !== 1) throw new Error(ATTACHMENT_UPLOAD_USAGE);
+  const house = await storedHouse(directory);
   const run = attachmentCancellation();
   try {
     const result = await uploadAttachment({
@@ -756,13 +767,13 @@ async function runAttachmentUpload(args, directory) {
 async function runAttachmentGet(args, directory) {
   const { values } = declared(
     args,
-    ["--house", "--attachment", "--room", "--private", "--output"],
+    ["--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);
+  if (!attachment) throw new Error(ATTACHMENT_GET_USAGE);
+  const house = await storedHouse(directory);
   const run = attachmentCancellation();
   try {
     const result = await getAttachment({
@@ -788,9 +799,8 @@ async function runAttachment(args, directory) {
 }
 
 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 { values } = declared(args, ["--config"], 0, { exact: true });
+  const house = await storedHouse(directory);
   const observed = await reportHost({
     house,
     directory,
@@ -802,9 +812,8 @@ async function runHostReport(args, directory) {
 }
 
 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 { values } = declared(args, ["--config"], 0, { exact: true });
+  const house = await storedHouse(directory);
   const { updated } = await updateAgents({
     house,
     directory,
@@ -830,10 +839,10 @@ async function runAgentsUpdate(args, directory) {
 }
 
 async function runAgentsSignIn(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--config"], 1, { exact: true });
-  const house = await selectedHouse(values, directory);
+  const { values, rest } = declared(args, ["--config"], 1, { exact: true });
   const [kind] = rest;
-  if (!house || !kind) throw new Error(AGENTS_USAGE);
+  if (!kind) throw new Error(AGENTS_USAGE);
+  const house = await storedHouse(directory);
   const { status, reported } = await signInAgent({
     house,
     directory,
@@ -850,19 +859,29 @@ async function runAgentsSignIn(args, directory) {
 }
 
 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 { values } = declared(args, ["--config", "--passes"], 0, { exact: true });
   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,
-  });
+  const house = await storedHouse(directory);
+  const cancellation = new AbortController();
+  const cancel = () => cancellation.abort();
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", cancel);
+  let served;
+  try {
+    served = await serveWorkspaces({
+      house,
+      directory,
+      configuration: values["--config"] ?? join(directory, "kit.json"),
+      passes,
+      signal: cancellation.signal,
+    });
+  } finally {
+    process.removeListener("SIGINT", cancel);
+    process.removeListener("SIGTERM", cancel);
+  }
   for (const name of served.reconciled) {
     write(`Stopped ${name}; House authorizes no running workspace for it.`);
   }
@@ -876,10 +895,24 @@ async function runWorkspaceHost(args, directory) {
   }
 }
 
+async function runWorkspaceUpdate(args, directory) {
+  declared(args, [], 0, { exact: true });
+  const answered = await updateWorkspaces({
+    house: await storedHouse(directory),
+    configuration: join(directory, "kit.json"),
+  });
+  for (const { workspace, running } of answered.updated) {
+    write(running ? `Updated workspace ${workspace}.` : `Updated workspace ${workspace}; it stays stopped.`);
+  }
+  for (const { workspace, cause } of answered.unchanged) {
+    write(`Workspace ${workspace} is unchanged: ${cause}`);
+  }
+  if (answered.unchanged.length > 0) process.exitCode = 1;
+}
+
 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);
+  declared(args, [], 0, { exact: true });
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);
@@ -897,9 +930,8 @@ async function runTelegramConnect(args, directory) {
 }
 
 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);
+  declared(args, [], 0, { exact: true });
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);
@@ -919,20 +951,25 @@ async function runTelegramDisconnect(args, directory) {
 }
 
 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 { values } = declared(args, ["--passes"], 0, { exact: true });
   const passes = values["--passes"] === undefined ? undefined : Number(values["--passes"]);
   if (passes !== undefined && (!Number.isSafeInteger(passes) || passes < 1)) {
     throw new Error(TELEGRAM_USAGE);
   }
+  const house = await storedHouse(directory);
   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 });
+    served = await serveTelegramGateway({
+      house,
+      directory,
+      passes,
+      signal: cancellation.signal,
+      refused: (failure) => write(refusedPassLine(failure)),
+    });
   } finally {
     process.removeListener("SIGINT", cancel);
     process.removeListener("SIGTERM", cancel);
@@ -952,20 +989,23 @@ async function runTelegramServe(args, directory) {
       `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}).`,
-    );
-  }
+  for (const failure of served.failures) write(refusedPassLine(failure));
   if (served.failures.length > 0) process.exitCode = 1;
 }
 
+function refusedPassLine(failure) {
+  return `The ${failure.activity} pass${failure.item === null ? "" : ` for ${failure.item}`} could not finish (${failure.code}).`;
+}
+
 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 === "resident") {
+    if (args[0] === "drain") return runResidentDrain(args.slice(1), directory);
+    return runResidentCommand(args, directory);
+  }
   if (command === "setup") return runSetup(args, directory);
   if (command === "apply") return runApply(args, directory);
   if (command === "worker") {
@@ -1002,6 +1042,7 @@ async function main() {
   if (command === "workspace") {
     const [action, ...rest] = args;
     if (action === "host") return runWorkspaceHost(rest, directory);
+    if (action === "update") return runWorkspaceUpdate(rest, directory);
     throw new Error(WORKSPACE_USAGE);
   }
   if (command === "telegram") {