Files
claude-mem/PATHFINDER-2026-04-22/_principle-crosscheck.md
T
Alex Newman 94d592f212 perf: streamline worker startup and consolidate database connections (#2122)
* docs: pathfinder refactor corpus + Node 20 preflight

Adds the PATHFINDER-2026-04-22 principle-driven refactor plan (11 docs,
cross-checked PASS) plus the exploratory PATHFINDER-2026-04-21 corpus
that motivated it. Bumps engines.node to >=20.0.0 per the ingestion-path
plan preflight (recursive fs.watch). Adds the pathfinder skill.

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

* refactor: land PATHFINDER Plan 01 — data integrity

Schema, UNIQUE constraints, self-healing claim, Chroma upsert fallback.

- Phase 1: fresh schema.sql regenerated at post-refactor shape.
- Phase 2: migrations 23+24 — rebuild pending_messages without
  started_processing_at_epoch; UNIQUE(session_id, tool_use_id);
  UNIQUE(memory_session_id, content_hash) on observations; dedup
  duplicate rows before adding indexes.
- Phase 3: claimNextMessage rewritten to self-healing query using
  worker_pid NOT IN live_worker_pids; STALE_PROCESSING_THRESHOLD_MS
  and the 60-s stale-reset block deleted.
- Phase 4: DEDUP_WINDOW_MS and findDuplicateObservation deleted;
  observations.insert now uses ON CONFLICT DO NOTHING.
- Phase 5: failed-message purge block deleted from worker-service
  2-min interval; clearFailedOlderThan method deleted.
- Phase 6: repairMalformedSchema and its Python subprocess repair
  path deleted from Database.ts; SQLite errors now propagate.
- Phase 7: Chroma delete-then-add fallback gated behind
  CHROMA_SYNC_FALLBACK_ON_CONFLICT env flag as bridge until
  Chroma MCP ships native upsert.
- Phase 8: migration 19 no-op block absorbed into fresh schema.sql.

Verification greps all return 0 matches. bun test tests/sqlite/
passes 63/63. bun run build succeeds.

Plan: PATHFINDER-2026-04-22/01-data-integrity.md

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

* refactor: land PATHFINDER Plan 02 — process lifecycle

OS process groups replace hand-rolled reapers. Worker runs until
killed; orphans are prevented by detached spawn + kill(-pgid).

- Phase 1: src/services/worker/ProcessRegistry.ts DELETED. The
  canonical registry at src/supervisor/process-registry.ts is the
  sole survivor; SDK spawn site consolidated into it via new
  createSdkSpawnFactory/spawnSdkProcess/getSdkProcessForSession/
  ensureSdkProcessExit/waitForSlot helpers.
- Phase 2: SDK children spawn with detached:true + stdio:
  ['ignore','pipe','pipe']; pgid recorded on ManagedProcessInfo.
- Phase 3: shutdown.ts signalProcess teardown uses
  process.kill(-pgid, signal) on Unix when pgid is recorded;
  Windows path unchanged (tree-kill/taskkill).
- Phase 4: all reaper intervals deleted — startOrphanReaper call,
  staleSessionReaperInterval setInterval (including the co-located
  WAL checkpoint — SQLite's built-in wal_autocheckpoint handles
  WAL growth without an app-level timer), killIdleDaemonChildren,
  killSystemOrphans, reapOrphanedProcesses, reapStaleSessions, and
  detectStaleGenerator. MAX_GENERATOR_IDLE_MS and MAX_SESSION_IDLE_MS
  constants deleted.
- Phase 5: abandonedTimer — already 0 matches; primary-path cleanup
  via generatorPromise.finally() already lives in worker-service
  startSessionProcessor and SessionRoutes ensureGeneratorRunning.
- Phase 6: evictIdlestSession and its evict callback deleted from
  SessionManager. Pool admission gates backpressure upstream.
- Phase 7: SDK-failure fallback — SessionManager has zero matches
  for fallbackAgent/Gemini/OpenRouter. Failures surface to hooks
  via exit code 2 through SessionRoutes error mapping.
- Phase 8: ensureWorkerRunning in worker-utils.ts rewritten to
  lazy-spawn — consults isWorkerPortAlive (which gates
  captureProcessStartToken for PID-reuse safety via commit
  99060bac), then spawns detached with unref(), then
  waitForWorkerPort({ attempts: 3, backoffMs: 250 }) hand-rolled
  exponential backoff 250→500→1000ms. No respawn npm dep.
- Phase 9: idle self-shutdown — zero matches for
  idleCheck/idleTimeout/IDLE_MAX_MS/idleShutdown. Worker exits
  only on external SIGTERM via supervisor signal handlers.

Three test files that exercised deleted code removed:
tests/worker/process-registry.test.ts,
tests/worker/session-lifecycle-guard.test.ts,
tests/services/worker/reap-stale-sessions.test.ts.
Pass count: 1451 → 1407 (-44), all attributable to deleted test
files. Zero new failures. 31 pre-existing failures remain
(schema-repair suite, logger-usage-standards, environmental
openclaw / plugin-distribution) — none introduced by Plan 02.

All 10 verification greps return 0. bun run build succeeds.

Plan: PATHFINDER-2026-04-22/02-process-lifecycle.md

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

* refactor: land PATHFINDER Plan 04 (narrowed) — search fail-fast

Phases 3, 5, 6 only. Plan-doc inaccuracies for phases 1/2/4/7/8/9
deferred for plan reconciliation:
  - Phase 1/2: ObservationRow type doesn't exist; the four
    "formatters" operate on three incompatible types.
  - Phase 4: RECENCY_WINDOW_MS already imported from
    SEARCH_CONSTANTS at every call site.
  - Phase 7: getExistingChromaIds is NOT @deprecated and has an
    active caller in ChromaSync.backfillMissingSyncs.
  - Phase 8: estimateTokens already consolidated.
  - Phase 9: knowledge-corpus rewrite blocked on PG-3
    prompt-caching cost smoke test.

Phase 3 — Delete SearchManager.findByConcept/findByFile/findByType.
SearchRoutes handlers (handleSearchByConcept/File/Type) now call
searchManager.getOrchestrator().findByXxx() directly via new
getter accessors on SearchManager. ~250 LoC deleted.

Phase 5 — Fail-fast Chroma. Created
src/services/worker/search/errors.ts with ChromaUnavailableError
extends AppError(503, 'CHROMA_UNAVAILABLE'). Deleted
SearchOrchestrator.executeWithFallback's Chroma-failed
SQLite-fallback branch; runtime Chroma errors now throw 503.
"Path 3" (chromaSync was null at construction — explicit-
uninitialized config) preserved as legitimate empty-result state
per plan text. ChromaSearchStrategy.search no longer wraps in
try/catch — errors propagate.

Phase 6 — Delete HybridSearchStrategy three try/catch silent
fallback blocks (findByConcept, findByType, findByFile) at lines
~82-95, ~120-132, ~161-172. Removed `fellBack` field from
StrategySearchResult type and every return site
(SQLiteSearchStrategy, BaseSearchStrategy.emptyResult,
SearchOrchestrator).

Tests updated (Principle 7 — delete in same PR):
  - search-orchestrator.test.ts: "fall back to SQLite" rewritten
    as "throw ChromaUnavailableError (HTTP 503)".
  - chroma/hybrid/sqlite-search-strategy tests: rewritten to
    rejects.toThrow; removed fellBack assertions.

Verification: SearchManager.findBy → 0; fellBack → 0 in src/.
bun test tests/worker/search/ → 122 pass, 0 fail.
bun test (suite-wide) → 1407 pass, baseline maintained, 0 new
failures. bun run build succeeds.

Plan: PATHFINDER-2026-04-22/04-read-path.md (Phases 3, 5, 6)

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

* refactor: land PATHFINDER Plan 03 — ingestion path

Fail-fast parser, direct in-process ingest, recursive fs.watch,
DB-backed tool pairing. Worker-internal HTTP loopback eliminated.

- Phase 0: Created src/services/worker/http/shared.ts exporting
  ingestObservation/ingestPrompt/ingestSummary as direct
  in-process functions plus ingestEventBus (Node EventEmitter,
  reusing existing pattern — no third event bus introduced).
  setIngestContext wires the SessionManager dependency from
  worker-service constructor.
- Phase 1: src/sdk/parser.ts collapsed to one parseAgentXml
  returning { valid:true; kind: 'observation'|'summary'; data }
  | { valid:false; reason: string }. Inspects root element;
  <skip_summary reason="…"/> is a first-class summary case
  with skipped:true. NEVER returns undefined. NEVER coerces.
- Phase 2: ResponseProcessor calls parseAgentXml exactly once,
  branches on the discriminated union. On invalid → markFailed
  + logger.warn(reason). On observation → ingestObservation.
  On summary → ingestSummary then emit summaryStoredEvent
  { sessionId, messageId } (consumed by Plan 05's blocking
  /api/session/end).
- Phase 3: Deleted consecutiveSummaryFailures field
  (ResponseProcessor + SessionManager + worker-types) and
  MAX_CONSECUTIVE_SUMMARY_FAILURES constant. Circuit-breaker
  guards and "tripped" log lines removed.
- Phase 4: coerceObservationToSummary deleted from sdk/parser.ts.
- Phase 5: src/services/transcripts/watcher.ts rescan setInterval
  replaced with fs.watch(transcriptsRoot, { recursive: true,
  persistent: true }) — Node 20+ recursive mode.
- Phase 6: src/services/transcripts/processor.ts pendingTools
  Map deleted. tool_use rows insert with INSERT OR IGNORE on
  UNIQUE(session_id, tool_use_id) (added by Plan 01). New
  pairToolUsesByJoin query in PendingMessageStore for read-time
  pairing (UNIQUE INDEX provides idempotency; explicit consumer
  not yet wired).
- Phase 7: HTTP loopback at processor.ts:252 replaced with
  direct ingestObservation call. maybeParseJson silent-passthrough
  rewritten to fail-fast (throws on malformed JSON).
- Phase 8: src/utils/tag-stripping.ts countTags + stripTagsInternal
  collapsed into one alternation regex, single-pass over input.
- Phase 9: src/utils/transcript-parser.ts (dead TranscriptParser
  class) deleted. The active extractLastMessage at
  src/shared/transcript-parser.ts:41-144 is the sole survivor.

Tests updated (Principle 7 — same-PR delete):
  - tests/sdk/parser.test.ts + parse-summary.test.ts: rewritten
    to assert discriminated-union shape; coercion-specific
    scenarios collapse into { valid:false } assertions.
  - tests/worker/agents/response-processor.test.ts: circuit-breaker
    describe block skipped; non-XML/empty-response tests assert
    fail-fast markFailed behavior.

Verification: every grep returns 0. transcript-parser.ts deleted.
bun run build succeeds. bun test → 1399 pass / 28 fail / 7 skip
(net -8 pass = the 4 retired circuit-breaker tests + 4 collapsed
parser cases). Zero new failures vs baseline.

Deferred (out of Plan 03 scope, will land in Plan 06): SessionRoutes
HTTP route handlers still call sessionManager.queueObservation
inline rather than the new shared helpers — the helpers are ready,
the route swap is mechanical and belongs with the Zod refactor.

Plan: PATHFINDER-2026-04-22/03-ingestion-path.md

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

* refactor: land PATHFINDER Plan 05 — hook surface

Worker-call plumbing collapsed to one helper. Polling replaced by
server-side blocking endpoint. Fail-loud counter surfaces persistent
worker outages via exit code 2.

- Phase 1: plugin/hooks/hooks.json — three 20-iteration `for i in
  1..20; do curl -sf .../health && break; sleep 0.1; done` shell
  retry wrappers deleted. Hook commands invoke their bun entry
  point directly.
- Phase 2: src/shared/worker-utils.ts — added
  executeWithWorkerFallback<T>(url, method, body) returning
  T | { continue: true; reason?: string }. All 8 hook handlers
  (observation, session-init, context, file-context, file-edit,
  summarize, session-complete, user-message) rewritten to use
  it instead of duplicating the ensureWorkerRunning →
  workerHttpRequest → fallback sequence.
- Phase 3: blocking POST /api/session/end in SessionRoutes.ts
  using validateBody + sessionEndSchema (z.object({sessionId})).
  One-shot ingestEventBus.on('summaryStoredEvent') listener,
  30 s timer, req.aborted handler — all share one cleanup so
  the listener cannot leak. summarize.ts polling loop, plus
  MAX_WAIT_FOR_SUMMARY_MS / POLL_INTERVAL_MS constants, deleted.
- Phase 4: src/shared/hook-settings.ts — loadFromFileOnce()
  memoizes SettingsDefaultsManager.loadFromFile per process.
  Per-handler settings reads collapsed.
- Phase 5: src/shared/should-track-project.ts — single exclusion
  check entry; isProjectExcluded no longer referenced from
  src/cli/handlers/.
- Phase 6: cwd validation pushed into adapter normalizeInput
  (all 6 adapters: claude-code, cursor, raw, gemini-cli,
  windsurf). New AdapterRejectedInput error in
  src/cli/adapters/errors.ts. Handler-level isValidCwd checks
  deleted from file-edit.ts and observation.ts. hook-command.ts
  catches AdapterRejectedInput → graceful fallback.
- Phase 7: session-init.ts conditional initAgent guard deleted;
  initAgent is idempotent. tests/hooks/context-reinjection-guard
  test (validated the deleted conditional) deleted in same PR
  per Principle 7.
- Phase 8: fail-loud counter at ~/.claude-mem/state/hook-failures
  .json. Atomic write via .tmp + rename. CLAUDE_MEM_HOOK_FAIL_LOUD
  _THRESHOLD setting (default 3). On consecutive worker-unreachable
  ≥ N: process.exit(2). On success: reset to 0. NOT a retry.
- Phase 9: ensureWorkerAliveOnce() module-scope memoization
  wrapping ensureWorkerRunning. executeWithWorkerFallback calls
  the memoized version.

Minimal validateBody middleware stub at
src/services/worker/http/middleware/validateBody.ts. Plan 06 will
expand with typed inference + error envelope conventions.

Verification: 4/4 grep targets pass. bun run build succeeds.
bun test → 1393 pass / 28 fail / 7 skip; -6 pass attributable
solely to deleted context-reinjection-guard test file. Zero new
failures vs baseline.

Plan: PATHFINDER-2026-04-22/05-hook-surface.md

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

* refactor: land PATHFINDER Plan 06 — API surface

One Zod-based validator wrapping every POST/PUT. Rate limiter,
diagnostic endpoints, and shutdown wrappers deleted. Failure-
marking consolidated to one helper.

- Phase 1 (preflight): zod@^3 already installed.
- Phase 2: validateBody middleware confirmed at canonical shape
  in src/services/worker/http/middleware/validateBody.ts —
  safeParse → 400 { error: 'ValidationError', issues: [...] }
  on failure, replaces req.body with parsed value on success.
- Phase 3: Per-route Zod schemas declared at the top of each
  route file. 24 POST endpoints across SessionRoutes,
  CorpusRoutes, DataRoutes, MemoryRoutes, SearchRoutes,
  LogsRoutes, SettingsRoutes now wrap with validateBody().
  /api/session/end (Plan 05) confirmed using same middleware.
- Phase 4: validateRequired() deleted from BaseRouteHandler
  along with every call site. Inline coercion helpers
  (coerceStringArray, coercePositiveInteger) and inline
  if (!req.body...) guards deleted across all route files.
- Phase 5: Rate limiter middleware and its registration deleted
  from src/services/worker/http/middleware.ts. Worker binds
  127.0.0.1:37777 — no untrusted caller.
- Phase 6: viewer.html cached at module init in ViewerRoutes.ts
  via fs.readFileSync; served as Buffer with text/html content
  type. SKILL.md + per-operation .md files cached in
  Server.ts as Map<string, string>; loadInstructionContent
  helper deleted. NO fs.watch, NO TTL — process restart is the
  cache-invalidation event.
- Phase 7: Four diagnostic endpoints deleted from DataRoutes.ts
  — /api/pending-queue (GET), /api/pending-queue/process (POST),
  /api/pending-queue/failed (DELETE), /api/pending-queue/all
  (DELETE). Helper methods that ONLY served them
  (getQueueMessages, getStuckCount, getRecentlyProcessed,
  clearFailed, clearAll) deleted from PendingMessageStore.
  KEPT: /api/processing-status (observability), /health
  (used by ensureWorkerRunning).
- Phase 8: stopSupervisor wrapper deleted from supervisor/index.ts.
  GracefulShutdown now calls getSupervisor().stop() directly.
  Two functions retained with clear roles:
    - performGracefulShutdown — worker-side 6-step shutdown
    - runShutdownCascade — supervisor-side child teardown
      (process.kill(-pgid), Windows tree-kill, PID-file cleanup)
  Each has unique non-trivial logic and a single canonical caller.
- Phase 9: transitionMessagesTo(status, filter) is the sole
  failure-marking path on PendingMessageStore. Old methods
  markSessionMessagesFailed and markAllSessionMessagesAbandoned
  deleted along with all callers (worker-service,
  SessionCompletionHandler, tests/zombie-prevention).

Tests updated (Principle 7 same-PR delete): coercion test files
refactored to chain validateBody → handler. Zombie-prevention
tests rewritten to call transitionMessagesTo.

Verification: all 4 grep targets → 0. bun run build succeeds.
bun test → 1393 pass / 28 fail / 7 skip — exact match to
baseline. Zero new failures.

Plan: PATHFINDER-2026-04-22/06-api-surface.md

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

* refactor: land PATHFINDER Plan 07 — dead code sweep

ts-prune-driven sweep across the tree after Plans 01-06 landed.
Deleted unused exports, orphan helpers, and one fully orphaned
file. Earlier-plan deletions verified.

Deleted:
- src/utils/bun-path.ts (entire file — getBunPath, getBunPathOrThrow,
  isBunAvailable: zero importers)
- bun-resolver.getBunVersionString: zero callers
- PendingMessageStore.retryMessage / resetProcessingToPending /
  abortMessage: superseded by transitionMessagesTo (Plan 06 Phase 9)
- EnvManager.MANAGED_CREDENTIAL_KEYS, EnvManager.setCredential:
  zero callers
- CodexCliInstaller.checkCodexCliStatus: zero callers; no status
  command exists in npx-cli
- Two "REMOVED: cleanupOrphanedSessions" stale-fence comments

Kept (with documented justification):
- Public API surface in dist/sdk/* (parseAgentXml, prompt
  builders, ParsedObservation, ParsedSummary, ParseResult,
  SUMMARY_MODE_MARKER) — exported via package.json sdk path.
- generateContext / loadContextConfig / token utilities — used
  via dynamic await import('../../../context-generator.js') in
  worker SearchRoutes.
- MCP_IDE_INSTALLERS, install/uninstall functions for codex/goose
  — used via dynamic await import in npx-cli/install.ts +
  uninstall.ts (ts-prune cannot trace dynamic imports).
- getExistingChromaIds — active caller in
  ChromaSync.backfillMissingSyncs (Plan 04 narrowed scope).
- processPendingQueues / getSessionsWithPendingMessages — active
  orphan-recovery caller in worker-service.ts plus
  zombie-prevention test coverage.
- StoreAndMarkCompleteResult legacy alias — return-type annotation
  in same file.
- All Database.ts barrel re-exports — used downstream.

Earlier-plan verification:
- Plan 03 Phase 9: VERIFIED — src/utils/transcript-parser.ts
  is gone; TranscriptParser has 0 references in src/.
- Plan 01 Phase 8: VERIFIED — migration 19 no-op absorbed.
- SessionStore.ts:52-70 consolidation NOT executed (deferred):
  the methods are not thin wrappers but ~900 LoC of bodies, and
  two methods are documented as intentional mirrors so the
  context-generator.cjs bundle stays schema-consistent without
  pulling MigrationRunner. Deserves its own plan, not a sweep.

Verification: TranscriptParser → 0; transcript-parser.ts → gone;
no commented-out code markers remain. bun run build succeeds.
bun test → 1393 pass / 28 fail / 7 skip — EXACT match to
baseline. Zero regressions.

Plan: PATHFINDER-2026-04-22/07-dead-code.md

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

* chore: remove residual ProcessRegistry comment reference

Plan 07 dead-code sweep missed one comment-level reference to the
deleted in-memory ProcessRegistry class in SessionManager.ts:347.
Rewritten to describe the supervisor.json scope without naming the
deleted class, completing the verification grep target.

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

* fix: address Greptile review (P1 + 2× P2)

P1 — Plan 05 Phase 3 blocking endpoint was non-functional:
executeWithWorkerFallback used HEALTH_CHECK_TIMEOUT_MS (3 s) for
the POST /api/session/end call, but the server holds the
connection for SERVER_SIDE_SUMMARY_TIMEOUT_MS (30 s). Client
always raced to a "timed out" rejection that isWorkerUnavailable
classified as worker-unreachable, so the hook silently degraded
instead of waiting for summaryStoredEvent.
  - Added optional timeoutMs to executeWithWorkerFallback,
    forwarded to workerHttpRequest.
  - summarize.ts call site now passes 35_000 (5 s above server
    hold window).

P2 — ingestSummary({ kind: 'parsed' }) branch was dead code:
ResponseProcessor emitted summaryStoredEvent directly via the
event bus, bypassing the centralized helper that the comment
claimed was the single source.
  - ResponseProcessor now calls ingestSummary({ kind: 'parsed',
    sessionDbId, messageId, contentSessionId, parsed }) so the
    event-emission path is single-sourced.
  - ingestSummary's requireContext() resolution moved inside the
    'queue' branch (the only branch that needs sessionManager /
    dbManager). 'parsed' is a pure event-bus emission and
    doesn't need worker-internal context — fixes mocked
    ResponseProcessor unit tests that don't call
    setIngestContext.

P2 — isWorkerFallback could false-positive on legitimate API
responses whose schema includes { continue: true, ... }:
  - Added a Symbol.for('claude-mem/worker-fallback') brand to
    WorkerFallback. isWorkerFallback now checks the brand, not
    a duck-typed property name.

Verification: bun run build succeeds. bun test → 1393 pass /
28 fail / 7 skip — exact baseline match. Zero new failures.

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

* fix: address Greptile iteration 2 (P1 + P2)

P1 — summaryStoredEvent fired regardless of whether the row was
persisted. ResponseProcessor's call to ingestSummary({ kind:
'parsed' }) ran for every parsed.kind === 'summary' even when
result.summaryId came back null (e.g. FK violation, null
memory_session_id at commit). The blocking /api/session/end
endpoint then returned { ok: true } and the Stop hook logged
'Summary stored' for a non-existent row.

  - Gate ingestSummary call on (parsed.data.skipped ||
    session.lastSummaryStored). Skipped summaries are an explicit
    no-op bypass and still confirm; real summaries only confirm
    when storage actually wrote a row.
  - Non-skipped + summaryId === null path logs a warn and lets
    the server-side timeout (504) surface to the hook instead of
    a false ok:true.

P2 — PendingMessageStore.enqueue() returns 0 when INSERT OR
IGNORE suppresses a duplicate (the UNIQUE(session_id, tool_use_id)
constraint added by Plan 01 Phase 1). The two callers
(SessionManager.queueObservation and queueSummarize) previously
logged 'ENQUEUED messageId=0' which read like a row was inserted.

  - Branch on messageId === 0 and emit a 'DUP_SUPPRESSED' debug
    log instead of the misleading ENQUEUED line. No behavior
    change — the duplicate is still correctly suppressed by the
    DB (Principle 3); only the log surface is corrected.
  - confirmProcessed is never called with the enqueue() return
    value (it operates on session.processingMessageIds[] from
    claimNextMessage), so no caller is broken; the visibility
    fix prevents future misuse.

Verification: bun run build succeeds. bun test → 1393 pass /
28 fail / 7 skip — exact baseline match. Zero new failures.

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

* fix: address Greptile iteration 3 (P1 + 2× P2)

- P1 worker-service.ts: wire ensureGeneratorRunning into the ingest
  context after SessionRoutes is constructed. setIngestContext runs
  before routes exist, so transcript-watcher observations queued via
  ingestObservation() had no way to auto-start the SDK generator.
  Added attachIngestGeneratorStarter() to patch the callback in.
- P2 shared.ts: IngestEventBus now sets maxListeners to 0. Concurrent
  /api/session/end calls register one listener each and clean up on
  completion, so the default-10 warning fires spuriously under normal
  load.
- P2 SessionRoutes.ts: handleObservationsByClaudeId now delegates to
  ingestObservation() instead of duplicating skip-tool / meta /
  privacy / queue logic. Single helper, matching the Plan 03 goal.

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

* fix: address Greptile iteration 4 (P1 tool-pair + P2 parse/path/doc)

- processor.handleToolResult: restore in-memory tool-use→tool-result
  pairing via session.pendingTools for schemas (e.g. Codex) whose
  tool_result events carry only tool_use_id + output. Without this,
  neither handler fired — all tool observations silently dropped.
- processor.maybeParseJson: return raw string on parse failure instead
  of throwing. Previously a single malformed JSON-shaped field caused
  handleLine's outer catch to discard the entire transcript line.
- watcher.deepestNonGlobAncestor: split on / and \\, emit empty string
  for purely-glob inputs so the caller skips the watch instead of
  anchoring fs.watch at the filesystem root. Windows-compatible.
- PendingMessageStore.enqueue: tighten docstring — callers today only
  log on the returned id; the SessionManager branches on id === 0.

* fix: forward tool_use_id through ingestObservation (Greptile iter 5)

P1 — Plan 01's UNIQUE(content_session_id, tool_use_id) dedup never
fired because the new shared ingest path dropped the toolUseId before
queueObservation. SQLite treats NULL values as distinct for UNIQUE,
so every replayed transcript line landed a duplicate row.

- shared.ingestObservation: forward payload.toolUseId to
  queueObservation so INSERT OR IGNORE can actually collapse.
- SessionRoutes.handleObservationsByClaudeId: destructure both
  tool_use_id (HTTP convention) and toolUseId (JS convention) from
  req.body and pass into ingestObservation.
- observationsByClaudeIdSchema: declare both keys explicitly so the
  validator doesn't rely on .passthrough() alone.

* fix: drop dead pairToolUsesByJoin, close session-end listener race

- PendingMessageStore: delete pairToolUsesByJoin. The method was never
  called and its self-join semantics are structurally incompatible
  with UNIQUE(content_session_id, tool_use_id): INSERT OR IGNORE
  collapses any second row with the same pair, so a self-join can
  only ever match a row to itself. In-memory pendingTools in
  processor.ts remains the pairing path for split-event schemas.

- IngestEventBus: retain a short-lived (60s) recentStored map keyed
  by sessionId. Populated on summaryStoredEvent emit, evicted on
  consume or TTL.

- handleSessionEnd: drain the recent-events buffer before attaching
  the listener. Closes the register-after-emit race where the summary
  can persist between the hook's summarize POST and its session/end
  POST — previously that window returned 504 after the 30s timeout.

* chore: merge origin/main into vivacious-teeth

Resolves conflicts with 15 commits on main (v12.3.9, security
observation types, Telegram notifier, PID-reuse worker start-guard).

Conflict resolution strategy:
- plugin/hooks/hooks.json, plugin/scripts/*.cjs, plugin/ui/viewer-bundle.js:
  kept ours — PATHFINDER Plan 05 deletes the for-i-in-1-to-20 curl retry
  loops and the built artifacts regenerate on build.
- src/cli/handlers/summarize.ts: kept ours — Plan 05 blocking
  POST /api/session/end supersedes main's fire-and-forget path.
- src/services/worker-service.ts: kept ours — Plan 05 ingest bus +
  summaryStoredEvent supersedes main's SessionCompletionHandler DI
  refactor + orphan-reaper fallback.
- src/services/worker/http/routes/SessionRoutes.ts: kept ours — same
  reason; generator .finally() Stop-hook self-clean is a guard for a
  path our blocking endpoint removes.
- src/services/worker/http/routes/CorpusRoutes.ts: merged — added
  security_alert / security_note to ALLOWED_CORPUS_TYPES (feature from
  #2084) while preserving our Zod validateBody schema.

Typecheck: 294 errors (vs 298 pre-merge). No new errors introduced; all
remaining are pre-existing (Component-enum gaps, DOM lib for viewer,
bun:sqlite types).

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

* fix: address Greptile P2 findings

1) SessionRoutes.handleSessionEnd was the only route handler not wrapped
   in wrapHandler — synchronous exceptions would hang the client rather
   than surfacing as 500s. Wrap it like every other handler.

2) processor.handleToolResult only consumed the session.pendingTools
   entry when the tool_result arrived without a toolName. In the
   split-schema path where tool_result carries both toolName and toolId,
   the entry was never deleted and the map grew for the life of the
   session. Consume the entry whenever toolId is present.

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

* fix: typing cleanup and viewer tsconfig split for PR feedback

- Add explicit return types for SessionStore query methods
- Exclude src/ui/viewer from root tsconfig, give it its own DOM-typed config
- Add bun to root tsconfig types, plus misc typing tweaks flagged by Greptile
- Rebuilt plugin/scripts/* artifacts

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

* fix: address Greptile P2 findings (iter 2)

- PendingMessageStore.transitionMessagesTo: require sessionDbId (drop
  the unscoped-drain branch that would nuke every pending/processing
  row across all sessions if a future caller omitted the filter).
- IngestEventBus.takeRecentSummaryStored: make idempotent — keep the
  cached event until TTL eviction so a retried Stop hook's second
  /api/session/end returns immediately instead of hanging 30 s.
- TranscriptWatcher fs.watch callback: skip full glob scan for paths
  already tailed (JSONL appends fire on every line; only unknown
  paths warrant a rescan).

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

* fix: call finalizeSession in terminal session paths (Greptile iter 3)

terminateSession and runFallbackForTerminatedSession previously called
SessionCompletionHandler.finalizeSession before removeSessionImmediate;
the refactor dropped those calls, leaving sdk_sessions.status='active'
for every session killed by wall-clock limit, unrecoverable error, or
exhausted fallback chain. The deleted reapStaleSessions interval was
the only prior backstop.

Re-wires finalizeSession (idempotent: marks completed, drains pending,
broadcasts) into both paths; no reaper reintroduced.

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

* fix: GC failed pending_messages rows at startup (Greptile iter 4)

Plan 07 deleted clearFailed/clearFailedOlderThan as "dead code", but
with the periodic sweep also removed, nothing reaps status='failed'
rows now — they accumulate indefinitely. Since claimNextMessage's
self-healing subquery scans this table, unbounded growth degrades
claim latency over time.

Re-introduces clearFailedOlderThan and calls it once at worker startup
(not a reaper — one-shot, idempotent). 7-day retention keeps enough
history for operator inspection while bounding the table.

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

* fix: finalize sessions on normal exit; cleanup hoist; share handler (iter 5)

1. startSessionProcessor success branch now calls completionHandler.
   finalizeSession before removeSessionImmediate. Hooks-disabled installs
   (and any Stop hook that fails before POST /api/sessions/complete) no
   longer leave sdk_sessions rows as status='active' forever. Idempotent
   — a subsequent /api/sessions/complete is a no-op.

2. Hoist SessionRoutes.handleSessionEnd cleanup declaration above the
   closures that reference it (TDZ safety; safe at runtime today but
   fragile if timeout ever shrinks).

3. SessionRoutes now receives WorkerService's shared SessionCompletionHandler
   instead of constructing its own — prevents silent divergence if the
   handler ever becomes stateful.

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

* fix: stop runaway crash-recovery loop on dead sessions

Two distinct bugs were combining to keep a dead session restarting forever:

Bug 1 (uncaught "The operation was aborted."):
  child_process.spawn emits 'error' asynchronously for ENOENT/EACCES/abort
  signal aborts. spawnSdkProcess() never attached an 'error' listener, so
  any async spawn failure became uncaughtException and escaped to the
  daemon-level handler. Attach an 'error' listener immediately after spawn,
  before the !child.pid early-return, so async spawn errors are logged
  (with errno code) and swallowed locally.

Bug 2 (sliding-window limiter never trips on slow restart cadence):
  RestartGuard tripped only when restartTimestamps.length exceeded
  MAX_WINDOWED_RESTARTS (10) within RESTART_WINDOW_MS (60s). With the 8s
  exponential-backoff cap, only ~7-8 restarts fit in the window, so a dead
  session that fail-restart-fail-restart on 8s cycles would loop forever
  (consecutiveRestarts climbing past 30+ in observed logs). Add a
  consecutiveFailures counter that increments on every restart and resets
  only on recordSuccess(). Trip when consecutive failures exceed
  MAX_CONSECUTIVE_FAILURES (5) — meaning 5 restarts with zero successful
  processing in between proves the session is dead. Both guards now run in
  parallel: tight loops still trip the windowed cap; slow loops trip the
  consecutive-failure cap.

Also: when the SessionRoutes path trips the guard, drain pending messages
to 'abandoned' so the session does not reappear in
getSessionsWithPendingMessages and trigger another auto-start cycle. The
worker-service.ts path already does this via terminateSession.

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

* perf: streamline worker startup and consolidate database connections

1. Database Pooling: Modified DatabaseManager, SessionStore, and SessionSearch to share a single bun:sqlite connection, eliminating redundant file descriptors.
2. Non-blocking Startup: Refactored WorktreeAdoption and Chroma backfill to run in the background (fire-and-forget), preventing them from stalling core initialization.
3. Diagnostic Routes: Added /api/chroma/status and bypassed the initialization guard for health/readiness endpoints to allow diagnostics during startup.
4. Robust Search: Implemented reliable SQLite FTS5 fallback in SearchManager for when Chroma (uvx) fails or is unavailable.
5. Code Cleanup: Removed redundant loopback MCP checks and mangled initialization logic from WorkerService.

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

* fix: hard-exclude observer-sessions from hooks; bundle migration 29 (#2124)

* fix: hard-exclude observer-sessions from hooks; backfill bundle migrations

Stop hook + SessionEnd hook were storing the SDK observer's own
init/continuation/summary prompts in user_prompts, leaking into the
viewer (meta-observation regression). 25 such rows accumulated.

- shouldTrackProject: hard-reject OBSERVER_SESSIONS_DIR (and its subtree)
  before consulting user-configured exclusion globs.
- summarize.ts (Stop) and session-complete.ts (SessionEnd): early-return
  when shouldTrackProject(cwd) is false, so the observer's own hooks
  cannot bootstrap the worker or queue a summary against the meta-session.
- SessionRoutes: cap user-prompt body at 256 KiB at the session-init
  boundary so a runaway observer prompt cannot blow up storage.
- SessionStore: add migration 29 (UNIQUE(memory_session_id, content_hash)
  on observations) inline so bundled artifacts (worker-service.cjs,
  context-generator.cjs) stay schema-consistent — without it, the
  ON CONFLICT clause in observation inserts throws.
- spawnSdkProcess: stdio[stdin] from 'ignore' to 'pipe' so the
  supervisor can actually feed the observer's stdin.

Also rebuilds plugin/scripts/{worker-service,context-generator}.cjs.

* fix: walk back to UTF-8 boundary on prompt truncation (Greptile P2)

Plain Buffer.subarray at MAX_USER_PROMPT_BYTES can land mid-codepoint,
which the utf8 decoder silently rewrites to U+FFFD. Walk back over any
continuation bytes (0b10xxxxxx) before decoding so the truncated prompt
ends on a valid sequence boundary instead of a replacement character.

* fix: cross-platform observer-dir containment; clarify SDK stdin pipe

claude-review feedback on PR #2124.

- shouldTrackProject: literal `cwd.startsWith(OBSERVER_SESSIONS_DIR + '/')`
  hard-coded a POSIX separator and missed Windows backslash paths plus any
  trailing-slash variance. Switched to a path.relative-based isWithin()
  helper so Windows hook input under observer-sessions\\... is also excluded.
- spawnSdkProcess: added a comment explaining why stdin must be 'pipe' —
  SpawnedSdkProcess.stdin is typed NonNullable and the Claude Agent SDK
  consumes that pipe; 'ignore' would null it and the null-check below
  would tear the child down on every spawn.

* fix: make Stop hook fire-and-forget; remove dead /api/session/end

The Stop hook was awaiting a 35-second long-poll on /api/session/end,
which the worker held open until the summary-stored event fired (or its
30s server-side timeout elapsed). Followed by another await on
/api/sessions/complete. Three sequential awaits, the middle one a 30s
hold — not fire-and-forget despite repeated requests.

The Stop hook now does ONE thing: POST /api/sessions/summarize to
queue the summary work and return. The worker drives the rest async.
Session-map cleanup is performed by the SessionEnd handler
(session-complete.ts), not duplicated here.

- summarize.ts: drop the /api/session/end long-poll and the trailing
  /api/sessions/complete await; ~40 lines removed; unused
  SessionEndResponse interface gone; header comment rewritten.
- SessionRoutes: delete handleSessionEnd, sessionEndSchema, the
  SERVER_SIDE_SUMMARY_TIMEOUT_MS constant, and the /api/session/end
  route registration. Drop the now-unused ingestEventBus and
  SummaryStoredEvent imports.
- ResponseProcessor + shared.ts + worker-utils.ts: update stale
  comments that referenced the dead endpoint. The IngestEventBus is
  left in place dormant (no listeners) for follow-up cleanup so this
  PR stays focused on the blocker.

Bundle artifact (worker-service.cjs) rebuilt via build-and-sync.

Verification:
- grep '/api/session/end' plugin/scripts/worker-service.cjs → 0
- grep 'timeoutMs:35' plugin/scripts/worker-service.cjs → 0
- Worker restarted clean, /api/health ok at pid 92368

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

* deps: bump all dependencies to latest including majors

Upgrades: React 18→19, Express 4→5, Zod 3→4, TypeScript 5→6,
@types/node 20→25, @anthropic-ai/claude-agent-sdk 0.1→0.2,
@clack/prompts 0.9→1.2, plus minors. Adds Daily Maintenance section
to CLAUDE.md mandating latest-version policy across manifests.

Express 5 surfaced a race in Server.listen() where the 'error' handler
was attached after listen() was invoked; refactored to use
http.createServer with both 'error' and 'listening' handlers attached
before listen(), restoring port-conflict rejection semantics.

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

* fix: surface real chroma errors and add deep status probe

Replace the misleading "Vector search failed - semantic search unavailable.
Install uv... restart the worker." string in SearchManager with the actual
exception text from chroma_query_documents. The lying message blamed `uv`
for any failure — even when the real cause was a chroma-mcp transport
timeout, an empty collection, or a dead subprocess.

Also add /api/chroma/status?deep=1 backed by a new
ChromaMcpManager.probeSemanticSearch() that round-trips a real query
(chroma_list_collections + chroma_query_documents) instead of just
checking the stdio handshake. The cheap default path is unchanged.

Includes the diagnostic plan (PLAN-fix-mcp-search.md) and updated test
fixtures for the new structured failure message.

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

---------

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

* chore: rebuild worker-service bundle to match merged src

Bundle was stale after the squash merge of #2124 — it still contained
the old "Install uv... semantic search unavailable" string and lacked
probeSemanticSearch. Rebuilt via bun run build-and-sync.

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

* docs: address coderabbit feedback on PLAN-fix-mcp-search.md

- replace machine-specific /Users/alexnewman absolute paths with portable
  <repo-root> placeholder (MD-style portability)
- add blank lines around the TypeScript fenced block (MD031)
- tag the bare fenced block with `text` (MD040)

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

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 13:37:40 -07:00

271 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Phase 7 — Principle Cross-Check
**Reviewer**: Phase 7 meta-review subagent
**Date**: 2026-04-22
**Scope**: Corpus files in `PATHFINDER-2026-04-22/` excluding `_rewrite-plan.md`, `_reference.md`, `_mapping.md`.
**Corpus under review**: `00-principles.md`, `01-data-integrity.md`, `02-process-lifecycle.md`, `03-ingestion-path.md`, `04-read-path.md`, `05-hook-surface.md`, `06-api-surface.md`, `07-dead-code.md`, `98-execution-order.md`, `99-verification.md`.
## Summary verdict
**PASS** — 0 violations across all 7 checks.
---
## Check 1 — Dangerous identifiers (`recover|reap|heal|repair|orphan|coerce|fallback`, case-insensitive)
**Total hits**: 96 across the corpus (9 review files + supporting docs). Every hit in a review file classifies as DELETE-context, NEVER-ADD-guard, canonical-example, glossary definition, or invariant (self-heal) that is explicitly the new primary path. No hit advocates a new recovery / coerce / silent-fallback pattern.
### 00-principles.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 9 | "No **recovery** code" | Principle 1 statement | OK (principle) |
| 10 | "circuit-break, **coerce**, or silently fall back" | Principle 2 statement | OK (principle) |
| 13 | "process groups over hand-rolled **reapers**" + "**orphan** sweeps" | Principle 5 statement | OK (principle) |
| 22 | "No new `**coerce***`, `**recover***`, `**heal***`, `**repair***`, `**reap***`, `kill*Orphans*` function names" | Anti-pattern guard | OK (NEVER-ADD) |
| 23 | "try/catch that swallows errors and returns a **fallback** value" | Anti-pattern guard | OK (NEVER-ADD) |
| 24 | "new schema column whose only purpose is to feed a **recovery** query" | Anti-pattern guard | OK (NEVER-ADD) |
| 26 | "HTTP endpoint for diagnostic / manual-**repair** purposes" | Anti-pattern guard | OK (NEVER-ADD) |
| 40 | "**Orphan** **reapers**, idle-evictors, **fallback** agents" | Inventory of DELETEd mechanisms | OK (DELETE) |
| 41 | "`**repair**MalformedSchema`" + "self-**heal**ing claim" | DELETE target + canonical-example (self-heal is new invariant) | OK (DELETE + canonical) |
| 43 | "`**coerce**ObservationToSummary`, circuit breaker" | DELETE target | OK (DELETE) |
| 44 | "`@deprecated` dead classes" + "**repair**MalformedSchema" | DELETE targets | OK (DELETE) |
| 5153 | Glossary: "lease pattern," "self-**healing** claim," "fail-fast contract" | Definitions of canonical new patterns (self-healing claim is the approved replacement invariant; lease pattern is a concept definition) | OK (canonical example / glossary) |
### 01-data-integrity.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 11 | "`**recover**StuckProcessing`, `clearFailedOlderThan` interval, `**repair**MalformedSchema` all hide bugs. They are deleted" | Principle 1 application | OK (DELETE) |
| 12 | "Chroma conflict errors surface through a narrow, flagged **fallback**; rest throws" | Scoped + flagged bridge, documented as non-permanent | OK (canonical bridge, gated by `CHROMA_SYNC_FALLBACK_ON_CONFLICT` flag with removal-commitment at line 282) |
| 15 | "self-**heal**ing claim is event-driven" | Canonical new invariant name | OK (canonical) |
| 30, 37, 71, 96, 98, 104, 106, 127, 129 | "self-**heal**ing claim" / "self-**heal** block" | Canonical invariant naming + "self-heal block" is the DELETE target within `claimNextMessage` | OK (canonical + DELETE) |
| 165, 180 | `clearFailedOlderThan` interval | DELETE target | OK (DELETE) |
| 187, 189, 192197, 262 | `**repair**MalformedSchema` | DELETE target (Phase 6) | OK (DELETE) |
| 206, 239, 282 | "Chroma upsert **fallback**" + `CHROMA_SYNC_FALLBACK_ON_CONFLICT` | Flag-gated, bridge-only, documented for removal | OK (justified bridge) |
| 274 | "Do NOT keep `**recover**StuckProcessing()` … any identifier matching `**recover***`, `**heal***`, or `**repair***` that survives must be in a DELETE context" | NEVER-ADD guard | OK (NEVER-ADD) |
| 275 | "No `setInterval`, no `setTimeout` loop" | Backfill design constraint | OK (NEVER-ADD) |
| 276 | "Do NOT add '**repair**' CLI commands" | NEVER-ADD guard | OK (NEVER-ADD) |
### 02-process-lifecycle.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 11 | "**Orphan** sweeps, idle-evictors, stale-session **reapers** are recovery code papering over a spawn bug" | Principle 1 application | OK (DELETE rationale) |
| 12 | "Gemini → OpenRouter **fallback** chain hides SDK failures. Delete it" | DELETE target | OK (DELETE) |
| 13 | "Delete the 30-second **orphan**-**reaper** interval, the stale-session **reaper** interval" | DELETE targets | OK (DELETE) |
| 14 | "`killSystemOrphans`, `killIdleDaemonChildren`, `**reap**OrphanedProcesses`, `**reap**StaleSessions`" | DELETE list | OK (DELETE) |
| 27 | "`**reap**OrphanedProcesses`" | DELETE target (file anchor) | OK (DELETE) |
| 37 | "`**reap**OrphanedProcesses() { /* three-layer sweep */ }`" | Before-snippet in DELETE diff | OK (DELETE) |
| 46 | "There is no ppid sweep, no **orphan** **reaper**, no 'shadow' registry" | After-state assertion | OK (NEVER-ADD) |
| 55 | "OS primitive that makes **orphan** **reap**ing unnecessary" | Rationale | OK (rationale) |
| 118, 120, 128, 129, 136 | "Delete all **reaper** intervals" + `**reap**OrphanedProcesses` / `**reap**StaleSessions` / `reapStaleSessions()` | DELETE targets | OK (DELETE) |
| 146147 | "no **reap**ers" + "Phase 2 process groups prevent **orphan**s" | After-state comment | OK (NEVER-ADD) |
| 208, 210, 213 | "Delete **fallback** agent chain (Gemini → OpenRouter)" + `**fallback**Agent` references | DELETE target (Phase 7) | OK (DELETE) |
| 233 | "no silent **fallback**s" | Reference to principle 2 | OK (NEVER-ADD) |
| 243 | "`detached: true` **fallback**" | Documented OS-level spawn primitive (daemon spawn pattern reference, not a silent-error fallback) | OK (canonical spawn primitive) |
| 341, 346, 347, 350, 353, 361 | Grep-zero greps for `**reap**StaleSessions`, `**reap**OrphanedProcesses`, `**fallback**Agent\|Gemini\|OpenRouter`, `**orphan** children`; "Do NOT keep `killSystemOrphans`" | Verification / NEVER-ADD | OK (DELETE-verification + NEVER-ADD) |
### 03-ingestion-path.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 13 | "`**coerce**ObservationToSummary` exists only to **recover** from LLM contract violations. Fix the contract, delete the coercion helper" | Principle 1 application | OK (DELETE) |
| 18 | "`**coerce**ObservationToSummary`, `pendingTools` Map, `TranscriptParser` class — all delete in the same PR" | DELETE list | OK (DELETE) |
| 64, 68, 84, 101, 129, 153, 155, 158, 163, 362 | `**coerce**ObservationToSummary` | DELETE target (Phase 4) + before-snippet + verification grep-zero | OK (DELETE) |
| 166 | "no `@deprecated` fence, no 'remove next release'" | Anti-pattern reminder | OK (NEVER-ADD) |
| 316 | "the dead class deletes now — not fenced with `@deprecated`" | Anti-pattern reminder | OK (NEVER-ADD) |
| 371 | "fuzz test: drop a JSONL file with an **orphan** tool_use" | Test case name describing input data, not a pattern to implement | OK (test vocabulary) |
| 384 | "Do NOT ship a polling **fallback** for `fs.watch`" | NEVER-ADD guard | OK (NEVER-ADD) |
| 389 | "No new `**coerce***`, `**heal***`, `**recover***`, `**repair***` function name" | NEVER-ADD guard | OK (NEVER-ADD) |
### 04-read-path.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 11 | "`SearchOrchestrator` throws `503` on Chroma error. … three try/catch **fallback**s that returned metadata-only are deleted" | Principle 2 application | OK (DELETE) |
| 13 | "the `fell**Back**: true` flag path, the `@deprecated getExistingChromaIds` fence … all delete in the PR" | DELETE list | OK (DELETE) |
| 86, 94, 98, 103, 108, 178, 183, 194 | "fell**Back**: true" / "silent **fallback**s" / "three near-identical methods … try/catch **fallback** to metadata-only" / "metadata-only **fallback**" / "Do NOT add a feature flag to 'disable fail-fast Chroma'" | DELETE targets + NEVER-ADD guard | OK (DELETE + NEVER-ADD) |
| 126 | "After Phase 2 deletes both classes, their `estimateTokens` helpers would **orphan**" | English verb (referring to consolidating helpers that would be orphaned), not a pattern | OK (narrative language) |
| 198200 | "No new `**coerce***`, `**recover***`, `**heal***`, `**repair***` function names" / "try/catch that swallows errors and returns a **fallback** value" | NEVER-ADD guards | OK (NEVER-ADD) |
| 208 | "read-path `503` is correct even while the write-path **fallback** remains active" | Explicit scoped-to-write-path Chroma bridge (owned by 01) | OK (canonical bridge) |
### 05-hook-surface.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 77 | "the request/**fallback** sequence has one implementation; eight handlers import it. No handler reimplements the 'worker missing → exit gracefully' path" | Describes the one single helper path that handles worker-unreachable — explicitly the non-silent, escalates-to-exit-2 path. Used in sense of "alternative path" not "silent recovery" | OK (canonical single-helper description; the handler uses exit-code escalation per principle 2) |
### 06-api-surface.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 9 | "pending-queue diagnostic endpoints exist to poke at rows a correct ingestion path should never leave behind. Deleting them is the cure" | Principle 1 application | OK (DELETE) |
| 87 | "grep-and-delete every … `**coerce***` helper across route files" | DELETE directive | OK (DELETE) |
| 97 | "Claim-side contention → `01-data-integrity.md` Phase 3 (self-**heal**ing claim)" | Canonical invariant reference | OK (canonical) |
| 100 | "'No new HTTP endpoint for diagnostic / manual-**repair** purposes' — the rate limiter is the HTTP-handler analogue" | NEVER-ADD guard citation | OK (NEVER-ADD) |
| 114 | "principle 1 (no watcher-plus-TTL 'cache-invalidation' **recovery** code)" | Principle 1 rationale | OK (NEVER-ADD) |
| 126 | "KEEP `/api/processing-status` … not a **repair** lever. It reads and reports" | Definition of what is kept (non-repair) | OK (boundary statement) |
| 129 | "'No new HTTP endpoint for diagnostic / manual-**repair** purposes' — the deletions here are that guard applied retroactively" | NEVER-ADD guard citation | OK (NEVER-ADD) |
### 07-dead-code.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 33, 45, 81, 135, 144, 159 | `@deprecated` identifiers / fences | All DELETE directives or NEVER-ADD guards | OK (DELETE + NEVER-ADD) |
### 98-execution-order.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 14 | "self-**heal**ing claim" | Canonical invariant name | OK (canonical) |
| 20 | "catches **orphan**ed exports / commented-out blocks / dead migrations" | Sweep-plan scope language | OK (narrative about dead-code sweep, not a pattern) |
| 154 | "self-**heal**ing claim query" | Canonical invariant reference | OK (canonical) |
| 174 | "Chroma upsert **fallback** is brittle" | Documented bridge with flag + removal-commitment | OK (justified bridge) |
| 177 | "lazy-spawn wrapper needs a retry **strategy**" — resolved to hand-rolled 3-attempt retry | Describing the decision (hand-rolled logic, no new class) | OK (narrative describing resolution) |
### 99-verification.md
| Line | Matched text | Context | Verdict |
|---|---|---|---|
| 50, 53, 54, 58, 59, 71, 78, 79 | Grep-zero checks for `**recover**StuckProcessing`, `killSystem**Orphan**s`, `**reap**StaleSessions`, `**reap**OrphanedProcesses`, `killIdleDaemonChildren`, `**fallback**Agent`, `**repair**MalformedSchema`, `**coerce**ObservationToSummary` | Verification (must return 0) | OK (DELETE-verification) |
| 161 | "I5: `/health` endpoint" — mention in "**heal**th" endpoint name | Substring match on word "health" in endpoint name (not a recovery/heal pattern) | OK (substring, not the pattern the rule targets) |
| 164 | "Deleted diagnostic endpoints return `404`, not `200` with a **fallback** body" | Verification that NO silent fallback exists | OK (NEVER-ADD verification) |
| 176 | "kill Chroma, issue a search → 503 rendered, no **fallback**" | Verification of no silent fallback | OK (NEVER-ADD verification) |
| 191 | "no **orphan** children remain" | Integration-test assertion | OK (verification) |
**Verdict**: PASS. Every hit is DELETE-context, NEVER-ADD guard, canonical-example (self-healing claim, lease pattern, fail-fast contract as glossary), or a scoped + flagged Chroma-upsert bridge with documented removal.
---
## Check 2 — Timers (`setInterval|setTimeout`)
**Total hits**: 35 across the corpus (excluding support docs). Every hit is a DELETE target OR the explicitly justified per-operation kill-escalation `setTimeout` in `src/supervisor/shutdown.ts` (the SIGTERM→SIGKILL 5-second escalator — non-repeating, bound to a specific operation, disposed in-scope).
### Per-file breakdown
| File | Hits | Classification |
|---|---|---|
| 00-principles.md | 2 (lines 12, 21) | Principle 4 statement + NEVER-ADD guard for `src/services/worker/` |
| 01-data-integrity.md | 3 (lines 165, 180, 275) | DELETE + NEVER-ADD ("no `setInterval`, no `setTimeout` loop" for Chroma backfill) |
| 02-process-lifecycle.md | 7 (lines 13, 124, 135, 138, 155, 166, 341) | All DELETE targets (reaper intervals, `abandonedTimer` setTimeout) + verification grep-zero |
| 03-ingestion-path.md | 6 (lines 16, 174, 177, 194, 209, 346, 365, 390) | DELETE targets (the 5-second rescan `setInterval` at watcher.ts:124-132) + verification + NEVER-ADD guard |
| 05-hook-surface.md | 1 (line 107) | `const timer = setTimeout(...)` in the consecutive-failure-counter code snippet — this is the narrowly-scoped per-operation timer in the hook (see below) |
| 06-api-surface.md | 1 (line 141) | DELETE directive for shutdown wrappers that create `setInterval` callers |
| 99-verification.md | 5 (lines 13, 14, 15, 22, 25, 47, 82) | DELETE targets in census + explicit justification for per-operation one-shot `setTimeout` in `src/supervisor/shutdown.ts` (kill-escalation) |
**Line 107 of 05-hook-surface.md**`const timer = setTimeout(...)`: this is a per-operation timer inside the consecutive-failure escalation code (bounded scope, cleared synchronously, not a repeating background sweep). Matches the "narrowly-justified per-operation" allowance in `99-verification.md:22`.
**Verdict**: PASS. No hit proposes a new repeating background timer in `src/services/worker/` or equivalent. Every repeating timer is a DELETE target. The only non-DELETE mentions are (a) the 5-second shutdown kill-escalation explicitly called out in 99, (b) the per-operation timer in 05 line 107 (bounded to the request lifecycle).
---
## Check 3 — Strategy/Factory/Builder
**Total hits**: 27 across the corpus (case-insensitive). All hits justify as one of: (a) `RenderStrategy` as a **config type** (not a class — explicitly enforced by `04-read-path.md` lines 33, 193); (b) existing module path `ChromaSearchStrategy` / `HybridSearchStrategy` (file-system name from existing code); (c) DELETE directives for the four old formatter "strategy classes"; (d) narrative descriptions (e.g., "retry strategy" for hand-rolled retry logic).
### Per-file breakdown
| File | Hits | Classification |
|---|---|---|
| 00-principles.md | 2 (lines 14, 25, 42) | Principle 6 statement + NEVER-ADD guard + "four formatter classes" = DELETE inventory | OK |
| 04-read-path.md | 15+ | `RenderStrategy` as config type (not class) — enforced explicitly at line 33 ("NO abstract class. NO factory. NO `RenderStrategyBase`") and line 193 ("Config object only. No `abstract class RenderStrategy`, no subclass-per-formatter, no factory, no registry"). `ChromaSearchStrategy` / `HybridSearchStrategy` are existing module paths from `src/services/worker/search/strategies/`. DELETE directives for old per-formatter strategies at lines 100, 103. | OK |
| 05-hook-surface.md | 2 (lines 275, 298) | "CLAUDE.md §Exit Code **Strategy**" — naming of the existing CLAUDE.md section, not a new class | OK |
| 06-api-surface.md | 0 | — |
| 07-dead-code.md | 1 (line 17) | Principle 6 quote — NEVER-ADD guard | OK |
| 98-execution-order.md | 3 (lines 160, 175, 177, 178) | `renderObservations(obs, strategy)` references config type; "retry **strategy**" at 177 resolves to "hand-roll a 3-attempt retry" (no new class); "explicit cache-control **strategy**" at 175 is a fallback plan description, not a proposed abstraction | OK |
**Verdict**: PASS. No hit proposes a new abstract-class / factory / builder layer. `RenderStrategy` is a `type` (object literal) and this is guarded three times in `04-read-path.md`.
---
## Check 4 — Forbidden phrases (`for backward compat|for one release|@deprecated`)
**Total hits**: 24 across the corpus. Every hit is a DELETE directive, a NEVER-ADD guard, or a reference to principle 7.
### Per-file breakdown
| File | Hits | Classification |
|---|---|---|
| 00-principles.md | 2 (lines 15, 44) | Principle 7 statement + DELETE inventory | OK (NEVER-ADD) |
| 03-ingestion-path.md | 2 (lines 166, 316) | "no `@deprecated` fence, no 'remove next release'" — NEVER-ADD reminder | OK |
| 04-read-path.md | 6 (lines 13, 112, 114, 117, 120, 179) | Phase 7 section DELETES `@deprecated getExistingChromaIds` | OK (DELETE) |
| 06-api-surface.md | 3 (lines 12, 89, 145, 224) | DELETE wrappers in-PR "not `@deprecated`-fenced"; "Do NOT keep a shutdown wrapper 'for backward compat'" | OK (NEVER-ADD) |
| 07-dead-code.md | 9 (lines 11, 33, 45, 81, 135, 144, 159) | Principle 7 quote + DELETE of residual `@deprecated` fences + NEVER-ADD guard | OK (DELETE + NEVER-ADD) |
| 99-verification.md | 1 (line 119) | Verification grep-zero for `// @deprecated\|// TODO remove\|// old$\|// legacy$` | OK (verification) |
**Verdict**: PASS. Zero advocacy for deprecated-fence or backward-compat retention; every mention is a DELETE directive or NEVER-ADD guard.
---
## Check 5 — `_reference.md` citations per plan
| Plan | `_reference.md` citations | Verdict |
|---|---|---|
| 00-principles.md | 0 | OK — 00 is the root principles doc; it defines anti-patterns and is cited by every downstream plan. It does not need to cite `_reference.md` because it asserts rules, not facts about specific code anchors. |
| 01-data-integrity.md | 10 | OK |
| 02-process-lifecycle.md | 17 | OK |
| 03-ingestion-path.md | 15 | OK |
| 04-read-path.md | 12 | OK |
| 05-hook-surface.md | 20 | OK |
| 06-api-surface.md | 6 | OK |
| 07-dead-code.md | 0 | ACCEPTABLE — 07 is the dead-code sweep plan. Its targets are identified by downstream DELETE directives in plans 01-06 (each of which cites `_reference.md`). 07 cites `_mapping.md` DELETE rows and runs `ts-prune`/`knip` for residue. Sweeping unused exports does not require line anchors — if a symbol has no callers after 01-06 land, it is dead. |
| 98-execution-order.md | 1 | OK (structural doc; cites as part of the "how to execute a phase" load list) |
| 99-verification.md | 0 | ACCEPTABLE — 99 is the verification-operational doc. It runs greps and integration tests whose targets are defined by the plans that cite `_reference.md`. Verification targets (e.g., `coerceObservationToSummary` grep → 0) are inherited from plans 01-06 that cite the anchors. |
**Verdict**: PASS. Every plan that touches existing code anchors cites `_reference.md` at least 6 times. The three plans with zero citations (00, 07, 99) are structurally correct: 00 asserts rules, 07 sweeps residue from plans that already cited, 99 verifies grep-zero against targets already cited.
---
## Check 6 — Mapping completeness
`_mapping.md` accounts for every old `PATHFINDER-2026-04-21` plan (Plans 01 through 12) and every supporting document (`00-features.md`, `02-duplication-report.md`, `03-unified-proposal.md`, `04-handoff-prompts.md`, `05-clean-flowcharts.md`, `06-implementation-plan.md` Phase 0 + Phases 1-15, `07-master-plan.md`, `08-reconciliation.md`, `09-execution-runbook.md`). Each row has a verdict (KEEP / REWRITE / DELETE / SPLIT) and a new-plan destination or explicit archive location.
Line 210-212 of `_mapping.md` explicitly asserts: "**Archive `PATHFINDER-2026-04-21/` wholesale once the new corpus lands. No orphans** — every section either maps to a new plan or goes to the archive."
No orphan old sections identified. Plan 03 (response-parsing-storage) is flagged as heavily duplicating Plan 01 — its unique content is consolidated into `03-ingestion-path.md` and duplicate phases are explicitly DELETE'd (lines 62-66). Plan 07 (session-lifecycle-management) — the heaviest-debt plan — has every mechanism line-item accounted for (Mechanism A KEEP, Mechanism B/C DELETE, Phase 1 SPLIT to 03 Phase 0, Phases 2-7 REWRITE to 02, Phase 8 KEEP).
**Verdict**: PASS.
---
## Check 7 — DAG in 98-execution-order.md
### Node → incoming edges
- `00` ← ∅
- `01` ← {00}
- `02` ← {00}
- `03` ← {01, 02}
- `04` ← {01}
- `05` ← {02, 03}
- `06` ← {05}
- `07` ← {00, 01, 02, 03, 04, 05, 06}
- `99` ← ∅ (alongside, not blocking)
### Confirmations
- **No edge references a non-existent node**: every source of an incoming edge is in the node set {00, 01, 02, 03, 04, 05, 06, 07, 99}. ✓
- **Topological sort exists and is emitted**: `00 → 01 → 02 → 03 → 04 → 05 → 06 → 07`. All edges point strictly forward. ✓
- **All plans 00-07 appear as DAG nodes**: confirmed. ✓
- **99 listed as "runs alongside"**: confirmed (line 21 of 98-execution-order.md, line 102). ✓
- **Acyclicity**: confirmed by explicit check at line 104: "No back-edges. DAG is acyclic." ✓
**Verdict**: PASS.
---
## Revisions needed
**None.** Every check passes. No plan requires revision before ship.
---
## Overall recommendation
**Ship as-is.** The corpus passes all seven Phase 7 cross-checks with zero violations. Every dangerous-identifier mention (`recover`, `reap`, `heal`, `repair`, `orphan`, `coerce`, `fallback`) is either a DELETE target, a NEVER-ADD guard, a canonical-example glossary entry, or the single flagged + scoped + removal-committed Chroma upsert bridge. Every `setInterval`/`setTimeout` is either a DELETE target or a narrowly-scoped per-operation timer justified in `99-verification.md` §22. Every `strategy`/`factory`/`builder` mention either (a) is guarded against class-hierarchy expansion (`04-read-path.md` line 33, 193), (b) refers to an existing module-path filename, or (c) quotes principle 6 in a NEVER-ADD context. Every `@deprecated` mention is a DELETE directive or a NEVER-ADD guard. Every plan that touches existing code anchors cites `_reference.md` extensively. The mapping accounts for every old section with explicit verdicts. The execution DAG is acyclic with a clean topological sort.
The only residual items that remain operational risks (not review violations) are the five blocking issues already enumerated in `98-execution-order.md` §Blocking issues — these are carried forward with resolution pointers and are not Phase 7 concerns.
**Confidence: HIGH** that this corpus is ready to enter the execution DAG.