@amd-gaia/gaia 0.1.1 → 0.2.0

package/SPEC.md

@@ -190,6 +190,44 @@ supervises the sidecar and does its own SHA-256 check on the binary it finds
 there; installing an already-verified binary at that path turns the daemon's fetch
 into a cache hit instead of a second multi-hundred-megabyte download.
 
+### 4.1 The `.installed` sentinel
+
+Installing the sidecar also writes `~/.gaia/agents/gaia/.installed`, the record
+the daemon and the TUI both read to answer "is this agent installed?". It is
+written on a **cache hit as well as a fresh download**, so an install staged by
+an earlier release repairs itself on the next run, and only when the fetch
+produced a runnable local install — that is, for the `sidecar` component (the
+TUI is not a hub agent) **and** for this host's own platform. A `--platform`
+fetch stages a binary for a different host; recording it would hand the daemon a
+wrong-architecture executable that re-hashes correctly and then fails to exec.
+
+```json
+{
+  "id": "gaia",
+  "version": "<sidecar componentVersion>",
+  "language": "python",
+  "installed_at": "<ISO-8601 UTC>",
+  "artifact_sha256": "<the verified SHA-256>",
+  "path": "<install directory>",
+  "artifact_kind": "binary",
+  "executable": "gaia-agent[.exe]"
+}
+```
+
+The shape is a cross-repo contract with `InstalledAgent.to_dict()` in
+`gaia.hub.installer`. Three fields are load-bearing:
+`gaia.daemon.sidecars.fetch._hub_installed_binary` ignores the install unless
+`artifact_kind` is `binary` and `executable` and `artifact_sha256` are non-empty,
+and it **re-hashes the binary and raises `IntegrityError` if the file no longer
+matches `artifact_sha256`** — so the recorded hash is the one actually verified,
+never the lock's nominal value. `executable` must be a bare filename;
+`installer.read_sentinel` discards a sentinel whose executable contains a path
+separator, which reads as "never installed".
+
+Without the sentinel the daemon sees no install and the TUI falls back to running
+`gaia-agent` as its own stdio child — spawning the REST sidecar over stdio and
+filling the chat with uvicorn's startup log.
+
 The TUI directory is keyed by `agentVersion` — this package's version, not the
 component's — so a bump of either never reuses the previous release's executable.
 
@@ -207,6 +245,11 @@ Both defaults are overridable (`--sidecar-dir`, `--cache-dir`).
 
 Served by `gaia_agent.server`. Bound to `127.0.0.1` only.
 
+Every request must carry a loopback `Host` header. A `Host` that is non-loopback,
+absent or empty is refused with `400` before routing — that check is what defeats
+DNS rebinding, so it fails closed rather than serving a request that simply omits
+the header.
+
 | Property           | Value                                   |
 | ------------------ | --------------------------------------- |
 | Default port       | `8141` (`DEFAULT_PORT` in `server.py`)  |
@@ -246,6 +289,15 @@ collapses the rest to a one-line menu entry (re-activated by calling
 disables it for the session and every body renders. Omitting it is a valid, explicit one-shot: nothing
 persists past that single turn, and the agent is not told otherwise.
 
+A retained session also carries a **project map** — up to 600 prompt tokens of
+directory shape, entry points, installed commands and platform quirks, present
+whenever the agent's working directory resolves to a code repository (a VCS
+directory or a recognised manifest at its root). `GAIA_PROJECT_ROOT=<path>`
+picks the project when the working directory is not it. If that repository has
+no code index, the first turn starts one in a background thread;
+`GAIA_PROJECT_MAP_AUTO_INDEX=0` disables that. Neither affects the wire
+contract — they change what the agent knows and what the first turn costs.
+
 A second `/query` for a `session_id` that already has a turn in flight gets
 `409 Conflict` — cancel the running turn or wait for it, then retry. A
 `/query` that needs a **new** session while every retained slot is busy and
@@ -253,12 +305,23 @@ none is idle enough to evict gets `503` with the reason in `detail` — a
 temporary, retryable condition, not a bug: wait for a turn to finish (or
 close an idle session) and retry. A
 `session_id` can also be evicted from the retention table under an idle
-timeout or an LRU cap on concurrent sessions; a `/query` that lands on an
+timeout (**4 hours** without a turn) or an LRU cap on concurrent sessions
+(**100**) — the two knobs that decide when the `503` above can happen at all
+(`session_registry.py`). Eviction is idle-only: a conversation still in use is
+never timed out mid-flight. A `/query` that lands on an
 evicted id gets a fresh agent (the conversation is not blocked) but the
 response stream's first event is a `{"type":"status","status":"warning",...}`
 telling the caller that per-turn state — most visibly any loaded skill — did
 not survive and should be reloaded.
 
+A second `/query` reusing a `run_id` that is still in flight gets `409` —
+`run_id` is caller-minted, so mint a fresh UUID per request; reusing one would
+leave the earlier run with no way to be cancelled. A `/query` supplying a `model`
+that differs from the one its `session_id` was built with also gets `409`: only
+agent construction reads a model, so the request cannot be honoured on the
+retained agent. Omit `model` to continue on the session's current one, or start a
+new `session_id` to switch.
+
 ### 5.3 Version gate
 
 `checkVersion()` reads `/version` and compares the **major** of `apiVersion`
@@ -266,13 +329,73 @@ against this package's `API_VERSION`. A differing major is a breaking contract
 change and raises `VersionMismatchError`. A higher minor with the same major is a
 backward-compatible addition and is accepted.
 
-### 5.4 No caller-auth token
-
-The email sidecar authenticates callers with a per-session bearer minted into
-`GAIA_EMAIL_SIDECAR_TOKEN`. `gaia_agent` has **no equivalent** at 0.1.1, so
-this package mints and sends nothing. When the sidecar grows one, it lands here as
-a spawn-time env var and a request header — a change to this section, not a new
-subsystem.
+### 5.4 Caller authentication
+
+Loopback binding is not access control: this sidecar exposes shell and file
+tools, so an unauthenticated port lets any page the user visits drive it. Three
+controls guard it, all in `gaia_agent.caller_auth`, which binds this sidecar's
+env-var names and exempt paths onto the shared mechanism in
+`gaia.sidecar.caller_auth`:
+
+1. **Per-session bearer token.** Every `/v1/gaia/*` request must carry
+   `Authorization: Bearer <token>`. The spawning parent supplies it one of two
+   ways: `GAIA_GAIA_SIDECAR_TOKEN_FILE` — the path to a `0600`, owner-only file
+   holding the token, which is the preferred channel because the secret never
+   sits in the environment — or `GAIA_GAIA_SIDECAR_TOKEN`, the token itself, the
+   legacy delivery. A request without it is **401**, with a `detail` naming both
+   env vars.
+2. **Host allowlist.** The `Host` header must be present *and* loopback
+   (`127.0.0.1`, `localhost`, `::1`); anything else — including an absent or
+   empty header — is **400**. This is what defeats DNS rebinding, where the
+   rebound request arrives with `Host: evil.com`, so it fails closed rather
+   than letting a caller opt out by omitting the header.
+3. **Origin rejection.** A request carrying a non-loopback browser `Origin` is
+   **403**. Non-browser clients send no `Origin` and are unaffected.
+
+`/health`, `/version`, and `/v1/gaia/version` are **token-exempt** — they are
+the probes a host polls during the attach handshake, before any token is in
+play, and none of them exposes user data or accepts work. Host and Origin still
+apply to them, so `waitForHealth` and `checkVersion` work against a
+token-protected sidecar without knowing the token.
+
+**Dev mode.** If neither env var is set the token check is skipped and the
+sidecar logs a loud warning saying so; Host and Origin are still enforced. That
+is the state a sidecar this package spawns comes up in, because `spawnSidecar`
+mints nothing — pass your own token through `spawnSidecar`'s `env` option to
+turn the check on. The shipped product does not rely on dev mode: the daemon
+mints a per-session token and passes it as `GAIA_GAIA_SIDECAR_TOKEN_FILE`
+(`gaia.daemon.sidecars.spec` mirrors both names as plain strings so core never
+imports this wheel).
+
+### 5.5 Other transports
+
+The HTTP server above is the surface this package drives, and everything in
+this document describes it. It is not the agent's only transport:
+`gaia_agent.stdio` runs the same agent over newline-delimited JSON on
+stdin/stdout — no port, no token, no discovery file. The terminal UI reaches it
+that way when it spawns the agent as a subprocess; an agent **installed** from
+the hub, which is what this package delivers, is supervised by the daemon over
+the HTTP surface above instead (§6.1).
+
+It emits the identical canonical event vocabulary, but its input channel accepts
+a JSON line carrying a `gaia_control` key, which gives it something HTTP does
+not have: a back-channel that can answer a confirmation prompt *while* a turn is
+in flight, and stop that turn (`cancel`) without ending the process — so loaded
+skills, "always" grants, history and the bypass mode survive a cancel. It also
+takes `--bypass-permissions` (start with gating off) and
+`--use-claude` / `--claude-model` (route chat to the Anthropic API instead of
+local Lemonade; embeddings stay on Lemonade either way). None of that is
+reachable over `/v1/gaia/query`.
+
+The stdio TUI also supports Local, Fireworks AI, and AMD LLM Gateway through
+Lemonade. `/model` lists downloaded local and discovered cloud chat models;
+`/model <id>` switches the live client while preserving conversation and skills.
+Cloud IDs (`fireworks.*`, `amd.*`) route through Lemonade without local model
+loading. Model-state status events identify the provider and remote inference.
+The TUI's `/provider` panel configures credentials directly with local Lemonade;
+keys never travel through stdio queries. These controls are not exposed over
+`/v1/gaia/query`. Lemonade may independently be configured to route a model
+remotely, so a local server URL alone does not establish local inference.
 
 ---
 
@@ -293,13 +416,23 @@ from `~/.gaia/agents/gaia/`. A sidecar spawned here would be a second process th
 TUI never talks to, competing for port `8141`.
 
 So `run`'s contribution to the sidecar is putting a **verified** binary where the
-daemon looks. Daemon and sidecar lifecycle belong to the daemon.
+daemon looks, and recording the install in `.installed` (§4.1) so the daemon and
+the TUI both see it. Daemon and sidecar lifecycle belong to the daemon.
 
 ### 6.2 `gaia serve` — the direct path
 
 `serve` fetches the sidecar and spawns it itself, for integrators who want the
-REST surface without a daemon or a UI. This path owns the process fully: spawn →
-`waitForHealth` → `checkVersion` → run until interrupted → tree-kill.
+REST surface without a daemon or a UI. This path owns the process fully:
+port pre-flight → spawn → `waitForHealth` → `checkVersion` → run until
+interrupted → tree-kill.
+
+The port is checked **before** the spawn, and a taken port raises
+`PortInUseError` without starting anything. That ordering is the guarantee: the
+frozen sidecar spends seconds unpacking before it attempts its bind, while an
+incumbent answers `/health` in milliseconds — so a post-spawn check alone would
+see a healthy port and a still-alive child, and hand back a handle for a server
+it does not own. `assertOurs` and the re-probe after a failed health wait remain
+as backstops for the narrower window where something binds after the pre-flight.
 
 ### 6.3 Tree-kill
 
@@ -325,8 +458,8 @@ failed start never leaks a process.
 | Code    | Meaning                                                                 |
 | ------- | ----------------------------------------------------------------------- |
 | `0`     | Success                                                                 |
-| `1`     | A typed failure: `IntegrityError`, `PlatformError`, `HealthTimeoutError`, `VersionMismatchError`, `BinaryNotFoundError`, or an unexpected error |
-| `2`     | Usage error: unknown command, unknown `--component`, invalid `--port`    |
+| `1`     | A typed failure: `IntegrityError`, `PlatformError`, `HealthTimeoutError`, `VersionMismatchError`, `BinaryNotFoundError`, `PortInUseError`, `SidecarExitedError`, `MalformedResponseError`, or an unexpected error |
+| `2`     | Usage error: unknown command, invalid `--port`, or a flag the command does not read (`run --port`, `serve --component`, `serve --cache-dir`, `run`/`serve` `--platform`), an unknown `--component`, or a non-https `--base-url` without `--allow-insecure-base-url` |
 | *other* | From `run`: the TUI's own exit code, propagated verbatim                 |
 
 A TUI killed by a signal propagates as `128 + signum` (the shell convention), so a
@@ -340,12 +473,15 @@ All extend `GaiaError`, so `instanceof GaiaError` catches any of ours.
 
 | Class                  | Raised when                                                    |
 | ---------------------- | -------------------------------------------------------------- |
-| `IntegrityError`       | A download's SHA-256 does not match the lock                   |
+| `IntegrityError`       | A download's SHA-256 does not match the lock, or a resolved binary's does not |
 | `PlatformError`        | Unsupported platform, missing/incomplete entry, placeholder hash, malformed lock |
 | `HealthTimeoutError`   | The sidecar did not report healthy within the timeout          |
 | `VersionMismatchError` | `apiVersion` major differs from this package's                 |
 | `BinaryNotFoundError`  | A binary is absent from disk when spawning                     |
+| `PortInUseError`       | The bind port was already taken; nothing was spawned            |
+| `SidecarExitedError`   | The spawned sidecar died while the port answered — something else owns it |
 | `HttpError`            | A non-2xx from a sidecar probe                                 |
+| `MalformedResponseError` | A 2xx from a sidecar probe whose body is not JSON            |
 
 Per the repo's no-silent-fallbacks rule, every message names what failed, what to
 do, and where to look next.
@@ -370,7 +506,8 @@ do, and where to look next.
 Exported from the package root — see `src/index.ts`.
 
 **Fetch:** `fetchAll`, `fetchBinary`, `verifySha256`, `fileSha256`,
-`binaryExists`, `defaultCacheDir`, `daemonSidecarCacheDir`.
+`binaryExists`, `defaultCacheDir`, `daemonSidecarCacheDir`,
+`INSTALLED_SENTINEL_NAME`, `SIDECAR_AGENT_ID`.
 
 **Lifecycle:** `spawnSidecar`, `startSidecar`, `waitForHealth`, `checkVersion`,
 `health`, `version`, `shutdown`, `runTui`, `resolveSidecarPath`, `resolveTuiPath`,
@@ -384,6 +521,13 @@ Exported from the package root — see `src/index.ts`.
 **Constants:** `AGENT_ID`, `API_VERSION`, `DEFAULT_HOST`, `DEFAULT_PORT`,
 `RESERVED_PORT`.
 
+`resolveSidecarPath` / `resolveTuiPath` re-verify the file's SHA-256 against
+`binaries.lock.json` before returning a path that is about to be spawned — the
+cache path is predictable, so anything able to write it would otherwise get code
+run. That makes them **O(size of the binary)**, not a cheap path join: resolve
+once at startup, not per request. Pass `{ verify: false }` for a binary you built
+yourself, which no lock describes, and `{ lock }` to reuse an already-loaded lock.
+
 ---
 
 ## 11. Logging

package/binaries.lock.json

@@ -1,76 +1,76 @@
 {
   "schemaVersion": "3.0",
-  "agentVersion": "0.1.1",
+  "agentVersion": "0.2.0",
   "components": {
     "sidecar": {
-      "componentVersion": "0.1.1",
-      "baseUrl": "https://hub.amd-gaia.ai/agents/gaia/0.1.1",
+      "componentVersion": "0.2.0",
+      "baseUrl": "https://hub.amd-gaia.ai/agents/gaia/0.2.0",
       "platforms": {
         "win32-x64": {
           "filename": "gaia-agent-win32-x64.exe",
           "executable": "gaia-agent.exe",
-          "sha256": "416ed0e24cd3457ae66acd1caaf8337d0761f093b86813d8640b7cad6236856a",
-          "size": 90667208
+          "sha256": "5d2ea1a5fd40e2399ba2bf50aec80b44d89c7e7bfdbad846c050f683fc8bf842",
+          "size": 103531825
         },
         "darwin-arm64": {
           "filename": "gaia-agent-darwin-arm64",
           "executable": "gaia-agent",
-          "sha256": "f962b8c7ce042938a940a01fcea5c94fc0ff33b4c05c02770804c89c31aaa1c2",
-          "size": 74152544
+          "sha256": "fbe526e7eb044a2ce633fbd487a1ae75001683eff190d8359eabf9ccc7196069",
+          "size": 88311472
         },
         "darwin-x64": {
           "filename": "gaia-agent-darwin-x64",
           "executable": "gaia-agent",
-          "sha256": "2f001c8c8e75b286c758269d0fc22fe57ef68ef5ee59476d960531e363b73c25",
-          "size": 78642224
+          "sha256": "b02731c786d79d7f5e644662238a64d1761eb6a23d421821df46e6a8282b585d",
+          "size": 94294544
         },
         "linux-x64": {
           "filename": "gaia-agent-linux-x64",
           "executable": "gaia-agent",
-          "sha256": "b704f83a4beaa4654a37cf8e2fcc7429cd6da91f7431c3381e7005370e760c7a",
-          "size": 122029424
+          "sha256": "6c68a22c25954ea3c8d2a0a541bc04eba2401281d2a2b6448007983acd050a00",
+          "size": 140015368
         }
       }
     },
     "tui": {
-      "componentVersion": "0.23.0",
-      "baseUrl": "https://hub.amd-gaia.ai/agents/terminal-hub/0.23.0",
+      "componentVersion": "0.24.1",
+      "baseUrl": "https://hub.amd-gaia.ai/agents/terminal-hub/0.24.1",
       "platforms": {
         "win32-x64": {
           "filename": "gaia-win-x64.exe",
           "executable": "gaia-tui.exe",
-          "sha256": "aad0c38c5c59e8107b608981f34608ee08feb7e5965de1cfcb929a49f21258ca",
-          "size": 19433984
+          "sha256": "ce07269674de6773fd304d67eef3ff19cd578f447fc90a13f0309a61ae5ef504",
+          "size": 19213824
         },
         "win32-arm64": {
           "filename": "gaia-win-arm64.exe",
           "executable": "gaia-tui.exe",
-          "sha256": "2f78c8128a8ad6d17d51938de12ed7aa29ceadb642af8d6e929920fe17e2463c",
-          "size": 17975808
+          "sha256": "41f2a25b2bf15bea6f70626bb519496aeb822cc2629dd3529e325319b7abb3ca",
+          "size": 17744384
         },
         "darwin-arm64": {
           "filename": "gaia-darwin-arm64",
           "executable": "gaia-tui",
-          "sha256": "766100459d22d9886a8d7839d5eddffb2a51134be76a57360b1584755be3cef1",
-          "size": 17896354
+          "sha256": "dc334e89cebefaa2cc5117942ccbc4dc391034c3013ebf02d2bebf87f5e99a5a",
+          "size": 17499282
         },
         "darwin-x64": {
           "filename": "gaia-darwin-x64",
           "executable": "gaia-tui",
-          "sha256": "494197bd2bf245df94de9361a274723536e73f275bbb92efc1c4db027cc08d9e",
-          "size": 19003168
+          "sha256": "9af8c1fefeff4814bae6bbe9698ffaac3b59f248a422525e9f9b50812f5435da",
+          "size": 18629664
         },
         "linux-x64": {
           "filename": "gaia-linux-x64",
           "executable": "gaia-tui",
-          "sha256": "d913c4cc4943f6a5a9be737cf397ad2a05e013e55a7880c27d4ddef973ee16f4",
-          "size": 18661538
+          "sha256": "ef80198f3c4f6c2a4e92993fe19257c67cf009e29632398642549274ef8c2ffa",
+          "size": 18292898
         },
         "linux-arm64": {
           "filename": "gaia-linux-arm64",
           "executable": "gaia-tui",
-          "sha256": "c8faee8cc7281819042d9e123d5a68b6ccfe4afa3d92d5fa3b2f42770df1d894",
-          "size": 17432738
+          "sha256": "31d9e1fee15e4a21e677ca7abb707fcf08257d5e7f50f1baa71bc7159335c170",
+          "size": 17105058
         }
       }
     }

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;GAWG;AA8BH,UAAU,UAAU;IAClB,CAAC,EAAE,MAAM,EAAE,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,mEAAmE;IACnE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAaD,4EAA4E;AAC5E,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuCpD;AA0ED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,MAAM,GAAG,SAA+B,EACjD,KAAK,GAAE,MAAM,GAAG,SAA2B,GAC1C,MAAM,GAAG,SAAS,CAmBpB;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAQnG;AAqJD,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC1D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;GAWG;AA8BH,UAAU,UAAU;IAClB,CAAC,EAAE,MAAM,EAAE,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,mEAAmE;IACnE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAaD,4EAA4E;AAC5E,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuCpD;AAsID;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,MAAM,GAAG,SAA+B,EACjD,KAAK,GAAE,MAAM,GAAG,SAA2B,GAC1C,MAAM,GAAG,SAAS,CAsBpB;AA+CD,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAUnG;AAuKD,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkC1D"}

package/dist/cli.js

@@ -13,7 +13,7 @@
  * written, and a mismatch or a placeholder hash aborts the run. There is no
  * "continue anyway" path.
  */
-import { realpathSync } from "node:fs";
+import { readFileSync, readdirSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { GaiaError } from "./errors.js";
@@ -88,7 +88,10 @@ Usage:
 
 run options:
   --base-url <url>     Override the per-component download base URL from
-                       binaries.lock.json (applies to every component fetched)
+                       binaries.lock.json (applies to every component fetched).
+                       Must be https unless --allow-insecure-base-url is given.
+  --allow-insecure-base-url
+                       Permit a non-https --base-url (a trusted local mirror)
   --cache-dir <dir>    Where to cache the TUI binary
   --sidecar-dir <dir>  Where to install the agent sidecar
                        (default ~/.gaia/agents/gaia — the daemon's own cache)
@@ -102,6 +105,8 @@ fetch options:
 
 serve options:
   --port <n>           Bind port (default ${DEFAULT_PORT}; ${RESERVED_PORT} is reserved and refused)
+  --base-url, --sidecar-dir, --force as above. \`serve\` never downloads the TUI,
+  so --cache-dir is refused rather than ignored.
 
 Notes:
   * No binaries are committed to the repo. Every download is SHA-256 verified
@@ -116,19 +121,69 @@ Notes:
 `;
 const flagStr = (args, k) => typeof args.flags[k] === "string" ? args.flags[k] : undefined;
 /**
- * Shared download options. `--platform` is accepted only by `fetch`: `run` and
- * `serve` execute what they download, and honouring a foreign platform there
- * would write a wrong-architecture binary into the daemon's cache and then try
- * to spawn it.
+ * Which commands actually READ each value flag, and why the others refuse it.
+ * A flag a command ignores is worse than one it rejects: `run --port 9000`
+ * used to parse fine and silently come up on the default port.
  */
+const VALUE_FLAG_SCOPE = {
+    "base-url": { commands: ["run", "fetch", "serve"], why: "it only affects downloads" },
+    "sidecar-dir": { commands: ["run", "fetch", "serve"], why: "it only affects downloads" },
+    platform: {
+        commands: ["fetch"],
+        why: "`run` and `serve` execute the binary, so it must be built for this host " +
+            `(${currentPlatformKey()})`,
+    },
+    port: {
+        commands: ["serve"],
+        why: "only `serve` binds a port; `run` reaches the agent through the daemon, which picks its own",
+    },
+    component: {
+        commands: ["fetch"],
+        why: "`run` needs both binaries and `serve` needs the sidecar, so neither can fetch a subset",
+    },
+    "cache-dir": {
+        commands: ["run", "fetch"],
+        why: "it caches the TUI, which `serve` never downloads (use --sidecar-dir)",
+    },
+};
+/** Refuse a value flag the chosen command would otherwise silently ignore. */
+function assertFlagsInScope(args, cmd) {
+    for (const [flag, scope] of Object.entries(VALUE_FLAG_SCOPE)) {
+        if (args.flags[flag] === undefined || scope.commands.includes(cmd))
+            continue;
+        throw new UsageError(`--${flag} is not valid for \`gaia ${cmd}\` — ${scope.why}. ` +
+            `It is accepted by: ${scope.commands.map((c) => `\`gaia ${c}\``).join(", ")}.`);
+    }
+}
+/**
+ * Require https for a download source. Integrity still holds over plaintext
+ * (the SHA is pinned), but a MITM then surfaces as a baffling IntegrityError
+ * instead of the transport failure it is.
+ */
+function checkedBaseUrl(args) {
+    const raw = flagStr(args, "base-url");
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new UsageError(`--base-url '${raw}' is not a valid absolute URL (expected e.g. https://host/path).`);
+    }
+    if (parsed.protocol !== "https:" && !args.flags["allow-insecure-base-url"]) {
+        throw new UsageError(`--base-url '${raw}' uses ${parsed.protocol}, not https. Downloads are ` +
+            "SHA-256 verified either way, but plaintext turns tampering into a " +
+            "confusing integrity failure instead of a transport error. Use an https " +
+            "URL, or pass --allow-insecure-base-url for a trusted local mirror.");
+    }
+    return raw;
+}
+/** Shared download options. Scope and scheme are validated before we get here. */
 function downloadOptions(args, allowPlatform = false) {
     const platformKey = flagStr(args, "platform");
-    if (platformKey !== undefined && !allowPlatform) {
-        throw new UsageError("--platform is only valid for `gaia fetch`. `run` and `serve` execute the " +
-            `binary, so it must be built for this host (${currentPlatformKey()}).`);
-    }
     return {
-        baseUrl: flagStr(args, "base-url"),
+        baseUrl: checkedBaseUrl(args),
         ...(allowPlatform && platformKey !== undefined ? { platformKey } : {}),
         force: Boolean(args.flags["force"]),
         tuiDir: flagStr(args, "cache-dir"),
@@ -148,8 +203,10 @@ export function pathWithoutOwnShim(rawPath = process.env["PATH"], argv1 = proces
         return rawPath;
     const sep = process.platform === "win32" ? ";" : ":";
     let ownBinDir;
+    let ownName;
     try {
         ownBinDir = path.resolve(path.dirname(argv1));
+        ownName = path.basename(argv1);
     }
     catch {
         return rawPath;
@@ -160,14 +217,65 @@ export function pathWithoutOwnShim(rawPath = process.env["PATH"], argv1 = proces
             ? resolved.toLowerCase() === ownBinDir.toLowerCase()
             : resolved === ownBinDir;
     };
-    return rawPath
-        .split(sep)
-        .filter((d) => d !== "" && !same(d))
-        .join(sep);
+    const entries = rawPath.split(sep).filter((d) => d !== "");
+    const ours = entries.filter((d) => same(d) || shimTargetsScript(d, argv1));
+    const kept = entries.filter((d) => !ours.includes(d));
+    const shared = ours.filter((d) => !isExclusivelyOurs(d, same(d) ? ownName : "gaia"));
+    return [...kept, ...shared].join(sep);
+}
+/** Match npm's symlink or generated cmd/PowerShell wrapper to this script. */
+function shimTargetsScript(dir, script) {
+    const canonical = (file) => {
+        try {
+            const resolved = realpathSync(file);
+            return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+        }
+        catch {
+            return undefined; // no resolvable executable at this candidate
+        }
+    };
+    const expected = canonical(script);
+    if (!expected)
+        return false;
+    for (const name of ["gaia", "gaia.cmd", "gaia.ps1"]) {
+        const shim = path.join(dir, name);
+        if (canonical(shim) === expected)
+            return true;
+        if (!name.includes("."))
+            continue;
+        let contents;
+        try {
+            contents = readFileSync(shim, "utf8");
+        }
+        catch {
+            continue; // this PATH directory does not contain a readable wrapper
+        }
+        for (const match of contents.matchAll(/["'](?:%dp0%|\$basedir)[\\/]([^"']+)["']/gi)) {
+            const target = path.resolve(dir, match[1].replace(/[\\/]/g, path.sep));
+            if (canonical(target) === expected)
+                return true;
+        }
+    }
+    return false;
+}
+/** True when every file in `dir` is a shim for `name` (`gaia`, `gaia.cmd`, …). */
+function isExclusivelyOurs(dir, name) {
+    const stem = name.replace(/\.(cmd|bat|ps1|exe)$/i, "");
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return false; // unreadable → treat as shared, the non-destructive branch
+    }
+    return (entries.length > 0 &&
+        entries.every((e) => e.replace(/\.(cmd|bat|ps1|exe)$/i, "") === stem));
 }
 /** Validate `--port`. Rejects out-of-range values and the reserved port. */
 export function resolvePort(raw) {
-    const port = typeof raw === "string" ? Number(raw) : DEFAULT_PORT;
+    // Strict digits, not Number(): that accepts "0x2710", " 80 ", and "1e3",
+    // so a typo would quietly bind a port the user never named.
+    const port = typeof raw === "string" ? (/^\d+$/.test(raw) ? Number(raw) : NaN) : DEFAULT_PORT;
     if (!Number.isInteger(port) || port <= 0 || port > 65535 || port === RESERVED_PORT) {
         return {
             error: `--port must be a port in 1..65535 and not ${RESERVED_PORT} (got ${String(raw)})`,
@@ -231,6 +339,7 @@ async function cmdFetch(args) {
     }, null, 2) + "\n");
     return 0;
 }
+const SERVE_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 async function cmdServe(args) {
     const parsed = resolvePort(args.flags["port"]);
     if ("error" in parsed) {
@@ -257,11 +366,17 @@ async function cmdServe(args) {
         process.stdout.write(`\n  ▸ GAIA agent: ${sidecar.baseUrl}/v1/gaia/query\n`);
         process.stdout.write(`    Health:     ${sidecar.baseUrl}/health\n`);
         process.stdout.write("    Lemonade must be running for live queries. Ctrl+C to stop.\n\n");
-        await new Promise((resolve) => {
+        let stop;
+        const stopped = new Promise((resolve) => {
             let stopping = false;
-            const stop = () => {
-                if (stopping)
-                    return; // a second signal must not re-enter shutdown
+            stop = () => {
+                if (stopping) {
+                    // Absorbed, so say what is happening — otherwise a repeat Ctrl+C
+                    // during a slow teardown just looks like a frozen terminal.
+                    process.stderr.write(`[gaia] already stopping the sidecar (pid ${String(sidecar.child.pid)}); ` +
+                        "waiting for its process tree to exit ...\n");
+                    return;
+                }
                 stopping = true;
                 process.stderr.write("\n[gaia] stopping the sidecar ...\n");
                 void shutdown(sidecar).catch(() => undefined).finally(resolve);
@@ -270,9 +385,18 @@ async function cmdServe(args) {
             // otherwise hit Node's default disposition and kill us mid-teardown,
             // orphaning the detached sidecar tree on port 8141. The `stopping` guard
             // absorbs the repeats.
-            for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+            for (const sig of SERVE_SIGNALS)
                 process.on(sig, stop);
         });
+        try {
+            await stopped;
+        }
+        finally {
+            // Left installed, they would swallow every later signal AND suppress
+            // Node's default disposition, so Ctrl+C would stop working entirely.
+            for (const sig of SERVE_SIGNALS)
+                process.removeListener(sig, stop);
+        }
         return 0;
     }
     catch (e) {
@@ -317,6 +441,7 @@ export async function main(argv) {
         throw new UsageError(`unexpected argument${extra.length > 1 ? "s" : ""} ${extra.map((a) => `'${a}'`).join(", ")}. ` +
             "Arguments for the terminal UI go after a bare `--`.");
     }
+    assertFlagsInScope(args, cmd);
     switch (cmd) {
         case "run":
             return cmdRun(args);