@agentshouse/kit 0.1.0-alpha.27 → 0.1.0-alpha.28

package/README.md

@@ -12,7 +12,7 @@ The Skill set Kit installs is Matt Pocock's
 On Linux `amd64` or `arm64`, run the published, versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.27/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.28/connect-linux.sh)
 ```
 
 The bootstrap first establishes Docker Engine from what it observes on the
@@ -446,7 +446,9 @@ kit setup
 ```
 
 `kit worker run` performs the same step at the start of a pass, before it
-hands out any work, so a managed Environment needs no terminal. The walk first
+hands out any work, so a managed Environment needs no terminal; the resident
+Kit performs it each time its control stream connects and on each `runs`
+signal, which House also sends for every setup request. The walk first
 prepares the absolute `/agents/house` base, then visits every declared agent
 CLI and then every connector instance, in configuration order:
 
@@ -557,6 +559,39 @@ send one JSON line
 with `action: "authorization"` and `mode: "status"` or `mode: "login"`; the
 command returns exactly one JSON object such as `{ "authorized": true }`.
 
+## The Kit control stream
+
+The resident Kit holds one `/kit/stream` WebSocket for its Environment,
+authenticated with its Environment control lease and the Kit contract header,
+for as long as it holds that lease; `kit worker run` holds one for the length
+of its pass to receive its owner's commands. The Kit sends nothing on it and
+accepts every frame House sends.
+
+Each time the socket connects, the resident acquires everything a signal could
+have named, because a signal House sent while the socket was down is lost: its
+Runs and resumptions with their setup and conversation files, the owner's
+pending commands, the agent CLI list, the saved working copy choice and its
+Google Sources. After that it acquires only what House names. A
+`work_available` frame for `agents`, `working_copy` or `sources` acquires that
+subject alone. `runs` takes a resumption or else a waiting Run, readying the
+agent CLIs, a requested setup and conversation files first. `commands` hands
+the supervised Session its stops, interrupts and answers and takes a
+resumption the same way, without acquiring a Run. An `entries` frame, a change
+in a Room the lease admits, delivers the working copies. A pass that took a Run
+acquires again once that Run ends, and a pass that found nothing waits for the
+next signal. A Run outcome House did not take is reported again every 30
+seconds until House answers. The Kit has no idle acquisition cycle, no command
+poll and no Session heartbeat: a Session is observed when its process starts
+and when its supervisor sees it stop.
+
+A socket that closes or never opens reconnects after a delay drawn between half
+and all of one second, doubled for each consecutive failure up to 30 seconds.
+An `authority_changed` close reconnects after a delay drawn between 0 and 2
+seconds, with no error backoff. A `replaced` close, which means a newer
+connection holds the Environment, ends the resident with `kit_stream_replaced`,
+and an upgrade House refuses with `kit_upgrade_required` stops every House call
+as [above](#connect-a-linux-computer) describes; neither is retried.
+
 ## The Worker runtime
 
 ```sh
@@ -980,8 +1015,9 @@ A save that fails leaves one note in `state/conversation-originals/` naming the
 attachment, its Run, the local file and the descriptor it declared. Each
 later `kit worker run` retries it from that file without materializing or
 acknowledging anything again, and reports `source_unavailable` when
-the file is gone or changed rather than saving different bytes. While a
-WorkerSession stays supervised the same retry runs at the heartbeat interval. The note leaves once
+the file is gone or changed rather than saving different bytes. When a
+supervised WorkerSession ends, the same retry runs once more before its Run is
+reported. The note leaves once
 House records the save, once House answers that the Run is over, or when House
 authorizes that Run's cache cleanup; House accepts no save for a Run that has
 settled, so an unsaved original keeps its failed outcome from then on. The owner
@@ -1117,7 +1153,10 @@ written into the durable binding. Reconciliation must obtain current House
 authority before the live process can make further calls.
 
 An owner stop requested through House reaches this Kit as a durable command,
-both at startup and while a Session is supervised. The Kit destroys the exact
+both at startup and while a Session is supervised: House signals `commands` on
+the Kit control stream and the supervisor acquires the pending stops,
+interrupts and answers at once, so a stop reaches the process within a second.
+The Kit destroys the exact
 tmux session, confirms that it is gone, and reports the stopped Session. It
 reports no continuation for a Run stopped by its owner and never reopens the
 local channel for that Session.
@@ -1278,8 +1317,8 @@ The Environment owner chooses in House which Rooms this Environment keeps
 locally, and whether it keeps `/private`. An Environment whose owner never chose
 copies nothing, and a Room joined later stays uncopied until the owner selects
 it. The resident Kit reads the saved choice through
-`POST /kit/working-copy/selection` when it starts, whenever its control stream
-connects or reconnects, and whenever House points it there after a save;
+`POST /kit/working-copy/selection` whenever its control stream connects or
+reconnects and whenever House points it there after a save;
 `kit worker run` reads it once before its pass.
 
 Each selected Room becomes one ordinary Git repository at
@@ -1308,8 +1347,9 @@ state. The House revision of every file content Kit received, keyed by path,
 Git blob and the House state that received it, stays in Kit home under
 `state/working-copies/`, outside the repository. A local commit is a local tree, never a House revision.
 
-The resident Kit keeps every active copy current. On each pass, and whenever
-it reads the saved choice, one `POST /kit/door/discover` tells it where each
+The resident Kit keeps every active copy current. Whenever its control stream
+carries a Room change, and whenever it reads the saved choice, one
+`POST /kit/door/discover` tells it where each
 copied Room stands, and for a Room that moved on it reads the changes after the
 copy's recorded position through `POST /kit/door/enumerate`. A changed, new or
 removed authored file becomes a commit on `refs/house/received`, its House
@@ -1328,7 +1368,8 @@ or protected paths House declares for the Room change, Kit reads the Room again
 as a reselection does. A position older than House
 retains, or from before House's database was restored, makes Kit read the Room
 again as a reselection does; while House's replica has not reached the position
-the copy waits for the next pass. A Room House no longer answers under its
+the copy waits, and the resident delivers again 30 seconds later. A Room House
+no longer answers under its
 recorded handle makes Kit read the saved choice again, which follows a handle
 change or marks the copy inactive, and a Room that lost sync is named on
 standard error as `operation_denied` and keeps what it holds. `kit worker run`

package/bootstrap.json

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

package/package.json

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

package/src/contract.js

@@ -1,6 +1,6 @@
 import { CLAUDE_PASTED_CODE, CODEX_DEVICE_CODE, GROK_DEVICE_CODE } from "./agent-logins.js";
 
-export const KIT_CONTRACT_VERSION = "1";
+export const KIT_CONTRACT_VERSION = "2";
 export const KIT_CAPTURE_BATCH_MAX = 100;
 export const COMMAND_INPUT_MAX_BYTES = 4 * 1024;
 export const AUTHORIZATION_OUTPUT_MAX_BYTES = 4 * 1024;
@@ -21,10 +21,11 @@ export const COMMAND_ADAPTER_SESSION_TIMEOUT_MS = 30_000;
 export const WORKER_EXIT_GRACE_MS = 5_000;
 export const WORKER_EXIT_POLL_MS = 100;
 export const WORKER_SUPERVISION_POLL_MS = 2_000;
-export const WORKER_COMMAND_POLL_MS = 2_000;
-export const WORKER_HEARTBEAT_MS = 30_000;
 export const WORKER_COMMAND_BATCH_MAX = 10;
 export const WORKER_RUN_TOKEN_MARGIN_MS = 60_000;
+export const KIT_STREAM_RECONNECT_MS = 1_000;
+export const KIT_STREAM_RECONNECT_MAX_MS = 30_000;
+export const KIT_STREAM_REJOIN_MS = 2_000;
 export const TELEGRAM_IMAGE_UPLOAD_CEILING_BYTES = 10 * 1024 * 1024;
 export const CONVERSATION_FILE_TRANSFER_TIMEOUT_MS = 30_000;
 export const WORKER_INHERITED_ENVIRONMENT = ["PATH", "HOME"];

package/src/house.js

@@ -1117,17 +1117,6 @@ function acquiredInterrupt(value, declaration) {
   };
 }
 
-export async function reportSessionHeartbeat(session, workerSession) {
-  await houseRequest(
-    session.house,
-    await heldControl(session),
-    `/kit/sessions/${encodeURIComponent(workerSession)}/heartbeat`,
-    {},
-    session.dependencies,
-    session.signal,
-  );
-}
-
 function answeredValue(value, declaration) {
   if (typeof value === "boolean") return value;
   if (typeof value === "number") {

package/src/kit-work-stream.js

@@ -1,11 +1,17 @@
 import { setTimeout as delay } from "node:timers/promises";
 import WebSocket from "ws";
-import { KIT_CONTRACT_VERSION } from "./contract.js";
+import {
+  KIT_CONTRACT_VERSION,
+  KIT_STREAM_RECONNECT_MAX_MS,
+  KIT_STREAM_RECONNECT_MS,
+  KIT_STREAM_REJOIN_MS,
+} from "./contract.js";
 import { heldControl } from "./house.js";
 import { KitRefusal } from "./refusal.js";
 
 const PROTOCOL = "house.kit.stream.1";
-const WATCHED_SUBJECTS = ["agents", "working_copy", "sources"];
+const WORK_SUBJECTS = ["runs", "commands", "agents", "working_copy", "sources"];
+const FINAL_REFUSALS = ["kit_upgrade_required", "kit_stream_replaced"];
 
 function streamAddress(house) {
   const url = new URL("/kit/stream", house);
@@ -15,72 +21,88 @@ function streamAddress(house) {
   return url;
 }
 
-async function connected(session, signal, available, dependencies) {
+function frameOf(data) {
+  try {
+    return JSON.parse(data.toString());
+  } catch {
+    return null;
+  }
+}
+
+async function held(session, signal, heard, dependencies) {
   const authorization = await heldControl(session, signal);
   return new Promise((resolve, reject) => {
     const Socket = dependencies.workSocket ?? WebSocket;
     const socket = new Socket(streamAddress(session.house), PROTOCOL, {
       headers: { authorization, "x-house-kit-version": KIT_CONTRACT_VERSION },
       handshakeTimeout: 10_000,
-      maxPayload: 4096,
       perMessageDeflate: false,
     });
     let finished = false;
-    const finish = (error = null) => {
+    const finish = (reason = null, refusal = null) => {
       if (finished) return;
       finished = true;
       signal.removeEventListener("abort", stop);
-      if (error === null) resolve();
-      else reject(error);
+      if (refusal === null) resolve(reason);
+      else reject(refusal);
     };
     const stop = () => {
       socket.terminate();
       finish();
     };
     signal.addEventListener("abort", stop, { once: true });
-    socket.on("open", () => available(null));
+    socket.on("open", () => heard.available(null));
     socket.on("message", (data) => {
-      let frame;
-      try {
-        frame = JSON.parse(data.toString());
-      } catch {
-        return;
-      }
-      if (frame?.type === "work_available" && WATCHED_SUBJECTS.includes(frame.subject)) {
-        available(frame.subject);
+      const frame = frameOf(data);
+      if (frame?.type === "work_available" && WORK_SUBJECTS.includes(frame.subject)) {
+        heard.available(frame.subject);
+      } else if (frame?.type === "entries") {
+        heard.changed();
       }
     });
     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;
+      finish(null, response.statusCode === 409 ? new KitRefusal("kit_upgrade_required") : null);
       socket.terminate();
-      finish(refusal);
     });
     socket.on("error", () => {
       socket.terminate();
       finish();
     });
-    socket.on("close", () => finish());
+    socket.on("close", (_code, reason) => {
+      const closed = reason?.toString() ?? "";
+      finish(closed, closed === "replaced" ? new KitRefusal("kit_stream_replaced") : null);
+    });
     if (signal.aborted) stop();
   });
 }
 
-export async function watchKitWork(session, signal, available, dependencies = {}) {
-  let retryMs = 500;
+export async function watchKitWork(session, signal, heard, dependencies = {}) {
+  const random = dependencies.random ?? Math.random;
+  const sleep = dependencies.streamSleep ?? ((milliseconds) => delay(milliseconds, undefined, { signal }));
+  let failures = 0;
   while (!signal.aborted) {
     const began = Date.now();
+    let reason = null;
     try {
-      await connected(session, signal, available, dependencies);
+      reason = await held(session, signal, heard, dependencies);
     } catch (error) {
-      if (error instanceof KitRefusal && error.code === "kit_upgrade_required") throw error;
-      if (signal.aborted) return;
+      if (error instanceof KitRefusal && FINAL_REFUSALS.includes(error.code)) throw error;
     }
     if (signal.aborted) return;
-    retryMs = Date.now() - began >= 30_000 ? 1000 : Math.min(retryMs * 2, 30_000);
+    let wait;
+    if (reason === "authority_changed") {
+      failures = 0;
+      wait = random() * KIT_STREAM_REJOIN_MS;
+    } else {
+      if (Date.now() - began >= KIT_STREAM_RECONNECT_MAX_MS) failures = 0;
+      const ceiling = Math.min(KIT_STREAM_RECONNECT_MAX_MS, KIT_STREAM_RECONNECT_MS * 2 ** failures);
+      failures += 1;
+      wait = ceiling / 2 + (random() * ceiling) / 2;
+    }
     try {
-      await delay(dependencies.workReconnectMs ?? retryMs, undefined, { signal });
+      await sleep(wait);
     } catch (error) {
       if (!signal.aborted) throw error;
     }

package/src/tasks.js

@@ -33,25 +33,28 @@ export function residentWake() {
       release?.();
     },
     async wait(milliseconds, signal) {
-      if (pending) {
-        pending = false;
-        return;
-      }
-      const pause = new AbortController();
-      try {
-        await Promise.race([
-          new Promise((resolve) => {
-            release = resolve;
-          }),
-          delay(milliseconds, undefined, { signal: AbortSignal.any([signal, pause.signal]) }),
-        ]);
-      } catch (error) {
-        if (!signal.aborted) throw error;
-      } finally {
-        release = null;
-        pending = false;
-        pause.abort();
+      if (!pending && !signal.aborted) {
+        const pause = new AbortController();
+        const paused = AbortSignal.any([signal, pause.signal]);
+        try {
+          await Promise.race([
+            new Promise((resolve) => {
+              release = resolve;
+            }),
+            Number.isFinite(milliseconds)
+              ? delay(milliseconds, undefined, { signal: paused })
+              : new Promise((resolve) => paused.addEventListener("abort", resolve, { once: true })),
+          ]);
+        } catch (error) {
+          if (!signal.aborted) throw error;
+        } finally {
+          release = null;
+          pause.abort();
+        }
       }
+      const woken = pending;
+      pending = false;
+      return woken;
     },
   };
 }

package/src/worker.js

@@ -40,10 +40,8 @@ import {
   MCP_REQUEST_BODY_MAX_BYTES,
   PROVIDER_CONTINUATION_UNAVAILABLE,
   WORKER_COMMAND_BATCH_MAX,
-  WORKER_COMMAND_POLL_MS,
   WORKER_EXIT_GRACE_MS,
   WORKER_EXIT_POLL_MS,
-  WORKER_HEARTBEAT_MS,
   WORKER_INHERITED_ENVIRONMENT,
   WORKER_SUPERVISION_POLL_MS,
   WORKING_COPY_INDEX_METHOD,
@@ -76,7 +74,6 @@ import {
   reportInteractionOutcome,
   toolMutations,
   reportRunOutcome,
-  reportSessionHeartbeat,
   releaseControl,
   reportSessions,
   serveResident,
@@ -101,6 +98,7 @@ import {
 
 const LAUNCHER_MAIN = fileURLToPath(new URL("launcher-main.js", import.meta.url));
 const RESIDENT_INTERVAL_MS = 30_000;
+const PASS_REACHES = ["commands", "runs"];
 
 async function dispatchSeal(context, bound) {
   try {
@@ -134,9 +132,7 @@ async function pendingCommands(context, kinds = ["stop"]) {
   try {
     return await acquireCommands(context.session, WORKER_COMMAND_BATCH_MAX, kinds);
   } catch (refusal) {
-    if (houseFailed(refusal) || context.session.refused === true) {
-      return { stops: [], answers: [], interrupts: [] };
-    }
+    if (houseFailed(refusal) || context.session.refused === true) return null;
     throw refusal;
   }
 }
@@ -157,14 +153,6 @@ async function settleInterrupt(context, interrupt, outcome) {
   }
 }
 
-async function reportHeartbeat(context, bound) {
-  try {
-    await reportSessionHeartbeat(context.session, bound.session);
-  } catch (refusal) {
-    if (!(refusal instanceof KitRefusal)) throw refusal;
-  }
-}
-
 function retryFiles(context) {
   if (context.retrying !== undefined) return;
   context.retrying = retryConversationFiles(context)
@@ -187,40 +175,32 @@ async function settleFiles(context) {
 }
 
 async function supervise(context, bound, bridge) {
-  const terminal = bridge.departed;
-  let live = true;
-  terminal.then(() => {
-    live = false;
-  });
-  let commanded = Date.now() + WORKER_COMMAND_POLL_MS;
-  let pulsed = Date.now() + WORKER_HEARTBEAT_MS;
-  while (live) {
-    await Promise.race([terminal, delay(WORKER_SUPERVISION_POLL_MS)]);
-    if (!live) return null;
+  const departed = new AbortController();
+  bridge.departed.then(() => departed.abort());
+  const waiting = AbortSignal.any([context.signal, departed.signal]);
+  let owed = false;
+  for (;;) {
+    const commanded = (await context.commands.wait(WORKER_SUPERVISION_POLL_MS, waiting)) || owed;
+    if (departed.signal.aborted) return null;
+    if (context.signal.aborted) throw new KitRefusal("kit_command_cancelled");
     await context.update?.announce();
-    if (Date.now() >= commanded) {
-      commanded = Date.now() + WORKER_COMMAND_POLL_MS;
+    if (commanded) {
       const polled = await pendingCommands(context, ["stop", "interrupt", "answer"]);
-      for (const answer of polled.answers) {
+      owed = polled === null && context.session.refused !== true;
+      for (const answer of polled?.answers ?? []) {
         if (answer.session === bound.session) bridge.answered(answer);
       }
-      for (const interrupt of polled.interrupts) {
+      for (const interrupt of polled?.interrupts ?? []) {
         if (interrupt.session !== bound.session || interrupt.run !== bound.run) continue;
         if (!bridge.interrupt(interrupt)) {
           await settleInterrupt(context, interrupt.interrupt, "nothing_to_interrupt");
         }
       }
-      const stop = polled.stops.find((command) => command.run === bound.run);
+      const stop = polled?.stops.find((command) => command.run === bound.run);
       if (stop !== undefined) return stop;
     }
-    if (Date.now() >= pulsed) {
-      pulsed = Date.now() + WORKER_HEARTBEAT_MS;
-      retryFiles(context);
-      await reportHeartbeat(context, bound);
-    }
     if (!(await sessionPresent(context.runtime, bound.tmux))) return null;
   }
-  return null;
 }
 
 async function grantExitGrace(runtime, handle) {
@@ -432,6 +412,7 @@ async function superviseBound(context, bound, opened, start) {
   } finally {
     try {
       try {
+        retryFiles(context);
         await settleFiles(context);
         for (const interaction of bridge.unsettledInteractions()) {
           await settleInteraction(context, interaction, "expired");
@@ -727,7 +708,7 @@ async function reconcile(context) {
   }
   const bindings = await readBindings(context.directory);
   if (bindings.length === 0) return { run: null, stopped, unresolved };
-  const commands = (await pendingCommands(context)).stops;
+  const commands = (await pendingCommands(context))?.stops ?? [];
   const carried = [];
   for (const binding of bindings) {
     if (binding.reported !== null) {
@@ -811,7 +792,7 @@ function unlessDraining(context, act) {
   return context.update?.requested ? null : act();
 }
 
-async function workerPass(context, dependencies, baseConfiguration) {
+async function workerPass(context, dependencies, baseConfiguration, reach) {
   const { session, signal } = context;
   const reconciled = await reconcile(context);
   if (reconciled.run !== null || reconciled.unresolved.length > 0 || context.update?.requested) {
@@ -842,6 +823,7 @@ async function workerPass(context, dependencies, baseConfiguration) {
   }
   const resumption = await unlessDraining(context, () => acquireOneResumption(session));
   if (resumption !== null) return { ...reconciled, run: await superviseResumption(context, resumption) };
+  if (reach !== "runs") return reconciled;
   const assignment = await unlessDraining(context, () => acquireOneRun(session));
   if (assignment === null) return reconciled;
   return { ...reconciled, run: await superviseAssignment(context, assignment) };
@@ -865,6 +847,7 @@ async function workerContext(options, dependencies, resident = false) {
     directory: options.directory,
     home: dependencies.home ?? homedir(),
     files: { originals: [], failures: [] },
+    commands: residentWake(),
     epochReport: null,
     agentRefresh: Promise.resolve(),
     configurationPath: options.configuration,
@@ -909,7 +892,7 @@ function queueAgentRefresh(context, dependencies, signal, configuration, pointer
   return refreshed;
 }
 
-async function controlledPass(context, dependencies, configuration, signal) {
+async function controlledPass(context, dependencies, configuration, signal, reach = "runs") {
   context.signal = signal;
   context.session.signal = signal;
   await reconcileSkillSet({
@@ -919,7 +902,7 @@ async function controlledPass(context, dependencies, configuration, signal) {
   });
   context.busy = true;
   try {
-    return await afterEpochReport(context, () => workerPass(context, dependencies, configuration));
+    return await afterEpochReport(context, () => workerPass(context, dependencies, configuration, reach));
   } finally {
     context.busy = false;
     if (context.deferredRemoval) context.onIdle?.();
@@ -930,8 +913,23 @@ export async function runWorkers(options, dependencies = {}) {
   const { context, tmux } = await workerContext(options, dependencies);
   const { session, runtime } = context;
   const supervised = await maintainControl(session, async (signal) => {
-    await reportedWorkingCopies(applyWorkingCopies, context, signal);
-    return controlledPass(context, dependencies, context.configuration, signal);
+    const watcher = new AbortController();
+    const commanded = (subject) => {
+      if (subject === null || subject === "commands") context.commands.notify();
+    };
+    const watching = (dependencies.watchKitWork ?? watchKitWork)(
+      session,
+      AbortSignal.any([signal, watcher.signal]),
+      { available: commanded, changed: () => {} },
+      dependencies,
+    ).catch((error) => reported(`control stream ended: ${error?.code ?? error?.message ?? error}`));
+    try {
+      await reportedWorkingCopies(applyWorkingCopies, context, signal);
+      return await controlledPass(context, dependencies, context.configuration, signal);
+    } finally {
+      watcher.abort();
+      await watching;
+    }
   }, session.signal);
   return {
     tmux,
@@ -952,9 +950,11 @@ function reported(line) {
 }
 
 async function reportedWorkingCopies(act, context, signal) {
-  for (const refused of (await act(context, signal)).refused) {
+  const outcome = await act(context, signal);
+  for (const refused of outcome.refused) {
     reported(`working copy ${refused.path} refused: ${refused.code}`);
   }
+  return outcome;
 }
 
 function residentUpdate(context, wake) {
@@ -1092,11 +1092,18 @@ export async function runResident(options, dependencies = {}) {
       context.startLogins(needsLogin);
     });
     const unavailable = (error) => reported(`working copies unavailable: ${error?.message ?? error}`);
-    const copies = coalescedTask(signal, unavailable, () =>
-      reportedWorkingCopies(applyWorkingCopies, context, signal),
+    const changed = () => {
+      if (!update.requested) deliveries.trigger();
+    };
+    const behind = (outcome) => {
+      if (!outcome.behind) return;
+      controlSleep(interval, signal).then(changed, () => {});
+    };
+    const copies = coalescedTask(signal, unavailable, async () =>
+      behind(await reportedWorkingCopies(applyWorkingCopies, context, signal)),
     );
-    const deliveries = coalescedTask(signal, unavailable, () =>
-      reportedWorkingCopies(deliverWorkingCopies, context, signal),
+    const deliveries = coalescedTask(signal, unavailable, async () =>
+      behind(await reportedWorkingCopies(deliverWorkingCopies, context, signal)),
     );
     sources = sourceEntries({
       session: context.session,
@@ -1111,7 +1118,38 @@ export async function runResident(options, dependencies = {}) {
     const pointer = () => {
       if (!update.requested) agentRefresh.trigger();
     };
-    const available = (subject = null) => {
+    let passOwed = null;
+    let deferred = null;
+    let retrying = null;
+    const higher = (reach, than) =>
+      PASS_REACHES.indexOf(reach) > PASS_REACHES.indexOf(than) ? reach : than;
+    const owe = (reach) => {
+      passOwed = higher(reach, passOwed);
+      wake.notify();
+    };
+    const defer = (reach) => {
+      deferred = higher(reach, deferred);
+      if (retrying !== null) return;
+      retrying = new AbortController();
+      controlSleep(interval, AbortSignal.any([signal, retrying.signal])).then(() => {
+        retrying = null;
+        const owed = deferred;
+        deferred = null;
+        owe(owed);
+      }, () => {});
+    };
+    const settle = (reach) => {
+      retrying?.abort();
+      retrying = null;
+      if (higher(deferred, reach) !== reach) owe(deferred);
+      deferred = null;
+    };
+    const available = (subject) => {
+      if (subject === null || subject === "runs") owe("runs");
+      if (subject === null || subject === "commands") {
+        context.commands.notify();
+        owe("commands");
+      }
       if (update.requested) return;
       if (subject === null || subject === "agents") agentRefresh.trigger();
       if (subject === null || subject === "working_copy") copies.trigger();
@@ -1119,23 +1157,31 @@ export async function runResident(options, dependencies = {}) {
     };
     context.onIdle = pointer;
     context.workingCopiesApplied = copies.settled;
-    if (!update.requested) copies.trigger();
     const watching = (dependencies.watchKitWork ?? watchKitWork)(
       context.session,
       AbortSignal.any([signal, watcher.signal]),
-      available,
+      { available, changed },
       dependencies,
     ).catch(fail);
     try {
       while (!signal.aborted) {
         if (failure !== null) throw failure;
-        if (!session.refused) {
+        if (passOwed !== null && !session.refused) {
+          const reach = passOwed;
+          passOwed = null;
           const configuration = await readConfiguration(options.configuration);
-          await controlledPass(context, dependencies, configuration, signal).catch((error) => {
-            if (!session.refused) throw error;
-          });
+          const passed = await controlledPass(context, dependencies, configuration, signal, reach).catch(
+            (error) => {
+              if (!session.refused) throw error;
+              return null;
+            },
+          );
+          if ((passed?.run ?? null) !== null) owe(reach);
+          if ((passed?.unresolved.length ?? 0) > 0) defer(reach);
+          else if (passed !== null) settle(reach);
         }
-        if (session.refused || update.requested) {
+        const draining = session.refused || update.requested;
+        if (draining) {
           const sessions = await heldSessions(context);
           if (sessions.length > 0) update.answer({ ready: false, sessions });
           else if (
@@ -1150,8 +1196,7 @@ export async function runResident(options, dependencies = {}) {
             return;
           }
         }
-        await wake.wait(interval, signal);
-        if (!update.requested && !session.refused) deliveries.trigger();
+        if (session.refused || passOwed === null) await wake.wait(draining ? interval : Infinity, signal);
       }
     } finally {
       watcher.abort();
@@ -1185,7 +1230,7 @@ export async function runResident(options, dependencies = {}) {
       await wake.wait(interval, options.signal);
     }
     update.quiesce();
-    while (!options.signal.aborted) await wake.wait(interval, options.signal);
+    while (!options.signal.aborted) await wake.wait(Infinity, options.signal);
     throw new KitRefusal("kit_command_cancelled");
   } finally {
     await served.close();

package/src/working-copy.js

@@ -497,7 +497,7 @@ async function deliver(context, path, authority, signal) {
   let copy = await readCopy(path);
   if (copy?.active && JSON.stringify(copy.received.declared) !== JSON.stringify(declaration(authority))) {
     await writeCopy(context.directory, await receive(context, copy, scopeOf(copy), signal), signal);
-    return;
+    return false;
   }
   while (
     copy?.active &&
@@ -508,24 +508,26 @@ async function deliver(context, path, authority, signal) {
     try {
       view = await enumerated(context, copy, since, signal);
     } catch (error) {
-      if (error.code === "replica_behind") return;
+      if (error.code === "replica_behind") return true;
       if (error.code !== "position_expired") throw error;
       await writeCopy(context.directory, await receive(context, copy, scopeOf(copy), signal), signal);
-      return;
+      return false;
     }
-    if (view.position === since.position) return;
+    if (view.position === since.position) return false;
     copy = await incorporated(copy, view, authority, signal);
     await writeCopy(context.directory, copy, signal);
   }
+  return false;
 }
 
 async function delivering(context, signal) {
   const copies = (await heldCopies(context.directory)).filter((copy) => copy.active);
-  if (copies.length === 0) return { refused: [], lost: false };
+  if (copies.length === 0) return { refused: [], lost: false, behind: false };
   const prefixes = copies.flatMap((copy) => selectedPrefixes(scopeOf(copy)));
   const discovery = discoveryOf(await door(context.session, KIT_DOOR_DISCOVER_PATH, { prefixes }, signal));
   const refused = [];
   let lost = false;
+  let behind = false;
   for (const copy of copies) {
     const at = housePath(scopeOf(copy));
     const authority = discovery.authorities.find((entry) => entry?.room_ref === copy.room_ref);
@@ -539,18 +541,24 @@ async function delivering(context, signal) {
     }
     const path = copyPath(context.directory, copy);
     try {
-      await exclusively(path, () => deliver(context, path, authority, signal));
+      if (await exclusively(path, () => deliver(context, path, authority, signal))) behind = true;
     } catch (error) {
       if (!scopeRefused(error)) throw error;
       refused.push({ path: at, code: error.code });
     }
   }
-  return { refused, lost };
+  return { refused, lost, behind };
+}
+
+function deliveredOutcome(refused, behind) {
+  return behind ? { refused, behind } : { refused };
 }
 
 export async function deliverWorkingCopies(context, signal) {
   const delivered = await delivering(context, signal);
-  return delivered.lost ? applyWorkingCopies(context, signal) : { refused: delivered.refused };
+  return delivered.lost
+    ? applyWorkingCopies(context, signal)
+    : deliveredOutcome(delivered.refused, delivered.behind);
 }
 
 export async function applyWorkingCopies(context, signal) {
@@ -582,7 +590,8 @@ export async function applyWorkingCopies(context, signal) {
       refused.push({ path: housePath(scope), code: error.code });
     }
   }
-  return { refused: [...refused, ...(await delivering(context, signal)).refused] };
+  const delivered = await delivering(context, signal);
+  return deliveredOutcome([...refused, ...delivered.refused], delivered.behind);
 }
 
 export async function workingCopyPaths(directory) {