@agentshouse/kit 0.1.0-alpha.11 → 0.1.0-alpha.13

package/README.md

@@ -10,7 +10,7 @@ On Linux `amd64` or `arm64` with a working Docker Engine, run the published,
 versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.11/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.13/connect-linux.sh)
 ```
 
 The release asset pins one immutable multi-architecture image digest. It creates
@@ -20,8 +20,31 @@ and starts the container with Docker's `unless-stopped` lifecycle. Pass
 `--workspace /absolute/path` for one other workspace root or `--manual` for
 the existing URL and one-time-code login route. `--house <origin>` selects
 another House and is retained in Kit home. A repeated invocation reuses the
-same container, credential and Environment; a different installed image is
-left for the explicit update journey.
+same container, credential and Environment.
+
+Running a newer release's bootstrap the same way is the only update. When the
+installed container runs another image, the bootstrap pulls this release's
+image and asks the running resident Kit to drain with `kit resident drain`. The
+resident stops acquiring Runs, resumptions, setup and agent CLI work, while the
+Sessions it supervises keep their renewal, owner stops, answers and reports.
+While any Agent Session is still running or unreported, including one whose Run
+was being acquired when the drain began, the bootstrap names it and leaves the
+container as it is; rerun it once they end. Once nothing remains,
+the resident stops renewing, releases its exact lease and stays quiescent, and
+the bootstrap replaces the container with one on this release's image over the
+same Kit home and workspace. The credential, Environment, Kit-home state and
+everything under the workspace are kept; anything installed elsewhere in the old
+container is not. A stopped container is replaced without a drain.
+
+If House refuses the installed Kit with `kit_upgrade_required`, including in
+its answer to a command the resident serves, the resident calls House no more,
+neither to release nor to report. It keeps supervising
+every running Session locally and never stops one to make progress. A Session
+that ends keeps its exact binding, stop observation and outcome in Kit home,
+and the drain answers ready once no supervised process runs. The updated Kit
+waits for the old lease to expire, acquires the next one and reports each held
+Session before it acquires any work, restoring no process and inventing no
+outcome.
 
 The versioned `bootstrap.json` is the machine-readable command source for this
 release. It is exported from the npm package as `@agentshouse/kit/bootstrap`
@@ -981,7 +1004,12 @@ content, no prompt, and no resolved secret, and Session authority is always
 reissued by House rather than recovered from disk. It is evidence for
 reconciliation, never permission to resume or recreate work, and nothing keeps
 it once House has answered for the Run: a settled terminal state, a confirmed
-owner stop, and a retained Provider continuation each drop it.
+owner stop, and a retained Provider continuation each drop it. When the
+supervised process ends, the binding first records what the Kit observed: the
+sealed final text, whether the turn completed, the capacity or provider refusal,
+the execution failure and whether a Provider continuation is retained. The Kit
+then reports that stop, and a restarted Kit reports the same recorded stop
+instead of treating the session as lost.
 
 A restarted `kit worker run` reconciles the records it kept before it acquires
 anything new. It reports every retained settlement note first, because those
@@ -1141,7 +1169,16 @@ cancels its request there, and the lease stays held when the command ends. The
 resident serves one such command at a time and refuses another with
 `environment_control_lease_active`, so two commands still never work at once.
 A resident whose lease House refuses answers the command with that refusal; the
-command never acquires a lease of its own while a resident serves it.
+command never acquires a lease of its own while a resident serves it. While an
+update drains, `state/update-drain` refuses every such command, `kit login` and
+`kit worker run` with `kit_update_draining` before it enrolls, acquires or
+delegates anything. A command already served keeps the resident's lease until
+it ends, while the resident refuses its acquisition of new work and its
+Telegram updates with `kit_update_draining`, which ends a served
+`kit telegram serve` once each of its activities reports the deliveries and
+files it already acquired; until it ends, the drain answers that it waits for
+that command and the bootstrap leaves the container as it is. The bootstrap
+removes the file when it replaces the container.
 
 Interrupting the command cancels the running connector without advancing the
 checkpoint.
@@ -1468,6 +1505,7 @@ $HOUSE_KIT_HOME/
   state/attachments/<upload identity>.json
   state/conversation-originals/<attachment identity>.json
   state/sessions/<tmux session>.json
+  state/update-drain
   state/continuations/<run identity>.json
   state/<instance>/credentials/google.json
   state/<instance>/checkpoints/<service>.json

package/bin/connect-linux.sh

@@ -37,6 +37,10 @@ login_kit() {
   done
 }
 
+start_resident() {
+  docker run -d --name "$NAME" --restart unless-stopped --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --label "agentshouse.house=$HOUSE" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 "$IMAGE" resident --house "$HOUSE" >/dev/null
+}
+
 if [[ "${1:-}" == kit ]]; then
   FORWARDING=1
   FORWARD=("${@:2}")
@@ -114,7 +118,8 @@ fi
 DOCKER_RUN=(docker run --rm --network host --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 --env "HOUSE_KIT_HOSTNAME=$(hostname)" "$IMAGE")
 
 if docker container inspect "$NAME" >/dev/null 2>&1; then
-  [[ "$(docker inspect --format '{{.Config.Image}}' "$NAME")" == "$IMAGE" ]] || refuse 'an installed Kit uses a different image; update it explicitly'
+  INSTALLED_IMAGE=$(docker inspect --format '{{.Config.Image}}' "$NAME")
+  ((FORWARDING == 0)) || [[ "$INSTALLED_IMAGE" == "$IMAGE" ]] || refuse 'an installed Kit uses a different image; rerun this bootstrap without arguments to update it'
   [[ "$(docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' "$NAME")" == unless-stopped ]] || refuse 'the installed Kit has a different lifecycle'
   [[ "$(docker inspect --format '{{len .Mounts}}' "$NAME")" == 2 ]] || refuse 'the installed Kit has unexpected mounts'
   [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/kit-home"}}{{.Source}}{{end}}{{end}}' "$NAME")" == "$KIT_HOME" ]] || refuse 'the installed Kit uses another Kit home'
@@ -142,6 +147,17 @@ if docker container inspect "$NAME" >/dev/null 2>&1; then
     fi
     exit
   fi
+  if [[ "$INSTALLED_IMAGE" != "$IMAGE" ]]; then
+    docker pull --quiet --platform "linux/$ARCH" "$IMAGE" >/dev/null
+    if [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]; then
+      docker exec "$NAME" kit resident drain
+    fi
+    docker rm -f "$NAME" >/dev/null
+    rm -f "$KIT_HOME/state/update-drain"
+    start_resident
+    printf 'House Kit updated for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
+    exit 0
+  fi
   "${DOCKER_RUN[@]}" credential check --house "$HOUSE"
   if [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]; then
     printf 'House Kit is already running for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
@@ -169,5 +185,5 @@ else
 fi
 
 "${DOCKER_RUN[@]}" apply --house "$HOUSE"
-docker run -d --name "$NAME" --restart unless-stopped --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --label "agentshouse.house=$HOUSE" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 "$IMAGE" resident --house "$HOUSE" >/dev/null
+start_resident
 printf 'House Kit connected for Environment %s.\n' "$(cat "$KIT_HOME/environment")"

package/bin/kit.js

@@ -9,7 +9,7 @@ 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 { openSession, releaseControl, requestDrain } 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";
@@ -167,6 +167,23 @@ 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);
@@ -965,7 +982,10 @@ async function main() {
   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") {

package/bootstrap.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "hosts": {
     "linux": {
-      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.11/connect-linux.sh)",
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.13/connect-linux.sh)",
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.11/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.13/connect-linux.sh"
       },
       "workspace": {
         "argument": "--workspace",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/binding.js

@@ -15,6 +15,18 @@ function bindingPath(directory, tmux) {
   return join(bindingDirectory(directory), `${tmux}.json`);
 }
 
+function stoppedNote(stopped) {
+  if (stopped === null || stopped === undefined) return null;
+  return {
+    turn_completed: stopped.turnCompleted,
+    capacity_exhausted: stopped.capacityExhausted,
+    provider_refused: stopped.providerRefused,
+    continuable: stopped.continuable,
+    failure: stopped.failure,
+    text_accepted: stopped.textAccepted,
+  };
+}
+
 export async function writeBinding(directory, binding) {
   const reported = binding.reported ?? null;
   await writeNote(bindingPath(directory, binding.tmux), {
@@ -29,6 +41,7 @@ export async function writeBinding(directory, binding) {
     sealed: binding.sealed === null || binding.sealed === undefined
       ? null
       : { operation: binding.sealed.operation, blocks: binding.sealed.blocks },
+    stopped: stoppedNote(binding.stopped),
     reported: reported === null ? null : reportedNote(reported),
   });
 }
@@ -45,6 +58,31 @@ function retainedSeal(stored) {
   return { operation: stored.operation, blocks: stored.blocks };
 }
 
+function retainedFailure(stored) {
+  if (stored === null) return null;
+  if (typeof stored !== "object" || Array.isArray(stored)) return undefined;
+  if (typeof stored.code !== "string" || stored.code.length === 0) return undefined;
+  if (stored.detail !== null && typeof stored.detail !== "string") return undefined;
+  return { code: stored.code, detail: stored.detail };
+}
+
+function retainedStop(stored) {
+  if (stored === null || stored === undefined) return null;
+  if (typeof stored !== "object" || Array.isArray(stored)) return undefined;
+  const flags = ["turn_completed", "capacity_exhausted", "provider_refused", "continuable", "text_accepted"];
+  if (flags.some((flag) => typeof stored[flag] !== "boolean")) return undefined;
+  const failure = retainedFailure(stored.failure);
+  if (failure === undefined) return undefined;
+  return {
+    turnCompleted: stored.turn_completed,
+    capacityExhausted: stored.capacity_exhausted,
+    providerRefused: stored.provider_refused,
+    continuable: stored.continuable,
+    failure,
+    textAccepted: stored.text_accepted,
+  };
+}
+
 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];
@@ -54,6 +92,8 @@ function completeBinding(directory, stored) {
   if (stored.owner_stop !== null && typeof stored.owner_stop !== "string") return null;
   const sealed = retainedSeal(stored.sealed);
   if (sealed === undefined) return null;
+  const stopped = retainedStop(stored.stopped);
+  if (stopped === undefined) return null;
   const reported = retainedReport(stored.reported);
   if (reported === undefined) return null;
   return {
@@ -65,6 +105,7 @@ function completeBinding(directory, stored) {
     conversation: stored.conversation === true,
     ownerStop: stored.owner_stop,
     sealed,
+    stopped,
     reported,
   };
 }

package/src/house.js

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { chmod, mkdir, readFile, rm } from "node:fs/promises";
 import { connect, createServer } from "node:net";
 import { dirname, join } from "node:path";
@@ -39,6 +40,8 @@ import { houseRefusal, KitRefusal, throwHouseAnswer } from "./refusal.js";
 const LEASE = /^ahl_[A-Za-z0-9_-]+$/;
 const RESIDENT = "Resident";
 const LEASE_ACTIVE = "environment_control_lease_active";
+const UPGRADE_REQUIRED = "kit_upgrade_required";
+const UPDATE_DRAINING = "kit_update_draining";
 const ASSISTANT_DRAFT_STATES = ["streamed", "unsupported"];
 const ITEM_OUTCOMES = ["accepted", "duplicate", "rejected"];
 
@@ -53,6 +56,10 @@ async function readCredential(directory) {
   return stored;
 }
 
+function latchRefusal(answer, dependencies) {
+  if (answer?.error?.code === UPGRADE_REQUIRED) dependencies.contractRefused?.();
+}
+
 async function houseAnswer(house, path, init, dependencies, signal) {
   const fetcher = dependencies.fetch ?? fetch;
   let response;
@@ -70,6 +77,7 @@ async function houseAnswer(house, path, init, dependencies, signal) {
   } catch {
     answer = null;
   }
+  latchRefusal(answer, dependencies);
   throwHouseAnswer(response.status, answer, path);
   if (answer === null) throw new KitRefusal("kit_house_unavailable", path);
   return answer;
@@ -113,16 +121,31 @@ function residentSocket(directory) {
   return join(directory, "run", "resident.sock");
 }
 
+export function updateDrain(directory) {
+  return join(directory, "state", "update-drain");
+}
+
+export function refuseDrained(directory) {
+  if (existsSync(updateDrain(directory))) throw new KitRefusal(UPDATE_DRAINING);
+}
+
 function residentAnswer(status, code) {
   const body = Buffer.from(JSON.stringify({ error: { code } })).toString("base64");
   return { status, type: "application/json", body };
 }
 
-async function residentRelay(session, request, signal) {
+function newWork(path) {
+  return path === "/kit/telegram/updates" || (path.endsWith("/acquire") && path !== "/kit/commands/acquire");
+}
+
+async function residentRelay(session, request, signal, draining) {
   const path = typeof request.path === "string" ? request.path : "";
   if (!path.startsWith("/kit/") || path.startsWith("/kit/lease")) {
     return residentAnswer(403, "kit_resident_route_refused");
   }
+  if (draining && newWork(path)) {
+    return residentAnswer(409, UPDATE_DRAINING);
+  }
   let authorization;
   try {
     authorization = await heldControl(session, signal);
@@ -137,6 +160,7 @@ async function residentRelay(session, request, signal) {
       signal,
     });
     const body = Buffer.from(await response.arrayBuffer());
+    if (response.status === 409) latchRefusal(JSON.parse(body.toString("utf8")), session.dependencies);
     return {
       status: response.status,
       type: response.headers.get("content-type"),
@@ -147,63 +171,105 @@ async function residentRelay(session, request, signal) {
   }
 }
 
-export async function serveResident(session, directory, signal) {
+export async function serveResident(session, directory, signal, drain) {
   const socket = residentSocket(directory);
   await mkdir(dirname(socket), { recursive: true, mode: 0o700 });
   await rm(socket, { force: true });
+  const connections = new Set();
   let holder = null;
-  const server = createServer((connection) => {
-    connection.on("error", () => connection.destroy());
-    if (holder !== null) {
-      writeFrame(connection, { refused: LEASE_ACTIVE });
+  let draining = false;
+  function answerDrain(connection) {
+    draining = true;
+    drain(holder !== null).then(
+      (answer) => {
+        if (!connection.destroyed) writeFrame(connection, answer);
+        connection.end();
+      },
+      () => connection.destroy(),
+    );
+    return false;
+  }
+  function hold(connection) {
+    if (holder !== null || draining || existsSync(updateDrain(directory))) {
+      writeFrame(connection, { refused: draining || holder === null ? UPDATE_DRAINING : LEASE_ACTIVE });
       connection.end();
-      return;
+      return false;
     }
     holder = connection;
+    renewControl(session, signal).then(
+      () => writeFrame(connection, { held: true }),
+      (error) => {
+        writeFrame(connection, { refused: error.code ?? "kit_lease_rejected" });
+        connection.end();
+      },
+    );
+    return true;
+  }
+  const server = createServer((connection) => {
+    connections.add(connection);
+    connection.on("error", () => connection.destroy());
     const relayed = new Map();
+    let held = null;
     connection.on("close", () => {
+      connections.delete(connection);
       if (holder === connection) holder = null;
       for (const cancelled of relayed.values()) cancelled.abort();
     });
-    renewControl(session, signal).then(
-      () => {
-        writeFrame(connection, { held: true });
-        readFrames(connection, {
-          onFrame: (request) => {
-            if (request.cancel === true) {
-              relayed.get(request.id)?.abort();
-              return;
-            }
-            const cancelled = new AbortController();
-            relayed.set(request.id, cancelled);
-            void residentRelay(session, request, AbortSignal.any([signal, cancelled.signal])).then(
-              (answer) => {
-                relayed.delete(request.id);
-                if (!connection.destroyed) writeFrame(connection, { id: request.id, ...answer });
-              },
-            );
+    readFrames(connection, {
+      onFrame: (request) => {
+        if (held === null) {
+          held = request.drain === true ? answerDrain(connection) : hold(connection);
+          return;
+        }
+        if (!held) return;
+        if (request.cancel === true) {
+          relayed.get(request.id)?.abort();
+          return;
+        }
+        const cancelled = new AbortController();
+        relayed.set(request.id, cancelled);
+        void residentRelay(session, request, AbortSignal.any([signal, cancelled.signal]), draining).then(
+          (answer) => {
+            relayed.delete(request.id);
+            if (!connection.destroyed) writeFrame(connection, { id: request.id, ...answer });
           },
-          onRefusal: () => connection.destroy(),
-        });
-      },
-      (error) => {
-        writeFrame(connection, { refused: error.code ?? "kit_lease_rejected" });
-        connection.end();
+        );
       },
-    );
+      onRefusal: () => connection.destroy(),
+    });
   });
   await new Promise((resolve, reject) => {
     server.once("error", reject);
     server.listen(socket, resolve);
   });
   await chmod(socket, 0o600);
-  return async () => {
-    holder?.destroy();
-    await new Promise((resolve) => server.close(resolve));
-    await rm(socket, { force: true });
+  return {
+    serving: () => holder !== null,
+    async close() {
+      for (const connection of connections) connection.destroy();
+      await new Promise((resolve) => server.close(resolve));
+      await rm(socket, { force: true });
+    },
   };
 }
 
+export function requestDrain(directory) {
+  const connection = connect(residentSocket(directory));
+  return new Promise((resolve, reject) => {
+    const unavailable = () => reject(new KitRefusal("kit_resident_unavailable"));
+    connection.on("error", unavailable);
+    connection.on("close", unavailable);
+    readFrames(connection, {
+      onFrame: (answer) => {
+        resolve(answer);
+        connection.end();
+      },
+      onRefusal: () => connection.destroy(),
+    });
+    writeFrame(connection, { drain: true });
+  });
+}
+
 async function residentDelegation(directory, fetcher) {
   const connection = connect(residentSocket(directory));
   const pending = new Map();
@@ -226,6 +292,7 @@ async function residentDelegation(directory, fetcher) {
     onFrame: (frame) => (frame.id === undefined ? greet(frame) : settle(frame.id, frame)),
     onRefusal: () => connection.destroy(),
   });
+  writeFrame(connection, { hold: true });
   const held = await greeting;
   if (held === null) return null;
   if (held.held !== true) {
@@ -276,6 +343,7 @@ async function residentDelegation(directory, fetcher) {
 }
 
 export async function openSession(options, dependencies = {}) {
+  if (options.resident !== true) refuseDrained(options.directory);
   const session = {
     house: options.house,
     dependencies,
@@ -285,7 +353,7 @@ export async function openSession(options, dependencies = {}) {
     signal: options.signal,
   };
   const resident =
-    options.acquire === true
+    options.acquire === true || options.resident === true
       ? null
       : await residentDelegation(options.directory, dependencies.fetch ?? fetch);
   if (resident !== null) {
@@ -293,24 +361,30 @@ export async function openSession(options, dependencies = {}) {
     session.dependencies = { ...dependencies, fetch: resident.fetch };
     return session;
   }
+  session.dependencies = {
+    ...dependencies,
+    contractRefused: () => {
+      session.refused = true;
+    },
+  };
   const credential = await readCredential(options.directory);
-  Object.assign(
-    session,
-    heldLease(
-      await houseRequest(
-        session.house,
-        `Bearer ${credential}`,
-        "/kit/lease",
-        {},
-        session.dependencies,
-        session.signal,
-      ),
-    ),
-  );
+  const answer = await houseRequest(
+    session.house,
+    `Bearer ${credential}`,
+    "/kit/lease",
+    {},
+    session.dependencies,
+    session.signal,
+  ).catch((error) => {
+    if (options.resident === true && session.refused) return null;
+    throw error;
+  });
+  if (answer !== null) Object.assign(session, heldLease(answer));
   return session;
 }
 
 async function renewControl(session, signal) {
+  if (session.refused) throw new KitRefusal(UPGRADE_REQUIRED);
   Object.assign(
     session,
     heldLease(
@@ -328,13 +402,14 @@ async function renewControl(session, signal) {
 
 export async function heldControl(session, signal = session.signal) {
   if (session.resident !== undefined) return RESIDENT;
+  if (session.refused) throw new KitRefusal(UPGRADE_REQUIRED);
   if (session.expiresAt - session.now().getTime() <= LEASE_RENEWAL_MARGIN_MS) {
     await renewControl(session, signal);
   }
   return `Bearer ${session.lease}`;
 }
 
-function controlSleep(milliseconds, signal) {
+export function controlSleep(milliseconds, signal) {
   return new Promise((resolve, reject) => {
     if (signal.aborted) {
       reject(new KitRefusal("kit_command_cancelled"));
@@ -382,6 +457,7 @@ export async function releaseControl(session, options = {}) {
   if (session.lease === null) return;
   const held = session.lease;
   try {
+    if (session.refused) throw new KitRefusal(UPGRADE_REQUIRED);
     await houseRequest(
       session.house,
       `Bearer ${held}`,
@@ -430,7 +506,7 @@ export async function maintainControl(session, operation, signal, { release = tr
           throw new KitRefusal("kit_lease_rejected");
         }
       } catch (error) {
-        if (stopped) return;
+        if (stopped || session.refused) return;
         rejectFailure(error);
         maintenance.abort();
         return;

package/src/kit-work-stream.js

@@ -49,6 +49,7 @@ async function connected(session, signal, available, dependencies) {
     });
     socket.on("unexpected-response", (_request, response) => {
       response.resume();
+      if (response.statusCode === 409) session.dependencies.contractRefused?.();
       const refusal =
         response.statusCode === 409 ? new KitRefusal("kit_upgrade_required") : null;
       socket.terminate();

package/src/login.js

@@ -8,7 +8,7 @@ import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { KIT_CREDENTIAL } from "./contract.js";
 import { launchBase, prepareLaunchBase } from "./directory.js";
-import { houseRequest } from "./house.js";
+import { houseRequest, refuseDrained } from "./house.js";
 import { KitRefusal } from "./refusal.js";
 import { writeText } from "./state.js";
 
@@ -260,6 +260,7 @@ export async function openBrowser(url) {
 }
 
 export async function connectHouse(options, dependencies = {}) {
+  refuseDrained(options.directory);
   await prepareLaunchBase(launchBase(dependencies));
   if (options.presentation === "manual") return login(options, dependencies);
   const callback = await loopback();

package/src/telegram.js

@@ -863,20 +863,21 @@ async function onePass(gateway, activity, work) {
   try {
     await work(gateway);
   } catch (error) {
-    if (cancelled(error) || !(error instanceof KitRefusal)) throw error;
+    if (cancelled(error) || !(error instanceof KitRefusal) || error.code === "kit_update_draining") throw error;
     gateway.summary.failures.push({ activity, item: null, code: error.code });
   }
 }
 
 async function paceActivity(gateway, stopping, activity, work) {
   try {
-    for (let index = 0; index < gateway.passes; index += 1) {
+    for (let index = 0; index < gateway.passes && !gateway.draining; index += 1) {
       if (gateway.signal?.aborted === true) throw new KitRefusal("kit_command_cancelled");
       await onePass(gateway, activity, work);
       if (index + 1 < gateway.passes) await gateway.wait(TELEGRAM_GATEWAY_POLL_MS, gateway.signal);
     }
   } catch (error) {
-    stopping.abort();
+    if (error.code === "kit_update_draining") gateway.draining = true;
+    else stopping.abort();
     throw error;
   }
 }
@@ -964,6 +965,7 @@ function gatewayContext(session, options, signal, summary = emptySummary()) {
     gate: rateGate(() => session.now().getTime()),
     wait: session.dependencies.wait ?? pause,
     passes: options.passes ?? Number.POSITIVE_INFINITY,
+    draining: false,
     summary,
   };
 }

package/src/worker.js

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
@@ -44,6 +45,7 @@ import {
   rejectResumption,
   callHouseMcp,
   commitRun,
+  controlSleep,
   maintainControl,
   mutatingCall,
   observeSessionStart,
@@ -56,14 +58,17 @@ import {
   toolMutations,
   reportRunOutcome,
   reportSessionHeartbeat,
+  releaseControl,
   reportSessions,
   serveResident,
   sessionAuthority,
   streamAssistantDraft,
+  updateDrain,
 } from "./house.js";
 import { operationId } from "./operation.js";
 import { runSetup, signInWantedAgent } from "./setup.js";
 import { readSettlements, removeSettlement, writeSettlement } from "./settlement.js";
+import { writeText } from "./state.js";
 import { failedReport, terminalReport } from "./terminal.js";
 import {
   createSession,
@@ -75,47 +80,31 @@ import {
 } from "./tmux.js";
 
 const LAUNCHER_MAIN = fileURLToPath(new URL("launcher-main.js", import.meta.url));
+const RESIDENT_INTERVAL_MS = 30_000;
 
 async function dispatchSeal(context, bound) {
   try {
-    const accepted = await acceptAssistantText(context.session, bound.session, bound.sealed);
-    await resolveSeal(context, bound);
-    return { accepted, failure: null, unresolved: false, refused: null };
+    await acceptAssistantText(context.session, bound.session, bound.sealed);
+    bound.stopped.textAccepted = true;
   } catch (refusal) {
     if (!(refusal instanceof KitRefusal)) throw refusal;
     const named = { code: refusal.code, detail: refusal.message };
-    if (undecided(refusal)) return { accepted: null, failure: null, unresolved: true, refused: named };
-    await resolveSeal(context, bound);
-    return { accepted: null, failure: named, unresolved: false, refused: null };
+    if (undecided(context, refusal)) return named;
+    bound.stopped.failure ??= named;
   }
-}
-
-async function resolveSeal(context, bound) {
   bound.sealed = null;
   await writeBinding(context.directory, bound);
-}
-
-async function sealAssistantText(context, bound, said) {
-  const blocks = assistantBlocks(said.join("\n\n"));
-  if (blocks === null) return { accepted: null, failure: null, unresolved: false, refused: null };
-  bound.sealed = { operation: operationId(), blocks };
-  await writeBinding(context.directory, bound);
-  return dispatchSeal(context, bound);
-}
-
-async function recoverAssistantSeal(context, binding) {
-  if (binding.sealed === null) return { unresolved: false, refused: null };
-  const sealed = await dispatchSeal(context, binding);
-  return { unresolved: sealed.unresolved, refused: sealed.refused };
+  return null;
 }
 
 function unresolvedRun(bound, refused = null) {
   return { run: bound.run, session: bound.session, refused };
 }
 
-function undecided(refusal) {
+function undecided(context, refusal) {
   return (
     houseFailed(refusal) ||
+    context.session.refused === true ||
     (refusal instanceof KitRefusal &&
       ["kit_command_cancelled", "kit_session_token_rejected"].includes(refusal.code))
   );
@@ -125,7 +114,9 @@ async function pendingCommands(context, kinds = ["stop"]) {
   try {
     return await acquireCommands(context.session, WORKER_COMMAND_BATCH_MAX, kinds);
   } catch (refusal) {
-    if (houseFailed(refusal)) return { stops: [], answers: [], interrupts: [] };
+    if (houseFailed(refusal) || context.session.refused === true) {
+      return { stops: [], answers: [], interrupts: [] };
+    }
     throw refusal;
   }
 }
@@ -186,6 +177,7 @@ async function supervise(context, bound, bridge) {
   while (live) {
     await Promise.race([terminal, delay(WORKER_SUPERVISION_POLL_MS)]);
     if (!live) return null;
+    await context.update?.announce();
     if (Date.now() >= commanded) {
       commanded = Date.now() + WORKER_COMMAND_POLL_MS;
       const polled = await pendingCommands(context, ["stop", "interrupt", "answer"]);
@@ -227,7 +219,7 @@ async function completeOwnerStop(context, bound, requestedAt) {
   try {
     await observeSessionStop(context.session, bound.session);
   } catch (refusal) {
-    if (houseFailed(refusal)) return { destroyed, confirmed: false, failure: null };
+    if (undecided(context, refusal)) return { destroyed, confirmed: false, failure: null };
     if (!(refusal instanceof KitRefusal)) throw refusal;
     failure = { code: refusal.code, detail: refusal.message };
   }
@@ -241,7 +233,7 @@ async function settleReported(context, bound) {
     await reportRunOutcome(context.session, bound.run, bound.reported);
     return { settled: true, failure: null };
   } catch (refusal) {
-    if (undecided(refusal)) return { settled: false, failure: null };
+    if (undecided(context, refusal)) return { settled: false, failure: null };
     if (!(refusal instanceof KitRefusal)) throw refusal;
     if (refusal.code === "worker_run_settled") return { settled: true, failure: null };
     return { settled: false, failure: { code: refusal.code, detail: refusal.message } };
@@ -375,50 +367,65 @@ async function superviseBound(context, bound, opened, start) {
     held !== null &&
     stopped?.providerContinuation === true &&
     stopped.providerSessionId !== null;
-  const turnObserved = stopped?.stopOutcome === "completed";
-  const sealed = turnObserved
-    ? await sealAssistantText(context, bound, outcome.assistant)
-    : { accepted: null, failure: null, unresolved: false, refused: null };
-  if (sealed.unresolved) return { ...outcome, refused: sealed.refused, settled: false };
-  if (sealed.failure !== null) outcome.failure ??= sealed.failure;
-  const execution = outcome.failure;
+  if (continuable) {
+    await writeContinuation(context.directory, { ...held, providerSessionId: stopped.providerSessionId });
+  }
+  const turnCompleted = stopped?.stopOutcome === "completed";
+  const blocks = turnCompleted ? assistantBlocks(outcome.assistant.join("\n\n")) : null;
+  bound.sealed = blocks === null ? null : { operation: operationId(), blocks };
+  bound.stopped = {
+    turnCompleted,
+    capacityExhausted,
+    providerRefused,
+    continuable,
+    failure: outcome.failure,
+    textAccepted: false,
+  };
+  await writeBinding(context.directory, bound);
+  return { ...outcome, ...(await settleStopped(context, bound)) };
+}
+
+function stoppedReport(bound) {
+  if (bound.stopped === null || bound.stopped === undefined) return null;
+  return terminalReport({ ...bound.stopped, conversation: bound.conversation === true });
+}
+
+async function settleStopped(context, bound) {
+  const { stopped } = bound;
+  const unresolved = (refused) => ({ failure: stopped.failure, refused, settled: false });
+  if (bound.sealed !== null) {
+    const refused = await dispatchSeal(context, bound);
+    if (refused !== null) return unresolved(refused);
+  }
+  let failure = stopped.failure;
   try {
-    await observeSessionStop(context.session, bound.session, sealed.accepted !== null);
+    await observeSessionStop(context.session, bound.session, stopped.textAccepted);
   } catch (refusal) {
+    if (undecided(context, refusal)) return unresolved(null);
     if (!(refusal instanceof KitRefusal) || refusal.code !== "conversation_final_text_pending") throw refusal;
-    outcome.failure ??= { code: refusal.code, detail: refusal.message };
+    failure ??= { code: refusal.code, detail: refusal.message };
     await observeSessionStop(context.session, bound.session);
   }
-  const report = terminalReport({
-    conversation: bound.conversation === true,
-    turnCompleted: turnObserved,
-    capacityExhausted,
-    providerRefused,
-    failure: execution,
-    continuable,
-  });
-  const retained = report === null;
-  if (retained) {
-    await writeContinuation(context.directory, {
-      ...held,
-      providerSessionId: stopped.providerSessionId,
+  const report = stoppedReport(bound);
+  if (report !== null) await removeContinuation(context.directory, bound.run);
+  try {
+    await reportContinuation(context.session, bound.session, {
+      providerContinuation: report === null,
+      providerCapacityExhausted: stopped.capacityExhausted,
     });
-  } else await removeContinuation(context.directory, bound.run);
-  await reportContinuation(context.session, bound.session, {
-    providerContinuation: retained,
-    providerCapacityExhausted: capacityExhausted,
-  });
-  if (retained) {
+  } catch (refusal) {
+    if (undecided(context, refusal)) return unresolved(null);
+    if (!(refusal instanceof KitRefusal) || refusal.code !== "worker_run_settled") throw refusal;
+    await removeContinuation(context.directory, bound.run);
+    await removeBinding(context.directory, bound.tmux);
+    return { failure, refused: null, settled: true };
+  }
+  if (report === null) {
     await removeBinding(context.directory, bound.tmux);
-    return outcome;
+    return { failure, refused: null, settled: true };
   }
   const settled = await reportTerminalState(context, bound, report);
-  return {
-    ...outcome,
-    reported: settled.reported,
-    refused: settled.failure,
-    settled: settled.settled,
-  };
+  return { failure, reported: settled.reported, refused: settled.failure, settled: settled.settled };
 }
 
 function assignmentRoute(context, assignment) {
@@ -506,7 +513,7 @@ async function superviseAssignment(context, assignment, resumed = false) {
       detail: refusal instanceof KitRefusal ? refusal.message : null,
     };
     if (resumed) return refuseContinuation(context, assignment, failure);
-    if (undecided(refusal)) throw refusal;
+    if (undecided(context, refusal)) throw refusal;
     return refuseAssignment(context, assignment, failure);
   }
   const { bound, opened } = prepared;
@@ -555,7 +562,7 @@ async function settleAbsentSession(context, binding) {
       providerCapacityExhausted: false,
     });
   } catch (refusal) {
-    if (undecided(refusal)) return { settled: false, failure: null };
+    if (undecided(context, refusal)) return { settled: false, failure: null };
     if (!(refusal instanceof KitRefusal)) throw refusal;
   }
   await removeContinuation(context.directory, binding.run);
@@ -571,7 +578,7 @@ async function confirmRestorable(context, binding) {
   try {
     authority = await replaceSessionAuthority(context.session, binding.session);
   } catch (refusal) {
-    if (undecided(refusal)) return { authority: null, unresolved: true };
+    if (undecided(context, refusal)) return { authority: null, unresolved: true };
     if (!(refusal instanceof KitRefusal)) throw refusal;
     await destroySession(context.runtime, binding.tmux);
     await removeBinding(context.directory, binding.tmux);
@@ -593,17 +600,17 @@ async function reconcile(context) {
   const commands = (await pendingCommands(context)).stops;
   const carried = [];
   for (const binding of bindings) {
-    const resealed = await recoverAssistantSeal(context, binding);
-    if (resealed.unresolved) {
-      unresolved.push(unresolvedRun(binding, resealed.refused));
-      continue;
-    }
     if (binding.reported !== null) {
       const settled = await settleReported(context, binding);
       if (settled.settled) await removeBinding(context.directory, binding.tmux);
       else unresolved.push(unresolvedRun(binding, settled.failure));
       continue;
     }
+    if (binding.stopped !== null) {
+      const settled = await settleStopped(context, binding);
+      if (!settled.settled) unresolved.push(unresolvedRun(binding, settled.refused));
+      continue;
+    }
     const command = commands.find((pending) => pending.run === binding.run) ?? null;
     const requestedAt = binding.ownerStop ?? command?.requestedAt ?? null;
     if (requestedAt === null) {
@@ -643,7 +650,7 @@ async function reportHeldSessions(context) {
   const continued = (await readContinuationRuns(context.directory)).map((run) => ({ run, reported: null }));
   const held = new Map();
   for (const entry of [...settlements, ...bindings, ...continued]) {
-    held.set(entry.run, held.get(entry.run) ?? entry.reported);
+    held.set(entry.run, held.get(entry.run) ?? entry.reported ?? stoppedReport(entry));
   }
   const reported = await reportSessions(
     context.session,
@@ -670,17 +677,23 @@ async function afterEpochReport(context, pass) {
   return pass();
 }
 
+function unlessDraining(context, act) {
+  return context.update?.requested ? null : act();
+}
+
 async function workerPass(context, dependencies, baseConfiguration) {
   const { session, signal } = context;
   const reconciled = await reconcile(context);
-  if (reconciled.run !== null || reconciled.unresolved.length > 0) return reconciled;
+  if (reconciled.run !== null || reconciled.unresolved.length > 0 || context.update?.requested) {
+    return reconciled;
+  }
   context.busy = false;
   const needsLogin = await queueAgentRefresh(context, dependencies, signal, baseConfiguration);
   context.startLogins?.(needsLogin);
   context.busy = true;
   const { configuration } = context;
-  context.inbound = await reconcileInbound(context.directory, session);
-  const setup = await acquireSetup(session, signal);
+  context.inbound = await unlessDraining(context, () => reconcileInbound(context.directory, session));
+  const setup = await unlessDraining(context, () => acquireSetup(session, signal));
   if (setup !== null) {
     context.setup = await runSetup(
       {
@@ -697,19 +710,21 @@ async function workerPass(context, dependencies, baseConfiguration) {
     const needsLogin = await queueAgentRefresh(context, dependencies, signal, undefined, true);
     context.startLogins?.(needsLogin);
   }
-  const resumption = await acquireOneResumption(session);
+  const resumption = await unlessDraining(context, () => acquireOneResumption(session));
   if (resumption !== null) return { ...reconciled, run: await superviseResumption(context, resumption) };
-  const assignment = await acquireOneRun(session);
+  const assignment = await unlessDraining(context, () => acquireOneRun(session));
   if (assignment === null) return reconciled;
   return { ...reconciled, run: await superviseAssignment(context, assignment) };
 }
 
-async function workerContext(options, dependencies) {
+async function workerContext(options, dependencies, resident = false) {
   const configuration = await readConfiguration(options.configuration);
   const runtime = workerRuntime(options.directory, dependencies.tmux ?? "tmux");
   const launcher = dependencies.launcher ?? [process.execPath, LAUNCHER_MAIN];
   const tmux = await readyTmux(runtime);
-  const session = await openSession({ ...options, acquire: true }, dependencies);
+  const session = resident
+    ? await residentSession(options, dependencies)
+    : await openSession({ ...options, acquire: true }, dependencies);
   const context = {
     configuration,
     runtime,
@@ -827,14 +842,83 @@ function residentWake() {
   };
 }
 
+function residentUpdate(context, wake) {
+  let requested = existsSync(updateDrain(context.directory));
+  let ready = null;
+  const waiting = [];
+  return {
+    get requested() {
+      return requested;
+    },
+    async request(serving) {
+      if (!requested) {
+        requested = true;
+        await writeText(updateDrain(context.directory), "");
+      }
+      wake.notify();
+      const sessions = await heldSessions(context);
+      if (ready !== null) return ready;
+      if (serving) return { ready: false, sessions, serving };
+      if (sessions.length > 0) return { ready: false, sessions };
+      return new Promise((resolve) => waiting.push(resolve));
+    },
+    answer(answer) {
+      for (const resolve of waiting.splice(0)) resolve(answer);
+    },
+    async announce() {
+      if (waiting.length === 0) return;
+      const sessions = await heldSessions(context);
+      if (sessions.length > 0) this.answer({ ready: false, sessions });
+    },
+    quiesce() {
+      ready = { ready: true, sessions: [] };
+      this.answer(ready);
+    },
+  };
+}
+
+async function heldSessions(context) {
+  const bindings = await readBindings(context.directory);
+  if (!context.session.refused) {
+    return [...bindings, ...(await readSettlements(context.directory))].map((held) => held.run);
+  }
+  const live = [];
+  for (const binding of bindings) {
+    if (binding.stopped === null && (await sessionPresent(context.runtime, binding.tmux))) {
+      live.push(binding.run);
+    }
+  }
+  return live;
+}
+
+async function residentSession(options, dependencies) {
+  for (;;) {
+    try {
+      return await openSession({ ...options, resident: true }, dependencies);
+    } catch (refusal) {
+      if (refusal?.code !== "environment_control_lease_active") throw refusal;
+      await controlSleep(dependencies.residentIntervalMs ?? RESIDENT_INTERVAL_MS, options.signal);
+    }
+  }
+}
+
 export async function runResident(options, dependencies = {}) {
-  const { context } = await workerContext(options, dependencies);
-  await maintainControl(context.session, async (signal) => {
-    const closeResident = await serveResident(context.session, context.directory, signal);
+  const { context } = await workerContext(options, dependencies, true);
+  const { session } = context;
+  const interval = dependencies.residentIntervalMs ?? RESIDENT_INTERVAL_MS;
+  const wake = residentWake();
+  const update = residentUpdate(context, wake);
+  context.update = update;
+  const served = await serveResident(session, context.directory, options.signal, (serving) => update.request(serving));
+  const serve = async (signal) => {
     context.busy = true;
-    const wake = residentWake();
     const watcher = new AbortController();
     let failure = null;
+    const fail = (error) => {
+      if (signal.aborted || session.refused) return;
+      failure = error;
+      wake.notify();
+    };
     const logins = new Map();
     const attemptedLogins = new Map();
     context.cancelLogins = (wanted) => {
@@ -853,6 +937,7 @@ export async function runResident(options, dependencies = {}) {
       }
     };
     context.startLogins = (agents) => {
+      if (update.requested) return;
       for (const agent of agents) {
         const { kind, release } = agent;
         if (logins.has(kind) || attemptedLogins.get(kind) === release) continue;
@@ -866,8 +951,7 @@ export async function runResident(options, dependencies = {}) {
         })()
           .catch((error) => {
             if (loginSignal.aborted) return;
-            failure = error;
-            wake.notify();
+            fail(error);
           })
           .finally(() => logins.delete(kind));
         logins.set(kind, { controller, task });
@@ -879,6 +963,7 @@ export async function runResident(options, dependencies = {}) {
     let pointerPending = false;
     let pointerTask = null;
     const pointer = () => {
+      if (update.requested) return;
       pointerPending = true;
       if (pointerTask !== null) return;
       pointerTask = (async () => {
@@ -890,8 +975,7 @@ export async function runResident(options, dependencies = {}) {
       })()
         .catch((error) => {
           if (signal.aborted) return;
-          failure = error;
-          wake.notify();
+          fail(error);
         })
         .finally(() => {
           pointerTask = null;
@@ -904,16 +988,22 @@ export async function runResident(options, dependencies = {}) {
       AbortSignal.any([signal, watcher.signal]),
       pointer,
       dependencies,
-    ).catch((error) => {
-      failure = error;
-      wake.notify();
-    });
+    ).catch(fail);
     try {
       while (!signal.aborted) {
         if (failure !== null) throw failure;
-        const configuration = await readConfiguration(options.configuration);
-        await controlledPass(context, dependencies, configuration, signal);
-        await wake.wait(dependencies.residentIntervalMs ?? 30_000, signal);
+        if (!session.refused) {
+          const configuration = await readConfiguration(options.configuration);
+          await controlledPass(context, dependencies, configuration, signal).catch((error) => {
+            if (!session.refused) throw error;
+          });
+        }
+        if (session.refused || update.requested) {
+          const sessions = await heldSessions(context);
+          if (sessions.length > 0) update.answer({ ready: false, sessions });
+          else if (session.refused || (!served.serving() && logins.size === 0 && pointerTask === null)) return;
+        }
+        await wake.wait(interval, signal);
       }
     } finally {
       watcher.abort();
@@ -922,7 +1012,31 @@ export async function runResident(options, dependencies = {}) {
       for (const running of logins.values()) running.controller.abort();
       await Promise.all([...logins.values()].map((running) => running.task));
       await context.agentRefresh;
-      await closeResident();
     }
-  }, options.signal);
+  };
+  try {
+    for (;;) {
+      try {
+        await maintainControl(session, serve, options.signal, { release: false });
+      } catch (error) {
+        await releaseControl(session);
+        throw error;
+      }
+      if (session.refused) break;
+      try {
+        await releaseControl(session, { required: true });
+        break;
+      } catch (refusal) {
+        if (!(refusal instanceof KitRefusal)) throw refusal;
+        if (session.refused) break;
+        update.answer({ ready: false, sessions: [], refused: refusal.code });
+      }
+      await wake.wait(interval, options.signal);
+    }
+    update.quiesce();
+    while (!options.signal.aborted) await wake.wait(interval, options.signal);
+    throw new KitRefusal("kit_command_cancelled");
+  } finally {
+    await served.close();
+  }
 }