humanish 0.16.0 → 0.18.0

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.16.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.18.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.
@@ -46,6 +46,8 @@ workflow without leaking private upstream truth into core.
 | 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 |
+| Serve result | `humanish.serve-result.v1` (`src/observer-serve.ts` is authoritative) | none (command result envelope; see Serve Result below) |
+| Serve control plane | reserved (`/_humanish/api/*` answers `501` `HUMANISH_SERVE_CONTROL_PLANE_DISABLED` in v1) | none |
 
 ## Lab Manifest
 
@@ -599,7 +601,11 @@ 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`
 
 Unexpected actor-loop diagnostics live inside `items[]` as
@@ -646,6 +652,31 @@ never shipped — no code emits or validates it. Substrate truth today lives
 inside run bundles (per-stream transport and status) and lab execution config
 (`execution.target: local | e2b-desktop`). Do not emit this schema.
 
+## Serve Result And Reserved Control-Plane Namespace
+
+`humanish serve` reports `humanish.serve-result.v1`. The exported `ServeResult`
+type and `SERVE_SCHEMA` constant in `src/observer-serve.ts` are authoritative:
+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.18.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.
+
 ## Terminal Cost Ledger And No-Spend Proof
 
 The terminal-product lane (`src/e2b-terminal-lab.ts`) passes a real provider key

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.16.0`)
+## Current Program Truth (source `0.18.0`)
 
 The package source and repository implementation in this tree agree on these
 points:
@@ -32,6 +32,7 @@ The immutable 2026-06-10 proof-roadmap packet is paired with a
 | Subject sources/routes | Six declared sources: `this-repo`, `clone`, `app-url`, `local-app`, `terminal-product`, and `local-tree`; support is route-specific and `this-repo` remains dry-run-only | One centralized run/resource lifecycle boundary across all routes |
 | Public proof | Version-pinned synthetic Observer sample shipped in the npm payload | A legible Observer hero from one verified real public-application run |
 | OSS meta-lab | Dry-run contract and separate disposable smoke harness | Live meta-lab execution; disabled until repository instructions and actor credentials have an isolated boundary |
+| Observer serving | `watch`/`observe` loopback servers plus `serve` — the run-library surface with loopback default, capability-link exposure, `share_ready`-gated open mode, and optional operator-run tunnel; streams never served remotely | A remote live-stream (`--live-streams`) design; a persistent capability-link store; a control plane that can start runs |
 
 Capability proof and adopter replacement are different gates. A deterministic
 test or kept live receipt proves that a Humanish mechanism works. The depth-axis

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

@@ -74,6 +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/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.16.0` (2026-08-01). The containment boundary introduced in
+Package/source version in this tree: `0.18.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.16.0",
+  "version": "0.18.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [