xmemcli 0.0.10__tar.gz → 0.0.12__tar.gz

{xmemcli-0.0.10 → xmemcli-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xmemcli
-Version: 0.0.10
+Version: 0.0.12
 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
@@ -15,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>
@@ -97,7 +97,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.10**.
+Version: **0.0.12**.
 
 
 ---
@@ -108,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).
@@ -129,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
@@ -137,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
 ```
 
@@ -161,6 +161,8 @@ 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`.
 
+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.
 
 ## Identity — `/whoami`
@@ -181,7 +183,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 +193,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.10` (see `xmemcli version`)
+**Version:** `0.0.12` (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 +412,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. |
@@ -513,7 +515,9 @@ 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.
+
+See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 
 ---
 
@@ -594,6 +598,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 |
@@ -601,6 +606,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.10 → xmemcli-0.0.12}/README.md

@@ -7,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>
@@ -89,7 +89,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.10**.
+Version: **0.0.12**.
 
 
 ---
@@ -100,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).
@@ -121,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
@@ -129,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
 ```
 
@@ -153,6 +153,8 @@ 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`.
 
+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.
 
 ## Identity — `/whoami`
@@ -173,7 +175,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 +185,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.10` (see `xmemcli version`)
+**Version:** `0.0.12` (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 +404,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. |
@@ -505,7 +507,9 @@ 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.
+
+See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 
 ---
 
@@ -586,6 +590,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 |
@@ -593,6 +598,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.10 → xmemcli-0.0.12}/pyproject.toml

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

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

{xmemcli-0.0.10 → xmemcli-0.0.12}/xmemcli/__init__.py

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

{xmemcli-0.0.10 → xmemcli-0.0.12}/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.10 → xmemcli-0.0.12}/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.10 → xmemcli-0.0.12}/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.10 → xmemcli-0.0.12}/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.10 → xmemcli-0.0.12}/xmemcli/_version.py

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

{xmemcli-0.0.10 → xmemcli-0.0.12}/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
 --------------------
@@ -149,6 +152,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,
@@ -743,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)
 
 
@@ -1116,6 +1141,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:
@@ -1217,6 +1245,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.
 
@@ -1409,6 +1466,7 @@ 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
@@ -1606,7 +1664,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",
             ),
@@ -1668,6 +1726,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,
         )
@@ -2553,6 +2612,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,