borgmcp 2.5.0 → 2.6.1

package/src/regen-format.ts

@@ -18,6 +18,7 @@ import {
 } from './roster-render.js';
 import { shellEscape } from './shell-escape.js';
 import { resolveInboxMonitorPath } from './self-path.js';
+import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
 
 /**
  * Extract the SessionStart `source` from a Claude Code hook payload (gh#926).
@@ -26,9 +27,8 @@ import { resolveInboxMonitorPath } from './self-path.js';
  * one of `startup` / `resume` / `clear` / `compact`. The `borg-regen`
  * SessionStart hook uses this to detect a `/clear` re-orientation, which is
  * the FIRST time the hook is the SOLE orientation path (the launch kickoff
- * prompt is gone) AND the moment Claude Code clears the session-scoped
- * `/loop` + `ScheduleWakeup` — so the re-injected orientation must instruct
- * an operational re-arm.
+ * prompt is gone), so the re-injected orientation must instruct an operational
+ * Monitor re-arm.
  *
  * Best-effort + total: empty input (manual / TTY run with no stdin),
  * malformed JSON, a missing `source`, or a non-string `source` all return
@@ -59,9 +59,8 @@ export type AgentKind = 'claude' | 'codex' | 'opencode';
  *
  * Agent-branched on the existing env-agnostic signal (BORG_SESSION-style
  * `isCodexRemoteWakeEnabled`), NOT on a mutable server-recorded field:
- * - claude: arm the inbox-file tail Monitor + engage `/loop` + maintain one
- *   adaptive `ScheduleWakeup` recovery deadline (long while the Monitor is
- *   healthy or indeterminate; short only while explicitly broken).
+ * - claude: arm the inbox-file tail Monitor, drain unread entries on every
+ *   wake, and re-arm the Monitor if it exits or is missing.
  * - codex: Borg's activity stream reaches the app-server remote-control inbox
  *   channel; each wake is followed by an unread-log drain. Manual full regen
  *   + drain is a degraded fallback when remote control is unavailable.
@@ -85,11 +84,7 @@ export function wakePathArming(
     ].join(' ');
   }
   if (agentKind === 'opencode') {
-    return (
-      'Wake path: OpenCode wakes via SDK-driven entry injection into the TUI session — ' +
-      'there is no tail-Monitor or `/loop` heartbeat to arm. Cube posts are delivered ' +
-      'directly into your active session. Use \`borg_regen\` at any time for fresh context.'
-    );
+    return OPENCODE_WAKE_PATH_GUIDANCE;
   }
   // gh#client#18: use absolute path to THIS installation's borg-inbox-monitor
   // so the orientation command always resolves to the same version as the
@@ -101,9 +96,8 @@ export function wakePathArming(
   return [
     'Arm your wake path before working:',
     `1. **Inbox Monitor** (wake path) — run a persistent Monitor on \`${monitorCommand}\` so cube posts wake you in real time.`,
-    '2. **Engage `/loop`** (self-paced) so you keep waking to triage the cube.',
-    '3. **Adaptive recovery** — set ONE `ScheduleWakeup`: [9000, 12600]s (3h ±30m) when Monitor healthy/indeterminate; [720, 1080]s (15m ±3m) when broken. Re-arm Monitor; retry short until healthy. A real Monitor wake resets, not stacks.',
-    '4. **Recovery tick** — drain `borg_read-log unread_only=true`. If empty, check wake status, set deadline, resume prior work. No full-regen or liveness post on empty; safety probes may still wake.',
+    '2. **On every wake** — drain `borg_read-log unread_only=true`. If empty, resume prior work without a full regen or liveness post; safety probes may still wake.',
+    '3. **Monitor recovery** — if the Monitor exits or is missing, re-arm it when the exit notification wakes you.',
   ].join('\n');
 }
 
@@ -168,8 +162,8 @@ export function formatLeanOrientation(args: {
         ? '\n_(`/clear` cleared your conversation; Codex remote-control wake remains active. Follow the required Codex wake path below.)_\n'
         : agentKind === 'claude'
           ? [
-              '\n_(`/clear` cleared Claude\'s `/loop` and recovery deadline — re-arm them now.)_',
-              '_Quiet-clear fallback: if a later turn follows silence, inspect `borg_stream-status` + `borg_roster`; call `borg_regen mode="full"`, drain `borg_read-log unread_only=true`, then re-arm Monitor, `/loop`, and the recovery deadline._\n',
+              '\n_(`/clear` cleared Claude\'s conversation — re-arm the inbox Monitor now.)_',
+              '_Quiet-clear fallback: if a later turn follows silence, inspect `borg_stream-status` + `borg_roster`; call `borg_regen mode="full"`, drain `borg_read-log unread_only=true`, then re-arm the Monitor._\n',
             ].join('\n')
           : ''
       : '';

package/src/repository-cube-init.ts

@@ -46,6 +46,8 @@ export interface RepositoryCubeInitDeps {
   isTTY(): boolean;
   prompt(message: string): Promise<string>;
   write(text: string): void;
+  writeResult?(text: string): void;
+  useColor?(): boolean;
   getIdentity(context: GitRepositoryContext): Promise<CreateCubeRepository>;
   getAssociation(repository: CreateCubeRepository): Promise<RepositoryAssociation | null>;
   saveAssociation(repository: CreateCubeRepository, association: RepositoryAssociation): Promise<void>;
@@ -132,8 +134,16 @@ function renderResult(
     adopted?: boolean;
   },
 ): void {
+  const resultWriter = deps.writeResult ?? deps.write;
+  const heading = input.adopted
+    ? 'Existing cube associated with this repository.'
+    : input.existing
+      ? 'Cube already initialized.'
+      : 'Cube created.';
   const lines = [
-    input.adopted ? 'Existing cube associated with this repository.' : input.existing ? 'Cube already initialized.' : 'Cube created.',
+    input.mode === 'cube-init'
+      ? `${deps.useColor?.() ? '\u001b[32m✓\u001b[0m' : '✓'} ${heading}`
+      : heading,
     `  Name: ${input.response.name}`,
     `  Template: ${presentation(input.response.template).label}`,
     `  Repository: ${input.root}`,
@@ -150,7 +160,7 @@ function renderResult(
   } else {
     lines.push('Continuing with role and seat setup...');
   }
-  deps.write(`${lines.join('\n')}\n`);
+  resultWriter(`${lines.join('\n')}\n`);
 }
 
 export async function initializeRepositoryCube(input: {
@@ -300,8 +310,11 @@ export async function initializeRepositoryCube(input: {
   if (proposedAdoption) return proposedAdoption;
 
   if (input.canCreate === false) {
+    const retryCommand = input.mode === 'cube-init'
+      ? `borg server cube init --host ${shellEscape(input.serverOrigin)}`
+      : `borg assimilate --host ${shellEscape(input.serverOrigin)}`;
     deps.write(
-      `This enrolled client cannot create a cube on ${input.serverOrigin}. Ask the server operator to grant access to a cube, then rerun borg assimilate --host ${shellEscape(input.serverOrigin)}.\n`,
+      `This enrolled client cannot create a cube on ${input.serverOrigin}. Ask the server operator to grant access to a cube, then rerun ${retryCommand}.\n`,
     );
     return { kind: 'stop', code: 1 };
   }

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,13 +353,39 @@ 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`,
     ``,
-    `No process is tailing this drone's inbox file. SSE delivery is healthy (entries reach disk), but Claude Code has no event source to wake on. Until you arm a Monitor, this session only wakes on the /loop fallback heartbeat and will miss live coordination from other drones:`,
+    `No process is tailing this drone's inbox file. SSE delivery is healthy (entries reach disk), but Claude Code has no event source to wake on. Until you arm a Monitor, this session has no wake path and will miss live coordination from other drones:`,
     ``,
     `> Monitor command: \`${monitorCommand(inboxPath, monitorStateRoot)}\` — persistent, 1h timeout, description "borg inbox for ${droneLabel} on cube ${cubeName}".`,
     ``,

package/src/tool-manifest.ts

@@ -172,7 +172,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_roster',
           description:
-            "List all currently connected drones in your cube, with each drone's label, role, and last-seen time. Optional `since` argument adds a sender-side liveness column — pass either an activity_log entry id (e.g., from a dispatch you posted) or an ISO-8601 timestamp; each drone is marked `awake` if they've posted a log entry after that point, otherwise `stale-since-X`. Useful for confirming a dispatch reached its named recipients (catches the silent-wake-path-failure class where SSE delivered but the drone's /loop never woke).",
+            "List all currently connected drones in your cube, with each drone's label, role, and last-seen time. Optional `since` argument adds a sender-side liveness column — pass either an activity_log entry id (e.g., from a dispatch you posted) or an ISO-8601 timestamp; each drone is marked `awake` if they've posted a log entry after that point, otherwise `stale-since-X`. Useful for confirming a dispatch reached its named recipients (catches the silent-wake-path-failure class where SSE delivered but the drone's inbox Monitor never woke it).",
           inputSchema: {
             type: 'object',
             properties: {
@@ -188,7 +188,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_stream-status',
           description:
-            "Diagnostic probe of the local SSE log-stream consumer: returns `connected`, `lastContentEventAt`, `lastWireActivityAt`, `lastHeartbeatAt`, `lastPersistedEventId`, `reconnectAttempts`, plus a wake-path check that flags if SSE is attached but no inbox-Monitor is watching the file (the silent failure where `/loop` never wakes on incoming entries). Read-only in-process state; does NOT re-open the stream. Use when troubleshooting wake-ups or verifying the stream is alive.",
+            "Diagnostic probe of the local SSE log-stream consumer: returns `connected`, `lastContentEventAt`, `lastWireActivityAt`, `lastHeartbeatAt`, `lastPersistedEventId`, `reconnectAttempts`, plus a wake-path check that flags if SSE is attached but no inbox Monitor is watching the file (the silent failure where incoming entries reach disk but do not wake the drone). Read-only in-process state; does NOT re-open the stream. Use when troubleshooting wake-ups or verifying the stream is alive.",
           inputSchema: {
             type: 'object',
             properties: {},

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,
+  };
+}