borgmcp 1.1.15 → 2.0.2

package/src/reset-local-seat-cmd.ts

@@ -0,0 +1,227 @@
+/**
+ * `borg reset-local-seat [--host <host>] [--yes]` — the dedicated LOCAL/OFFLINE
+ * seat reset from the ratified client-seat-reset-state-model (Option W).
+ *
+ * Attach is PURE DIAGNOSIS on a pin-matched SESSION_REJECTED (it mutates
+ * nothing and points here). This command is the ONLY writer that intentionally
+ * clears a worktree's saved local seat. It performs ZERO network I/O: it never
+ * contacts the server, so it makes NO server-revocation claim. It clears ONLY
+ * this worktree's saved local seat — its credential and cube binding together —
+ * from the local seat store (keyed on findProjectRoot()); server, trust anchor,
+ * cube, and every sibling worktree are untouched.
+ *
+ * Flow (decision clause 2):
+ *   S0  snapshot exact binding + token-safe credential observation
+ *       (PRESENT(digest) | ABSENT); --host normalized-mismatch = no-op BEFORE
+ *       any mutation; no local binding = honest no-op.
+ *   S1  consent OUTSIDE any lock — TTY [y/N] defaulting to No; non-TTY requires
+ *       the explicit --yes flag.
+ *   S2/S3  re-acquire cube→seat store, re-verify the exact snapshot (any change /
+ *       missing / same-ref replacement = honest no-op), then delete the
+ *       CREDENTIAL FIRST and remove the binding.
+ */
+
+import { createInterface } from 'node:readline/promises';
+import {
+  snapshotLocalSeat as cubesSnapshotLocalSeat,
+  resetLocalSeatBinding as cubesResetLocalSeatBinding,
+  findProjectRoot as cubesFindProjectRoot,
+  type LocalSeatSnapshot,
+  type ResetLocalSeatOutcome,
+} from './cubes.js';
+import { normalizeServerEndpoint } from './server-endpoint.js';
+
+export interface ResetLocalSeatFlags {
+  host?: string;
+  yes?: boolean;
+}
+
+export interface ResetLocalSeatDeps {
+  snapshotLocalSeat: () => Promise<LocalSeatSnapshot | null>;
+  resetLocalSeatBinding: (expected: LocalSeatSnapshot) => Promise<ResetLocalSeatOutcome>;
+  findProjectRoot: (cwd: string) => string;
+  normalizeHost: (host: string) => string;
+  cwd: () => string;
+  isTTY: () => boolean;
+  prompt: (message: string) => Promise<string>;
+  stdout: (line: string) => void;
+  stderr: (line: string) => void;
+}
+
+function reenrollCommand(apiUrl: string): string {
+  return `\`borg assimilate --host ${apiUrl} --enroll\``;
+}
+
+/**
+ * Recovery guidance shared by the success + honest-no-op copy. Makes NO
+ * server-revocation claim: it recommends the operator issue a LIVE scoped
+ * invitation (the server can stay running) and re-enroll from this worktree.
+ */
+function recoveryGuidance(apiUrl: string): string {
+  return (
+    'To rejoin: ask the server operator for a new enrollment invitation — the server can ' +
+    'stay running (`borg-mcp-server client-invite`, or `owner-invite` for an owner) — then ' +
+    `re-enroll from this worktree with ${reenrollCommand(apiUrl)}.\n`
+  );
+}
+
+export async function runResetLocalSeat(
+  flags: ResetLocalSeatFlags,
+  deps: ResetLocalSeatDeps,
+): Promise<number> {
+  const worktree = deps.findProjectRoot(deps.cwd());
+
+  // Normalize --host up front so an unparseable value fails before any read.
+  let requestedHost: string | undefined;
+  if (flags.host !== undefined) {
+    try {
+      requestedHost = deps.normalizeHost(flags.host);
+    } catch (error) {
+      deps.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
+  }
+
+  // ----- S0: snapshot -----
+  const snapshot = await deps.snapshotLocalSeat();
+  if (!snapshot) {
+    deps.stdout(
+      `No saved local seat was found for this worktree (${worktree}); nothing to reset.\n`,
+    );
+    return 0;
+  }
+
+  // --host normalized-mismatch = honest no-op BEFORE any mutation. This worktree
+  // points at a different server than the one named, so it is not the seat the
+  // operator asked to reset.
+  if (requestedHost !== undefined && requestedHost !== snapshot.apiUrl) {
+    deps.stdout(
+      `This worktree's saved local seat is on ${snapshot.apiUrl}, not ${requestedHost}; ` +
+        `nothing was changed. Re-run \`borg reset-local-seat --host ${snapshot.apiUrl}\` to ` +
+        "reset this worktree's seat.\n",
+    );
+    return 0;
+  }
+
+  const observed =
+    snapshot.observation.state !== 'absent'
+      ? `a saved local session credential is present (${snapshot.observation.state})`
+      : 'the saved local session credential is already cleared (only the binding remains)';
+  deps.stderr(
+    `This will clear ONLY this worktree's saved local seat on ${snapshot.apiUrl} ` +
+      `(worktree ${worktree}) — ${observed}. Server, trust anchor, cube, and sibling ` +
+      'worktrees are left untouched. It makes no network call and revokes nothing server-side.\n',
+  );
+
+  // ----- S1: consent OUTSIDE any lock -----
+  if (deps.isTTY()) {
+    const answer = await deps.prompt(
+      `Reset this worktree's saved local seat now? [y/N]: `,
+    );
+    const normalized = answer.trim().toLowerCase();
+    if (normalized !== 'y' && normalized !== 'yes') {
+      deps.stderr("audit: no changes made — this worktree's saved seat was left in place.\n");
+      return 0;
+    }
+  } else if (flags.yes !== true) {
+    deps.stderr(
+      'audit: no changes made — stdin is non-interactive and --yes was not passed. Re-run ' +
+        '`borg reset-local-seat --yes` to clear this worktree\'s saved seat without a prompt.\n',
+    );
+    return 1;
+  }
+
+  // ----- S2/S3: re-verify under lock, credential-FIRST delete, then binding -----
+  let outcome: ResetLocalSeatOutcome;
+  try {
+    outcome = await deps.resetLocalSeatBinding(snapshot);
+  } catch {
+    deps.stderr(
+      `audit: no changes made — the local seat reset for ${snapshot.apiUrl} (worktree ` +
+        `${worktree}) could not complete (local credential store error). Retry — it is ` +
+        'safe to re-run.\n',
+    );
+    return 1;
+  }
+
+  if (outcome.outcome === 'reset') {
+    deps.stderr(
+      `audit: this worktree's saved local seat for ${snapshot.apiUrl} (worktree ${worktree}) ` +
+        'was cleared; server, trust anchor, cube, and sibling worktrees unchanged.\n',
+    );
+    deps.stdout(recoveryGuidance(snapshot.apiUrl));
+    return 0;
+  }
+
+  if (outcome.outcome === 'no-binding') {
+    deps.stdout(
+      `No saved local seat remained for this worktree (${worktree}); nothing to reset.\n`,
+    );
+    return 0;
+  }
+
+  // 'changed': the seat drifted between the snapshot and the commit re-check
+  // (a concurrent re-enroll wrote a fresh bearer, or another process already
+  // reset it). Never clobber a replacement — report the honest no-op.
+  deps.stdout(
+    `This worktree's saved local seat on ${snapshot.apiUrl} changed since it was read ` +
+      "(a concurrent re-enroll or reset); nothing was changed. Re-run to observe the current " +
+      'state.\n',
+  );
+  return 0;
+}
+
+export function buildDefaultResetLocalSeatDeps(): ResetLocalSeatDeps {
+  return {
+    snapshotLocalSeat: () => cubesSnapshotLocalSeat(),
+    resetLocalSeatBinding: (expected) => cubesResetLocalSeatBinding(expected),
+    findProjectRoot: (cwd) => cubesFindProjectRoot(cwd),
+    normalizeHost: (host) => normalizeServerEndpoint(host),
+    cwd: () => process.cwd(),
+    isTTY: () => process.stdin.isTTY === true,
+    prompt: async (message: string): Promise<string> => {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      try {
+        return await rl.question(message);
+      } finally {
+        rl.close();
+      }
+    },
+    stdout: (line) => process.stdout.write(line),
+    stderr: (line) => process.stderr.write(line),
+  };
+}
+
+export type ResetLocalSeatParseResult =
+  | { ok: true; flags: ResetLocalSeatFlags }
+  | { ok: false; error: string };
+
+/** Parse args after `borg reset-local-seat`. Supports `--host <h>` / `--host=<h>` / `--yes` / `-y`. */
+export function parseResetLocalSeatArgs(rawArgs: string[]): ResetLocalSeatParseResult {
+  const flags: ResetLocalSeatFlags = {};
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const arg = rawArgs[i];
+    if (arg === '--host') {
+      const next = rawArgs[i + 1];
+      if (typeof next !== 'string' || next.length === 0 || next.startsWith('-')) {
+        return { ok: false, error: '--host requires a host or URL (e.g. `--host localhost:7091`)' };
+      }
+      flags.host = next;
+      i += 1;
+    } else if (arg.startsWith('--host=')) {
+      const value = arg.slice('--host='.length);
+      if (!value) {
+        return { ok: false, error: '--host requires a host or URL (e.g. `--host localhost:7091`)' };
+      }
+      flags.host = value;
+    } else if (arg === '--yes' || arg === '-y') {
+      flags.yes = true;
+    } else {
+      return {
+        ok: false,
+        error: `unexpected argument: ${arg}. Usage: borg reset-local-seat [--host <host>] [--yes]`,
+      };
+    }
+  }
+  return { ok: true, flags };
+}

package/src/role-match.ts

@@ -0,0 +1,29 @@
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Rollout-compat guard. An old worker ignores the `?role=` param and
+ * returns the CALLER's own role, so a new client on a not-yet-deployed
+ * worker would silently show the wrong playbook. Verify the returned
+ * role actually matches the request: by id when the input was a uuid,
+ * otherwise by case-insensitive trimmed name.
+ *
+ * Benign residual: if the requested name/id equals the caller's OWN role,
+ * an old worker's echo passes the check — but that echo IS the correct role
+ * (names are unique per cube, ids globally unique), so no wrong playbook is
+ * ever shown. The guard only needs to catch a request for a DIFFERENT role.
+ */
+export function assertRoleMatches(
+  requested: string,
+  returned: { id?: string | null; name?: string | null }
+): void {
+  const req = requested.trim();
+  const matches = UUID_RE.test(req)
+    ? returned.id === req
+    : (returned.name ?? '').trim().toLowerCase() === req.toLowerCase();
+  if (!matches) {
+    throw new Error(
+      `server does not support named-role lookup yet (returned "${returned.name ?? '?'}" for "${requested}") — worker upgrade pending`
+    );
+  }
+}

package/src/role-resolver.ts

@@ -0,0 +1,93 @@
+export interface Role {
+  id: string;
+  name: string;
+  is_default: boolean;
+  // Optional so a newly published client remains compatible with an older
+  // worker that has not yet deployed the mandatory-role migration.
+  is_mandatory?: boolean;
+  is_human_seat: boolean;
+  // gh#899: present when the server includes it; used to give queen-class seats
+  // the full native tool surface. Optional — absent → treated as non-management
+  // (degrades to dispatcher access, never a capability loss).
+  role_class?: 'queen' | 'worker';
+  default_model?: string | null;
+}
+
+export interface RoleOccupant {
+  role_id: string;
+  /** Server-derived advisory; absent remains occupied for rollout safety. */
+  presumed_abandoned?: boolean;
+}
+
+/**
+ * Build the advisory occupancy set used only by role-less assimilation.
+ * Explicit role selection and server authorization do not consult it.
+ */
+export function occupiedRoleIdsForAutoRole(
+  drones: readonly RoleOccupant[],
+): Set<string> {
+  return new Set(
+    drones
+      .filter((drone) => drone.presumed_abandoned !== true)
+      .map((drone) => drone.role_id),
+  );
+}
+
+/**
+ * Normalize a role-name argument or stored name into a slug used for
+ * both worktree-path construction and role lookup. Single source of
+ * truth so the path and the matched role always agree.
+ *
+ * Path-safe: strips characters outside `[a-z0-9-]` after the
+ * underscore/whitespace collapse. The no-arg path bypasses
+ * validateName (the matched role's name comes from the DB, which
+ * has no charset constraint on role names — CreateRoleSchema is
+ * `min(1).max(64)` only), so the safety has to live here.
+ */
+export function roleSlug(raw: string): string {
+  return raw.toLowerCase().replace(/[_\s]+/g, '-').replace(/[^a-z0-9-]/g, '');
+}
+
+/**
+ * Case- and separator-insensitive lookup against the cube's roles.
+ */
+export function matchRoleByName(roles: Role[], query: string): Role | undefined {
+  const slug = roleSlug(query);
+  return roles.find((r) => roleSlug(r.name) === slug);
+}
+
+/**
+ * Role picker for the no-arg `borg assimilate` case:
+ *   - First drone in cube + a human-seat role exists → that role.
+ *   - Otherwise → the first UNOCCUPIED mandatory non-queen role in list
+ *     order. This includes a mandatory human-seat role such as Coordinator;
+ *     its active seat remains the occupancy guard against a double-fill.
+ *   - Otherwise → the first UNOCCUPIED eligible worker role in list order
+ *     (eligible = not queen-class, not human-seat). The default role is an
+ *     equal candidate in this pass.
+ *   - If every eligible worker role is occupied → the is_default role.
+ *   - Neither available → undefined (caller errors out).
+ *
+ * `occupiedRoleIds` is the set of role_ids that still hold a live-enough active
+ * seat for automatic selection. Omitted → treated as empty (all roles
+ * unoccupied), which degrades to "first eligible worker role, else default".
+ */
+export function pickDefaultRole(
+  roles: Role[],
+  opts: { isFirstDrone: boolean; occupiedRoleIds?: ReadonlySet<string> }
+): Role | undefined {
+  if (opts.isFirstDrone) {
+    const humanSeat = roles.find((r) => r.is_human_seat);
+    if (humanSeat) return humanSeat;
+  }
+  const occupied = opts.occupiedRoleIds ?? new Set<string>();
+  const mandatory = roles.filter(
+    (r) => r.is_mandatory === true && r.role_class !== 'queen'
+  );
+  const eligible = roles.filter(
+    (r) => r.role_class !== 'queen' && !r.is_human_seat
+  );
+  return mandatory.find((r) => !occupied.has(r.id))
+    ?? eligible.find((r) => !occupied.has(r.id))
+    ?? roles.find((r) => r.is_default);
+}

package/src/roster-render.ts

@@ -0,0 +1,196 @@
+/**
+ * Pure renderer for the `borg_roster` MCP tool output.
+ *
+ * Split out from `index.ts` so the T2.1 sender-side liveness probe
+ * (the `awake`/`stale-since-X` column rendering when a `since` arg is
+ * passed) can be unit-tested without spinning up the MCP server. Same
+ * pure-function + injected-`humanAgo` pattern as `stream-status.ts`.
+ *
+ * Two modes:
+ *   - No `since` provided: classic roster — one line per drone with
+ *     label, role, and `last seen` relative time.
+ *   - `since` provided: each line additionally carries an `awake`
+ *     marker if the drone's `last_seen` is after the resolved
+ *     timestamp, otherwise a `stale-since-<relative>` marker derived
+ *     from the resolved timestamp the server echoed back.
+ */
+
+import { formatDroneAddressToken } from 'borgmcp-shared/drone-address';
+
+export interface RosterDrone {
+  id?: string;
+  label: string;
+  role_id: string;
+  last_seen: string | Date;
+  /** Only present when the request carried `since`. */
+  seen_since?: boolean;
+  /**
+   * gh#370 — which AI agent is running this drone. Null for drones that
+   * joined before the column existed or via a launcher path that didn't
+   * forward the kind. This is the agent CLI, not a model descriptor.
+   */
+  agent_kind?: 'claude' | 'codex' | 'opencode' | null;
+  regen_count?: number | null;
+  wake_path?: 'live' | 'degraded' | 'deaf' | null;
+  wake_path_alert_class?:
+    | 'dead'
+    | 'post-blocked'
+    | 'presumed-dead'
+    | 'systemic-post-block'
+    | 'wake-path-deaf'
+    | 'independent'
+    | null;
+  /** Legacy launch descriptor retained on the wire for the Ollama launch path; not displayed. */
+  model?: string | null;
+  /** Advisory model string self-reported by the agent on regen. */
+  reported_model?: string | null;
+  /** Current cwd-derived repository identity, refreshed on regen. */
+  working_repo_name?: string | null;
+  working_repo_origin?: string | null;
+}
+
+export interface RosterRole {
+  id: string;
+  name: string;
+  /**
+   * Default model descriptor for drones assigned to this role.
+   * Null = no role default (use cube default or null for Claude).
+   */
+  default_model?: string | null;
+}
+
+/**
+ * gh#503 — render-layer display labels for the wake-path wire enum.
+ *
+ * The gh#406 SLI MEASURES a streak of unanswered directed challenges; it
+ * cannot confirm a genuinely broken wake path ("deaf") — a seat that is
+ * alive but idle-and-text-only looks identical past the SLA. So the
+ * roster shows the measured-confidence label, not the unconfirmed verdict:
+ *   degraded (1 miss)  → `unverified`   (signal seen, not yet corroborated)
+ *   deaf     (2+ miss) → `unresponsive` (no response past the SLA)
+ *
+ * The wire enum VALUES (`live`/`degraded`/`deaf`), computed server-side by
+ * `wakePathFromStreak`, are intentionally UNCHANGED — this is a display-only
+ * relabel within gh#503's copy-only scope (renaming the enum would be a
+ * wire + schema change). An operator who wants a confirmed read cross-checks
+ * `borg_stream-status` on the affected seat. Unknown wire values fall back
+ * to the raw value so a newer server can't break an older client's roster.
+ */
+const WAKE_PATH_DISPLAY: Record<string, string> = {
+  degraded: 'unverified',
+  deaf: 'unresponsive',
+};
+
+export function formatRoleAgentLabel(
+  roleName: string,
+  agentKind: RosterDrone['agent_kind']
+): string {
+  const agentCli = agentKind === 'claude'
+    ? 'Claude Code'
+    : agentKind === 'codex'
+      ? 'Codex'
+      : agentKind === 'opencode'
+        ? 'OpenCode'
+        : 'not reported';
+  return `Role: ${roleName} · Agent CLI: ${agentCli}`;
+}
+
+export function formatWorkingRepoLabel(drone: Pick<RosterDrone, 'working_repo_name' | 'working_repo_origin'>): string {
+  if (drone.working_repo_name && drone.working_repo_origin) {
+    return `Working repo: ${drone.working_repo_name} · origin: ${drone.working_repo_origin}`;
+  }
+  if (drone.working_repo_name) return `Working repo: ${drone.working_repo_name}`;
+  if (drone.working_repo_origin) return `Working repo: origin: ${drone.working_repo_origin}`;
+  return 'Working repo: not reported';
+}
+
+export interface RenderRosterInputs {
+  cubeName: string;
+  drones: RosterDrone[];
+  roles: RosterRole[];
+  /**
+   * Server-echoed resolved timestamp (ISO-8601). Present iff caller
+   * passed `since` to `borg_roster`. Drives both the column header copy
+   * AND the relative-time label on `stale-since-X` cells.
+   */
+  resolvedSince: string | null;
+  /** Relative-time formatter, injected so the renderer is pure. */
+  humanAgo: (d: Date | string) => string;
+}
+
+export function renderRoster(inputs: RenderRosterInputs): string {
+  const { cubeName, drones, roles, resolvedSince, humanAgo } = inputs;
+  const roleById = new Map<string, RosterRole>();
+  for (const r of roles) roleById.set(r.id, r);
+
+  const lines: string[] = [];
+  lines.push(`# Drones in cube: ${cubeName}`);
+  lines.push('');
+
+  if (resolvedSince) {
+    // Surface the liveness-probe context so the reader knows what the
+    // `awake`/`stale-since-X` column is measured against.
+    lines.push(
+      `_Liveness probe since ${resolvedSince} (${humanAgo(
+        resolvedSince
+      )}). \`awake\` = drone posted to the cube log after that point._`
+    );
+    lines.push('');
+  }
+
+  if (!drones.length) {
+    lines.push('_(no drones connected)_');
+    return lines.join('\n');
+  }
+
+  for (const d of drones) {
+    const role = roleById.get(d.role_id);
+    const roleName = role?.name ?? 'unknown';
+    const roleLabel = formatRoleAgentLabel(roleName, d.agent_kind);
+    // gh#371: stable short-uuid address token beside the (renumber-prone) label.
+    const addr = d.id ? ` ${formatDroneAddressToken(d.id)}` : '';
+    const lastSeen = humanAgo(d.last_seen);
+    const reportedModelMarker = d.reported_model
+      ? ` · \`Reported model: ${d.reported_model}\``
+      : ' · `Reported model: not reported`';
+    const workingRepo = formatWorkingRepoLabel(d);
+    const workingRepoMarker = ` · \`${workingRepo}\``;
+    const wakePathMarker =
+      d.wake_path && d.wake_path !== 'live'
+        ? ` · \`wake-path:${WAKE_PATH_DISPLAY[d.wake_path] ?? d.wake_path}\``
+        : '';
+    const wakePathClassMarker =
+      d.wake_path_alert_class && d.wake_path_alert_class !== 'independent'
+        ? ` · \`wake-path-class:${d.wake_path_alert_class}\``
+        : '';
+    const regenCountMarker =
+      typeof d.regen_count === 'number' ? ` · \`regen-count:${d.regen_count}\`` : '';
+    if (resolvedSince) {
+      // T2.1 awake/stale column. `seen_since === true` → drone called a
+      // tool after the resolved timestamp; treat as awake. False or
+      // missing → stale. Missing should not happen when the server
+      // echoed a since, but defending against a shape mismatch is
+      // cheap and matches the renderer's no-server-assumptions
+      // discipline established in stream-status.ts.
+      //
+      // Per drone-4's polish NIT on the original T2.1 ship: the marker
+      // is just `stale` (not `stale-since-<relative>`) because the
+      // header already anchors the reference point and per-row "since
+      // when" would be identical across all stale rows in a single
+      // probe call — pure redundancy. The per-row `last seen X ago`
+      // field carries the diagnostic detail for "how stale is this
+      // particular drone."
+      const isAwake = d.seen_since === true;
+      const marker = isAwake ? '`awake`' : '`stale`';
+      lines.push(
+        `- **${d.label}**${addr} (${roleLabel}) — last seen ${lastSeen} · ${marker}${regenCountMarker}${wakePathMarker}${wakePathClassMarker}${reportedModelMarker}${workingRepoMarker}`
+      );
+    } else {
+      lines.push(
+        `- **${d.label}**${addr} (${roleLabel}) — last seen ${lastSeen}${regenCountMarker}${wakePathMarker}${wakePathClassMarker}${reportedModelMarker}${workingRepoMarker}`
+      );
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/seat-probe.ts

@@ -0,0 +1,115 @@
+// Shared per-seat liveness probe (gh#877 reuse).
+//
+// Extracted from cleanup-cmd.ts so BOTH `borg cleanup` (destructive → fail-SAFE)
+// and `borg launch-all` (constructive → fail-OPEN) can classify a saved seat by
+// ITS OWN token, without launch-all having to import cleanup-cmd's chalk/report
+// graph. cleanup-cmd re-exports `SeatStatus` for backwards compatibility.
+
+import { whoami } from './remote-client.js';
+import { DroneEvictedError } from './drone-lifecycle.js';
+import {
+  BorgServerError,
+  BorgServerHttpError,
+  BorgServerTrustError,
+  BorgServerUnreachableError,
+} from './server-errors.js';
+
+/**
+ * Eviction-probe verdict for ONE worktree's saved seat. Distinct CAUSES are
+ * preserved (CR #6 / CR5 — the probe must NOT collapse them). Each verdict is
+ * derived from the actual error TYPE/CODE, never from a mutable error-text regex:
+ *   evicted            ← 410 DRONE_EVICTED (terminal; the SOLE delete authority — gh#882 S1)
+ *   rejected           ← pin-matched drone-SESSION 401 carrying the EXACT typed
+ *                        SESSION_REJECTED code (revoked / taken over; recover via
+ *                        the offline `borg reset-local-seat` — never here)
+ *   credential-rejected← any OTHER 401 on the drone session (bare/untyped or a
+ *                        non-SESSION typed code): the saved credential is no longer
+ *                        accepted, but this is NON-DESTRUCTIVE — re-enroll, NEVER a
+ *                        seat reset and never a "restart the server" blip
+ *   trust-mismatch     ← the pinned server identity no longer matches (TYPED
+ *                        BorgServerTrustError; terminal — restarting does not fix it)
+ *   unreachable        ← transport failure: connection refused/reset, DNS, or a
+ *                        request timeout (TYPED BorgServerUnreachableError or a stable
+ *                        transport errno) — genuinely transient
+ *   endpoint-mismatch  ← a 404 from a verified server: the drone endpoint/protocol is
+ *                        not recognized (a client/server version mismatch)
+ *   server-failure     ← a 5xx from a verified server (its internal error; transient)
+ *   live               ← 200 (resolves)
+ *   indeterminate      ← any other ambiguous/unknown failure — never authorizes a
+ *                        delete or a seat reset
+ */
+export type SeatStatus =
+  | 'evicted'
+  | 'rejected'
+  | 'live'
+  | 'credential-rejected'
+  | 'trust-mismatch'
+  | 'unreachable'
+  | 'endpoint-mismatch'
+  | 'server-failure'
+  | 'indeterminate';
+
+// Stable transport-level errno / undici codes (a CODE check, not error-text). A
+// pinned-CA TLS failure and a refused/reset/timeout all surface one of these.
+const TRANSPORT_ERRNOS = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ENOTFOUND',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'ETIMEDOUT',
+  'EAI_AGAIN',
+  'EPIPE',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_SOCKET',
+  'ABORT_ERR',
+]);
+
+function isTransportFailure(err: unknown): boolean {
+  if (err instanceof BorgServerUnreachableError) return true;
+  const e = err as { name?: string; code?: string; cause?: { code?: string } };
+  if (e?.name === 'AbortError') return true;
+  const code = e?.code ?? e?.cause?.code;
+  return typeof code === 'string' && TRANSPORT_ERRNOS.has(code);
+}
+
+/**
+ * Default seat probe: a lightweight drone-authed `whoami` with the seat's OWN
+ * saved token. authedFetch throws TYPED errors on the authoritative outcomes
+ * (410→DroneEvictedError; pin-matched typed 401→BorgServerError('SESSION_REJECTED');
+ * every other 401→BorgServerError('CREDENTIAL_REJECTED'); a pinned-identity mismatch
+ * →BorgServerTrustError; a non-ok status→BorgServerHttpError(status); a transport
+ * failure/timeout→BorgServerUnreachableError). Each maps to a STABLE typed verdict
+ * so recovery copy is cause-accurate; the cleanup path must NEVER delete on anything
+ * but `evicted`; the launch path treats every non-`evicted`/non-terminal cause as
+ * fail-OPEN.
+ */
+export async function defaultProbeSeat(
+  sessionToken: string,
+  apiUrl: string,
+  serverTrustIdentity?: string,
+): Promise<SeatStatus> {
+  try {
+    await whoami(sessionToken, apiUrl, serverTrustIdentity);
+    return 'live';
+  } catch (err) {
+    if (err instanceof DroneEvictedError) return 'evicted';
+    // A pinned-identity / CA mismatch is a TERMINAL trust verdict — classified from
+    // the error TYPE, never from message text (the security boundary).
+    if (err instanceof BorgServerTrustError) return 'trust-mismatch';
+    if (err instanceof BorgServerError) {
+      if (err.code === 'SESSION_REJECTED') return 'rejected';
+      // Every non-SESSION 401 (bare/untyped or a different typed code) is a
+      // credential rejection — non-destructive, distinct from a takeover.
+      if (err.code === 'CREDENTIAL_REJECTED') return 'credential-rejected';
+    }
+    if (err instanceof BorgServerHttpError) {
+      if (err.status === 404) return 'endpoint-mismatch';
+      if (err.status >= 500 && err.status <= 599) return 'server-failure';
+      return 'indeterminate';
+    }
+    if (isTransportFailure(err)) return 'unreachable';
+    return 'indeterminate';
+  }
+}