fix: bug-batch — 17 issues + 4 foundations (chroma, opencode, parser, OAuth, paths, uptime, classification) (#2282)

* feat: foundations F1-F4 + simple bug fixes

Foundations (no consumer adoption yet):
- F1 spawnHidden wrapper at src/shared/spawn.ts
- F2 paths namespace with 18 accessors + invariant test (tests/shared/paths.test.ts)
- F3 getUptimeSeconds at src/shared/uptime.ts
- F4 ClassifiedProviderError at src/services/worker/provider-errors.ts + 6 tests

Issue fixes (file-isolated, parallel-safe):
- #2231: SECURITY.md at repo root for GitHub Security tab
- #2240: dedupe observationIds before Chroma sync (ResponseProcessor.ts)
- #2247: add task_complete to Codex session-end events
- #2243: rsync excludes scripts/package.json + scripts/node_modules

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: validate Claude executable with --version and detect desktop app

Extract findClaudeExecutable() into shared utility used by both
SDKAgent and KnowledgeAgent (deduplication). Every candidate is now
validated with --version (3s timeout). Desktop app executables in
AppData/Program Files get an actionable error message directing
users to install the CLI via npm.

Closes #2222

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: use Zod schemas in OpenCode plugin to fix _zod.def crash

OpenCode 1.14.x walks arg._zod.def at plugin registration, which
crashes on plain JSON Schema objects like {type: "string"}. Replace
with z.string().describe() so the Zod internals are present.

Closes #2226, #2225, #2154

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: neutralize chroma-mcp CPU storm at the root

Two surgical fixes to the chroma backfill path that together cause the
sustained 60–80% CPU + orphan accumulation pattern reported across

1. ChromaMcpManager.getSpawnEnv: cap embedding-thread fanout
   ONNX Runtime / OpenBLAS / MKL all default to cpu_count(), so a 12-core
   machine spins 12 threads burning embeddings concurrently. The user's
   getSpawnEnv only handled SSL certs — no thread limits at all. Inject
   OMP_NUM_THREADS / ONNX_NUM_THREADS / OPENBLAS_NUM_THREADS / MKL_NUM_THREADS
   defaults of 2 (only if user hasn't pinned them), and
   ANONYMIZED_TELEMETRY=false to stop background HTTP from the embedding
   subprocess. Closes the storm at the source.

2. ChromaSync.backfill{Observations,Summaries,Prompts}: per-batch watermark
   The bump was in a trailing finally block. SIGKILL / OOM / power loss
   mid-flight skips finally entirely, so the watermark stayed at 0 and the
   next worker boot re-embedded the entire history (16K obs in #2220's
   case), which then pegged CPU forever in combination with (1). Move the
   bump inside the loop so progress is durable per batch.
   Closes #2214.

Verification:
- 26/26 chroma tests pass (tests/services/sync, tests/integration/chroma-vector-sync)
- Bundle confirms thread caps and per-batch bumps are present
- Full suite: 1429 pass / 20 fail — pre-existing failures only, no
  regression vs v12.4.9 baseline (1429 pass / 27 fail)

Closes #2214.
Substantially de-amplifies #2220 (the structural Job-Object cleanup is
still tracked separately at #2216).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: kill chroma-mcp process tree and limit backfill concurrency

Three fixes for orphan chroma-mcp processes and resource exhaustion:

1. killProcessTree() in ChromaMcpManager.stop() tears down the full
   uvx->uv->python->chroma-mcp spawn chain (pkill -P on POSIX,
   taskkill /T on Windows) before MCP client.close().

2. Register chroma process with pgid for supervisor shutdown cascade.

3. backfillAllProjects() now processes max 3 projects concurrently
   with a re-entrancy guard to prevent overlapping fire-and-forget runs.

Closes #2216, advances #2220, #2213

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* build: regenerate plugin artifacts after cherry-picks

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: foundation consumers + Cursor/stdin/queue/docs fixes

F1 spawnHidden adoption (#2236):
- 8 spawn → spawnHidden conversions across worker-utils, ProcessManager,
  npx-cli (install/runtime), supervisor/process-registry

F3 getUptimeSeconds adoption (#2250):
- Server.ts:165 (THE BUG: returned ms)
- Server.ts:270, SessionRoutes.ts:326 (4th ms-bug consumer found),
  DataRoutes.ts:225 (refactor for consistency)

#2188 stdin '{}' fallback removal:
- Diagnostic logging to <DATA_DIR>/logs/runner-errors.log + CAPTURE_BROKEN
  marker; exit 0 to preserve Windows Terminal exit-code strategy

#2196 ANTHROPIC_BASE_URL docs:
- New docs/public/configuration/custom-anthropic-backends.mdx
- Note: issue may need separate auto-detect feature; docs document
  existing plumbing only

#2242 check-pending-queue endpoints:
- Point at /api/processing-status + /api/processing per DataRoutes.ts;
  honor CLAUDE_MEM_WORKER_PORT env

#2248 Cursor sessions never summarized:
- Pulled reporter wbingli's tested fix (commit 46eaba44)
- Bug A: cursor adapter now derives transcriptPath from cwd+sessionId
- Bug B: parser accepts both line.type and line.role
- Bug C: walk backward, prefer non-empty text, fallback to empty
- Tests: 10-case regression suite + tests/fixtures/cursor-session.jsonl

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: F2 paths namespace adoption (#2237 + #2238)

Replaced 24 hardcoded homedir() + '.claude-mem' sites across 18 source
files with paths.<accessor>() calls from src/shared/paths.ts.

Accessors used: dataDir, workerPid, settings, database, chroma,
combinedCerts, transcriptsConfig, transcriptsState, corpora,
supervisorRegistry, envFile, logsDir.

Sites converted (file:area):
- src/cli/claude-md-commands.ts (database)
- src/services/context/ContextConfigLoader.ts (settings)
- src/services/infrastructure/ProcessManager.ts (workerPid)
- src/services/infrastructure/WorktreeAdoption.ts (settings)
- src/services/integrations/CodexCliInstaller.ts (settings)
- src/services/sync/ChromaMcpManager.ts (chroma + combinedCerts)
- src/services/transcripts/config.ts (transcriptsConfig + transcriptsState)
- src/services/worker/ClaudeProvider.ts (envFile)
- src/services/worker/GeminiProvider.ts (envFile + 2 more)
- src/services/worker/http/routes/DataRoutes.ts (dataDir)
- src/services/worker/http/routes/SettingsRoutes.ts (settings + envFile)
- src/services/worker/knowledge/CorpusStore.ts (corpora)
- src/shared/EnvManager.ts (envFile)
- src/supervisor/index.ts (supervisorRegistry)
- src/supervisor/process-registry.ts (supervisorRegistry)
- src/supervisor/shutdown.ts (supervisorRegistry)
- src/utils/claude-md-utils.ts (database)
- src/utils/logger.ts (logsDir + settings, lazy to avoid cycle)

CLAUDE_MEM_DATA_DIR override now flows through 100% of the worker
runtime; no per-file env reads needed.

Verification:
- Grep guard: zero homedir+'.claude-mem' sites remain in src/
  (excluding paths.ts itself and SettingsDefaultsManager.ts)
- F2 invariant test: 3/3 pass (60 expects)
- Foundation tests: 19/19 pass

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: F4 provider classification + parser fence + OAuth keychain

F4 adoption (#2244 + #2254):
- Per-provider classifiers: classifyClaudeError, classifyGeminiError,
  classifyOpenRouterError. Each lives in the provider file.
- New retry helper at src/services/worker/retry.ts: withRetry() honors
  ClassifiedProviderError.kind; retriable=transient/rate_limit (with
  retryAfterMs); not retriable=unrecoverable/auth_invalid/quota_exhausted.
  maxRetries=2, perAttemptTimeout=30s, exponential backoff with jitter.
- GeminiProvider + OpenRouterProvider fetch calls wrapped with retry.
  Best-effort request-id capture (x-goog-request-id, x-request-id,
  x-openrouter-request-id) for dedup logging.
- Deleted unrecoverablePatterns allowlist at worker-service.ts:540 area;
  worker dispatches on err.kind instead.
- 28 new classifier tests at tests/worker/provider-classifiers.test.ts:
  429-no-Retry-After, 500-with-quota-exceeded, OverloadedError,
  per-provider auth_invalid signals.

#2233 Part A — parser fence handling:
- src/sdk/prompts.ts: removed 4 fence markers from XML example blocks.
  Model now sees plain XML, eliminating the failure-mode that drained
  quota via repeated retries.
- src/sdk/parser.ts: stripCodeFences() at top, called before
  parseAgentXml. Fence-tolerant regardless of model behavior.
- TODO comment references #2233 Part B (tool-use migration as separate
  scope).
- 4 fence-tolerance tests added to tests/sdk/parser.test.ts.

#2215 OAuth token keychain:
- New src/shared/oauth-token.ts (~360 LOC): readClaudeOAuthToken()
  reads from platform-native credential stores at worker spawn-time.
  - macOS: security find-generic-password -s "Claude Code-credentials"
  - Windows: PowerShell wrapper around CredRead (Win32 Advapi32.dll)
  - Linux: secret-tool lookup
  - Fallback: env CLAUDE_CODE_OAUTH_TOKEN with JWT exp claim or sidecar
    expiresAt validation; refuses stale-token injection.
- EnvManager.buildIsolatedEnvWithFreshOAuth() (async) replaces silent
  process.env copy. Empty injection on absent; marker write on expired.
- <DATA_DIR>/oauth-stale.marker surfaces "re-login via Claude Desktop"
  via existing SessionStart additionalContext mechanism (context.ts).
- ClaudeProvider.startSession + KnowledgeAgent.prime/executeQuery now
  await the async env builder.
- 17 oauth-token tests covering decodeJwtExpMs, marker round-trip,
  env-fallback expiry detection.

Verification:
- npx tsc --noEmit: only pre-existing bun-types error
- bun test (foundations + new): 70 pass, 0 new fails (8 fails are
  pre-existing parser.test.ts cases unrelated to fence work)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: #2234 quota-aware wall-clock guard

New src/services/worker/RateLimitStore.ts (207 LOC) — vendor pattern from
meridian/rateLimitStore.ts (MIT, copied not depended).

API:
- class RateLimitStore: set/get/getAll/getMostRecentByWindow/size/clear,
  in-memory last-write-wins keyed by rateLimitType.
- globalRateLimitStore singleton.
- shouldAbortForQuota(authMethod, store, now?) → {abort, reason?, window?}
- isApiKeyAuth(authMethod): matches both verbose getAuthMethodDescription
  strings and concise "api_key".

Thresholds (auth-type gated):
- api_key: never aborts (user authorized per-call spend).
- cli/oauth/subscription:
  - five_hour utilization >= 0.95 OR resetsAt within 15min (with 0.85
    utilization floor to avoid false trip on freshly-reset windows)
  - seven_day_opus >= 0.93
  - seven_day_sonnet >= 0.92
  - seven_day >= 0.93
  - overage >= 0.95

ClaudeProvider integration (line 198, for-await loop):
- Detects message.type === 'system' && subtype === 'rate_limit'
- Records rate_limit_info via globalRateLimitStore.set
- Calls shouldAbortForQuota(authMethod, globalRateLimitStore)
- On abort: session.abortReason = 'quota:<window>', abortController.abort,
  break out of loop. Worker continues other sessions.

Health endpoint (Server.ts:174):
- New rateLimits field on /api/health from getMostRecentByWindow().
- Field shape: {five_hour?, seven_day?, seven_day_opus?, seven_day_sonnet?,
  overage?} each carrying utilization, status, resetsAt, observedAt.

Tests (tests/worker/rate-limit-store.test.ts):
- 22 cases covering store CRUD, isApiKeyAuth, abort decision matrix.
- api_key never aborts at any utilization.
- cli aborts at threshold breaches per window.
- Reset-grace buffer with utilization floor.

Verification:
- npx tsc --noEmit: only pre-existing bun error
- bun test tests/worker/rate-limit-store.test.ts: 22/22 pass
- bun test tests/claude-provider-resume.test.ts: 9/9 pass
- bun test tests/server/: 44/44 pass

Plugin artifacts regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* build: regenerate worker-service.cjs after final build-and-sync

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: align test assertions with F4 classification + timeout

Two test fixes for branch-introduced regressions vs main:

1. tests/gemini_provider.test.ts "should throw on other errors":
   F4's classifyGeminiError replaced upstream Error message with
   ClassifiedProviderError. Test was pinned to pre-F4 string.
   Updated assertion to match new "Gemini bad request (status 400)".

2. tests/infrastructure/graceful-shutdown.test.ts:
   Test pokes real ~/.claude-mem/supervisor.json registry which on a
   developer machine contains live worker + chroma-mcp PIDs. SIGTERM →
   wait → SIGKILL cascade takes ~6s end-to-end. Bumped per-test timeout
   to 15000ms. Underlying shutdown code unchanged. Future cleanup
   should mock getSupervisor() here.

Result: branch failure count == main (77 pre-existing failures).
No new regressions from this branch's work.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: address 4 Greptile P1/P2 findings on PR #2282

P1 (real bug): clearStaleMarker silently broken in ESM
- src/shared/oauth-token.ts:14: add unlinkSync to top-level fs import
- src/shared/oauth-token.ts:342: drop inline require('fs'), call
  unlinkSync directly. ESM has no require, so the previous code threw
  ReferenceError swallowed by try/catch — making clearStaleMarker a
  permanent no-op. Stale oauth marker would persist indefinitely after
  Claude Desktop refreshed the token.

P2 (security): execSync shell-string interpolation
- src/shared/find-claude-executable.ts:39: execSync(`"${candidate}"
  --version`) → execFileSync(candidate, ['--version']). Path containing
  ", ;, & — reachable on Windows via crafted CLAUDE_CODE_PATH in
  settings.json — would otherwise produce a malformed/exploitable
  command.

P2 (security): PowerShell username injection
- src/shared/oauth-token.ts:119: userInfo().username escaped with PS
  single-quote convention (' → '') before interpolation into
  `'Claude Code-credentials:${user}'`. Defensive against future Windows
  versions or domain-joined machines that may permit ' in usernames.

P2 (style): Unreachable throw lastError post-loop
- src/services/worker/retry.ts:109: explained as the safety net for
  opts.maxRetries < 0 (pathological input where the loop never executes
  and lastError is undefined). Annotated with comment + descriptive
  fallback Error so the dead-looking code is now self-documenting.

Verification:
- npx tsc --noEmit: clean (only pre-existing bun-types error)
- bun test tests/shared/oauth-token.test.ts tests/worker/provider-classifiers.test.ts
  tests/worker/provider-errors.test.ts: 50 pass / 0 fail

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: tighten SECURITY.md data-flow and audit dates

Fixes CodeRabbit comments #3178957249 (Data Storage section overstated
"no external transmission" — softened to call out Claude Agent SDK,
alternate provider, Chroma MCP, OAuth keychain, and registry fetches)
and #3178957250 (Next Scheduled Audit was earlier than Last Updated;
bumped Last Updated to 2026-05-03 and audit to 2026-09-16) on PR #2282.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: drop inline require('fs') in paths.ts

Fixes CodeRabbit outside-diff comment on src/shared/paths.ts:25-29 from
PR #2282 review. resolveDataDir() ran require('fs') inside an ESM module
(this file uses import.meta.url and .js imports), which can break in
strict ESM environments. readFileSync now imports at the top alongside
existsSync/mkdirSync.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: block CLAUDE_CODE_OAUTH_TOKEN from parent env (issue #2215)

Fixes CodeRabbit outside-diff comment on src/shared/EnvManager.ts:14-17
from PR #2282 review. The OAuth-token leak fix was bypassed because
buildIsolatedEnv() copied every parent env var that wasn't in
BLOCKED_ENV_VARS, but CLAUDE_CODE_OAUTH_TOKEN was not blocked. A stale
parent token therefore still reached isolatedEnv even when the fresh
keychain read returned expired/absent — defeating the fix documented
inline at lines 178-183.

Adds CLAUDE_CODE_OAUTH_TOKEN to BLOCKED_ENV_VARS and defensively deletes
it again at the top of buildIsolatedEnvWithFreshOAuth() so the
fresh-spawn-time read is the only path that can populate it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: validate cursor sessionId against path traversal

Fixes CodeRabbit comment #3178957252 on PR #2282. The Cursor adapter
took sessionId straight from stdin and concatenated it into a
join(homedir(), '.cursor', 'projects', ..., sessionId, ...) path. A
crafted value containing path separators or '..' segments could escape
~/.cursor/projects, and the later transcript read would then probe
arbitrary local files.

deriveCursorTranscriptPath() now rejects any sessionId that doesn't
match /^[A-Za-z0-9_-]+$/ — Cursor's real session ids are UUID-style
identifiers, so the safe whitelist is non-disruptive.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: scope stripCodeFences() to full-wrapper payloads only

Fixes CodeRabbit comment #3178957253 on PR #2282. The previous regex
greedily removed the first opening and last closing triple-backticks
anywhere in the input, which could mangle valid content with internal
fenced examples or surrounding prose — and ran before XML parsing so
it created false negatives.

stripCodeFences() now only strips when the entire payload is a single
fenced block (start-to-end, with optional language tag and surrounding
whitespace), capturing the inner content. Adds a regression test that
feeds prose with internal triple-backtick markers around a real
<observation> block and asserts the inner ``` are preserved.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: honor abortSignal during retry backoff sleep

Fixes CodeRabbit comment #3178957263 on PR #2282. The retry helper used
an unconditional `setTimeout` Promise for backoff between attempts, so
an external abort that fired during the wait was delayed until the
timer completed.

The backoff now races setTimeout against opts.abortSignal: if the signal
flips, the timer is cleared and the Promise rejects with 'Aborted'
immediately. The abort listener is registered with { once: true } and
removed when the timer fires to avoid leaks.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: abort immediately on provider-side rejected status

Fixes CodeRabbit comment #3178957261 on PR #2282. shouldAbortForQuota()
only checked utilization thresholds and reset-grace heuristics; a
snapshot with status='rejected' (or overageStatus='rejected' on the
overage window) but no utilization number could still return
{ abort: false }, letting the worker keep consuming after the provider
had already declared the bucket exhausted.

Provider-side rejection is now checked before utilization. When either
rejection signal is present the guard returns abort=true with reason
"quota:<window> rejected by provider".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: only bump Chroma watermark on confirmed batch writes

Fixes CodeRabbit comments #3178957259 (watermark advances on swallowed
batch failures) and #3178957260 (backfillInProgress can stick true if
init throws) on PR #2282.

addDocuments() previously logged and swallowed per-batch failures with a
void return type, so all three backfill loops (observations, summaries,
prompts) bumped the watermark unconditionally after the call —
turning a transient Chroma failure into permanently-skipped records.
addDocuments() now returns the count of documents that actually landed
(including delete+add reconcile retries), and each loop only advances
the watermark when the batch wrote successfully. Failed batches log a
debug message and continue so the loop still gets through the rest.

backfillAllProjects() now constructs SessionStore and ChromaSync inside
a try block so a constructor throw can't leave the static
backfillInProgress guard stuck true and silently skip every later
backfill. The finally always clears the guard and best-effort closes
each resource.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: fall back to pid kill when process group is gone

Fixes CodeRabbit outside-diff comment on src/supervisor/shutdown.ts:118-134
from PR #2282 review. signalProcess() returned silently when a pgid was
present and process.kill(-pgid, signal) threw ESRCH, never attempting
the per-pid signal. With the new chroma registration path that records a
pgid alongside the pid, an already-collapsed group could turn shutdown
into a no-op even though the root pid was still alive.

The POSIX branch now tries -pgid first when present, and on ESRCH falls
through to process.kill(pid, signal). Non-ESRCH errors still propagate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: settings path, uptime clamp, fetch timeouts

Fixes three smaller CodeRabbit issues on PR #2282:

- SettingsRoutes (outside-diff #2282 review on lines 65-79): the
  parse-error response told users to delete ~/.claude-mem/settings.json
  even when paths.settings() resolved elsewhere. Now uses the resolved
  settingsPath variable in the message.

- uptime.ts (#3178957264 / lines 2-3): getUptimeSeconds() could return
  a negative value if startedAtMs was in the future or the system clock
  moved backward. Clamps with Math.max(0, ...) so health endpoints
  never see negative seconds.

- check-pending-queue.ts (#3178957248 / lines 27-45): checkWorkerHealth,
  getProcessingStatus and triggerProcessing all called fetch with no
  timeout, so the script could block forever if the worker accepted the
  TCP connection but never responded. Wraps each fetch with an
  AbortController + 10s timeout that throws a clear timeout message.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: walk descendants recursively when killing chroma-mcp tree

Fixes CodeRabbit comment #3178957258 on PR #2282. The POSIX teardown in
ChromaMcpManager.killProcessTree() relied on `pkill -P <pid>`, which
only signals direct children. Under uv, chroma-mcp spawns python as a
grandchild — when uv exits and python re-parents to init, pkill -P
never reaches it and the descendant survives the "tree kill".

killProcessTree() now collects the full descendant set via a recursive
`pgrep -P` walk before each signal phase. The walk returns leaves first
so signals propagate bottom-up (SIGTERM children before their parents,
then again for SIGKILL after the 500ms grace window so any layer that
re-parented during teardown still gets cleaned up). pgrep failures
(no children, missing binary) return [] so this stays best-effort and
falls back to the existing per-pid signal.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: tolerate malformed JSONL lines in transcript-parser

Fixes Greptile P1 comment 3178964456 on PR #2282.

extractLastMessageFromJsonl previously called JSON.parse(rawLine) with no
guard. A truncated/malformed JSONL line — common when a transcript was
crashed mid-write or partially flushed — would throw SyntaxError, crash
the summarization pipeline for that session, and silently lose all
prior valid messages.

Fix: wrap JSON.parse in try/catch and skip bad lines. The empty-line
guard only catches truly empty strings, not malformed fragments.

Regression tests added for two cases:
- Mixed valid + truncated lines: returns last valid match.
- All lines malformed: returns empty string (no throw).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: classify FK constraint failures BEFORE provider classifier

Fixes Greptile P1 comment 3178979583 on PR #2282.

The F4 #2244 work introduced a regression: reclassifyAtDispatch always
returns a non-null ClassifiedProviderError for known agent types
(Claude/Gemini/OpenRouter), so the isFkConstraintFailure branch was dead
code. Per-provider classifiers don't recognize "FOREIGN KEY constraint
failed", so SQLite FK failures fell through to the default 'transient'
kind and would retry indefinitely — restart loop on corrupted session
DB state.

Old unrecoverablePatterns explicitly listed FK constraint as
unrecoverable; restoring that semantic by checking FK FIRST and only
deferring to the classifier when not an FK error.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: validate CLAUDE_MEM_WORKER_PORT in check-pending-queue

Parse the env var, range-check (1-65535), and fall back to 37777 with a
console.warn on invalid input instead of letting a malformed value flow
into the URL builder unchecked (CodeRabbit Minor on PR #2282).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: SIGKILL union of pre-TERM and post-wait descendant sets

When the chroma-mcp root exits during the SIGTERM grace window, its
descendants get re-parented to init and drop out of the post-wait
pgrep -P scan. Without including the pre-TERM snapshot, those
re-parented PIDs would never receive SIGKILL even though they were
definitely children before SIGTERM and may still be alive (CodeRabbit
Major on PR #2282).

Compute Array.from(new Set([...descendantsBeforeTerm, ...descendantsBeforeKill]))
and SIGKILL the union. The two sets typically overlap, so dedupe is
required.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: enforce addDocuments return-count in direct sync paths

syncObservation/syncSummary/syncUserPrompt now capture the written count
from addDocuments() and only bump the watermark when every requested
document landed in Chroma. addDocuments() tolerates per-batch failures
(returns the actual written count), so the previous unconditional bump
was silently marking unsynced rows as synced on transient errors —
preventing the next backfill from retrying them (CodeRabbit Major on PR
#2282).

A partial write now logs a warn with the (requested, written) pair and
preserves retryability on the next pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: guard backfill watermark against non-contiguous failures

The backfill watermark is a single monotonic id, so it cannot represent
sparse success: "synced through 200, gap at 201–250, then 251 onward"
would, on restart, skip 201–250 forever because the watermark sat at
either 200 or 251 — both lose data (CodeRabbit Major on PR #2282).

Add a per-loop hadGap flag to backfillObservations / backfillSummaries /
backfillPrompts. Once any batch under-writes, every subsequent batch
must also skip the bump, regardless of whether it itself succeeded.
Also tighten the failure check from `writtenInBatch <= 0` to
`writtenInBatch < batch.length` so partial-batch writes are caught.

The watermark stays at the last contiguously-synced position; the next
backfill pass retries from there, eventually closing the gap.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: clear oauth-stale marker when token is absent

When an OAuth token disappears entirely (user logs out, keychain
cleared), buildIsolatedEnvWithFreshOAuth's absent branch was leaving any
prior stale-marker file in place. The session-start hook would then keep
surfacing an "expired token, re-login" warning even though the token is
no longer expired — it's gone, and re-login was already done elsewhere
or not applicable (CodeRabbit Minor on PR #2282).

Call clearStaleMarker() in the absent branch the same way the present
branch already does. Add a regression test exercising the full
buildIsolatedEnvWithFreshOAuth path: pre-write a marker, force absent
via spoofed unsupported platform, assert the marker is gone after.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: skip unknown message.content shapes instead of throwing

extractLastMessageFromJsonl already tolerates malformed JSONL lines
(JSON.parse failure -> continue), but a valid JSON line whose
message.content is an unexpected type (null, number, plain object) was
still throwing — contradicting the new tolerance and crashing the entire
summary pipeline on a single weird line (CodeRabbit Major + Greptile P1
on PR #2282).

Replace the `throw new Error(...)` with `continue` so a single bad
content shape skips that line instead of failing the whole transcript
read. Forward compat: future content schemas land harmlessly.

Add regression tests covering null, number, and plain-object content;
each must not throw and must fall back to the most recent valid line.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: guard null/primitive entries in message.content array

Fixes CodeRabbit comment 3179004190 on PR #2282.

The Array.isArray branch previously did `c.type === 'text'` directly,
which throws if `c` is null or a primitive — possible in malformed logs.
Tightened the filter with a type guard: requires c to be a non-null
object with type === 'text' and a string text field. Same defensive
class as the malformed-line and unknown-content-shape tolerances.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/services/context/ContextConfigLoader.ts

@@ -1,12 +1,11 @@
 
-import path from 'path';
-import { homedir } from 'os';
 import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.js';
+import { paths } from '../../shared/paths.js';
 import { ModeManager } from '../domain/ModeManager.js';
 import type { ContextConfig } from './types.js';
 
 export function loadContextConfig(): ContextConfig {
-  const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+  const settingsPath = paths.settings();
   const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
 
   const mode = ModeManager.getInstance().getActiveMode();

src/services/infrastructure/ProcessManager.ts

@@ -2,17 +2,19 @@
 import path from 'path';
 import { homedir } from 'os';
 import { existsSync, writeFileSync, readFileSync, unlinkSync, mkdirSync, rmSync, statSync, utimesSync, copyFileSync } from 'fs';
-import { exec, execSync, spawn, spawnSync } from 'child_process';
+import { exec, execSync, spawnSync } from 'child_process';
+import { spawnHidden } from '../../shared/spawn.js';
 import { promisify } from 'util';
 import { logger } from '../../utils/logger.js';
 import { HOOK_TIMEOUTS } from '../../shared/hook-constants.js';
 import { sanitizeEnv } from '../../supervisor/env-sanitizer.js';
 import { getSupervisor, validateWorkerPidFile, type ValidateWorkerPidStatus } from '../../supervisor/index.js';
+import { paths } from '../../shared/paths.js';
 
 const execAsync = promisify(exec);
 
-const DATA_DIR = path.join(homedir(), '.claude-mem');
-const PID_FILE = path.join(DATA_DIR, 'worker.pid');
+const DATA_DIR = paths.dataDir();
+const PID_FILE = paths.workerPid();
 
 interface RuntimeResolverOptions {
   platform?: NodeJS.Platform;
@@ -455,7 +457,7 @@ export function spawnDaemon(
     ? [runtimePath, scriptPath, '--daemon']
     : [scriptPath, '--daemon'];
 
-  const child = spawn(execPath, args, {
+  const child = spawnHidden(execPath, args, {
     detached: true,
     stdio: 'ignore',
     env

src/services/infrastructure/WorktreeAdoption.ts

@@ -1,13 +1,13 @@
 
 import path from 'path';
-import { homedir } from 'os';
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
 import { logger } from '../../utils/logger.js';
 import { getProjectContext } from '../../utils/project-name.js';
 import { ChromaSync } from '../sync/ChromaSync.js';
+import { paths } from '../../shared/paths.js';
 
-const DEFAULT_DATA_DIR = path.join(homedir(), '.claude-mem');
+const DEFAULT_DATA_DIR = paths.dataDir();
 
 export interface AdoptionResult {
   repoPath: string;

src/services/integrations/CodexCliInstaller.ts

@@ -9,11 +9,12 @@ import {
   DEFAULT_STATE_PATH,
   SAMPLE_CONFIG,
 } from '../transcripts/config.js';
+import { paths } from '../../shared/paths.js';
 import type { TranscriptWatchConfig, WatchTarget } from '../transcripts/types.js';
 
 const CODEX_DIR = path.join(homedir(), '.codex');
 const CODEX_AGENTS_MD_PATH = path.join(CODEX_DIR, 'AGENTS.md');
-const CLAUDE_MEM_DIR = path.join(homedir(), '.claude-mem');
+const CLAUDE_MEM_DIR = paths.dataDir();
 
 const CODEX_WATCH_NAME = 'codex';
 

src/services/server/Server.ts

@@ -11,6 +11,8 @@ import { getSupervisor } from '../../supervisor/index.js';
 import { isPidAlive } from '../../supervisor/process-registry.js';
 import { ENV_PREFIXES, ENV_EXACT_MATCHES } from '../../supervisor/env-sanitizer.js';
 import { flushResponseThen } from './flushResponseThen.js';
+import { getUptimeSeconds } from '../../shared/uptime.js';
+import { globalRateLimitStore } from '../worker/RateLimitStore.js';
 
 const INSTRUCTIONS_BASE_DIR: string = path.resolve(__dirname, '../skills/mem-search');
 const INSTRUCTIONS_OPERATIONS_DIR: string = path.join(INSTRUCTIONS_BASE_DIR, 'operations');
@@ -161,7 +163,7 @@ export class Server {
         status: 'ok',
         version: BUILT_IN_VERSION,
         workerPath: this.options.workerPath,
-        uptime: Date.now() - this.startTime,
+        uptime: getUptimeSeconds(this.startTime),
         managed: process.env.CLAUDE_MEM_MANAGED === 'true',
         hasIpc: typeof process.send === 'function',
         platform: process.platform,
@@ -169,6 +171,7 @@ export class Server {
         initialized: this.options.getInitializationComplete(),
         mcpReady: this.options.getMcpReady(),
         ai: this.options.getAiStatus(),
+        rateLimits: globalRateLimitStore.getMostRecentByWindow(),
       });
     });
 
@@ -266,8 +269,7 @@ export class Server {
         ENV_EXACT_MATCHES.has(key) || ENV_PREFIXES.some(prefix => key.startsWith(prefix))
       );
 
-      const uptimeMs = Date.now() - this.startTime;
-      const uptimeSeconds = Math.floor(uptimeMs / 1000);
+      const uptimeSeconds = getUptimeSeconds(this.startTime);
       const hours = Math.floor(uptimeSeconds / 3600);
       const minutes = Math.floor((uptimeSeconds % 3600) / 60);
       const formattedUptime = hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`;

src/services/sync/ChromaMcpManager.ts

@@ -1,21 +1,24 @@
 
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { execSync } from 'child_process';
+import { execFile, execSync, type ChildProcess } from 'child_process';
+import { promisify } from 'util';
 import path from 'path';
 import os from 'os';
 import fs from 'fs';
 import { logger } from '../../utils/logger.js';
 import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.js';
-import { USER_SETTINGS_PATH } from '../../shared/paths.js';
+import { USER_SETTINGS_PATH, paths } from '../../shared/paths.js';
 import { sanitizeEnv } from '../../supervisor/env-sanitizer.js';
 import { getSupervisor } from '../../supervisor/index.js';
 
+const execFileAsync = promisify(execFile);
+
 const CHROMA_MCP_CLIENT_NAME = 'claude-mem-chroma';
 const CHROMA_MCP_CLIENT_VERSION = '1.0.0';
 const MCP_CONNECTION_TIMEOUT_MS = 30_000;
-const RECONNECT_BACKOFF_MS = 10_000; 
-const DEFAULT_CHROMA_DATA_DIR = path.join(os.homedir(), '.claude-mem', 'chroma');
+const RECONNECT_BACKOFF_MS = 10_000;
+const DEFAULT_CHROMA_DATA_DIR = paths.chroma();
 const CHROMA_SUPERVISOR_ID = 'chroma-mcp';
 
 const CHROMA_MCP_PINNED_VERSION = '0.2.6';
@@ -325,6 +328,18 @@ export class ChromaMcpManager {
     }
   }
 
+  /**
+   * Gracefully stop the MCP connection and kill the chroma-mcp subprocess tree.
+   *
+   * The MCP SDK's client.close() sends stdin close -> SIGTERM -> SIGKILL to the
+   * direct child (uvx), but the spawn chain (uvx -> uv -> python -> chroma-mcp)
+   * can leave descendants orphaned because MCP SDK does not use process groups.
+   *
+   * Fix: kill the entire process tree rooted at the direct child PID BEFORE
+   * closing the MCP client, ensuring no orphan python/chroma-mcp processes
+   * accumulate across reconnects or worker restarts. Matches the tree-kill
+   * pattern from shutdown.ts (Principle 5: OS-supervised teardown).
+   */
   async stop(): Promise<void> {
     if (!this.client) {
       logger.debug('CHROMA_MCP', 'No active MCP connection to stop');
@@ -333,6 +348,13 @@ export class ChromaMcpManager {
 
     logger.info('CHROMA_MCP', 'Stopping chroma-mcp MCP connection');
 
+    // Kill the entire process tree before closing the MCP client so
+    // descendants (uv, python, chroma-mcp) don't become orphans.
+    const chromaProcess = (this.transport as unknown as { _process?: ChildProcess })?._process;
+    if (chromaProcess?.pid) {
+      await ChromaMcpManager.killProcessTree(chromaProcess.pid);
+    }
+
     try {
       await this.client.close();
     } catch (error) {
@@ -352,6 +374,137 @@ export class ChromaMcpManager {
     logger.info('CHROMA_MCP', 'chroma-mcp MCP connection stopped');
   }
 
+  /**
+   * Kill a process and all its descendants (tree-kill).
+   *
+   * POSIX: Sends SIGTERM to the process, then uses `pkill -P` to signal
+   * children recursively. Falls back to single-PID kill if pkill is unavailable.
+   *
+   * Windows: Uses `taskkill /T /F /PID` for full subtree teardown (same
+   * pattern as shutdown.ts).
+   *
+   * Best-effort — swallows ESRCH (already dead) and logs other errors.
+   */
+  private static async killProcessTree(pid: number): Promise<void> {
+    logger.debug('CHROMA_MCP', `Killing process tree rooted at PID ${pid}`);
+
+    if (process.platform === 'win32') {
+      try {
+        await execFileAsync('taskkill', ['/PID', String(pid), '/T', '/F'], {
+          timeout: 5_000,
+          windowsHide: true
+        });
+      } catch (error) {
+        // taskkill exits non-zero when the process is already dead — that's fine.
+        logger.debug('CHROMA_MCP', `taskkill tree-kill finished (may already be dead)`, {
+          pid,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+      return;
+    }
+
+    // POSIX: walk descendants recursively (bottom-up) and signal each.
+    // `pkill -P <pid>` only reaches direct children, so `python` /
+    // `chroma-mcp` under `uv` (grandchildren) get re-parented to init and
+    // survive. We collect the full descendant set via `pgrep -P` walks before
+    // signaling, so the SIGTERM phase reaches every layer
+    // (CodeRabbit review on PR #2282).
+    try {
+      const descendantsBeforeTerm = await ChromaMcpManager.collectDescendantPids(pid);
+      // Signal leaves first, then the root.
+      for (const child of descendantsBeforeTerm) {
+        try {
+          process.kill(child, 'SIGTERM');
+        } catch {
+          // Already gone — fine.
+        }
+      }
+      try {
+        process.kill(pid, 'SIGTERM');
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== 'ESRCH') {
+          logger.debug('CHROMA_MCP', `Failed to SIGTERM PID ${pid}`, { code });
+        }
+      }
+
+      // Brief wait for SIGTERM to propagate, then SIGKILL stragglers.
+      await new Promise(resolve => setTimeout(resolve, 500));
+
+      // Re-collect descendants — some layers may have re-parented during the
+      // SIGTERM grace window.
+      //
+      // SIGKILL targets the UNION of pre-TERM and post-wait descendant sets:
+      // when the root exits between snapshots, children get re-parented to
+      // init and drop out of `pgrep -P <root>`. Without the union, those
+      // re-parented descendants would never receive SIGKILL even though they
+      // were definitely children before SIGTERM (CodeRabbit review on PR
+      // #2282). Dedupe via Set since `descendantsBeforeKill` typically
+      // overlaps with `descendantsBeforeTerm`.
+      const descendantsBeforeKill = await ChromaMcpManager.collectDescendantPids(pid);
+      const killTargets = Array.from(new Set([...descendantsBeforeTerm, ...descendantsBeforeKill]));
+      for (const child of killTargets) {
+        try {
+          process.kill(child, 'SIGKILL');
+        } catch {
+          // Already dead — fine.
+        }
+      }
+      try {
+        process.kill(pid, 'SIGKILL');
+      } catch {
+        // Already dead — fine.
+      }
+    } catch (error) {
+      logger.debug('CHROMA_MCP', `Process tree kill completed (best-effort)`, {
+        pid,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  /**
+   * Recursively collect all descendant PIDs of `rootPid` using `pgrep -P`.
+   * Returned bottom-up (leaves first) so callers can signal leaves before
+   * their ancestors. Best-effort: missing pgrep / non-zero exits return [].
+   */
+  private static async collectDescendantPids(rootPid: number): Promise<number[]> {
+    const seen = new Set<number>();
+    const collected: number[] = [];
+
+    async function walk(pid: number): Promise<void> {
+      let stdout = '';
+      try {
+        const result = await execFileAsync('pgrep', ['-P', String(pid)], { timeout: 2_000 });
+        stdout = result.stdout;
+      } catch {
+        // pgrep exits 1 when no children match — that's fine, just return.
+        return;
+      }
+      const children = stdout
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => line.length > 0)
+        .map(line => Number.parseInt(line, 10))
+        .filter(n => Number.isFinite(n) && n > 0 && !seen.has(n));
+
+      for (const child of children) {
+        seen.add(child);
+        await walk(child);
+        // Bottom-up: push after recursion so leaves come first.
+        collected.push(child);
+      }
+    }
+
+    await walk(rootPid);
+    return collected;
+  }
+
+  /**
+   * Reset the singleton instance (for testing).
+   * Awaits stop() to prevent dual subprocesses.
+   */
   static async reset(): Promise<void> {
     if (ChromaMcpManager.instance) {
       await ChromaMcpManager.instance.stop();
@@ -360,7 +513,7 @@ export class ChromaMcpManager {
   }
 
   private getCombinedCertPath(): string | undefined {
-    const combinedCertPath = path.join(os.homedir(), '.claude-mem', 'combined_certs.pem');
+    const combinedCertPath = paths.combinedCerts();
 
     if (fs.existsSync(combinedCertPath)) {
       const stats = fs.statSync(combinedCertPath);
@@ -435,6 +588,19 @@ export class ChromaMcpManager {
       }
     }
 
+    // Cap embedding-thread fanout. ONNX Runtime / OpenBLAS / MKL all default to
+    // cpu_count(), so a 12-core box runs 12 threads burning embeddings in
+    // parallel — the dominant cause of the chroma-mcp CPU storm on Windows
+    // (#2220). Two threads keeps backfill latency reasonable without saturating
+    // the box. Only set if the user hasn't pinned them explicitly.
+    const threadCap = '2';
+    for (const key of ['OMP_NUM_THREADS', 'ONNX_NUM_THREADS', 'OPENBLAS_NUM_THREADS', 'MKL_NUM_THREADS']) {
+      if (!baseEnv[key]) baseEnv[key] = threadCap;
+    }
+    // Disable Chroma's anonymous telemetry — it issues background HTTP from
+    // the embedding subprocess on every collection touch.
+    if (!baseEnv.ANONYMIZED_TELEMETRY) baseEnv.ANONYMIZED_TELEMETRY = 'false';
+
     const combinedCertPath = this.getCombinedCertPath();
     if (!combinedCertPath) {
       return baseEnv;
@@ -454,15 +620,30 @@ export class ChromaMcpManager {
   }
 
   private registerManagedProcess(): void {
-    const chromaProcess = (this.transport as unknown as { _process?: import('child_process').ChildProcess })._process;
+    const chromaProcess = (this.transport as unknown as { _process?: ChildProcess })._process;
     if (!chromaProcess?.pid) {
       return;
     }
 
+    // Register with pgid so the supervisor's shutdown cascade can use
+    // process-group signaling (kill(-pgid, signal)) to tear down the
+    // entire spawn chain (uvx -> uv -> python -> chroma-mcp) in one
+    // syscall, matching the SDK subprocess pattern in process-registry.ts.
+    //
+    // Note: MCP SDK's StdioClientTransport does NOT use detached:true,
+    // so the child shares our process group — setting pgid here enables
+    // tree-kill via signalProcess() in shutdown.ts which falls back to
+    // taskkill /T on Windows when pgid is present but group signal fails.
+    // On POSIX the pgid recorded here is used by killProcessTree() in
+    // stop() for explicit tree teardown rather than negative-PID signaling.
     getSupervisor().registerProcess(CHROMA_SUPERVISOR_ID, {
       pid: chromaProcess.pid,
       type: 'chroma',
-      startedAt: new Date().toISOString()
+      startedAt: new Date().toISOString(),
+      // Store pid as pgid — shutdown.ts will attempt kill(-pgid) on POSIX.
+      // If the child isn't actually its own group leader, the ESRCH is caught
+      // and shutdown falls back to single-PID kill (see signalProcess()).
+      pgid: chromaProcess.pid
     }, chromaProcess);
 
     chromaProcess.once('exit', () => {

src/services/sync/ChromaSync.ts

@@ -222,15 +222,25 @@ export class ChromaSync {
     return documents;
   }
 
-  private async addDocuments(documents: ChromaDocument[]): Promise<void> {
+  /**
+   * Write `documents` to Chroma in BATCH_SIZE-sized batches.
+   *
+   * Returns the number of documents that were successfully written (or
+   * confirmed via delete+add reconcile). Per-batch failures are logged and the
+   * loop continues — we never throw — so callers must use the returned count
+   * to advance their watermark, otherwise an interrupted backfill can mark
+   * unsynced records as synced.
+   */
+  private async addDocuments(documents: ChromaDocument[]): Promise<number> {
     if (documents.length === 0) {
-      return;
+      return 0;
     }
 
     await this.ensureCollectionExists();
 
     const chromaMcp = ChromaMcpManager.getInstance();
 
+    let written = 0;
     for (let i = 0; i < documents.length; i += this.BATCH_SIZE) {
       const batch = documents.slice(i, i + this.BATCH_SIZE);
 
@@ -247,6 +257,7 @@ export class ChromaSync {
           documents: batch.map(d => d.document),
           metadatas: cleanMetadatas
         });
+        written += batch.length;
       } catch (error) {
         const errMsg = error instanceof Error ? error.message : String(error);
         if (errMsg.includes('already exist')) {
@@ -261,20 +272,21 @@ export class ChromaSync {
               documents: batch.map(d => d.document),
               metadatas: cleanMetadatas
             });
+            written += batch.length;
             logger.info('CHROMA_SYNC', 'Batch reconciled via delete+add after duplicate conflict', {
               collection: this.collectionName,
               batchStart: i,
               batchSize: batch.length
             });
           } catch (reconcileError) {
-            logger.error('CHROMA_SYNC', 'Batch reconcile (delete+add) failed', {
+            logger.error('CHROMA_SYNC', 'Batch reconcile (delete+add) failed — watermark will not advance for this batch', {
               collection: this.collectionName,
               batchStart: i,
               batchSize: batch.length
             }, reconcileError as Error);
           }
         } else {
-          logger.error('CHROMA_SYNC', 'Batch add failed, continuing with remaining batches', {
+          logger.error('CHROMA_SYNC', 'Batch add failed — watermark will not advance for this batch, continuing with remaining batches', {
             collection: this.collectionName,
             batchStart: i,
             batchSize: batch.length
@@ -285,8 +297,10 @@ export class ChromaSync {
 
     logger.debug('CHROMA_SYNC', 'Documents added', {
       collection: this.collectionName,
-      count: documents.length
+      requested: documents.length,
+      written
     });
+    return written;
   }
 
   async syncObservation(
@@ -326,8 +340,22 @@ export class ChromaSync {
       project
     });
 
-    await this.addDocuments(documents);
-    ChromaSyncState.bump(project, 'observations', observationId);
+    // Only advance the watermark on a confirmed full write. addDocuments() now
+    // returns a written count and tolerates per-batch failures, so a transient
+    // Chroma error must NOT mark this observation as synced — otherwise the
+    // backfill pass on next boot will skip past it (CodeRabbit review on PR
+    // #2282).
+    const written = await this.addDocuments(documents);
+    if (written === documents.length) {
+      ChromaSyncState.bump(project, 'observations', observationId);
+    } else {
+      logger.warn('CHROMA_SYNC', 'Observation watermark bump skipped — partial write', {
+        observationId,
+        project,
+        requested: documents.length,
+        written
+      });
+    }
   }
 
   async syncSummary(
@@ -364,8 +392,18 @@ export class ChromaSync {
       project
     });
 
-    await this.addDocuments(documents);
-    ChromaSyncState.bump(project, 'summaries', summaryId);
+    // Only bump on a confirmed full write — see syncObservation() for rationale.
+    const written = await this.addDocuments(documents);
+    if (written === documents.length) {
+      ChromaSyncState.bump(project, 'summaries', summaryId);
+    } else {
+      logger.warn('CHROMA_SYNC', 'Summary watermark bump skipped — partial write', {
+        summaryId,
+        project,
+        requested: documents.length,
+        written
+      });
+    }
   }
 
   private formatUserPromptDoc(prompt: StoredUserPrompt): ChromaDocument {
@@ -409,8 +447,17 @@ export class ChromaSync {
       project
     });
 
-    await this.addDocuments([document]);
-    ChromaSyncState.bump(project, 'prompts', promptId);
+    // Only bump on a confirmed full write — see syncObservation() for rationale.
+    const written = await this.addDocuments([document]);
+    if (written === 1) {
+      ChromaSyncState.bump(project, 'prompts', promptId);
+    } else {
+      logger.warn('CHROMA_SYNC', 'Prompt watermark bump skipped — write failed', {
+        promptId,
+        project,
+        written
+      });
+    }
   }
 
   private async getExistingChromaIds(projectOverride?: string): Promise<{
@@ -574,34 +621,67 @@ export class ChromaSync {
       obsByDocCount.push({ obs, docs });
     }
 
+    // Watermark must be durable per-batch: SIGKILL / OOM / reboot mid-flight
+    // skips any trailing finally, so a once-at-end bump leaves the watermark
+    // at zero and the next boot re-embeds everything (#2214, amplifies #2220).
+    //
+    // Non-contiguous failure guard: once any batch under-writes, ALL later
+    // batches must also skip the watermark bump. The watermark is a single
+    // monotonic id, so it cannot represent "synced through 200, then a gap at
+    // 201–250, then 251 onward" — bumping past the gap would silently drop
+    // 201–250 forever (CodeRabbit review on PR #2282).
     let writtenDocs = 0;
     let lastSyncedObsIdx = -1;
-    try {
-      for (let i = 0; i < allDocs.length; i += this.BATCH_SIZE) {
-        const batch = allDocs.slice(i, i + this.BATCH_SIZE);
-        await this.addDocuments(batch);
-        writtenDocs += batch.length;
-
-        let cursor = 0;
-        for (let j = 0; j < obsByDocCount.length; j++) {
-          cursor += obsByDocCount[j].docs.length;
-          if (cursor <= writtenDocs) {
-            lastSyncedObsIdx = j;
-          } else {
-            break;
-          }
-        }
-
-        logger.debug('CHROMA_SYNC', 'Backfill progress', {
+    let hadGap = false;
+    for (let i = 0; i < allDocs.length; i += this.BATCH_SIZE) {
+      const batch = allDocs.slice(i, i + this.BATCH_SIZE);
+      const writtenInBatch = await this.addDocuments(batch);
+      // Only advance the watermark for documents that actually landed in
+      // Chroma. addDocuments() logs and continues on per-batch failures, so a
+      // partial write must not mark unwritten docs as synced.
+      if (writtenInBatch < batch.length) {
+        hadGap = true;
+        logger.debug('CHROMA_SYNC', 'Skipping watermark bump for failed/partial batch', {
           project: backfillProject,
-          progress: `${Math.min(i + this.BATCH_SIZE, allDocs.length)}/${allDocs.length}`
+          batchStart: i,
+          requested: batch.length,
+          written: writtenInBatch
         });
+        continue;
       }
-    } finally {
+      if (hadGap) {
+        // A previous batch left a gap; downstream batches cannot bump the
+        // watermark even if they themselves succeeded.
+        logger.debug('CHROMA_SYNC', 'Skipping watermark bump after prior gap', {
+          project: backfillProject,
+          batchStart: i
+        });
+        continue;
+      }
+      writtenDocs += writtenInBatch;
+
+      let cursor = 0;
+      for (let j = 0; j < obsByDocCount.length; j++) {
+        cursor += obsByDocCount[j].docs.length;
+        if (cursor <= writtenDocs) {
+          lastSyncedObsIdx = j;
+        } else {
+          break;
+        }
+      }
+
       if (lastSyncedObsIdx >= 0) {
-        const highestId = obsByDocCount[lastSyncedObsIdx].obs.id;
-        ChromaSyncState.bump(backfillProject, 'observations', highestId);
+        ChromaSyncState.bump(
+          backfillProject,
+          'observations',
+          obsByDocCount[lastSyncedObsIdx].obs.id
+        );
       }
+
+      logger.debug('CHROMA_SYNC', 'Backfill progress', {
+        project: backfillProject,
+        progress: `${Math.min(i + this.BATCH_SIZE, allDocs.length)}/${allDocs.length}`
+      });
     }
 
     return allDocs;
@@ -641,30 +721,53 @@ export class ChromaSync {
       summaryByDocCount.push({ summary, docs });
     }
 
+    // Non-contiguous failure guard: see backfillObservations() for rationale.
     let writtenDocs = 0;
     let lastSyncedIdx = -1;
-    try {
-      for (let i = 0; i < summaryDocs.length; i += this.BATCH_SIZE) {
-        const batch = summaryDocs.slice(i, i + this.BATCH_SIZE);
-        await this.addDocuments(batch);
-        writtenDocs += batch.length;
-
-        let cursor = 0;
-        for (let j = 0; j < summaryByDocCount.length; j++) {
-          cursor += summaryByDocCount[j].docs.length;
-          if (cursor <= writtenDocs) lastSyncedIdx = j;
-          else break;
-        }
-
-        logger.debug('CHROMA_SYNC', 'Backfill progress', {
+    let hadGap = false;
+    for (let i = 0; i < summaryDocs.length; i += this.BATCH_SIZE) {
+      const batch = summaryDocs.slice(i, i + this.BATCH_SIZE);
+      const writtenInBatch = await this.addDocuments(batch);
+      // Only advance the watermark for documents that actually landed in
+      // Chroma. See the analogous comment in backfillObservations().
+      if (writtenInBatch < batch.length) {
+        hadGap = true;
+        logger.debug('CHROMA_SYNC', 'Skipping watermark bump for failed/partial batch', {
           project: backfillProject,
-          progress: `${Math.min(i + this.BATCH_SIZE, summaryDocs.length)}/${summaryDocs.length}`
+          batchStart: i,
+          requested: batch.length,
+          written: writtenInBatch
         });
+        continue;
       }
-    } finally {
+      if (hadGap) {
+        logger.debug('CHROMA_SYNC', 'Skipping watermark bump after prior gap', {
+          project: backfillProject,
+          batchStart: i
+        });
+        continue;
+      }
+      writtenDocs += writtenInBatch;
+
+      let cursor = 0;
+      for (let j = 0; j < summaryByDocCount.length; j++) {
+        cursor += summaryByDocCount[j].docs.length;
+        if (cursor <= writtenDocs) lastSyncedIdx = j;
+        else break;
+      }
+
       if (lastSyncedIdx >= 0) {
-        ChromaSyncState.bump(backfillProject, 'summaries', summaryByDocCount[lastSyncedIdx].summary.id);
+        ChromaSyncState.bump(
+          backfillProject,
+          'summaries',
+          summaryByDocCount[lastSyncedIdx].summary.id
+        );
       }
+
+      logger.debug('CHROMA_SYNC', 'Backfill progress', {
+        project: backfillProject,
+        progress: `${Math.min(i + this.BATCH_SIZE, summaryDocs.length)}/${summaryDocs.length}`
+      });
     }
 
     return summaryDocs;
@@ -709,23 +812,41 @@ export class ChromaSync {
       promptDocs.push(this.formatUserPromptDoc(prompt));
     }
 
-    let lastSyncedPromptId = 0;
-    try {
-      for (let i = 0; i < promptDocs.length; i += this.BATCH_SIZE) {
-        const batch = promptDocs.slice(i, i + this.BATCH_SIZE);
-        await this.addDocuments(batch);
-        const upTo = Math.min(i + this.BATCH_SIZE, prompts.length);
-        lastSyncedPromptId = prompts[upTo - 1].id;
-
-        logger.debug('CHROMA_SYNC', 'Backfill progress', {
+    // Prompts are 1 doc each — bump the watermark per batch so an interrupted
+    // backfill resumes where it left off instead of re-embedding from zero.
+    // Only advance the watermark when the batch actually wrote — partial
+    // writes must not skip the failed prompts on restart.
+    //
+    // Non-contiguous failure guard: see backfillObservations() for rationale.
+    let hadGap = false;
+    for (let i = 0; i < promptDocs.length; i += this.BATCH_SIZE) {
+      const batch = promptDocs.slice(i, i + this.BATCH_SIZE);
+      const writtenInBatch = await this.addDocuments(batch);
+      const upTo = Math.min(i + this.BATCH_SIZE, prompts.length);
+      if (writtenInBatch < batch.length) {
+        hadGap = true;
+        logger.debug('CHROMA_SYNC', 'Skipping prompt watermark bump for failed/partial batch', {
           project: backfillProject,
-          progress: `${upTo}/${promptDocs.length}`
+          batchStart: i,
+          requested: batch.length,
+          written: writtenInBatch
         });
+        continue;
       }
-    } finally {
-      if (lastSyncedPromptId > 0) {
-        ChromaSyncState.bump(backfillProject, 'prompts', lastSyncedPromptId);
+      if (hadGap) {
+        logger.debug('CHROMA_SYNC', 'Skipping prompt watermark bump after prior gap', {
+          project: backfillProject,
+          batchStart: i
+        });
+        continue;
       }
+      const lastSyncedPromptId = prompts[upTo - 1].id;
+      ChromaSyncState.bump(backfillProject, 'prompts', lastSyncedPromptId);
+
+      logger.debug('CHROMA_SYNC', 'Backfill progress', {
+        project: backfillProject,
+        progress: `${upTo}/${promptDocs.length}`
+      });
     }
 
     return promptDocs;
@@ -814,9 +935,50 @@ export class ChromaSync {
     return { ids, distances, metadatas };
   }
 
+  /** Maximum number of concurrent project backfills to run at once. */
+  private static readonly BACKFILL_CONCURRENCY_LIMIT = 3;
+
+  /** Guard flag to prevent overlapping backfill runs from fire-and-forget callers. */
+  private static backfillInProgress = false;
+
+  /**
+   * Backfill all projects that have observations in SQLite but may be missing from Chroma.
+   * Uses a single shared ChromaSync('claude-mem') instance and Chroma connection.
+   * Per-project scoping is passed as a parameter to ensureBackfilled(), avoiding
+   * instance state mutation. All documents land in the cm__claude-mem collection
+   * with project scoped via metadata, matching how DatabaseManager and SearchManager operate.
+   * Designed to be called fire-and-forget on worker startup.
+   *
+   * Concurrency: processes at most BACKFILL_CONCURRENCY_LIMIT projects in parallel
+   * to bound CPU and memory pressure from concurrent Chroma embedding operations.
+   * A re-entrant guard prevents overlapping backfill runs from accumulating.
+   */
   static async backfillAllProjects(storeOverride?: SessionStore): Promise<void> {
-    const db = storeOverride ?? new SessionStore();
-    const sync = new ChromaSync('claude-mem');
+    if (ChromaSync.backfillInProgress) {
+      logger.info('CHROMA_SYNC', 'Backfill already in progress, skipping duplicate run');
+      return;
+    }
+
+    // Allocate first so a constructor throw cannot leave the guard stuck true
+    // and silently skip every subsequent backfill (CodeRabbit review on PR
+    // #2282). The guard only flips to true after both resources are alive,
+    // and the finally always clears it.
+    let db: SessionStore | undefined;
+    let sync: ChromaSync | undefined;
+    try {
+      db = storeOverride ?? new SessionStore();
+      sync = new ChromaSync('claude-mem');
+    } catch (error) {
+      logger.error('CHROMA_SYNC', 'Failed to initialize backfill resources',
+        {}, error instanceof Error ? error : new Error(String(error)));
+      // Best-effort cleanup if SessionStore allocated but ChromaSync threw.
+      if (db && !storeOverride) {
+        try { db.close(); } catch { /* ignore */ }
+      }
+      throw error;
+    }
+
+    ChromaSync.backfillInProgress = true;
     try {
       const projects = db.db.prepare(
         'SELECT DISTINCT project FROM observations WHERE project IS NOT NULL AND project != ?'
@@ -837,22 +999,45 @@ export class ChromaSync {
         logger.info('CHROMA_SYNC', 'Bootstrap complete — incremental backfills will use watermarks');
       }
 
-      for (const { project } of projects) {
-        try {
-          await sync.ensureBackfilled(project, db);
-        } catch (error) {
-          if (error instanceof Error) {
-            logger.error('CHROMA_SYNC', `Backfill failed for project: ${project}`, {}, error);
-          } else {
-            logger.error('CHROMA_SYNC', `Backfill failed for project: ${project}`, { error: String(error) });
+      // Process projects in chunks of BACKFILL_CONCURRENCY_LIMIT to bound
+      // CPU/memory pressure from concurrent Chroma embedding operations.
+      // Each chunk runs its projects in parallel; we wait for the entire chunk
+      // before starting the next one. Simple and predictable — no semaphore
+      // overhead, no unbounded fan-out.
+      const concurrency = ChromaSync.BACKFILL_CONCURRENCY_LIMIT;
+      for (let i = 0; i < projects.length; i += concurrency) {
+        const chunk = projects.slice(i, i + concurrency);
+        const chunkResults = await Promise.allSettled(
+          chunk.map(({ project }) => sync!.ensureBackfilled(project, db!))
+        );
+
+        for (let j = 0; j < chunkResults.length; j++) {
+          const result = chunkResults[j];
+          if (result.status === 'rejected') {
+            const project = chunk[j].project;
+            const error = result.reason;
+            if (error instanceof Error) {
+              logger.error('CHROMA_SYNC', `Backfill failed for project: ${project}`, {}, error);
+            } else {
+              logger.error('CHROMA_SYNC', `Backfill failed for project: ${project}`, { error: String(error) });
+            }
+            // Continue to next chunk — don't let one failure stop others
           }
-          // Continue to next project — don't let one failure stop others
         }
       }
     } finally {
-      await sync.close();
-      if (!storeOverride) {
-        db.close();
+      ChromaSync.backfillInProgress = false;
+      if (sync) {
+        try { await sync.close(); } catch (closeError) {
+          logger.debug('CHROMA_SYNC', 'sync.close() failed during backfill teardown',
+            {}, closeError instanceof Error ? closeError : new Error(String(closeError)));
+        }
+      }
+      if (!storeOverride && db) {
+        try { db.close(); } catch (closeError) {
+          logger.debug('CHROMA_SYNC', 'db.close() failed during backfill teardown',
+            {}, closeError instanceof Error ? closeError : new Error(String(closeError)));
+        }
       }
     }
   }

src/services/transcripts/config.ts

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
+import { paths } from '../../shared/paths.js';
 import type { TranscriptSchema, TranscriptWatchConfig } from './types.js';
 
-export const DEFAULT_CONFIG_PATH = join(homedir(), '.claude-mem', 'transcript-watch.json');
-export const DEFAULT_STATE_PATH = join(homedir(), '.claude-mem', 'transcript-watch-state.json');
+export const DEFAULT_CONFIG_PATH = paths.transcriptsConfig();
+export const DEFAULT_STATE_PATH = paths.transcriptsState();
 
 const CODEX_SAMPLE_SCHEMA: TranscriptSchema = {
   name: 'codex',
@@ -78,7 +79,8 @@ const CODEX_SAMPLE_SCHEMA: TranscriptSchema = {
     },
     {
       name: 'session-end',
-      match: { path: 'payload.type', in: ['turn_aborted', 'turn_completed'] },
+      // TODO(#2249): delete watcher when Codex hook lifecycle migration ships
+      match: { path: 'payload.type', in: ['turn_aborted', 'turn_completed', 'task_complete'] },
       action: 'session_end'
     }
   ]

src/services/worker-service.ts

@@ -58,10 +58,11 @@ import {
 import { DatabaseManager } from './worker/DatabaseManager.js';
 import { SessionManager } from './worker/SessionManager.js';
 import { SSEBroadcaster } from './worker/SSEBroadcaster.js';
-import { ClaudeProvider } from './worker/ClaudeProvider.js';
+import { ClaudeProvider, classifyClaudeError } from './worker/ClaudeProvider.js';
 import type { WorkerRef } from './worker/agents/types.js';
-import { GeminiProvider, isGeminiSelected, isGeminiAvailable } from './worker/GeminiProvider.js';
-import { OpenRouterProvider, isOpenRouterSelected, isOpenRouterAvailable } from './worker/OpenRouterProvider.js';
+import { GeminiProvider, classifyGeminiError, isGeminiSelected, isGeminiAvailable } from './worker/GeminiProvider.js';
+import { OpenRouterProvider, classifyOpenRouterError, isOpenRouterSelected, isOpenRouterAvailable } from './worker/OpenRouterProvider.js';
+import { ClassifiedProviderError, isClassified, type ProviderErrorClass } from './worker/provider-errors.js';
 import { PaginationHelper } from './worker/PaginationHelper.js';
 import { SettingsManager } from './worker/SettingsManager.js';
 import { SearchManager } from './worker/SearchManager.js';
@@ -503,6 +504,36 @@ export class WorkerService implements WorkerRef {
     return this.sdkAgent;
   }
 
+  /**
+   * Re-classify a raw error at the worker-service dispatch site using the
+   * active provider's classifier. Returns null when the provider classifier
+   * doesn't recognize the shape (caller falls back to default behavior).
+   *
+   * Most provider errors should already be classified at the provider
+   * boundary — this is a safety net for errors from inside the SDK that
+   * never round-tripped through fetch (e.g. Anthropic SDK exceptions).
+   */
+  private reclassifyAtDispatch(
+    error: unknown,
+    agent: ClaudeProvider | GeminiProvider | OpenRouterProvider
+  ): ClassifiedProviderError | null {
+    try {
+      if (agent instanceof ClaudeProvider) {
+        return classifyClaudeError(error);
+      }
+      if (agent instanceof GeminiProvider) {
+        // Without a status code we still want network/spawn detection.
+        return classifyGeminiError({ cause: error });
+      }
+      if (agent instanceof OpenRouterProvider) {
+        return classifyOpenRouterError({ cause: error });
+      }
+    } catch {
+      // If the classifier itself throws, fall back to unclassified.
+    }
+    return null;
+  }
+
   private startSessionProcessor(
     session: ReturnType<typeof this.sessionManager.getSession>,
     source: string
@@ -531,22 +562,26 @@ export class WorkerService implements WorkerRef {
       .catch(async (error: unknown) => {
         const errorMessage = (error as Error)?.message || '';
 
-        const unrecoverablePatterns = [
-          'Claude executable not found',
-          'CLAUDE_CODE_PATH',
-          'ENOENT',
-          'spawn',
-          'Invalid API key',
-          'API_KEY_INVALID',
-          'API key expired',
-          'API key not valid',
-          'PERMISSION_DENIED',
-          'Gemini API error: 400',
-          'Gemini API error: 401',
-          'Gemini API error: 403',
-          'FOREIGN KEY constraint failed',
-        ];
-        if (unrecoverablePatterns.some(pattern => errorMessage.includes(pattern))) {
+        // Dispatch on F4 ClassifiedProviderError.kind. Replaces the old
+        // string-matching allowlist (#2244). Already-classified errors
+        // propagate kind from the provider boundary; raw errors get
+        // re-classified here using provider-specific helpers based on the
+        // active agent.
+        const classified: ClassifiedProviderError | null = isClassified(error)
+          ? error
+          : this.reclassifyAtDispatch(error, agent);
+
+        // FOREIGN KEY constraint failures from SQLite are unrecoverable but
+        // not provider-specific; check before deferring to the classifier so
+        // FK failures don't get misclassified as transient and retry forever
+        // (per-provider classifiers don't recognize FK errors).
+        const isFkConstraintFailure = errorMessage.includes('FOREIGN KEY constraint failed');
+
+        const dispatchKind: ProviderErrorClass | null = isFkConstraintFailure
+          ? 'unrecoverable'
+          : (classified ? classified.kind : null);
+
+        if (dispatchKind === 'unrecoverable' || dispatchKind === 'auth_invalid' || dispatchKind === 'quota_exhausted') {
           hadUnrecoverableError = true;
           this.lastAiInteraction = {
             timestamp: Date.now(),
@@ -554,9 +589,13 @@ export class WorkerService implements WorkerRef {
             provider: providerName,
             error: errorMessage,
           };
-          logger.error('SDK', 'Unrecoverable generator error - will NOT restart', {
+          const logLabel =
+            dispatchKind === 'auth_invalid' ? 'auth invalid' :
+            dispatchKind === 'quota_exhausted' ? 'quota exhausted' : 'unrecoverable';
+          logger.error('SDK', `Unrecoverable generator error (${logLabel}) - will NOT restart`, {
             sessionId: session.sessionDbId,
             project: session.project,
+            errorKind: dispatchKind,
             errorMessage
           });
           return;

src/services/worker-types.ts

@@ -33,7 +33,7 @@ export interface ActiveSession {
   lastSummaryStored?: boolean;
   pendingAgentId?: string | null;
   pendingAgentType?: string | null;
-  abortReason?: 'idle' | 'shutdown' | 'overflow' | 'restart-guard' | null;
+  abortReason?: 'idle' | 'shutdown' | 'overflow' | 'restart-guard' | 'quota' | string | null;
   respawnTimer?: ReturnType<typeof setTimeout>;
 }
 

src/services/worker/ClaudeProvider.ts

@@ -1,14 +1,12 @@
 
-import { execSync } from 'child_process';
-import { homedir } from 'os';
-import path from 'path';
 import { DatabaseManager } from './DatabaseManager.js';
 import { SessionManager } from './SessionManager.js';
 import { logger } from '../../utils/logger.js';
 import { buildInitPrompt, buildObservationPrompt, buildSummaryPrompt, buildContinuationPrompt } from '../../sdk/prompts.js';
 import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.js';
-import { USER_SETTINGS_PATH, OBSERVER_SESSIONS_DIR, ensureDir } from '../../shared/paths.js';
-import { buildIsolatedEnv, getAuthMethodDescription } from '../../shared/EnvManager.js';
+import { USER_SETTINGS_PATH, OBSERVER_SESSIONS_DIR, ensureDir, paths } from '../../shared/paths.js';
+import { buildIsolatedEnvWithFreshOAuth, getAuthMethodDescription } from '../../shared/EnvManager.js';
+import { findClaudeExecutable } from '../../shared/find-claude-executable.js';
 import type { ActiveSession, SDKUserMessage } from '../worker-types.js';
 import { ModeManager } from '../domain/ModeManager.js';
 import { processAgentResponse, type WorkerRef } from './agents/index.js';
@@ -19,9 +17,86 @@ import {
   waitForSlot,
 } from '../../supervisor/process-registry.js';
 import { sanitizeEnv } from '../../supervisor/env-sanitizer.js';
+import {
+  globalRateLimitStore,
+  shouldAbortForQuota,
+  type RateLimitInfo,
+} from './RateLimitStore.js';
 
 // @ts-ignore - Agent SDK types may not be available
 import { query } from '@anthropic-ai/claude-agent-sdk';
+import { ClassifiedProviderError } from './provider-errors.js';
+
+/**
+ * Classify a ClaudeProvider error (executable spawn failures, SDK errors,
+ * Anthropic API errors). Provider-specific because it relies on:
+ *   - SDK error class names (e.g. OverloadedError) when present
+ *   - spawn errors (ENOENT) when the Claude executable is missing
+ *   - Anthropic-specific message strings ("Invalid API key", "Prompt is too long")
+ */
+export function classifyClaudeError(err: unknown): ClassifiedProviderError {
+  const message = err instanceof Error ? err.message : String(err);
+  const errAny = err as { name?: string; status?: number; error?: { type?: string } };
+
+  // Executable / spawn issues — unrecoverable, no point retrying.
+  if (
+    message.includes('Claude executable not found') ||
+    message.includes('CLAUDE_CODE_PATH') ||
+    message.includes('ENOENT') ||
+    message.startsWith('spawn ')
+  ) {
+    return new ClassifiedProviderError(message, { kind: 'unrecoverable', cause: err });
+  }
+
+  // Anthropic auth failures.
+  if (
+    errAny.status === 401 ||
+    errAny.status === 403 ||
+    message.includes('Invalid API key') ||
+    message.includes('API_KEY_INVALID') ||
+    message.includes('API key expired') ||
+    message.includes('API key not valid')
+  ) {
+    return new ClassifiedProviderError(message, { kind: 'auth_invalid', cause: err });
+  }
+
+  // SDK-level overloaded — Anthropic emits OverloadedError or 529 with type:'overloaded_error'.
+  if (
+    errAny.name === 'OverloadedError' ||
+    errAny.status === 529 ||
+    errAny.error?.type === 'overloaded_error'
+  ) {
+    return new ClassifiedProviderError(message || 'Anthropic overloaded', { kind: 'transient', cause: err });
+  }
+
+  // Rate limit.
+  if (errAny.status === 429) {
+    return new ClassifiedProviderError(message, { kind: 'rate_limit', cause: err });
+  }
+
+  // Quota.
+  if (message.toLowerCase().includes('quota exceeded')) {
+    return new ClassifiedProviderError(message, { kind: 'quota_exhausted', cause: err });
+  }
+
+  // Context overflow — unrecoverable in this session, requires reset.
+  if (
+    message.includes('Prompt is too long') ||
+    message.includes('prompt is too long') ||
+    message.includes('context window')
+  ) {
+    return new ClassifiedProviderError(message, { kind: 'unrecoverable', cause: err });
+  }
+
+  // Server errors → transient.
+  if (typeof errAny.status === 'number' && errAny.status >= 500 && errAny.status < 600) {
+    return new ClassifiedProviderError(message, { kind: 'transient', cause: err });
+  }
+
+  // Default: treat unknown errors as transient (preserve old behavior of
+  // retrying everything not explicitly marked unrecoverable).
+  return new ClassifiedProviderError(message, { kind: 'transient', cause: err });
+}
 
 export class ClaudeProvider {
   private dbManager: DatabaseManager;
@@ -41,7 +116,8 @@ export class ClaudeProvider {
   async startSession(session: ActiveSession, worker?: WorkerRef): Promise<void> {
     const cwdTracker = { lastCwd: undefined as string | undefined };
 
-    const claudePath = this.findClaudeExecutable();
+    // Find and validate Claude executable (shared utility, closes #2222)
+    const claudePath = findClaudeExecutable('SDK');
 
     const modelId = session.modelOverride || this.getModelId();
     const disallowedTools = [
@@ -76,7 +152,7 @@ export class ClaudeProvider {
     const maxConcurrent = parseInt(settings.CLAUDE_MEM_MAX_CONCURRENT_AGENTS, 10) || 2;
     await waitForSlot(maxConcurrent, 60_000);
 
-    const isolatedEnv = sanitizeEnv(buildIsolatedEnv());
+    const isolatedEnv = sanitizeEnv(await buildIsolatedEnvWithFreshOAuth());
     const authMethod = getAuthMethodDescription();
 
     logger.info('SDK', 'Starting SDK query', {
@@ -120,6 +196,36 @@ export class ClaudeProvider {
 
     try {
       for await (const message of queryResult) {
+        // Quota-aware wall-clock guard (#2234): the SDK pushes `system` events
+        // with subtype `rate_limit` carrying live subscription quota state.
+        // Capture the snapshot, then bail out of the loop before issuing
+        // another request if we've crossed a per-window threshold. API-key
+        // users are exempt — they authorized per-call spend.
+        if (
+          (message as any)?.type === 'system' &&
+          (message as any)?.subtype === 'rate_limit'
+        ) {
+          const info = (message as any).rate_limit_info as RateLimitInfo | undefined;
+          if (info) {
+            globalRateLimitStore.set(info);
+          }
+          const decision = shouldAbortForQuota(authMethod, globalRateLimitStore);
+          if (decision.abort) {
+            logger.warn('SDK', `Aborting session for quota guard: ${decision.reason}`, {
+              sessionDbId: session.sessionDbId,
+              window: decision.window,
+              authMethod,
+            });
+            session.abortReason = `quota:${decision.window ?? 'unknown'}`;
+            try {
+              session.abortController.abort();
+            } catch {
+              // best-effort
+            }
+            break;
+          }
+        }
+
         if (message.session_id && message.session_id !== session.memorySessionId) {
           const previousId = session.memorySessionId;
           session.memorySessionId = message.session_id;
@@ -333,46 +439,8 @@ export class ClaudeProvider {
     }
   }
 
-  private findClaudeExecutable(): string {
-    const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
-
-    if (settings.CLAUDE_CODE_PATH) {
-      const { existsSync } = require('fs');
-      if (!existsSync(settings.CLAUDE_CODE_PATH)) {
-        throw new Error(`CLAUDE_CODE_PATH is set to "${settings.CLAUDE_CODE_PATH}" but the file does not exist.`);
-      }
-      return settings.CLAUDE_CODE_PATH;
-    }
-
-    if (process.platform === 'win32') {
-      try {
-        execSync('where claude.cmd', { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
-        return 'claude.cmd'; 
-      } catch {
-        // Fall through to generic error
-      }
-    }
-
-    try {
-      const claudePath = execSync(
-        process.platform === 'win32' ? 'where claude' : 'which claude',
-        { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }
-      ).trim().split('\n')[0].trim();
-
-      if (claudePath) return claudePath;
-    } catch (error) {
-      if (error instanceof Error) {
-        logger.debug('SDK', 'Claude executable auto-detection failed', {}, error);
-      } else {
-        logger.debug('SDK', 'Claude executable auto-detection failed with non-Error', {}, new Error(String(error)));
-      }
-    }
-
-    throw new Error('Claude executable not found. Please either:\n1. Add "claude" to your system PATH, or\n2. Set CLAUDE_CODE_PATH in ~/.claude-mem/settings.json');
-  }
-
   private getModelId(): string {
-    const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+    const settingsPath = paths.settings();
     const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
     return settings.CLAUDE_MEM_MODEL;
   }

src/services/worker/GeminiProvider.ts

@@ -1,13 +1,11 @@
 
-import path from 'path';
-import { homedir } from 'os';
 import { DatabaseManager } from './DatabaseManager.js';
 import { SessionManager } from './SessionManager.js';
 import { logger } from '../../utils/logger.js';
 import { buildInitPrompt, buildObservationPrompt, buildSummaryPrompt, buildContinuationPrompt } from '../../sdk/prompts.js';
 import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.js';
 import { getCredential } from '../../shared/EnvManager.js';
-import { USER_SETTINGS_PATH } from '../../shared/paths.js';
+import { USER_SETTINGS_PATH, paths } from '../../shared/paths.js';
 import { estimateTokens } from '../../shared/timeline-formatting.js';
 import type { ActiveSession, ConversationMessage } from '../worker-types.js';
 import { ModeManager } from '../domain/ModeManager.js';
@@ -17,9 +15,105 @@ import {
   isAbortError,
   type WorkerRef
 } from './agents/index.js';
+import { ClassifiedProviderError } from './provider-errors.js';
+import { withRetry } from './retry.js';
 
 const GEMINI_API_URL = 'https://generativelanguage.googleapis.com/v1/models';
 
+/**
+ * Parse Retry-After header (seconds or HTTP-date).
+ * Returns ms or undefined.
+ */
+function parseRetryAfterMs(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (!Number.isNaN(seconds) && seconds >= 0) {
+    return Math.floor(seconds * 1000);
+  }
+  const dateMs = Date.parse(value);
+  if (!Number.isNaN(dateMs)) {
+    const delta = dateMs - Date.now();
+    return delta > 0 ? delta : 0;
+  }
+  return undefined;
+}
+
+/**
+ * Classify a Gemini fetch failure into ClassifiedProviderError. Called at
+ * the boundary right after `fetch()` returns or throws. Provider-specific
+ * because Gemini surfaces auth/quota/rate-limit signals via specific status
+ * codes and body strings (e.g. "quota exceeded", "API key not valid").
+ */
+export function classifyGeminiError(input: {
+  status?: number;
+  bodyText?: string;
+  headers?: Headers | { get(name: string): string | null };
+  cause: unknown;
+  requestId?: string;
+}): ClassifiedProviderError {
+  const status = input.status;
+  const body = input.bodyText ?? '';
+  const lower = body.toLowerCase();
+  const headers = input.headers;
+  const retryAfterMs = headers ? parseRetryAfterMs(headers.get('retry-after')) : undefined;
+
+  // Quota exceeded — by body marker — even on 500 (Gemini quirk).
+  if (lower.includes('quota exceeded') || lower.includes('resource_exhausted')) {
+    return new ClassifiedProviderError(
+      `Gemini quota exhausted${status !== undefined ? ` (status ${status})` : ''}`,
+      { kind: 'quota_exhausted', cause: input.cause },
+    );
+  }
+
+  if (status === 429) {
+    return new ClassifiedProviderError(
+      'Gemini rate limit (429)',
+      { kind: 'rate_limit', cause: input.cause, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) },
+    );
+  }
+
+  if (status === 401 || status === 403) {
+    // API_KEY_INVALID, PERMISSION_DENIED, etc.
+    if (lower.includes('api key not valid') || lower.includes('api_key_invalid') || lower.includes('api key expired')) {
+      return new ClassifiedProviderError(
+        `Gemini auth invalid (status ${status})`,
+        { kind: 'auth_invalid', cause: input.cause },
+      );
+    }
+    return new ClassifiedProviderError(
+      `Gemini auth error (status ${status})`,
+      { kind: 'auth_invalid', cause: input.cause },
+    );
+  }
+
+  if (status === 400) {
+    return new ClassifiedProviderError(
+      `Gemini bad request (status 400)`,
+      { kind: 'unrecoverable', cause: input.cause },
+    );
+  }
+
+  if (status !== undefined && status >= 500 && status < 600) {
+    return new ClassifiedProviderError(
+      `Gemini upstream error (status ${status})`,
+      { kind: 'transient', cause: input.cause },
+    );
+  }
+
+  // Network errors (no status) — treat as transient.
+  if (status === undefined) {
+    return new ClassifiedProviderError(
+      `Gemini network error: ${input.cause instanceof Error ? input.cause.message : String(input.cause)}`,
+      { kind: 'transient', cause: input.cause },
+    );
+  }
+
+  return new ClassifiedProviderError(
+    `Gemini API error: ${status}${body ? ` - ${body.substring(0, 200)}` : ''}`,
+    { kind: 'unrecoverable', cause: input.cause },
+  );
+}
+
 export type GeminiModel =
   | 'gemini-2.5-flash-lite'
   | 'gemini-2.5-flash'
@@ -346,26 +440,54 @@ export class GeminiProvider {
 
     await enforceRateLimitForModel(model, rateLimitingEnabled);
 
-    const response = await fetch(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        contents,
-        generationConfig: {
-          temperature: 0.3,  // Lower temperature for structured extraction
-          maxOutputTokens: 4096,
-        },
-      }),
-    });
+    // Track request-id (best-effort dedup) across retries.
+    let priorRequestId: string | null = null;
 
-    if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`Gemini API error: ${response.status} - ${error}`);
-    }
+    const data = await withRetry<GeminiResponse>(async (attemptSignal) => {
+      let response: Response;
+      try {
+        response = await fetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(priorRequestId ? { 'x-claude-mem-prior-request-id': priorRequestId } : {}),
+          },
+          body: JSON.stringify({
+            contents,
+            generationConfig: {
+              temperature: 0.3,  // Lower temperature for structured extraction
+              maxOutputTokens: 4096,
+            },
+          }),
+          signal: attemptSignal,
+        });
+      } catch (networkError: unknown) {
+        // Network failures, aborts, DNS, etc.
+        throw classifyGeminiError({
+          cause: networkError,
+        });
+      }
 
-    const data = await response.json() as GeminiResponse;
+      const requestId = response.headers.get('x-goog-request-id') ?? response.headers.get('x-request-id');
+      if (requestId) {
+        priorRequestId = requestId;
+      } else {
+        logger.debug('SDK', 'Gemini response missing request-id header; retry dedup is best-effort');
+      }
+
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw classifyGeminiError({
+          status: response.status,
+          bodyText: errorBody,
+          headers: response.headers,
+          cause: new Error(`Gemini API error: ${response.status} - ${errorBody}`),
+          ...(requestId ? { requestId } : {}),
+        });
+      }
+
+      return await response.json() as GeminiResponse;
+    }, { label: `Gemini ${model}` });
 
     if (!data.candidates?.[0]?.content?.parts?.[0]?.text) {
       logger.error('SDK', 'Empty response from Gemini');
@@ -379,7 +501,7 @@ export class GeminiProvider {
   }
 
   private getGeminiConfig(): { apiKey: string; model: GeminiModel; rateLimitingEnabled: boolean } {
-    const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+    const settingsPath = paths.settings();
     const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
 
     const apiKey = settings.CLAUDE_MEM_GEMINI_API_KEY || getCredential('GEMINI_API_KEY') || '';
@@ -414,13 +536,13 @@ export class GeminiProvider {
 }
 
 export function isGeminiAvailable(): boolean {
-  const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+  const settingsPath = paths.settings();
   const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
   return !!(settings.CLAUDE_MEM_GEMINI_API_KEY || getCredential('GEMINI_API_KEY'));
 }
 
 export function isGeminiSelected(): boolean {
-  const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+  const settingsPath = paths.settings();
   const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
   return settings.CLAUDE_MEM_PROVIDER === 'gemini';
 }

src/services/worker/OpenRouterProvider.ts

@@ -14,9 +14,99 @@ import {
   processAgentResponse,
   type WorkerRef
 } from './agents/index.js';
+import { ClassifiedProviderError } from './provider-errors.js';
+import { withRetry } from './retry.js';
 
 const OPENROUTER_API_URL = 'https://openrouter.ai/api/v1/chat/completions';
 
+/**
+ * Parse Retry-After header (seconds or HTTP-date). Returns ms or undefined.
+ */
+function parseRetryAfterMs(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (!Number.isNaN(seconds) && seconds >= 0) {
+    return Math.floor(seconds * 1000);
+  }
+  const dateMs = Date.parse(value);
+  if (!Number.isNaN(dateMs)) {
+    const delta = dateMs - Date.now();
+    return delta > 0 ? delta : 0;
+  }
+  return undefined;
+}
+
+/**
+ * Classify an OpenRouter fetch failure into ClassifiedProviderError. Called
+ * at the boundary right after `fetch()` returns or throws.
+ */
+export function classifyOpenRouterError(input: {
+  status?: number;
+  bodyText?: string;
+  headers?: Headers | { get(name: string): string | null };
+  cause: unknown;
+  requestId?: string;
+}): ClassifiedProviderError {
+  const status = input.status;
+  const body = input.bodyText ?? '';
+  const lower = body.toLowerCase();
+  const headers = input.headers;
+  const retryAfterMs = headers ? parseRetryAfterMs(headers.get('retry-after')) : undefined;
+
+  // Quota / insufficient credits — body marker takes precedence over status.
+  if (
+    lower.includes('quota exceeded') ||
+    lower.includes('insufficient credits') ||
+    lower.includes('insufficient_quota')
+  ) {
+    return new ClassifiedProviderError(
+      `OpenRouter quota exhausted${status !== undefined ? ` (status ${status})` : ''}`,
+      { kind: 'quota_exhausted', cause: input.cause },
+    );
+  }
+
+  if (status === 429) {
+    return new ClassifiedProviderError(
+      'OpenRouter rate limit (429)',
+      { kind: 'rate_limit', cause: input.cause, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) },
+    );
+  }
+
+  if (status === 401 || status === 403) {
+    return new ClassifiedProviderError(
+      `OpenRouter auth error (status ${status})`,
+      { kind: 'auth_invalid', cause: input.cause },
+    );
+  }
+
+  if (status === 400 || status === 404) {
+    return new ClassifiedProviderError(
+      `OpenRouter bad request (status ${status})`,
+      { kind: 'unrecoverable', cause: input.cause },
+    );
+  }
+
+  if (status !== undefined && status >= 500 && status < 600) {
+    return new ClassifiedProviderError(
+      `OpenRouter upstream error (status ${status})`,
+      { kind: 'transient', cause: input.cause },
+    );
+  }
+
+  // Network errors (no status) — treat as transient.
+  if (status === undefined) {
+    return new ClassifiedProviderError(
+      `OpenRouter network error: ${input.cause instanceof Error ? input.cause.message : String(input.cause)}`,
+      { kind: 'transient', cause: input.cause },
+    );
+  }
+
+  return new ClassifiedProviderError(
+    `OpenRouter API error: ${status}${body ? ` - ${body.substring(0, 200)}` : ''}`,
+    { kind: 'unrecoverable', cause: input.cause },
+  );
+}
+
 const DEFAULT_MAX_CONTEXT_MESSAGES = 20;  
 const DEFAULT_MAX_ESTIMATED_TOKENS = 100000;  
 const CHARS_PER_TOKEN_ESTIMATE = 4;  
@@ -339,32 +429,64 @@ export class OpenRouterProvider {
       estimatedTokens
     });
 
-    const response = await fetch(OPENROUTER_API_URL, {
-      method: 'POST',
-      headers: {
-        'Authorization': `Bearer ${apiKey}`,
-        'HTTP-Referer': siteUrl || 'https://github.com/thedotmack/claude-mem',
-        'X-Title': appName || 'claude-mem',
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        model,
-        messages,
-        temperature: 0.3,  // Lower temperature for structured extraction
-        max_tokens: 4096,
-      }),
-    });
+    let priorRequestId: string | null = null;
 
-    if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(`OpenRouter API error: ${response.status} - ${errorText}`);
-    }
+    const data = await withRetry<OpenRouterResponse>(async (attemptSignal) => {
+      let response: Response;
+      try {
+        response = await fetch(OPENROUTER_API_URL, {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'HTTP-Referer': siteUrl || 'https://github.com/thedotmack/claude-mem',
+            'X-Title': appName || 'claude-mem',
+            'Content-Type': 'application/json',
+            ...(priorRequestId ? { 'x-claude-mem-prior-request-id': priorRequestId } : {}),
+          },
+          body: JSON.stringify({
+            model,
+            messages,
+            temperature: 0.3,  // Lower temperature for structured extraction
+            max_tokens: 4096,
+          }),
+          signal: attemptSignal,
+        });
+      } catch (networkError: unknown) {
+        throw classifyOpenRouterError({ cause: networkError });
+      }
 
-    const data = await response.json() as OpenRouterResponse;
+      const requestId = response.headers.get('x-request-id') ?? response.headers.get('x-openrouter-request-id');
+      if (requestId) {
+        priorRequestId = requestId;
+      } else {
+        logger.debug('SDK', 'OpenRouter response missing request-id header; retry dedup is best-effort');
+      }
 
-    if (data.error) {
-      throw new Error(`OpenRouter API error: ${data.error.code} - ${data.error.message}`);
-    }
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw classifyOpenRouterError({
+          status: response.status,
+          bodyText: errorText,
+          headers: response.headers,
+          cause: new Error(`OpenRouter API error: ${response.status} - ${errorText}`),
+          ...(requestId ? { requestId } : {}),
+        });
+      }
+
+      const responseData = await response.json() as OpenRouterResponse;
+
+      if (responseData.error) {
+        // Per OpenRouter spec, errors can come in 200 responses too.
+        throw classifyOpenRouterError({
+          status: response.status,
+          bodyText: `${responseData.error.code} ${responseData.error.message ?? ''}`,
+          headers: response.headers,
+          cause: new Error(`OpenRouter API error: ${responseData.error.code} - ${responseData.error.message}`),
+        });
+      }
+
+      return responseData;
+    }, { label: `OpenRouter ${model}` });
 
     if (!data.choices?.[0]?.message?.content) {
       logger.error('SDK', 'Empty response from OpenRouter');

src/services/worker/RateLimitStore.ts

@@ -0,0 +1,223 @@
+/**
+ * Rate limit store — captures `rate_limit` system events emitted by
+ * `@anthropic-ai/claude-agent-sdk`'s `query()` stream.
+ *
+ * The SDK reports the live Claude subscription quota state as `system` events
+ * with subtype `rate_limit`. The payload includes the (currently undocumented)
+ * `rate_limit_info` shape:
+ *
+ *   {
+ *     status: "allowed" | "allowed_warning" | "rejected",
+ *     resetsAt?: number,                              // epoch ms
+ *     rateLimitType?: "five_hour" | "seven_day"
+ *                   | "seven_day_opus" | "seven_day_sonnet"
+ *                   | "overage",
+ *     utilization?: number,                           // 0..1
+ *     overageStatus?: "allowed" | "allowed_warning" | "rejected",
+ *     overageResetsAt?: number,
+ *     isUsingOverage?: boolean,
+ *     surpassedThreshold?: number,
+ *   }
+ *
+ * Pattern adapted from meridian's proxy/rateLimitStore.ts (last-write-wins
+ * per `rateLimitType` bucket, in-memory only). State resets on worker
+ * restart — that's fine, the SDK pushes a fresh event on the next request.
+ *
+ * Quota-aware abort logic gates the worker from continuing to consume a
+ * subscription bucket once it crosses a per-window threshold. API-key
+ * users are exempt because they authorized per-call spend.
+ */
+
+export type RateLimitWindow =
+  | 'five_hour'
+  | 'seven_day'
+  | 'seven_day_opus'
+  | 'seven_day_sonnet'
+  | 'overage';
+
+export interface RateLimitInfo {
+  status?: 'allowed' | 'allowed_warning' | 'rejected';
+  resetsAt?: number;
+  rateLimitType?: RateLimitWindow;
+  utilization?: number;
+  overageStatus?: 'allowed' | 'allowed_warning' | 'rejected';
+  overageResetsAt?: number;
+  isUsingOverage?: boolean;
+  surpassedThreshold?: number;
+}
+
+export interface RateLimitEntry extends RateLimitInfo {
+  observedAt: number;
+}
+
+export type RateLimitBucketKey = RateLimitWindow | 'default';
+
+export class RateLimitStore {
+  private entries = new Map<RateLimitBucketKey, RateLimitEntry>();
+
+  /**
+   * Record a rate-limit info snapshot. Last-write-wins per bucket key.
+   * Accepts both the literal `rate_limit_info` payload and a wrapping object;
+   * callers should pass the inner info.
+   */
+  set(info: RateLimitInfo | undefined | null): void {
+    if (!info || typeof info !== 'object') return;
+    const key: RateLimitBucketKey = info.rateLimitType ?? 'default';
+    this.entries.set(key, { ...info, observedAt: Date.now() });
+  }
+
+  /** Snapshot a single bucket, or undefined if not yet seen. */
+  get(type: RateLimitWindow | undefined): RateLimitEntry | undefined {
+    if (!type) return this.entries.get('default');
+    return this.entries.get(type);
+  }
+
+  /** All current entries, newest-first by observedAt. */
+  getAll(): RateLimitEntry[] {
+    return Array.from(this.entries.values()).sort(
+      (a, b) => b.observedAt - a.observedAt,
+    );
+  }
+
+  /** Latest snapshot per "interesting" window for health surface. */
+  getMostRecentByWindow(): {
+    five_hour?: RateLimitEntry;
+    seven_day?: RateLimitEntry;
+    seven_day_opus?: RateLimitEntry;
+    seven_day_sonnet?: RateLimitEntry;
+    overage?: RateLimitEntry;
+  } {
+    return {
+      five_hour: this.entries.get('five_hour'),
+      seven_day: this.entries.get('seven_day'),
+      seven_day_opus: this.entries.get('seven_day_opus'),
+      seven_day_sonnet: this.entries.get('seven_day_sonnet'),
+      overage: this.entries.get('overage'),
+    };
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /** Drop all entries — used by tests for isolation. */
+  clear(): void {
+    this.entries.clear();
+  }
+}
+
+/** Process-wide singleton. */
+export const globalRateLimitStore = new RateLimitStore();
+
+/**
+ * Per-window utilization thresholds for subscription users (cli/oauth).
+ * Crossing one of these aborts the SDK loop so we don't burn through the
+ * window on background memory work and starve interactive sessions.
+ */
+const UTILIZATION_THRESHOLDS: Record<RateLimitWindow, number> = {
+  five_hour: 0.95,
+  seven_day_opus: 0.93,
+  seven_day_sonnet: 0.92,
+  seven_day: 0.93,
+  overage: 0.95,
+};
+
+/** Reset-window grace: bail early if a window resets within this many ms. */
+const RESET_GRACE_MS = 15 * 60 * 1000; // 15 minutes
+/** Utilization floor before the reset-grace check kicks in. */
+const RESET_GRACE_UTILIZATION_FLOOR = 0.85;
+
+/**
+ * Decide whether to abort SDK consumption based on the latest rate-limit
+ * snapshot and the active auth method.
+ *
+ * - `api_key` (or any string starting with "API key"): never abort —
+ *   per-call billing means the user already authorized the spend.
+ * - `cli` / OAuth / subscription: per-window utilization thresholds plus a
+ *   reset-grace buffer so we avoid burning the last few percent right
+ *   before a window resets.
+ */
+export function shouldAbortForQuota(
+  authMethod: string,
+  store: RateLimitStore,
+  now: number = Date.now(),
+): { abort: boolean; reason?: string; window?: RateLimitWindow } {
+  // API-key users authorized per-call spend; the wall-clock guard is for
+  // subscription quota only.
+  if (isApiKeyAuth(authMethod)) {
+    return { abort: false };
+  }
+
+  const windows: RateLimitWindow[] = [
+    'five_hour',
+    'seven_day_opus',
+    'seven_day_sonnet',
+    'seven_day',
+    'overage',
+  ];
+
+  for (const window of windows) {
+    const entry = store.get(window);
+    if (!entry) continue;
+
+    const util = entry.utilization;
+    const threshold = UTILIZATION_THRESHOLDS[window];
+
+    // Provider-side rejection trumps utilization heuristics. A snapshot with
+    // status='rejected' (or overageStatus='rejected' on the overage window)
+    // means the provider has already declared the bucket exhausted; we must
+    // stop regardless of whether utilization is reported.
+    const isRejected =
+      entry.status === 'rejected' ||
+      (window === 'overage' && entry.overageStatus === 'rejected');
+
+    if (isRejected) {
+      return {
+        abort: true,
+        window,
+        reason: `quota:${window} rejected by provider`,
+      };
+    }
+
+    if (typeof util === 'number' && util >= threshold) {
+      return {
+        abort: true,
+        window,
+        reason: `quota:${window} utilization ${(util * 100).toFixed(1)}% >= ${(threshold * 100).toFixed(0)}%`,
+      };
+    }
+
+    // Reset-grace buffer: only meaningful for the rolling 5h window where
+    // a fresh bucket is imminent. Skip when utilization is low — no point
+    // bailing on a window that just reset to ~0%.
+    if (
+      window === 'five_hour' &&
+      typeof entry.resetsAt === 'number' &&
+      typeof util === 'number' &&
+      util >= RESET_GRACE_UTILIZATION_FLOOR
+    ) {
+      const msUntilReset = entry.resetsAt - now;
+      if (msUntilReset > 0 && msUntilReset <= RESET_GRACE_MS) {
+        return {
+          abort: true,
+          window,
+          reason: `quota:${window} resets in ${Math.round(msUntilReset / 60000)}m (grace buffer ${RESET_GRACE_MS / 60000}m, util ${(util * 100).toFixed(1)}%)`,
+        };
+      }
+    }
+  }
+
+  return { abort: false };
+}
+
+/**
+ * Detects API-key auth from a free-form auth-method label. Matches the
+ * verbose strings produced by `getAuthMethodDescription()` (e.g.
+ * "API key (from ~/.claude-mem/.env)") as well as concise tokens like
+ * "api_key".
+ */
+export function isApiKeyAuth(authMethod: string): boolean {
+  if (!authMethod) return false;
+  const normalized = authMethod.toLowerCase();
+  return normalized.startsWith('api key') || normalized === 'api_key';
+}

src/services/worker/agents/ResponseProcessor.ts

@@ -173,9 +173,15 @@ async function syncAndBroadcastObservations(
   agentName: string,
   projectRoot?: string
 ): Promise<void> {
-  for (let i = 0; i < observations.length; i++) {
-    const obsId = result.observationIds[i];
-    const obs = observations[i];
+  // Dedupe observation IDs before sync/broadcast: storeObservations may collapse
+  // multiple parsed observations onto the same row via content_hash, producing
+  // duplicate IDs. Syncing them 1:1 triggers repeated Chroma "IDs already exist"
+  // reconciles. See issue #2240.
+  const uniqueObservationIds = [...new Set(result.observationIds)];
+
+  for (const obsId of uniqueObservationIds) {
+    const observationIndex = result.observationIds.indexOf(obsId);
+    const obs = observations[observationIndex];
     const chromaStart = Date.now();
 
     dbManager.getChromaSync()?.syncObservation(

src/services/worker/http/routes/DataRoutes.ts

@@ -4,8 +4,7 @@ import { z } from 'zod';
 import path from 'path';
 import { readFileSync, statSync, existsSync } from 'fs';
 import { logger } from '../../../../utils/logger.js';
-import { homedir } from 'os';
-import { getPackageRoot } from '../../../../shared/paths.js';
+import { getPackageRoot, paths } from '../../../../shared/paths.js';
 import { getWorkerPort } from '../../../../shared/worker-utils.js';
 import { PaginationHelper } from '../../PaginationHelper.js';
 import { DatabaseManager } from '../../DatabaseManager.js';
@@ -17,6 +16,7 @@ import { validateBody } from '../middleware/validateBody.js';
 import { normalizePlatformSource } from '../../../../shared/platform-source.js';
 import { getObservationsByFilePath } from '../../../sqlite/observations/get.js';
 import { getFirstObservationCreatedAt } from '../../../sqlite/observations/recent.js';
+import { getUptimeSeconds } from '../../../../shared/uptime.js';
 
 const integerArrayLike = z.preprocess((value) => {
   if (Array.isArray(value)) return value;
@@ -215,13 +215,13 @@ export class DataRoutes extends BaseRouteHandler {
     const totalSummaries = db.prepare('SELECT COUNT(*) as count FROM session_summaries').get() as { count: number };
     const firstObservationAt = getFirstObservationCreatedAt(db);
 
-    const dbPath = path.join(homedir(), '.claude-mem', 'claude-mem.db');
+    const dbPath = paths.database();
     let dbSize = 0;
     if (existsSync(dbPath)) {
       dbSize = statSync(dbPath).size;
     }
 
-    const uptime = Math.floor((Date.now() - this.startTime) / 1000);
+    const uptime = getUptimeSeconds(this.startTime);
     const activeSessions = this.sessionManager.getActiveSessionCount();
     const sseClients = this.sseBroadcaster.getClientCount();
 

src/services/worker/http/routes/SessionRoutes.ts

@@ -20,6 +20,7 @@ import { getProjectContext } from '../../../../utils/project-name.js';
 import { normalizePlatformSource } from '../../../../shared/platform-source.js';
 import { handleGeneratorExit } from '../../session/GeneratorExitHandler.js';
 import { SessionCompletionHandler } from '../../session/SessionCompletionHandler.js';
+import { getUptimeSeconds } from '../../../../shared/uptime.js';
 
 const MAX_USER_PROMPT_BYTES = 256 * 1024;
 
@@ -322,7 +323,7 @@ export class SessionRoutes extends BaseRouteHandler {
       sessionDbId,
       queueLength,
       summaryStored: session.lastSummaryStored ?? null,
-      uptime: Date.now() - session.startTime
+      uptime: getUptimeSeconds(session.startTime)
     });
   });
 

src/services/worker/http/routes/SettingsRoutes.ts

@@ -3,8 +3,7 @@ import express, { Request, Response } from 'express';
 import { z } from 'zod';
 import path from 'path';
 import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync } from 'fs';
-import { homedir } from 'os';
-import { getPackageRoot } from '../../../../shared/paths.js';
+import { getPackageRoot, paths } from '../../../../shared/paths.js';
 import { logger } from '../../../../utils/logger.js';
 import { SettingsManager } from '../../SettingsManager.js';
 import { getBranchInfo, switchBranch, pullUpdates } from '../../BranchManager.js';
@@ -47,7 +46,7 @@ export class SettingsRoutes extends BaseRouteHandler {
   }
 
   private handleGetSettings = this.wrapHandler((req: Request, res: Response): void => {
-    const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+    const settingsPath = paths.settings();
     this.ensureSettingsFile(settingsPath);
     const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
     res.json(settings);
@@ -63,7 +62,7 @@ export class SettingsRoutes extends BaseRouteHandler {
       return;
     }
 
-    const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+    const settingsPath = paths.settings();
     this.ensureSettingsFile(settingsPath);
     let settings: any = {};
 
@@ -76,7 +75,7 @@ export class SettingsRoutes extends BaseRouteHandler {
         logger.error('HTTP', 'Failed to parse settings file', { settingsPath }, normalizedParseError);
         res.status(500).json({
           success: false,
-          error: 'Settings file is corrupted. Delete ~/.claude-mem/settings.json to reset.'
+          error: `Settings file is corrupted. Delete ${settingsPath} to reset.`
         });
         return;
       }

src/services/worker/knowledge/CorpusStore.ts

@@ -1,11 +1,11 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as os from 'node:os';
 import { logger } from '../../../utils/logger.js';
+import { paths } from '../../../shared/paths.js';
 import type { CorpusFile, CorpusStats } from './types.js';
 
-const CORPORA_DIR = path.join(os.homedir(), '.claude-mem', 'corpora');
+const CORPORA_DIR = paths.corpora();
 
 export class CorpusStore {
   private readonly corporaDir: string;

src/services/worker/knowledge/KnowledgeAgent.ts

@@ -1,12 +1,12 @@
 
-import { execSync } from 'child_process';
 import { CorpusStore } from './CorpusStore.js';
 import { CorpusRenderer } from './CorpusRenderer.js';
 import type { CorpusFile, QueryResult } from './types.js';
 import { logger } from '../../../utils/logger.js';
 import { SettingsDefaultsManager } from '../../../shared/SettingsDefaultsManager.js';
 import { USER_SETTINGS_PATH, OBSERVER_SESSIONS_DIR, ensureDir } from '../../../shared/paths.js';
-import { buildIsolatedEnv } from '../../../shared/EnvManager.js';
+import { buildIsolatedEnvWithFreshOAuth } from '../../../shared/EnvManager.js';
+import { findClaudeExecutable } from '../../../shared/find-claude-executable.js';
 import { sanitizeEnv } from '../../../supervisor/env-sanitizer.js';
 
 // @ts-ignore - Agent SDK types may not be available
@@ -50,8 +50,8 @@ export class KnowledgeAgent {
     ].join('\n');
 
     ensureDir(OBSERVER_SESSIONS_DIR);
-    const claudePath = this.findClaudeExecutable();
-    const isolatedEnv = sanitizeEnv(buildIsolatedEnv());
+    const claudePath = findClaudeExecutable('WORKER');
+    const isolatedEnv = sanitizeEnv(await buildIsolatedEnvWithFreshOAuth());
 
     const queryResult = query({
       prompt: primePrompt,
@@ -145,8 +145,8 @@ export class KnowledgeAgent {
 
   private async executeQuery(corpus: CorpusFile, question: string): Promise<QueryResult> {
     ensureDir(OBSERVER_SESSIONS_DIR);
-    const claudePath = this.findClaudeExecutable();
-    const isolatedEnv = sanitizeEnv(buildIsolatedEnv());
+    const claudePath = findClaudeExecutable('WORKER');
+    const isolatedEnv = sanitizeEnv(await buildIsolatedEnvWithFreshOAuth());
 
     const queryResult = query({
       prompt: question,
@@ -196,41 +196,4 @@ export class KnowledgeAgent {
     return settings.CLAUDE_MEM_MODEL;
   }
 
-  private findClaudeExecutable(): string {
-    const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
-
-    if (settings.CLAUDE_CODE_PATH) {
-      const { existsSync } = require('fs');
-      if (!existsSync(settings.CLAUDE_CODE_PATH)) {
-        throw new Error(`CLAUDE_CODE_PATH is set to "${settings.CLAUDE_CODE_PATH}" but the file does not exist.`);
-      }
-      return settings.CLAUDE_CODE_PATH;
-    }
-
-    if (process.platform === 'win32') {
-      try {
-        execSync('where claude.cmd', { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
-        return 'claude.cmd';
-      } catch {
-        // Fall through to generic detection
-      }
-    }
-
-    try {
-      const claudePath = execSync(
-        process.platform === 'win32' ? 'where claude' : 'which claude',
-        { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }
-      ).trim().split('\n')[0].trim();
-
-      if (claudePath) return claudePath;
-    } catch (error) {
-      if (error instanceof Error) {
-        logger.debug('WORKER', 'Claude executable auto-detection failed', {}, error);
-      } else {
-        logger.debug('WORKER', 'Claude executable auto-detection failed (non-Error thrown)', { thrownValue: String(error) });
-      }
-    }
-
-    throw new Error('Claude executable not found. Please either:\n1. Add "claude" to your system PATH, or\n2. Set CLAUDE_CODE_PATH in ~/.claude-mem/settings.json');
-  }
 }

src/services/worker/provider-errors.ts

@@ -0,0 +1,32 @@
+// F4 foundation: classified provider errors with extensible kind field.
+export type ProviderErrorClass =
+  | 'transient'
+  | 'unrecoverable'
+  | 'rate_limit'
+  | 'quota_exhausted'
+  | 'auth_invalid'
+  | (string & {}); // open union: providers may emit custom kinds
+
+export class ClassifiedProviderError extends Error {
+  readonly kind: ProviderErrorClass;
+  readonly retryAfterMs?: number;
+  readonly cause: unknown;
+
+  constructor(message: string, opts: {
+    kind: ProviderErrorClass;
+    cause: unknown;
+    retryAfterMs?: number;
+  }) {
+    super(message);
+    this.name = 'ClassifiedProviderError';
+    this.kind = opts.kind;
+    this.cause = opts.cause;
+    if (opts.retryAfterMs !== undefined) {
+      this.retryAfterMs = opts.retryAfterMs;
+    }
+  }
+}
+
+export function isClassified(err: unknown): err is ClassifiedProviderError {
+  return err instanceof ClassifiedProviderError;
+}

src/services/worker/retry.ts

@@ -0,0 +1,130 @@
+/**
+ * Retry helper that consumes ClassifiedProviderError.kind to decide whether to
+ * retry. Pattern adapted from open-agent-sdk's retry.ts (MIT) — exponential
+ * backoff with jitter, but driven by classified error kinds, not raw HTTP
+ * status codes.
+ *
+ * Used by GeminiProvider + OpenRouterProvider for fetch retries. Cap retries
+ * at 2 because POSTs to these APIs aren't strictly idempotent; we honor a
+ * provider-supplied request-id (best-effort) for dedup.
+ */
+
+import { ClassifiedProviderError, isClassified } from './provider-errors.js';
+import { logger } from '../../utils/logger.js';
+
+export interface RetryOptions {
+  /** Maximum retry attempts (in addition to the initial attempt). Cap=2 by default for non-idempotent POSTs. */
+  maxRetries?: number;
+  /** Per-attempt timeout in ms. Default 30s. */
+  perAttemptTimeoutMs?: number;
+  /** Base delay used for exponential backoff. Default 100ms. */
+  baseDelayMs?: number;
+  /** Cap for backoff delay. Default 30s. */
+  maxDelayMs?: number;
+  /** Tag for logging. */
+  label?: string;
+  /** External abort signal. */
+  abortSignal?: AbortSignal;
+}
+
+const DEFAULT_OPTIONS: Required<Omit<RetryOptions, 'label' | 'abortSignal'>> = {
+  maxRetries: 2,
+  perAttemptTimeoutMs: 30_000,
+  baseDelayMs: 100,
+  maxDelayMs: 30_000,
+};
+
+/** Returns true if a classified error is worth retrying. */
+export function isRetryableKind(err: unknown): boolean {
+  if (!isClassified(err)) {
+    // Unclassified errors are treated as transient (preserve old default).
+    return true;
+  }
+  return err.kind === 'transient' || err.kind === 'rate_limit';
+}
+
+/** Compute backoff delay: 100 * 2^attempt + random(50). Capped at maxDelayMs. */
+export function computeBackoffMs(attempt: number, opts: { baseDelayMs: number; maxDelayMs: number }): number {
+  const exponential = opts.baseDelayMs * Math.pow(2, attempt);
+  const jitter = Math.random() * 50;
+  return Math.min(exponential + jitter, opts.maxDelayMs);
+}
+
+/**
+ * Run `fn` with retry. `fn` receives an AbortSignal scoped to the current
+ * attempt's timeout. The classified error from `fn` (if any) drives the
+ * retry/no-retry decision. Honors `retryAfterMs` for rate_limit kind.
+ */
+export async function withRetry<T>(
+  fn: (attemptSignal: AbortSignal) => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    if (options.abortSignal?.aborted) {
+      throw new Error('Aborted');
+    }
+
+    // Per-attempt timeout via AbortController. Forward external aborts too.
+    const attemptController = new AbortController();
+    const timeoutHandle = setTimeout(() => attemptController.abort(), opts.perAttemptTimeoutMs);
+    const onExternalAbort = () => attemptController.abort();
+    options.abortSignal?.addEventListener('abort', onExternalAbort, { once: true });
+
+    try {
+      return await fn(attemptController.signal);
+    } catch (err: unknown) {
+      lastError = err;
+
+      if (!isRetryableKind(err)) {
+        throw err;
+      }
+
+      if (attempt === opts.maxRetries) {
+        throw err;
+      }
+
+      // Honor retryAfterMs from rate_limit errors; otherwise exponential backoff.
+      let delayMs: number;
+      if (isClassified(err) && err.kind === 'rate_limit' && err.retryAfterMs !== undefined) {
+        delayMs = err.retryAfterMs;
+      } else {
+        delayMs = computeBackoffMs(attempt, { baseDelayMs: opts.baseDelayMs, maxDelayMs: opts.maxDelayMs });
+      }
+
+      const errMsg = err instanceof Error ? err.message : String(err);
+      logger.warn('SDK', `Retrying ${opts.label ?? 'fetch'} after ${delayMs}ms (attempt ${attempt + 1}/${opts.maxRetries})`, {
+        kind: isClassified(err) ? err.kind : 'unclassified',
+        message: errMsg.substring(0, 200),
+      });
+      // Abort-aware sleep: an external abort during backoff should exit
+      // immediately instead of waiting out the full delay.
+      await new Promise<void>((resolve, reject) => {
+        const signal = options.abortSignal;
+        if (signal?.aborted) {
+          reject(new Error('Aborted'));
+          return;
+        }
+        const timer = setTimeout(() => {
+          signal?.removeEventListener('abort', onAbort);
+          resolve();
+        }, delayMs);
+        const onAbort = () => {
+          clearTimeout(timer);
+          reject(new Error('Aborted'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+      });
+    } finally {
+      clearTimeout(timeoutHandle);
+      options.abortSignal?.removeEventListener('abort', onExternalAbort);
+    }
+  }
+
+  // Reachable only if opts.maxRetries < 0 (loop never executed). The success
+  // and exhaustion paths both return/throw inside the loop. This guards
+  // pathological inputs and satisfies TypeScript's return-type exhaustiveness.
+  throw lastError ?? new Error('withRetry exited without an attempt (maxRetries < 0)');
+}