feat(chat-swarm): deterministic worker continuation epoch transfer (#120)

.github/workflows/ci.yml

@@ -11,6 +11,21 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  diff-check:
+    name: Diff check (PR)
+    if: github.event_name == 'pull_request'
+    runs-on: macos-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Git diff check
+        run: git diff --check "${{ github.event.pull_request.base.sha }}...HEAD"
+
   smoke:
     name: Smoke (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
@@ -64,6 +79,45 @@ jobs:
       - name: Doctor
         run: node dist/cli.js doctor
 
+  chat-swarm-continuation:
+    name: Chat Swarm continuation ${{ matrix.name }} (macOS)
+    runs-on: macos-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: coordinator
+            file: src/chat-swarm-continuation-coordinator.test.ts
+          - name: durable-store
+            file: src/chat-swarm-continuation-store.test.ts
+          - name: restart-fence
+            file: src/chat-swarm-continuation-restart-fence.test.ts
+          - name: retired-carrier
+            file: src/chat-swarm-continuation-stale-carrier.test.ts
+          - name: terminal-replay
+            file: src/chat-swarm-continuation-terminal-replay.test.ts
+          - name: corruption-fence
+            file: src/chat-swarm-continuation-corruption-fence.test.ts
+          - name: aggregate-domain
+            file: src/chat-swarm-continuation-domain.test.ts
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run focused continuation test
+        run: npx tsx ${{ matrix.file }}
+
   local-agent-sessions:
     name: Local agent sessions (macOS)
     runs-on: macos-latest

package.json

@@ -32,7 +32,7 @@
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "test:node-pty-permissions": "node --import tsx --test src/node-pty-postinstall.test.ts",
     "start": "node dist/cli.js serve",
-     "test": "npm run test:node-pty-permissions && npm run test:carrier-binding && tsx src/coordination-reader-loader.test.ts && tsx src/control-plane-ownership.test.ts && tsx src/control-plane-handoff.test.ts && tsx src/control-plane-continuation.test.ts && tsx src/deployment-convergence.test.ts && tsx src/current-completion-matrix.test.ts && tsx src/control-plane-consumer.test.ts && tsx src/local-agent-cline-catalog.test.ts && tsx src/chat-swarm-contract.test.ts && tsx src/chat-swarm-store.test.ts && tsx src/chat-swarm-runtime-owner.test.ts && tsx src/local-agent-opencode-mcp-catalog.test.ts && tsx src/chat-swarm-coordinator.test.ts && tsx src/chat-swarm-peer-runtime.test.ts && tsx src/chat-swarm-tools.test.ts && tsx src/chat-swarm-lifecycle.test.ts && tsx src/chat-swarm-carrier.test.ts && tsx src/chat-swarm-peer-admission.test.ts && tsx src/chat-swarm-task-ledger.test.ts && tsx src/git-worktrees.test.ts && tsx src/execution-protocol.test.ts && tsx src/durable-operations-ci.test.ts && tsx src/git-candidate.test.ts && tsx src/config.test.ts && tsx src/onboarding.test.ts && tsx src/cli-workspace.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions-ci.test.ts && tsx src/codex-goal-sessions-ci.test.ts && tsx src/mcp-sessions.test.ts && tsx src/cutover-state.test.ts && tsx src/cutover-state-recovery-guard.test.ts && tsx src/cutover-build-ready.test.ts && tsx src/cutover-orchestration.test.ts && tsx src/mcp-cutover.test.ts && tsx src/cutover-restart.test.ts && tsx src/cutover-http.test.ts && tsx src/cutover-recovery.test.ts && tsx src/cutover-binding-repair.test.ts && tsx src/capability-manifest.test.ts && tsx src/server-shutdown.test.ts && tsx src/codex-runtime.test.ts && tsx src/local-agent-config.test.ts && tsx src/local-agent-catalog.test.ts && tsx src/local-agent-presentation.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-daemon-lifecycle.test.ts && tsx src/local-agent-daemon-protocol.test.ts && tsx src/local-agent-daemon.test.ts && tsx src/local-agent-codex.test.ts && tsx src/local-agent-opencode.test.ts && tsx src/local-agent-opencode-catalog.test.ts && tsx src/local-agent-acp.test.ts && tsx src/local-agent-grok.test.ts && tsx src/local-agent-pi-sandbox.test.ts && tsx src/local-agent-pi.test.ts && tsx src/local-agent-claude.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-profile-source.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-toolchains.test.ts && tsx src/local-agent-idle-policy.test.ts && tsx src/local-agent-capacity.test.ts && tsx src/local-agent-execution-contract.test.ts && tsx src/local-agent-continuation.test.ts && tsx src/provider-scratch.test.ts && tsx src/git-integration-ci.test.ts && tsx src/repository-intelligence.test.ts && tsx src/local-agent-store.test.ts && tsx src/local-agent-manager.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/conversation-isolation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server-ci.test.ts && tsx src/oauth-store.test.ts && tsx src/cli-ci.test.ts && tsx src/oauth-json-and-child-reap.test.ts && tsx src/local-agent-errors.test.ts && tsx src/provider-output-redaction.test.ts && tsx src/host-operation-policy.test.ts && tsx src/host-operations.test.ts && tsx src/host-operations-http.test.ts",
+    "test": "npm run test:node-pty-permissions && npm run test:carrier-binding && tsx src/coordination-reader-loader.test.ts && tsx src/control-plane-ownership.test.ts && tsx src/control-plane-handoff.test.ts && tsx src/control-plane-continuation.test.ts && tsx src/deployment-convergence.test.ts && tsx src/current-completion-matrix.test.ts && tsx src/control-plane-consumer.test.ts && tsx src/local-agent-cline-catalog.test.ts && tsx src/chat-swarm-contract.test.ts && tsx src/chat-swarm-store.test.ts && tsx src/chat-swarm-runtime-owner.test.ts && tsx src/local-agent-opencode-mcp-catalog.test.ts && tsx src/chat-swarm-coordinator.test.ts && tsx src/chat-swarm-peer-runtime.test.ts && tsx src/chat-swarm-tools.test.ts && tsx src/chat-swarm-lifecycle.test.ts && tsx src/chat-swarm-carrier.test.ts && tsx src/chat-swarm-continuation-domain.test.ts && tsx src/chat-swarm-continuation-store.test.ts && tsx src/chat-swarm-peer-admission.test.ts && tsx src/chat-swarm-task-ledger.test.ts && tsx src/git-worktrees.test.ts && tsx src/execution-protocol.test.ts && tsx src/durable-operations-ci.test.ts && tsx src/git-candidate.test.ts && tsx src/config.test.ts && tsx src/onboarding.test.ts && tsx src/cli-workspace.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions-ci.test.ts && tsx src/codex-goal-sessions-ci.test.ts && tsx src/mcp-sessions.test.ts && tsx src/cutover-state.test.ts && tsx src/cutover-state-recovery-guard.test.ts && tsx src/cutover-build-ready.test.ts && tsx src/cutover-orchestration.test.ts && tsx src/mcp-cutover.test.ts && tsx src/cutover-restart.test.ts && tsx src/cutover-http.test.ts && tsx src/cutover-recovery.test.ts && tsx src/cutover-binding-repair.test.ts && tsx src/capability-manifest.test.ts && tsx src/server-shutdown.test.ts && tsx src/codex-runtime.test.ts && tsx src/local-agent-config.test.ts && tsx src/local-agent-catalog.test.ts && tsx src/local-agent-presentation.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-daemon-lifecycle.test.ts && tsx src/local-agent-daemon-protocol.test.ts && tsx src/local-agent-daemon.test.ts && tsx src/local-agent-codex.test.ts && tsx src/local-agent-opencode.test.ts && tsx src/local-agent-opencode-catalog.test.ts && tsx src/local-agent-acp.test.ts && tsx src/local-agent-grok.test.ts && tsx src/local-agent-pi-sandbox.test.ts && tsx src/local-agent-pi.test.ts && tsx src/local-agent-claude.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-profile-source.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-toolchains.test.ts && tsx src/local-agent-idle-policy.test.ts && tsx src/local-agent-capacity.test.ts && tsx src/local-agent-execution-contract.test.ts && tsx src/local-agent-continuation.test.ts && tsx src/provider-scratch.test.ts && tsx src/git-integration-ci.test.ts && tsx src/repository-intelligence.test.ts && tsx src/local-agent-store.test.ts && tsx src/local-agent-manager.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/conversation-isolation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server-ci.test.ts && tsx src/oauth-store.test.ts && tsx src/cli-ci.test.ts && tsx src/oauth-json-and-child-reap.test.ts && tsx src/local-agent-errors.test.ts && tsx src/provider-output-redaction.test.ts && tsx src/host-operation-policy.test.ts && tsx src/host-operations.test.ts && tsx src/host-operations-http.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:carrier-binding": "tsx src/carrier-binding.test.ts && tsx src/carrier-binding-http.test.ts",
     "test:local-agent-sessions": "node --import tsx --test src/local-agent-sessions.test.ts"
@@ -85,4 +85,4 @@
   "optionalDependencies": {
     "node-pty": "1.1.0"
   }
-}
+}

src/chat-swarm-continuation-contract.ts

@@ -0,0 +1,43 @@
+export const CHAT_SWARM_CONTINUATION_STATES = [
+  "PENDING",
+  "APPROVED",
+  "EXPIRED",
+  "SUPERSEDED",
+  "RECONCILE_REQUIRED",
+] as const;
+
+export type ChatSwarmContinuationState = (typeof CHAT_SWARM_CONTINUATION_STATES)[number];
+
+export interface ChatSwarmContinuationRequest {
+  id: string;
+  swarmId: string;
+  workerId: string;
+  attemptKey: string;
+  requestHash: string;
+  sourceEpoch: number;
+  targetEpoch: number;
+  sourceCarrierFingerprint: string;
+  targetCarrierFingerprint: string;
+  checkpointHash: string;
+  ttlSeconds: number;
+  version: number;
+  status: ChatSwarmContinuationState;
+  requestedAt: string;
+  expiresAt: string;
+  approvedAt?: string;
+}
+
+export interface CreateContinuationRequestInput {
+  swarmId: string;
+  workerId: string;
+  attemptKey: string;
+  sourceEpoch: number;
+  ttlSeconds?: number;
+}
+
+export interface ApproveContinuationRequestInput {
+  swarmId: string;
+  requestId: string;
+  expectedRequestVersion: number;
+  expectedSwarmVersion: number;
+}

src/chat-swarm-continuation-coordinator.test.ts

@@ -0,0 +1,147 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { ChatSwarmError } from "./chat-swarm-contract.js";
+import { ChatSwarmContinuationCoordinator } from "./chat-swarm-continuation-coordinator.js";
+import { ChatSwarmContinuationStore } from "./chat-swarm-continuation-store.js";
+import { ChatSwarmCoordinator } from "./chat-swarm-coordinator.js";
+import { ChatSwarmStore } from "./chat-swarm-store.js";
+
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), "swarm-continuation-coordinator-"));
+  const swarmStore = new ChatSwarmStore(root);
+  const swarmCoordinator = new ChatSwarmCoordinator(swarmStore);
+  const continuationStore = new ChatSwarmContinuationStore(root);
+  const continuation = new ChatSwarmContinuationCoordinator(continuationStore, swarmCoordinator);
+  const ownerMeta = { "openai/session": "continuation-owner" };
+  const attackerMeta = { "openai/session": "continuation-attacker" };
+  const sourceMeta = { "openai/conversation_id": "continuation-source" };
+  const targetMeta = { "openai/conversation_id": "continuation-target" };
+  const otherTargetMeta = { "openai/conversation_id": "continuation-other-target" };
+  const swarm = swarmCoordinator.createSwarm(ownerMeta, { workerLimit: 3, metadata: { test: true } });
+  const worker = swarmCoordinator.joinWorker(sourceMeta, swarm.id, {
+    label: "Worker-01",
+    runtimeKind: "mcp_peer",
+  });
+  swarmCoordinator.checkpoint(
+    sourceMeta,
+    worker.id,
+    0,
+    new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+    { summary: "safe checkpoint" },
+  );
+  return {
+    root,
+    swarmStore,
+    continuationStore,
+    continuation,
+    ownerMeta,
+    attackerMeta,
+    sourceMeta,
+    targetMeta,
+    otherTargetMeta,
+    swarm,
+    worker,
+  };
+}
+
+function cleanup(f: ReturnType<typeof fixture>) {
+  f.continuationStore.close();
+  f.swarmStore.close();
+  rmSync(f.root, { recursive: true, force: true });
+}
+
+test("target request identity comes from authenticated metadata and exact target can read it", () => {
+  const f = fixture();
+  try {
+    const created = f.continuation.request(f.targetMeta, {
+      swarmId: f.swarm.id,
+      workerId: f.worker.id,
+      attemptKey: "target-bound-1",
+      sourceEpoch: 0,
+    });
+    assert.equal(created.created, true);
+    assert.equal(f.continuation.targetStatus(f.targetMeta, f.swarm.id)?.id, created.request.id);
+    assert.equal(f.continuation.targetStatus(f.otherTargetMeta, f.swarm.id), undefined);
+
+    assert.throws(
+      () => f.continuation.request(f.sourceMeta, {
+        swarmId: f.swarm.id,
+        workerId: f.worker.id,
+        attemptKey: "source-cannot-replace-itself",
+        sourceEpoch: 0,
+      }),
+      (error: unknown) => error instanceof ChatSwarmError && error.code === "INVALID_INPUT",
+    );
+  } finally {
+    cleanup(f);
+  }
+});
+
+test("only exact owner may approve, including idempotent approved readback", () => {
+  const f = fixture();
+  try {
+    const created = f.continuation.request(f.targetMeta, {
+      swarmId: f.swarm.id,
+      workerId: f.worker.id,
+      attemptKey: "owner-bound-1",
+      sourceEpoch: 0,
+    });
+
+    assert.throws(
+      () => f.continuation.approve(f.attackerMeta, {
+        swarmId: f.swarm.id,
+        requestId: created.request.id,
+        expectedRequestVersion: 1,
+        expectedSwarmVersion: 1,
+      }),
+      (error: unknown) => error instanceof ChatSwarmError && error.code === "OWNERSHIP_CONFLICT",
+    );
+
+    const approved = f.continuation.approve(f.ownerMeta, {
+      swarmId: f.swarm.id,
+      requestId: created.request.id,
+      expectedRequestVersion: 1,
+      expectedSwarmVersion: 1,
+    });
+    assert.equal(approved.status, "APPROVED");
+
+    assert.throws(
+      () => f.continuation.approve(f.attackerMeta, {
+        swarmId: f.swarm.id,
+        requestId: created.request.id,
+        expectedRequestVersion: 1,
+        expectedSwarmVersion: 1,
+      }),
+      (error: unknown) => error instanceof ChatSwarmError && error.code === "OWNERSHIP_CONFLICT",
+    );
+  } finally {
+    cleanup(f);
+  }
+});
+
+test("same owner cannot reconcile a continuation through a different swarm id", () => {
+  const f = fixture();
+  try {
+    const created = f.continuation.request(f.targetMeta, {
+      swarmId: f.swarm.id,
+      workerId: f.worker.id,
+      attemptKey: "cross-swarm-reconcile",
+      sourceEpoch: 0,
+    });
+    const otherSwarm = f.continuation.swarmCoordinator.createSwarm(f.ownerMeta, {
+      workerLimit: 1,
+      metadata: { test: "other-swarm" },
+    });
+
+    assert.throws(
+      () => f.continuation.reconcileNoEffect(f.ownerMeta, otherSwarm.id, created.request.id),
+      (error: unknown) => error instanceof ChatSwarmError && error.code === "OWNERSHIP_CONFLICT",
+    );
+    assert.equal(f.continuationStore.getRequest(created.request.id)?.status, "PENDING");
+  } finally {
+    cleanup(f);
+  }
+});

src/chat-swarm-continuation-coordinator.ts

@@ -0,0 +1,56 @@
+import { ChatSwarmError } from "./chat-swarm-contract.js";
+import type {
+  ApproveContinuationRequestInput,
+  ChatSwarmContinuationRequest,
+  CreateContinuationRequestInput,
+} from "./chat-swarm-continuation-contract.js";
+import { ChatSwarmContinuationStore } from "./chat-swarm-continuation-store.js";
+import { ChatSwarmCoordinator } from "./chat-swarm-coordinator.js";
+import { resolveChatSwarmIdentity } from "./request-meta.js";
+
+export class ChatSwarmContinuationCoordinator {
+  constructor(
+    readonly store: ChatSwarmContinuationStore,
+    readonly swarmCoordinator: ChatSwarmCoordinator,
+  ) {}
+
+  request(
+    meta: unknown,
+    input: CreateContinuationRequestInput,
+  ): { request: ChatSwarmContinuationRequest; created: boolean } {
+    const identity = resolveChatSwarmIdentity(meta);
+    return this.store.createRequest(identity.fingerprint, input);
+  }
+
+  targetStatus(meta: unknown, swarmId: string): ChatSwarmContinuationRequest | undefined {
+    const identity = resolveChatSwarmIdentity(meta);
+    return this.store.getLatestForTarget(swarmId, identity.fingerprint);
+  }
+
+  approve(meta: unknown, input: ApproveContinuationRequestInput): ChatSwarmContinuationRequest {
+    this.swarmCoordinator.assertOwnerForLifecycle(meta, input.swarmId);
+    const identity = resolveChatSwarmIdentity(meta);
+    return this.store.approveRequest(identity.fingerprint, input);
+  }
+
+  reconcileNoEffect(
+    meta: unknown,
+    swarmId: string,
+    requestId: string,
+  ): ChatSwarmContinuationRequest {
+    this.swarmCoordinator.assertOwnerForLifecycle(meta, swarmId);
+    const request = this.store.getRequest(requestId);
+    if (!request || request.swarmId !== swarmId) {
+      throw new ChatSwarmError(
+        "OWNERSHIP_CONFLICT",
+        "continuation request does not belong to asserted swarm",
+      );
+    }
+    const identity = resolveChatSwarmIdentity(meta);
+    return this.store.reconcileUnknownNoEffect(identity.fingerprint, requestId);
+  }
+
+  recoverAfterRestart(): number {
+    return this.store.recoverAfterRestart();
+  }
+}