Merge remote-tracking branch 'origin/main' into HEAD

# Conflicts:
#	tests/e2e/graph-engine.spec.js
#	tests/test_graph_engine_asset.py

Author: Coding-Dev-Tools

.github/workflows/codeql.yml

@@ -28,14 +28,14 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4
         with:
           languages: ${{ matrix.language }}
           build-mode: none
           config-file: ./.github/codeql/codeql-config.yml
       - name: Analyze
         id: analyze
-        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/analyze@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4
         with:
           output: codeql-results
       - name: Require clean CodeQL results

.github/workflows/release.yml

@@ -678,14 +678,14 @@ jobs:
         with:
           python-version: "3.11"
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4
         with:
           languages: ${{ matrix.language }}
           build-mode: none
           config-file: ./.github/codeql/codeql-config.yml
       - name: Analyze complete source tree
         id: analyze
-        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/analyze@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4
         with:
           output: codeql-results
           upload: never

.gitignore

@@ -138,3 +138,6 @@ uv.lock
 # mixed-case variants from slipping through on case-insensitive machines.
 /[Pp][Rr][Oo][Mm][Pp][Tt]_[Ss][Ee][Ss][Ss][Ii][Oo][Nn]_[Tt][Rr][Aa][Nn][Ss][Cc][Rr][Ii][Pp][Tt]_[Aa][Nn][Aa][Ll][Yy][Ss][Ii][Ss].md
 /[Ss][Ee][Ss][Ss][Ii][Oo][Nn]_[Tt][Rr][Aa][Nn][Ss][Cc][Rr][Ii][Pp][Tt]_[Qq][Uu][Ee][Rr][Yy]_[Pp][Rr][Oo][Mm][Pp][Tt].md
+
+# Command Code per-session scratchpad (agent working files, never package content).
+/$COMMANDCODE_SCRATCHPAD/

AGENTS.md

@@ -9,6 +9,14 @@ and pluggable.
 This is the canonical operating manual for any AI agent working in this repo. `CLAUDE.md`
 imports it. Read §0 before editing anything.
 
+### Internal subagent delegation
+
+When parallel delegation is appropriate for ChatGPT/Codex tasks, use exactly four bounded
+subagents inside the current task and chat. Keep delegation at one level: workers return bounded
+results and the parent performs the sole integration. Subagents must never be sent to Orca, Orca
+orchestration, or separate user-visible threads. Before finalizing, verify that all four workers
+returned and that no forbidden routing or descendant delegation occurred.
+
 ---
 
 ## 0. Read this first — two architectures live in one package

CHANGELOG.md

@@ -184,12 +184,26 @@ All notable changes to Engraphis are documented here. Format loosely follows
 - Folder imports report truncation explicitly: a folder with more matching files than the
   ceiling now warns and returns `truncated`/`matched_total`/`unreadable` fields instead of
   silently importing an alphabetically-first slice that looks complete.
+- The `engraphis_prime_agent` integration now ships a fleet wrapper that boots multiple
+  sub-agents (researcher / coder / reviewer / writer) with one shared memory workspace,
+  with fleet-wide configuration via `ENGRAPHIS_REPO` and per-agent override via the
+  `repo=` argument; the `engraphis-prime-agent install` subcommand configures a target
+  prime-agent configuration file and `python -m engraphis_prime_agent install`
+  works directly from the installed wheel.
 
 ### Fixed
 
 - The Every node dashboard view no longer crashes on open: a declaration-order bug in the
   renderer threw during construction before anything painted. The scene canvas also keeps its
   accessible role/label now instead of being hidden from assistive technology.
+- Prompt-only recall now honours an opt-in `ENGRAPHIS_RECALL_ARM_CANDIDATE_K` env var (and
+  the matching `RecallEngine(arm_candidate_k_cap=...)` constructor argument) that clamps both
+  the first-page widening (`candidate_k + min(250, candidate_k*3)`) and the second-page
+  ceiling, so operators can trade untrusted-scope widening for latency on the new k=50
+  default without code changes. The accompanying benchmark test,
+  `test_recall_arm_candidate_k_cap.py`, uses a 300-fact trusted corpus because both requested
+  arm depths clamp to the same 49 rows on a smaller corpus and the timing assertion was
+  unreliable. Default behaviour is unchanged.
 - Import previews now page the source manifest exactly like execution, so vaults whose manifest
   outgrew one list page (10k identities) no longer show manifest-only files as silently absent
   from the preview plan; beyond-boundary rows are reported as `missing` instead of dropped.

README.md

@@ -396,6 +396,51 @@ including `engraphis_check_update`, is in the [MCP tool reference](https://githu
 For installation, configuration, lifecycle commands, and the local trust boundary, see the
 [Pi extension guide](https://github.com/Coding-Dev-Tools/engraphis/blob/main/integrations/pi/README.md).
 
+### Command Code SessionStart hook
+
+`integrations/commandcode/` ships a SessionStart hook that warms up a new
+session with bounded, recalled context from the local Engraphis gateway. Fails
+open on timeout and is installed via `python scripts/install_cc_hook.py`.
+
+### prime-agent fleet
+
+`integrations/prime_agent/` ships a first-party Python package for
+[PrimeIntellect prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
+that exposes the same nine Smart MCP tools, with a `PrimeAgentFleet` of eight
+named sub-agents (`researcher`, `planner`, `coder`, `reviewer`, `tester`,
+`documenter`, `monitor`, `integrator`) sharing one `engraphis-mcp` stdio
+subprocess. Install via `pip install ./integrations/prime_agent` and register
+with `python scripts/install_prime_agent.py`. See the
+[prime-agent integration guide](https://github.com/Coding-Dev-Tools/engraphis/blob/main/integrations/prime_agent/README.md).
+
+**What the integration is.** A `PrimeAgentFleet` is a thin Python layer
+around the same `engraphis-mcp` Smart gateway every other host uses. At
+runtime the fleet holds one shared `EngraphisMcpClient`, which owns one
+`engraphis-mcp` subprocess over JSON-RPC stdio. Each of the eight named
+sub-agents gets its own Engraphis session (started lazily on first tool use)
+and its own default `repo` scope, so per-role memory is isolated while the
+local gateway stays single-process. The eight sub-agent names
+(`researcher`, `planner`, `coder`, `reviewer`, `tester`, `documenter`,
+`monitor`, `integrator`) are the fixed default; pass `agent_names=[...]` to
+`PrimeAgentFleet(...)` for a custom set. Concurrent tool calls serialize at
+the JSON-RPC frame layer through an `asyncio.Lock`, so framework-level
+parallelism (eight sub-agents reasoning at once) is preserved while the
+underlying MCP transport remains one ordered stream. The only integration
+surface is `EngraphisPrimeAgent.register()` in
+`integrations/prime_agent/src/engraphis_prime_agent/agent.py` -- that is the
+single adapter point to override if prime-agent's tool-registration API
+differs from the assumed `target.register_tool(name, fn, schema=...)`
+contract.
+
+The design -- eight named sub-agents, one shared stdio subprocess,
+per-agent session bootstrap, and `ENGRAPHIS_*`-only environment forwarding
+to the gateway -- is recorded in `~/.commandcode/plans/prime-agent-integration.md`
+on the host where the integration was developed. When that host plan is not
+available (other contributor machines, CI), the same design is summarized in
+the PR description that introduced the integration and in the
+[prime-agent integration guide](https://github.com/Coding-Dev-Tools/engraphis/blob/main/integrations/prime_agent/README.md)
+("Architecture" and "Concurrency model" sections).
+
 ## Quickstart: repository graph
 
 ```bash
@@ -721,8 +766,8 @@ file. It never searches the working directory for `.env`, and explicit process v
 | `ENGRAPHIS_ALLOW_AUTOMATIC_CRITICAL_RETENTION` | `false` | Opt in only when an LLM supervisor may automatically assign the long-lived `critical` class; explicit user-selected critical retention is unaffected |
 | `ENGRAPHIS_WHISPER_MODEL` | Not set | Enables local faster-whisper audio/video transcription |
 | `ENGRAPHIS_POSTGRES_DSN` | Not set | CLI-only PostgreSQL source; used for the connection and never stored |
-| `ENGRAPHIS_POSTGRES_CONNECT_TIMEOUT` | `10` | PostgreSQL introspection connection timeout in seconds (bounded to 1–120) |
-| `ENGRAPHIS_POSTGRES_STATEMENT_TIMEOUT_MS` | `30000` | Per-introspection PostgreSQL statement timeout in milliseconds (bounded to 1–300000) |
+| `ENGRAPHIS_POSTGRES_CONNECT_TIMEOUT` | `10` | PostgreSQL introspection connection timeout in seconds (bounded to 1--120) |
+| `ENGRAPHIS_POSTGRES_STATEMENT_TIMEOUT_MS` | `30000` | Per-introspection PostgreSQL statement timeout in milliseconds (bounded to 1--300000) |
 | `ENGRAPHIS_GRAPH_TOKEN` | Not set | Bearer token for `engraphis-graph-server`; required off-loopback |
 | `ENGRAPHIS_GRAPH_HOST` / `ENGRAPHIS_GRAPH_PORT` | `127.0.0.1` / `8720` | Read-only graph/recall server bind address |
 | `ENGRAPHIS_LLM_PROVIDER` | `openai` | `openai \| anthropic \| google \| openrouter \| custom` |
@@ -743,10 +788,20 @@ file. It never searches the working directory for `.env`, and explicit process v
 | `ENGRAPHIS_CLOUD_ACCESS_TOKEN` | Not set | Optional short-lived access token for ephemeral jobs |
 | `ENGRAPHIS_MANAGED_COMPUTE_CONSENT` | *(auto)* | Operator override only; default follows whether a cloud session is configured (connected = allowed, local-only = never). `0` opts a connected installation out; `1` permits local snapshot preparation but does not create a cloud credential or authorize an upload |
 
+The optional cross-encoder reranker is model- and hardware-dependent. Treat its quality and
+latency as deployment-specific until a versioned model identity, exact configuration, and
+reproducible evaluation artifact are available for the comparison being reported.
+
 See `.env.example` for the full variable inventory. Supply those values through the process
 environment or the trusted config file above; copying it to an arbitrary `./.env` does not make
 Engraphis load it.
 
+> **Ablation fixture:** `python -m eval.ablation` is an offline deterministic check that prints
+> `recall@5` comparisons for vector-only and hybrid retrieval, multi-hop graph arms, and
+> retrieval policies, plus ordinary-recall age and semantic-confidence checks. It does not
+> produce MRR, hit@5, or ms/query results. Use `python -m eval.reinforcement` for retention
+> trajectories, and register evidence before quoting any benchmark results.
+
 ---
 
 ## Project structure

docs/LLM_PROVIDERS.md

@@ -223,6 +223,13 @@ server, replacing the path with the one from initialization:
 cmd mcp add --scope local --env ENGRAPHIS_DB_PATH=/absolute/path/to/engraphis.db engraphis -- engraphis-mcp
 ```
 
+Windows: `cmd` may resolve to `cmd.exe` (the built-in Windows command interpreter)
+instead of the Command Code CLI. If `cmd mcp list` opens a Windows command-prompt window or
+prints `'mcp' is not recognized`, the wrong `cmd` was found on `PATH`. Run `where cmd` and
+ensure the Command Code CLI's install directory appears before `C:\Windows\System32`;
+otherwise invoke the CLI by its absolute path (e.g.
+`C:\Users\you\AppData\Roaming\Python\Scripts\cmd.exe`).
+
 All Command Code options precede the server name, and `--` separates the name from the stdio
 command. `engraphis-mcp` runs locally over stdio; normal local use needs no HTTP endpoint or
 Engraphis API key.
@@ -244,6 +251,9 @@ cmd mcp list
 cmd mcp get engraphis
 ```
 
+(If these commands open a Windows command prompt instead of listing MCP servers, follow the
+Windows note above -- `cmd` resolved to `cmd.exe`.)
+
 Start a normal Command Code session with `cmd`, open `/mcp`, and confirm that `engraphis` is
 connected and exposes tools. Then ask Command Code: "Call `engraphis_stats` and show me the
 result." A response with memory counts confirms the end-to-end connection.