@amd-gaia/gaia 0.1.1 → 0.3.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,11 +245,16 @@ 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`)  |
 | Reserved port      | `4001` — refused with a `RangeError`    |
-| Contract version   | `API_VERSION = "2.12"`                  |
+| Contract version   | `API_VERSION = "2.17"`                  |
 | Agent id / prefix  | `gaia` → `/v1/gaia/...`                 |
 
 ### 5.1 Endpoints
@@ -222,13 +265,67 @@ Served by `gaia_agent.server`. Bound to `127.0.0.1` only.
 | `GET`  | `/version`                       | Contract probe. `{ "apiVersion", "agentVersion" }` |
 | `GET`  | `/v1/gaia/version`               | The TUI's negotiation probe                    |
 | `GET`  | `/v1/gaia/init`                  | Readiness detail (Lemonade, model, connectors) |
+| `GET`  | `/v1/gaia/memory`                | The `/memory` snapshot (contract ≥ 2.13)       |
+| `GET`  | `/v1/gaia/skills`                | The skills the agent can load (contract ≥ 2.17) |
 | `POST` | `/v1/gaia/query`                 | The streaming surface (`text/event-stream`)    |
 | `POST` | `/v1/gaia/query/{run_id}/cancel` | Cancel a run by its host-minted `run_id`       |
 | `POST` | `/v1/gaia/query/{run_id}/respond`| Answer a mid-run question                      |
+| `POST` | `/v1/gaia/query/{run_id}/tool_decision` | Answer a confirmation-gated tool (≥ 2.14) |
+| `POST` | `/v1/gaia/sessions/{session_id}/bypass` | Run gated tools without asking, for one session (≥ 2.14) |
+| `POST` | `/v1/gaia/query/{run_id}/followup`| Add to a run already in flight (contract ≥ 2.15) |
+
+#### `/query` request body
+
+The full, machine-readable contract — every field, type, and which are
+required — is the committed
+[`openapi.gaia.json`](https://github.com/amd/gaia/blob/main/hub/agents/gaia/python/openapi.gaia.json),
+regenerated from the live routes by `python -m gaia_agent.export_openapi` and
+checked for drift in CI — the same pattern as the email agent's own
+`openapi.email.json`. Required: **`query`**, **`run_id`**,
+**`context`** — `additionalProperties: false`, so an unrecognized field or a
+missing required one is `422` before the agent runs. `run_id` must parse as a
+UUID (`uuid.UUID(v)`); a non-UUID string is also `422`. Everything else
+(`model`, `provider`, `max_steps`, `session_id`, `can_answer_questions`,
+`documents`) is optional.
+
+`documents` (contract ≥ 2.16) carries the absolute paths of the files the user
+attached to the conversation. Send the whole set on every turn. Before the turn
+runs, the agent indexes the ones it has not indexed yet, so a file attached
+mid-conversation is read on the next turn. Each path is granted as that exact
+file, never its folder. A relative path is a `422`. A missing file, a folder, or
+a secret the path policy refuses is reported as not indexed in the turn's
+`index_documents` step, and the turn still runs. Pre-2.16 binaries `422` the
+field, so probe `/version` before sending it.
+
+```json
+{
+  "query": "What's in this directory?",
+  "run_id": "5b1f6e2a-7c34-4b4d-9b3e-2b6d9a7a1c3e",
+  "context": [],
+  "session_id": "my-session-1",
+  "can_answer_questions": true
+}
+```
 
 `/health` is liveness only. It says nothing about whether Lemonade is up or a
 model is loaded — `/v1/gaia/init` answers that.
 
+`GET /v1/gaia/memory` returns the read-only snapshot behind the TUI's
+`/memory` view: `{ "available", "reason", "stats", "contexts", "shown",
+"total", "items" }`. `available: false` means the session has no live memory
+store (Lemonade down, embedding model not pulled, disabled via env) — `reason`
+names why, so an outage never renders as "you have no memories". This is the
+daemon-transport counterpart of the stdio `MEMORY_DUMP_QUERY` sentinel; both
+paths call the same `build_memory_dump()` and return the identical shape.
+
+`GET /v1/gaia/skills` (contract ≥ 2.17) lists the skills the agent can load:
+`{ "skills": [{ "name", "description", "version", "tier", "tools", "path" }],
+"invalid": { "<folder>": "<why it failed to parse>" } }`. It reads the same
+roots the agent does — its bundled skills, `~/.gaia/skills`, Claude Code skill
+folders — so a host without the Python package (the bundled skills live inside
+the binary) can still show them. A skill root that cannot be read is a `500`
+naming it.
+
 ### 5.2 `session_id` and agent retention
 
 `POST /v1/gaia/query` accepts an optional `session_id` in the request body.
@@ -236,29 +333,83 @@ model is loaded — `/v1/gaia/init` answers that.
 whole conversation.** Contract ≥ 2.12 resolves `session_id` to a *retained*
 agent instead of a throwaway built fresh per call — indexed documents and
 `load_skill` state only survive between turns when the same `session_id`
-threads them together.
+threads them together. A `session_id` must be 1–128 characters from
+`A-Z a-z 0-9 . _ -`, not only dots (a UUID works); any other value is a **400**
+naming the allowed characters, on `/query` and on `/sessions/{session_id}/bypass`.
+Omitting it is a valid, explicit one-shot: nothing persists past that single
+turn, and the agent is not told otherwise.
+
+Internal explicit deletion follows the same idle-only rule as eviction: it returns
+`False` for an absent or busy session and preserves a running agent. Successful
+deletion claims the turn lock before removal and closes outside the registry lock.
+
+A skill **captured** in-conversation (the `capture_skill` tool — itself
+confirmation-gated, so over `/query` it needs a session that can answer) loads
+**instruction-only** until a human runs `gaia skill promote <name>` in a
+terminal: `load_skill` injects its body but defers registering any tools it
+declares, and reports the deferral in its result. Integrators must not expect
+a captured skill's `<skill>/<tool>` names to exist before that promote.
 
 A retained skill stays *loaded* but its body is not necessarily in the prompt
 every turn: the agent selects per turn which loaded bodies match the query and
 collapses the rest to a one-line menu entry (re-activated by calling
 `load_skill` again). `GAIA_DYNAMIC_SKILLS=0` disables the selection;
 `GAIA_DYNAMIC_SKILLS_TAU=<float>` overrides its threshold; an embedder outage
-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.
+disables it for the session and every body renders.
+
+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 `search_code_index` builds one;
+`GAIA_PROJECT_MAP_AUTO_INDEX=1` builds it in a background thread at task start
+instead. The same repository check also
+makes `run_shell_command` always-on for the session instead of semantically
+selected. Neither affects the wire contract — they change what the agent
+knows, what tools it is offered, 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
+`409 Conflict` — cancel the running turn or wait for it, then retry. Once that
+turn has been cancelled, the new `/query` is held until it finishes its
+in-flight model call (up to **240 s**) and then runs, instead of getting `409`;
+only a cancelled turn that outlasts the wait still gets `409`. A
 `/query` that needs a **new** session while every retained slot is busy and
 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 **switches the retained
+agent in place** (≥ 2.14), so the conversation and any loaded skills survive the
+change; the same machinery the stdio transport's `/model` uses. A switch that
+fails — a missing Claude credential, an unknown local model — is a `409` naming
+the reason, and leaves the session on its previous model. The session records its
+`provider` too: a turn naming a different `provider` switches it the same way,
+onto that turn's `model` or, if it names none, the provider's default model. A
+`model` from the other provider than the one named (a `claude-*` id with
+`"lemonade"`, or a non-Claude id with `"claude"`) is a `400` on a new session and
+an existing one alike, before anything is built or switched.
+
+`provider` is optional, and an omitted one is **not** read as `"lemonade"` — it
+means "whatever the `model` implies", so a `claude-*` id alone reaches Anthropic
+and any other id runs locally. The `400` above therefore fires only when a
+request names a `provider` that disagrees with its `model`; there is no pair to
+disagree when only one is given. On a retained session, omitting both leaves the
+session on the provider it is already using, so an ordinary follow-up turn never
+moves a Claude conversation back to Lemonade.
+
 ### 5.3 Version gate
 
 `checkVersion()` reads `/version` and compares the **major** of `apiVersion`
@@ -266,16 +417,163 @@ 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).
+
+**Child processes.** The programs the agent starts — shell commands, MCP
+servers, CLI installs and sign-ins, native hub agents, media tools, the Lemonade
+server — never inherit the sidecar token or GAIA's other internal credentials
+(the model-broker token, custody secret and engineering pairing token): their
+environment comes from `gaia.env.child_env`, which also drops any name listed
+in `GAIA_CHILD_ENV_DENY` (comma or space separated). User credentials such as `GH_TOKEN` pass through unchanged.
+`GAIA_NO_DOTENV=1` in the sidecar's launch environment stops it loading `.env`
+files; a `.env` file cannot set that switch itself.
+
+### 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: a back-channel that answers a
+confirmation prompt *while* a turn is in flight, toggles full access or
+"accept edits" (file edits inside the starting folder run unasked; commands still
+ask), and stops a turn (`cancel`) without ending the process — so loaded skills,
+"always" grants, history and the permission mode survive a cancel.
+
+Contract 2.14 gave the HTTP surface the same three capabilities per run and per
+session — `/tool_decision`, `/sessions/{id}/bypass` (the route keeps its
+original spelling), and `provider: "claude"`. What remains stdio-only is the
+*launch* form of those switches: `--full-access` starts a process with gating
+already off, `--accept-edits` starts it in accept-edits mode, and `--use-claude` / `--claude-model` pin the backend for the life
+of the process (embeddings stay on Lemonade either way).
+
+The stdio TUI also supports Local, Fireworks AI, and AMD LLM Gateway through
+Lemonade. `/model` lists downloaded local and discovered cloud chat models,
+grouped by provider, with `(default)` beside the configured default model;
+`/model <id>` switches the live client while preserving conversation and skills.
+The switch reply is one line naming the model, where it runs, and, for a cloud
+model, that messages and anything read from files or memory are sent there.
+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.
+
+`--bypass-permissions` turns off more than the prompt. It also lifts the shell
+tool's own guardrails for the session: the shell-only operators — redirection
+(`>`, `>>`, `<`), backgrounding (`&`), substitution (`` ` ``, `$()`) and the
+newline — parse and run, chaining (`&&`, `||`, `;`, `|`) already ran by
+default, the read-only binary allowlist is replaced by a developer set
+(`node`, `npm`, `make`, `cmake`, `go`, `cargo`, `sed`, `awk`, `curl`, `sleep`,
+`timeout`, `export`, `cp`, `mv`, plus `python`/`python3`/`pytest`/`gh`/`git`,
+which already had their own paths), and the shell rate limit is dropped. `git`
+being in that set means its policy's outright refusals — push, reset, rebase —
+also stop applying under bypass. That is
+arbitrary code execution in the working directory, which is why it exists only
+on this transport: one local parent process on a private pipe. It is **not**
+reachable over HTTP, and the request body cannot ask for it —
+`POST /v1/gaia/sessions/{id}/bypass` stops an HTTP session's approval prompts
+but never lifts these shell gates. `rm` is excluded
+from the developer set — not a boundary, since anything in the set can delete a
+file, but a tripwire against an accidental recursive delete. Redirection has one
+exception: a command that is nothing but a skill-granted CLI runs argv-only
+rather than through a shell, so a `>` there is refused with an explanation
+instead of reaching the binary as a literal argument.
+
+Every shell command run under bypass is recorded with its full arguments and its
+per-segment breakdown in `~/.gaia/cache/file_audit.log` — skipping the prompt
+does not skip the record. Treat that file as sensitive; arguments are verbatim.
+The host can toggle bypass mid-session over `gaia_control`, and the shell gates
+follow on the very next command.
+
+`--use-claude` is the one with a reach beyond the machine, and it cannot be
+turned on for what this package delivers: the terminal UI **refuses** the launch
+flag for a daemon-transport agent, with an error saying so, because it pins the
+backend for the life of the process and the daemon relay has no such lever.
+
+That is a limit on the *launch flag*, not on the agent. Since contract 2.14 a
+caller can ask for Anthropic per request with `/query`'s `provider` field (§5.2),
+so local inference is this package's **default**, not a property of the transport
+that nobody can change. Anything reaching Anthropic is named by the request that
+asked for it.
 
 ---
 
+### 5.6 Adding to a turn already running
+
+`POST /v1/gaia/query/{run_id}/followup` with `{ "text": "…" }` hands a live run
+something the user typed after it started. Contract ≥ 2.15.
+
+It is not a second turn and not an interrupt. The run keeps going on its
+existing SSE stream; the agent folds the text into that turn's context at its
+next agent-loop step boundary, labelled as arriving mid-task, and answers it
+alongside the work already in progress. A five-minute turn can therefore be
+corrected ("actually, only the unread ones") while it is still running, instead
+of the correction waiting out the turn it was meant to change.
+
+Two refusals, both loud, because the caller has already taken the message from
+the user and owes them a truthful answer about where it went:
+
+| Status | Meaning                                                      |
+| ------ | ------------------------------------------------------------ |
+| `404`  | No such run in flight — it finished or was cancelled. Send it as a new `/query`. |
+| `409`  | The run's agent is not accepting mid-turn input.              |
+
+A turn that has already formed its answer takes one more step to address a
+follow-up, so a turn answering in a single step is covered too. The one
+exception is a turn already at its step limit: the message stays queued rather
+than being consumed into a context no model call will read.
+
+Because `/query` is stateless (§2.4) the host still owns the transcript: record
+a delivered follow-up in the `context` you push on the **next** turn, between
+that turn's question and its answer, or the conversation loses words the agent
+demonstrably saw.
+
+Clients that predate 2.15 get a `404` on the path itself. Probe `/version`
+before sending rather than reading a 404 as "the run ended".
+
 ## 6. Process ownership
 
 Two distinct paths, deliberately:
@@ -293,13 +591,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 +633,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; also `serve` on Ctrl+C when the sidecar survives the forced kill (the message names its pid and the kill command) |
+| `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 +648,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 +681,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 +696,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
@@ -391,3 +710,24 @@ Exported from the package root — see `src/index.ts`.
 `DEBUG=gaia` (or `DEBUG=*`) enables debug output. **Everything goes to stderr** —
 stdout belongs to the TUI once it is exec'd, and to machine-readable JSON for
 `fetch` / `version`.
+
+## Developer engineering mode
+
+- **Opt-in.** The agent enables it with `--developer-mode` or `GAIA_DEVELOPER_MODE=1`
+  in the host process. `gaia engineering` and the engineering MCP server accept only
+  the explicit `--developer-mode` flag. It is separate from diagnostic `--dev`.
+- **Surface.** Only in that mode does the agent load the `gaia-harness-engineering`
+  skill and the `share_engineering_context`, `append_engineering_context`,
+  `approve_engineering_code`, `engineering_status`, `open_engineering_app` and
+  `revoke_engineering_context` tools. Sessions without it have none of them.
+- **Consent.** Sharing, appending and code approval each ask for a fresh approval of
+  the exact content or scope shown. None of them can be remembered or auto-approved.
+  Snapshots are recipient-bound and expire; revoking stops future reads.
+- **Pairing.** Configure the coding app's MCP connection from a Python GAIA install
+  with the `[mcp]` extra. The frozen binary this package ships can reuse that
+  configuration but cannot launch the Python MCP server itself.
+- **Code.** Fixes happen in the coding app, in worktrees from GAIA's managed source
+  cache. Preview results are reported by that app, not verified by GAIA. Nothing
+  self-assesses or updates the installed GAIA.
+
+See the [usage guide](https://amd-gaia.ai/docs/guides/harness-engineering).

package/binaries.lock.json

@@ -1,76 +1,76 @@
 {
   "schemaVersion": "3.0",
-  "agentVersion": "0.1.1",
+  "agentVersion": "0.3.0",
   "components": {
     "sidecar": {
-      "componentVersion": "0.1.1",
-      "baseUrl": "https://hub.amd-gaia.ai/agents/gaia/0.1.1",
+      "componentVersion": "0.3.0",
+      "baseUrl": "https://hub.amd-gaia.ai/agents/gaia/0.3.0",
       "platforms": {
         "win32-x64": {
           "filename": "gaia-agent-win32-x64.exe",
           "executable": "gaia-agent.exe",
-          "sha256": "416ed0e24cd3457ae66acd1caaf8337d0761f093b86813d8640b7cad6236856a",
-          "size": 90667208
+          "sha256": "12e79e63e1169eafadbdd453e2d5e9114bc8c9c04e7ab95e9bd1c96249f50067",
+          "size": 169416076
         },
         "darwin-arm64": {
           "filename": "gaia-agent-darwin-arm64",
           "executable": "gaia-agent",
-          "sha256": "f962b8c7ce042938a940a01fcea5c94fc0ff33b4c05c02770804c89c31aaa1c2",
-          "size": 74152544
+          "sha256": "f431642fc5cd9c05110cb8f0ffd05fe36853fe1a579bbd0b5421a3c79adc5ddd",
+          "size": 159366272
         },
         "darwin-x64": {
           "filename": "gaia-agent-darwin-x64",
           "executable": "gaia-agent",
-          "sha256": "2f001c8c8e75b286c758269d0fc22fe57ef68ef5ee59476d960531e363b73c25",
-          "size": 78642224
+          "sha256": "c793fa760b42c1c1acea7aa411f7a6830ee3bd9f68f56c5b6fac686801883f3b",
+          "size": 168077296
         },
         "linux-x64": {
           "filename": "gaia-agent-linux-x64",
           "executable": "gaia-agent",
-          "sha256": "b704f83a4beaa4654a37cf8e2fcc7429cd6da91f7431c3381e7005370e760c7a",
-          "size": 122029424
+          "sha256": "b2b115d0ae84e5fbe9aebcf055b264b5b68ae2f1a4b436bdd80de6602ca51437",
+          "size": 221414096
         }
       }
     },
     "tui": {
-      "componentVersion": "0.23.0",
-      "baseUrl": "https://hub.amd-gaia.ai/agents/terminal-hub/0.23.0",
+      "componentVersion": "0.25.0",
+      "baseUrl": "https://hub.amd-gaia.ai/agents/terminal-hub/0.25.0",
       "platforms": {
         "win32-x64": {
           "filename": "gaia-win-x64.exe",
           "executable": "gaia-tui.exe",
-          "sha256": "aad0c38c5c59e8107b608981f34608ee08feb7e5965de1cfcb929a49f21258ca",
-          "size": 19433984
+          "sha256": "9b1c467b04b267f172a6024589f1ba0ddc882729337913d8afa7dcd43a7a7967",
+          "size": 20604416
         },
         "win32-arm64": {
           "filename": "gaia-win-arm64.exe",
           "executable": "gaia-tui.exe",
-          "sha256": "2f78c8128a8ad6d17d51938de12ed7aa29ceadb642af8d6e929920fe17e2463c",
-          "size": 17975808
+          "sha256": "332068c5588e5639213225d63e4a1827d9258928e4053b7d6602668dc7eda60c",
+          "size": 19030016
         },
         "darwin-arm64": {
           "filename": "gaia-darwin-arm64",
           "executable": "gaia-tui",
-          "sha256": "766100459d22d9886a8d7839d5eddffb2a51134be76a57360b1584755be3cef1",
-          "size": 17896354
+          "sha256": "bb5ae28ae99ad25c095b3f57c4abf4e2ff67fa560122dc0a99036aedf9184802",
+          "size": 18801330
         },
         "darwin-x64": {
           "filename": "gaia-darwin-x64",
           "executable": "gaia-tui",
-          "sha256": "494197bd2bf245df94de9361a274723536e73f275bbb92efc1c4db027cc08d9e",
-          "size": 19003168
+          "sha256": "5259c82dc195297130e16377586ed6e0e668c5ec7f8b27a76ee029d67d776b52",
+          "size": 20015840
         },
         "linux-x64": {
           "filename": "gaia-linux-x64",
           "executable": "gaia-tui",
-          "sha256": "d913c4cc4943f6a5a9be737cf397ad2a05e013e55a7880c27d4ddef973ee16f4",
-          "size": 18661538
+          "sha256": "07f1cc448f8056b5915eff2869f9f3eec3a5d04485d93e448ccad00d186d23c5",
+          "size": 19669154
         },
         "linux-arm64": {
           "filename": "gaia-linux-arm64",
           "executable": "gaia-tui",
-          "sha256": "c8faee8cc7281819042d9e123d5a68b6ccfe4afa3d92d5fa3b2f42770df1d894",
-          "size": 17432738
+          "sha256": "c324100d2de989823e816a6aae7eb4e1224019096b9a46ef1a6983ca6b98598f",
+          "size": 18350242
         }
       }
     }

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;AAsLD,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkC1D"}