fde-framework 0.1.43__tar.gz → 0.1.45__tar.gz

{fde_framework-0.1.43 → fde_framework-0.1.45}/CHANGELOG.md

@@ -5,6 +5,75 @@ the project is pre-release, so everything sits under 0.1.0 until the first tag.
 
 ## [Unreleased]
 
+## [0.1.45] — 2026-10-11
+
+A twelfth outside reading, and a coding agent driving the server for the
+first time, found three things between them: a release page that said
+nothing about what it was, a date a day ahead, and an MCP server that lost
+the agent's second call two different ways.
+
+- **The agent's second call finds the first call's work.**
+  `start(name="acme")` puts the record at engagements/acme;
+  `status(engagement="acme")` a moment later looked at `<workspace>/acme`
+  and said there was no engagement. The in-process test had passed the
+  path `start` returned, so it never asked by name. A bare name is now
+  looked for where `start` puts it, as `fde status acme` does at the
+  terminal; a path is taken as given; a name that climbs out is refused
+  before anything is looked for.
+- **Calls issued at once all come back.** Claude Code asked for `status`
+  and `next` in the same breath and the second came back "Connection
+  closed". The server runs each tool on its own thread, and the capture
+  that collects a command's output does so by swapping the process's
+  stdout; two swaps interleaved left one command printing straight onto
+  the JSON-RPC channel. Commands now run one at a time inside the server.
+  A new suite drives the server as a separate process over stdio with the
+  official client: six calls at once for three rounds, a call abandoned
+  midway, a record changed on disk between calls, and every tool's input
+  schema published. The hang reproduced before the fix and fails within
+  ninety seconds instead of hanging CI.
+- **The envelope's contract is a JSON Schema.** `fde mcp --schema` prints
+  it; every reply is validated against it; the schema's list of tools is
+  the server's; a field it does not name or a status it does not name
+  fails. The README says when the version moves: a field changing meaning
+  or going away, never one being added.
+- **A release page means verified.** It is written only after the wheel
+  PyPI serves has been installed on Python 3.11, 3.12 and 3.13, hashed
+  against the wheel the tests ran on, and walked through the first five
+  minutes. It carries the wheel and the sdist, their SHA-256, the commit,
+  the run and the install line.
+- **One date.** 0.1.44 shipped on October 11 dated October 12 in both
+  CHANGELOG and CITATION. Corrected; the release workflow now holds the
+  CHANGELOG date, CITATION's date-released and the tagged commit's own day
+  in the author's time zone to one value, and a test holds the two files
+  to each other.
+- A corrupt record is a sentence naming the file, not a traceback, through
+  the server as at the terminal; now pinned by a test.
+
+## [0.1.44] — 2026-10-11
+
+An eleventh outside reading found the README contradicting itself on its
+own test count, and asked for the published wheel to be the thing that
+is tested. Both done, with the two small things a stranger's first five
+minutes need.
+
+- **One count, in one place.** The README stated the test count three
+  times and two of them were six releases stale. It is now stated once,
+  in the claim ladder, and the other two places say where to look.
+- **A stranger's install, every release.** The release workflow now
+  installs the published wheel, not the checkout, into a fresh
+  interpreter and walks the documented first five minutes: triage,
+  start, next, status, the MCP check, the doctor. The index lags a tag
+  by a minute, so it retries before concluding anything.
+- **`fde doctor`.** The interpreter, the package, the registry, the
+  working directory, each optional extra, and whether docker, the agent
+  and the linter are on the path -- each line a measurement, exit 1 only
+  when something the core needs is missing.
+- **The envelope is versioned.** `schema_version` on every reply, the
+  contract written in the server module, and a test that reaches all
+  four statuses, including failed.
+- The first screen links the banking run as the one case where the
+  framework told itself to stop.
+
 ## [0.1.43] — 2026-10-11
 
 A tenth outside reading, of 0.1.42, found the one place the server's

{fde_framework-0.1.43 → fde_framework-0.1.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fde-framework
-Version: 0.1.43
+Version: 0.1.45
 Summary: The decision before the AI build: evidence in, an architecture with receipts out, a scored build or a stop. For Forward Deployed Engineers and anyone deciding whether an AI system should exist.
 Project-URL: Homepage, https://github.com/atulkapoor/fde-framework
 Project-URL: Documentation, https://atulkapoor.github.io/fde-framework/
@@ -111,12 +111,15 @@ it can say stop.
 
 ```bash
 pip install fde-framework
+fde doctor               # the interpreter, the package, the registry, the extras: measured, not guessed
 fde start acme --statement "Route each support message to one of 77 queues."
 fde next acme            # the one thing to learn or do next, and what turns on it
 ```
 
 One minute, nothing to bring: paste two problems and see which one is
-decidable yet.
+decidable yet. For what the whole loop looks like on a real dataset,
+including the one time the framework told itself to stop, read the
+[banking run](https://github.com/atulkapoor/fde-demo-banking#the-operating-loop-closed).
 
 ```
 $ fde triage --statement "Route each inbound support message to one of 77 queues; customer data may not leave our cloud account." \
@@ -154,16 +157,26 @@ the argument `mcp`:
 It serves `triage`, `start`, `frame`, `status`, `next`, `stage`, `debt`,
 `stop_when` and `history`, each returning exactly what the terminal prints,
 refusals included, beside a small envelope an agent can branch on without
-parsing prose: `status` (ok, blocked, refused, failed), `mutated`, and the
-workspace. The envelope follows the command's exit, never a reading of
-its text. An agent is not a person, so every path it supplies must
-stay inside one workspace, the directory the server started in or
+parsing prose: `schema_version`, `status` (ok, blocked, refused, failed),
+`mutated`, and the workspace. The envelope follows the command's exit,
+never a reading of its text. Its contract is a JSON Schema, `fde mcp
+--schema`, that every reply is tested against; a client pins
+`schema_version`, which moves only when a field changes meaning or goes
+away, never when one is added. An engagement is named as `start` named
+it (`start(name="acme")`, then `status(engagement="acme")`), or by its
+path. An agent is not a person, so every path it supplies must stay
+inside one workspace, the directory the server started in or
 `FDE_WORKSPACE`; a path outside it, a traversal, or a symlink that points
 out is refused in words, and engagement names are plain names. The two
 tools that write to the record, `start` and `frame`, say so and carry the
-protocol's hints so a client can ask first. Building, implementing and
-deploying are not served; they stay on the command line, where the person
-who runs them is accountable for them.
+protocol's hints so a client can ask first. Calls run one at a time
+inside the server, so an agent that asks for `status` and `next` in the
+same breath gets both. Exercised against two real clients: the official
+MCP Python client over stdio, in the test suite, with concurrent calls,
+an abandoned call and a record changed on disk between calls; and Claude
+Code 2.1, by hand, from the configuration above. Building, implementing
+and deploying are not served; they stay on the command line, where the
+person who runs them is accountable for them.
 
 > ### Five founding engagements
 > One real workflow, your real examples, a measured baseline, and someone
@@ -228,7 +241,7 @@ ladder, so nothing here can be over-read:
 
 | Claim | Status | The evidence, and where it stops |
 |---|---|---|
-| The framework is implemented | verified | 1,306 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed |
+| The framework is implemented | verified | 1,316 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
 | A build is reproducible | verified | byte-identical rebuild pinned by test; each public demo carries a Reproduce section and its digests |
 | The decisions generalise | partial | four shapes (extraction, freeform QA, a labelled decision, seventy-seven-way routing) on real data; one industry set; `fde kb sweep` names the shapes nothing serves |
 | The deliverable is production-reliable | unverified | no production engagement; the banking operating loop ran on a laptop and its record says so |
@@ -292,9 +305,10 @@ pairs, role-scoped interview, hardware scan) → fact log with provenance →
 permutation space → eight gates → decide → architect → build (code, evals,
 deploy and ops assets, `RISKS.md`, `COMPLIANCE.md`) → retro and case
 capture. Overrides are honoured on the next run, trigger observations feed
-calibration, and a reviewed case can enter the corpus. 1160+ tests; nine
-fresh-eyes audit passes, every finding resolved and the fix pinned as a
-regression test; CI gates on the suite, lint, and a sanitisation scan of
+calibration, and a reviewed case can enter the corpus. The test count is
+stated once, in the claim ladder above, and updated at every release;
+eleven fresh-eyes audit passes, every finding resolved and the fix pinned
+as a regression test; CI gates on the suite, lint, and a sanitisation scan of
 the tree *and its history*; the evidence corpus is anchored to publicly
 documented production deployments; every decision is reproducible from its
 inputs.
@@ -712,6 +726,7 @@ the same receipts the emitted `ARCHITECTURE.md` prints.
 | `fde bench <eng>=<project> ...` | the same figures off every record, side by side, in `BENCH.md` |
 | `fde history <eng>` | every dated entry on the record in order, one line each |
 | `fde mcp` / `fde mcp --check` | serve triage, start, frame, status, next, stage, debt, stop-when and history to a coding agent over stdio, confined to `FDE_WORKSPACE`; `--check` lists what it serves |
+| `fde doctor` | whether this install can do what the README says: interpreter, package, registry, working directory, extras, docker, the agent, the linter; exit 1 only on what the core needs |
 | `fde outcome-contract <eng> --owner --metric --baseline --unit --target --method --window` | the eighth gate: which number this system exists to move, from what to what, measured how, by when |
 | `fde debt <eng>` | decision debt: what nobody has settled, with an owner, what it blocks, and its age |
 | `fde stop-when <eng> --when "answered_accuracy < 0.88"` | what evidence would stop the engagement; judged against the record, exit 1 and a STOP stage when triggered |
@@ -898,7 +913,7 @@ Set up as in [Install → from source](#install) (python3.11+), then:
 
 ```bash
 .venv/bin/pip install -e ".[dev,documents]"
-.venv/bin/pytest -q          # 1160+ tests, ~ 100s
+.venv/bin/pytest -q          # the full suite, about two minutes
 .venv/bin/ruff check src tests
 ```
 

{fde_framework-0.1.43 → fde_framework-0.1.45}/README.md

@@ -67,12 +67,15 @@ it can say stop.
 
 ```bash
 pip install fde-framework
+fde doctor               # the interpreter, the package, the registry, the extras: measured, not guessed
 fde start acme --statement "Route each support message to one of 77 queues."
 fde next acme            # the one thing to learn or do next, and what turns on it
 ```
 
 One minute, nothing to bring: paste two problems and see which one is
-decidable yet.
+decidable yet. For what the whole loop looks like on a real dataset,
+including the one time the framework told itself to stop, read the
+[banking run](https://github.com/atulkapoor/fde-demo-banking#the-operating-loop-closed).
 
 ```
 $ fde triage --statement "Route each inbound support message to one of 77 queues; customer data may not leave our cloud account." \
@@ -110,16 +113,26 @@ the argument `mcp`:
 It serves `triage`, `start`, `frame`, `status`, `next`, `stage`, `debt`,
 `stop_when` and `history`, each returning exactly what the terminal prints,
 refusals included, beside a small envelope an agent can branch on without
-parsing prose: `status` (ok, blocked, refused, failed), `mutated`, and the
-workspace. The envelope follows the command's exit, never a reading of
-its text. An agent is not a person, so every path it supplies must
-stay inside one workspace, the directory the server started in or
+parsing prose: `schema_version`, `status` (ok, blocked, refused, failed),
+`mutated`, and the workspace. The envelope follows the command's exit,
+never a reading of its text. Its contract is a JSON Schema, `fde mcp
+--schema`, that every reply is tested against; a client pins
+`schema_version`, which moves only when a field changes meaning or goes
+away, never when one is added. An engagement is named as `start` named
+it (`start(name="acme")`, then `status(engagement="acme")`), or by its
+path. An agent is not a person, so every path it supplies must stay
+inside one workspace, the directory the server started in or
 `FDE_WORKSPACE`; a path outside it, a traversal, or a symlink that points
 out is refused in words, and engagement names are plain names. The two
 tools that write to the record, `start` and `frame`, say so and carry the
-protocol's hints so a client can ask first. Building, implementing and
-deploying are not served; they stay on the command line, where the person
-who runs them is accountable for them.
+protocol's hints so a client can ask first. Calls run one at a time
+inside the server, so an agent that asks for `status` and `next` in the
+same breath gets both. Exercised against two real clients: the official
+MCP Python client over stdio, in the test suite, with concurrent calls,
+an abandoned call and a record changed on disk between calls; and Claude
+Code 2.1, by hand, from the configuration above. Building, implementing
+and deploying are not served; they stay on the command line, where the
+person who runs them is accountable for them.
 
 > ### Five founding engagements
 > One real workflow, your real examples, a measured baseline, and someone
@@ -184,7 +197,7 @@ ladder, so nothing here can be over-read:
 
 | Claim | Status | The evidence, and where it stops |
 |---|---|---|
-| The framework is implemented | verified | 1,306 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed |
+| The framework is implemented | verified | 1,316 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
 | A build is reproducible | verified | byte-identical rebuild pinned by test; each public demo carries a Reproduce section and its digests |
 | The decisions generalise | partial | four shapes (extraction, freeform QA, a labelled decision, seventy-seven-way routing) on real data; one industry set; `fde kb sweep` names the shapes nothing serves |
 | The deliverable is production-reliable | unverified | no production engagement; the banking operating loop ran on a laptop and its record says so |
@@ -248,9 +261,10 @@ pairs, role-scoped interview, hardware scan) → fact log with provenance →
 permutation space → eight gates → decide → architect → build (code, evals,
 deploy and ops assets, `RISKS.md`, `COMPLIANCE.md`) → retro and case
 capture. Overrides are honoured on the next run, trigger observations feed
-calibration, and a reviewed case can enter the corpus. 1160+ tests; nine
-fresh-eyes audit passes, every finding resolved and the fix pinned as a
-regression test; CI gates on the suite, lint, and a sanitisation scan of
+calibration, and a reviewed case can enter the corpus. The test count is
+stated once, in the claim ladder above, and updated at every release;
+eleven fresh-eyes audit passes, every finding resolved and the fix pinned
+as a regression test; CI gates on the suite, lint, and a sanitisation scan of
 the tree *and its history*; the evidence corpus is anchored to publicly
 documented production deployments; every decision is reproducible from its
 inputs.
@@ -668,6 +682,7 @@ the same receipts the emitted `ARCHITECTURE.md` prints.
 | `fde bench <eng>=<project> ...` | the same figures off every record, side by side, in `BENCH.md` |
 | `fde history <eng>` | every dated entry on the record in order, one line each |
 | `fde mcp` / `fde mcp --check` | serve triage, start, frame, status, next, stage, debt, stop-when and history to a coding agent over stdio, confined to `FDE_WORKSPACE`; `--check` lists what it serves |
+| `fde doctor` | whether this install can do what the README says: interpreter, package, registry, working directory, extras, docker, the agent, the linter; exit 1 only on what the core needs |
 | `fde outcome-contract <eng> --owner --metric --baseline --unit --target --method --window` | the eighth gate: which number this system exists to move, from what to what, measured how, by when |
 | `fde debt <eng>` | decision debt: what nobody has settled, with an owner, what it blocks, and its age |
 | `fde stop-when <eng> --when "answered_accuracy < 0.88"` | what evidence would stop the engagement; judged against the record, exit 1 and a STOP stage when triggered |
@@ -854,7 +869,7 @@ Set up as in [Install → from source](#install) (python3.11+), then:
 
 ```bash
 .venv/bin/pip install -e ".[dev,documents]"
-.venv/bin/pytest -q          # 1160+ tests, ~ 100s
+.venv/bin/pytest -q          # the full suite, about two minutes
 .venv/bin/ruff check src tests
 ```
 

{fde_framework-0.1.43 → fde_framework-0.1.45}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name matches the repository and stays unique on any index;
 # the import package and the CLI command remain the short `fde`.
 name = "fde-framework"
-version = "0.1.43"
+version = "0.1.45"
 description = "The decision before the AI build: evidence in, an architecture with receipts out, a scored build or a stop. For Forward Deployed Engineers and anyone deciding whether an AI system should exist."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{fde_framework-0.1.43 → fde_framework-0.1.45}/src/fde/cli.py

@@ -2339,17 +2339,87 @@ def experiment_cmd(
         raise typer.Exit(1) from exc
 
 
+@app.command("doctor")
+def doctor_cmd(
+    registry_root: Annotated[Path, typer.Option("--registry")] = DEFAULT_ROOT,
+) -> None:
+    """Whether this install can do what the README says: the interpreter,
+    the package, the registry, the working directory, the optional extras,
+    and the tools the implement loop and the sandbox would call. Each line
+    is a measurement, never a guess; exit 1 when something the core needs
+    is missing."""
+    import importlib.metadata
+    import shutil
+    import sys
+
+    from fde.registry import is_empty, load_registry
+
+    rows: list[tuple[str, bool | None, str]] = []
+    rows.append(("python", sys.version_info >= (3, 11),
+                 f"{sys.version.split()[0]} at {sys.executable}"))
+    try:
+        rows.append(("fde-framework", True, importlib.metadata.version("fde-framework")))
+    except importlib.metadata.PackageNotFoundError:
+        rows.append(("fde-framework", False, "not installed as a package (a checkout?)"))
+    try:
+        registry = load_registry(registry_root)
+        ok = not is_empty(registry)
+        rows.append(("registry", ok, f"{registry_root} -- {len(registry.dimensions)} dimensions, "
+                                     f"{len(registry.approaches)} approaches, "
+                                     f"{len(registry.patterns)} patterns, "
+                                     f"{len(registry.stacks)} stacks" if ok
+                     else f"{registry_root} loads empty"))
+    except RegistryError as exc:
+        rows.append(("registry", False, str(exc).splitlines()[0]))
+    cwd = Path.cwd()
+    rows.append(("working directory", os.access(cwd, os.W_OK), f"{cwd} is "
+                 + ("writable" if os.access(cwd, os.W_OK) else "not writable")))
+    for extra, module, why in (("documents", "pypdf", "fde frame --file brief.pdf"),
+                               ("mcp", "mcp", "fde mcp"),
+                               ("llm", "anthropic", "fde frame --reader llm (hosted)")):
+        try:
+            importlib.import_module(module)
+            rows.append((f"extra [{extra}]", None, f"installed -- {why}"))
+        except ImportError:
+            rows.append((f"extra [{extra}]", None,
+                         f"not installed -- pip install 'fde-framework[{extra}]' for {why}"))
+    for tool, why in (("docker", "fde implement --sandbox docker"),
+                      ("claude", "the default --agent-cmd of fde implement"),
+                      ("ruff", "the lint row of fde scorecard and the emitted project's "
+                               "own lint test")):
+        found = shutil.which(tool)
+        rows.append((tool, None, f"{found} -- {why}" if found
+                     else f"not on PATH -- {why} will say so when asked"))
+    width = max(len(name) for name, _, _ in rows)
+    failed = False
+    for name, ok, detail in rows:
+        mark = "  --" if ok is None else ("  ok" if ok else "  NO")
+        failed = failed or ok is False
+        typer.echo(f"{mark} {name:{width}}  {detail}")
+    typer.echo("\nsomething the core needs is missing" if failed
+               else "\nthe core can run; the -- lines are optional")
+    if failed:
+        raise typer.Exit(1)
+
+
 @app.command("mcp")
 def mcp_cmd(
     check: Annotated[bool, typer.Option(
         "--check", help="Build the server and list what it serves, without serving it."
     )] = False,
+    schema: Annotated[bool, typer.Option(
+        "--schema", help="Print the JSON Schema of the envelope beside every reply."
+    )] = False,
 ) -> None:
     """Serve the framework's conversational commands to a coding agent over
     stdio (Model Context Protocol): triage, start, frame, status, next,
     stage, debt, stop_when, history. Every path the agent supplies must be
     inside the workspace (FDE_WORKSPACE, else the current directory). Add
     it with, for example, `claude mcp add fde -- fde mcp`."""
+    if schema:
+        from fde.mcp_server import ENVELOPE_SCHEMA
+        typer.echo(json.dumps(ENVELOPE_SCHEMA, indent=2))
+        return
     try:
         from fde.mcp_server import describe, serve
         if check:

{fde_framework-0.1.43 → fde_framework-0.1.45}/src/fde/mcp_server.py

@@ -30,10 +30,43 @@ from __future__ import annotations
 
 import os
 import re
+import threading
 from pathlib import Path
 
 NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
 
+# The envelope beside every reply, as the JSON Schema a client can validate
+# against (`fde mcp --schema` prints it). Bump the version when a field
+# changes meaning or goes away; adding a field keeps the version.
+SCHEMA_VERSION = 1
+STATUSES = ("ok", "blocked", "refused", "failed")
+TOOLS = ("triage", "start", "frame", "status", "next", "stage", "debt", "stop_when", "history")
+ENVELOPE_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": f"https://github.com/atulkapoor/fde-framework/schemas/mcp-envelope/v{SCHEMA_VERSION}",
+    "title": f"fde MCP reply envelope, version {SCHEMA_VERSION}",
+    "description": "The structured content beside the text of every tool reply. The text "
+                   "is what the command printed; the envelope is what an agent branches on "
+                   "without parsing prose. It follows the command's exit, not its wording.",
+    "type": "object",
+    "properties": {
+        "schema_version": {"const": SCHEMA_VERSION,
+                           "description": "Bumped when a field changes meaning or goes away."},
+        "tool": {"enum": list(TOOLS), "description": "The tool that answered."},
+        "status": {"enum": list(STATUSES),
+                   "description": "ok: the command exited 0. blocked: it refused or a "
+                                  "condition triggered (exit 1); the text says which. "
+                                  "refused: a path or name was outside what the agent may "
+                                  "touch; nothing ran. failed: an exception; a bug to report."},
+        "mutated": {"type": "boolean",
+                    "description": "True only when a writing tool ran and exited 0."},
+        "workspace": {"type": "string",
+                      "description": "The directory every path was confined to."},
+    },
+    "required": ["schema_version", "tool", "status", "mutated", "workspace"],
+    "additionalProperties": False,
+}
+
 THIRTY_SECONDS = """\
 You give it the problem as the client put it, the client's own examples,
 the constraints, a baseline someone measured, and where it has to run. It
@@ -54,10 +87,12 @@ brief into typed facts; `status` for the gates and what is still unknown;
 for where the engagement stands on its record; `debt` for what nobody has
 settled; `stop_when` for whether the evidence says stop; `history` for the
 whole record in order. Every tool returns the command's own output,
-refusals included. `start` and `frame` write to the record; the rest only
-read it. Every path must be inside the server's workspace. Nothing here
-builds, implements or deploys; those are run by a person on the command
-line.
+refusals included, with a status beside it (ok, blocked, refused, failed)
+to branch on instead of the prose. `start` and `frame` write to the
+record; the rest only read it. An engagement is named as `start` named
+it, or by its path; every path must be inside the server's workspace.
+Nothing here builds, implements or deploys; those are run by a person on
+the command line.
 """
 
 
@@ -86,6 +121,21 @@ def confine(path: str | None, what: str, root: Path | None = None) -> Path | Non
     return resolved
 
 
+def locate(engagement: str) -> Path:
+    """The engagement as the command will see it. `start(name="acme")` puts
+    the record at engagements/acme; `status(engagement="acme")` a moment
+    later must find it, as `fde status acme` does on the command line. So a
+    bare name is looked for at <workspace>/<name> and then where `start`
+    puts it; both candidates are confined, so a name that climbs out is
+    refused before anything is looked for. A path is taken as given."""
+    path = confine(engagement, "engagement")
+    if path is not None and not (path / "facts").is_dir() and not Path(engagement).is_absolute():
+        under = confine(str(Path("engagements") / engagement), "engagement")
+        if under is not None and (under / "facts").is_dir():
+            return under
+    return path
+
+
 def plain_name(name: str) -> str:
     if not NAME.match(name or ""):
         raise Outside(f"an engagement name is a plain name (letters, digits, '.', '_', '-'), "
@@ -99,6 +149,16 @@ def _registry() -> str:
     return os.environ.get("FDE_REGISTRY") or str(default_root())
 
 
+# One command at a time. The server runs each tool on a worker thread, and
+# a coding agent will issue `status` and `next` in the same breath; the
+# runner that captures a command's output does so by swapping the
+# process's stdout, and two swaps interleaved left one command printing
+# straight onto the JSON-RPC channel. The protocol broke, the client saw
+# "Connection closed", and the record was not at fault. Commands take
+# milliseconds; the record has one writer at a time, as it should.
+_ONE_AT_A_TIME = threading.Lock()
+
+
 def run_command(args: list[str], registry: bool = True) -> tuple[str, str]:
     """One command, in-process, as the terminal would run it: the text it
     printed, and a status an agent can branch on without parsing prose --
@@ -109,7 +169,8 @@ def run_command(args: list[str], registry: bool = True) -> tuple[str, str]:
     from fde.cli import app
 
     argv = [*args, "--registry", _registry()] if registry else list(args)
-    result = CliRunner().invoke(app, argv)
+    with _ONE_AT_A_TIME:
+        result = CliRunner().invoke(app, argv)
     text = (result.output or "").strip()
     if result.exception and not isinstance(result.exception, SystemExit):
         return (f"{text}\n\nfde: {type(result.exception).__name__}: {result.exception}".strip(),
@@ -128,8 +189,8 @@ def reply(tool: str, text: str, status: str, mutated: bool):
 
     return types.CallToolResult(
         content=[types.TextContent(type="text", text=text)],
-        structured_content={"tool": tool, "status": status, "mutated": mutated,
-                            "workspace": str(workspace())},
+        structured_content={"schema_version": SCHEMA_VERSION, "tool": tool, "status": status,
+                            "mutated": mutated, "workspace": str(workspace())},
         is_error=status == "failed",
     )
 
@@ -197,14 +258,14 @@ def build_server():
         """WRITES: reads a brief, pasted as text, into typed facts appended to
         the engagement's record, played back for correction with the
         follow-up questions. The engagement must be inside the workspace."""
-        return run_command(["frame", str(confine(engagement, "engagement")), "--text", text])
+        return run_command(["frame", str(locate(engagement)), "--text", text])
 
     @server.tool(annotations=reads)
     @guarded
     def status(engagement: str):
         """The engagement's gates, what is known by scope and who said it, what
         is still missing, and which roles have not been heard."""
-        return run_command(["status", str(confine(engagement, "engagement"))])
+        return run_command(["status", str(locate(engagement))])
 
     @server.tool(annotations=reads)
     @guarded
@@ -213,7 +274,7 @@ def build_server():
         and -- when it is a question -- the evidence already on record and
         the decisions that turn on each candidate answer. Reads only; the
         action it names is for a person to run."""
-        return run_command(["next", str(confine(engagement, "engagement"))])
+        return run_command(["next", str(locate(engagement))])
 
     @server.tool(annotations=reads)
     @guarded
@@ -222,7 +283,7 @@ def build_server():
         validation, prototype, pilot, production, adoption, retrospective,
         or stopped -- with what would move it to the next stage. Reads only:
         a person runs `fde stage` to append the transition to the record."""
-        args = ["stage", str(confine(engagement, "engagement")), "--no-record"]
+        args = ["stage", str(locate(engagement)), "--no-record"]
         target = confine(project, "project")
         return run_command(args + (["--project", str(target)] if target else []))
 
@@ -233,7 +294,7 @@ def build_server():
         settled -- failing gates, standing waivers, guessed or merely stated
         facts, disagreements, unsigned attestations, unheard roles, open
         incidents, undecided components -- each with an owner and an age."""
-        return run_command(["debt", str(confine(engagement, "engagement"))])
+        return run_command(["debt", str(locate(engagement))])
 
     @server.tool(annotations=reads)
     @guarded
@@ -242,7 +303,7 @@ def build_server():
         """Judge the engagement's stop conditions against what the record has
         measured: the scorecard, the field journal, the recorded outcomes.
         Reads only; recording a condition is for a person."""
-        args = ["stop-when", str(confine(engagement, "engagement"))]
+        args = ["stop-when", str(locate(engagement))]
         target = confine(project, "project")
         if target:
             args += ["--project", str(target)]
@@ -256,7 +317,7 @@ def build_server():
     def history(engagement: str):
         """Every dated entry on the engagement's record, in order, the undated
         ones above it, one line each."""
-        return run_command(["history", str(confine(engagement, "engagement"))],
+        return run_command(["history", str(locate(engagement))],
                            registry=False)
 
     @server.resource("fde://thirty-seconds", name="fde in thirty seconds",
@@ -279,6 +340,7 @@ def describe() -> str:
             else "reads"
         lines.append(f"    {tool.name:10} {hint}")
     lines.append("  resources: fde://thirty-seconds")
+    lines.append(f"  envelope: schema_version {SCHEMA_VERSION} (`fde mcp --schema`)")
     return "\n".join(lines)