xmemcli 0.0.9__tar.gz → 0.0.11__tar.gz

xmemcli-0.0.9/README.md → xmemcli-0.0.11/PKG-INFO

@@ -1,3 +1,11 @@
+Metadata-Version: 2.5
+Name: xmemcli
+Version: 0.0.11
+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
+Description-Content-Type: text/markdown
+
 # `xmemcli` — xmemory command-line client
 
 Single-command CLI for reading from, writing to, and managing xmemory instances over the HTTP API at `$XMEM_API_URL` (default `https://api.xmemory.ai`), using an API key from the Console UI or `xmemcli auth login`.
@@ -7,7 +15,7 @@ Full command reference is included below.
 ## Usage
 
 ```text
-xmemcli auth login [--no-browser] [--timeout S] [--console-url URL] [--email ADDR [--org-name NAME]]
+xmemcli auth login [--no-browser] [--timeout S] [--console-url URL] [--callback-port N] [--email ADDR [--org-name NAME]]
 xmemcli auth logout
 xmemcli auth status
 xmemcli read <query>
@@ -89,7 +97,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.9**.
+Version: **0.0.11**.
 
 
 ---
@@ -100,7 +108,7 @@ The CLI is **human-approved for key acquisition**: an AI-assisted IDE may run re
 
 Two acquisition paths share `xmemcli auth login`:
 
-- **Browser PKCE handoff** (default): the CLI sends the human to **`/xmemcli/<challenge>`** on the Console, listens on **`127.0.0.1:9636/callback`**, and the Console redirects a signed short-lived **code** (not the key) to that callback.
+- **Browser PKCE handoff** (default): the CLI sends the human to **`/xmemcli/<challenge>`** on the Console, listens on an ephemeral **`127.0.0.1`** port named in that URL, and the Console delivers a signed short-lived **code** (not the key) to that callback — in the background where the browser allows it, otherwise through a link the human clicks.
 - **Headless email sign-in** (`--email <addr>`): the CLI plays the waiting-browser role of the Console's cross-device email sign-in and then mints its own key — no browser on this machine. See [Email sign-in](#email-sign-in----email) below.
 
 > **Scope.** Shipped in this package: `.xmemrc.json` discovery, PKCE `auth login` / `logout` / `status`, email `auth login --email`, `/whoami` consumption, and `quota`. Server endpoints: `POST /cli/handoff`, `POST /cli/token`, and — for the email path — the Console sign-in and accounts routes listed below (all pre-existing Console surfaces; the email path added no server endpoint).
@@ -121,7 +129,7 @@ Plaintext keys in URLs leak to history and proxies. Handoff uses **PKCE + signed
 
 1. CLI mints **`verifier`**, derives **`challenge`** = `base64url(SHA256(verifier))`, opens **`/xmemcli/<challenge>`**.
 2. Human clicks **"Use this key in the CLI"** → Console **`POST`s the key** to `/cli/handoff` bound to the challenge → receives a short-lived **`code`**.
-3. Browser navigates to **`http://127.0.0.1:9636/callback?code=…&state=<challenge>`** — key never in the URL.
+3. Browser delivers to **`http://127.0.0.1:<port>/callback?code=…&state=<challenge>`** — key never in the URL.
 4. CLI **`POST /cli/token`** with `{ code, verifier }` → receives key → writes `0600` `.xmemrc.json`.
 
 ### Sequence
@@ -129,7 +137,7 @@ Plaintext keys in URLs leak to history and proxies. Handoff uses **PKCE + signed
 ```
 AI-assisted IDE ── xmemcli auth login ──► CLI: PKCE verifier + localhost listener
 Human ── opens Console URL ──► creates key → "Use this key in the CLI"
-CLI ◄── localhost redirect ── redeems code + verifier → writes .xmemrc.json
+CLI ◄── local callback    ── redeems code + verifier → writes .xmemrc.json
 AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never handles plaintext key
 ```
 
@@ -173,7 +181,7 @@ Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `-
 | Unsolicited sign-in email initiation | server-side send limits per mailbox (enforced per server node, so the fleet-wide budget scales with node count); the email itself grants nothing without the inbox owner's Approve, and the CLI best-effort-cancels attempts it cannot complete |
 | Approving someone else's email sign-in | **user-mediated** — the confirmation page leads with "only if this is your address" and states that approving lets the requesting device act on the account, including creating API keys; the stake is higher here than in the browser flow, because approving a CLI-started attempt ends in a durable API key, not a two-day browser session. The matching-code comparison that once narrowed this further is retired for now (the code still travels on the wire but no surface displays it). Approve only sign-ins you started. |
 
-Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding; security rests on PKCE, not port secrecy.
+Each login binds its own port and names it in the login URL, so concurrent logins never contend for one listener. Security rests on PKCE and on the callback being reachable only from the CLI's own machine, not on port secrecy. For SSH or devcontainer use the port has to exist before the tunnel does, so pin it: `--callback-port <n>` or `$XMEM_CALLBACK_PORT`, then forward that port.
 
 ## Quota (observe vs escalate)
 
@@ -183,7 +191,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.9` (see `xmemcli version`)
+**Version:** `0.0.11` (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.
 
@@ -402,7 +410,7 @@ so a typo fails loudly rather than being ignored.
 
 | Command | Description |
 |---------|-------------|
-| **`auth login`** | PKCE via Console `/xmemcli/<challenge>` → `.xmemrc.json`. `--no-browser`, `--timeout`, `--console-url`. With `--email ADDR` (+ optional `--org-name`, used only when a new account is created; requires `--email`): headless email sign-in — one emailed approval, then the CLI mints its own org-wide key named `CLI email login (<hostname>, <timestamp>)`; details in the auth-flow reference. New-organisation creation additionally requires the deployment to allow public registration. Payload shapes: a fresh email mint carries `method: email`, `key_name`, `api_role`, and `org_created`; the browser path carries `method: pkce` (no role/org fields); a matching `--api-key` or rc credential short-circuits to `status: already_authorized` with `source`: flag / rc (`persisted: false` on the flag arm, which saves nothing); a matching `$XMEM_API_KEY` is copied into the rc and reports `status: authorized`, `source: environment`. Exit codes follow the standard HTTP contract (401 → 4 with stage `auth`, 403 → 3 with stage `permission`, other HTTP/network/server-state failures → 3). |
+| **`auth login`** | PKCE via Console `/xmemcli/<challenge>` → `.xmemrc.json`. `--no-browser`, `--timeout`, `--console-url`, `--callback-port` (pins the loopback callback port for `ssh -L`; `0` or omitted means any free port, otherwise 1024–65535; also `$XMEM_CALLBACK_PORT`, which is read globally). With `--email ADDR` (+ optional `--org-name`, used only when a new account is created; requires `--email`): headless email sign-in — one emailed approval, then the CLI mints its own org-wide key named `CLI email login (<hostname>, <timestamp>)`; details in the auth-flow reference. New-organisation creation additionally requires the deployment to allow public registration. Payload shapes: a fresh email mint carries `method: email`, `key_name`, `api_role`, and `org_created`; the browser path carries `method: pkce` (no role/org fields); a matching `--api-key` or rc credential short-circuits to `status: already_authorized` with `source`: flag / rc (`persisted: false` on the flag arm, which saves nothing); a matching `$XMEM_API_KEY` is copied into the rc and reports `status: authorized`, `source: environment`. Exit codes follow the standard HTTP contract (401 → 4 with stage `auth`, 403 → 3 with stage `permission`, other HTTP/network/server-state failures → 3). |
 | **`auth logout`** | Remove active `.xmemrc.json` |
 | **`auth status`** | Call `/whoami`. No key → exit 0; bad key → auth error; good key → email + prefix. |
 | **`mcp <instance-id>`** | Serve one instance to an MCP client over stdio, using this CLI's credential. Not for humans — see below. |
@@ -586,6 +594,7 @@ These apply **before** any subcommand (`xmemcli help options`).
 | `--api-url` | `XMEM_API_URL` | API origin (default `https://api.xmemory.ai`) |
 | `--api-key` | `XMEM_API_KEY` | Bearer API key |
 | `--instance-id` | `XMEM_INSTANCE_ID` | Default instance for read/write and cluster derivation |
+
 | `--rc-dir` | `XMEM_RC_DIR` | Where `auth login` writes `.xmemrc.json`; reads walk **up** toward `$HOME` |
 | `--binding-dir` | `XMEM_BINDING_DIR` | Where `binding` commands look for `.xmemory.json`; reads walk **up** toward `$HOME` and **merge** every scope |
 | `--json` | — | Force one JSON document on stdout |

xmemcli-0.0.9/PKG-INFO → xmemcli-0.0.11/README.md

@@ -1,11 +1,3 @@
-Metadata-Version: 2.5
-Name: xmemcli
-Version: 0.0.9
-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
-Description-Content-Type: text/markdown
-
 # `xmemcli` — xmemory command-line client
 
 Single-command CLI for reading from, writing to, and managing xmemory instances over the HTTP API at `$XMEM_API_URL` (default `https://api.xmemory.ai`), using an API key from the Console UI or `xmemcli auth login`.
@@ -15,7 +7,7 @@ Full command reference is included below.
 ## Usage
 
 ```text
-xmemcli auth login [--no-browser] [--timeout S] [--console-url URL] [--email ADDR [--org-name NAME]]
+xmemcli auth login [--no-browser] [--timeout S] [--console-url URL] [--callback-port N] [--email ADDR [--org-name NAME]]
 xmemcli auth logout
 xmemcli auth status
 xmemcli read <query>
@@ -97,7 +89,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.9**.
+Version: **0.0.11**.
 
 
 ---
@@ -108,7 +100,7 @@ The CLI is **human-approved for key acquisition**: an AI-assisted IDE may run re
 
 Two acquisition paths share `xmemcli auth login`:
 
-- **Browser PKCE handoff** (default): the CLI sends the human to **`/xmemcli/<challenge>`** on the Console, listens on **`127.0.0.1:9636/callback`**, and the Console redirects a signed short-lived **code** (not the key) to that callback.
+- **Browser PKCE handoff** (default): the CLI sends the human to **`/xmemcli/<challenge>`** on the Console, listens on an ephemeral **`127.0.0.1`** port named in that URL, and the Console delivers a signed short-lived **code** (not the key) to that callback — in the background where the browser allows it, otherwise through a link the human clicks.
 - **Headless email sign-in** (`--email <addr>`): the CLI plays the waiting-browser role of the Console's cross-device email sign-in and then mints its own key — no browser on this machine. See [Email sign-in](#email-sign-in----email) below.
 
 > **Scope.** Shipped in this package: `.xmemrc.json` discovery, PKCE `auth login` / `logout` / `status`, email `auth login --email`, `/whoami` consumption, and `quota`. Server endpoints: `POST /cli/handoff`, `POST /cli/token`, and — for the email path — the Console sign-in and accounts routes listed below (all pre-existing Console surfaces; the email path added no server endpoint).
@@ -129,7 +121,7 @@ Plaintext keys in URLs leak to history and proxies. Handoff uses **PKCE + signed
 
 1. CLI mints **`verifier`**, derives **`challenge`** = `base64url(SHA256(verifier))`, opens **`/xmemcli/<challenge>`**.
 2. Human clicks **"Use this key in the CLI"** → Console **`POST`s the key** to `/cli/handoff` bound to the challenge → receives a short-lived **`code`**.
-3. Browser navigates to **`http://127.0.0.1:9636/callback?code=…&state=<challenge>`** — key never in the URL.
+3. Browser delivers to **`http://127.0.0.1:<port>/callback?code=…&state=<challenge>`** — key never in the URL.
 4. CLI **`POST /cli/token`** with `{ code, verifier }` → receives key → writes `0600` `.xmemrc.json`.
 
 ### Sequence
@@ -137,7 +129,7 @@ Plaintext keys in URLs leak to history and proxies. Handoff uses **PKCE + signed
 ```
 AI-assisted IDE ── xmemcli auth login ──► CLI: PKCE verifier + localhost listener
 Human ── opens Console URL ──► creates key → "Use this key in the CLI"
-CLI ◄── localhost redirect ── redeems code + verifier → writes .xmemrc.json
+CLI ◄── local callback    ── redeems code + verifier → writes .xmemrc.json
 AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never handles plaintext key
 ```
 
@@ -181,7 +173,7 @@ Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `-
 | Unsolicited sign-in email initiation | server-side send limits per mailbox (enforced per server node, so the fleet-wide budget scales with node count); the email itself grants nothing without the inbox owner's Approve, and the CLI best-effort-cancels attempts it cannot complete |
 | Approving someone else's email sign-in | **user-mediated** — the confirmation page leads with "only if this is your address" and states that approving lets the requesting device act on the account, including creating API keys; the stake is higher here than in the browser flow, because approving a CLI-started attempt ends in a durable API key, not a two-day browser session. The matching-code comparison that once narrowed this further is retired for now (the code still travels on the wire but no surface displays it). Approve only sign-ins you started. |
 
-Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding; security rests on PKCE, not port secrecy.
+Each login binds its own port and names it in the login URL, so concurrent logins never contend for one listener. Security rests on PKCE and on the callback being reachable only from the CLI's own machine, not on port secrecy. For SSH or devcontainer use the port has to exist before the tunnel does, so pin it: `--callback-port <n>` or `$XMEM_CALLBACK_PORT`, then forward that port.
 
 ## Quota (observe vs escalate)
 
@@ -191,7 +183,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.9` (see `xmemcli version`)
+**Version:** `0.0.11` (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.
 
@@ -410,7 +402,7 @@ so a typo fails loudly rather than being ignored.
 
 | Command | Description |
 |---------|-------------|
-| **`auth login`** | PKCE via Console `/xmemcli/<challenge>` → `.xmemrc.json`. `--no-browser`, `--timeout`, `--console-url`. With `--email ADDR` (+ optional `--org-name`, used only when a new account is created; requires `--email`): headless email sign-in — one emailed approval, then the CLI mints its own org-wide key named `CLI email login (<hostname>, <timestamp>)`; details in the auth-flow reference. New-organisation creation additionally requires the deployment to allow public registration. Payload shapes: a fresh email mint carries `method: email`, `key_name`, `api_role`, and `org_created`; the browser path carries `method: pkce` (no role/org fields); a matching `--api-key` or rc credential short-circuits to `status: already_authorized` with `source`: flag / rc (`persisted: false` on the flag arm, which saves nothing); a matching `$XMEM_API_KEY` is copied into the rc and reports `status: authorized`, `source: environment`. Exit codes follow the standard HTTP contract (401 → 4 with stage `auth`, 403 → 3 with stage `permission`, other HTTP/network/server-state failures → 3). |
+| **`auth login`** | PKCE via Console `/xmemcli/<challenge>` → `.xmemrc.json`. `--no-browser`, `--timeout`, `--console-url`, `--callback-port` (pins the loopback callback port for `ssh -L`; `0` or omitted means any free port, otherwise 1024–65535; also `$XMEM_CALLBACK_PORT`, which is read globally). With `--email ADDR` (+ optional `--org-name`, used only when a new account is created; requires `--email`): headless email sign-in — one emailed approval, then the CLI mints its own org-wide key named `CLI email login (<hostname>, <timestamp>)`; details in the auth-flow reference. New-organisation creation additionally requires the deployment to allow public registration. Payload shapes: a fresh email mint carries `method: email`, `key_name`, `api_role`, and `org_created`; the browser path carries `method: pkce` (no role/org fields); a matching `--api-key` or rc credential short-circuits to `status: already_authorized` with `source`: flag / rc (`persisted: false` on the flag arm, which saves nothing); a matching `$XMEM_API_KEY` is copied into the rc and reports `status: authorized`, `source: environment`. Exit codes follow the standard HTTP contract (401 → 4 with stage `auth`, 403 → 3 with stage `permission`, other HTTP/network/server-state failures → 3). |
 | **`auth logout`** | Remove active `.xmemrc.json` |
 | **`auth status`** | Call `/whoami`. No key → exit 0; bad key → auth error; good key → email + prefix. |
 | **`mcp <instance-id>`** | Serve one instance to an MCP client over stdio, using this CLI's credential. Not for humans — see below. |
@@ -594,6 +586,7 @@ These apply **before** any subcommand (`xmemcli help options`).
 | `--api-url` | `XMEM_API_URL` | API origin (default `https://api.xmemory.ai`) |
 | `--api-key` | `XMEM_API_KEY` | Bearer API key |
 | `--instance-id` | `XMEM_INSTANCE_ID` | Default instance for read/write and cluster derivation |
+
 | `--rc-dir` | `XMEM_RC_DIR` | Where `auth login` writes `.xmemrc.json`; reads walk **up** toward `$HOME` |
 | `--binding-dir` | `XMEM_BINDING_DIR` | Where `binding` commands look for `.xmemory.json`; reads walk **up** toward `$HOME` and **merge** every scope |
 | `--json` | — | Force one JSON document on stdout |

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

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "0.0.9"
+version = "0.0.11"
 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.9 → xmemcli-0.0.11}/uv.lock

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

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

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

{xmemcli-0.0.9 → xmemcli-0.0.11}/xmemcli/_context_cmd.py

@@ -94,6 +94,12 @@ _CONSUMER_HOOK_OUTPUT_LIMIT = 10_000
 #: just fits over the edge.
 MAX_PACK_CHARS = _CONSUMER_HOOK_OUTPUT_LIMIT - 500
 
+#: Sections the server renders per pack (identity, owner, rules, schema, live state).
+#: The footprint is a diagnostic, so a server sending more is not describing a pack this
+#: client received; publishing them unbounded would let a small response build a large
+#: document. Mirrors the renderer's section list rather than any transport limit.
+_MAX_SECTIONS_PER_PACK = 5
+
 
 def _requestable_ids(autoload: tuple[Any, ...], listed: AbstractSet[str]) -> tuple[list[str], list[str]]:
     """Ids the server will accept, and the ones dropped with a reason.
@@ -456,9 +462,94 @@ def _curated_unavailable(entry: Any) -> dict[str, Any]:
     return curated
 
 
+def _curated_pack(entry: Any) -> dict[str, Any]:
+    """One pack's footprint: what it cost, whether it was cut, and where the cost sits.
+
+    Sizes and identity only. The pack's own text is already in ``text``, and republishing
+    section bodies here would hand a caller a second copy of content that the clamp and
+    scrub below bound exactly once.
+
+    Section titles are the server's own headings rather than anything an owner wrote, but
+    they arrive over the wire like everything else here, so they are scrubbed and length-
+    bounded. Not the UTF-16 clamp the pack text also gets — a title is capped at 200 code
+    points, so it cannot reach the limit that clamp exists for. A count that is not a
+    number is published as ``None``: a caller doing arithmetic on it should see a gap, not
+    a zero it cannot distinguish from a section that genuinely cost nothing.
+    """
+    curated: dict[str, Any] = {
+        "instance_id": scrub(entry["instance_id"], limit=200) if isinstance(entry.get("instance_id"), str) else None,
+        "estimated_tokens": _count(entry.get("estimated_tokens")),
+        "truncated": entry["truncated"] if isinstance(entry.get("truncated"), bool) else None,
+    }
+    raw_sections = entry.get("sections")
+    # Filtered before the cap, not after: slicing first let junk consume the slots, so a
+    # response whose first five entries were nulls published none of the real ones.
+    sections = [s for s in raw_sections if isinstance(s, dict)] if isinstance(raw_sections, list) else []
+    # Bounded as well as filtered. The server renders at most five sections per pack, so
+    # anything beyond that is not a breakdown of anything, and an unbounded array on a
+    # payload whose text is hard-capped is a way for a small response to build a large
+    # document. Not the only one — ``unavailable`` above is still uncapped — but the cap
+    # is cheap where the shape is known.
+    curated["sections"] = [
+        {
+            "title": scrub(section["title"], limit=200) if isinstance(section.get("title"), str) else None,
+            "estimated_tokens": _count(section.get("estimated_tokens")),
+        }
+        for section in sections[:_MAX_SECTIONS_PER_PACK]
+    ]
+    return curated
+
+
+def _curated_universal_rules(entry: Any) -> dict[str, Any] | None:
+    """The response-level rules block's footprint, or ``None`` when the server sent none.
+
+    Published for the same reason the per-pack sections are: this is the one part of the response
+    that belongs to no pack, so a caller summing ``packs`` to account for ``estimated_tokens``
+    comes up short by exactly it. It used to be inside every pack and is now charged once, which
+    is a change someone reading the breakdown to explain a budget needs to see.
+
+    Title and size only, like ``_curated_pack`` — the body is already in ``text``.
+    """
+    if not isinstance(entry, dict):
+        return None
+    return {
+        "title": scrub(entry["title"], limit=200) if isinstance(entry.get("title"), str) else None,
+        "estimated_tokens": _count(entry.get("estimated_tokens")),
+    }
+
+
+def _count(value: Any) -> int | None:
+    """A published token count, or ``None`` when the server sent something that is not one.
+
+    ``bool`` is excluded explicitly because it is a subclass of ``int``: without that,
+    ``"estimated_tokens": true`` published ``true`` and a caller summing the sections
+    added one, which is the arithmetic the ``None`` exists to keep honest. Spelled the
+    same way in ``_pretty.py`` and ``xmem.py``; ``_binding.py`` reaches the same result
+    through the negated form. The idiom appears at several sites in ``cli/`` and each
+    checks something different afterwards (``> 0``, ``>= 0``, ``< 1``), which is why this
+    stays local rather than becoming a shared helper.
+    """
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
 def _nothing_to_inject() -> dict[str, Any]:
-    """The payload for "there is no context to add", used by every such path."""
-    return {"text": "", "instance_ids": [], "unavailable": [], "estimated_tokens": 0}
+    """The payload for "there is no context to add", used by every such path.
+
+    ``max_tokens`` is ``None`` rather than absent: the success path always carries it,
+    and a caller told the shape is stable should not have to test for the key before
+    reading it on the one branch that omitted it.
+    """
+    return {
+        "text": "",
+        "instance_ids": [],
+        "unavailable": [],
+        "estimated_tokens": 0,
+        "max_tokens": None,
+        "packs": [],
+        # Present and null for the same reason ``max_tokens`` is: the success path always carries
+        # the key, and a caller told the shape is stable should not have to test for it.
+        "universal_rules": None,
+    }
 
 
 def _command_budget(args: argparse.Namespace) -> float:
@@ -743,6 +834,23 @@ def _context(args: argparse.Namespace, deadline: float) -> tuple[CliOutput, int]
     # `diff_plan`, anything an internal renderer attaches) cannot arrive here and be
     # published; it is dropped until someone decides it belongs.
     unavailable = [_curated_unavailable(entry) for entry in unavailable]
+    # Shape-checked before iteration for the same reason `items` and `unavailable` above
+    # are: `result.get("packs") or []` keeps whatever truthy value arrived, so
+    # `{"packs": 7}` raised `TypeError` out of the comprehension and the blanket guard
+    # turned a perfectly good, already-clamped pack into an empty payload — the whole
+    # session's context discarded because an optional diagnostic field had the wrong
+    # type. A dict or a string would not even raise: they iterate, and publish phantom
+    # entries. The footprint is a diagnostic, so a bad one costs itself and nothing else.
+    raw_packs = result.get("packs")
+    if raw_packs is not None and not isinstance(raw_packs, list):
+        m._note_cli_warning(args, "xmemory returned an unreadable context footprint; sizes omitted")
+        raw_packs = []
+    # Non-dict elements are skipped rather than curated into all-null entries: a
+    # phantom pack is the outcome the guard above warns about, one level down, and a
+    # caller cannot tell it from an instance that genuinely reported nothing. Capped at
+    # the number of instances the server will accept in one request, for the same reason
+    # the sections are capped.
+    packs = [_curated_pack(p) for p in [p for p in (raw_packs or []) if isinstance(p, dict)][:MAX_REQUESTED_INSTANCES]]
     delivered = [i for i in requested if i not in missing]
     if unavailable:
         m._note_cli_warning(
@@ -769,7 +877,30 @@ def _context(args: argparse.Namespace, deadline: float) -> tuple[CliOutput, int]
     # passes the first at 9,500 and measures 19,000 to the second, and Claude Code
     # writes it to a file and injects a preview instead of the context. Bounding the
     # unit the consumer actually counts is what the cap was for.
-    text = clamp_utf16(scrub(text, limit=MAX_PACK_CHARS), limit=MAX_PACK_CHARS)
+    # Sanitised first, with a limit that cannot bite, so the two jobs `scrub` performs are
+    # separated: it strips Cc/Cf/Cs characters *and* clamps. Measuring the final text
+    # against the raw server text conflated them — a fully delivered pack carrying one
+    # zero-width joiner, soft hyphen, BOM or bidi mark came out shorter and was reported as
+    # cut, which is a false alarm aimed at exactly the reader who asked why their context
+    # shrank. Only a length cut is a length cut.
+    sanitised = scrub(text, limit=len(text))
+    injected = clamp_utf16(scrub(sanitised, limit=MAX_PACK_CHARS), limit=MAX_PACK_CHARS)
+    # The footprint below describes what the *server* rendered. When this clamp bites, part
+    # of that never reaches the model, and a breakdown still reporting the full sizes with
+    # `truncated: false` misleads precisely the reader it exists for — someone asking why
+    # their live state disappeared, being shown a section that advertises 4,900 tokens and
+    # arrived as nothing. So a client-side cut marks every pack too. The flag means "what
+    # you are reading is not the whole of it", whichever side did the cutting; the warning
+    # names which side, because the fixes are different — retier a binding, or lower
+    # `pack_max_tokens`.
+    if len(injected) < len(sanitised):
+        m._note_cli_warning(
+            args,
+            "the rendered context was longer than this client can inject and was cut; "
+            "the sizes reported describe what xmemory rendered, not what was injected",
+        )
+        packs = [{**pack, "truncated": True} for pack in packs]
+    text = injected
     return (
         CliOutput(
             OutputKind.AGENT_CONTEXT,
@@ -777,8 +908,22 @@ def _context(args: argparse.Namespace, deadline: float) -> tuple[CliOutput, int]
                 "text": text,
                 "instance_ids": delivered,
                 "unavailable": unavailable,
-                "estimated_tokens": result.get("estimated_tokens") or 0,
-                "max_tokens": result.get("max_tokens"),
+                # Through the same guard as the parts: publishing `true` as a total while
+                # the sections it explains correctly read null is the inconsistency the
+                # breakdown exists to avoid.
+                "estimated_tokens": _count(result.get("estimated_tokens")) or 0,
+                "max_tokens": _count(result.get("max_tokens")),
+                # Where the total sits, per instance and per section. The total alone says a
+                # pack was expensive or was cut; only the breakdown says which instance spent
+                # the budget and what a shrink took, which is what someone asking "why is my
+                # context so big" or "why did my live state disappear" is actually asking.
+                # Curated the way `unavailable` is, so a section body cannot arrive by this
+                # route and bypass the clamp the pack text goes through.
+                "packs": packs,
+                # The part of the total that belongs to no pack: the operating rules, carried once
+                # for the response rather than repeated in each pack. Without it the breakdown
+                # cannot account for its own total.
+                "universal_rules": _curated_universal_rules(result.get("universal_rules")),
             },
         ),
         m.EXIT_OK,

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

@@ -1,11 +1,16 @@
 """The browser handoff behind ``xmem auth login`` (PKCE + loopback callback).
 
 The CLI mints a PKCE ``verifier`` / ``challenge`` and opens ``/xmemcli/<challenge>``.
-It listens on ``127.0.0.1:9636`` while the human creates a key and clicks **Use this key
-in the CLI**. The Console POSTs the key to ``/cli/handoff``, receives a signed short-lived
-``code``, then redirects the browser to the local callback with ``code`` + ``state``.
+It listens on an ephemeral ``127.0.0.1`` port, named in the login URL, while the human
+creates a key and clicks **Use this key in the CLI**. A port per run means two logins never
+contend for one listener. The Console POSTs the key to ``/cli/handoff``, receives a signed
+short-lived ``code``, then delivers it to that callback with ``code`` + ``state`` — in the
+background where the browser allows that, otherwise through a link the human clicks.
 The CLI redeems with ``verifier`` + ``code`` over TLS; only it holds the verifier.
 
+Delivery reaching the CLI's own machine is what binds the key to the human who approved it:
+the code is only ever handed to a listener on their loopback interface.
+
 This loopback callback is a conscious multi-node design choice: the API remains stateless
 for sign-in, because any node can mint/verify the signed code and no shared relay table,
 cache, sticky session, or cross-node pub/sub is required.
@@ -13,6 +18,7 @@ Standard-library only, like the rest of the CLI.
 """
 
 import base64
+import errno
 import hashlib
 import json
 import os
@@ -23,7 +29,7 @@ import threading
 import time
 import urllib.error
 import urllib.request
-from http.server import BaseHTTPRequestHandler, HTTPServer
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from typing import IO, Any, Callable, NamedTuple, cast, override
 from urllib.parse import parse_qs, quote, urlparse, urlsplit
 
@@ -46,8 +52,27 @@ _ENV_CONSOLE_URL = "XMEM_CONSOLE_URL"
 _ENV_API_URL = "XMEM_API_URL"
 DEFAULT_CONSOLE_URL = "https://console.xmemory.ai"
 
-CALLBACK_PORT = 9636
+#: Every login binds its own ephemeral port and tells the Console which one in the login URL, so
+#: two ``auth login`` runs never contend for one listener. This value is only the legacy default a
+#: pre-ephemeral client used; it is what ``build_login_page_url`` compares against to decide the
+#: URL still needs a ``callback_url``.
+LEGACY_CALLBACK_PORT = 9636
+#: Bind an ephemeral port: the OS picks a free one and the listener reports it back.
+EPHEMERAL_CALLBACK_PORT = 0
 CALLBACK_PATH = "/callback"
+# Chrome restricts a public HTTPS page (the Console) reaching a loopback address behind a
+# Local Network Access permission. Measured on Chrome 150: the same request issued straight
+# off the human's click prompts for that permission, while one issued after an awaited POST
+# is refused outright ("Permission was denied for this request to access the `loopback`
+# address space") with no prompt at all. No Chrome/WICG/MDN document explains the difference
+# — spending the click's transient user activation is the likeliest cause but is inference,
+# not a documented contract. The Console therefore hits this path first, before it awaits
+# anything else. Nothing is captured here, so a permission request is never mistaken for a
+# callback.
+PERMISSION_PROBE_PATH = "/permission-probe"
+#: Answered on the probe so the Console can tell a real xmemcli listener from any other local
+#: server on the port the login URL named. Must match cli_handoff.js XMEMCLI_MARKER_HEADER.
+XMEMCLI_MARKER_HEADER = "X-Xmemcli"
 CLI_LOGIN_PATH = "/xmemcli"
 CLI_TOKEN_PROXY_PATH = "/api/cli/token"
 CLI_WHOAMI_PROXY_PATH = "/api/cli/whoami"
@@ -58,10 +83,15 @@ API_KEY_PREFIX = "xmem_"
 #: local-dev Console. One list, shared — three copies had already grown two different values.
 LOOPBACK_HOSTS = ("localhost", "127.0.0.1", "::1")
 
+# Deliberately does NOT claim success: this page is written when the code arrives, before the
+# CLI has redeemed it, and redemption can still fail (an expired code, most plausibly when a
+# human clicks the fallback link minutes after it was minted). Reporting the outcome here would
+# mean holding the response open across the redeem; pointing at the terminal, which does know,
+# is honest and keeps the handler a single non-blocking write.
 _DONE_PAGE = (
     f"<!doctype html><html><head><meta charset='utf-8'><title>{CLI_NAME}</title></head>"
     "<body style='font-family:system-ui;margin:3rem'>"
-    "<h2>You're all set.</h2><p>You can close this tab and return to your terminal.</p>"
+    "<h2>Code received.</h2><p>Return to your terminal — it reports whether the login completed.</p>"
     "</body></html>"
 ).encode("utf-8")
 
@@ -136,13 +166,14 @@ def build_login_page_url(console_url: str, *, challenge: str, callback_url: str
     """Console CLI login URL: ``/xmemcli/<challenge>`` (PKCE S256, also the callback state)."""
     segment = quote(challenge, safe="-_")
     url = f"{console_url.rstrip('/')}{CLI_LOGIN_PATH}/{segment}"
-    if callback_url and callback_url != redirect_uri_for_port(CALLBACK_PORT):
+    if callback_url and callback_url != redirect_uri_for_port(LEGACY_CALLBACK_PORT):
         url += "?callback_url=" + quote(callback_url, safe=":/?&=-_.")
     return url
 
 
 def _login_prompt_line(label: str, body: str) -> str:
-    return f"  {label:<10}{body}"
+    # Width fits the longest label below; anything longer would run into its own body text.
+    return f"  {label:<12}{body}"
 
 
 def write_login_handoff_prompt(
@@ -153,7 +184,7 @@ def write_login_handoff_prompt(
 ) -> None:
     """Human-facing instructions while ``auth login`` waits for a credential."""
     out = stream or sys.stderr
-    body_indent = "            "
+    body_indent = " " * 14  # 2-space margin + the 12-wide label column, so bodies line up
     lines = [
         "",
         f"Authorize {CLI_NAME} on this machine.",
@@ -163,12 +194,16 @@ def write_login_handoff_prompt(
         "",
         _login_prompt_line(
             "Onboarding",
-            "During first-instance setup the Console auto-delivers the key — no extra clicks.",
+            "During first-instance setup the Console delivers the key for you where it can.",
         ),
         _login_prompt_line(
-            "After onboarding",
+            "Otherwise",
             'Create a key on API Keys and click "Use this key in the CLI".',
         ),
+        _login_prompt_line(
+            "New tab",
+            "Some browsers (Safari) finish the login in a new tab — follow the link if one appears.",
+        ),
     ]
     if offer_paste:
         lines.extend(
@@ -287,21 +322,183 @@ def validate_api_key_shape(key: str) -> str | None:
     return None
 
 
-class _LoopbackServer(HTTPServer):
+class _LoopbackServer(ThreadingHTTPServer):
+    # Threading, not the plain server: browsers open speculative preconnects that send nothing,
+    # and a single-threaded server serves them one at a time — each costing the full per-request
+    # timeout before the real callback is even accepted. CPython documents ThreadingHTTPServer as
+    # existing for exactly this. Handlers run concurrently, so ``captured`` is written under a
+    # lock and only once: first delivery wins. Without that, two callbacks racing would both
+    # write and the later one — which may carry a stale or mismatched ``state`` — would replace
+    # the one already accepted.
+    daemon_threads = True
     captured: dict[str, str] | None = None
+    # Serialized origin of the Console this login is talking to, per RFC 6454. Carried on the
+    # server so the handler compares against the origin actually in play — including one passed
+    # via ``--console-url`` — instead of re-deriving it from the environment.
+    console_origin: str = ""
+
+    @override
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        # Owned here rather than by the caller: every construction site needs it, including the
+        # tests that build a listener directly, and a missing lock fails as a dropped connection
+        # rather than anything that names the cause.
+        self.capture_lock = threading.Lock()
+        super().__init__(*args, **kwargs)
+
+    @override
+    def handle_error(self, request: Any, client_address: Any) -> None:
+        """Swallow the disconnects this listener expects; let anything else surface.
+
+        Delivery is up to three connections plus browser preconnects, two of them fire-and-forget
+        ``no-cors`` fetches whose sockets the browser may reset. The default handler would dump
+        those tracebacks onto stderr, interleaved with the login prompt.
+
+        Scoped deliberately: swallowing everything would hide a bug raised inside a handler, and
+        the only symptom would be a login that waits out its full timeout with nothing printed.
+        (Socket timeouts are quiet for a different reason — the ``log_message`` override.)
+        """
+        exc = sys.exc_info()[1]
+        if isinstance(exc, (ConnectionResetError, BrokenPipeError, TimeoutError)):
+            return
+        super().handle_error(request, client_address)
+
+
+def _same_console_origin(actual: str, expected: str) -> bool:
+    """Whether two serialized origins name the same Console.
+
+    Exact equality except among the loopback spellings, which are the same host reached by
+    different names — the equivalence ``LOOPBACK_HOSTS`` exists for. A developer whose CLI
+    derives ``http://localhost:8002`` but who opens ``http://127.0.0.1:8002`` is at their own
+    Console; refusing the marker there disables background delivery and blames a permission
+    the browser never asked about.
+
+    Deliberately not a general relaxation: scheme and port must still match exactly, so this
+    cannot bridge a loopback origin to a public one.
+    """
+    if not actual or not expected:
+        return False
+    if actual == expected:
+        return True
+    parsed_actual, parsed_expected = urlsplit(actual), urlsplit(expected)
+    if parsed_actual.scheme != parsed_expected.scheme:
+        return False
+    if (parsed_actual.hostname or "") not in LOOPBACK_HOSTS:
+        return False
+    if (parsed_expected.hostname or "") not in LOOPBACK_HOSTS:
+        return False
+    try:
+        return parsed_actual.port == parsed_expected.port
+    except ValueError:
+        return False
+
+
+def serialized_origin(url: str) -> str:
+    """``scheme://host[:port]``, lowercased, default port elided — comparable to an ``Origin``."""
+    parsed = urlsplit(url.strip())
+    scheme = parsed.scheme.lower()
+    host = (parsed.hostname or "").lower()
+    if not scheme or not host:
+        return ""
+    try:
+        port = parsed.port
+    except ValueError:
+        # A non-numeric or out-of-range port is a malformed origin, and this value is only ever
+        # compared against a request's Origin header — an unparseable one matches nothing, which
+        # is the safe answer. Raising here would escape before the listener can be closed.
+        return ""
+    if port is None or (scheme, port) in (("http", 80), ("https", 443)):
+        return f"{scheme}://{host}"
+    return f"{scheme}://{host}:{port}"
 
 
 class _CallbackHandler(BaseHTTPRequestHandler):
+    # A connection that opens and then says nothing must not wedge the listener: HTTPServer is
+    # threaded, so a silent peer gets its own thread rather than starving the listener — but
+    # without this that thread would live for the whole login, so
+    # Threading keeps accept() moving, so a silent peer no longer delays the real callback. This
+    # timeout is what bounds how long that peer's worker thread sits in rfile.readline() — without
+    # it the thread would live for the whole login. Do not delete it as "redundant now we thread":
+    # the two solve different halves.
+    timeout = 5
+
+    def _console_origin_or_none(self) -> str | None:
+        """The request's ``Origin`` when it is this login's Console, else ``None``.
+
+        One predicate for both the preflight and the probe. Written twice it drifted: the probe
+        branch echoed the raw header, so an obs-folded value carrying CR/LF round-tripped into
+        ``Access-Control-Allow-Origin`` while the identical input on ``OPTIONS`` was refused.
+        """
+        origin = self.headers.get("Origin")
+        if not origin or "\r" in origin or "\n" in origin:
+            return None
+        expected = cast(_LoopbackServer, self.server).console_origin
+        if not expected:
+            return None
+        return origin if _same_console_origin(serialized_origin(origin), expected) else None
+
+    def do_OPTIONS(self) -> None:  # noqa: N802
+        """Answer a CORS/Private-Network preflight, should one ever be sent.
+
+        Defensive rather than load-bearing: both Console requests are ``no-cors`` GETs, which are
+        never CORS-preflighted, and the only mechanism that would have preflighted them —
+        Private Network Access — is on hold, with its Local Network Access successor gating on a
+        permission instead. Left in place because ``BaseHTTPRequestHandler`` would otherwise
+        answer 501, which fails such a preflight and silently drops the callback.
+        """
+        origin = self._console_origin_or_none()
+        self.send_response(204)
+        self.send_header("Vary", "Origin")
+        if origin:
+            self.send_header("Access-Control-Allow-Origin", origin)
+            self.send_header("Access-Control-Allow-Methods", "GET, OPTIONS")
+            # Private Network Access. Its Local Network Access successor dropped the header
+            # mechanism for a permission prompt, so there is no second header to send.
+            if self.headers.get("Access-Control-Request-Private-Network") == "true":
+                self.send_header("Access-Control-Allow-Private-Network", "true")
+            self.send_header("Access-Control-Max-Age", "60")
+        self.end_headers()
+
     def do_GET(self) -> None:  # noqa: N802
+        # The callback carries no CORS headers: the Console fetches it with ``mode: 'no-cors'``
+        # and never reads the response, so letting arbitrary pages read it buys nothing. The
+        # probe above is the deliberate exception — it is fetched with ``mode: 'cors'`` precisely
+        # so the marker is readable, which an opaque response would prevent.
         parsed = urlparse(self.path)
+        if parsed.path == PERMISSION_PROBE_PATH:
+            # Captures nothing — its job is to let the Console tell this listener apart from an
+            # unrelated service that happens to hold the port named in the URL, before it mints a
+            # key toward it. The marker is a fixed public value, so it proves cooperation with
+            # this protocol, not identity: malicious local code can send the same headers, which
+            # is out of scope — a process on the user's loopback already implies code execution
+            # on the machine. What it does buy is that a benign service answering there gets no
+            # key. The CORS headers
+            # are what let the Console read the marker cross-origin; without a matching Origin we
+            # send neither, so nothing here leaks to an arbitrary page. Reaching it at all is also
+            # still what makes the browser prompt for local-network access.
+            origin = self._console_origin_or_none()
+            self.send_response(204)
+            self.send_header("Vary", "Origin")
+            if origin:
+                self.send_header("Access-Control-Allow-Origin", origin)
+                self.send_header("Access-Control-Expose-Headers", XMEMCLI_MARKER_HEADER)
+                self.send_header(XMEMCLI_MARKER_HEADER, "1")
+            self.end_headers()
+            return
         if parsed.path != CALLBACK_PATH:
             self.send_response(404)
+            self.send_header("Content-Length", "0")
             self.end_headers()
             return
         params = {k: v[0] for k, v in parse_qs(parsed.query).items() if v}
-        cast(_LoopbackServer, self.server).captured = params
+        server = cast(_LoopbackServer, self.server)
+        # First delivery wins. Handlers are concurrent now, so an unconditional write would let a
+        # second callback replace one already accepted.
+        with server.capture_lock:
+            if server.captured is None:
+                server.captured = params
         self.send_response(200)
         self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(_DONE_PAGE)))
         self.end_headers()
         self.wfile.write(_DONE_PAGE)
 
@@ -316,8 +513,9 @@ def wait_for_callback(
     on_url: Callable[[str], None],
     timeout_s: float,
     *,
-    callback_port: int = CALLBACK_PORT,
+    callback_port: int = EPHEMERAL_CALLBACK_PORT,
     stop: threading.Event | None = None,
+    console_url: str | None = None,
 ) -> dict[str, str]:
     """Listen for the browser's local callback carrying the signed code.
 
@@ -327,13 +525,30 @@ def wait_for_callback(
     try:
         server = _LoopbackServer(("127.0.0.1", callback_port), _CallbackHandler)
     except OSError as e:
-        label = callback_port if callback_port != 0 else CALLBACK_PORT
-        raise LoginError(
-            f"could not bind 127.0.0.1:{label} — is another `{CLI_NAME} auth login` in progress? ({e})"
-        ) from None
+        # Say what actually happened. Naming a cause the errno does not support sends people
+        # hunting the wrong thing — a permission failure is not a port conflict — and the raw
+        # exception text ("[Errno 98] ...") is not something to put in front of a user.
+        if callback_port == EPHEMERAL_CALLBACK_PORT:
+            raise LoginError("could not bind a local port for the login callback") from None
+        if e.errno == errno.EACCES:
+            # Reachable through direct library use with a privileged port, and via the CLI only
+            # when something other than the port number denied the bind — `_callback_port` has
+            # already required >= 1024 there. So it names both causes rather than telling a CLI
+            # user to do what they just did.
+            raise LoginError(
+                f"not allowed to bind 127.0.0.1:{callback_port} — ports below 1024 need elevated "
+                f"privileges, and a host firewall or security product can deny a bind at any port."
+            ) from None
+        if e.errno == errno.EADDRINUSE:
+            raise LoginError(
+                f"could not bind 127.0.0.1:{callback_port} — something is already using that port, "
+                f"possibly another `{CLI_NAME} auth login`."
+            ) from None
+        raise LoginError(f"could not bind 127.0.0.1:{callback_port} for the login callback") from None
     bound_port = server.server_address[1]
     server.timeout = 0.5
     try:
+        server.console_origin = serialized_origin(console_url_for_api(console_url=console_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()):
@@ -548,7 +763,7 @@ def wait_for_handoff(
     build_url: Callable[[str], str],
     on_url: Callable[[str], None],
     timeout_s: float,
-    callback_port: int = CALLBACK_PORT,
+    callback_port: int = EPHEMERAL_CALLBACK_PORT,
     interactive: bool = False,
     notify: Callable[[str], None] | None = None,
 ) -> HandoffResult:
@@ -582,6 +797,7 @@ def wait_for_handoff(
                 timeout_s,
                 callback_port=callback_port,
                 stop=stop,
+                console_url=console_url,
             )
             code = params.get("code")
             if not code:
@@ -674,7 +890,7 @@ def run_pkce_login(
     verifier: str,
     on_url: Callable[[str], None],
     timeout_s: float,
-    callback_port: int = CALLBACK_PORT,
+    callback_port: int = EPHEMERAL_CALLBACK_PORT,
     interactive: bool = False,
     notify: Callable[[str], None] | None = None,
 ) -> HandoffResult:

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

@@ -139,7 +139,18 @@ class OutputKind(StrEnum):
 
     #: Output of ``xmemcli context`` — the session-start pack for the autoload
     #: bindings in this directory. Curated payload: ``{text, instance_ids,
-    #: unavailable, estimated_tokens, max_tokens}``. ``text`` is injected verbatim.
+    #: unavailable, estimated_tokens, max_tokens, packs, universal_rules}``. ``text`` is injected
+    #: verbatim; ``packs`` is the footprint breakdown — per instance, and per
+    #: section within it — carrying sizes and titles but no section bodies.
+    #: The breakdown accounts for slightly less than ``estimated_tokens``, in both
+    #: directions: each pack's heading, the blank lines between packs and the note
+    #: prepended when a project binding introduced instances are injected text
+    #: charged to no section, and a pack too long for this client is cut after the
+    #: sizes are read — every ``truncated`` is then ``true`` and a warning says so.
+    #: Present the parts as where the budget went, not as an exact decomposition.
+    #: ``max_tokens`` is ``null`` whenever no pack was delivered — which includes
+    #: every failure path, so read ``warnings`` for why rather than inferring an
+    #: empty binding.
     AGENT_CONTEXT = "agent_context"
 
     #: Output of ``xmemcli org list instances`` (and ``instance list`` alias).

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

@@ -114,6 +114,18 @@ def _render_read_structured(payload: Any, stream: IO[str]) -> None:
     The curated payload IS the rows / xresponse the operator explicitly
     asked for; dump it as JSON.
     """
+    if isinstance(payload, dict) and payload.get("reader_result", ...) is None:
+        stream.write("No rows.\n")
+        pending = payload.get("pending_suggestions")
+        if isinstance(pending, int) and not isinstance(pending, bool) and pending > 0:
+            stream.write(f"({pending} pending schema suggestion(s) — {CLI_NAME} schema suggestions review)\n")
+        trace_id = payload.get("trace_id")
+        if isinstance(trace_id, str) and trace_id.strip():
+            stream.write(f"  trace: {_terminal_safe(trace_id.strip())}\n")
+        console_url = payload.get("console_url")
+        if isinstance(console_url, str) and console_url.strip():
+            stream.write(f"  console: {_terminal_safe(console_url.strip())}\n")
+        return
     json.dump(payload, stream, indent=2, default=str)
     stream.write("\n")
 

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

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

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

@@ -149,6 +149,12 @@ ENV_INSTANCE_ID = "XMEM_INSTANCE_ID"
 ENV_API_URL = "XMEM_API_URL"
 ENV_CLUSTER_ID = "XMEM_CLUSTER_ID"
 ENV_CONSOLE_URL = "XMEM_CONSOLE_URL"
+#: Pin the loopback callback port. Unset means any free port, which is what lets concurrent
+#: logins coexist; pinning is for when the port has to be known before the login starts.
+ENV_CALLBACK_PORT = "XMEM_CALLBACK_PORT"
+#: Ports below this need privileges the CLI never takes, and the Console refuses them too.
+#: Must match cli_handoff.js CLI_MIN_CALLBACK_PORT.
+MIN_CALLBACK_PORT = 1024
 DEFAULT_API_URL = "https://api.xmemory.ai"
 
 #: Where MCP connections go. A separate origin from the API rather than a path on it,
@@ -776,7 +782,12 @@ def _curate_read(item: dict[str, Any], *, read_mode: str, verbose: bool) -> dict
     rr = item.get("reader_result")
     rr_dict = rr if isinstance(rr, dict) else {}
     curated: dict[str, Any]
-    if read_mode == "single":
+    if "reader_result" in item and rr is None:
+        # Preserve the server's explicit no-result signal. Converting None to
+        # an empty dict makes a zero-row read indistinguishable from an unknown
+        # or malformed ReaderResult shape.
+        curated = {"reader_result": None}
+    elif read_mode == "single":
         answer = _extract_single_answer(rr_dict)
         # No extractable answer string → emit the reader_result subtree so
         # the user still sees something truthful rather than `answer: null`.
@@ -1212,6 +1223,35 @@ def cmd_auth_status(args: argparse.Namespace) -> tuple[CliOutput, int]:
     )
 
 
+def _callback_port(args: argparse.Namespace) -> int:
+    """The port to bind the login callback to; ``0`` means "any free port".
+
+    Any free port is the default because it lets two logins run at once — one fixed port meant
+    the second could not bind. Pinning exists for the case where the port must be known before
+    the login starts, which an ``ssh -L`` tunnel to a remote dev box needs: the tunnel has to be
+    up first, so the port cannot be chosen after.
+    """
+    explicit = getattr(args, "callback_port", None)
+    if explicit is None:
+        from_env = os.environ.get(ENV_CALLBACK_PORT, "").strip()
+        if not from_env:
+            return _login.EPHEMERAL_CALLBACK_PORT
+        try:
+            explicit = int(from_env)
+        except ValueError:
+            # Bounded: this value is echoed back in a JSON error field and comes from the
+            # environment, so it is not something to reproduce in full.
+            shown = from_env if len(from_env) <= 32 else from_env[:32] + "…"
+            raise UsageError(f"${ENV_CALLBACK_PORT} must be a port number, got {shown!r}") from None
+    port = int(explicit)
+    # Below 1024 is refused rather than merely unbindable: the Console rejects such a callback
+    # too (WHATWG URL elides :80 entirely, so it never arrives as a port at all), and the login
+    # would fail later with nothing pointing at the cause. 0 stays legal — it means ephemeral.
+    if port != _login.EPHEMERAL_CALLBACK_PORT and not MIN_CALLBACK_PORT <= port <= 65535:
+        raise UsageError(f"callback port must be 0 or between {MIN_CALLBACK_PORT} and 65535, got {port}")
+    return port
+
+
 def _login_timeout(args: argparse.Namespace, *, default: float) -> float:
     """The ``--timeout`` value, or the per-path default when the flag was not passed.
 
@@ -1663,6 +1703,7 @@ def cmd_auth_login(args: argparse.Namespace) -> tuple[CliOutput, int]:
             verifier=verifier,
             on_url=on_url,
             timeout_s=_login_timeout(args, default=300.0),
+            callback_port=_callback_port(args),
             interactive=interactive,
             notify=_eprint,
         )
@@ -2548,6 +2589,16 @@ def _build_parser() -> argparse.ArgumentParser:
         add_help=False,
     )
     pal.add_argument("--no-browser", action="store_true", help="Print the URL only; do not open a browser")
+    pal.add_argument(
+        "--callback-port",
+        type=int,
+        default=None,
+        help=(
+            "Bind the login callback to this port instead of any free one "
+            f"(or ${ENV_CALLBACK_PORT}). Use when the port must be known in advance, e.g. an "
+            "ssh -L tunnel for remote development."
+        ),
+    )
     pal.add_argument(
         "--timeout",
         type=float,