Let the operator console speak stdio, with the OS login as the approver

CHANGELOG.md

@@ -9,6 +9,31 @@ any change to one appears here.
 
 ## [Unreleased]
 
+### Added
+
+- **`ctrlrun mcp-operator --stdio`: the operator console for the client that launched it.**
+  Desktop assistants, Cursor and the editors launch an MCP server as a subprocess and speak to it on
+  stdin and stdout; until now this server spoke only HTTP on loopback, so the registry listing
+  that went live at 0.12.2 described a server none of those clients could start. `--stdio` opens
+  no socket at all, which is stricter than the loopback rule and not a loosening of it, and every
+  message still goes through the same parser, the same refusals and the same store calls as a
+  POST body does. The approver is the account the process runs as, read from the **real uid**
+  and from nothing the client sends or sets: not `getpass.getuser()`, which believes the
+  environment, not `clientInfo`, not `SUDO_USER`. What that does and does not promise is stated
+  rather than implied: a client that can subvert the process can already open the store as that
+  account, so nothing is added to what it can do, only a name on what it did. Root is an account
+  and not a person, so under uid 0 every write is refused and reads still answer. The login
+  carries no roles and no expiry, and says so: a control naming an `approver_role` refuses over
+  stdio, and the client process holds approve, deny and resolve under the login for as long as it
+  runs, which the `initialize` instructions and the startup block both say, because the
+  confirmation the client shows before a write is then the only human step. Every flag that
+  names a header is refused with it, by name, and `--max-body-bytes` now has a floor on both
+  transports. `SPEC-mcp-operator.md` §2.3 and §3.1 carry the
+  design, and §10's exclusion of stdio is struck through with the reasoning that replaced it
+  rather than deleted. The registry manifest now describes this: `uvx ctrlrun mcp-operator
+  --stdio` with `CTRLRUN_CONFIG` pointing at your policy, which is a config block a desktop
+  client can install.
+
 ## [0.12.2] — the operator's tool descriptions, and the marker the registry reads
 
 A patch release with no change to the enforcement path. Two things sat on `main` with no way for

server.json

@@ -15,15 +15,28 @@
       "registryBaseUrl": "https://pypi.org",
       "identifier": "ctrlrun",
       "version": "0.12.2",
+      "runtimeHint": "uvx",
       "transport": {
-        "type": "streamable-http",
-        "url": "http://127.0.0.1:8901/mcp"
+        "type": "stdio"
       },
       "packageArguments": [
         {
           "type": "positional",
           "value": "mcp-operator",
-          "description": "Serve the operator's own commands as MCP tools, over loopback."
+          "description": "Serve the operator's own commands as MCP tools."
+        },
+        {
+          "type": "named",
+          "name": "--stdio",
+          "description": "Speak MCP on stdin and stdout, open no socket, and record each answer under the OS login of the person whose client launched this."
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "CTRLRUN_CONFIG",
+          "description": "Path to the ctrlrun.yaml your agents run against. The store is found beside it.",
+          "isRequired": true,
+          "format": "filepath"
         }
       ]
     }

src/ctrlrun/cli/main.py

@@ -1882,6 +1882,14 @@ def _delegation_dict(delegation: Delegation) -> dict[str, Any]:
 @main.command(name="mcp-operator")
 @click.option("--listen", default="127.0.0.1:8901", show_default=True, help="HOST:PORT.")
 @click.option("--path", default="/mcp", show_default=True, help="The MCP endpoint path.")
+@click.option(
+    "--stdio",
+    is_flag=True,
+    help="Speak MCP on stdin and stdout to the client that launched this process (a "
+    "desktop assistant, Cursor, an editor). Opens no socket. The approver is the account this "
+    "process runs as, read from the real uid; takes no header, JWT or origin flag "
+    "(SPEC-mcp-operator §2.3).",
+)
 @click.option(
     "--principal-header",
     default=None,
@@ -1963,6 +1971,7 @@ def _delegation_dict(delegation: Delegation) -> dict[str, Any]:
 def mcp_operator(
     listen: str,
     path: str,
+    stdio: bool,
     principal_header: str | None,
     user_header: str | None,
     environment: str | None,
@@ -1987,11 +1996,13 @@ def mcp_operator(
     identity_jwt_http_timeout: float,
     store_url: str | None,
 ) -> None:
-    """Answer approvals from an MCP client, over loopback (SPEC-mcp-operator.md).
+    """Answer approvals from an MCP client, over loopback or stdio (SPEC-mcp-operator.md).
 
     There is no --principal and no --allow-remote, and both absences are load-bearing: a
     static principal cannot attribute an answer to a person (§3.1), and a server whose read
-    tools answer without a credential must not be the one that opens a port (§2.1).
+    tools answer without a credential must not be the one that opens a port (§2.1). --stdio
+    opens none at all, and its approver is the one name the launching client cannot set: the
+    OS login of the process (§2.3).
     """
     host, _, port = listen.rpartition(":")
     try:
@@ -2005,6 +2016,7 @@ def mcp_operator(
             host=host or "127.0.0.1",
             port=int(port),
             path=path,
+            stdio=stdio,
             principal_header=principal_header,
             user_header=user_header,
             environment=environment,

src/ctrlrun/gateway/__init__.py

@@ -283,39 +283,70 @@ def _announce_operator(control: Any, config: Any, identity: Any, store: Any) ->
     `print` rather than the logger, because this is the CLI's own output and a logger with no
     configured handler would swallow it — which is the failure mode the block exists to
     prevent, in miniature.
+
+    **Over stdio the whole block goes to stderr** (§2.3). Stdout is the protocol stream there,
+    the client parses every line of it as JSON-RPC, and a startup block on it is read as a
+    broken message rather than as information: the first stdio client this was tried behind
+    logged "ignoring non-JSON output" for every line of it.
     """
-    print(
-        f"ctrlrun mcp-operator — listening on {config.host}:{config.port}{config.path}",
-        flush=True,
-    )
-    print(f"environment  {control.environment}", flush=True)
+    out = sys.stderr if config.stdio else sys.stdout
+
+    def line(text: str) -> None:
+        print(text, file=out, flush=True)
+
+    if config.stdio:
+        line("ctrlrun mcp-operator — stdio; no socket, one client, the one that launched this")
+    else:
+        line(f"ctrlrun mcp-operator — listening on {config.host}:{config.port}{config.path}")
+    line(f"environment  {control.environment}")
     # SPEC-mcp-operator §6 — for a server whose whole premise is "both processes on one host
     # against one store", and which has a `--store-url` that silently changes it, this is the
     # line an operator most needs. A review found the block printing everything but this.
-    print(f"store        {getattr(store, 'path', store)}", flush=True)
-    print(f"identity     {type(identity).__name__}", flush=True)
+    line(f"store        {getattr(store, 'path', store)}")
+    line(f"identity     {type(identity).__name__}")
     if config.principal_header is not None:
-        print(
+        line(
             f"             trusts the header {config.principal_header!r}: it is worth what "
             "the proxy that sets it is worth,"
         )
-        print(
+        line(
             "             and that proxy must authenticate the caller and overwrite the "
             "header on every request (SPEC-v0.3 §3.3)"
         )
-    print(
+    if config.stdio:
+        line(
+            f"             the account this process runs as, {identity.login!r}, read from the "
+            "real uid and from nothing the client"
+        )
+        line(
+            "             sends or sets. It carries no roles and no expiry, so this process "
+            "holds approve, deny and resolve under"
+        )
+        line(
+            "             that name for as long as it runs; the confirmation the client shows "
+            "before a write is the only human step"
+        )
+        if identity.is_root:
+            line(
+                "             RUNNING AS ROOT: an account, not a person. Every write is "
+                "refused (-41013); reads still answer"
+            )
+    line(
         "read tools   answer without a credential; loopback is not a boundary against "
         "other processes on this host"
     )
-    print(
-        "write tools  approve, deny, resolve — each needs a credential naming a human, "
-        "and each answer is recorded under that name"
-    )
-    if control.authority is not None:
-        print(
-            f"authority    {len(control.authority.grants)} grant(s), evaluated by the agent",
-            flush=True,
+    if config.stdio:
+        line(
+            "write tools  approve, deny, resolve — each answer is recorded under "
+            f"{identity.login!r}"
         )
+    else:
+        line(
+            "write tools  approve, deny, resolve — each needs a credential naming a human, "
+            "and each answer is recorded under that name"
+        )
+    if control.authority is not None:
+        line(f"authority    {len(control.authority.grants)} grant(s), evaluated by the agent")
 
 
 def _observe_the_upstream(control: Any, config: Any) -> None:

src/ctrlrun/gateway/mcp.py

@@ -285,10 +285,18 @@ def _decoded(value: str) -> str | None:
 
 
 def encode_header_value(value: str) -> str:
-    """Wrap a value in the revision's base64 sentinel where it is not ASCII-safe (§6.4)."""
+    """Wrap a value in the revision's base64 sentinel where it is not ASCII-safe (§6.4).
+
+    A value that is ASCII but *looks like* the sentinel is wrapped too, or `_decoded` on the far
+    side would try to decode the bare value and refuse a header that faithfully mirrored the
+    body. A review found the gap when the operator's stdio loop started mirroring tool names.
+    """
     try:
         value.encode("ascii")
+        wrap = value.startswith(_SENTINEL_OPEN) and value.endswith(_SENTINEL_CLOSE)
     except UnicodeEncodeError:
+        wrap = True
+    if wrap:
         encoded = base64.b64encode(value.encode("utf-8")).decode("ascii")
         return f"{_SENTINEL_OPEN}{encoded}{_SENTINEL_CLOSE}"
     return value