@agentshouse/kit 0.1.0-alpha.30 → 0.1.0-alpha.32

package/README.md

@@ -12,7 +12,7 @@ The Skill set Kit installs is Matt Pocock's
 On Linux `amd64` or `arm64`, run the published, versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.30/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.32/connect-linux.sh)
 ```
 
 The bootstrap first establishes Docker Engine from what it observes on the
@@ -584,13 +584,14 @@ Google Sources. After that it acquires only what House names. A
 subject alone. `runs` takes a resumption or else a waiting Run, readying the
 agent CLIs, a requested setup and conversation files first. `commands` hands
 the supervised Session its stops, interrupts and answers and takes a
-resumption the same way, without acquiring a Run. An `entries` frame, a change
-in a Room the lease admits, delivers the working copies. A pass that took a Run
-acquires again once that Run ends, and a pass that found nothing waits for the
-next signal. A Run outcome House did not take is reported again every 30
-seconds until House answers. The Kit has no idle acquisition cycle, no command
-poll and no Session heartbeat: a Session is observed when its process starts
-and when its supervisor sees it stop.
+resumption the same way, without acquiring a Run. An `entries` frame carries
+the Change entries of a Room the lease admits, which the resident applies to
+that Room's [working copy](#working-copies) in the order the frames arrive. A
+pass that took a Run acquires again once that Run ends, and a pass that found
+nothing waits for the next signal. A Run outcome House neither took nor finally
+refused is reported again every 30 seconds. The Kit has no idle acquisition
+cycle, no command poll and no Session heartbeat: a Session is observed when its
+process starts and when its supervisor sees it stop.
 
 A socket that closes or never opens reconnects after a delay drawn between half
 and all of one second, doubled for each consecutive failure up to 30 seconds.
@@ -968,7 +969,7 @@ Within the same live Kit and supervised WorkerSession, a lost response or
 infrastructure failure resends that request with the same identifier. A local
 socket reconnect delivers the retained outcome to the process.
 A second deliberate call gets a new identifier; read-only calls carry none.
-House refusals pass through to the CLI without automatic resend. [R193](https://github.com/agentshouse/core/blob/main/docs/concept/implementation/08-routine-requests-human-notifications-and-workers.md#r193)
+House refusals pass through to the CLI without automatic resend. [R193](https://github.com/agentshouse/core/blob/main/docs/concept/implementation/14-agents-profiles-sessions-and-runs.md#r193)
 owns recovery authority, lifetime, and refusal semantics.
 
 The launcher speaks only what the adapter contract fixes for this build. Every
@@ -1070,7 +1071,7 @@ Between turns, Kit retains the opaque provider session identifier and the Run's
 Worker, working directory, and route references in an owner-only local record.
 The record carries no transcript or Session credential and grants no authority:
 House must authorize each successor WorkerSession. A reported terminal state and
-owner stops remove the record. [R199](https://github.com/agentshouse/core/blob/main/docs/concept/implementation/08-routine-requests-human-notifications-and-workers.md#r199)
+owner stops remove the record. [R199](https://github.com/agentshouse/core/blob/main/docs/concept/implementation/14-agents-profiles-sessions-and-runs.md#r199)
 owns conversation continuity.
 
 Launcher exit is the terminal process observation. The Kit closes the local
@@ -1097,7 +1098,11 @@ Provider continuation remains available reports no terminal state at all and
 leaves the Run active for an owner-originated resumption.
 
 The Kit decides that terminal state once, records it beside its stable operation
-identity before it reports it, and reports it from that record. A Run with a
+identity before it reports it, and reports it from that record. It decides and
+records it as soon as the stop is recorded and the final text sealed, before it
+reports the stopped Session and its continuation facts: a refusal of either of
+those does not change the terminal state, so the Kit reports that recorded state
+whatever House answered to them. A Run with a
 supervised session records it in that session's durable local binding; a Run
 whose terminal state was decided without one — a resume command this Kit rejects
 because it retains no Provider continuation for the Run, or an acquired Run it
@@ -1109,11 +1114,23 @@ House answers the committed settlement verbatim and the Agent is never executed
 again. A Run House has already settled answers `worker_run_settled`, which the
 Kit accepts as settled and drops the record for.
 
-Every other refusal leaves that record exactly as it is. The Run stays bound to
-this installation, `kit worker run` names the refusal House answered with and
-exits non-zero, and the same decided body is reported again before anything is
-acquired. Nothing is dropped locally that House did not accept, and a refused
-report is never presented to the owner as a delivered one.
+The Kit keeps that record until House answers it. The record stays exactly as it
+is while House is unavailable, never answers or answers in a form the Kit cannot
+read, declares its refusal retryable, answers 429, 502 or 503 without declaring
+otherwise, refuses the Kit contract or the Kit's lease, including a lease
+renewal the report waited on, refuses the operation identity as issued ahead of
+its clock, or answers `conversation_file_send_pending` because a conversation
+file the Run sent is still being delivered. A report whose operation identity
+House no longer holds, answered `operation_expired` or `position_expired`, keeps
+the same body under a new operation identity. Either way the Run stays bound to
+this installation, `kit worker run` names the refusal House answered with, if
+any, and exits non-zero, and the same decided body is reported again before
+anything is acquired. Every other refusal is House's final answer for that
+report, such as `worker_run_not_found` or `worker_run_not_acquired`: the Kit
+writes `kit: run <run> outcome refused: <code>` to standard error once, drops
+the record, and acquires as if the report had been taken. For the Run it
+supervised in that pass, `kit worker run` also names that refusal and exits
+non-zero. A refused report is never presented to the owner as a delivered one.
 
 While a WorkerSession is supervised the Kit keeps one durable local binding
 naming this installation, the WorkerRun, the WorkerSession, the exact tmux
@@ -1131,21 +1148,21 @@ instead of treating the session as lost.
 
 A restarted `kit worker run` reconciles the records it kept before it acquires
 anything new. It reports every retained settlement note first, because those
-Runs have no session left to reconcile, and drops each note House accepts or
-already settled. It next consumes the durable commands House holds for this
-Environment, so a requested owner stop ends the exact tmux session before any
-local channel reopens. It then considers only sessions of its own namespace
-whose binding is complete, and never lists unknown sessions, scans host
-processes, searches another namespace, or adopts an arbitrary process. A session
-that is already gone is confirmed gone, reported as one stopped Session with no
-Provider continuation, and settled as a terminal execution failure. A session
-that is still running is restored only after House
-positively replaces the Session authority for the same Run and Session; the Kit
-then reconnects the typed adapter channel, refreshes the started observation,
-and supervises that session to settlement instead of acquiring another Run. An
-explicit House refusal destroys the stale tmux session and exposes no channel.
-House that cannot be reached leaves the binding and the session exactly as they
-are, invents no stopped, active, or authorized state, and acquires nothing.
+Runs have no session left to reconcile, and drops each note House accepts,
+already settled or finally refused. It next consumes the durable commands House
+holds for this Environment, so a requested owner stop ends the exact tmux
+session before any local channel reopens. It then considers only sessions of its
+own namespace whose binding is complete, and never lists unknown sessions, scans
+host processes, searches another namespace, or adopts an arbitrary process. A
+session that is already gone is confirmed gone, reported as one stopped Session
+with no Provider continuation, and settled as a terminal execution failure. A
+session that is still running is restored only after House positively replaces
+the Session authority for the same Run and Session; the Kit then reconnects the
+typed adapter channel, refreshes the started observation, and supervises that
+session to settlement instead of acquiring another Run. An explicit House
+refusal destroys the stale tmux session and exposes no channel. House that
+cannot be reached leaves the binding and the session exactly as they are,
+invents no stopped, active, or authorized state, and acquires nothing.
 
 A restore of House's database starts a new log epoch. Until this Environment
 has reported in it, House refuses every act that touches a Run, acquisition and
@@ -1373,9 +1390,17 @@ state. The House revision of every file content Kit received, keyed by path,
 Git blob and the House state that received it, stays in Kit home under
 `state/working-copies/`, outside the repository. A local commit is a local tree, never a House revision.
 
-The resident Kit keeps every active copy current. Whenever its control stream
-carries a Room change, and whenever it reads the saved choice, one
-`POST /kit/door/discover` tells it where each
+The resident Kit keeps every active copy current. An `entries` frame on its
+control stream names a copied Room, the Room's position and log epoch, and the
+Change entries that brought it there: each changed path with its revision and
+text, or its removal. The resident applies the entries under the copy's own
+homes directly, without reading House, when the frame follows on from the copy:
+the same socket already carried an earlier frame for that Room, the copy's
+recorded position has reached that earlier frame's position, the log epoch is
+the copy's, and every changed path carries its revision and text. A frame the
+copy already holds changes nothing. Any other frame, and every reading of the
+saved choice, reads House instead, with the frames that arrive during one
+reading served by the next: one `POST /kit/door/discover` tells it where each
 copied Room stands, and for a Room that moved on it reads the changes after the
 copy's recorded position through `POST /kit/door/enumerate`. A changed, new or
 removed authored file becomes a commit on `refs/house/received`, its House
@@ -1548,7 +1573,12 @@ House alone validates the resulting Library: a batch it refuses answers with
 House's own file path, field, rule, and version. A refusal is reported with the
 current material House returned and the local directory is left for the caller.
 An acceptance updates the recorded position, its log epoch, and the affected
-files from the returned final content.
+files from the returned final content. It also reads House's own provenance
+for those files by enumerating from the position the batch started at, and
+writes each served sidecar whose revision is the accepted one, so a submit,
+answered or recovered after a lost answer, leaves each file's `_provenance`
+sidecar at the revision House recorded. Kit never composes that metadata
+itself.
 
 Pending submissions are written before transfer. A lost response, reconnect, or
 lease renewal recovers that exact request under the same identifier. A domain
@@ -1561,6 +1591,10 @@ the Kit drops it like any other refusal, `rebootstrap` rebuilds the directory,
 and a change still wanted is a new deliberate submit against the rebuilt bases.
 Once House has answered any request for a replica `position_expired`, the
 replica refuses `submit` as `position_expired` until `rebootstrap` rebuilds it.
+A pending submission House answers `operation_expired` is uncertain, so the
+Kit first pulls confirmed state. If House already holds the pending change,
+the Kit drops the pending copy and sends nothing more; only if it does not
+does the Kit send that change again under a new identifier.
 `rebootstrap` drops a submission still pending against the directory it
 replaces.
 
@@ -2099,6 +2133,19 @@ the previous control lease before starting the next isolated command. Evidence
 is written to `tmp/delivery-evidence/migrator-pair.json` with producer revisions
 and the installed package digest.
 
+Explicit sync has its own paired proof:
+
+```sh
+HOUSE_CORE_ROOT=<core checkout> HOUSE_AUTH_ROOT=<auth checkout> \
+  KIT_PAIR_SPECS=/kit/test/pair/sync.vitest.ts bash test/pair/run.sh
+```
+
+It proves that an accepted `submit`, answered or recovered after a lost answer,
+leaves each file's `_provenance` sidecar equal to the provenance House serves,
+and that a pending submission House answers `operation_expired` is pulled first,
+then sent again under a new identifier only if it never landed. Evidence is
+written to `tmp/delivery-evidence/sync-pair.json`.
+
 The retained-original consumers have their own paired proofs:
 
 ```sh

package/bin/kit.js

@@ -478,8 +478,10 @@ async function runWorkerRun(args, directory) {
       `Run ${run.run} stays bound to this installation until House accepts that report` +
         `${run.refused === null ? "" : ` (${run.refused.code})`}.`,
     );
+  } else if (run.refused !== null) {
+    write(`House refused that report (${run.refused.code}); this installation no longer holds Run ${run.run}.`);
   }
-  if (!run.settled || reported?.outcome === "failed") process.exitCode = 1;
+  if (!run.settled || run.refused !== null || reported?.outcome === "failed") process.exitCode = 1;
 }
 
 function syncCancellation() {

package/bootstrap.json

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

package/package.json

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

package/src/kit-work-stream.js

@@ -40,6 +40,7 @@ async function held(session, signal, heard, dependencies) {
       perMessageDeflate: false,
     });
     let finished = false;
+    const carried = new Map();
     const finish = (reason = null, refusal = null) => {
       if (finished) return;
       finished = true;
@@ -63,7 +64,8 @@ async function held(session, signal, heard, dependencies) {
       if (frame?.type === "work_available" && WORK_SUBJECTS.includes(frame.subject)) {
         heard.available(frame.subject);
       } else if (frame?.type === "entries") {
-        heard.changed();
+        heard.changed(frame, carried.get(frame.authority) ?? null);
+        carried.set(frame.authority, frame.position);
       } else if (VIEW_FRAMES.includes(frame?.type)) {
         heard.viewed?.(frame);
       }

package/src/sync.js

@@ -13,6 +13,7 @@ import {
   assertWritableChanges,
   authorityFor,
   deriveChanges,
+  housePath,
   OPERATIONS,
   relativeTo,
   resultingFiles,
@@ -248,6 +249,12 @@ function enumeratedRecord(path, content, change) {
   };
 }
 
+async function writeSidecar(options, authority, recorded, path, change, signal) {
+  const sidecar = sidecarPath(path);
+  await writeReplicaFile(locate(options.replica, authority.path, sidecar), change.provenance, signal);
+  recorded.set(sidecar, enumeratedRecord(sidecar, change.provenance, change));
+}
+
 async function applyEnumeration(options, state, enumeration, signal) {
   if (!Array.isArray(enumeration?.authorities)) throw new KitRefusal("kit_sync_rejected", "enumerate");
   for (const view of enumeration.authorities) {
@@ -271,13 +278,7 @@ async function applyEnumeration(options, state, enumeration, signal) {
         recorded.set(change.path, enumeratedRecord(change.path, change.content, change));
       }
       if (typeof change.provenance === "string") {
-        const sidecar = sidecarPath(change.path);
-        await writeReplicaFile(
-          locate(options.replica, authority.path, sidecar),
-          change.provenance,
-          signal,
-        );
-        recorded.set(sidecar, enumeratedRecord(sidecar, change.provenance, change));
+        await writeSidecar(options, authority, recorded, change.path, change, signal);
       }
     }
     authority.files = [...recorded.values()];
@@ -309,12 +310,40 @@ function uncertainTransport(error) {
   );
 }
 
-async function acceptBatch(options, state, outcome, signal, pending = null) {
+async function servedProvenance(session, options, state, authority, signal) {
+  const enumeration = await replicaDoor(
+    session,
+    options,
+    state,
+    KIT_DOOR_ENUMERATE_PATH,
+    {
+      prefixes: state.prefixes.filter((prefix) => authorityFor(state, prefix) === authority),
+      positions: [
+        { authority: authority.authority, position: authority.position, log_epoch: authority.log_epoch },
+      ],
+    },
+    signal,
+  );
+  const view = Array.isArray(enumeration?.authorities)
+    ? enumeration.authorities.find((entry) => entry?.authority === authority.authority)
+    : undefined;
+  if (!Array.isArray(view?.changes)) throw new KitRefusal("kit_sync_rejected", "enumerate");
+  return new Map(
+    view.changes
+      .filter((change) => typeof change?.provenance === "string")
+      .map((change) => [change.path, change]),
+  );
+}
+
+async function acceptBatch(session, options, state, outcome, signal, pending = null) {
   const authority = state.authorities.find((entry) => entry.authority === outcome.authority);
   if (authority === undefined) throw new KitRefusal("kit_sync_rejected", outcome.authority);
   const reached = changePosition(outcome, "batch");
   const recorded = new Map(authority.files.map((file) => [file.path, file]));
   const predicted = predictedReplica(authority, pending);
+  const provenance = (outcome.contents ?? []).some((file) => typeof file?.content === "string")
+    ? await servedProvenance(session, options, state, authority, signal)
+    : new Map();
   for (const file of removalsFirst(outcome.contents ?? [], (file) => file?.content === null)) {
     const relative = relativeTo(authority.path, file.path);
     const destination = locate(options.replica, authority.path, relative);
@@ -340,6 +369,10 @@ async function acceptBatch(options, state, outcome, signal, pending = null) {
       sha256: "",
       content: accepted,
     });
+    const served = provenance.get(relative);
+    if (served !== undefined && served.revision === file.revision) {
+      await writeSidecar(options, authority, recorded, relative, served, signal);
+    }
   }
   authority.files = [...recorded.values()];
   Object.assign(authority, reached);
@@ -351,16 +384,65 @@ function sameBody(left, right) {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
+function contentMap(authority) {
+  return Object.fromEntries(authority.files.map((file) => [file.path, file.content]));
+}
+
+async function pullConfirmed(session, options, state, signal) {
+  const enumeration = await replicaDoor(
+    session,
+    options,
+    state,
+    KIT_DOOR_ENUMERATE_PATH,
+    { prefixes: state.prefixes, positions: positionsOf(state) },
+    signal,
+  );
+  return applyEnumeration(options, state, enumeration, signal);
+}
+
+async function settleExpired(session, options, state, pending, signal) {
+  const authority = authorityFor(state, pending.body.changes[0].path);
+  const predicted = predictedReplica(authority, pending);
+  const before = contentMap(authority);
+  await pullConfirmed(session, options, state, signal);
+  const confirmed = contentMap(authority);
+  const touched = [...new Set([...Object.keys(before), ...Object.keys(predicted)])]
+    .filter((path) => before[path] !== predicted[path])
+    .sort();
+  const landed = touched.length > 0 && touched.every((path) => confirmed[path] === predicted[path]);
+  await clearPending(options.directory, state.directory);
+  if (!landed) {
+    return { pending, accepted: await sendBatch(session, options, state, pending.body.changes, signal) };
+  }
+  const recorded = new Map(authority.files.map((file) => [file.path, file]));
+  return {
+    pending,
+    accepted: {
+      authority: authority.authority,
+      position: authority.position,
+      log_epoch: authority.log_epoch,
+      contents: touched.map((path) => ({
+        path: housePath(authority.path, path),
+        content: recorded.get(path)?.content ?? null,
+        revision: recorded.get(path)?.revision ?? null,
+      })),
+    },
+  };
+}
+
 async function recoverPending(session, options, state, signal) {
   const pending = await readPending(options.directory, state.directory);
   if (pending === null) return null;
   try {
     const outcome = await replicaDoor(session, options, state, pending.path, pending.body, signal);
-    const accepted = await acceptBatch(options, state, outcome, signal, pending);
+    const accepted = await acceptBatch(session, options, state, outcome, signal, pending);
     await clearPending(options.directory, state.directory);
     return { pending, accepted };
   } catch (error) {
     if (uncertainTransport(error)) throw error;
+    if (error.code === "operation_expired") {
+      return settleExpired(session, options, state, pending, signal);
+    }
     await clearPending(options.directory, state.directory);
     throw error;
   }
@@ -396,7 +478,7 @@ async function sendBatch(session, options, state, changes, signal) {
     );
     try {
       const outcome = await replicaDoor(session, options, state, KIT_DOOR_BATCH_PATH, body, signal);
-      last = await acceptBatch(options, state, outcome, signal);
+      last = await acceptBatch(session, options, state, outcome, signal);
       await clearPending(options.directory, state.directory);
     } catch (error) {
       if (uncertainTransport(error)) throw error;
@@ -441,16 +523,7 @@ export async function bootstrap(options, dependencies = {}) {
 
 export async function pull(options, dependencies = {}) {
   return withSession(options, dependencies, async (session, signal) => {
-    const state = await loadState(options);
-    const enumeration = await replicaDoor(
-      session,
-      options,
-      state,
-      KIT_DOOR_ENUMERATE_PATH,
-      { prefixes: state.prefixes, positions: positionsOf(state) },
-      signal,
-    );
-    const next = await applyEnumeration(options, state, enumeration, signal);
+    const next = await pullConfirmed(session, options, await loadState(options), signal);
     return { positions: positionsOf(next) };
   });
 }

package/src/tasks.js

@@ -24,6 +24,23 @@ export function coalescedTask(signal, fail, work) {
   return { trigger, idle: () => task === null, settled: () => task };
 }
 
+export function orderedTask(signal, fail, work) {
+  let task = null;
+  const push = (...args) => {
+    const next = (task ?? Promise.resolve())
+      .then(() => (signal.aborted ? undefined : work(...args)))
+      .catch((error) => {
+        if (signal.aborted) return;
+        fail(error);
+      });
+    task = next;
+    void next.then(() => {
+      if (task === next) task = null;
+    });
+  };
+  return { push, idle: () => task === null, settled: () => task };
+}
+
 export function residentWake() {
   let pending = false;
   let release = null;

package/src/worker.js

@@ -22,12 +22,13 @@ import { inheritedEnvironment } from "./command.js";
 import { sourceEntries } from "./google/entries.js";
 import { watchKitWork } from "./kit-work-stream.js";
 import { finalPlan } from "./plan.js";
-import { coalescedTask, residentWake } from "./tasks.js";
+import { coalescedTask, orderedTask, residentWake } from "./tasks.js";
 import {
   applyWorkingCopies,
   deliverWorkingCopies,
   ownerCaller,
   pushWorkingCopy,
+  receiveWorkingCopyEntries,
   recordIndexChange,
   uploadedPaths,
   workingCopyPaths,
@@ -48,7 +49,7 @@ import {
   WORKING_COPY_PUSH_METHOD,
   WORKING_COPY_UPLOAD_COMMAND,
 } from "./contract.js";
-import { EpochReportRequired, formatCommandError, houseFailed, KitRefusal } from "./refusal.js";
+import { EpochReportRequired, formatCommandError, houseAnswered, houseFailed, KitRefusal } from "./refusal.js";
 import {
   acceptAssistantText,
   acquireCommands,
@@ -227,7 +228,21 @@ async function completeOwnerStop(context, bound, requestedAt) {
   return { destroyed, confirmed: true, failure };
 }
 
-async function settleReported(context, bound) {
+const REPORT_LATER = ["conversation_file_send_pending", "environment_control_lease_rejected", "operation_id_invalid"];
+
+const REPORT_REISSUED = ["operation_expired", "position_expired"];
+
+function reportLater(refusal) {
+  const retryable = refusal.payload?.error?.retryable;
+  return (
+    !houseAnswered(refusal) ||
+    retryable === true ||
+    REPORT_LATER.includes(refusal.code) ||
+    ([429, 502, 503].includes(refusal.status) && retryable === undefined)
+  );
+}
+
+async function settleReported(context, bound, retain) {
   try {
     await reportRunOutcome(context.session, bound.run, bound.reported, bound.plan);
     return { settled: true, failure: null };
@@ -235,14 +250,22 @@ async function settleReported(context, bound) {
     if (undecided(context, refusal)) return { settled: false, failure: null };
     if (!(refusal instanceof KitRefusal)) throw refusal;
     if (refusal.code === "worker_run_settled") return { settled: true, failure: null };
-    return { settled: false, failure: { code: refusal.code, detail: refusal.message } };
+    const failure = { code: refusal.code, detail: refusal.message };
+    if (REPORT_REISSUED.includes(refusal.code)) {
+      bound.reported = { ...bound.reported, operation: operationId() };
+      await retain(bound);
+      return { settled: false, failure };
+    }
+    if (reportLater(refusal)) return { settled: false, failure };
+    reported(`run ${bound.run} outcome refused: ${refusal.code}`);
+    return { settled: true, failure };
   }
 }
 
 async function reportTerminalState(context, bound, report) {
   const settling = { ...bound, reported: { operation: operationId(), ...report } };
   await writeBinding(context.directory, settling);
-  const settled = await settleReported(context, settling);
+  const settled = await settleReported(context, settling, (held) => writeBinding(context.directory, held));
   if (settled.settled) await removeBinding(context.directory, settling.tmux);
   return { ...settled, reported: settling.reported };
 }
@@ -482,22 +505,35 @@ function stoppedReport(bound) {
 
 async function settleStopped(context, bound) {
   const { stopped } = bound;
-  const unresolved = (refused) => ({ failure: stopped.failure, refused, settled: false });
+  const unresolved = (refused) => ({ failure: stopped.failure, reported: bound.reported, refused, settled: false });
   if (bound.sealed !== null) {
     const refused = await dispatchSeal(context, bound);
     if (refused !== null) return unresolved(refused);
   }
-  let failure = stopped.failure;
-  try {
-    await observeSessionStop(context.session, bound.session, stopped.textAccepted, bound.plan);
-  } catch (refusal) {
-    if (undecided(context, refusal)) return unresolved(null);
-    if (!(refusal instanceof KitRefusal) || refusal.code !== "conversation_final_text_pending") throw refusal;
-    failure ??= { code: refusal.code, detail: refusal.message };
-    await observeSessionStop(context.session, bound.session, false, bound.plan);
-  }
   const report = stoppedReport(bound);
+  if (report !== null && bound.reported === null) {
+    bound.reported = { operation: operationId(), ...report };
+    await writeBinding(context.directory, bound);
+  }
   if (report !== null) await removeContinuation(context.directory, bound.run);
+  let failure = stopped.failure;
+  const observe = async (textAccepted) => {
+    try {
+      await observeSessionStop(context.session, bound.session, textAccepted, bound.plan);
+      return null;
+    } catch (refusal) {
+      if (undecided(context, refusal)) return undefined;
+      if (!(refusal instanceof KitRefusal)) throw refusal;
+      return refusal;
+    }
+  };
+  let observed = await observe(stopped.textAccepted);
+  if (observed?.code === "conversation_final_text_pending") {
+    failure ??= { code: observed.code, detail: observed.message };
+    observed = await observe(false);
+  }
+  if (observed === undefined) return unresolved(null);
+  if (observed !== null && report === null) throw observed;
   try {
     await reportContinuation(context.session, bound.session, {
       providerContinuation: report === null,
@@ -505,17 +541,21 @@ async function settleStopped(context, bound) {
     });
   } catch (refusal) {
     if (undecided(context, refusal)) return unresolved(null);
-    if (!(refusal instanceof KitRefusal) || refusal.code !== "worker_run_settled") throw refusal;
-    await removeContinuation(context.directory, bound.run);
-    await removeBinding(context.directory, bound.tmux);
-    return { failure, refused: null, settled: true };
+    if (!(refusal instanceof KitRefusal)) throw refusal;
+    if (refusal.code === "worker_run_settled") {
+      await removeContinuation(context.directory, bound.run);
+      await removeBinding(context.directory, bound.tmux);
+      return { failure, refused: null, settled: true };
+    }
+    if (report === null) throw refusal;
   }
   if (report === null) {
     await removeBinding(context.directory, bound.tmux);
     return { failure, refused: null, settled: true };
   }
-  const settled = await reportTerminalState(context, bound, report);
-  return { failure, reported: settled.reported, refused: settled.failure, settled: settled.settled };
+  const settled = await settleReported(context, bound, (held) => writeBinding(context.directory, held));
+  if (settled.settled) await removeBinding(context.directory, bound.tmux);
+  return { failure, reported: bound.reported, refused: settled.failure, settled: settled.settled };
 }
 
 function assignmentRoute(context, assignment) {
@@ -601,7 +641,7 @@ async function settleRefused(context, command, failure) {
     reported: { operation: operationId(), ...failedReport(failure) },
   };
   await writeSettlement(context.directory, settling);
-  const settled = await settleReported(context, settling);
+  const settled = await settleReported(context, settling, (held) => writeSettlement(context.directory, held));
   if (settled.settled) await removeSettlement(context.directory, settling.run);
   return { run: settling.run, session: settling.session, tmux: null, assistant: [],
     failure, reported: settling.reported, refused: settled.failure,
@@ -697,7 +737,7 @@ async function reconcile(context) {
   const stopped = [];
   const unresolved = [];
   for (const settlement of await readSettlements(context.directory)) {
-    const settled = await settleReported(context, settlement);
+    const settled = await settleReported(context, settlement, (held) => writeSettlement(context.directory, held));
     if (settled.settled) await removeSettlement(context.directory, settlement.run);
     else unresolved.push(unresolvedRun(settlement, settled.failure));
   }
@@ -706,17 +746,17 @@ async function reconcile(context) {
   const commands = (await pendingCommands(context))?.stops ?? [];
   const carried = [];
   for (const binding of bindings) {
-    if (binding.reported !== null) {
-      const settled = await settleReported(context, binding);
-      if (settled.settled) await removeBinding(context.directory, binding.tmux);
-      else unresolved.push(unresolvedRun(binding, settled.failure));
-      continue;
-    }
     if (binding.stopped !== null) {
       const settled = await settleStopped(context, binding);
       if (!settled.settled) unresolved.push(unresolvedRun(binding, settled.refused));
       continue;
     }
+    if (binding.reported !== null) {
+      const settled = await settleReported(context, binding, (held) => writeBinding(context.directory, held));
+      if (settled.settled) await removeBinding(context.directory, binding.tmux);
+      else unresolved.push(unresolvedRun(binding, settled.failure));
+      continue;
+    }
     const command = commands.find((pending) => pending.run === binding.run) ?? null;
     const requestedAt = binding.ownerStop ?? command?.requestedAt ?? null;
     if (requestedAt === null) {
@@ -958,7 +998,7 @@ async function reportedWorkingCopies(act, context, signal) {
   return outcome;
 }
 
-function residentUpdate(context, wake) {
+export function residentUpdate(context, wake) {
   let requested = existsSync(updateDrain(context.directory));
   let ready = null;
   const waiting = [];
@@ -967,16 +1007,27 @@ function residentUpdate(context, wake) {
       return requested;
     },
     async request(serving) {
+      let heard = null;
+      let hear;
+      const answered = new Promise((resolve) => {
+        hear = (answer) => {
+          heard = answer;
+          resolve(answer);
+        };
+      });
+      waiting.push(hear);
       if (!requested) {
         requested = true;
         await writeText(updateDrain(context.directory), "");
       }
       wake.notify();
       const sessions = await heldSessions(context);
+      if (heard !== null) return heard;
+      if (ready === null && !serving && sessions.length === 0) return answered;
+      waiting.splice(waiting.indexOf(hear), 1);
       if (ready !== null) return ready;
       if (serving) return { ready: false, sessions, serving };
-      if (sessions.length > 0) return { ready: false, sessions };
-      return new Promise((resolve) => waiting.push(resolve));
+      return { ready: false, sessions };
     },
     answer(answer) {
       for (const resolve of waiting.splice(0)) resolve(answer);
@@ -1094,12 +1145,12 @@ export async function runResident(options, dependencies = {}) {
       context.startLogins(needsLogin);
     });
     const unavailable = (error) => reported(`working copies unavailable: ${error?.message ?? error}`);
-    const changed = () => {
+    const redeliver = () => {
       if (!update.requested) deliveries.trigger();
     };
     const behind = (outcome) => {
       if (!outcome.behind) return;
-      controlSleep(interval, signal).then(changed, () => {});
+      controlSleep(interval, signal).then(redeliver, () => {});
     };
     const copies = coalescedTask(signal, unavailable, async () =>
       behind(await reportedWorkingCopies(applyWorkingCopies, context, signal)),
@@ -1107,6 +1158,12 @@ export async function runResident(options, dependencies = {}) {
     const deliveries = coalescedTask(signal, unavailable, async () =>
       behind(await reportedWorkingCopies(deliverWorkingCopies, context, signal)),
     );
+    const entries = orderedTask(signal, unavailable, async (frame, since) => {
+      if (!(await receiveWorkingCopyEntries(context, frame, since, signal))) redeliver();
+    });
+    const changed = (frame, since) => {
+      if (!update.requested) entries.push(frame, since);
+    };
     sources = sourceEntries({
       session: context.session,
       directory: context.directory,
@@ -1199,6 +1256,7 @@ export async function runResident(options, dependencies = {}) {
               agentRefresh.idle() &&
               copies.idle() &&
               deliveries.idle() &&
+              entries.idle() &&
               sources.idle())
           ) {
             return;
@@ -1212,6 +1270,7 @@ export async function runResident(options, dependencies = {}) {
       await agentRefresh.settled();
       await copies.settled();
       await deliveries.settled();
+      await entries.settled();
       await sources.settled();
       for (const running of logins.values()) running.controller.abort();
       await Promise.all([...logins.values()].map((running) => running.task));

package/src/working-copy.js

@@ -561,6 +561,55 @@ export async function deliverWorkingCopies(context, signal) {
     : deliveredOutcome(delivered.refused, delivered.behind);
 }
 
+function streamChange(entry) {
+  if (entry?.kind === "removed") return { path: entry.path, removed: true };
+  return { path: entry?.path, revision: entry?.revision, content: entry?.text, provenance: entry?.provenance };
+}
+
+function followsOn(copy, frame, since, changes) {
+  const { received } = copy;
+  return (
+    since !== null &&
+    received.log_epoch === frame.log_epoch &&
+    BigInt(received.position) >= BigInt(since) &&
+    !unreadableChanges(changes)
+  );
+}
+
+async function carriedEntries(context, path, frame, since, signal) {
+  const copy = await readCopy(path);
+  if (!copy?.active) return true;
+  const { received } = copy;
+  if (received.log_epoch === frame.log_epoch && BigInt(frame.position) <= BigInt(received.position)) return true;
+  const homes = copy.scope === "private" ? WORKING_COPY_PRIVATE_HOMES : WORKING_COPY_ROOM_HOMES;
+  const changes = frame.entries
+    .map(streamChange)
+    .filter((change) => typeof change.path !== "string" || homes.some((home) => covers(change.path, home)));
+  if (!followsOn(copy, frame, since, changes)) return false;
+  const view = { changes, position: frame.position, log_epoch: frame.log_epoch };
+  const authority = { operations: { write: received.declared.write }, protected_paths: received.declared.protected };
+  await writeCopy(context.directory, await incorporated(copy, view, authority, signal), signal);
+  return true;
+}
+
+export async function receiveWorkingCopyEntries(context, frame, since, signal) {
+  if (
+    typeof frame.authority !== "string" ||
+    typeof frame.log_epoch !== "string" ||
+    !/^[0-9]+$/.test(frame.position) ||
+    !Array.isArray(frame.entries) ||
+    (since !== null && !/^[0-9]+$/.test(since))
+  ) {
+    return false;
+  }
+  const copy = (await heldCopies(context.directory)).find(
+    (held) => held.active && held.room_ref === frame.authority,
+  );
+  if (copy === undefined) return true;
+  const path = copyPath(context.directory, copy);
+  return exclusively(path, () => carriedEntries(context, path, frame, since, signal));
+}
+
 export async function applyWorkingCopies(context, signal) {
   const selected = (await savedSelection(context.session, signal)).filter(
     (scope) => scope.kind === "private" || scope.handle !== null,
@@ -913,6 +962,14 @@ export function uploadedPaths(changes) {
   return [...pushedPaths(changes)].sort();
 }
 
+function unreadableChanges(changes) {
+  return changes.some(
+    (change) =>
+      typeof change?.path !== "string" ||
+      (change.removed !== true && (typeof change.content !== "string" || typeof change.revision !== "string")),
+  );
+}
+
 async function enumerated(context, copy, since, signal) {
   const answer = await door(
     context.session,
@@ -925,11 +982,7 @@ async function enumerated(context, copy, since, signal) {
     !Array.isArray(view?.changes) ||
     typeof view.position !== "string" ||
     typeof view.log_epoch !== "string" ||
-    view.changes.some(
-      (change) =>
-        typeof change?.path !== "string" ||
-        (change.removed !== true && (typeof change.content !== "string" || typeof change.revision !== "string")),
-    )
+    unreadableChanges(view.changes)
   ) {
     throw rejected("enumerate");
   }