humanish 0.110.1 → 0.110.3

package/dist/study/parse/subject.js

@@ -2,6 +2,7 @@ import { normalizeExtraExcludeEntry } from "../../subject/local-tree-archive.js"
 import { ENV_NAME_PATTERN, invalid, posInt, str, strList } from "./values.js";
 import { parseEnvValues, parseState, subjectStateInvalidReason } from "./subject-state.js";
 import { isRecord } from "../../run/type-guards.js";
+import { urlCredentialReason } from "./url-credentials.js";
 export function parseSubject(raw) {
     if (!isRecord(raw)) {
         return invalid("`subject` is required and must be an object.");
@@ -175,7 +176,7 @@ function parseServedApp(raw, subject) {
         return stateResult;
     }
     if (stateResult.value) {
-        // Semantic validation is shared with the engine (runCuaActorStudy re-enforces it for
+        // Semantic validation is shared with the engine (planComputerUseStudy re-enforces it for
         // configs that arrive through the library API without the parser).
         const reason = subjectStateInvalidReason(stateResult.value, subject.env);
         if (reason) {
@@ -202,6 +203,9 @@ function parseAppSubject(raw, source, subject) {
     else if (!isHttpUrl(appUrl)) {
         return invalid("`subject.appUrl` must be an http(s) URL.");
     }
+    const credential = urlCredentialReason("subject.appUrl", appUrl);
+    if (credential)
+        return invalid(credential);
     subject.appUrl = appUrl;
     // publicTarget (external-public shared-world ownership attestation) is app-url-only. Shape it
     // here; its required-on-that-route semantics live in externalPublicSharedWorldValidationReason.
@@ -278,6 +282,11 @@ function parseProduct(raw) {
     if (badSurface) {
         return invalid(`subject.product.publicSurfaces entries must be http(s) URLs (got "${badSurface}").`);
     }
+    const surfaceCredential = publicSurfaces
+        .map((surface) => urlCredentialReason("subject.product.publicSurfaces", surface))
+        .find((reason) => reason !== undefined);
+    if (surfaceCredential)
+        return invalid(surfaceCredential);
     return {
         ok: true,
         value: {
@@ -332,6 +341,9 @@ function parseServe(raw) {
     if (!url || !isLoopbackUrl(url)) {
         return invalid("`subject.serve.url` must be a loopback http(s) URL (127.0.0.1 or localhost), because the app runs inside the sandbox.");
     }
+    const credential = urlCredentialReason("subject.serve.url", url);
+    if (credential)
+        return invalid(credential);
     const serve = { start, url };
     const install = str(raw.install);
     if (install)

package/dist/study/parse/url-credentials.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Why the URL declared at `field` cannot be used: it has userinfo, or its path, query or fragment
+ * holds a value verify flags as a secret, as written or encoded. Undefined for a URL with neither,
+ * and for text that is not a URL, which the field's own shape check refuses. `base` resolves a
+ * relative entry path.
+ */
+export declare function urlCredentialReason(field: string, value: string, base?: string): string | undefined;
+/** Why the participant entry at `field` cannot be used, resolved as a path on the subject. */
+export declare function entryCredentialReason(field: string, entry: string): string | undefined;

package/dist/study/parse/url-credentials.js

@@ -0,0 +1,50 @@
+// A URL a study declares is recorded in the run, shown in the participant's address bar and so in
+// every screenshot and model request. It may not carry a credential. Ordinary query parameters,
+// such as a filter or a page number, stay as they are.
+import { scanEncodedText } from "../../evidence/encoded-text.js";
+// A relative participant entry is resolved against this before it is read.
+const ENTRY_BASE = "http://127.0.0.1/";
+/**
+ * Why the URL declared at `field` cannot be used: it has userinfo, or its path, query or fragment
+ * holds a value verify flags as a secret, as written or encoded. Undefined for a URL with neither,
+ * and for text that is not a URL, which the field's own shape check refuses. `base` resolves a
+ * relative entry path.
+ */
+export function urlCredentialReason(field, value, base) {
+    let url;
+    try {
+        url = new URL(value, base);
+    }
+    catch {
+        return undefined;
+    }
+    // The URL parser drops tabs and line breaks, which can split a key the scan would otherwise read.
+    if (/[\u0000-\u001f\u007f]/.test(value))
+        return `\`${field}\` has a tab, line break or other control character in it, which the URL parser drops. Write the URL without it.`;
+    if (url.username !== "" || url.password !== "")
+        return `\`${field}\` has a user name or password in it. humanish records the URL in the run, and the participant's browser shows it in every screenshot, so the credential would reach the bundle and the model. Remove it from the URL and give the participant a test account to sign in with.`;
+    if (urlPartsHoldSecret(value, url))
+        return `\`${field}\` carries a credential in its path, query or fragment, such as a token, a signature or a preview bypass parameter. humanish records the URL in the run, and the participant's browser shows it in every screenshot. Remove it from the URL. For a protected preview, make the deployment reachable without a token for the study, or build the app in the desktop with a clone subject.`;
+    return undefined;
+}
+/** Why the participant entry at `field` cannot be used, resolved as a path on the subject. */
+export function entryCredentialReason(field, entry) {
+    return urlCredentialReason(field, entry, ENTRY_BASE);
+}
+/**
+ * Whether the URL's path, query or fragment holds a secret: read whole, as the parser normalized
+ * it and as written (`..` segments can drop a segment from the normalized path), and one segment,
+ * value or fragment piece at a time, so the text around an encoded key cannot shift its decoding.
+ */
+function urlPartsHoldSecret(value, url) {
+    const written = value.replace(/^[a-z][a-z0-9+.-]{0,31}:\/\/[^/?#]*/i, "");
+    const normalized = `${url.pathname}${url.search}${url.hash}`;
+    const pieces = [
+        written,
+        normalized,
+        ...written.split(/[/?#&=;]/),
+        ...normalized.split(/[/?#&=;]/),
+    ];
+    return pieces.some((piece) => piece.length > 0 &&
+        scanEncodedText(piece, { secretsOnly: true, allowOpaqueBase64: true }).sensitive);
+}

package/dist/study/preflight-probes.js

@@ -14,6 +14,7 @@ import { redactText } from "../evidence/redaction.js";
 import { digest, fail, finalize } from "./preflight-result.js";
 import { rosterOf } from "./parse/actors.js";
 import { plural } from "../run/text.js";
+import { cli } from "../cli/invocation.js";
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 // Room on the probe's lease for desktop boot and teardown around the work it does.
 const PREFLIGHT_LEASE_BUFFER_MS = 5 * 60_000;
@@ -240,7 +241,7 @@ async function settlePreflightJournal(ctx, journal, gone) {
         return;
     if (!gone) {
         await abandonPreflightJournal(journal).catch(() => undefined);
-        ctx.warnings.push(`The preflight sandbox's receipt stays in .humanish/preflight/${journal.id}; run \`humanish reclaim --preflight\` to kill it by id.`);
+        ctx.warnings.push(`The preflight sandbox's receipt stays in .humanish/preflight/${journal.id}; run \`${cli("reclaim --preflight")}\` to kill it by id.`);
         return;
     }
     await discardPreflightJournal(journal).catch((error) => {

package/dist/study/types.d.ts

@@ -448,10 +448,11 @@ export interface StudyExecutionTerminal {
     stdin?: StudyTerminalStdin;
 }
 /**
- * The terminal agent's runtime-auth channel. "openai-env" (the default) passes the raw runtime
- * key command-scoped. "openai-egress" keeps it in an E2B outbound header transform for the default
- * OpenAI endpoint and passes an inert placeholder to Codex. The latter still gives every sandbox
- * process a spendable OpenAI proxy capability; it is not a spend cap or an egress restriction.
+ * The terminal agent's runtime-auth channel. "openai-egress" (the default) keeps the raw runtime
+ * key in an E2B outbound header transform for the default OpenAI endpoint and passes an inert
+ * placeholder to Codex. It still gives every sandbox process a spendable OpenAI proxy capability;
+ * it is not a spend cap or an egress restriction. "openai-env" passes the raw key command-scoped,
+ * where the agent and its child processes can read it.
  */
 export type StudyRuntimeAuth = "openai-env" | "openai-egress";
 export type StudyDesktopBrowser = "default" | "chrome" | "chromium" | "firefox";
@@ -559,8 +560,9 @@ export interface StudyExecution {
     caps?: StudyScenarioCaps;
     /** `terminal-product` route: the terminal transport + stdin posture. Consumed on that route. */
     terminal?: StudyExecutionTerminal;
-    /** `terminal-product` route: runtime key placement, defaulting to openai-env. openai-egress
-     *  uses an external header transform; dry-runs record declarations only. Inert on other routes. */
+    /** `terminal-product` route: runtime key placement, defaulting to openai-egress, an external
+     *  header transform. openai-env passes the key to the agent command. Dry-runs record declarations
+     *  only. Inert on other routes. */
     runtimeAuth?: StudyRuntimeAuth;
     /** Terminal Codex package pin. Omit to resolve latest once, observe it, then execute that version. */
     runtime?: {

package/dist/study/url-credentials.d.ts

@@ -0,0 +1,6 @@
+import type { StudyConfig } from "./types.js";
+/**
+ * The first URL in `config` that carries a credential, with why: the subject's app, serve and
+ * public surface URLs, and each participant's target and entry.
+ */
+export declare function studyUrlCredentialReason(config: StudyConfig): string | undefined;

package/dist/study/url-credentials.js

@@ -0,0 +1,34 @@
+// Every URL a study config declares, checked for a credential. Route planners call it, since a
+// library caller's config skips the parser that refuses these first.
+import { rosterOf } from "./parse/actors.js";
+import { entryCredentialReason, urlCredentialReason } from "./parse/url-credentials.js";
+/**
+ * The first URL in `config` that carries a credential, with why: the subject's app, serve and
+ * public surface URLs, and each participant's target and entry.
+ */
+export function studyUrlCredentialReason(config) {
+    const { subject } = config;
+    const reasons = [
+        () => subject.appUrl === undefined
+            ? undefined
+            : urlCredentialReason("subject.appUrl", subject.appUrl),
+        () => subject.serve === undefined
+            ? undefined
+            : urlCredentialReason("subject.serve.url", subject.serve.url),
+        ...(subject.product?.publicSurfaces ?? []).map((surface) => () => urlCredentialReason("subject.product.publicSurfaces", surface)),
+        ...config.actors.flatMap((actor) => (rosterOf(actor) ?? []).flatMap((participant, index) => [
+            () => participant.target === undefined
+                ? undefined
+                : urlCredentialReason(`participants[${index}].target`, participant.target),
+            () => participant.entry === undefined
+                ? undefined
+                : entryCredentialReason(`participants[${index}].entry`, participant.entry),
+        ])),
+    ];
+    for (const reason of reasons) {
+        const found = reason();
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}

package/dist/substrates/e2b/sandbox.js

@@ -4,8 +4,9 @@
 // provider error, capture of the exact id and kill authority, and a provider-qualified receipt in
 // the run directory before the caller gets the handle. The desktop startup guard
 // (guardDesktopSandboxCreate) is installed by loadE2BDesktopModule, so a create whose desktop
-// startup fails has already reclaimed its handle when the error reaches the retry here, and it
-// reports the id to the registry before desktop startup begins.
+// startup fails has already reclaimed its handle when the error reaches the retry here. The guard
+// reports the id before desktop startup begins, and the id goes to the registry and the receipt
+// journal at that point, so a startup error that quotes it is scrubbed from every run file.
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { beginSandboxCreate, recordSandboxOwnerOnce, SandboxCreateRefusedError, sandboxOwnerTags, } from "../../run/sandbox-creates.js";
 import { appendSandboxOwner, appendSandboxReceipt } from "../../run/sandbox-receipts.js";
@@ -24,6 +25,9 @@ async function acquire(request, template) {
     const target = request.receipt;
     // Refused before any provider call once the run is stopping.
     const ticket = target === null ? undefined : beginSandboxCreate(target.root, target.participantId);
+    // The receipts written when the guard reported an id, before desktop startup. A startup error
+    // can quote the id and the create may never return, so the journal holds it first.
+    const reported = new Map();
     try {
         // The owner tags let reclaim find this sandbox on E2B even if its id never reaches this
         // process: a create that throws after E2B allocated, or a process that dies mid-create. The
@@ -34,8 +38,26 @@ async function acquire(request, template) {
         const options = owner === undefined
             ? request.options
             : { ...request.options, metadata: { ...request.options.metadata, ...owner } };
+        const receipt = (sandboxId) => {
+            if (target === null)
+                return Promise.resolve(false);
+            const { root, participantId, now = Date.now } = target;
+            return appendSandboxReceipt(root, {
+                at: new Date(now()).toISOString(),
+                laneId: participantId,
+                provider: "e2b",
+                sandboxId,
+                ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            });
+        };
         if (ticket !== undefined)
-            observeDesktopAllocation(options, (sandboxId) => ticket.created(sandboxId));
+            observeDesktopAllocation(options, (sandboxId) => {
+                ticket.created(sandboxId);
+                // Started synchronously, so the run's writers know the id at once. A clock that throws
+                // fails only this write; the receipt after create throws it again.
+                if (!reported.has(sandboxId))
+                    reported.set(sandboxId, new Promise((resolve) => resolve(receipt(sandboxId))).catch(() => false));
+            });
         const sandbox = await withOneRetryOnTransientE2BError(() => {
             if (ticket?.stopping())
                 throw new SandboxCreateRefusedError();
@@ -47,18 +69,11 @@ async function acquire(request, template) {
         ticket?.created(sandbox.sandboxId);
         const allocation = ownE2BSandbox(module, sandbox.sandboxId, ticket);
         try {
-            if (target !== null) {
-                const { root, participantId, now = Date.now } = target;
-                // Best effort by contract: a failed write leaves the owner tags and the TTL as the
-                // backstops and never fails the participant.
-                await appendSandboxReceipt(root, {
-                    at: new Date(now()).toISOString(),
-                    laneId: participantId,
-                    provider: "e2b",
-                    sandboxId: allocation.resourceId,
-                    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
-                });
-            }
+            // Best effort by contract: a failed write leaves the owner tags and the TTL as the
+            // backstops and never fails the participant. One line per sandbox: a receipt the guard's
+            // report wrote is not written again, so reclaim counts the sandbox once.
+            if (!(await reported.get(allocation.resourceId)))
+                await receipt(allocation.resourceId);
         }
         catch (error) {
             // The caller never receives this sandbox, so release it here. A throwing or invalid injected
@@ -69,6 +84,9 @@ async function acquire(request, template) {
         return { sandbox, allocation };
     }
     finally {
+        // A create that threw settles once its reported receipts are on disk, as one that returned
+        // does. These writes never reject.
+        await Promise.all(reported.values());
         ticket?.settled();
     }
 }

package/dist/substrates/local/firecracker-desktop.js

@@ -9,6 +9,7 @@ import { ownDesktopAllocation, } from "../desktop-session.js";
 import { runtimeDocker, runtimeExec, usesLima } from "./runtime-host.js";
 import { openLimaTunnel } from "./runtime-ssh.js";
 import { guestMediaConfigSchema } from "../../guest/media-config.js";
+import { cli } from "../../cli/invocation.js";
 const docker = async (args) => (await runtimeDocker(args, {}, 60_000)).stdout.trim();
 const readLogs = async (id) => {
     const result = await runtimeDocker(["logs", "--tail", "100", id], {}, 10_000);
@@ -18,12 +19,12 @@ function checkDesktopOptions(options) {
     if (options.media !== undefined) {
         guestMediaConfigSchema.parse(options.media);
         if (options.assets.media !== true)
-            throw new Error("This local runtime does not include media. Run humanish runtime setup --media.");
+            throw new Error(`This local runtime does not include media. Run ${cli("runtime setup --media")}.`);
     }
     if (options.recording !== undefined) {
         desktopRecordingConfigSchema.parse(options.recording);
         if (options.assets.media !== true)
-            throw new Error("This runtime does not include the recorder. Run humanish runtime setup --media.");
+            throw new Error(`This runtime does not include the recorder. Run ${cli("runtime setup --media")}.`);
     }
     let url;
     try {

package/dist/substrates/local/runtime-host.js

@@ -3,6 +3,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { cli } from "../../cli/invocation.js";
 const exec = promisify(execFile);
 export const LIMA_INSTANCE = "humanish-runtime";
 export const usesLima = (options = {}) => (options.platform ?? process.platform) === "darwin";
@@ -86,11 +87,11 @@ export async function limaStatus(options = {}) {
         version = (await hostExec("limactl", ["--version"], options)).stdout;
     }
     catch {
-        throw new Error("Install Lima 2.2 or newer (brew install lima), then run humanish runtime setup. Docker Desktop is not required.");
+        throw new Error(`Install Lima 2.2 or newer (brew install lima), then run ${cli("runtime setup")}. Docker Desktop is not required.`);
     }
     const match = /\b(\d+)\.(\d+)\.\d+/.exec(version);
     if (!match || Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 2))
-        throw new Error("Update Lima to 2.2 or newer (brew upgrade lima), then run humanish runtime setup.");
+        throw new Error(`Update Lima to 2.2 or newer (brew upgrade lima), then run ${cli("runtime setup")}.`);
     const output = (await hostExec("limactl", ["list", "--json"], options)).stdout.trim();
     const instance = output
         .split("\n")
@@ -104,8 +105,8 @@ export async function limaStatus(options = {}) {
         ready: instance?.status === "Running",
         exists: !!instance,
         message: instance
-            ? "The humanish Lima host is stopped. Run humanish runtime setup to start it."
-            : "Run humanish runtime setup to create the humanish Lima host and install the browser runtime.",
+            ? `The humanish Lima host is stopped. Run ${cli("runtime setup")} to start it.`
+            : `Run ${cli("runtime setup")} to create the humanish Lima host and install the browser runtime.`,
     };
 }
 export async function prepareLima(options = {}, progress) {

package/dist/substrates/local/runtime.js

@@ -7,6 +7,7 @@ import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { LOCAL_MEDIA_RUNTIME_RELEASES, LOCAL_RUNTIME_RELEASES } from "./runtime-release.js";
 import { limaStatus, loadRuntimeArchive, prepareLima, runtimeArchitecture, runtimeDocker, runtimeExec, usesLima, } from "./runtime-host.js";
+import { cli } from "../../cli/invocation.js";
 const docker = async (args, options) => (await runtimeDocker(args, options)).stdout.trim();
 const runtimeRelease = (options) => options.release ??
     (options.media ? LOCAL_MEDIA_RUNTIME_RELEASES : LOCAL_RUNTIME_RELEASES)[runtimeArchitecture(options) ?? "amd64"];
@@ -80,7 +81,7 @@ export async function localRuntimeStatus(options = {}) {
             installed: false,
             message: lima
                 ? "Docker is unavailable inside the humanish Lima host. Check limactl shell humanish-runtime -- sudo systemctl status docker; Docker Desktop is not used."
-                : "Docker is unavailable. Install/start Docker Engine and give your account access, then run humanish runtime setup.",
+                : `Docker is unavailable. Install/start Docker Engine and give your account access, then run ${cli("runtime setup")}.`,
         };
     }
     const release = runtimeRelease(options);
@@ -108,7 +109,7 @@ export async function localRuntimeStatus(options = {}) {
             : {
                 ok: true,
                 installed: false,
-                message: "Local runtime will download before the first live run. Run humanish runtime setup to prepare it now.",
+                message: `Local runtime will download before the first live run. Run ${cli("runtime setup")} to prepare it now.`,
             };
     }
     const image = images[0];
@@ -161,7 +162,7 @@ export async function prepareLocalRuntime(options = {}) {
     try {
         const response = await fetch(release.url, { signal });
         if (!response.ok || !response.body)
-            throw new Error(`Runtime download failed (HTTP ${response.status}). Run humanish runtime setup to retry.`);
+            throw new Error(`Runtime download failed (HTTP ${response.status}). Run ${cli("runtime setup")} to retry.`);
         let bytes = 0;
         const hash = createHash("sha256");
         await pipeline(Readable.fromWeb(response.body), new Transform({
@@ -181,7 +182,7 @@ export async function prepareLocalRuntime(options = {}) {
         await loadRuntimeArchive(archive, { ...options, signal });
         const after = await localRuntimeStatus(options);
         if (!after.assets)
-            throw new Error("Downloaded runtime did not provide the expected image. Run humanish runtime setup to retry.");
+            throw new Error(`Downloaded runtime did not provide the expected image. Run ${cli("runtime setup")} to retry.`);
         return after.assets;
     }
     finally {

package/dist/tui/contract.js

@@ -12,6 +12,7 @@
 //
 // It also makes the UI testable without a terminal: a test hands `startTui` a fake index and reads
 // the frames back.
+import { cli } from "../cli/invocation.js";
 /** Node version the Ink runtime requires (ink@7 declares `engines.node >= 22`). */
 export const TUI_MIN_NODE_MAJOR = 22;
 /**
@@ -41,12 +42,12 @@ export const TUI_BUNDLE_URL = new URL("../tui-app.js", import.meta.url);
  */
 export function terminalSurfaceMessage(state) {
     if (!state.supported) {
-        return `\`humanish tui\` needs Node ${TUI_MIN_NODE_MAJOR}+ (this is ${state.nodeVersion}); every other command works here`;
+        return `\`${cli("tui")}\` needs Node ${TUI_MIN_NODE_MAJOR}+ (this is ${state.nodeVersion}); every other command works here`;
     }
     if (!state.bundlePresent) {
-        return "`humanish tui` is not built in this checkout; run `pnpm build` (installed packages ship it prebuilt)";
+        return `\`${cli("tui")}\` is not built in this checkout; run \`pnpm build\` (installed packages ship it prebuilt)`;
     }
     return state.interactive
-        ? "`humanish tui` opens the interactive surface for browsing studies and runs"
-        : "`humanish tui` is the interactive screen a person uses to watch and start runs here. This shell is not a terminal, so pass it on to a person at one";
+        ? `\`${cli("tui")}\` opens the interactive surface for browsing studies and runs`
+        : `\`${cli("tui")}\` is the interactive screen a person uses to watch and start runs here. This shell is not a terminal, so pass it on to a person at one`;
 }

package/dist/verify/liveness.js

@@ -11,6 +11,7 @@ import { runLiveness } from "../run/run-index.js";
 import { parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
 import { RUN_STATUS_FILE } from "../run/status.js";
 import { plural } from "../run/text.js";
+import { cli } from "../cli/invocation.js";
 /** The stable code every RUN_NOT_FINISHED warning starts with. */
 const RUN_NOT_FINISHED = "RUN_NOT_FINISHED";
 const GONE_STATES = new Set(["killed", "already-gone"]);
@@ -55,7 +56,7 @@ async function reclaimState(runPaths, runId) {
     // Matched by digest: a reclaim receipt names each sandbox by digest, and one written before it
     // did holds the raw id, which is digested here.
     const journaled = new Set((journal === null ? [] : parseSandboxReceipts(journal)).map((receipt) => sandboxIdDigest(receipt.sandboxId)));
-    const command = `\`humanish reclaim --run ${runId}\``;
+    const command = `\`${cli(`reclaim --run ${runId}`)}\``;
     const receipt = reclaimReceipt(await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT), runId);
     if (receipt === undefined)
         return {

package/dist/verify/verify.js

@@ -19,6 +19,7 @@ import { rerunLineageFindings } from "./rerun.js";
 import { sharedWorldEvidenceFindings } from "./shared-world.js";
 import { subjectStateFindings, undeclaredSubjectStateWarnings } from "./subject.js";
 import { plural } from "../run/text.js";
+import { cli } from "../cli/invocation.js";
 export const VERIFY_SCHEMA = "humanish.verify-result.v1";
 // The UNSCANNED_ARTIFACT reason names this many paths and counts the rest.
 const MAX_LISTED_UNSCANNED = 10;
@@ -387,7 +388,7 @@ function buildShareSafety(args) {
         ];
         reasons.push({
             code: "RAW_SANDBOX_ID",
-            message: `Raw sandbox ids appear in ${files.sort().join(", ")}. Runs from 0.110 keep them only in sandbox-receipts.ndjson; \`humanish export --format bundle --redact-screenshots\` writes a copy without them.`,
+            message: `Raw sandbox ids appear in ${files.sort().join(", ")}. Runs from 0.110 keep them only in sandbox-receipts.ndjson; \`${cli("export --format bundle --redact-screenshots")}\` writes a copy without them.`,
         });
     }
     const rawStreamIds = rawScreenshotStreamIds(args.bundle, args.redactedShapeFrames);

package/docs/architecture/actor-contract.md

@@ -17,7 +17,7 @@ capture-vs-publish rule in
 
 `codex-exec` is a real dispatch key for terminal-product studies, but the exported
 descriptor `runSession` is a fail-closed compatibility entry. Live execution is
-owned by `runTerminalProductStudy`, which coordinates sandbox creation,
+owned by `runLiveTerminalSession` (`src/routes/terminal/session.ts`), which coordinates sandbox creation,
 command-scoped runtime auth, evidence, caps, and by-id cleanup.
 
 The `pi-agent-core` and `claude-agent-sdk` descriptors, the `app` run kind and the

package/docs/architecture/external-public-shared-world.md

@@ -64,7 +64,7 @@ public `runComputerUseLoop` refuses them. The actor passes them through
 `runComputerUseLoopWithTaps`. A library caller wraps the executor's `observe` (for `url` and
 `screenshot`) or the provider's `nextTurn` (for `reasoning` and `message`).
 
-Flow, a host-first barrier inside `runConcurrentSharedWorld`'s fan-out:
+Flow, a host-first barrier inside the shared-world route's fan-out:
 
 1. **Designated host.** Exactly one roster entry carries `host: true` (validated). Its mission = create
    the shared lobby; its browser opens `subject.appUrl`.

package/docs/architecture/terminal-product-route.md

@@ -1,7 +1,7 @@
 # Terminal-product route
 
 The live terminal-product route has shipped since `0.8.0`, with the in-sandbox runtime,
-command-scoped credential placement, exact-id cleanup proof, an interventions ledger, a cost and
+explicit credential placement (an E2B egress proxy by default, or command-scoped), exact-id cleanup proof, an interventions ledger, a cost and
 no-spend ledger, caps, and product scoring and feedback hooks. The
 [original plan](https://github.com/danielgwilson/humanish/blob/main/docs/history/goals/terminal-product-lane/goal.md)
 holds the build order and the safety contract.
@@ -24,19 +24,19 @@ fail-closed cross-validation, and forward-declared warnings.
 
 ## The composition
 
-| Axis                              | Value                                                                                                                                                       |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subject.source`                  | `terminal-product`                                                                                                                                          |
-| `subject.product`                 | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                                    |
-| `execution.target`                | `e2b-terminal` (or absent → implied)                                                                                                                        |
-| `execution.terminal`              | `{ transport: exec-stream, stdin: disabled }`                                                                                                               |
-| `execution.runtimeAuth`           | `openai-env` (default) or opt-in `openai-egress`; names-only durable evidence                                                                               |
-| `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                                     |
-| `actor.model` / `reasoningEffort` | Passed to Codex as `--model` (default `gpt-5.6-sol`) and `-c model_reasoning_effort`; declarations, not observed provider identity                          |
-| `caps`                            | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused: no adopter cost source exists until issue 347 lands                    |
-| `policies`                        | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all default false                                |
-| `actor.type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                       |
-| route                             | `terminal` → `runTerminalProductStudy` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |
+| Axis                              | Value                                                                                                                                                 |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subject.source`                  | `terminal-product`                                                                                                                                    |
+| `subject.product`                 | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                              |
+| `execution.target`                | `e2b-terminal` (or absent → implied)                                                                                                                  |
+| `execution.terminal`              | `{ transport: exec-stream, stdin: disabled }`                                                                                                         |
+| `execution.runtimeAuth`           | `openai-egress` (default) or opt-in `openai-env`; names-only durable evidence                                                                         |
+| `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                               |
+| `actor.model` / `reasoningEffort` | Passed to Codex as `--model` (default `gpt-5.6-sol`) and `-c model_reasoning_effort`; declarations, not observed provider identity                    |
+| `caps`                            | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused: no adopter cost source exists until issue 347 lands              |
+| `policies`                        | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all default false                          |
+| `actor.type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                 |
+| route                             | `terminal` → `admitTerminalPlan` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |
 
 Routing is `routeOf` (`src/study/plan.ts`). It sends every `terminal-product` subject to
 this route, even with an unregistered actor, so this route refuses the actor.
@@ -86,11 +86,8 @@ product's no-spend boundary still needs separate interpretation.
 
 ## Runtime auth: raw-key placement and remaining provider access
 
-`execution.runtimeAuth: openai-env` remains the compatible default. It supplies
-`CODEX_API_KEY` command-scoped to Codex, with `OPENAI_API_KEY` also supplied when
-that was the host source. Child processes can read and use the raw key.
-
-Opt in to keeping the raw key outside the sandbox:
+`execution.runtimeAuth: openai-egress` is the default: a study that declares no
+`runtimeAuth` keeps the raw key outside the sandbox, as if it declared:
 
 ```yaml
 execution:
@@ -115,7 +112,7 @@ output and errors, including errors during sandbox creation.
 This mode supports the default OpenAI endpoint only. humanish explicitly sets Codex's
 built-in `openai` provider and `openai_base_url` to `https://api.openai.com/v1` for
 that invocation. It does not support a custom provider, proxy base URL, or regional
-endpoint under this mode. `openai-env` retains its existing command behavior. E2B
+endpoint under this mode; a study that needs one declares `openai-env`. E2B
 header rules are a public-beta capability;
 `tests/routes/terminal/runtime-auth.test.ts` checks the local contract against the
 installed Desktop SDK (the lockfile has `@e2b/desktop` 2.4.0, resolving `e2b` 2.49.0).
@@ -136,6 +133,11 @@ requests can fail. E2B domain allowlists are routing controls rather than strict
 destination isolation on shared infrastructure. An existing exact OpenAI host
 rule is rejected instead of silently overwritten.
 
+`execution.runtimeAuth: openai-env` is the opt-in alternative. It supplies
+`CODEX_API_KEY` command-scoped to Codex, with `OPENAI_API_KEY` also supplied when
+that was the host source. Child processes can read and use the raw key, and so can
+anything the agent runs or a page it reads asks it to run.
+
 Evidence records the selected auth mode and the residual proxy capability.
 Resolved live actor traces use `keyPlacement: external` in `openai-egress`; the
 actor registry continues to describe the default `in-sandbox-command-scoped`
@@ -197,10 +199,10 @@ deadline.
 
 ## The original command-scoped safety contract
 
-The default mode **inverts** the credential-placement default of every other E2B route.
-On the computer-use route the model's key stays _outside_ the sandbox; here the
-agent-under-test runs _inside_ with a real `OPENAI_API_KEY`/`CODEX_API_KEY` and
-is **presumed exfiltratable**. The placement rule in invariants-and-defaults.md
+The `openai-env` mode **inverts** the credential-placement default of every other E2B route.
+On the computer-use route the model's key stays _outside_ the sandbox; under `openai-env` the
+agent-under-test runs _inside_ with a real `OPENAI_API_KEY`/`CODEX_API_KEY` and is **presumed
+exfiltratable**. The placement rule in invariants-and-defaults.md
 applies: _keys live where the keyed process runs, and nowhere else;
 blast radius is bounded by key scoping and budgets, not by hoping._
 

package/docs/contracts/run-bundle.md

@@ -585,7 +585,9 @@ shareSafety:
 bundle is safe to promote into a public issue. Public promotion should branch on
 `shareSafety.status`:
 
-- `share_ready`: feedback draft commands may render public issue payloads;
+- `share_ready`: feedback draft commands may render public issue payloads, and `observe --all --safe`
+  serves the run. The folder still holds `sandbox-receipts.ndjson` (raw sandbox ids) and `status.json`
+  (the recording pid); no Observer server serves them and bundle export omits them;
 - `local_only`: keep the run local; only supported redaction-only cases can produce a shareable derivative;
   `RAW_SANDBOX_ID` is one: a file other than `sandbox-receipts.ndjson` names one of the run's raw
   sandbox ids, which verify reads from the receipts and from any raw `providerResources[].id` in
@@ -658,6 +660,16 @@ trace references outside `screenshots/`. An unregistered
 `.mp4`, and a file or directory whose name contains `\`, are public-safety
 findings and block the run.
 
+The patterns live in `src/evidence/redaction.ts`: provider key formats (OpenAI,
+Anthropic, E2B, GitHub, GitLab, npm, Vercel, AWS, Google, Stripe, Slack,
+SendGrid, Hugging Face), JWTs, bearer and basic `Authorization` values, private
+key headers, database URLs with a password, the password in any URL's user info,
+credential query and fragment parameters with a value of 16 characters or more,
+credential-named upper-case variables set to a value of 16 characters or more
+with a digit and a letter, an AWS secret access key next to its name, E2B URLs, and Linux,
+macOS and Windows local paths. `tests/verify/secret-formats.test.ts` lists the
+formats and the ordinary values that must not match.
+
 Before matching, the scan undoes JSON and JS escapes, percent-encoding and HTML
 character references, the decoding bundle export applies (`decodeEscapes`), and
 then JSON whitespace escapes and quoted-printable. It reads inside base64 runs of
@@ -673,9 +685,13 @@ wrapped across lines, and inside hex runs of 32 characters or more:
 
 `observer/index.html` is exempt from that base64 rule: serve renders it from
 `run.json`, export regenerates it, and it embeds the Observer's own base64 fonts.
-Its text is still scanned. Known limits: base64 split across separate strings,
-nesting deeper than three levels, and encodings a pattern scan cannot undo (such
-as encryption) still grade `share_ready`. `tests/verify/encoding-coverage.test.ts`
+Its text is still scanned. A base64 run of up to 4096 characters is also read one
+slash-separated piece at a time, and from just after each slash in its first 64
+characters, so a URL path before an encoded key cannot shift its decoding. Known
+limits: base64 split across separate strings, nesting deeper than three levels,
+base64 that holds a slash itself and starts more than 64 characters into a longer
+run, and encodings a pattern scan cannot undo (such as encryption) still grade
+`share_ready`. `tests/verify/encoding-coverage.test.ts`
 records each case.
 
 Real email receiving adds `publication.restrictions: [real-communications]` and