UX redesign: installer + provider rename + /learn-codebase + welcome card + SessionStart hint (#2255)

* feat(ux): claude-mem UX improvements with installer enhancements Squashed PR #2156 commits for clean rebase onto main: - feat(installer): add provider selection, model prompt, worker auto-start - refactor: rename *Agent provider classes to *Provider - feat: add /learn-codebase skill and viewer welcome card - feat(worker): inject welcome hint when project has zero observations - fix(pr-2156): address greptile review comments - fix(pr-2156): address coderabbit review comments - fix(pr-2156): persist CLAUDE_MEM_PROVIDER for non-claude in non-TTY mode - fix(pr-2156): file-backed settings reads in installer + env-first SKILL doc Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * build: rebuild plugin artifacts after rebase onto v12.4.7 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(skills): strip claude-mem internals from learn-codebase The learn-codebase skill, install next-step copy, WelcomeCard, and welcome-hint previously walked the primary agent through worker endpoints and synthetic observation payloads. The PostToolUse hook already captures every Read/Edit the agent makes — the agent should have no awareness that the memory layer exists. Collapse the skill to one instruction ("read every source file in full") and rephrase touchpoints to describe only what the user observes (Claude reading files), not what happens behind the scenes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(sync): preflight version mismatch + settings-aware port resolution Two related fixes for build-and-sync's worker restart step: 1. Read CLAUDE_MEM_WORKER_PORT from ~/.claude-mem/settings.json the same way the worker does, instead of computing the default port from the uid alone. Previously, users with a custom port saw a misleading "Worker not running" message because the restart POST hit the wrong port and got ECONNREFUSED. 2. Add a preflight check that aborts the sync when the running worker's reported version does not match the version we are about to build. Claude Code's plugin loader pins the worker to a specific cache version per session, so syncing into a newer cache directory has no effect until the user runs `claude plugin update thedotmack/claude-mem` to bump the pin. The preflight surfaces this explicitly with the exact command to run; --force bypasses it for intentional cases. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(learn-codebase): note sed for partial reads of large files Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor: strip comments codebase-wide Removed prose comments from all tracked source. Preserved directives (@ts-ignore, eslint-disable, biome-ignore, prettier-ignore, triple-slash references, webpack magic, shebangs). Deleted two tests that asserted on comment text rather than runtime behavior. Net: 401 files, -14,587 / +389 lines, -10.4% bytes. Verified: typecheck passes, build passes, test count unchanged from baseline (22 pre-existing fails, all unrelated). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(installer): move runtime setup into npx, eliminate hook dead air Smart-install ran 3 times during a fresh install — the worst run was silent, fired by Claude Code's Setup hook after `claude plugin install`, producing ~30s of dead air that looked like the plugin was hung. This change makes `npx claude-mem install` the single place heavy work happens, with a visible spinner. Hooks become runtime-only. - New `src/npx-cli/install/setup-runtime.ts` module: ensureBun, ensureUv, installPluginDependencies, read/writeInstallMarker, isInstallCurrent. Marker schema preserved exactly ({version, bun, uv, installedAt}) so ContextBuilder and BranchManager readers keep working. - `npx claude-mem install`: ungated copy/register/enable for every IDE, inserts a "Setting up runtime" task with honest "first install can take ~30s" spinner. The claude-code shell-out to `claude plugin install` is removed — npx already populated everything Claude reads. - New `npx claude-mem repair` command for post-`claude plugin update` recovery, force-reinstalls runtime. - Setup hook now runs `plugin/scripts/version-check.js` (29ms wall) instead of smart-install. Mismatch prints "run: npx claude-mem repair" on stderr. Always exits 0 (non-blocking, per CLAUDE.md exit-code strategy). - SessionStart loses the smart-install entry; 2 hooks remain (worker start, context fetch). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(installer): delete smart-install sources, retarget tests - Delete scripts/smart-install.js + plugin/scripts/smart-install.js (both are source files kept in sync manually; both must go). - Delete tests/smart-install.test.ts (covered surface is gone). - tests/plugin-scripts-line-endings: drop smart-install.js entry. - tests/infrastructure/plugin-distribution: retarget two assertions at version-check.js (the new Setup hook script). - New tests/setup-runtime.test.ts: 9 tests covering marker read/write, isInstallCurrent semantics. Marker schema invariant verified. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(installer): describe npx-driven setup + version-check Setup hook Sweep public docs and architecture notes to reflect the new flow: npx installer does Bun/uv setup with a visible spinner; Setup hook runs sub-100ms version-check.js; users hit `npx claude-mem repair` after a `claude plugin update`. - docs/architecture-overview.md: hook lifecycle table + npx flow paragraph - docs/public/configuration.mdx: tree + hook config example - docs/public/development.mdx: build output line - docs/public/hooks-architecture.mdx: full rewrite of pre-hook section, timing table, performance table - docs/public/architecture/{overview,hooks,worker-service}.mdx: tree comments, JSON config example, Bun requirement section docs/reports/* untouched (historical incident reports). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(install): mergeSettings writes via USER_SETTINGS_PATH Greptile P1 (#2156): `settingsFilePath()` only resolved `process.env.CLAUDE_MEM_DATA_DIR`, while `getSetting()` reads via `USER_SETTINGS_PATH` which `resolveDataDir()` populates from BOTH the env var AND a `CLAUDE_MEM_DATA_DIR` entry persisted in `~/.claude-mem/settings.json`. Result: a user with the data dir saved in settings.json but not exported in their shell would have provider/model settings silently written to `~/.claude-mem/settings.json` while `getSetting()` read from `/custom/path/settings.json` — read/write split. Drop `settingsFilePath()` and the now-unused `homedir` import; reuse the already-imported `USER_SETTINGS_PATH` constant. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(cli): parse --provider, --model, --no-auto-start install flags Greptile P1 (#2156): InstallOptions has fields `provider`, `model`, `noAutoStart`, but the install case in the npx-cli switch only parsed `--ide`. The other three flags were silently dropped — `npx claude-mem install --provider gemini` was a no-op. Extract a `parseInstallOptions(argv)` helper, share it between the bare `npx claude-mem` and `npx claude-mem install` paths, and validate `--provider` against the allowed set. Update help text accordingly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(install): pipe runtime-setup output, always show IDE multiselect Two issues caught in a docker test of the installer: 1. The bun.sh installer, uv installer, and `bun install` were using stdio: 'inherit', dumping their stdout/stderr through clack's spinner region — visible as raw "downloading uv 0.11.8…" / "Checked 58 installs across 38 packages…" text streaming under the spinner. Switch to stdio: 'pipe' and surface captured stderr only on failure (via a shared describeExecError() helper that includes stdout when stderr is empty). Spinner stays clean on the happy path. 2. promptForIDESelection() silently picked claude-code when no IDEs were detected, never showing the user the multiselect. On a fresh machine with no IDEs present yet (e.g. our docker test container), the user never got to choose. Now: always show the full IDE list when interactive; mark detected ones with [detected] hints and pre-select them; show a warn line if zero are detected explaining they should pick what they plan to use. Non-TTY callers still get the silent claude-code default at the call site (unchanged). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(install): skip marketplace work for claude-code-only, offer to install Claude Code Two related UX fixes from a docker test: **Delay between "Saved Claude model=…" and "Plugin files copied OK"** After dropping the needsManualInstall gate, every install was unconditionally running `copyPluginToMarketplace` (which copied the entire root node_modules tree — thousands of files, dozens of seconds) and `runNpmInstallInMarketplace` (npm install --production) even when only claude-code was selected. Neither is needed for claude-code: that path uses the plugin cache dir + the installed_plugins.json + enabledPlugins flag, all of which we already write. - Drop `node_modules` from `copyPluginToMarketplace`'s allowed-entries list; the dependency-install task populates it on the destination side anyway. - Re-introduce `needsMarketplace = selectedIDEs.some(id => id !== 'claude-code')` scoped *only* to `copyPluginToMarketplace`, `runNpmInstallInMarketplace`, and the pre-install `shutdownWorkerAndWait` (also pointless for claude-code- only flows since we're not overwriting the worker's running cache dir source). All other tasks (cache copy, register, enable, runtime setup) stay unconditional. **Claude Code missing → silent install of an IDE that isn't there** When the user picked claude-code on a machine without it (e.g. a fresh container), the install completed but `claude` was unavailable and the only hint was a generic warn line. Replace with an explicit pre-flight prompt: Claude Code is not installed. Claude-mem works best in Claude Code, but also works with the IDEs below. ? Install Claude Code now? ◆ Yes — install Claude Code (recommended) ◯ No — pick another IDE below ◯ Cancel installation If the user picks "Yes", run `curl -fsSL https://claude.ai/install.sh | bash` (or the PowerShell equivalent on Windows), then re-detect IDEs and proceed with claude-code pre-selected. If the install fails or the user picks "No", the multiselect still appears with claude-code visible (just unmarked [detected]), so they can opt in or pick another IDE. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(install): detect Claude Code via `claude` CLI, not ~/.claude dir The directory `~/.claude` can exist (e.g. mounted in Docker, or created by tooling) without Claude Code actually being installed. Detect the `claude` command in PATH instead so the installer correctly offers to install Claude Code when missing. * docs(learn-codebase): add reviewer note explaining the cost tradeoff The skill intentionally reads every file in full to build a cognitive cache that pays off across the rest of the project. Add a brief note so reviewers (human or bot) understand the tradeoff before flagging the unbounded read as a cost issue. * fix: address Greptile P1 feedback on welcome hint and learn-codebase - SearchRoutes: skip welcome hint when caller passes ?full=true so explicit full-context requests aren't intercepted by the hint. - learn-codebase: replace `sed` instruction with the Read tool's offset/limit parameters, since Bash is gated in Claude Code by default. * feat(install): ASCII-animated logo splash on interactive install Plays a ~1s bloom animation of the claude-mem sunburst logomark when the installer starts in an interactive terminal — geometrically rendered via 12 ray curves around a center disc, in the brand orange. The wordmark and tagline type on alongside the final frame. Auto-skipped on non-TTY, in CI, when NO_COLOR or CLAUDE_MEM_NO_BANNER is set, or when the terminal is too narrow. Inspired by ghostty +boo. * feat(banner): replace rotation frames with angular-sector bloom generator Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(banner): replace rotation frames with angular-sector bloom generator Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(banner): three-act choreography renderer with radial gradient and diff redraw Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(banner): update preview script to support small/medium/hero tier selection Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(docker): add COLORTERM=truecolor to test-installer sandbox Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(install): auto-apply PATH for Claude Code with spinner UX The Claude Code install.sh prints a Setup notes block telling users to manually edit "your shell config file" to add ~/.local/bin to PATH — which left fresh installs unable to launch claude from the command line. After a successful install, detect ~/.local/bin/claude on disk and, if the dir is missing from PATH, append the right export line to .zshrc / .bash_profile / .bashrc / fish config (idempotent, marked with a comment). Also updates process.env.PATH for the current install run. Wraps the curl|bash install in a clack spinner (interactive only) so the ~4 minute native-build download doesn't look frozen — output is captured silently and dumped on failure for debuggability. Non-interactive mode keeps inherited stdio for CI logs. Verified end-to-end in the test-installer docker sandbox: spinner animates, .bashrc gets the export, fresh login shell resolves claude. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(banner): video-frame ASCII renderer with three-act choreography Generator switched from a single Jimp-rendered logo to pre-extracted video frames concatenated with \x01 separators and gzip-deflated, ported from ghostty's boo wire format. Renderer rewritten around three acts (ignite → stagger bloom → text reveal + breathe) with adaptive sizing, radial gradient, and diff-based redraw. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(onboarding): unify install / SessionStart / viewer around one first-success moment Three surfaces now point at the same north-star moment — open the viewer, do anything in Claude Code, watch an observation appear within seconds — with the same verbatim timing and privacy lines, and a single canonical "how it works" explainer instead of three diverging copies. - Canonical explainer at src/services/worker/onboarding-explainer.md served via GET /api/onboarding/explainer; mirrored into plugin/skills/how-it-works/SKILL.md - SessionStart welcome hint rewritten as third-person status (no imperatives Claude tries to execute), pinned with a default-value regression test - Post-install Next Steps reframed as "two paths": passive default + optional /learn-codebase front-load; drops /mem-search and /knowledge-agent from this surface; adds verbatim timing + privacy lines and /how-it-works link - /api/stats response gains firstObservationAt for the viewer stat row - Viewer WelcomeCard branches on observationCount === 0: empty state shows live worker-connection dot + "waiting for activity"; has-data state shows observations · projects · since [date] and two example prompts. v2 dismiss key - jimp added to package.json to fix pre-existing banner-frame build break Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(banner): play unconditionally; only honor CLAUDE_MEM_NO_BANNER The 128-col / TTY / CI / NO_COLOR gates silently swallowed the banner in narrower terminals, CI logs, and any non-TTY pipe — including Docker runs where -it should preserve the experience but column width was the wrong gate. Remove the implicit gates; keep the explicit opt-out only. If a frame wraps in a narrow terminal, that's better than the banner not playing at all. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * revert(banner): restore 15:33 gating logic per user request Reverts eb6fc157. Restores isBannerEnabled to the state at commit 8e448015 (2026-04-30 15:33): TTY check, !CI, !NO_COLOR, !CLAUDE_MEM_NO_BANNER, and cols >= BANNER.width. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(install): wrap remaining slow steps with spinners Each IDE installer (Cursor, Gemini CLI, OpenCode, Windsurf, OpenClaw, Codex CLI, MCP integrations) now runs inside a clack task spinner with per-step progress messages instead of silent dynamic-import + cpSync. Pre-overwrite worker shutdown (up to 10s) and the post-install health probe (up to 3s) also get spinners. Internal console.log/error/warn from each IDE installer is buffered during the spinner; if the install fails, captured output is replayed afterward via log.warn so users can see what broke. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(review): observation count + IDE pre-selection regressions WelcomeCard's "no observations yet" empty state was triggered when a project filter narrowed the feed to zero rows, even with thousands of observations elsewhere. Source the count from global stats.database to match firstObservationAt's scope. Restore initialValues: [] in the IDE multiselect — pre-selecting every detected IDE was the exact regression #2106 was filed for. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(install): trichotomy worker state + cache fallback for script path ensureWorkerStarted now returns 'ready' | 'warming' | 'dead' instead of boolean. The spawned-but-still-warming case (common in Docker cold starts and slow first-time inits) was being misreported as 'did not start', which contradicted the next-steps panel saying 'still starting up'. Install task message and Next Steps headline now agree on the actual state. Also fixes the actual root cause of 'Worker did not start' on claude-code-only installs: the worker script path was hardcoded to the marketplace dir, which is left empty when no non-claude-code IDE is selected. Now falls back to pluginCacheDirectory(version) when the marketplace copy isn't present. Verified end-to-end in docker/claude-mem with --ide claude-code, --ide cursor, and a fresh container — install task and headline agree on 'Worker ready at http://localhost:<port>' in all cases. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: align CLAUDE.md and public docs with current code Sweep across CLAUDE.md and 10 high-traffic docs/public/ MDX files to remove point-in-time references and align with the actual current shape of the codebase. Highlights: - Hardcoded port 37777 → per-user formula (37700 + uid % 100) on the front-door pages (introduction, installation, configuration, architecture/overview, architecture/worker-service, troubleshooting, hooks-architecture, platform-integration). - Default model 'sonnet' → 'claude-haiku-4-5-20251001' (matches SettingsDefaultsManager). - Node 18 → 20 (matches package.json engines). - Lifecycle hook count corrected (5 events). - Removed the nonexistent 'Smart Install' component and pre-built directory tree referencing files that no longer exist (context-hook.ts, save-hook.ts, cleanup-hook.ts, etc.); replaced with the real worker dispatcher shape. - Removed CLAUDE.md '#2101' issue tag (kept the design rationale). - Replaced obsolete hooks.json example with a description of the real bun-runner.js / worker-service.cjs hook event shape. Lower-traffic doc pages still hardcode 37777 — left for a separate global pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(scripts): land strip-comments around real parsers (postcss, remark, parse5) Each language gets a real parser to locate comments, then we splice ranges out of the original source. The library never serializes — that's how remark-stringify produced 243 reformat-noise diffs in the first attempt versus the 21 real strip targets here. JS/TS/JSX -> ts.createSourceFile + getLeadingCommentRanges CSS/SCSS -> postcss.parse + walkComments + node.source offsets MD/MDX -> remark-parse (+ remark-mdx) + AST html / mdx-expression nodes HTML -> parse5 with sourceCodeLocationInfo shell/py -> kept hand-rolled hash stripper (no library worth the dep) Preserves: shebangs, @ts-* directives, eslint-disable, biome-ignore, prettier-ignore, triple-slash refs, webpack magic, /*! license keep, @strip-comments-keep file marker. JS/TS handler runs a parse-roundtrip check and refuses to write if syntax errors increased (catches the worker-utils.ts breakage class from the 2026-04-29 attempt). npm scripts: strip-comments (apply) strip-comments:check (CI-style, exits non-zero if changes needed) strip-comments:dry-run (list, no writes) Verified --check on this repo: 21 changes, -4.0% bytes, no parse-error regressions, no reformat-suspect false positives. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor: strip comments codebase-wide via parser-backed tool 21 files changed, -17,550 bytes (-4.0%) of narrative comments removed across .ts / .tsx / .js / .mjs and the .gitignore. JS/TS comments stripped via ts.createSourceFile + getLeadingCommentRanges — same canonical lexer, same behavior as the 2026-04-29 strip, no reformat noise. Preexisting baseline (unchanged): typecheck: 16 errors at HEAD, 16 errors after strip (line numbers shift, no new error classes — verified via diff of sorted error lists) build: fails at HEAD with CrushHooksInstaller.js unresolved import (preexisting, unrelated to this strip) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(install): drop Crush integration references after extract The Crush integration was extracted to its own branch on May 1, but the import at install.ts:280 (and the case block + ide-detection entry + McpIntegrations config + npx-cli help text) still referenced the now- removed CrushHooksInstaller.js, breaking the build. Removes: - case 'crush' block in install.ts - crush entry in ide-detection.ts - CRUSH_CONFIG and registration in McpIntegrations.ts - 'crush' from the IDE Identifiers help line in index.ts Rebuilds worker-service.cjs to match. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(banner): mark generated banner-frames.ts with @strip-comments-keep Without this, every build/strip cycle ping-pongs five lines of doc comments in and out of the auto-generated output. The keep-marker tells strip-comments.ts to skip the file entirely. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(build): drop banner-frame regen from build script generate-banner-frames.mjs requires PNG frames in /tmp/cmem-banner-frames that only exist after the maintainer runs ffmpeg locally on the source video. CI has neither the video nor the frames, so the build broke on Windows. The output (src/npx-cli/banner-frames.ts) is committed, so the regen is a one-shot dev step — not a build step. Run the script directly when the video changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(worker): unstick the spinner — kill claim-self-lock, wake on fail, auto-broadcast Three surgical changes that cure the stuck-spinner bug at the source. Phase 1.1 (L9): claimNextMessage no longer self-excludes its own worker_pid. A single UPDATE-RETURNING grabs the oldest pending row by id. Removes the LiveWorkerPidsProvider plumbing that was never injected — Supervisor enforces single-worker via PID file, so the multi-worker SQL was defending against a configuration the project does not support. Phase 1.2 (L19): SessionManager.markMessageFailed wraps PendingMessageStore.markFailed and emits 'message' on the per-session EventEmitter. The iterator's waitForMessage now wakes immediately on re-pend instead of parking for 3 minutes. ResponseProcessor and SessionRoutes routed through the new wrapper. Phase 1.3 (L24): PendingMessageStore takes an optional onMutate callback fired from every mutator (enqueue, claimNextMessage, confirmProcessed, markFailed, transitionMessagesTo, clearFailedOlderThan). SessionManager wires it; WorkerService passes broadcastProcessingStatus. Ten manual broadcast calls deleted across SessionCleanupHelper, SessionEventBroadcaster, SessionRoutes, DataRoutes, and worker-service. Caller discipline becomes structurally impossible to forget. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(worker): delete dead code — legacy routes, processPendingQueues, decorative guards Pure deletions. Phase 2 of kill-the-asshole-gates. - Legacy /sessions/:sessionDbId/* routes (handleSessionInit, handleObservations, handleSummarize, handleSessionStatus, handleSessionDelete, handleSessionComplete) bypassed all five ingest gates and were a parallel write path. Folded the initializeSession + broadcastNewPrompt + syncUserPrompt + ensureGeneratorRunning + broadcastSessionStarted work into the canonical /api/sessions/init handler so the hook makes one round trip instead of two. - processPendingQueues (~104 lines, zero callers) — replaced in Phase 6 by a one-statement startup sweep. - spawnInProgress Map and crashRecoveryScheduled Set — decorative dedupe over generatorPromise and stillExists checks that already provide the real safety. - STALE_GENERATOR_THRESHOLD_MS — pre-empted live generators and raced with the finally block; the 3min idle timeout already kills zombies. - MAX_SESSION_WALL_CLOCK_MS — ran a SELECT on every observation to enforce 24h. Runaway-spend protection lives in the API key, not in claude-mem. - Missing-id 400 in shared.ts ingestObservation — Zod already enforces min(1) on contentSessionId and toolName at the route schema. - SessionCompletionHandler import + completionHandler field on SessionRoutes (orphaned after handler deletions). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(worker): SQL-backed getTotalQueueDepth — single source of truth Was: iterate this.sessions.values() and sum getPendingCount per session. Now: SELECT COUNT(*) FROM pending_messages WHERE status IN ('pending','processing'). The in-memory sessions Map drifted from the DB rows whenever a generator exited without confirm/fail, leading to false-positive isProcessing in the UI. Phase 1.3's auto-broadcast fires on every mutation, but it broadcast a stale Map count. Reading from the DB makes the UI's spinner state match what the queue actually holds. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(worker): typed abortReason replaces wasAborted boolean Was: a boolean wasAborted that lumped every abort together. The finally block branched on !wasAborted, so any abort skipped restart — including idle aborts with pending work, which is exactly the case where we DO want to restart. Now: ActiveSession.abortReason is a typed enum 'idle' | 'shutdown' | 'overflow' | 'restart-guard'. The finally block consumes the reason and only skips restart for 'shutdown' and 'restart-guard'. Idle and overflow aborts fall through, so if pending work exists they trigger restart correctly. Dropped 'stale' and 'wall-clock' from the union — Phase 2 deleted those paths. Natural-completion abort (post-success) intentionally has no reason; it's not gating restart logic. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(worker): unify the two generator-exit finally blocks Was: worker-service.ts:startSessionProcessor and SessionRoutes:ensureGeneratorRunning each had their own ~70-line finally block with divergent restart-guard handling. The worker-service path called terminateSession on RestartGuard trip and orphaned pending rows (the L16 bug); the SessionRoutes path drained them. Two places to update when rules changed. Now: handleGeneratorExit in src/services/worker/session/GeneratorExitHandler.ts owns the contract: 1. Always kill the SDK subprocess if alive. 2. Always drain processingMessageIds via sessionManager.markMessageFailed (which wakes the iterator — Phase 1.2). 3. shutdown / restart-guard reasons: drain pending rows via transitionMessagesTo('failed'), finalize, remove from Map. Fixes L16. 4. pendingCount=0: finalize normally and remove from Map. 5. pendingCount>0: backoff respawn via per-session respawnTimer (no global Set; Phase 2.4 deleted that). RestartGuard trip drains to 'abandoned'. Both finally blocks are now ~10-line wrappers that translate local state into the canonical abortReason and delegate. Restored completionHandler injection into SessionRoutes (was dropped in Phase 2 cleanup; needed by the unified helper for finalizeSession). Behavior change: SessionRoutes' previous "keep idle session in memory" was deliberately replaced by the plan's "remove from Map on natural completion" — next observation reinitializes via getMessageIterator → initializeSession. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(worker): startup orphan sweep — reset 'processing' rows at boot When the worker dies (crash, kill, restart), any pending_messages rows it left in 'processing' state are by definition orphans (the only worker is dead). Single SQL UPDATE at boot resets them to 'pending' so the iterator can claim them again. Replaces the deleted processPendingQueues function (Phase 2.2). Runs in initializeBackground after dbManager.initialize() and before the initializationComplete middleware releases blocked HTTP requests, so no in-flight request can race the sweep. NOT on a periodic timer — after boot, every 'processing' row has a live consumer and a periodic sweep would race. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(worker): simplify enqueue catch, replace memorySessionId throw with re-pend 7.1: queueObservation's catch was logging two ERROR-level messages and rethrowing. The rethrow is correct (FK violations / disk full / schema drift should crash loudly), but the verbose ERROR logging pretended the error was recoverable. Reduced to one INFO line + rethrow. 7.2: ResponseProcessor's memorySessionId guard was throwing if the SDK hadn't included session_id on the first user-yield, terminal-failing the entire batch. Now warns and re-pends in-flight messages via sessionManager.markMessageFailed (which wakes the iterator — Phase 1.2). The next iteration tries again with memorySessionId hopefully captured. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(sync): mirror builds to installed-version cache for hot reload When package.json bumps past Claude Code's installed pin, sync-marketplace wrote new code to cache/<buildVersion>/ but the worker loaded from cache/<installedVersion>/, so worker:restart reloaded the same old code. Replace the exit-on-mismatch preflight with a mirror step: when versions differ, also rsync plugin/ into cache/<installedVersion>/ so worker:restart hot-reloads new code without a Claude Code session restart. The build-version cache still gets written for the eventual `claude plugin update`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: delete dead barrel files and orphan utilities - src/sdk/index.ts (re-exports parser+prompts; nothing imported the barrel) - src/services/Context.ts (re-exports ./context/index.js; no importers) - src/services/integrations/index.ts (no importers) - src/services/worker/Search.ts (3-line barrel of ./search/index.js) - src/services/infrastructure/index.ts: drop CleanupV12_4_3 re-export - src/utils/error-messages.ts (getWorkerRestartInstructions never imported) - src/types/transcript.ts (170 LoC of types, zero importers) - src/npx-cli/_preview.ts (banner dev preview, no script wires it) Build + tests still pass; observations still flowing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(parser): drop unused detectLanguage Only the user-grammar-aware variant detectLanguageWithUserGrammars() is actually called. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(types): drop unused SdkSessionRecord + ObservationWithContext Both interfaces in src/types/database.ts had zero importers anywhere in src or tests. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(npx-cli): drop unused getDetectedIDEs + claudeMemDataDirectory getDetectedIDEs has no callers — install.ts uses detectInstalledIDEs directly. claudeMemDataDirectory has no callers either. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(ProcessManager): drop dead orphan-reaper + signal-handler helpers Each had zero callers in src/ or tests/: - cleanupOrphanedProcesses + enumerateOrphanedProcesses - ORPHAN_PROCESS_PATTERNS + ORPHAN_MAX_AGE_MINUTES - forceKillProcess - waitForProcessesExit - createSignalHandler - resetWorkerRuntimePathCache The orphan reaper was retired in PATHFINDER Plan 02 ("OS process groups replace hand-rolled reapers", commit 94d592f2) — these were the leftover pieces. shutdown.ts uses the supervisor's own kill-pgid path instead. parseElapsedTime kept (covered by tests/infrastructure/process-manager.test.ts). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(scripts): delete 11 unreferenced DX/forensic scripts None of these are referenced by package.json npm scripts or docs/. All last touched on Apr 29 only as part of the comment-stripping pass — the feature code itself is older and orphaned: analyze-transformations-smart.js debug-transcript-structure.ts dump-transcript-readable.ts endless-mode-token-calculator.js extract-prompts-to-yaml.cjs extract-rich-context-examples.ts find-silent-failures.sh fix-all-timestamps.ts format-transcript-context.ts test-transcript-parser.ts transcript-to-markdown.ts These are standalone tools — runtime behavior unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(scripts): delete unused extraction/ and types/ subdirs - scripts/extraction/{extract-all-xml.py, filter-actual-xml.py, README.md} point at ~/Scripts/claude-mem/ — the user's pre-relocation path that no longer exists. Zero references in package.json, src/, or tests/. - scripts/types/export.ts duplicates ObservationRecord etc. and has no importers (CodexCliInstaller imports transcripts/types, not this). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(BranchManager): drop dead getInstalledPluginPath OpenCodeInstaller has its own (used) getInstalledPluginPath; the BranchManager copy never had any external callers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(ChromaSyncState): unexport DocKind (used internally only) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(gemini): drop stale earliestPendingTimestamp / processingMessageIds Both fields were removed from ActiveSession in earlier queue-engine cleanup. Tests had been silently keeping them because the mock sessions use 'as any' to bypass strict typing, so the dead fields rode along without complaint. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: drop 3 unused module-level constants - src/npx-cli/banner.ts: CURSOR_HOME, CLEAR_DOWN (banner uses CLEAR_SCREEN which combines clear-down + cursor-home into a single CSI sequence; the standalone constants were leftovers). - src/services/worker/BranchManager.ts: DEFAULT_SHELL_TIMEOUT_MS (BranchManager only uses GIT_COMMAND_TIMEOUT_MS / NPM_INSTALL_TIMEOUT_MS). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(opencode-plugin): drop dead workerPost helper Only the fire-and-forget variant (workerPostFireAndForget) is actually called. workerPost was the await-result version with no remaining caller. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: drop 8 truly-unused interface fields Verified each by grepping for `.field`, `"field"`, `'field'`, and `field:` patterns across src/ + tests/ + plugin/scripts. Where the only remaining usage was the assignment site, removed the assignments too. - GitHubStarsData: watchers_count, forks_count (only stargazers_count read) - TableColumnInfo: dflt_value (PRAGMA returns it but no caller reads it) - IndexInfo: seq (PRAGMA returns it but no caller reads it) - ObservationRecord: source_files (legacy field, no readers) - HookResult.hookSpecificOutput: permissionDecisionReason - WatchTarget: rescanIntervalMs (set in config, never read) - ShutdownResult: confirmedStopped (write-only — assigned but no reader; updated all 3 return sites to drop it) - ModePrompts: language_instruction (multilingual support never wired) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(npx-cli): reuse InstallOptions type instead of inline duplicate parseInstallOptions had its return type written out inline as an anonymous duplicate of InstallOptions. Use the canonical type (import type — zero bundle cost). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(integrations): drop unused Platform type alias The detectPlatform() function that returned this type was deleted earlier in the branch (along with getScriptExtension that consumed it). The type itself outlived its consumer; only string literals "Platform:" survive in console.log diagnostics, which don't reference the alias. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(worker): broadcast processing_status when summarize is queued broadcastSummarizeQueued was an empty no-op even though handleSummarizeByClaudeId calls it after enqueueing. The PendingMessageStore onMutate callback already fires broadcastProcessingStatus on enqueue, but calling it explicitly from broadcastSummarizeQueued ensures the spinner ticks on the moment a summary is requested even if the onMutate chain has any timing race. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(worker): keep spinner on while summary generates ClaudeProvider's SDK can pull multiple synthetic prompts (e.g. observation + summarize) before producing responses. Each pull pushed an ID to session.processingMessageIds. When the SDK's first observation response came back, ResponseProcessor.confirmProcessed deleted ALL pending message rows — including the still-in-flight summary — so getTotalQueueDepth dropped to 0 and the spinner turned off, even though the summary took another ~22s to actually generate. Tag each in-flight message with its type ({id, type}) so the response processor can pop only the FIFO message of the matching type (observation vs summarize). The summary row stays in 'processing' until its own response arrives, keeping the spinner lit through the entire summary window. Also updates Gemini/OpenRouter providers and GeneratorExitHandler for the new shape. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(worker): clear summary from queue on any SDK response Switch ResponseProcessor from type-aware FIFO matching to strict FIFO popping (each SDK response → 1 in-flight message consumed). This way the summary always clears when the SDK responds, even when the response is unparseable or the summary doesn't actually generate content — preventing stuck spinner / queue-depth-stuck-at-1. Spinner behavior is preserved: messages enqueued after the summary keep the queue depth elevated, and only when the SDK has responded to every prompt does the queue drain to zero. Also: when the consumed message is a 'summarize' and parsing fails, treat it as best-effort and confirmProcessed (no retry) — summaries that can't be parsed shouldn't keep retrying. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(viewer): redesign welcome card and remove source filters The first-start welcome card now explains the three feed card types (observation/summary/prompt) with color-coded badges, points users at the gear icon for settings and the project dropdown for filtering, and plugs /mem-search for recall — replacing the old two-line "ask:" prompts. Source filter tabs (Claude/Codex/etc.) are removed from the header. Filtering by AI provider was nonsense from a user POV; the project dropdown is the only header filter now. Source tracking is also stripped from useSSE, usePagination, App state, and CSS. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(viewer): keep welcome card in feed column, swap rows for 3 squares Two visible problems in the previous design: the card stretched edge-to-edge while feed cards sit in a centered 650px column, and the body was a stack of long horizontal rows that scanned line-by-line. Both fixed: Feed now accepts a pinnedTop slot so the welcome card renders inside the same .feed-content column as observation cards. Body is now a 3-column grid of square feature blocks — Live feed, Tune it, Recall it — each with a custom inline SVG illustration (stacked cards with color-coded stripes, gear+sliders, magnifier over cards). Old text-row sections (welcome-card-types, welcome-card-tips, welcome-card-section, welcome-card-tip-icon) are removed. Squares stack to one column under 600px. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(viewer): convert welcome card to glassy modal with stylized logo Card now opens as a centered modal with a frosted/glass backdrop (blur + saturate) so it doubles as a proper help dialog when reopened from the header's question-mark button. Removed the observation count, project count, and "since" date — those don't make sense for a first-launch surface and felt out of place in a help context. Header art swapped from the small webp logomark to the new high-resolution sun/sunburst PNG (claude-mem-logo-stylized.png), shipped as a checked-in asset in src/ui and plugin/ui. Bigger throughout: 28px h2, 16px tagline, 88px illustrations, 26px feature padding, 1:1 aspect-ratio squares. Backdrop click and Esc both close. Mobile collapses the grid to one column and drops the aspect-ratio constraint. Reverted the unused pinnedTop slot on Feed.tsx since the welcome card is now a true overlay rather than an in-feed pinned card. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(viewer): make welcome modal actually glassy Previous version had a 55%-opacity black backdrop that almost fully blocked the underlying UI — the "glass" was just a dark plate. Now the backdrop is fully transparent (no darkening at all), the panel itself drops to 55% bg-card opacity with its existing backdrop-filter blur(28px) saturate(170%), and the feature squares drop to 35% bg-tertiary so they layer as glass-on-glass over the already-blurred panel. The header and feed below now read clearly through the modal's frosted blur. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(viewer): bulletproof square features via padding-bottom + clamp() fluid type Squares were rendering taller than wide because aspect-ratio is treated as a minimum — content can push the box past 1:1. Switched to the classic padding-bottom: 100% trick: percentage padding resolves against the parent's width, so the box is ALWAYS W × W regardless of content. Inner content sits in an absolutely-positioned flex column that can't push the shell taller. Whole modal is now desktop-first and fluid via clamp() — no media-query stair-steps for type, padding, gaps, border-radius, illustration size, or modal width. Single mobile breakpoint at <600px collapses the grid to one column and reverts the padding-bottom trick so each feature can grow to natural content height. Tightened the three feature descriptions so they fit comfortably inside the square at the desktop size. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * style(viewer): 15% black overlay + heavier modal shadow for elevation Backdrop goes from transparent to rgba(0,0,0,0.15) — just enough darkening to push the modal visually forward without burying the underlying UI. Modal shadow stacked: 40px/120px ambient + 16px/48px contact, both deeper, plus the existing inset 1px highlight. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(build): clear pending_messages queue on build-and-sync Rewrites scripts/clear-failed-queue.ts to talk directly to SQLite via bun:sqlite — the previous HTTP endpoints (/api/pending-queue/*) were removed during the queue engine rewrite, so the script was orphaned. Wires `npm run queue:clear` into `build-and-sync` so each rebuild starts with a clean queue. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(worker): collapse parser to binary valid/invalid + clearPendingForSession model - Parser: { valid: true, observations, summary } | { valid: false } — drops kind/skipped enum dispatch - ResponseProcessor: two branches only (parseable → store + clearPendingForSession; else → no-op) - Drop processingMessageIds + per-message claim/confirm/markFailed lifecycle across 3 providers - PendingMessageStore: 226 → 140 lines; remove markFailed/transitionMessagesTo/confirmProcessed/clearFailedOlderThan/getAllPending/peekPendingTypes... wait keep peekPendingTypes - Schema migration v31+v32: drop retry_count, failed_at_epoch, completed_at_epoch, worker_pid columns - SessionQueueProcessor: delete two 1s recovery sleeps (let iterator end on error) - Server.ts/SettingsRoutes.ts: replace four magic-number setTimeout exit-flush patterns with flushResponseThen helper - GeneratorExitHandler: 183 → 117 lines (drain in-flight loop gone) Net: -181 lines. No more silent data loss via maxRetries=3. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(pr-2255): address review comments batch 1 - install.ts: needsMarketplace true when claude-code selected (P1, was no-op) - install.ts: throw on invalid --model so CLI exits non-zero - install.ts: skip worker health checks + adapt next-step copy when --no-auto-start - install.ts: repair regenerates plugin cache when missing - index.ts: readFlag rejects missing/flag-shaped values - index.ts: route flag-first invocations (e.g. `--provider claude`) to install - banner.ts: fail-open if frame payload decode throws - SearchRoutes.ts: 5s TTL cache for settings reads on hot hook path (P2) - detect-error-handling-antipatterns.ts: trailing-brace strip whitespace-tolerant - investigate-timestamps.ts: compute Dec 2025 epochs at runtime (was Dec 2024) - regenerate-claude-md.ts: include workingDir in fallback walker so root is covered - sync-marketplace.cjs: parseWorkerPort validates 1..65535 before http.request - sync-to-marketplace.sh: resolve SOURCE_DIR from script location, not cwd - Dockerfile.test-installer: bash --login sources .bashrc via .bash_profile - docs/configuration.mdx: drop nonexistent .worker.port file refs, use settings.json - docs/architecture-overview.md: dynamic port + queue model after parser collapse - docs/architecture/worker-service.mdx: dynamic port example + drop port-file claim - docs/platform-integration.mdx: WORKER_BASE_URL pattern, drop hardcoded 37777 - install/public/install.sh: Node 20 floor (was 18) to match docs Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(pr-2255): reset claimed messages to pending on early-return paths ResponseProcessor returns early in two cases: - parser invalid (unparseable response) - memorySessionId not yet captured Both paths previously left the just-claimed message in `status='processing'`, which counts toward `getPendingCount`. The generator-exit handler then sees `pendingCount > 0` and respawns the generator, looping until the restart guard trips and `clearPendingForSession` deletes the message — silent data loss. Calling `resetProcessingToPending` on these paths lets the next generator pass re-claim the message and try again, instead of burning the restart budget on no-op respawns. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(pr-2255): swebench fallback row + troubleshooting port path - evals/swebench/run-batch.py: append fallback prediction row when orchestrator future raises, preserving "never drop an instance" guarantee - docs/troubleshooting.mdx: drop nonexistent .worker.port / worker.port file references; use settings.json + /api/health for port discovery Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(pr-2255): memoize per-project observation count for welcome-hint hot path handleContextInject runs on every PostToolUse hook (after every Read/Edit). The welcome-hint block ran a COUNT(*) on observations for every call once CLAUDE_MEM_WELCOME_HINT_ENABLED was true. Observation counts are monotonically increasing — once a project has any observations it always will — so cache the positive result in a Set and skip the COUNT(*) on subsequent requests. Combined with the 5s settings TTL added earlier, the steady-state cost on the hook hot path drops to a Set lookup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(pr-2255): use clearProcessingForSession on AI-success path clearPendingForSession deletes ALL rows for the session. On the success path of processAgentResponse, that's wrong: messages that arrived as 'pending' during the (1-5s) AI response latency get deleted along with the 'processing' row we just consumed. In a hook burst (three quick PostToolUse hooks), B and C land while A is in flight; A's success then nukes B and C — silent data loss. Add a status-scoped clearProcessingForSession to PendingMessageStore + SessionManager, and use it in ResponseProcessor's success path. The unconditional clearPendingForSession remains correct in GeneratorExitHandler for hard-stop / restart-guard-trip paths. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Revert "fix(pr-2255): use clearProcessingForSession on AI-success path" This reverts commit a08995299c30cbad36bddc3e5bddda7af8604b35. --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 16:05:56 -07:00
parent 28b40c05f2
commit 9e2973059a
452 changed files with 6189 additions and 21059 deletions
@@ -3,14 +3,9 @@ import { dirname, resolve } from 'path';
 import { replaceTaggedContent } from './claude-md-utils.js';
 import { logger } from './logger.js';

-/**
- * Write AGENTS.md with claude-mem context, preserving user content outside tags.
- * Uses atomic write to prevent partial writes.
- */
 export function writeAgentsMd(agentsPath: string, context: string): void {
  if (!agentsPath) return;

-  // Never write inside .git directories — corrupts refs (#1165)
  const resolvedPath = resolve(agentsPath);
  if (resolvedPath.includes('/.git/') || resolvedPath.includes('\\.git\\') || resolvedPath.endsWith('/.git') || resolvedPath.endsWith('\\.git')) return;

@@ -1,14 +1,3 @@
-/**
- * CLAUDE.md / CLAUDE.local.md File Utilities
- *
- * Shared utilities for writing folder-level context files with
- * auto-generated context sections. Preserves user content outside
- * <claude-mem-context> tags.
- *
- * When CLAUDE_MEM_FOLDER_USE_LOCAL_MD is 'true', writes to CLAUDE.local.md
- * instead of CLAUDE.md. This keeps auto-generated context in a personal,
- * gitignored file separate from shared project instructions.
- */

 import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs';
 import path from 'path';
@@ -20,29 +9,15 @@ import { workerHttpRequest } from '../shared/worker-utils.js';

 const SETTINGS_PATH = path.join(os.homedir(), '.claude-mem', 'settings.json');

-/** Default target filename */
 const CLAUDE_MD_FILENAME = 'CLAUDE.md';

-/** Alternative target filename for personal/local context */
 const CLAUDE_LOCAL_MD_FILENAME = 'CLAUDE.local.md';

-/**
- * Get the target filename based on settings.
- * Returns 'CLAUDE.local.md' when CLAUDE_MEM_FOLDER_USE_LOCAL_MD is 'true',
- * otherwise returns 'CLAUDE.md'.
- */
 export function getTargetFilename(settings?: ReturnType<typeof SettingsDefaultsManager.loadFromFile>): string {
  const s = settings ?? SettingsDefaultsManager.loadFromFile(SETTINGS_PATH);
  return s.CLAUDE_MEM_FOLDER_USE_LOCAL_MD === 'true' ? CLAUDE_LOCAL_MD_FILENAME : CLAUDE_MD_FILENAME;
 }

-/**
- * Check for consecutive duplicate path segments like frontend/frontend/ or src/src/.
- * This catches paths created when cwd already includes the directory name (Issue #814).
- *
- * @param resolvedPath - The resolved absolute path to check
- * @returns true if consecutive duplicate segments are found
- */
 function hasConsecutiveDuplicateSegments(resolvedPath: string): boolean {
  const segments = resolvedPath.split(path.sep).filter(s => s && s !== '.' && s !== '..');
  for (let i = 1; i < segments.length; i++) {
@@ -51,41 +26,24 @@ function hasConsecutiveDuplicateSegments(resolvedPath: string): boolean {
  return false;
 }

-/**
- * Validate that a file path is safe for CLAUDE.md generation.
- * Rejects tilde paths, URLs, command-like strings, and paths with invalid chars.
- *
- * @param filePath - The file path to validate
- * @param projectRoot - Optional project root for boundary checking
- * @returns true if path is valid for CLAUDE.md processing
- */
 function isValidPathForClaudeMd(filePath: string, projectRoot?: string): boolean {
-  // Reject empty or whitespace-only
  if (!filePath || !filePath.trim()) return false;

-  // Reject tilde paths (Node.js doesn't expand ~)
  if (filePath.startsWith('~')) return false;

-  // Reject URLs
  if (filePath.startsWith('http://') || filePath.startsWith('https://')) return false;

-  // Reject paths with spaces (likely command text or PR references)
  if (filePath.includes(' ')) return false;

-  // Reject paths with # (GitHub issue/PR references)
  if (filePath.includes('#')) return false;

-  // If projectRoot provided, ensure path stays within project boundaries
  if (projectRoot) {
-    // For relative paths, resolve against projectRoot; for absolute paths, use directly
    const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(projectRoot, filePath);
    const normalizedRoot = path.resolve(projectRoot);
    if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
      return false;
    }

-    // Reject paths with consecutive duplicate segments (Issue #814)
-    // e.g., frontend/frontend/, backend/backend/, src/src/
    if (hasConsecutiveDuplicateSegments(resolved)) {
      return false;
    }
@@ -94,24 +52,14 @@ function isValidPathForClaudeMd(filePath: string, projectRoot?: string): boolean
  return true;
 }

-/**
- * Replace tagged content in existing file, preserving content outside tags.
- *
- * Handles three cases:
- * 1. No existing content → wraps new content in tags
- * 2. Has existing tags → replaces only tagged section
- * 3. No tags in existing content → appends tagged content at end
- */
 export function replaceTaggedContent(existingContent: string, newContent: string): string {
  const startTag = '<claude-mem-context>';
  const endTag = '</claude-mem-context>';

-  // If no existing content, wrap new content in tags
  if (!existingContent) {
    return `${startTag}\n${newContent}\n${endTag}`;
  }

-  // If existing has tags, replace only tagged section
  const startIdx = existingContent.indexOf(startTag);
  const endIdx = existingContent.indexOf(endTag);

@@ -121,109 +69,69 @@ export function replaceTaggedContent(existingContent: string, newContent: string
      existingContent.substring(endIdx + endTag.length);
  }

-  // If no tags exist, append tagged content at end
  return existingContent + `\n\n${startTag}\n${newContent}\n${endTag}`;
 }

-/**
- * Write CLAUDE.md file to folder with atomic writes.
- * Only writes to existing folders; skips non-existent paths to prevent
- * creating spurious directory structures from malformed paths.
- *
- * @param folderPath - Absolute path to the folder (must already exist)
- * @param newContent - Content to write inside tags
- * @param targetFilename - Target filename (default: determined by settings)
- */
 export function writeClaudeMdToFolder(folderPath: string, newContent: string, targetFilename?: string): void {
  const resolvedPath = path.resolve(folderPath);

-  // Never write inside .git directories — corrupts refs (#1165)
  if (resolvedPath.includes('/.git/') || resolvedPath.includes('\\.git\\') || resolvedPath.endsWith('/.git') || resolvedPath.endsWith('\\.git')) return;

  const filename = targetFilename ?? getTargetFilename();
  const claudeMdPath = path.join(folderPath, filename);
  const tempFile = `${claudeMdPath}.tmp`;

-  // Only write to folders that already exist - never create new directories
-  // This prevents creating spurious folder structures from malformed paths
  if (!existsSync(folderPath)) {
    logger.debug('FOLDER_INDEX', 'Skipping non-existent folder', { folderPath });
    return;
  }

-  // Read existing content if file exists
  let existingContent = '';
  if (existsSync(claudeMdPath)) {
    existingContent = readFileSync(claudeMdPath, 'utf-8');
  }

-  // Replace only tagged content, preserve user content
  const finalContent = replaceTaggedContent(existingContent, newContent);

-  // Atomic write: temp file + rename
  writeFileSync(tempFile, finalContent);
  renameSync(tempFile, claudeMdPath);
 }

-/**
- * Parsed observation from API response text
- */
 interface ParsedObservation {
  id: string;
  time: string;
  typeEmoji: string;
  title: string;
  tokens: string;
-  epoch: number; // For date grouping
+  epoch: number; 
 }

-/**
- * Format timeline text from API response to timeline format.
- *
- * Uses the same format as search results:
- * - Grouped by date (### Jan 4, 2026)
- * - Grouped by file within each date (**filename**)
- * - Table with columns: ID, Time, T (type emoji), Title, Read (tokens)
- * - Ditto marks for repeated times
- *
- * @param timelineText - Raw API response text
- * @returns Formatted markdown with date/file grouping
- */
 export function formatTimelineForClaudeMd(timelineText: string): string {
  const lines: string[] = [];
  lines.push('# Recent Activity');
  lines.push('');

-  // Parse the API response to extract observation rows
  const apiLines = timelineText.split('\n');

-  // Note: We skip file grouping since we're querying by folder - all results are from the same folder
-
-  // Parse observations: | #123 | 4:30 PM | 🔧 | Title | ~250 | ... |
  const observations: ParsedObservation[] = [];
  let lastTimeStr = '';
  let currentDate: Date | null = null;

  for (const line of apiLines) {
-    // Check for date headers: ### Jan 4, 2026
    const dateMatch = line.match(/^###\s+(.+)$/);
    if (dateMatch) {
      const dateStr = dateMatch[1].trim();
      const parsedDate = new Date(dateStr);
-      // Validate the parsed date
      if (!isNaN(parsedDate.getTime())) {
        currentDate = parsedDate;
      }
      continue;
    }

-    // Match table rows: | #123 | 4:30 PM | 🔧 | Title | ~250 | ... |
-    // Also handles ditto marks and session IDs (#S123)
    const match = line.match(/^\|\s*(#[S]?\d+)\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|/);
    if (match) {
      const [, id, timeStr, typeEmoji, title, tokens] = match;

-      // Handle ditto mark (″) - use last time
      let time: string;
      if (timeStr.trim() === '″' || timeStr.trim() === '"') {
        time = lastTimeStr;
@@ -232,7 +140,6 @@ export function formatTimelineForClaudeMd(timelineText: string): string {
        lastTimeStr = time;
      }

-      // Parse time and combine with current date header (or fallback to today)
      const baseDate = currentDate ? new Date(currentDate) : new Date();
      const timeParts = time.match(/(\d+):(\d+)\s*(AM|PM)/i);
      let epoch = baseDate.getTime();
@@ -261,10 +168,8 @@ export function formatTimelineForClaudeMd(timelineText: string): string {
    return '';
  }

-  // Group by date
  const byDate = groupByDate(observations, obs => new Date(obs.epoch).toISOString());

-  // Render each date group
  for (const [day, dayObs] of byDate) {
    lines.push(`### ${day}`);
    lines.push('');
@@ -284,10 +189,6 @@ export function formatTimelineForClaudeMd(timelineText: string): string {
  return lines.join('\n').trim();
 }

-/**
- * Built-in directory names where CLAUDE.md generation is unsafe or undesirable.
- * e.g. Android res/ is compiler-strict (non-XML breaks build); .git, build, node_modules are tooling-owned.
- */
 const EXCLUDED_UNSAFE_DIRECTORIES = new Set([
  'res',
  '.git',
@@ -296,32 +197,17 @@ const EXCLUDED_UNSAFE_DIRECTORIES = new Set([
  '__pycache__'
 ]);

-/**
- * Returns true if folder path contains any excluded segment (e.g. .../res/..., .../node_modules/...).
- */
 function isExcludedUnsafeDirectory(folderPath: string): boolean {
  const normalized = path.normalize(folderPath);
  const segments = normalized.split(path.sep);
  return segments.some(segment => EXCLUDED_UNSAFE_DIRECTORIES.has(segment));
 }

-/**
- * Check if a folder is a project root (contains .git directory).
- * Project root CLAUDE.md files should remain user-managed, not auto-updated.
- */
 function isProjectRoot(folderPath: string): boolean {
  const gitPath = path.join(folderPath, '.git');
  return existsSync(gitPath);
 }

-/**
- * Check if a folder path is excluded from CLAUDE.md generation.
- * A folder is excluded if it matches or is within any path in the exclude list.
- *
- * @param folderPath - Absolute path to check
- * @param excludePaths - Array of paths to exclude
- * @returns true if folder should be excluded
- */
 function isExcludedFolder(folderPath: string, excludePaths: string[]): boolean {
  const normalizedFolder = path.resolve(folderPath);
  for (const excludePath of excludePaths) {
@@ -334,29 +220,16 @@ function isExcludedFolder(folderPath: string, excludePaths: string[]): boolean {
  return false;
 }

-/**
- * Update CLAUDE.md files for folders containing the given files.
- * Fetches timeline from worker API and writes formatted content.
- *
- * NOTE: Project root folders (containing .git) are excluded to preserve
- * user-managed root CLAUDE.md files. Only subfolder CLAUDE.md files are auto-updated.
- *
- * @param filePaths - Array of absolute file paths (modified or read)
- * @param project - Project identifier for API query
- * @param _port - Worker API port (legacy, now resolved automatically via socket/TCP)
- */
 export async function updateFolderClaudeMdFiles(
  filePaths: string[],
  project: string,
  _port: number,
  projectRoot?: string
 ): Promise<void> {
-  // Load settings to get configurable observation limit, exclude list, and target filename
  const settings = SettingsDefaultsManager.loadFromFile(SETTINGS_PATH);
  const limit = parseInt(settings.CLAUDE_MEM_CONTEXT_OBSERVATIONS, 10) || 50;
  const targetFilename = getTargetFilename(settings);

-  // Parse exclude paths from settings
  let folderMdExcludePaths: string[] = [];
  try {
    const parsed = JSON.parse(settings.CLAUDE_MEM_FOLDER_MD_EXCLUDE || '[]');
@@ -367,12 +240,8 @@ export async function updateFolderClaudeMdFiles(
    logger.warn('FOLDER_INDEX', 'Failed to parse CLAUDE_MEM_FOLDER_MD_EXCLUDE setting');
  }

-  // Track folders containing CLAUDE.md files that were read/modified in this observation.
-  // We must NOT update these - it would cause "file modified since read" errors in Claude Code.
-  // See: https://github.com/thedotmack/claude-mem/issues/859
  const foldersWithActiveClaudeMd = new Set<string>();

-  // First pass: identify folders with actively-used CLAUDE.md or CLAUDE.local.md files
  for (const filePath of filePaths) {
    if (!filePath) continue;
    const basename = path.basename(filePath);
@@ -387,11 +256,9 @@ export async function updateFolderClaudeMdFiles(
    }
  }

-  // Extract unique folder paths from file paths
  const folderPaths = new Set<string>();
  for (const filePath of filePaths) {
    if (!filePath || filePath === '') continue;
-    // VALIDATE PATH BEFORE PROCESSING
    if (!isValidPathForClaudeMd(filePath, projectRoot)) {
      logger.debug('FOLDER_INDEX', 'Skipping invalid file path', {
        filePath,
@@ -399,29 +266,24 @@ export async function updateFolderClaudeMdFiles(
      });
      continue;
    }
-    // Resolve relative paths to absolute using projectRoot
    let absoluteFilePath = filePath;
    if (projectRoot && !path.isAbsolute(filePath)) {
      absoluteFilePath = path.join(projectRoot, filePath);
    }
    const folderPath = path.dirname(absoluteFilePath);
    if (folderPath && folderPath !== '.' && folderPath !== '/') {
-      // Skip project root - root CLAUDE.md should remain user-managed
      if (isProjectRoot(folderPath)) {
        logger.debug('FOLDER_INDEX', 'Skipping project root CLAUDE.md', { folderPath });
        continue;
      }
-      // Skip known-unsafe directories (e.g. Android res/, .git, build, node_modules)
      if (isExcludedUnsafeDirectory(folderPath)) {
        logger.debug('FOLDER_INDEX', 'Skipping unsafe directory for CLAUDE.md', { folderPath });
        continue;
      }
-      // Skip folders where CLAUDE.md was read/modified in this observation (issue #859)
      if (foldersWithActiveClaudeMd.has(folderPath)) {
        logger.debug('FOLDER_INDEX', 'Skipping folder with active CLAUDE.md to avoid race condition', { folderPath });
        continue;
      }
-      // Skip folders in user-configured exclude list
      if (folderMdExcludePaths.length > 0 && isExcludedFolder(folderPath, folderMdExcludePaths)) {
        logger.debug('FOLDER_INDEX', 'Skipping excluded folder', { folderPath });
        continue;
@@ -437,16 +299,13 @@ export async function updateFolderClaudeMdFiles(
    folderCount: folderPaths.size
  });

-  // Process each folder
  for (const folderPath of folderPaths) {
    let response: Response;
    try {
-      // Fetch timeline via existing API (uses socket or TCP automatically)
      response = await workerHttpRequest(
        `/api/search/by-file?filePath=${encodeURIComponent(folderPath)}&limit=${limit}&project=${encodeURIComponent(project)}&isFolder=true`
      );
    } catch (error: unknown) {
-      // Fire-and-forget: log warning but don't fail
      const message = error instanceof Error ? error.message : String(error);
      const stack = error instanceof Error ? error.stack : undefined;
      logger.error('FOLDER_INDEX', `Failed to fetch timeline for ${targetFilename}`, {
@@ -470,8 +329,6 @@ export async function updateFolderClaudeMdFiles(

    const formatted = formatTimelineForClaudeMd(result.content[0].text);

-    // Fix for #794: Don't create new context files if there's no activity
-    // But update existing ones to show "No recent activity" if they already exist
    const claudeMdPath = path.join(folderPath, targetFilename);
    const hasNoActivity = formatted.includes('*No recent activity*');
    const fileExists = existsSync(claudeMdPath);
@@ -1,34 +1,10 @@
-/**
- * Shared context injection utilities for claude-mem.
- *
- * Provides tag constants and a function to inject or update a
- * <claude-mem-context> section in any markdown file. Used by
- * MCP integrations and OpenCode installer.
- */

 import path from 'path';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';

-// ============================================================================
-// Tag Constants
-// ============================================================================
-
 export const CONTEXT_TAG_OPEN = '<claude-mem-context>';
 export const CONTEXT_TAG_CLOSE = '</claude-mem-context>';

-// ============================================================================
-// Context Injection
-// ============================================================================
-
-/**
- * Inject or update a <claude-mem-context> section in a markdown file.
- * Creates the file if it doesn't exist. Preserves content outside the tags.
- *
- * @param filePath - Absolute path to the target markdown file.
- * @param contextContent - The content to place between the context tags.
- * @param headerLine - Optional first line written when creating a new file
- *                     (e.g. `"# Claude-Mem Memory Context"` for AGENTS.md).
- */
 export function injectContextIntoMarkdownFile(
  filePath: string,
  contextContent: string,
@@ -46,19 +22,16 @@ export function injectContextIntoMarkdownFile(
    const tagEndIndex = existingContent.indexOf(CONTEXT_TAG_CLOSE);

    if (tagStartIndex !== -1 && tagEndIndex !== -1) {
-      // Replace existing section
      existingContent =
        existingContent.slice(0, tagStartIndex) +
        wrappedContent +
        existingContent.slice(tagEndIndex + CONTEXT_TAG_CLOSE.length);
    } else {
-      // Append section
      existingContent = existingContent.trimEnd() + '\n\n' + wrappedContent + '\n';
    }

    writeFileSync(filePath, existingContent, 'utf-8');
  } else {
-    // Create new file
    if (headerLine) {
      writeFileSync(filePath, `${headerLine}\n\n${wrappedContent}\n`, 'utf-8');
    } else {
@@ -1,18 +1,8 @@
-/**
- * Cursor Integration Utilities
- *
- * Pure functions for Cursor project registry, context files, and MCP configuration.
- * Designed for testability - all file paths are passed as parameters.
- */

 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'fs';
 import { join, basename } from 'path';
 import { logger } from './logger.js';

-// ============================================================================
-// Types
-// ============================================================================
-
 export interface CursorProjectRegistry {
  [projectName: string]: {
    workspacePath: string;
@@ -30,13 +20,6 @@ export interface CursorMcpConfig {
  };
 }

-// ============================================================================
-// Project Registry Functions
-// ============================================================================
-
-/**
- * Read the Cursor project registry from a file
- */
 export function readCursorRegistry(registryFile: string): CursorProjectRegistry {
  try {
    if (!existsSync(registryFile)) return {};
@@ -50,18 +33,12 @@ export function readCursorRegistry(registryFile: string): CursorProjectRegistry
  }
 }

-/**
- * Write the Cursor project registry to a file
- */
 export function writeCursorRegistry(registryFile: string, registry: CursorProjectRegistry): void {
  const dir = join(registryFile, '..');
  mkdirSync(dir, { recursive: true });
  writeFileSync(registryFile, JSON.stringify(registry, null, 2));
 }

-/**
- * Register a project in the Cursor registry
- */
 export function registerCursorProject(
  registryFile: string,
  projectName: string,
@@ -75,9 +52,6 @@ export function registerCursorProject(
  writeCursorRegistry(registryFile, registry);
 }

-/**
- * Unregister a project from the Cursor registry
- */
 export function unregisterCursorProject(registryFile: string, projectName: string): void {
  const registry = readCursorRegistry(registryFile);
  if (registry[projectName]) {
@@ -86,14 +60,6 @@ export function unregisterCursorProject(registryFile: string, projectName: strin
  }
 }

-// ============================================================================
-// Context File Functions
-// ============================================================================
-
-/**
- * Write context file to a Cursor project's .cursor/rules directory
- * Uses atomic write (temp file + rename) to prevent corruption
- */
 export function writeContextFile(workspacePath: string, context: string): void {
  const rulesDir = join(workspacePath, '.cursor', 'rules');
  const rulesFile = join(rulesDir, 'claude-mem-context.mdc');
@@ -116,33 +82,20 @@ ${context}
 *Updated after last session. Use claude-mem's MCP search tools for more detailed queries.*
 `;

-  // Atomic write: temp file + rename
  writeFileSync(tempFile, content);
  renameSync(tempFile, rulesFile);
 }

-/**
- * Read context file from a Cursor project's .cursor/rules directory
- */
 export function readContextFile(workspacePath: string): string | null {
  const rulesFile = join(workspacePath, '.cursor', 'rules', 'claude-mem-context.mdc');
  if (!existsSync(rulesFile)) return null;
  return readFileSync(rulesFile, 'utf-8');
 }

-// ============================================================================
-// MCP Configuration Functions
-// ============================================================================
-
-/**
- * Configure claude-mem MCP server in Cursor's mcp.json
- * Preserves existing MCP servers
- */
 export function configureCursorMcp(mcpJsonPath: string, mcpServerScriptPath: string): void {
  const dir = join(mcpJsonPath, '..');
  mkdirSync(dir, { recursive: true });

-  // Load existing config or create new
  let config: CursorMcpConfig = { mcpServers: {} };
  if (existsSync(mcpJsonPath)) {
    try {
@@ -159,7 +112,6 @@ export function configureCursorMcp(mcpJsonPath: string, mcpServerScriptPath: str
    }
  }

-  // Add claude-mem MCP server
  config.mcpServers['claude-mem'] = {
    command: 'node',
    args: [mcpServerScriptPath]
@@ -168,10 +120,6 @@ export function configureCursorMcp(mcpJsonPath: string, mcpServerScriptPath: str
  writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2));
 }

-/**
- * Remove claude-mem MCP server from Cursor's mcp.json
- * Preserves other MCP servers
- */
 export function removeMcpConfig(mcpJsonPath: string): void {
  if (!existsSync(mcpJsonPath)) return;

@@ -189,14 +137,6 @@ export function removeMcpConfig(mcpJsonPath: string): void {
  }
 }

-// ============================================================================
-// JSON Utility Functions (mirrors common.sh logic)
-// ============================================================================
-
-/**
- * Parse array field syntax like "workspace_roots[0]"
- * Returns null for simple fields
- */
 export function parseArrayField(field: string): { field: string; index: number } | null {
  const match = field.match(/^(.+)\[(\d+)\]$/);
  if (!match) return null;
@@ -206,10 +146,6 @@ export function parseArrayField(field: string): { field: string; index: number }
  };
 }

-/**
- * Extract JSON field with fallback (mirrors common.sh json_get)
- * Supports array access like "field[0]"
- */
 export function jsonGet(json: Record<string, unknown>, field: string, fallback: string = ''): string {
  const arrayAccess = parseArrayField(field);

@@ -226,19 +162,14 @@ export function jsonGet(json: Record<string, unknown>, field: string, fallback:
  return String(value);
 }

-/**
- * Get project name from workspace path (mirrors common.sh get_project_name)
- */
 export function getProjectName(workspacePath: string): string {
  if (!workspacePath) return 'unknown-project';

-  // Handle Windows drive root (C:\ or C:)
  const driveMatch = workspacePath.match(/^([A-Za-z]):[\\\/]?$/);
  if (driveMatch) {
    return `drive-${driveMatch[1].toUpperCase()}`;
  }

-  // Normalize to forward slashes for cross-platform support
  const normalized = workspacePath.replace(/\\/g, '/');
  const name = basename(normalized);

@@ -249,10 +180,6 @@ export function getProjectName(workspacePath: string): string {
  return name;
 }

-/**
- * Check if string is empty/null (mirrors common.sh is_empty)
- * Also treats jq's literal "null" string as empty
- */
 export function isEmpty(str: string | null | undefined): boolean {
  if (str === null || str === undefined) return true;
  if (str === '') return true;
@@ -261,9 +188,6 @@ export function isEmpty(str: string | null | undefined): boolean {
  return false;
 }

-/**
- * URL encode a string (mirrors common.sh url_encode)
- */
 export function urlEncode(str: string): string {
  return encodeURIComponent(str);
 }
@@ -1,47 +0,0 @@
-/**
- * Platform-aware error message generator for worker connection failures
- */
-
-export interface WorkerErrorMessageOptions {
-  port?: number;
-  includeSkillFallback?: boolean;
-  customPrefix?: string;
-  actualError?: string;
-}
-
-/**
- * Generate platform-specific worker restart instructions
- * @param options Configuration for error message generation
- * @returns Formatted error message with platform-specific paths and commands
- */
-export function getWorkerRestartInstructions(
-  options: WorkerErrorMessageOptions = {}
-): string {
-  const {
-    port,
-    includeSkillFallback = false,
-    customPrefix,
-    actualError
-  } = options;
-
-  // Build error message
-  const prefix = customPrefix || 'Worker service connection failed.';
-  const portInfo = port ? ` (port ${port})` : '';
-
-  let message = `${prefix}${portInfo}\n\n`;
-  message += `To restart the worker:\n`;
-  message += `1. Exit Claude Code completely\n`;
-  message += `2. Run: npm run worker:restart\n`;
-  message += `3. Restart Claude Code`;
-
-  if (includeSkillFallback) {
-    message += `\n\nIf that doesn't work, try: /troubleshoot`;
-  }
-
-  // Prepend actual error if provided
-  if (actualError) {
-    message = `Worker Error: ${actualError}\n\n${message}`;
-  }
-
-  return message;
-}
@@ -1,22 +1,7 @@
-/**
- * Shared JSON file utilities for claude-mem.
- *
- * Provides safe read/write helpers used across the CLI and services.
- */

 import { existsSync, readFileSync } from 'fs';
 import { logger } from './logger.js';

-/**
- * Read a JSON file safely, returning a default value if the file
- * does not exist. Throws on corrupt JSON to prevent silent data loss
- * when callers merge and write back.
- *
- * @param filePath - Absolute path to the JSON file.
- * @param defaultValue - Value returned when the file is missing.
- * @returns The parsed JSON content, or `defaultValue` when file is missing.
- * @throws {Error} When the file exists but contains invalid JSON.
- */
 export function readJsonSafe<T>(filePath: string, defaultValue: T): T {
  if (!existsSync(filePath)) return defaultValue;
  try {
@@ -1,7 +1,3 @@
-/**
- * Structured Logger for claude-mem Worker Service
- * Provides readable, traceable logging with correlation IDs and data flow tracking
- */

 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'fs';
 import { join } from 'path';
@@ -59,8 +55,6 @@ interface LogContext {
  [key: string]: any;
 }

-// NOTE: This default must match DEFAULT_DATA_DIR in src/shared/SettingsDefaultsManager.ts
-// Inlined here to avoid circular dependency with SettingsDefaultsManager
 const DEFAULT_DATA_DIR = join(homedir(), '.claude-mem');

 class Logger {
@@ -70,46 +64,32 @@ class Logger {
  private logFileInitialized: boolean = false;

  constructor() {
-    // Disable colors when output is not a TTY (e.g., PM2 logs)
    this.useColor = process.stdout.isTTY ?? false;
    // Don't initialize log file in constructor - do it lazily to avoid circular dependency
  }

-  /**
-   * Initialize log file path and ensure directory exists (lazy initialization)
-   */
  private ensureLogFileInitialized(): void {
    if (this.logFileInitialized) return;
    this.logFileInitialized = true;

    try {
-      // Use default data directory to avoid circular dependency with SettingsDefaultsManager
-      // The log directory is always based on the default, not user settings
      const logsDir = join(DEFAULT_DATA_DIR, 'logs');

-      // Ensure logs directory exists
      if (!existsSync(logsDir)) {
        mkdirSync(logsDir, { recursive: true });
      }

-      // Create log file path with date
      const date = new Date().toISOString().split('T')[0];
      this.logFilePath = join(logsDir, `claude-mem-${date}.log`);
    } catch (error: unknown) {
-      // [ANTI-PATTERN IGNORED]: Logger cannot log its own failures, using stderr/console as last resort
      console.error('[LOGGER] Failed to initialize log file:', error instanceof Error ? error.message : String(error));
      this.logFilePath = null;
    }
  }

-  /**
-   * Lazy-load log level from settings file
-   * Uses direct file reading to avoid circular dependency with SettingsDefaultsManager
-   */
  private getLevel(): LogLevel {
    if (this.level === null) {
      try {
-        // Read settings file directly to avoid circular dependency
        const settingsPath = join(DEFAULT_DATA_DIR, 'settings.json');
        if (existsSync(settingsPath)) {
          const settingsData = readFileSync(settingsPath, 'utf-8');
@@ -120,7 +100,6 @@ class Logger {
          this.level = LogLevel.INFO;
        }
      } catch (error: unknown) {
-        // [ANTI-PATTERN IGNORED]: Logger cannot log its own failures, using stderr/console as last resort
        console.error('[LOGGER] Failed to load log level from settings:', error instanceof Error ? error.message : String(error));
        this.level = LogLevel.INFO;
      }
@@ -128,48 +107,34 @@ class Logger {
    return this.level;
  }

-  /**
-   * Create correlation ID for tracking an observation through the pipeline
-   */
  correlationId(sessionId: number, observationNum: number): string {
    return `obs-${sessionId}-${observationNum}`;
  }

-  /**
-   * Create session correlation ID
-   */
  sessionId(sessionId: number): string {
    return `session-${sessionId}`;
  }

-  /**
-   * Format data for logging - create compact summaries instead of full dumps
-   */
  private formatData(data: any): string {
    if (data === null || data === undefined) return '';
    if (typeof data === 'string') return data;
    if (typeof data === 'number') return data.toString();
    if (typeof data === 'boolean') return data.toString();

-    // For objects, create compact summaries
    if (typeof data === 'object') {
-      // If it's an error, show message and stack in debug mode
      if (data instanceof Error) {
        return this.getLevel() === LogLevel.DEBUG
          ? `${data.message}\n${data.stack}`
          : data.message;
      }

-      // For arrays, show count
      if (Array.isArray(data)) {
        return `[${data.length} items]`;
      }

-      // For objects, show key count
      const keys = Object.keys(data);
      if (keys.length === 0) return '{}';
      if (keys.length <= 3) {
-        // Show small objects inline
        return JSON.stringify(data);
      }
      return `{${keys.length} keys: ${keys.slice(0, 3).join(', ')}...}`;
@@ -178,9 +143,6 @@ class Logger {
    return String(data);
  }

-  /**
-   * Format a tool name and input for compact display
-   */
  formatTool(toolName: string, toolInput?: any): string {
    if (!toolInput) return toolName;

@@ -189,37 +151,30 @@ class Logger {
      try {
        input = JSON.parse(toolInput);
      } catch (_parseError: unknown) {
-        // Input is a raw string (e.g., Bash command), use as-is — JSON.parse failure is expected here
        input = toolInput;
      }
    }

-    // Bash: show full command
    if (toolName === 'Bash' && input.command) {
      return `${toolName}(${input.command})`;
    }

-    // File operations: show full path
    if (input.file_path) {
      return `${toolName}(${input.file_path})`;
    }

-    // NotebookEdit: show full notebook path
    if (input.notebook_path) {
      return `${toolName}(${input.notebook_path})`;
    }

-    // Glob: show full pattern
    if (toolName === 'Glob' && input.pattern) {
      return `${toolName}(${input.pattern})`;
    }

-    // Grep: show full pattern
    if (toolName === 'Grep' && input.pattern) {
      return `${toolName}(${input.pattern})`;
    }

-    // WebFetch/WebSearch: show full URL or query
    if (input.url) {
      return `${toolName}(${input.url})`;
    }
@@ -228,7 +183,6 @@ class Logger {
      return `${toolName}(${input.query})`;
    }

-    // Task: show subagent_type or full description
    if (toolName === 'Task') {
      if (input.subagent_type) {
        return `${toolName}(${input.subagent_type})`;
@@ -238,23 +192,17 @@ class Logger {
      }
    }

-    // Skill: show skill name
    if (toolName === 'Skill' && input.skill) {
      return `${toolName}(${input.skill})`;
    }

-    // LSP: show operation type
    if (toolName === 'LSP' && input.operation) {
      return `${toolName}(${input.operation})`;
    }

-    // Default: just show tool name
    return toolName;
  }

-  /**
-   * Format timestamp in local timezone (YYYY-MM-DD HH:MM:SS.mmm)
-   */
  private formatTimestamp(date: Date): string {
    const year = date.getFullYear();
    const month = String(date.getMonth() + 1).padStart(2, '0');
@@ -266,9 +214,6 @@ class Logger {
    return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${ms}`;
  }

-  /**
-   * Core logging method
-   */
  private log(
    level: LogLevel,
    component: Component,
@@ -278,14 +223,12 @@ class Logger {
  ): void {
    if (level < this.getLevel()) return;

-    // Lazy initialize log file on first use
    this.ensureLogFileInitialized();

    const timestamp = this.formatTimestamp(new Date());
    const levelStr = LogLevel[level].padEnd(5);
    const componentStr = component.padEnd(6);

-    // Build correlation ID part
    let correlationStr = '';
    if (context?.correlationId) {
      correlationStr = `[${context.correlationId}] `;
@@ -293,18 +236,13 @@ class Logger {
      correlationStr = `[session-${context.sessionId}] `;
    }

-    // Build data part
    let dataStr = '';
    if (data !== undefined && data !== null) {
-      // Handle Error objects specially - they don't JSON.stringify properly
      if (data instanceof Error) {
        dataStr = this.getLevel() === LogLevel.DEBUG
          ? `\n${data.message}\n${data.stack}`
          : ` ${data.message}`;
      } else if (this.getLevel() === LogLevel.DEBUG && typeof data === 'object') {
-        // In debug mode, show full JSON for objects.
-        // Wrap stringify in try/catch so circular structures don't crash the logger;
-        // fall back to formatData (which marks arrays/object key counts safely).
        try {
          dataStr = '\n' + JSON.stringify(data, null, 2);
        } catch {
@@ -315,7 +253,6 @@ class Logger {
      }
    }

-    // Build additional context
    let contextStr = '';
    if (context) {
      const { sessionId, memorySessionId, correlationId, ...rest } = context;
@@ -327,22 +264,17 @@ class Logger {

    const logLine = `[${timestamp}] [${levelStr}] [${componentStr}] ${correlationStr}${message}${contextStr}${dataStr}`;

-    // Output to log file ONLY (worker runs in background, console is useless)
    if (this.logFilePath) {
      try {
        appendFileSync(this.logFilePath, logLine + '\n', 'utf8');
      } catch (error: unknown) {
-        // [ANTI-PATTERN IGNORED]: Logger cannot log its own failures, using stderr/console as last resort
-        // This is expected during disk full / permission errors
        process.stderr.write(`[LOGGER] Failed to write to log file: ${error instanceof Error ? error.message : String(error)}\n`);
      }
    } else {
-      // If no log file available, write to stderr as fallback
      process.stderr.write(logLine + '\n');
    }
  }

-  // Public logging methods
  debug(component: Component, message: string, context?: LogContext, data?: any): void {
    this.log(LogLevel.DEBUG, component, message, context, data);
  }
@@ -359,63 +291,26 @@ class Logger {
    this.log(LogLevel.ERROR, component, message, context, data);
  }

-  /**
-   * Log data flow: input → processing
-   */
  dataIn(component: Component, message: string, context?: LogContext, data?: any): void {
    this.info(component, `→ ${message}`, context, data);
  }

-  /**
-   * Log data flow: processing → output
-   */
  dataOut(component: Component, message: string, context?: LogContext, data?: any): void {
    this.info(component, `← ${message}`, context, data);
  }

-  /**
-   * Log successful completion
-   */
  success(component: Component, message: string, context?: LogContext, data?: any): void {
    this.info(component, `✓ ${message}`, context, data);
  }

-  /**
-   * Log failure
-   */
  failure(component: Component, message: string, context?: LogContext, data?: any): void {
    this.error(component, `✗ ${message}`, context, data);
  }

-  /**
-   * Log timing information
-   */
  timing(component: Component, message: string, durationMs: number, context?: LogContext): void {
    this.info(component, `⏱ ${message}`, context, { duration: `${durationMs}ms` });
  }

-  /**
-   * Happy Path Error - logs when the expected "happy path" fails but we have a fallback
-   *
-   * Semantic meaning: "When the happy path fails, this is an error, but we have a fallback."
-   *
-   * Use for:
-   * ✅ Unexpected null/undefined values that should theoretically never happen
-   * ✅ Defensive coding where silent fallback is acceptable
-   * ✅ Situations where you want to track unexpected nulls without breaking execution
-   *
-   * DO NOT use for:
-   * ❌ Nullable fields with valid default behavior (use direct || defaults)
-   * ❌ Critical validation failures (use logger.warn or throw Error)
-   * ❌ Try-catch blocks where error is already logged (redundant)
-   *
-   * @param component - Component where error occurred
-   * @param message - Error message describing what went wrong
-   * @param context - Optional context (sessionId, correlationId, etc)
-   * @param data - Optional data to include
-   * @param fallback - Value to return (defaults to empty string)
-   * @returns The fallback value
-   */
  happyPathError<T = string>(
    component: Component,
    message: string,
@@ -423,19 +318,14 @@ class Logger {
    data?: any,
    fallback: T = '' as T
  ): T {
-    // Capture stack trace to get caller location
    const stack = new Error().stack || '';
    const stackLines = stack.split('\n');
-    // Line 0: "Error"
-    // Line 1: "at happyPathError ..."
-    // Line 2: "at <CALLER> ..." <- We want this one
    const callerLine = stackLines[2] || '';
    const callerMatch = callerLine.match(/at\s+(?:.*\s+)?\(?([^:]+):(\d+):(\d+)\)?/);
    const location = callerMatch
      ? `${callerMatch[1].split('/').pop()}:${callerMatch[2]}`
      : 'unknown';

-    // Log as a warning with location info
    const enhancedContext = {
      ...context,
      location
@@ -447,5 +337,4 @@ class Logger {
  }
 }

-// Export singleton instance
 export const logger = new Logger();
@@ -1,63 +1,33 @@
-/**
- * Project Filter Utility
- *
- * Provides glob-based path matching for project exclusion.
- * Supports: ~ (home), * (any chars except /), ** (any path), ? (single char)
- */

 import { homedir } from 'os';
 import { basename } from 'path';

-/**
- * Convert a glob pattern to a regular expression
- * Supports: ~ (home dir), * (any non-slash), ** (any path), ? (single char)
- */
 function globToRegex(pattern: string): RegExp {
-  // Expand ~ to home directory
  let expanded = pattern.startsWith('~')
    ? homedir() + pattern.slice(1)
    : pattern;

-  // Normalize path separators to forward slashes
  expanded = expanded.replace(/\\/g, '/');

-  // Escape regex special characters except * and ?
  let regex = expanded.replace(/[.+^${}()|[\]\\]/g, '\\$&');

-  // Convert glob patterns to regex:
-  // ** matches any path (including /)
-  // * matches any characters except /
-  // ? matches single character except /
  regex = regex
-    .replace(/\*\*/g, '<<<GLOBSTAR>>>')  // Temporary placeholder
-    .replace(/\*/g, '[^/]*')              // * = any non-slash
-    .replace(/\?/g, '[^/]')               // ? = single non-slash
-    .replace(/<<<GLOBSTAR>>>/g, '.*');    // ** = anything
+    .replace(/\*\*/g, '<<<GLOBSTAR>>>')  
+    .replace(/\*/g, '[^/]*')              
+    .replace(/\?/g, '[^/]')               
+    .replace(/<<<GLOBSTAR>>>/g, '.*');    

  return new RegExp(`^${regex}$`);
 }

-/**
- * Check if a path matches any of the exclusion patterns
- *
- * @param projectPath - Current working directory (absolute path)
- * @param exclusionPatterns - Comma-separated glob patterns (e.g., "~/kunden/*,/tmp/*")
- * @returns true if path should be excluded
- */
 export function isProjectExcluded(projectPath: string, exclusionPatterns: string): boolean {
  if (!exclusionPatterns || !exclusionPatterns.trim()) {
    return false;
  }

-  // Normalize cwd path separators
  const normalizedProjectPath = projectPath.replace(/\\/g, '/');
-  // Basename match pass: users intuitively expect `observer-sessions` or
-  // `*observer-sessions*` to match any cwd whose final segment matches, but
-  // globToRegex translates `*` → `[^/]*` which can't cross `/`. Without this,
-  // both bare names and basename globs silently fail (#2126 item 1).
  const projectBasename = basename(normalizedProjectPath);

-  // Parse comma-separated patterns
  const patternList = exclusionPatterns
    .split(',')
    .map(p => p.trim())
@@ -70,7 +40,6 @@ export function isProjectExcluded(projectPath: string, exclusionPatterns: string
        return true;
      }
    } catch (error: unknown) {
-      // Invalid pattern, skip it
      console.warn(`[project-filter] Invalid exclusion pattern "${pattern}":`, error instanceof Error ? error.message : String(error));
      continue;
    }
@@ -3,10 +3,6 @@ import path from 'path';
 import { logger } from './logger.js';
 import { detectWorktree } from './worktree.js';

-/**
- * Expand leading ~ to the user's home directory.
- * Handles "~", "~/", and "~/subpath" but not "~user/" (which is rare in cwd).
- */
 function expandTilde(p: string): string {
  if (p === '~' || p.startsWith('~/')) {
    return p.replace(/^~/, homedir())
@@ -14,29 +10,17 @@ function expandTilde(p: string): string {
  return p
 }

-/**
- * Extract project name from working directory path
- * Handles edge cases: null/undefined cwd, drive roots, trailing slashes, unexpanded ~
- *
- * @param cwd - Current working directory (absolute path, or ~-prefixed path)
- * @returns Project name or "unknown-project" if extraction fails
- */
 export function getProjectName(cwd: string | null | undefined): string {
  if (!cwd || cwd.trim() === '') {
    logger.warn('PROJECT_NAME', 'Empty cwd provided, using fallback', { cwd });
    return 'unknown-project';
  }

-  // Expand leading ~ before path operations
  const expanded = expandTilde(cwd)

-  // Extract basename (handles trailing slashes automatically)
  const basename = path.basename(expanded);

-  // Edge case: Drive roots on Windows (C:\, J:\) or Unix root (/)
-  // path.basename('C:\') returns '' (empty string)
  if (basename === '') {
-    // Extract drive letter on Windows, or use 'root' on Unix
    const isWindows = process.platform === 'win32';
    if (isWindows) {
      const driveMatch = cwd.match(/^([A-Z]):\\/i);
@@ -54,34 +38,13 @@ export function getProjectName(cwd: string | null | undefined): string {
  return basename;
 }

-/**
- * Project context with worktree awareness
- */
 export interface ProjectContext {
-  /** Canonical project name for writes/queries; `parent/worktree` when in a worktree */
  primary: string;
-  /** Parent project name if in a worktree, null otherwise */
  parent: string | null;
-  /** True if currently in a worktree */
  isWorktree: boolean;
-  /** Projects to query for reads. In a worktree: `[parent, composite]` so
-   *  main-repo context flows into every worktree while sibling worktrees stay
-   *  isolated. In the main repo: `[primary]`. Writes always use `.primary`. */
  allProjects: string[];
 }

-/**
- * Get project context with worktree detection.
- *
- * Each worktree is its own bucket. When in a worktree, `primary` is the
- * composite `parent/worktree` (e.g. `claude-mem/dar-es-salaam`) so worktrees
- * are uniquely identified and grouped under their parent project without
- * mixing observations across them. In the main repo, `primary` is just the
- * project basename.
- *
- * @param cwd - Current working directory (absolute path)
- * @returns ProjectContext with worktree info
- */
 export function getProjectContext(cwd: string | null | undefined): ProjectContext {
  const cwdProjectName = getProjectName(cwd);

@@ -1,28 +1,6 @@
-/**
- * Tag Stripping Utilities
- *
- * Implements the tag system for meta-observation control:
- * 1. <claude-mem-context> - System-level tag for auto-injected observations
- *    (prevents recursive storage when context injection is active)
- * 2. <private> - User-level tag for manual privacy control
- *    (allows users to mark content they don't want persisted)
- * 3. <system_instruction> / <system-instruction> - Conductor-injected system instructions
- *    (should not be persisted to memory)
- * 4. <system-reminder> - Claude Code-injected system reminders
- *    (CLAUDE.md contents, deferred tool lists, etc. — should not be persisted)
- * 5. <persisted-output> - Persisted-output payload tag
- *
- * EDGE PROCESSING PATTERN: Filter at hook layer before sending to worker/storage.
- * This keeps the worker service simple and follows one-way data stream.
- *
- * PATHFINDER plan 03 phase 8: collapsed countTags + stripTagsInternal into a
- * single alternation regex. One pass over the input. One helper, N callers
- * (`stripMemoryTagsFromJson` / `stripMemoryTagsFromPrompt` are thin adapters).
- */

 import { logger } from './logger.js';

-/** All tag names this module strips. Single source of truth for the regex. */
 const TAG_NAMES = [
  'private',
  'claude-mem-context',
@@ -33,43 +11,21 @@ const TAG_NAMES = [
 ] as const;
 type TagName = (typeof TAG_NAMES)[number];

-/**
- * Single-pass alternation regex covering every privacy / context tag.
- * Backreference `\1` ensures a closing tag matches the opening name; tag
- * attributes (e.g. `<system-reminder data-foo="…">`) are tolerated via
- * `[^>]*`.
- */
 const STRIP_REGEX = new RegExp(
  `<(${TAG_NAMES.join('|')})\\b[^>]*>[\\s\\S]*?</\\1>`,
  'g'
 );

-/**
- * Regex to match <system-reminder> tags and their content.
- * Exported for use by transcript parsers that strip system-reminder at read-time.
- *
- * Kept as a separate single-tag regex because the active transcript parser
- * (`src/shared/transcript-parser.ts`) consumes only this one tag and would
- * otherwise need to re-import the multi-tag list.
- */
 export const SYSTEM_REMINDER_REGEX = /<system-reminder>[\s\S]*?<\/system-reminder>/g;

-/** Maximum total stripped-tag count before we log a ReDoS-class anomaly. */
 const MAX_TAG_COUNT = 100;

-/**
- * Strip every recognised tag from `input` in a single pass.
- *
- * @returns the stripped string (trimmed) and per-tag counts. Counts are
- *          surfaced to logs for observability but are not used as a control
- *          signal.
- */
 export function stripTags(input: string): { stripped: string; counts: Record<TagName, number> } {
  const counts: Record<TagName, number> = Object.fromEntries(
    TAG_NAMES.map(name => [name, 0])
  ) as Record<TagName, number>;

-  STRIP_REGEX.lastIndex = 0; // /g state is per-instance — reset before each call.
+  STRIP_REGEX.lastIndex = 0; 

  let total = 0;
  const stripped = input.replace(STRIP_REGEX, (_, name: TagName) => {
@@ -89,51 +45,22 @@ export function stripTags(input: string): { stripped: string; counts: Record<Tag
  return { stripped: stripped.trim(), counts };
 }

-/**
- * Strip memory tags from JSON-serialized content (tool inputs/responses).
- * Thin adapter around `stripTags` — same regex, same single pass.
- */
 export function stripMemoryTagsFromJson(content: string): string {
  return stripTags(content).stripped;
 }

-/**
- * Strip memory tags from user prompt content.
- * Thin adapter around `stripTags` — same regex, same single pass.
- */
 export function stripMemoryTagsFromPrompt(content: string): string {
  return stripTags(content).stripped;
 }

-/**
- * Tag names that Claude Code emits autonomously into the prompt stream as
- * protocol notifications — never authored by the user. When the entire prompt
- * payload is one of these blocks (with no surrounding user text), the hook
- * MUST skip storage to keep `user_prompts` clean.
- *
- * Conservative deny-list: do NOT add `<command-name>` / `<command-message>`
- * here — those wrap genuine user slash-command invocations.
- */
 const PROTOCOL_ONLY_TAGS = ['task-notification'] as const;

-// Negative lookahead in the body keeps a payload like
-// "<task-notification>x</task-notification> hi <task-notification>y</task-notification>"
-// from matching as a single outer block (greedy [\s\S]* would otherwise span
-// the middle user text and silently drop a real prompt).
 const PROTOCOL_ONLY_REGEX = new RegExp(
  `^\\s*<(${PROTOCOL_ONLY_TAGS.join('|')})\\b[^>]*>(?:(?!<\\1\\b|</\\1\\b)[\\s\\S])*</\\1>\\s*$`,
 );

-// Bounds the unanchored `[\s\S]*` body to keep a malformed 1MB+ payload that
-// opens a protocol tag and never closes it from running the regex engine
-// against the whole prompt before failing.
 const MAX_PROTOCOL_PAYLOAD_BYTES = 256 * 1024;

-/**
- * Returns true when `text` is *entirely* a Claude Code protocol payload
- * (e.g. a `<task-notification>` block emitted on background Agent completion)
- * with no surrounding user-authored content.
- */
 export function isInternalProtocolPayload(text: string): boolean {
  if (!text) return false;
  if (text.length > MAX_PROTOCOL_PAYLOAD_BYTES) return false;
@@ -1,21 +1,12 @@
-/**
- * Worktree Detection Utility
- *
- * Detects if the current working directory is a git worktree and extracts
- * information about the parent repository.
- *
- * Git worktrees have a `.git` file (not directory) containing:
- *   gitdir: /path/to/parent/.git/worktrees/<name>
- */

 import { statSync, readFileSync } from 'fs';
 import path from 'path';

 export interface WorktreeInfo {
  isWorktree: boolean;
-  worktreeName: string | null;     // e.g., "yokohama"
-  parentRepoPath: string | null;   // e.g., "/Users/alex/main"
-  parentProjectName: string | null; // e.g., "main"
+  worktreeName: string | null;     
+  parentRepoPath: string | null;   
+  parentProjectName: string | null; 
 }

 const NOT_A_WORKTREE: WorktreeInfo = {
@@ -25,21 +16,13 @@ const NOT_A_WORKTREE: WorktreeInfo = {
  parentProjectName: null
 };

-/**
- * Detect if a directory is a git worktree and extract parent info.
- *
- * @param cwd - Current working directory (absolute path)
- * @returns WorktreeInfo with parent details if worktree, otherwise isWorktree=false
- */
 export function detectWorktree(cwd: string): WorktreeInfo {
  const gitPath = path.join(cwd, '.git');

-  // Check if .git is a file (worktree) or directory (main repo)
  let stat;
  try {
    stat = statSync(gitPath);
  } catch (error: unknown) {
-    // No .git at all - not a git repo (ENOENT is expected, other errors are noteworthy)
    if (error instanceof Error && (error as NodeJS.ErrnoException).code !== 'ENOENT') {
      console.warn(`[worktree] Unexpected error checking .git:`, error);
    }
@@ -47,11 +30,9 @@ export function detectWorktree(cwd: string): WorktreeInfo {
  }

  if (!stat.isFile()) {
-    // .git is a directory = main repo, not a worktree
    return NOT_A_WORKTREE;
  }

-  // Parse .git file to find parent repo
  let content: string;
  try {
    content = readFileSync(gitPath, 'utf-8').trim();
@@ -60,7 +41,6 @@ export function detectWorktree(cwd: string): WorktreeInfo {
    return NOT_A_WORKTREE;
  }

-  // Format: gitdir: /path/to/parent/.git/worktrees/<name>
  const match = content.match(/^gitdir:\s*(.+)$/);
  if (!match) {
    return NOT_A_WORKTREE;
@@ -68,8 +48,6 @@ export function detectWorktree(cwd: string): WorktreeInfo {

  const gitdirPath = match[1];

-  // Extract: /path/to/parent from /path/to/parent/.git/worktrees/name
-  // Handle both Unix and Windows paths
  const worktreesMatch = gitdirPath.match(/^(.+)[/\\]\.git[/\\]worktrees[/\\]([^/\\]+)$/);
  if (!worktreesMatch) {
    return NOT_A_WORKTREE;