humanish 0.17.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.17.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.
@@ -601,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
@@ -652,19 +656,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.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.
 

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.18.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.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.17.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": [

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

package/dist/observer-auth.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"observer-auth.js","sourceRoot":"","sources":["../src/observer-auth.ts"],"names":[],"mappings":"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"}