@agentshouse/kit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/worker.js

@@ -1,17 +1,32 @@
 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";
-import { agentReadiness, installedAgentCommand, updateDeclaredAgents } from "./agents.js";
+import {
+  installedAgentCommand,
+  readAgentState,
+  reconcileAgentKinds,
+} from "./agents.js";
 import { readBindings, removeBinding, writeBinding } from "./binding.js";
 import { readContinuation, readContinuationRuns, writeContinuation, removeContinuation } from "./continuation.js";
-import { openBridge } from "./bridge.js";
+import { bridgedFrame, openBridge } from "./bridge.js";
 import { assistantBlocks } from "./blocks.js";
 import { retryConversationFiles } from "./conversation-originals.js";
 import { openAssistantDrafts } from "./draft.js";
-import { localReply, localRequest, reconcileInbound } from "./inbound.js";
+import { localRequest, reconcileInbound } from "./inbound.js";
 import { localFiles } from "./local-files.js";
+import { answerText, answerYaml } from "./mcp.js";
 import { inheritedEnvironment } from "./command.js";
+import { watchKitWork } from "./kit-work-stream.js";
+import {
+  applyWorkingCopies,
+  deliverWorkingCopies,
+  ownerCaller,
+  pushWorkingCopy,
+  recordIndexChange,
+  workingCopyPaths,
+} from "./working-copy.js";
 import { readConfiguration } from "./configuration.js";
 import { launchBase, readyLaunchDirectory } from "./directory.js";
 import {
@@ -25,13 +40,14 @@ import {
   WORKER_HEARTBEAT_MS,
   WORKER_INHERITED_ENVIRONMENT,
   WORKER_SUPERVISION_POLL_MS,
+  WORKING_COPY_INDEX_METHOD,
+  WORKING_COPY_PUSH_METHOD,
 } from "./contract.js";
-import { EpochReportRequired, houseFailed, KitRefusal } from "./refusal.js";
+import { EpochReportRequired, formatCommandError, houseFailed, KitRefusal } from "./refusal.js";
 import {
   acceptAssistantText,
   acquireCommands,
   acquireSetup,
-  reportAgentCapabilities,
   acquireOneRun,
   acquireOneResumption,
   admitInteraction,
@@ -40,12 +56,13 @@ import {
   rejectResumption,
   callHouseMcp,
   commitRun,
-  desiredAgents,
+  controlSleep,
   maintainControl,
   mutatingCall,
   observeSessionStart,
   observeSessionStop,
   openSession,
+  readRunRequest,
   replaceSessionAuthority,
   reportContinuation,
   reportInterruptOutcome,
@@ -53,13 +70,17 @@ import {
   toolMutations,
   reportRunOutcome,
   reportSessionHeartbeat,
+  releaseControl,
   reportSessions,
+  serveResident,
   sessionAuthority,
   streamAssistantDraft,
+  updateDrain,
 } from "./house.js";
 import { operationId } from "./operation.js";
-import { runSetup } from "./setup.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,
@@ -71,47 +92,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))
   );
@@ -121,7 +126,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;
   }
 }
@@ -182,6 +189,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"]);
@@ -223,7 +231,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 };
   }
@@ -237,7 +245,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 } };
@@ -272,6 +280,54 @@ function endOnEpochReport(ended, act) {
   };
 }
 
+function refusedWith(text) {
+  const conflicts = answerYaml(text.slice(text.indexOf("\n") + 1))?.conflicts;
+  const current = Array.isArray(conflicts)
+    ? conflicts.map(({ path, state, revision }) =>
+        state === "absent" ? { path, revision: null, content: null } : { path, revision },
+      )
+    : null;
+  return { refused: { code: text.split(":")[0].trim(), text, current } };
+}
+
+function acceptedWith(text) {
+  const written = new Map();
+  for (const { path, op, revision, from } of answerYaml(text).results) {
+    if (from !== undefined) written.set(from, { path: from, revision: null, content: null });
+    written.set(path, op === "remove" ? { path, revision: null, content: null } : { path, revision });
+  }
+  return { refused: null, written: [...written.values()] };
+}
+
+async function sessionPush(context, bound, authority, frame, signal) {
+  const edit = async (body, sent) => {
+    const answer = await callHouseMcp(
+      context.session,
+      await sessionAuthority(context.session, bound.session, authority, sent),
+      bridgedFrame(
+        { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "edit", arguments: { changes: body.changes } } },
+        body.operation_id,
+      ),
+      sent,
+    );
+    if (answer.error !== undefined) return refusedWith(answer.error.message ?? "kit_house_refused");
+    const text = answerText(answer.result);
+    return answer.result?.isError === true ? refusedWith(text) : acceptedWith(text);
+  };
+  let outcome;
+  try {
+    outcome = await pushWorkingCopy(context, frame.params, { binding: { session: bound.session }, submit: edit }, signal);
+  } catch (refusal) {
+    if (!(refusal instanceof KitRefusal)) throw refusal;
+    outcome = { refused: true, text: refusal.message };
+  }
+  return {
+    jsonrpc: "2.0",
+    id: frame.id,
+    result: { content: [{ type: "text", text: outcome.text }], ...(outcome.refused ? { isError: true } : {}) },
+  };
+}
+
 async function openRunBridge(context, bound, authority, start) {
   const ended = new AbortController();
   const handed = (act) => endOnEpochReport(ended, act);
@@ -293,14 +349,17 @@ async function openRunBridge(context, bound, authority, start) {
     ),
     secret: (interaction, ceremony) => awaitSecretInput(context.session, interaction, ceremony),
     settle: handed((interaction, outcome) => settleInteraction(context, interaction, outcome)),
-    forward: handed((frame, signal) =>
-      localFiles(async (sent) =>
-        localReply(context.directory, bound.run, sent, await callHouseMcp(
+    forward: handed((frame, signal) => frame.method === WORKING_COPY_PUSH_METHOD
+      ? sessionPush(context, bound, authority, frame, signal)
+      : frame.method === WORKING_COPY_INDEX_METHOD
+      ? recordIndexChange(context, frame.params, signal).then(() => ({ jsonrpc: "2.0", id: frame.id, result: {} }))
+      : localFiles(async (sent) =>
+        callHouseMcp(
           context.session,
           await sessionAuthority(context.session, bound.session, authority, signal),
           sent,
           signal,
-        )), context.session.dependencies, signal)(frame)),
+        ), context.session.dependencies, signal)(frame)),
   });
   return { bridge, drafts, ended };
 }
@@ -371,50 +430,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) {
@@ -425,6 +499,11 @@ function assignmentRoute(context, assignment) {
   return assignment.route;
 }
 
+async function appliedWorkingCopies(context) {
+  await context.workingCopiesApplied?.();
+  return workingCopyPaths(context.directory);
+}
+
 async function prepareAssignment(context, assignment, resumed) {
   const route = assignmentRoute(context, assignment);
   const command = await installedAgentCommand(context.directory, route.adapter.kind);
@@ -450,8 +529,9 @@ async function prepareAssignment(context, assignment, resumed) {
     reported: null,
   };
   const authority = { token: assignment.session.token, expiresAt: assignment.session.expiresAt };
-  const opened = await openRunBridge(context, bound, authority, {
+  const start = {
     working_directory: assignment.workingDirectory,
+    working_copies: await appliedWorkingCopies(context),
     execution_authority: context.configuration.executionAuthority,
     adapter: {
       kind: route.adapter.kind,
@@ -461,10 +541,16 @@ async function prepareAssignment(context, assignment, resumed) {
       effort: route.effort,
       environment: {},
     },
-    request: await localRequest(context.directory, assignment.run, assignment.request),
+    request: null,
     provider_session: assignment.providerSessionId ?? null,
-  });
-  return { bound, opened };
+  };
+  const opened = await openRunBridge(context, bound, authority, start);
+  const request = async () => {
+    const token = await sessionAuthority(context.session, bound.session, authority);
+    start.request = await localRequest(context.directory, bound.run,
+      await readRunRequest(context.session, bound.run, token));
+  };
+  return { bound, opened, request };
 }
 
 async function refuseContinuation(context, command, failure) {
@@ -502,14 +588,15 @@ 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;
+  const { bound, opened, request } = prepared;
   return superviseBound(context, bound, opened, async (spawn) => {
     if (!resumed) await commitRun(context.session, assignment.run);
     spawn.committed = true;
     await writeBinding(context.directory, bound);
+    await request();
     await createSession(context.runtime, {
       session: bound.tmux,
       workingDirectory: assignment.workingDirectory,
@@ -531,7 +618,7 @@ async function superviseResumption(context, command) {
   }
   return superviseAssignment(context, {
     ...command, agentId: held.agentId, workingDirectory: held.workingDirectory,
-    conversation: held.conversation, providerSessionId: held.providerSessionId, request: null,
+    conversation: held.conversation, providerSessionId: held.providerSessionId,
   }, true);
 }
 
@@ -551,7 +638,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);
@@ -567,7 +654,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);
@@ -589,17 +676,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) {
@@ -639,7 +726,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,
@@ -666,39 +753,54 @@ async function afterEpochReport(context, pass) {
   return pass();
 }
 
-async function workerPass(context, dependencies) {
-  const { configuration, session, signal } = context;
+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;
-  context.inbound = await reconcileInbound(context.directory, session);
-  const setup = await acquireSetup(session, signal);
+  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 unlessDraining(context, () => reconcileInbound(context.directory, session));
+  const setup = await unlessDraining(context, () => acquireSetup(session, signal));
   if (setup !== null) {
     context.setup = await runSetup(
-      { session, configuration, directory: context.directory, dependencies, signal },
+      {
+        session,
+        configuration,
+        directory: context.directory,
+        dependencies,
+        signal,
+        waitAgentLogin: context.waitAgentLogin,
+      },
       setup.request,
     );
+    await context.recordSetupLogins?.(context.setup);
+    const needsLogin = await queueAgentRefresh(context, dependencies, signal, undefined, true);
+    context.startLogins?.(needsLogin);
   }
-  context.agents = await updateDeclaredAgents(
-    { directory: context.directory, at: dependencies.now?.() },
-    configuration,
-    dependencies,
-  );
-  const readiness = await agentReadiness({ directory: context.directory }, configuration, dependencies);
-  await reportAgentCapabilities(session, readiness.agents);
-  if (readiness.refused !== null) throw readiness.refused;
-  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, dependencies);
+  const session = resident
+    ? await residentSession(options, dependencies)
+    : await openSession({ ...options, acquire: true }, dependencies);
   const context = {
     configuration,
     runtime,
@@ -709,21 +811,66 @@ async function workerContext(options, dependencies) {
     directory: options.directory,
     files: { originals: [], failures: [] },
     epochReport: null,
+    agentRefresh: Promise.resolve(),
+    configurationPath: options.configuration,
+    busy: false,
+    deferredRemoval: false,
   };
   return { context, tmux };
 }
 
+async function refreshAgentCapabilities(context, dependencies, signal, configuration, pointer = false) {
+  const base = configuration ?? (await readConfiguration(context.configurationPath));
+  const busy = context.busy || (await readBindings(context.directory)).length > 0;
+  const result = await reconcileAgentKinds(
+    { directory: context.directory },
+    context.session,
+    base,
+    dependencies,
+    signal,
+    {
+      pointer,
+      busy,
+      lastDesired: context.lastDesired,
+      onDesired: (wanted) => context.cancelLogins?.(wanted),
+    },
+  );
+  context.deferredRemoval = result.retained.length > 0;
+  context.configuration = result.selected;
+  context.agents = result.updated;
+  context.lastDesired = [...result.selected.agents];
+  if (result.refused !== null) throw result.refused;
+  return result.reported.filter(
+    (agent) =>
+      result.selected.agents.includes(agent.kind) && agent.release !== null && !agent.signed_in,
+  );
+}
+
+function queueAgentRefresh(context, dependencies, signal, configuration, pointer = false) {
+  const refreshed = context.agentRefresh.then(() =>
+    refreshAgentCapabilities(context, dependencies, signal, configuration, pointer),
+  );
+  context.agentRefresh = refreshed.catch(() => {});
+  return refreshed;
+}
+
 async function controlledPass(context, dependencies, configuration, signal) {
-  context.configuration = { ...configuration, agents: await desiredAgents(context.session, signal) };
   context.signal = signal;
   context.session.signal = signal;
-  return afterEpochReport(context, () => workerPass(context, dependencies));
+  context.busy = true;
+  try {
+    return await afterEpochReport(context, () => workerPass(context, dependencies, configuration));
+  } finally {
+    context.busy = false;
+    if (context.deferredRemoval) context.onIdle?.();
+  }
 }
 
 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);
   }, session.signal);
   return {
@@ -740,17 +887,283 @@ export async function runWorkers(options, dependencies = {}) {
   };
 }
 
-export async function runResident(options, dependencies = {}) {
-  const { context } = await workerContext(options, dependencies);
-  await maintainControl(context.session, async (signal) => {
-    while (!signal.aborted) {
-      const configuration = await readConfiguration(options.configuration);
-      await controlledPass(context, dependencies, configuration, signal);
+function reported(line) {
+  process.stderr.write(`kit: ${line}\n`);
+}
+
+async function reportedWorkingCopies(act, context, signal) {
+  for (const refused of (await act(context, signal)).refused) {
+    reported(`working copy ${refused.path} refused: ${refused.code}`);
+  }
+}
+
+function coalescedTask(signal, fail, work) {
+  let pending = false;
+  let task = null;
+  const trigger = () => {
+    pending = true;
+    if (task !== null) return;
+    task = (async () => {
+      while (pending && !signal.aborted) {
+        pending = false;
+        await work();
+      }
+    })()
+      .catch((error) => {
+        if (signal.aborted) return;
+        fail(error);
+      })
+      .finally(() => {
+        task = null;
+        if (pending && !signal.aborted) trigger();
+      });
+  };
+  return { trigger, idle: () => task === null, settled: () => task };
+}
+
+function residentWake() {
+  let pending = false;
+  let release = null;
+  return {
+    notify() {
+      pending = true;
+      release?.();
+    },
+    async wait(milliseconds, signal) {
+      if (pending) {
+        pending = false;
+        return;
+      }
+      const pause = new AbortController();
       try {
-        await delay(dependencies.residentIntervalMs ?? 30_000, undefined, { signal });
+        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();
+      }
+    },
+  };
+}
+
+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, 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),
+    (request, signal) =>
+      pushWorkingCopy({ directory: context.directory, session }, request, ownerCaller(session), signal).catch(
+        (error) => ({ refused: true, text: formatCommandError(error) }),
+      ),
+  );
+  const serve = async (signal) => {
+    context.busy = true;
+    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) => {
+      for (const [kind, running] of logins) {
+        if (!wanted.includes(kind)) running.controller.abort();
+      }
+      for (const kind of attemptedLogins.keys()) {
+        if (!wanted.includes(kind)) attemptedLogins.delete(kind);
+      }
+    };
+    context.recordSetupLogins = async (modules) => {
+      for (const module of modules) {
+        if (module.category !== "agent" || module.status !== "needs_attention") continue;
+        const release = (await readAgentState(context.directory, module.name)).release;
+        if (release !== null) attemptedLogins.set(module.name, release);
+      }
+    };
+    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;
+        const controller = new AbortController();
+        const loginSignal = AbortSignal.any([signal, controller.signal]);
+        const task = (async () => {
+          if ((await acquireSetup(context.session, loginSignal)) !== null) return;
+          attemptedLogins.set(kind, release);
+          await signInWantedAgent({ ...context, dependencies, signal: loginSignal }, kind);
+          await queueAgentRefresh(context, dependencies, signal, undefined, true);
+        })()
+          .catch((error) => {
+            if (loginSignal.aborted) return;
+            fail(error);
+          })
+          .finally(() => logins.delete(kind));
+        logins.set(kind, { controller, task });
+      }
+    };
+    context.waitAgentLogin = async (kind) => {
+      await logins.get(kind)?.task;
+    };
+    const agentRefresh = coalescedTask(signal, fail, async () => {
+      const needsLogin = await queueAgentRefresh(context, dependencies, signal, undefined, true);
+      context.startLogins(needsLogin);
+    });
+    const unavailable = (error) => reported(`working copies unavailable: ${error?.message ?? error}`);
+    const copies = coalescedTask(signal, unavailable, () =>
+      reportedWorkingCopies(applyWorkingCopies, context, signal),
+    );
+    const deliveries = coalescedTask(signal, unavailable, () =>
+      reportedWorkingCopies(deliverWorkingCopies, context, signal),
+    );
+    const pointer = () => {
+      if (!update.requested) agentRefresh.trigger();
+    };
+    const available = (subject) => {
+      if (update.requested) return;
+      if (subject !== "working_copy") agentRefresh.trigger();
+      if (subject !== "agents") copies.trigger();
+    };
+    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,
+      dependencies,
+    ).catch(fail);
+    try {
+      while (!signal.aborted) {
+        if (failure !== null) throw failure;
+        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 && agentRefresh.idle() && copies.idle() && deliveries.idle())
+          ) {
+            return;
+          }
+        }
+        await wake.wait(interval, signal);
+        if (!update.requested && !session.refused) deliveries.trigger();
       }
+    } finally {
+      watcher.abort();
+      await watching;
+      await agentRefresh.settled();
+      await copies.settled();
+      await deliveries.settled();
+      for (const running of logins.values()) running.controller.abort();
+      await Promise.all([...logins.values()].map((running) => running.task));
+      await context.agentRefresh;
     }
-  }, 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();
+  }
 }