borgmcp 3.2.0 → 3.4.0

package/src/opencode-plugin.ts

@@ -1,37 +1,231 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { borgHomeRoot } from './private-root.js';
-
-/**
- * Plugin source that preserves borg cube context across session compaction.
- * The initial kickoff and ongoing entry injection are handled by the launcher
- * and MCP client via the SDK, not by the plugin.
- */
-export const BORG_PLUGIN_SOURCE = `
-// Borg MCP context-preservation plugin — installed by borg assimilate
-export default function () {
-  return {
-    'experimental.session.compacting': async (_input, output) => {
-      output.context.push(
-        '## Borg Cube\\nYou are in a Borg MCP multi-agent coordination cube. ' +
-        'Use MCP tool borg_regen to get full context and recent activity.'
+import { evaluateLogAudit } from './log-audit-core.js';
+import { borgHomeRoot, isCanonicalPath } from './private-root.js';
+import { getPackageVersion } from './version.js';
+
+export const OPENCODE_COMPATIBILITY = {
+  // Empirically pinned on 2026-08-09. OpenCode 1.18.15 loads the default
+  // function -> Hooks object shape while the installed SDK uses the 1.17.18
+  // path/query/body client call shape. TextPart.metadata exists, persists
+  // through history/compaction/reload, and is hidden from the TUI and model.
+  // Do not replace either contract without a new live compatibility measurement.
+  opencode: '1.18.15',
+  sdk: '1.17.18',
+} as const;
+
+const COMPACT_FALLBACK =
+  '## Borg Cube\nYou are in a Borg MCP multi-agent coordination cube. ' +
+  'Use MCP tool borg_regen to get full context and recent activity.';
+export const OPENCODE_INJECTED_ENTRY_METADATA_KEY = 'borgOpenCodeInjectedEntry';
+export const OPENCODE_RECOVERY_METADATA_KEY = 'borgOpenCodeSessionOrientation';
+const PLUGIN_REL_PATH = path.join('.config', 'opencode', 'plugins', 'borg-orient.js');
+
+export interface OpenCodePluginCoreDeps {
+  defer(task: () => Promise<void>): void;
+  wait(milliseconds: number): Promise<void>;
+  listMessages(sessionID: string): Promise<any[]>;
+  renderOrientation(source: 'clear' | 'compact'): Promise<string>;
+  submitPrompt(
+    sessionID: string,
+    text: string,
+    recoveryVersion: string,
+    shouldSubmit: () => boolean,
+  ): Promise<boolean>;
+  audit(messages: readonly any[]): string | null;
+}
+
+export interface OpenCodePluginCoreOptions {
+  enabled: boolean;
+  pluginVersion: string;
+  recoveryMetadataKey: string;
+  injectedEntryMetadataKey: string;
+  kickoffPollAttempts: number;
+  confirmationPollAttempts: number;
+  pollDelayMs: number;
+  compactFallback: string;
+}
+
+/** Pure, dependency-injected behavior core. Its emitted JavaScript function
+ * body is also embedded in the installed self-contained plugin. */
+export function createOpenCodePluginCore(
+  deps: OpenCodePluginCoreDeps,
+  options: OpenCodePluginCoreOptions,
+) {
+  const claimedSessions = new Set<string>();
+  const humanPromptSessions = new Set<string>();
+  const textParts = (message: any): any[] => Array.isArray(message?.parts)
+    ? message.parts.filter((part: any) => part?.type === 'text' && typeof part.text === 'string')
+    : [];
+  const isInjectedEntry = (message: any): boolean => {
+    const parts = textParts(message);
+    return message?.info?.role === 'user' &&
+      parts[0]?.metadata?.[options.injectedEntryMetadataKey] === true;
+  };
+  const isOwnedRecovery = (message: any): boolean => {
+    const parts = textParts(message);
+    return message?.info?.role === 'user' &&
+      parts[0]?.metadata?.[options.recoveryMetadataKey] === options.pluginVersion;
+  };
+  const hasRecoveryBlocker = (sessionID: string, messages: readonly any[]): boolean =>
+    humanPromptSessions.has(sessionID) || messages.some((message) =>
+      isOwnedRecovery(message) ||
+      (message?.info?.role === 'user' && !isInjectedEntry(message)));
+
+  const recoverNewSession = async (sessionID: string): Promise<void> => {
+    try {
+      for (let attempt = 0; attempt < options.kickoffPollAttempts; attempt++) {
+        const messages = await deps.listMessages(sessionID);
+        if (hasRecoveryBlocker(sessionID, messages)) return;
+        if (attempt + 1 < options.kickoffPollAttempts) await deps.wait(options.pollDelayMs);
+      }
+
+      const orientation = (await deps.renderOrientation('clear')).trim();
+      if (!orientation) return;
+      const beforeSubmit = await deps.listMessages(sessionID);
+      if (hasRecoveryBlocker(sessionID, beforeSubmit)) return;
+
+      const submitted = await deps.submitPrompt(
+        sessionID,
+        orientation,
+        options.pluginVersion,
+        () => !hasRecoveryBlocker(sessionID, []),
       );
+      if (!submitted) return;
+      // promptAsync is not idempotent. Confirmation may retry, submission may not.
+      for (let attempt = 0; attempt < options.confirmationPollAttempts; attempt++) {
+        const messages = await deps.listMessages(sessionID);
+        if (messages.some(isOwnedRecovery)) return;
+        if (attempt + 1 < options.confirmationPollAttempts) await deps.wait(options.pollDelayMs);
+      }
+    } catch {
+      // The plugin is best-effort. Never block OpenCode session creation.
+    }
+  };
+
+  return {
+    event: async ({ event }: any): Promise<void> => {
+      if (!options.enabled || event?.type !== 'session.created') return;
+      const sessionID = event?.properties?.info?.id;
+      if (typeof sessionID !== 'string' || claimedSessions.has(sessionID)) return;
+      claimedSessions.add(sessionID);
+      deps.defer(() => recoverNewSession(sessionID));
+    },
+    'experimental.session.compacting': async (
+      _input: { sessionID: string },
+      output: { context: string[] },
+    ): Promise<void> => {
+      if (!options.enabled) return;
+      try {
+        const orientation = (await deps.renderOrientation('compact')).trim();
+        output.context.push(orientation || options.compactFallback);
+      } catch {
+        output.context.push(options.compactFallback);
+      }
+    },
+    'chat.message': async (
+      input: { sessionID: string },
+      output: { message: unknown; parts: any[] },
+    ): Promise<void> => {
+      if (!options.enabled) return;
+      const current = { info: { role: 'user' }, parts: [...output.parts] };
+      if (!isInjectedEntry(current) && !isOwnedRecovery(current)) {
+        // chat.message fires before the user message is persisted. Record the
+        // human turn synchronously so recovery cannot race that short gap.
+        humanPromptSessions.add(input.sessionID);
+      }
+      try {
+        const history = await deps.listMessages(input.sessionID);
+        const nudge = deps.audit([...history, current]);
+        if (nudge) output.parts.push({ type: 'text', text: nudge });
+      } catch {
+        // Audit is advisory and must never block a prompt.
+      }
     },
   };
 }
+
+export function buildBorgPluginSource(version: string): string {
+  const marker = `borgmcp-opencode-plugin:${version};opencode=${OPENCODE_COMPATIBILITY.opencode};sdk=${OPENCODE_COMPATIBILITY.sdk};textpart-metadata=exists+persisted+tui-hidden+model-hidden`;
+  return `// ${marker}
+// Generated by borgmcp. Self-contained; do not edit.
+const createCore = ${createOpenCodePluginCore.toString()};
+const evaluateAudit = ${evaluateLogAudit.toString()};
+export default async function (ctx) {
+  const runRegen = async (source) => {
+    const input = JSON.stringify({ source });
+    const result = await ctx.$\`printf '%s' \${input} | borg-regen\`.quiet().nothrow();
+    return result.exitCode === 0 ? result.stdout.toString('utf8') : '';
+  };
+  return createCore({
+    defer: (task) => { setTimeout(() => { void task(); }, 0); },
+    wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+    listMessages: async (sessionID) => {
+      const result = await ctx.client.session.messages({
+        path: { id: sessionID },
+        query: { directory: ctx.directory },
+      });
+      return Array.isArray(result.data) ? result.data : [];
+    },
+    renderOrientation: runRegen,
+    submitPrompt: async (sessionID, text, recoveryVersion, shouldSubmit) => {
+      if (!shouldSubmit()) return false;
+      await ctx.client.session.promptAsync({
+        path: { id: sessionID },
+        query: { directory: ctx.directory },
+        body: { parts: [{
+          type: 'text',
+          text,
+          metadata: { [${JSON.stringify(OPENCODE_RECOVERY_METADATA_KEY)}]: recoveryVersion },
+        }] },
+      });
+      return true;
+    },
+    audit: (messages) => evaluateAudit(messages),
+  }, {
+    ...${JSON.stringify({
+    pluginVersion: version,
+    recoveryMetadataKey: OPENCODE_RECOVERY_METADATA_KEY,
+    injectedEntryMetadataKey: OPENCODE_INJECTED_ENTRY_METADATA_KEY,
+    kickoffPollAttempts: 6,
+    confirmationPollAttempts: 6,
+    pollDelayMs: 200,
+    compactFallback: COMPACT_FALLBACK,
+  })},
+    enabled: process.env.BORG_SESSION === '1',
+  });
+}
 `;
+}
 
-const PLUGIN_REL_PATH = path.join('.config', 'opencode', 'plugins', 'borg-orient.js');
+export const BORG_PLUGIN_SOURCE = buildBorgPluginSource(getPackageVersion());
 
-export function installBorgPlugin(): void {
-  const pluginPath = path.join(borgHomeRoot(), PLUGIN_REL_PATH);
+export function openCodePluginPath(homeDir: string = borgHomeRoot()): string {
+  return path.join(homeDir, PLUGIN_REL_PATH);
+}
+
+export function installBorgPlugin(options: {
+  homeDir?: string;
+  version?: string;
+} = {}): void {
+  const pluginPath = openCodePluginPath(options.homeDir);
+  const source = buildBorgPluginSource(options.version ?? getPackageVersion());
   try {
-    if (fs.existsSync(pluginPath)) {
-      const existing = fs.readFileSync(pluginPath, 'utf-8');
-      if (existing === BORG_PLUGIN_SOURCE) return;
+    if (!isCanonicalPath(pluginPath)) return;
+    try {
+      if (fs.lstatSync(pluginPath).isSymbolicLink()) return;
+      if (fs.readFileSync(pluginPath, 'utf-8') === source) return;
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) return;
     }
     fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
-    fs.writeFileSync(pluginPath, BORG_PLUGIN_SOURCE, 'utf-8');
+    if (!isCanonicalPath(pluginPath)) return;
+    try {
+      if (fs.lstatSync(pluginPath).isSymbolicLink()) return;
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) return;
+    }
+    fs.writeFileSync(pluginPath, source, 'utf-8');
   } catch {
     // Best-effort — plugin is an optimization, not a requirement.
   }

package/src/regen-format.ts

@@ -18,7 +18,6 @@ import {
   renderRuntimeMetadataLines,
 } 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';
 import { isBorgSession } from './launch-gate.js';
 
@@ -112,10 +111,10 @@ export function wakePathArming(
   if (agentKind === 'opencode') {
     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
-  // running client — never a different one via PATH.
-  const monitorBin = shellEscape(resolveInboxMonitorPath());
+  // client#394: the stable npm bin survives Node/nvm install-path rotation.
+  // Launch-time health checks make a missing or version-skewed PATH target
+  // visible instead of silently embedding a stale installation path here.
+  const monitorBin = 'borg-inbox-monitor';
   const monitorCommand = monitorStateRoot
     ? `${monitorBin} --state-root ${shellEscape(monitorStateRoot)} ${shellEscape(inboxPath)}`
     : `${monitorBin} ${shellEscape(inboxPath)}`;
@@ -191,7 +190,7 @@ export function formatLeanOrientation(args: {
               '\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')
-          : ''
+          : '\n_(OpenCode started a new session; Borg supplied this orientation automatically.)_\n'
       : '';
   return [
     `# Cube: ${cubeName} — ${droneLabel}`,

package/src/resolved-cli-config.ts

@@ -7,6 +7,7 @@ export interface ResolvedCliConfigDeps {
   addClaudeUserPromptSubmitHook(): void;
   addCodexSessionStartHook(): void;
   addCodexUserPromptSubmitHook(): void;
+  installOpenCodePlugin(): void;
 }
 /**
  * Apply only the integration writes for the CLI the launcher resolved.
@@ -37,4 +38,5 @@ export function configureResolvedCli(
   }
 
   deps.ensureMcp('opencode');
+  deps.installOpenCodePlugin();
 }

package/src/startup-services.ts

@@ -2,7 +2,6 @@ export type McpStartupTask = () => void | Promise<void>;
 
 /** Required named services: omission from index wiring is a type error. */
 export interface McpStartupServices {
-  sessionStartHook: McpStartupTask;
   auditHook: McpStartupTask;
   sseStream: McpStartupTask;
   openCode: McpStartupTask;
@@ -21,12 +20,10 @@ export async function runMcpStartupServices(
 ): Promise<void> {
   if (readinessProbe) return;
   const tasks = options.openCodeFirst ? [
-    services.sessionStartHook,
     services.auditHook,
     services.openCode,
     services.sseStream,
   ] : [
-    services.sessionStartHook,
     services.auditHook,
     services.sseStream,
     services.openCode,

package/src/unknown-subcommand.ts

@@ -15,6 +15,7 @@
 export const KNOWN_SUBCOMMANDS = [
   'setup',
   'update',
+  'doctor',
   'assimilate',
   'reset-local-connection',
   'recover-enrollment',

package/src/update-cmd.ts

@@ -8,7 +8,7 @@ import { updateHelpText } from './cli-help.js';
 import { preflightBorgServerTag } from './server-handshake.js';
 import { loadBorgServerTrust } from './server-trust.js';
 import { shellEscape } from './shell-escape.js';
-import { refreshManagedAgentMcpConfigs } from './config-utils.js';
+import { refreshAndVerifyManagedAgentIntegrations } from './agent-integration-health.js';
 
 const CLIENT_PACKAGE = 'borgmcp';
 const SERVER_PACKAGE = 'borgmcp-server';
@@ -65,7 +65,7 @@ export interface UpdateDeps {
   reenter(binPath: string, args: readonly string[]): Promise<number>;
   serverJson(binPath: string, command: 'update' | 'status'): Promise<unknown>;
   verifyRunningProtocol(origin: string): Promise<void>;
-  refreshAgentMcpConfigs(): Promise<Array<'claude' | 'codex' | 'opencode'>>;
+  refreshAgentIntegrations(): Promise<void>;
   confirm(message: string): Promise<'yes' | 'no' | 'eof' | 'interrupted'>;
   isTTY(): boolean;
   stdout(text: string): void;
@@ -115,8 +115,7 @@ type ServerUpdateFailureStage =
   | 'final server state verification'
   | 'final package verification'
   | 'managed service continuity check'
-  | 'running server protocol verification'
-  | 'agent MCP config refresh';
+  | 'running server protocol verification';
 
 interface NpmContext {
   commandPath: string;
@@ -699,11 +698,10 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
 
   if (!serverWasPresent) {
     try {
-      await deps.refreshAgentMcpConfigs();
+      await deps.refreshAgentIntegrations();
     } catch (error) {
       deps.stderr(
-        `Client updated, but agent MCP config refresh failed: ${errorMessage(error, 'unknown failure')}.\n` +
-        `Run borg setup to repair Borg-written agent registrations. Configurations that use another command are not changed.\n`,
+        `Client updated, but agent integration refresh and health check failed: ${errorMessage(error, 'unknown failure')}.\n`,
       );
       return 1;
     }
@@ -821,9 +819,18 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
       retryCommand = 'borg server status';
       await deps.verifyRunningProtocol(status.endpoint!);
     }
-    failureStage = 'agent MCP config refresh';
-    retryCommand = 'borg update --yes';
-    await deps.refreshAgentMcpConfigs();
+    try {
+      await deps.refreshAgentIntegrations();
+    } catch (error) {
+      const verifiedOutcome = state === 'stopped'
+        ? 'prepared runtime verified; server remains stopped'
+        : 'running identities and protocol verified';
+      deps.stderr(
+        `Updated ${CLIENT_PACKAGE}@${pair.client.version} and ${SERVER_PACKAGE}@${pair.server.version}; ${verifiedOutcome}.\n` +
+        `Agent integration refresh and health check failed: ${errorMessage(error, 'unknown failure')}.\n`,
+      );
+      return signalExitCode(error) ?? 1;
+    }
     deps.stdout(
       state === 'stopped'
         ? (
@@ -1225,7 +1232,7 @@ export function buildDefaultUpdateDeps(): UpdateDeps {
       const trust = await loadBorgServerTrust(origin);
       await preflightBorgServerTag(origin, trust.fetchImpl);
     },
-    refreshAgentMcpConfigs: async () => refreshManagedAgentMcpConfigs(),
+    refreshAgentIntegrations: async () => refreshAndVerifyManagedAgentIntegrations(),
     confirm: defaultConfirm,
     isTTY: () => process.stdin.isTTY === true && process.stdout.isTTY === true,
     stdout: (text) => process.stdout.write(text),