@agentshouse/kit 0.1.0-alpha.13 → 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.13/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
@@ -1217,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
@@ -1502,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/bootstrap.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.14",
   "hosts": {
     "linux": {
-      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.13/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.13/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.13",
+  "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/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/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 {
@@ -436,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);
@@ -463,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,
@@ -794,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 {
@@ -810,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;
@@ -960,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 {
@@ -1001,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));
+}