@agentshouse/kit 0.1.0-alpha.16 → 0.1.0-alpha.18

package/src/working-copy.js

@@ -1,8 +1,11 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readdir, rename, rm, stat } from "node:fs/promises";
+import { mkdir, readdir, realpath, rename, rm, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { readBindings } from "./binding.js";
 import {
+  KIT_DOOR_BATCH_PATH,
   KIT_DOOR_DISCOVER_PATH,
+  KIT_DOOR_REVISIONS_PATH,
   KIT_WORKING_COPY_SELECTION_PATH,
   ROOM_REFERENCE,
   WORKING_COPIES_HOME,
@@ -13,13 +16,16 @@ import {
   WORKING_COPY_VERSION,
 } from "./contract.js";
 import { runGit } from "./git.js";
-import { houseAnswered, KitRefusal } from "./refusal.js";
+import { operationId } from "./operation.js";
+import { formatCommandError, houseAnswered, houseFailed, 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 { bootstrapBundle, discoveryOf, door, withSession } from "./sync.js";
+import { sidecarPath, structuredOrReplace } from "./sync-library.js";
 import { locate, removeReplicaFile, writeReplicaFile } from "./sync-state.js";
 
-const COMMITTER = "House Kit <house-kit@localhost>";
+const COMMITTER_NAME = "House Kit";
+const COMMITTER_EMAIL = "house-kit@localhost";
+const COMMITTER = `${COMMITTER_NAME} <${COMMITTER_EMAIL}>`;
 const GIT_FAILED = "kit_working_copy_git_failed";
 
 function rejected(detail = null) {
@@ -149,25 +155,53 @@ 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`),
+function importCommit(message, parents) {
+  return [
     Buffer.from(`committer ${COMMITTER} ${Math.floor(Date.now() / 1000)} +0000\n`),
     ...importData(message),
-    ...(parent === null ? [] : [Buffer.from(`from ${parent}\n`)]),
-    Buffer.from("deleteall\n"),
+    ...parents.map((parent, index) => Buffer.from(`${index === 0 ? "from" : "merge"} ${parent}\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));
+}
+
+function importFile(path, content) {
+  if (content === null) return [Buffer.from(`D ${quotedPath(path)}\n`)];
+  return [Buffer.from(`M 100644 inline ${quotedPath(path)}\n`), ...importData(content)];
+}
+
+async function importReceived(repository, { message, parents, files, whole = false, acknowledging = null }, signal) {
+  const stream = [];
+  const merged = [...parents];
+  if (acknowledging !== null && acknowledging.edits.length === 0) merged.push(acknowledging.commit);
+  if (acknowledging !== null && acknowledging.edits.length > 0) {
+    stream.push(
+      Buffer.from(`commit ${WORKING_COPY_RECEIVED_REF}\nmark :1\n`),
+      ...importCommit(`House accepted ${acknowledging.commit}`, [acknowledging.commit]),
+      ...acknowledging.edits.flatMap((edit) => importFile(edit.path, edit.content)),
+      Buffer.from("\n"),
+    );
+    merged.push(":1");
   }
-  lines.push(Buffer.from("\n"));
+  stream.push(
+    Buffer.from(`commit ${WORKING_COPY_RECEIVED_REF}\n`),
+    ...importCommit(message, merged),
+    ...(whole ? [Buffer.from("deleteall\n")] : []),
+    ...files.flatMap((file) => importFile(file.path, file.content)),
+    Buffer.from("\n"),
+  );
   await runGit(repository, ["fast-import", "--quiet", "--force"], {
-    input: Buffer.concat(lines),
+    input: Buffer.concat(stream),
     signal,
     failure: GIT_FAILED,
   });
-  const commit = await runGit(repository, ["rev-parse", "--verify", `${WORKING_COPY_RECEIVED_REF}^{commit}`], {
+  const received = await commitOf(repository, WORKING_COPY_RECEIVED_REF, signal);
+  if (acknowledging === null) return { received, acknowledged: null };
+  const acknowledged =
+    acknowledging.edits.length === 0 ? acknowledging.commit : await commitOf(repository, `${received}^2`, signal);
+  return { received, acknowledged };
+}
+
+async function commitOf(repository, name, signal) {
+  const commit = await runGit(repository, ["rev-parse", "--verify", `${name}^{commit}`], {
     capture: true,
     signal,
     failure: GIT_FAILED,
@@ -175,6 +209,16 @@ async function importReceived(repository, scope, read, parent, signal) {
   return commit.toString("utf8").trim();
 }
 
+async function remembered(repository, revisions, commit, files, signal) {
+  const tree = await treeOf(repository, commit, signal);
+  const next = { ...revisions };
+  for (const { path, revision } of files) {
+    const entry = tree.get(path);
+    if (entry !== undefined && revision !== null) next[path] = { ...next[path], [entry.object]: revision };
+  }
+  return next;
+}
+
 function readOnlyContents(read) {
   const contents = new Map();
   for (const file of read.files) {
@@ -268,13 +312,21 @@ function manifest(read, commit) {
     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()],
   };
 }
 
+function copyPath(directory, copy) {
+  return statePath(directory, { kind: copy.scope, ref: copy.room_ref });
+}
+
 async function writeCopy(directory, copy, signal) {
-  await writeNote(statePath(directory, { kind: copy.scope, ref: copy.room_ref }), copy, signal);
+  await writeNote(copyPath(directory, copy), copy, signal);
+}
+
+async function readCopy(path) {
+  const copy = await readNote(path, null);
+  return copy?.version === WORKING_COPY_VERSION ? copy : null;
 }
 
 async function heldCopies(directory) {
@@ -287,10 +339,30 @@ async function heldCopies(directory) {
   }
   const held = [];
   for (const name of names.filter((entry) => entry.endsWith(".json")).sort()) {
-    held.push(await readNote(join(rooms, name), null));
+    held.push(await readCopy(join(rooms, name)));
   }
-  held.push(await readNote(statePath(directory, { kind: "private" }), null));
-  return held.filter((copy) => copy?.version === WORKING_COPY_VERSION);
+  held.push(await readCopy(statePath(directory, { kind: "private" })));
+  return held.filter((copy) => copy !== null);
+}
+
+const turns = new Map();
+
+function exclusively(path, work) {
+  const turn = (turns.get(path) ?? Promise.resolve()).then(work);
+  const settled = turn.then(
+    () => undefined,
+    () => undefined,
+  );
+  turns.set(path, settled);
+  void settled.then(() => {
+    if (turns.get(path) === settled) turns.delete(path);
+  });
+  return turn;
+}
+
+function received(scope, read, parents) {
+  const files = read.files.filter((file) => file.writable);
+  return { message: `House ${housePath(scope)} at position ${read.position}`, parents, files, whole: true };
 }
 
 async function materialize(context, scope, signal) {
@@ -300,10 +372,13 @@ async function materialize(context, scope, signal) {
   if (await present(repository)) throw new KitRefusal("kit_working_copy_unmanaged", repository);
   const staging = join(dirname(repository), `.${randomUUID()}.staging`);
   await mkdir(staging, { recursive: true });
+  const imported = received(scope, read, []);
   let commit;
+  let revisions;
   try {
     await runGit(staging, ["init", "-q", "-b", WORKING_COPY_BRANCH], { signal, failure: GIT_FAILED });
-    commit = await importReceived(staging, scope, read, null, signal);
+    commit = (await importReceived(staging, imported, signal)).received;
+    revisions = await remembered(staging, {}, commit, imported.files, signal);
     await runGit(staging, ["update-ref", `refs/heads/${WORKING_COPY_BRANCH}`, commit], {
       signal,
       failure: GIT_FAILED,
@@ -316,7 +391,6 @@ async function materialize(context, scope, signal) {
     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,
@@ -324,27 +398,33 @@ async function materialize(context, scope, signal) {
     room_handle: scope.handle,
     repository,
     active: true,
-    base: received,
-    received,
+    received: manifest(read, commit),
+    revisions,
   });
 }
 
+async function receive(context, copy, scope, signal) {
+  const read = await readScope(context.session, scope, signal);
+  if (read.anchor !== copy.room_ref) throw rejected("bootstrap");
+  const imported = received(scope, read, [copy.received.commit]);
+  const commit = (await importReceived(copy.repository, imported, signal)).received;
+  await replaceReadOnly(copy.repository, copy.received.read_only, readOnlyContents(read), signal);
+  await writeIgnoreRules(copy.repository, read, signal);
+  return {
+    ...copy,
+    received: manifest(read, commit),
+    revisions: await remembered(copy.repository, copy.revisions, commit, imported.files, signal),
+  };
+}
+
 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 rm(copyPath(context.directory, copy), { 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,
-  );
+  const next = await receive(context, copy, scope, signal);
+  await writeCopy(context.directory, { ...next, room_handle: scope.handle, active: true }, signal);
 }
 
 function scopeRefused(error) {
@@ -355,21 +435,26 @@ 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);
-    }
+  for (const held of await heldCopies(context.directory)) {
+    if (!held.active || selected.some((scope) => sameScope(held, scope))) continue;
+    const path = copyPath(context.directory, held);
+    await exclusively(path, async () => {
+      const copy = await readCopy(path);
+      if (copy !== null) await writeCopy(context.directory, { ...copy, active: false }, signal);
+    });
   }
   const refused = [];
   for (const scope of selected) {
-    const copy = held.find((entry) => sameScope(entry, scope));
+    const path = statePath(context.directory, 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);
-      }
+      await exclusively(path, async () => {
+        const copy = await readCopy(path);
+        if (copy === null) 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 });
@@ -387,3 +472,387 @@ export async function workingCopyPaths(directory) {
     }))
     .sort((left, right) => (left.path < right.path ? -1 : 1));
 }
+
+function scopeOf(copy) {
+  return { kind: copy.scope, ref: copy.room_ref, handle: copy.room_handle };
+}
+
+function without(copy) {
+  const { push, ...settled } = copy;
+  return settled;
+}
+
+function lines(output) {
+  return output.toString("utf8").split("\n").filter((line) => line !== "");
+}
+
+function succeeded(git) {
+  return git.then(
+    () => true,
+    () => false,
+  );
+}
+
+function contains(repository, ancestor, descendant, signal) {
+  return succeeded(
+    runGit(repository, ["merge-base", "--is-ancestor", ancestor, descendant], { signal, failure: GIT_FAILED }),
+  );
+}
+
+async function located(cwd, signal) {
+  const [common, worktree] = lines(
+    await runGit(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir", "--show-toplevel"], {
+      capture: true,
+      signal,
+      failure: "kit_working_copy_unresolved",
+    }),
+  );
+  return { repository: await realpath(dirname(common)), worktree };
+}
+
+async function copyAt(directory, repository) {
+  for (const copy of await heldCopies(directory)) {
+    if ((await realpath(copy.repository).catch(() => null)) === repository) return copy;
+  }
+  throw new KitRefusal("kit_working_copy_not_found", repository);
+}
+
+async function treeOf(repository, commit, signal) {
+  const listed = await runGit(repository, ["ls-tree", "-r", "-z", commit], {
+    capture: true,
+    signal,
+    failure: GIT_FAILED,
+  });
+  const tree = new Map();
+  for (const entry of listed.toString("utf8").split("\0").filter((line) => line !== "")) {
+    const tab = entry.indexOf("\t");
+    const [, type, object] = entry.slice(0, tab).split(" ");
+    tree.set(entry.slice(tab + 1), { type, object });
+  }
+  return tree;
+}
+
+async function blobText(repository, entry, path, signal) {
+  if (entry === undefined) return null;
+  if (entry.type !== "blob") throw new KitRefusal("kit_working_copy_not_text", path);
+  const bytes = await runGit(repository, ["cat-file", "blob", entry.object], {
+    capture: true,
+    signal,
+    failure: GIT_FAILED,
+  });
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    throw new KitRefusal("kit_working_copy_not_text", path);
+  }
+}
+
+async function trustedBase(copy, commit, signal) {
+  const git = (args) => runGit(copy.repository, args, { capture: true, signal, failure: GIT_FAILED });
+  const house = new Set(
+    lines(await git(["rev-list", "--first-parent", "--parents", copy.received.commit])).flatMap((line) => {
+      const [received, , acknowledged] = line.split(" ");
+      return acknowledged === undefined ? [received] : [received, acknowledged];
+    }),
+  );
+  const base = lines(await git(["rev-list", "--topo-order", commit])).find((ancestor) => house.has(ancestor));
+  if (base !== undefined) return base;
+  throw new KitRefusal(
+    "kit_working_copy_base_unknown",
+    `${commit} contains no House state; merge or rebase onto ${WORKING_COPY_RECEIVED_REF}`,
+  );
+}
+
+async function derived(copy, base, commit, signal) {
+  const root = housePath(scopeOf(copy));
+  const before = await treeOf(copy.repository, base, signal);
+  const after = await treeOf(copy.repository, commit, signal);
+  const changes = [];
+  for (const path of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+    const prior = before.get(path);
+    const next = after.get(path);
+    if (prior?.object === next?.object) continue;
+    const target = `${root}/${path}`;
+    const revision = copy.revisions[path]?.[prior?.object];
+    if (next === undefined) {
+      changes.push({ op: "remove", path: target, base: revision });
+      continue;
+    }
+    const content = await blobText(copy.repository, next, path, signal);
+    if (prior === undefined) {
+      changes.push({ op: "create", path: target, content });
+      continue;
+    }
+    const recorded = { content: await blobText(copy.repository, prior, path, signal), revision };
+    changes.push(...structuredOrReplace(root, path, recorded, content));
+  }
+  return changes;
+}
+
+async function revisionText(session, { path, revision }, signal) {
+  const page = await door(session, KIT_DOOR_REVISIONS_PATH, { path, revision }, signal);
+  const content = page?.revisions?.find((entry) => entry?.revision === revision)?.content;
+  if (typeof content !== "string") throw new KitRefusal("kit_working_copy_result_unreadable", `${path} at ${revision}`);
+  return content;
+}
+
+async function materials(context, copy, entries, signal) {
+  const root = housePath(scopeOf(copy));
+  const files = [];
+  for (const entry of entries) {
+    const content = entry.content === undefined ? await revisionText(context.session, entry, signal) : entry.content;
+    files.push({ path: entry.path.slice(root.length + 1), revision: entry.revision, content });
+  }
+  return files;
+}
+
+async function recorded(copy, files, message, acknowledging, signal) {
+  const imported = await importReceived(
+    copy.repository,
+    { message, parents: [copy.received.commit], files, acknowledging },
+    signal,
+  );
+  return {
+    copy: {
+      ...copy,
+      received: { ...copy.received, commit: imported.received },
+      revisions: await remembered(copy.repository, copy.revisions, imported.received, files, signal),
+    },
+    acknowledged: imported.acknowledged,
+  };
+}
+
+function submittedPaths(copy) {
+  const root = housePath(scopeOf(copy));
+  return new Set(copy.push.changes.map((change) => change.path.slice(root.length + 1)));
+}
+
+function short(commit) {
+  return commit.slice(0, 12);
+}
+
+async function acknowledge(context, copy, signal) {
+  const { push } = copy;
+  const files = await materials(context, copy, push.written, signal);
+  const selected = await treeOf(copy.repository, push.commit, signal);
+  const edits = [];
+  for (const file of files) {
+    if ((await blobText(copy.repository, selected.get(file.path), file.path, signal)) !== file.content) edits.push(file);
+  }
+  const { copy: next, acknowledged } = await recorded(
+    copy,
+    files,
+    `House ${housePath(scopeOf(copy))} with ${push.commit} accepted`,
+    { commit: push.commit, edits },
+    signal,
+  );
+  return { ...next, push: { ...push, acknowledged } };
+}
+
+async function integrated(copy, signal) {
+  const { commit, acknowledged, worktree, branch } = copy.push;
+  const accepted = `House accepted ${short(commit)}`;
+  if (acknowledged === commit) return { done: true, text: `${accepted}.` };
+  const pending = (reason) => ({
+    done: false,
+    text: `${accepted}; local integration is pending (${reason}): ${acknowledged} holds House's result.`,
+  });
+  const git = (args) => runGit(worktree, args, { capture: true, signal, failure: GIT_FAILED });
+  const head = await git(["symbolic-ref", "-q", "HEAD"]).then(
+    (output) => lines(output)[0],
+    () => null,
+  );
+  if (branch === null || head !== branch) return pending("the branch changed");
+  const tip = lines(await git(["rev-parse", "HEAD"]))[0];
+  const name = branch.replace(/^refs\/heads\//, "");
+  if (await contains(worktree, acknowledged, tip, signal)) return { done: true, text: `${accepted}; ${name} holds it.` };
+  if (!(await contains(worktree, commit, tip, signal))) return pending("the branch changed");
+  if (lines(await git(["status", "--porcelain", "--untracked-files=no"])).length > 0) {
+    return pending("uncommitted changes");
+  }
+  if (tip === commit) {
+    if (!(await succeeded(git(["merge", "--ff-only", "-q", acknowledged])))) return pending("a conflict");
+  } else if (
+    !(await succeeded(
+      git(["-c", `user.name=${COMMITTER_NAME}`, "-c", `user.email=${COMMITTER_EMAIL}`, "rebase", "-q", "--onto", acknowledged, commit]),
+    ))
+  ) {
+    await git(["rebase", "--abort"]).catch(() => undefined);
+    return pending("a conflict");
+  }
+  return { done: true, text: `${accepted}; ${name} is at ${short(lines(await git(["rev-parse", "HEAD"]))[0])}.` };
+}
+
+async function finish(context, copy, signal) {
+  try {
+    let acknowledged = copy;
+    if (copy.push.acknowledged === undefined) {
+      acknowledged = await acknowledge(context, copy, signal);
+      await writeCopy(context.directory, acknowledged, signal);
+    }
+    const outcome = await integrated(acknowledged, signal);
+    if (outcome.done) await writeCopy(context.directory, without(acknowledged), signal);
+    return { refused: false, text: outcome.text };
+  } catch (error) {
+    return {
+      refused: false,
+      text: `House accepted ${short(copy.push.commit)}; local integration is pending (${formatCommandError(error)}); run house git push again to finish it.`,
+    };
+  }
+}
+
+function sameCaller(left, right) {
+  return left.session === right.session && left.owner === right.owner;
+}
+
+function definite(error) {
+  return (
+    error instanceof KitRefusal &&
+    error.code !== "kit_command_cancelled" &&
+    !houseFailed(error) &&
+    !(error.status >= 500)
+  );
+}
+
+async function orphaned(context, copy, signal) {
+  const held = copy.push.caller.session;
+  const live = (binding) => binding.session === held && binding.stopped === null && binding.reported === null;
+  if (held === undefined || (await readBindings(context.directory)).some(live)) {
+    throw new KitRefusal("kit_working_copy_push_pending", "another caller's push awaits its recovery");
+  }
+  await writeCopy(context.directory, await receive(context, without(copy), scopeOf(copy), signal), signal);
+  throw new KitRefusal(
+    "kit_working_copy_push_unrecoverable",
+    `the Session that pushed ended before its outcome arrived; ${WORKING_COPY_RECEIVED_REF} holds House's current state`,
+  );
+}
+
+async function expired(context, copy, text, signal) {
+  const { push } = copy;
+  const root = housePath(scopeOf(copy));
+  const confirmed = await receive(context, without(copy), scopeOf(copy), signal);
+  const house = await treeOf(copy.repository, confirmed.received.commit, signal);
+  const selected = await treeOf(copy.repository, push.commit, signal);
+  const paths = [...submittedPaths(copy)];
+  if (paths.some((path) => house.get(path)?.object !== selected.get(path)?.object)) {
+    await writeCopy(context.directory, confirmed, signal);
+    return {
+      refused: true,
+      text: `${text}\nHouse does not hold ${short(push.commit)}; run house git push again to submit it as a new operation.`,
+    };
+  }
+  const written = [];
+  for (const path of paths) {
+    const entry = house.get(path);
+    written.push({
+      path: `${root}/${path}`,
+      revision: entry === undefined ? null : confirmed.revisions[path][entry.object],
+      content: await blobText(copy.repository, entry, path, signal),
+    });
+  }
+  const accepted = { ...confirmed, push: { ...push, state: "accepted", written } };
+  await writeCopy(context.directory, accepted, signal);
+  return finish(context, accepted, signal);
+}
+
+async function settle(context, copy, caller, signal) {
+  const { push } = copy;
+  if (!sameCaller(push.caller, caller.binding)) return orphaned(context, copy, signal);
+  let answer;
+  try {
+    answer = await caller.submit({ operation_id: push.operation_id, changes: push.changes }, signal);
+  } catch (error) {
+    if (!definite(error)) {
+      throw new KitRefusal("kit_working_copy_push_uncertain", "run house git push again to recover its outcome");
+    }
+    const current = error.payload?.error?.current;
+    answer = { refused: { code: error.code, text: formatCommandError(error), current: Array.isArray(current) ? current : null } };
+  }
+  const { refused } = answer;
+  if (refused?.code === "operation_expired") return expired(context, copy, refused.text, signal);
+  if (refused === null) {
+    const submitted = new Set(push.changes.map((change) => change.path));
+    const written = answer.written.filter((entry) => submitted.has(entry.path));
+    const accepted = { ...copy, push: { ...push, state: "accepted", written } };
+    await writeCopy(context.directory, accepted, signal);
+    return finish(context, accepted, signal);
+  }
+  const settled = without(copy);
+  await writeCopy(context.directory, settled, signal);
+  if (refused.current === null) return { refused: true, text: refused.text };
+  try {
+    const files = await materials(context, settled, refused.current, signal);
+    const message = `House ${housePath(scopeOf(settled))} current where ${short(push.commit)} was refused`;
+    await writeCopy(context.directory, (await recorded(settled, files, message, null, signal)).copy, signal);
+    return { refused: true, text: refused.text };
+  } catch (error) {
+    return { refused: true, text: `${refused.text}\n${WORKING_COPY_RECEIVED_REF} is unchanged: ${formatCommandError(error)}` };
+  }
+}
+
+async function pushed(context, path, at, selector, caller, signal) {
+  let copy = await readCopy(path);
+  if (copy.push?.state === "submitted") return settle(context, copy, caller, signal);
+  const commit = (
+    await runGit(at.worktree, ["rev-parse", "--verify", "--quiet", "--end-of-options", `${selector}^{commit}`], {
+      capture: true,
+      signal,
+      failure: "kit_working_copy_commit_unknown",
+    })
+  )
+    .toString("utf8")
+    .trim();
+  if (copy.push !== undefined) {
+    const held = copy.push.acknowledged;
+    if (held === undefined || !(await contains(copy.repository, held, commit, signal))) {
+      return finish(context, copy, signal);
+    }
+    copy = without(copy);
+    await writeCopy(context.directory, copy, signal);
+  }
+  if (!copy.active) throw new KitRefusal("kit_working_copy_inactive", housePath(scopeOf(copy)));
+  const changes = await derived(copy, await trustedBase(copy, commit, signal), commit, signal);
+  if (changes.length === 0) return { refused: false, text: `Nothing to submit: ${short(commit)} matches House.` };
+  const branch = await runGit(at.worktree, ["symbolic-ref", "-q", "HEAD"], { capture: true, signal, failure: GIT_FAILED })
+    .then((output) => lines(output)[0], () => null);
+  const submitted = {
+    ...copy,
+    push: {
+      state: "submitted",
+      caller: caller.binding,
+      operation_id: operationId(),
+      changes,
+      commit,
+      worktree: at.worktree,
+      branch,
+    },
+  };
+  await writeCopy(context.directory, submitted, signal);
+  return settle(context, submitted, caller, signal);
+}
+
+export async function pushWorkingCopy(context, request, caller, signal) {
+  if (typeof request?.cwd !== "string" || typeof request.commit !== "string") {
+    throw new KitRefusal("kit_house_arguments_invalid", "cwd and commit");
+  }
+  const at = await located(request.cwd, signal);
+  const path = copyPath(context.directory, await copyAt(context.directory, at.repository));
+  return exclusively(path, () => pushed(context, path, at, request.commit, caller, signal));
+}
+
+export function ownerCaller(session) {
+  return {
+    binding: { owner: true },
+    async submit(body, signal) {
+      return { refused: null, written: (await door(session, KIT_DOOR_BATCH_PATH, body, signal)).contents };
+    },
+  };
+}
+
+export function ownerPush(options, request, dependencies = {}) {
+  return withSession(options, dependencies, (session, signal) =>
+    session.resident === undefined
+      ? pushWorkingCopy({ directory: options.directory, session }, request, ownerCaller(session), signal)
+      : session.push(request, signal),
+  );
+}