fix(state): read-only session search silently returned no results; add stateless memory/session_search MCP shims

[fcavalcantirj]

Summary

Read-only SessionDB handles silently returned [] from search_messages() — the FTS availability probe latched False for the handle's lifetime on ANY error, including transient ones (database is locked during a checkpoint). This PR classifies transient vs absent for both the primary and trigram probes, and adds stateless memory / session_search MCP shims to the hermes-tools server (implements #26604) so runtimes that can't reach the agent-loop tools (codex app-server) regain both capabilities.

Stacking

NousResearch#65982 (claude-agent-sdk provider) is stacked on this PR — its branch contains these five commits at 9756d26e5 plus newer polish commits that ride this PR's head. Merge this first; #65982 restacks cleanly.

Commits (10)

• Five reviewed commits through 9756d26e5: RO probe classification, claude_sdk_session_id column (consumer ships in feat(providers): claude-agent-sdk provider — the official Agent SDK as a first-class runtime under subscription OAuth (fail-closed) #65982), MCP shims + schema fix, session-id comment honesty, HERMES_MCP_SESSION_ID removal (sweeper feedback — contract narrowed as documented).
• Five follow-ups through b1a78807e (2026-07-26): the codex-runtime docs page no longer claims memory/session_search are unavailable (it was made false by this PR); RO-probe comment states what the query path actually does; a transient-lock test now drives the PRIMARY probe (the old harness only intercepted the trigram probe); the seeded-rows shim test asserts hit-side fields (old assertion passed on zero hits); shim cites anchored to open tracker codex_app_server runtime: expose memory + session_search via stateless MCP shim #26604 instead of closed hermes_tools_mcp_server: scope docstring claims memory/session_search/delegate_task but EXPOSED_TOOLS excludes them #26567.

Verification

Full targeted suite green (112 tests across shims/server/state); each commit buildable standalone; uv lock --check clean (no dependency changes).

🤖 Generated with Claude Code

[tonydwb]

Looks good. No obvious issues found.

---

Reviewed by Hermes Agent

[tonydwb]

Code Review Summary

Verdict: Comment

Prior COMMENT review noted. Medium PR (644 additions) — read-only session search fix + stateless memory/session_search MCP shims. Addresses silent failure when session search returns no results.

Key observations:

• Adds shims for memory/session_search MCP in read-only contexts
• Fixes silent failure path for stateless scenarios
• No security concerns
• No debug artifacts

Clean fix for the described issue. LGTM.

---

Reviewed by Hermes Agent

[tonydwb]

Code Review Summary

Verdict: Comment

Summary

Fix: model wizard now recognizes credential pool keys in auth.json. Allows credentials added via auth add to appear in model selection.

Clean fix. No security concerns.

---

Reviewed by Hermes Agent

[teknium1]

Thanks for addressing a real read-only FTS defect and for preserving the generic _AGENT_LOOP_TOOLS refusal. Current main confirms the premise: the read-only SessionDB branch returns without setting _fts_enabled (hermes_state.py:1030-1047), and search_messages() then returns [] (hermes_state.py:5277-5278). The stateless MCP direction also matches the open maintainer-owned request in #26604.

Problems

• The session-search shim's own-lineage exclusion is not wired to the Codex MCP lifecycle. It reads HERMES_MCP_SESSION_ID at agent/transports/hermes_tools_mcp_server.py:286, but the managed MCP entry only supplies HERMES_HOME, PYTHONPATH, quiet mode, and redaction (hermes_cli/codex_runtime_plugin_migration.py:568-601). A repository-wide search found no producer of that session-id variable, so ordinary calls use current_session_id=None and can return the active session.

Suggested changes

• Carry the active Hermes session id through a session-aware MCP launch/request path and add an end-to-end regression covering exclusion of the current lineage. If that transport is not feasible for the shared stdio server, narrow the shim contract rather than claiming native exclusion.

Automated hermes-sweeper review.

[teknium1]

HERMES_MCP_SESSION_ID has no producer in the managed Codex MCP launch path: hermes_cli/codex_runtime_plugin_migration.py:568-601 only sets HERMES_HOME/PYTHONPATH/quiet/redaction. This is therefore None in normal runtime use and current-session lineage is not excluded. Please wire session-aware propagation and cover the real launch path, or narrow this behavior claim.

[fcavalcantirj]

You're right, and thanks for the precise pointer — _build_hermes_tools_mcp_entry() sets only HERMES_HOME / PYTHONPATH / HERMES_QUIET / HERMES_REDACT_SECRETS. I checked repo-wide across all file types: HERMES_MCP_SESSION_ID had no producer anywhere in product code — only the consumer, two doc comments, and two monkeypatch.setenv calls in tests. The one test that looked like coverage set the variable itself, so it proved the shim's internal plumbing and nothing about the launch path. In normal runtime it was None and own-lineage exclusion never ran.

I also don't think it should be wired where you pointed: that entry is serialized into ~/.codex/config.toml at migrate time, so a per-session id written there would be burned in stale — the same failure mode the _looks_like_test_tempdir guard already exists to prevent. There's now a test forbidding it.

The real mistake was inventing a variable that duplicates one Hermes already has. HERMES_SESSION_ID is written by set_current_session_id() (gateway/session_context.py:153), is in _VAR_MAP, and is bridged into the codex spawn env by _inject_session_context_env() inside hermes_subprocess_env() — the same inheritance HERMES_KANBAN_TASK relies on (codex_app_server.py:102). The value was already arriving; the shim was reading the wrong name.

Fixed by deleting HERMES_MCP_SESSION_ID and reading the canonical HERMES_SESSION_ID. No launch-path change, and deliberately no new HERMES_* variable — I didn't keep the old name as an override, since per AGENTS.md that would be a new non-secret env var with no consumer. Reading the canonical var also picks up the cross-session leak guard in _inject_session_context_env for free, which turns out to matter: a hand-rolled producer for the bespoke name would have sat outside that guard and could have carried a sibling session's id under a concurrent multi-session host, excluding the wrong lineage — a silent wrong answer rather than a silent no-op.

Tests: the fixture now clears HERMES_SESSION_ID (otherwise a developer's live session id leaks into the suite and the new tests pass spuriously), and exclusion is driven through the real producer via set_current_session_id() instead of setenv, so a producer/consumer name mismatch fails loudly instead of hiding. Both new tests were confirmed red before the fix.

While in there I audited the rest of the shim docs and corrected four claims that outran the code:

• the stale "we deliberately do not expose memory / session_search" note — this PR exposes them — plus its wrong line reference (model_tools.py:493; it's :606, gate at :1167);
• "faithful stateless equivalents" — not true for session_search, which adds a deterministic zero-hit OR-relaxation the native tool doesn't have;
• the claude-agent-sdk reference — that provider isn't in this PR;
• the consolidation-failure breaker listed as "inherited" — a fresh store per call resets its counter, so it can never trip here.

Also documented the staged-write caveat (with no foreground approver in a stdio subprocess the approval gate can return staged, so a write reports success without landing yet) and the fail-open behaviour when no session id is present — exclusion is simply inactive, no error.

One thing I'd rather state than overclaim: I verified that codex's spawn env carries HERMES_SESSION_ID by reading the code path and the HERMES_KANBAN_TASK precedent that production gating already depends on. I have not instrumented the codex binary itself to confirm it forwards inherited env to the hermes-tools child.

Not addressed here, flagging as a follow-up: CodexAppServerSession doesn't accept or forward env= to its client factory, so CodexAppServerClient(env=...) is effectively dead on that path.

[fcavalcantirj]

One correction to my reply above, before anyone relies on it: "the value was already arriving" holds only where the MCP host forwards the parent env — and the codex-managed launch specifically does not. Codex builds each MCP subprocess env from scratch (create_env_for_mcp_server, codex-rs/rmcp-client/src/utils.rs): a fixed whitelist (HOME/PATH/…), plus names listed in the entry's env_vars, plus the entry's literal env map — the parent env is not inherited. Our migration entry sets only HERMES_HOME/PYTHONPATH/HERMES_QUIET/HERMES_REDACT_SECRETS, so HERMES_SESSION_ID reaches the codex process (via _inject_session_context_env) and is then dropped at the codex→MCP hop. On that path own-lineage exclusion remains inactive (fail-open) — i.e., the "narrow this behavior claim" branch of your review applies to it, and the shim docs' fail-open wording is the accurate description there.

The clean wiring does exist on codex main: env_vars in the MCP server entry is a name-passthrough resolved from the codex process env at spawn time, so listing "HERMES_SESSION_ID" propagates the live id without serializing a value into config.toml (the burned-in-stale problem that ruled out the literal-env route). I can add that to _build_hermes_tools_mcp_entry with a launch-path regression here, or leave the contract narrowed as documented — happy to take direction. (For completeness: the stacked #65982 runtime sets the id explicitly in its MCP env map, so exclusion is active on that path.)

[fcavalcantirj]

Closing the loop on this thread with current state (2026-08-13): the producer gap is closed in code — b3b3508c0f wires the active session id through the codex MCP lifecycle by naming HERMES_SESSION_ID in the MCP entry's env_vars (codex's spawn-time name-passthrough delivers it), and d920b47ab adds the launch-path regression covering exactly the fail-open scenario you flagged. Also re-verified today: the branch merges clean against current main (bd6dcd4bd5-era) with all checks green, and the added claude_sdk_session_id column is safely picked up on pre-existing DBs by the declarative reconciler (_reconcile_columns) — empirically tested against a v25 DB built without the column. From our side the thread is addressed; happy to adjust if you see a remaining gap.

[fcavalcantirj]

@teknium1 — bumping the one open thread here, a week on (2026-07-19): own-lineage exclusion is fail-open on the codex-managed MCP path because codex builds each MCP subprocess env from scratch and the migration entry doesn't pass HERMES_SESSION_ID through. Direction needed, either way works: (a) wire the env_vars name-passthrough in _build_hermes_tools_mcp_entry plus a launch-path regression — pushed within a day of the word; or (b) keep the shim contract narrowed as now documented. The branch merges clean against today's main (merge-tree-checked), and the stacked #65982 restacks the moment this lands.

[fcavalcantirj]

The keep_open either/or is resolved in code as option (a) — the active session id wired through the codex MCP lifecycle, end-to-end regression included:

• d920b47ab wires delivery: the hermes-tools MCP entry now names HERMES_SESSION_ID in its env_vars — codex's spawn-time name passthrough — so the shim's own-lineage exclusion follows the active session. The burn-in rule stands untouched: no session value is ever serialized into config.toml, and the existing test pinning that rule still passes as-is.
• The new end-to-end regression (test_codex_entry_delivers_session_id_end_to_end) covers precisely the leg the production-producer test scoped out: the real producer writes the id → codex-style spawn snapshots exactly the names the real migration entry declares → the shim, reading only what was delivered, excludes the calling lineage.
• Hosts that don't deliver the var are unchanged: exclusion stays fail-open, results include the caller, no error — the documented behavior.

Gate: the full suite's failure set is identical to the branch's pre-change baseline (same pre-existing machine-env failures, none added, none removed).

With (a) landed the contract is no longer narrowed, so the (b) acceptance question dissolves — but if maintainers still prefer the narrowed-contract documentation for other hosts, happy to add it on top.

[GottZ]

This was generated by AI during triage.

Summary

Three PRs address or reference this issue complex: #26601 and #26603 correct the documentation contradiction in #26567, while #65978 implements the stateless memory/session_search capability tracked by #26604 and repairs read-only FTS probing.

Related pull requests

• docs(mcp): align hermes tools server scope #26601 [closed] fixes — (+23/-14) — n/a: This closed documentation fix aligns the MCP scope with EXPOSED_TOOLS and adds a regression test, but it was superseded by the already-merged docs(hermes_tools_mcp_server): align scope docstring with EXPOSED_TOOLS #26603 and remains relevant as its explicit duplicate.
• docs(hermes_tools_mcp_server): align scope docstring with EXPOSED_TOOLS #26603 [merged] best fix — (+14/-6) — n/a (recorded best fix for hermes_tools_mcp_server: scope docstring claims memory/session_search/delegate_task but EXPOSED_TOOLS excludes them #26567): This merged reference implementation removes memory, session_search, and delegate_task from the exposed scope, adds the actually exposed tools, and records the agent-loop rationale; the capability work was intentionally deferred to codex_app_server runtime: expose memory + session_search via stateless MCP shim #26604.
• fix(state): read-only session search silently returned no results; add stateless memory/session_search MCP shims #65978 best fix — (+936/-17) — n/a (recorded best fix for codex_app_server runtime: expose memory + session_search via stateless MCP shim #26604): The diff adds dedicated memory and read-only session_search shims, provider and failure guards, read-only FTS probe handling, lifecycle delivery of HERMES_SESSION_ID by name, and an end-to-end lineage-exclusion regression. The contributor keep_open review identified missing Codex lifecycle forwarding; the current diff addresses that specific objection, although the runtime documentation still says the session ID does not reach the shim and should be reconciled with the new behavior.

Duplicates

#26601 and #26603 substantially duplicate the doc-only correction for #26567; #26601 is closed as superseded by merged #26603. #65978 is not a duplicate because it implements the separate capability work tracked by #26604.

Suggested consolidation

Keep #65978 open with a salvage path: retain the stateless shims, read-only FTS correction, HERMES_SESSION_ID name-passthrough, and lifecycle regression, while asking the author to update the stale fail-open documentation and obtain contributor re-review of the previously blocking keep_open concern. Leave #26601 closed as a duplicate of #26603; #26603 remains the merged reference implementation for #26567.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I26567(["issue #26567 (closed)"])
    I26604(["issue #26604 (open)"])
    P65978["PR #65978 (open)"]
    P65978 -.->|partial| I26567
    P65978 -->|best fix| I26604
    class I26567 closed
    class I26604 open
    class P65978 open
    class P65978 best
    class P65978 target
    click I26567 "https://github.com/NousResearch/hermes-agent/issues/26567"
    click I26604 "https://github.com/NousResearch/hermes-agent/issues/26604"
    click P65978 "https://github.com/NousResearch/hermes-agent/pull/65978"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed (state tag in the node label).

Cross-PR triage: Reviewed 3 pull requests and 2 issues in this complex. Each diff was read against this issue; Assessment working set: 65 kB of PR diffs, 13 kB of issue/PR text, 19 kB of discussion (11 comments), 7 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.