simplicio-cli 0.10.0__tar.gz → 0.16.1__tar.gz

{simplicio_cli-0.10.0 → simplicio_cli-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-cli
-Version: 0.10.0
+Version: 0.16.1
 Summary: Portable task-to-code pipeline that works with any LLM. Turn a one-line task into a verified code change — diff + test + verify loop. +55 pts on a 156-check benchmark, 21% faster, ~same tokens.
 Author-email: Wesley Simplicio <wesleybob4@gmail.com>
 License: MIT
@@ -28,7 +28,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=2.1.0
-Requires-Dist: simplicio-mapper>=0.18.0
+Requires-Dist: simplicio-mapper>=0.23.1
 Requires-Dist: simplicio-prompt>=1.14.1
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: orjson>=3.11.9
@@ -98,8 +98,12 @@ The new first screen is the doorway; the restored guide below is the workshop. T
 pip install -U simplicio-cli
 simplicio-py detect "hide the Delete button for non-admins"
 simplicio-py task "hide the Delete button for non-admins"
+simplicio-py --version --json
 ```
 
+The JSON version handshake is the canonical identity surface for runtime/agent consumers. It
+includes the package version, entrypoints, mapper version, and supported contract capabilities.
+
 Auto-upgrade is now opt-in: set `SIMPLICIO_AUTO_UPGRADE=1` for session-start upgrades, or run `simplicio-py doctor --upgrade` explicitly.
 Python consumers can expose the bundled mapper dependency directly with
 `from simplicio import mapper_module, mapper_version` or `import simplicio.mapper_api`.
@@ -109,7 +113,7 @@ Python consumers can expose the bundled mapper dependency directly with
 - Classifies the task before execution so small fixes stay small and sprint-scale work becomes a plan.
 - Loads simplicio-mapper artifacts before asking an LLM to edit.
 - Keeps a verification loop around generated diffs instead of trusting the first answer.
-- Works with local Simplicio1, OpenRouter, OpenAI, Anthropic, DeepSeek, Hermes, Codex and Claude-style hosts.
+- Works with local Simplicio1, OpenRouter, OpenAI, Anthropic, DeepSeek, Simplicio Agent, Codex and Claude-style hosts.
 
 ## Why this README is built to earn attention
 
@@ -168,7 +172,7 @@ delivery status"]
 
 The section below restores the project-specific README material that existed before the globalization pass. Keep this substance when refreshing the top-level narrative: add polish, do not erase operational memory.
 
-**Your tasks with 99% accuracy using any LLM (Claude, DeepSeek, Codex, Gemini, Hermes, OpenClaw, Cursor).**
+**Your tasks with 99% accuracy using any LLM (Claude, DeepSeek, Codex, Gemini, Simplicio Agent, OpenClaw, Cursor).**
 
 [![PyPI](https://img.shields.io/pypi/v/simplicio-cli.svg)](https://pypi.org/project/simplicio-cli/)
 [![Python](https://img.shields.io/pypi/pyversions/simplicio-cli.svg)](https://pypi.org/project/simplicio-cli/)
@@ -640,6 +644,13 @@ cost_usd, diff_summary, warnings}`. Repeat `--bound-paths <glob>` to reject
 diffs outside the allowed edit surface; violations are reported in `warnings`
 and the command exits non-zero.
 
+See [structured blocked-precondition receipts](docs/blocked-preconditions.md) for the JSON `status`, `blocked_preconditions`, `reason`, and `next_surface` contract.
+See [patch receipts](docs/patch-receipts.md) for parser strategy, recovery fingerprint, and requested/effective capability evidence.
+See [the evidence ledger](docs/evidence-ledger.md) for append-only AC/RN receipts and stale-artifact gates.
+See [multi-task batches](docs/multi-task-batches.md) for deterministic DAG state and resumable transitions.
+See [prompt envelopes](docs/prompt-envelopes.md) for layer budgets, stable prefix hashes, and typed retry deltas.
+The deterministic delivery corpus is available with `python -m bench.run_delivery_corpus`.
+
 #### Path 3 example — standalone with API key
 
 ```bash

{simplicio_cli-0.10.0 → simplicio_cli-0.16.1}/README.md

@@ -34,22 +34,26 @@ The new first screen is the doorway; the restored guide below is the workshop. T
 
 ## Quick Start
 
-```bash
-pip install -U simplicio-cli
-simplicio-py detect "hide the Delete button for non-admins"
-simplicio-py task "hide the Delete button for non-admins"
-```
-
-Auto-upgrade is now opt-in: set `SIMPLICIO_AUTO_UPGRADE=1` for session-start upgrades, or run `simplicio-py doctor --upgrade` explicitly.
-Python consumers can expose the bundled mapper dependency directly with
-`from simplicio import mapper_module, mapper_version` or `import simplicio.mapper_api`.
+```bash
+pip install -U simplicio-cli
+simplicio-py detect "hide the Delete button for non-admins"
+simplicio-py task "hide the Delete button for non-admins"
+simplicio-py --version --json
+```
+
+The JSON version handshake is the canonical identity surface for runtime/agent consumers. It
+includes the package version, entrypoints, mapper version, and supported contract capabilities.
+
+Auto-upgrade is now opt-in: set `SIMPLICIO_AUTO_UPGRADE=1` for session-start upgrades, or run `simplicio-py doctor --upgrade` explicitly.
+Python consumers can expose the bundled mapper dependency directly with
+`from simplicio import mapper_module, mapper_version` or `import simplicio.mapper_api`.
 
 ## What it does
 
 - Classifies the task before execution so small fixes stay small and sprint-scale work becomes a plan.
 - Loads simplicio-mapper artifacts before asking an LLM to edit.
 - Keeps a verification loop around generated diffs instead of trusting the first answer.
-- Works with local Simplicio1, OpenRouter, OpenAI, Anthropic, DeepSeek, Hermes, Codex and Claude-style hosts.
+- Works with local Simplicio1, OpenRouter, OpenAI, Anthropic, DeepSeek, Simplicio Agent, Codex and Claude-style hosts.
 
 ## Why this README is built to earn attention
 
@@ -108,7 +112,7 @@ delivery status"]
 
 The section below restores the project-specific README material that existed before the globalization pass. Keep this substance when refreshing the top-level narrative: add polish, do not erase operational memory.
 
-**Your tasks with 99% accuracy using any LLM (Claude, DeepSeek, Codex, Gemini, Hermes, OpenClaw, Cursor).**
+**Your tasks with 99% accuracy using any LLM (Claude, DeepSeek, Codex, Gemini, Simplicio Agent, OpenClaw, Cursor).**
 
 [![PyPI](https://img.shields.io/pypi/v/simplicio-cli.svg)](https://pypi.org/project/simplicio-cli/)
 [![Python](https://img.shields.io/pypi/pyversions/simplicio-cli.svg)](https://pypi.org/project/simplicio-cli/)
@@ -417,7 +421,7 @@ recorded to a separate append-only ledger,
 `.simplicio/ledger/savings-events.jsonl` (`simplicio.savings-event/v1`), via
 `simplicio.observability.record_savings_event()`.
 
-#### Cross-vendor memory
+#### Cross-vendor memory
 
 `simplicio-dev-cli memory init|store|recall` is a markdown + git store under
 `~/.simplicio/memory/` (override with `SIMPLICIO_MEMORY_DIR`) for handing
@@ -580,6 +584,13 @@ cost_usd, diff_summary, warnings}`. Repeat `--bound-paths <glob>` to reject
 diffs outside the allowed edit surface; violations are reported in `warnings`
 and the command exits non-zero.
 
+See [structured blocked-precondition receipts](docs/blocked-preconditions.md) for the JSON `status`, `blocked_preconditions`, `reason`, and `next_surface` contract.
+See [patch receipts](docs/patch-receipts.md) for parser strategy, recovery fingerprint, and requested/effective capability evidence.
+See [the evidence ledger](docs/evidence-ledger.md) for append-only AC/RN receipts and stale-artifact gates.
+See [multi-task batches](docs/multi-task-batches.md) for deterministic DAG state and resumable transitions.
+See [prompt envelopes](docs/prompt-envelopes.md) for layer budgets, stable prefix hashes, and typed retry deltas.
+The deterministic delivery corpus is available with `python -m bench.run_delivery_corpus`.
+
 #### Path 3 example — standalone with API key
 
 ```bash

{simplicio_cli-0.10.0 → simplicio_cli-0.16.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simplicio-cli"
-version = "0.10.0"
+version = "0.16.1"
 description = "Portable task-to-code pipeline that works with any LLM. Turn a one-line task into a verified code change — diff + test + verify loop. +55 pts on a 156-check benchmark, 21% faster, ~same tokens."
 readme = "README.md"
 license = { text = "MIT" }
@@ -33,8 +33,8 @@ classifiers = [
   "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
-  "Programming Language :: Python :: 3.12",
-  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Topic :: Software Development",
   "Topic :: Software Development :: Code Generators",
   "Topic :: Software Development :: Libraries :: Python Modules",
@@ -53,7 +53,7 @@ classifiers = [
 # (generated, `--check`-able) for the full graph and #99 for the audit.
 dependencies = [
   "numpy>=2.1.0",
-  "simplicio-mapper>=0.18.0",
+  "simplicio-mapper>=0.23.1",
   "simplicio-prompt>=1.14.1",
   "httpx>=0.28.1",
   "orjson>=3.11.9",
@@ -89,10 +89,10 @@ test = ["pytest>=8", "tomli>=2.0.1; python_version < '3.11'"]
 dev = ["simplicio-cli[test]", "ruff>=0.15.8", "mypy>=1.19.1"]
 
 [project.urls]
-Homepage = "https://github.com/wesleysimplicio/simplicio-dev-cli"
-Repository = "https://github.com/wesleysimplicio/simplicio-dev-cli"
-Issues = "https://github.com/wesleysimplicio/simplicio-dev-cli/issues"
-Changelog = "https://github.com/wesleysimplicio/simplicio-dev-cli/releases"
+Homepage = "https://github.com/wesleysimplicio/simplicio-dev-cli"
+Repository = "https://github.com/wesleysimplicio/simplicio-dev-cli"
+Issues = "https://github.com/wesleysimplicio/simplicio-dev-cli/issues"
+Changelog = "https://github.com/wesleysimplicio/simplicio-dev-cli/releases"
 
 [project.scripts]
 simplicio-cli = "simplicio.cli:main"
@@ -118,6 +118,13 @@ simplicio = [
   "templates/stacks/**/*",
   "templates/stacks/*/tree/.gitignore",
   "templates/stacks/*/tree/.eslintrc.json",
+  # `score-skill` loads these builtin scenario fixtures at runtime from
+  # Path(__file__).resolve().parent / "scenarios" (see
+  # simplicio/commands/score_skill.py:_resolve_scenarios). Without this
+  # entry the wheel ships score_skill.py but not its data, so an installed
+  # `simplicio-py score-skill` with no --scenario silently fails outside the
+  # checkout (#167 AC "Package instalado contem docs/schemas esperados").
+  "commands/scenarios/*.json",
 ]
 
 [tool.pytest.ini_options]
@@ -146,7 +153,7 @@ extend-exclude = [
 [tool.ruff.lint]
 # E/F = pyflakes+pycodestyle core, I = isort, UP = pyupgrade, B = bugbear,
 # T20 = flake8-print (issue #106 — blocks new print() regressions in
-# library code; see per-file-ignores below for the documented
+# library code; see per-file-ignores below for the documented
 # CLI-handler exception, where stdout IS the subcommand's intended output).
 select = ["E", "F", "I", "UP", "B", "T20"]
 # B008: PLAN_JSON-style default args show up in a few argparse builders;
@@ -158,8 +165,8 @@ ignore = []
 "tests/**/*.py" = ["E501", "T201"]
 # CLI-handler exception (#106): stdout IS the intended output of these
 # subcommand entry points (JSON payloads, tables, human summaries), so
-# print() is the correct tool here — never in providers.py, pipeline.py,
-# mapper.py, or any other library module, which
+# print() is the correct tool here — never in providers.py, pipeline.py,
+# mapper.py, or any other library module, which
 # stay covered by the bare T201 rule above with zero suppressions.
 "simplicio/cli.py" = ["T201"]
 "simplicio/doctor.py" = ["T201"]
@@ -179,7 +186,7 @@ quote-style = "double"
 indent-style = "space"
 
 [tool.mypy]
-python_version = "3.13"
+python_version = "3.13"
 files = ["simplicio"]
 # Baseline rigor (#102 AC): permissive on missing third-party stubs, but
 # real within the package. Tighten per-module (`[[tool.mypy.overrides]]`)

{simplicio_cli-0.10.0 → simplicio_cli-0.16.1}/simplicio/__init__.py

@@ -1,5 +1,5 @@
-__version__ = "0.10.0"
-
-from .mapper_api import mapper_module, mapper_version
-
-__all__ = ["__version__", "mapper_module", "mapper_version"]
+__version__ = "0.16.1"
+
+from .mapper_api import mapper_module, mapper_version
+
+__all__ = ["__version__", "mapper_module", "mapper_version"]

{simplicio_cli-0.10.0 → simplicio_cli-0.16.1}/simplicio/bench.py

@@ -26,7 +26,14 @@ def _test(output: str, root: str, test_cmd: str) -> bool:
     os.makedirs(os.path.join(root, ".simplicio"), exist_ok=True)
     Path(root, ".simplicio", "bench_out.txt").write_text(output or "", encoding="utf-8")
     test_cmd = wrap_project_command(root, test_cmd)
-    p = subprocess.run(test_cmd, shell=True, cwd=root, capture_output=True, text=True)
+    p = subprocess.run(
+        test_cmd,
+        shell=True,
+        cwd=root,
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        text=True,
+    )
     return p.returncode == 0
 
 

{simplicio_cli-0.10.0 → simplicio_cli-0.16.1}/simplicio/cli.py

@@ -49,11 +49,24 @@ def maybe_autoinstall(cmd: str | None) -> bool:
     return False
 
 
+def _delegation_route(*, forced_python: bool, native_available: bool, delegated: bool) -> tuple[str, str]:
+    """Classify a gate/nest delegation attempt into (route, reason) for
+    `runtime_bridge.record_delegation` (issue #111)."""
+    if forced_python:
+        return "python-forced", "user-forced-python"
+    if delegated:
+        return "native", ""
+    if not native_available:
+        return "python-fallback", "binary-not-found"
+    return "python-fallback", "delegation-error"
+
+
 def _dispatch_nested(argv: list[str]) -> int | None:
     """``gate``/``nest``/``scratch``/``skill`` bypass the main argparse
     parser entirely — each owns its own argv[0]-based dispatch and arg
     parsing (unchanged by issue #103's cli.py cleanup)."""
     from .commands._shared import parse_rust_flags, try_route_via_simplicio
+    from .runtime_bridge import record_delegation, simplicio_available
 
     def wants_help(args: list[str]) -> bool:
         return any(arg in {"-h", "--help"} for arg in args)
@@ -61,9 +74,14 @@ def _dispatch_nested(argv: list[str]) -> int | None:
     if argv and argv[0] == "gate":
         clean_args, native, python = parse_rust_flags(argv[1:])
         if not wants_help(clean_args):
+            native_available = simplicio_available()
             result = try_route_via_simplicio(
                 "gate", clean_args, prefer_native=native or not python, prefer_python=python
             )
+            route, reason = _delegation_route(
+                forced_python=python, native_available=native_available, delegated=result is not None
+            )
+            record_delegation("gate", route, reason=reason or None)
             if result is not None:
                 return result
         from .commands.gate import main as gate_main
@@ -72,9 +90,14 @@ def _dispatch_nested(argv: list[str]) -> int | None:
     if argv and argv[0] == "nest":
         clean_args, native, python = parse_rust_flags(argv[1:])
         if not wants_help(clean_args):
+            native_available = simplicio_available()
             result = try_route_via_simplicio(
                 "nest", clean_args, prefer_native=native or not python, prefer_python=python
             )
+            route, reason = _delegation_route(
+                forced_python=python, native_available=native_available, delegated=result is not None
+            )
+            record_delegation("nest", route, reason=reason or None)
             if result is not None:
                 return result
         from .commands.nest import main as nest_main
@@ -239,6 +262,42 @@ def _build_parser() -> argparse.ArgumentParser:
     p_inspect.add_argument("--goal", default="")
     p_inspect.add_argument("--json", action="store_true")
 
+    p_intake = sub.add_parser(
+        "intake",
+        help="parse raw task cards into the provider-free TaskSpec v2 contract",
+    )
+    p_intake.add_argument("text", nargs="?", help="raw task text; defaults to stdin")
+    p_intake.add_argument("--root", default=".", help="repository root used for plan-only mapper discovery")
+    p_intake.add_argument("--file", help="read task Markdown/text from a file")
+    p_intake.add_argument("--stdin", action="store_true", help="read task Markdown/text from stdin")
+    p_intake.add_argument("--url", help="fetch task Markdown/text from an HTTP(S) URL")
+    p_intake.add_argument("--source-url", help="preserve an external source URL without fetching it")
+    p_intake.add_argument(
+        "--validate-only",
+        action="store_true",
+        help="validate and wrap the TaskSpec in a validation result",
+    )
+    p_intake.add_argument(
+        "--contract",
+        action="store_true",
+        help="compile each TaskSpec into an immutable ExecutionContract",
+    )
+    p_intake.add_argument(
+        "--execution-mode",
+        action="store_true",
+        help="fail closed when the compiled contract is not executable",
+    )
+    p_intake.add_argument(
+        "--plan-only",
+        action="store_true",
+        help="emit a contract-backed plan preview without dispatch or mutation",
+    )
+    p_intake.add_argument(
+        "--batch-path",
+        help="persist the frozen multi-task batch at this path (explicitly mutating)",
+    )
+    p_intake.add_argument("--json", action="store_true", help="emit stable structured JSON")
+
     p_doctor = sub.add_parser(
         "doctor",
         help="check local llama.cpp readiness and dependency freshness",
@@ -387,6 +446,10 @@ def _build_parser() -> argparse.ArgumentParser:
     p_runtime_doctor = runtime_sub.add_parser("doctor")
     p_runtime_doctor.add_argument("--root", default=".")
     p_runtime_doctor.add_argument("--json", action="store_true")
+    p_runtime_verify = runtime_sub.add_parser(
+        "verify", help="verify the real reserved Simplicio Runtime identity and capabilities"
+    )
+    p_runtime_verify.add_argument("--timeout", type=int, default=30)
 
     p_memory = sub.add_parser(
         "memory", help="cross-vendor memory handoff (markdown + git under ~/.simplicio/memory)"
@@ -404,8 +467,23 @@ def _build_parser() -> argparse.ArgumentParser:
     p_mem_recall = memory_sub.add_parser("recall", help="keyword search over stored notes")
     p_mem_recall.add_argument("query")
     p_mem_recall.add_argument("--limit", type=int, default=5)
+    p_mem_recall.add_argument("--mode", choices=("fts5", "vector", "hybrid"), default="hybrid")
     p_mem_recall.add_argument("--dir", default=None)
     p_mem_recall.add_argument("--json", action="store_true")
+    p_mem_validate = memory_sub.add_parser("validate", help="audit markdown memory store integrity")
+    p_mem_validate.add_argument("--dir", default=None)
+    p_mem_validate.add_argument("--strict", action="store_true", help="exit 2 when validation fails")
+    p_mem_validate.add_argument("--json", action="store_true")
+    p_mem_handoff = memory_sub.add_parser(
+        "handoff",
+        help="build a deterministic cross-vendor handoff packet from recall hits",
+    )
+    p_mem_handoff.add_argument("query")
+    p_mem_handoff.add_argument("--limit", type=int, default=5)
+    p_mem_handoff.add_argument("--dir", default=None)
+    p_mem_handoff.add_argument("--from-agent", default=None)
+    p_mem_handoff.add_argument("--to-agent", default=None)
+    p_mem_handoff.add_argument("--json", action="store_true")
 
     return ap
 
@@ -425,6 +503,7 @@ _COMMAND_MODULES = {
     "status": "status",
     "claims": "claims",
     "inspect": "inspect",
+    "intake": "intake",
     "doctor": "doctor",
     "env-export": "env_export",
     "file": "file",
@@ -443,6 +522,18 @@ def main(argv=None):
 
     configure_logging(quiet=quiet, verbose=verbose)
 
+    if argv and argv[0] in {"--version", "version"}:
+        import json
+
+        from .runtime_contracts import version_contract
+
+        payload = version_contract()
+        if "--json" in argv[1:]:
+            print(json.dumps(payload, sort_keys=True))
+        else:
+            print(f"{CLI_PROG} {payload['package']['version']}")
+        return 0
+
     try:
         # Session-start ecosystem-freshness check (closes the runtime gap where
         # pyproject pins >=X but the installed version is older). Idempotent +

{simplicio_cli-0.10.0 → simplicio_cli-0.16.1}/simplicio/commands/__init__.py

@@ -3,6 +3,17 @@
 Command routing — dispatches ``gate``, ``nest``, and ``score-skill``
 commands to the native Rust ``simplicio`` binary when available, with
 automatic fallback to the Python implementation.
+
+All three reach `route_command` (below) through
+`simplicio.commands._shared.try_route_via_simplicio`, but via two different
+paths — worth spelling out explicitly (issue #111 audit) so "score-skill is
+delegable" doesn't read as dead documentation: ``gate``/``nest`` bypass the
+main argparse parser entirely (`cli.py`'s ``_dispatch_nested`` calls
+`try_route_via_simplicio` directly, before falling back to
+`commands.gate`/`commands.nest`'s own ``main()``); ``score-skill`` goes
+through the normal argparse subparser and `commands/score_skill.py`'s
+``run()``, which calls `try_route_via_simplicio` itself
+(`commands/score_skill.py:246`) before falling back to its own ``main()``.
 """
 
 from __future__ import annotations

{simplicio_cli-0.10.0 → simplicio_cli-0.16.1}/simplicio/commands/edit.py

@@ -15,6 +15,7 @@ import shutil
 import subprocess
 import sys
 
+from ..runtime_bridge import delegated_command, record_delegation
 from ._shared import read_text_source
 
 CLI_PROG = "simplicio-py"
@@ -49,7 +50,7 @@ def _runtime_edit_binary() -> str | None:
 def run_edit(a: argparse.Namespace) -> int:
     runtime = None if a.no_runtime else _runtime_edit_binary()
     if runtime:
-        cmd = [runtime, "edit", "--plan", a.plan, "--repo", a.root]
+        cmd = delegated_command(runtime, ["edit", "--plan", a.plan, "--repo", a.root])
         if a.json:
             cmd.append("--json")
         if not a.apply:
@@ -61,6 +62,17 @@ def run_edit(a: argparse.Namespace) -> int:
             print(
                 f"{CLI_PROG} edit: runtime delegation failed ({exc}); using local fallback", file=sys.stderr
             )
+            record_delegation("edit", "python-fallback", root=a.root, reason=f"delegation-error: {exc}")
         else:
+            record_delegation("edit", "native", root=a.root)
             return completed.returncode
+    else:
+        if a.no_runtime:
+            reason = "user-forced-python (--no-runtime)"
+        elif os.environ.get("SIMPLICIO_DEV_CLI_NO_RUNTIME_EDIT"):
+            reason = "user-forced-python (SIMPLICIO_DEV_CLI_NO_RUNTIME_EDIT)"
+        else:
+            reason = "binary-not-found"
+        route = "python-forced" if reason.startswith("user-forced-python") else "python-fallback"
+        record_delegation("edit", route, root=a.root, reason=reason)
     return run_mechanical_edit(a)

{simplicio_cli-0.10.0 → simplicio_cli-0.16.1}/simplicio/commands/file_read.py

@@ -22,7 +22,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-from ..runtime_bridge import discover_simplicio
+from ..runtime_bridge import delegated_command, discover_simplicio, record_delegation
 
 SCHEMA = "simplicio.file-read/v1"
 DEFAULT_MAX_BYTES = 2 * 1024 * 1024  # 2 MiB
@@ -44,20 +44,26 @@ def _build_runtime_args(a: argparse.Namespace) -> list[str]:
     return cmd
 
 
-def _run_via_runtime(a: argparse.Namespace) -> int | None:
+def _run_via_runtime(a: argparse.Namespace) -> tuple[int | None, str | None]:
     """Attempt delegation to the Rust ``simplicio`` binary.
 
-    Returns the exit code on success, or ``None`` so the caller falls back
-    to the Python implementation (binary missing, or the call errored).
+    Returns ``(exit_code, reason)``: ``exit_code`` is the runtime binary's
+    exit code on success, or ``None`` so the caller falls back to the
+    Python implementation (binary missing, delegation errored, or the
+    binary didn't return the expected JSON contract). ``reason`` is a short
+    telemetry tag for `runtime_bridge.record_delegation`, always populated
+    when ``exit_code`` is ``None``.
     """
     binary = discover_simplicio()
     if binary is None:
-        return None
-    cmd = [binary, *_build_runtime_args(a)]
+        return None, "binary-not-found"
+    cmd = delegated_command(binary, _build_runtime_args(a))
     try:
         completed = subprocess.run(cmd, capture_output=True, text=True, timeout=RUNTIME_DELEGATION_TIMEOUT_S)
-    except (OSError, subprocess.TimeoutExpired):
-        return None
+    except subprocess.TimeoutExpired:
+        return None, "timeout"
+    except OSError as exc:
+        return None, f"delegation-error: {exc}"
 
     # Only trust the Rust binary's result if it actually produced the
     # expected JSON envelope — an unimplemented/erroring subcommand prints
@@ -66,9 +72,9 @@ def _run_via_runtime(a: argparse.Namespace) -> int | None:
     try:
         payload = json.loads(completed.stdout)
     except (json.JSONDecodeError, ValueError):
-        return None
+        return None, "invalid-json"
     if payload.get("schema") != SCHEMA:
-        return None
+        return None, "schema-mismatch"
 
     if a.json:
         print(completed.stdout, end="")
@@ -76,7 +82,7 @@ def _run_via_runtime(a: argparse.Namespace) -> int | None:
         print(payload.get("content", ""), end="")
     if completed.stderr:
         print(completed.stderr, end="", file=sys.stderr)
-    return completed.returncode
+    return completed.returncode, None
 
 
 def _read_fallback(a: argparse.Namespace) -> tuple[dict | None, str | None]:
@@ -147,7 +153,10 @@ def _run_fallback(a: argparse.Namespace) -> int:
 
 def run(a: argparse.Namespace) -> int:
     """Entry point wired from ``cli.py`` for ``simplicio-dev-cli file read``."""
-    result = _run_via_runtime(a)
+    result, reason = _run_via_runtime(a)
+    root = a.repo or "."
     if result is not None:
+        record_delegation("file", "native", root=root)
         return result
+    record_delegation("file", "python-fallback", root=root, reason=reason)
     return _run_fallback(a)