humanish 0.17.0 → 0.19.0

package/docs/architecture/serve.md

@@ -2,10 +2,19 @@
 
 Date: 2026-08-02
 
-Status: shipped in v1 — loopback, capability-link, and share-safe-open modes
-(`src/observer-serve.ts`, `src/observer-auth.ts`, `src/observer-library.ts`,
-`src/serve-tunnel.ts`; CLI wiring in `src/program.ts`). The `/_humanish/api/*`
-control-plane namespace is reserved and answers `501`; no mutating route ships.
+Status: shipped — `loopback`, `exposed` (edge-authed), and `share-safe-open`
+modes (`src/observer-serve.ts`, `src/observer-library.ts`, `src/serve-http.ts`,
+`src/serve-exposure.ts`, `src/serve-tunnel.ts`; CLI wiring in `src/program.ts`).
+The `/_humanish/api/*` control-plane namespace is reserved and answers `501`; no
+mutating route ships.
+
+Exposure auth is **tunnel-edge only**. As of 0.18.0 humanish carries NO
+in-process auth: the hand-rolled capability-link (cookie/token/TTL, the whole
+`observer-auth.ts` module and the `serve --auth link|none` flags) was removed as
+a pre-1.0 breaking change. The gate now lives entirely at the edge — ngrok
+`--oauth google` (with `--allow-email`/`--allow-domain` allow rules), or an
+operator-secured `--public-url` (Cloudflare Access, Tailscale, a reverse proxy
+you own).
 
 ## What serve is
 
@@ -13,69 +22,107 @@ control-plane namespace is reserved and answers `501`; no mutating route ships.
 the LIBRARY rather than a run:
 
 - `humanish watch` — one ATTACHED run: the process that created the run serves
-  it and may inject runtime stream URLs for live following;
+  it and may inject runtime stream URLs for live following (see the stream-URL
+  doctrine below and `watch --expose`);
 - `humanish observe` — one FINISHED run, re-served read-only;
 - `humanish serve` — the whole local library under `.humanish/runs/`: a
   library index, per-run Observer pages, `/_humanish/history.json` polling, and
-  optional exposure beyond the machine.
+  optional edge-authenticated exposure beyond the machine.
 
 The server binds `127.0.0.1` unconditionally (`serveObserverLibrary`); exposure
 only ever happens through a tunnel or proxy forwarding to the loopback port.
-`--expose` gates every request behind a capability link: a per-process secret
-whose SHA-256 digest is compared timing-safe (`verifyTokenDigest`), minting an
-HttpOnly viewer-session cookie with a bounded TTL. Ctrl-C revokes the link and
-all sessions (`revokeAll` on close); restarting mints a new link.
+`--expose` never changes the bind — it declares intent and requires an
+authenticated edge (or `--safe`, see the fail-closed matrix).
+
+## Fail-closed exposure matrix
+
+One shared validator (`validateExposure` in `src/serve-exposure.ts`) governs
+both `serve` and `watch`. `--expose` must ALWAYS resolve to a reachable public
+origin (a `--tunnel` or a `--public-url`) — even under `--safe`, since an
+origin-less exposed server is an unreachable loopback no-op. With an origin
+present, exposure requires EITHER edge auth (`--oauth` on the ngrok edge, or a
+`--public-url` you secure) OR `--safe` (share_ready runs only). A tunnel with
+neither is a wide-open public URL to local bundles and is refused.
+
+| `--expose` | `--tunnel` | `--oauth` | `--public-url` | `--safe` | Outcome |
+| --- | --- | --- | --- | --- | --- |
+| — | — | — | — | any | `loopback` (no exposure) |
+| ✓ | ✓ | ✓ | — | any | OK → `exposed` (edge-authed; all runs unless `--safe`) |
+| ✓ | ✓ | — | — | ✓ | OK → `share-safe-open` (public, share_ready only) |
+| ✓ | ✓ | — | — | — | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE` |
+| ✓ | — | — | ✓ | any | OK → `exposed` (operator-secured edge) |
+| ✓ | — | — | — | any | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN` (no reachable origin, even with `--safe`) |
+| ✓ | — | ✓ | — | any | **REFUSED** `HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL` |
+| ✓ | ✓ | ✓ | ✓ | any | **REFUSED** `HUMANISH_SERVE_OPTION_CONFLICT` (tunnel + public-url) |
+
+Guard order (all before any bind/spawn): `--allow-email`/`--allow-domain`
+without `--oauth` → `HUMANISH_SERVE_ALLOW_REQUIRES_OAUTH`; `--oauth` without
+`--tunnel` → `HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL`; `--tunnel`+`--public-url` →
+conflict; `--tunnel-domain` without `--tunnel` → conflict; `--expose` with no
+tunnel and no `--public-url` (even under `--safe`) →
+`HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN`; `--expose` with an origin but without
+edge auth and without `--safe` →
+`HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`; a tunnel/public-url without
+`--expose` → `HUMANISH_SERVE_TUNNEL_REQUIRES_EXPOSE`/conflict. `--oauth google`
+with NO allow rule is ALLOWED (any Google account authenticates) but pushes a
+prominent warning recommending at least one `--allow-email`/`--allow-domain`.
+
+The `watch` surface reuses the same validator but is stricter: a live,
+in-progress run is never `share_ready` (raw, unverified screenshots), so `--safe`
+would admit nothing. `watch --expose --safe` is therefore REFUSED outright with
+`HUMANISH_WATCH_SAFE_NOT_APPLICABLE` (rather than silently ignoring the flag);
+`watch --expose` ALWAYS requires edge auth (`--tunnel --oauth` or `--public-url`),
+and is additionally refused with `--dry-run`/`--detach`/`--json` (no live desktop
+/ no attached follow). An exposed watch serves ONLY the attached live run: its
+`/_humanish/history.json` lists just that run and every other run id 404s
+byte-identically to a nonexistent one, so a remote viewer can never enumerate or
+reach any prior run's raw evidence (loopback watch still serves the full library).
+
+## ngrok edge OAuth
+
+`startNgrokTunnel` builds `ngrok http <port> [--url <domain>] [--oauth google
+[--oauth-allow-email <addr>]… [--oauth-allow-domain <domain>]…] --log stdout
+--log-format json`. ngrok authenticates the viewer at its edge before any request
+reaches the loopback port; the stdout JSON parser skips every line except
+`msg:"started tunnel"`, so ngrok's `--oauth has been deprecated` info line (it is
+still accepted and functional on ngrok 3.39.x) is ignored automatically. The
+forward-compatible path if ngrok removes the flags is a Traffic Policy YAML — a
+documented fast-follow, out of scope for 0.18.0.
 
 ## Threat model
 
-**The tunnel-agent-connects-from-loopback trap.** The classic mistake on a
-tunneled local server is "peer address is 127.0.0.1, so this is the local
-operator — skip auth." The tunnel agent connects from loopback, so that
-shortcut disables auth in exactly the deployment it exists to protect. Serve
-auth therefore ignores source address entirely: every route below the auth
-mint requires a valid session, loopback peer or not.
-
-**Referer and unfurler leakage.** The capability URL embeds the secret in the
-path. Every response carries `referrer-policy: no-referrer` (plus `no-store`
-and `x-robots-tag: noindex`), so a link inside a served page can never leak the
-origin or token onward. The residual channel is the operator pasting the link
-into a chat app whose unfurler prefetches it server-side — which is why the
-link is deliberately NOT single-use (a preview fetch must not burn it before
-the phone taps it), and why the README steers sharing toward AirDrop or manual
-entry.
-
-**Host-only cookie scope on shared tunnel domains.** The session cookie sets
-no `Domain` attribute (`buildSessionCookie`), so it is host-only. On a shared
-tunnel apex (many customers under one provider domain), a `Domain` cookie
-would be presented to sibling subdomains an attacker can rent; a host-only
-cookie can never leave the exact public origin the operator declared.
+**No in-process secret to leak.** The old capability-link posture (a token in
+the URL path, an HttpOnly cookie, unfurler/history leakage, host-only cookie
+scope, TTL/revocation) is gone with the module. There is no secret in any URL
+served by humanish; the operator's edge owns authentication and session
+lifetime.
 
 **DNS rebinding and the strict Host allowlist.** A malicious page can point an
 attacker-controlled DNS name at 127.0.0.1 and read a permissive local server
 from the victim's browser. Serve keeps a strict Host allowlist in ALL modes —
-loopback names plus the declared tunnel/public origin only — and answers
-`421 Misdirected Request` otherwise. Even the unauthenticated loopback default
-never trusts an arbitrary Host header.
+loopback names plus the declared tunnel/public origin only — and answers `421
+Misdirected Request` otherwise. Even the unauthenticated loopback default never
+trusts an arbitrary Host header. The live `serveObserver` server gains the same
+allowlist + security headers under its new `exposed` option (see observer.md), so
+`watch --expose` is not a header-less, rebinding-vulnerable surface.
 
-**Token in phone history (residual).** After the tap, the capability URL
-remains in the phone's browser history and share sheet. TTL-bounded sessions,
-per-process minting, and Ctrl-C revocation bound the damage — a link recovered
-from history after the process exits or restarts is dead — but while the same
-process runs, a leaked history entry is a live credential. This risk is
-accepted and documented, not solved.
+**Security headers.** Every response carries `cache-control: no-store`,
+`referrer-policy: no-referrer`, `x-content-type-options: nosniff`,
+`x-frame-options: DENY`, and `x-robots-tag: noindex, nofollow`
+(`buildServeSecurityHeaders`).
 
 ## Mode-to-boundary mapping
 
 | Mode | Invocation | Boundary class |
 | --- | --- | --- |
 | `loopback` | `humanish serve` | Capture-side trust: readable only by whoever can already read gitignored `.humanish/` on this machine; no new boundary is crossed. |
-| `capability-link` | `--expose` (auth defaults to `link`) | Declared-friction exposure: publishing-adjacent, not publishing. Anyone holding the secret link reads everything it grants until Ctrl-C — the printed warning names the run count, including non-`share_ready` runs unless `--safe` composes in. |
-| `share-safe-open` | `--expose --safe --auth none` | Genuine publishing, behind the feedback-grade `share_ready` gate: only runs that pass verify are served — admission is re-checked when a bundle changes and re-verified within a bounded window (default 30s), so it is fresh, not perfectly live; everything else is absent, 404ing byte-identically to a nonexistent run (no existence oracle). |
+| `exposed` | `--expose --tunnel ngrok --oauth google …`, or `--expose --public-url <origin>` | Edge-authed exposure: only viewers who clear the edge OAuth (or the operator's own edge) reach the loopback server, which then serves everything it grants unless `--safe` composes in. The gate is the edge, not humanish. |
+| `share-safe-open` | `--expose --safe --tunnel ngrok` (no `--oauth`) | Genuine publishing behind the feedback-grade `share_ready` gate: only runs that pass verify are served — admission is re-checked when a bundle changes and re-verified within a bounded window (default 30s); everything else is absent, 404ing byte-identically to a nonexistent run (no existence oracle). |
 
 ## Stream-URL doctrine
 
-Live desktop stream URLs (auth-bearing hosted-VNC links) are never served by
-this surface, in any mode, and the guarantee is layered:
+Live desktop stream URLs (auth-bearing hosted-VNC links) are never served by the
+LIBRARY surface, in any mode, and the guarantee is layered:
 
 - **structural** — runtime stream URLs live in a `WeakMap` keyed by the watch
   process's in-memory `ObserverResult` (`src/observer.ts`) and are never
@@ -87,54 +134,63 @@ this surface, in any mode, and the guarantee is layered:
 - **tested** — the serve suite pins a no-injection test: observer data served
   through the library surface carries no runtime stream URLs.
 
-A `--live-streams` flag on serve was considered and deliberately refused: the
-persisted bundle carries no stream URLs, so the flag would be a claim without a
-mechanism (invariant 6). Remote live following belongs to a designed
-`watch --expose` (see Future work), where the attached process actually holds
-the URLs.
+`watch --expose` is the ONE surface that deliberately serves runtime E2B stream
+URLs — the attached watch process genuinely holds them, and streaming the live
+desktop is the whole point of watching from a phone. It is safe only because the
+edge authenticates first, and the URLs are still never persisted (they are
+injected into the in-memory bundle, not disk). See observer.md.
 
 ## The share_ready doctrine
 
 `share_ready` was designed as the bar for FEEDBACK payloads: evidence eligible
-to leave the machine inside a public issue draft. Serve's open mode extends
-that same gate to arbitrary-audience BROWSING, which is a broader exposure of
-the same artifacts. The honest caveat carries over unchanged: `humanish
-verify` does not yet detect free-form PII/PHI (names, emails, medical
+to leave the machine inside a public issue draft. Serve's `share-safe-open` mode
+extends that same gate to arbitrary-audience BROWSING, which is a broader
+exposure of the same artifacts. The honest caveat carries over unchanged:
+`humanish verify` does not yet detect free-form PII/PHI (names, emails, medical
 identifiers — see the README's public-safety boundary and issue #108), so
-`share_ready` means the automated secret/path scan passed, not that a human
-would publish every pixel. Maintainers should treat open mode accordingly:
-synthetic data upstream, review before exposing, and treat `--safe --auth
-none` as publishing because it is.
+`share_ready` means the automated secret/path scan passed, not that a human would
+publish every pixel. Maintainers should treat open mode accordingly: synthetic
+data upstream, review before exposing, and treat `--safe` without edge auth as
+publishing because it is.
 
 ## v2 control-plane seam contract
 
 The reserved `/_humanish/api/*` namespace answers `501` with
-`HUMANISH_SERVE_CONTROL_PLANE_DISABLED` in v1 to any request that clears the
-auth gate — so under `--expose --auth link` a session-less request gets the
-uniform `401` first, and the `501` is what an authenticated (or loopback) caller
-sees. No run artifact can ever shadow the namespace. The seam is already typed:
-`createServeRequestHandler` accepts an optional `ServeControlPlane`, and v1
-always passes `undefined`. Before any mutating route ships, the contract is:
-
-- sessions grow a real scope split — today every session is scope `viewer`;
-  operators get a DISTINCT operator token, never an upgraded viewer cookie;
-- mutating routes require double-submit CSRF on top of the operator session,
-  because a cookie alone is exactly what a cross-site request forges;
-- the spend rule is invariant 3 applied to remote hands: a phone-initiated
-  LIVE run needs its own affirmative declaration at serve startup (an explicit
-  opt-in naming the lab and budget), never a default the viewer UI can reach.
+`HUMANISH_SERVE_CONTROL_PLANE_DISABLED` to any request. Because the in-process
+auth gate is gone, a request that clears the edge (or a loopback caller) reaches
+the `501` directly — there is no `401`-first anymore. No run artifact can ever
+shadow the namespace. The seam is already typed: `createServeRequestHandler`
+accepts an optional `ServeControlPlane`, and v1 always passes `undefined`. Before
+any mutating route ships, the contract is:
+
+- an operator identity distinct from a viewer — but sourced from the edge/control
+  plane, not a humanish-minted cookie;
+- mutating routes require CSRF defenses appropriate to the chosen edge session;
+- the spend rule is invariant 3 applied to remote hands: a phone-initiated LIVE
+  run needs its own affirmative declaration at serve startup (an explicit opt-in
+  naming the lab and budget), never a default the viewer UI can reach.
+
+## Why not Better Auth here
+
+Better Auth is a strong TypeScript auth framework, but it is deliberately NOT
+used for this CLI serve surface: serve is an ephemeral, no-database,
+per-invocation loopback server whose only job is to hand persisted evidence to an
+already-authenticated edge. A password/session/social-login framework with a
+schema and a datastore is the wrong shape for a process that lives for the length
+of a `Ctrl-C`. The right home for Better Auth is a FUTURE hosted humanish
+dashboard / control-plane — a persistent, multi-user service with a database —
+where accounts, org membership, and durable sessions actually exist.
 
 ## Future work
 
-- **Persistent capability links.** A link that survives restart is a stored
-  secret and needs a real secret-storage design (keychain/agent integration,
-  rotation, revocation records) — not a `--token <value>` CLI string, which
-  would land in shell history and process listings.
+- **Traffic Policy for ngrok.** Migrate off the deprecated `--oauth*` flags to a
+  generated Traffic Policy YAML once ngrok requires it (the `yaml` dep is already
+  available); pin the behavior in `serve-tunnel` tests first.
 - **Google Fonts inlining for per-run observer pages.** The library index is
-  self-contained; the per-run observer HTML still references remote Google
-  Fonts, which degrade gracefully offline but should be inlined (or dropped)
-  so a served run page makes no third-party requests from a viewer's browser.
-- **`watch --expose --live-streams`.** Remote LIVE following is a separate
-  design: the attached watch process genuinely holds runtime stream URLs, so
-  it can expose them deliberately — with the same capability-link gate and its
-  own doctrine for auth-bearing hosted-desktop URLs.
+  self-contained; the per-run observer HTML still references remote Google Fonts,
+  which degrade gracefully offline but should be inlined (or dropped) so a served
+  run page makes no third-party requests from a viewer's browser.
+- **Shipped in 0.18.0: `watch --expose`.** Remote LIVE following of a run,
+  including its live E2B desktop stream, behind the same edge auth — the one
+  surface that deliberately serves runtime stream URLs. See observer.md and
+  live_watch_wiring.

package/docs/contracts/run-bundle.md

@@ -112,6 +112,29 @@ instead (a dirty working tree cannot be commit-pinned), and `app-url` carries
 no code pin at all. No path, basename, or other host-machine string ever
 enters this field; identity is digests, a sha, a boolean, and counts.
 
+## Cost Estimate (advisory)
+
+`cost` is optional and additive (`humanish.run-cost-summary.v1`): the
+computer-use lane's run-level cost ESTIMATE — the sum of each lane's
+token-derived model cost plus one aggregate E2B desktop-minute figure. It is an
+ESTIMATE, never authoritative: every dollar is a rate-table multiply from the
+operator-editable `src/pricing.ts`, carries the pricing `ratesAsOf` date and
+`source`, and is surfaced with the "estimated (rates as of `<date>`)" label —
+never a bare charge. It follows the same **declared-absent** discipline as the
+terminal cost ledger: an unpriceable line stays present with
+`estimatedCostUsd: null` + a `reason` and contributes nothing;
+`estimatedTotalUsd` is `null` iff every line is null (never coerced to `0`).
+Dry-runs and lanes that spend nothing omit `cost` entirely, so pre-existing
+bundles stay byte-stable. Each lane's own estimate also rides its
+`stream.actor.estimatedCost` (`humanish.actor-estimated-cost.v1`), kept distinct
+from the reserved provider-returned `tokenUsage.costUsd`. See
+[`schemas.md`](schemas.md) → Run Cost Summary And Estimated Actor Cost.
+
+`humanish verify` treats cost as ADVISORY on magnitude and FAIL-CLOSED on
+labeling: absence passes, but a claimed dollar figure without its `ratesAsOf`
+date + `source`, or a total that does not match its known lines, fails. Verify
+never inspects the magnitude — a correctly-labeled large estimate still passes.
+
 ## Adapter Score
 
 `adapterScore` is optional and namespaced. It lets a downstream adapter summarize

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.17.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.19.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
 schema constants, parsers, and validators in `src/` are authoritative. Rows
 marked "reserved" name layering intent only — no code emits or validates them
 yet. Do not emit a reserved schema.
@@ -43,6 +43,9 @@ workflow without leaking private upstream truth into core.
 | Feedback | `humanish.feedback.v1` | `public-safe-feedback` |
 | Terminal cost ledger | `humanish.terminal-cost-ledger.v1` | see Terminal Cost Ledger below |
 | Terminal no-spend proof | `humanish.terminal-no-spend-proof.v1` | see Terminal Cost Ledger below |
+| Pricing (operator-editable rates) | `humanish.pricing.v1` (`src/pricing.ts`; dated per-model + E2B desktop rates) | see Run Cost Summary And Estimated Actor Cost below |
+| Run cost summary | `humanish.run-cost-summary.v1` (additive `RunBundle.cost`; estimate, never a charge) | see Run Cost Summary And Estimated Actor Cost below |
+| Estimated actor cost | `humanish.actor-estimated-cost.v1` (additive `ActorTrace.estimatedCost`) | see Run Cost Summary And Estimated Actor Cost below |
 | Adapter score | `humanish.adapter-score.v1` (`RunBundle.adapterScore`; namespaced; route-specific acceptance semantics) | see Product-Adapter Extension Seam below |
 | Adapter artifact | `humanish.adapter-artifact.v1` (`RunBundle.adapterArtifacts[]`; namespaced; local relative proof references) | see Product-Adapter Extension Seam below |
 | Shared-world evidence | `humanish.shared-world.v1` (additive `RunBundle.sharedWorld` + `RunBundle.attributionClass`; `topologyMode: sequential \| concurrent`) | see Shared-World Evidence below |
@@ -601,8 +604,20 @@ Core-owned fields:
 - `startedAt` / `completedAt` / `durationMs`
 - `status` / `completionReason` / `reason` (`completionReason` includes
   `step_failed`: a deterministic scripted step/expectation evaluated false —
-  the subject failed the script while the harness executed faithfully)
+  the subject failed the script while the harness executed faithfully; and
+  `budget_reached`: an open-ended watch session that hit the wall-clock time
+  budget AFTER productive activity — status `passed`, a NON-FAILURE completion,
+  distinct from `timed_out`, which stays reserved for a zero-progress deadline
+  hit and remains a failure)
 - `ids`, `counts`, `items[]`, optional `tokenUsage`, `capabilities`
+- optional `estimatedCost` (`humanish.actor-estimated-cost.v1`): a token-derived
+  cost ESTIMATE for this lane (see Run Cost Summary And Estimated Actor Cost).
+  It is deliberately a DIFFERENT field from `tokenUsage.costUsd`: a bare
+  `costUsd` is RESERVED for a real provider-returned charge, while
+  `estimatedCost.estimatedCostUsd` is a rate-table multiply, named honestly as
+  an estimate so a reader can never confuse the two (invariant 6). Absent on
+  codex/scripted lanes and on every pre-existing bundle; a `null`
+  `estimatedCostUsd` is DECLARED ABSENT (unknown rate / no usage), never 0.
 
 Unexpected actor-loop diagnostics live inside `items[]` as
 `kind: notice`, `status: error` rows. They are public-safe evidence, not crash
@@ -652,19 +667,24 @@ inside run bundles (per-stream transport and status) and lab execution config
 
 `humanish serve` reports `humanish.serve-result.v1`. The exported `ServeResult`
 type and `SERVE_SCHEMA` constant in `src/observer-serve.ts` are authoritative:
-mode (`loopback | capability-link | share-safe-open`), the loopback host/port,
-capability/public URLs, runs listed, computed warnings, and the
-`ServeErrorCode` union. Capability URLs embed a live secret; they belong on the
-operator's terminal and never in a persisted or committed artifact.
-
-Reserved: `/_humanish/api/*` is the serve control-plane namespace. In v1 any
-request under it that clears the auth gate answers `501` with error code
-`HUMANISH_SERVE_CONTROL_PLANE_DISABLED`; under `--expose --auth link` a
-session-less request answers the uniform `401` first. The typed `ServeControlPlane`
-parameter exists in the handler options and is always `undefined` in v1; no
-code dispatches into it yet. Do not build against the namespace; the
-reservation guarantees only that no run artifact or observer asset will ever be
-served under it. See
+mode (`loopback | exposed | share-safe-open`), the loopback host/port,
+`publicUrl`, the `tunnel` provider/url, an `oauth` echo (`provider`,
+`allowEmails`, `allowDomains` — operator-supplied allow rules, public-safe to
+echo to the operator's own stdout, never persisted into any bundle), runs
+listed, computed warnings, and the `ServeErrorCode` union. Exposure auth is
+tunnel-edge only — as of 0.19.0 there are no `capabilityUrl`/`publicCapabilityUrl`
+/`ttlMinutes` fields, no `--auth`/`--ttl` flags, and no `capability-link` mode
+(the in-process `observer-auth.ts` capability-link was removed as a pre-1.0
+breaking change).
+
+Reserved: `/_humanish/api/*` is the serve control-plane namespace. Any request
+under it answers `501` with error code `HUMANISH_SERVE_CONTROL_PLANE_DISABLED`.
+Because the in-process auth gate is gone, a request that clears the edge (or a
+loopback caller) reaches the `501` directly — there is no `401`-first anymore.
+The typed `ServeControlPlane` parameter exists in the handler options and is
+always `undefined` in v1; no code dispatches into it yet. Do not build against
+the namespace; the reservation guarantees only that no run artifact or observer
+asset will ever be served under it. See
 [`docs/architecture/serve.md`](../architecture/serve.md) for the v2 seam
 contract.
 
@@ -734,6 +754,82 @@ measure) and never grant a green pass (they surface as unmeasured). `verifyRun`
 fails closed when a live bundle lacks the cost ledger or no-spend proof, when the
 proof claims zero on a `null` line, or when known spend exceeds the declared cap.
 
+## Run Cost Summary And Estimated Actor Cost
+
+The computer-use (CUA) lane surfaces an ADVISORY, additive cost ESTIMATE. It is
+never authoritative: every dollar figure is a rate-table multiply, labeled
+"estimated (rates as of `<date>`)", and is NEVER presented as a provider charge
+(invariant 6). Three new `.v1` schema tags ship, all additive and optional so
+`humanish.run-bundle.v1` stays v1 and every pre-existing bundle is byte-stable:
+
+- `humanish.pricing.v1` — the OPERATOR-EDITABLE rate table in `src/pricing.ts`:
+  dated per-model input/output USD-per-token rates and an E2B desktop
+  USD-per-minute rate, each with a public pricing-page `source` and an `asOf`
+  date. A prominent banner says these are estimates to update when providers
+  change pricing. Some entries are `placeholder: true` stand-ins (the shipped
+  `gpt-5.5` model rate and the E2B desktop rate) — an operator MUST confirm them
+  before trusting the magnitude; the flag propagates into every estimate so a
+  stand-in is never mistaken for a live rate. An UNKNOWN model/desktop rate is
+  DECLARED ABSENT (`estimatedCostUsd: null` + a `reason`), never guessed.
+- `humanish.actor-estimated-cost.v1` — `ActorTrace.estimatedCost`: one lane's
+  token-derived model cost, with `estimatedCostUsd` (or `null` + `reason`
+  `no_rate_for_model`/`no_token_usage`), `ratesAsOf`, `source`, `modelId`,
+  optional `placeholder`, and a `breakdown`.
+- `humanish.run-cost-summary.v1` — `RunBundle.cost`: the sum of every lane's
+  `model-tokens` line PLUS one aggregate `desktop-minutes` line.
+
+The summary follows the SAME null discipline as the terminal cost ledger above.
+`estimatedTotalUsd` sums ONLY the non-null `breakdown` lines and is `null` iff
+EVERY line is null (never coerced to `0`); a present-but-unpriceable line stays
+in `breakdown` with `estimatedCostUsd: null` + a `reason` (it records that we
+tried and could not price it) and contributes nothing. `fullyEstimated` is
+`false` when any applicable line is null (the total is then a lower bound);
+`placeholder` is true when any contributing rate is a stand-in; `ratesAsOf` is
+the MIN (oldest) `asOf` across contributing rates — an aggregate is only as fresh
+as its stalest input, so MAX would overclaim freshness (each `breakdown` line
+keeps its own true `asOf`). `desktopMinutes` is a HOST-SIDE
+create→teardown span — an approximation of E2B's server-side billed lifetime, so
+the desktop dollar figure is doubly an estimate.
+
+```yaml
+schema: humanish.run-cost-summary.v1
+currency: usd
+estimatedTotalUsd: 11.60167          # sum of KNOWN lines only; null iff every line null
+ratesAsOf: "2026-08-01"
+fullyEstimated: true                  # both breakdown lines are priced (no null line)
+placeholder: true                     # a stand-in rate contributed
+breakdown:
+  - { kind: model-tokens, laneId: lane-01, modelId: computer-use-preview,
+      estimatedCostUsd: 11.60, ratesAsOf: "2026-08-01", source: "openai.com/api/pricing" }
+  - { kind: desktop-minutes, estimatedCostUsd: 0.00167, ratesAsOf: "2026-08-01",
+      source: "…e2b.dev/pricing", placeholder: true }
+tokenUsage: { input: 3843523, output: 5869, total: 3849392 }
+desktopMinutes: 1
+note: "Estimated 11.60167 USD total…"
+```
+
+`verifyRun` asserts LABELING/provenance, never MAGNITUDE. Absence PASSES
+(fail-open on display): a bundle with no cost, a null estimate, or a lane without
+`estimatedCost` verifies fine. A CLAIMED number FAILS closed when it lacks its
+`ratesAsOf` date or `source`, or when `estimatedTotalUsd` does not equal the
+rounded sum of its non-null lines (a null line coerced to 0 is a mechanism
+mismatch). A correctly-labeled huge estimate still passes. Cost is neither a
+secret nor a share-blocker, so it never affects `shareSafety`.
+
+**Fail-closed spend cap.** `execution.caps.maxUsd` (the terminal lane's
+`LabScenarioCaps` shape, consumed on the CUA route) aborts a session the moment
+its running ESTIMATED spend crosses the cap — the runaway-retry guard. It is a
+**PER-LANE** cap: enforced INSIDE each lane's loop independently, so an N-lane
+fan-out can spend up to N × `maxUsd` before any lane aborts (the run bundle
+warns with the true ~N × cap ceiling; a shared run-level budget is future work).
+A lane that does real work THEN crosses its cap ends `budget_reached` (passed); a
+zero-action runaway that crosses it ends `gave_up` (failed) — the cap classifies
+its outcome honestly rather than greenlighting the runaway it exists to catch.
+Absent = uncapped (the historical behavior); `maxUsd: 0` = no-spend. A cap on a
+model `src/pricing.ts` cannot price is REFUSED at preflight
+(`HUMANISH_CUA_LAB_UNPRICED_CAP`) before any sandbox rather than run uncapped —
+an unenforceable cap is more dangerous than none.
+
 ## Product-Adapter Extension Seam
 
 The terminal-product and browser/computer-use lanes let an adopter attach

package/docs/goals/current.md

@@ -16,7 +16,7 @@ Humanish should be the open-source CLI that lets a maintainer ask:
 The answer should be observable, verifiable, public-safe, and easy to turn into
 actionable feedback.
 
-## Current Program Truth (source `0.17.0`)
+## Current Program Truth (source `0.19.0`)
 
 The package source and repository implementation in this tree agree on these
 points:

package/docs/principles/invariants-and-defaults.md

@@ -74,7 +74,8 @@ silently drifting from one is not.
 | Single lane | Cost + evidence simplicity | Declared fan-out where the backend supports it — `actors[0].count: N` (homogeneous), explicit `actors[0].lanes[]` (differentiated persona/device/instruction), or compact `actors[0].roster[]` groups that normalize into lanes on the computer-use E2B route (per-lane worlds, cap 16; `execution.concurrency` bounds concurrent paid lanes) |
 | Stock `desktop` template | The stock E2B desktop image is right for most subjects; absent `execution.desktop.template` keeps `Sandbox.create(opts)` byte-stable | `execution.desktop.template` names a custom E2B desktop image (any name/id, no allowlist) for a subject needing baked-in runtimes the stock image lacks (e.g. node/bun/a local Postgres) — threaded to `Sandbox.create(template, opts)` on every desktop-creating route and recorded in the bundle as `desktopTemplate` (public-safe) |
 | Desktop default URL opener | Preserve the route/image's historical browser/default opener behavior when unset | `execution.desktop.browser: chrome | chromium | firefox` makes hosted CUA/shared-world browser choice explicit, fail-closed, and recorded as `desktopBrowser` in the run bundle |
-| Loopback-only observer serving | Run bundles are local by default (public-safety plank 3); the serve surface binds `127.0.0.1` unconditionally, and exposing the library is publishing-adjacent, so it carries declared friction | `humanish serve --expose` (secret capability link + a declared public origin via `--tunnel`/`--public-url`) or `--expose --safe --auth none` (open mode, gated on verify-`share_ready` runs only); both print computed warnings naming exactly what became reachable |
+| Loopback-only observer serving | Run bundles are local by default (public-safety plank 3); the serve/watch surfaces bind `127.0.0.1` unconditionally, and exposing them is publishing-adjacent, so exposure is fail-closed and carries declared friction | `humanish serve --expose` behind TUNNEL-EDGE auth — ngrok `--oauth google` (`--allow-email`/`--allow-domain` allow rules) or an operator `--public-url` you secure — OR `--expose --safe` (open, gated on verify-`share_ready` runs only). `watch --expose` streams a live run behind edge auth (a live run is never `share_ready`, so `--safe` alone is refused). humanish carries no in-process auth; both print computed warnings naming exactly what became reachable |
+| Generous wall-clock safety cap | `execution.timeoutMs` bounds runaway spend, not a goal; ~30 min is reasonable for open-ended "watch it play" | A session that reaches the cap AFTER productive activity is recorded as `budget_reached` (status `passed`, a NON-FAILURE completion, exit `0`), distinct from a zero-progress `timed_out` (a failure, exit `2`). Goal-directed labs set a tight `timeoutMs` and read `completionReason` to confirm the goal, not the cap |
 
 ## The placement rule (worked example)
 

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.17.0` (2026-08-02). The containment boundary introduced in
+Package/source version in this tree: `0.19.0` (2026-08-02). The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [

package/dist/observer-auth.d.ts

@@ -1,21 +0,0 @@
-export declare const SERVE_COOKIE_NAME = "humanish_serve";
-export interface ServeSessionStore {
-    mint(): {
-        cookieValue: string;
-    };
-    validate(cookieHeader: string | undefined): boolean;
-    revokeAll(): void;
-    sessionCount(): number;
-}
-export declare function mintServeToken(): string;
-export declare function sha256Digest(value: string): Buffer;
-export declare function verifyTokenDigest(candidate: string, digest: Buffer): boolean;
-export declare function createServeSessionStore(options: {
-    ttlMs: number;
-    now?: () => number;
-}): ServeSessionStore;
-export declare function parseCookies(header: string | undefined): Record<string, string>;
-export declare function buildSessionCookie(cookieValue: string, options: {
-    ttlSeconds: number;
-    secure: boolean;
-}): string;

package/dist/observer-auth.js

@@ -1,92 +0,0 @@
-import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
-export const SERVE_COOKIE_NAME = "humanish_serve";
-export function mintServeToken() {
-    return randomBytes(32).toString("base64url");
-}
-export function sha256Digest(value) {
-    return createHash("sha256").update(value, "utf8").digest();
-}
-// Hash-first comparison: both sides become fixed-length digests before
-// timingSafeEqual, so an attacker-controlled candidate can neither throw on
-// length mismatch nor learn the token length.
-export function verifyTokenDigest(candidate, digest) {
-    return timingSafeEqual(sha256Digest(candidate), digest);
-}
-export function createServeSessionStore(options) {
-    const now = options.now ?? (() => Date.now());
-    const sessions = new Map();
-    return {
-        mint() {
-            // Sweep expired records on each mint so the map cannot grow without bound
-            // when many links are tapped: without this, a record is only pruned when
-            // its own cookie is presented again, which an abandoned session never is.
-            const currentTime = now();
-            for (const [digest, record] of sessions) {
-                if (record.expiresAt <= currentTime) {
-                    sessions.delete(digest);
-                }
-            }
-            const cookieValue = randomBytes(32).toString("base64url");
-            sessions.set(sha256Digest(cookieValue).toString("hex"), {
-                expiresAt: currentTime + options.ttlMs,
-                scope: "viewer"
-            });
-            return { cookieValue };
-        },
-        validate(cookieHeader) {
-            const cookieValue = parseCookies(cookieHeader)[SERVE_COOKIE_NAME];
-            if (!cookieValue) {
-                return false;
-            }
-            const record = sessions.get(sha256Digest(cookieValue).toString("hex"));
-            if (!record || record.scope !== "viewer") {
-                return false;
-            }
-            if (record.expiresAt <= now()) {
-                sessions.delete(sha256Digest(cookieValue).toString("hex"));
-                return false;
-            }
-            return true;
-        },
-        revokeAll() {
-            sessions.clear();
-        },
-        sessionCount() {
-            return sessions.size;
-        }
-    };
-}
-export function parseCookies(header) {
-    if (!header) {
-        return {};
-    }
-    const cookies = {};
-    for (const part of header.split(";")) {
-        const separator = part.indexOf("=");
-        if (separator <= 0) {
-            continue;
-        }
-        const name = part.slice(0, separator).trim();
-        const value = part.slice(separator + 1).trim();
-        if (name) {
-            cookies[name] = value;
-        }
-    }
-    return cookies;
-}
-export function buildSessionCookie(cookieValue, options) {
-    const attributes = [
-        `${SERVE_COOKIE_NAME}=${cookieValue}`,
-        "Path=/",
-        "HttpOnly",
-        "SameSite=Lax",
-        `Max-Age=${options.ttlSeconds}`
-    ];
-    if (options.secure) {
-        attributes.push("Secure");
-    }
-    // Deliberately no Domain attribute: a host-only cookie on the public origin
-    // can never leak to sibling subdomains of a shared tunnel domain.
-    return attributes.join("; ");
-}
-//# sourceMappingURL=observer-auth.js.map