@memorax/memorax-code 0.1.4 → 0.1.6

package/bin/memorax-code.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { stagePackagedClientHookRuntime } from "../lib/client-hook-runtime.mjs";
 import { unsupportedNodeVersionMessage } from "../lib/node-version.mjs";
 import { resolveNpmInvocation } from "../lib/npm-invocation.mjs";
@@ -37,6 +37,51 @@ Options:
   -h, --help  Show this help message`);
 }
 
+function printMainHelp() {
+  console.log(`Usage: memorax-code [command] [options]
+
+Commands:
+  setup       Run or repair the interactive setup
+  account     Manage local MemoraX account information
+  start       Reconcile selected integrations and start the Backend
+  status      Show Backend and integration status
+  stop        Stop the Backend and selected integrations
+  restart     Restart the Backend and selected integrations
+  update      Update the globally installed npm package
+  uninstall   Remove managed integrations and the npm package
+  logs        Show Backend logs
+  token       Manage the local Backend token
+
+Run \`memorax-code setup\` to complete first-time setup or repair an installation.
+Run \`memorax-code\` with no command to show setup guidance or current status.
+Run \`memorax-code <command> --help\` for command-specific options.`);
+}
+
+function printAccountHelp() {
+  console.log(`Usage: memorax-code account --show-mark-id [--home DIR]
+
+Show the Mark ID for the ready local trial identity. Run this command directly
+in your local terminal and keep its output private.
+
+Options:
+  --show-mark-id  Show the complete local trial Mark ID
+  --home DIR      Read the specified MemoraX Code home
+  -h, --help      Show this help message`);
+}
+
+function printSetupHelp() {
+  console.log(`Usage: memorax-code setup [--existing-account | --reconfigure] [--home DIR]
+
+Run interactive setup to configure or repair MemoraX Code. A complete existing
+configuration is reused automatically.
+
+Options:
+  --existing-account  Configure an existing account instead of anonymous access
+  --reconfigure       Re-detect memory preferences instead of reusing configuration
+  --home DIR           Configure the specified MemoraX Code home
+  -h, --help           Show this help message`);
+}
+
 function printCommand(command, args) {
   console.log([command, ...args].join(" "));
 }
@@ -48,6 +93,39 @@ function npmCommandCwd() {
   return "/";
 }
 
+async function runAccountCommand(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    printAccountHelp();
+    return 0;
+  }
+  let memoraxCodeHome;
+  try {
+    memoraxCodeHome = requestedMemoraxCodeHome(args);
+    assertAccountArgs(args);
+  } catch (error) {
+    console.error(`memorax-code account: ${error instanceof Error ? error.message : String(error)}`);
+    printAccountHelp();
+    return 2;
+  }
+
+  try {
+    const { loadReadyTrialSetupCredential } = await loadTrialSetupApi();
+    const credential = await loadReadyTrialSetupCredential({
+      memoraxCodeHome,
+      env: process.env,
+    });
+    if (!credential) {
+      console.error("memorax-code account: no ready local trial identity was found");
+      return 1;
+    }
+    console.log(`Mark ID: ${credential.markId}`);
+    return 0;
+  } catch {
+    console.error("memorax-code account: unable to read the secure local trial identity");
+    return 1;
+  }
+}
+
 async function runUpdateCommand(args) {
   let dryRun = false;
   let force = false;
@@ -98,7 +176,6 @@ async function runUpdateCommand(args) {
   const channel = requestedChannel ?? (pkg.version.includes("-") ? "preview" : "latest");
   const npmArgs = ["install", "-g", `${pkg.name}@${channel}`];
   if (force) npmArgs.push("--force");
-  npmArgs.push("--foreground-scripts");
 
   if (dryRun) {
     printCommand("npm", npmArgs);
@@ -120,11 +197,10 @@ async function runUpdateCommand(args) {
     env: {
       ...process.env,
       PWD: cwd,
-      MEMORAX_CODE_NPM_POSTINSTALL_UPDATE: "1",
       ...(requestedHome ? { MEMORAX_CODE_HOME: requestedHome } : {}),
     },
   });
-  return await new Promise((resolve) => {
+  const npmExitCode = await new Promise((resolve) => {
     child.on("error", (error) => {
       console.error(`memorax-code update: failed to start npm: ${error.message}`);
       resolve(1);
@@ -138,6 +214,196 @@ async function runUpdateCommand(args) {
       }
     });
   });
+  if (npmExitCode !== 0) return npmExitCode;
+
+  const memoraxCodeHome = requestedHome ?? requestedMemoraxCodeHome([]);
+  if (!existsSync(join(memoraxCodeHome, "runtime", "backend", "backend.pid.json"))) {
+    console.error("memorax-code update: package updated; the managed Backend remains stopped; run `memorax-code setup` from a terminal to review client and Hook changes");
+    return 0;
+  }
+  if (!setupCanPrompt()) {
+    console.error("memorax-code update: package updated; run `memorax-code setup` from a terminal to review client and Hook changes");
+    return 0;
+  }
+  return await runSetupCommand(["--home", memoraxCodeHome], { updateMode: true });
+}
+
+async function runSetupCommand(args, { updateMode = false } = {}) {
+  if (args.includes("--help") || args.includes("-h")) {
+    printSetupHelp();
+    return 0;
+  }
+  let memoraxCodeHome;
+  let setupMode;
+  try {
+    memoraxCodeHome = requestedMemoraxCodeHome(args);
+    setupMode = parseSetupMode(args);
+  } catch (error) {
+    console.error(`memorax-code setup: ${error instanceof Error ? error.message : String(error)}`);
+    printSetupHelp();
+    return 2;
+  }
+  if (!setupCanPrompt()) {
+    console.error("memorax-code setup: an interactive terminal is required");
+    return 1;
+  }
+  try {
+    const { withSetupCompletionLock } = await loadSetupCompletionApi();
+    return await withSetupCompletionLock(memoraxCodeHome, async (completion) => {
+      if (updateMode && completion.status === "absent") {
+        if (hasReadyMemoraxConfiguration(memoraxCodeHome)) {
+          console.error("memorax-code update: existing configuration detected; completing the one-time setup migration");
+          return await spawnSetupProcess(memoraxCodeHome, { setupMode });
+        }
+        console.error("memorax-code update: package updated; setup has not been completed; run `memorax-code setup` from an interactive terminal");
+        return 0;
+      }
+      if (updateMode) {
+        console.error("memorax-code update: reviewing client and Hook changes in the foreground");
+      }
+      return await spawnSetupProcess(memoraxCodeHome, {
+        updateMode,
+        setupMode,
+      });
+    });
+  } catch (error) {
+    console.error(`memorax-code setup: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+
+async function routeDefaultCommand() {
+  const memoraxCodeHome = requestedMemoraxCodeHome([]);
+  try {
+    const { readSetupCompletionRecord, setupCompletionPath } = await loadSetupCompletionApi();
+    const state = readSetupCompletionRecord(memoraxCodeHome);
+    if (state.status === "absent") {
+      if (setupCanPrompt() && hasReadyMemoraxConfiguration(memoraxCodeHome)) {
+        console.error("memorax-code: existing configuration detected; completing the one-time setup migration");
+        return await runSetupCommand(["--home", memoraxCodeHome]);
+      }
+      console.error("memorax-code: setup has not been completed. Run `memorax-code setup` from an interactive terminal.");
+      return 1;
+    }
+    if (state.status !== "valid") {
+      const detail = state.status === "unsupported"
+        ? `uses unsupported version ${state.version}`
+        : `is invalid (${state.reason})`;
+      console.error(`memorax-code: setup completion record ${detail}: ${setupCompletionPath(memoraxCodeHome)}`);
+      console.error("Inspect or repair this private record before running setup again.");
+      return 1;
+    }
+    process.argv.splice(2, 0, "status");
+    return undefined;
+  } catch (error) {
+    console.error(`memorax-code: unable to inspect setup state: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+
+function assertAccountArgs(args) {
+  let showMarkId = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--show-mark-id") {
+      showMarkId = true;
+    } else if (arg === "--home") {
+      const value = args[++index];
+      if (!value || value.startsWith("--")) throw new Error("--home requires a directory");
+    } else if (arg.startsWith("--home=")) {
+      if (!arg.slice("--home=".length).trim()) throw new Error("--home requires a directory");
+    } else {
+      throw new Error(`unknown option ${arg}`);
+    }
+  }
+  if (!showMarkId) throw new Error("--show-mark-id is required");
+}
+
+function parseSetupMode(args) {
+  let setupMode = "automatic";
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--existing-account" || arg === "--reconfigure") {
+      const requestedMode = arg === "--existing-account" ? "existing-account" : "reconfigure";
+      if (setupMode !== "automatic" && setupMode !== requestedMode) {
+        throw new Error("--existing-account and --reconfigure cannot be used together");
+      }
+      setupMode = requestedMode;
+    } else if (arg === "--home") {
+      const value = args[++index];
+      if (!value || value.startsWith("--")) throw new Error("--home requires a directory");
+    } else if (arg.startsWith("--home=")) {
+      if (!arg.slice("--home=".length).trim()) throw new Error("--home requires a directory");
+    } else {
+      throw new Error(`unknown option ${arg}`);
+    }
+  }
+  return setupMode;
+}
+
+function setupCanPrompt() {
+  return truthyEnv(process.env.MEMORAX_CODE_SETUP_ASSUME_INTERACTIVE)
+    || (process.stdin.isTTY === true && process.stderr.isTTY === true);
+}
+
+async function loadSetupCompletionApi() {
+  const modulePath = join(
+    packageRoot(),
+    "lib",
+    "memorax-code-adapter-common",
+    "src",
+    "setup-completion.mjs",
+  );
+  return await import(pathToFileURL(modulePath).href);
+}
+
+async function loadTrialSetupApi() {
+  return await import(pathToFileURL(join(packageRoot(), "lib", "trial-setup.mjs")).href);
+}
+
+function hasReadyMemoraxConfiguration(memoraxCodeHome) {
+  const result = spawnSync(process.execPath, [
+    join(packageRoot(), "bin", "memorax-cli.mjs"),
+    "status",
+    "--json",
+    "--config-only",
+  ], {
+    encoding: "utf8",
+    env: { ...process.env, MEMORAX_CODE_HOME: memoraxCodeHome },
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 10_000,
+    windowsHide: true,
+  });
+  return !result.error && !result.signal && result.status === 0;
+}
+
+async function spawnSetupProcess(memoraxCodeHome, { updateMode = false, setupMode = "automatic" } = {}) {
+  const env = {
+    ...process.env,
+    MEMORAX_CODE_HOME: memoraxCodeHome,
+  };
+  delete env.MEMORAX_CODE_SETUP_UPDATE;
+  delete env.MEMORAX_CODE_SETUP_MODE;
+  if (updateMode) env.MEMORAX_CODE_SETUP_UPDATE = "1";
+  if (setupMode !== "automatic") env.MEMORAX_CODE_SETUP_MODE = setupMode;
+  const child = spawn(process.execPath, [join(packageRoot(), "bin", "memorax-code-setup.mjs")], {
+    stdio: "inherit",
+    env,
+  });
+  return await new Promise((resolve) => {
+    child.on("error", (error) => {
+      console.error(`memorax-code setup: failed to start setup: ${error.message}`);
+      resolve(1);
+    });
+    child.on("close", (code, signal) => {
+      if (signal) {
+        console.error(`memorax-code setup: setup exited from signal ${signal}`);
+        resolve(1);
+      } else {
+        resolve(code ?? 1);
+      }
+    });
+  });
 }
 
 if (process.argv[2] === "update") {
@@ -150,6 +416,24 @@ if (process.argv[2] === "--version" || process.argv[2] === "-v") {
   process.exit(0);
 }
 
+if (process.argv.length === 3 && (process.argv[2] === "--help" || process.argv[2] === "-h")) {
+  printMainHelp();
+  process.exit(0);
+}
+
+if (process.argv[2] === "setup") {
+  process.exit(await runSetupCommand(process.argv.slice(3)));
+}
+
+if (process.argv[2] === "account") {
+  process.exit(await runAccountCommand(process.argv.slice(3)));
+}
+
+if (process.argv.length === 2) {
+  const exitCode = await routeDefaultCommand();
+  if (exitCode !== undefined) process.exit(exitCode);
+}
+
 if (shouldStageClientHookRuntime(process.argv.slice(2))
   && !truthyEnv(process.env.MEMORAX_CODE_DEFER_CLIENT_HOOK_RUNTIME_ACTIVATION)) {
   try {

package/docs/configuration.md

@@ -19,7 +19,8 @@ explicit command/context value > environment variable > config.toml > code fallb
 ```
 
 Use `config.toml` for durable choices and environment variables for temporary
-overrides or credentials that should not be written to disk. After editing the
+overrides. Both account-free and existing-account setup write the effective API
+key to this private file so the connection can be reused. After editing the
 file, run:
 
 ```sh
@@ -42,7 +43,7 @@ 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
+OpenCode. Foreground setup may narrow `[clients]` to clients detected on the
 host. The tables below list all fallbacks, including tuning fields omitted from
 the generated file.
 
@@ -64,25 +65,65 @@ comma-separated subset:
 --clients codex|claude|dsh|opencode|<comma-separated subset>|all|none
 ```
 
-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`.
+Foreground `memorax-code setup` refreshes `[clients]` from the clients
+available 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.
+
+On later setup runs, enabled client intent is preserved. Each newly available
+disabled client is offered for activation with a default of yes; declining
+keeps it disabled. A selected client that is temporarily unavailable remains
+selected instead of being permanently disabled. Direct npm installation does
+not detect clients or modify `[clients]`.
 
 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.
 
+## Setup and package-transition state
+
+npm installation and foreground setup are separate operations.
+`npm install -g @memorax/memorax-code` installs or replaces package files
+without reading terminal input. `memorax-code setup` owns client detection,
+connection setup, configuration writes, Codex Hook activation or review, and
+final readiness checks.
+
+Default setup reuses a complete effective connection. Otherwise it detects the
+logged-in operating-system username and maps the system language to `zh` or
+`en`, asking only when a value cannot be detected safely. It then creates or
+restores an account-free credential and writes its API key to `config.toml`.
+`memorax-code setup --existing-account` bypasses automatic reuse and accepts
+an existing connection's username and API key. `--reconfigure` bypasses reuse
+and follows the account-free path again.
+
+Successful setup writes a private versioned record at:
+
+```text
+$MEMORAX_CODE_HOME/runtime/setup/setup-completion.json
+```
+
+The record controls only no-argument CLI routing. When it is valid, the command
+shows status. When it is absent and an interactive terminal is available,
+`memorax-code` validates and reuses a complete effective configuration, then
+runs setup and reconciliation once to write the record. If the configuration
+is incomplete or no interactive terminal is available, it points to
+`memorax-code setup`. Invalid and unsupported records fail closed. A complete
+product uninstall removes this marker while retaining `config.toml`; stop and
+partial client uninstall preserve it.
+
+Replacing a running managed Backend uses a separate private record:
+
+```text
+$MEMORAX_CODE_HOME/runtime/install/package-transition.json
+```
+
+Preinstall records and retires the running installation. Postinstall restores
+and verifies it before consuming the record. A fresh or already-stopped
+installation has no transition and remains stopped. Do not edit either runtime
+record by hand.
+
 ## DeepSeek Harness integration paths
 
 DSH Profiles are discovered under:
@@ -145,7 +186,7 @@ MemoraX is the required remote-memory service:
 ```toml
 [memorax]
 endpoint = "https://platform.memorax.net"
-user_id = "your-base-user-id"
+user_id = "your-username"
 api_key = "your-api-key"
 # timeout_ms = 5000
 # startup_timeout_ms = 3000
@@ -154,8 +195,8 @@ api_key = "your-api-key"
 | Field | Environment override | Fallback |
 | --- | --- | --- |
 | `endpoint` | `MEMORAX_CODE_MEMORAX_ENDPOINT` | `https://platform.memorax.net` |
-| `user_id` | `MEMORAX_CODE_MEMORAX_USER_ID` | required |
-| `api_key` | `MEMORAX_CODE_MEMORAX_API_KEY` | required |
+| `user_id` | `MEMORAX_CODE_MEMORAX_USER_ID` | required username |
+| `api_key` | `MEMORAX_CODE_MEMORAX_API_KEY` | required; setup writes it |
 | `timeout_ms` | `MEMORAX_CODE_MEMORAX_TIMEOUT_MS` | `5000` ms |
 | `startup_timeout_ms` | `MEMORAX_CODE_MEMORAX_STARTUP_TIMEOUT_MS` | `3000` ms |
 
@@ -163,8 +204,14 @@ MemoraX requests send the API key and the query or content required by the
 selected memory operation to the HTTPS endpoint. Override `endpoint` only with
 a compatible MemoraX service you trust.
 
+Quota reminders keep only a one-way connection fingerprint and the last
+notified level for memory write and memory search under the private runtime
+directory. They do not store a raw API key, Mark ID, or account-registration
+state. The returned quota limit is used only to decide whether to include
+conditional anonymous-account guidance.
+
 `startup_timeout_ms` controls synchronous automatic retrieval and is capped at
-10 seconds. `user_id` is a base identity; MemoraX Code derives a
+10 seconds. `user_id` is the configured username; MemoraX Code derives a
 repository-scoped identity for Git workspaces and a folder-scoped identity for
 non-Git workspaces. It never falls back to the unscoped base identity.
 
@@ -341,6 +388,8 @@ token. Persistent connection, token, and PID records live under
   read or parsed; memory readers may also warn. Unsupported field types are
   ignored.
 - Targeted configuration updates preserve unrelated and unknown TOML content.
+- Setup writes completion only after Backend, client, and effective MemoraX
+  readiness checks succeed.
 - Invalid or unsupported Backend runtime records fail closed instead of
   silently falling back to `127.0.0.1:8787`.
 

package/docs/troubleshooting.md

@@ -18,17 +18,83 @@ memory switches without printing secrets. Codex, Claude Code, and OpenCode
 also provide client-specific `doctor` commands; DSH uses the shared lifecycle
 status.
 
+## Package installed, but setup did not start
+
+This is expected after:
+
+```sh
+npm install -g @memorax/memorax-code
+```
+
+npm installation is deliberately non-interactive. Start setup from a normal
+terminal:
+
+```sh
+memorax-code setup
+```
+
+If a complete configuration was retained from an earlier installation,
+default setup reuses it automatically. Use `memorax-code setup --reconfigure`
+to replace it, or `memorax-code setup --existing-account` to enter an
+existing MemoraX connection.
+
+Setup requires terminal input and terminal-visible stderr. A pipe, background
+process, or redirected stdin/stderr cannot complete setup; rerun it in a normal
+interactive terminal.
+
+## Setup does not complete
+
+Setup writes
+`$MEMORAX_CODE_HOME/runtime/setup/setup-completion.json` only after
+configuration, client and Hook reconciliation, Backend start, and final
+readiness checks succeed. Until then, running `memorax-code` with no command
+points back to `memorax-code setup`.
+
+If secure credential setup fails, confirm that the operating-system credential
+backend is available to the same logged-in user and that the MemoraX service is
+reachable. On Linux, confirm that `/usr/bin/secret-tool` is installed and the
+session can reach an unlocked Secret Service. Minimal containers and detached
+SSH sessions often do not provide one.
+
+Malformed `config.toml` is preserved rather than overwritten. Repair or
+restore the file, then rerun setup. Invalid setup-completion records also fail
+closed; preserve a diagnostic copy and confirm no setup command is active
+before moving an invalid record aside. An unsupported record version requires
+a compatible MemoraX Code release.
+
+## npm package transition fails
+
+Replacing a running managed installation uses
+`$MEMORAX_CODE_HOME/runtime/install/package-transition.json`. If preinstall
+cannot retire the old Backend, installation stops before package replacement.
+If postinstall cannot start or verify the new Backend, the retired transition
+is retained for a bounded retry.
+
+Do not delete the record while the old Backend or another lifecycle command may
+still own state. After confirming process ownership, retry:
+
+```sh
+memorax-code stop --clients none
+npm install -g @memorax/memorax-code
+```
+
+Fresh and already-stopped installations do not create a transition and remain
+stopped.
+
 ## Installed, but memory is unavailable
 
 The package and Backend can be healthy while MemoraX remains unconfigured. Run:
 
 ```sh
+memorax-code setup
 memorax-cli status
 ```
 
-Configure `endpoint`, `user_id`, and `api_key` under `[memorax]` in
-`$MEMORAX_CODE_HOME/config.toml`, or set their environment equivalents. The
-current default endpoint is `https://platform.memorax.net`.
+Default setup creates or restores an account-free connection. For an existing
+account, run `memorax-code setup --existing-account`. A manually managed
+connection may instead configure `endpoint`, `user_id`, and `api_key`
+under `[memorax]`, or set their environment equivalents. The current default
+endpoint is `https://platform.memorax.net`.
 
 After changing persistent configuration:
 
@@ -42,6 +108,29 @@ search. Automatic writeback requires `[memory.writeback] enabled = true` and
 must not be disabled by
 `MEMORAX_CODE_MEMORAX_WRITEBACK_ENABLED=false`.
 
+## Quota reminder and Mark ID
+
+Memory write and memory search reminders are tracked independently. A reminder
+is emitted when the corresponding remaining quota reaches 10% or less and
+again at 0%; raw quota counts are not shown.
+
+Automatic quota reminders are currently supported in Codex, Claude Code, and
+OpenCode. DeepSeek Harness does not currently surface these reminders.
+
+Routine reminders do not include a complete Mark ID. If this device uses an
+unregistered anonymous identity and the MemoraX account page requires its Mark
+ID, run this command yourself in a local terminal:
+
+```sh
+memorax-code account --show-mark-id
+```
+
+The command reads a ready local trial identity and prints only its Mark ID. Do
+not ask an Agent to run it or paste the output into a conversation, screenshot,
+or log. If no ready local trial identity exists, use `memorax-code setup`; a
+connection copied from another computer does not include that computer's
+device-local Mark ID.
+
 ## Backend does not start
 
 ```sh
@@ -91,9 +180,10 @@ memorax-code start --clients codex
 memorax-code-codex doctor
 ```
 
-Codex requires review for new or changed Hook command hashes. A declined or
-non-interactive update can leave Hooks untrusted even though the update
-succeeded. Do not write trust entries directly. If the skill is missing, rerun
+Codex requires review for new or changed Hook command hashes. A declined,
+non-interactive, or direct npm update can leave changed Hooks untrusted even
+though package replacement succeeded. Run `memorax-code setup` for foreground
+review; do not write trust entries directly. If the skill is missing, rerun
 `memorax-code start --clients codex`, then restart or refresh Codex.
 
 ## Claude Code plugin or Hook is inactive
@@ -116,10 +206,18 @@ memorax-code start --clients dsh
 memorax-code status --clients dsh
 ```
 
+Automatic DSH discovery is optional: an unavailable DSH integration is
+reported as degraded without blocking the Backend or another detected client.
+The explicit commands above are strict and return a failure until DSH is ready.
+
 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
+means neither the selected DSH command nor an existing Profile-linked DSH
+runtime supplied a valid semantic version. A `dsh_profile_runtime_stale` result
+means that Profile-linked package is invalid or its original package cache is
+no longer available. Repair or relaunch DSH itself, then rerun the MemoraX Code
+start command. MemoraX Code never invokes `npx` or installs or updates DSH. 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.

package/lib/memorax-code-adapter-common/src/config-utils.d.mts

@@ -4,6 +4,10 @@ export type JsonFileLockOptions = Readonly<{
   retryMs?: number;
 }>;
 
+export type AsyncJsonFileLockOptions = JsonFileLockOptions & Readonly<{
+  signal?: AbortSignal;
+}>;
+
 export function readAdapterState(path: string): any;
 export function readJsonFile(path: string): any;
 export function readJsonValue(path: string): any;
@@ -23,5 +27,5 @@ export function withJsonFileLock<T>(
 export function withJsonFileLockAsync<T>(
   path: string,
   operation: () => T | Promise<T>,
-  options?: JsonFileLockOptions,
+  options?: AsyncJsonFileLockOptions,
 ): Promise<T>;