xmemcli 0.0.11__tar.gz → 0.0.13__tar.gz

{xmemcli-0.0.11 → xmemcli-0.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xmemcli
-Version: 0.0.11
+Version: 0.0.13
 Summary: Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools.
 Keywords: api,cli,llm,memory,xmemory
 Requires-Python: <4,>=3.12
@@ -97,7 +97,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.11**.
+Version: **0.0.13**.
 
 
 ---
@@ -151,7 +151,7 @@ AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never hand
 4. With the session, the CLI runs the Console onboarding's core sequence: `GET /api/check-user`; when the address has no account, `GET /api/suggest-slug` (server-derived org name, `--org-name` overrides; ignored for an existing account) and `POST /api/public-signup` — **note that creating a new organisation requires the deployment to allow public registration, which the hosted service currently does not**: an existing account gets a key, a new address gets the server's "organisation creation is not available" refusal (the Console's admin-fallback signup arm is not implemented here); then `GET /api/accounts/users/by-email`, `GET /api/accounts/api-roles` (the seeded default role, or the org's only role — an ambiguous set is refused, never guessed), and `POST /api/accounts/api-keys` with **no cluster list** — the key attaches to every cluster the org has at mint time. Clusters created later are attached by a server-side backfill that repairs only keys already linked to every other cluster in the org; an org with no clusters at mint time gets a key attached to nothing. The key is named **`CLI email login (<hostname>, <timestamp>)`** so every mint stays individually identifiable and revocable on the Console's API Keys page.
 5. The key is written to `.xmemrc.json` (0600), stdout carries the prefix only, and the session cookie dies with the process.
 
-The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI refuses to guess the Console (pass `--console-url` or set `$XMEM_CONSOLE_URL`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
+The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url` or set `$XMEM_CONSOLE_URL`). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
 
 When the server offers no matching code on the request reply (cross-device hand-off disabled, no public Console origin configured, or a transient degradation), there is nothing for a headless starter to claim — the emailed link then signs in the *approving* browser — so the CLI falls back to the emailed **six-digit code typed into the terminal** (`POST /api/kingdom-signin-verify`), still a single human action. That fallback needs an interactive stdin; a non-interactive run cancels the attempt it just started (the mode is only known from the server's reply, after the email is on its way) and refuses with instructions — the typed code dies with that cancel, but on such a server the one-click link has nothing durable to revoke and stays redeemable in a browser until it expires (about five minutes), which the terminal states plainly.
 
@@ -161,7 +161,9 @@ A credential that already resolves (via `/whoami`) to the requested address at t
 
 Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking up from `--rc-dir` / CWD, ceiling `$HOME`.
 
-Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin.
+Those three keys are required and must be strings. Anything else in the file is **ignored, not rejected** (since 0.0.12): the rc is the only durable credential store, so a file this CLI cannot load is a CLI that cannot run any command at all — which would make adding a field to the file a breaking change far wider than the feature that added it.
+
+Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of a single-origin API base → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
 
 ## Identity — `/whoami`
 
@@ -191,7 +193,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.11` (see `xmemcli version`)
+**Version:** `0.0.13` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
@@ -513,7 +515,13 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, …)
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 
-See also [`ACCOUNTS_AUTH.md`](../ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
+**Compatibility change in 0.0.12:** an `.xmemrc.json` carrying a key this release does not recognise is now **accepted**, and the unknown key ignored; `email`, `api_url`, and `api_key` are still required and still have to be strings. Until 0.0.12 the key set was closed, which made adding a field to the file a breaking change for **every** command rather than for the one that would read it — a CLI that cannot load the rc cannot resolve a credential for anything. Nothing writes an extra key yet; this release exists so that a later one can.
+
+**Compatibility change in 0.0.13 (single-origin deployments):** an API base URL's path is now **preserved**, never stripped — `--api-url https://host/xmem` builds requests under `/xmem` instead of reducing to the bare origin. Where the base's path is exactly `/xmem`, the CLI infers its single-origin siblings on the same host: `auth login` finds the Console at `/console` without `--console-url`, and `xmemcli mcp` reaches `/mcp` without `--mcp-url` (explicit flags and `$XMEM_CONSOLE_URL` / `$XMEM_MCP_URL` still win, and the MCP origin guard accepts the `/xmem` ↔ `/mcp` pair as one deployment). Bare origins and every other path shape behave exactly as before. See `cli/`.
+
+Two consequences worth knowing. A single-origin deployment's own setup instructions rely on this inference — they render `auth login --api-url https://host/xmem` with **no** `--console-url` — so **0.0.13 is the minimum on such a deployment**; an older CLI given that command signs in at the hosted Console instead. And the inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
+
+See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 
 ---
 
@@ -602,6 +610,8 @@ These apply **before** any subcommand (`xmemcli help options`).
 
 **Credential resolution:** `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` → *Not logged in — run `xmemcli auth login` first.*
 
+**`.xmemrc.json` shape:** `{email, api_url, api_key}`, all three required and all three strings. Keys beyond those are ignored rather than rejected (see the 0.0.12 note above), so a file written by a newer CLI still loads here.
+
 **`context` is the one exception, and it is a security boundary.** Every other command walks up
 from the current directory for the nearest `.xmemrc.json`, which is deliberate: a person chose
 that directory and ran the command in it. `context` has neither — a session-start hook runs it

{xmemcli-0.0.11 → xmemcli-0.0.13}/README.md

@@ -89,7 +89,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.11**.
+Version: **0.0.13**.
 
 
 ---
@@ -143,7 +143,7 @@ AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never hand
 4. With the session, the CLI runs the Console onboarding's core sequence: `GET /api/check-user`; when the address has no account, `GET /api/suggest-slug` (server-derived org name, `--org-name` overrides; ignored for an existing account) and `POST /api/public-signup` — **note that creating a new organisation requires the deployment to allow public registration, which the hosted service currently does not**: an existing account gets a key, a new address gets the server's "organisation creation is not available" refusal (the Console's admin-fallback signup arm is not implemented here); then `GET /api/accounts/users/by-email`, `GET /api/accounts/api-roles` (the seeded default role, or the org's only role — an ambiguous set is refused, never guessed), and `POST /api/accounts/api-keys` with **no cluster list** — the key attaches to every cluster the org has at mint time. Clusters created later are attached by a server-side backfill that repairs only keys already linked to every other cluster in the org; an org with no clusters at mint time gets a key attached to nothing. The key is named **`CLI email login (<hostname>, <timestamp>)`** so every mint stays individually identifiable and revocable on the Console's API Keys page.
 5. The key is written to `.xmemrc.json` (0600), stdout carries the prefix only, and the session cookie dies with the process.
 
-The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI refuses to guess the Console (pass `--console-url` or set `$XMEM_CONSOLE_URL`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
+The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url` or set `$XMEM_CONSOLE_URL`). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
 
 When the server offers no matching code on the request reply (cross-device hand-off disabled, no public Console origin configured, or a transient degradation), there is nothing for a headless starter to claim — the emailed link then signs in the *approving* browser — so the CLI falls back to the emailed **six-digit code typed into the terminal** (`POST /api/kingdom-signin-verify`), still a single human action. That fallback needs an interactive stdin; a non-interactive run cancels the attempt it just started (the mode is only known from the server's reply, after the email is on its way) and refuses with instructions — the typed code dies with that cancel, but on such a server the one-click link has nothing durable to revoke and stays redeemable in a browser until it expires (about five minutes), which the terminal states plainly.
 
@@ -153,7 +153,9 @@ A credential that already resolves (via `/whoami`) to the requested address at t
 
 Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking up from `--rc-dir` / CWD, ceiling `$HOME`.
 
-Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin.
+Those three keys are required and must be strings. Anything else in the file is **ignored, not rejected** (since 0.0.12): the rc is the only durable credential store, so a file this CLI cannot load is a CLI that cannot run any command at all — which would make adding a field to the file a breaking change far wider than the feature that added it.
+
+Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of a single-origin API base → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
 
 ## Identity — `/whoami`
 
@@ -183,7 +185,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.11` (see `xmemcli version`)
+**Version:** `0.0.13` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
@@ -505,7 +507,13 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, …)
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 
-See also [`ACCOUNTS_AUTH.md`](../ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
+**Compatibility change in 0.0.12:** an `.xmemrc.json` carrying a key this release does not recognise is now **accepted**, and the unknown key ignored; `email`, `api_url`, and `api_key` are still required and still have to be strings. Until 0.0.12 the key set was closed, which made adding a field to the file a breaking change for **every** command rather than for the one that would read it — a CLI that cannot load the rc cannot resolve a credential for anything. Nothing writes an extra key yet; this release exists so that a later one can.
+
+**Compatibility change in 0.0.13 (single-origin deployments):** an API base URL's path is now **preserved**, never stripped — `--api-url https://host/xmem` builds requests under `/xmem` instead of reducing to the bare origin. Where the base's path is exactly `/xmem`, the CLI infers its single-origin siblings on the same host: `auth login` finds the Console at `/console` without `--console-url`, and `xmemcli mcp` reaches `/mcp` without `--mcp-url` (explicit flags and `$XMEM_CONSOLE_URL` / `$XMEM_MCP_URL` still win, and the MCP origin guard accepts the `/xmem` ↔ `/mcp` pair as one deployment). Bare origins and every other path shape behave exactly as before. See `cli/`.
+
+Two consequences worth knowing. A single-origin deployment's own setup instructions rely on this inference — they render `auth login --api-url https://host/xmem` with **no** `--console-url` — so **0.0.13 is the minimum on such a deployment**; an older CLI given that command signs in at the hosted Console instead. And the inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
+
+See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 
 ---
 
@@ -594,6 +602,8 @@ These apply **before** any subcommand (`xmemcli help options`).
 
 **Credential resolution:** `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` → *Not logged in — run `xmemcli auth login` first.*
 
+**`.xmemrc.json` shape:** `{email, api_url, api_key}`, all three required and all three strings. Keys beyond those are ignored rather than rejected (see the 0.0.12 note above), so a file written by a newer CLI still loads here.
+
 **`context` is the one exception, and it is a security boundary.** Every other command walks up
 from the current directory for the nearest `.xmemrc.json`, which is deliberate: a person chose
 that directory and ran the command in it. `context` has neither — a session-start hook runs it

{xmemcli-0.0.11 → xmemcli-0.0.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "0.0.11"
+version = "0.0.13"
 description = "Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools."
 readme = "README.md"
 requires-python = ">=3.12,<4"

{xmemcli-0.0.11 → xmemcli-0.0.13}/uv.lock

@@ -4,5 +4,5 @@ requires-python = ">=3.12, <4"
 
 [[package]]
 name = "xmemcli"
-version = "0.0.11"
+version = "0.0.13"
 source = { editable = "." }

{xmemcli-0.0.11 → xmemcli-0.0.13}/xmemcli/__init__.py

@@ -1,3 +1,3 @@
 """Standalone xmemcli package (``xmemcli`` console script)."""
 
-__version__ = "0.0.11"
+__version__ = "0.0.13"

{xmemcli-0.0.11 → xmemcli-0.0.13}/xmemcli/_login.py

@@ -77,6 +77,13 @@ CLI_LOGIN_PATH = "/xmemcli"
 CLI_TOKEN_PROXY_PATH = "/api/cli/token"
 CLI_WHOAMI_PROXY_PATH = "/api/cli/whoami"
 
+#: Mount paths of a single-origin deployment, where one hostname serves every surface under
+#: fixed path prefixes. An API base ending in ``/xmem`` therefore names its Console and MCP
+#: siblings by construction — the grammar ``single_origin_sibling_url`` implements.
+SINGLE_ORIGIN_API_PATH = "/xmem"
+SINGLE_ORIGIN_CONSOLE_PATH = "/console"
+SINGLE_ORIGIN_MCP_PATH = "/mcp"
+
 API_KEY_PREFIX = "xmem_"
 
 #: Hostnames treated as loopback wherever the CLI relaxes an https-only rule or infers the
@@ -130,8 +137,43 @@ def challenge_for(verifier: str) -> str:
     return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
 
 
+def single_origin_sibling_url(api_url: str, *, sibling_path: str) -> str | None:
+    """``https://host/xmem`` → ``https://host<sibling_path>``, or None when the shape says nothing.
+
+    Exact on purpose: only an API base whose path is exactly ``/xmem`` sits on a single-origin
+    deployment, where the siblings are fixed by the routing grammar. A bare origin (a five-host
+    deployment) infers nothing, and extra path segments, query, fragment, or credentials make it
+    someone else's URL. Hostname surgery (``api.stg`` → ``mcp.stg``) is deliberately not done
+    here — deriving one *hostname* from another is what the pairing table in ``_mcp_bridge``
+    exists to avoid guessing.
+    """
+    try:
+        parsed = urlsplit(api_url.strip())
+        _ = parsed.port  # the port is parsed lazily; force it — a malformed URL must refuse, not raise
+    except ValueError:
+        # `urlsplit` itself raises on an unbracketed-IPv6 shape, and this helper sees origins
+        # read from an rc file the user may have edited by hand (see `_host_of` in _mcp_bridge).
+        return None
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        return None
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        return None
+    if parsed.path.rstrip("/") != SINGLE_ORIGIN_API_PATH:
+        return None
+    return f"{parsed.scheme}://{parsed.netloc}{sibling_path}"
+
+
 def console_url_from_api_url(api_url: str) -> str | None:
-    """Local dev convention: API on :8000, Console on :8002 (same host)."""
+    """Infer the Console base from an API base, where the deployment layout determines it.
+
+    Two shapes qualify: a single-origin ``/xmem`` base names its ``/console`` sibling on the
+    same host, and the local dev convention pairs API :8000 with Console :8002 on the same
+    loopback host. A bare non-loopback origin infers nothing — five-host deployments name
+    their Console explicitly.
+    """
+    sibling = single_origin_sibling_url(api_url, sibling_path=SINGLE_ORIGIN_CONSOLE_PATH)
+    if sibling is not None:
+        return sibling
     parsed = urlparse(api_url.rstrip("/"))
     if parsed.hostname not in LOOPBACK_HOSTS:
         return None
@@ -147,18 +189,25 @@ def console_url_from_api_url(api_url: str) -> str | None:
     return None
 
 
-def console_url_for_api(*, console_url: str | None = None) -> str:
-    """Resolve the Console origin for PKCE login and token/whoami proxies."""
+def console_url_for_api(*, console_url: str | None = None, api_url: str | None = None) -> str:
+    """Resolve the Console origin for PKCE login and token/whoami proxies.
+
+    Explicit wins (flag, then ``$XMEM_CONSOLE_URL``); then inference from the API base the
+    caller is actually signing in against, then from ``$XMEM_API_URL``; then the default.
+    ``api_url`` outranks the environment because it is the resolved target of this very call
+    — an exported ``$XMEM_API_URL`` must not steer the Console away from an explicit
+    ``--api-url``.
+    """
     if console_url:
         return console_url.rstrip("/")
     from_env = os.environ.get(_ENV_CONSOLE_URL, "").strip()
     if from_env:
         return from_env.rstrip("/")
-    api_from_env = os.environ.get(_ENV_API_URL, "").strip()
-    if api_from_env:
-        inferred = console_url_from_api_url(api_from_env)
-        if inferred:
-            return inferred
+    for candidate in (api_url, os.environ.get(_ENV_API_URL, "").strip()):
+        if candidate:
+            inferred = console_url_from_api_url(candidate)
+            if inferred:
+                return inferred
     return DEFAULT_CONSOLE_URL
 
 
@@ -226,22 +275,35 @@ def write_login_handoff_prompt(
     out.flush()
 
 
+def _api_candidates(api_url: str, *, path: str, legacy_path: str) -> list[str]:
+    """The API's own route for something, plus the ``/api``-prefixed spelling where it can exist.
+
+    The second candidate is compatibility only: it answers a deployment served at the origin
+    root, which replies under ``/api`` as well. A base that carries a mount cannot serve it —
+    on a single-origin deployment the API is at ``https://host/xmem`` and
+    ``https://host/xmem/api/whoami`` is a path no layout produces — so it is left out there
+    rather than spending a request, and a 404, on a URL known in advance to be wrong.
+    """
+    base = api_url.rstrip("/")
+    if urlsplit(base).path:
+        return [f"{base}{path}"]
+    return [f"{base}{path}", f"{base}{legacy_path}"]
+
+
 def token_redeem_urls(*, api_url: str, console_url: str | None) -> list[str]:
     """Candidate ``POST /cli/token`` URLs, most likely first."""
-    console = console_url_for_api(console_url=console_url)
     if console_url or os.environ.get(_ENV_CONSOLE_URL, "").strip():
+        console = console_url_for_api(console_url=console_url)
         return [f"{console.rstrip('/')}{CLI_TOKEN_PROXY_PATH}"]
-    base = api_url.rstrip("/")
-    return [f"{base}/cli/token", f"{base}/api/cli/token"]
+    return _api_candidates(api_url, path="/cli/token", legacy_path="/api/cli/token")
 
 
 def whoami_urls(*, api_url: str, console_url: str | None) -> list[str]:
     """Candidate ``GET /whoami`` URLs for bearer API-key lookup, most likely first."""
-    console = console_url_for_api(console_url=console_url)
     if console_url or os.environ.get(_ENV_CONSOLE_URL, "").strip():
+        console = console_url_for_api(console_url=console_url)
         return [f"{console.rstrip('/')}{CLI_WHOAMI_PROXY_PATH}"]
-    base = api_url.rstrip("/")
-    return [f"{base}/whoami", f"{base}/api/whoami"]
+    return _api_candidates(api_url, path="/whoami", legacy_path="/api/whoami")
 
 
 def origin_of(url: str) -> tuple[str, str, int]:
@@ -516,6 +578,7 @@ def wait_for_callback(
     callback_port: int = EPHEMERAL_CALLBACK_PORT,
     stop: threading.Event | None = None,
     console_url: str | None = None,
+    api_url: str | None = None,
 ) -> dict[str, str]:
     """Listen for the browser's local callback carrying the signed code.
 
@@ -548,7 +611,7 @@ def wait_for_callback(
     bound_port = server.server_address[1]
     server.timeout = 0.5
     try:
-        server.console_origin = serialized_origin(console_url_for_api(console_url=console_url))
+        server.console_origin = serialized_origin(console_url_for_api(console_url=console_url, api_url=api_url))
         on_url(build_url(redirect_uri_for_port(bound_port)))
         deadline = time.monotonic() + timeout_s
         while server.captured is None and not (stop and stop.is_set()):
@@ -798,6 +861,7 @@ def wait_for_handoff(
                 callback_port=callback_port,
                 stop=stop,
                 console_url=console_url,
+                api_url=api_url,
             )
             code = params.get("code")
             if not code:
@@ -895,7 +959,7 @@ def run_pkce_login(
     notify: Callable[[str], None] | None = None,
 ) -> HandoffResult:
     """Open the Console login page and wait for loopback callback and/or hidden stdin paste."""
-    console = console_url_for_api(console_url=console_url)
+    console = console_url_for_api(console_url=console_url, api_url=api_url)
     challenge = challenge_for(verifier)
     return wait_for_handoff(
         api_url,

{xmemcli-0.0.11 → xmemcli-0.0.13}/xmemcli/_mcp_bridge.py

@@ -35,6 +35,7 @@ import urllib.error
 import urllib.request
 from typing import IO, Any, override
 
+from . import _login
 from ._xmem_bridge import xmem_module
 
 #: JSON-RPC's reserved range ends at -32000; everything at or below it is free for an
@@ -534,6 +535,27 @@ def _unusable_origin(origin: str) -> str | None:
     return None
 
 
+def _is_single_origin_pair(api_origin: str, mcp_origin: str, m: Any) -> bool:
+    """One host serving the API at ``/xmem`` and MCP at ``/mcp`` — one deployment.
+
+    On such a deployment the mounts are path siblings of the same origin, so a key bound to
+    the ``/xmem`` base stays home when sent to the ``/mcp`` sibling. Path-aware on purpose:
+    the canonical forms used by the table strip paths and cannot tell ``/mcp`` from any
+    other path on that host, so the MCP side's path is pinned here before origins are
+    compared.
+    """
+    expected = _login.single_origin_sibling_url(api_origin, sibling_path=_login.SINGLE_ORIGIN_MCP_PATH)
+    if expected is None:
+        return False
+    try:
+        parsed = urllib.parse.urlsplit(mcp_origin.strip())
+    except ValueError:
+        return False
+    if parsed.path.rstrip("/") != _login.SINGLE_ORIGIN_MCP_PATH or parsed.query or parsed.fragment:
+        return False
+    return _canonical_origin(expected, m) == _canonical_origin(mcp_origin, m)
+
+
 def _refuse_foreign_origin(api_origin: str | None, mcp_origin: str, m: Any) -> str | None:
     """Why this credential may not be sent to this MCP origin, or ``None``.
 
@@ -554,6 +576,8 @@ def _refuse_foreign_origin(api_origin: str | None, mcp_origin: str, m: Any) -> s
     mcp = _canonical_origin(mcp_origin, m)
     if _deployments(m).get(api) == mcp:
         return None
+    if _is_single_origin_pair(api_origin, mcp_origin, m):
+        return None
     # The originals, not the canonical forms: normalising rebuilds an origin as
     # `scheme://host:port`, which for IPv6 drops the brackets that made the address
     # parseable — so `http://[::1]:8000` canonicalises to something no URL parser can
@@ -609,11 +633,19 @@ def cmd_mcp(args: argparse.Namespace) -> int:
         )
         _eprint(unavailable)
 
+    # Resolved once, with the API base as inference context: on a single-origin
+    # deployment (an rc minted against `https://host/xmem`, or that base named on the
+    # call) the MCP endpoint is the `/mcp` sibling of the same host, and no flag or
+    # variable should be needed to say so. `_explicit_api_url` is the rc-free reading
+    # on purpose — a malformed rc already produced `unavailable` above and must not
+    # take this resolution down with it.
+    mcp_origin = m._mcp_url(args, api_url=api_origin or m._explicit_api_url(args))
+
     # Is it a URL at all — asked first, and for every caller. The guard below is skipped
     # when the operator names the key, and that used to skip the only look this origin
     # ever got, so a malformed one reached `urllib` and raised out of the loop.
     if unavailable is None:
-        unavailable = _unusable_origin(m._mcp_url(args))
+        unavailable = _unusable_origin(mcp_origin)
         if unavailable is not None:
             _eprint(unavailable)
 
@@ -624,11 +656,11 @@ def cmd_mcp(args: argparse.Namespace) -> int:
     # anywhere else needs a credential the operator named on the call. `api_origin` comes
     # from the same read as `api_key`, so the two always describe one file.
     if api_key is not None and unavailable is None:
-        unavailable = _refuse_foreign_origin(api_origin, m._mcp_url(args), m)
+        unavailable = _refuse_foreign_origin(api_origin, mcp_origin, m)
         if unavailable is not None:
             _eprint(unavailable)
 
-    url = f"{m._mcp_url(args).rstrip('/')}/instance/{instance_id}"
+    url = f"{mcp_origin.rstrip('/')}/instance/{instance_id}"
     return _pump(*_utf8_stdio(), url, api_key, unavailable)
 
 

{xmemcli-0.0.11 → xmemcli-0.0.13}/xmemcli/_output.py

@@ -84,9 +84,12 @@ class OutputKind(StrEnum):
     #: payload: ``write_id``; the caller must poll.
     WRITE_ASYNC = "write_async"
 
-    #: Terminal result of an ``async_write_status`` poll. Curated payload:
-    #: ``write_id`` + ``write_status`` in {``completed``, ``failed``,
-    #: ``not_found``} (+ ``error_detail`` / ``timed_out`` when applicable).
+    #: Result of an ``async_write_status`` poll. Curated payload: ``write_id`` + ``write_status``
+    #: — any ``WriteQueueStatus`` value, not only the terminal ones, plus the CLI's own
+    #: ``"error"`` / ``"unknown"`` fallbacks — whichever of ``submitted_at`` / ``started_at`` /
+    #: ``completed_at`` is set, ``restart_count`` once non-zero (``--verbose`` keeps a zero count and
+    #: drops only the null an unknown ``write_id`` reports), and ``error_detail`` / ``error``
+    #: / ``http_status`` / ``timed_out`` when applicable.
     WRITE_STATUS = "write_status"
 
     #: Read in ``mode=single-answer``. Curated payload: ``answer`` (falls

{xmemcli-0.0.11 → xmemcli-0.0.13}/xmemcli/_pretty.py

@@ -78,7 +78,7 @@ def _render_write_async(payload: Any, stream: IO[str]) -> None:
 
 
 def _render_write_status(payload: Any, stream: IO[str]) -> None:
-    """Terminal poll result — short status line, no body."""
+    """Poll result — short status line, no body; the timing fields stay JSON-only."""
     if not isinstance(payload, dict):
         _default_handler(payload, stream)
         return

{xmemcli-0.0.11 → xmemcli-0.0.13}/xmemcli/_rc.py

@@ -5,9 +5,11 @@ The CLI resolves its API key and API origin from a **project-local**
 (or the current directory). The search does **not** stop at the repository root
 and is **ceilinged at ``$HOME``** — ``~/.xmemrc.json`` is the last fallback.
 
-The file is stdlib JSON, strongly typed ``{email, api_url, api_key}`` (one
-identity per file; extras / missing / non-string keys are rejected). The ``0600``
-atomic writer is used by ``xmem auth login``; see ``cli/AUTH-FLOW.md``.
+The file is stdlib JSON, one identity per file: ``{email, api_url, api_key}``.
+Those three are required and must be strings; a key this release does not know is
+ignored rather than rejected, so a later release can record something new in the
+file without every older CLI refusing to run. The ``0600`` atomic writer is used
+by ``xmem auth login``; see ``cli/AUTH-FLOW.md``.
 
 Resolution precedence (applied by ``cli/xmem.py``): ``--api-key`` → ``$XMEM_API_KEY`` → ``.xmemrc.json``; and
 ``--api-url`` → ``$XMEM_API_URL`` → the rc's ``api_url`` → the built-in default — **with one escape hatch**: when the
@@ -26,9 +28,10 @@ from typing import NamedTuple
 RC_FILENAME = ".xmemrc.json"
 ENV_RC_DIR = "XMEM_RC_DIR"
 
-# The exact, complete set of keys an `.xmemrc.json` must contain — no more, no
-# fewer. Keeping it closed means a typo'd or extended file fails loudly instead
-# of silently ignoring a field.
+# The keys an `.xmemrc.json` must contain. Required, not exhaustive: anything else in the file is ignored.
+# The set was closed until 0.0.12, on the grounds that a typo'd or extended file should fail loudly.
+# It made adding a field a breaking change for every command rather than for the one that would read it,
+# because a CLI that cannot load the rc cannot resolve a credential for anything.
 _RC_KEYS = ("email", "api_url", "api_key")
 
 
@@ -90,27 +93,22 @@ def find_rc(start_dir: Path) -> Path | None:
 
 
 def load_rc(path: Path) -> RcRecord:
-    """Parse and validate an ``.xmemrc.json``; raise ``RcError`` if malformed."""
+    """Parse and validate an ``.xmemrc.json``; raise ``RcError`` if malformed.
+
+    "Required keys present", not "exactly these keys": an unrecognised key is ignored
+    whatever its type. Type-checking a field nothing here reads is how a later release's
+    richer value becomes this release's hard failure — having no opinion about it is the
+    whole point of ignoring it.
+    """
     try:
         raw = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError) as exc:
         raise RcError(f"{path}: could not read JSON ({exc})") from exc
     if not isinstance(raw, dict):
         raise RcError(f"{path}: expected a JSON object, got {type(raw).__name__}")
-    keys = set(raw.keys())
-    expected = set(_RC_KEYS)
-    if keys != expected:
-        missing = sorted(expected - keys)
-        extra = sorted(keys - expected)
-        detail = ", ".join(
-            part
-            for part in (
-                f"missing {missing}" if missing else "",
-                f"unexpected {extra}" if extra else "",
-            )
-            if part
-        )
-        raise RcError(f"{path}: must contain exactly {list(_RC_KEYS)} ({detail})")
+    missing = sorted(set(_RC_KEYS) - set(raw.keys()))
+    if missing:
+        raise RcError(f"{path}: must contain {list(_RC_KEYS)} (missing {missing})")
     for key in _RC_KEYS:
         if not isinstance(raw[key], str):
             raise RcError(f"{path}: '{key}' must be a string")

{xmemcli-0.0.11 → xmemcli-0.0.13}/xmemcli/_version.py

@@ -1,4 +1,4 @@
 """Release metadata for the xmemcli CLI (copied into standalone builds)."""
 
 CLI_NAME = "xmemcli"
-__version__ = "0.0.11"
+__version__ = "0.0.13"

{xmemcli-0.0.11 → xmemcli-0.0.13}/xmemcli/cli.py

@@ -30,13 +30,16 @@ Curated output
 The CLI does NOT echo the raw API payload. Every subcommand reduces the
 server response to the fields the user actually asked for (see the
 ``_curate_*`` helpers): a read returns the answer / rows, a write returns
-its ``write_id``, a status poll returns ``write_id`` + ``write_status``.
+its ``write_id``, a status poll returns ``write_id`` + ``write_status``
+plus whichever timing fields the server set (and the restart count once
+it is non-zero).
 Server internals — ``sql``, ``diff_plan``, the raw ``cleaned_objects``
 tree — are never emitted, in either output mode. ``pending_suggestions``
 (a count of schema-evolution proposals waiting for review) is kept on
 read responses so agents know when to run ``schema suggestions review``.
 ``--verbose`` adds *extra* (still non-internal) context: ``trace_id`` and
-``console_url``, when the server provided them.
+``console_url``, when the server provided them, and keeps a zero
+``restart_count`` a status poll would otherwise curate away.
 
 Sync vs async writes
 --------------------
@@ -749,10 +752,26 @@ def _curate_write_status(item: dict[str, Any], verbose: bool) -> dict[str, Any]:
         "write_status": item.get("write_status", "unknown"),
     }
     # Carry the failure / bookkeeping fields only when they say something.
-    for key in ("error_detail", "completed_at", "error", "http_status", "timed_out"):
+    for key in (
+        "error_detail",
+        "submitted_at",
+        "started_at",
+        "completed_at",
+        "error",
+        "http_status",
+        "timed_out",
+    ):
         value = item.get(key)
         if value is not None:
             curated[key] = value
+    # Never-restarted is the norm, so a zero count is noise on the default output; show it there only when
+    # the write was restarted. Under --verbose the 0 is kept and only the null is dropped: the server sends
+    # null exactly for an unknown write_id, and printing that as 0 would let a caller aggregating polls count
+    # a row that does not exist as a write that ran clean.
+    restart_count = item.get("restart_count")
+    show_restart_count = restart_count is not None if verbose else bool(restart_count)
+    if show_restart_count:
+        curated["restart_count"] = restart_count
     return _add_verbose_extras(curated, item, verbose)
 
 
@@ -863,6 +882,21 @@ def _normalize_api_origin(url: str) -> str | None:
     return f"{scheme}://{host}:{port}"
 
 
+def _normalize_api_base_url(url: str) -> str | None:
+    """Canonical *request* base: the normalized origin plus the URL's own path, sans trailing slash.
+
+    ``_normalize_api_origin`` exists for origin comparison and deliberately drops the path;
+    this form exists for building requests, where a single-origin deployment's ``/xmem``
+    mount is load-bearing — stripping it would aim every call at the Console's root instead
+    of the API. Query and fragment are still dropped: a base URL carries neither.
+    """
+    origin = _normalize_api_origin(url)
+    if origin is None:
+        return None
+    path = urlsplit(url.strip()).path.rstrip("/")
+    return f"{origin}{path}" if path else origin
+
+
 def _origins_match(a: str, b: str) -> bool:
     norm_a = _normalize_api_origin(a)
     norm_b = _normalize_api_origin(b)
@@ -936,7 +970,7 @@ def _api_url(args: argparse.Namespace) -> str:
     # explicit --api-key / $XMEM_API_KEY skips rc api_url (see AUTH-FLOW.md).
     explicit_url = args.api_url or os.environ.get(ENV_API_URL)
     if explicit_url:
-        return _normalize_api_origin(explicit_url) or explicit_url.rstrip("/")
+        return _normalize_api_base_url(explicit_url) or explicit_url.rstrip("/")
     # No explicit origin. The rc supplies the default origin ONLY when the rc is also the
     # credential source — i.e. when no explicit key was given. With an explicit --api-key /
     # $XMEM_API_KEY the rc is irrelevant (its api_url binds only the rc's own key), and a
@@ -944,23 +978,36 @@ def _api_url(args: argparse.Namespace) -> str:
     # default WITHOUT reading the rc. This mirrors the same explicit-key escape hatch in
     # _require(), so `--api-key` + a broken rc + no --api-url resolves cleanly end to end.
     if args.api_key or os.environ.get(ENV_API_KEY):
-        return _normalize_api_origin(DEFAULT_API_URL) or DEFAULT_API_URL.rstrip("/")
+        return _normalize_api_base_url(DEFAULT_API_URL) or DEFAULT_API_URL.rstrip("/")
     rc = _rc_record(args)
     fallback = (rc.api_url if rc else None) or DEFAULT_API_URL
-    return _normalize_api_origin(fallback) or fallback.rstrip("/")
+    return _normalize_api_base_url(fallback) or fallback.rstrip("/")
 
 
 def _explicit_api_url(args: argparse.Namespace) -> str | None:
-    """Origin from flags/env only — never from ``.xmemrc.json``."""
+    """API base from flags/env only — never from ``.xmemrc.json``."""
     explicit = args.api_url or os.environ.get(ENV_API_URL)
     if not explicit:
         return None
-    return _normalize_api_origin(explicit) or explicit.rstrip("/")
+    return _normalize_api_base_url(explicit) or explicit.rstrip("/")
+
 
+def _mcp_url(args: argparse.Namespace, *, api_url: str | None = None) -> str:
+    """The MCP base: flag, then environment, then the API base's single-origin sibling, then the default.
 
-def _mcp_url(args: argparse.Namespace) -> str:
-    """The MCP origin: flag, then environment, then the default."""
-    return (getattr(args, "mcp_url", None) or os.environ.get(ENV_MCP_URL) or DEFAULT_MCP_URL).strip()
+    The sibling step is what lets an rc minted against ``https://host/xmem`` reach
+    ``https://host/mcp`` with no extra flags — on a single-origin deployment the two are one
+    host by construction. It fires only on that exact shape; every other API base leaves the
+    default in place.
+    """
+    explicit = (getattr(args, "mcp_url", None) or os.environ.get(ENV_MCP_URL) or "").strip()
+    if explicit:
+        return explicit
+    if api_url:
+        inferred = _login.single_origin_sibling_url(api_url, sibling_path=_login.SINGLE_ORIGIN_MCP_PATH)
+        if inferred:
+            return inferred
+    return DEFAULT_MCP_URL
 
 
 def _rc_dir(args: argparse.Namespace) -> Path:
@@ -1122,6 +1169,9 @@ def cmd_write_status(args: argparse.Namespace) -> tuple[CliOutput, int]:
                 }
             last_status = item.get("write_status", "unknown")
             last_body = item
+            # Mirrors the terminal tail of WriteQueueStatus (completed, failed, not_found). Hand-written
+            # rather than derived: this CLI is stdlib-only by design and imports nothing from the server
+            # packages, so the enum is out of reach here.
             if last_status in ("completed", "failed", "not_found"):
                 return item
             if time.monotonic() >= deadline:
@@ -1444,10 +1494,11 @@ def _cmd_auth_login_email(args: argparse.Namespace) -> tuple[CliOutput, int]:
             ),
             EXIT_HTTP_ERROR,
         )
+
     explicit_api = _explicit_api_url(args)
     rc_origin = rc.api_url.strip() if rc is not None and rc.api_url.strip() else None
     api_origin = explicit_api or rc_origin or DEFAULT_API_URL
-    base = _normalize_api_origin(api_origin) or api_origin.rstrip("/")
+    base = _normalize_api_base_url(api_origin) or api_origin.rstrip("/")
     console, refusal = _email_console_origin(args, api_origin=api_origin)
     if refusal is not None:
         return refusal
@@ -1641,7 +1692,7 @@ def _cmd_auth_login_email(args: argparse.Namespace) -> tuple[CliOutput, int]:
         detail = getattr(exc, "strerror", None) or type(exc).__name__
         return (
             make_error(
-                f"could not write {RC_FILENAME} ({detail}). The minted key \"{result.key_name}\" "
+                f'could not write {RC_FILENAME} ({detail}). The minted key "{result.key_name}" '
                 f"(prefix {result.key_prefix}…) is active — revoke it in the Console if it should not stay.",
                 stage="login",
             ),
@@ -1683,7 +1734,7 @@ def cmd_auth_login(args: argparse.Namespace) -> tuple[CliOutput, int]:
     explicit_api = _explicit_api_url(args) or os.environ.get(ENV_API_URL, "").strip()
     console = _console_url_for_args(args)
     api_origin = explicit_api or DEFAULT_API_URL
-    base = _normalize_api_origin(api_origin) or api_origin.rstrip("/")
+    base = _normalize_api_base_url(api_origin) or api_origin.rstrip("/")
     verifier = _login.new_verifier()
     interactive = stdout_is_tty()
     offer_paste = interactive and _login.paste_from_stdin_supported()