borgmcp 2.3.0 → 2.4.0

package/docs/SEAT_LIFECYCLE.md

@@ -0,0 +1,242 @@
+# Seat Lifecycle and Recovery
+
+This guide describes the local seat behavior shipped by the client. A seat is
+one server-side drone identity plus its client-generated session bearer and
+worktree binding. The bearer and binding are stored together in the private
+`seats.json` store; commands never reconstruct one from the other.
+
+## Stored states
+
+Only two seat states are persisted:
+
+| State | Meaning | What can use it |
+| --- | --- | --- |
+| `pending` | The client persisted a fresh bearer before attach completed. It may be unbound, or bound to a worktree after a recoverable finalize failure. | Retry logic only. It is never hydrated as a live seat. |
+| `active` | Attach completed and the server session metadata, display metadata, and worktree binding were committed together. | Normal coordination and re-attach. |
+
+`revoked`, `superseded`, and `evicted` are server verdicts, not values written
+to `seats.json`. Revocation and supersession do not silently delete local
+state. An authoritative eviction is the sole verdict that permits the terminal
+assimilation flow to replace a rejected seat. `borg reset-local-seat` is the
+explicit offline deletion path.
+
+Seat sessions do not expire. A legacy `expiresAt` field is ignored, and current
+attach responses containing `expires_at` are rejected. An enrollment
+invitation can expire; recovery is to request a new invitation. An expired
+stream cursor is also separate from seat identity and is recovered by resetting
+the cursor and reconnecting.
+
+The whole seat store fails closed if any persisted record is malformed. The
+store reader raises:
+
+```text
+Borg seat store is malformed or has an unsupported version; refusing to read it
+```
+
+The file is not rewritten and no bearer material is included in the error.
+
+## Enrollment, attach, and retry
+
+Enrollment establishes the authority-bound parent credential used to request
+seat attachment. Invitation enrollment persists its retry tuple before network
+I/O; a rejected or expired invitation requires a new invitation.
+
+For a seat attach, the client:
+
+1. Mints a 32-byte base64url session bearer and persists a `pending` record
+   before sending it.
+2. Sends that bearer to the server. The server stores only its digest.
+3. On success, atomically changes the same record to `active` and adds the
+   server metadata and worktree binding.
+
+An ambiguous retry reuses the same persisted bearer, so the server resolves the
+same seat instead of minting a duplicate. A crash after server acceptance but
+before local finalization is also resumed from that pending record. If a
+sibling worktree was already created when activation failed, Borg binds the
+still-pending record to that worktree without making it live; rerunning from
+there resends the same bearer.
+
+Only an `implicit-sibling:<id>` pending operation is eligible for automatic
+implicit retry adoption. A `named-sibling:<name>` operation remains distinct
+and is never silently adopted by an unnamed sibling launch.
+
+If activation fails and the exact pending record is successfully bound to the
+spawned worktree, Borg preserves that worktree and the printed retry reuses the
+same seat. If the record is missing, replaced, or unavailable, Borg removes the
+spawned worktree and does not print a client retry command: the server may
+already have accepted the seat, and the current protocol has no client-side
+operation identifier or cleanup endpoint that can prove reuse or remove it.
+
+## Re-attaching from a terminal
+
+`borg assimilate --here` first resolves this worktree's saved active seat and
+probes it. A live seat is reattached with the identical bearer; its saved role
+is authoritative, and no new drone is minted. The success line is:
+
+```text
+re-attached to existing seat <drone-label> (same session, no new drone minted)
+```
+
+Before relaunch, Borg checks the seat's inbox-monitor PID. A live holder refuses
+the relaunch, names its PID, and gives both the safe fresh-worktree path and the
+explicit one-time override:
+
+```text
+This worktree's Borg seat already has a live session (inbox monitor pid <pid>).
+No agent was launched. Stop the existing session or use a fresh worktree with `borg assimilate --worktree <name>`. If the live monitor is wedged, override once with `borg assimilate --here --force`.
+```
+
+For a stale or missing heartbeat, the first line adds:
+
+```text
+Its heartbeat is <stale|missing>, so the process may be wedged.
+```
+
+A dead, absent, malformed, or unreadable PID file is not evidence of a live
+holder, so ordinary crash recovery proceeds without `--force`. The probe is
+read-only; it does not reap, kill, rewrite, or clear monitor state.
+
+If a second monitor reaches the singleton after launch, it exits successfully
+without tailing and prints:
+
+```text
+borg-inbox-monitor: seat inbox "<path>" is already monitored by a live instance (pid <pid>); yielding — another session likely holds this seat.
+```
+
+The existing monitor remains the sole inbox reader.
+
+## Re-attaching from an agent session
+
+The `borg_assimilate` MCP tool is re-attach-only. It can reuse this worktree's
+saved seat for the requested cube, but it cannot create a seat or switch the
+worktree to another cube.
+
+With no saved identity, it returns:
+
+```text
+◼ This session has no drone seat for this worktree, and in-session borg_assimilate is re-attach-only (it never creates seats — gh#780). To create a seat for cube "<cube>", run `borg assimilate` in a terminal — it spawns the worktree, persists the identity, and launches the agent in one step.
+```
+
+For another cube, it returns:
+
+```text
+◼ This worktree is attached to cube "<active-cube>"; in-session borg_assimilate is re-attach-only and cannot switch to "<requested-cube>" (gh#780). To work in "<requested-cube>", run `borg assimilate` in a terminal from that project (or spawn a fresh worktree for it).
+```
+
+A successful in-session re-attach begins:
+
+```text
+# Re-attached to cube: <cube>
+
+**Drone label:** <drone-label>
+**Seat:** existing identity reused — no new drone minted (gh#780)
+```
+
+If the server no longer accepts the saved seat, the tool fails rather than
+reminting:
+
+```text
+◼ Re-attach failed — this worktree's saved seat is unreachable (likely evicted or its session was revoked). Server said: <server-error>
+Recover by running `borg assimilate` in a terminal to create a fresh seat; in-session borg_assimilate never re-mints (gh#780).
+```
+
+## Terminal verdicts and recovery
+
+### Revoked or superseded session
+
+A pin-matched `SESSION_REVOKED` or `SESSION_REJECTED` is diagnosis only. Attach
+does not mutate the saved seat. The exact output is one of:
+
+```text
+Local session was revoked.
+Next: run borg reset-local-seat, then borg assimilate --host <server> --enroll.
+```
+
+```text
+Local session was superseded by a newer enrollment.
+Next: run borg reset-local-seat, then borg assimilate --host <server> --enroll.
+```
+
+Run the named offline reset, obtain a new invitation, and enroll again.
+
+### Evicted seat
+
+Only an authoritative `410 DRONE_EVICTED` permits replacement of a rejected
+saved seat. If the pre-attach probe establishes eviction, the terminal
+assimilation flow may replace the bearer and attach a fresh seat. Ambiguous
+transport, trust, endpoint, credential, or server failures never authorize that
+replacement.
+
+If the attach itself returns the eviction after re-attach began, Borg does not
+claim recovery. It prints:
+
+```text
+This worktree's saved seat on <server> was evicted. Remove this worktree, or from a fresh worktree run `borg assimilate --host <server>`.
+```
+
+The stream path also treats typed `DRONE_EVICTED` as terminal: it marks that
+exact local candidate rejected, stops retrying that seat, and does not restart
+the loop as though the failure were transient.
+
+### Rejected or expired invitation
+
+An invitation failure is enrollment recovery, not a seat reset:
+
+```text
+The enrollment invitation for <server> was rejected or expired. Ask the server operator for a replacement invitation — the server can stay running: for an unclaimed owner client run `borg-mcp-server owner-invite`; for an ordinary client run `borg-mcp-server client-invite`. Then rerun `borg assimilate --host <server> --enroll`.
+```
+
+## Offline reset
+
+`borg reset-local-seat` clears only the current worktree's saved credential and
+cube binding. It makes no network call, revokes nothing server-side, and leaves
+the server, trust anchor, cube, and sibling worktrees unchanged.
+
+Its shipped help describes the command as:
+
+```text
+borg reset-local-seat (borgmcp <version>) — clear ONLY this worktree's saved local seat
+
+Usage:
+  borg reset-local-seat                 Reset this worktree's saved seat (TTY confirms [y/N])
+  borg reset-local-seat --host <host>   No-op unless this worktree's seat is on <host>
+  borg reset-local-seat --yes           Reset without a prompt (required when non-interactive)
+  borg reset-local-seat --help          Show this help
+```
+
+The command snapshots the exact binding and token-safe bearer observation,
+prompts outside the store lock, then revalidates the same seat before deleting
+it. If another process replaced or reset the seat, the command is an honest
+no-op rather than deleting the successor. After a successful reset, Borg reads
+the same worktree again without hydrating any bearer. If another saved active
+seat remains on the same server, the command points to
+`borg assimilate --host <server> --here` and states that the server will
+revalidate it before launch. Otherwise it gives the fresh-enrollment path:
+
+```text
+borg assimilate --host <server> --enroll
+```
+
+## Multiple seats and deterministic selection
+
+An in-place seat uses operation kind `seat` and operation key
+`current-worktree`. A sibling uses operation kind `sibling`; named siblings key
+on their worktree name, while implicit siblings receive a unique operation key.
+These operations derive distinct credential references and distinct bearers.
+Creating a sibling therefore never moves or overwrites the original
+worktree's active seat.
+
+Historical recovery or interrupted operations can leave more than one active
+record bound to one worktree. Every process uses the same total order:
+
+1. A candidate not definitively rejected in this process comes before a
+   rejected, revoked, or evicted candidate.
+2. A `sibling` candidate finalized into this worktree comes before an older
+   in-place `seat` candidate.
+3. Remaining ties use the credential reference's lexical order.
+
+Only `active` records participate in normal selection. A bound `pending` record
+is discoverable only by the convergence path that resends its exact bearer.
+This ordering is shared by SessionStart, kickoff construction, MCP children,
+stream ownership, and normal active-cube hydration, so one process does not
+select different seats for different surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",

package/src/assimilate-cmd.ts

@@ -28,6 +28,11 @@ import {
 import type { BorgCli } from './cubes.js';
 import { inboxPathForDrone } from './cubes.js';
 import { monitorStateRootForWorktree } from './inbox-monitor.js';
+import {
+  formatSeatReattachRefusal,
+  inspectLiveInboxMonitor,
+  type LiveInboxMonitor,
+} from './seat-reattach-guard.js';
 import { resolveLaunchEnv } from './model-presets.js';
 import { unlinkSync } from 'node:fs';
 import {
@@ -89,6 +94,7 @@ export interface AssimilateFlags {
   model?: string;
   server?: string;
   enroll?: boolean;
+  force?: boolean;
 }
 
 export interface AssimilateArgs {
@@ -154,6 +160,8 @@ export interface ActiveCube {
   /** Verified local-server CA identity; absent until a local server is selected. */
   serverTrustIdentity?: string;
   localSessionCredentialRef?: string;
+  /** Durable operation that produced this exact seat binding. */
+  operation?: ServerSessionOperation;
   // gh#899: assimilated role, persisted for connect-time tool-surface scoping
   // (mirrors cubes.ts ActiveCube; optional → backward-compatible).
   roleName?: string;
@@ -202,6 +210,11 @@ export interface AssimilateDeps {
   // The scaffold previously declared them sync; that would silently
   // mis-await in Phase F wiring. Promise<...> matches the real shape.
   getActiveCube: () => Promise<ActiveCube | null>;
+  /** Read-only relaunch guard for the saved seat's inbox monitor. */
+  inspectLiveInboxMonitor?: (
+    inboxPath: string,
+    monitorStateRoot: string,
+  ) => LiveInboxMonitor | null;
   hasPersistedActiveCube: () => Promise<boolean>;
   /** Read the RAW persisted local seat for this worktree WITHOUT hydrating its
    *  keychain credential — used to recover a crash-in-gap PENDING seat when
@@ -848,6 +861,12 @@ export async function runAssimilate(
         : `named-sibling:${args.flags.worktree}`)
       : 'current-worktree',
   };
+  // A selected sibling can be the surviving live seat for this worktree (#63).
+  // `--here` must re-send that seat's durable operation, not reconstruct the
+  // in-place operation and then fail PREPARE forever on the wrong ref.
+  if (existing && args.flags.here && existing.operation) {
+    sessionOperation = existing.operation;
+  }
   let reattachPriorId: string | undefined;
   let remintInvalidPrior = false;
   let savedLocalRole: Role | undefined;
@@ -1083,6 +1102,16 @@ export async function runAssimilate(
     reattachPriorId = existing.droneId;
   }
 
+  if (existing && reattachPriorId !== undefined && !args.flags.force) {
+    const inboxPath = deps.getInboxPath(existing.cubeId, existing.droneId);
+    const stateRoot = monitorStateRootForWorktree(projectRoot);
+    const holder = (deps.inspectLiveInboxMonitor ?? inspectLiveInboxMonitor)(inboxPath, stateRoot);
+    if (holder !== null) {
+      deps.stderr(formatSeatReattachRefusal(holder, 'borg assimilate --here --force'));
+      return 1;
+    }
+  }
+
   // ----- Step 5: Role resolution -----
   let resolvedRole: Role | undefined;
   if (savedLocalRole) {
@@ -1545,14 +1574,23 @@ export async function runAssimilate(
           return 1;
         }
         // missing / replaced / threw / unavailable: the worktree owns NO durable
-        // locator, so make NO convergence claim. Roll back the just-spawned worktree
-        // (preserve ONLY when it owns a durable locator) and point at the offline reset.
+        // locator. The server may already have accepted the seat, while the client
+        // has no protocol operation id or cleanup endpoint with which to prove reuse
+        // or remove it. State the exact local outcome and do not prescribe a retry
+        // that can silently create a duplicate server seat (#35).
+        const bindFailure =
+          bindOutcome === 'missing'
+            ? 'the exact pending seat record went missing locally before it could be bound'
+            : bindOutcome === 'replaced'
+              ? 'the exact pending seat record was replaced locally before it could be bound; the replacement was left untouched'
+              : bindOutcome === 'threw'
+                ? 'the local seat store could not be read or written while preserving the pending seat'
+                : 'this client did not receive a pending-seat preservation handle';
         deps.stderr(
-          `This worktree's secure session on ${auth.apiUrl} did not finish activating, and its ` +
-            'seat state could NOT be preserved to this worktree (it was concurrently reset or ' +
-            'replaced, or the local seat store could not be written). No usable seat remains here. ' +
-            `Run ${resetLocalSeatCommand(auth.apiUrl)} to clear any saved seat, then re-run ` +
-            `${localAssimilateCommand(auth.apiUrl)} to attach against the current state.\n`,
+          `This worktree's secure session on ${auth.apiUrl} did not finish activating: ` +
+            `${bindFailure}. The spawned worktree will be removed. No client-only command can ` +
+            'prove reuse or safely clear the possibly accepted server-side seat; ask the server ' +
+            'operator to inspect that seat before retrying.\n',
         );
         rollbackWorktree();
         return 1;

package/src/assimilate-deps.ts

@@ -17,6 +17,7 @@ import prompts from 'prompts';
 import { readinessProbeEnv } from './readiness-probe.js';
 import { resolveMcpBinaryPath } from './self-path.js';
 import { buildRuntimeMetadataReport } from './runtime-metadata.js';
+import { inspectLiveInboxMonitor } from './seat-reattach-guard.js';
 
 import type { AssimilateDeps } from './assimilate-cmd.js';
 import {
@@ -170,6 +171,7 @@ export function buildDefaultAssimilateDeps(
     },
 
     getActiveCube: () => cubesGetActive(),
+    inspectLiveInboxMonitor,
     hasPersistedActiveCube: () => cubesHasPersistedActive(),
     readPersistedLocalSeat: () => readPersistedLocalSeat(),
     peekServerSessionRecord: async (credentialRef, binding) =>

package/src/claude.ts

@@ -26,6 +26,7 @@ import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import { findProjectRoot, getActiveCube, inboxPathForDrone, setCodexWakeTarget, pruneDeadCodexWakeTargets } from './cubes.js';
 import { monitorStateRootForWorktree } from './inbox-monitor.js';
+import { formatSeatReattachRefusal, inspectLiveInboxMonitor } from './seat-reattach-guard.js';
 import { handleVersionFlag, getPackageVersion } from './version.js';
 import { isHelpFlag, setupHelpText, topLevelHelpText, assimilateHelpText, resetLocalSeatHelpText } from './cli-help.js';
 import { runSpawn } from './spawn.js';
@@ -310,6 +311,16 @@ async function main() {
     cli = action.cli;
   }
 
+  if (active && !parsedCli.force) {
+    const inboxPath = inboxPathForDrone(active.cubeId, active.droneId);
+    const stateRoot = monitorStateRootForWorktree(findProjectRoot(process.cwd()));
+    const holder = inspectLiveInboxMonitor(inboxPath, stateRoot);
+    if (holder !== null) {
+      process.stderr.write(formatSeatReattachRefusal(holder, 'borg --force'));
+      process.exit(1);
+    }
+  }
+
   // client#20: inspect only the SELECTED harness after the one-shot launch
   // menu choice. Explicit consent enables a narrow per-process override;
   // Borg never rewrites the user's approval policy here.

package/src/cli-help.ts

@@ -109,12 +109,14 @@ export function assimilateHelpText(version: string): string {
     `  borg assimilate [role] --worktree <name>   Spawn the drone in an isolated git worktree\n` +
     `                                       (~/.borg/worktrees/<repo>/<name>)\n` +
     `  borg assimilate --here               Assimilate in the current worktree (no sibling spawn)\n` +
+    `  borg assimilate --here --force       Reattach despite a still-live inbox monitor\n` +
     `  borg assimilate --host <host>        Join an authorized self-hosted cube\n` +
     `  borg assimilate --host <host> --enroll   Operator-terminal enrollment, then create/join (preview)\n` +
     `  borg assimilate --help               Show this help\n\n` +
     `Flags:\n` +
     `  --worktree <name>          Create + launch the drone in a sibling git worktree\n` +
     `  --here                     Stay in the current worktree (no sibling spawn)\n` +
+    `  --force                    Override a live-seat guard for a wedged monitor\n` +
     `  --cube-name <name>         Repository cube name (otherwise edit the proposed name)\n` +
     `  --host <host>              Borg server host or URL (bare hosts default to HTTPS)\n` +
     `  --enroll                   Prompt for a hidden enrollment invitation in the operator terminal\n` +

package/src/cli-platform.ts

@@ -101,9 +101,10 @@ export function defaultCliChoiceDeps(prompt: (message: string) => Promise<string
 
 const VALID_CLIS: readonly BorgCli[] = ['claude', 'codex', 'opencode'];
 
-export function parseCliFlag(args: string[]): { cli?: BorgCli; rest: string[]; error?: string } {
+export function parseCliFlag(args: string[]): { cli?: BorgCli; force?: boolean; rest: string[]; error?: string } {
   const rest: string[] = [];
   let cli: BorgCli | undefined;
+  let force = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--cli') {
@@ -119,9 +120,11 @@ export function parseCliFlag(args: string[]): { cli?: BorgCli; rest: string[]; e
         return { rest, error: `--cli requires one of: ${VALID_CLIS.join(', ')}` };
       }
       cli = value as BorgCli;
+    } else if (arg === '--force') {
+      force = true;
     } else {
       rest.push(arg);
     }
   }
-  return { cli, rest };
+  return { ...(cli ? { cli } : {}), ...(force ? { force: true } : {}), rest };
 }

package/src/console-prefix.ts

@@ -9,9 +9,9 @@
  * insufficient — the Queen reads the active terminal's output stream,
  * not its title bar.
  *
- * This module exports a one-shot initializer that resolves the prefix
- * from the local cube state cache, plus a synchronous getter that
- * call sites use to wrap each console.error.
+ * This module exports a one-shot initializer that seeds the process-local
+ * display identity from the selected seat, plus a synchronous getter that
+ * follows later server confirmations and wraps each console.error.
  *
  * Format (matches the terminal-title.ts middle-dot convention so
  * surfaces stay internally consistent):
@@ -27,8 +27,13 @@
 import { basename } from 'node:path';
 import chalk from 'chalk';
 import { getActiveCube } from './cubes.js';
+import {
+  _resetDisplayIdentityForTests,
+  currentDisplayIdentity,
+  seedDisplayIdentity,
+} from './display-identity.js';
 
-let cachedPrefix: string | null = null;
+let initialized = false;
 
 /** Neutral prefix for a not-yet-assimilated session (gh#818 P1). */
 function unassimilatedPrefix(): string {
@@ -36,34 +41,35 @@ function unassimilatedPrefix(): string {
 }
 
 /**
- * Resolve the drone-self-identification prefix from cube state and
- * cache it for subsequent synchronous reads. Idempotent — calling
- * multiple times returns the same value. Falls back silently to the
- * unassimilated shape on any read error so console emission is never
- * blocked.
+ * Resolve the drone-self-identification prefix from cube state and seed the
+ * shared display source. Idempotent — later calls do not re-read the store,
+ * while the synchronous prefix still follows server-confirmed display changes.
+ * Falls back silently on any read error so console emission is never blocked.
  */
 export async function initConsolePrefix(): Promise<string> {
-  if (cachedPrefix !== null) return cachedPrefix;
+  if (initialized) return droneIdPrefix();
   try {
     const active = await getActiveCube();
     if (active?.droneLabel && active?.name) {
-      cachedPrefix = `[${active.droneLabel} · ${active.name}]`;
-      return cachedPrefix;
+      seedDisplayIdentity(active);
+      initialized = true;
+      return droneIdPrefix();
     }
   } catch {
     // Fall through to unassimilated fallback.
   }
-  cachedPrefix = unassimilatedPrefix();
-  return cachedPrefix;
+  initialized = true;
+  return unassimilatedPrefix();
 }
 
 /**
- * Synchronous prefix getter. Returns the cached value if initialized,
- * otherwise the unassimilated fallback — safe to call before
+ * Synchronous prefix getter. Returns the current process-local display value
+ * if initialized, otherwise the unassimilated fallback — safe to call before
  * initConsolePrefix() resolves.
  */
 export function droneIdPrefix(): string {
-  if (cachedPrefix !== null) return cachedPrefix;
+  const identity = currentDisplayIdentity();
+  if (initialized && identity) return `[${identity.droneLabel} · ${identity.cubeName}]`;
   return unassimilatedPrefix();
 }
 
@@ -95,5 +101,6 @@ export function cerr(...args: any[]): void {
 }
 
 export function _resetCachedPrefixForTests(): void {
-  cachedPrefix = null;
+  initialized = false;
+  _resetDisplayIdentityForTests();
 }

package/src/cubes.ts

@@ -62,6 +62,8 @@ export interface ActiveCube {
   serverTrustIdentity?: string;
   /** Opaque local-session keychain reference; never a bearer. */
   localSessionCredentialRef?: string;
+  /** Durable seat operation that produced this exact local binding. */
+  operation?: SeatOperation;
   // gh#899: the assimilated role, persisted so the connect-time ListTools
   // handler can role-scope the NATIVE tool surface (UX/context only — never an
   // auth boundary). Absent on pre-gh#899 cubes.json entries → the filter
@@ -279,12 +281,26 @@ async function hydrateActiveCube(record: SeatRecord): Promise<ActiveCube | null>
     apiUrl: record.origin,
     serverTrustIdentity: record.trustIdentity,
     localSessionCredentialRef: ref,
+    operation: record.operation,
     ...(record.roleName !== undefined ? { roleName: record.roleName } : {}),
     ...(record.roleClass !== undefined ? { roleClass: record.roleClass } : {}),
     ...(record.isHumanSeat !== undefined ? { isHumanSeat: record.isHumanSeat } : {}),
   };
 }
 
+/**
+ * Token-free lookup used after an offline reset. A surviving seat is only
+ * described as saved local state; the caller must still revalidate it with the
+ * server before launch.
+ */
+export async function findRemainingActiveSeatForWorktree(worktree: string): Promise<{
+  apiUrl: string;
+  operation: SeatOperation;
+} | null> {
+  const record = await getActiveSeatForWorktree(worktree);
+  return record ? { apiUrl: record.origin, operation: record.operation } : null;
+}
+
 /**
  * Legacy binding-only writer. In the collapsed single-store model an ACTIVE seat is
  * created ONLY by the atomic mint→activate+bind path in seats.ts (driven by the