@maxkle1nz/m1nd 0.9.0-beta.0 → 0.9.0-beta.1

package/README.md

@@ -4,24 +4,26 @@
   <img src=".github/m1nd-logo.svg" alt="m1nd" width="400" />
 </p>
 
-<h3 align="center">Operational intelligence for coding agents</h3>
+<h1 align="center">The Agent Memory Layer for Codebases</h1>
 
 <p align="center">
-  <strong>A local intelligence layer for coding agents.</strong><br/>
-  <em>Local execution. MCP over stdio. Optional HTTP/UI surface in the default build.</em>
+  <strong>Your coding agent stops starting blind.</strong><br/>
+  <em>Local-first. MCP-native. Graph memory, recovery, and change reasoning for agent hosts.</em>
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/@maxkle1nz/m1nd"><img src="https://img.shields.io/npm/v/@maxkle1nz/m1nd.svg?color=00f5ff&label=npm" alt="npm" /></a>
   <a href="https://crates.io/crates/m1nd-core"><img src="https://img.shields.io/crates/v/m1nd-core.svg" alt="crates.io" /></a>
   <a href="https://github.com/maxkle1nz/m1nd/actions"><img src="https://github.com/maxkle1nz/m1nd/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
   <a href="https://docs.rs/m1nd-core"><img src="https://img.shields.io/docsrs/m1nd-core" alt="docs.rs" /></a>
-  <a href="https://github.com/maxkle1nz/m1nd/releases"><img src="https://img.shields.io/badge/release-v0.8.0-00f5ff" alt="Release" /></a>
 </p>
 
 <p align="center">
+  <a href="#why-agents-need-it">Why Agents Need It</a> &middot;
   <a href="#what-m1nd-is">What m1nd Is</a> &middot;
   <a href="#what-that-intelligence-covers">What That Intelligence Covers</a> &middot;
+  <a href="#how-m1nd-thinks">How m1nd Thinks</a> &middot;
   <a href="#what-m1nd-is-not">What m1nd Is Not</a> &middot;
   <a href="#capability-map">Capability Map</a> &middot;
   <a href="#quick-start">Quick Start</a> &middot;
@@ -29,6 +31,7 @@
   <a href="#try-the-agent-demo">Agent Demo</a> &middot;
   <a href="#default-agent-workflow">Default Agent Workflow</a> &middot;
   <a href="#evidence">Evidence</a> &middot;
+  <a href="#why-m1nd-over-alternatives">Why m1nd</a> &middot;
   <a href="#agent-testimonials">Agent Testimonials</a> &middot;
   <a href="#limits">Limits</a> &middot;
   <a href="#architecture-at-a-glance">Architecture</a> &middot;
@@ -38,6 +41,7 @@
 </p>
 
 <p align="center">
+  <a href="https://github.com/openai/codex"><img src="https://img.shields.io/badge/OpenAI_Codex-412991?logo=openai&logoColor=fff" alt="OpenAI Codex" /></a>
   <a href="https://claude.ai/download"><img src="https://img.shields.io/badge/Claude_Code-f0ebe3?logo=claude&logoColor=d97706" alt="Claude Code" /></a>
   <a href="https://cursor.sh"><img src="https://img.shields.io/badge/Cursor-000?logo=cursor&logoColor=fff" alt="Cursor" /></a>
   <a href="https://codeium.com/windsurf"><img src="https://img.shields.io/badge/Windsurf-0d1117?logo=windsurf&logoColor=3ec9a7" alt="Windsurf" /></a>
@@ -47,6 +51,7 @@
   <a href="https://roocode.com"><img src="https://img.shields.io/badge/Roo_Code-6d28d9?logoColor=fff" alt="Roo Code" /></a>
   <a href="https://github.com/continuedev/continue"><img src="https://img.shields.io/badge/Continue-000?logoColor=fff" alt="Continue" /></a>
   <a href="https://opencode.ai"><img src="https://img.shields.io/badge/OpenCode-18181b?logoColor=fff" alt="OpenCode" /></a>
+  <a href="https://aistudio.google.com"><img src="https://img.shields.io/badge/Gemini-4285F4?logo=google&logoColor=fff" alt="Gemini" /></a>
   <a href="https://aws.amazon.com/q/developer"><img src="https://img.shields.io/badge/Amazon_Q-232f3e?logo=amazonaws&logoColor=f90" alt="Amazon Q" /></a>
 </p>
 
@@ -54,16 +59,44 @@
   <img src=".github/m1nd-agent-first-map-v2.jpeg" alt="Traditional agent loop vs m1nd-grounded loop" width="960" />
 </p>
 
-> grep finds text. `m1nd` helps agents recover structure, context, and continuity.
+> grep finds text. Vector search finds similar chunks. `m1nd` gives agents a local graph of what connects, what changed, what breaks, what drifted, and where to resume.
+
+## Why Agents Need It
+
+Give a coding agent a large repo and it often starts the same way every time:
+search, open likely files, rebuild context, make a plan, then repeat the whole
+orientation loop in the next session.
+
+That works for small codebases. It falls apart when the project has generated
+artifacts, specs, docs, hidden co-change history, multiple agents, and long
+handoffs.
+
+The problem is not only the agent's reasoning. The agent has no durable model of
+the codebase's structure.
+
+`m1nd` gives it one.
 
 ## What m1nd Is
 
-`m1nd` is a local MCP runtime that gives coding agents structural retrieval, change reasoning, document grounding, operations, and continuity through a graph they can reason over before, during, and after change.
+`m1nd` is a local MCP runtime that gives coding agents graph-native memory of a
+codebase: structure, docs, decisions, change impact, recovery state, and
+investigation continuity.
 
-It ingests repositories, documentation, history, runtime-adjacent signals, and graph-native knowledge into a local graph. That graph is the operational model the agent works against instead of rebuilding context from scratch on every step.
+It ingests repositories, documentation, history, runtime-adjacent signals, and
+graph-native knowledge into a local graph. That graph becomes the operational
+model the agent works against instead of rebuilding context from scratch on
+every task.
 
 It is not only a query surface. It is an operational layer: answers and edit surfaces can carry proof state, next-step guidance, recovery hints, observable execution, verified writes, stateful navigation, and persisted continuity across sessions.
 
+Agents can ask the graph questions that plain file search cannot answer well:
+
+- "What is the authentication flow?" -> `activate` finds the connected chain, not only files named `auth`.
+- "What breaks if I change this?" -> `impact` and `counterfactual` surface blast radius before edits.
+- "Where did this decision live?" -> `boot_memory`, trails, and perspectives recover prior context.
+- "Does this spec still match the code?" -> document bindings and drift checks expose stale claims.
+- "Is this repo binding trustworthy?" -> `trust_selftest`, `session_handshake`, and `recovery_playbook` tell the agent whether to proceed, ingest, rebind, or fall back.
+
 With `m1nd`, an agent can:
 
 - build a durable operational model of a codebase from code, docs, history, runtime signals, and graph-native knowledge
@@ -89,6 +122,21 @@ With `m1nd`, an agent can:
 - Operations: audits, graph-vs-disk verification, daemon monitoring, alerts, metrics, diagrams, runtime overlays, panoramas, savings, reporting, built-in help, and recovery-oriented workflow routing.
 - Continuity: perspectives, trails, session coverage, boot memory, persisted state, feedback-driven reinforcement, multi-agent isolation, and cross-repo or cross-session investigative state.
 
+## How m1nd Thinks
+
+Most code intelligence tools treat a repo as a flat index. `m1nd` treats it as a
+system of relationships.
+
+- **Spreading activation** moves signal through topology, semantics, recency, and directed flow so the agent can find connected neighborhoods rather than isolated keyword hits.
+- **Ghost edges** lift hidden coupling from git history, including files that often change together without an explicit import.
+- **Impact and counterfactuals** turn "what if I touch this?" into a graph question before the edit happens.
+- **Hebbian plasticity** reinforces useful paths from repeated feedback, so the graph can preserve local project memory over time.
+- **L1GHT and universal document ingest** let specs, claims, citations, and implementation bindings live in the same graph as code.
+- **Context Guard and recovery tools** keep agents honest when a host is stale, bound to the wrong repo, missing recovery tools, or operating through a dead MCP transport.
+
+The result is not just retrieval. It is structured orientation, change
+reasoning, and recovery behavior that an agent can call before acting.
+
 ## What m1nd Is Not
 
 `m1nd` is not just:
@@ -155,6 +203,10 @@ Then start with this trust loop:
 // 0b. If you need the cheaper sub-check only
 {"method":"tools/call","params":{"name":"session_handshake","arguments":{"agent_id":"dev"}}}
 
+// 0c. If the task names an absolute repo/scope, pass it so Context Guard can
+// detect "active repo A graph, asked about repo B" before retrieval lies by silence.
+{"method":"tools/call","params":{"name":"session_handshake","arguments":{"agent_id":"dev","scope":"/your/project"}}}
+
 // If your host only exposes health, read its tool_surface_contract first
 {"method":"tools/call","params":{"name":"health","arguments":{"agent_id":"dev"}}}
 
@@ -214,14 +266,43 @@ from source or point your host at an installed binary.
 ```bash
 m1nd mcp-config codex
 m1nd mcp-config generic
+m1nd restart --source /path/to/m1nd --yes
 m1nd pack-check
 ```
 
+`m1nd restart` is the external repair button for agents. It is useful when a
+host is still launching an old `m1nd-mcp`, reports `Transport closed`, or keeps
+a stale MCP process alive. With `--yes`, it builds from the source checkout,
+installs the native runtime to the default m1nd binary path, and stops visible
+`m1nd-mcp` processes. The host still needs to restart or rebind afterward so it
+can launch the updated binary.
+
+In live multi-agent work, use `--no-kill` when you want to update the managed
+binary without interrupting active hosts:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes --no-kill
+```
+
+For every host that supports environment variables, prefer setting
+`M1ND_WORKSPACE_ROOT` to the real repository/workspace. It is the portable
+signal used across Codex, Claude Code, Antigravity, Gemini, Cursor, Windsurf,
+VS Code, and generic MCP clients.
+
+When an agent is working across repos, pass the intended absolute repo or
+subtree as `scope` to `session_handshake`, `trust_selftest`,
+`recovery_playbook`, `doctor`, or `validate_plan`. Context Guard returns
+`wrong_workspace_binding` when the host is bound to one workspace but the tool
+call targets another. That is not graph staleness. Rebind the host with
+`M1ND_WORKSPACE_ROOT` set to the requested workspace, ingest that workspace on
+the same binding, or use explicit federation if the task truly spans repos.
+
 See [docs/AGENT-PACKS.md](docs/AGENT-PACKS.md) for the full install map.
 
 Windows is part of the universal target. The installer emits Windows-safe MCP
-paths and looks for `m1nd-mcp.exe` on `PATH`, through `M1ND_MCP_BINARY`, or at
-`%USERPROFILE%\.m1nd\bin\m1nd-mcp.exe`.
+paths and resolves the runtime in this order: `M1ND_MCP_BINARY`,
+`M1ND_MCP_BIN`, the managed `~/.m1nd/bin` path, then `PATH`. On Windows the
+managed path is `%USERPROFILE%\.m1nd\bin\m1nd-mcp.exe`.
 
 The Windows support boundary is the universal MCP lane: `m1nd-core`,
 `m1nd-ingest`, and `m1nd-mcp`. The `m1nd-openclaw` fast path remains a Unix
@@ -251,6 +332,15 @@ If your local demo sees `trust_selftest` but your editor or agent host does not,
 use the [MCP host refresh guide](docs/MCP-HOST-REFRESH.md) to compare the host
 tool surface against the local runtime.
 
+If a host returns `Transport closed`, treat it as a dead MCP transport, not a
+stale graph. Restart/rebind the host MCP client or open a fresh session, then
+run `trust_selftest` or `session_handshake` before relying on retrieval.
+
+If a response includes
+`context_guard.wrong_workspace_binding=true`, stop before shell fallback. The
+current graph may be healthy but bound to the wrong repo. Follow the embedded
+`recovery_playbook` payload and rebind or federate intentionally.
+
 ## Default Agent Workflow
 
 Make `m1nd` the default investigative layer before `rg`, filesystem globbing, or manual file reads when the task depends on structure, docs, impact, or change.
@@ -279,6 +369,22 @@ Detailed client-by-client setup lives in the [canonical wiki](https://m1nd.world
 | `impact` depth=3 | **543 ns** ([benchmarks](https://m1nd.world/wiki/benchmarks.html)) |
 | Post-write validation sample | **12/12** classified correctly |
 
+## Why m1nd Over Alternatives
+
+| What an agent needs | grep / rg | vector RAG | `m1nd` |
+|---|---:|---:|---:|
+| Find exact text | yes | yes | yes, through `search` |
+| Find similar concepts | no | yes | yes, with graph context |
+| Understand structural relationships | no | limited | yes |
+| Ask "what breaks if I change this?" | no | no | yes, through `impact` and `counterfactual` |
+| Resume investigation state | no | no | yes, through trails, perspectives, and boot memory |
+| Bind docs/specs to code | no | partial | yes, through document bindings and drift checks |
+| Detect hidden co-change coupling | no | no | yes, through ghost edges |
+| Recover from stale host bindings | no | no | yes, through trust and recovery surfaces |
+
+`m1nd` does not replace grep, embeddings, tests, or compilers. It gives agents
+the structural layer those tools do not provide by themselves.
+
 ## Agent Testimonials
 
 ### Jimi - build agent on SAMBA/DOOB
@@ -324,9 +430,9 @@ The workspace is split into three core crates plus one auxiliary bridge crate:
 
 Current crate versions:
 
-- `m1nd-core` `0.8.0`
-- `m1nd-ingest` `0.8.0`
-- `m1nd-mcp` `0.8.0`
+- `m1nd-core` `0.9.0-beta.1`
+- `m1nd-ingest` `0.9.0-beta.1`
+- `m1nd-mcp` `0.9.0-beta.1`
 
 <p align="center">
   <img src=".github/m1nd-architecture-overview-v2.jpeg" alt="m1nd architecture overview" width="960" />

package/docs/AGENT-FIRST-DEMO.md

@@ -47,6 +47,10 @@ The demo proves the practical agent loop:
 The point is not just search. The point is that the agent knows whether it can
 trust the current session before it acts.
 
+When a task points at a different repo than the active binding, the same trust
+loop should return `wrong_workspace_binding` through `context_guard` rather than
+letting the agent confuse workspace mismatch with a stale or empty graph.
+
 ## How To Read The Output
 
 The Markdown output is shaped like a handoff:

package/docs/AGENT-PACKS.md

@@ -47,6 +47,30 @@ Those commands write into `/path/to/project/.m1nd/agent-pack/`. Point the host
 at the generated rule file or paste it into the host custom-instructions
 surface.
 
+The portable pack includes recovery language for dead MCP transports. If a host
+reports `Transport closed`, treat it as a host binding death, not as stale graph
+state. Relaunch/rebind the MCP client or open a fresh session before calling
+`doctor`, `recovery_playbook`, or `ingest`.
+
+If the host is stale because it is still launching an older native binary, use
+the external restart helper from a m1nd source checkout:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes
+```
+
+This builds the latest `m1nd-mcp`, installs it to the default m1nd binary path,
+and stops visible `m1nd-mcp` processes so the host can relaunch. It still cannot
+refresh a client's cached MCP tool list by itself; restart or rebind the host
+session afterward.
+
+During live multi-agent work, add `--no-kill` if the goal is only to update the
+managed binary while keeping current host sessions alive:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes --no-kill
+```
+
 ## MCP Config Snippets
 
 Codex:
@@ -77,8 +101,19 @@ Then point your host at:
 target/release/m1nd-mcp
 ```
 
-On Windows, the native binary is `m1nd-mcp.exe`. The npm installer looks for it
-on `PATH`, through `M1ND_MCP_BINARY`, or at:
+When the host supports environment variables, set:
+
+```text
+M1ND_WORKSPACE_ROOT=/path/to/project
+```
+
+That is the host-neutral workspace contract. Host-specific variables from
+Claude Code, Antigravity, Gemini, Cursor, Windsurf, VS Code, and shells are
+recognized as aliases, but `M1ND_WORKSPACE_ROOT` is the preferred signal.
+
+On Windows, the native binary is `m1nd-mcp.exe`. The npm installer resolves it
+in this order: `M1ND_MCP_BINARY`, `M1ND_MCP_BIN`, the managed m1nd binary path,
+then `PATH`. The managed Windows path is:
 
 ```text
 %USERPROFILE%\.m1nd\bin\m1nd-mcp.exe
@@ -96,6 +131,8 @@ should use plain MCP until a Windows-native fast lane is introduced.
 
 ## Trust Loop For Every Host
 
+0. If the host returns `Transport closed`, restart/rebind the host MCP client
+   first. The transport died before m1nd could run a recovery tool.
 1. Call `trust_selftest`.
 2. If unavailable, call `session_handshake`.
 3. If only `health` is visible, inspect `tool_surface_contract`.

package/docs/IDE-INTEGRATIONS.md

@@ -33,7 +33,8 @@ Most hosts are perfectly fine with:
       "command": "/path/to/m1nd-mcp",
       "env": {
         "M1ND_GRAPH_SOURCE": "/tmp/m1nd-graph.json",
-        "M1ND_PLASTICITY_STATE": "/tmp/m1nd-plasticity.json"
+        "M1ND_PLASTICITY_STATE": "/tmp/m1nd-plasticity.json",
+        "M1ND_WORKSPACE_ROOT": "/path/to/your/project"
       }
     }
   }
@@ -63,6 +64,7 @@ args = ["--stdio", "--no-gui"]
 [mcp_servers.m1nd.env]
 M1ND_GRAPH_SOURCE = "/tmp/m1nd-graph.json"
 M1ND_PLASTICITY_STATE = "/tmp/m1nd-plasticity.json"
+M1ND_WORKSPACE_ROOT = "/path/to/your/project"
 ```
 
 But some editor hosts still pay too much overhead if they cold-start a stdio MCP
@@ -108,6 +110,31 @@ Examples:
 
 ## Practical recommendations
 
+### Set the workspace root when possible
+
+Use `M1ND_WORKSPACE_ROOT` as the portable contract for Codex, Claude Code,
+Antigravity, Gemini, Cursor, Windsurf, VS Code, and generic MCP clients. Point
+it at the real repository or workspace, not at a host-managed runtime folder.
+
+Host-specific hints such as `CLAUDE_PROJECT_DIR` or
+`ANTIGRAVITY_WORKSPACE_ROOT` are recognized as compatibility aliases, but
+`M1ND_WORKSPACE_ROOT` is the clearest cross-host signal.
+
+If a tool call fails with `Transport closed`, the MCP pipe died before m1nd
+could run. Restart/rebind the host MCP client or open a fresh session, then
+call `trust_selftest` or `session_handshake` before retrieval.
+
+If the host is launching an old native runtime, use the external repair helper
+from a m1nd source checkout:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes
+```
+
+For live multi-agent sessions, add `--no-kill` to install the updated managed
+binary without stopping current host processes, then restart/rebind only the
+target host.
+
 ### Use plain MCP when:
 
 - the host already keeps the MCP server alive

package/docs/MCP-HOST-REFRESH.md

@@ -10,6 +10,27 @@ The most common symptom is simple:
 - the host session only sees some of those tools
 - retrieval looks blocked or stale even after ingest
 
+Another common symptom is more abrupt:
+
+- a tool call fails with `Transport closed`
+
+That is not graph staleness. It means the MCP transport died before m1nd could
+execute a tool. Recovery tools such as `doctor`, `recovery_playbook`, and
+`ingest` cannot run through that closed transport. Prove the binary locally,
+restart/rebind the host MCP client or open a fresh session, then call
+`trust_selftest` or `session_handshake` on the newly launched binding.
+
+A third symptom is a cross-repo binding mismatch:
+
+- the active graph is populated for repo A
+- a tool call passes a scope/path from repo B
+- retrieval returns blocked or zero candidates even though repo B has content
+
+Current builds surface this as `wrong_workspace_binding` in `trust_selftest`,
+`session_handshake`, `recovery_playbook`, `doctor`, and `validate_plan`. That
+means the graph may be fine; the host is just bound to the wrong workspace for
+this task.
+
 ## 1. Prove The Local Binary First
 
 From the repo root:
@@ -53,6 +74,12 @@ If `trust_selftest` is visible, call it first:
 {"agent_id":"dev"}
 ```
 
+If the task names a target repo or absolute path, pass it as `scope`:
+
+```json
+{"agent_id":"dev","scope":"/path/to/intended/repo"}
+```
+
 If it returns `full_trust`, continue with m1nd-first work. If it returns any
 other verdict, follow the embedded `recovery_playbook` or call
 `recovery_playbook` with the same evidence.
@@ -76,10 +103,34 @@ Recommended order:
 
 1. Rebuild `m1nd-mcp`.
 2. Confirm the MCP config points at the rebuilt binary.
-3. Restart the MCP server process if the host manages it separately.
-4. Reload or restart the client window/session.
-5. Re-run `tools/list`.
-6. Call `trust_selftest`.
+3. Set `M1ND_WORKSPACE_ROOT` to the intended repo/workspace when the host lets
+   you configure environment variables.
+4. Restart the MCP server process if the host manages it separately.
+5. Reload or restart the client window/session.
+6. Re-run `tools/list`.
+7. Call `trust_selftest`.
+
+If the error is `Transport closed`, the old binding is already gone. Skip graph
+recovery calls in that session and relaunch the host binding first.
+
+For agent-driven repair from a source checkout, the shortest external helper is:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes
+```
+
+`m1nd restart` is deliberately outside MCP, so it can still help when the MCP
+transport is stale or closed. With `--yes`, it builds the release binary,
+installs it to the default m1nd binary path, and stops visible `m1nd-mcp`
+processes. Then the agent or human must restart/rebind the host so it launches
+the updated binary. Without `--yes`, it prints the repair plan only.
+
+For a live multi-agent session, use `--no-kill` when you need to update the
+managed binary without stopping current hosts:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes --no-kill
+```
 
 For hosts that cache tool schemas per conversation or workspace, start a new
 conversation/session after rebuilding the binary. The old conversation may keep
@@ -116,6 +167,23 @@ The important rule is to compare binding fingerprints before falling back to
 manual search. If the local stdio/HTTP demo and the host session disagree, the
 problem is likely host binding freshness, not the graph model itself.
 
+For a wrong workspace binding, include the suspicious target scope:
+
+```json
+{
+  "agent_id": "dev",
+  "observed_tool": "seek",
+  "observed_proof_state": "blocked",
+  "observed_candidates": 0,
+  "scope": "/path/to/intended/repo"
+}
+```
+
+If the result includes `context_guard.wrong_workspace_binding=true`, rebind the
+host with `M1ND_WORKSPACE_ROOT=/path/to/intended/repo`, ingest that workspace on
+the same binding, or choose `federate_auto`/`federate` for intentional cross-repo
+reasoning. Do not keep retrying retrieval against the old workspace.
+
 ## Limits
 
 This guide does not force any client to reload its MCP registry. It gives the

package/npm/lib/cli.js

@@ -19,12 +19,18 @@ Usage:
   m1nd install-skills <host> [--project <dir>]
   m1nd mcp-config <host> [--binary <path>]
   m1nd doctor [--json]
+  m1nd restart [--source <dir>] [--binary <path>] [--yes] [--json]
   m1nd demo [--repo <dir>] [--transport stdio|http] [--json]
   m1nd smoke [--repo <dir>] [--transport stdio|http] [--json]
   m1nd pack-check [--json]
 
 This npm package installs the universal agent doctrine and host adapters. The
-native runtime is still m1nd-mcp; doctor tells you whether it is visible.`;
+native runtime is still m1nd-mcp; doctor tells you whether it is visible.
+
+restart is an external repair helper for stale host bindings. Without --yes it
+prints the plan. With --yes it builds from source when available, installs the
+native binary to the m1nd default path, and stops visible m1nd-mcp processes so
+the host can relaunch/rebind.`;
 }
 
 function parseArgs(args) {
@@ -36,7 +42,7 @@ function parseArgs(args) {
       continue;
     }
     const key = arg.slice(2);
-    if (["help", "json", "yes"].includes(key)) {
+    if (["build", "help", "install", "json", "kill", "no-build", "no-install", "no-kill", "yes"].includes(key)) {
       parsed[key] = true;
       continue;
     }
@@ -96,7 +102,13 @@ function defaultRuntimePath(platform = process.platform, homeDir = os.homedir())
 }
 
 function findRuntimeBinary() {
-  return process.env.M1ND_MCP_BINARY || which("m1nd-mcp") || (fs.existsSync(defaultRuntimePath()) ? defaultRuntimePath() : null);
+  const managedRuntime = defaultRuntimePath();
+  return (
+    process.env.M1ND_MCP_BINARY ||
+    process.env.M1ND_MCP_BIN ||
+    (fs.existsSync(managedRuntime) ? managedRuntime : null) ||
+    which("m1nd-mcp")
+  );
 }
 
 function readPackageVersion() {
@@ -202,6 +214,8 @@ args = ["--stdio", "--no-gui"]
 function doctor() {
   const pack = assertPackShape();
   const binary = findRuntimeBinary();
+  const binaryVersion = runtimeVersion(binary);
+  const packageVersion = readPackageVersion();
   const codexSkillRoot = path.join(os.homedir(), ".codex", "skills");
   const codexSkillsInstalled =
     fs.existsSync(path.join(codexSkillRoot, "m1nd-first", "SKILL.md")) &&
@@ -209,7 +223,7 @@ function doctor() {
 
   const result = {
     schema: "m1nd-npm-doctor-v0",
-    package_version: readPackageVersion(),
+    package_version: packageVersion,
     package_root: PACKAGE_ROOT,
     pack_ok: pack.ok,
     missing_pack_files: pack.missing,
@@ -217,6 +231,7 @@ function doctor() {
       platform: process.platform,
       arch: process.arch,
       binary: binary || null,
+      version: binaryVersion,
       default_install_path: defaultRuntimePath(),
       visible_on_path_or_env: Boolean(binary),
       hint: binary
@@ -236,6 +251,9 @@ function doctor() {
   if (!binary) {
     result.next_actions.push(`From a source checkout: cargo build --release -p m1nd-mcp, then copy ${runtimeBinaryName()} to ${defaultRuntimePath()}`);
   }
+  if (binary && (!binaryVersion || !binaryVersion.includes(packageVersion))) {
+    result.next_actions.push(`Runtime version ${binaryVersion || "unknown"} does not match package ${packageVersion}; run m1nd restart --source /path/to/m1nd --yes, then rebind the host.`);
+  }
   if (!codexSkillsInstalled) {
     result.next_actions.push("For Codex: m1nd install-skills codex");
   }
@@ -245,6 +263,209 @@ function doctor() {
   return result;
 }
 
+function runCommand(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    stdio: options.stdio || "pipe",
+    timeout: options.timeout,
+    killSignal: options.killSignal || "SIGKILL",
+  });
+  return {
+    command,
+    args,
+    cwd: options.cwd || process.cwd(),
+    status: result.status,
+    ok: !result.error && result.status === 0,
+    error: result.error ? result.error.message : null,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+  };
+}
+
+function runtimeVersion(binary) {
+  if (!binary || !fs.existsSync(binary)) return null;
+  const result = runCommand(binary, ["--version"], { timeout: 1500 });
+  if (result.error && result.error.includes("ETIMEDOUT")) return "version-check-timeout";
+  if (!result.ok) return null;
+  return result.stdout.trim() || null;
+}
+
+function sourceReleaseBinary(sourceDir) {
+  return path.join(sourceDir, "target", "release", runtimeBinaryName());
+}
+
+function sourceLooksBuildable(sourceDir) {
+  return (
+    fs.existsSync(path.join(sourceDir, "Cargo.toml")) &&
+    fs.existsSync(path.join(sourceDir, "m1nd-mcp", "Cargo.toml"))
+  );
+}
+
+function listRuntimeProcesses() {
+  if (process.platform === "win32") {
+    const result = runCommand("tasklist", ["/FI", `IMAGENAME eq ${runtimeBinaryName()}`, "/FO", "CSV", "/NH"]);
+    if (!result.ok) return [];
+    return result.stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        const columns = line
+          .split(/","/)
+          .map((part) => part.replace(/^"|"$/g, ""));
+        return { pid: Number(columns[1]), ppid: null, state: null, command: columns[0] };
+      })
+      .filter((processInfo) => Number.isFinite(processInfo.pid));
+  }
+  const result = runCommand("ps", ["-ax", "-o", "pid=,ppid=,state=,command="]);
+  if (!result.ok) return [];
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .map((line) => {
+      const match = line.match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/);
+      if (!match) return null;
+      return { pid: Number(match[1]), ppid: Number(match[2]), state: match[3], command: match[4] };
+    })
+    .filter(Boolean)
+    .filter((processInfo) => commandLooksLikeRuntime(processInfo.command));
+}
+
+function commandLooksLikeRuntime(command) {
+  const firstToken = String(command || "").trim().split(/\s+/)[0] || "";
+  const base = path.basename(firstToken).replace(/^\(|\)$/g, "");
+  return base === runtimeBinaryName();
+}
+
+function stopRuntimeProcesses(processes) {
+  const stopped = [];
+  for (const processInfo of processes) {
+    if (!processInfo.pid || processInfo.pid === process.pid) continue;
+    const result =
+      process.platform === "win32"
+        ? runCommand("taskkill", ["/PID", String(processInfo.pid), "/T", "/F"])
+        : runCommand("kill", ["-TERM", String(processInfo.pid)]);
+    stopped.push({
+      pid: processInfo.pid,
+      ppid: processInfo.ppid || null,
+      state: processInfo.state || null,
+      command: processInfo.command,
+      ok: result.ok,
+      status: result.status,
+      stderr: result.stderr.trim(),
+    });
+  }
+  return stopped;
+}
+
+function installRuntimeBinary(sourceBinary, targetBinary) {
+  ensureDir(path.dirname(targetBinary));
+  const tempTarget = path.join(
+    path.dirname(targetBinary),
+    `.${path.basename(targetBinary)}.${process.pid}.tmp`
+  );
+  fs.copyFileSync(sourceBinary, tempTarget);
+  if (process.platform !== "win32") fs.chmodSync(tempTarget, 0o755);
+  fs.renameSync(tempTarget, targetBinary);
+}
+
+function restart(args) {
+  const sourceDir = path.resolve(args.source || args["build-from"] || process.cwd());
+  const targetBinary = path.resolve(args.binary || defaultRuntimePath());
+  const yes = Boolean(args.yes);
+  const buildRequested = !args["no-build"] && (args.build || args.install || yes);
+  const installRequested = !args["no-install"] && (args.install || yes);
+  const killRequested = !args["no-kill"] && (args.kill || yes);
+  const buildable = sourceLooksBuildable(sourceDir);
+  const beforeVersion = runtimeVersion(targetBinary);
+  const processes = listRuntimeProcesses();
+  const result = {
+    schema: "m1nd-npm-restart-v0",
+    package_version: readPackageVersion(),
+    source_dir: sourceDir,
+    source_buildable: buildable,
+    target_binary: targetBinary,
+    before_version: beforeVersion,
+    after_version: null,
+    dry_run: !yes,
+    actions: {
+      build_requested: buildRequested,
+      install_requested: installRequested,
+      kill_requested: killRequested,
+      built: false,
+      installed: false,
+      stopped_processes: [],
+    },
+    visible_runtime_processes: processes,
+    next_actions: [],
+    non_claims: [
+      "m1nd restart does not refresh a host's cached MCP tool list by itself.",
+      "m1nd restart does not repair graph contents, ingest roots, or semantic retrieval.",
+      "m1nd restart does not select the correct workspace for the agent.",
+    ],
+  };
+
+  if (buildRequested && !buildable) {
+    result.next_actions.push("Run from a m1nd source checkout or pass --source /path/to/m1nd before building.");
+  }
+
+  if (yes && buildRequested && buildable) {
+    const build = runCommand("cargo", ["build", "--release", "-p", "m1nd-mcp"], { cwd: sourceDir });
+    result.actions.build = {
+      ok: build.ok,
+      status: build.status,
+      stderr: build.stderr.trim(),
+    };
+    result.actions.built = build.ok;
+    if (!build.ok) {
+      result.next_actions.push("Fix the cargo build failure before installing or rebinding hosts.");
+      result.after_version = runtimeVersion(targetBinary);
+      return result;
+    }
+  }
+
+  if (yes && installRequested) {
+    const builtBinary = sourceReleaseBinary(sourceDir);
+    if (!fs.existsSync(builtBinary)) {
+      result.next_actions.push(`Built binary not found at ${builtBinary}; run cargo build --release -p m1nd-mcp first.`);
+    } else {
+      try {
+        installRuntimeBinary(builtBinary, targetBinary);
+        result.actions.install = { ok: true, source: builtBinary, target: targetBinary };
+        result.actions.installed = true;
+      } catch (error) {
+        result.actions.install = {
+          ok: false,
+          source: builtBinary,
+          target: targetBinary,
+          error: error instanceof Error ? error.message : String(error),
+        };
+        result.next_actions.push("Install failed; close live runtimes or use --binary to install to an isolated target, then retry.");
+        result.after_version = runtimeVersion(targetBinary);
+        return result;
+      }
+    }
+  }
+
+  if (yes && killRequested) {
+    result.actions.stopped_processes = stopRuntimeProcesses(processes);
+    const failedStops = result.actions.stopped_processes.filter((processInfo) => !processInfo.ok);
+    if (failedStops.length > 0) {
+      result.next_actions.push("Some visible m1nd-mcp processes did not stop; restart the host session or OS if the process state is uninterruptible.");
+    }
+  }
+
+  result.after_version = runtimeVersion(targetBinary);
+
+  if (!yes) {
+    result.next_actions.push("Re-run with --yes to build/install/stop processes, or add --no-build/--no-install/--no-kill to narrow the repair.");
+  }
+  result.next_actions.push("Restart or rebind the MCP host/client so it launches the installed binary.");
+  result.next_actions.push("Then run trust_selftest or session_handshake with the intended workspace scope.");
+  return result;
+}
+
 function runDemo(args) {
   const repo = path.resolve(args.repo || process.cwd());
   const script = path.join(repo, "scripts", "m1nd_agent_demo.py");
@@ -279,18 +500,31 @@ function print(value, asJson) {
   if (value.schema === "m1nd-npm-doctor-v0") {
     console.log(`m1nd npm package ${value.package_version}`);
     console.log(`pack: ${value.pack_ok ? "ok" : "missing files"}`);
-    console.log(`runtime: ${value.runtime.binary || "not found"}`);
+    console.log(`runtime: ${value.runtime.binary || "not found"}${value.runtime.version ? ` (${value.runtime.version})` : ""}`);
     console.log(`codex skills: ${value.codex.skills_installed ? "installed" : "not installed"}`);
     console.log("next:");
     for (const action of value.next_actions) console.log(`  - ${action}`);
     return;
   }
+  if (value.schema === "m1nd-npm-restart-v0") {
+    console.log(`m1nd restart ${value.dry_run ? "plan" : "result"}`);
+    console.log(`source: ${value.source_dir}${value.source_buildable ? "" : " (not buildable)"}`);
+    console.log(`target: ${value.target_binary}`);
+    console.log(`version: ${value.before_version || "unknown"} -> ${value.after_version || "unknown"}`);
+    console.log(`visible m1nd-mcp processes: ${value.visible_runtime_processes.length}`);
+    console.log(`built: ${value.actions.built ? "yes" : "no"}`);
+    console.log(`installed: ${value.actions.installed ? "yes" : "no"}`);
+    console.log(`stopped: ${value.actions.stopped_processes.length}`);
+    console.log("next:");
+    for (const action of value.next_actions) console.log(`  - ${action}`);
+    return;
+  }
   console.log(String(value));
 }
 
 async function main(rawArgs) {
   const args = parseArgs(rawArgs);
-  const command = args._[0] || "help";
+  const command = args._[0] === "/restart" ? "restart" : args._[0] || "help";
 
   if (args.help || ["help", "-h", "--help"].includes(command)) {
     console.log(usage());
@@ -315,6 +549,11 @@ async function main(rawArgs) {
     return;
   }
 
+  if (command === "restart") {
+    print(restart(args), args.json);
+    return;
+  }
+
   if (command === "pack-check") {
     const result = assertPackShape();
     if (args.json) {
@@ -341,6 +580,8 @@ module.exports = {
   doctor,
   findRuntimeBinary,
   installSkills,
+  restart,
   mcpConfig,
   runtimeBinaryName,
+  commandLooksLikeRuntime,
 };

package/npm/test/cli.test.js

@@ -5,8 +5,10 @@ const path = require("path");
 const { spawnSync } = require("child_process");
 
 const {
+  commandLooksLikeRuntime,
   defaultRuntimePath,
   mcpConfig,
+  restart,
   runtimeBinaryName,
 } = require("../lib/cli");
 
@@ -15,6 +17,9 @@ const cli = path.resolve(__dirname, "../bin/m1nd.js");
 assert.strictEqual(runtimeBinaryName("win32"), "m1nd-mcp.exe");
 assert.strictEqual(runtimeBinaryName("darwin"), "m1nd-mcp");
 assert.strictEqual(runtimeBinaryName("linux"), "m1nd-mcp");
+assert.strictEqual(commandLooksLikeRuntime("/Users/you/.m1nd/bin/m1nd-mcp --stdio"), true);
+assert.strictEqual(commandLooksLikeRuntime("(m1nd-mcp)"), true);
+assert.strictEqual(commandLooksLikeRuntime("node codex prompt mentions m1nd-mcp"), false);
 
 assert.strictEqual(
   defaultRuntimePath("win32", "C:\\Users\\you"),
@@ -41,9 +46,23 @@ const help = spawnSync(process.execPath, [cli, "--help"], { encoding: "utf8" });
 assert.strictEqual(help.status, 0, help.stderr);
 assert(help.stdout.includes("m1nd installer"));
 assert(help.stdout.includes("m1nd smoke"));
+assert(help.stdout.includes("m1nd restart"));
 
 const packCheck = spawnSync(process.execPath, [cli, "pack-check", "--json"], { encoding: "utf8" });
 assert.strictEqual(packCheck.status, 0, packCheck.stderr);
 assert.strictEqual(JSON.parse(packCheck.stdout).schema, "m1nd-agent-pack-check-v0");
 
+const restartPlan = restart({
+  source: path.resolve(__dirname, "..", ".."),
+  binary: path.resolve(__dirname, "missing-m1nd-mcp"),
+  "no-build": true,
+  "no-install": true,
+  "no-kill": true,
+});
+assert.strictEqual(restartPlan.schema, "m1nd-npm-restart-v0");
+assert.strictEqual(restartPlan.dry_run, true);
+assert.strictEqual(restartPlan.actions.built, false);
+assert.strictEqual(restartPlan.actions.installed, false);
+assert(restartPlan.next_actions.some((action) => action.includes("Restart or rebind")));
+
 console.log("npm cli tests ok");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxkle1nz/m1nd",
-  "version": "0.9.0-beta.0",
+  "version": "0.9.0-beta.1",
   "description": "Universal installer and agent pack for the m1nd MCP runtime.",
   "license": "MIT",
   "repository": {

package/skills/m1nd-first/SKILL.md

@@ -36,6 +36,26 @@ Skip the `m1nd` first pass only when:
 
 If `m1nd` does not answer enough, then fall back to shell search, direct file reads, compiler output, tests, logs, and debugger data.
 
+If a tool call fails with `Transport closed`, classify it as a host MCP binding
+failure before m1nd can run. Do not call `doctor`, `recovery_playbook`, or
+`ingest` through that dead binding. Verify the binary with a local smoke, kill
+stale `m1nd-mcp --stdio` processes if you own the host, and restart/rebind the
+agent host or open a fresh thread so the MCP client launches a new transport.
+After rebind, run `trust_selftest` or `session_handshake` before trusting
+retrieval.
+
+If the host appears to be launching an old native runtime, use the external CLI
+repair path from a m1nd source checkout:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes
+```
+
+Use `--no-kill` in live multi-agent sessions when you only want to install the
+updated managed binary and rebind one selected host. `m1nd restart` does not
+ingest, repair graph contents, choose a workspace, or refresh an already-open
+client's cached MCP tool list.
+
 For local m1nd repo work, prefer the cheap trust selftest path before a full smoke:
 
 ```bash
@@ -54,6 +74,28 @@ retrieval. If the verdict is not `full_trust`, follow the embedded
 guessing the next move. The selftest is diagnostic-only: no ingest, repair,
 host refresh, graph mutation, or retrieval probe happens automatically.
 
+If the verdict is `needs_ingest`, or `graph_state.node_count` is `0` while
+`ingest` is available, treat it as a recoverable cold graph, not as a reason to
+abandon m1nd. Call `ingest` on the same MCP binding with the absolute path of
+the intended repo/workspace, never a managed runtime/session path such as
+`~/.codex/m1nd-runtimes/...`, `~/.claude/m1nd-runtimes/...`, an Antigravity
+agent runtime, or a generic `mcp-runtimes`/`agent-runtimes` folder. Host
+integrations should prefer `M1ND_WORKSPACE_ROOT`; m1nd also recognizes common
+workspace hints from Claude Code, Antigravity, Gemini, Cursor, Windsurf, VS
+Code, and shell/package-manager env vars. Then rerun `session_handshake` and
+one cheap retrieval. Fall back to direct files only when ingest is unavailable,
+ingest fails, or a post-ingest retrieval still reports `blocked` and
+`recovery_playbook`/`doctor` confirms stale binding or degraded host surface.
+
+If `trust_selftest`, `session_handshake`, `recovery_playbook`, `doctor`,
+`validate_plan`, or a retrieval response includes
+`context_guard.wrong_workspace_binding=true`, do not classify the repo graph as
+stale. The active binding is pointed at one workspace while the call asked about
+another. Follow the embedded `recovery_playbook` payload, rebind the host with
+`M1ND_WORKSPACE_ROOT` set to `requested_workspace_hint`, or explicitly ingest
+that workspace on the same binding if the switch is intentional. Use
+`federate_auto`/`federate` only when the task is genuinely cross-repo.
+
 If `trust_selftest` is not exposed but `session_handshake` is, call the cheaper
 sub-check:
 
@@ -61,6 +103,12 @@ sub-check:
 {"agent_id":"codex-m1nd"}
 ```
 
+When the task names a target repo or absolute path, include it as `scope`:
+
+```json
+{"agent_id":"codex-m1nd","scope":"/path/to/intended/repo"}
+```
+
 Treat its `trust_mode` as the session routing decision before relying on
 retrieval. If the mode is not `full_trust`, call `recovery_playbook` before
 guessing the next move. The playbook returns ordered recovery steps and a

package/skills/m1nd-operator/SKILL.md

@@ -28,20 +28,54 @@ Only skip the `m1nd` first pass when:
 - Prefer the live MCP surface over stale prose. If tool names, counts, or parameters matter, run the bundled helper from this skill directory: `python3 scripts/probe_m1nd.py tools`.
 - Keep `agent_id` stable within one investigation. Change it only when intentionally starting another role or another concurrent investigation.
 - Ingest first. Re-ingest after code changes, or use incremental ingest for code repos when appropriate.
+- If a m1nd tool call fails with `Transport closed`, treat it as a host MCP
+  transport death, not as a graph, retrieval, or proof-state failure. Recovery
+  tools cannot run through a closed transport. Verify the local binary with the
+  repo smoke harness, kill stale `m1nd-mcp --stdio` processes if you own that
+  host, then restart/rebind the MCP client or open a fresh thread. After the
+  host relaunches the transport, run `trust_selftest` or `session_handshake`
+  before relying on retrieval.
+- If the host is launching an old native runtime, use the external repair
+  helper from a m1nd source checkout: `m1nd restart --source /path/to/m1nd
+  --yes`. In live multi-agent sessions, add `--no-kill` and rebind only the
+  selected host. This helper does not ingest, choose a workspace, or refresh an
+  already-open client's cached MCP tool list.
 - If the live MCP surface exposes `trust_selftest`, call it first and route by
   `verdict` before relying on retrieval. `full_trust` means proceed with
   m1nd-first; `needs_ingest` means ingest the intended repo; `orientation_only`
   or `degraded_host_tool_surface` means use m1nd only for orientation and
   verify final truth with local files until the binding is refreshed;
-  `stale_binding_suspected` means compare binding fingerprints and follow the
-  recovery playbook before trusting retrieval.
+  `wrong_workspace_binding` means the active graph is healthy but bound to the
+  wrong repo for the requested scope; `stale_binding_suspected` means compare
+  binding fingerprints and follow the recovery playbook before trusting
+  retrieval.
 - If `trust_selftest` is not exposed but `session_handshake` is, call the
-  handshake and route by `trust_mode` as the cheaper sub-check.
+  handshake and route by `trust_mode` as the cheaper sub-check. When the task
+  names a target repo or absolute path, pass it as `scope` so Context Guard can
+  detect cross-repo binding mistakes before retrieval.
 - If the selftest verdict or handshake trust mode is not `full_trust`, or
   retrieval returns `blocked`/zero candidates unexpectedly, call
   `recovery_playbook` before inventing the next step. Use its ordered steps and
   `binding_fingerprint` to compare host, stdio, HTTP, runtime root, graph paths,
   generation counters, and ingest roots.
+- If a response includes `context_guard.wrong_workspace_binding=true`, stop the
+  normal stale-graph path. Rebind the MCP host with `M1ND_WORKSPACE_ROOT` set to
+  `requested_workspace_hint`, intentionally ingest that workspace on the same
+  binding, or use `federate_auto`/`federate` only when the investigation truly
+  spans repos. Do not treat this as proof that m1nd retrieval is broken.
+- If `trust_selftest` or `session_handshake` reports `needs_ingest`, or the
+  mini `graph_state.node_count` is `0` while `ingest` is available, treat the
+  session as a recoverable cold graph. Do not jump straight to shell fallback.
+  Call `ingest` on the same MCP binding with the absolute intended
+  repo/workspace path, never a managed runtime/session path such as
+  `~/.codex/m1nd-runtimes/...`, `~/.claude/m1nd-runtimes/...`, an Antigravity
+  agent runtime, or a generic `mcp-runtimes`/`agent-runtimes` folder. Host
+  integrations should prefer `M1ND_WORKSPACE_ROOT`; m1nd also recognizes common
+  workspace hints from Claude Code, Antigravity, Gemini, Cursor, Windsurf, VS
+  Code, and shell/package-manager env vars. Then rerun `session_handshake` and
+  one cheap retrieval. Fall back only if ingest is unavailable, ingest fails,
+  or post-ingest retrieval is still blocked and `recovery_playbook`/`doctor`
+  confirms stale binding or degraded host surface.
 - If the host exposes `health` but not `trust_selftest`, `session_handshake`, or
   `recovery_playbook`, read `health.tool_surface_contract` and
   `health.host_binding_alignment`. Treat missing required host-visible tools as
@@ -116,6 +150,7 @@ Use the bundled probe script from this skill directory whenever the live runtime
 python3 scripts/probe_m1nd.py tools
 python3 scripts/probe_m1nd.py call health '{"agent_id":"codex-m1nd"}'
 python3 scripts/probe_m1nd.py call trust_selftest '{"agent_id":"codex-m1nd"}'
+python3 scripts/probe_m1nd.py call session_handshake '{"agent_id":"codex-m1nd","scope":"/path/to/intended/repo"}'
 python3 scripts/probe_m1nd.py call recovery_playbook '{"agent_id":"codex-m1nd","observed_tool":"seek","observed_proof_state":"blocked","observed_candidates":0}'
 python3 scripts/probe_m1nd.py call help '{"agent_id":"codex-m1nd","tool_name":"validate_plan"}'
 python3 scripts/probe_m1nd.py run '[{"name":"ingest","arguments":{"agent_id":"codex-m1nd","path":"/path/to/repo"}},{"name":"seek","arguments":{"agent_id":"codex-m1nd","query":"where retry backoff is decided","top_k":5}}]'

package/skills/m1nd-operator/references/runtime-and-refresh.md

@@ -10,6 +10,8 @@ Most hosts should point their MCP config at the same native binary:
 - Binary name: `m1nd-mcp`
 - Default launch args: `--stdio --no-gui`
 - Optional env override: `M1ND_MCP_BINARY=/absolute/path/to/m1nd-mcp`
+- Compatibility alias accepted by the probe helper:
+  `M1ND_MCP_BIN=/absolute/path/to/m1nd-mcp`
 
 Use the bundled helper script to verify the current runtime instead of trusting memory:
 
@@ -128,6 +130,30 @@ When this skill starts feeling stale:
 3. Run `python3 scripts/probe_m1nd.py tools` against the local installed binary.
 4. Update this skill only where the live runtime or official docs actually changed.
 
+## External Restart Helper
+
+When an agent sees `Transport closed`, an old binary version, stale host tools,
+or repeated blocked retrieval after a good local graph, use an external restart
+instead of trying to repair through the dead MCP binding:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes
+```
+
+This command builds the latest source checkout, installs the native runtime to
+the default m1nd binary path, and stops visible `m1nd-mcp` processes. It does
+not refresh the host's cached tool list, choose a workspace, or ingest a graph.
+After it runs, restart/rebind the host client and call `trust_selftest` or
+`session_handshake` with the intended `scope`.
+
+For live multi-agent sessions, prefer:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes --no-kill
+```
+
+Then restart/rebind only the host that needs the new binary.
+
 ## Host-Specific Note For Codex
 
 At the protocol level, `m1nd`'s canonical tool names are bare names like `activate` and `validate_plan`.

package/skills/m1nd-operator/scripts/probe_m1nd.py

@@ -10,7 +10,12 @@ import shutil
 from typing import Any
 
 
-DEFAULT_BINARY = os.environ.get("M1ND_MCP_BINARY") or shutil.which("m1nd-mcp") or "m1nd-mcp"
+DEFAULT_BINARY = (
+    os.environ.get("M1ND_MCP_BINARY")
+    or os.environ.get("M1ND_MCP_BIN")
+    or shutil.which("m1nd-mcp")
+    or "m1nd-mcp"
+)
 DEFAULT_ARGS = shlex.split(os.environ.get("M1ND_MCP_ARGS", "--stdio --no-gui"))
 
 

package/skills/m1nd-universal-agent-pack.md

@@ -15,6 +15,10 @@ local file action.
 
 ## Startup Trust Loop
 
+0. If a tool call fails with `Transport closed`, stop treating it as graph
+   staleness. The MCP transport died before m1nd could run. Verify the binary
+   with a local smoke, restart/rebind the host MCP client or open a fresh
+   thread, then continue with this loop.
 1. Call `trust_selftest` if the host exposes it.
 2. If unavailable, call `session_handshake`.
 3. If only `health` is exposed, inspect `tool_surface_contract` and
@@ -22,6 +26,15 @@ local file action.
 4. If trust is not full, call or follow `recovery_playbook`.
 5. Only then rely on retrieval surfaces such as `search`, `seek`, or `activate`.
 
+When the task names a concrete repo, worktree, or absolute path, pass it as
+`scope` to `session_handshake`, `trust_selftest`, `recovery_playbook`, `doctor`,
+or `validate_plan`. If the response reports
+`context_guard.wrong_workspace_binding=true` or trust mode
+`wrong_workspace_binding`, the host is bound to a different workspace than the
+one you asked about. Rebind with `M1ND_WORKSPACE_ROOT`, intentionally ingest the
+requested workspace on the same binding, or use explicit federation for real
+cross-repo work. Do not call this graph staleness.
+
 `trust_selftest` and `recovery_playbook` are diagnostic. They do not ingest,
 repair, refresh the host, or mutate the graph.
 
@@ -40,6 +53,24 @@ repair, refresh the host, or mutate the graph.
 
 ## Recovery Rules
 
+`Transport closed` is a host transport failure, not a m1nd proof-state. Do not
+call `doctor`, `recovery_playbook`, or `ingest` through that dead binding. A
+fresh MCP transport must be launched first.
+
+If the host appears to be launching an old or stale native runtime, and a local
+`m1nd` CLI is available outside the MCP transport, run:
+
+```bash
+m1nd restart --source /path/to/m1nd --yes
+```
+
+Then restart or rebind the host MCP client. `m1nd restart` is external repair:
+it does not ingest, pick the workspace, or refresh a client's cached tool list
+inside an already-open conversation.
+
+In live multi-agent sessions, use `--no-kill` to install the updated managed
+binary without stopping every active `m1nd-mcp` host.
+
 If `seek`, `search`, or `activate` returns `blocked`, zero candidates, or an
 unexpectedly empty graph after ingest, treat it as possible stale binding or
 session split-brain before blaming the repo.
@@ -74,6 +105,11 @@ and local file truth. It does not replace them.
 Keep `agent_id` stable within one investigation. Use trails, perspectives, and
 coverage sessions when work spans agents, branches, or sessions.
 
+For host setup, prefer exporting `M1ND_WORKSPACE_ROOT` to the actual repository
+or project root. Claude Code, Antigravity, Gemini, Cursor, Windsurf, VS Code,
+and generic shells can expose their own workspace hints too, but
+`M1ND_WORKSPACE_ROOT` is the portable contract.
+
 ## L1GHT
 
 Use `adapter="light"` for graph-native semantic markdown. Use