feat(cli+api+mcp): agent walk-aware CLI + council doc fixes + 5 AI-user friction fixes

[mbachaud]

Summary

Two commits, two slices of work, both surfaced by AI-user testing of the CLI+MCP surface:

1. 9dbd960 — Council prioritized doc fixes + agent walk-aware CLI. Closes the gap the first council flagged on the v1 CLI (PR feat(cli): v1 cold-start helix-cli (query/ingest/status/diag/config) #71): agents now drive genome lookups via subprocess CLI calls instead of MCP-injected context. Plus the README / ROSETTA / docs fixes the council prioritized.
2. 0a68896 — Five friction points reported by a second AI-user pass on origin/master@93deaf2. Each is a one-shot fix with a focused unit test.

Branch is two commits ahead of origin/master. Full mock suite green (1924 passed, 0 failures, ~8min).

Commit 1 — Agent walk-aware CLI + council doc fixes

CLI agent surface (4 new subcommands; identical JSON shape to the matching MCP tools + HTTP endpoints):

• helix packet <text> --task-type edit|ops|... — agent-safe bundle with verified / stale_risk / refresh_targets
• helix gene get <id> / helix gene preview <id> --chars N — single-document inspection
• helix neighbors <text> --k N — SEMA graph walk
• helix refresh-targets <text> — reread plan only

api.HelixSession: promote gene_get, packet, refresh_targets, neighbors from v1.1-deferred to v1 — they back the four new CLI subcommands without requiring an HTTP server or MCP host. Pure in-process wrappers over Genome.get_gene, build_context_packet, and the existing SEMA codec. Read-only.

Docs: README adds an "Agent CLI surface (no server required)" section and sources the 28.7× / 5.4× headline against the reproducer at benchmarks/bench_rag_vs_sike_tokens.py. ROSETTA adds a "Response & routing types (STAYS — no biology twin)" section covering ContextWindow / ContextPacket / KnowBlock / MissBlock / RefreshTarget / ContextHealth / ContextItem / QueryResult / IngestResult / StatsResult. The HGT → cross_store_import row is annotated as a forward-pointer; the OPEN/EUCHROMATIN/HETEROCHROMATIN → OPEN/WARM/COLD row notes the rename is deferred to R3.

Commit 2 — Five AI-user friction fixes

#	Friction reported	Fix
1	helix query and helix diag corpus silently ignored HELIX_CONFIG / HELIX_GENOME_PATH — read/created ./genome.db while helix status looked at the configured genome	api.py: open_session() now routes through load_config() (single-source with helix status)
2	helix status --json falsely reported a healthy-but-slow server as unreachable (1.5s timeout, cold-start /health takes 5-10s)	helix_status.py: default 1.5s → 10s, override via HELIX_STATUS_TIMEOUT_S, malformed-value fallback warns instead of crashes
3	MCP helix_context failed schema validation — /context returns the Continue HTTP list shape, MCP host expected Dict[str, Any]	New _unwrap_context_list() helper unwraps the single-entry list; applied to helix_context and helix_document_query. Continue IDE compatibility untouched.
4	helix ingest README.md raised TranscriptionError: Pack failed: Ribosome is disabled on cold-start install	config.py: load_config() auto-flips ingestion.backend → "cpu" when ribosome is disabled. Routes to the spaCy/heuristic CpuTagger that's already in tree. Explicit cpu/hybrid configs untouched. LLM-free pillar intact. Logs WARNING.
5	helix.exe broken (pip console script pointed at deleted editable path; Scripts dir off PATH)	Added helix_context/cli/__main__.py so python -m helix_context.cli works as a fallback. Recovery recipe + pip install --force-reinstall --no-deps documented in docs/clients/cli.md.

Test plan

• 38 new unit tests (10 cli_packet/refresh/neighbors/gene + 10 api_walk + 3 config + 6 mcp_server + 9 dispatcher/integration). All pass.
• Full mock suite: python -m pytest -m "not live and not requires_rocm and not requires_real_cuda and not requires_mps" → 1924 passed, 0 failures, 10 skipped, 26 deselected, 2 xfailed in 470s.
• Manual smoke against a real genome: helix packet "foo" --json, helix gene get <id> --json, helix refresh-targets "edit X" — not done here; reviewer should sanity-check on their workstation before merge.
• Manual MCP smoke: confirm Claude Code / Cursor see helix_context returning a dict (not a list) after the unwrap fix.

Related issues

This PR does not close any open issue outright. Two issues partially overlap and should be reconciled at merge time:

• MCP slimdown — Move 2: CLI parity for 13 deprecation candidates #80 (MCP slimdown — Move 2: CLI parity for 13 deprecation candidates) — this PR ships 4 of the 13 candidates as CLI peers (packet, gene get/preview, neighbors, refresh-targets), but under different command names than MCP slimdown — Move 2: CLI parity for 13 deprecation candidates #80 specifies (top-level helix packet etc. vs. spec's helix diag packet / helix diag refresh-plan). The remaining 9 candidates are not addressed here. See "Note on the MCP slimdown plan" below.
• Operational silent-failure modes: Headroom upstream rewrite, hardware balloon, ribosome paid WARN, WAL bloat #65 (Operational silent-failure modes) — different specific items than the four in this PR (SF1-SF4 are Headroom upstream rewrite, hardware balloon, ribosome paid WARN, WAL bloat). Spiritually adjacent — all four fixes in commit 2 are silent-failure-mode cleanups in the same vein.

Note on the MCP slimdown plan (#78 / #79 / #80 / #81)

Building the four CLI peers in this PR was originally framed under the council's recommendation to "complete the CLI as an agent tool." The earlier round of analysis on PR #78 (MCP slimdown spec) found that:

• The 13-tool demotion-to-CLI premise rests on CLI peers existing — 9 of 13 still don't, and would degrade agent UX on day-one.
• The latency-defense argument the spec uses for keeping 6 MCP tools (in-stdio beats subprocess.run) applies equally to most of the demoted tools agents walk during a multi-step loop.
• The "1038 → 450 adapter LOC" headline is engineering convenience, not user value.
• Agent UX is the product; shrinking the easiest agent surface to save adapter code works against the product thesis.

Recommendation kept from that analysis: don't merge #78 as written. What stays valuable from the slimdown work:

• MCP slimdown — Move 1: HELIX_IDENTITY_TOML loader #79 (HELIX_IDENTITY_TOML) — legitimate ergonomics win regardless of tool count. Worth landing as a separate small PR.
• Drop the 4 software-vocab aliases (helix_document_*) — they're redundant after R2 and shipping is no-cost.
• Keep building CLI peers (MCP slimdown — Move 2: CLI parity for 13 deprecation candidates #80 scope) as additions, not replacements. The 4 in this PR are a start; the remaining 9 are valuable as a scripting surface. Reconcile naming with the spec at merge.

🤖 Generated with Claude Code