Skip to content

docs(readme): note npx/ephemeral invocation under daemon model - #1541

Open
wassolles wants to merge 1 commit into
DeusData:mainfrom
wassolles:docs/npx-daemon-fingerprint
Open

docs(readme): note npx/ephemeral invocation under daemon model#1541
wassolles wants to merge 1 commit into
DeusData:mainfrom
wassolles:docs/npx-daemon-fingerprint

Conversation

@wassolles

Copy link
Copy Markdown

What

Docs-only PR adding the "npx / ephemeral invocation under the daemon model" note requested in #1539, so people hitting -32000: Connection closed today can find the cause and the managed-install fix.

Under v0.10+'s daemon model, a client launched via npx -y codebase-memory-mcp runs from an ephemeral package cache (~/.npm/_npx/<hash>/...). The daemon's admission barrier fingerprints each connecting client's running executable, and an ephemeral cache binary can't be fingerprinted, so the daemon rejects it as image_unverifiable. The rejected client then waits for admission until its timeout and exits with no JSON-RPC on stdout, which MCP clients surface as a silent connection failure (e.g. -32000: Connection closed). A managed install (codebase-memory-mcp install) places the binary at a stable, fingerprintable path and works.

Changes (README.md only, +3 lines)

  1. Session Coordination Daemon — a short paragraph immediately after the existing package-manager / admission-barrier discussion, explaining why ephemeral npx invocation is rejected and pointing to the managed install.
  2. Troubleshooting table — a row for the -32000 / silent-startup symptom with the managed-install fix, cross-linked to the daemon section.

Scope

Docs only — no code, no behavior change, no new dependencies, no tool/ABI surface. Does not close #1539 (the code-level fail-open/loud-failure work is separate); this only documents the current behavior and workaround as @maintainer asked for in #1539.

Refs #1539.

Verification

  • Reproduced the failure deterministically via npx and the success via the managed binary on Linux x86_64 (WSL2, ptrace_scope=1); details in the #1539 root-cause comment.
  • README renders with the two new entries; anchor links (#installation, #session-coordination-daemon) resolve to existing headings.

DCO: commit signed off (Signed-off-by: wassolles <136268174+wassolles@users.noreply.github.com>).

Under v0.10+'s daemon model, a client launched via npx runs from an ephemeral
cache path the daemon cannot fingerprint, so it is rejected as
image_unverifiable and dies after its admission timeout with no JSON-RPC on
stdout (surfaced by MCP clients as a silent -32000: Connection closed).

Document the cause and the managed-install workaround in two places:
  - Session Coordination Daemon: a paragraph next to the existing
    package-manager/admission-barrier discussion.
  - Troubleshooting table: a row for the -32000 symptom.

Refs DeusData#1539

Signed-off-by: wassolles <136268174+wassolles@users.noreply.github.com>
@wassolles
wassolles requested a review from DeusData as a code owner August 11, 2026 10:35
@github-actions

Copy link
Copy Markdown

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

  • It will not be closed for inactivity. No stale bot touches pull requests here.
  • It may still sit a while before a human reads it. That is on us, not on you.
  • Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

  • Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
  • Get CI green, or say which failures you believe are pre-existing.
  • Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
  • Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0.10.0/0.10.1 MCP server silent on initialize (regression from 0.9.0)

1 participant