borgmcp 2.16.1 → 3.0.2

package/src/cli-help.ts

@@ -16,16 +16,6 @@ export function isHelpFlag(arg: string | undefined): boolean {
   return arg === '--help' || arg === '-h';
 }
 
-export function syncHelpText(version: string): string {
-  return (
-    `borg sync (borgmcp ${version}) — update this Borg worktree from origin/main\n\n` +
-    `Usage:\n` +
-    `  borg sync             Update safely; refuse if the worktree is dirty\n` +
-    `  borg sync --prune     Also delete a merged local feature branch\n` +
-    `  borg sync --help      Show this help\n`
-  );
-}
-
 export function cleanupHelpText(version: string): string {
   return (
     `borg cleanup (borgmcp ${version}) — review orphaned Borg-managed worktrees\n\n` +
@@ -63,9 +53,8 @@ export function clientSubcommandHelpText(
   switch (command) {
     case 'setup': return setupHelpText(version);
     case 'assimilate': return assimilateHelpText(version);
-    case 'reset-local-seat': return resetLocalSeatHelpText(version);
+    case 'reset-local-connection': return resetLocalSeatHelpText(version);
     case 'recover-enrollment': return recoverEnrollmentHelpText(version);
-    case 'sync': return syncHelpText(version);
     case 'cleanup': return cleanupHelpText(version);
     case 'launch-all': return launchAllHelpText(version);
     default: return null;
@@ -101,9 +90,8 @@ export function topLevelHelpText(version: string): string {
     `  borg assimilate --host <host>   Join or create on an explicit server\n` +
     `  borg assimilate --worktree <name>   Spawn a worktree drone (in ~/.borg/worktrees/<repo>/<name>)\n` +
     `  borg server cube init    Initialize this repository's cube without creating a drone\n` +
-    `  borg reset-local-seat    Clear ONLY this worktree's saved local seat (offline; after a rejection)\n` +
+    `  borg reset-local-connection  Clear ONLY this worktree's saved connection to its cube (offline; after a rejection)\n` +
     `  borg recover-enrollment  Restore or clear ONLY one failed server enrollment transaction\n` +
-    `  borg sync [--prune]      Sync this worktree's branch to origin/main\n` +
     `  borg cleanup [--prune]   Report (or --prune) worktrees orphaned by evicted drones\n` +
     `  borg launch-all [cube]   Launch all drone worktrees of a cube (default: active cube)\n` +
     `  borg launch-all [cube] --cli claude|codex|opencode\n` +
@@ -157,8 +145,8 @@ export function serverHelpText(): string {
     `  update   Verify and activate a local server artifact.\n` +
     `  invite   Create a single-use invitation in an interactive terminal.\n` +
     `  cert-reissue  Widen the server certificate to cover another address without replacing the CA.\n` +
-    `  client-list   List enrolled clients, states, and cube grants while the server is stopped.\n` +
-    `  client-grant  Grant a client read, write, or manage access to a cube while the server is stopped.\n` +
+    `  client-list   List enrolled clients, states, and cube grants while the server is live; committed changes take effect on the next request.\n` +
+    `  client-grant  Grant a client read, write, or manage access to a cube while the server is live; committed changes take effect on the next request.\n` +
     `  dashboard   View the running local server dashboard.\n` +
     `  cube init   Initialize this Git repository's cube; does not create a drone.\n\n` +
     `Run borg server <command> --help for server command options.\n`
@@ -203,7 +191,7 @@ export function assimilateHelpText(version: string): string {
     `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` +
+    `  --force                    Reattach despite a still-live inbox monitor in this worktree\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` +
@@ -216,7 +204,7 @@ export function assimilateHelpText(version: string): string {
     `repository association skips all prompts. One accessible exact-name legacy cube requires\n` +
     `explicit interactive adoption; ambiguous matches fail closed. An enrolled owner client may\n` +
     `create an idempotent repository cube; ordinary clients require an explicit cube grant.\n` +
-    `Agent seats begin only after enrollment. Preview only.\n` +
+    `A drone is created only after enrollment. Preview only.\n` +
     `See docs/LOCAL_SERVER.md for self-hosted setup and current status.\n\n` +
     `For local or provider-specific models, configure the selected agent CLI directly.\n` +
     `OpenCode supports Ollama and other providers through its own model configuration.\n`
@@ -224,25 +212,25 @@ export function assimilateHelpText(version: string): string {
 }
 
 /**
- * Help text for `borg reset-local-seat --help`. The offline, network-free seat
+ * Help text for `borg reset-local-connection --help`. The offline, network-free seat
  * reset recommended by the pin-matched SESSION_REJECTED diagnostic (#1082).
  */
 export function resetLocalSeatHelpText(version: string): string {
   return (
-    `borg reset-local-seat (borgmcp ${version}) — clear ONLY this worktree's saved local seat\n\n` +
+    `borg reset-local-connection (borgmcp ${version}) — clear ONLY this worktree's saved connection to its cube\n\n` +
     `Offline and network-free: it contacts no server and revokes nothing server-side. It clears\n` +
-    `just this worktree's saved local seat — its credential and cube binding together — from the\n` +
-    `local seat store on this machine. Server, trust anchor, cube, and every sibling worktree are\n` +
+    `just this worktree's saved connection — its credential and cube binding together — from the\n` +
+    `private store on this machine. Server, trust anchor, cube, and every sibling worktree are\n` +
     `left untouched.\n\n` +
     `Use it after \`borg assimilate\` reports this worktree's session was revoked or superseded\n` +
     `(a pin-matched rejection), then ask the operator for a new invitation and re-enroll.\n\n` +
     `Usage:\n` +
-    `  borg reset-local-seat                 Reset this worktree's saved seat (TTY confirms [y/N])\n` +
-    `  borg reset-local-seat --host <host>   No-op unless this worktree's seat is on <host>\n` +
-    `  borg reset-local-seat --yes           Reset without a prompt (required when non-interactive)\n` +
-    `  borg reset-local-seat --help          Show this help\n\n` +
+    `  borg reset-local-connection                 Reset this worktree's saved connection (TTY confirms [y/N])\n` +
+    `  borg reset-local-connection --host <host>   No-op unless this worktree connects to <host>\n` +
+    `  borg reset-local-connection --yes           Reset without a prompt (required when non-interactive)\n` +
+    `  borg reset-local-connection --help          Show this help\n\n` +
     `Flags:\n` +
-    `  --host <host>              Only act if this worktree's saved seat is on <host> (else no-op)\n` +
+    `  --host <host>              Only act if this worktree connects to <host> (else no-op)\n` +
     `  --yes, -y                  Skip the confirmation prompt (required in non-TTY contexts)\n`
   );
 }

package/src/cli-platform.ts

@@ -1,6 +1,11 @@
 import which from 'which';
 import type { BorgCli } from './cubes.js';
 import { getProjectCliPreference, setProjectCliPreference } from './cubes.js';
+import {
+  isCodexMcpServerConfigured,
+  isMcpServerConfigured,
+  isOpenCodeMcpServerConfigured,
+} from './config-utils.js';
 
 export interface CliAvailability {
   claude: string | null;
@@ -8,8 +13,11 @@ export interface CliAvailability {
   opencode: string | null;
 }
 
+export type CliConfiguration = Record<BorgCli, boolean>;
+
 export interface CliChoiceDeps {
   detectCli: () => CliAvailability;
+  detectConfigured: () => CliConfiguration;
   getPreference: () => Promise<BorgCli | null>;
   setPreference: (cli: BorgCli) => Promise<void>;
   prompt: (message: string) => Promise<string>;
@@ -40,6 +48,21 @@ export function installedCliNames(availability: CliAvailability): BorgCli[] {
   return out;
 }
 
+export function detectCliConfiguration(): CliConfiguration {
+  return {
+    claude: isMcpServerConfigured(),
+    codex: isCodexMcpServerConfigured(),
+    opencode: isOpenCodeMcpServerConfigured(),
+  };
+}
+
+export function configuredCliNames(
+  availability: CliAvailability,
+  configuration: CliConfiguration,
+): BorgCli[] {
+  return installedCliNames(availability).filter((cli) => configuration[cli]);
+}
+
 async function setPreferenceAndReturn(cli: BorgCli, deps: CliChoiceDeps): Promise<BorgCli> {
   await deps.setPreference(cli);
   return cli;
@@ -59,31 +82,39 @@ export async function resolveCliChoice(
     if (!installed.includes(explicit)) {
       throw new Error(`${explicit} CLI is not installed.`);
     }
+    // An explicit --cli is an intentional request, so the caller may still
+    // configure that installed CLI on demand. Automatic selection below is
+    // restricted to registrations already present in the agent config.
     await deps.setPreference(explicit);
     return explicit;
   }
 
+  const configured = configuredCliNames(availability, deps.detectConfigured());
+  if (configured.length === 0) {
+    throw new Error('No supported agent CLI is configured for Borg. Run `borg setup` to configure one, then run `borg` or `borg assimilate` again.');
+  }
+
   const stored = await deps.getPreference();
-  if (stored && installed.includes(stored)) return stored;
+  if (stored && configured.includes(stored)) return stored;
 
-  if (installed.length === 1) {
-    await deps.setPreference(installed[0]);
-    return installed[0];
+  if (configured.length === 1) {
+    await deps.setPreference(configured[0]);
+    return configured[0];
   }
 
   if (!deps.isTTY()) {
-    throw new Error('Multiple agent CLIs detected. Pass --cli claude, --cli codex, or --cli opencode to choose.');
+    throw new Error('Multiple configured agent CLIs detected. Pass --cli claude, --cli codex, or --cli opencode to choose.');
   }
 
-  const promptLines = installed.map((cli, i) => `  ${i + 1}) ${cli}`);
+  const promptLines = configured.map((cli, i) => `  ${i + 1}) ${cli}`);
   const answer = (await deps.prompt(`Use which CLI for this project?\n${promptLines.join('\n')}\n[1]: `)).trim();
-  if (answer === '' || answer === '1') return setPreferenceAndReturn(installed[0], deps);
+  if (answer === '' || answer === '1') return setPreferenceAndReturn(configured[0], deps);
   const num = parseInt(answer, 10);
-  if (!Number.isNaN(num) && num >= 1 && num <= installed.length) {
-    return setPreferenceAndReturn(installed[num - 1], deps);
+  if (!Number.isNaN(num) && num >= 1 && num <= configured.length) {
+    return setPreferenceAndReturn(configured[num - 1], deps);
   }
   const lower = answer.toLowerCase();
-  for (const cli of installed) {
+  for (const cli of configured) {
     if (lower === cli) return setPreferenceAndReturn(cli, deps);
   }
   throw new Error(`invalid CLI choice "${answer}"`);
@@ -92,6 +123,7 @@ export async function resolveCliChoice(
 export function defaultCliChoiceDeps(prompt: (message: string) => Promise<string>, isTTY: () => boolean): CliChoiceDeps {
   return {
     detectCli: detectCliAvailability,
+    detectConfigured: detectCliConfiguration,
     getPreference: getProjectCliPreference,
     setPreference: setProjectCliPreference,
     prompt,

package/src/cubes.ts

@@ -84,6 +84,13 @@ interface LaunchFile {
   projects: Record<string, { cli: BorgCli }>;
 }
 
+const UNREADABLE_STATE = Symbol('unreadable-state-file');
+type StateFileRead<T> = T | null | typeof UNREADABLE_STATE;
+
+function unreadableStateError(filePath: string): Error {
+  return new Error(`Borg state file is unreadable; refusing to overwrite it: ${filePath}`);
+}
+
 export interface CodexWakeTargetRecord {
   threadId: string;
   socketPath: string;
@@ -110,7 +117,7 @@ let pinnedMcpSeatIdentity: {
 export class McpSeatIdentityChangedError extends Error {
   readonly code = 'SEAT_IDENTITY_CHANGED';
   constructor() {
-    super('The saved Borg seat changed after this MCP session pinned its identity. Exit this session and relaunch from the intended worktree.');
+    super('This worktree\'s saved connection changed after this MCP session pinned its identity. Exit this session and relaunch from the intended worktree.');
     this.name = 'McpSeatIdentityChangedError';
   }
 }
@@ -225,7 +232,7 @@ function isLaunchFile(data: any): data is LaunchFile {
   );
 }
 
-async function readLaunchFile(): Promise<LaunchFile | null> {
+async function readLaunchFile(): Promise<StateFileRead<LaunchFile>> {
   let raw: string;
   try {
     raw = await readFile(LAUNCH_FILE, 'utf8');
@@ -235,9 +242,9 @@ async function readLaunchFile(): Promise<LaunchFile | null> {
   }
   try {
     const parsed = JSON.parse(raw);
-    return isLaunchFile(parsed) ? parsed : null;
+    return isLaunchFile(parsed) ? parsed : UNREADABLE_STATE;
   } catch {
-    return null;
+    return UNREADABLE_STATE;
   }
 }
 
@@ -263,7 +270,7 @@ function isCodexWakeTargetsFile(data: any): data is CodexWakeTargetsFile {
   );
 }
 
-async function readCodexWakeTargetsFile(): Promise<CodexWakeTargetsFile | null> {
+async function readCodexWakeTargetsFile(): Promise<StateFileRead<CodexWakeTargetsFile>> {
   let raw: string;
   try {
     raw = await readFile(CODEX_WAKE_TARGETS_FILE, 'utf8');
@@ -273,9 +280,9 @@ async function readCodexWakeTargetsFile(): Promise<CodexWakeTargetsFile | null>
   }
   try {
     const parsed = JSON.parse(raw);
-    return isCodexWakeTargetsFile(parsed) ? parsed : null;
+    return isCodexWakeTargetsFile(parsed) ? parsed : UNREADABLE_STATE;
   } catch {
-    return null;
+    return UNREADABLE_STATE;
   }
 }
 
@@ -439,7 +446,7 @@ export async function snapshotLocalSeat(): Promise<LocalSeatSnapshot | null> {
   // CR#4: discover an ACTIVE seat OR a bound-PENDING record (a sibling whose
   // activation failed, bound to THIS worktree by the attach bind-pending step).
   // getActiveSeatForWorktree would MISS the bound-pending record (it requires
-  // state==='active' + a drone id), so `reset-local-seat` would FALSELY report
+  // state==='active' + a drone id), so `reset-local-connection` would FALSELY report
   // "nothing to reset" (exit 0) while a resumable, server-digest-bound bearer
   // persists at rest — a FALSE-SUCCESS revocation failure. getSeatForWorktree sees
   // both, and the offline reset's exact re-check + delete cover the bound-pending
@@ -574,6 +581,7 @@ export async function refreshActiveCubeMetadata(active: ActiveCubeInput): Promis
 
 export async function getProjectCliPreference(): Promise<BorgCli | null> {
   const data = await readLaunchFile();
+  if (data === UNREADABLE_STATE) throw unreadableStateError(LAUNCH_FILE);
   if (!data) return null;
   const entry = data.projects[findProjectRoot()];
   return entry?.cli === 'claude' || entry?.cli === 'codex' || entry?.cli === 'opencode' ? entry.cli : null;
@@ -586,6 +594,7 @@ export async function getProjectCliPreference(): Promise<BorgCli | null> {
  */
 export async function getProjectCliPreferenceForPath(dir: string): Promise<BorgCli | null> {
   const data = await readLaunchFile();
+  if (data === UNREADABLE_STATE) throw unreadableStateError(LAUNCH_FILE);
   if (!data) return null;
   const entry = data.projects[findProjectRoot(dir)];
   return entry?.cli === 'claude' || entry?.cli === 'codex' || entry?.cli === 'opencode' ? entry.cli : null;
@@ -617,9 +626,11 @@ export async function readAllProjectIdentities(): Promise<
  * sibling worktree but the process still began in the invoking checkout.
  */
 export async function setProjectCliPreference(cli: BorgCli, dir?: string): Promise<void> {
-  const existing = (await readLaunchFile()) ?? { projects: {} };
-  existing.projects[findProjectRoot(dir)] = { cli };
-  await writeLaunchFile(existing);
+  const existing = await readLaunchFile();
+  if (existing === UNREADABLE_STATE) throw unreadableStateError(LAUNCH_FILE);
+  const next = existing ?? { projects: {} };
+  next.projects[findProjectRoot(dir)] = { cli };
+  await writeLaunchFile(next);
 }
 
 export async function setCodexWakeTarget(
@@ -627,12 +638,14 @@ export async function setCodexWakeTarget(
   droneId: string,
   target: Omit<CodexWakeTargetRecord, 'updatedAt'>
 ): Promise<void> {
-  const existing = (await readCodexWakeTargetsFile()) ?? { targets: {} };
-  existing.targets[codexWakeTargetKey(cubeId, droneId)] = {
+  const existing = await readCodexWakeTargetsFile();
+  if (existing === UNREADABLE_STATE) throw unreadableStateError(CODEX_WAKE_TARGETS_FILE);
+  const next = existing ?? { targets: {} };
+  next.targets[codexWakeTargetKey(cubeId, droneId)] = {
     ...target,
     updatedAt: new Date().toISOString(),
   };
-  await writeCodexWakeTargetsFile(existing);
+  await writeCodexWakeTargetsFile(next);
 }
 
 export async function getCodexWakeTarget(
@@ -640,6 +653,7 @@ export async function getCodexWakeTarget(
   droneId: string
 ): Promise<CodexWakeTargetRecord | null> {
   const existing = await readCodexWakeTargetsFile();
+  if (existing === UNREADABLE_STATE) throw unreadableStateError(CODEX_WAKE_TARGETS_FILE);
   if (!existing) return null;
   const target = existing.targets[codexWakeTargetKey(cubeId, droneId)];
   if (!target || typeof target.threadId !== 'string' || typeof target.socketPath !== 'string') {
@@ -661,6 +675,7 @@ export async function pruneDeadCodexWakeTargets(
   socketLiveness: (socketPath: string) => boolean | null
 ): Promise<void> {
   const existing = await readCodexWakeTargetsFile();
+  if (existing === UNREADABLE_STATE) throw unreadableStateError(CODEX_WAKE_TARGETS_FILE);
   if (!existing) return;
   const { targets, changed } = pruneDeadWakeTargets(existing.targets, socketLiveness);
   if (changed) await writeCodexWakeTargetsFile({ ...existing, targets });

package/src/docs-sections.ts

@@ -78,7 +78,7 @@ export const DOCS_SECTIONS: DocsSection[] = [
     url: SEAT_LIFECYCLE_URL,
     page: "docs/SEAT_LIFECYCLE.md",
     summary: "Saved-seat states, re-attach and reset recovery, duplicate-session guards, and deterministic multi-seat selection.",
-    keywords: ["seat", "lifecycle", "reattach", "re-attach", "reset-local-seat", "evicted", "revoked", "superseded", "inbox monitor", "multiple seats", "silent deafness"],
+    keywords: ["seat", "lifecycle", "reattach", "re-attach", "reset-local-connection", "evicted", "revoked", "superseded", "inbox monitor", "multiple seats", "silent deafness"],
   },
   {
     slug: "self-hosting",

package/src/drone-lifecycle.ts

@@ -16,7 +16,7 @@ export const CUBE_DELETED_CODE = 'CUBE_DELETED';
 
 export class DroneEvictedError extends Error {
   constructor(
-    message = 'This seat was removed from the cube.'
+    message = 'This drone was removed from the cube.'
   ) {
     super(message);
     this.name = 'DroneEvictedError';
@@ -45,8 +45,8 @@ export const CUBE_DELETED_RESULT_MARKER = '[CUBE-DELETED]';
 export function formatEvictedToolResult(cubeName?: string): string {
   const cube = cubeName ?? 'the selected cube';
   return (
-    `${EVICTED_RESULT_MARKER} This seat was removed from cube ${cube}.\n\n` +
-    'Borg has stopped listening for activity for this seat. Do not retry this request or restart the loop.\n\n' +
+    `${EVICTED_RESULT_MARKER} This drone was removed from cube ${cube}.\n\n` +
+    'Borg has stopped listening for activity for this drone. Do not retry this request or restart the loop.\n\n' +
     'Your worktree and project files are unchanged. Finish any local file safety checks, then end this agent session.\n\n' +
     'To rejoin later, start a new session and use a new invitation from the server operator. Do not re-assimilate from this evicted session.'
   );

package/src/drone-management.ts

@@ -50,7 +50,7 @@ const defaultDeps: DroneManagementDeps = {
 };
 
 export const STALE_ROLE_DISPLAY_WARNING =
-  'Local display warning: The server committed this change, but Borg could not refresh this worktree\'s saved seat metadata. Local role details may be stale. Do not retry the reassignment.\n\n' +
+  'Local display warning: The server committed this change, but Borg could not refresh this worktree\'s saved connection metadata. Local role details may be stale. Do not retry the reassignment.\n\n' +
   'Run `borg_regen` to refresh the server-authoritative role. If this session still shows the previous role, restart this agent session once. Do not re-assimilate or repeat the management request.';
 
 function opaqueNotFound(): never {

package/src/evict-drone.ts

@@ -75,8 +75,8 @@ export function formatReassignDroneSuccess(input: {
 export function formatEvictDroneSuccess(droneLabel: string, cubeName: string): string {
   return (
     `Removed ${droneLabel} from cube ${cubeName}.\n` +
-    'The seat credential is revoked. The session will stop after its next Borg request.\n' +
-    'The worktree and project files were not deleted. Activity history remains attributed to the removed seat.\n' +
+    'The drone\'s credential is revoked. The session will stop after its next Borg request.\n' +
+    'The worktree and project files were not deleted. Activity history remains attributed to the removed drone.\n' +
     'After its work is merged, run `borg cleanup` to review whether the worktree can be pruned.'
   );
 }

package/src/first-run-server.ts

@@ -177,8 +177,11 @@ export async function offerFirstRunServerInstall(
       : decision === 'eof'
         ? 'Installation was cancelled because confirmation input ended.'
         : 'Installation was declined.';
+    const setupRecovery = options.initializeServer
+      ? ', and no agent configuration was written. Run `borg setup` again to configure your agents.'
+      : '.';
     deps.stderr(
-      `${reason} No server package or server state was changed.\n` +
+      `${reason} No server package or server state was changed${setupRecovery}\n` +
       `To install it later, run \`${command}\`. Then run \`borg server setup\` and \`borg server start\`.\n`,
     );
     return { kind: 'declined' };

package/src/foreign-path-reminder.ts

@@ -17,7 +17,7 @@ import {
   BORG_LAUNCH_WORKTREE_ENV,
 } from './launch-access.js';
 
-const REMINDER = 'Reminder: this seat is scoped to its own worktree and scratch root; coordinate before working on a foreign path.';
+const REMINDER = 'Reminder: this drone is scoped to its own worktree and scratch root; coordinate before working on a foreign path.';
 
 const PATH_KEYS = new Set([
   'cwd',

package/src/inbox-monitor.ts

@@ -797,8 +797,8 @@ function liveMonitorYieldLine(
     : null;
   const holder = livePid === null ? 'another monitor instance' : `a live instance (pid ${livePid})`;
   return (
-    `borg-inbox-monitor: seat inbox ${JSON.stringify(inboxPath)} is already monitored by ${holder}; ` +
-    'yielding — another session likely holds this seat.'
+    `borg-inbox-monitor: inbox ${JSON.stringify(inboxPath)} is already monitored by ${holder}; ` +
+    'yielding — another session likely holds this worktree\'s connection.'
   );
 }
 

package/src/index.ts

@@ -561,7 +561,7 @@ export async function main() {
               `# Re-attached to cube: ${displayIdentity.cubeName}`,
               ``,
               `**Drone label:** ${displayIdentity.droneLabel}`,
-              `**Seat:** existing identity reused — no new drone minted (gh#780)`,
+              `**Drone:** existing identity reused — no new drone minted (gh#780)`,
               ``,
               ``,
             ].join('\n');

package/src/launch-all-cmd.ts

@@ -53,7 +53,7 @@ async function resolveTargetCube(
     const identities = await deps.readAllProjectIdentities();
     const matches = identities.filter((e) => e.cube.name === args.cubeName);
     if (matches.length === 0) {
-      return { error: `no cube named '${args.cubeName}' found among this machine's saved seats — has any drone assimilated into it?` };
+      return { error: `no cube named '${args.cubeName}' found among this machine's saved connections — has any drone assimilated into it?` };
     }
     // gh#850: distinct cubes can share a name (same name across accounts/
     // environments, or a stale seat). Silently taking matches[0] could launch
@@ -61,13 +61,13 @@ async function resolveTargetCube(
     // cubeId + the project that holds the seat and refuse to guess.
     if (matches.length > 1) {
       const list = matches
-        .map((m) => `  ${m.cube.cubeId}  (seat in ${m.projectPath})`)
+        .map((m) => `  ${m.cube.cubeId}  (drone in ${m.projectPath})`)
         .join('\n');
       return {
         error:
-          `'${args.cubeName}' is ambiguous — ${matches.length} saved seats on this machine share that name:\n${list}\n` +
+          `'${args.cubeName}' is ambiguous — ${matches.length} saved connections on this machine share that name:\n${list}\n` +
           'cd into the intended project and re-run without --cube-name (resolves the active cube), ' +
-          'or clear the stale seat(s) by running `borg reset-local-seat` from the worktree that holds each.',
+          'or clear the stale connection(s) by running `borg reset-local-connection` from the worktree that holds each.',
       };
     }
     return { cubeId: matches[0].cube.cubeId, name: args.cubeName };
@@ -237,7 +237,7 @@ export async function runLaunchAll(
       }
     } else {
       deps.stdout(
-        `No worktrees found for cube '${cubeName}' — have you run \`borg assimilate --worktree\` to create any drone seats?\n`
+        `No worktrees found for cube '${cubeName}' — have you run \`borg assimilate --worktree\` to create any drones?\n`
       );
     }
     return 0;
@@ -290,8 +290,8 @@ export async function runLaunchAll(
     if (status === 'evicted') {
       evictedCount += 1;
       deps.stderr(
-        `skipping ${c.droneLabel} (${c.worktreeDir}): seat no longer in cube (evicted) — ` +
-          `run \`borg cleanup --prune\` to remove the worktree, or \`borg assimilate\` to re-seat fresh.\n`
+        `skipping ${c.droneLabel} (${c.worktreeDir}): drone no longer in cube (evicted) — ` +
+          `run \`borg cleanup --prune\` to remove the worktree, or \`borg assimilate\` to start fresh.\n`
       );
       continue;
     }
@@ -299,7 +299,7 @@ export async function runLaunchAll(
       revokedCount += 1;
       deps.stderr(
         `Local session was revoked.\n` +
-          `Next: run borg reset-local-seat, then borg assimilate --host ${c.apiUrl} --enroll.\n`
+          `Next: run borg reset-local-connection, then borg assimilate --host ${c.apiUrl} --enroll.\n`
       );
       continue;
     }
@@ -307,7 +307,7 @@ export async function runLaunchAll(
       rejectedCount += 1;
       deps.stderr(
         `Local session was superseded by a newer enrollment.\n` +
-          `Next: run borg reset-local-seat, then borg assimilate --host ${c.apiUrl} --enroll.\n`
+          `Next: run borg reset-local-connection, then borg assimilate --host ${c.apiUrl} --enroll.\n`
       );
       continue;
     }
@@ -336,7 +336,7 @@ export async function runLaunchAll(
     // cause-accurate note. Only the authoritative/terminal causes above skip.
     if (status === 'unreachable') {
       deps.stderr(
-        `note: could not reach ${c.droneLabel}'s server to confirm its seat (network/timeout) — launching anyway.\n`
+        `note: could not reach ${c.droneLabel}'s server to confirm that drone (network/timeout) — launching anyway.\n`
       );
     } else if (status === 'endpoint-mismatch') {
       deps.stderr(
@@ -344,11 +344,11 @@ export async function runLaunchAll(
       );
     } else if (status === 'server-failure') {
       deps.stderr(
-        `note: ${c.droneLabel}'s server returned an error while confirming its seat (transient) — launching anyway.\n`
+        `note: ${c.droneLabel}'s server returned an error while confirming that drone (transient) — launching anyway.\n`
       );
     } else if (status === 'indeterminate') {
       deps.stderr(
-        `note: could not confirm ${c.droneLabel}'s seat is live (network/transient) — launching anyway.\n`
+        `note: could not confirm ${c.droneLabel} is live (network/transient) — launching anyway.\n`
       );
     }
     launchable.push(c);

package/src/launch-all-discovery.ts

@@ -95,7 +95,7 @@ export async function discoverDroneCandidates(
     // 4. malformed entry (cubeId/droneId not UUID) → warn + skip
     if (!isUuid(cube.cubeId) || !isUuid(cube.droneId)) {
       deps.stderr(
-        `skipping ${worktreeDir}: its saved seat has a malformed cubeId/droneId — re-assimilate to fix\n`
+        `skipping ${worktreeDir}: its saved connection has a malformed cubeId/droneId — re-assimilate to fix\n`
       );
       continue;
     }

package/src/lifecycle-log-guard.ts

@@ -28,6 +28,15 @@ interface LifecycleStateFile {
   entries: Record<string, LifecycleStateEntry>;
 }
 
+const UNREADABLE_STATE = Symbol('unreadable-lifecycle-state');
+type LifecycleStateRead = LifecycleStateFile | typeof UNREADABLE_STATE;
+
+function unreadableStateError(): Error {
+  return new Error(
+    `Lifecycle log state is unreadable; refusing to overwrite it: ${STATE_FILE}`,
+  );
+}
+
 export function lifecycleSignalForMessage(message: string): LifecycleSignal | null {
   if (message.startsWith('ARRIVAL: ')) return 'arrival';
   if (
@@ -44,7 +53,7 @@ function stateKey(subject: LifecycleLogSubject): string {
   return `${subject.cubeId}:${subject.droneId}`;
 }
 
-async function readState(): Promise<LifecycleStateFile> {
+async function readState(): Promise<LifecycleStateRead> {
   try {
     const raw = await readFile(STATE_FILE, 'utf8');
     const parsed = JSON.parse(raw);
@@ -58,9 +67,10 @@ async function readState(): Promise<LifecycleStateFile> {
       return parsed as LifecycleStateFile;
     }
   } catch (err: any) {
-    if (err?.code !== 'ENOENT') throw err;
+    if (err?.code === 'ENOENT') return { entries: {} };
+    return UNREADABLE_STATE;
   }
-  return { entries: {} };
+  return UNREADABLE_STATE;
 }
 
 async function writeState(state: LifecycleStateFile): Promise<void> {
@@ -100,6 +110,7 @@ export async function shouldSuppressLifecycleLog(
   message: string
 ): Promise<{ suppress: boolean; signal: LifecycleSignal | null }> {
   const state = await readState();
+  if (state === UNREADABLE_STATE) throw unreadableStateError();
   return shouldSuppressLifecycleLogFromState(
     message,
     state.entries[stateKey(subject)]
@@ -138,6 +149,7 @@ export async function recordLifecycleLog(
   message: string
 ): Promise<void> {
   const state = await readState();
+  if (state === UNREADABLE_STATE) throw unreadableStateError();
   const key = stateKey(subject);
   state.entries[key] = nextLifecycleStateAfterLog(message, state.entries[key]);
   await writeState(state);

package/src/opencode-seat-identity.ts

@@ -71,14 +71,14 @@ export async function resolveOpenCodeSeatIdentity(
   if (!active) {
     throw new OpenCodeSeatIdentityError(
       'SEAT_NOT_FOUND',
-      'No active Borg seat is bound to the OpenCode session directory.',
+      'No Borg drone is bound to the OpenCode session directory.',
       sessionWorktree,
     );
   }
   if (typeof active.worktree !== 'string' || resolve(active.worktree) !== resolve(sessionWorktree)) {
     throw new OpenCodeSeatIdentityError(
       'SEAT_WORKTREE_MISMATCH',
-      'The resolved Borg seat belongs to a different worktree than the OpenCode session.',
+      'The resolved Borg drone belongs to a different worktree than the OpenCode session.',
       sessionWorktree,
       active,
     );
@@ -93,19 +93,19 @@ export function formatOpenCodeSeatIdentityError(
   childCwd: string,
 ): string {
   const lines = [
-    `Borg OpenCode seat identity error [${error.code}]`,
+    `Borg OpenCode identity error [${error.code}]`,
     '',
     error.message,
     `- OpenCode session directory: ${error.sessionDirectory ?? 'unavailable'}`,
     `- Borg MCP child cwd: ${childCwd}`,
   ];
   if (error.seat) {
-    lines.push(`- Resolved seat: ${error.seat.droneLabel} (${error.seat.worktree})`);
+    lines.push(`- Resolved drone: ${error.seat.droneLabel} (${error.seat.worktree})`);
   }
   lines.push(
     '',
     'The Borg stream and OpenCode wake injection were not started.',
-    'Exit this session and run `borg --cli opencode` from the intended worktree. If that worktree’s saved seat is stale, run `borg reset-local-seat` from that exact worktree before assimilating again.',
+    'Exit this session and run `borg --cli opencode` from the intended worktree. If that worktree\'s saved connection is stale, run `borg reset-local-connection` from that exact worktree before assimilating again.',
   );
   return lines.join('\n');
 }

package/src/regen-format.ts

@@ -6,6 +6,7 @@
  * index.ts's stdio MCP server bootstrap.
  */
 
+import { hostname as osHostname } from 'node:os';
 import {
   ROLE_SCOPED_SAFETY_DISCIPLINES,
   UNIVERSAL_SAFETY_DISCIPLINES,
@@ -243,7 +244,7 @@ export function markArrivalAnnouncedThisProcess(): void {
 export function getDronePlaybook(): string {
   const arrivalInstruction = arrivalAnnouncedThisProcess
     ? ''
-    : '\n**When this MCP session first starts:** post one `ARRIVAL: <your-label> (<your-role>) online on <hostname>` (run `hostname`). After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit `/mcp` reconnect may show it again.\n';
+    : `\n**When this MCP session first starts:** post one \`ARRIVAL: <your-label> (<your-role>) online on ${osHostname()}\`. After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit \`/mcp\` reconnect may show it again.\n`;
   return `## How to operate as a Drone
 
 You're a Drone in a Cube. Coordinate with other drones through the activity log.