borgmcp 2.5.0 → 2.6.0

package/src/server-facade.ts

@@ -1,6 +1,9 @@
 import { spawn as spawnChild, type SpawnOptions } from 'node:child_process';
 import { constants } from 'node:os';
+import chalk from 'chalk';
 import { cubeInitHelpText, isHelpFlag, serverHelpText } from './cli-help.js';
+import { consolePrefix } from './console-prefix.js';
+import { getPackageVersion } from './version.js';
 
 export const SERVER_LIFECYCLE_COMMANDS = ['setup', 'start', 'stop', 'status', 'update', 'invite', 'dashboard'] as const;
 export type ServerLifecycleCommand = typeof SERVER_LIFECYCLE_COMMANDS[number];
@@ -12,6 +15,10 @@ export type ParsedServerFacadeArgs =
   | { kind: 'command'; command: ServerLifecycleCommand; args: string[] }
   | { kind: 'error'; reason: 'unknown-command'; command: string };
 
+export function isClientOwnedCubeInitArgv(argv: readonly string[]): boolean {
+  return argv[2] === 'server' && argv[3] === 'cube' && argv[4] === 'init';
+}
+
 export function parseServerFacadeArgs(args: readonly string[]): ParsedServerFacadeArgs {
   const [command, ...rest] = args;
   if (command === undefined || command === '--help' || command === '-h') {
@@ -92,8 +99,9 @@ export function buildDefaultServerFacadeClientDeps(
         import('./assimilate-cmd.js'),
       ]);
       const parsed = parseAssimilateArgs([...args]);
-      if (!parsed.ok || parsed.role !== undefined) {
-        process.stderr.write(`${parsed.ok ? 'borg server cube init does not accept a role' : parsed.error}\n`);
+      const unsupported = parsed.ok ? unsupportedCubeInitInput(args, parsed) : undefined;
+      if (!parsed.ok || unsupported !== undefined) {
+        process.stderr.write(cubeInitUsageErrorText(parsed.ok ? unsupported! : parsed.error));
         return 1;
       }
       return runAssimilate(
@@ -104,6 +112,29 @@ export function buildDefaultServerFacadeClientDeps(
   };
 }
 
+function unsupportedCubeInitInput(
+  args: readonly string[],
+  parsed: { role: string | undefined },
+): string | undefined {
+  if (parsed.role !== undefined) {
+    return 'A role is not accepted because this command does not create a drone.';
+  }
+  const unsupported = ['--worktree', '--here', '--force', '--cli', '--model', '--backend', '--no-template'];
+  const flag = args.find((arg) => unsupported.some((candidate) =>
+    arg === candidate || arg.startsWith(`${candidate}=`)));
+  return flag === undefined
+    ? undefined
+    : `${flag.split('=', 1)[0]} is not accepted because this command does not create a drone.`;
+}
+
+export function cubeInitUsageErrorText(reason: string): string {
+  const sentence = /[.!?]$/.test(reason) ? reason : `${reason}.`;
+  return (
+    chalk.red(`${consolePrefix()}◼ borg server cube init: ${sentence}\n`) +
+    'Run `borg server cube init --help` for usage.\n'
+  );
+}
+
 const defaultClientDeps = buildDefaultServerFacadeClientDeps();
 
 const MAX_RENDERED_COMMAND_CODE_POINTS = 80;
@@ -222,7 +253,7 @@ export async function runEarlyServerFacade(
     return 0;
   }
   if (parsed.kind === 'cube-init-help') {
-    output.writeStdout(cubeInitHelpText());
+    output.writeStdout(cubeInitHelpText(getPackageVersion()));
     return 0;
   }
   if (parsed.kind === 'error') {

package/src/setup.ts

@@ -37,6 +37,7 @@ import { ensureCliMcpConfigured } from './ensure-mcp-config.js';
 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';
 
 /**
  * Main setup wizard
@@ -67,6 +68,16 @@ async function main() {
     process.exit(1);
   }
 
+  // Resolve the separately published local server before setup writes agent
+  // configuration. Decline/non-interactive/failure paths therefore leave no
+  // partial setup state behind.
+  console.log(chalk.blue('◼ Local Server'));
+  const serverInstall = await offerFirstRunServerInstall();
+  if (serverInstall.kind !== 'present' && serverInstall.kind !== 'installed') {
+    process.exit(serverInstall.kind === 'declined' ? 0 : 1);
+  }
+  console.log('');
+
   // Step 1: Configure every detected agent CLI
   console.log(chalk.blue('◼ Agent CLI Integration'));
 

package/src/stream-status.ts

@@ -28,6 +28,7 @@ import {
   HEARTBEAT_STALE_MS,
 } from './inbox-monitor.js';
 import { shellEscape } from './shell-escape.js';
+import type { WakePathSnapshot } from './wake-path-health.js';
 
 /**
  * Best-effort check: is a process tailing this inbox file?
@@ -111,11 +112,10 @@ export function isHeartbeatStale(inboxPath: string, monitorStateRoot?: string |
 
 export interface RenderInputs {
   status: StreamStatus;
-  /**
-   * Tri-state Monitor liveness: true = healthy, false = wake-path
-   * broken, null = cannot determine.
-   */
+  /** Legacy Claude Monitor health; runtime-aware callers also pass `wakePath`. */
   inboxMonitorHealthy: boolean | null;
+  /** Runtime-specific wake-path evidence. Omitted by legacy pure-render callers. */
+  wakePath?: WakePathSnapshot;
   /**
    * Inbox path for the State-5 self-arm instruction. Pass null when
    * unknown (no active cube); State 5 will then surface the failure
@@ -140,6 +140,12 @@ export interface RenderInputs {
 export function renderStreamStatus(inputs: RenderInputs): string {
   const { status, inboxMonitorHealthy, inboxPath, monitorStateRoot, droneLabel, cubeName, humanAgo } =
     inputs;
+  const wakePath = inputs.wakePath ?? {
+    agentKind: 'claude' as const,
+    healthy: inboxMonitorHealthy,
+    openCode: null,
+  };
+  const wakePathHealthy = wakePath.healthy;
 
   const isNotStarted =
     status.reconnectAttempts === 0 &&
@@ -149,9 +155,8 @@ export function renderStreamStatus(inputs: RenderInputs): string {
   const orphanedInitialization = status.ownership?.state === 'orphaned-initialization';
   const ownershipInitializing = status.ownership?.state === 'initializing';
 
-  // Top-line verdict — 5 states + override per drone-4 contract.
-  // Precedence: disconnected > no-inbox-Monitor (wire-down upstream
-  // cause; State 5 only applies when wire is healthy).
+  // Top-line verdict — 5 states + runtime wake-path override.
+  // Precedence: disconnected > wake-path failure.
   let summary: string;
   if (orphanedInitialization) {
     summary = '**Stream blocked by an orphaned initialization lock.**';
@@ -161,8 +166,12 @@ export function renderStreamStatus(inputs: RenderInputs): string {
     summary = '**Stream not started.**';
   } else if (!status.connected) {
     summary = `**Stream disconnected (reconnect attempt ${status.reconnectAttempts}).**`;
-  } else if (inboxMonitorHealthy === false) {
-    summary = '**Stream connected (no inbox-Monitor — wake path broken).**';
+  } else if (wakePathHealthy === false) {
+    summary = wakePath.agentKind === 'opencode'
+      ? '**Stream connected (OpenCode delivery degraded).**'
+      : wakePath.agentKind === 'codex'
+        ? '**Stream connected (Codex wake path unavailable).**'
+        : '**Stream connected (no inbox-Monitor — wake path broken).**';
   } else if (status.lastContentEventAt === null) {
     // State 2: wire works, no content yet. Collapses two underlying
     // conditions per drone-4 contract — fresh connect pre-first-content
@@ -247,13 +256,42 @@ export function renderStreamStatus(inputs: RenderInputs): string {
     );
   }
 
-  // State-5 body line + self-arm instruction. Only fires when we
-  // POSITIVELY detected wake-path breakage AND the wire is up — the
-  // disconnected case takes precedence above and would never reach
-  // here. When `inboxMonitorHealthy === null` (couldn't determine) we
-  // stay silent; surfacing an uncertain failure mode is worse UX than
-  // omitting it.
-  if (status.connected && inboxMonitorHealthy === false) {
+  if (wakePath.agentKind === 'opencode' && wakePath.openCode) {
+    const delivery = wakePath.openCode.deliveryStates;
+    lines.push(`- **OpenCode delivery connected**: ${wakePath.openCode.connected}`);
+    lines.push(`- **OpenCode queued**: ${delivery.queued}`);
+    lines.push(
+      `- **OpenCode delivered-unconfirmed**: ${delivery['delivered-unconfirmed']}`
+    );
+    lines.push(`- **OpenCode retried**: ${delivery.retried}`);
+    lines.push(`- **OpenCode failed**: ${delivery.failed}`);
+  }
+
+  // Runtime-specific wake-path warning. The wire-down case takes
+  // precedence above; an indeterminate signal remains honest and silent.
+  if (status.connected && wakePathHealthy === false) {
+    if (wakePath.agentKind === 'opencode') {
+      lines.push(
+        '- **OpenCode delivery**: _(degraded — inspect the durable unread log)_'
+      );
+      lines.push('');
+      lines.push('## OpenCode wake delivery is degraded');
+      lines.push(
+        'One or more durable inbox entries were rejected or could not be confirmed. Run `borg_read-log unread_only=true` and drain the unread log now. Use `borg_stream-status` to check whether failed or delivered-unconfirmed entries remain.'
+      );
+      return lines.join('\n');
+    }
+    if (wakePath.agentKind === 'codex') {
+      lines.push(
+        '- **Codex wake path**: _(remote-control bridge unavailable)_'
+      );
+      lines.push('');
+      lines.push('## Codex wake delivery is unavailable');
+      lines.push(
+        'The Codex remote-control bridge cannot currently deliver a wake. Run `borg_read-log unread_only=true` and drain the unread log now, then reconnect the Codex wake path.'
+      );
+      return lines.join('\n');
+    }
     lines.push(
       `- **inbox-monitor**: _(no watcher detected — wake path broken)_`
     );
@@ -278,13 +316,13 @@ export function renderStreamStatus(inputs: RenderInputs): string {
  * from the inline ternary in `src/index.ts` for direct unit-test
  * coverage of the (connected × healthy) cross-product).
  *
- * Returns true ONLY when the wire is up AND we positively detected a
- * dead inbox Monitor (`=== false` strict). The `null` branch
+ * Returns true ONLY when the wire is up AND the runtime-specific wake
+ * mechanism is positively unhealthy (`=== false` strict). The `null` branch
  * (couldn't determine) stays silent — surfacing an uncertain failure
  * mode is worse UX than omitting it (mirrors the State-5 precedence
  * rule in `renderStreamStatus`). When disconnected, the wire-down case
  * is the upstream cause and takes precedence; no point warning about
- * the wake path when the wake-path's input has no events to deliver.
+ * the wake path when its input has no events to deliver.
  */
 export function shouldShowWakePathWarning(
   streamStatus: StreamStatus,
@@ -294,7 +332,7 @@ export function shouldShowWakePathWarning(
 }
 
 /**
- * Wake-path-broken prefix for `borg_regen` output (gh#43).
+ * Runtime-specific wake-path-broken prefix for `borg_regen` output.
  *
  * Pure function — caller decides whether to call (gates on
  * `shouldShowWakePathWarning`). Returns an empty string when called
@@ -315,8 +353,34 @@ export function formatWakePathPrefix(inputs: {
   monitorStateRoot?: string | null;
   droneLabel: string | null;
   cubeName: string | null;
+  wakePath?: WakePathSnapshot;
 }): string {
-  const { inboxPath, monitorStateRoot, droneLabel, cubeName } = inputs;
+  const { inboxPath, monitorStateRoot, droneLabel, cubeName, wakePath } = inputs;
+  if (wakePath?.agentKind === 'opencode') {
+    const delivery = wakePath.openCode?.deliveryStates;
+    return [
+      '## ⚠ OpenCode wake delivery degraded',
+      '',
+      `Durable delivery has ${
+        delivery
+          ? `${delivery['delivered-unconfirmed']} delivered-unconfirmed and ${delivery.failed} failed entries`
+          : 'an unhealthy runtime signal'
+      }. Run \`borg_stream-status\`, then run \`borg_read-log unread_only=true\` and drain the unread log.`,
+      '',
+      '---',
+      '',
+    ].join('\n');
+  }
+  if (wakePath?.agentKind === 'codex') {
+    return [
+      '## ⚠ Codex wake path unavailable',
+      '',
+      'The remote-control bridge cannot currently deliver a wake. Run `borg_read-log unread_only=true` and drain the unread log, then reconnect the Codex wake path.',
+      '',
+      '---',
+      '',
+    ].join('\n');
+  }
   if (!inboxPath || !droneLabel || !cubeName) return '';
   return [
     `## ⚠ Wake path broken — arm Monitor NOW`,

package/src/update-cmd.ts

@@ -54,7 +54,12 @@ export interface UpdateDeps {
     name: typeof CLIENT_PACKAGE | typeof SERVER_PACKAGE,
     version: string,
   ): Promise<PublishedPackage>;
-  installGlobal(name: typeof CLIENT_PACKAGE | typeof SERVER_PACKAGE, version: string): Promise<void>;
+  publishedVersions(name: typeof CLIENT_PACKAGE | typeof SERVER_PACKAGE): Promise<string[]>;
+  installGlobal(
+    name: typeof CLIENT_PACKAGE | typeof SERVER_PACKAGE,
+    version: string,
+    options?: { ignoreScripts?: boolean },
+  ): Promise<void>;
   reenter(binPath: string, args: readonly string[]): Promise<number>;
   serverJson(binPath: string, command: 'update' | 'status'): Promise<unknown>;
   verifyRunningProtocol(origin: string): Promise<void>;
@@ -150,7 +155,7 @@ function renderServerState(
   );
 }
 
-function isExactSemver(value: unknown): boolean {
+export function isExactSemver(value: unknown): value is string {
   return typeof value === 'string' && EXACT_SEMVER.test(value);
 }
 
@@ -275,6 +280,44 @@ async function publishedPair(
   return { client, server };
 }
 
+/**
+ * Resolve the exact published server that can run with an already-installed
+ * client. First-run onboarding uses this instead of inventing a second
+ * registry path or installing an unpinned `latest` spec.
+ */
+export async function resolveCompatibleServerTarget(
+  clientSharedVersion: string,
+  deps: Pick<UpdateDeps, 'publishedPackage' | 'publishedVersions'>,
+): Promise<PublishedPackage> {
+  if (!isExactSemver(clientSharedVersion)) {
+    throw new Error(`installed client has an invalid ${SHARED_PACKAGE} pin`);
+  }
+  const stableVersions = (await deps.publishedVersions(SERVER_PACKAGE))
+    .filter((version) => isExactSemver(version) && !version.includes('-'))
+    .sort(compareStableSemverDescending);
+  for (const version of stableVersions) {
+    const server = await deps.publishedPackage(SERVER_PACKAGE, version);
+    validatePublishedPackage(server, SERVER_PACKAGE);
+    if (server.version !== version) {
+      throw new Error(`registry returned the wrong ${SERVER_PACKAGE} manifest version`);
+    }
+    if (server.sharedVersion === clientSharedVersion) return server;
+  }
+  throw new Error(
+    `no published ${SERVER_PACKAGE} release uses ${SHARED_PACKAGE}@${clientSharedVersion}`,
+  );
+}
+
+function compareStableSemverDescending(left: string, right: string): number {
+  const leftParts = left.split('+', 1)[0].split('.').map((part) => BigInt(part));
+  const rightParts = right.split('+', 1)[0].split('.').map((part) => BigInt(part));
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] > rightParts[index]) return -1;
+    if (leftParts[index] < rightParts[index]) return 1;
+  }
+  return right.localeCompare(left);
+}
+
 function assertInstalled(
   installed: InstalledPackage,
   published: PublishedPackage,
@@ -533,7 +576,11 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
   if (client.version !== pair.client.version || client.sharedVersion !== pair.client.sharedVersion) {
     let installedClient: InstalledPackage | null = null;
     try {
-      await deps.installGlobal(CLIENT_PACKAGE, pair.client.version);
+      await deps.installGlobal(
+        CLIENT_PACKAGE,
+        pair.client.version,
+        { ignoreScripts: true },
+      );
       installedClient = await deps.currentClient();
       assertInstalled(installedClient, pair.client);
       const args = [
@@ -597,7 +644,11 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
       discoveredServer.version !== pair.server.version ||
       discoveredServer.sharedVersion !== pair.server.sharedVersion
     ) {
-      await deps.installGlobal(SERVER_PACKAGE, pair.server.version);
+      await deps.installGlobal(
+        SERVER_PACKAGE,
+        pair.server.version,
+        { ignoreScripts: true },
+      );
     }
     const verified = await deps.currentServer();
     if (!verified) throw new Error('server controller disappeared after installation');
@@ -920,6 +971,36 @@ async function defaultPublishedPackage(
   return published;
 }
 
+async function defaultPublishedVersions(
+  name: typeof CLIENT_PACKAGE | typeof SERVER_PACKAGE,
+  context: NpmContext,
+): Promise<string[]> {
+  void context;
+  const endpoint = new URL(encodeURIComponent(name), CANONICAL_NPM_REGISTRY);
+  try {
+    const response = await fetch(endpoint, {
+      headers: { Accept: 'application/json' },
+      redirect: 'error',
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const parsed: unknown = await response.json();
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('response was not a package object');
+    }
+    const versions = (parsed as Record<string, unknown>).versions;
+    if (!versions || typeof versions !== 'object' || Array.isArray(versions)) {
+      throw new Error('package versions were not an object');
+    }
+    const values = Object.keys(versions);
+    if (values.length === 0 || values.some((version) => !isExactSemver(version))) {
+      throw new Error('package versions were missing or invalid');
+    }
+    return values;
+  } catch {
+    throw new Error(`registry version lookup failed for ${name}`);
+  }
+}
+
 async function defaultConfirm(message: string): Promise<'yes' | 'no' | 'eof' | 'interrupted'> {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   let interrupted = false;
@@ -958,11 +1039,13 @@ export function buildDefaultUpdateDeps(): UpdateDeps {
       await context(),
     ),
     publishedPackage: async (name, version) => defaultPublishedPackage(name, version, await context()),
-    installGlobal: async (name, version) => {
+    publishedVersions: async (name) => defaultPublishedVersions(name, await context()),
+    installGlobal: async (name, version, options) => {
       const npm = await context();
       const result = await runCommand(npm.commandPath, [
         'install',
         '--global',
+        ...(options?.ignoreScripts ? ['--ignore-scripts'] : []),
         `--prefix=${npm.prefix}`,
         `--registry=${CANONICAL_NPM_REGISTRY}`,
         `${name}@${version}`,

package/src/wake-path-health.ts

@@ -0,0 +1,85 @@
+import { probeCodexBridgeArmed } from './codex-app-wake.js';
+import { checkInboxMonitorHealthy } from './stream-status.js';
+import {
+  getOpenCodeConnectionState,
+  type OpenCodeConnectionState,
+} from './opencode-drone.js';
+import type { AgentKind } from './agent-runtime.js';
+
+export interface WakePathSnapshot {
+  agentKind: AgentKind;
+  healthy: boolean | null;
+  openCode: OpenCodeConnectionState | null;
+}
+
+interface InspectWakePathInputs {
+  agentKind: AgentKind;
+  active: { cubeId: string; droneId: string } | null;
+  inboxPath: string | null;
+  monitorStateRoot: string | null;
+}
+
+interface InspectWakePathDeps {
+  checkClaudeMonitor?: typeof checkInboxMonitorHealthy;
+  probeCodex?: typeof probeCodexBridgeArmed;
+  getOpenCodeState?: typeof getOpenCodeConnectionState;
+}
+
+export function openCodeWakePathHealthy(
+  state: OpenCodeConnectionState,
+): boolean | null {
+  if (!state.connected) return false;
+  if (
+    state.deliveryStates.failed > 0 ||
+    state.deliveryStates['delivered-unconfirmed'] > 0
+  ) {
+    return false;
+  }
+  if (
+    state.deliveryStates.queued > 0 ||
+    state.deliveryStates.retried > 0
+  ) {
+    return null;
+  }
+  if (state.sessionId === null) return null;
+  return true;
+}
+
+export async function inspectWakePath(
+  inputs: InspectWakePathInputs,
+  deps: InspectWakePathDeps = {},
+): Promise<WakePathSnapshot> {
+  if (!inputs.active) {
+    return {
+      agentKind: inputs.agentKind,
+      healthy: null,
+      openCode: null,
+    };
+  }
+
+  if (inputs.agentKind === 'claude') {
+    const check = deps.checkClaudeMonitor ?? checkInboxMonitorHealthy;
+    return {
+      agentKind: inputs.agentKind,
+      healthy: check(inputs.inboxPath, inputs.monitorStateRoot),
+      openCode: null,
+    };
+  }
+
+  if (inputs.agentKind === 'codex') {
+    const probe = deps.probeCodex ?? probeCodexBridgeArmed;
+    return {
+      agentKind: inputs.agentKind,
+      healthy: await probe(inputs.active),
+      openCode: null,
+    };
+  }
+
+  const getState = deps.getOpenCodeState ?? getOpenCodeConnectionState;
+  const openCode = getState();
+  return {
+    agentKind: inputs.agentKind,
+    healthy: openCodeWakePathHealthy(openCode),
+    openCode,
+  };
+}