feat(worker): add CLAUDE_MEM_WORKER_SCRIPT_PATH to pin the worker bundle

[crippledgeek]

Closes #3054.

Problem

resolveWorkerScriptPath() (src/shared/worker-utils.ts) resolves the worker-service.cjs the daemon spawns/respawns from two hardcoded candidates — the installed marketplace path, then cwd — with no override. The installed path is checked first and almost always exists, so every respawn resolves to the installed bundle, even when the worker was launched from a local build. There's no documented way to run/test the worker against a local branch build without overwriting the install via sync-marketplace.

Change

Add an opt-in env var CLAUDE_MEM_WORKER_SCRIPT_PATH, checked first in resolveWorkerScriptPath() (guarded by existsSync):

const candidates = [
  process.env.CLAUDE_MEM_WORKER_SCRIPT_PATH,   // opt-in override, first
  path.join(MARKETPLACE_ROOT, 'plugin', 'scripts', 'worker-service.cjs'),
  path.join(process.cwd(), 'plugin', 'scripts', 'worker-service.cjs'),
];
for (const candidate of candidates) {
  if (candidate && existsSync(candidate)) return candidate;
}

• One site, all daemon spawn paths inherit it — worker-utils.ts lazy-spawn, worker-service.ts restart + restart-handoff successor, mcp-server.ts. (The npx CLI wrapper and hook shell templates intentionally keep resolving the installed bundle as thin entry-clients; they delegate to the daemon, which honors the override.)
• Opt-in / zero-risk — unset, empty, or set-but-nonexistent → byte-identical prior behavior. The candidate && guard is also required for the type to compile (process.env.X is string | undefined).
• Env-only — this is a bootstrap resolution (which worker to spawn, before settings load), so it deliberately gets no SettingsDefaults entry, mirroring how MARKETPLACE_ROOT/CLAUDE_CONFIG_DIR are env-derived.
• Naming follows the project conventions: CLAUDE_MEM_WORKER_* scope (cf. WORKER_PORT/WORKER_HOST) + _PATH suffix (cf. CLAUDE_MEM_CHROMA_UVX_PATH).

Tests

New tests/shared/worker-script-path.test.ts (first coverage for this resolver): override-set-and-existing wins; set-but-nonexistent ignored (== unset); empty-string ignored (== unset). Env/temp-file isolated. npm run typecheck clean; full suite shows no new failures.

Docs

configuration.mdx (env table) + development.mdx (Manual Testing: local-build recipe, with a note that pinning a different-version bundle than the installed plugin can trigger the existing version-recycle restart behavior once sessions fire hooks).

[greptile-apps]

Greptile Summary

This PR adds an opt-in worker bundle override for daemon launches. The main changes are:

• Adds CLAUDE_MEM_WORKER_SCRIPT_PATH as the first candidate in resolveWorkerScriptPath().
• Preserves the existing marketplace and cwd fallback behavior when the override is unset, empty, or missing.
• Adds tests for override precedence and fallback behavior.
• Documents the new environment variable and a local-build testing workflow.

Confidence Score: 5/5

The change is limited to an opt-in environment override with existing fallback behavior preserved.

The implementation is narrow, covered by focused tests for override and fallback cases, and the documentation matches the intended local-build workflow.

T-Rex Logs

What T-Rex did

• Ran a test comparing base and head resolvers for CLAUDE_MEM_WORKER_SCRIPT_PATH to verify behavior across override scenarios.
• Compared the before and after behavior: the base resolver ignored CLAUDE_MEM_WORKER_SCRIPT_PATH and used the cwd fallback when marketplace was absent, while the head resolver returned the existing override path for the override scenario and used the same cwd fallback for nonexistent or empty overrides.
• Confirmed both test runs exited with code 0 and captured the resolver implementation lines and return_value for each scenario.

_{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "docs(worker): document CLAUDE_MEM_WORKER..." | Re-trigger Greptile}