[KrasimirKralev]

Restore server instructions in ordinary named listings, including text and JSON output, without requiring --no-oauth.

Uncached discovery closes its connection before the CLI requests instructions. Retain a normalized snapshot in the runtime connection cache under its existing generation/abort guard, while preserving active-connection precedence and clearing the snapshot when instructions are absent or a definition is replaced. OAuth policy, connection cleanup, and all-server summaries keep their existing behavior.

Fixes #455. Restores the contract from #76 and preserves the lifecycle safeguards from #383. Thanks @KrasimirKralev for the fix and real CLI regressions, and @Strajk for the reproduction.

Validation: reproduced the five new failing regression cases on main, covering legacy and modern servers over stdio and HTTP plus the cache snapshot. Added coverage for cancelled setup with nonempty instructions and subsequent absent instructions. Independent Codex review found no actionable P0–P2 findings. Full remote checks and exact-head CI are required before merge.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-20T07:51:12.933893Z	095b098	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[clawsweeper]

Codex review: needs maintainer review before merge.

What this changes

Retains server instructions after uncached discovery so named listings include them in text and JSON output.

Example: A stdio server returns instructions HELLO-INSTRUCTIONS during initialization.

• Before: Ordinary named listings omit the instructions unless --no-oauth is supplied.
• After: Text shows Instructions: HELLO-INSTRUCTIONS and JSON includes the instructions without requiring --no-oauth.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused contract repair with supplied shipped-CLI evidence, relevant regression coverage, passing head checks, and no actionable finding.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (terminal): The contributor's terminal transcript exercises the built CLI on Linux with Node 24.21 against a real stdio server, showing the connection-cache fix restores HELLO-INSTRUCTIONS in ordinary text and JSON listings while preserving --no-oauth output.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: Users and agents miss server-provided guidance in ordinary named listings.
Reason: Restores documented behavior and the owner-confirmed named-listing contract without adding configuration or changing summary listings.

Merge readiness

✅ Ready for maintainer review

This PR fixes a documented behavior still broken on current main; no actionable correctness or security defect was found.

Priority: P2
Reviewed head: 095b098ae2e7cebb5e0e73b8a4929c61858d64fc

Before merge

None.

Findings

None.

Agent review details

How this fits together

The CLI discovers tools through the runtime connection cache, then retrieves initialization instructions to render the named-server listing.

flowchart TD
  A[Named list command] --> B[Runtime tool discovery]
  B --> C[MCP server initialization]
  C --> D[Guarded instruction snapshot]
  B --> E[Close uncached connection]
  E --> F[Read server instructions]
  D --> F
  F --> G[Text or JSON output]

Loading

Technical review

Best possible solution:

Retain initialization instructions through the existing connection-cache owner while preserving OAuth behavior and lifecycle invalidation.

Do we have a high-confidence way to reproduce the issue?

Current-main source establishes the failure path, and Strajk's minimal server plus the contributor's before/after CLI transcript provide a concrete reproduction; this review executed no target code.

Is this the best way to solve the issue?

The snapshot repairs the shared runtime owner without reconnecting, extending connection lifetime, or changing OAuth policy.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 5362d60d2e17.

Provenance checked

• Instruction lookup and normalization keeps the original intent (69c98e8: refactor: dedupe and modularize runtime, OAuth, and CLI internals #249 extracted the existing runtime cache without intended public behavior changes; the original display contract is confirmed in the discussion of MCP server instructions from initialize response not surfaced to agents #76.)
• Retained metadata lifecycle keeps the original intent (f96d403: Prevent late aborted or superseded setup from replacing current metadata and leaking connections.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

• Existing product contract: The CLI reference promises initialization instructions for named listings; steipete confirmed text and JSON support and intentionally excluded all-server summaries in MCP server instructions from initialize response not surfaced to agents #76 (comment). (docs/cli-reference.md:16, 5362d60d2e17)
• Current-main failure path: autoAuthorize:false selects uncached discovery unless OAuth is explicitly disabled; listTools closes that context before the CLI calls getInstructions, whose main implementation has no retained fallback. (src/runtime.ts:268, 5362d60d2e17)
• Focused repair: The introduced diff retains normalized instructions under the existing generation and abort guard, clears them on absent instructions or definition replacement, and preserves active-entry precedence. (src/runtime/connection-cache.ts:332, 095b098ae2e7)
• Supplied shipped-CLI proof: The full PR body records Linux and Node 24.21 runs of the built CLI against Strajk's minimal stdio reproduction from list: server instructions missing unless --no-oauth (regression of #76) #455, showing HELLO-INSTRUCTIONS after the fix in text and JSON with and without --no-oauth; captured sourceRevision is 9c96a99605ea3058fc9baa6fb108265ccba8f8b27b769abda53b2411c4fff7b8. (095b098ae2e7)
• Real-CLI regression coverage: Added cases invoke dist/cli.js for ordinary text and JSON listings against legacy and modern fixtures over stdio and HTTP; runtime tests cover retained instructions, normalization, active precedence, blank clearing, and definition replacement. (tests/e2e-fixture-servers.test.ts:101, 095b098ae2e7)
• Lifecycle provenance: fix: cancel and retire uncached discovery connections #383 introduced the guard preventing aborted or superseded setup from replacing retained metadata; this PR places instructions inside that guard. (src/runtime/connection-cache.ts:332, f96d40303db5)

Likely related people:

• Sebastien Tardif: Raw commit f96d403 adds src/runtime/connection-cache.ts:333 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: f96d40303db5; files: src/runtime/connection-cache.ts)

Review metrics

Metric	Value	Why it matters
Production and regression coverage	Production +19/-7; tests +63/-0; changelog +1	The small runtime addition follows an existing metadata-retention pattern, with coverage through both the runtime and shipped CLI.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #455
Summary: This PR supplies the focused repair for instruction loss after uncached discovery.

Members:

• canonical: list: server instructions missing unless --no-oauth (regression of #76) #455 - Owns the reproduced missing-instructions defect addressed by this PR.
• adjacent_distinct: MCP server instructions from initialize response not surfaced to agents #76 - Established the named-listing display contract.
• adjacent_distinct: fix: cancel and retire uncached discovery connections #383 - Established cancellation and supersession safeguards retained by this repair.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Labels

Label changes:

• add P2: Documented server guidance disappears from ordinary listings, but tool discovery remains usable and --no-oauth provides a workaround.
• add proof: sufficient: Contributor real behavior proof is sufficient.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P2: Documented server guidance disappears from ordinary listings, but tool discovery remains usable and --no-oauth provides a workaround.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.
• proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 20, 2026, 3:59 AM ET / 07:59 UTC.

[steipete]

Reviewed the runtime lifecycle fix and independently reproduced the regression. The focused repair, strengthened coverage, full remote code checks, and exact-head CI are ready.