[plan-stable] Stable working build across supported IDEs and platforms

[thedotmack]

Defect

Current main has many targeted fixes in flight, but the product can still install cleanly while core claude-mem behavior fails at runtime: packaged workers can miss runtime modules, hooks can block or emit host-invalid JSON, worker startup can split across cache/marketplace roots, stale Windows sockets can hold the configured port, Chroma/search can be unavailable after install, provider env sanitization can remove required auth/proxy variables, and settings/storage/project identity can corrupt or mis-key state.

This plan is for branch plan/stable-working-build. The goal is not a new architecture. It is a stable, working build from current main plus only low-risk patches/backports needed for the intended claude-mem feature set to work across supported IDEs/platforms.

Snapshot and Baseline

• Snapshot: /tmp/claude-mem-three-track/backlog-full.json, captured 2026-07-05T04:56:22Z.
• Backlog size: 116 open issues, 134 open PRs.
• Baseline inspected locally: package claude-mem@13.10.1, HEAD e02494852, worktree branch freckle-nail.
• Target branch: plan/stable-working-build.
• Stable principle: prefer small backports, generated-artifact fixes, and contract tests over holistic rewrites.

Backlog Evidence

Release-quality signal

• User-facing brokenness signal: CONSISTENTLY BROKEN #3131.
• Existing plan issues that are broader than this stable track and should not be blindly absorbed: [plan-12] Provider & Extensibility Roadmap — net-new capabilities, not defects #2785, [plan-09] Data-Pipeline Integrity & Migration Transparency — stop 'healthy worker, frozen observations' #2782, [plan-02] Spawn-Contract Templating — canonical ${CLAUDE_PLUGIN_ROOT} resolution across all hosts #2779.

Distribution and runtime packaging

Symptoms:

• Published build can start but fail on missing generated/runtime modules: Backfill crashes on missing module '../sqlite/observations/files.js'; search query param ignored (v13.10.0, v13.9.3) #3126, Chroma vector sync broken on 13.9.x: worker-service.cjs requires ../sqlite/*.js which the build never emits #3107, v13.9.1: two more missing-bundle modules — SessionStore.js (backfill fails at startup) + .install-version marker ("runtime not yet set up") #3092.
• Runtime dependency drift can leave packaged worker/plugin without required modules: fix(build): bundle zod into worker-service.cjs to survive node_modules churn (closes #2831) #2887, worker-service.cjs has external zod requires — breaks when node_modules missing #2831, Every hook reports "Failed with non-blocking status code: No stderr output" on Claude Code 2.1.168 (10.4.0); 13.4.0 unusable (missing deps) — both released paths broken #2823, marketplace.json location not compatible with Claude Code plugin discovery #3004, doctor's required 'Marketplace deps' check cannot be cured by its own hint — repair installs only to the version cache #3117.
• smart-explore/tree-sitter runtime provisioning is inconsistent: v13.5.6: smart_search/smart_outline/smart_unfold return 0 symbols on clean Windows install - tree-sitter-cli binary never downloaded (--ignore-scripts), #1247's extensionless existsSync check still unfixed #2910, tracking: plugin runtime deps missing in distributed bundles — zod external, tree-sitter-cli not downloaded, hooks crash #2964.

Patch evidence:

• Prefer minimal package/build fixes from fix(build): emit plugin/sqlite runtime modules required by worker-service #3108 and, only if needed, fix: worker-service missing sqlite/SessionStore.js + observations/files.js (#3092) #3102.
• Bundle/ship runtime dependency fixes from fix(build): bundle zod into worker-service.cjs to survive node_modules churn (closes #2831) #2887, fix(build): ship & harden plugin/node_modules so hooks resolve zod/v3 (#2379) #2710, fix(packaging): bundle plugin/node_modules so marketplace install ships runtime deps (closes #2407) #2531.
• Runtime provisioning/version marker fixes from fix(install): repair smart-explore runtime provisioning across IDEs #3095, fix: force reinstall on missing .install-version marker instead of nagging (#3092) #3113, fix: ensure marketplace.json is available at Claude Code expected location #3006.
• Node/bun compatibility fix from fix: avoid top-level await in bun-runner so hooks load on Node < 14.8 #3061.

Stable reading:

• Current scripts/build-hooks.js builds the worker and checks generated hook outputs, but the inspected main build path does not emit the plugin/sqlite runtime modules required by the bundled worker.
• This is a release-blocking stable fix because clean installs should not depend on source-tree-only modules.

Worker singleton, root resolution, and port lifecycle

Symptoms:

• Hook root resolution can start separate workers from cache and marketplace copies: Linux: worker path resolves to different on-disk copies across invocation contexts (marketplace checkout vs version cache) → two concurrent daemons, one unsupervised orphan; stale cache versions never GC'd #3134.
• Windows version recycling and Chroma child processes can inherit or hold the listening socket: Windows: version-mismatch recycle orphans children (chroma-mcp) that inherit the listening socket — port stays bound under a dead PID, blocking all respawns for hours #3128, [Windows] Zombie-port killer (#1721) misses orphaned children holding the inherited socket — repro on 13.5.5 via version-mismatch recycle #2893.
• Stale/orphaned workers and port conflicts block prompts or leave misleading health: Windows: failed worker recycle on version bump leaves a zombie process holding port 37777; stale supervisor.json PID then blocks every respawn #3031, Windows: stale port holder + aggressive spawn cooldown blocks prompts for ~15 min (fail-loud threshold 3 too low) #2996, Worker never starts on Windows — port 37777 held by orphaned process; UserPromptSubmit hook fails in a loop and blocks prompts #2926, [Windows] Plugin update orphans the worker port (ghost LISTENING socket), blocking all Claude Code prompts with no graceful recovery #2899, claude-mem worker unreachable — hooks fail silently on every tool call after session start #2891.
• Worker startup/restart behavior is brittle across IDE launches: [Windows] chroma-mcp spawn fails instantly — quote-wrapping of --with specs double-quotes through cmd.exe, silently breaking semantic search (+ expired-token blocks valid CLAUDE_CODE_OAUTH_TOKEN fallback) #3121, [Windows] 版本不匹配时 worker 自杀 + 端口 zombie 连锁故障（13.9.x） #3100, Windows reliability: poison-loop (#3032) still present in 13.8.1 + worker-lifecycle issues (FD inheritance, stale daemon) #3083, [Windows] No shutdown hook for the persistent worker daemon — blocks Claude Code update/restart, and manual stop can leave a ghost LISTEN socket on 37777 #3073, Linux/WSL2: worker-cli.js start reports false "Process died during startup" — #2260 pre-written-PID self-exit still present in v13.8.0 #3052, [Windows] Hook times out after 29s — localhost resolves to ::1 (IPv6) first but worker only listens on 127.0.0.1 (IPv4) #2992, tracking: unreachable worker causes Stop hook exit-2 → infinite retry loop blocking all Claude Code prompts #2966, tracking: Windows worker port orphaned after crash/update — ghost LISTEN socket blocks respawn, hooks fail loop #2963.

Patch evidence:

• Diagnostics and stale-port handling from fix(worker): detect stale/orphaned port socket on startup and fail with actionable guidance #3112, fix: use configured worker host in HealthMonitor instead of hardcoded 127.0.0.1 #2998, fix: improve Windows multi-window stability with zombie worker recovery (#2996) #3009, fix worker restart port cleanup on Windows #2980, fix(worker): detect real port occupation cross-platform and reclaim stale workers #2895.
• Hook watchdog/fail-open behavior from fix(bun-runner): bound hook invocations so a wedged worker can't block the prompt #3099, fix(launcher): exit 0 on signal-kill for hook event subcommands (addresses #2823) #2889, fix: never block Claude Code harness on worker outages #2892, fix(hooks): cap summarize Stop-hook retry loop with per-session disabled sentinel (closes #2846) #2885.
• Worker script override/root unification from feat(worker): add CLAUDE_MEM_WORKER_SCRIPT_PATH to pin the worker bundle #3055.
• Removal of stale worker CLI surfaces from fix: remove stale plugin/scripts/worker-cli.js (regressed #2747/#2891 "Process died during startup") #2937 where that reduces ambiguity.

Stable reading:

• src/build/hook-shell-template.ts is the canonical generated shell resolver for hooks/MCP, but src/shared/worker-utils.ts has its own worker script resolution path. The stable branch should make resolution deterministic without introducing a new service manager.
• Windows port cleanup should not wait for a long cooldown when the port owner is stale, dead, or the previous version.

Hook and platform contracts

Symptoms:

• Codex App on Windows can execute hook commands through PowerShell and fail on POSIX shell syntax: Windows Codex App executes codex-hooks.json POSIX commands with PowerShell, causing ParserError #3101, Codex plugin hooks on Windows need commandWindows overrides #3075, 启用了 claude-mem 的 Codex hook，但它的 PostToolUse hook 输出了当前 Codex 不支持的字段 #2871.
• Codex JSON output has had unsupported fields such as suppressOutput: tracking: Codex PostToolUse hook emits unsupported suppressOutput field — hook rejected on every tool call #2975.
• Platform hook setup can break for version checks, Windows shell availability, npm/npx shell behavior, or command-window flashing: [Windows] Plugin hooks spawn visible console windows on every tool call #3069, tracking: OpenCode plugin captures nothing — dead hook names, un-awaited POSTs, and invalid export shape #2968, tracking: Windows console window flashes on every hook/tool-use — missing windowsHide and cmd.exe wrappers in spawn paths #2965, tracking: DEP0190 (shell:true + args) and bash PATH probe regressions in npx-cli bundle and hook scripts #2962, Windows: worker daemon flashes a console window on every observation/summarize (claude.cmd spawned via cmd.exe) #2946, DEP0190 still reproducible on 13.6.1 (regression of #1503 / #438 / #433): args + shell in the npx-cli bundle #2941, 每次对话，或是回答，就会有一些窗口一闪而过非常快，经常会被晃到不舒服，影响使用体验； #2913, [Windows] Hook execution flashes black console window on every tool use #2869, opencode plugin loading error: "Plugin export is not a function" #2854, OpenCode plugin loads but captures nothing on opencode 1.16.2 (dead chat.message hook + un-awaited POSTs) #2832.

Patch evidence:

• Codex SessionStart/version JSON from fix(codex): emit SessionStart JSON from version check #2692.
• Windows hook command fixes from fix: install Windows Claude Code hooks without bash #2945, fix(windows): hide cmd window in where bun spawnSync (findBun) #2944, fix: bypass cmd.exe when spawning .cmd files to prevent console window flash #2997, fix(windows): carry windowsHide through the remaining live Windows spawn paths (closes #2900) #2921.
• npx/DEP0190 shell fix from fix(installer): drop shell:IS_WINDOWS from version-probe spawns to silence DEP0190 on Node 22 (closes #2941) #3046.
• OpenCode compatibility/capture fixes from fix(opencode): full OpenCode v1.17.8 plugin compatibility #3014, fix(hooks): restore OpenCode capture on the current plugin hook contract (closes #2832) #2855, fix(opencode-plugin): add platformSource identifier to all observations #2936.
• Runtime tool visibility fix from fix(mcp): hide server-beta-only tools from worker-runtime tools/list (closes #3064) #3065.

Stable reading:

• src/cli/adapters/index.ts declares supported adapters: claude-code, codex, cursor, windsurf, antigravity, antigravity-cli, and raw.
• OpenCode support in current main is plugin/capture-oriented rather than a full CLI adapter; stable work should keep that supported path working without inventing a new adapter.
• Generated hook files must be regenerated from src/build/hook-shell-template.ts and verified by scripts/build-hooks.js; do not hand-edit generated command strings.

Chroma, semantic search, MCP, and smart explore

Symptoms:

• Chroma/search can fail because of startup, uvx invocation, or packaging gaps: v13.9.1: observation → Chroma vector sync fails on every observation (summaries/prompts unaffected) #3091, Semantic injection always returns empty: project-filter mismatch between Chroma sync and /api/context/semantic #2979, tracking: chroma-mcp spawn fails with MCP -32000 — uvx version syntax errors and Windows cmd.exe redirection mangling #2961, tracking: chroma-mcp subprocess leak — zombie uv+python process pairs accumulate due to silent kill failures and orphan socket inheritance #2959, Windows: Chroma spawn routes >/< dependency specifiers through cmd.exe /c, breaking semantic search (Connection closed -> FTS5 fallback) #2954, chroma-mcp subprocess leak on macOS — zombie uv+python3.13 process pairs accumulate across sessions #2950, chroma-mcp== version pinning breaks uvx — use @ instead of == (MCP error -32000) #2939, Chroma semantic search never connects with uv < 0.5.31 — bare uvx <pkg>==<ver> positional rejected → MCP -32000 Connection closed (repro: macOS) #2879.
• Runtime can advertise server-beta-only MCP tools in worker mode: Server-beta-only tools (e.g. observation_search) advertised in tools/list under worker runtime — agents call a non-functional tool; under Codex the call hangs the client #3064.
• smart-explore needs consistent tree-sitter runtime availability: v13.5.6: smart_search/smart_outline/smart_unfold return 0 symbols on clean Windows install - tree-sitter-cli binary never downloaded (--ignore-scripts), #1247's extensionless existsSync check still unfixed #2910, tracking: plugin runtime deps missing in distributed bundles — zod external, tree-sitter-cli not downloaded, hooks crash #2964.
• Search/project filtering can go empty when project identity is wrong or filtering is too strict: Runaway ChromaDB growth to 157 GB filled disk to 99% and caused kernel panics; dual chroma-mcp writers on same data dir; auto-reinstalls after uninstall #3012, chroma-mcp children pin port after hook-parent exit, blocking respawn #2907, chroma-mcp 30s connect timeout kills uvx mid-install, causing infinite retry loop that leaked ~111GB of uv temp files (macOS) #2897, chroma-mcp subprocess leak: unbounded process accumulation via reconnection loop #2896.

Patch evidence:

• Chroma uvx command and singleton/prewarm fixes from fix: use @ instead of == for chroma-mcp version pinning with uvx #2940, fix(chroma): spawn chroma-mcp via --from so uv < 0.5.31 works #2880, fix(chroma): prewarm uvx installs before the MCP connect deadline (closes #2897) #2920.
• Server/worker MCP tool visibility from fix(mcp): hide server-beta-only tools from worker-runtime tools/list (closes #3064) #3065.
• smart-explore provisioning from fix(install): repair smart-explore runtime provisioning across IDEs #3095.
• Semantic project filter fallback from fix(context): recover semantic injection when scoped Chroma metadata misses matches (closes #2979) #3011 if current-main behavior still reproduces the issue.

Stable reading:

• Current src/services/sync/ChromaMcpManager.ts already uses direct uvx --from chroma-mcp==0.2.6 chroma-mcp and StdioClientTransport; preserve that patch shape.
• Do not replace Chroma or MCP transport as part of the stable build.

Observer, provider env, and prompt safety

Symptoms:

• Observer/proactive memory generation can poison transcripts, persist synthetic messages, or treat benign prose/no-op output as invalid: Headless observation generator inherits interactive plugin hooks → a third-party SessionStart hook (superpowers) hijacks generation → empty response, no observations stored #3074, tracking: observer hook spawns accumulate unlimited .jsonl transcript files and mix cross-session context #2976, tracking: observer poison loop — skip-prose counted as invalid, triggering endless kill/respawn cycle #2960, SDK session poison-loop: generator emits prose "empty observation" instead of <skip_summary/>, triggering repeated kill/respawn #2955, Generator poison loop: prompt says 'return empty response' to skip, but parser only accepts <skip_summary/> — empty/prose replies poison the session #2935, 用cc switch 切换智谱模型后 只会记录问题不会记录回答 #2915, Observer silently drops observations on "Prompt is too long" — strip image/base64 payloads before sending to the model #2866, v13.4.0 (Linux): observer still poison-loops on prose-empty responses despite plan-11 recovery — root cause (#2749 expected behavior) not addressed #2817.
• Large base64/tool payloads and unbounded context can overflow provider limits: tracking: Claude provider observer overflows context window — no bound on history size, zero memory saved on long sessions #2958, Claude provider (SDKAgent) has no context bound — observer overflows with "Prompt is too long" and saves zero memory on long sessions #2956.
• Env sanitizer removes proxy and provider skip-auth variables needed in real enterprise/provider setups: Bug: ENV_PROXY_VARS stripped instead of preserved in sanitizeEnv() #2999, Bug: CLAUDE_CODE_SKIP_BEDROCK_AUTH (and CLAUDE_CODE_SKIP_VERTEX_AUTH) stripped from SDK subprocess env — SDK hangs / 401s for Bedrock-routed gateways with Bearer auth #3053.
• Tool allow/deny coverage should include newer tool names: [Bug] subscription/cli auth: SDK returns 'Failed to authenticate. API Error: 403' on clean install, isolated to worker's live session (not reproducible manually) #3105.

Patch evidence:

• Env preservation from Preserve proxy variables during environment sanitization #3018 and fix(supervisor): preserve Bedrock and Vertex skip-auth flags in SDK env (closes #3053) #3060.
• Observer isolation/no transcript persistence from fix(observer): disable observer transcript persistence for tool-use queries #2942.
• Payload stripping/context bounding from fix(observer): strip base64 image blobs from tool payloads before building observer prompt (closes #2866) #2884 and fix(sdk): bound Claude provider observer context to prevent overflow (#2956) #2957.
• Benign no-op/prose handling from fix(observer): accept prose-empty acknowledgements without poison respawn (closes #2817) #2857, fix(worker): stop respawning sessions on benign "nothing to record" output #2943, fix(sdk): break observer respawn loop on haiku skip-prose #2927, fix(observer): harden non-Claude observation flow #2905, Avoid no-op SDK respawns #2901.
• Deny-list expansion from fix(security): add Skill/Workflow/SlashCommand/ExitPlanMode to Observer deny-list #3136.

Stable reading:

• Current src/services/worker/agents/ResponseProcessor.ts already treats benign non-XML/no-op output as valid; verify and avoid reworking it.
• Current src/supervisor/env-sanitizer.ts still appears to strip proxy variables and omits CLAUDE_CODE_SKIP_BEDROCK_AUTH / CLAUDE_CODE_SKIP_VERTEX_AUTH; this is a low-risk stable backport because it preserves caller-provided env rather than adding new behavior.

Settings, storage, migration, and project identity

Symptoms:

• Settings JSON can truncate or reset on transient read/write failures: bug: ~/.claude-mem/settings.json truncated to one key under concurrent hooks (non-atomic writes + reset-to-empty on parse failure) #3080.
• BOM handling is inconsistent across JSON readers: Windows: settings.json written with UTF-8 BOM causes JSON parse failure on every hook #3013.
• Schema migration order can fail for older DBs, especially v23 to v35 with platform_source: [upgrade] Direct schema v23 → v35 fails: worker background-init throws no such column: platform_source #3118, Upgrade to v13.9.1 from an older DB leaves migrations v24-v35 unapplied → worker init fails with "no such column: platform_source" and stays "healthy but not ready" (blocks Claude Code) #3094.
• SQLite can hit lock/bloat behavior under normal use: tracking: SQLite data integrity — unbounded prompt bloat (no cap/retention/VACUUM) and busy_timeout=0 drops writes under contention #2969, Worker drops observations under lock contention (busy_timeout=0 → 500 "database is locked") #2821, Database grows unbounded: prompt_text stored verbatim (×2), no retention, no VACUUM #2793.
• Project/session identity can collapse across worktrees, monorepo subdirs, and submodules: tracking: project name detection resolves wrong directory in monorepos, worktrees, and submodules #2967, Project detection uses git root instead of working directory, causing issues in monorepos/subdirectories #2882, Worktree observations orphaned by one-shot .cwd-remap-applied-v1 migration; unreachable after the worktree is removed (v13.3.0) #2864, Submodule cwd resolves to empty leaf project — "no memory yet" despite parent repo history #2842.

Patch evidence:

• BOM/read-side fixes from fix(windows): strip UTF-8 BOM in all settings.json readers (#3013) #3033.
• SQLite busy_timeout from fix(sqlite): apply busy_timeout to primary SQLite connections (closes #2821) #2849.
• Project key fixes from fix(sqlite): make cwd-remap reconciliation idempotent to fix orphaned worktree observations (closes #2864) #2883, fix(context): use repo-relative project keys for monorepo subdirectories (closes #2882) #3047, fix(context): fold submodule cwd sessions into the parent repo memory (closes #2842) #2856.
• Broader retention/VACUUM work in fix(sqlite): reclaim residual prompt and queue bloat (refs #2793) #2904 should only be taken if it can be reduced to a narrow, low-risk storage maintenance patch.

Stable reading:

• SettingsDefaultsManager strips BOM in one reader but uses direct writes for defaults/migrations; stable should use the existing atomic JSON writer pattern where applicable.
• src/utils/project-name.ts and src/utils/worktree.ts should get minimal identity fixes, not a new project model.

Explicitly Out Of Scope

• New roadmap/provider/platform capabilities: [plan-12] Provider & Extensibility Roadmap — net-new capabilities, not defects #2785, feat: add Amazon Kiro CLI platform support (hooks, MCP, skills, insta… #3125, Add Codex CLI provider #3093, feat(openrouter): add CLAUDE_MEM_OPENROUTER_EXTRA_BODY for provider-specific request parameters #3040, feat(integrations): add Antigravity CLI hooks support #3000, Feat/mysql support #2949, feat: add Kimi Code CLI support #2908, Add native Hermes Agent integration #2825, feat(context): add opt-in Mermaid task-flow diagram for token-efficient context injection #2777, feat(provider): add Gemini CLI as a headless observation provider #2764, feat: add Vertex AI support for Gemini provider (gemini-3.1-flash-lite default) #2523.
• Large storage redesigns, new databases, or data-model rewrites.
• New daemon/supervisor architecture, socket protocol rewrite, or per-IDE worker model.
• UX redesigns, new memory ranking strategy, or feature flags unrelated to restoring intended stable behavior.

Documentation Discovery / Allowed APIs

Use only documented/local contracts below unless a failing test proves a narrower patch is required.

• Worker HTTP base and env contract: docs/public/platform-integration.mdx:13, docs/public/platform-integration.mdx:23, docs/public/platform-integration.mdx:48.
• Worker session/event/search/context APIs: docs/public/platform-integration.mdx:148, docs/public/platform-integration.mdx:354, docs/public/platform-integration.mdx:475.
• Health and SSE APIs: docs/public/platform-integration.mdx:532.
• Hook lifecycle and Claude Code hookSpecificOutput.additionalContext: docs/public/hooks-architecture.mdx:30, docs/public/hooks-architecture.mdx:117, docs/public/hooks-architecture.mdx:264.
• Hook timing and fail-open design: docs/public/hooks-architecture.mdx:422, docs/public/hooks-architecture.mdx:521.
• Cursor hook names, config, inputs, and outputs: docs/context/cursor-hooks-reference.md:16, docs/context/cursor-hooks-reference.md:239, docs/context/cursor-hooks-reference.md:328, docs/context/cursor-hooks-reference.md:356, docs/context/cursor-hooks-reference.md:425, docs/context/cursor-hooks-reference.md:494.
• OpenClaw lifecycle and context/SSE integration: docs/public/openclaw-integration.mdx:21, docs/public/openclaw-integration.mdx:40, docs/public/openclaw-integration.mdx:64.
• Adapter contracts: src/cli/types.ts:1, src/cli/adapters/index.ts:9, src/cli/adapters/claude-code.ts:8, src/cli/adapters/codex.ts:5, src/cli/adapters/cursor.ts:18, src/cli/adapters/windsurf.ts:4, src/cli/adapters/antigravity-cli.ts:4.
• Canonical generated hook command resolver: src/build/hook-shell-template.ts:1, src/build/hook-shell-template.ts:61, src/build/hook-shell-template.ts:111, src/build/hook-shell-template.ts:163, src/build/hook-shell-template.ts:217.
• Build/generation verification: scripts/build-hooks.js:57, scripts/build-hooks.js:138, scripts/build-hooks.js:287, scripts/build-hooks.js:606.
• Worker lifecycle/root APIs: src/shared/worker-utils.ts:126, src/shared/worker-utils.ts:207, src/services/worker-spawner.ts:69, src/services/infrastructure/HealthMonitor.ts:8.
• Runtime selector/server client API boundary: src/services/hooks/runtime-selector.ts:39, src/services/hooks/server-client.ts:57.
• Chroma MCP API boundary: src/services/sync/ChromaMcpManager.ts:31, src/services/sync/ChromaMcpManager.ts:127, src/services/sync/ChromaMcpManager.ts:167, src/services/sync/ChromaMcpManager.ts:265, src/services/sync/ChromaMcpManager.ts:395.
• Settings/storage/project APIs: src/shared/SettingsDefaultsManager.ts:197, src/utils/json-utils.ts:5, src/utils/project-name.ts:21, src/utils/worktree.ts:20.

Allowed API changes:

• Add missing generated/package outputs needed by the existing worker.
• Add env-preservation keys and tests to the existing sanitizer.
• Add narrow project-key/worktree/submodule cases to existing utilities.
• Add deterministic worker script override/root resolution using existing env/config hooks.
• Add health/port stale-owner diagnostics and cleanup within existing worker-spawner/HealthMonitor.
• Add generated hook command variants required by documented host shells.

Disallowed API changes:

• Do not change documented worker HTTP endpoints.
• Do not change adapter NormalizedHookInput, HookResult, or platform output schemas unless the host contract currently rejects the output.
• Do not add server-only MCP tools to worker runtime.
• Do not make hooks depend on network, Chroma, or observer success before returning control to the host.

Phased Fix Sequence

Phase 0 - Reproduce and pin stable gates

1. Create branch plan/stable-working-build from current main.
2. Capture a failing baseline for the smallest representative cases:
   • Clean package install with no source tree: Backfill crashes on missing module '../sqlite/observations/files.js'; search query param ignored (v13.10.0, v13.9.3) #3126, Chroma vector sync broken on 13.9.x: worker-service.cjs requires ../sqlite/*.js which the build never emits #3107, v13.9.1: two more missing-bundle modules — SessionStore.js (backfill fails at startup) + .install-version marker ("runtime not yet set up") #3092.
   • Codex App Windows hook startup: Windows Codex App executes codex-hooks.json POSIX commands with PowerShell, causing ParserError #3101, Codex plugin hooks on Windows need commandWindows overrides #3075.
   • Worker duplicate root or stale port: Linux: worker path resolves to different on-disk copies across invocation contexts (marketplace checkout vs version cache) → two concurrent daemons, one unsupervised orphan; stale cache versions never GC'd #3134, Windows: version-mismatch recycle orphans children (chroma-mcp) that inherit the listening socket — port stays bound under a dead PID, blocking all respawns for hours #3128, Windows: failed worker recycle on version bump leaves a zombie process holding port 37777; stale supervisor.json PID then blocks every respawn #3031.
   • Chroma/search after clean install: v13.9.1: observation → Chroma vector sync fails on every observation (summaries/prompts unaffected) #3091, Semantic injection always returns empty: project-filter mismatch between Chroma sync and /api/context/semantic #2979.
   • Env sanitizer with proxy/Bedrock/Vertex skip auth: Bug: ENV_PROXY_VARS stripped instead of preserved in sanitizeEnv() #2999, Bug: CLAUDE_CODE_SKIP_BEDROCK_AUTH (and CLAUDE_CODE_SKIP_VERTEX_AUTH) stripped from SDK subprocess env — SDK hangs / 401s for Bedrock-routed gateways with Bearer auth #3053.
   • Settings write/read interruption and BOM parse: bug: ~/.claude-mem/settings.json truncated to one key under concurrent hooks (non-atomic writes + reset-to-empty on parse failure) #3080, Windows: settings.json written with UTF-8 BOM causes JSON parse failure on every hook #3013.
3. Add or update regression tests first when a small test can capture the stable contract.

Exit criteria:

• Every later patch maps to a failing test, a clean-install package assertion, or a documented host contract.

Phase 1 - Fix package completeness before runtime behavior

Apply the minimal patch shape from #3108 first. Ensure package/build outputs include the plugin/sqlite runtime modules required by the worker and that generated package contents are verified in CI.

Then apply only the necessary runtime dependency packaging from #2887, #2710, #2531, #3095, #3113, #3006, and #3061.

Verification:

• npm run build
• Package/tarball inspection proves these exist without the source tree:
  • plugin/dist/worker.js
  • required plugin/sqlite/** runtime modules
  • hook configs under plugin/hooks/**
  • plugin/runtime dependencies required by worker, Chroma, and smart-explore
• Clean-room smoke install runs a SessionStart hook without MODULE_NOT_FOUND.
• Regression coverage includes Backfill crashes on missing module '../sqlite/observations/files.js'; search query param ignored (v13.10.0, v13.9.3) #3126, Chroma vector sync broken on 13.9.x: worker-service.cjs requires ../sqlite/*.js which the build never emits #3107, v13.9.1: two more missing-bundle modules — SessionStore.js (backfill fails at startup) + .install-version marker ("runtime not yet set up") #3092, fix(build): bundle zod into worker-service.cjs to survive node_modules churn (closes #2831) #2887, v13.5.6: smart_search/smart_outline/smart_unfold return 0 symbols on clean Windows install - tree-sitter-cli binary never downloaded (--ignore-scripts), #1247's extensionless existsSync check still unfixed #2910.

Do not proceed to hook/lifecycle fixes until a clean package can load the worker.

Phase 2 - Make hook IO host-valid and fail-open

Patch generated hook command/output contracts with the smallest host-specific changes:

• Codex: preserve valid SessionStart/UserPromptSubmit/PostToolUse/Stop output; ensure suppressOutput is absent; handle Windows App shell execution (Windows Codex App executes codex-hooks.json POSIX commands with PowerShell, causing ParserError #3101, tracking: Codex PostToolUse hook emits unsupported suppressOutput field — hook rejected on every tool call #2975, 启用了 claude-mem 的 Codex hook，但它的 PostToolUse hook 输出了当前 Codex 不支持的字段 #2871).
• Claude Code: preserve hookSpecificOutput.additionalContext and fail-open semantics.
• Cursor/Windsurf/Antigravity/OpenCode capture: keep current adapter shapes and only patch documented incompatibilities.
• Ensure all optional memory/observer/search failures return host-safe success unless the hook is intentionally blocking for a documented reason.

Patch sources:

• fix(codex): emit SessionStart JSON from version check #2692, fix: install Windows Claude Code hooks without bash #2945, fix(windows): hide cmd window in where bun spawnSync (findBun) #2944, fix(installer): drop shell:IS_WINDOWS from version-probe spawns to silence DEP0190 on Node 22 (closes #2941) #3046, fix: bypass cmd.exe when spawning .cmd files to prevent console window flash #2997, fix(windows): carry windowsHide through the remaining live Windows spawn paths (closes #2900) #2921, fix(opencode): full OpenCode v1.17.8 plugin compatibility #3014, fix(hooks): restore OpenCode capture on the current plugin hook contract (closes #2832) #2855, fix(opencode-plugin): add platformSource identifier to all observations #2936, fix(mcp): hide server-beta-only tools from worker-runtime tools/list (closes #3064) #3065, fix(bun-runner): bound hook invocations so a wedged worker can't block the prompt #3099, fix(launcher): exit 0 on signal-kill for hook event subcommands (addresses #2823) #2889.

Verification:

• scripts/build-hooks.js generated-file verification passes.
• Codex hook JSON validates against allowed event keys from scripts/build-hooks.js.
• Unit tests cover adapter output for Claude Code, Codex, Cursor, Windsurf, and Antigravity.
• Windows command tests prove hooks do not require POSIX shell under Codex App/PowerShell.
• Hook watchdog tests prove no observer/worker timeout blocks normal prompt submission.

Phase 3 - Unify worker root, singleton, health, and stale-port recovery

Patch existing worker resolution/lifecycle code rather than adding a new process manager:

• Reconcile hook resolver and resolveWorkerScriptPath so marketplace/cache/source launches converge on one deterministic worker identity (Linux: worker path resolves to different on-disk copies across invocation contexts (marketplace checkout vs version cache) → two concurrent daemons, one unsupervised orphan; stale cache versions never GC'd #3134).
• Add or use CLAUDE_MEM_WORKER_SCRIPT_PATH only as a controlled override/testability hook (feat(worker): add CLAUDE_MEM_WORKER_SCRIPT_PATH to pin the worker bundle #3055).
• Treat stale/dead PID and previous-version port owners as recoverable with diagnostics (Windows: version-mismatch recycle orphans children (chroma-mcp) that inherit the listening socket — port stays bound under a dead PID, blocking all respawns for hours #3128, Windows: failed worker recycle on version bump leaves a zombie process holding port 37777; stale supervisor.json PID then blocks every respawn #3031, Windows: stale port holder + aggressive spawn cooldown blocks prompts for ~15 min (fail-loud threshold 3 too low) #2996, Worker never starts on Windows — port 37777 held by orphaned process; UserPromptSubmit hook fails in a loop and blocks prompts #2926, [Windows] Plugin update orphans the worker port (ghost LISTENING socket), blocking all Claude Code prompts with no graceful recovery #2899, [Windows] Zombie-port killer (#1721) misses orphaned children holding the inherited socket — repro on 13.5.5 via version-mismatch recycle #2893).
• Use configured host consistently in health checks (fix: use configured worker host in HealthMonitor instead of hardcoded 127.0.0.1 #2998).
• Avoid long Windows cooldown when the port holder is provably stale (fix(worker): detect stale/orphaned port socket on startup and fail with actionable guidance #3112, fix: improve Windows multi-window stability with zombie worker recovery (#2996) #3009, fix worker restart port cleanup on Windows #2980, fix(worker): detect real port occupation cross-platform and reclaim stale workers #2895).
• Keep hook-facing behavior fail-open (fix: never block Claude Code harness on worker outages #2892, fix(launcher): exit 0 on signal-kill for hook event subcommands (addresses #2823) #2889, fix(hooks): cap summarize Stop-hook retry loop with per-session disabled sentinel (closes #2846) #2885).

Verification:

• Worker launch from marketplace and cache paths produces one healthy daemon, not two.
• Concurrent SessionStart hooks race to one worker.
• Windows stale-socket fixture recovers without waiting for an arbitrary cooldown.
• Worker restart/version-recycle tests prove child processes do not keep the listening socket alive after shutdown.
• Existing worker-spawner, process-registry, supervisor, and health-monitor tests pass.

Phase 4 - Restore Chroma, search, MCP, and smart-explore under the stable package

After packaging and worker lifecycle are stable, verify current Chroma patches and backport only missing deltas:

• Preserve direct uvx --from chroma-mcp==0.2.6 chroma-mcp execution and StdioClientTransport (fix: use @ instead of == for chroma-mcp version pinning with uvx #2940, fix(chroma): spawn chroma-mcp via --from so uv < 0.5.31 works #2880).
• Keep Chroma singleton/prewarm behavior narrow and non-blocking (fix(chroma): prewarm uvx installs before the MCP connect deadline (closes #2897) #2920).
• Ensure the clean package contains any sqlite/runtime modules Chroma path requires (fix(build): emit plugin/sqlite runtime modules required by worker-service #3108).
• Hide server-beta-only MCP tools from worker runtime (Server-beta-only tools (e.g. observation_search) advertised in tools/list under worker runtime — agents call a non-functional tool; under Codex the call hangs the client #3064, fix(mcp): hide server-beta-only tools from worker-runtime tools/list (closes #3064) #3065).
• Add semantic project-filter fallback only if current main still reproduces empty search for valid memories (fix(context): recover semantic injection when scoped Chroma metadata misses matches (closes #2979) #3011).
• Ensure smart-explore tree-sitter runtime exists in packaged installs (fix(install): repair smart-explore runtime provisioning across IDEs #3095, v13.5.6: smart_search/smart_outline/smart_unfold return 0 symbols on clean Windows install - tree-sitter-cli binary never downloaded (--ignore-scripts), #1247's extensionless existsSync check still unfixed #2910, tracking: plugin runtime deps missing in distributed bundles — zod external, tree-sitter-cli not downloaded, hooks crash #2964).

Verification:

• MCP tool schema/list tests prove worker runtime does not expose server-only tools.
• Chroma MCP manager tests cover singleton, uvx args, Windows shell avoidance, SSL/env, prewarm cleanup.
• Semantic search smoke:
  • record observation
  • summarize/store
  • search same project
  • search after worker restart
• smart-explore smoke runs from a clean package with no global tree-sitter install.

Phase 5 - Harden observer/provider env without transcript side effects

Patch only stable correctness defects:

• Preserve proxy variables and provider skip-auth variables in isolated SDK env (Bug: ENV_PROXY_VARS stripped instead of preserved in sanitizeEnv() #2999, Bug: CLAUDE_CODE_SKIP_BEDROCK_AUTH (and CLAUDE_CODE_SKIP_VERTEX_AUTH) stripped from SDK subprocess env — SDK hangs / 401s for Bedrock-routed gateways with Bearer auth #3053, Preserve proxy variables during environment sanitization #3018, fix(supervisor): preserve Bedrock and Vertex skip-auth flags in SDK env (closes #3053) #3060).
• Keep generated observer messages out of the user transcript/session log (Headless observation generator inherits interactive plugin hooks → a third-party SessionStart hook (superpowers) hijacks generation → empty response, no observations stored #3074, fix(observer): disable observer transcript persistence for tool-use queries #2942).
• Keep benign no-op/prose output valid; do not rework the parser if current main already passes (tracking: observer poison loop — skip-prose counted as invalid, triggering endless kill/respawn cycle #2960, SDK session poison-loop: generator emits prose "empty observation" instead of <skip_summary/>, triggering repeated kill/respawn #2955, Generator poison loop: prompt says 'return empty response' to skip, but parser only accepts <skip_summary/> — empty/prose replies poison the session #2935, v13.4.0 (Linux): observer still poison-loops on prose-empty responses despite plan-11 recovery — root cause (#2749 expected behavior) not addressed #2817, fix(observer): accept prose-empty acknowledgements without poison respawn (closes #2817) #2857, fix(worker): stop respawning sessions on benign "nothing to record" output #2943, fix(sdk): break observer respawn loop on haiku skip-prose #2927, fix(observer): harden non-Claude observation flow #2905, Avoid no-op SDK respawns #2901).
• Strip or bound large base64/tool payloads before provider calls (tracking: Claude provider observer overflows context window — no bound on history size, zero memory saved on long sessions #2958, Claude provider (SDKAgent) has no context bound — observer overflows with "Prompt is too long" and saves zero memory on long sessions #2956, fix(observer): strip base64 image blobs from tool payloads before building observer prompt (closes #2866) #2884, fix(sdk): bound Claude provider observer context to prevent overflow (#2956) #2957).
• Extend observer deny-list for newer tools only ([Bug] subscription/cli auth: SDK returns 'Failed to authenticate. API Error: 403' on clean install, isolated to worker's live session (not reproducible manually) #3105, fix(security): add Skill/Workflow/SlashCommand/ExitPlanMode to Observer deny-list #3136).

Verification:

• Env sanitizer tests show proxy vars, Bedrock skip-auth, and Vertex skip-auth survive; unrelated CLAUDE_CODE_* control vars remain stripped.
• Observer tests prove no synthetic assistant/user messages are persisted.
• Response processor tests include empty/no-op/prose, malformed XML, and valid memory XML.
• Provider tests include large image/base64 transcript inputs and bounded history.
• Security/tool-enforcement tests include Skill, Workflow, SlashCommand, and ExitPlanMode.

Phase 6 - Make settings, storage, migrations, and project identity safe

Patch narrowly:

• Use atomic JSON writes for settings/default migrations where the repo already has an atomic writer pattern (bug: ~/.claude-mem/settings.json truncated to one key under concurrent hooks (non-atomic writes + reset-to-empty on parse failure) #3080).
• Strip BOM in shared JSON readers, not only one settings path (Windows: settings.json written with UTF-8 BOM causes JSON parse failure on every hook #3013, fix(windows): strip UTF-8 BOM in all settings.json readers (#3013) #3033).
• Add migration-order smoke for old DBs including v23 to v35 platform_source ([upgrade] Direct schema v23 → v35 fails: worker background-init throws no such column: platform_source #3118, Upgrade to v13.9.1 from an older DB leaves migrations v24-v35 unapplied → worker init fails with "no such column: platform_source" and stays "healthy but not ready" (blocks Claude Code) #3094).
• Add SQLite busy_timeout as a low-risk lock mitigation (tracking: SQLite data integrity — unbounded prompt bloat (no cap/retention/VACUUM) and busy_timeout=0 drops writes under contention #2969, fix(sqlite): apply busy_timeout to primary SQLite connections (closes #2821) #2849).
• Add minimal project identity fixes for worktrees, monorepo subdirs, and submodules (tracking: project name detection resolves wrong directory in monorepos, worktrees, and submodules #2967, Project detection uses git root instead of working directory, causing issues in monorepos/subdirectories #2882, Worktree observations orphaned by one-shot .cwd-remap-applied-v1 migration; unreachable after the worktree is removed (v13.3.0) #2864, Submodule cwd resolves to empty leaf project — "no memory yet" despite parent repo history #2842, fix(sqlite): make cwd-remap reconciliation idempotent to fix orphaned worktree observations (closes #2864) #2883, fix(context): use repo-relative project keys for monorepo subdirectories (closes #2882) #3047, fix(context): fold submodule cwd sessions into the parent repo memory (closes #2842) #2856).

Verification:

• Settings tests simulate interrupted write/read and prove existing valid settings are not reset to defaults.
• JSON utility tests cover BOM with objects/arrays.
• Migration tests run from historical fixture DBs through current schema.
• SQLite tests cover busy timeout configuration without changing retention policy.
• Project-name/worktree tests distinguish:
  • main repo
  • git worktree
  • nested monorepo package
  • git submodule

Phase 7 - Cross-platform smoke and release gate

Run final matrix before marking the stable branch ready:

• Clean install from package/tarball, not repo source.
• First launch, second launch, worker restart, and package-version recycle.
• SessionStart context injection, UserPromptSubmit observation, PostToolUse observation, Stop summarization.
• MCP search and Chroma semantic retrieval.
• smart-explore invocation.
• Settings read/write and old-DB migration.
• Provider env passthrough for proxy, Bedrock, and Vertex.

Exit criteria:

• All stable issues named in this plan either have a direct closing patch or are explicitly marked "covered by stable verification" in the PR description.
• No feature-roadmap issue/PR from the out-of-scope list is merged as part of the branch.

Verification Matrix

Area	macOS arm64	Linux x64	Windows 10/11 PowerShell	Windows Git Bash / Claude Desktop	WSL2
Clean package install	tarball install, no source tree	tarball install, no source tree	npm/bun path with spaces	Claude Desktop extension path	install from Linux filesystem
Worker lifecycle	first launch, restart, duplicate root	marketplace/cache root convergence	stale port, version recycle, hidden windows	no POSIX dependency where host shell is PowerShell	host/port env consistency
Claude Code	SessionStart, UserPromptSubmit, PostToolUse, Stop	same	hook output JSON and fail-open	desktop extension hook path	same
Codex CLI/App	SessionStart context, PostToolUse	same	PowerShell-safe command, no suppressOutput	Git Bash fallback if present	same
Cursor Agent/Tab	beforeSubmitPrompt, afterFileEdit	same	path escaping and transcript handling	n/a	same
Windsurf	prompt/write/command/MCP/cascade events	same	path escaping	n/a	same
Antigravity CLI	env/cwd/session mapping	same	env/cwd/session mapping	n/a	same
OpenCode capture	supported capture/plugin path only	supported capture/plugin path only	supported capture/plugin path only	n/a	same
OpenClaw	documented event endpoints/SSE	documented event endpoints/SSE	documented event endpoints/SSE	n/a	same
Chroma/search	uvx direct, restart search	uvx direct, restart search	uvx without cmd shell, cleanup	same	same
smart-explore	packaged tree-sitter runtime	packaged tree-sitter runtime	packaged tree-sitter runtime	same	same
Settings/storage	atomic write, BOM, migration	atomic write, BOM, migration	atomic write, BOM, migration	same	same

Minimum command/test gate:

• npm run build
• generated hook verification from scripts/build-hooks.js
• package/tarball content check
• clean-room install smoke
• adapter/hook contract tests
• worker-spawner/health/process-registry tests
• Chroma/MCP/smart-explore tests
• env-sanitizer/provider/observer tests
• settings/json/storage/project identity tests

Anti-pattern Guards

• No second-system rewrite: do not introduce a new daemon architecture, queue system, storage engine, RPC protocol, or provider abstraction to fix these issues.
• No hand-edited generated hooks: update templates/build inputs, then regenerate and verify.
• No shell: true plus args for subprocess fixes unless a platform contract requires it and a test proves the exact behavior.
• No cmd.exe workaround for uvx/Chroma if direct executable resolution works.
• No hook may block the host because memory/search/observer/Chroma is unavailable.
• No source-tree-only fixes: package/tarball verification must prove clean installs work.
• No server-only MCP tools in worker runtime.
• No settings reset on parse/write errors; preserve user data and fail with a recoverable diagnostic.
• No deletion of user memory to address DB bloat; limit stable scope to busy timeout and safe migration unless a narrow retention patch is separately verified.
• No broad platform additions or provider integrations in this branch.
• No behavior changes that require users to reconfigure existing Claude Code, Codex, Cursor, Windsurf, Antigravity, OpenCode, or OpenClaw setups.

PR Handling

• Mergeable stable candidates may be used directly after current-main review: fix(security): add Skill/Workflow/SlashCommand/ExitPlanMode to Observer deny-list #3136, fix(worker): detect stale/orphaned port socket on startup and fail with actionable guidance #3112, fix(build): emit plugin/sqlite runtime modules required by worker-service #3108, fix(bun-runner): bound hook invocations so a wedged worker can't block the prompt #3099, fix(install): repair smart-explore runtime provisioning across IDEs #3095, fix: avoid top-level await in bun-runner so hooks load on Node < 14.8 #3061, test(settings): isolate loadFromFile tests from all ambient default env keys #3058, feat(worker): add CLAUDE_MEM_WORKER_SCRIPT_PATH to pin the worker bundle #3055, Preserve proxy variables during environment sanitization #3018, fix: use configured worker host in HealthMonitor instead of hardcoded 127.0.0.1 #2998, fix: install Windows Claude Code hooks without bash #2945, fix(windows): hide cmd window in where bun spawnSync (findBun) #2944, fix(opencode-plugin): add platformSource identifier to all observations #2936, fix(launcher): exit 0 on signal-kill for hook event subcommands (addresses #2823) #2889, fix(build): bundle zod into worker-service.cjs to survive node_modules churn (closes #2831) #2887, fix(context): drop sub-day clock from injected headers to stop busting prefix cache (closes #2872) #2886, fix(observer): strip base64 image blobs from tool payloads before building observer prompt (closes #2866) #2884, fix(context): fold submodule cwd sessions into the parent repo memory (closes #2842) #2856, fix(build): ship & harden plugin/node_modules so hooks resolve zod/v3 (#2379) #2710, fix(codex): emit SessionStart JSON from version check #2692, fix(packaging): bundle plugin/node_modules so marketplace install ships runtime deps (closes #2407) #2531.
• Conflicting PRs should be treated as patch evidence, not merged wholesale: fix: force reinstall on missing .install-version marker instead of nagging (#3092) #3113, fix: worker-service missing sqlite/SessionStore.js + observations/files.js (#3092) #3102, fix(mcp): hide server-beta-only tools from worker-runtime tools/list (closes #3064) #3065, fix(supervisor): preserve Bedrock and Vertex skip-auth flags in SDK env (closes #3053) #3060, fix(context): use repo-relative project keys for monorepo subdirectories (closes #2882) #3047, fix(installer): drop shell:IS_WINDOWS from version-probe spawns to silence DEP0190 on Node 22 (closes #2941) #3046, fix(windows): strip UTF-8 BOM in all settings.json readers (#3013) #3033, fix(opencode): full OpenCode v1.17.8 plugin compatibility #3014, fix(context): recover semantic injection when scoped Chroma metadata misses matches (closes #2979) #3011, fix: improve Windows multi-window stability with zombie worker recovery (#2996) #3009, fix worker restart port cleanup on Windows #2980, fix(sdk): bound Claude provider observer context to prevent overflow (#2956) #2957, fix(worker): stop respawning sessions on benign "nothing to record" output #2943, fix(observer): disable observer transcript persistence for tool-use queries #2942, fix: use @ instead of == for chroma-mcp version pinning with uvx #2940, fix: remove stale plugin/scripts/worker-cli.js (regressed #2747/#2891 "Process died during startup") #2937, fix(sdk): break observer respawn loop on haiku skip-prose #2927, fix(chroma): prewarm uvx installs before the MCP connect deadline (closes #2897) #2920, fix(setup): restore tree-sitter CLI on clean Windows installs (closes #2910) #2918, fix(context): avoid blocking Claude SessionStart on Windows cold boot (closes #2903) #2917, fix(observer): harden non-Claude observation flow #2905, fix(sqlite): reclaim residual prompt and queue bloat (refs #2793) #2904, Avoid no-op SDK respawns #2901, fix(worker): detect real port occupation cross-platform and reclaim stale workers #2895, fix: never block Claude Code harness on worker outages #2892, fix(hooks): cap summarize Stop-hook retry loop with per-session disabled sentinel (closes #2846) #2885, fix(sqlite): make cwd-remap reconciliation idempotent to fix orphaned worktree observations (closes #2864) #2883, fix(chroma): spawn chroma-mcp via --from so uv < 0.5.31 works #2880, fix(observer): accept prose-empty acknowledgements without poison respawn (closes #2817) #2857, fix(hooks): restore OpenCode capture on the current plugin hook contract (closes #2832) #2855, fix(sqlite): apply busy_timeout to primary SQLite connections (closes #2821) #2849.
• If two PRs solve the same defect, take the smaller patch that preserves current contracts and has the stronger regression test.

Done

The branch is ready when:

• Clean package installs exercise the full intended claude-mem path without source-tree dependencies.
• Supported IDE/platform hooks return host-valid output and fail open on optional memory failures.
• One worker owns the configured host/port and stale owner recovery is deterministic.
• Chroma, MCP search, semantic search, and smart-explore work after clean install and worker restart.
• Observer/provider paths preserve required env, bound prompt payloads, and do not mutate transcripts with synthetic messages.
• Settings/storage/migration/project identity tests pass without data loss.
• The verification matrix above is complete or each skipped cell has an explicit, documented reason.