@memorax/memorax-code 0.1.1 → 0.1.3

package/docs/configuration.md

@@ -38,12 +38,13 @@ are not a compatibility contract.
 
 ## New configuration
 
-The generated template selects both clients, disables automatic retrieval,
-enables automatic writeback, sets the preferred language to Chinese (`zh`),
-uses a five-turn skill reminder and the adaptive repository-update policy, and
-enables content-bearing local traces for both clients. npm installation may
-narrow `[clients]` to clients detected on the host. The tables below list all
-fallbacks, including tuning fields omitted from the generated file.
+The generated template selects all four client integrations, disables automatic
+retrieval, enables automatic writeback, sets the preferred language to Chinese
+(`zh`), uses a five-turn skill reminder and the adaptive repository-update
+policy, and enables content-bearing local traces for Codex, Claude Code, and
+OpenCode. npm installation may narrow `[clients]` to clients detected on the
+host. The tables below list all fallbacks, including tuning fields omitted from
+the generated file.
 
 On POSIX systems MemoraX Code creates `$MEMORAX_CODE_HOME` with mode `0700`
 and a new `config.toml` with mode `0600`. Windows relies on the current user's
@@ -51,17 +52,87 @@ filesystem ACLs.
 
 ## Client selection
 
-If `[clients]` is absent, lifecycle commands select both clients. If it is
-present, `codex` and `claude` are boolean fields and an omitted client is
-disabled. The command-line override is:
+If `[clients]` is absent, lifecycle commands select Codex, Claude Code, DSH,
+and OpenCode. If it is present, `codex`, `claude`, `dsh`, and `opencode` are
+boolean fields. Omitted `codex`, `claude`, or `opencode` values are disabled;
+an omitted `dsh` value remains enabled so configurations written before DSH
+support can discover an existing local Harness. Set `dsh = false` explicitly
+to disable that integration. The command-line override accepts a
+comma-separated subset:
 
 ```text
---clients codex|claude|codex,claude|all|none
+--clients codex|claude|dsh|opencode|<comma-separated subset>|all|none
 ```
 
-Client selection controls plugin and Hook lifecycle only. It does not change
-Codex or Claude Code provider settings. `--clients none` runs the Backend
-without managing either client integration.
+A normal npm install or reinstall refreshes `[clients]` from the available
+clients detected at that time. OpenCode is available when its explicit, XDG,
+or default configuration directory exists, or when `opencode` is on `PATH`.
+DSH is available when at least one valid Profile exists under
+`$DSH_HOME/profiles`; `DSH_HOME` defaults to `~/.dsh`. An explicit
+`[clients].dsh = false` is preserved.
+Update-mode postinstall runs preserve enabled
+clients and also probe each disabled client. An interactive update offers each
+runnable disabled integration for activation with a default of yes. Declining
+the prompt, or running non-interactively, keeps that integration disabled. A
+selected client that is temporarily unavailable also remains selected in the
+configuration instead of being permanently disabled. When an update newly
+enables Codex, it requests initial Hook activation after the client-selection
+prompt.
+
+Client selection controls managed client-integration lifecycle only. It does
+not change Codex, Claude Code, DSH, or OpenCode provider settings.
+`--clients none` runs the Backend without managing a client integration.
+
+## DeepSeek Harness integration paths
+
+DSH Profiles are discovered under:
+
+```text
+$DSH_HOME/profiles/<profile-name>/
+```
+
+`DSH_HOME` defaults to `~/.dsh`. The managed ownership record lives at
+`$MEMORAX_CODE_HOME/adapters/dsh/state.json`. Runtime packages are materialized
+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.
+
+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
+guaranteed. An unavailable or malformed `dsh --version` result fails Profile
+reconciliation when a Profile exists. Run `memorax-code start --clients dsh`
+after changing `DSH_HOME`, DSH, or its Profiles.
+
+## OpenCode integration paths
+
+The managed OpenCode plugin loader and shared skill use OpenCode's automatic
+discovery directories:
+
+```text
+~/.config/opencode/plugins/memorax-code.js
+~/.config/opencode/skills/memorax-code/
+```
+
+Set `OPENCODE_CONFIG_DIR` to override the complete OpenCode configuration root.
+Otherwise, `XDG_CONFIG_HOME` replaces `~/.config` when set. The managed adapter
+record lives at `$MEMORAX_CODE_HOME/adapters/opencode/state.json`. Content-free
+plugin runtime evidence lives beside it in `workspaces.json` and records only
+the observed event, workspace, optional session identifier, and timestamp.
+
+MemoraX Code does not add entries to or otherwise modify `opencode.json` or
+`opencode.jsonc`. Restart or refresh OpenCode after installation or after these
+managed assets change.
+
+The managed loader records the exact MemoraX Code home, OpenCode configuration
+directory, installed Node runtime, and `memorax-code` entrypoint. When the
+enabled plugin loads, it performs a best-effort Backend health check and uses
+those installed package paths to restore an unavailable loopback Backend. A
+prompt waits no more than the plugin instance's single five-second recovery
+budget; if that budget expires, automatic memory handling for that turn is
+skipped while recovery continues in the background. This preserves the
+configured client selection. Remote Backend URLs, invalid connection
+authority, and a removed package command are not recovered automatically.
 
 ## MemoraX connection
 
@@ -110,20 +181,20 @@ Automatic prompt retrieval is disabled by default.
 | `memory_type_order` | `MEMORAX_CODE_MEMORAX_MEMORY_TYPE_ORDER` | `core,episodic,semantic,procedural,unclassified` |
 
 The TOML form of `memory_type_order` is an array of strings; the environment
-form is comma-separated. `enabled` controls automatic `UserPromptSubmit`
-retrieval only. Explicit `memorax-cli search` remains available when
+form is comma-separated. `enabled` controls automatic prompt retrieval only.
+Explicit `memorax-cli search` remains available when
 credentials and a trusted workspace scope resolve.
 
 ## Writeback and explicit add
 
-New configurations explicitly set automatic transcript writeback to enabled.
+New configurations explicitly set automatic completed-turn writeback to enabled.
 An existing configuration without `enabled` remains disabled.
 
 | Field | Environment override | Fallback |
 | --- | --- | --- |
 | `enabled` | `MEMORAX_CODE_MEMORY_WRITEBACK_ENABLED` | `false` when absent |
 | `buffer_enabled` | `MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_ENABLED` | `true` |
-| `buffer_max_turns` | `MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_TURNS` | `8`; `-1` disables automatic Hook writeback |
+| `buffer_max_turns` | `MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_TURNS` | `8`; `-1` disables automatic writeback |
 | `buffer_max_age_ms` | `MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_AGE_MS` | `600000` |
 | `buffer_max_chars` | `MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_CHARS` | `128000` |
 | `max_message_chars` | `MEMORAX_CODE_MEMORY_WRITEBACK_MAX_MESSAGE_CHARS` | `64000` |
@@ -150,12 +221,42 @@ selecting another language. The setting affects newly generated content;
 `raw` input and client-supplied `pre_summarized` text are not translated.
 Command arguments override the other add defaults.
 
+### Automatic writeback redaction
+
+Automatic writeback first bounds each user or assistant message with
+`max_message_chars`, discarding an incomplete token at the cutoff, and then
+runs a local best-effort detector before hashing, buffering, chunking, or
+sending the content. The detector replaces these categories with typed
+placeholders:
+
+| Category | Placeholder |
+| --- | --- |
+| Private keys | `[REDACTED:PRIVATE_KEY]` |
+| Authorization tokens and JWTs | `[REDACTED:AUTH_TOKEN]` |
+| Cookie values | `[REDACTED:COOKIE]` |
+| Common API key formats | `[REDACTED:API_KEY]` |
+| Credential assignments, CLI arguments, URL query values, and URL passwords | `[REDACTED:CREDENTIAL]` |
+| Email addresses | `[REDACTED:EMAIL]` |
+| Long numbers, including common spaces, hyphens, and parentheses | `[REDACTED:LONG_NUMBER]` |
+| UUIDs, fixed-length hexadecimal strings, and high-entropy alphanumeric identifiers | `[REDACTED:OPAQUE_ID]` |
+
+If either bounded message has no meaningful content after replacement, the
+automatic writeback is skipped before network dispatch. The detector is
+always active for automatic writeback, but it is not a complete
+data-loss-prevention system and may miss unknown or weak-context sensitive
+formats. Explicit `memorax-cli add` content and Search queries are sent as
+entered and do not pass through this detector.
+
 ## Skill reminder and repository maintenance
 
 `[memory.skill_reminder].interval_turns` defaults to `5`; its environment
 override is `MEMORAX_CODE_MEMORY_SKILL_REMINDER_INTERVAL_TURNS`. A positive
-value controls the reminder cadence for both clients, beginning with the first
-eligible prompt.
+value controls the native skill reminder cadence for supported client
+sessions, beginning with the first eligible prompt or Turn. The same interval
+controls trusted repo-scoped Procedure Memory. User Profile preferences are
+applied on first observation and restored with a personal-memory reminder
+after successful context compaction. These local contexts remain separate
+from automatic writeback content.
 
 | Field | Environment override | Fallback |
 | --- | --- | --- |
@@ -167,24 +268,45 @@ Supported policies are `every-commit`, `commit-count`, `daily`,
 `pull-request`, `pull-request-or-daily`, and `adaptive`. Invalid policy values
 fall back to `adaptive`.
 
+In Codex, Claude Code, DSH, and OpenCode, the first eligible prompt starts a
+background build only when the Backend has authorized a Git worktree and that
+worktree has no `.repo_memory/PROFILE.md`. If the Backend or workspace
+authority is unavailable, the client integration skips that attempt instead
+of falling back to its local workspace path. DSH schedules this work through
+its native pre-step integration rather than a Hook.
+
+A relevant repo-read runs supervised maintenance in all four clients. The
+configured policy may select a build, update, or no-op. DSH maintenance
+requires an enabled, managed Profile that includes `@deepseek-ai/dsh-headless`.
+OpenCode executes the job through its active local server. Desktop-only
+installations do not require a standalone `opencode` executable in `PATH`.
+
 ## Local traces
 
-`[trace.codex]` and `[trace.claude]` support the same fields:
+`[trace.codex]`, `[trace.claude]`, `[trace.dsh]`, and `[trace.opencode]`
+support the same fields:
 
-| Field | Codex environment | Claude environment | Fallback |
-| --- | --- | --- | --- |
-| `enabled` | `MEMORAX_CODE_CODEX_TRACE_ENABLED` | `MEMORAX_CODE_CLAUDE_TRACE_ENABLED` | `true` |
-| `capture_content` | `MEMORAX_CODE_CODEX_TRACE_CAPTURE_CONTENT` | `MEMORAX_CODE_CLAUDE_TRACE_CAPTURE_CONTENT` | `true` |
-| `retention_days` | `MEMORAX_CODE_CODEX_TRACE_RETENTION_DAYS` | `MEMORAX_CODE_CLAUDE_TRACE_RETENTION_DAYS` | `7` |
-| `max_event_chars` | `MEMORAX_CODE_CODEX_TRACE_MAX_EVENT_CHARS` | `MEMORAX_CODE_CLAUDE_TRACE_MAX_EVENT_CHARS` | `20000` |
-| `max_file_bytes` | `MEMORAX_CODE_CODEX_TRACE_MAX_FILE_BYTES` | `MEMORAX_CODE_CLAUDE_TRACE_MAX_FILE_BYTES` | `52428800` |
+| Field | Codex environment | Claude environment | DSH environment | OpenCode environment | Fallback |
+| --- | --- | --- | --- | --- | --- |
+| `enabled` | `MEMORAX_CODE_CODEX_TRACE_ENABLED` | `MEMORAX_CODE_CLAUDE_TRACE_ENABLED` | `MEMORAX_CODE_DSH_TRACE_ENABLED` | `MEMORAX_CODE_OPENCODE_TRACE_ENABLED` | `true` |
+| `capture_content` | `MEMORAX_CODE_CODEX_TRACE_CAPTURE_CONTENT` | `MEMORAX_CODE_CLAUDE_TRACE_CAPTURE_CONTENT` | `MEMORAX_CODE_DSH_TRACE_CAPTURE_CONTENT` | `MEMORAX_CODE_OPENCODE_TRACE_CAPTURE_CONTENT` | `true` |
+| `retention_days` | `MEMORAX_CODE_CODEX_TRACE_RETENTION_DAYS` | `MEMORAX_CODE_CLAUDE_TRACE_RETENTION_DAYS` | `MEMORAX_CODE_DSH_TRACE_RETENTION_DAYS` | `MEMORAX_CODE_OPENCODE_TRACE_RETENTION_DAYS` | `7` |
+| `max_event_chars` | `MEMORAX_CODE_CODEX_TRACE_MAX_EVENT_CHARS` | `MEMORAX_CODE_CLAUDE_TRACE_MAX_EVENT_CHARS` | `MEMORAX_CODE_DSH_TRACE_MAX_EVENT_CHARS` | `MEMORAX_CODE_OPENCODE_TRACE_MAX_EVENT_CHARS` | `20000` |
+| `max_file_bytes` | `MEMORAX_CODE_CODEX_TRACE_MAX_FILE_BYTES` | `MEMORAX_CODE_CLAUDE_TRACE_MAX_FILE_BYTES` | `MEMORAX_CODE_DSH_TRACE_MAX_FILE_BYTES` | `MEMORAX_CODE_OPENCODE_TRACE_MAX_FILE_BYTES` | `52428800` |
 
-Content capture can include prompts, responses, recalled memory, writeback
-content, reminder text, and local paths. Set `capture_content=false` for
+Depending on the enabled client capabilities, content capture can include
+prompts, responses, recalled memory, writeback content, reminder text, and
+local paths. Set `capture_content=false` for
 metadata-only local traces, or `enabled=false` to disable a client's trace.
 Trace files stay under `$MEMORAX_CODE_HOME`; MemoraX Code has no trace upload,
 export, or public collector.
 
+DSH trace contains only normalized lifecycle and memory-operation events. Its
+native Session Event Log and raw events remain local to DSH; MemoraX Code does
+not copy that log into trace. Memory Viewer includes DSH activity from
+normalized operational events and retained trace, and never reads the native
+Session Event Log.
+
 ## Backend runtime settings
 
 Backend connection and process authority is not stored in `config.toml`.
@@ -227,6 +349,8 @@ memorax-cli status
 memorax-cli status --json
 memorax-code-codex doctor
 memorax-code-claude doctor
+memorax-code status --clients dsh
+memorax-code-opencode doctor
 ```
 
 The status commands do not print the MemoraX API key or Backend token.

package/docs/troubleshooting.md

@@ -7,12 +7,16 @@ memorax-code status
 memorax-cli status
 memorax-code-codex doctor
 memorax-code-claude doctor
+memorax-code status --clients dsh
+memorax-code-opencode doctor
 memorax-code logs
 ```
 
-`status` checks the Backend and client integrations. `memory status` checks
-credentials, scope, and memory switches without printing secrets. Each client
-`doctor` checks its plugin, skill, workspace, and Backend connection.
+`memorax-code status` checks the Backend and selected client integrations,
+including DSH and OpenCode. `memorax-cli status` checks credentials, scope, and
+memory switches without printing secrets. Codex, Claude Code, and OpenCode
+also provide client-specific `doctor` commands; DSH uses the shared lifecycle
+status.
 
 ## Installed, but memory is unavailable
 
@@ -103,6 +107,55 @@ This reconciles the Claude Code marketplace plugin and Hooks. If the plugin is
 still missing or stale, restart or refresh Claude Code. Do not manually copy
 Hooks into Claude settings.
 
+## DeepSeek Harness Profile integration is inactive
+
+```sh
+dsh --version
+pnpm --version
+memorax-code start --clients dsh
+memorax-code status --clients dsh
+```
+
+MemoraX Code discovers existing Profiles under `$DSH_HOME/profiles`;
+`DSH_HOME` defaults to `~/.dsh`. A `no_existing_profiles` result means DSH has
+not created a valid Profile in that home. A `dsh_version_unavailable` result
+means the selected `dsh` command did not return a valid semantic version. The
+tested baseline is `0.1.0-rc.6`; another valid version is allowed but marked
+untested. A `pnpm_not_found` result means DSH's native Profile plugin manager
+could not find `pnpm` on `PATH`; install `pnpm`, then rerun the start command.
+
+After repairing the command, Profile manifest, or home selection, rerun the
+start command and restart or refresh DSH. `profile_drift`,
+`profile_manifest_unreadable`, and `runtime_authority_invalid` are managed-state
+failures rather than reasons to edit the Profile or
+`$MEMORAX_CODE_HOME/adapters/dsh/state.json` manually. The lifecycle command
+uses DSH's plugin manager to reconcile the integration. Stop and uninstall
+remove the managed MemoraX Code plugin, not the DSH Profile or its session
+data.
+
+## OpenCode plugin or skill is inactive
+
+```sh
+memorax-code start --clients opencode
+memorax-code status --clients opencode
+memorax-code-opencode doctor
+```
+
+Rerun the start command to reconcile the managed plugin and skill, then restart
+or refresh OpenCode. The configuration root follows `OPENCODE_CONFIG_DIR`, then
+`XDG_CONFIG_HOME`, and otherwise defaults to `~/.config/opencode`. MemoraX Code
+does not add plugin entries to `opencode.json` or `opencode.jsonc`.
+
+An enabled managed plugin normally attempts to restore an unavailable local
+loopback Backend when OpenCode loads it. A prompt stops waiting after the
+plugin instance's single five-second recovery budget and skips automatic
+memory handling for that turn, but the Backend start continues in the
+background. If that recovery is skipped or fails, use `memorax-code status` and
+`memorax-code logs`, then run the start command above. If doctor reports no
+plugin runtime evidence, restart or refresh OpenCode and rerun it. Automatic
+recovery intentionally skips remote URLs, invalid connection authority, and
+stale loaders whose recorded package command no longer exists.
+
 An already-open client may keep its loaded plugin shell while a later prompt
 uses the updated Hook runtime. Restart or refresh the client to load a changed
 plugin manifest, icon, or bundled skill.
@@ -116,6 +169,8 @@ environment may be intercepting `127.0.0.1` or `localhost`.
 memorax-code start
 memorax-code-codex doctor
 memorax-code-claude doctor
+memorax-code status --clients dsh
+memorax-code-opencode doctor
 /usr/sbin/scutil --proxy
 /bin/launchctl getenv NO_PROXY
 /bin/launchctl getenv no_proxy
@@ -132,6 +187,8 @@ memorax-cli status
 memorax-cli search --query 'test'
 memorax-code-codex doctor
 memorax-code-claude doctor
+memorax-code status --clients dsh
+memorax-code-opencode doctor
 ```
 
 Common causes are:
@@ -147,16 +204,43 @@ MemoraX Code reads filesystem Git metadata without executing Git. Linked
 worktrees share the remote repository identity; non-Git workspaces use the
 normalized folder name. Resolution never falls back to the bare base user ID.
 
+A live Codex, Claude Code, DSH, or OpenCode session remains pinned to the
+repository or local workspace resolved at the start of the session. Starting
+the client from a parent workspace and then entering a nested Git repository
+does not rebind the session. The only in-session scope upgrade is from a direct
+`.git` directory whose internal metadata was malformed or incomplete to a
+verified Git repository at the same canonical workspace root and for the same
+Base User ID.
+
+During that degraded state, MemoraX Code reports
+`workspaceScopeFallbackReason: git_metadata_invalid` for manual CLI operations
+and continues Search and Add with the normalized local folder name. Automatic
+writeback also continues under that fallback scope without interrupting the
+client task. The reported `effectiveUserId` identifies the fallback namespace
+and may differ from the restored Git repository namespace. Repair the
+repository or restore valid `.git` metadata, and later Search, Add, and
+automatic writeback in the same client session automatically use the verified
+Git repository scope. Memories already accepted under the fallback namespace
+are not migrated. Any unsent automatic-writeback buffer for the fallback scope
+is discarded instead of being flushed into either namespace.
+
+Invalid or unreadable Git marker files, symlinked markers, and session scope
+conflicts do not use this fallback. If Search or Add reports
+`workspace_scope_mismatch` or `workspace_scope_unavailable`, start a new
+session from the target repository or local workspace and verify that its
+`.git` metadata is readable and valid. These failures stop Search or Add before
+any request is sent to MemoraX.
+
 Codex projectless tasks under its canonical dated-task location intentionally
 use the shared `Codex-General` memory name. Open a task in a real workspace
 when repository isolation matters.
 
 ## Model-provider requests fail while MemoraX Code is healthy
 
-MemoraX Code does not proxy Codex or Claude Code model requests. If
-`memorax-code status` and the relevant client doctor are healthy, inspect the
-provider URL, credentials, model selection, and network settings owned by that
-client. Do not copy model-provider credentials into
+MemoraX Code does not proxy Codex, Claude Code, DSH, or OpenCode model
+requests. If `memorax-code status` and the available client-specific doctor
+are healthy, inspect the provider URL, credentials, model selection, and
+network settings owned by that client. Do not copy model-provider credentials into
 `$MEMORAX_CODE_HOME`.
 
 ## Safe issue reports
@@ -168,6 +252,8 @@ memorax-code status --json
 memorax-cli status --json
 memorax-code-codex doctor --json
 memorax-code-claude doctor --json
+memorax-code status --clients dsh --json
+memorax-code-opencode doctor --json
 ```
 
 Include the MemoraX Code version, operating system, affected client,

package/lib/dsh-plugin-install.mjs

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageLib = dirname(fileURLToPath(import.meta.url));
+const stagedLifecycle = join(
+  packageLib,
+  "memorax-code-dsh-adapter",
+  "src",
+  "profile-lifecycle.mjs",
+);
+const sourceLifecycle = resolve(
+  packageLib,
+  "../../../ts/memorax-code-dsh-adapter/src/profile-lifecycle.mjs",
+);
+const lifecycle = await import(
+  pathToFileURL(existsSync(stagedLifecycle) ? stagedLifecycle : sourceLifecycle).href
+);
+
+export const collectDshAdapterStatus = lifecycle.collectDshAdapterStatus;
+export const discoverDshProfiles = lifecycle.discoverDshProfiles;
+export const withDshPluginLifecycleLock = lifecycle.withDshPluginLifecycleLock;

package/lib/memorax-code-adapter-common/src/hooks/capture-cwd-hook.mjs

@@ -10,6 +10,18 @@ import {
 
 export async function runCaptureCwdHook(options) {
   const input = await readStdinJson();
+  const record = recordWorkspaceEvidence(options, input);
+  if (!record) return;
+
+  if (record.cwd) {
+    const pluginDataPath = pluginDataWorkspacePath();
+    if (pluginDataPath) writeWorkspaceState(pluginDataPath, record, options);
+  }
+  writeSessionRegistry(memoraxCodeSessionRegistryPath(options), record, options);
+  return input;
+}
+
+export function recordWorkspaceEvidence(options, input) {
   const transcriptPath = stringOption(input.transcript_path) ?? stringOption(input.transcriptPath);
   if (options.requireTranscriptPathForTurnEvents && isTurnScopedEvent(input) && !transcriptPath) return;
   const cwd = typeof input.cwd === "string" && input.cwd.trim()
@@ -24,19 +36,12 @@ export async function runCaptureCwdHook(options) {
     capturedAt: new Date().toISOString(),
   };
 
-  const registryPath = memoraxCodeSessionRegistryPath(options);
-
   if (cwd) {
-    const targets = [
-      memoraxCodeWorkspacePath(options),
-      pluginDataWorkspacePath(),
-    ].filter(Boolean);
-
-    for (const target of targets) writeWorkspaceState(target, record, options);
+    const workspacePath = memoraxCodeWorkspacePath(options);
+    if (workspacePath) writeWorkspaceState(workspacePath, record, options);
   }
 
-  writeSessionRegistry(registryPath, record, options);
-  return input;
+  return record;
 }
 
 function isTurnScopedEvent(input) {
@@ -45,17 +50,19 @@ function isTurnScopedEvent(input) {
 }
 
 function memoraxCodeWorkspacePath(options) {
-  const home = memoraxCodeHome();
+  const home = memoraxCodeHome(options);
   return home ? join(home, "adapters", options.adapterDir, "workspaces.json") : undefined;
 }
 
 function memoraxCodeSessionRegistryPath(options) {
-  const home = memoraxCodeHome();
+  const home = memoraxCodeHome(options);
   return home ? join(home, "adapters", options.adapterDir, "session-registry.json") : undefined;
 }
 
-function memoraxCodeHome() {
-  return process.env.MEMORAX_CODE_HOME || (process.env.HOME ? join(process.env.HOME, ".memorax-code") : undefined);
+function memoraxCodeHome(options) {
+  return stringOption(options.memoraxCodeHome)
+    ?? stringOption(process.env.MEMORAX_CODE_HOME)
+    ?? (process.env.HOME ? join(process.env.HOME, ".memorax-code") : undefined);
 }
 
 function pluginDataWorkspacePath() {

package/lib/memorax-code-adapter-common/src/hooks/ensure-backend-runner.mjs

@@ -5,19 +5,23 @@ import {
   localBackendRecoveryArguments,
   resolveBackendConnection,
 } from "../backend-connection.mjs";
-import { readStdinJson } from "../config-utils.mjs";
 import { isRepoMemoryJobWorker } from "../repo-memory/repo-memory-job-context.mjs";
 
 export const DEFAULT_ENSURE_BACKEND_START_TIMEOUT_MS = 90000;
+const HOOK_INPUT_SYMBOL = Symbol.for("memorax-code.client-hook.input.v1");
 
 export async function runEnsureBackendHook(options) {
-  if (isRepoMemoryJobWorker() || ensureDisabled(options.ensureBackendValue)) return;
-
   const input = await readStdinJson();
+  await ensureBackendAvailable(options, input);
+}
+
+export async function ensureBackendAvailable(options, input = {}) {
+  if (isRepoMemoryJobWorker() || ensureDisabled(options.ensureBackendValue)) return;
   const homes = options.resolveHomes(input);
   let connection;
   try {
-    connection = resolveBackendConnection({ memoraxCodeHome: homes.memoraxCodeHome });
+    connection = options.backendConnection
+      ?? resolveBackendConnection({ memoraxCodeHome: homes.memoraxCodeHome });
   } catch (error) {
     options.debug?.(error instanceof Error ? error.message : String(error));
     return;
@@ -36,6 +40,8 @@ export async function runEnsureBackendHook(options) {
     command.value,
     options.buildStartArgs(homes, recoveryArguments),
     parsePositiveInt(options.startTimeoutValue, DEFAULT_ENSURE_BACKEND_START_TIMEOUT_MS),
+    options.nodePath,
+    options.recoveryEnv,
   );
   if (result.code !== 0) {
     options.debug?.(
@@ -105,14 +111,14 @@ function memoraxCodeCommandAvailable(command) {
   return path.split(delimiter).some((dir) => dir && existsSync(join(dir, command)));
 }
 
-function runMemoraxCode(command, args, timeoutMs) {
+function runMemoraxCode(command, args, timeoutMs, nodePath, recoveryEnv) {
   return new Promise((resolve) => {
     const childArgs = nodeEntrypoint(command) ? [command, ...args] : args;
-    const childCommand = nodeEntrypoint(command) ? process.execPath : command;
+    const childCommand = nodeEntrypoint(command) ? (stringValue(nodePath) ?? process.execPath) : command;
     let stderr = "";
     let settled = false;
     const child = spawn(childCommand, childArgs, {
-      env: process.env,
+      env: recoveryEnv === undefined ? process.env : { ...process.env, ...recoveryEnv },
       stdio: ["ignore", "ignore", "pipe"],
     });
     const finish = (result) => {
@@ -140,3 +146,16 @@ function parsePositiveInt(value, fallback) {
   const parsed = Number(value);
   return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
 }
+
+async function readStdinJson() {
+  const injected = globalThis[HOOK_INPUT_SYMBOL];
+  if (injected && typeof injected === "object" && !Array.isArray(injected)) return injected;
+  let text = "";
+  for await (const chunk of process.stdin) text += chunk;
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}