@agentshouse/kit 0.1.0-alpha.3 → 0.1.0-alpha.31

package/src/worker.js

@@ -1,66 +1,91 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 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 { transferBytes } from "./bytes.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, editRefusal } from "./mcp.js";
 import { inheritedEnvironment } from "./command.js";
+import { sourceEntries } from "./google/entries.js";
+import { watchKitWork } from "./kit-work-stream.js";
+import { finalPlan } from "./plan.js";
+import { coalescedTask, residentWake } from "./tasks.js";
+import {
+  applyWorkingCopies,
+  deliverWorkingCopies,
+  ownerCaller,
+  pushWorkingCopy,
+  recordIndexChange,
+  uploadedPaths,
+  workingCopyPaths,
+} from "./working-copy.js";
 import { readConfiguration } from "./configuration.js";
 import { launchBase, readyLaunchDirectory } from "./directory.js";
 import {
   BRIDGE_NONCE_ENVIRONMENT,
   BRIDGE_SOCKET_ENVIRONMENT,
+  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,
+  WORKING_COPY_PUSH_METHOD,
+  WORKING_COPY_UPLOAD_COMMAND,
 } 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,
-  admitPlanSnapshot,
   awaitSecretInput,
   rejectResumption,
   callHouseMcp,
   commitRun,
-  desiredAgents,
+  controlSleep,
   maintainControl,
   mutatingCall,
   observeSessionStart,
   observeSessionStop,
   openSession,
+  readRunRequest,
   replaceSessionAuthority,
   reportContinuation,
   reportInterruptOutcome,
   reportInteractionOutcome,
   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 { howWeWorkOwed, noteHowWeWork, reconcileSkillSet } from "./skill-set.js";
+import { writeText } from "./state.js";
 import { failedReport, terminalReport } from "./terminal.js";
+import { kitStreamWriter, turnFrames } from "./turn-frames.js";
 import {
   createSession,
   destroySession,
@@ -71,47 +96,32 @@ import {
 } from "./tmux.js";
 
 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 {
-    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.plan);
+    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 +131,7 @@ 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 null;
     throw refusal;
   }
 }
@@ -142,14 +152,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)
@@ -172,39 +174,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;
-    if (Date.now() >= commanded) {
-      commanded = Date.now() + WORKER_COMMAND_POLL_MS;
+  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 (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) {
@@ -221,9 +216,9 @@ async function completeOwnerStop(context, bound, requestedAt) {
   const destroyed = await destroySession(context.runtime, bound.tmux);
   let failure = null;
   try {
-    await observeSessionStop(context.session, bound.session);
+    await observeSessionStop(context.session, bound.session, false, bound.plan);
   } 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 };
   }
@@ -234,10 +229,10 @@ async function completeOwnerStop(context, bound, requestedAt) {
 
 async function settleReported(context, bound) {
   try {
-    await reportRunOutcome(context.session, bound.run, bound.reported);
+    await reportRunOutcome(context.session, bound.run, bound.reported, bound.plan);
     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,41 +267,134 @@ function endOnEpochReport(ended, act) {
   };
 }
 
+function refusedWith(text) {
+  const { code, conflicts } = editRefusal(text);
+  const current =
+    conflicts?.map(({ path, state, revision }) =>
+      state === "absent" ? { path, revision: null, content: null } : { path, revision },
+    ) ?? null;
+  return { refused: { code, 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()] };
+}
+
+function toolFrame(name, args, operation) {
+  return bridgedFrame({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }, operation);
+}
+
+function uploadBody(changes) {
+  const body = Buffer.from(JSON.stringify({ changes }), "utf8");
+  if (body.length > MCP_REQUEST_BODY_MAX_BYTES) return body;
+  return Buffer.concat([body, Buffer.alloc(MCP_REQUEST_BODY_MAX_BYTES + 1 - body.length, " ")]);
+}
+
+async function sessionPush(context, bound, authority, frame, signal) {
+  const call = async (sent, called) =>
+    callHouseMcp(context.session, await sessionAuthority(context.session, bound.session, authority, sent), called, sent);
+  const refused = (answer) =>
+    answer.error !== undefined
+      ? refusedWith(answer.error.message ?? "kit_house_refused")
+      : answer.result?.isError === true
+        ? refusedWith(answerText(answer.result))
+        : null;
+  const stage = async (body, sent) => {
+    const bytes = uploadBody(body.changes);
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    const prepare = { paths: uploadedPaths(body.changes), bytes: bytes.length, sha256 };
+    const prepared = await call(
+      sent,
+      toolFrame("run_command", { command: WORKING_COPY_UPLOAD_COMMAND, arguments: prepare }, body.operation_id),
+    );
+    const refusal = refused(prepared);
+    if (refusal !== null) return refusal;
+    const transfer = answerYaml(answerText(prepared.result))?.transfer;
+    const staged = (
+      await transferBytes(
+        { url: transfer?.url, method: "POST", operation: transfer?.operation, body: bytes, framed: true, signal: sent },
+        context.session.dependencies,
+      )
+    ).transfer;
+    if (typeof staged?.url !== "string" || typeof staged.operation !== "string") {
+      throw new KitRefusal("kit_house_answer_unreadable", WORKING_COPY_UPLOAD_COMMAND);
+    }
+    return { upload: { url: staged.url, operation: staged.operation, bytes: bytes.length, sha256 } };
+  };
+  const edit = async (body, sent, retain) => {
+    let { upload } = body;
+    const inline = toolFrame("edit", { changes: body.changes }, body.operation_id);
+    if (upload === undefined && Buffer.byteLength(JSON.stringify(inline)) > MCP_REQUEST_BODY_MAX_BYTES) {
+      const staged = await stage(body, sent);
+      if (staged.upload === undefined) return staged;
+      ({ upload } = staged);
+      await retain(upload);
+    }
+    const answer = await call(
+      sent,
+      upload === undefined ? inline : toolFrame("edit", { paths: uploadedPaths(body.changes), upload }, body.operation_id),
+    );
+    return refused(answer) ?? acceptedWith(answerText(answer.result));
+  };
+  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);
-  const drafts = openAssistantDrafts({
-    send: handed((blocks) => streamAssistantDraft(context.session, bound.session, blocks)),
-  });
+  const frames = turnFrames(context.stream);
   const bridge = await openBridge({
     socket: bound.socket,
     nonce: bound.nonce,
     signal: AbortSignal.any([context.signal, ended.signal]),
     mutates: mutatingCall(await toolMutations(context.session, context.signal)),
     alive: () => sessionPresent(context.runtime, bound.tmux),
-    draft: (text) => drafts.update(text),
+    draft: (view) => frames.draft(view),
+    plan: (snapshot) => frames.plan(snapshot),
     start,
     question: handed((batch) => admitInteraction(context.session, bound.session, batch)),
-    plan: handed((snapshot) => admitPlanSnapshot(context.session, bound.session, snapshot)),
-    interrupt: handed((interrupt, outcome) =>
-      reportInterruptOutcome(context.session, interrupt, outcome),
+    howWeWork: () =>
+      noteHowWeWork(context.directory).catch((error) =>
+        reported(`How-we-work note unwritable (${error.code ?? "unknown"})`),
+      ),
+    interrupt: handed((interrupt, outcome, plan) =>
+      reportInterruptOutcome(context.session, interrupt, outcome, finalPlan(plan)),
     ),
     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 };
+  return { bridge, frames, ended };
 }
 
 async function superviseBound(context, bound, opened, start) {
-  const { bridge, drafts, ended } = opened;
+  const { bridge, ended } = opened;
   const spawn = { committed: false };
   let unsupervised = null;
   let destroyed = false;
@@ -320,23 +408,20 @@ async function superviseBound(context, bound, opened, start) {
     unsupervised = { code: refusal.code, detail: refusal.message };
   } finally {
     try {
-      try {
-        await settleFiles(context);
-        for (const interaction of bridge.unsettledInteractions()) {
-          await settleInteraction(context, interaction, "expired");
-        }
-      } finally {
-        bridge.stopRecovery();
-        if (owner === null) {
-          try {
-            destroyed = await grantExitGrace(context.runtime, bound.tmux);
-          } finally {
-            await bridge.close();
-          }
-        }
+      retryFiles(context);
+      await settleFiles(context);
+      for (const interaction of bridge.unsettledInteractions()) {
+        await settleInteraction(context, interaction, "expired");
       }
     } finally {
-      drafts.close();
+      bridge.stopRecovery();
+      if (owner === null) {
+        try {
+          destroyed = await grantExitGrace(context.runtime, bound.tmux);
+        } finally {
+          await bridge.close();
+        }
+      }
     }
   }
   ended.signal.throwIfAborted();
@@ -352,6 +437,7 @@ async function superviseBound(context, bound, opened, start) {
     destroyed,
     stopped: null,
   };
+  bound.plan = finalPlan(bridge.plan());
   if (owner !== null) {
     const finished = await completeOwnerStop(context, bound, owner.requestedAt);
     return {
@@ -371,50 +457,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;
-  try {
-    await observeSessionStop(context.session, bound.session, sealed.accepted !== null);
-  } catch (refusal) {
-    if (!(refusal instanceof KitRefusal) || refusal.code !== "conversation_final_text_pending") throw refusal;
-    outcome.failure ??= { code: refusal.code, detail: refusal.message };
-    await observeSessionStop(context.session, bound.session);
+  if (continuable) {
+    await writeContinuation(context.directory, { ...held, providerSessionId: stopped.providerSessionId });
   }
-  const report = terminalReport({
-    conversation: bound.conversation === true,
-    turnCompleted: turnObserved,
+  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,
-    failure: execution,
     continuable,
-  });
-  const retained = report === null;
-  if (retained) {
-    await writeContinuation(context.directory, {
-      ...held,
-      providerSessionId: stopped.providerSessionId,
+    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, stopped.textAccepted, bound.plan);
+  } catch (refusal) {
+    if (undecided(context, refusal)) return unresolved(null);
+    if (!(refusal instanceof KitRefusal) || refusal.code !== "conversation_final_text_pending") throw refusal;
+    failure ??= { code: refusal.code, detail: refusal.message };
+    await observeSessionStop(context.session, bound.session, false, bound.plan);
+  }
+  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 +526,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);
@@ -448,10 +554,14 @@ async function prepareAssignment(context, assignment, resumed) {
     ownerStop: null,
     sealed: null,
     reported: null,
+    plan: null,
   };
   const authority = { token: assignment.session.token, expiresAt: assignment.session.expiresAt };
-  const opened = await openRunBridge(context, bound, authority, {
+  const start = {
+    base_instructions: assignment.baseInstructions,
+    create_how_we_work: await howWeWorkOwed(context.directory),
     working_directory: assignment.workingDirectory,
+    working_copies: await appliedWorkingCopies(context),
     execution_authority: context.configuration.executionAuthority,
     adapter: {
       kind: route.adapter.kind,
@@ -461,10 +571,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 +618,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,
@@ -520,7 +637,7 @@ async function superviseAssignment(context, assignment, resumed = false) {
       },
       command: context.launcher,
     });
-    await observeSessionStart(context.session, bound.session);
+    opened.frames.identify(await observeSessionStart(context.session, bound.session));
   });
 }
 
@@ -531,7 +648,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);
 }
 
@@ -539,7 +656,7 @@ async function superviseRestored(context, binding, authority) {
   const opened = await openRunBridge(context, binding, authority);
   return superviseBound(context, binding, opened, async (spawn) => {
     spawn.committed = true;
-    await observeSessionStart(context.session, binding.session);
+    opened.frames.identify(await observeSessionStart(context.session, binding.session));
   });
 }
 
@@ -551,7 +668,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 +684,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);
@@ -586,20 +703,20 @@ 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) {
-    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 +756,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 +783,55 @@ 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, reach) {
+  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);
+  if (reach !== "runs") return reconciled;
+  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,
@@ -707,24 +840,97 @@ async function workerContext(options, dependencies) {
     launchBase: launchBase(dependencies),
     container: dependencies.container ?? process.env.HOUSE_KIT_CONTAINER === "1",
     directory: options.directory,
+    home: dependencies.home ?? homedir(),
     files: { originals: [], failures: [] },
+    commands: residentWake(),
+    stream: kitStreamWriter(),
     epochReport: null,
+    agentRefresh: Promise.resolve(),
+    configurationPath: options.configuration,
+    busy: false,
+    deferredRemoval: false,
   };
   return { context, tmux };
 }
 
-async function controlledPass(context, dependencies, configuration, signal) {
-  context.configuration = { ...configuration, agents: await desiredAgents(context.session, signal) };
+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, reach = "runs") {
   context.signal = signal;
   context.session.signal = signal;
-  return afterEpochReport(context, () => workerPass(context, dependencies));
+  await reconcileSkillSet({
+    directory: context.directory,
+    home: context.home,
+    accepted: configuration.skills,
+  });
+  context.busy = true;
+  try {
+    return await afterEpochReport(context, () => workerPass(context, dependencies, configuration, reach));
+  } 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) => {
-    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: () => {},
+        opened: context.stream.opened,
+        closed: context.stream.closed,
+      },
+      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,
@@ -740,17 +946,312 @@ export async function runWorkers(options, dependencies = {}) {
   };
 }
 
+function reported(line) {
+  process.stderr.write(`kit: ${line}\n`);
+}
+
+async function reportedWorkingCopies(act, context, signal) {
+  const outcome = await act(context, signal);
+  for (const refused of outcome.refused) {
+    reported(`working copy ${refused.path} refused: ${refused.code}`);
+  }
+  return outcome;
+}
+
+export function residentUpdate(context, wake) {
+  let requested = existsSync(updateDrain(context.directory));
+  let ready = null;
+  const waiting = [];
+  return {
+    get requested() {
+      return requested;
+    },
+    async request(serving) {
+      let heard = null;
+      let hear;
+      const answered = new Promise((resolve) => {
+        hear = (answer) => {
+          heard = answer;
+          resolve(answer);
+        };
+      });
+      waiting.push(hear);
+      if (!requested) {
+        requested = true;
+        await writeText(updateDrain(context.directory), "");
+      }
+      wake.notify();
+      const sessions = await heldSessions(context);
+      if (heard !== null) return heard;
+      if (ready === null && !serving && sessions.length === 0) return answered;
+      waiting.splice(waiting.indexOf(hear), 1);
+      if (ready !== null) return ready;
+      if (serving) return { ready: false, sessions, serving };
+      return { ready: false, sessions };
+    },
+    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) => {
-    while (!signal.aborted) {
-      const configuration = await readConfiguration(options.configuration);
-      await controlledPass(context, dependencies, configuration, 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;
+  let sources = null;
+  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) }),
+      ),
+    (source) =>
+      sources === null ? Promise.reject(new KitRefusal("kit_resident_unavailable")) : sources.capture(source),
+    context.stream,
+  );
+  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 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, async () =>
+      behind(await reportedWorkingCopies(deliverWorkingCopies, context, signal)),
+    );
+    sources = sourceEntries({
+      session: context.session,
+      directory: context.directory,
+      dependencies,
+      signal: AbortSignal.any([signal, watcher.signal]),
+      now: session.now,
+      draining: () => update.requested,
+      unavailable: (error) => reported(`google sources unavailable: ${error?.message ?? error}`),
+    });
+    await sources.start();
+    const pointer = () => {
+      if (!update.requested) agentRefresh.trigger();
+    };
+    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();
+      if (subject === null || subject === "sources") sources.reconcile();
+    };
+    context.onIdle = pointer;
+    context.workingCopiesApplied = copies.settled;
+    const watching = (dependencies.watchKitWork ?? watchKitWork)(
+      context.session,
+      AbortSignal.any([signal, watcher.signal]),
+      {
+        available,
+        changed,
+        opened: context.stream.opened,
+        closed: context.stream.closed,
+        viewed: (frame) => served.forward(frame),
+      },
+      dependencies,
+    ).catch(fail);
+    try {
+      while (!signal.aborted) {
+        if (failure !== null) throw failure;
+        if (passOwed !== null && !session.refused) {
+          const reach = passOwed;
+          passOwed = null;
+          const configuration = await readConfiguration(options.configuration);
+          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);
+        }
+        const draining = session.refused || update.requested;
+        if (draining) {
+          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() &&
+              sources.idle())
+          ) {
+            return;
+          }
+        }
+        if (session.refused || passOwed === null) await wake.wait(draining ? interval : Infinity, signal);
+      }
+    } finally {
+      watcher.abort();
+      await watching;
+      await agentRefresh.settled();
+      await copies.settled();
+      await deliveries.settled();
+      await sources.settled();
+      for (const running of logins.values()) running.controller.abort();
+      await Promise.all([...logins.values()].map((running) => running.task));
+      await context.agentRefresh;
+    }
+  };
+  try {
+    for (;;) {
       try {
-        await delay(dependencies.residentIntervalMs ?? 30_000, undefined, { signal });
+        await maintainControl(session, serve, options.signal, { release: false });
       } catch (error) {
-        if (!signal.aborted) throw 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);
     }
-  }, options.signal);
+    update.quiesce();
+    while (!options.signal.aborted) await wake.wait(Infinity, options.signal);
+    throw new KitRefusal("kit_command_cancelled");
+  } finally {
+    await served.close();
+  }
 }