@agentshouse/kit 0.1.0-alpha.12 → 0.1.0-alpha.14

package/README.md

@@ -10,7 +10,7 @@ On Linux `amd64` or `arm64` with a working Docker Engine, run the published,
 versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.12/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.14/connect-linux.sh)
 ```
 
 The release asset pins one immutable multi-architecture image digest. It creates
@@ -27,16 +27,18 @@ installed container runs another image, the bootstrap pulls this release's
 image and asks the running resident Kit to drain with `kit resident drain`. The
 resident stops acquiring Runs, resumptions, setup and agent CLI work, while the
 Sessions it supervises keep their renewal, owner stops, answers and reports.
-While any Agent Session is still running or unreported, the bootstrap names it
-and leaves the container as it is; rerun it once they end. Once nothing remains,
+While any Agent Session is still running or unreported, including one whose Run
+was being acquired when the drain began, the bootstrap names it and leaves the
+container as it is; rerun it once they end. Once nothing remains,
 the resident stops renewing, releases its exact lease and stays quiescent, and
 the bootstrap replaces the container with one on this release's image over the
 same Kit home and workspace. The credential, Environment, Kit-home state and
 everything under the workspace are kept; anything installed elsewhere in the old
 container is not. A stopped container is replaced without a drain.
 
-If House refuses the installed Kit with `kit_upgrade_required`, the resident
-calls House no more, neither to release nor to report. It keeps supervising
+If House refuses the installed Kit with `kit_upgrade_required`, including in
+its answer to a command the resident serves, the resident calls House no more,
+neither to release nor to report. It keeps supervising
 every running Session locally and never stops one to make progress. A Session
 that ends keeps its exact binding, stop observation and outcome in Kit home,
 and the drain answers ready once no supervised process runs. The updated Kit
@@ -1170,8 +1172,13 @@ A resident whose lease House refuses answers the command with that refusal; the
 command never acquires a lease of its own while a resident serves it. While an
 update drains, `state/update-drain` refuses every such command, `kit login` and
 `kit worker run` with `kit_update_draining` before it enrolls, acquires or
-delegates anything, and the drain request ends the delegation of a command
-already served; the bootstrap removes the file when it replaces the container.
+delegates anything. A command already served keeps the resident's lease until
+it ends, while the resident refuses its acquisition of new work and its
+Telegram updates with `kit_update_draining`, which ends a served
+`kit telegram serve` once each of its activities reports the deliveries and
+files it already acquired; until it ends, the drain answers that it waits for
+that command and the bootstrap leaves the container as it is. The bootstrap
+removes the file when it replaces the container.
 
 Interrupting the command cancels the running connector without advancing the
 checkpoint.
@@ -1210,9 +1217,52 @@ interrupted run is never resumed: the next run opens a new manifest and House
 answers with what is still needed. The command reports the Publication
 reference, the paths delivered, the items refused and the ending.
 
+## Working copies
+
+The Environment owner chooses in House which Rooms this Environment keeps
+locally, and whether it keeps `/private`. An Environment whose owner never chose
+copies nothing, and a Room joined later stays uncopied until the owner selects
+it. The resident Kit reads the saved choice through
+`POST /kit/working-copy/selection` when it starts, whenever its control stream
+connects or reconnects, and whenever House points it there after a save;
+`kit worker run` reads it once before its pass.
+
+Each selected Room becomes one ordinary Git repository at
+`/agents/house/working-copies/rooms/<room_ref>`, and `/private` one at
+`/agents/house/working-copies/private`. The Room reference names the location,
+so a Room handle change moves nothing. Every Agent launched afterwards receives
+the House path and local repository of each active copy in its context, one
+line each, such as `/rooms/work: /agents/house/working-copies/rooms/r_1x.q`.
+
+A Room repository holds the Room's complete readable content: `ROOM.md`,
+`library/`, `capture/` with its provenance sidecars, and `collaboration/`. The
+`/private` repository holds its Library, collaboration, each Room's private
+`AGENTS.md`, the `agents/` cards and `house/`. Attached settings and attachment
+bytes are not copied. The branch `main` starts at the commit House served, which
+tracks exactly the files House declares writable under the Environment's
+current grant. Every other file is read-only House content: the generated
+`.gitignore` names and explains it, so Git never tracks it, and the matching
+`.ignore` keeps it visible to ripgrep and other native search. Neither file
+grants anything, and House refuses a change to a read-only path however it is
+committed.
+
+Local edits, staging and commits change nothing in House. `refs/house/received`
+records the House content last received. The per-file manifest, with each
+file's House revision, digest and writability, and the commit it corresponds to
+stay in Kit home under `state/working-copies/`, outside the repository. A local
+commit is a local tree, never a House revision.
+
+Deselecting a Room, or losing read access to it, marks its copy inactive:
+launches omit it and nothing local is deleted. Selecting it again reads the Room
+again, advances `refs/house/received`, and replaces only the read-only content
+Kit wrote, never the branch, the index or a tracked file. A Room the owner may
+read without sync is refused as `operation_denied` and stays uncopied, while its
+ordinary remote reads are unaffected. Kit names each refused copy on its
+standard error.
+
 ## Explicit synchronization
 
-Beside the reconciling Working Copy, Kit has one explicit synchronization mode.
+Beside [working copies](#working-copies), Kit has one explicit synchronization mode.
 It selects prefixes over the User root, materializes them into a named local
 directory, enumerates whole content and removals after the recorded positions,
 and submits a resolved exact-base change set the caller prepared. Kit does no
@@ -1495,6 +1545,8 @@ $HOUSE_KIT_HOME/
   state/repositories/<repository identity>.json
   state/sync/<replica identity>.json
   state/sync/<replica identity>.pending.json
+  state/working-copies/rooms/<room ref>.json
+  state/working-copies/private.json
   state/attachments/<upload identity>.json
   state/conversation-originals/<attachment identity>.json
   state/sessions/<tmux session>.json

package/bin/kit.js

@@ -177,7 +177,9 @@ async function runResidentDrain(args, directory) {
   write(
     answer.sessions.length > 0
       ? `House Kit is draining for its update and waits for Agent Sessions ${answer.sessions.join(", ")}.`
-      : `House Kit is draining for its update; House refused its lease release (${answer.refused}).`,
+      : answer.serving === true
+        ? "House Kit is draining for its update and waits for the Kit command it serves."
+        : `House Kit is draining for its update; House refused its lease release (${answer.refused}).`,
   );
   process.exitCode = 1;
 }

package/bootstrap.json

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

package/package.json

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

package/src/contract.js

@@ -291,6 +291,15 @@ export const KIT_DOOR_BATCH_PATH = "/kit/door/batch";
 export const EXPLICIT_SYNC_VERSION = "explicit-sync/2";
 export const KIT_DOOR_UNMOUNT_PATH = "/kit/door/unmount";
 
+export const KIT_WORKING_COPY_SELECTION_PATH = "/kit/working-copy/selection";
+export const WORKING_COPY_VERSION = "working-copy-state/1";
+export const WORKING_COPIES_HOME = "working-copies";
+export const WORKING_COPY_ROOM_HOMES = ["capture", "library", "collaboration"];
+export const WORKING_COPY_PRIVATE_HOMES = ["library", "collaboration", "rooms", "agents", "house"];
+export const WORKING_COPY_RECEIVED_REF = "refs/house/received";
+export const WORKING_COPY_BRANCH = "main";
+export const ROOM_REFERENCE = /^r_[0-9a-z]+\.[0-9a-z]$/;
+
 export const MIGRATOR_CONTRACT = "kit-migrator/1";
 export const MIGRATOR_CATEGORY = "migrator";
 export const MIGRATOR_MANIFEST = "migrator.json";

package/src/git.js

@@ -0,0 +1,62 @@
+import { spawn } from "node:child_process";
+import { KitRefusal } from "./refusal.js";
+
+function cancelledOr(signal, error, code) {
+  return signal?.aborted === true || error?.name === "AbortError"
+    ? new KitRefusal("kit_command_cancelled")
+    : new KitRefusal(code);
+}
+
+function stdio(capture, input) {
+  if (input !== null) return ["pipe", capture ? "pipe" : "inherit", "inherit"];
+  return capture ? ["ignore", "pipe", "inherit"] : "inherit";
+}
+
+export function runGit(cwd, args, options = {}) {
+  const { dependencies = {}, capture = false, input = null, signal, failure } = options;
+  if (signal?.aborted === true) return Promise.reject(new KitRefusal("kit_command_cancelled"));
+  const launcher = dependencies.spawn ?? spawn;
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = launcher("git", args, {
+        cwd,
+        env: process.env,
+        stdio: stdio(capture, input),
+        signal,
+        killSignal: "SIGKILL",
+      });
+    } catch (error) {
+      reject(cancelledOr(signal, error, "kit_git_unavailable"));
+      return;
+    }
+    const output = [];
+    let settled = false;
+    const finish = (operation) => {
+      if (settled) return;
+      settled = true;
+      operation();
+    };
+    child.stdout?.on("data", (chunk) => output.push(Buffer.from(chunk)));
+    child.once("error", (error) =>
+      finish(() => reject(cancelledOr(signal, error, "kit_git_unavailable"))),
+    );
+    child.once("close", (status) => {
+      finish(() => {
+        if (signal?.aborted === true) {
+          reject(new KitRefusal("kit_command_cancelled"));
+          return;
+        }
+        if (status !== 0) {
+          reject(new KitRefusal(failure));
+          return;
+        }
+        resolve(Buffer.concat(output));
+      });
+    });
+    if (input !== null) {
+      child.stdin.on("error", () => undefined);
+      child.stdin.end(input);
+    }
+  });
+}

package/src/house.js

@@ -56,6 +56,10 @@ async function readCredential(directory) {
   return stored;
 }
 
+function latchRefusal(answer, dependencies) {
+  if (answer?.error?.code === UPGRADE_REQUIRED) dependencies.contractRefused?.();
+}
+
 async function houseAnswer(house, path, init, dependencies, signal) {
   const fetcher = dependencies.fetch ?? fetch;
   let response;
@@ -73,7 +77,7 @@ async function houseAnswer(house, path, init, dependencies, signal) {
   } catch {
     answer = null;
   }
-  if (answer?.error?.code === UPGRADE_REQUIRED) dependencies.contractRefused?.();
+  latchRefusal(answer, dependencies);
   throwHouseAnswer(response.status, answer, path);
   if (answer === null) throw new KitRefusal("kit_house_unavailable", path);
   return answer;
@@ -130,11 +134,18 @@ function residentAnswer(status, code) {
   return { status, type: "application/json", body };
 }
 
-async function residentRelay(session, request, signal) {
+function newWork(path) {
+  return path === "/kit/telegram/updates" || (path.endsWith("/acquire") && path !== "/kit/commands/acquire");
+}
+
+async function residentRelay(session, request, signal, draining) {
   const path = typeof request.path === "string" ? request.path : "";
   if (!path.startsWith("/kit/") || path.startsWith("/kit/lease")) {
     return residentAnswer(403, "kit_resident_route_refused");
   }
+  if (draining && newWork(path)) {
+    return residentAnswer(409, UPDATE_DRAINING);
+  }
   let authorization;
   try {
     authorization = await heldControl(session, signal);
@@ -149,6 +160,7 @@ async function residentRelay(session, request, signal) {
       signal,
     });
     const body = Buffer.from(await response.arrayBuffer());
+    if (response.status === 409) latchRefusal(JSON.parse(body.toString("utf8")), session.dependencies);
     return {
       status: response.status,
       type: response.headers.get("content-type"),
@@ -168,9 +180,7 @@ export async function serveResident(session, directory, signal, drain) {
   let draining = false;
   function answerDrain(connection) {
     draining = true;
-    const answered = drain();
-    holder?.destroy();
-    answered.then(
+    drain(holder !== null).then(
       (answer) => {
         if (!connection.destroyed) writeFrame(connection, answer);
         connection.end();
@@ -181,7 +191,7 @@ export async function serveResident(session, directory, signal, drain) {
   }
   function hold(connection) {
     if (holder !== null || draining || existsSync(updateDrain(directory))) {
-      writeFrame(connection, { refused: holder === null ? UPDATE_DRAINING : LEASE_ACTIVE });
+      writeFrame(connection, { refused: draining || holder === null ? UPDATE_DRAINING : LEASE_ACTIVE });
       connection.end();
       return false;
     }
@@ -218,7 +228,7 @@ export async function serveResident(session, directory, signal, drain) {
         }
         const cancelled = new AbortController();
         relayed.set(request.id, cancelled);
-        void residentRelay(session, request, AbortSignal.any([signal, cancelled.signal])).then(
+        void residentRelay(session, request, AbortSignal.any([signal, cancelled.signal]), draining).then(
           (answer) => {
             relayed.delete(request.id);
             if (!connection.destroyed) writeFrame(connection, { id: request.id, ...answer });

package/src/kit-work-stream.js

@@ -5,6 +5,7 @@ import { heldControl } from "./house.js";
 import { KitRefusal } from "./refusal.js";
 
 const PROTOCOL = "house.kit.stream.1";
+const WATCHED_SUBJECTS = ["agents", "working_copy"];
 
 function streamAddress(house) {
   const url = new URL("/kit/stream", house);
@@ -37,7 +38,7 @@ async function connected(session, signal, available, dependencies) {
       finish();
     };
     signal.addEventListener("abort", stop, { once: true });
-    socket.on("open", available);
+    socket.on("open", () => available(null));
     socket.on("message", (data) => {
       let frame;
       try {
@@ -45,7 +46,9 @@ async function connected(session, signal, available, dependencies) {
       } catch {
         return;
       }
-      if (frame?.type === "work_available" && frame.subject === "agents") available();
+      if (frame?.type === "work_available" && WATCHED_SUBJECTS.includes(frame.subject)) {
+        available(frame.subject);
+      }
     });
     socket.on("unexpected-response", (_request, response) => {
       response.resume();
@@ -64,7 +67,7 @@ async function connected(session, signal, available, dependencies) {
   });
 }
 
-export async function watchKitAgentWork(session, signal, available, dependencies = {}) {
+export async function watchKitWork(session, signal, available, dependencies = {}) {
   let retryMs = 500;
   while (!signal.aborted) {
     const began = Date.now();

package/src/launcher.js

@@ -129,6 +129,12 @@ async function configureSession(acp, contract, sessionId, adapter) {
   }
 }
 
+function workingCopyContext(copies) {
+  if (!Array.isArray(copies) || copies.length === 0) return [];
+  const lines = copies.map((copy) => `${copy.path}: ${copy.repository}`);
+  return [{ type: "text", text: ["Local Git working copies of House paths:", ...lines].join("\n") }];
+}
+
 async function runTurn(channel, start, bridge, turn) {
   const contract = compiledContract(start.adapter?.kind);
   const adapter = startCommandAdapter(
@@ -193,6 +199,7 @@ async function runTurn(channel, start, bridge, turn) {
       prompt: [
         { type: "text", text: JSON.stringify(request) },
         { type: "text", text: instructions },
+        ...workingCopyContext(start.working_copies),
       ],
     });
     await new Promise((resolve) => setImmediate(resolve));

package/src/repository.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
-import { spawn } from "node:child_process";
 import { constants } from "node:fs";
 import { open, readlink, realpath } from "node:fs/promises";
 import { join } from "node:path";
+import { runGit } from "./git.js";
 import { deliverPublicationChunk, maintainControl, openPublicationManifest, openSession } from "./house.js";
 import { KitRefusal } from "./refusal.js";
 import { readRepositoryState, writeRepositoryState } from "./state.js";
@@ -258,69 +258,11 @@ async function* chunkArchive(checkout, entries, signal) {
   yield Buffer.alloc(BLOCK_BYTES * 2);
 }
 
-function runGit(checkout, args, dependencies, capture, signal) {
-  active(signal);
-  const launcher = dependencies.spawn ?? spawn;
-  return new Promise((resolve, reject) => {
-    let child;
-    try {
-      child = launcher("git", args, {
-        cwd: checkout,
-        env: process.env,
-        stdio: capture ? ["ignore", "pipe", "inherit"] : "inherit",
-        signal,
-        killSignal: "SIGKILL",
-      });
-    } catch (error) {
-      reject(
-        signal?.aborted === true || error?.name === "AbortError"
-          ? new KitRefusal("kit_command_cancelled")
-          : new KitRefusal("kit_git_unavailable"),
-      );
-      return;
-    }
-    const output = [];
-    let settled = false;
-    const finish = (operation) => {
-      if (settled) return;
-      settled = true;
-      operation();
-    };
-    child.stdout?.on("data", (chunk) => output.push(Buffer.from(chunk)));
-    child.once("error", (error) =>
-      finish(() =>
-        reject(
-          signal?.aborted === true || error?.name === "AbortError"
-            ? new KitRefusal("kit_command_cancelled")
-            : new KitRefusal("kit_git_unavailable"),
-        ),
-      ),
-    );
-    child.once("close", (status) => {
-      finish(() => {
-        if (signal?.aborted === true) {
-          reject(new KitRefusal("kit_command_cancelled"));
-          return;
-        }
-        if (status !== 0) {
-          reject(
-            new KitRefusal(args[0] === "pull" ? "kit_git_pull_failed" : "kit_git_selection_failed"),
-          );
-          return;
-        }
-        resolve(Buffer.concat(output));
-      });
-    });
-  });
-}
-
 async function selectedPaths(checkout, dependencies, signal) {
   const output = await runGit(
     checkout,
     ["ls-files", "--cached", "--others", "--exclude-standard", "-z"],
-    dependencies,
-    true,
-    signal,
+    { dependencies, capture: true, signal, failure: "kit_git_selection_failed" },
   );
   const paths = [];
   let offset = 0;
@@ -469,7 +411,7 @@ export async function captureRepository(options, dependencies = {}) {
     session,
     async (signal) => {
       const state = stateOf(await readRepositoryState(options.directory, key), identity);
-      await runGit(identity.checkout, ["pull"], dependencies, false, signal);
+      await runGit(identity.checkout, ["pull"], { dependencies, signal, failure: "kit_git_pull_failed" });
       const now = dependencies.now ?? (() => new Date());
       let sourceRef = state.source_ref;
       let publication = null;

package/src/sync.js

@@ -46,7 +46,7 @@ async function withSession(options, dependencies, operation) {
   return maintainControl(session, (signal) => operation(session, signal), options.signal);
 }
 
-async function door(session, path, body, signal) {
+export async function door(session, path, body, signal) {
   return houseRequest(
     session.house,
     await heldControl(session, signal),
@@ -83,7 +83,7 @@ function changePosition(value, declaration) {
   return { position: value.position, log_epoch: value.log_epoch };
 }
 
-function discoveryOf(value) {
+export function discoveryOf(value) {
   if (typeof value?.md_model_version !== "string" || !Array.isArray(value.authorities)) {
     throw new KitRefusal("kit_sync_rejected", "discover");
   }
@@ -93,7 +93,7 @@ function discoveryOf(value) {
   return value;
 }
 
-async function bootstrapBundle(session, prefixes, signal) {
+export async function bootstrapBundle(session, prefixes, signal) {
   const answer = await door(session, KIT_DOOR_BOOTSTRAP_PATH, { prefixes }, signal);
   if (typeof answer?.transfer?.url === "string") {
     const granted = await houseGetJson(answer.transfer.url, session.dependencies, signal);

package/src/telegram.js

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

package/src/worker.js

@@ -17,7 +17,8 @@ import { openAssistantDrafts } from "./draft.js";
 import { localReply, localRequest, reconcileInbound } from "./inbound.js";
 import { localFiles } from "./local-files.js";
 import { inheritedEnvironment } from "./command.js";
-import { watchKitAgentWork } from "./kit-work-stream.js";
+import { watchKitWork } from "./kit-work-stream.js";
+import { applyWorkingCopies, workingCopyPaths } from "./working-copy.js";
 import { readConfiguration } from "./configuration.js";
 import { launchBase, readyLaunchDirectory } from "./directory.js";
 import {
@@ -177,6 +178,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"]);
@@ -435,6 +437,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);
@@ -462,6 +469,7 @@ async function prepareAssignment(context, assignment, resumed) {
   const authority = { token: assignment.session.token, expiresAt: assignment.session.expiresAt };
   const opened = await openRunBridge(context, bound, authority, {
     working_directory: assignment.workingDirectory,
+    working_copies: await appliedWorkingCopies(context),
     execution_authority: context.configuration.executionAuthority,
     adapter: {
       kind: route.adapter.kind,
@@ -793,6 +801,7 @@ 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 applySavedWorkingCopies(context, signal);
     return controlledPass(context, dependencies, context.configuration, signal);
   }, session.signal);
   return {
@@ -809,6 +818,41 @@ export async function runWorkers(options, dependencies = {}) {
   };
 }
 
+function reported(line) {
+  process.stderr.write(`kit: ${line}\n`);
+}
+
+async function applySavedWorkingCopies(context, signal) {
+  const applied = await applyWorkingCopies(context, signal);
+  for (const refused of applied.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;
@@ -849,20 +893,26 @@ function residentUpdate(context, wake) {
     get requested() {
       return requested;
     },
-    async request() {
+    async request(serving) {
       if (!requested) {
         requested = true;
         await writeText(updateDrain(context.directory), "");
       }
       wake.notify();
-      if (ready !== null) return ready;
       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);
@@ -902,7 +952,7 @@ export async function runResident(options, dependencies = {}) {
   const wake = residentWake();
   const update = residentUpdate(context, wake);
   context.update = update;
-  const served = await serveResident(session, context.directory, options.signal, () => update.request());
+  const served = await serveResident(session, context.directory, options.signal, (serving) => update.request(serving));
   const serve = async (signal) => {
     context.busy = true;
     const watcher = new AbortController();
@@ -953,33 +1003,30 @@ export async function runResident(options, dependencies = {}) {
     context.waitAgentLogin = async (kind) => {
       await logins.get(kind)?.task;
     };
-    let pointerPending = false;
-    let pointerTask = null;
+    const agentRefresh = coalescedTask(signal, fail, async () => {
+      const needsLogin = await queueAgentRefresh(context, dependencies, signal, undefined, true);
+      context.startLogins(needsLogin);
+    });
+    const copies = coalescedTask(
+      signal,
+      (error) => reported(`working copies unavailable: ${error?.message ?? error}`),
+      () => applySavedWorkingCopies(context, signal),
+    );
     const pointer = () => {
+      if (!update.requested) agentRefresh.trigger();
+    };
+    const available = (subject) => {
       if (update.requested) return;
-      pointerPending = true;
-      if (pointerTask !== null) return;
-      pointerTask = (async () => {
-        while (pointerPending && !signal.aborted) {
-          pointerPending = false;
-          const needsLogin = await queueAgentRefresh(context, dependencies, signal, undefined, true);
-          context.startLogins(needsLogin);
-        }
-      })()
-        .catch((error) => {
-          if (signal.aborted) return;
-          fail(error);
-        })
-        .finally(() => {
-          pointerTask = null;
-          if (pointerPending && !signal.aborted) pointer();
-        });
+      if (subject !== "working_copy") agentRefresh.trigger();
+      if (subject !== "agents") copies.trigger();
     };
     context.onIdle = pointer;
-    const watching = (dependencies.watchKitAgentWork ?? watchKitAgentWork)(
+    context.workingCopiesApplied = copies.settled;
+    if (!update.requested) copies.trigger();
+    const watching = (dependencies.watchKitWork ?? watchKitWork)(
       context.session,
       AbortSignal.any([signal, watcher.signal]),
-      pointer,
+      available,
       dependencies,
     ).catch(fail);
     try {
@@ -994,14 +1041,20 @@ export async function runResident(options, dependencies = {}) {
         if (session.refused || update.requested) {
           const sessions = await heldSessions(context);
           if (sessions.length > 0) update.answer({ ready: false, sessions });
-          else if (session.refused || (!served.serving() && logins.size === 0 && pointerTask === null)) return;
+          else if (
+            session.refused ||
+            (!served.serving() && logins.size === 0 && agentRefresh.idle() && copies.idle())
+          ) {
+            return;
+          }
         }
         await wake.wait(interval, signal);
       }
     } finally {
       watcher.abort();
       await watching;
-      if (pointerTask !== null) await pointerTask;
+      await agentRefresh.settled();
+      await copies.settled();
       for (const running of logins.values()) running.controller.abort();
       await Promise.all([...logins.values()].map((running) => running.task));
       await context.agentRefresh;

package/src/working-copy.js

@@ -0,0 +1,389 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, rename, rm, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+  KIT_DOOR_DISCOVER_PATH,
+  KIT_WORKING_COPY_SELECTION_PATH,
+  ROOM_REFERENCE,
+  WORKING_COPIES_HOME,
+  WORKING_COPY_BRANCH,
+  WORKING_COPY_PRIVATE_HOMES,
+  WORKING_COPY_RECEIVED_REF,
+  WORKING_COPY_ROOM_HOMES,
+  WORKING_COPY_VERSION,
+} from "./contract.js";
+import { runGit } from "./git.js";
+import { houseAnswered, KitRefusal } from "./refusal.js";
+import { readNote, writeNote, writeText } from "./state.js";
+import { bootstrapBundle, discoveryOf, door } from "./sync.js";
+import { sidecarPath } from "./sync-library.js";
+import { locate, removeReplicaFile, writeReplicaFile } from "./sync-state.js";
+
+const COMMITTER = "House Kit <house-kit@localhost>";
+const GIT_FAILED = "kit_working_copy_git_failed";
+
+function rejected(detail = null) {
+  return new KitRefusal("kit_working_copy_rejected", detail);
+}
+
+function stateHome(directory) {
+  return join(directory, "state", "working-copies");
+}
+
+function statePath(directory, scope) {
+  if (scope.kind === "private") return join(stateHome(directory), "private.json");
+  if (!ROOM_REFERENCE.test(scope.ref)) throw new KitRefusal("kit_state_name_invalid", scope.ref);
+  return join(stateHome(directory), "rooms", `${scope.ref}.json`);
+}
+
+function repositoryPath(base, scope) {
+  const root = join(base, WORKING_COPIES_HOME);
+  return scope.kind === "private" ? join(root, "private") : join(root, "rooms", scope.ref);
+}
+
+function housePath(scope) {
+  return scope.kind === "private" ? "/private" : `/rooms/${scope.handle}`;
+}
+
+function sameScope(copy, scope) {
+  return copy.scope === scope.kind && (scope.kind === "private" || copy.room_ref === scope.ref);
+}
+
+function selectedScope(room) {
+  if (
+    typeof room?.room_ref !== "string" ||
+    !ROOM_REFERENCE.test(room.room_ref) ||
+    (room.room_handle !== null && (typeof room.room_handle !== "string" || room.room_handle === ""))
+  ) {
+    throw rejected("selection");
+  }
+  return { kind: "room", ref: room.room_ref, handle: room.room_handle };
+}
+
+async function savedSelection(session, signal) {
+  const answer = await door(session, KIT_WORKING_COPY_SELECTION_PATH, {}, signal);
+  const copy = answer?.working_copy;
+  if (copy === null) return [];
+  if (!Array.isArray(copy?.rooms) || typeof copy.private !== "boolean") throw rejected("selection");
+  return [
+    ...copy.rooms.map(selectedScope),
+    ...(copy.private ? [{ kind: "private", ref: null, handle: null }] : []),
+  ];
+}
+
+function selectedPrefixes(scope) {
+  const homes = scope.kind === "private" ? WORKING_COPY_PRIVATE_HOMES : WORKING_COPY_ROOM_HOMES;
+  return homes.map((home) => `${housePath(scope)}/${home}`);
+}
+
+function receivedFiles(view) {
+  const manifest = view?.manifest;
+  if (
+    !Array.isArray(manifest?.files) ||
+    !Array.isArray(view.contents) ||
+    typeof manifest.anchor !== "string" ||
+    typeof manifest.position !== "string" ||
+    typeof manifest.log_epoch !== "string"
+  ) {
+    throw rejected("bootstrap");
+  }
+  const contents = new Map();
+  for (const entry of view.contents) {
+    if (typeof entry?.path !== "string" || typeof entry.content !== "string") throw rejected("bootstrap");
+    contents.set(entry.path, entry.content);
+  }
+  return manifest.files.map((file) => {
+    const content = contents.get(file?.path);
+    if (
+      content === undefined ||
+      typeof file.revision !== "string" ||
+      typeof file.sha256 !== "string" ||
+      typeof file.writable !== "boolean"
+    ) {
+      throw rejected("bootstrap");
+    }
+    return {
+      path: file.path,
+      revision: file.revision,
+      sha256: file.sha256,
+      writable: file.writable,
+      content,
+      provenance: typeof file.provenance === "string" ? file.provenance : null,
+    };
+  });
+}
+
+async function readScope(session, scope, signal) {
+  const prefixes = selectedPrefixes(scope);
+  const discovery = discoveryOf(await door(session, KIT_DOOR_DISCOVER_PATH, { prefixes }, signal));
+  const bundle = await bootstrapBundle(session, prefixes, signal);
+  if (bundle.scopes.length === 0) throw new KitRefusal("kit_working_copy_unavailable", housePath(scope));
+  if (bundle.scopes.length !== 1) throw rejected("bootstrap");
+  const [view] = bundle.scopes;
+  const files = receivedFiles(view);
+  const authority = discovery.authorities.find(
+    (entry) => entry?.room_ref === view.manifest.anchor,
+  );
+  if (
+    authority === undefined ||
+    !Array.isArray(authority.protected_paths) ||
+    (scope.kind === "room" && view.manifest.anchor !== scope.ref)
+  ) {
+    throw rejected("discover");
+  }
+  return {
+    anchor: view.manifest.anchor,
+    position: view.manifest.position,
+    logEpoch: view.manifest.log_epoch,
+    protectedPaths: authority.protected_paths.filter((path) => typeof path === "string"),
+    files,
+  };
+}
+
+function importData(text) {
+  const bytes = Buffer.from(text, "utf8");
+  return [Buffer.from(`data ${bytes.length}\n`), bytes, Buffer.from("\n")];
+}
+
+function quotedPath(path) {
+  return `"${path.replace(/[\\"]/g, "\\$&").replace(/\n/g, "\\n")}"`;
+}
+
+async function importReceived(repository, scope, read, parent, signal) {
+  const message = `House ${housePath(scope)} at position ${read.position}`;
+  const lines = [
+    Buffer.from(`commit ${WORKING_COPY_RECEIVED_REF}\n`),
+    Buffer.from(`committer ${COMMITTER} ${Math.floor(Date.now() / 1000)} +0000\n`),
+    ...importData(message),
+    ...(parent === null ? [] : [Buffer.from(`from ${parent}\n`)]),
+    Buffer.from("deleteall\n"),
+  ];
+  for (const file of read.files.filter((entry) => entry.writable)) {
+    lines.push(Buffer.from(`M 100644 inline ${quotedPath(file.path)}\n`), ...importData(file.content));
+  }
+  lines.push(Buffer.from("\n"));
+  await runGit(repository, ["fast-import", "--quiet", "--force"], {
+    input: Buffer.concat(lines),
+    signal,
+    failure: GIT_FAILED,
+  });
+  const commit = await runGit(repository, ["rev-parse", "--verify", `${WORKING_COPY_RECEIVED_REF}^{commit}`], {
+    capture: true,
+    signal,
+    failure: GIT_FAILED,
+  });
+  return commit.toString("utf8").trim();
+}
+
+function readOnlyContents(read) {
+  const contents = new Map();
+  for (const file of read.files) {
+    if (!file.writable) contents.set(file.path, file.content);
+    if (file.provenance !== null) contents.set(sidecarPath(file.path), file.provenance);
+  }
+  return contents;
+}
+
+async function present(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function trackedPaths(repository, signal) {
+  const listed = await runGit(repository, ["ls-files", "-z"], { capture: true, signal, failure: GIT_FAILED });
+  return new Set(listed.toString("utf8").split("\0").filter((path) => path !== ""));
+}
+
+async function replaceReadOnly(repository, previous, next, signal) {
+  const tracked = await trackedPaths(repository, signal);
+  const held = new Set(previous);
+  for (const [path, content] of next) {
+    if (tracked.has(path)) continue;
+    const target = locate(repository, "", path);
+    if (!held.has(path) && (await present(target))) continue;
+    await writeReplicaFile(target, content, signal);
+  }
+  for (const path of held) {
+    if (next.has(path) || tracked.has(path)) continue;
+    await removeReplicaFile(locate(repository, "", path));
+  }
+}
+
+function covers(path, prefix) {
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+function ignorePattern(path) {
+  return `/${path.replace(/[\\*?[]/g, "\\$&").replace(/ +$/, (spaces) => spaces.replace(/ /g, "\\ "))}`;
+}
+
+function ignoreGroups(read) {
+  const writable = read.files.filter((file) => file.writable).map((file) => file.path);
+  const readOnly = read.files.filter((file) => !file.writable).map((file) => file.path);
+  const whole = read.protectedPaths.filter((path) => !writable.some((file) => covers(file, path)));
+  const protectedPath = (path) => read.protectedPaths.some((prefix) => covers(path, prefix));
+  const house = [
+    ...whole,
+    ...readOnly.filter((path) => protectedPath(path) && !whole.some((prefix) => covers(path, prefix))),
+  ];
+  const granted = readOnly.filter((path) => !protectedPath(path));
+  return { house: house.map(ignorePattern), granted: granted.map(ignorePattern) };
+}
+
+async function writeIgnoreRules(repository, read, signal) {
+  const { house, granted } = ignoreGroups(read);
+  const gitignore = [
+    "# House Kit writes this file and .ignore. The paths below are read-only House",
+    "# content: Git does not track them, and House refuses a change to them even",
+    "# when this file is edited or a path is force-added.",
+    "/.gitignore",
+    "/.ignore",
+    "_provenance",
+    "",
+    "# House maintains or protects these paths.",
+    ...house,
+    "",
+    "# Your current House grant does not allow writing these paths.",
+    ...granted,
+    "",
+  ];
+  const ignore = [
+    "# House Kit writes this file so native search still reads the read-only House",
+    "# content that .gitignore keeps out of Git.",
+    "!_provenance",
+    ...[...house, ...granted].map((pattern) => `!${pattern}`),
+    "",
+  ];
+  await writeText(join(repository, ".gitignore"), gitignore.join("\n"), signal, 0o644);
+  await writeText(join(repository, ".ignore"), ignore.join("\n"), signal, 0o644);
+}
+
+function manifest(read, commit) {
+  return {
+    commit,
+    position: read.position,
+    log_epoch: read.logEpoch,
+    files: read.files.map(({ path, revision, sha256, writable }) => ({ path, revision, sha256, writable })),
+    read_only: [...readOnlyContents(read).keys()],
+  };
+}
+
+async function writeCopy(directory, copy, signal) {
+  await writeNote(statePath(directory, { kind: copy.scope, ref: copy.room_ref }), copy, signal);
+}
+
+async function heldCopies(directory) {
+  const rooms = join(stateHome(directory), "rooms");
+  let names = [];
+  try {
+    names = await readdir(rooms);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw new KitRefusal("kit_state_unreadable", rooms);
+  }
+  const held = [];
+  for (const name of names.filter((entry) => entry.endsWith(".json")).sort()) {
+    held.push(await readNote(join(rooms, name), null));
+  }
+  held.push(await readNote(statePath(directory, { kind: "private" }), null));
+  return held.filter((copy) => copy?.version === WORKING_COPY_VERSION);
+}
+
+async function materialize(context, scope, signal) {
+  const read = await readScope(context.session, scope, signal);
+  const identity = { kind: scope.kind, ref: read.anchor };
+  const repository = repositoryPath(context.launchBase, identity);
+  if (await present(repository)) throw new KitRefusal("kit_working_copy_unmanaged", repository);
+  const staging = join(dirname(repository), `.${randomUUID()}.staging`);
+  await mkdir(staging, { recursive: true });
+  let commit;
+  try {
+    await runGit(staging, ["init", "-q", "-b", WORKING_COPY_BRANCH], { signal, failure: GIT_FAILED });
+    commit = await importReceived(staging, scope, read, null, signal);
+    await runGit(staging, ["update-ref", `refs/heads/${WORKING_COPY_BRANCH}`, commit], {
+      signal,
+      failure: GIT_FAILED,
+    });
+    await runGit(staging, ["read-tree", "-m", "-u", "HEAD"], { signal, failure: GIT_FAILED });
+    await replaceReadOnly(staging, [], readOnlyContents(read), signal);
+    await writeIgnoreRules(staging, read, signal);
+    await rename(staging, repository);
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+  const received = manifest(read, commit);
+  await writeCopy(context.directory, {
+    version: WORKING_COPY_VERSION,
+    scope: scope.kind,
+    room_ref: read.anchor,
+    room_handle: scope.handle,
+    repository,
+    active: true,
+    base: received,
+    received,
+  });
+}
+
+async function refresh(context, copy, scope, signal) {
+  if (!(await present(copy.repository))) {
+    await rm(statePath(context.directory, { kind: copy.scope, ref: copy.room_ref }), { force: true });
+    await materialize(context, scope, signal);
+    return;
+  }
+  const read = await readScope(context.session, scope, signal);
+  if (read.anchor !== copy.room_ref) throw rejected("bootstrap");
+  const commit = await importReceived(copy.repository, scope, read, copy.received.commit, signal);
+  await replaceReadOnly(copy.repository, copy.received.read_only, readOnlyContents(read), signal);
+  await writeIgnoreRules(copy.repository, read, signal);
+  await writeCopy(
+    context.directory,
+    { ...copy, room_handle: scope.handle, active: true, received: manifest(read, commit) },
+    signal,
+  );
+}
+
+function scopeRefused(error) {
+  return error instanceof KitRefusal && (houseAnswered(error) || error.code.startsWith("kit_working_copy_"));
+}
+
+export async function applyWorkingCopies(context, signal) {
+  const selected = (await savedSelection(context.session, signal)).filter(
+    (scope) => scope.kind === "private" || scope.handle !== null,
+  );
+  const held = await heldCopies(context.directory);
+  for (const copy of held) {
+    if (copy.active && !selected.some((scope) => sameScope(copy, scope))) {
+      await writeCopy(context.directory, { ...copy, active: false }, signal);
+    }
+  }
+  const refused = [];
+  for (const scope of selected) {
+    const copy = held.find((entry) => sameScope(entry, scope));
+    try {
+      if (copy === undefined) await materialize(context, scope, signal);
+      else if (!copy.active) await refresh(context, copy, scope, signal);
+      else if (copy.room_handle !== scope.handle) {
+        await writeCopy(context.directory, { ...copy, room_handle: scope.handle }, signal);
+      }
+    } catch (error) {
+      if (!scopeRefused(error)) throw error;
+      refused.push({ path: housePath(scope), code: error.code });
+    }
+  }
+  return { refused };
+}
+
+export async function workingCopyPaths(directory) {
+  return (await heldCopies(directory))
+    .filter((copy) => copy.active)
+    .map((copy) => ({
+      path: housePath({ kind: copy.scope, handle: copy.room_handle }),
+      repository: copy.repository,
+    }))
+    .sort((left, right) => (left.path < right.path ? -1 : 1));
+}