@memorax/memorax-code 0.1.5 → 0.1.6

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

@@ -6,6 +6,7 @@ import {
   lstatSync,
   mkdirSync,
   readFileSync,
+  realpathSync,
   readdirSync,
   renameSync,
   rmSync,
@@ -22,6 +23,7 @@ import {
   parseDshVersion,
 } from "./dsh-version.mjs";
 import {
+  buildDshCommand,
   requireDshRuntimeAuthority,
   requireEnabledDshRuntime,
 } from "./runtime-state.mjs";
@@ -49,6 +51,7 @@ const { resolveWindowsCliInvocation } = await import(
 
 const STATE_VERSION = 1;
 const RUNTIME = "dsh";
+const DSH_PACKAGE_NAME = "@deepseek-ai/dsh";
 const ADAPTER_PACKAGE_NAME = "@memorax-code/dsh-memorax-code";
 const HEADLESS_PROFILE_NAME = "headless";
 const HEADLESS_BUNDLE_NAME = "@deepseek-ai/dsh-headless";
@@ -160,14 +163,18 @@ export function collectDshAdapterStatus(options = {}) {
       return { ok: true, ...base, skipped: true, reason: "no_existing_profiles" };
     }
 
-    const dshCommand = resolveDshCommand(options, paths, state);
-    const compatibility = inspectDshCompatibility(options, paths, dshCommand);
+    const { dshCommand, compatibility } = resolveDshStatusCompatibility(
+      options,
+      paths,
+      state,
+    );
     const version = compatibility.dshVersion;
     const versionStatus = {
       dshVersionTested: compatibility.dshVersionTested,
       testedDshVersions: [...DSH_TESTED_VERSIONS],
     };
-    if (compatibility.reason === "dsh_version_unavailable") {
+    if (compatibility.reason === "dsh_version_unavailable"
+      || compatibility.reason === "dsh_profile_runtime_stale") {
       return {
         ok: false,
         ...base,
@@ -327,8 +334,7 @@ function ensureDshPluginInstalledUnlocked(paths, options) {
     };
   }
 
-  const dshCommand = resolveDshCommand(options, paths, state);
-  const compatibility = inspectDshCompatibility(options, paths, dshCommand);
+  const { dshCommand, compatibility } = resolveDshCompatibility(options, paths, state);
   if (compatibility.compatible !== true) {
     const nextState = state?.enabled === true
       ? disabledState(state, state.profiles)
@@ -805,7 +811,13 @@ function disableDshPluginInstallationUnlocked(paths, options, removeState) {
   };
 }
 
-function removeProfileAdapterPackages(paths, options, name, packageNames, dshCommand) {
+function removeProfileAdapterPackages(
+  paths,
+  options,
+  name,
+  packageNames,
+  dshCommand,
+) {
   const profilePath = join(paths.profilesRoot, name);
   let profile = inspectProfile(name, profilePath);
   let failure;
@@ -1049,14 +1061,153 @@ function resolveDshCommand(options, paths, state) {
     ?? nonEmpty(paths.env.MEMORAX_CODE_DSH_COMMAND)
     ?? nonEmpty(state?.dshCommand)
     ?? "dsh";
+  const normalized = normalizeDshCommand(command);
+  if (normalized) return normalized;
+  const profileRuntime = inspectProfileDshRuntime(paths, state);
+  return profileRuntime?.compatibility.compatible === true
+    ? profileRuntime.dshCommand
+    : "dsh";
+}
+
+function resolveDshStatusCompatibility(options, paths, state) {
+  if (state?.enabled !== true) return resolveDshCompatibility(options, paths, state);
+  const dshCommand = normalizeDshCommand(state.dshCommand);
+  if (!dshCommand) {
+    return {
+      dshCommand: state.dshCommand,
+      compatibility: unavailableDshCompatibility("dsh_version_unavailable"),
+    };
+  }
+  const profileRuntime = inspectProfileDshRuntime(paths, state);
+  return profileRuntime?.dshCommand === dshCommand
+    ? profileRuntime
+    : { dshCommand, compatibility: inspectDshCompatibility(options, paths, dshCommand) };
+}
+
+function resolveDshCompatibility(options, paths, state) {
+  const configured = nonEmpty(options.dshCommand)
+    ?? nonEmpty(paths.env.MEMORAX_CODE_DSH_COMMAND);
+  if (configured) {
+    const dshCommand = normalizeDshCommand(configured);
+    return dshCommand
+      ? { dshCommand, compatibility: inspectDshCompatibility(options, paths, dshCommand) }
+      : {
+          dshCommand: configured,
+          compatibility: unavailableDshCompatibility("dsh_version_unavailable"),
+        };
+  }
+
+  const profileRuntime = inspectProfileDshRuntime(paths, state);
+  const attemptedCommands = new Set();
+  let unavailable;
+  for (const value of [state?.dshCommand, "dsh"]) {
+    const dshCommand = normalizeDshCommand(value);
+    if (!dshCommand || attemptedCommands.has(dshCommand)) continue;
+    attemptedCommands.add(dshCommand);
+    if (dshCommand === profileRuntime?.dshCommand) {
+      if (profileRuntime.compatibility.compatible === true) return profileRuntime;
+      continue;
+    }
+    const compatibility = inspectDshCompatibility(options, paths, dshCommand);
+    if (compatibility.compatible === true) return { dshCommand, compatibility };
+    unavailable ??= { dshCommand, compatibility };
+  }
+  if (profileRuntime?.compatibility.compatible === true) return profileRuntime;
+  if (profileRuntime?.compatibility.reason === "dsh_profile_runtime_stale") {
+    return {
+      dshCommand: profileRuntime.dshCommand ?? unavailable?.dshCommand ?? "dsh",
+      compatibility: profileRuntime.compatibility,
+    };
+  }
+  return unavailable ?? {
+    dshCommand: "dsh",
+    compatibility: unavailableDshCompatibility("dsh_version_unavailable"),
+  };
+}
+
+function normalizeDshCommand(value) {
+  const command = nonEmpty(value);
+  if (!command) return undefined;
+  const name = command
+    .split(/[\\/]/)
+    .at(-1)
+    .replace(/\.(?:cmd|bat|exe|com)$/i, "")
+    .toLowerCase();
+  if (name === "npx") return undefined;
   return command.includes("/") || command.includes("\\") ? resolve(command) : command;
 }
 
+function inspectProfileDshRuntime(paths, state) {
+  const packageRoot = join(paths.profilesRoot, "node_modules", ...DSH_PACKAGE_NAME.split("/"));
+  const persistedCommand = normalizeDshCommand(state?.dshCommand);
+  const profileCommand = persistedCommand && isPathInside(persistedCommand, packageRoot)
+    ? persistedCommand
+    : undefined;
+  try {
+    lstatSync(packageRoot);
+  } catch (error) {
+    return error?.code === "ENOENT" && !profileCommand
+      ? undefined
+      : {
+          dshCommand: profileCommand,
+          compatibility: unavailableDshCompatibility("dsh_profile_runtime_stale"),
+        };
+  }
+
+  try {
+    const realPackageRoot = realpathSync(packageRoot);
+    if (!lstatSync(realPackageRoot).isDirectory()) throw new Error("DSH package root is not a directory");
+    const manifest = readJsonObject(join(realPackageRoot, "package.json"));
+    const version = manifest?.name === DSH_PACKAGE_NAME
+      ? parseDshVersion(manifest.version)
+      : undefined;
+    const bin = manifest?.bin !== null
+      && typeof manifest?.bin === "object"
+      && !Array.isArray(manifest.bin)
+      ? nonEmpty(manifest.bin.dsh)
+      : undefined;
+    if (!version || !bin || isAbsolute(bin)) throw new Error("DSH package metadata is invalid");
+
+    const dshCommand = resolve(packageRoot, bin);
+    const realCommand = realpathSync(dshCommand);
+    if (!isPathInside(dshCommand, packageRoot)
+      || !isPathInside(realCommand, realPackageRoot)
+      || !lstatSync(realCommand).isFile()) {
+      throw new Error("DSH package entrypoint is invalid");
+    }
+    return {
+      dshCommand,
+      compatibility: {
+        compatible: true,
+        dshVersion: version,
+        dshVersionTested: isTestedDshVersion(version),
+        testedDshVersions: [...DSH_TESTED_VERSIONS],
+      },
+    };
+  } catch {
+    return {
+      dshCommand: profileCommand,
+      compatibility: unavailableDshCompatibility("dsh_profile_runtime_stale"),
+    };
+  }
+}
+
+function unavailableDshCompatibility(reason) {
+  return {
+    compatible: false,
+    reason,
+    testedDshVersions: [...DSH_TESTED_VERSIONS],
+  };
+}
+
 function runDsh(options, paths, args, command) {
   const env = { ...paths.env, DSH_HOME: paths.dshHome };
   let executable;
   try {
-    executable = resolveWindowsCliInvocation(command, args, {
+    const [launcher, ...launcherArgs] = buildDshCommand(command, args, {
+      nodePath: options.windowsCliResolution?.nodePath,
+    });
+    executable = resolveWindowsCliInvocation(launcher, launcherArgs, {
       ...options.windowsCliResolution,
       env,
     });

package/lib/memorax-code-dsh-adapter/src/runtime-state.mjs

@@ -5,6 +5,17 @@ import { parseDshVersion } from "./dsh-version.mjs";
 
 const PACKAGE_METADATA_VERSION = 1;
 const STATE_VERSION = 1;
+
+export function buildDshCommand(command, args, options = {}) {
+  const executable = nonEmptyString(command);
+  if (!executable) throw new TypeError("DSH command must be a non-empty string");
+  if (!Array.isArray(args)) throw new TypeError("DSH arguments must be an array");
+  if (isNpxCommand(executable)) throw disabledError();
+  return isAbsolute(executable) && /\.(?:cjs|js|mjs)$/i.test(executable)
+    ? [nonEmptyString(options.nodePath) ?? process.execPath, executable, ...args]
+    : [executable, ...args];
+}
+
 /** Read the current durable enablement authority for this installed DSH bundle. */
 export function requireEnabledDshRuntime(pluginRoot) {
   const authority = requireDshRuntimeAuthority(pluginRoot);
@@ -28,6 +39,7 @@ export function requireDshRuntimeAuthority(pluginRoot) {
     || !nonEmptyString(metadata.memoraxCodeCommand)
     || !nonEmptyString(metadata.memoraxCodeHome)
     || !nonEmptyString(metadata.dshCommand)
+    || isNpxCommand(metadata.dshCommand)
     || !nonEmptyString(metadata.dshHome)
     || !parseDshVersion(metadata.dshVersion)
     || !nonEmptyString(metadata.sourceAdapterRoot)
@@ -102,6 +114,15 @@ function nonEmptyString(value) {
   return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 
+function isNpxCommand(value) {
+  const command = nonEmptyString(value);
+  return Boolean(command && command
+    .split(/[\\/]/)
+    .at(-1)
+    .replace(/\.(?:cmd|bat|exe|com)$/i, "")
+    .toLowerCase() === "npx");
+}
+
 function timestampString(value) {
   const normalized = nonEmptyString(value);
   return normalized && Number.isFinite(Date.parse(normalized)) ? normalized : undefined;

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

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

package/lib/memorax-code-opencode-adapter/skills/memorax-code/references/memorax-add.md

@@ -83,4 +83,6 @@ Do not add speculation, assistant-only praise, or a current instruction merely b
 
 ## Output
 
+If a successful Add returns `quotaNotice`, or prints it as a quota-reminder line in the default CLI output, present the complete reminder once and prominently before the normal result summary. Do not reduce it to only a percentage or omit its account URL or conditional local Mark ID retrieval instructions. Never run `memorax-code account --show-mark-id` for the user, ask for its output, or reproduce a Mark ID in chat. Treat the reminder as user-facing operational output, not coding memory content, and continue the current task.
+
 After an add request is accepted, confirm briefly that it was submitted for processing and identify the reusable coding lesson at a high level. If add is disabled or fails, report the issue and continue without bypassing the CLI.

package/lib/memorax-code-opencode-adapter/skills/memorax-code/references/memorax-search.md

@@ -6,11 +6,11 @@ Use these instructions only to search reusable coding memory through `memorax-cl
 
 Run the CLI from the active task workspace. The installed Hook and session binding supply the authoritative workspace root; do not run `git rev-parse`, infer the root from Git metadata, or substitute an unrelated working directory. Do not make `memorax-cli status` a mandatory preflight; use it only to diagnose a configuration or scope failure.
 
-Coding memory uses `<MemoraX base user ID>@<normalized repository name>` for Git workspaces and the normalized folder name for genuine non-Git directories. MemoraX Code resolves `.git`, `gitdir`, and `commondir` without executing Git. Linked worktrees share one repository scope; another clone, repository, or non-Git directory retains a different local session key even when its readable name matches.
+Coding memory uses `<MemoraX base username>@<normalized repository name>` for Git workspaces and the normalized folder name for genuine non-Git directories. MemoraX Code resolves `.git`, `gitdir`, and `commondir` without executing Git. Linked worktrees share one repository scope; another clone, repository, or non-Git directory retains a different local session key even when its readable name matches.
 
 If a successful Search result reports `workspaceScopeFallbackReason: git_metadata_invalid`, malformed or incomplete metadata inside a direct `.git` directory was downgraded to the normalized local folder scope. Search has already run with the reported `effectiveUserId`. Present its `userNotice` once without pausing the current task or asking the user to repair Git first, then continue with the returned memory and live evidence. After the repository or `.git` metadata is repaired, later Search, Add, and automatic writeback in the same client session automatically use the restored Git repository scope.
 
-Require a readable active workspace binding. A CLI command from a linked worktree of the bound repository is valid. If `memorax-cli search` reports `workspace_scope_mismatch` or `workspace_scope_unavailable`, do not bypass the scope or fall back to an unscoped user id. Do not change the CLI working directory and retry. Tell the user that memory search was not executed and no request was sent to MemoraX, then present the CLI's `userAction` in natural language. Continue the current task using only live code and documentation.
+Require a readable active workspace binding. A CLI command from a linked worktree of the bound repository is valid. If `memorax-cli search` reports `workspace_scope_mismatch` or `workspace_scope_unavailable`, do not bypass the scope or fall back to an unscoped username. Do not change the CLI working directory and retry. Tell the user that memory search was not executed and no request was sent to MemoraX, then present the CLI's `userAction` in natural language. Continue the current task using only live code and documentation.
 
 If `memorax-cli` is not on `PATH`, or memory is disabled, unconfigured, or unavailable, report that briefly and continue with live code or documentation. Authenticate through MemoraX Code configuration; never recover credentials from shell history or place tokens in prompts. Treat injected memory as a hypothesis and verify it against the current checkout.
 
@@ -88,4 +88,6 @@ Do not apply this retry to `memorax-cli add`, authentication or configuration fa
 
 ## Output
 
+If a successful Search returns `quotaNotice`, or prints it as a quota-reminder line in the default CLI output, present the complete reminder once and prominently before the normal result summary. Do not reduce it to only a percentage or omit its account URL or conditional local Mark ID retrieval instructions. Never run `memorax-code account --show-mark-id` for the user, ask for its output, or reproduce a Mark ID in chat. Treat the reminder as user-facing operational output, not recalled memory, and continue the current task.
+
 Mention only an invariant, pitfall, convention, or validation idea that materially affects the answer. Ground claims about current implementation behavior in live code and checks.

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

@@ -210,6 +210,7 @@ export function createMemoraxOpenCodePlugin(options = {}) {
           }, TURN_START_TIMEOUT_MS);
           turnStartAccepted = true;
           if (!pluginEnabled(options)) return;
+          void showUserNotice(client, directory, result?.userNotice, options);
           repositoryWorktree = stringValue(result?.repoMemoryWorktree);
           const repoMemoryEnv = openCodeRepoMemoryEnv(options, openCodeServerUrl, sessionId);
           if (repoMemoryEnv) {
@@ -384,6 +385,25 @@ function appendSystemContexts(output, ...contexts) {
   output.message.system = [existing, ...additions].filter(Boolean).join("\n\n");
 }
 
+async function showUserNotice(client, directory, notice, options) {
+  const message = stringValue(notice);
+  if (!message || typeof client?.tui?.showToast !== "function") return;
+  try {
+    await client.tui.showToast({
+      body: {
+        title: "MemoraX Code",
+        message,
+        variant: "warning",
+        duration: 10_000,
+      },
+      query: { directory },
+      throwOnError: true,
+    });
+  } catch (error) {
+    debug(options, "opencode quota reminder failed", error);
+  }
+}
+
 function recordReminder(options, reminder) {
   if (!reminder.turnId) return Promise.resolve();
   return postBackend(options, "/memory/skill-reminder", {

package/lib/package-transition.mjs

@@ -0,0 +1,311 @@
+import { randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { withJsonFileLock, withJsonFileLockAsync } from "./memorax-code-adapter-common/src/config-utils.mjs";
+import {
+  readJsonRuntimeRecord,
+  RuntimeRecordError,
+  writePrivateJsonRecord,
+} from "./memorax-code-adapter-common/src/runtime-record.mjs";
+
+export const PACKAGE_TRANSITION_RECORD_VERSION = 1;
+export const PACKAGE_TRANSITION_FRESHNESS_MS = 15 * 60 * 1_000;
+export const PACKAGE_TRANSITION_COMMAND_TIMEOUT_MS = 45_000;
+
+const RETIRING_KEYS = new Set([
+  "version",
+  "state",
+  "transitionId",
+  "startedAt",
+  "sourceVersion",
+]);
+const RETIRED_KEYS = new Set([...RETIRING_KEYS, "retiredAt"]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+export class PackageTransitionRecordError extends RuntimeRecordError {
+  constructor(state, path) {
+    super({
+      name: "Package transition record",
+      path,
+      state,
+      codePrefix: "PACKAGE_TRANSITION_RECORD",
+      recovery: state.status === "unsupported"
+        ? "upgrade MemoraX Code or restore a supported package transition record"
+        : "inspect the package transition record before retrying installation",
+    });
+    this.name = "PackageTransitionRecordError";
+  }
+}
+
+export function packageTransitionPath(memoraxCodeHome = defaultMemoraxCodeHome()) {
+  return join(memoraxCodeHome, "runtime", "install", "package-transition.json");
+}
+
+export function readPackageTransitionRecord(memoraxCodeHome = defaultMemoraxCodeHome()) {
+  const path = packageTransitionPath(memoraxCodeHome);
+  const state = readJsonRuntimeRecord(path);
+  if (state.status !== "present") return state;
+  const value = state.value;
+  if (value.version !== PACKAGE_TRANSITION_RECORD_VERSION) {
+    if (Number.isSafeInteger(value.version) && value.version > 0) {
+      return { status: "unsupported", version: value.version };
+    }
+    return { status: "invalid", reason: "invalid_version" };
+  }
+  if (value.state !== "retiring" && value.state !== "retired") {
+    return { status: "invalid", reason: "invalid_state" };
+  }
+  const allowedKeys = value.state === "retiring" ? RETIRING_KEYS : RETIRED_KEYS;
+  if (Object.keys(value).length !== allowedKeys.size
+    || Object.keys(value).some((key) => !allowedKeys.has(key))) {
+    return { status: "invalid", reason: "unknown_or_missing_fields" };
+  }
+  if (typeof value.transitionId !== "string" || !UUID_PATTERN.test(value.transitionId)) {
+    return { status: "invalid", reason: "invalid_transition_id" };
+  }
+  const startedAt = isoTimestamp(value.startedAt);
+  if (!startedAt) return { status: "invalid", reason: "invalid_started_at" };
+  const sourceVersion = nonEmptyString(value.sourceVersion);
+  if (!sourceVersion) return { status: "invalid", reason: "invalid_source_version" };
+  const record = {
+    version: PACKAGE_TRANSITION_RECORD_VERSION,
+    state: value.state,
+    transitionId: value.transitionId,
+    startedAt,
+    sourceVersion,
+  };
+  if (value.state === "retired") {
+    const retiredAt = isoTimestamp(value.retiredAt);
+    if (!retiredAt || Date.parse(retiredAt) < Date.parse(startedAt)) {
+      return { status: "invalid", reason: "invalid_retired_at" };
+    }
+    record.retiredAt = retiredAt;
+  }
+  return { status: "valid", record };
+}
+
+export function runNpmPreinstallPackageTransition(options = {}) {
+  const memoraxCodeHome = nonEmptyString(options.memoraxCodeHome) ?? defaultMemoraxCodeHome();
+  const memoraxCodeBin = requiredString(options.memoraxCodeBin, "memoraxCodeBin");
+  const packageVersion = requiredString(options.packageVersion, "packageVersion");
+  const pidPath = backendPidPath(memoraxCodeHome);
+  const dshStatePath = join(memoraxCodeHome, "adapters", "dsh", "state.json");
+  if (!existsSync(pidPath) && !existsSync(dshStatePath)) return { disposition: "noop" };
+
+  const transitionPath = packageTransitionPath(memoraxCodeHome);
+  let transition;
+  let shouldStop = false;
+  withJsonFileLock(transitionPath, () => {
+    const existing = readPackageTransitionRecord(memoraxCodeHome);
+    if (existing.status !== "absent") throw packageTransitionStateError(existing, transitionPath);
+    const pidState = readBackendPidState(pidPath);
+    const hasDshState = existsSync(dshStatePath);
+    if (pidState.status === "absent" && !hasDshState) return;
+    shouldStop = true;
+    if (pidState.status !== "alive" && !hasDshState) return;
+    transition = {
+      version: PACKAGE_TRANSITION_RECORD_VERSION,
+      state: "retiring",
+      transitionId: randomUUID(),
+      startedAt: nowIso(options),
+      sourceVersion: packageVersion,
+    };
+    const write = writePrivateJsonRecord(transitionPath, transition, {
+      durableBoundary: memoraxCodeHome,
+    });
+    if (write.durability !== "confirmed") {
+      throw transitionError("PACKAGE_TRANSITION_DURABILITY_UNCERTAIN", "durable persistence of the retiring package transition could not be confirmed");
+    }
+  });
+
+  if (!shouldStop) return { disposition: "noop" };
+  const stopped = runLifecycleCommand({
+    ...options,
+    memoraxCodeHome,
+    memoraxCodeBin,
+    args: ["stop", "--home", memoraxCodeHome, "--clients", "none", "--json"],
+    env: { ...options.env, MEMORAX_CODE_PACKAGE_REPLACEMENT: "1" },
+    label: "memorax-code stop",
+  });
+  if (existsSync(pidPath)) {
+    throw transitionError(
+      "PACKAGE_TRANSITION_PID_REMAINS",
+      `managed Backend PID authority still exists at ${pidPath}`,
+      stopped.result,
+    );
+  }
+  if (!transition) return { disposition: "cleaned" };
+
+  const retired = withJsonFileLock(transitionPath, () => {
+    const current = requireValidTransition(memoraxCodeHome);
+    if (current.record.state !== "retiring"
+      || current.record.transitionId !== transition.transitionId) {
+      throw transitionError("PACKAGE_TRANSITION_REPLACED", "package transition changed while the Backend was being retired");
+    }
+    const record = { ...current.record, state: "retired", retiredAt: nowIso(options) };
+    const write = writePrivateJsonRecord(transitionPath, record, {
+      durableBoundary: memoraxCodeHome,
+    });
+    if (write.durability !== "confirmed") {
+      throw transitionError("PACKAGE_TRANSITION_DURABILITY_UNCERTAIN", "durable persistence of the retired package transition could not be confirmed");
+    }
+    return record;
+  });
+  return { disposition: "retired", transition: retired };
+}
+
+export async function runNpmPostinstallPackageTransition(options = {}) {
+  const memoraxCodeHome = nonEmptyString(options.memoraxCodeHome) ?? defaultMemoraxCodeHome();
+  const memoraxCodeBin = requiredString(options.memoraxCodeBin, "memoraxCodeBin");
+  const transitionPath = packageTransitionPath(memoraxCodeHome);
+  if (readJsonRuntimeRecord(transitionPath).status === "absent") {
+    return { disposition: "noop" };
+  }
+
+  return await withJsonFileLockAsync(transitionPath, async () => {
+    const reloaded = readPackageTransitionRecord(memoraxCodeHome);
+    if (reloaded.status === "absent") return { disposition: "noop" };
+    if (reloaded.status !== "valid") {
+      throw new PackageTransitionRecordError(reloaded, transitionPath);
+    }
+    const current = reloaded;
+    if (current.record.state !== "retired") {
+      throw transitionError("PACKAGE_TRANSITION_NOT_RETIRED", "package transition is still retiring");
+    }
+    const ageMs = nowMs(options) - Date.parse(current.record.retiredAt);
+    if (ageMs < 0 || ageMs > PACKAGE_TRANSITION_FRESHNESS_MS) {
+      throw transitionError("PACKAGE_TRANSITION_STALE", "retired package transition is stale");
+    }
+
+    runLifecycleCommand({
+      ...options,
+      memoraxCodeHome,
+      memoraxCodeBin,
+      args: ["start", "--home", memoraxCodeHome, "--json"],
+      env: { ...options.env, MEMORAX_CODE_PACKAGE_REPLACEMENT: "1" },
+      label: "memorax-code start",
+    });
+    runLifecycleCommand({
+      ...options,
+      memoraxCodeHome,
+      memoraxCodeBin,
+      args: ["status", "--home", memoraxCodeHome, "--json"],
+      label: "memorax-code status",
+    });
+
+    const finalState = requireValidTransition(memoraxCodeHome);
+    if (finalState.record.state !== "retired"
+      || finalState.record.transitionId !== current.record.transitionId) {
+      throw transitionError("PACKAGE_TRANSITION_REPLACED", "package transition changed before it could be consumed");
+    }
+    unlinkSync(transitionPath);
+    return { disposition: "restored", transitionId: current.record.transitionId };
+  });
+}
+
+function requireValidTransition(memoraxCodeHome) {
+  const path = packageTransitionPath(memoraxCodeHome);
+  const state = readPackageTransitionRecord(memoraxCodeHome);
+  if (state.status !== "valid") throw new PackageTransitionRecordError(state, path);
+  return state;
+}
+
+function packageTransitionStateError(state, path) {
+  if (state.status === "valid") {
+    return transitionError("PACKAGE_TRANSITION_PENDING", `package transition is already ${state.record.state}: ${path}`);
+  }
+  return new PackageTransitionRecordError(state, path);
+}
+
+function readBackendPidState(path) {
+  const state = readJsonRuntimeRecord(path);
+  if (state.status === "absent") return state;
+  if (state.status !== "present" || !Number.isSafeInteger(state.value.pid) || state.value.pid <= 0) {
+    return { status: "unknown" };
+  }
+  try {
+    process.kill(state.value.pid, 0);
+    return { status: "alive", pid: state.value.pid };
+  } catch (error) {
+    if (error?.code === "ESRCH") return { status: "dead", pid: state.value.pid };
+    if (error?.code === "EPERM") return { status: "alive", pid: state.value.pid };
+    return { status: "unknown", pid: state.value.pid };
+  }
+}
+
+function runLifecycleCommand(options) {
+  const spawn = options.spawnSyncImpl ?? spawnSync;
+  const result = spawn(process.execPath, [options.memoraxCodeBin, ...options.args], {
+    encoding: "utf8",
+    env: { ...process.env, ...options.env, MEMORAX_CODE_HOME: options.memoraxCodeHome },
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: positiveInteger(options.commandTimeoutMs, PACKAGE_TRANSITION_COMMAND_TIMEOUT_MS),
+    killSignal: "SIGKILL",
+    windowsHide: true,
+  });
+  if (result.error || result.signal || result.status !== 0) {
+    const detail = result.error?.code === "ETIMEDOUT"
+      ? `${options.label} timed out after ${positiveInteger(options.commandTimeoutMs, PACKAGE_TRANSITION_COMMAND_TIMEOUT_MS)} ms`
+      : result.error?.message
+      ?? (result.signal ? `${options.label} exited from signal ${result.signal}` : `${options.label} exited with status ${result.status ?? "unknown"}`);
+    throw transitionError("PACKAGE_TRANSITION_COMMAND_FAILED", detail, result);
+  }
+  let report;
+  try {
+    report = JSON.parse(String(result.stdout ?? ""));
+  } catch {
+    throw transitionError("PACKAGE_TRANSITION_COMMAND_INVALID_JSON", `${options.label} did not return valid JSON`, result);
+  }
+  if (!report || typeof report !== "object" || Array.isArray(report) || report.ok !== true) {
+    throw transitionError("PACKAGE_TRANSITION_COMMAND_NOT_OK", `${options.label} did not report ok=true`, result);
+  }
+  return { result, report };
+}
+
+function transitionError(code, message, command) {
+  const error = new Error(message);
+  error.name = "PackageTransitionError";
+  error.code = code;
+  if (command) error.command = command;
+  return error;
+}
+
+function backendPidPath(memoraxCodeHome) {
+  return join(memoraxCodeHome, "runtime", "backend", "backend.pid.json");
+}
+
+function defaultMemoraxCodeHome() {
+  return join(homedir(), ".memorax-code");
+}
+
+function requiredString(value, name) {
+  const result = nonEmptyString(value);
+  if (!result) throw new TypeError(`package transition requires ${name}`);
+  return result;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function isoTimestamp(value) {
+  const candidate = nonEmptyString(value);
+  return candidate && ISO_TIMESTAMP_PATTERN.test(candidate) && Number.isFinite(Date.parse(candidate))
+    ? candidate
+    : undefined;
+}
+
+function positiveInteger(value, fallback) {
+  return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+function nowMs(options) {
+  return typeof options.now === "function" ? Number(options.now()) : Date.now();
+}
+
+function nowIso(options) {
+  return new Date(nowMs(options)).toISOString();
+}