borgmcp 4.3.0 → 4.4.0

package/src/opencode-seat-identity.ts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
 import type { ActiveCube } from './cubes.js';
 
 export type OpenCodeSeatIdentityErrorCode =
+  | 'IDENTITY_HANDSHAKE_TIMEOUT'
   | 'ROOTS_UNAVAILABLE'
   | 'ROOTS_INVALID'
   | 'SEAT_NOT_FOUND'

package/src/roster-render.ts

@@ -217,8 +217,7 @@ export function renderRoster(inputs: RenderRosterInputs): string {
     const regenCountMarker =
       typeof d.regen_count === 'number' ? ` · \`regen-count:${d.regen_count}\`` : '';
     if (resolvedSince) {
-      // T2.1 awake/stale column. When available, wake_state is the server's
-      // richer state; older servers fall back to seen_since. `seen_since === true` → drone called a
+      // T2.1 awake/stale column. `seen_since === true` means the drone called a
       // tool after the resolved timestamp; treat as awake. False or
       // missing → stale. Missing should not happen when the server
       // echoed a since, but defending against a shape mismatch is
@@ -232,7 +231,7 @@ export function renderRoster(inputs: RenderRosterInputs): string {
       // probe call — pure redundancy. The per-row `last seen X ago`
       // field carries the diagnostic detail for "how stale is this
       // particular drone."
-      const marker = d.wake_state ?? (d.seen_since === true ? 'awake' : 'stale');
+      const marker = d.seen_since === true ? 'awake' : 'stale';
       lines.push(
         `- **${d.label}**${addr} (Role: ${roleName}) — last seen ${lastSeen} · \`${marker}\`${regenCountMarker}${wakePathMarker}${wakePathClassMarker}`
       );

package/src/server-errors.ts

@@ -110,6 +110,56 @@ export class BorgServerUnreachableError extends Error {
   }
 }
 
+export type OpenCodeFailureCode =
+  | 'unauthorized'
+  | 'not-found'
+  | 'incompatible-api'
+  | 'timeout'
+  | 'transient';
+
+export class OpenCodeAuthenticationError extends Error {
+  readonly code = 'unauthorized' as const;
+
+  constructor(message = 'OpenCode API authentication is unavailable') {
+    super(message);
+    this.name = 'OpenCodeAuthenticationError';
+  }
+}
+
+export class OpenCodeHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code: OpenCodeFailureCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'OpenCodeHttpError';
+  }
+}
+
+export class OpenCodeResponseError extends Error {
+  readonly code = 'incompatible-api' as const;
+
+  constructor(
+    message = 'OpenCode returned an incompatible API response',
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = 'OpenCodeResponseError';
+  }
+}
+
+export class OpenCodeUnreachableError extends Error {
+  constructor(
+    public readonly code: 'timeout' | 'transient',
+    message: string,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = 'OpenCodeUnreachableError';
+  }
+}
+
 export class CubeCreationOutcomeUnknownError extends Error {
   constructor() {
     super('Cube creation outcome is unknown.');

package/src/stream-status.ts

@@ -264,8 +264,13 @@ export function renderStreamStatus(inputs: RenderInputs): string {
   }
 
   if (wakePath.agentKind === 'opencode' && wakePath.openCode) {
-    const delivery = wakePath.openCode.deliveryStates;
-    lines.push(`- **OpenCode delivery connected**: ${wakePath.openCode.connected}`);
+    const openCode = wakePath.openCode;
+    const delivery = openCode.deliveryStates;
+    lines.push(`- **OpenCode delivery connected**: ${openCode.connected}`);
+    lines.push(`- **OpenCode target session**: ${openCode.sessionId ?? '_(none resolved yet)_'}`);
+    lines.push(`- **OpenCode last injection**: ${openCode.lastInjectionResult ?? '_(none yet)_'}${typeof openCode.lastInjectionAt === 'number' ? ` at ${new Date(openCode.lastInjectionAt).toISOString()}` : ''}`);
+    lines.push(`- **OpenCode last accepted entry**: ${openCode.lastAcceptedEntryId ?? '_(none)_'}`);
+    lines.push(`- **OpenCode last failure code**: ${openCode.lastFailureCode ?? '_(none)_'}`);
     lines.push(`- **OpenCode queued**: ${delivery.queued}`);
     lines.push(
       `- **OpenCode delivered-unconfirmed**: ${delivery['delivered-unconfirmed']}`

package/src/update-cmd.ts

@@ -42,6 +42,7 @@ export interface UpdateTarget {
 export interface UpdateOptions {
   yes: boolean;
   help?: boolean;
+  registry?: string;
   target?: UpdateTarget;
 }
 
@@ -129,10 +130,21 @@ type ServerUpdateFailureStage =
 interface NpmContext {
   commandPath: string;
   commandIdentity: string;
+  registry: string;
   prefix: string;
   root: string;
 }
 
+class RegistryChangedDuringUpdateError extends Error {
+  constructor(
+    readonly expectedRegistry: string,
+    readonly observedRegistry: string,
+  ) {
+    super(`npm registry changed during update from ${expectedRegistry} to ${observedRegistry}`);
+    this.name = 'RegistryChangedDuringUpdateError';
+  }
+}
+
 function signalExitCode(error: unknown): number | null {
   return error instanceof CommandSignalError ? error.exitCode : null;
 }
@@ -141,11 +153,26 @@ function errorMessage(error: unknown, fallback: string): string {
   return error instanceof Error ? error.message : fallback;
 }
 
+function updateRetryCommand(registry?: string): string {
+  return `borg update --yes${registry ? ` --registry ${shellEscape(registry)}` : ''}`;
+}
+
+function renderUpdateRetry(error: unknown, registry?: string): string {
+  if (error instanceof RegistryChangedDuringUpdateError) {
+    return (
+      `The configured npm registry changed during the update.\n` +
+      `Restore ${error.expectedRegistry} and retry with: ${updateRetryCommand(error.expectedRegistry)}\n` +
+      `Or deliberately start a new update against the current registry with: ${updateRetryCommand(error.observedRegistry)}\n`
+    );
+  }
+  return `Retry with: ${updateRetryCommand(registry)}\n`;
+}
+
 function hasErrorCode(error: unknown, code: string): boolean {
   return error instanceof Error && (error as NodeJS.ErrnoException).code === code;
 }
 
-function renderReentryPreflightFailure(error: unknown, target: UpdateTarget): string {
+function renderReentryPreflightFailure(error: unknown, target: UpdateTarget, registry?: string): string {
   return (
     `Update preflight failed: ${errorMessage(error, 'unknown failure')}\n` +
     `Observed update state:\n` +
@@ -154,7 +181,7 @@ function renderReentryPreflightFailure(error: unknown, target: UpdateTarget): st
     `  prepared runtime: not inspected\n` +
     `  running runtime: not inspected\n` +
     `Server mutation was not attempted.\n` +
-    `Retry with: borg update --yes\n`
+    renderUpdateRetry(error, registry)
   );
 }
 
@@ -185,6 +212,27 @@ export function isExactSemver(value: unknown): value is string {
   return typeof value === 'string' && EXACT_SEMVER.test(value);
 }
 
+function normalizeRegistryUrl(value: string): string {
+  if (value !== value.trim()) throw new Error('npm registry URL must not contain surrounding whitespace');
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('npm registry URL is invalid');
+  }
+  if (
+    url.protocol !== 'https:' ||
+    url.username !== '' ||
+    url.password !== '' ||
+    url.search !== '' ||
+    url.hash !== ''
+  ) {
+    throw new Error('npm registry URL must be an HTTPS URL without credentials, query, or fragment');
+  }
+  if (!url.pathname.endsWith('/')) url.pathname += '/';
+  return url.href;
+}
+
 function isCanonicalSha512Integrity(value: unknown): boolean {
   if (typeof value !== 'string' || !value.startsWith('sha512-') || value.includes(' ')) return false;
   const encoded = value.slice('sha512-'.length);
@@ -219,6 +267,7 @@ export function parseUpdateArgs(
 ): ParsedUpdateArgs {
   let yes = false;
   let help = false;
+  let registry: string | undefined;
   let clientVersion: string | undefined;
   let serverVersion: string | undefined;
   let serverPresent: boolean | undefined;
@@ -230,6 +279,16 @@ export function parseUpdateArgs(
       yes = true;
     } else if (arg === '--help' || arg === '-h') {
       help = true;
+    } else if (arg === '--registry') {
+      if (registry !== undefined) return { ok: false, error: '--registry may be specified only once' };
+      const value = args[index + 1];
+      if (!value) return { ok: false, error: '--registry requires a value' };
+      index += 1;
+      try {
+        registry = normalizeRegistryUrl(value);
+      } catch (error) {
+        return { ok: false, error: errorMessage(error, 'npm registry URL is invalid') };
+      }
     } else if (arg === '--target-client' || arg === '--target-server' || arg === '--server-present') {
       hasInternalOption = true;
       const value = args[index + 1];
@@ -262,10 +321,11 @@ export function parseUpdateArgs(
       ok: true,
       yes,
       ...(help ? { help: true } : {}),
+      ...(registry ? { registry } : {}),
       target: { clientVersion, serverVersion, serverPresent },
     };
   }
-  return { ok: true, yes, ...(help ? { help: true } : {}) };
+  return { ok: true, yes, ...(help ? { help: true } : {}), ...(registry ? { registry } : {}) };
 }
 
 function validatePublishedPackage(
@@ -582,7 +642,9 @@ function verifyServerStatus(status: ServerStatus, target: PublishedPackage): 'ru
 function renderServerFailureRecovery(
   status: ServerStatus | null,
   updateAttempted: boolean,
-  retryCommand: 'borg update --yes' | 'borg server status' | 'borg server update' | 'borg server start',
+  retryCommand: string,
+  error: unknown,
+  registry?: string,
 ): string {
   let text = '';
   if (status?.state === 'stopped') {
@@ -594,7 +656,9 @@ function renderServerFailureRecovery(
       `If it is stopped, run the recovery command reported by borg server status.\n`
     );
   }
-  if (retryCommand !== 'borg server start') {
+  if (error instanceof RegistryChangedDuringUpdateError) {
+    text += renderUpdateRetry(error, registry);
+  } else if (retryCommand !== 'borg server start') {
     text += status?.state === 'stopped'
       ? `Then retry the failed stage with: ${retryCommand}\n`
       : `Next: ${retryCommand}\n`;
@@ -622,6 +686,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
   let pair: { client: PublishedPackage; server: PublishedPackage };
   let client: InstalledPackage;
   let discoveredServer: InstalledPackage | null;
+  const updateRetry = updateRetryCommand(options.registry);
   try {
     [pair, client, discoveredServer] = await Promise.all([
       publishedPair(options.target, deps),
@@ -631,7 +696,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
   } catch (error) {
     const interrupted = signalExitCode(error);
     deps.stderr(options.target
-      ? renderReentryPreflightFailure(error, options.target)
+      ? renderReentryPreflightFailure(error, options.target, options.registry)
       : (
         `Update preflight failed: ${errorMessage(error, 'unknown failure')}\n` +
         `Observed update state:\n` +
@@ -640,7 +705,9 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
         `  prepared runtime: not inspected\n` +
         `  running runtime: not inspected\n` +
         `No mutation was attempted.\n` +
-        `Manual fallback: npm install -g ${CLIENT_PACKAGE} && npm install -g ${SERVER_PACKAGE}\n`
+        (error instanceof RegistryChangedDuringUpdateError
+          ? renderUpdateRetry(error, options.registry)
+          : `Manual fallback: npm install -g ${CLIENT_PACKAGE} && npm install -g ${SERVER_PACKAGE}\n`)
       ));
     return interrupted ?? 1;
   }
@@ -655,13 +722,13 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
       `  prepared runtime: not inspected\n` +
       `  running runtime: not inspected\n` +
       `Server mutation was not attempted.\n` +
-      `Retry with: borg update --yes\n`,
+      `Retry with: ${updateRetry}\n`,
     );
     return 1;
   }
 
   deps.stdout(
-    `Published update plan (${CANONICAL_NPM_REGISTRY}):\n` +
+    `Published update plan (${options.registry ?? CANONICAL_NPM_REGISTRY}):\n` +
     `  client: ${CLIENT_PACKAGE}@${client.version} -> ${CLIENT_PACKAGE}@${pair.client.version}\n` +
     `    target integrity: ${pair.client.integrity}\n` +
     `  server: ${discoveredServer ? `${SERVER_PACKAGE}@${discoveredServer.version}` : 'not installed'} -> ${SERVER_PACKAGE}@${pair.server.version}\n` +
@@ -707,6 +774,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
       const args = [
         'update',
         '--yes',
+        ...(options.registry ? ['--registry', options.registry] : []),
         '--target-client', pair.client.version,
         '--target-server', pair.server.version,
         '--server-present', serverWasPresent ? 'yes' : 'no',
@@ -726,7 +794,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
         `  prepared runtime: not inspected\n` +
         `  running runtime: not inspected\n` +
         `Server mutation was not attempted.\n` +
-        `Retry with: borg update --yes\n`,
+        renderUpdateRetry(error, options.registry),
       );
       return interrupted ?? 1;
     }
@@ -746,7 +814,9 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
       `  prepared runtime: not inspected\n` +
       `  running runtime: not inspected\n` +
       `Server mutation was not attempted.\n` +
-      `Next: reinstall ${CLIENT_PACKAGE}@${pair.client.version} from ${CANONICAL_NPM_REGISTRY}, then rerun borg update --yes.\n`,
+      (error instanceof RegistryChangedDuringUpdateError
+        ? renderUpdateRetry(error, options.registry)
+        : `Next: reinstall ${CLIENT_PACKAGE}@${pair.client.version} from ${options.registry ?? CANONICAL_NPM_REGISTRY}, then rerun ${updateRetry}.\n`),
     );
     return interrupted ?? 1;
   }
@@ -794,7 +864,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
       `  prepared runtime: not inspected\n` +
       `  running runtime: not inspected\n` +
       `Server runtime mutation was not attempted.\n` +
-      `Retry with: borg update --yes\n`,
+      renderUpdateRetry(error, options.registry),
     );
     return interrupted ?? 1;
   }
@@ -805,7 +875,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
   let updateAttempted = false;
   let recoveryStatusAttempted = false;
   let failureStage: ServerUpdateFailureStage = 'initial server status check';
-  let retryCommand: Parameters<typeof renderServerFailureRecovery>[2] = 'borg server status';
+  let retryCommand = 'borg server status';
   const observeStatusAfterFailure = async (): Promise<void> => {
     recoveryStatusAttempted = true;
     try {
@@ -820,7 +890,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
     initialServerState = status.state;
     if (status.installedController !== exactServerIdentity(pair.server.version)) {
       failureStage = 'server controller identity check';
-      retryCommand = 'borg update --yes';
+      retryCommand = updateRetry;
       throw new Error('server status contradicted the verified controller identity');
     }
     try {
@@ -856,7 +926,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
     retryCommand = 'borg server update';
     const state = verifyServerStatus(status, pair.server);
     failureStage = 'final package verification';
-    retryCommand = 'borg update --yes';
+    retryCommand = updateRetry;
     const [finalClient, finalServer] = await Promise.all([
       deps.currentClient(),
       deps.currentServer(),
@@ -904,7 +974,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
     deps.stderr(
       `Server update failed during ${failureStage}: ${errorMessage(error, 'unknown failure')}.\n` +
       renderServerState(client, server, observedStatus, observedUpdate) +
-      renderServerFailureRecovery(observedStatus, updateAttempted, retryCommand),
+      renderServerFailureRecovery(observedStatus, updateAttempted, retryCommand, error, options.registry),
     );
     return interrupted ?? 1;
   }
@@ -998,26 +1068,34 @@ async function npmText(commandPath: string, args: readonly string[], label: stri
   return singleLine(result.stdout, label);
 }
 
-function requireCanonicalRegistry(value: string): void {
-  let normalized: string;
-  try {
-    normalized = new URL(value).href;
-  } catch {
-    throw new Error('npm registry configuration is invalid');
+function requireAcknowledgedRegistry(value: string, acknowledgedRegistry?: string): string {
+  const normalized = normalizeRegistryUrl(value);
+  if (acknowledgedRegistry !== undefined) {
+    const acknowledged = normalizeRegistryUrl(acknowledgedRegistry);
+    if (acknowledged !== normalized) {
+      throw new Error(
+        `the configured npm registry ${normalized} does not match the explicitly acknowledged registry ${acknowledged}`,
+      );
+    }
+    return normalized;
   }
   if (normalized !== CANONICAL_NPM_REGISTRY) {
     throw new Error(
-      `borg update requires the canonical npm registry ${CANONICAL_NPM_REGISTRY}; ` +
-      `the configured registry is unsupported. Use your package manager manually for this installation.`,
+      `borg update uses the canonical npm registry ${CANONICAL_NPM_REGISTRY} by default; ` +
+      `the configured registry ${normalized} has not been explicitly acknowledged. ` +
+      `Rerun with: borg update --registry ${shellEscape(normalized)} to acknowledge this exact registry for one update.`,
     );
   }
+  return normalized;
 }
 
-async function resolveNpmContext(): Promise<NpmContext> {
+async function resolveNpmContext(acknowledgedRegistry?: string): Promise<NpmContext> {
   const commandPath = which.sync('npm');
   const commandIdentity = await realpath(commandPath);
-  const registry = await npmText(commandPath, ['config', 'get', 'registry'], 'registry');
-  requireCanonicalRegistry(registry);
+  const registry = requireAcknowledgedRegistry(
+    await npmText(commandPath, ['config', 'get', 'registry'], 'registry'),
+    acknowledgedRegistry,
+  );
   const prefixText = await npmText(commandPath, ['prefix', '--global'], 'global prefix');
   const rootText = await npmText(commandPath, ['root', '--global'], 'global root');
   if (!isAbsolute(prefixText) || !isAbsolute(rootText)) {
@@ -1029,7 +1107,7 @@ async function resolveNpmContext(): Promise<NpmContext> {
   if (relativeRoot === '' || relativeRoot.startsWith('..') || isAbsolute(relativeRoot)) {
     throw new Error('npm global root is outside its global prefix');
   }
-  return { commandPath, commandIdentity, prefix, root };
+  return { commandPath, commandIdentity, registry, prefix, root };
 }
 
 async function assertNpmContext(context: NpmContext): Promise<NpmContext> {
@@ -1037,8 +1115,8 @@ async function assertNpmContext(context: NpmContext): Promise<NpmContext> {
   if (await realpath(activeCommand) !== context.commandIdentity) {
     throw new Error('active npm executable changed during update');
   }
-  const registry = await npmText(context.commandPath, ['config', 'get', 'registry'], 'registry');
-  requireCanonicalRegistry(registry);
+  const registry = normalizeRegistryUrl(await npmText(context.commandPath, ['config', 'get', 'registry'], 'registry'));
+  if (registry !== context.registry) throw new RegistryChangedDuringUpdateError(context.registry, registry);
   const prefix = await realpath(await npmText(context.commandPath, ['prefix', '--global'], 'global prefix'));
   if (prefix !== context.prefix) throw new Error('npm global prefix changed during update');
   const root = await realpath(await npmText(context.commandPath, ['root', '--global'], 'global root'));
@@ -1146,8 +1224,7 @@ async function defaultPublishedPackage(
   if (version !== 'latest' && !isExactSemver(version)) throw new Error('invalid registry target version');
   // Keep npm context validation above, but read the registry's typed manifest
   // contract directly rather than parsing npm CLI presentation output.
-  void context;
-  const endpoint = new URL(`${encodeURIComponent(name)}/${encodeURIComponent(version)}`, CANONICAL_NPM_REGISTRY);
+  const endpoint = new URL(`${encodeURIComponent(name)}/${encodeURIComponent(version)}`, context.registry);
   let published: PublishedPackage;
   try {
     const response = await fetch(endpoint, {
@@ -1179,8 +1256,7 @@ 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);
+  const endpoint = new URL(encodeURIComponent(name), context.registry);
   try {
     const response = await fetch(endpoint, {
       headers: { Accept: 'application/json' },
@@ -1229,10 +1305,10 @@ async function defaultConfirm(message: string, defaultYes = false): Promise<'yes
   }
 }
 
-export function buildDefaultUpdateDeps(): UpdateDeps {
+export function buildDefaultUpdateDeps(acknowledgedRegistry?: string): UpdateDeps {
   let contextPromise: Promise<NpmContext> | undefined;
   const context = async (): Promise<NpmContext> => {
-    contextPromise ??= resolveNpmContext();
+    contextPromise ??= resolveNpmContext(acknowledgedRegistry);
     return assertNpmContext(await contextPromise);
   };
   return {
@@ -1256,7 +1332,7 @@ export function buildDefaultUpdateDeps(): UpdateDeps {
         '--global',
         ...(options?.ignoreScripts ? ['--ignore-scripts'] : []),
         `--prefix=${npm.prefix}`,
-        `--registry=${CANONICAL_NPM_REGISTRY}`,
+        `--registry=${npm.registry}`,
         `${name}@${version}`,
       ], { inherit: true });
       if (result.code !== 0) throw new Error(`${name} installation exited ${result.code}`);
@@ -1292,17 +1368,18 @@ export function buildDefaultUpdateDeps(): UpdateDeps {
 
 export async function runEarlyUpdate(
   argv: readonly string[],
-  deps: UpdateDeps = buildDefaultUpdateDeps(),
+  deps?: UpdateDeps,
 ): Promise<number | null> {
   if (argv[2] !== 'update') return null;
   const parsed = parseUpdateArgs(argv.slice(3), process.env[REENTRY_ENV] === '1');
+  const resolvedDeps = deps ?? buildDefaultUpdateDeps(parsed.ok ? parsed.registry : undefined);
   if (!parsed.ok) {
-    deps.stderr(`${parsed.error}\nRun \`borg update --help\` for usage.\n`);
+    resolvedDeps.stderr(`${parsed.error}\nRun \`borg update --help\` for usage.\n`);
     return 1;
   }
   if (parsed.help) {
-    deps.stdout(updateHelpText(''));
+    resolvedDeps.stdout(updateHelpText(''));
     return 0;
   }
-  return runUpdate(parsed, deps);
+  return runUpdate(parsed, resolvedDeps);
 }