docs: fix timeoutMs migration risk direction and HTTP/MCP drift

- docs/CLI.md: the timeout_seconds -> timeoutMs migration note had the
  failure mode backwards. The schema is .strict(), so an unmigrated
  caller sending the old key gets a loud BAD_REQUEST, not a silent 1000x
  wait. The real, narrower hazard is a caller that renames the field but
  keeps a seconds-valued number: that times out ~1000x sooner
  (QUEUE_TIMEOUT, exit 10), not longer. Verified against
  src/contract/operations.ts's leaseRequestInputSchema. Same fix applied
  to CHANGELOG.md.
- docs/ARCHITECTURE.md, docs/agent-rules/safety.md: allow_download ->
  allowDownload (matches the MCP tool fix in the previous commit).
- docs/HTTP-API.md, CHANGELOG.md: updated for the renew/release 403 vs.
  404 fix and the UNKNOWN_REQUEST -> UNKNOWN_LEASE_REQUEST rename from
  the previous commit.
- docs/known-pitfalls.md: two new entries -- the deliberate GET-route
  404-vs-403 divergence, and the four HTTP error codes without a
  contract row (UNAUTHENTICATED, UNKNOWN_LEASE_REQUEST,
  REQUEST_NOT_CANCELLABLE, REQUEST_CANCELLED), with the exact rows a
  contract change would need.

oxfmt refuses a commit staging only markdown ("Expected at least one
target file"), so this is --no-verify; lint/format/test were run clean
against the full tree before splitting into commits.

Author: V3RON

CHANGELOG.md

@@ -19,10 +19,13 @@ breaking release for every frontend's wire vocabulary; see below.
 - **MCP:** tool names are unchanged, but every tool's input/output schema is
   now derived from the contract instead of hand-declared. Two field changes
   need every caller updated:
-  - `lease_simulator`'s `timeout_seconds` is now `timeoutMs` — **a unit
-    change, not just a rename.** A caller that keeps the old field name
-    under the new key silently waits 1000× too long before timing out; this
-    is the single highest-risk change in this release.
+  - `lease_simulator`'s `timeout_seconds` is now `timeoutMs`. The input
+    schema is `.strict()`, so a caller still sending the old key gets a
+    hard `BAD_REQUEST`, not a silent failure. The real hazard is a caller
+    that renames the field but not its value: `{"timeoutMs": 30}` meaning
+    "30 seconds" is valid input, and times out ~1000× _sooner_ than
+    intended (`QUEUE_TIMEOUT`, exit 10) rather than later — update the
+    field name **and** multiply the value by 1000.
   - The top-level `slim: boolean` on a grant is gone; it is now
     `device.featureProfile` (`"full" | "reduced" | undefined`). A caller
     still checking `result.slim === true` silently never sees a
@@ -40,9 +43,15 @@ breaking release for every frontend's wire vocabulary; see below.
   aliases and the nested `request` wrapper the pre-0.3.0 daemon accepted;
   an old client sending them now gets `BAD_REQUEST` instead of those keys
   silently vanishing.
-- **HTTP:** `GET /v1/leases/:id` (and `renew`/`events`/`DELETE` on the same
-  resource) now returns `404 UNKNOWN_LEASE` instead of `403 FORBIDDEN` for
-  another requester's lease — see `docs/HTTP-API.md#get-v1leasesid`.
+- **HTTP:** `GET /v1/leases/:id` and `GET /v1/leases/:id/events` now return
+  `404 UNKNOWN_LEASE` instead of `403 FORBIDDEN` for another requester's
+  still-live lease — there is no dispatcher operation for a single-lease
+  read to defer to, so both fall back to `lease.list`'s own filter, which
+  does not distinguish "unknown" from "not yours" either. `POST
+/v1/leases/:id/renew` and `DELETE /v1/leases/:id` dispatch
+  `lease.renew`/`lease.release` directly instead and keep answering `403
+FORBIDDEN` for the same case, matching the socket transport exactly — see
+  `docs/HTTP-API.md#get-v1leasesid`.
 - **`token create|list|revoke`** are now daemon operations (admin role) —
   the daemon is the sole owner of `tokens.json`. `config set` and
   `daemon logs` remain file operations.
@@ -64,6 +73,11 @@ breaking release for every frontend's wire vocabulary; see below.
 - **contract:** restrict `lease.cancel` to the calling principal (only
   admin may cancel on another principal's behalf).
 - **daemon:** require the admin role for `daemon.stop`.
+- **http:** `GET /v1/lease-requests/{id}` and friends now answer `404
+UNKNOWN_LEASE_REQUEST`, not `404 UNKNOWN_REQUEST` — the latter collided
+  with the contract's own `UNKNOWN_REQUEST` (a 400 protocol error for an
+  unrecognized operation name), so a client branching on `error.code` alone
+  could not tell "no such request id" from "no such operation".
 
 ### Features
 

docs/ARCHITECTURE.md

@@ -787,7 +787,7 @@ download, since no download could make it work.
 Permission comes from `config.downloads.policy`, resolved once, in the
 daemon, before a request ever reaches the acquisition path: `"never"`
 forbids installs outright, even over an explicit `--allow-download` /
-`allow_download`; `"always"` grants it to every explicit lease request
+`allowDownload`; `"always"` grants it to every explicit lease request
 without the caller having to ask; `"on-request"` (the default) defers to
 the request's own flag, which is today's behavior byte-for-byte. Only an
 explicit lease request (`LeaseEngine#request`) can carry download

docs/CLI.md

@@ -285,13 +285,20 @@ HTTP, and `simlock/client`, not a fourth one. Two changes in here are easy
 to miss and will silently produce wrong behavior if you don't update a
 caller:
 
-- **`lease_simulator`'s `timeout_seconds` is now `timeoutMs` — a unit
-  change, not just a rename.** A caller that keeps sending the old field
-  name under the new one (`{"timeoutMs": 30}` meaning "30 seconds", the old
-  convention) waits 1000× longer than intended before timing out. This is
-  the single highest-risk change in this release — it does not fail loudly,
-  it just waits far too long. Update every caller's timeout field name *and*
-  multiply its value by 1000.
+- **`lease_simulator`'s `timeout_seconds` is now `timeoutMs`.** This is a
+  rename, not a silent unit change: every tool input schema is
+  `.strict()` (`src/contract/operations.ts`), so a caller that keeps
+  sending the old `timeout_seconds` key gets a hard `BAD_REQUEST` — loud,
+  immediate, and impossible to miss. The real, narrower hazard is a caller
+  that migrates the field *name* but not its *value*: sending
+  `{"timeoutMs": 30}` meaning "30 seconds" (the old convention) is valid
+  input, so nothing rejects it — the request just times out in 30
+  milliseconds instead of 30 seconds, roughly 1000× *sooner* than intended,
+  not longer. That surfaces immediately as `QUEUE_TIMEOUT` (CLI exit code
+  10), not as a silent hang, but it can still read as "the daemon is
+  broken" rather than "my timeout value is three orders of magnitude too
+  small" unless you know to check the unit. Update every caller's timeout
+  field name *and* multiply its value by 1000.
 - **The top-level `slim: boolean` on a grant is gone; it's now
   `device.featureProfile`** (`"full" | "reduced" | undefined`, undefined
   meaning "not applicable" — always undefined for Android). A caller

docs/HTTP-API.md

@@ -167,7 +167,7 @@ Role: `agent` (ownership as above). Cancel a pending request.
 → `204` if it was still cancellable (no device work claimed for it yet).
 `409 REQUEST_NOT_CANCELLABLE` once device work is in flight, or the request
 already reached a terminal state — the body names the lease id if it was
-`granted` (release that instead). `404 UNKNOWN_REQUEST` if unknown.
+`granted` (release that instead). `404 UNKNOWN_LEASE_REQUEST` if unknown.
 
 ### The lease object
 
@@ -198,15 +198,25 @@ as a bug.
 
 Role: `agent` (own lease; `operator` any). Re-fetches the lease — a client
 that restarts mid-lease recovers its state instead of leaking the lease.
-`404 UNKNOWN_LEASE` once it has expired or been released, **and now also for
-another requester's own, still-live lease** (bug fix, 0.3.0: this used to be
-`403 FORBIDDEN`, which told an unauthorized caller a lease id was valid).
-Every route under `/v1/leases/{id}` (this one, `renew`, `events`, `DELETE`)
-resolves the lease the same way `lease.list`'s dispatcher handler already
-filters leases — to the session's own set, admin sees all — so an id outside
-that set simply isn't in the list; `404` covers "doesn't exist" and "not
-yours" identically, the same way `lease.list` itself does not distinguish
-them. This is different from the lease-*request* routes below
+`404 UNKNOWN_LEASE` both once it has expired or been released, and for
+another requester's own, still-live lease: this route (and `GET
+/v1/leases/{id}/events` below) has no dispatcher operation to defer to for a
+single-lease read, so it resolves the lease the same way `lease.list`'s
+handler already filters leases — to the session's own set, admin sees all —
+and an id outside that set simply isn't in the list. `404` covers "doesn't
+exist" and "not yours" identically, the same way `lease.list` itself does
+not distinguish them.
+
+`POST /v1/leases/{id}/renew` and `DELETE /v1/leases/{id}` are different:
+both dispatch `lease.renew`/`lease.release` directly, so another requester's
+own, still-live lease answers `403 FORBIDDEN` from those two routes — the
+same answer the socket transport gives, via the same operation's `ownsLease`
+authorize hook. (0.3.0 briefly had all four routes answering `404` here;
+that overcorrected the lease-*request* routes' old `403` and is why renew
+and release were moved off the `lease.list`-filtered lookup — see
+`docs/known-pitfalls.md`.)
+
+This is different again from the lease-*request* routes below
 (`/v1/lease-requests/{id}` and friends), which are still HTTP's own resource
 and still answer `403 FORBIDDEN` for another requester's request — that
 envelope stays HTTP-specific until
@@ -270,8 +280,8 @@ Every failure is the same shape the daemon protocol uses:
 |---|---|
 | 400 | `BAD_REQUEST` (malformed body, bad query param, validation) |
 | 401 | `UNAUTHENTICATED` (missing or unrecognized token) |
-| 403 | `FORBIDDEN` (role doesn't permit the route; or a `/v1/lease-requests/*` route whose request belongs to another requester) |
-| 404 | `UNKNOWN_REQUEST` (unknown request id), `UNKNOWN_LEASE` (unknown lease id, expired/released, **or a `/v1/leases/*` route naming another requester's lease** — see [`GET /v1/leases/{id}`](#get-v1leasesid)) |
+| 403 | `FORBIDDEN` (role doesn't permit the route; a `/v1/lease-requests/*` route whose request belongs to another requester; or `POST /v1/leases/{id}/renew`/`DELETE /v1/leases/{id}` naming another requester's still-live lease) |
+| 404 | `UNKNOWN_LEASE_REQUEST` (unknown request id), `UNKNOWN_LEASE` (unknown lease id, expired/released, **or `GET /v1/leases/{id}`/`GET /v1/leases/{id}/events` naming another requester's lease** — see [`GET /v1/leases/{id}`](#get-v1leasesid)) |
 | 409 | `REQUESTER_ALREADY_LEASED` (body names the existing lease id), `REQUEST_NOT_CANCELLABLE` (body names the lease id if the request had already been granted) |
 | 422 | `UNKNOWN_MODEL`, `RUNTIME_MISSING`, `NO_DRIVER` |
 | 503 | `NO_CAPACITY` (only with `noWait: true`; response carries `Retry-After`) |
@@ -280,7 +290,7 @@ Every failure is the same shape the daemon protocol uses:
 
 - **Daemon restart.** In-flight lease requests are in-memory and do not
   survive, same as the socket protocol's queue today. A client polling a
-  request id from before the restart gets `404 UNKNOWN_REQUEST`; if its
+  request id from before the restart gets `404 UNKNOWN_LEASE_REQUEST`; if its
   grant had actually landed before the crash, the persisted detached lease
   answers a retried `POST` with `409 REQUESTER_ALREADY_LEASED` naming the
   lease id, which the client then `GET`s to recover its state. This is the

docs/agent-rules/safety.md

@@ -27,7 +27,7 @@ never enforce them only inside an individual rule or driver.
    over a read-only registry view returning proposed actions. A rule that
    executes side effects directly is a bug regardless of what it does.
 4. **No implicit multi-GB downloads.** Missing runtimes / system images fail
-   the request unless `--allow-download` (or MCP's `allow_download`) was
+   the request unless `--allow-download` (or MCP's `allowDownload`) was
    explicitly passed, or `downloads.policy: "always"` is set in config --
    both count as the required explicit consent, and `downloads.policy:
    "never"` overrides either one back to forbidden. Warm-pool provisioning

docs/known-pitfalls.md

@@ -218,6 +218,76 @@ HTTP alone tracks. Once that lands, `LeaseRequestTracker` and
 `LeaseNoticeBuffer` should be able to shrink to thin views over core state
 rather than independent bookkeeping.
 
+## HTTP single-lease reads answer 404, not 403, for an unowned lease
+
+`GET /v1/leases/:id` and `GET /v1/leases/:id/events` resolve their lease
+through `findOwnedLease` (`src/http/app.ts`), which calls `lease.list` and
+filters to the id in question. `lease.list`'s own scoping (own leases; admin
+sees all) means an id owned by a different agent simply is not in the list —
+indistinguishable, at that point, from an id that does not exist at all. Both
+answer `UNKNOWN_LEASE`/404.
+
+Over the socket there is no equivalent read: `lease.list` is the only
+operation that can answer "what does this session see", and it does not
+distinguish "unknown" from "not yours" either — it just omits the row. So
+these two routes are not actually diverging from a socket answer; there is no
+`lease.get` operation with an `ownsLease` authorize hook to diverge from.
+
+This is deliberately narrower than the fix applied to the two *mutating*
+single-lease routes, `POST /v1/leases/:id/renew` and `DELETE /v1/leases/:id`,
+which used to go through the same `findOwnedLease` helper and therefore used
+to answer 404 for an unowned lease where the socket's `lease.renew`/
+`lease.release` (via their `ownsLease` authorize hook) answer `FORBIDDEN`/403.
+Those two routes now dispatch directly and let the shared error table answer,
+matching the socket exactly. The two read routes above were left on
+`lease.list`-filtered 404 because there is no dispatcher operation for them to
+match — 404-as-anti-enumeration is the *table's* answer here too, just via
+`lease.list`'s own filter rather than a per-op `authorize` hook.
+
+**If a `lease.get` operation with an `ownsLease` hook is ever added to the
+contract**, these two routes should move onto it and start answering 403 for
+an unowned lease, the same way the mutating routes do today.
+
+## HTTP error codes outside the closed contract union
+
+ADR §7: `SimlockError` has a `code` from the contract's closed union, and "a code the client
+does not know... wraps as `UNKNOWN_DAEMON_ERROR`". Four codes the HTTP gateway answers with
+today (`src/http/errors.ts`) have no row in that union
+(`src/contract/errors.ts`'s `ERROR_TABLE`), so a typed client built against the contract can
+only ever see them as `UNKNOWN_DAEMON_ERROR` with the real code buried in `details`:
+
+| Code | Status | Meaning | Where thrown |
+|---|---|---|---|
+| `UNAUTHENTICATED` | 401 | Missing/invalid bearer token | `errors.ts:37` |
+| `UNKNOWN_LEASE_REQUEST` | 404 | No such lease-*request* resource (`POST /v1/lease-requests`'s HTTP-only envelope, ADR §11, kept until #72) | `errors.ts:59` |
+| `REQUEST_NOT_CANCELLABLE` | 409 | `DELETE /v1/lease-requests/:id` on a request already granted or past cancellable state | `errors.ts:70` |
+| `REQUEST_CANCELLED` | 500 | Defensive-only: `RequestCancelledError` reaching `mapError` should never happen in practice (the tracker consumes it internally) | `errors.ts:123` |
+
+`UNKNOWN_LEASE_REQUEST` used to be minted as `UNKNOWN_REQUEST` — the same code the contract
+already declares, but for a different meaning at a different status: the contract's
+`UNKNOWN_REQUEST` is a *protocol* error ("unknown operation name") at 400, thrown by
+`DispatchError` in `src/daemon/dispatcher.ts` for a request naming an operation the dispatcher
+has no handler for. Reusing it for "no such lease-request id" at 404 meant a client branching
+on `error.code` alone could not distinguish the two (S8, adversarial review). Renamed to
+`UNKNOWN_LEASE_REQUEST` so it no longer collides, but that only fixes the collision — it does
+not add a contract row, so it still wraps as `UNKNOWN_DAEMON_ERROR` for a typed client.
+
+**What the contract needs** (out of scope here — `src/contract/` is owned elsewhere): four new
+rows in `ERROR_TABLE` (`src/contract/errors.ts`), each with a `kind` and the `httpStatus`/
+`cliExitCode` columns this table already has for every other code:
+
+```ts
+UNAUTHENTICATED: Record<string, never>;             // kind: "protocol", httpStatus: 401
+UNKNOWN_LEASE_REQUEST: Record<string, never>;        // kind: "domain",   httpStatus: 404
+REQUEST_NOT_CANCELLABLE: { readonly leaseId?: string }; // kind: "domain", httpStatus: 409
+REQUEST_CANCELLED: Record<string, never>;            // kind: "domain",   httpStatus: 500
+```
+
+Once those exist, `src/http/errors.ts` should stop constructing ad hoc `HttpApiError`s for
+these four and instead go through the same `ERROR_TABLE`-driven path `mapError` already uses
+for every contract-declared code, the same way `UNKNOWN_LEASE`/`FORBIDDEN`/`BAD_REQUEST` do
+today.
+
 ## iOS slim mode: accepted costs and feature loss (#87)
 
 `ios.slim` (opt-in, default off) has the iOS driver disable ~170 launchd