@agentshouse/kit 0.0.1 → 0.1.0-alpha.2

package/src/worker.js

@@ -0,0 +1,756 @@
+import { randomBytes } from "node:crypto";
+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 { readBindings, removeBinding, writeBinding } from "./binding.js";
+import { readContinuation, readContinuationRuns, writeContinuation, removeContinuation } from "./continuation.js";
+import { 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 { localFiles } from "./local-files.js";
+import { inheritedEnvironment } from "./command.js";
+import { readConfiguration } from "./configuration.js";
+import { launchBase, readyLaunchDirectory } from "./directory.js";
+import {
+  BRIDGE_NONCE_ENVIRONMENT,
+  BRIDGE_SOCKET_ENVIRONMENT,
+  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,
+} from "./contract.js";
+import { EpochReportRequired, houseFailed, KitRefusal } from "./refusal.js";
+import {
+  acceptAssistantText,
+  acquireCommands,
+  acquireSetup,
+  reportAgentCapabilities,
+  acquireOneRun,
+  acquireOneResumption,
+  admitInteraction,
+  admitPlanSnapshot,
+  awaitSecretInput,
+  rejectResumption,
+  callHouseMcp,
+  commitRun,
+  desiredAgents,
+  maintainControl,
+  mutatingCall,
+  observeSessionStart,
+  observeSessionStop,
+  openSession,
+  replaceSessionAuthority,
+  reportContinuation,
+  reportInterruptOutcome,
+  reportInteractionOutcome,
+  toolMutations,
+  reportRunOutcome,
+  reportSessionHeartbeat,
+  reportSessions,
+  sessionAuthority,
+  streamAssistantDraft,
+} from "./house.js";
+import { operationId } from "./operation.js";
+import { runSetup } from "./setup.js";
+import { readSettlements, removeSettlement, writeSettlement } from "./settlement.js";
+import { failedReport, terminalReport } from "./terminal.js";
+import {
+  createSession,
+  destroySession,
+  readyTmux,
+  sessionPresent,
+  workerRuntime,
+  workerSessionName,
+} from "./tmux.js";
+
+const LAUNCHER_MAIN = fileURLToPath(new URL("launcher-main.js", import.meta.url));
+
+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 };
+  } 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 };
+  }
+}
+
+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 };
+}
+
+function unresolvedRun(bound, refused = null) {
+  return { run: bound.run, session: bound.session, refused };
+}
+
+function undecided(refusal) {
+  return (
+    houseFailed(refusal) ||
+    (refusal instanceof KitRefusal &&
+      ["kit_command_cancelled", "kit_session_token_rejected"].includes(refusal.code))
+  );
+}
+
+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: [] };
+    throw refusal;
+  }
+}
+
+async function settleInteraction(context, interaction, outcome) {
+  try {
+    await reportInteractionOutcome(context.session, interaction, outcome);
+  } catch (refusal) {
+    if (!(refusal instanceof KitRefusal)) throw refusal;
+  }
+}
+
+async function settleInterrupt(context, interrupt, outcome) {
+  try {
+    await reportInterruptOutcome(context.session, interrupt, outcome);
+  } catch (refusal) {
+    if (!(refusal instanceof KitRefusal)) throw refusal;
+  }
+}
+
+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)
+    .then((originals) => {
+      context.files.originals.push(...originals);
+    })
+    .catch((error) => {
+      const code = error instanceof KitRefusal ? error.code : "kit_conversation_files_failed";
+      if (code !== "kit_command_cancelled" && context.files.failures.at(-1) !== code) {
+        context.files.failures.push(code);
+      }
+    })
+    .finally(() => {
+      context.retrying = undefined;
+    });
+}
+
+async function settleFiles(context) {
+  await context.retrying;
+}
+
+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 polled = await pendingCommands(context, ["stop", "interrupt", "answer"]);
+      for (const answer of polled.answers) {
+        if (answer.session === bound.session) bridge.answered(answer);
+      }
+      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);
+      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) {
+  const deadline = Date.now() + WORKER_EXIT_GRACE_MS;
+  for (;;) {
+    if (!(await sessionPresent(runtime, handle))) return false;
+    if (Date.now() >= deadline) return destroySession(runtime, handle);
+    await delay(WORKER_EXIT_POLL_MS);
+  }
+}
+
+async function completeOwnerStop(context, bound, requestedAt) {
+  await writeBinding(context.directory, { ...bound, ownerStop: requestedAt });
+  const destroyed = await destroySession(context.runtime, bound.tmux);
+  let failure = null;
+  try {
+    await observeSessionStop(context.session, bound.session);
+  } catch (refusal) {
+    if (houseFailed(refusal)) return { destroyed, confirmed: false, failure: null };
+    if (!(refusal instanceof KitRefusal)) throw refusal;
+    failure = { code: refusal.code, detail: refusal.message };
+  }
+  await removeBinding(context.directory, bound.tmux);
+  await removeContinuation(context.directory, bound.run);
+  return { destroyed, confirmed: true, failure };
+}
+
+async function settleReported(context, bound) {
+  try {
+    await reportRunOutcome(context.session, bound.run, bound.reported);
+    return { settled: true, failure: null };
+  } catch (refusal) {
+    if (undecided(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 } };
+  }
+}
+
+async function reportTerminalState(context, bound, report) {
+  const settling = { ...bound, reported: { operation: operationId(), ...report } };
+  await writeBinding(context.directory, settling);
+  const settled = await settleReported(context, settling);
+  if (settled.settled) await removeBinding(context.directory, settling.tmux);
+  return { ...settled, reported: settling.reported };
+}
+
+async function retainedContinuation(directory, run) {
+  try {
+    return await readContinuation(directory, run);
+  } catch (refusal) {
+    if (!(refusal instanceof KitRefusal)) throw refusal;
+    return null;
+  }
+}
+
+function endOnEpochReport(ended, act) {
+  return async (...args) => {
+    try {
+      return await act(...args);
+    } catch (refusal) {
+      if (refusal instanceof EpochReportRequired) ended.abort(refusal);
+      throw refusal;
+    }
+  };
+}
+
+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 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),
+    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),
+    ),
+    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(
+          context.session,
+          await sessionAuthority(context.session, bound.session, authority, signal),
+          sent,
+          signal,
+        )), context.session.dependencies, signal)(frame)),
+  });
+  return { bridge, drafts, ended };
+}
+
+async function superviseBound(context, bound, opened, start) {
+  const { bridge, drafts, ended } = opened;
+  const spawn = { committed: false };
+  let unsupervised = null;
+  let destroyed = false;
+  let owner = null;
+  try {
+    await start(spawn);
+    owner = await supervise(context, bound, bridge);
+    if (owner !== null) await bridge.close();
+  } catch (refusal) {
+    if (!spawn.committed || !(refusal instanceof KitRefusal)) throw refusal;
+    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();
+          }
+        }
+      }
+    } finally {
+      drafts.close();
+    }
+  }
+  ended.signal.throwIfAborted();
+  const outcome = {
+    run: bound.run,
+    session: bound.session,
+    tmux: bound.tmux,
+    assistant: bridge.assistant(),
+    failure: bridge.failure() ?? unsupervised,
+    reported: null,
+    refused: null,
+    settled: true,
+    destroyed,
+    stopped: null,
+  };
+  if (owner !== null) {
+    const finished = await completeOwnerStop(context, bound, owner.requestedAt);
+    return {
+      ...outcome,
+      destroyed: finished.destroyed,
+      failure: finished.failure,
+      stopped: owner.requestedAt,
+    };
+  }
+  const stopped = bridge.stop();
+  const held = await retainedContinuation(context.directory, bound.run);
+  const capacityExhausted = stopped?.stopOutcome === "exhausted";
+  const providerRefused = stopped?.stopOutcome === "refused";
+  const continuable =
+    !capacityExhausted &&
+    !providerRefused &&
+    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);
+  }
+  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,
+    });
+  } else await removeContinuation(context.directory, bound.run);
+  await reportContinuation(context.session, bound.session, {
+    providerContinuation: retained,
+    providerCapacityExhausted: capacityExhausted,
+  });
+  if (retained) {
+    await removeBinding(context.directory, bound.tmux);
+    return outcome;
+  }
+  const settled = await reportTerminalState(context, bound, report);
+  return {
+    ...outcome,
+    reported: settled.reported,
+    refused: settled.failure,
+    settled: settled.settled,
+  };
+}
+
+function assignmentRoute(context, assignment) {
+  const kind = assignment.route.adapter.kind;
+  if (!context.configuration.agents.includes(kind)) {
+    throw new KitRefusal("kit_agent_undeclared", `${kind}; this Environment does not declare it`);
+  }
+  return assignment.route;
+}
+
+async function prepareAssignment(context, assignment, resumed) {
+  const route = assignmentRoute(context, assignment);
+  const command = await installedAgentCommand(context.directory, route.adapter.kind);
+  await readyLaunchDirectory(assignment.workingDirectory, context.launchBase, assignment.agentId, {
+    container: context.container,
+  });
+  if (!resumed) await writeContinuation(context.directory, {
+    run: assignment.run, agentId: assignment.agentId,
+    workingDirectory: assignment.workingDirectory,
+    routeId: assignment.route.id, conversation: assignment.conversation === true,
+    providerSessionId: null,
+  });
+  const handle = workerSessionName();
+  const bound = {
+    run: assignment.run,
+    session: assignment.session.id,
+    tmux: handle,
+    socket: join(context.directory, "run", `${handle}.sock`),
+    nonce: randomBytes(24).toString("base64url"),
+    conversation: assignment.conversation === true,
+    ownerStop: null,
+    sealed: null,
+    reported: null,
+  };
+  const authority = { token: assignment.session.token, expiresAt: assignment.session.expiresAt };
+  const opened = await openRunBridge(context, bound, authority, {
+    working_directory: assignment.workingDirectory,
+    execution_authority: context.configuration.executionAuthority,
+    adapter: {
+      kind: route.adapter.kind,
+      command,
+      arguments: route.arguments,
+      model: route.model,
+      effort: route.effort,
+      environment: {},
+    },
+    request: await localRequest(context.directory, assignment.run, assignment.request),
+    provider_session: assignment.providerSessionId ?? null,
+  });
+  return { bound, opened };
+}
+
+async function refuseContinuation(context, command, failure) {
+  await rejectResumption(context.session, command.session.id);
+  return settleRefused(context, command, failure);
+}
+
+async function refuseAssignment(context, assignment, failure) {
+  await commitRun(context.session, assignment.run);
+  return settleRefused(context, assignment, failure);
+}
+
+async function settleRefused(context, command, failure) {
+  await removeContinuation(context.directory, command.run);
+  const settling = {
+    run: command.run,
+    session: command.session.id,
+    reported: { operation: operationId(), ...failedReport(failure) },
+  };
+  await writeSettlement(context.directory, settling);
+  const settled = await settleReported(context, settling);
+  if (settled.settled) await removeSettlement(context.directory, settling.run);
+  return { run: settling.run, session: settling.session, tmux: null, assistant: [],
+    failure, reported: settling.reported, refused: settled.failure,
+    settled: settled.settled, destroyed: false, stopped: null };
+}
+
+async function superviseAssignment(context, assignment, resumed = false) {
+  let prepared;
+  try {
+    prepared = await prepareAssignment(context, assignment, resumed);
+  } catch (refusal) {
+    const failure = {
+      code: refusal instanceof KitRefusal ? refusal.code : "kit_worker_preparation_failed",
+      detail: refusal instanceof KitRefusal ? refusal.message : null,
+    };
+    if (resumed) return refuseContinuation(context, assignment, failure);
+    if (undecided(refusal)) throw refusal;
+    return refuseAssignment(context, assignment, failure);
+  }
+  const { bound, opened } = 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 createSession(context.runtime, {
+      session: bound.tmux,
+      workingDirectory: assignment.workingDirectory,
+      environment: {
+        ...inheritedEnvironment(WORKER_INHERITED_ENVIRONMENT),
+        [BRIDGE_SOCKET_ENVIRONMENT]: bound.socket,
+        [BRIDGE_NONCE_ENVIRONMENT]: bound.nonce,
+      },
+      command: context.launcher,
+    });
+    await observeSessionStart(context.session, bound.session);
+  });
+}
+
+async function superviseResumption(context, command) {
+  const held = await retainedContinuation(context.directory, command.run);
+  if (held === null || held.providerSessionId === null || held.routeId !== command.route.id) {
+    return refuseContinuation(context, command, { code: "kit_provider_continuation_unavailable", detail: null });
+  }
+  return superviseAssignment(context, {
+    ...command, agentId: held.agentId, workingDirectory: held.workingDirectory,
+    conversation: held.conversation, providerSessionId: held.providerSessionId, request: null,
+  }, true);
+}
+
+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);
+  });
+}
+
+async function settleAbsentSession(context, binding) {
+  try {
+    await observeSessionStop(context.session, binding.session);
+    await reportContinuation(context.session, binding.session, {
+      providerContinuation: false,
+      providerCapacityExhausted: false,
+    });
+  } catch (refusal) {
+    if (undecided(refusal)) return { settled: false, failure: null };
+    if (!(refusal instanceof KitRefusal)) throw refusal;
+  }
+  await removeContinuation(context.directory, binding.run);
+  return reportTerminalState(
+    context,
+    binding,
+    failedReport({ code: PROVIDER_CONTINUATION_UNAVAILABLE, detail: null }),
+  );
+}
+
+async function confirmRestorable(context, binding) {
+  let authority;
+  try {
+    authority = await replaceSessionAuthority(context.session, binding.session);
+  } catch (refusal) {
+    if (undecided(refusal)) return { authority: null, unresolved: true };
+    if (!(refusal instanceof KitRefusal)) throw refusal;
+    await destroySession(context.runtime, binding.tmux);
+    await removeBinding(context.directory, binding.tmux);
+    return { authority: null, unresolved: false };
+  }
+  return { authority, unresolved: false };
+}
+
+async function reconcile(context) {
+  const stopped = [];
+  const unresolved = [];
+  for (const settlement of await readSettlements(context.directory)) {
+    const settled = await settleReported(context, settlement);
+    if (settled.settled) await removeSettlement(context.directory, settlement.run);
+    else unresolved.push(unresolvedRun(settlement, settled.failure));
+  }
+  const bindings = await readBindings(context.directory);
+  if (bindings.length === 0) return { run: null, stopped, unresolved };
+  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;
+    }
+    const command = commands.find((pending) => pending.run === binding.run) ?? null;
+    const requestedAt = binding.ownerStop ?? command?.requestedAt ?? null;
+    if (requestedAt === null) {
+      carried.push(binding);
+      continue;
+    }
+    const finished = await completeOwnerStop(context, binding, requestedAt);
+    if (!finished.confirmed) unresolved.push(unresolvedRun(binding));
+    else stopped.push({ run: binding.run, session: binding.session, requestedAt });
+  }
+  let restorable = null;
+  for (const binding of carried) {
+    if (restorable !== null) {
+      unresolved.push(unresolvedRun(binding));
+      continue;
+    }
+    if (!(await sessionPresent(context.runtime, binding.tmux))) {
+      const settled = await settleAbsentSession(context, binding);
+      if (!settled.settled) unresolved.push(unresolvedRun(binding, settled.failure));
+      continue;
+    }
+    const confirmed = await confirmRestorable(context, binding);
+    if (confirmed.unresolved) unresolved.push(unresolvedRun(binding));
+    else if (confirmed.authority !== null) restorable = { binding, authority: confirmed.authority };
+  }
+  if (restorable === null) return { run: null, stopped, unresolved };
+  return {
+    run: await superviseRestored(context, restorable.binding, restorable.authority),
+    stopped,
+    unresolved,
+  };
+}
+
+async function reportHeldSessions(context) {
+  const settlements = await readSettlements(context.directory);
+  const bindings = await readBindings(context.directory);
+  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);
+  }
+  const reported = await reportSessions(
+    context.session,
+    [...held].map(([run, outcome]) => ({ run, reported: outcome })),
+  );
+  for (const binding of bindings) {
+    await destroySession(context.runtime, binding.tmux);
+    await removeBinding(context.directory, binding.tmux);
+  }
+  for (const run of held.keys()) {
+    await removeSettlement(context.directory, run);
+    await removeContinuation(context.directory, run);
+  }
+  return reported;
+}
+
+async function afterEpochReport(context, pass) {
+  try {
+    return await pass();
+  } catch (refusal) {
+    if (!(refusal instanceof EpochReportRequired)) throw refusal;
+  }
+  context.epochReport = await reportHeldSessions(context);
+  return pass();
+}
+
+async function workerPass(context, dependencies) {
+  const { configuration, 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 (setup !== null) {
+    context.setup = await runSetup(
+      { session, configuration, directory: context.directory, dependencies, signal },
+      setup.request,
+    );
+  }
+  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);
+  if (resumption !== null) return { ...reconciled, run: await superviseResumption(context, resumption) };
+  const assignment = await acquireOneRun(session);
+  if (assignment === null) return reconciled;
+  return { ...reconciled, run: await superviseAssignment(context, assignment) };
+}
+
+async function workerContext(options, dependencies) {
+  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 context = {
+    configuration,
+    runtime,
+    session,
+    launcher,
+    launchBase: launchBase(dependencies),
+    container: dependencies.container ?? process.env.HOUSE_KIT_CONTAINER === "1",
+    directory: options.directory,
+    files: { originals: [], failures: [] },
+    epochReport: null,
+  };
+  return { context, tmux };
+}
+
+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));
+}
+
+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);
+  }, session.signal);
+  return {
+    tmux,
+    namespace: runtime.namespace,
+    agents: context.agents ?? [],
+    inbound: context.inbound ?? null,
+    setup: context.setup ?? null,
+    files: context.files,
+    epochReport: context.epochReport,
+    run: supervised.run,
+    stopped: supervised.stopped,
+    unresolved: supervised.unresolved,
+  };
+}
+
+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);
+      try {
+        await delay(dependencies.residentIntervalMs ?? 30_000, undefined, { signal });
+      } catch (error) {
+        if (!signal.aborted) throw error;
+      }
+    }
+  }, options.signal);
+}