borgmcp 2.0.1 → 2.0.2

package/docs/EXTRACTION_PROVENANCE.md

@@ -8,7 +8,7 @@ The extraction copied the monorepo's `client/src/` production boundary and top-l
 
 ## Deliberate Transformations
 
-- Replaced the monorepo dependency on `borgmcp-shared` with the exact audited registry release `borgmcp-shared@0.4.2` and a fresh standalone lockfile.
+- Replaced the monorepo dependency on `borgmcp-shared` with the exact audited registry release `borgmcp-shared@0.4.3` and a fresh standalone lockfile.
 - Replaced local template, role-section, drone-address, and log high-water-mark implementations with `borgmcp-shared` exports.
 - Removed monorepo-only website anti-drift tests and re-anchored remaining filesystem tests to this repository.
 - Removed consumer lifecycle hooks, parent-directory deployment scripts, minification, and private integration-environment configuration.
@@ -18,8 +18,9 @@ The extraction copied the monorepo's `client/src/` production boundary and top-l
   client-generated PENDING credential/retry tuple and capability-gated,
   repository-idempotent cube creation required for local dogfood.
 - Initially set the standalone package identity to `2.0.0`. Its immutable
-  lightweight release tag failed before packaging, so the reviewed recovery
-  identity is `2.0.1`; extraction and versioning do not authorize publication.
+  lightweight release tag failed before packaging. The reviewed `2.0.1`
+  recovery was published and registry-verified; the next candidate identity is
+  `2.0.2`. Extraction and versioning do not authorize publication.
 
 ## Review Holds
 
@@ -34,7 +35,8 @@ artifact reaches no hosted authority.
 Local enrollment now uses the reviewed client-generated credential/retry
 contract, with a pre-request `PENDING` record in the local 0600-permission seat
 store, exact-tuple ambiguous retry, and verified activation. The contract now
-resolves to the audited registry `borgmcp-shared@0.4.2`. The matching
-`borgmcp-server@0.1.7` release is published and registry-verified; client
-publication remains gated by reviewed `v2.0.1` source, a fresh annotated tag,
-and exact registry integrity and signature verification.
+resolves to the audited registry `borgmcp-shared@0.4.3`. The matching
+`borgmcp-server@0.1.7` release is published and registry-verified. Client
+`borgmcp@2.0.1` is published and registry-verified. Publication of the next
+candidate remains gated by reviewed `v2.0.2` source, a fresh annotated tag, and
+exact registry integrity and signature verification.

package/docs/LOCAL_SERVER.md

@@ -96,7 +96,7 @@ The default discovery endpoint is `https://127.0.0.1:7091`. Explicit `--host` va
 
 ## Release status
 
-This self-hosted path consumes the published `borgmcp-shared@0.4.2` v2 registry
+This self-hosted path consumes the published `borgmcp-shared@0.4.3` v2 registry
 release. The matching server owner-enrollment, cube-create, attach, restart, log,
 and SSE implementation must also pass the full process-level local dogfood gate.
 Until that gate opens the self-hosted path remains preview-only, and the client

package/docs/RELEASING.md

@@ -4,15 +4,24 @@ The GitHub Actions workflow publishes one immutable, reviewed `borgmcp` version
 from a protected annotated tag. The protected publish job uses npm Trusted
 Publishing; no long-lived npm token is stored or exposed.
 
-## Immutable Failed Release Evidence
+## Immutable Release Evidence
 
 The existing lightweight `v2.0.0` tag points to
 `90a078264f4d61c0140ad0a30357a4df42c34ab0`. Immutable workflow run
 `29693915689` rejected it at annotated-tag verification and failed before package
 creation or npm publication; the publish job was skipped and
 `borgmcp@2.0.0` remains absent from npm. Never delete, move, replace, reuse, or
-rerun that tag or run. Recovery uses the unused `v2.0.1` identity from a fresh
-reviewed protected-main commit and requires the complete release gate again.
+rerun that tag or run.
+
+The annotated `v2.0.1` tag object
+`def12ee40af665fc6c3af4873a7d566b3f844fc1` peels to protected-main commit
+`b30fc54a4d73bda98db4630864cca796c8923dd9`. Workflow run `29748931957`
+successfully published that exact source as `borgmcp@2.0.1`; the registry records
+integrity
+`sha512-Ah8IY2izZ774gYLKthRL9lfrV+JBk2o9HSlrWUplyZgoGqwVjVboHNon0hWWF5i/fObiCGikFOMY6qZ+vaeyCw==`.
+Never move, replace, reuse, or rerun that tag or workflow. The next candidate
+uses the unused `v2.0.2` identity from a fresh reviewed protected-main commit
+and requires the complete release gate again.
 
 ## Release Prerequisites
 
@@ -23,7 +32,7 @@ Before creating the release tag, independently verify all of these conditions:
 - the extraction review confirms no private backend secrets, deployment
   configuration, customer data, local state, or duplicated shared contracts
   entered the public package;
-- the exact audited registry dependency `borgmcp-shared@0.4.2` remains locked to
+- the exact audited registry dependency `borgmcp-shared@0.4.3` remains locked to
   its canonical tarball and integrity;
 - the client and matching server pass the complete local dogfood gate;
 - the selected stable client version is unused and the exact release commit is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "borgmcp-shared": "0.4.2",
+    "borgmcp-shared": "0.4.3",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
     "which": "^4.0.0"

package/src/codex-app-wake.ts

@@ -1,6 +1,12 @@
-import { getActiveCube, getCodexWakeTarget, setCodexWakeTarget } from './cubes.js';
+import {
+  getActiveCube,
+  getCodexWakeTarget,
+  setCodexWakeTarget,
+  type ActiveCube,
+} from './cubes.js';
 import { CodexAppServerClient } from './codex-app-server.js';
 import { checkCodexBridgeHealthy } from './codex-remote.js';
+import { hasPendingWakeActivity } from './remote-client.js';
 import {
   BORG_CODEX_REMOTE_WAKE_ENV,
   resolveSessionAgentKind,
@@ -176,6 +182,10 @@ export interface CodexWakeDeps {
   // WAKE_RETRY_MAX_ATTEMPTS); small values let tests prove the loop terminates
   // under a non-advancing clock without running thousands of iterations.
   maxAttempts?: number;
+  // client#76: token-free, non-mutating preflight for the periodic backstop.
+  // Per-entry and retry-drain paths do not use this: their pending obligation is
+  // already established by a concrete delivered/deferred event.
+  hasPendingWork?: (active: ActiveCube) => Promise<boolean>;
   // gh#861 finding 2: lease-ownership gate for the heartbeat tick — a lease-LOSING
   // duplicate child must NOT tick/inject (symmetry with the per-entry path, which
   // only fires inside an SSE session that holds the stream lease). Heartbeat-only;
@@ -403,16 +413,13 @@ async function runRetryDrainLoop(deps: CodexWakeDeps): Promise<void> {
 export const CODEX_HEARTBEAT_CADENCE_MS = 20 * 60_000;
 
 /**
- * gh#857 WI-2: one tick of the codex /loop-equivalent heartbeat — a periodic,
- * independent re-engagement that injects a borg_read-log (unread_only=true) DRAIN turn so an
- * idle codex drone re-syncs even if every per-entry wake was missed. SKIPS when a
- * delivery (per-entry wake, retry-drain, or a prior heartbeat) already landed
- * within the cadence window (shouldFireHeartbeat), so an active cube with flowing
- * wakes never gets a redundant injection. Unlike the per-entry path it does NOT
- * consult deliveredWakeKeys — the cadence gate is the throttle, and the static
- * drain prompt is intentionally re-delivered each idle window. Best-effort: a
- * mid-turn thread / transient error / unresolved target just skips this tick (the
- * next tick retries). Never throws.
+ * gh#857/client#76: one tick of the codex catch-up backstop. The cadence only
+ * initiates a token-free unread-state preflight; a DRAIN turn is injected when
+ * that authoritative scan finds real work that a per-entry wake missed. Recent
+ * delivery still suppresses redundant preflights. Unlike the per-entry path it
+ * does not consult deliveredWakeKeys because the unread cursor is authoritative.
+ * Best-effort: a failed preflight, mid-turn thread, transient error, or unresolved
+ * target skips this tick and lets the next cadence retry. Never throws.
  */
 export async function fireCodexHeartbeatTick(
   deps: CodexWakeDeps = {},
@@ -434,6 +441,11 @@ export async function fireCodexHeartbeatTick(
   try {
     const active = await (deps.getActiveCube ?? getActiveCube)();
     if (!active) return;
+    // Elapsed time alone must never cross the model boundary. Query the
+    // authoritative unread state without advancing its cursor; only then touch
+    // the app-server socket or resolve a thread.
+    const hasPendingWork = deps.hasPendingWork ?? hasPendingWakeActivity;
+    if (!(await hasPendingWork(active))) return;
     const resolved = await resolveFreshCodexWakeTarget(active, deps);
     if (!resolved) return; // thread not loaded yet → next tick retries
     const client = makeCodexClient(resolved.socketPath, deps);

package/src/codex-wake-resolve.ts

@@ -140,10 +140,10 @@ export function wakeRetryExpired(
 }
 
 /**
- * WI-2 double-fire avoidance: the periodic heartbeat fires only when no wake (or
- * prior heartbeat) delivery landed within the cadence window — so an active cube
- * with flowing per-entry wakes doesn't get redundant heartbeat injections. A
- * never-delivered seat (null) always fires.
+ * WI-2 double-fire avoidance: the periodic catch-up preflight runs only when no
+ * wake delivery landed within the cadence window. A never-delivered seat (null)
+ * is eligible for preflight; client#76 separately requires pending unread work
+ * before a model turn can start.
  */
 export function shouldFireHeartbeat(
   lastDeliveredAt: number | null,

package/src/log-stream.ts

@@ -28,6 +28,7 @@ import { Buffer } from 'node:buffer';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { compareBroadcastHwm, type BroadcastHwm } from 'borgmcp-shared/log-stream-hwm';
+import { decodeProtocolErrorEnvelope, ErrorCode } from 'borgmcp-shared/protocol';
 import { getActiveCube, inboxPathForDrone } from './cubes.js';
 import { assertUuidShape } from './evict-drone.js';
 import { loadBorgServerTrust } from './server-trust.js';
@@ -53,6 +54,8 @@ import {
   wakeCodexViaAppServer,
 } from './codex-app-wake.js';
 import { readBoundedResponseBody } from './server-response.js';
+import { BorgServerError, BorgServerUnreachableError } from './server-errors.js';
+import { recoverExpiredLocalSession } from './session-continuity.js';
 import {
   acquireStreamLease,
   readOwnershipSnapshot,
@@ -97,6 +100,13 @@ export class StreamCursorExpiredError extends Error {
   }
 }
 
+class TerminalStreamError extends Error {
+  constructor() {
+    super('terminal local session state');
+    this.name = 'TerminalStreamError';
+  }
+}
+
 function isProcessAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -322,6 +332,7 @@ function runStreamLoopForever(): void {
         await runLoop();
         process.stderr.write('[borg-mcp log stream] runLoop returned unexpectedly; restarting in 5s\n');
       } catch (err: any) {
+        if (err instanceof TerminalStreamError) return;
         process.stderr.write(`[borg-mcp log stream] runLoop threw: ${err?.message ?? err}; restarting in 5s\n`);
       }
       streamState.runLoopRestartCount += 1;
@@ -417,6 +428,7 @@ export interface RunLoopTestDeps {
   getActiveCube?: typeof getActiveCube;
   acquireStreamLease?: typeof acquireStreamLease;
   streamOnce?: typeof streamOnce;
+  recoverExpiredSession?: typeof recoverExpiredLocalSession;
   sleep?: (ms: number) => Promise<void>;
   maxIterations?: number;
 }
@@ -425,6 +437,7 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
   const _getActiveCube = testDeps.getActiveCube ?? getActiveCube;
   const _acquireStreamLease = testDeps.acquireStreamLease ?? acquireStreamLease;
   const _streamOnce = testDeps.streamOnce ?? streamOnce;
+  const _recoverExpiredSession = testDeps.recoverExpiredSession ?? recoverExpiredLocalSession;
   const _sleep = testDeps.sleep ?? sleep;
   const _maxIterations = testDeps.maxIterations ?? Infinity;
   let _iterations = 0;
@@ -434,6 +447,7 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
   let currentCubeId: string | null = null;
   let lease: StreamLease | null = null;
   let leaseKey: string | null = null;
+  let lastRecoveredToken: string | null = null;
 
   try {
     while (_iterations < _maxIterations) {
@@ -534,6 +548,7 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
       }
       // Clean disconnect (e.g. server-side rollout). Reset backoff.
       attempt = 0;
+      lastRecoveredToken = null;
       streamState.reconnectAttempts = 0;
     } catch (err: any) {
       if (ownerLost) {
@@ -559,7 +574,28 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
         process.stderr.write(
           `[borg-mcp log stream] drone evicted — stream terminated (no reconnect).\n`
         );
-        return;
+        throw new TerminalStreamError();
+      }
+      if (err instanceof BorgServerError) {
+        if (err.code !== 'AUTH_EXPIRED' || lastRecoveredToken === active.sessionToken) {
+          throw new TerminalStreamError();
+        }
+        try {
+          const renewed = await _recoverExpiredSession(active);
+          lastRecoveredToken = renewed.sessionToken;
+          attempt = 0;
+          streamState.reconnectAttempts = 0;
+          continue;
+        } catch (recoveryError) {
+          if (!(recoveryError instanceof BorgServerUnreachableError)) {
+            throw new TerminalStreamError();
+          }
+          // The replacement bearer is durable and intentionally survives an
+          // ambiguous transport failure. Fall through to the ordinary bounded
+          // reconnect backoff; the next AUTH_EXPIRED response resumes that exact
+          // replacement instead of permanently silencing the stream.
+          err = recoveryError;
+        }
       }
       streamState.connected = false;
       const delay =
@@ -603,6 +639,8 @@ export interface ActiveCube {
   sessionToken: string;
   apiUrl: string;
   serverTrustIdentity?: string;
+  localSessionCredentialRef?: string;
+  localSessionExpiresAt?: string | null;
 }
 
 export async function streamOnce(
@@ -762,7 +800,7 @@ export async function streamOnce(
   // Set + FIFO array for O(1) membership + bounded memory.
   const recentIds = new Set<string>();
   const recentIdsOrder: string[] = [];
-  let isCatchingUp = lastEventId !== null;
+  let isCatchingUp = lastEventId !== null || cursor !== null;
 
   // gh#29 quality-stream (#5): shared inbox-write + cursor-advance helpers,
   // extracted from the previously-duplicated ack / regular-log branches in the
@@ -856,6 +894,30 @@ export async function streamOnce(
     // off forever against a dead seat. Keyed on the structured code, not the
     // bare status (SEC R2). Any other status falls through to the generic throw
     // so the reconnect loop keeps retrying transient failures.
+    if (response.status === 401) {
+      const body = await readBoundedResponseBody(
+        response,
+        LOCAL_SERVER_SSE_FRAME_LIMIT_BYTES,
+        'Local Borg server SSE response exceeded the response limit',
+        ac.signal,
+      ).catch(() => '');
+      let code: ErrorCode | undefined;
+      try {
+        code = decodeProtocolErrorEnvelope(JSON.parse(body)).error.code;
+      } catch {
+        code = undefined;
+      }
+      if (code === ErrorCode.AUTH_EXPIRED) {
+        throw new BorgServerError('AUTH_EXPIRED', 'Borg server session expired');
+      }
+      if (code === ErrorCode.SESSION_REJECTED) {
+        throw new BorgServerError('SESSION_REJECTED', 'Borg server session was rejected');
+      }
+      if (code === ErrorCode.SESSION_REVOKED) {
+        throw new BorgServerError('SESSION_REVOKED', 'Borg server session was revoked');
+      }
+      throw new BorgServerError('CREDENTIAL_REJECTED', 'Borg server rejected the stream credential');
+    }
     if (response.status === 410) {
       const body = await readBoundedResponseBody(
         response,

package/src/remote-client.ts

@@ -47,6 +47,7 @@ import {
 } from './local-server-cursor.js';
 import { readBoundedResponseBody } from './server-response.js';
 import { resolveLocalLogRecipients } from './local-log-routing.js';
+import { ensureLocalSessionFresh, recoverExpiredLocalSession } from './session-continuity.js';
 
 export interface RemoteConnection {
   apiUrl: string;
@@ -228,20 +229,31 @@ async function localServerRequest<T>(
   method: 'GET' | 'POST' | 'PUT' | 'PATCH',
   payload?: Record<string, unknown>,
 ): Promise<T | null> {
-  return decodeLocalProtocolResponse<T>((signal) => authedFetch(path, {
-    method,
-    signal,
-    droneSession: active.sessionToken,
-    apiUrl: active.apiUrl,
-    serverTrustIdentity: active.serverTrustIdentity,
-    redirect: 'error',
-    ...(payload === undefined
-      ? { headers: { Accept: 'application/json' } }
-      : {
-        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-        body: JSON.stringify(createProtocolEnvelope(randomUUID(), payload)),
-      }),
-  }), true);
+  let current = active.localSessionCredentialRef && active.localSessionExpiresAt
+    ? await ensureLocalSessionFresh(active)
+    : active;
+  const request = (candidate: ActiveCube) => decodeLocalProtocolResponse<T>((signal) => authedFetch(path, {
+      method,
+      signal,
+      droneSession: candidate.sessionToken,
+      apiUrl: candidate.apiUrl,
+      serverTrustIdentity: candidate.serverTrustIdentity,
+      redirect: 'error',
+      ...(payload === undefined
+        ? { headers: { Accept: 'application/json' } }
+        : {
+          headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+          body: JSON.stringify(createProtocolEnvelope(randomUUID(), payload)),
+        }),
+    }), true);
+  try {
+    return await request(current);
+  } catch (error) {
+    if (!(error instanceof BorgServerError) || error.code !== 'AUTH_EXPIRED') throw error;
+    if (current.sessionToken !== active.sessionToken) throw error;
+    current = await recoverExpiredLocalSession(current);
+    return request(current);
+  }
 }
 
 export interface LocalManageOperation {
@@ -404,6 +416,66 @@ async function localReadLogPage(
   return payload;
 }
 
+interface PendingWakePage {
+  entries: Array<{
+    drone_id?: unknown;
+    message?: unknown;
+    visibility?: unknown;
+    recipient_drone_ids?: unknown;
+  }>;
+  cursor: LocalServerCursor | null;
+  has_more: boolean;
+}
+
+function isPendingWakeEntry(
+  entry: PendingWakePage['entries'][number],
+  droneId: string,
+): boolean {
+  if (entry.visibility === 'direct') {
+    const recipients = Array.isArray(entry.recipient_drone_ids)
+      ? entry.recipient_drone_ids.filter((recipient): recipient is string => typeof recipient === 'string')
+      : [];
+    if (!recipients.includes(droneId)) return false;
+  }
+
+  const isHeartbeatPing =
+    typeof entry.message === 'string' && entry.message.startsWith('[HEARTBEAT-PING]');
+  return entry.drone_id !== droneId || isHeartbeatPing;
+}
+
+/**
+ * client#76: inspect authoritative unread log state without advancing the
+ * agent-owned unread cursor. The scan mirrors the SSE wake filters: unaddressed
+ * direct entries and ordinary own posts are not work for this seat. A full
+ * paginated scan prevents a run of skipped entries from hiding later real work.
+ */
+export async function hasPendingWakeActivity(
+  active: ActiveCube,
+  deps: {
+    getCursor?: typeof getLocalServerCursor;
+    readPage?: (active: ActiveCube, opts: { cursor: LocalServerCursor | null; limit: number }) => Promise<PendingWakePage>;
+  } = {},
+): Promise<boolean> {
+  if (!active.serverTrustIdentity) {
+    throw new Error('Selected Borg server authority state is missing or unreadable');
+  }
+
+  const getCursor = deps.getCursor ?? getLocalServerCursor;
+  const readPage = deps.readPage ?? localReadLogPage;
+  let cursor = await getCursor(localCursorBinding(active));
+
+  for (;;) {
+    const page: PendingWakePage = await readPage(active, { cursor, limit: 500 });
+    if (page.entries.some((entry) => isPendingWakeEntry(entry, active.droneId))) return true;
+    if (!page.has_more) return false;
+    if (!page.cursor ||
+      (cursor && page.cursor.id === cursor.id && page.cursor.created_at === cursor.created_at)) {
+      throw new Error('Local Borg server returned a non-advancing log cursor');
+    }
+    cursor = page.cursor;
+  }
+}
+
 async function resolveLocalLogCursor(
   active: ActiveCube,
   since: string,
@@ -549,6 +621,12 @@ async function authedFetch(
     } catch {
       rejectedCode = undefined;
     }
+    if (droneSession !== undefined && rejectedCode === ErrorCode.AUTH_EXPIRED) {
+      throw new BorgServerError(
+        'AUTH_EXPIRED',
+        'the selected Borg server session expired',
+      );
+    }
     if (droneSession !== undefined && rejectedCode === ErrorCode.SESSION_REJECTED) {
       throw new BorgServerError(
         'SESSION_REJECTED',

package/src/seats.ts

@@ -55,6 +55,9 @@ export interface SeatRecord {
   roleName?: string;
   roleClass?: 'queen' | 'worker';
   isHumanSeat?: boolean;
+  // One crash-safe replacement may coexist with an ACTIVE session until the
+  // server confirms the same-seat restore. It is never hydratable or bound.
+  replacement?: { credential: string };
 }
 
 interface SeatsFile {
@@ -154,6 +157,19 @@ function isValidSeatRecord(ref: string, value: unknown): value is SeatRecord {
   ) {
     return false;
   }
+  if (r.replacement !== undefined) {
+    if (
+      r.state !== 'active' ||
+      r.replacement === null ||
+      typeof r.replacement !== 'object' ||
+      Array.isArray(r.replacement) ||
+      Object.keys(r.replacement as object).length !== 1 ||
+      typeof (r.replacement as { credential?: unknown }).credential !== 'string' ||
+      !/^[A-Za-z0-9_-]{43}$/.test((r.replacement as { credential: string }).credential)
+    ) {
+      return false;
+    }
+  }
   // State-consistency invariants (no inconsistent active|pending).
   if (r.state === 'active') {
     // An ACTIVE record MUST carry its full server session + worktree binding.
@@ -281,6 +297,17 @@ export async function getActiveSeatCredential(
   return record.credential;
 }
 
+/** Exact ACTIVE record for the internal continuity coordinator. */
+export async function getActiveSeat(
+  ref: string,
+  binding: { origin: string; trustIdentity: string; cubeId: string },
+): Promise<SeatRecord | null> {
+  if (!REF_RE.test(ref)) return null;
+  const store = await readStore();
+  const record = store.seats[ref];
+  return recordMatches(record, ref, binding) && record.state === 'active' ? record : null;
+}
+
 // ─── PREPARE / mint (no worktree yet) ────────────────────────────────────────
 
 /**
@@ -483,6 +510,149 @@ export async function activateAndBindSeat(input: {
   });
 }
 
+export type PrepareSeatReplacementOutcome =
+  | { ok: true; credential: string; digest: string }
+  | { ok: false; reason: 'expectation-mismatch' };
+
+/**
+ * Preserve the exact ACTIVE seat while preparing one durable replacement bearer.
+ * A lost response or process restart reuses the stored replacement; a changed
+ * authority, drone, or active bearer fails before any mutation.
+ */
+export async function prepareSeatReplacement(input: {
+  ref: string;
+  binding: { origin: string; trustIdentity: string; cubeId: string };
+  expectedDroneId: string;
+  expectedActiveDigest: string;
+  replacementCredential: string;
+}): Promise<PrepareSeatReplacementOutcome> {
+  if (!REF_RE.test(input.ref) || !/^[A-Za-z0-9_-]{43}$/.test(input.replacementCredential)) {
+    return { ok: false, reason: 'expectation-mismatch' };
+  }
+  return withStore<SeatsFile, PrepareSeatReplacementOutcome>(SEATS_FILE, emptyStore, parseStore, async (txn) => {
+    const record = txn.data.seats[input.ref];
+    if (
+      !recordMatches(record, input.ref, input.binding) ||
+      record.state !== 'active' ||
+      record.droneId !== input.expectedDroneId ||
+      digestOf(record.credential) !== input.expectedActiveDigest
+    ) {
+      return { ok: false as const, reason: 'expectation-mismatch' as const };
+    }
+    if (record.replacement) {
+      return {
+        ok: true as const,
+        credential: record.replacement.credential,
+        digest: digestOf(record.replacement.credential),
+      };
+    }
+    record.replacement = { credential: input.replacementCredential };
+    await txn.commit();
+    return {
+      ok: true as const,
+      credential: input.replacementCredential,
+      digest: digestOf(input.replacementCredential),
+    };
+  });
+}
+
+export type PromoteSeatReplacementOutcome = 'promoted' | 'missing' | 'replaced';
+
+/** Update only the committed expiry for an exact same-bearer session renewal. */
+export async function refreshActiveSeatSession(input: {
+  ref: string;
+  binding: { origin: string; trustIdentity: string; cubeId: string };
+  expectedDroneId: string;
+  expectedActiveDigest: string;
+  expectedSessionId: string;
+  expiresAt: string;
+}): Promise<boolean> {
+  if (!UUID_RE.test(input.expectedDroneId) || !UUID_RE.test(input.expectedSessionId)) {
+    throw new Error('invalid Borg server session identity');
+  }
+  if (!Number.isFinite(Date.parse(input.expiresAt))) {
+    throw new Error('invalid Borg server session expiry');
+  }
+  return withStore<SeatsFile, boolean>(SEATS_FILE, emptyStore, parseStore, async (txn) => {
+    const record = txn.data.seats[input.ref];
+    if (
+      !recordMatches(record, input.ref, input.binding) ||
+      record.state !== 'active' ||
+      record.droneId !== input.expectedDroneId ||
+      record.sessionId !== input.expectedSessionId ||
+      digestOf(record.credential) !== input.expectedActiveDigest
+    ) {
+      return false;
+    }
+    record.expiresAt = input.expiresAt;
+    await txn.commit();
+    return true;
+  });
+}
+
+/** Atomically promote only the response-bound replacement onto the same ACTIVE seat. */
+export async function promoteSeatReplacement(input: {
+  ref: string;
+  binding: { origin: string; trustIdentity: string; cubeId: string };
+  expectedDroneId: string;
+  expectedActiveDigest: string;
+  expectedReplacementDigest: string;
+  sessionId: string;
+  expiresAt: string;
+}): Promise<PromoteSeatReplacementOutcome> {
+  if (!UUID_RE.test(input.expectedDroneId) || !UUID_RE.test(input.sessionId)) {
+    throw new Error('invalid Borg server session identity');
+  }
+  if (!Number.isFinite(Date.parse(input.expiresAt))) {
+    throw new Error('invalid Borg server session expiry');
+  }
+  return withStore<SeatsFile, PromoteSeatReplacementOutcome>(SEATS_FILE, emptyStore, parseStore, async (txn) => {
+    const record = txn.data.seats[input.ref];
+    if (!recordMatches(record, input.ref, input.binding) || record.state !== 'active') return 'missing';
+    if (
+      record.droneId !== input.expectedDroneId ||
+      digestOf(record.credential) !== input.expectedActiveDigest ||
+      !record.replacement ||
+      digestOf(record.replacement.credential) !== input.expectedReplacementDigest
+    ) {
+      return 'replaced';
+    }
+    const { replacement, ...active } = record;
+    txn.data.seats[input.ref] = {
+      ...active,
+      credential: replacement.credential,
+      sessionId: input.sessionId,
+      expiresAt: input.expiresAt,
+    };
+    await txn.commit();
+    return 'promoted';
+  });
+}
+
+/** Remove only the caller's exact pending replacement, never the ACTIVE seat. */
+export async function scrubSeatReplacement(input: {
+  ref: string;
+  binding: { origin: string; trustIdentity: string; cubeId: string };
+  expectedActiveDigest: string;
+  expectedReplacementDigest: string;
+}): Promise<boolean> {
+  return withStore<SeatsFile, boolean>(SEATS_FILE, emptyStore, parseStore, async (txn) => {
+    const record = txn.data.seats[input.ref];
+    if (
+      !recordMatches(record, input.ref, input.binding) ||
+      record.state !== 'active' ||
+      digestOf(record.credential) !== input.expectedActiveDigest ||
+      !record.replacement ||
+      digestOf(record.replacement.credential) !== input.expectedReplacementDigest
+    ) {
+      return false;
+    }
+    delete record.replacement;
+    await txn.commit();
+    return true;
+  });
+}
+
 // ─── CR#2: bind a PENDING record to a preserved worktree (no activation) ─────
 
 export type BindPendingSeatOutcome = 'bound' | 'missing' | 'replaced';

package/src/server-errors.ts

@@ -4,7 +4,9 @@ export type BorgServerErrorCode =
   | 'INVITATION_REJECTED'
   | 'CREATE_CUBE_DENIED'
   | 'ATTACH_CONFLICT'
-  | 'SESSION_REJECTED';
+  | 'SESSION_REJECTED'
+  | 'SESSION_REVOKED'
+  | 'AUTH_EXPIRED';
 
 /** Safe, non-secret state code for deterministic authority recovery copy. */
 export class BorgServerError extends Error {