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

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.31/connect-linux.sh)
 ```
 
 The bootstrap first establishes Docker Engine from what it observes on the
@@ -968,7 +968,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 +1070,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
@@ -1548,7 +1548,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 +1566,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 +2108,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/bootstrap.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "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.31/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.31/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.31",
   "license": "MIT",
   "repository": {
     "type": "git",

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/worker.js

@@ -958,7 +958,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 +967,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);