Skip to content

[plan-root-cause] Holistic worker/runtime reliability fixes for lifecycle, Chroma, Windows, packaging, migrations, observer loops, project scoping, and data integrity #3138

Open
Open
[plan-root-cause] Holistic worker/runtime reliability fixes for lifecycle, Chroma, Windows, packaging, migrations, observer loops, project scoping, and data integrity#3138
Labels
plan

Description

@thedotmack
thedotmack
opened on Jul 5, 2026

Problem

The current backlog has many symptom issues that keep reappearing because the runtime contracts are split across several partial implementations:

  • Worker liveness is inferred from a mix of PID files, port probes, health/version endpoints, spawn cooldowns, marketplace/cache paths, and hook exit behavior.
  • Chroma is a long-lived sidecar with its own uvx spawn, dependency install, timeout, process-tree, and metadata contract, but it can outlive the worker or write to the same data dir from multiple writers.
  • Windows hosts still have multiple command-generation paths, some host configs run POSIX shell strings through PowerShell, and several spawn sites leak console windows or inherited handles.
  • Install and runtime packaging can disagree about the executable root, marker root, cache root, marketplace root, and bundled dependency set.
  • SQLite migrations and data-pipeline invariants are not tested as direct upgrades across real historical schema states.
  • Observer no-op/error behavior can be treated as poison, causing respawn loops, transcript accumulation, and dropped observations.
  • Project identity is inconsistent across git roots, cwd-relative subprojects, worktrees, submodules, Chroma metadata, and distilled memory namespaces.

This plan is for branch plan/root-cause-holistic-fixes. It is intentionally a root-cause plan-master, not another batch of one-off fixes. Child issues should be redirected here only after this issue exists and each child is mapped to a concrete phase and verification row.

Snapshot source: /tmp/claude-mem-three-track/backlog-full.json, /tmp/claude-mem-three-track/backlog-summary.json, /tmp/claude-mem-three-track/open-prs.json.

Snapshot metadata: thedotmack/claude-mem, 116 open issues, 134 open PRs, captured at 2026-07-05T04:56:22Z.

Related existing plan masters:

Root-Cause Clusters

1. Worker lifecycle and liveness need one source of truth

Root cause: worker startup, restart, version recycle, PID ownership, port ownership, marketplace/cache path identity, and hook failure behavior are not governed by a single lifecycle state machine.

Child issues:

Relevant open PRs to evaluate, rebase, or replace:

2. Chroma sidecar spawn, lifecycle, and semantic-search degradation are not a contract

Root cause: Chroma subprocess management has improved in pieces, but it still lacks a fully tested contract tying uvx invocation, dependency syntax, prewarm timeout, worker restart shutdown, process-tree cleanup, single-writer guarantees, and project metadata search fallback together.

Child issues:

Relevant open PRs:

3. Windows host/process behavior is scattered across wrappers

Root cause: Windows command generation, shell selection, hidden-window behavior, .cmd handling, commandWindows, IPv4/IPv6 host selection, and environment inheritance are not centralized and verified as one host matrix.

Child issues:

Relevant open PRs:

4. Install/runtime packaging and executable-root identity are inconsistent

Root cause: install, repair, version-check, plugin cache, marketplace copy, bundled runtime deps, build outputs, and executable marker files are not validated as one deployable artifact.

Child issues:

Relevant open PRs:

5. Migration, storage, and data-pipeline integrity need historical-state tests

Root cause: schema migration steps, readiness state, Chroma sync, prompt retention, settings writes, lock contention, and server-beta tool visibility are validated as isolated code paths rather than direct upgrades from real historical databases under concurrent hooks.

Child issues:

Relevant open PRs:

6. Observer generator contract and poison-loop containment are incomplete

Root cause: benign no-observation output, prose empty responses, prompt-too-long failures, inherited third-party hooks, transcript persistence, and restart retries are not represented as bounded states with clear acknowledgements.

Child issues:

Relevant open PRs:

7. Project scoping and cross-source identity are not uniform

Root cause: SQLite rows, Chroma metadata, context injection, dream namespaces, git-root/cwd/worktree/submodule identity, and project remaps use different keys and one-shot migrations.

Child issues:

Relevant open PRs:

8. Auth/env subprocess boundary is mixed into unrelated failures

Root cause: provider auth, proxy variables, credential-manager probes, and skip-auth flags are filtered or warned about inside generic subprocess startup paths, making clean installs and worker-side provider calls look like lifecycle failures.

Child issues:

Relevant open PRs:

Documentation Discovery And Allowed APIs

Local documentation and source files consulted before planning:

  • plans/02-spawn-contract-templating.md
    • Allowed API: buildShellCommand(options) and ShellTemplateOptions.
    • Contract: host-managed shell-template for Claude Code/Codex; installer-managed absolute bake only where the host does not expand templates; runtime resolution prelude for CLAUDE_PLUGIN_ROOT.
    • Anti-pattern source: do not patch each host config independently.
  • plans/04-installer-transparency.md
    • Allowed APIs: runTasks, bufferConsole, describeExecError, marker write pattern, pluginCacheDirectory, IDE list, trustedDependencies, installer taxonomy tests.
    • Contract: installer failures must be categorized through taxonomy; no silent fallback category.
  • plans/2026-06-10-worker-restart-single-source-of-truth.md
    • Allowed APIs: ensureWorkerRunning(), resolveWorkerScriptPath(), waitForWorkerPort(), waitForWorkerReadiness(), ensureWorkerStarted(port, workerScriptPath), spawnDaemon(scriptPath, port, extraEnv?), resolveWorkerRuntimePath(options?), PID-file helpers, httpShutdown(), waitForPortFree(), checkVersionMatch(), performGracefulShutdown(), flushResponseThen(), writeJsonFileAtomic(), MARKETPLACE_ROOT, resolveDataDir().
    • Contract: health/readiness endpoints are lifecycle oracles; built .cjs artifacts are generated outputs.
  • docs/architecture-overview.md
    • Runtime model: hook lifecycle, pending queue, parser valid/invalid flow, ProcessRegistry, ChromaSync, graceful degradation.
    • Existing invariant to restore: worker unavailability must not block the user session.
  • src/shared/worker-utils.ts
    • Existing entrypoint: ensureWorkerRunning(), resolveWorkerScriptPath(), worker settings host/port/timeout readers, health/readiness polling, restart wait.
  • src/shared/worker-spawn-gate.ts
    • Existing lock API: acquireSpawnLock() and releaseSpawnLock() gate spawning only; health checks must not be serialized behind the spawn lock.
  • src/services/worker-spawner.ts
    • Existing API: ensureWorkerStarted(port, workerScriptPath), Windows startup cooldown, stale PID cleanup.
  • src/services/infrastructure/HealthMonitor.ts
    • Existing APIs: isPortInUse(), waitForHealth(), waitForReadiness(), waitForPortFree(), httpShutdown(), checkVersionMatch().
  • src/services/server/Server.ts
    • Allowed lifecycle endpoints: /api/health, /api/readiness, /api/admin/restart, /api/admin/shutdown.
    • /api/version may remain as an informational endpoint, but lifecycle decisions need /api/health because it includes PID, version, runtime, worker path, initialized state, and dependency status.
  • src/services/worker-shutdown.ts
    • Allowed API: runShutdownSequence() and restart handoff flow.
  • src/services/restart-verify.ts
    • Allowed API: verifyRestartedWorker() using /api/health PID and version proof.
  • src/supervisor/process-registry.ts and src/supervisor/shutdown.ts
    • Allowed APIs: ProcessRegistry, captureProcessStartToken(), verifyPidFileOwnership(), spawnSdkProcess(), runShutdownCascade(), signalProcess(), removeOwnedPidFile().
  • src/shared/spawn.ts
    • Allowed wrapper: spawnHidden() for windowsHide: true.
  • src/services/sync/ChromaMcpManager.ts
    • Allowed APIs: resolveUvxCommand(), buildCommandArgs(), prewarmChromaMcp(), disposeCurrentSubprocess(), stop(), reset(), killProcessTree(), registerManagedProcess().
    • Existing contract to keep: uvx direct execution with shell:false; no cmd.exe /c for Chroma.
  • src/shared/dependency-health.ts
    • Allowed APIs: dependency health records for degraded vector-search status.
  • src/services/sqlite/SessionStore.ts and src/services/worker/DatabaseManager.ts
    • Migration surface for v23 to v35, platform_source, session/content identity, busy timeout, WAL, retention, and auto-vacuum.
  • src/npx-cli/install/setup-runtime.ts, src/npx-cli/commands/install.ts, src/npx-cli/install/error-taxonomy.ts, src/npx-cli/install/error-reporter.ts, plugin/scripts/version-check.js, scripts/build-hooks.js
    • Packaging surface for marker files, bundled modules, marketplace/cache copies, runtime repair, and failure taxonomy.
  • Existing tests to extend rather than bypass:
    • tests/infrastructure/plugin-distribution.test.ts
    • tests/infrastructure/version-consistency.test.ts
    • tests/services/sync/chroma-mcp-manager-singleton.test.ts
    • tests/services/sync/chroma-sync-unavailable.test.ts
    • tests/setup-runtime.test.ts
    • tests/plugin-version-check-ensure-deps.test.ts
    • tests/install-error-matrix.test.ts

Phase Sequence

Phase 0 - Intake gate, documentation lock, and PR triage

Goal: make this issue the root-cause router before any child issue is closed.

Work:

Verification:

  • The final issue body includes every cluster above, exact child issue numbers, exact PR numbers, this phase sequence, the verification matrix, the documentation discovery list, and anti-pattern guards.
  • No child issue is closed only because this plan exists.

Phase 1 - Worker lifecycle single source of truth

Goal: define and enforce one lifecycle state machine for worker identity, liveness, restart, stale-port recovery, and hook behavior.

Work:

  • Make /api/health plus /api/readiness the lifecycle oracle for hook startup, restart verification, stale-worker detection, and version recycle. Keep /api/version informational.
  • Standardize worker identity as {pid, startToken, version, workerPath, runtimePath, dataDir, rootKind, host, port}.
  • Use worker-spawn-gate only for spawn critical sections; never gate cheap health checks behind it.
  • Use ProcessRegistry, start-token ownership, and shutdown cascade for tree cleanup. Do not trust PID files without ownership proof.
  • Ensure version-mismatch recycle shuts down or detaches children without leaving an inherited listening socket.
  • Make hook invocations bounded and fail open for prompt usability when the worker is unreachable.
  • Accept CLAUDE_MEM_WORKER_SCRIPT_PATH only as a validated diagnostic/operability override; do not let it create a second canonical root.
  • Reconcile marketplace root, plugin cache root, and dev root so only one executable worker root owns a data dir at a time.
  • Fix host selection so getWorkerHost() is used consistently and Windows IPv6 localhost does not block IPv4-only worker listeners.

Issues covered: #3134, #3128, #3100, #3083, #3073, #3054, #3052, #3031, #2996, #2992, #2966, #2963, #2926, #2903, #2899, #2893, #2891, #2846, #2823.

PRs to consume or supersede: #3112, #3099, #3055, #3009, #2998, #2980, #2937, #2895, #2892, #2830, #2828, #2731.

Verification:

  • Unit tests for stale PID, wrong start token, dead PID with bound port, live unrelated port holder, version mismatch restart, and inherited child socket.
  • Integration tests for five concurrent hook launchers racing on a cold start.
  • Windows restart soak: version recycle, stop hook, update/restart, VS Code extension 60s init path.
  • Prompt hooks must continue without infinite retry when worker is unreachable.

Phase 2 - Chroma sidecar contract

Goal: make vector search a degraded dependency with deterministic spawn, teardown, single-writer, and metadata behavior.

Work:

  • Keep Chroma launches on direct uvx/uvx.exe, shell:false, raw argv arrays, and --from launcher syntax.
  • Route all Chroma subprocess abandon paths through disposeCurrentSubprocess() and killProcessTree().
  • Register Chroma subprocess lineage in ProcessRegistry and make worker shutdown/restart stop Chroma before releasing or rebinding the worker port.
  • Make prewarm timeout clean up uv temp installs and record dependency health instead of triggering unbounded retry.
  • Add a single-writer guard per Chroma data dir so dual worker roots cannot write the same persistent Chroma database.
  • Surface vector-search degraded status through /api/health.dependencies.
  • Align Chroma metadata project keys with Phase 7 project identity.
  • Preserve FTS5 fallback when vector search is unavailable, and make the fallback reason visible in telemetry/logs.

Issues covered: #3121, #3107, #3091, #3012, #2979, #2978, #2961, #2959, #2954, #2950, #2939, #2907, #2897, #2896, #2879.

PRs to consume or supersede: #3116, #3108, #3102, #3011, #2940, #2920, #2880.

Verification:

  • Windows tests prove no cmd.exe /c uvx, no shell quoting of >/<, and no bare positional chroma-mcp==version.
  • Timeout test proves prewarm kills the full process tree and does not leave uv/python children.
  • Concurrent ensureConnected() calls produce one subprocess.
  • Worker restart test proves Chroma is stopped before successor worker binds.
  • Dual-root test proves second worker cannot open the same Chroma data dir as a writer.

Phase 3 - Windows host/process hygiene

Goal: centralize Windows command generation so every host has the correct shell contract, hidden windows, and no deprecated spawn patterns.

Work:

  • Generate host configs through the spawn-contract API rather than per-file string patches.
  • Use commandWindows or equivalent host-specific Windows overrides for Codex and other hosts that support it.
  • Remove POSIX hook commands from Windows configs executed by PowerShell.
  • Centralize .cmd handling. If a wrapper is needed, use one audited path and keep windowsHide:true.
  • Remove shell:true plus args patterns from live runtime paths.
  • Carry windowsHide:true through bun, uvx, where, git, provider SDK, and hook subprocesses.
  • Treat absent Windows credentials as a neutral miss, not a warning loop.
  • Add an explicit Windows hook-disable escape hatch only as a user-facing mitigation; it cannot be the primary fix.

Issues covered: #3123, #3106, #3101, #3075, #3072, #3069, #2965, #2962, #2946, #2941, #2913, #2910, #2900, #2869.

PRs to consume or supersede: #3095, #3046, #3033, #2997, #2945, #2944, #2921, #2890, #2699, #2507.

Verification:

  • Windows 10/11 matrix across Claude Code, Codex, VS Code extension, PowerShell, cmd.exe, Git Bash, and WSL2 invocation.
  • No visible console window during prompt submit, tool use, summarize, observer generation, git subprocesses, or bun/uv discovery.
  • rg guard for shell: IS_WINDOWS, cmd.exe /c, and spawn(..., { shell: true, args }) in live runtime code.

Phase 4 - Install/runtime packaging and executable-root identity

Goal: make a marketplace or cache install a complete, self-verifying runtime artifact.

Work:

  • Define the executable root invariant: the root that runs hooks must be the root that owns .install-version, bundled deps, marketplace.json, worker scripts, sqlite runtime modules, and repair operations.
  • Repair both marketplace and cache roots when both exist, or remove stale roots that cannot be repaired.
  • Add build-time runtime-require closure checks for worker-service, mcp-server, hooks, sqlite modules, SessionStore, and observations/files modules.
  • Preserve bundled zod, tree-sitter CLI, sqlite runtime files, and any runtime deps needed when node_modules churn occurs.
  • Make missing .install-version a repair path, not just a nag.
  • Route install failures through the taxonomy. Unknown fatal install failures remain ABORT; expected per-IDE failures are FAIL_LOUD_PER_IDE; optional vector-search warnings are WARN_CONTINUE.
  • Keep ERESOLVE fallback narrow and diagnostic, not a global --force.

Issues covered: #3126, #3122, #3117, #3107, #3092, #3035, #3004, #2964, #2952, #2922, #2910, #2831, #2823.

PRs to consume or supersede: #3113, #3110, #3108, #3102, #3066, #3058, #3018, #3006, #2918, #2887, #2710, #2531, #2597.

Verification:

  • Clean install, repair install, missing marker, missing node_modules, missing bun, missing uv, ERESOLVE, and Windows tree-sitter scenarios.
  • Runtime smoke test from marketplace root and cache root with CLAUDE_PLUGIN_ROOT present and absent.
  • Build artifact test imports every generated worker/runtime entrypoint in a temp directory without repo node_modules.
  • Doctor hint must repair the same root that the failing hook executes.

Phase 5 - Migration, SQLite, settings, and data-pipeline integrity

Goal: make historical database upgrades and concurrent hook writes deterministic and visible.

Work:

  • Use one migration runner/init path for worker DB startup. If SessionStore receives an existing Database, it must still apply required pragmas and migration invariants.
  • Add direct-upgrade fixtures for v23, v24, v31, and v35-era schemas, including missing platform_source, old unique indexes, pending message indexes, prompt tables, and content/session identity columns.
  • Ensure platform_source exists before any query or backfill path that references it.
  • Distinguish healthy process from initialized:false and ready:false; migration failure cannot look like a healthy ready worker.
  • Apply busy_timeout, WAL, foreign keys, and synchronous settings consistently to all SQLite connections.
  • Use atomic settings writes and BOM-tolerant reads.
  • Add prompt retention, incremental auto-vacuum for fresh DBs, and explicit maintenance for existing DBs without running heavy vacuum on prompt-critical paths.
  • Hide server-beta-only tools from worker-runtime tools/list.
  • Preserve proxy and provider env vars through sanitized subprocess environments where required.

Issues covered: #3118, #3094, #3091, #3080, #3064, #3038, #3025, #3013, #2999, #2978, #2976, #2969, #2916, #2821, #2793, #2769, #2772, #2767, #2729, #2705.

PRs to consume or supersede: #3065, #3063, #3044, #3041, #3002, #2904, #2849, #2770, #2632, plus env preservation from #3018.

Verification:

  • Direct upgrade tests v23 -> current, v24 -> current, v31 -> current, fresh -> current.
  • Background init failure returns /api/health.initialized=false and /api/readiness.ready=false with a useful dependency/error reason.
  • Concurrent hooks cannot truncate settings.json and cannot drop observations under SQLite lock contention.
  • DB growth tests confirm prompt retention and incremental vacuum behavior.

Phase 6 - Observer generator contract and poison-loop containment

Goal: make observation generation bounded, idempotent, and non-poisonous when there is nothing to record.

Work:

  • Treat benign empty/prose/no-observation output as an acknowledged no-op, not an invalid output that triggers respawn.
  • Add a bounded observer context window, strip base64/image payloads, and preserve required init prompt/system context.
  • Prevent headless observer generation from inheriting interactive third-party hooks.
  • Add a dead-letter path for repeated invalid observer outputs with rate-limited diagnostics.
  • Cap summarize Stop-hook retries and transcript persistence.
  • Remove minute-granularity volatile timestamps from injected context or move them to cache-stable metadata.
  • Ensure observer deny-lists include tool/workflow/skill/package forms that should never be summarized recursively.

Issues covered: #3074, #2970, #2960, #2958, #2956, #2955, #2935, #2906, #2872, #2866, #2846, #2817.

PRs to consume or supersede: #3136, #2943, #2942, #2927, #2905, #2901, #2885, #2884, #2857, #2739.

Verification:

  • No-observation sessions complete without respawn.
  • Long session with large tool payloads stays under provider context limits.
  • Prompt-too-long failures become bounded degraded observations, not silent drops.
  • Third-party hook inheritance test proves headless observer runs in sanitized mode.
  • Transcript file count and size are capped.

Phase 7 - Project scoping and Chroma metadata identity

Goal: define one project identity model used by SQLite, Chroma, context injection, search, dream namespaces, and migrations.

Work:

  • Introduce a canonical project identity object with cwd key, git-root key, repo-relative key, platform source, optional user override, and alias/remap history.
  • Apply that identity to observation writes, generated observations, Chroma metadata, semantic queries, FTS fallback, stats endpoints, and context injection.
  • Make cwd/worktree/submodule/remap reconciliation idempotent, not one-shot.
  • Do not collapse monorepo subdirectories into one git-root key unless explicitly configured.
  • Inject distilled dream namespaces alongside recent raw memory using the same project identity rules.

Issues covered: #3062, #2967, #2882, #2864, #2842, #2834, #2971, #2979.

PRs to consume or supersede: #3047, #3005, #2883, #2856, #2858, #2827, #2665, #2671.

Verification:

  • Matrix for monorepo subdirectory, nested git repo, submodule, worktree, removed worktree, repo re-home, parent git init, and .claude-mem.json override.
  • Chroma semantic query finds observations written under equivalent alias/remap keys.
  • Dream namespace memories inject for the correct project without leaking unrelated projects.

Phase 8 - Final integration and release gate

Goal: land the holistic branch only when runtime contracts are verified together.

Work:

  • Merge/rebase accepted PRs into plan/root-cause-holistic-fixes in phase order.
  • Add integration tests for cross-cluster failure modes: Windows version recycle with Chroma child, marketplace/cache mismatch with worker spawn, migration failure with hook behavior, project remap with Chroma semantic query.
  • Update docs for worker lifecycle, Chroma degraded mode, install repair roots, migration readiness, observer no-op behavior, and project identity.
  • Close child issues only with a comment naming the phase and verification that covers them.

Verification:

  • Run the repo's existing test, typecheck, and build commands.
  • Run targeted suites for worker lifecycle, supervisor/process registry, Chroma sync, SQLite migrations, installer/runtime packaging, observer, project scoping, and Windows spawn contracts.
  • Run platform smoke tests on Windows, macOS, Linux, and WSL2.
  • Run artifact smoke tests from generated marketplace/cache layouts, not from the source tree.

Verification Matrix

Area Required scenarios Expected proof
Worker lifecycle fresh boot, version mismatch recycle, shutdown, restart, stale PID, unrelated port holder, child-inherited socket, five concurrent launchers /api/health PID/version/path proof, readiness proof, bounded hook timeout, no infinite retry
Worker roots dev tree, marketplace root, version cache root, CLAUDE_PLUGIN_ROOT present/absent, CLAUDE_MEM_WORKER_SCRIPT_PATH override one executable root owns the data dir; stale roots are repaired or ignored
Windows hosts Claude Code, Codex, VS Code extension, PowerShell, cmd.exe, Git Bash, WSL2 correct Windows command config, no POSIX string through PowerShell, no console flashes
Spawn hygiene bun, uvx, git, provider SDK, tree-sitter, hook scripts, worker daemon windowsHide:true, no shell:true plus args, direct uvx, centralized .cmd handling
Chroma uv missing, uv < 0.5.31, Windows dep spec with </>, prewarm timeout, transport close, worker restart, dual data-dir writer degraded health status, full process-tree cleanup, no dual writers, FTS5 fallback
Install/runtime clean install, repair, missing marker, missing deps, missing bun, missing uv, ERESOLVE, marketplace/cache mismatch taxonomy result, repaired executable root, generated artifact imports without repo node_modules
SQLite migrations fresh DB, v23, v24, v31, current, old unique indexes, missing platform_source direct upgrade success, readiness failure on migration error, no hidden healthy-not-ready state
Concurrent data writes parallel hooks, settings write/read, DB lock contention, prompt retention, auto-vacuum no truncation, no dropped observations, bounded DB growth
Observer no-op/prose output, skip summary, prompt too long, base64/image payloads, third-party hook inheritance, long session no poison respawn, bounded context, sanitized headless env, capped transcripts
Project identity monorepo, subdir, submodule, worktree, removed worktree, repo re-home, parent git init, dream namespace SQLite, Chroma, stats, context injection, and semantic search agree on identity
Auth/env boundary proxy vars, skip-auth vars, missing Credential Manager entry, expired OAuth with valid fallback token env preserved where required; absent credentials are neutral misses; warnings are actionable

Anti-Pattern Guards

  • Do not hand-edit generated plugin/scripts/*.cjs; edit source and rebuild.
  • Do not introduce a second worker liveness oracle. Use /api/health plus /api/readiness for lifecycle decisions.
  • Do not use /api/version alone for lifecycle decisions; it lacks PID, path, initialization, and dependency state.
  • Do not put health checks behind the spawn lock. The lock gates spawning only.
  • Do not hardcode port 37777; read the configured worker host and port.
  • Do not trust PID files without start-token ownership or process proof.
  • Do not recover stale ports by killing arbitrary processes without ownership proof or clear user-facing diagnostics.
  • Do not spawn Chroma via cmd.exe /c, shell redirection, or shell-quoted dependency strings.
  • Do not pass dependency specifiers through a shell where <, >, or quotes can be reinterpreted.
  • Do not leave Chroma, uv, python, provider SDK, or observer child processes outside ProcessRegistry/tree cleanup.
  • Do not add new Windows spawn sites without windowsHide:true and a test or grep guard.
  • Do not add host config strings directly when buildShellCommand() or host generator APIs can produce them.
  • Do not make runtime repair target only the version cache if the marketplace root is the executable root.
  • Do not classify installer failures as silent. Use ABORT, FAIL_LOUD_PER_IDE, or WARN_CONTINUE.
  • Do not use global --force or broad dependency bypasses for ERESOLVE; keep fallbacks targeted and diagnosed.
  • Do not mark the worker ready when migrations failed or initialized:false.
  • Do not write version-only migrations that assume intermediate schema states; probe columns/indexes idempotently.
  • Do not open SQLite connections without the required pragmas and busy timeout.
  • Do not treat benign no-observation/prose output as observer poison.
  • Do not persist unlimited observer transcripts or prompt text.
  • Do not collapse project identity to git root only; preserve cwd/subproject/worktree/submodule identity and explicit overrides.
  • Do not close child issues just because this plan exists; close only after the phase verification that covers the child has passed.

Suggested Child-Issue Redirect Comment

After this issue is opened and a child issue is mapped to a phase:

This is being tracked as part of the root-cause reliability plan in #[NEW_PLAN_ISSUE], Phase [N]. The fix should land through that plan because this symptom shares the same lifecycle/spawn/packaging/migration/project identity contract as the linked cluster. This child should close only after the phase verification matrix row passes.

Out Of Scope

  • Net-new provider and extensibility roadmap work from [plan-12] Provider & Extensibility Roadmap — net-new capabilities, not defects #2785 unless it fixes runtime auth/env boundaries that block existing flows.
  • Feature requests unrelated to worker lifecycle, Chroma, Windows process behavior, install/runtime packaging, migrations, observer loops, project scoping, or data integrity.
  • Cosmetic docs/UI changes that do not affect the runtime contract.

Metadata

Metadata

Assignees

No one assigned

    Labels

    plan

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions