borgmcp 2.7.1 → 2.7.3

package/src/opencode-seat-identity.ts

@@ -0,0 +1,111 @@
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import type { ActiveCube } from './cubes.js';
+
+export type OpenCodeSeatIdentityErrorCode =
+  | 'ROOTS_UNAVAILABLE'
+  | 'ROOTS_INVALID'
+  | 'SEAT_NOT_FOUND'
+  | 'SEAT_WORKTREE_MISMATCH';
+
+export class OpenCodeSeatIdentityError extends Error {
+  constructor(
+    public readonly code: OpenCodeSeatIdentityErrorCode,
+    message: string,
+    public readonly sessionDirectory?: string,
+    public readonly seat?: Pick<ActiveCube, 'droneLabel' | 'worktree'>,
+  ) {
+    super(message);
+    this.name = 'OpenCodeSeatIdentityError';
+  }
+}
+
+export interface OpenCodeSeatIdentityDeps {
+  listRoots: () => Promise<{ roots?: Array<{ uri?: string }> }>;
+  findProjectRoot: (directory: string) => string;
+  getActiveCubeForWorktree: (worktree: string) => Promise<ActiveCube | null>;
+  pinSeatIdentity: (active: ActiveCube) => void;
+  childCwd: string;
+}
+
+export async function resolveOpenCodeSeatIdentity(
+  deps: OpenCodeSeatIdentityDeps,
+): Promise<ActiveCube> {
+  let roots: { roots?: Array<{ uri?: string }> };
+  try {
+    roots = await deps.listRoots();
+  } catch {
+    throw new OpenCodeSeatIdentityError(
+      'ROOTS_UNAVAILABLE',
+      'OpenCode did not provide its session directory.',
+    );
+  }
+  if (!Array.isArray(roots.roots) || roots.roots.length !== 1) {
+    throw new OpenCodeSeatIdentityError(
+      'ROOTS_INVALID',
+      'OpenCode must provide exactly one local session directory.',
+    );
+  }
+  const uri = roots.roots[0]?.uri;
+  let sessionDirectory: string;
+  try {
+    const parsed = new URL(typeof uri === 'string' ? uri : '');
+    if (parsed.protocol !== 'file:' || parsed.hostname || parsed.search || parsed.hash) throw new Error();
+    sessionDirectory = resolve(fileURLToPath(parsed));
+  } catch {
+    throw new OpenCodeSeatIdentityError(
+      'ROOTS_INVALID',
+      'OpenCode provided an invalid or non-local session directory.',
+    );
+  }
+
+  const sessionWorktree = deps.findProjectRoot(sessionDirectory);
+  const cwdWorktree = deps.findProjectRoot(deps.childCwd);
+  // Direct `borg` launch keeps cwd as its seat source. When a shared OpenCode
+  // server spawns the MCP child elsewhere, the session-scoped root is the
+  // launcher-conferred pin and replaces that ambient cwd inference.
+  const identityWorktree = cwdWorktree === sessionWorktree
+    ? cwdWorktree
+    : sessionWorktree;
+  const active = await deps.getActiveCubeForWorktree(identityWorktree);
+  if (!active) {
+    throw new OpenCodeSeatIdentityError(
+      'SEAT_NOT_FOUND',
+      'No active Borg seat 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.',
+      sessionWorktree,
+      active,
+    );
+  }
+
+  deps.pinSeatIdentity(active);
+  return active;
+}
+
+export function formatOpenCodeSeatIdentityError(
+  error: OpenCodeSeatIdentityError,
+  childCwd: string,
+): string {
+  const lines = [
+    `Borg OpenCode seat 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(
+    '',
+    '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.',
+  );
+  return lines.join('\n');
+}

package/src/server-facade.ts

@@ -12,6 +12,7 @@ export type ParsedServerFacadeArgs =
   | { kind: 'help' }
   | { kind: 'cube-init-help' }
   | { kind: 'cube-init'; args: string[] }
+  | { kind: 'command-help'; command: ServerLifecycleCommand }
   | { kind: 'command'; command: ServerLifecycleCommand; args: string[] }
   | { kind: 'error'; reason: 'unknown-command'; command: string };
 
@@ -33,6 +34,9 @@ export function parseServerFacadeArgs(args: readonly string[]): ParsedServerFaca
   if (!(SERVER_LIFECYCLE_COMMANDS as readonly string[]).includes(command)) {
     return { kind: 'error', reason: 'unknown-command', command };
   }
+  if (rest.some(isHelpFlag)) {
+    return { kind: 'command-help', command: command as ServerLifecycleCommand };
+  }
   return {
     kind: 'command',
     command: command as ServerLifecycleCommand,
@@ -163,6 +167,13 @@ export function unknownServerCommandText(command: string): string {
   );
 }
 
+export function serverLifecycleHelpText(command: ServerLifecycleCommand): string {
+  return (
+    `Usage: borg server ${command} [arguments]\n\n` +
+    `Command arguments are server-owned and pass to the verified borg-mcp-server executable when run.\n`
+  );
+}
+
 export function missingServerExecutableText(command: ServerLifecycleCommand): string {
   return (
     `Local server command is unavailable: borg-mcp-server was not found.\n` +
@@ -256,6 +267,10 @@ export async function runEarlyServerFacade(
     output.writeStdout(cubeInitHelpText(getPackageVersion()));
     return 0;
   }
+  if (parsed.kind === 'command-help') {
+    output.writeStdout(serverLifecycleHelpText(parsed.command));
+    return 0;
+  }
   if (parsed.kind === 'error') {
     output.writeStderr(unknownServerCommandText(parsed.command));
     return 1;

package/src/setup.ts

@@ -38,6 +38,7 @@ import { handleVersionFlag } from './version.js';
 import { initDebugFromArgv } from './debug.js';
 import { defaultApprovalIo, setupApprovalWarnings } from './cli-tool-approval.js';
 import { offerFirstRunServerInstall } from './first-run-server.js';
+import { setupNextStepsText } from './cli-help.js';
 
 /**
  * Main setup wizard
@@ -184,10 +185,7 @@ async function main() {
   // Success message
   console.log(chalk.green.bold('\nSetup complete!\n'));
   console.log(chalk.yellow('🔄 Restart Claude Code / Codex / OpenCode (or open a new session) for the changes to take effect.\n'));
-  console.log(chalk.gray('◼ Next steps:'));
-  console.log(chalk.gray('1. cd into your project, then run "borg assimilate --host <host>" to join a cube'));
-  console.log(chalk.gray('   (this connects to your local server and launches your agent)'));
-  console.log(chalk.gray('2. Use `borg assimilate --host <host> --enroll` from the operator terminal to enroll a new client\n'));
+  console.log(chalk.gray(setupNextStepsText()));
 }
 
 // Run wizard

package/src/startup-services.ts

@@ -16,10 +16,16 @@ export interface McpStartupServices {
  */
 export async function runMcpStartupServices(
   readinessProbe: boolean,
-  services: McpStartupServices
+  services: McpStartupServices,
+  options: { openCodeFirst?: boolean } = {},
 ): Promise<void> {
   if (readinessProbe) return;
-  const tasks = [
+  const tasks = options.openCodeFirst ? [
+    services.sessionStartHook,
+    services.auditHook,
+    services.openCode,
+    services.sseStream,
+  ] : [
     services.sessionStartHook,
     services.auditHook,
     services.sseStream,

package/src/stream-owner.ts

@@ -24,6 +24,9 @@ export interface StreamOwnerRecord {
   cwd: string;
   startedAt: string;
   heartbeatAt: string;
+  worktree?: string;
+  droneLabel?: string;
+  cubeName?: string;
 }
 
 export interface StreamOwnershipSnapshot {
@@ -33,6 +36,9 @@ export interface StreamOwnershipSnapshot {
   cwd?: string;
   startedAt?: string;
   heartbeatAt?: string;
+  worktree?: string;
+  droneLabel?: string;
+  cubeName?: string;
   ageMs?: number;
   lockPath?: string;
   /** Opened-directory identity used to bind inspection to later takeover. */
@@ -54,6 +60,9 @@ export interface StreamOwnerDeps {
   locksDir?: string;
   processNonce?: string;
   processStartedAt?: string;
+  worktree?: string;
+  droneLabel?: string;
+  cubeName?: string;
   isPidAlive?: (pid: number) => boolean;
   beforeTakeoverVerify?: (takeoverPath: string) => Promise<void>;
   beforeLeaseRefreshMutation?: (lockPath: string) => Promise<void>;
@@ -177,6 +186,9 @@ export async function readOwnershipSnapshot(
     cwd: parsed.cwd,
     startedAt: parsed.startedAt,
     heartbeatAt: parsed.heartbeatAt,
+    worktree: parsed.worktree,
+    droneLabel: parsed.droneLabel,
+    cubeName: parsed.cubeName,
     ageMs,
     lockPath,
     lockDev: lockStat.dev,
@@ -572,7 +584,10 @@ function sameOwner(left: StreamOwnerRecord, right: StreamOwnerRecord): boolean {
     left.processNonce === right.processNonce &&
     left.cwd === right.cwd &&
     left.startedAt === right.startedAt &&
-    left.heartbeatAt === right.heartbeatAt;
+    left.heartbeatAt === right.heartbeatAt &&
+    left.worktree === right.worktree &&
+    left.droneLabel === right.droneLabel &&
+    left.cubeName === right.cubeName;
 }
 
 async function readOwnershipRecord(lockPath: string): Promise<StreamOwnerRecord | null> {
@@ -655,6 +670,9 @@ function makeRecord(deps: StreamOwnerDeps): StreamOwnerRecord {
     cwd: deps.cwd ?? process.cwd(),
     startedAt: deps.processStartedAt ?? processStartedAt,
     heartbeatAt: now().toISOString(),
+    ...(deps.worktree ? { worktree: deps.worktree } : {}),
+    ...(deps.droneLabel ? { droneLabel: deps.droneLabel } : {}),
+    ...(deps.cubeName ? { cubeName: deps.cubeName } : {}),
   };
 }
 
@@ -668,7 +686,10 @@ function isRecord(value: any): value is StreamOwnerRecord {
     isSafeLeaseText(value.processNonce, 128) &&
     isSafeLeaseText(value.cwd, 4096) &&
     isIsoTimestamp(value.startedAt) &&
-    isIsoTimestamp(value.heartbeatAt)
+    isIsoTimestamp(value.heartbeatAt) &&
+    (value.worktree === undefined || isSafeLeaseText(value.worktree, 4096)) &&
+    (value.droneLabel === undefined || isSafeLeaseText(value.droneLabel, 256)) &&
+    (value.cubeName === undefined || isSafeLeaseText(value.cubeName, 256))
   );
 }
 

package/src/stream-status.ts

@@ -161,7 +161,10 @@ export function renderStreamStatus(inputs: RenderInputs): string {
   if (orphanedInitialization) {
     summary = '**Stream blocked by an orphaned initialization lock.**';
   } else if (ownedByOther) {
-    summary = '**Stream owned by another Borg MCP process.**';
+    const owner = status.ownership!;
+    summary = owner.droneLabel && owner.worktree
+      ? `**Stream owned by seat ${owner.droneLabel} in \`${owner.worktree}\`.**`
+      : '**Stream owned by another Borg MCP process.**';
   } else if (isNotStarted) {
     summary = '**Stream not started.**';
   } else if (!status.connected) {
@@ -245,6 +248,8 @@ export function renderStreamStatus(inputs: RenderInputs): string {
 
   if (ownedByOther) {
     const owner = status.ownership!;
+    lines.push(`- **stream owner seat**: ${owner.droneLabel ?? '_(unknown)_'}`);
+    lines.push(`- **stream owner worktree**: ${owner.worktree ?? '_(unknown)_'}`);
     lines.push(`- **stream owner pid**: ${owner.pid ?? '_(unknown)_'}`);
     lines.push(`- **stream owner cwd**: ${owner.cwd ?? '_(unknown)_'}`);
     lines.push(
@@ -254,6 +259,8 @@ export function renderStreamStatus(inputs: RenderInputs): string {
           : '_(unknown)_'
       }`
     );
+    lines.push('');
+    lines.push('Continue in the owning seat, or close its duplicate agent session before relaunching from the intended worktree. The live owner releases this lock on exit; a stale lock is reclaimed automatically.');
   }
 
   if (wakePath.agentKind === 'opencode' && wakePath.openCode) {

package/src/tool-manifest.ts

@@ -58,10 +58,10 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_assimilate',
           description:
-            "RE-ATTACH this session to the drone seat already saved for this worktree (gh#780: " +
-            "this tool never creates seats). Provide the cube's name; on a match it returns the " +
-            "cube directive, your role's instructions, and recent activity for the EXISTING seat. " +
-            'To create a seat or switch cubes, run `borg assimilate` in a terminal instead.',
+            "Reconnect this session to the existing drone saved for this worktree. This tool " +
+            "never creates drones. Provide the cube's name; on a match it returns the cube " +
+            "directive, your role's instructions, and recent activity for that drone. To create " +
+            'a drone or switch cubes, run `borg assimilate` in a terminal instead.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -116,7 +116,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_playbook',
           description:
-            'Load the full operating-playbook chapter — the detailed disciplines, rationale, and examples behind the rule-spine in your regen (verification discipline v1/v2/v3, concrete source-of-truth surfaces, four-surface propagation). This detail is kept OUT of the regen bootstrap to keep it light; fetch it ONCE per session when doing review/verify-class work. Static text — do NOT re-fetch on every wake.',
+            'Load the full operating-playbook chapter — the detailed disciplines, rationale, and examples behind the abbreviated session instructions (verification discipline v1/v2/v3, concrete source-of-truth surfaces, four-surface propagation). This detail is omitted from the initial context to keep it light; fetch it ONCE per session when doing review/verify-class work. Static text — do NOT re-fetch on every wake.',
           inputSchema: {
             type: 'object',
             properties: {},
@@ -153,7 +153,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
           name: 'borg_role-rationale',
           description:
             "Fetch an on-demand rationale/case-study section for a role playbook. " +
-            "Pass a role name/id and a plain-label section key to read the rationale without expanding every regen.",
+            "Pass a role name/id and a plain-label section key to read the rationale without expanding every context refresh.",
           inputSchema: {
             type: 'object',
             properties: {
@@ -249,7 +249,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_decide',
           description:
-            'Record a RATIFIED cube decision in the durable decision registry (gh#740) so drones cite it by topic instead of restating from memory. Coordinator/Queen are workflow-eligible to ratify, but their labels grant no server permission; the selected local client must have a live cube-manage grant. Recording IS the ratification act; a decision is not ratified until it is in the registry. Topic-keyed: recording a new decision on an existing topic supersedes the prior (one active per topic). Surfaces in borg_regen + borg_decisions.',
+            'Record a RATIFIED cube decision in the durable decision registry so drones cite it by topic instead of restating from memory. Coordinator and Queen roles are workflow-eligible to ratify, but role labels grant no server permission; the selected local client must have a live cube-manage grant. Recording IS the ratification act; a decision is not ratified until it is in the registry. Topic-keyed: recording a new decision on an existing topic supersedes the prior (one active per topic). The decision appears in borg_regen and borg_decisions.',
           inputSchema: {
             type: 'object',
             required: ['topic', 'decision'],
@@ -272,7 +272,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_decisions',
           description:
-            'List the active ratified decisions for the cube (gh#740) — the source of truth to CITE instead of restating a decision from memory. Any member may read. Pass `topic` to fetch one topic\'s active decision; omit for all active decisions.',
+            'List the active ratified decisions for the cube — the source of truth to CITE instead of restating a decision from memory. Any member may read. Pass `topic` to fetch one topic\'s active decision; omit for all active decisions.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -350,7 +350,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
                 pattern: '^[a-z0-9-]+$',
                 maxLength: 64,
               },
-              cube_directive: { type: 'string', description: 'Markdown text every drone in this cube will see in regen. Anything project-specific.' },
+              cube_directive: { type: 'string', description: 'Project-specific Markdown shown to every drone when it refreshes cube context.' },
               template: {
                 type: 'string',
                 description: 'Optional template name to apply after cube creation (e.g. "software-dev"). Roles are merged by name; the default Drone role gets overwritten by the template if a same-named role is in the template.',
@@ -439,7 +439,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
               short_description: { type: 'string', description: 'One-line summary, shown to every drone in the cube.' },
               detailed_description: { type: 'string', description: 'Full playbook for drones in this role — workflow, conventions, log signals to post.' },
               is_default: { type: 'boolean', description: 'If true, new drones assimilating into this cube are assigned this role. Demotes the previous default.' },
-              is_mandatory: { type: 'boolean', description: 'If true, role-less assimilate fills this unoccupied non-queen role before ordinary worker roles. A mandatory human-seat role is therefore selected first until occupied.' },
+              is_mandatory: { type: 'boolean', description: 'If true, role-less assimilation prioritizes this unoccupied role before ordinary worker roles. Platform-wide management roles are never auto-assigned; a mandatory human-operator role is selected first until occupied.' },
               is_human_seat: { type: 'boolean', description: 'If true, this role represents the cube\'s human-occupied seat (where the human Queen sits directly). The class-hierarchy guard in reassign-drone allows promotion FROM a human-seat role TO the platform Queen role; promotion from non-human-seat roles is rejected.' },
               can_broadcast: { type: 'boolean', description: 'If true, drones in this role may post broadcast log entries when strict broadcast gating is enabled.' },
               receives_all_direct: { type: 'boolean', description: 'If true, drones in this role can see direct log entries as observer/audit recipients.' },
@@ -458,7 +458,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
               short_description: { type: 'string', description: 'New short description (optional).' },
               detailed_description: { type: 'string', description: 'New detailed playbook (optional).' },
               is_default: { type: 'boolean', description: 'Set true to make this the cube\'s default role (optional).' },
-              is_mandatory: { type: 'boolean', description: 'Set true/false to prioritize this unoccupied non-queen role during role-less assimilate.' },
+              is_mandatory: { type: 'boolean', description: 'Set true/false to prioritize this unoccupied role during role-less assimilation. Platform-wide management roles are never auto-assigned.' },
               is_human_seat: { type: 'boolean', description: 'Set true/false to mark/unmark this as the cube\'s human-occupied seat (the elevation source for the platform Queen role).' },
               can_broadcast: { type: 'boolean', description: 'Set true/false to allow or deny broadcast log entries when strict broadcast gating is enabled.' },
               receives_all_direct: { type: 'boolean', description: 'Set true/false to grant or remove observer visibility into direct log entries.' },