LearnNewsExamplesServices
Frontmatter
id13475
titleExpose live MCP sibling-process diagnostics
stateClosed
labels
enhancementdeveloper-experienceaiarchitecturemodel-experience
assigneesneo-gpt
createdAtJun 18, 2026, 5:05 PM
updatedAtJun 19, 2026, 8:50 AM
githubUrlhttps://github.com/neomjs/neo/issues/13475
authorneo-gpt
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtJun 19, 2026, 8:50 AM

Expose live MCP sibling-process diagnostics

Closed v13.1.0/archive-v13-1-0-chunk-3 enhancementdeveloper-experienceaiarchitecturemodel-experience
neo-gpt
neo-gpt commented on Jun 18, 2026, 5:05 PM

Context

Release classification: boardless operational hardening; this is not a v13 release blocker.

A 2026-06-18 stability sweep found the local Agent OS healthy, but Memory Core startup logging reported several peer processes holding SQLite files, including long-lived desktop harness processes. The existing signal appears at boot only, while the richer diagnostic script exists separately. Operators need a cheap on-demand way to see the current holder picture without restarting a server or digging through stale boot logs.

Verification before filing:

  • Live latest-open sweep: checked latest 20 open issues at 2026-06-18T15:04:02Z; no equivalent open issue found.
  • Targeted GitHub duplicate sweep: MCP sibling process diagnostics SQLite holder harness returned no open matches.
  • A2A in-flight sweep: checked recent 30 messages; no overlapping lane claim found.
  • KB/local sweep: #10187 created the read-only concurrency diagnostic script and #10206 added boot-time harness classification. No active ticket covers on-demand live exposure through a current health/diagnostic surface.

The Problem

When several harnesses remain open for hours, each may keep multiple MCP-related processes alive. That is normal up to a point, but it becomes hard to distinguish expected steady state from stale or accidental process accumulation.

Today the best live answer is manual: rerun the diagnostic script, inspect process output, or restart a server and read its startup line. That is too awkward for routine Agent OS health triage, and startup logs become stale immediately after process topology changes.

The Architectural Reality

  • ai/scripts/diagnostics/diagnoseMcpConcurrency.mjs already performs read-only SQLite holder discovery.
  • ai/services/memory-core/helpers/harnessClassifier.mjs already classifies parent process chains by harness family.
  • ai/mcp/server/memory-core/Server.mjs boot-time sibling logging groups holders at startup, but it is not a current-state query surface.
  • Recent Memory Core healthcheck work added optional detail parameters; expensive process inspection should stay opt-in, not part of every hot-path healthcheck.

The Fix

Expose the existing sibling-process holder data through an on-demand diagnostic surface:

  • Add a structured current-state output path for SQLite holder diagnostics, reusing the existing script/classifier logic.
  • Prefer a non-default healthcheck detail option or explicit diagnostic tool/script alias so normal healthchecks remain cheap.
  • Include grouped harness counts, PIDs, unknown classifications, and enough parent-chain/command context to identify stale holders.
  • Keep the surface read-only; do not kill, signal, or manage peer processes.
  • Add thresholds or warning fields for unknown holders and unexpectedly high counts without treating ordinary multi-harness steady state as unhealthy by default.
  • Add focused unit/stub coverage around classification/projection rather than shelling out in tests.

Contract Ledger Matrix

Target Surface Source of Authority Proposed Behavior Fallback / Edge Case Docs Evidence
MCP sibling holder diagnostic output diagnoseMcpConcurrency.mjs + harnessClassifier.mjs Exposes current SQLite holder counts grouped by harness plus PID/context details. If lsof/ps is unavailable, return a degraded diagnostic with the error captured, not an unhealthy server verdict. Script/help text or MCP tool schema description. Stubbed test for grouped projection and unavailable-platform fallback.
Memory Core health/diagnostic surface Existing optional healthcheck-detail pattern Expensive process-holder inspection is opt-in and never part of the default hot-path healthcheck. Default healthcheck stays current/healthy when the database is usable even if process-holder diagnostics are skipped. Tool schema/config docs if surfaced through MCP. Test proving default output omits holder scan and opt-in output includes it.

Decision Record impact

None. This is an observability extension over existing read-only diagnostics and does not change the shared-SQLite concurrency model.

Acceptance Criteria

  • There is an on-demand structured way to inspect live Memory Core SQLite holder processes without restarting Memory Core.
  • The output groups holders by harness classification and includes PID/context details for unknown or stale-looking holders.
  • Default healthchecks do not run expensive process-holder scans.
  • Diagnostic failures are reported as degraded diagnostic data, not as Memory Core unhealthy when the actual database path is working.
  • The implementation is read-only and never attempts to kill or manage peer harness processes.
  • Focused tests cover grouped classification/projection and default-versus-opt-in behavior.

Out of Scope

  • Auto-killing or restarting desktop harness processes.
  • Solving stale Chroma/SQLite cache coherence; that is covered separately.
  • Changing the shared SQLite WAL concurrency architecture.
  • Replacing the existing diagnoseMcpConcurrency.mjs diagnostic.

Related

  • #10186 — original cross-harness concurrency diagnostic epic.
  • #10187 — read-only diagnoseMcpConcurrency script.
  • #10206 — boot-time harness classification for sibling PID logging.
  • #13466 / #13468 — stale Chroma handle recovery after daemon recycle.

Origin Session ID: ef8b263f-1cdc-431a-a730-2c6c2ff26f98

Retrieval Hint: "MCP sibling SQLite holders live diagnostics harness classifier long-lived desktop harness processes"