@memorax/memorax-code 0.1.3 → 0.1.5

package/README.md

@@ -5,7 +5,7 @@ Harness, and OpenCode.
 
 ## Requirements
 
-- Node.js 24 or newer and npm.
+- Node.js 20 or newer (Node.js 24 LTS recommended) and npm.
 - At least one of Codex, Claude Code, DeepSeek Harness, OpenCode Desktop, or
   the OpenCode CLI.
 - A MemoraX account, Base User ID, and API key for memory features.

package/docs/configuration.md

@@ -96,7 +96,11 @@ $DSH_HOME/profiles/<profile-name>/
 under `$MEMORAX_CODE_HOME/adapters/dsh/runtime/generations/` and installed into
 Profiles through DSH's native plugin command. The globally installed npm
 package remains immutable; do not copy or edit the generated state or runtime
-directories by hand.
+directories by hand. When at least one valid Profile exists but none provides
+a loadable `@deepseek-ai/dsh-headless` bundle, MemoraX Code asks the same native
+plugin command to initialize the standard `headless` Profile when that name is
+available. Stop and uninstall remove the MemoraX Code adapter from this Profile
+but preserve the Profile and its native data.
 
 MemoraX Code is tested with DSH `0.1.0-rc.6`. Other valid semantic versions are
 accepted but appear as untested in status output; compatibility is not

package/lib/memorax-code-backend/dist/lifecycle/backend/process.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 const POSIX_PROCESS_PROBE_TIMEOUT_MS = 2_000;
 const WINDOWS_PROCESS_PROBE_TIMEOUT_MS = 10_000;
@@ -48,6 +49,26 @@ export function probeProcessCommandLine(pid, runtime = {}) {
     if (!Number.isSafeInteger(pid) || pid <= 0) {
         return { status: "inconclusive", reason: "invalid_pid", timeoutMs };
     }
+    if (platform === "linux") {
+        try {
+            const rawCommandLine = (runtime.readFileSync ?? readFileSync)(`/proc/${pid}/cmdline`);
+            const commandLine = rawCommandLine.toString("utf8").replaceAll("\0", " ").trim();
+            return commandLine
+                ? { status: "ok", commandLine }
+                : { status: "not_found" };
+        }
+        catch (error) {
+            const code = error instanceof Error
+                ? error.code
+                : undefined;
+            return {
+                status: "inconclusive",
+                reason: "read_error",
+                timeoutMs,
+                ...(code ? { code } : {}),
+            };
+        }
+    }
     const run = runtime.spawnSync ?? runProbeCommand;
     let command;
     let args;

package/lib/memorax-code-backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorax-code/backend",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": true,
   "type": "module",
   "description": "Local memory integration, lifecycle, trace, and diagnostics for MemoraX Code.",
@@ -17,7 +17,7 @@
     "test:memory-viewer": "npm run build && node --test --test-timeout=5000 --test-force-exit test/viewer/http/memory-viewer-routes.test.mjs"
   },
   "devDependencies": {
-    "@types/node": "^24.13.2",
+    "@types/node": "^20.0.0",
     "typescript": "^5.9.0"
   },
   "dependencies": {

package/lib/memorax-code-claude-adapter/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorax-code-claude-adapter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Memory skill and local hooks for MemoraX Code in Claude Code.",
   "author": {
     "name": "MemoraX Code Maintainers"

package/lib/memorax-code-claude-adapter/hooks/runtime-shell.json

@@ -1,5 +1,5 @@
 {
   "version": 1,
-  "shellVersion": "0.1.3",
+  "shellVersion": "0.1.5",
   "runtimeAbi": 1
 }

package/lib/memorax-code-claude-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorax-code/claude-adapter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": true,
   "type": "module",
   "description": "Claude Code Hook adapter for MemoraX Code memory services.",

package/lib/memorax-code-claude-marketplace/plugins/memorax-code-claude-adapter/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorax-code-claude-adapter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Memory skill and local hooks for MemoraX Code in Claude Code.",
   "author": {
     "name": "MemoraX Code Maintainers"

package/lib/memorax-code-claude-marketplace/plugins/memorax-code-claude-adapter/hooks/runtime-shell.json

@@ -1,5 +1,5 @@
 {
   "version": 1,
-  "shellVersion": "0.1.3",
+  "shellVersion": "0.1.5",
   "runtimeAbi": 1
 }

package/lib/memorax-code-claude-marketplace/plugins/memorax-code-claude-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorax-code/claude-adapter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": true,
   "type": "module",
   "description": "Claude Code Hook adapter for MemoraX Code memory services.",

package/lib/memorax-code-codex-adapter/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorax-code-codex-adapter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Codex adapter, memory skill, and local hooks for MemoraX Code.",
   "author": {
     "name": "MemoraX AI"

package/lib/memorax-code-codex-adapter/hooks/runtime-shell.json

@@ -1,5 +1,5 @@
 {
   "version": 1,
-  "shellVersion": "0.1.3",
+  "shellVersion": "0.1.5",
   "runtimeAbi": 1
 }

package/lib/memorax-code-codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorax-code/codex-adapter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": true,
   "type": "module",
   "description": "Codex Hook and memory integration for MemoraX Code.",

package/lib/memorax-code-dsh-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorax-code/dsh-memorax-code",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": true,
   "type": "module",
   "description": "DeepSeek Harness native memory adapter for MemoraX Code.",

package/lib/memorax-code-dsh-adapter/src/profile-lifecycle.mjs

@@ -50,6 +50,8 @@ const { resolveWindowsCliInvocation } = await import(
 const STATE_VERSION = 1;
 const RUNTIME = "dsh";
 const ADAPTER_PACKAGE_NAME = "@memorax-code/dsh-memorax-code";
+const HEADLESS_PROFILE_NAME = "headless";
+const HEADLESS_BUNDLE_NAME = "@deepseek-ai/dsh-headless";
 const LEGACY_ADAPTER_PACKAGE_NAMES = Object.freeze(["@memorax-code/dsh-adapter"]);
 const MANAGED_ADAPTER_PACKAGE_NAMES = Object.freeze([
   ADAPTER_PACKAGE_NAME,
@@ -142,7 +144,8 @@ export function collectDshAdapterStatus(options = {}) {
     );
     const managed = Boolean(state) && !stateProblem;
     const installed = profiles.length > 0
-      && profiles.every((profile) => profile.managed && profile.exists && profile.installed);
+      && profiles.every((profile) => profile.managed && profile.exists && profile.installed)
+      && managedProfilesHaveInstalledHeadlessBundle(discoveredProfiles, managedNames);
     const base = {
       integration: "plugin",
       managed,
@@ -283,7 +286,8 @@ function readDshPluginStatusUnlocked(paths, options) {
     state,
   );
   const installed = state.profiles.length > 0
-    && managedProfiles.every((profile) => profile.installed);
+    && managedProfiles.every((profile) => profile.installed)
+    && managedProfilesHaveInstalledHeadlessBundle(profiles, new Set(state.profiles));
   return {
     ok: true,
     action: "dsh-plugin-status",
@@ -358,6 +362,38 @@ function ensureDshPluginInstalledUnlocked(paths, options) {
     };
   }
 
+  let workerProfileName = profiles.find(profileHasInstalledHeadlessBundle)?.name;
+  let targetProfiles = profiles;
+  let initializeWorkerProfile = false;
+  if (!workerProfileName) {
+    const headlessPath = join(paths.profilesRoot, HEADLESS_PROFILE_NAME);
+    const headless = inspectProfile(HEADLESS_PROFILE_NAME, headlessPath);
+    if (headless.status === "manifest_unreadable") {
+      return {
+        ok: false,
+        action: "dsh-plugin-install",
+        runtime: RUNTIME,
+        reason: "profile_manifest_unreadable",
+        profiles: [HEADLESS_PROFILE_NAME],
+      };
+    }
+    if (headless.status === "valid") {
+      return {
+        ok: false,
+        action: "dsh-plugin-install",
+        runtime: RUNTIME,
+        reason: "headless_profile_not_capable",
+        profiles: [HEADLESS_PROFILE_NAME],
+      };
+    }
+    workerProfileName = HEADLESS_PROFILE_NAME;
+    initializeWorkerProfile = true;
+    targetProfiles = [
+      ...profiles,
+      { name: HEADLESS_PROFILE_NAME, path: headlessPath },
+    ].sort((left, right) => left.name.localeCompare(right.name));
+  }
+
   const memoraxCodeCommand = resolveMemoraxCodeCommand(options.memoraxCodeCommand);
   const metadata = {
     version: 1,
@@ -387,7 +423,7 @@ function ensureDshPluginInstalledUnlocked(paths, options) {
     // interrupted or partial native add remains repairable and removable.
     profiles: [...new Set([
       ...previouslyManaged,
-      ...profiles.map((profile) => profile.name),
+      ...targetProfiles.map((profile) => profile.name),
     ])].sort(),
     updatedAt: now,
   };
@@ -396,9 +432,12 @@ function ensureDshPluginInstalledUnlocked(paths, options) {
   const installedProfiles = [];
   const failedProfiles = [];
   const mutatedProfiles = [];
-  for (const profile of profiles) {
+  for (const profile of targetProfiles) {
     let current = inspectProfile(profile.name, profile.path);
-    if (current.status !== "valid") {
+    if (current.status !== "valid"
+      && !(initializeWorkerProfile
+        && profile.name === workerProfileName
+        && current.status === "directory_missing")) {
       failedProfiles.push(current.status === "directory_missing"
         ? { name: profile.name, reason: "profile_disappeared" }
         : profileManifestFailure(profile.name));
@@ -420,12 +459,16 @@ function ensureDshPluginInstalledUnlocked(paths, options) {
       if (result.status !== 0
         || result.error
         || current.status !== "valid"
-        || !profileHasInstalledAdapter(current.profile, runtimeBundleRoot, pendingState)) {
+        || !profileHasInstalledAdapter(current.profile, runtimeBundleRoot, pendingState)
+        || (profile.name === workerProfileName
+          && !profileHasInstalledHeadlessBundle(current.profile))) {
         failedProfiles.push(profileMutationFailure(
           profile.name,
           result,
           current,
-          "dsh_bundle_not_activated",
+          profile.name === workerProfileName
+            ? "headless_profile_not_capable"
+            : "dsh_bundle_not_activated",
         ));
         continue;
       }
@@ -450,7 +493,9 @@ function ensureDshPluginInstalledUnlocked(paths, options) {
     }
 
     if (current.status === "valid"
-      && profileHasInstalledAdapter(current.profile, runtimeBundleRoot, pendingState)) {
+      && profileHasInstalledAdapter(current.profile, runtimeBundleRoot, pendingState)
+      && (profile.name !== workerProfileName
+        || profileHasInstalledHeadlessBundle(current.profile))) {
       installedProfiles.push(profile.name);
     } else {
       failedProfiles.push(profileMutationFailure(
@@ -474,6 +519,11 @@ function ensureDshPluginInstalledUnlocked(paths, options) {
       failedProfiles.push({ name: profile.name, reason: "dsh_bundle_not_activated" });
     }
   }
+  if (!finalProfiles.some((profile) => (
+    profile.status === "valid" && profileHasInstalledHeadlessBundle(profile.profile)
+  )) && !failedProfiles.some((failure) => failure.name === workerProfileName)) {
+    failedProfiles.push({ name: workerProfileName, reason: "headless_profile_not_capable" });
+  }
   const managedProfiles = finalProfiles
     .filter((profile) => profile.status !== "directory_missing")
     .map((profile) => profile.name);
@@ -644,7 +694,8 @@ function activateDshPluginInstallationUnlocked(paths, options) {
   if (state.profiles.length === 0
     || state.profiles.some((name) => (
       !profileHasInstalledAdapter(profileByName.get(name), state.runtimeBundleRoot, state)
-    ))) {
+    ))
+    || !managedProfilesHaveInstalledHeadlessBundle(profiles, new Set(state.profiles))) {
     return {
       ok: false,
       action: "dsh-plugin-activate",
@@ -1162,6 +1213,24 @@ function profileHasAdapter(profile, packageName = ADAPTER_PACKAGE_NAME) {
     && profile.bundles.includes(packageName));
 }
 
+function managedProfilesHaveInstalledHeadlessBundle(profiles, managedNames) {
+  return profiles.some((profile) => (
+    managedNames.has(profile.name) && profileHasInstalledHeadlessBundle(profile)
+  ));
+}
+
+function profileHasInstalledHeadlessBundle(profile) {
+  if (!profile?.bundles.includes(HEADLESS_BUNDLE_NAME)) return false;
+  try {
+    // DSH exposes built-in bundles through the Profile's shared resolution tree.
+    const requireFromProfile = createRequire(join(profile.path, "package.json"));
+    readFileSync(requireFromProfile.resolve(HEADLESS_BUNDLE_NAME), "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function profileHasInstalledAdapter(
   profile,
   runtimeBundleRoot,

package/lib/memorax-code-opencode-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorax-code/opencode-adapter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": true,
   "type": "module",
   "description": "OpenCode plugin adapter for MemoraX Code memory services.",

package/lib/memorax-code-opencode-adapter/src/plugin.mjs

@@ -254,6 +254,8 @@ export function createMemoraxOpenCodePlugin(options = {}) {
         output.env.MEMORAX_CODE_MEMORY_CLI_TRACE_CLIENT = "opencode";
         if (openCodeServerUrl) {
           output.env.MEMORAX_CODE_OPENCODE_SERVER_URL = openCodeServerUrl;
+          output.env.MEMORAX_CODE_OPENCODE_COMMAND = stringValue(options.openCodeCommand)
+            ?? process.execPath;
         }
         const sessionId = stringValue(input?.sessionID);
         delete output.env.MEMORAX_CODE_MEMORY_CLI_TRACE_SESSION_ID;
@@ -441,6 +443,7 @@ function openCodeRepoMemoryEnv(options, serverUrl, sessionId) {
     ...process.env,
     MEMORAX_CODE_HOME: memoraxCodeHome,
     MEMORAX_CODE_MEMORY_CLI_SESSION_ID: sessionId,
+    MEMORAX_CODE_OPENCODE_COMMAND: stringValue(options.openCodeCommand) ?? process.execPath,
     MEMORAX_CODE_OPENCODE_SERVER_URL: serverUrl,
   };
 }

package/lib/memorax-code-opencode-adapter/src/repo-memory-server-runner.mjs

@@ -1,39 +1,103 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const OPENCODE_REPO_MEMORY_AGENT = "memorax-code-repo-memory";
 
+const OWNED_SERVER_USERNAME = "memorax-code";
+const DEFAULT_SERVER_START_TIMEOUT_MS = 20_000;
+const DEFAULT_SERVER_STOP_TIMEOUT_MS = 5_000;
+const MAX_SERVER_START_OUTPUT = 8_192;
+
+class OpenCodeTransportError extends Error {
+  constructor(operation, cause) {
+    super(`OpenCode ${operation} request failed: ${errorMessage(cause)}`);
+    this.name = "OpenCodeTransportError";
+    this.operation = operation;
+    this.cause = cause;
+  }
+}
+
 export async function runOpenCodeRepoMemory(input, options = {}) {
   const env = options.env ?? process.env;
   const managedServerUrl = stringValue(env.MEMORAX_CODE_OPENCODE_SERVER_URL);
   const serverUrl = stringValue(input?.serverUrl) ?? managedServerUrl;
-  if (!serverUrl) {
-    throw new Error(
-      "OpenCode repo memory runner requires --server-url or MEMORAX_CODE_OPENCODE_SERVER_URL",
-    );
-  }
   const repo = stringValue(input?.repo);
   if (!repo) throw new Error("OpenCode repo memory runner requires --repo");
   const prompt = stringValue(input?.prompt);
   if (!prompt) throw new Error("OpenCode repo memory runner requires --prompt");
 
-  const baseUrl = normalizedServerUrl(serverUrl);
-  const authorization = serverAuthorization(env, baseUrl, managedServerUrl);
   const directory = resolve(repo);
   const parentID = stringValue(input?.parentID)
     ?? stringValue(env.MEMORAX_CODE_MEMORY_CLI_SESSION_ID);
   const fetchImpl = options.fetchImpl ?? fetch;
+  let inheritedError;
+  if (serverUrl) {
+    const baseUrl = normalizedServerUrl(serverUrl);
+    try {
+      return await runOpenCodeRepoMemorySession({
+        authorization: serverAuthorization(env, baseUrl, managedServerUrl),
+        baseUrl,
+        directory,
+        fetchImpl,
+        parentID,
+        prompt,
+      });
+    } catch (error) {
+      if (!isSessionCreationTransportError(error)) throw error;
+      inheritedError = error;
+    }
+  } else {
+    inheritedError = new Error(
+      "OpenCode repo memory runner requires --server-url or MEMORAX_CODE_OPENCODE_SERVER_URL",
+    );
+  }
+
+  const openCodeCommand = stringValue(env.MEMORAX_CODE_OPENCODE_COMMAND);
+  if (!openCodeCommand) throw inheritedError;
+
+  let ownedServer;
+  try {
+    ownedServer = await startOwnedOpenCodeServer({
+      command: openCodeCommand,
+      directory,
+      env,
+      options,
+    });
+  } catch (error) {
+    throw new Error(
+      `${errorMessage(inheritedError)}; managed OpenCode server fallback failed: ${errorMessage(error)}`,
+    );
+  }
+
+  try {
+    return await runOpenCodeRepoMemorySession({
+      authorization: ownedServer.authorization,
+      baseUrl: ownedServer.baseUrl,
+      directory,
+      fetchImpl,
+      parentID,
+      prompt,
+      signal: ownedServer.signal,
+    });
+  } finally {
+    await ownedServer.close();
+  }
+}
+
+async function runOpenCodeRepoMemorySession(input) {
   let sessionID;
   try {
-    const session = await requestJson(fetchImpl, endpoint(baseUrl, "/session", directory), {
+    const session = await requestJson(input.fetchImpl, endpoint(input.baseUrl, "/session", input.directory), {
       method: "POST",
       headers: {
         "content-type": "application/json",
-        ...(authorization ? { authorization } : {}),
+        ...(input.authorization ? { authorization: input.authorization } : {}),
       },
       body: JSON.stringify({
-        ...(parentID ? { parentID } : {}),
+        ...(input.parentID ? { parentID: input.parentID } : {}),
         title: "MemoraX Code Repo Memory",
         permission: [
           { permission: "edit", pattern: "*", action: "allow" },
@@ -43,23 +107,25 @@ export async function runOpenCodeRepoMemory(input, options = {}) {
           { permission: "external_directory", pattern: "*", action: "allow" },
         ],
       }),
+      ...(input.signal ? { signal: input.signal } : {}),
     }, "session creation");
     sessionID = stringValue(session?.id);
     if (!sessionID) throw new Error("OpenCode session creation returned no session id");
 
     const message = await requestJson(
-      fetchImpl,
-      endpoint(baseUrl, `/session/${encodeURIComponent(sessionID)}/message`, directory),
+      input.fetchImpl,
+      endpoint(input.baseUrl, `/session/${encodeURIComponent(sessionID)}/message`, input.directory),
       {
         method: "POST",
         headers: {
           "content-type": "application/json",
-          ...(authorization ? { authorization } : {}),
+          ...(input.authorization ? { authorization: input.authorization } : {}),
         },
         body: JSON.stringify({
           agent: OPENCODE_REPO_MEMORY_AGENT,
-          parts: [{ type: "text", text: prompt }],
+          parts: [{ type: "text", text: input.prompt }],
         }),
+        ...(input.signal ? { signal: input.signal } : {}),
       },
       "blocking prompt",
     );
@@ -69,14 +135,170 @@ export async function runOpenCodeRepoMemory(input, options = {}) {
   } finally {
     if (sessionID) {
       await bestEffortDelete(
-        fetchImpl,
-        endpoint(baseUrl, `/session/${encodeURIComponent(sessionID)}`, directory),
-        authorization,
+        input.fetchImpl,
+        endpoint(input.baseUrl, `/session/${encodeURIComponent(sessionID)}`, input.directory),
+        input.authorization,
       );
     }
   }
 }
 
+async function startOwnedOpenCodeServer(input) {
+  const username = OWNED_SERVER_USERNAME;
+  const password = randomBytes(24).toString("base64url");
+  const spawnImpl = input.options.spawnImpl ?? spawn;
+  const child = spawnImpl(input.command, [
+    "serve",
+    "--hostname=127.0.0.1",
+    "--port=0",
+  ], {
+    cwd: input.directory,
+    env: {
+      ...input.env,
+      OPENCODE_SERVER_USERNAME: username,
+      OPENCODE_SERVER_PASSWORD: password,
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  const lifecycle = ownedServerLifecycle(child);
+  let closePromise;
+  const close = () => {
+    closePromise ??= stopOwnedServer(
+      child,
+      positiveInteger(input.options.serverStopTimeoutMs, DEFAULT_SERVER_STOP_TIMEOUT_MS),
+    ).finally(lifecycle.dispose);
+    return closePromise;
+  };
+  try {
+    const baseUrl = await waitForOwnedServer(
+      child,
+      positiveInteger(input.options.serverStartTimeoutMs, DEFAULT_SERVER_START_TIMEOUT_MS),
+    );
+    return {
+      authorization: basicAuthorization(username, password),
+      baseUrl,
+      close,
+      signal: lifecycle.signal,
+    };
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}
+
+function waitForOwnedServer(child, timeoutMs) {
+  return new Promise((resolveReady, rejectReady) => {
+    let output = "";
+    let settled = false;
+    let timer;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.off("error", onError);
+      child.off("exit", onExit);
+      child.stdout?.off("data", onOutput);
+      child.stderr?.off("data", onOutput);
+      child.stdout?.resume();
+      child.stderr?.resume();
+      if (error) rejectReady(error);
+      else resolveReady(value);
+    };
+    const onOutput = (chunk) => {
+      output = `${output}${String(chunk)}`.slice(-MAX_SERVER_START_OUTPUT);
+      const match = output.match(/opencode server listening on (https?:\/\/[^\s\u001b]+)/i);
+      if (!match) return;
+      let url;
+      try {
+        url = normalizedOwnedServerUrl(match[1]);
+      } catch (error) {
+        finish(error);
+        return;
+      }
+      finish(undefined, url);
+    };
+    const onError = (error) => finish(error);
+    const onExit = (code, signal) => finish(new Error(
+      `OpenCode managed server exited before readiness${code === null ? "" : ` with code ${code}`}`
+      + `${signal ? ` after ${signal}` : ""}${output.trim() ? `: ${output.trim().slice(-500)}` : ""}`,
+    ));
+    timer = setTimeout(() => finish(new Error(
+      `timed out waiting for OpenCode managed server readiness after ${timeoutMs} ms`,
+    )), timeoutMs);
+    child.once("error", onError);
+    child.once("exit", onExit);
+    child.stdout?.on("data", onOutput);
+    child.stderr?.on("data", onOutput);
+  });
+}
+
+function normalizedOwnedServerUrl(value) {
+  const url = normalizedServerUrl(value);
+  if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port) {
+    throw new Error("OpenCode managed server did not bind to the requested loopback address");
+  }
+  return url;
+}
+
+function ownedServerLifecycle(child) {
+  const controller = new AbortController();
+  const handlers = new Map();
+  const onExit = (code, signal) => {
+    if (controller.signal.aborted) return;
+    controller.abort(new Error(
+      `OpenCode managed server exited${code === null ? "" : ` with code ${code}`}`
+      + `${signal ? ` after ${signal}` : ""}`,
+    ));
+  };
+  child.once("exit", onExit);
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    const handler = () => {
+      controller.abort(new Error(`OpenCode managed server interrupted by ${signal}`));
+      if (!childStopped(child)) child.kill(signal);
+    };
+    handlers.set(signal, handler);
+    process.once(signal, handler);
+  }
+  return {
+    signal: controller.signal,
+    dispose() {
+      child.off("exit", onExit);
+      for (const [signal, handler] of handlers) process.off(signal, handler);
+    },
+  };
+}
+
+async function stopOwnedServer(child, timeoutMs) {
+  if (childStopped(child)) return;
+  const exited = new Promise((resolveExit) => child.once("exit", resolveExit));
+  child.kill("SIGTERM");
+  if (await settlesWithin(exited, timeoutMs) || childStopped(child)) return;
+  child.kill("SIGKILL");
+  if (await settlesWithin(exited, timeoutMs) || childStopped(child)) return;
+  child.stdout?.destroy();
+  child.stderr?.destroy();
+  child.unref?.();
+}
+
+async function settlesWithin(promise, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise.then(() => true, () => true),
+      new Promise((resolveTimeout) => {
+        timer = setTimeout(() => resolveTimeout(false), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function childStopped(child) {
+  return child.exitCode !== null || child.signalCode !== null;
+}
+
 function parseArgs(values) {
   const result = {};
   for (let index = 0; index < values.length; index += 1) {
@@ -131,7 +353,7 @@ async function requestJson(fetchImpl, url, init, operation) {
   try {
     response = await fetchImpl(url, init);
   } catch (error) {
-    throw new Error(`OpenCode ${operation} request failed: ${errorMessage(error)}`);
+    throw new OpenCodeTransportError(operation, error);
   }
   const body = await response.text();
   if (!response.ok) {
@@ -148,6 +370,19 @@ async function requestJson(fetchImpl, url, init, operation) {
   }
 }
 
+function isSessionCreationTransportError(error) {
+  return error instanceof OpenCodeTransportError && error.operation === "session creation";
+}
+
+function basicAuthorization(username, password) {
+  return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+}
+
+function positiveInteger(value, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
 async function bestEffortDelete(fetchImpl, url, authorization) {
   try {
     await fetchImpl(url, {

package/lib/node-version.mjs

@@ -1,4 +1,4 @@
-export const MINIMUM_NODE_MAJOR = 24;
+export const MINIMUM_NODE_MAJOR = 20;
 
 export function unsupportedNodeVersionMessage(version = process.versions.node) {
   const value = String(version ?? "").trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorax/memorax-code",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Persistent coding memory for Codex, Claude Code, DeepSeek Harness, and OpenCode.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=20"
   },
   "dependencies": {
     "smol-toml": "^1.7.0"