@codemem/opencode-plugin 0.47.0-beta.2 → 0.47.0-beta.3

package/.opencode/lib/cached-cli-runner.js

@@ -0,0 +1,220 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const executeFile = (...args) => promisify(execFile)(...args);
+const PROBE_PATH = fileURLToPath(new URL("./cli-runner-probe.js", import.meta.url));
+const MAX_OUTPUT_BYTES = 16 * 1024;
+const PROBE_TIMEOUT_MS = 5_000;
+const BOOTSTRAP_TIMEOUT_MS = 60_000;
+const RETRY_DELAY_MS = 30_000;
+
+const readManifest = (path) => {
+  if (statSync(path).size > 64 * 1024) throw new Error("manifest_unavailable");
+  return JSON.parse(readFileSync(path, "utf8"));
+};
+
+const isContainedPath = (root, path) => {
+  const child = relative(root, path);
+  return !!child && child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute(child);
+};
+
+const containedFile = (root, path) => {
+  const canonicalPath = realpathSync(path);
+  if (!isContainedPath(realpathSync(root), canonicalPath) || !statSync(canonicalPath).isFile()) {
+    throw new Error("entrypoint_unavailable");
+  }
+  return canonicalPath;
+};
+
+const fileStamp = (path) => {
+  const canonicalPath = realpathSync(path);
+  const stat = statSync(canonicalPath);
+  if (!stat.isFile()) throw new Error("entrypoint_unavailable");
+  return [canonicalPath, stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs];
+};
+
+const candidateStamp = (candidate) => JSON.stringify(candidate.files.map(fileStamp));
+
+export const isCachedCliCurrent = (candidate) => {
+  try {
+    return candidateStamp(candidate) === candidate.stamp;
+  } catch {
+    return false;
+  }
+};
+
+const readEmbeddings = (entrypoint, version) => {
+  // Use Node's lookup paths without requiring the package's private manifest
+  // subpath to be exported. Exclude CJS global folders, which ESM cannot import.
+  const paths = createRequire(entrypoint).resolve.paths("@codemem/embeddings") || [];
+  const manifestPath = paths.filter((path) => isContainedPath(dirname(path), entrypoint))
+    .map((path) => join(path, "@codemem/embeddings/package.json")).find(existsSync);
+  const manifest = readManifest(manifestPath);
+  if (manifest.name !== "@codemem/embeddings" || manifest.version !== version) {
+    throw new Error("embeddings_unavailable");
+  }
+  const exported = manifest.exports?.["."]?.import;
+  if (typeof exported !== "string") throw new Error("embeddings_unavailable");
+  const entry = containedFile(dirname(manifestPath), resolve(dirname(manifestPath), exported));
+  return [manifestPath, entry];
+};
+
+const readCandidate = (manifestPath, { nodePath, executable, expectedVersion }) => {
+  const manifest = readManifest(manifestPath);
+  if (manifest.name !== "codemem" || typeof manifest.version !== "string"
+    || typeof manifest.bin?.codemem !== "string") throw new Error("package_unavailable");
+  if (expectedVersion && manifest.version !== expectedVersion) throw new Error("version_mismatch");
+  const entrypoint = containedFile(dirname(manifestPath), resolve(dirname(manifestPath), manifest.bin.codemem));
+  // POSIX package bins are symlinks. Windows command shims are not JS files;
+  // resolve their package metadata instead of parsing or executing the shim.
+  if (executable && !executable.endsWith(".cmd") && realpathSync(executable) !== entrypoint) {
+    throw new Error("entrypoint_mismatch");
+  }
+  const files = [nodePath, manifestPath, entrypoint];
+  if (executable) files.push(executable);
+  if (expectedVersion) files.push(...readEmbeddings(entrypoint, expectedVersion));
+  const candidate = { command: realpathSync(nodePath), args: [entrypoint], version: manifest.version, files,
+    manifestPath, executable };
+  return { ...candidate, stamp: candidateStamp(candidate) };
+};
+
+const pathCandidateManifests = ({ path, selectedOnly }) => {
+  const candidates = [];
+  for (const directory of String(path || "").slice(0, 32_768).split(delimiter).slice(0, 128)) {
+    if (!isAbsolute(directory)) continue;
+    const executable = join(directory, process.platform === "win32" ? "codemem.cmd" : "codemem");
+    if (selectedOnly && !existsSync(executable)) continue;
+    try {
+      const anchor = realpathSync(executable);
+      const manifestPath = createRequire(anchor).resolve("codemem/package.json");
+      candidates.push({ manifestPath, executable });
+    } catch { /* Check only named executable files, never enumerate cache directories. */ }
+    // Do not bypass a selected shim for another CLI later on PATH or in the
+    // plugin's dependencies. Keep its legacy invocation if it cannot be resolved.
+    if (selectedOnly) return candidates;
+  }
+  return candidates;
+};
+
+const candidateManifests = ({ path, bootstrap, selectedOnly }) => {
+  const candidates = pathCandidateManifests({ path, selectedOnly });
+  if (!bootstrap && !selectedOnly) {
+    try { candidates.push({ manifestPath: createRequire(import.meta.url).resolve("codemem/package.json") }); }
+    catch { /* The plugin need not depend on the CLI package. */ }
+  }
+  return candidates;
+};
+
+export const probeCliCandidate = async ({ path, nodePath, expectedVersion, bootstrap = false, selectedOnly = false }) => {
+  const deadline = Date.now() + 4_000;
+  for (const location of candidateManifests({ path, bootstrap, selectedOnly }).slice(0, 8)) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    try {
+      const candidate = readCandidate(location.manifestPath, { nodePath, expectedVersion, executable: location.executable });
+      const result = await executeFile(candidate.command, [...candidate.args, "--version"], {
+        timeout: remaining, maxBuffer: MAX_OUTPUT_BYTES, killSignal: "SIGKILL",
+      });
+      if (result.stdout.trim() === candidate.version && isCachedCliCurrent(candidate)) return candidate;
+    } catch { /* An unusable candidate must not select an unverified command. */ }
+  }
+  return null;
+};
+
+const runProbe = async ({ command, args, cwd, env, timeout, execute, expectedVersion }) => {
+  try {
+    const result = await execute(command, args, {
+      cwd, env, timeout, maxBuffer: MAX_OUTPUT_BYTES, killSignal: "SIGKILL",
+    });
+    const candidate = JSON.parse(result.stdout);
+    if (!candidate || !isAbsolute(candidate.command) || candidate.args?.length !== 1
+      || !isAbsolute(candidate.args[0]) || !Array.isArray(candidate.files)
+      || candidate.files.length > 6 || !isCachedCliCurrent(candidate)) return null;
+    const verified = readCandidate(candidate.manifestPath, {
+      nodePath: candidate.command, executable: candidate.executable, expectedVersion,
+    });
+    if (verified.version !== candidate.version || verified.args[0] !== candidate.args[0]
+      || verified.stamp !== candidate.stamp) return null;
+    return verified;
+  } catch {
+    return null;
+  }
+};
+
+const warnOnce = (warn) => {
+  let warned = false;
+  return (reason) => {
+    if (warned) return;
+    warned = true;
+    try { void Promise.resolve(warn(reason)).catch(() => {}); } catch { /* best effort */ }
+  };
+};
+
+const resolveDefaultCli = async ({ runner, pin, cwd, env, isCompatibleVersion, warn, execute }) => {
+  const probe = (command, args, timeout, expectedVersion) =>
+    runProbe({ command, args, timeout, cwd, env, execute, expectedVersion });
+  const probeArgs = [PROBE_PATH];
+  if (runner === "codemem") probeArgs.push("--selected");
+  const installed = await probe("node", probeArgs, PROBE_TIMEOUT_MS);
+  if (installed && isCompatibleVersion(installed.version, pin)) return installed;
+  if (installed) warn("channel_or_version_mismatch");
+  // A compatible PATH command may be a version-manager or package-manager shim.
+  // Failure to optimize it must not replace the selected backend with the pin.
+  if (runner !== "npx") return null;
+  // npm exec documents the requested packages' bins on child PATH. The shipped
+  // probe reads that PATH; it does not infer npm's private cache layout.
+  const bootstrapped = await probe("npx", [
+    "-y", "--package", `codemem@${pin}`, "--package", `@codemem/embeddings@${pin}`,
+    "node", PROBE_PATH, pin,
+  ], BOOTSTRAP_TIMEOUT_MS, pin);
+  if (bootstrapped?.version === pin) return bootstrapped;
+  warn("resolution_unavailable");
+  return null;
+};
+
+export const createCachedCliRunner = ({
+  runner, runnerArgs, explicit, pin, cwd, env = process.env,
+  isCompatibleVersion, warn = () => {}, now = Date.now, execute = executeFile,
+}) => {
+  let cached = null;
+  let pending = null;
+  let retryAt = 0;
+  let generation = 0;
+  const report = warnOnce(warn);
+
+  const invalidate = () => { cached = null; pending = null; retryAt = 0; generation += 1; };
+  const resolveInvocation = async () => {
+    if (pending) return pending;
+    if (cached && isCachedCliCurrent(cached)) return cached;
+    cached = null;
+    if (now() < retryAt) return null;
+    const startedGeneration = generation;
+    const resolution = resolveDefaultCli({ runner, pin, cwd, env, isCompatibleVersion, warn: report, execute })
+      .catch(() => null)
+      .then((candidate) => {
+        if (startedGeneration !== generation) return null;
+        cached = candidate;
+        if (!candidate) retryAt = now() + RETRY_DELAY_MS;
+        return candidate;
+      })
+      .finally(() => { if (pending === resolution) pending = null; });
+    pending = resolution;
+    return resolution;
+  };
+
+  const command = (args) => {
+    if (explicit) return [runner, ...runnerArgs, ...args];
+    return resolveInvocation().then((invocation) => {
+      if (!invocation) {
+        if (runner === "codemem") return [runner, ...runnerArgs, ...args];
+        return null;
+      }
+      return [invocation.command, ...invocation.args, ...args];
+    });
+  };
+  return { command, invalidate };
+};

package/.opencode/lib/cli-runner-probe.js

@@ -0,0 +1,21 @@
+import { probeCliCandidate } from "./cached-cli-runner.js";
+
+// This script runs under the PATH-selected Node, not the plugin host executable.
+// npm exec supplies its package bins through PATH on the one bootstrap call.
+const main = async () => {
+  if (process.release?.name !== "node" || process.versions.bun) return;
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  if (major < 24 || (major === 24 && minor < 15)) return;
+  const selectedOnly = process.argv[2] === "--selected";
+  const expectedVersion = selectedOnly ? undefined : process.argv[2];
+  const candidate = await probeCliCandidate({
+    path: process.env.PATH,
+    nodePath: process.execPath,
+    expectedVersion,
+    selectedOnly,
+    bootstrap: expectedVersion !== undefined,
+  });
+  if (candidate) process.stdout.write(JSON.stringify(candidate));
+};
+
+main().catch(() => { process.exitCode = 1; });

package/.opencode/lib/prompt-transport-diagnostics.js

@@ -0,0 +1,75 @@
+const REASONS = [
+  "success", "disabled", "backoff", "profile_malformed", "protocol_mismatch",
+  "database_mismatch", "identity_mismatch", "contract_unsupported",
+  "request_rejected", "authorization_failure", "policy_failure",
+  "endpoint_unavailable", "server_failure", "unexpected_status",
+  "malformed_response", "timeout", "connection_failure", "unknown",
+];
+const OPERATIONS = ["pack", "prompt-pack-ledger"];
+const RUNNERS = ["viewer", "none", "codemem", "npx", "node", "uvx", "uv", "custom"];
+const STAGES = ["skipped", "profile", "request"];
+const MAX_COUNT = 1_000_000;
+const MAX_ELAPSED_MS = 86_400_000;
+const LOG_INTERVAL_MS = 30_000;
+
+const increment = (count) => Math.min(MAX_COUNT, count + 1);
+const boundedElapsed = (value) => Number.isFinite(value)
+  ? Math.min(MAX_ELAPSED_MS, Math.max(0, Math.round(value)))
+  : 0;
+
+const safeFields = (input) => ({
+  stage: STAGES.includes(input.stage) ? input.stage : "skipped",
+  elapsed_ms: boundedElapsed(input.elapsed_ms),
+  runner: RUNNERS.includes(input.runner) ? input.runner : "custom",
+  disposition: ["fallback", "local_fallback", "terminal"].includes(input.disposition)
+    ? input.disposition : "unknown",
+  status_class: ["2xx", "3xx", "4xx", "5xx"].includes(input.status_class)
+    ? input.status_class : "none",
+});
+
+// Only fixed categories and bounded numbers cross this boundary. No request,
+// response, error, runner path, or identity is retained, even in suppressed logs.
+export const createPromptTransportDiagnostics = ({ logLine, now = () => performance.now() }) => {
+  const counters = Object.fromEntries(OPERATIONS.map((operation) => [
+    operation, Object.fromEntries(REASONS.map((reason) => [reason, 0])),
+  ]));
+  let suppressed = 0;
+  let nextLogAt = -Infinity;
+  let writing = false;
+
+  const snapshot = () => ({
+    counters: Object.fromEntries(OPERATIONS.map((operation) => [operation, { ...counters[operation] }])),
+    suppressed,
+  });
+
+  const record = (input) => {
+    if (!OPERATIONS.includes(input.operation)) return;
+    const reason = REASONS.includes(input.reason) ? input.reason : "unknown";
+    const counts = counters[input.operation];
+    counts[reason] = increment(counts[reason]);
+    if (reason === "success") return;
+    const timestamp = now();
+    if (writing || timestamp < nextLogAt) {
+      suppressed = increment(suppressed);
+      return;
+    }
+    nextLogAt = timestamp + LOG_INTERVAL_MS;
+    const entry = {
+      operation: input.operation,
+      reason,
+      ...safeFields(input),
+      ...snapshot(),
+    };
+    suppressed = 0;
+    writing = true;
+    try {
+      void Promise.resolve(logLine(`inject.transport ${JSON.stringify(entry)}`))
+        .catch(() => {})
+        .finally(() => { writing = false; });
+    } catch {
+      writing = false;
+    }
+  };
+
+  return { record, snapshot };
+};

package/.opencode/lib/runtime.js

@@ -4,6 +4,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { appendFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, posix, resolve, win32 } from "node:path";
+import { createCachedCliRunner } from "./cached-cli-runner.js";
 import {
   isVersionAtLeast,
   parseBackendUpdatePolicy,
@@ -12,6 +13,7 @@ import {
   resolveUpgradeGuidance,
 } from "./compat.js";
 import { V2_ADAPTER_DIAGNOSTICS } from "./host-contract.js";
+import { createPromptTransportDiagnostics } from "./prompt-transport-diagnostics.js";
 import {
   classifyRawEventTransportCause,
   createRawEventDelivery,
@@ -30,7 +32,7 @@ import {
 
 const TRUTHY_VALUES = ["1", "true", "yes"];
 const DISABLED_VALUES = ["0", "false", "off"];
-const PINNED_BACKEND_VERSION = "0.47.0-beta.2";
+const PINNED_BACKEND_VERSION = "0.47.0-beta.3";
 const COMPAT_CHECK_DELAY_MS = 1500;
 const COMPAT_CHECK_CACHE_TTL_MS = 5 * 60 * 1000;
 const MAX_UPDATE_STATUS_BYTES = 16 * 1024;
@@ -939,6 +941,84 @@ const isViewerPolicyOrAuthFailurePayload = (payload) => {
   ].includes(code);
 };
 
+const diagnosticTimeoutReason = (signal, fallback) =>
+  signal?.aborted && signal.reason?.name === "TimeoutError" ? "timeout" : fallback;
+
+const diagnosticStatusClass = (status) =>
+  Number.isInteger(status) ? `${Math.floor(status / 100)}xx` : "none";
+
+const viewerHttpDiagnosticReason = ({ operation, status, body, signal }) => {
+  // A timeout is reported only when our own deadline fired, never from raw
+  // exception text or merely observing that a CLI fallback was selected.
+  if (diagnosticTimeoutReason(signal) === "timeout") return "timeout";
+  if (isViewerDbMismatchPayload(body)) return "database_mismatch";
+  if (isViewerIdentityMismatchPayload(body)) return "identity_mismatch";
+  if (isViewerContractUnsupportedPayload(body)) return "contract_unsupported";
+  if (operation === "prompt-pack-ledger" && isValidLedgerFailureHttpPayload(body)) {
+    return "request_rejected";
+  }
+  if (status === 401 || status === 403) return "authorization_failure";
+  if (isViewerPolicyOrAuthFailurePayload(body)) return "policy_failure";
+  if (isViewerInvalidRequestPayload(body)) {
+    return "request_rejected";
+  }
+  if (status === 404 || status === 405) return "endpoint_unavailable";
+  if (Number.isInteger(status) && status >= 500) return "server_failure";
+  if (Number.isInteger(status)) return "unexpected_status";
+  return "connection_failure";
+};
+
+const viewerProfileFailureKind = (profileBody, dbPath, identityTarget) => {
+  if (!isRecord(profileBody) || profileBody.service !== "codemem-viewer") return "profile_malformed";
+  const range = normalizePromptTransportProtocolRange(
+    profileBody.protocol_version, profileBody.min_supported_protocol_version,
+  );
+  if (!range) return "protocol_malformed";
+  if (!arePromptTransportProtocolRangesCompatible(PROMPT_TRANSPORT_PROTOCOL_RANGE, range)) {
+    return "protocol_range_mismatch";
+  }
+  if (profileBody.db_path !== dbPath) return "database_mismatch";
+  if (canonicalJson(profileBody.identity_target) !== canonicalJson(identityTarget)) {
+    return "runtime_identity_mismatch";
+  }
+  return null;
+};
+
+const classifyViewerProfileFailure = (profileBody, { operation, dbPath, identityTarget }) => {
+  const kind = viewerProfileFailureKind(profileBody, dbPath, identityTarget);
+  if (!kind) return null;
+  const details = {
+    profile_malformed: ["profile malformed", "profile_malformed"],
+    protocol_malformed: ["protocol range malformed", "profile_malformed"],
+    protocol_range_mismatch: ["protocol range unsupported", "protocol_mismatch"],
+    database_mismatch: ["database mismatch", "database_mismatch"],
+    runtime_identity_mismatch: ["runtime identity mismatch", "identity_mismatch"],
+  };
+  const [description, reason] = details[kind];
+  return {
+    classification: viewerFailureClassification(
+      `${operation} viewer ${description}`, classifyPromptTransportFailure({ kind }),
+    ),
+    reason,
+  };
+};
+
+const createPromptTransportResult = ({ operation, runner, diagnostics, viewerOnly, timing }) =>
+  (result, reason, status = null) => {
+    let selectedRunner = "viewer";
+    if (!result.ok) {
+      selectedRunner = result.classification.retryable && !viewerOnly ? runner : "none";
+    }
+    diagnostics.record({
+      operation, reason, stage: timing.stage,
+      elapsed_ms: performance.now() - timing.startedAt,
+      status_class: diagnosticStatusClass(status),
+      runner: selectedRunner,
+      disposition: result.classification?.disposition,
+    });
+    return result;
+  };
+
 const viewerFailureClassification = (cause, disposition, kind = null) => ({
   cause,
   disposition,
@@ -2171,6 +2251,27 @@ const buildRunnerArgs = ({ runner, runnerFrom, runnerFromExplicit }) => {
   return runnerFromExplicit ? [runnerFrom] : [];
 };
 
+const resolveRuntimeRunner = ({ cwd, log }) => {
+  const runner = detectRunner({ cwd, envRunner: process.env.CODEMEM_RUNNER });
+  const runnerFromExplicit = Boolean(String(process.env.CODEMEM_RUNNER_FROM || "").trim());
+  const runnerFrom = process.env.CODEMEM_RUNNER_FROM || cwd;
+  const runnerArgs = buildRunnerArgs({ runner, runnerFrom, runnerFromExplicit });
+  const cliRunner = createCachedCliRunner({
+    runner, runnerArgs, pin: PINNED_BACKEND_VERSION, cwd,
+    explicit: Object.hasOwn(process.env, "CODEMEM_RUNNER") || Object.hasOwn(process.env, "CODEMEM_RUNNER_FROM"),
+    isCompatibleVersion: isSameChannelVersionAtLeast,
+    warn: (reason) => log("warn", "codemem default CLI runner could not be reused", { reason }),
+  });
+  return { runner, runnerArgs, runnerFrom, runnerFromExplicit, cliRunner };
+};
+
+const createViewerCliArgs = ({ viewerHost, viewerPort, viewerDbPath, viewerConfigPath }) => (action) => {
+  const args = ["serve", action, "--host", viewerHost, "--port", viewerPort];
+  if (String(viewerDbPath || "").trim()) args.push("--db-path", viewerDbPath);
+  if (String(viewerConfigPath || "").trim()) args.push("--config", viewerConfigPath);
+  return args;
+};
+
 export const createCodememRuntime = async ({ location, host, hostGeneration = null }) => {
   const { project, directory, worktree } = location;
   const hostLog = typeof host?.log === "function" ? host.log : async () => {};
@@ -2203,6 +2304,7 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
   const errorLogPath = resolveErrorLogPath(cwd, process.env.HOME);
   const logLine = createLogLine(logPath);
   const errorLogLine = createLogLine(errorLogPath);
+  const promptTransportDiagnostics = createPromptTransportDiagnostics({ logLine: errorLogLine });
   const log = createDebugLogger({
     debug,
     host: { log: hostLog },
@@ -2225,13 +2327,7 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
     return null;
   }
 
-  const runner = detectRunner({
-    cwd,
-    envRunner: process.env.CODEMEM_RUNNER,
-  });
-  const runnerFromExplicit = Boolean(String(process.env.CODEMEM_RUNNER_FROM || "").trim());
-  const runnerFrom = process.env.CODEMEM_RUNNER_FROM || cwd;
-  const runnerArgs = buildRunnerArgs({ runner, runnerFrom, runnerFromExplicit });
+  const { runner, runnerArgs, runnerFrom, runnerFromExplicit, cliRunner } = resolveRuntimeRunner({ cwd, log });
   const viewerEnabled = envNotDisabled(process.env.CODEMEM_VIEWER || "1");
   const viewerAutoStart = envNotDisabled(
     process.env.CODEMEM_VIEWER_AUTO || "1"
@@ -2361,16 +2457,7 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
     return `${Date.now()}-${Math.random()}`;
   };
 
-  const buildViewerCliArgs = (action) => {
-    const args = ["serve", action, "--host", viewerHost, "--port", viewerPort];
-    if (String(viewerDbPath || "").trim()) {
-      args.push("--db-path", viewerDbPath);
-    }
-    if (String(viewerConfigPath || "").trim()) {
-      args.push("--config", viewerConfigPath);
-    }
-    return args;
-  };
+  const buildViewerCliArgs = createViewerCliArgs({ viewerHost, viewerPort, viewerDbPath, viewerConfigPath });
 
   // Session context tracking for comprehensive memories
   const createSessionContext = () => ({
@@ -2702,9 +2789,10 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
       return;
     }
     const viewerArgs = buildViewerCliArgs("start");
-    const cmd = [runner, ...runnerArgs, ...viewerArgs];
-    logLine(`auto-starting viewer: ${cmd.join(" ")}`).catch(() => {});
     try {
+      const cmd = await cliRunner.command(viewerArgs);
+      if (!cmd || !runtimeActive) { viewerStartInFlight = false; return; }
+      logLine("auto-starting viewer").catch(() => {});
       const child = nodeSpawn(cmd[0], cmd.slice(1), {
         cwd,
         env: process.env,
@@ -2800,8 +2888,20 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
     });
   };
 
-  const runCli = async (args, options = {}) =>
-    runCommand([runner, ...runnerArgs, ...args], options);
+  const runCli = (args, options = {}) => {
+    const command = cliRunner.command(args);
+    if (Array.isArray(command)) return runCommand(command, options);
+    return command.then((cmd) => {
+      if (!cmd) return { exitCode: 1, stdout: "", stderr: "CLI runner unavailable" };
+      return runCommand(cmd, options);
+    });
+  };
+
+  const installCliUpdate = async (command) => {
+    const result = await runCommand(command, { env: resolveAutoUpdateEnvironment(), timeoutMs: 480_000 });
+    if (result?.exitCode === 0) cliRunner.invalidate();
+    return result;
+  };
 
   rawEventDelivery = createRawEventDelivery({
     backoffMs: rawEventsBackoffMs,
@@ -2830,32 +2930,39 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
     spoolMaxEntries: rawEventSpoolMaxEntries,
   });
 
-  const postViewerJson = async ({ url, operation, payload, validate }) => {
+  const postViewerJson = async ({ url, operation, payload, validate, viewerOnly = false }) => {
+    const timing = { startedAt: performance.now(), stage: "skipped" };
+    let signal;
+    const finish = createPromptTransportResult({
+      operation, runner, diagnostics: promptTransportDiagnostics, viewerOnly, timing,
+    });
     if (!viewerEnabled) {
-      return {
+      return finish({
         ok: false,
         classification: viewerFailureClassification(
           `${operation} viewer transport disabled`,
           "fallback",
         ),
-      };
+      }, "disabled");
     }
     if (Date.now() < promptPackTransportUnavailableUntil) {
-      return {
+      return finish({
         ok: false,
         classification: viewerFailureClassification(
           `${operation} viewer transport in backoff`,
           "fallback",
         ),
-      };
+      }, "backoff");
     }
 
     let response;
     try {
+      timing.stage = "profile";
+      signal = AbortSignal.timeout(promptPackHttpTimeout);
       const profileResponse = await fetch(promptPackProfileUrl, {
         method: "GET",
         redirect: "manual",
-        signal: AbortSignal.timeout(promptPackHttpTimeout),
+        signal,
       });
       let profileBody;
       try {
@@ -2872,65 +2979,34 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
         if (classification.retryable) {
           promptPackTransportUnavailableUntil = Date.now() + Math.max(1000, rawEventsBackoffMs);
         }
-        return { ok: false, classification };
-      }
-      const viewerProtocolRange = isRecord(profileBody)
-        ? normalizePromptTransportProtocolRange(
-            profileBody.protocol_version,
-            profileBody.min_supported_protocol_version,
-          )
-        : null;
-      let profileFailure = null;
-      if (!isRecord(profileBody) || profileBody.service !== "codemem-viewer") {
-        profileFailure = viewerFailureClassification(
-          `${operation} viewer profile malformed`,
-          classifyPromptTransportFailure({ kind: "profile_malformed" }),
-        );
-      } else if (!viewerProtocolRange) {
-        profileFailure = viewerFailureClassification(
-          `${operation} viewer protocol range malformed`,
-          classifyPromptTransportFailure({ kind: "profile_malformed" }),
-        );
-      } else if (!arePromptTransportProtocolRangesCompatible(
-        PROMPT_TRANSPORT_PROTOCOL_RANGE,
-        viewerProtocolRange,
-      )) {
-        profileFailure = viewerFailureClassification(
-          `${operation} viewer protocol range unsupported`,
-          classifyPromptTransportFailure({ kind: "protocol_range_mismatch" }),
-        );
-      } else if (profileBody.db_path !== promptPackDbPath) {
-        profileFailure = viewerFailureClassification(
-          `${operation} viewer database mismatch`,
-          classifyPromptTransportFailure({ kind: "database_mismatch" }),
-        );
-      } else if (
-        canonicalJson(profileBody.identity_target) !== canonicalJson(promptPackIdentityTarget)
-      ) {
-        profileFailure = viewerFailureClassification(
-          `${operation} viewer runtime identity mismatch`,
-          classifyPromptTransportFailure({ kind: "runtime_identity_mismatch" }),
-        );
+        return finish({ ok: false, classification }, viewerHttpDiagnosticReason({
+          operation: `${operation} profile`, status: profileResponse.status, body: profileBody, signal,
+        }), profileResponse.status);
       }
+      const profileFailure = classifyViewerProfileFailure(profileBody, {
+        operation, dbPath: promptPackDbPath, identityTarget: promptPackIdentityTarget,
+      });
       if (profileFailure) {
         promptPackTransportUnavailableUntil = Date.now() + Math.max(1000, rawEventsBackoffMs);
-        return {
+        return finish({
           ok: false,
-          classification: profileFailure,
-        };
+          classification: profileFailure.classification,
+        }, diagnosticTimeoutReason(signal, profileFailure.reason), profileResponse.status);
       }
+      timing.stage = "request";
+      signal = AbortSignal.timeout(promptPackHttpTimeout);
       response = await fetch(url, {
         method: "POST",
         redirect: "manual",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(payload),
-        signal: AbortSignal.timeout(promptPackHttpTimeout),
+        signal,
       });
     } catch (error) {
       const classification = classifyViewerHttpFailure({ operation, error });
       promptPackTransportUnavailableUntil =
         Date.now() + Math.max(1000, rawEventsBackoffMs);
-      return { ok: false, classification };
+      return finish({ ok: false, classification }, viewerHttpDiagnosticReason({ operation, signal }));
     }
 
     let body;
@@ -2950,18 +3026,20 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
         promptPackTransportUnavailableUntil =
           Date.now() + Math.max(1000, rawEventsBackoffMs);
       }
-      return { ok: false, classification };
+      return finish({ ok: false, classification }, viewerHttpDiagnosticReason({
+        operation, status: response.status, body, signal,
+      }), response.status);
     }
 
     if (!validate(body)) {
       const classification = classifyViewerHttpFailure({ operation, malformed: true });
       promptPackTransportUnavailableUntil =
         Date.now() + Math.max(1000, rawEventsBackoffMs);
-      return { ok: false, classification };
+      return finish({ ok: false, classification }, diagnosticTimeoutReason(signal, "malformed_response"), response.status);
     }
 
     promptPackTransportUnavailableUntil = 0;
-    return { ok: true, body };
+    return finish({ ok: true, body }, "success", response.status);
   };
 
   const runPromptPackLedger = async (payload, { viewerOnly = false } = {}) => {
@@ -2973,6 +3051,7 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
     const httpResult = await postViewerJson({
       url: promptPackLedgerUrl,
       operation: "prompt-pack-ledger",
+      viewerOnly,
       payload: viewerPayload,
       validate: isValidLedgerHttpPayload,
     });
@@ -3152,10 +3231,7 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
         return;
       }
       await logLine(`compat.auto_update_start cmd=${autoPlan.commandText}`);
-      const updateResult = await runCommand(autoPlan.command, {
-        env: resolveAutoUpdateEnvironment(),
-        timeoutMs: 480_000,
-      });
+      const updateResult = await installCliUpdate(autoPlan.command);
       if (updateResult?.exitCode === 0) {
         await logLine(
           `compat.auto_update_result exit=${updateResult?.exitCode ?? "unknown"} stderr=${redactLog(
@@ -3234,10 +3310,7 @@ export const createCodememRuntime = async ({ location, host, hostGeneration = nu
       });
       if (autoPlan.allowed) {
         await logLine(`release.auto_update_start cmd=${autoPlan.commandText}`);
-        const installation = await runCommand(autoPlan.command, {
-          env: resolveAutoUpdateEnvironment(),
-          timeoutMs: 480_000,
-        });
+        const installation = await installCliUpdate(autoPlan.command);
         if (installation?.exitCode === 0) {
           const verification = await runCli(["version"]);
           const installedVersion = (verification?.stdout || "").trim();
@@ -4757,6 +4830,9 @@ export const __testUtils = {
   arePromptTransportProtocolRangesCompatible,
   classifyPromptTransportFailure,
   classifyViewerHttpFailure,
+  viewerHttpDiagnosticReason,
+  classifyViewerProfileFailure,
+  createPromptTransportResult,
   isValidPackHttpPayload,
   isValidLedgerHttpPayload,
   buildPackHttpBody,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemem/opencode-plugin",
-  "version": "0.47.0-beta.2",
+  "version": "0.47.0-beta.3",
   "description": "CodeMem plugin for OpenCode",
   "type": "module",
   "main": "./index.js",