humanish 0.110.1 → 0.110.3

package/dist/evidence/redaction.js

@@ -3,26 +3,124 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { PNG } from "pngjs";
 import { SCREENSHOT_MAX_WIDTH_CAP, pngDecodeRefusal } from "./image.js";
+import { isRecord } from "../run/type-guards.js";
 // Single source of truth for public-safety redaction patterns. Producers and the verify gate
 // both use these, so the denylist cannot drift between them. See docs/contracts/policy.md for
 // the enforcement-scope policy.
+// A whole value that stands in for a secret rather than being one, as written or percent-encoded:
+// a redaction marker, a shell or template variable, a placeholder in angle brackets, or a mask of
+// asterisks. A context pattern skips a value only when one of these is all of it, up to a
+// character that ends that pattern's value, so a password that merely starts with `*` or `$`
+// still counts.
+const PLACEHOLDER = [
+    String.raw `\[REDACTED_[A-Z0-9_]{1,40}\]`,
+    String.raw `%5[Bb]REDACTED_[A-Z0-9_]{1,40}%5[Dd]`,
+    String.raw `\$\{[A-Za-z_][A-Za-z0-9_]{0,63}\}`,
+    String.raw `%24%7[Bb][A-Za-z_][A-Za-z0-9_]{0,63}%7[Dd]`,
+    String.raw `\$[A-Za-z_][A-Za-z0-9_]{0,63}`,
+    String.raw `%24[A-Za-z_][A-Za-z0-9_]{0,63}`,
+    String.raw `\{\{[A-Za-z0-9_. -]{1,64}\}\}`,
+    String.raw `<[A-Za-z0-9_. -]{1,64}>`,
+    String.raw `%3[Cc][A-Za-z0-9_.-]{1,64}%3[Ee]`,
+    String.raw `\*{3,64}`,
+    String.raw `(?:%2[Aa]){3,64}`,
+].join("|");
+const notAPlaceholder = (valueEnd) => String.raw `(?!(?:${PLACEHOLDER})(?:${valueEnd}|$))`;
+// An optional quote around a name or a value, also as JSON writes it inside other JSON strings,
+// four levels deep (\", \\\", ...).
+const QUOTE = String.raw `(?:\\{0,15}["'])?`;
+// A JSON number, which a credential-named key can hold and redaction must not turn into a string.
+// The bounds are far past any number a run writes and keep the lookahead linear.
+const NOT_A_NUMBER = String.raw `(?!-?[0-9]{1,512}(?:\.[0-9]{0,512})?(?:[eE][+-]?[0-9]{1,64})?(?:[\s,}\]]|$))`;
+// The characters that end each context pattern's value.
+const USERINFO_END = String.raw `[\s@/?#"'<>\\]`;
+const PARAMETER_END = String.raw `[\s&#"'<>\\]`;
+const VARIABLE_END = String.raw `[\s"'\\,;&]`;
+// Query and fragment parameters that carry a credential. `page_token` and other cursors match too;
+// their values are long and opaque, so a reader cannot tell them from a credential either.
+const CREDENTIAL_PARAMETER = [
+    String.raw `(?:[a-z0-9]{1,24}[_-]){0,2}token`,
+    String.raw `api[_-]?key`,
+    String.raw `(?:client[_-])?secret`,
+    "password",
+    "passwd",
+    "pwd",
+    "sig",
+    "signature",
+    String.raw `session[_-]?id`,
+    "jwt",
+    "x-vercel-protection-bypass",
+    "_vercel_share",
+    String.raw `x-amz-(?:signature|security-token|credential)`,
+    String.raw `x-goog-(?:signature|credential)`,
+    "auth",
+].join("|");
+// Upper-case variable names that hold a credential, as an env file, a shell or a JSON dump writes
+// them: GITHUB_TOKEN, VERCEL_TOKEN, AWS_SECRET_ACCESS_KEY, DATABASE_PASSWORD.
+const CREDENTIAL_VARIABLE = String.raw `\b(?:[A-Z][A-Z0-9_]{0,48}_)?(?:TOKEN|SECRET|SECRET_KEY|PASSWORD|PASSWD|API_KEY|APIKEY|ACCESS_KEY|PRIVATE_KEY)`;
+// The public E2B pages its errors link to, which name no sandbox and carry no credential: the
+// dashboard as the SDK's missing-key error names it (https://e2b.dev/dashboard?tab=keys), with no
+// path below /dashboard and no query but one short `tab`, and a docs page as the API's 401 names
+// it (https://docs.e2b.dev/api-key), whose path segments hold only letters and hyphens and which
+// has no query. Neither has user info, and only closing punctuation, ")" included, may follow
+// before the next space or the end of the text.
+const E2B_PUBLIC_PAGE = [
+    String.raw `(?:www\.)?e2b\.dev\/dashboard\/?(?:\?tab=[a-z]{1,16})?`,
+    String.raw `(?:docs\.e2b\.dev|(?:www\.)?e2b\.dev\/docs)(?:\/[a-z][a-z-]{0,39}){0,8}\/?`,
+].join("|");
+// A pattern that matches a credential by its context puts the context in a `keep` group, which
+// redaction leaves in place: `?token=[REDACTED_SECRET]`. Context goes in a group and not in a
+// lookbehind, because a pattern that starts with a lookbehind is tried at every position of the
+// text and scans many times slower. An open-ended repeat is written `[...]{n}[...]*`: V8 runs
+// `{n,}` with a backtrack entry per character and overflows its stack on a run of several
+// megabytes, and a star loop does not.
 const SECRET_PATTERNS = [
-    /\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{20,}\b/g,
-    /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
-    /\be2b_[A-Za-z0-9]{16,}\b/g,
-    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b/g,
-    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
-    /\bAKIA[0-9A-Z]{16}\b/g,
-    /\bAIza[0-9A-Za-z_-]{20,}\b/g,
-    /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}\b/g,
-    /\bhf_[A-Za-z0-9]{30,}\b/g,
-    /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/g,
-    /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\b/g,
+    /\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*\b/g,
+    /\bsk-ant-[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*\b/g,
+    /\be2b_[A-Za-z0-9]{16}[A-Za-z0-9]*\b/g,
+    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20}[A-Za-z0-9_]*\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20}[A-Za-z0-9_]*\b/g,
+    /\bglpat-[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*/g,
+    /\bnpm_[A-Za-z0-9]{36}\b/g,
+    // Vercel personal, integration, app access, app refresh and API key tokens.
+    /\bvc[pciark]_[A-Za-z0-9]{24}[A-Za-z0-9]*\b/g,
+    /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    /\bAIza[0-9A-Za-z_-]{20}[0-9A-Za-z_-]*\b/g,
+    /\bya29\.[0-9A-Za-z_-]{20}[0-9A-Za-z_-]*/g,
+    /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16}[A-Za-z0-9]*\b/g,
+    /\bwhsec_[A-Za-z0-9]{24}[A-Za-z0-9]*\b/g,
+    /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/g,
+    /\bhf_[A-Za-z0-9]{30}[A-Za-z0-9]*\b/g,
+    /\bxox[abeoprs]-[A-Za-z0-9-]{20}[A-Za-z0-9-]*\b/g,
+    /\bxapp-[0-9]-[A-Za-z0-9-]{20}[A-Za-z0-9-]*\b/g,
+    /\bhooks\.slack\.com\/(?:services|workflows|triggers)\/[A-Za-z0-9_/-]{20}[A-Za-z0-9_/-]*/g,
+    // A JWT starts only where a token run starts, so a run of `eyJ-` repeated is read once.
+    /eyJ(?<![A-Za-z0-9_-]eyJ)[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*\.[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*\.[A-Za-z0-9_-]{10}[A-Za-z0-9_-]*\b/g,
     /-----BEGIN [A-Z ]*PRIVATE KEY-----/g,
-    /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^:@/\s]+:[^@/\s]+@\S+/g,
-    /_authToken\s*=\s*[A-Za-z0-9._~+/=-]{20,}/g,
-    /\bBearer\s+[A-Za-z0-9._~+/-]{24,}\b/g,
-    /https?:\/\/[^/\s]*e2b[^)\s]+/gi,
+    /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^:@/\s"'<>\\]+:[^@/\s"'<>\\]+@[^\s"'<>\\]+/g,
+    /_authToken\s*=\s*[A-Za-z0-9._~+/=-]{20}[A-Za-z0-9._~+/=-]*/g,
+    /\bBearer\s+[A-Za-z0-9._~+/-]{24}[A-Za-z0-9._~+/-]*\b/g,
+    new RegExp(String.raw `(?<keep>\bAuthorization${QUOTE}[ \t]{0,4}[:=][ \t]{0,4}${QUOTE}Basic[ \t]{1,4})[A-Za-z0-9+/]{16}[A-Za-z0-9+/]*={0,2}`, "gi"),
+    // The password in a URL's userinfo, any scheme, with or without a user name:
+    // https://user:password@host, https://:password@host.
+    new RegExp(String.raw `(?<keep>\b[a-z][a-z0-9+.-]{0,31}:\/\/[^\s:@/?#"'<>\\[\]]{0,256}:)${notAPlaceholder(USERINFO_END)}[^\s@/?#"'<>\\]{1,256}(?=@)`, "gi"),
+    // A credential-named query or fragment parameter's value, up to the next delimiter, so a
+    // password with punctuation in it counts whole. `;` also follows an HTML `&amp;`.
+    new RegExp(String.raw `(?<keep>[?&#;](?:${CREDENTIAL_PARAMETER})=)${notAPlaceholder(PARAMETER_END)}[^\s&#"'<>\\]{16}[^\s&#"'<>\\]*`, "gi"),
+    // An Amazon Web Services secret access key next to its name, as a credentials file, an env
+    // line or a temporary-credentials JSON response writes it. The key is 40 characters, no prefix.
+    new RegExp(String.raw `(?<keep>\b(?:aws_?)?secret_?access_?key${QUOTE}[ \t]{0,4}[:=][ \t]{0,4}${QUOTE})${NOT_A_NUMBER}[A-Za-z0-9/+]{40}(?![A-Za-z0-9/+=])`, "gi"),
+    // A credential-named variable set to a value of 16 characters or more, up to the next space,
+    // quote or separator, with a digit and a letter in its first 256 characters. Words, placeholders
+    // such as humanish-egress-auth-placeholder and JSON numbers do not count. The lookaheads are
+    // bounded, so a long run of `TOKEN=` costs linear time.
+    new RegExp(String.raw `(?<keep>${CREDENTIAL_VARIABLE}${QUOTE}[ \t]{0,4}[:=][ \t]{0,4}${QUOTE})${notAPlaceholder(VARIABLE_END)}${NOT_A_NUMBER}(?=[^\s"'\\,;&]{0,255}[0-9])(?=[^\s"'\\,;&]{0,255}[A-Za-z])[^\s"'\\,;&]{16}[^\s"'\\,;&]*`, "g"),
+    // Any URL on an E2B host: a sandbox host names its sandbox, and a stream URL carries its auth
+    // key. The slashes may be JSON-escaped (`https:\/\/`). User info runs to its last `@`, as a URL
+    // parser reads it, and may hold any character but a slash or space. The host part stops at a
+    // backslash, quote or angle bracket, so a URL followed by an escaped line break and an `E2B_...`
+    // variable in JSON text is not read as an E2B host. A public page followed by `)@` is user info.
+    new RegExp(String.raw `(?!https:\/\/(?:${E2B_PUBLIC_PAGE})[.,;:!?'")]*(?:\s|$))https?:\\?\/\\?\/(?:[^/\s@]*@)*[^/\s\\"'<>@]*e2b[^)\s]+`, "gi"),
     /BEGIN (RSA|OPENSSH|PRIVATE) KEY/gi,
 ];
 const LOCAL_PATH_PATTERNS = [
@@ -32,6 +130,12 @@ const LOCAL_PATH_PATTERNS = [
     [/\/tmp\/[^\s"'`<>)]*/g, "[REDACTED_LOCAL_PATH]"],
     [/\/Users\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, "[REDACTED_LOCAL_PATH]"],
     [/\/home\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, "[REDACTED_RUNTIME_PATH]"],
+    // A Windows profile path, with `\`, `\\` (JSON-escaped) or `/` between segments. A match never
+    // ends in a backslash, so it cannot swallow the escape of a closing quote.
+    [
+        /\b[A-Za-z]:(?:\\\\|\\|\/)Users(?:\\\\|\\|\/)[^\\/\s"'`<>)]+[^\s"'`<>)]*/g,
+        "[REDACTED_LOCAL_PATH]",
+    ],
 ];
 /** Every pattern containsSensitive tests. A test pins each to ASCII, which scanEncodedText relies on. */
 export function sensitivePatterns() {
@@ -43,10 +147,13 @@ function matchesPattern(pattern, text) {
     pattern.lastIndex = 0;
     return pattern.test(text);
 }
+/** True if the text contains a secret-shaped token. Local paths do not count. */
+export function containsSecret(text) {
+    return SECRET_PATTERNS.some((pattern) => matchesPattern(pattern, text));
+}
 /** True if the text contains any secret-shaped token or known local path. */
 export function containsSensitive(text) {
-    return (SECRET_PATTERNS.some((pattern) => matchesPattern(pattern, text)) ||
-        LOCAL_PATH_PATTERNS.some(([pattern]) => matchesPattern(pattern, text)));
+    return (containsSecret(text) || LOCAL_PATH_PATTERNS.some(([pattern]) => matchesPattern(pattern, text)));
 }
 // A local-path match may end in the backslashes escaping its closing quote in
 // serialized JSON (including JSON nested inside a terminal event). Keep that
@@ -142,15 +249,21 @@ export function redactSandboxIds(value) {
         entries.some(([key, child]) => child !== value[key]);
     return changed ? Object.fromEntries(entries) : value;
 }
+/** Each secret replaced by [REDACTED_SECRET], with the context a pattern keeps left in place. */
+function redactSecrets(text) {
+    return SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, (...args) => {
+        const groups = args.at(-1);
+        const keep = isRecord(groups) && typeof groups.keep === "string" ? groups.keep : "";
+        return `${keep}[REDACTED_SECRET]`;
+    }), text);
+}
 /** Redact secrets to [REDACTED_SECRET] and local paths to their path labels. */
 export function redactText(text) {
-    const withoutSecrets = SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, "[REDACTED_SECRET]"), text);
-    return redactLocalPaths(withoutSecrets);
+    return redactLocalPaths(redactSecrets(text));
 }
 /** Redact every sensitive match (secrets and paths) to a single [REDACTED_SECRET] label. */
 export function redactToSecretLabel(text) {
-    const withoutSecrets = SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, "[REDACTED_SECRET]"), text);
-    return redactLocalPaths(withoutSecrets, "[REDACTED_SECRET]");
+    return redactLocalPaths(redactSecrets(text), "[REDACTED_SECRET]");
 }
 function canonicalizePath(value) {
     const resolved = path.resolve(value);

package/dist/feedback/export-bundle.js

@@ -18,6 +18,7 @@ import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import {} from "../run/bundle.js";
 import { runIdOf, isPathInside, prepareRunArtifactPaths, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { isAnalysisRecordPath } from "../analysis/sharing.js";
+import { LOCAL_ONLY_RUN_FILES } from "../run/local-only-files.js";
 import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
 const DERIVATION_SCHEMA = "humanish.redacted-derivation.v1";
 const MAX_FILES = 10_000;
@@ -36,8 +37,7 @@ const OMITTED = new Map([
     ["observer/index.html", "regenerated Observer"],
     ["observer/observer-data.json", "regenerated Observer projection"],
     ["observer/study-analysis.json", "analysis must be regenerated against derivative evidence"],
-    ["status.json", "local process status is not a new attempt"],
-    ["sandbox-receipts.ndjson", "operational journal does not confer a derivative resource lease"],
+    ...LOCAL_ONLY_RUN_FILES,
 ]);
 const PNG_MAGIC = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 function hash(bytes) {

package/dist/keys/key-resolution.js

@@ -21,6 +21,7 @@ import { chmodSync, closeSync, constants as fsConstants, existsSync, ftruncateSy
 import { homedir } from "node:os";
 import path from "node:path";
 import { loadEnvFile } from "./env-file.js";
+import { cli } from "../cli/invocation.js";
 /** The only names implicit discovery may fill (and `humanish keys set` may store). Everything
  *  else in an overlay/store file is ignored-and-named: a repo-planted NODE_OPTIONS/LD_PRELOAD
  *  must never enter process env off a file the operator did not explicitly pass (an explicit
@@ -235,16 +236,16 @@ function storeLabel(env, deps) {
 export function missingKeyHint(name) {
     switch (name) {
         case "E2B_API_KEY":
-            return "run `e2b auth login`, or `humanish keys set e2b`";
+            return `run \`e2b auth login\`, or \`${cli("keys set e2b")}\``;
         case "GH_TOKEN":
         case "GITHUB_TOKEN":
-            return "run `gh auth login`, or `humanish keys set github`";
+            return `run \`gh auth login\`, or \`${cli("keys set github")}\``;
         case "OPENAI_API_KEY":
-            return "run `humanish keys set openai`";
+            return `run \`${cli("keys set openai")}\``;
         case "ANTHROPIC_API_KEY":
-            return "run `humanish keys set anthropic`";
+            return `run \`${cli("keys set anthropic")}\``;
         default:
-            return `run \`humanish keys set ${name}\``;
+            return `run \`${cli(`keys set ${name}`)}\``;
     }
 }
 /** One shared suffix for *_KEYS_MISSING messages: where discovery looked, and what fills each

package/dist/observer/exposure.js

@@ -73,7 +73,7 @@ export function validateExposure(surface, request, live) {
         // admit nothing and expose nothing: watch --expose always requires edge auth, and the live-follow
         // preconditions are checked first so `--dry-run`/`--detach`/`--json` fail with the clearer reason.
         if (live && (live.dryRun || live.detach || live.json)) {
-            return fail("EXPOSE_REQUIRES_LIVE_FOLLOW", "watch --expose streams a live desktop over an attached follow channel; it cannot combine with --dry-run, --detach, or --json.");
+            return fail("EXPOSE_REQUIRES_LIVE_FOLLOW", "watch --expose streams a live desktop over an attached follow channel. It cannot combine with --dry-run, --detach or --json, and without an interactive terminal it needs --serve.");
         }
         // --safe is a share_ready library filter for `serve`; watch streams a single live run that is
         // never share_ready, so --safe would silently do nothing here. Reject it rather than ignore it.

package/dist/observer/library.js

@@ -1,3 +1,4 @@
+import { cli } from "../cli/invocation.js";
 // The pip color for each RunDisplay tone; a run with no display gets the neutral gray.
 const DISPLAY_TONES = {
     pass: "#3fb970",
@@ -8,8 +9,8 @@ const DISPLAY_TONES = {
 };
 export function renderLibraryHtml(history, opts) {
     const emptyState = opts.safe
-        ? "No share_ready runs yet. Run `humanish verify` to see why."
-        : "No runs yet. Run `humanish watch` to create one.";
+        ? `No share_ready runs yet. Run \`${cli("verify")}\` to see why.`
+        : `No runs yet. Run \`${cli("run first-run")}\` to create one.`;
     return `<!doctype html>
 <html lang="en" data-theme="dark">
 <head>

package/dist/observer/render.js

@@ -20,6 +20,7 @@ import { buildServeSecurityHeaders, hostAllowed, parsePublicOrigin } from "./htt
 import { listenOnLoopback } from "./listen.js";
 import { pinDirectChildDirectory, pinDirectory, readContainedFile, } from "./pinned-files.js";
 import { buildHistoryIndex, matchRunRoute, serveRunPath, writeResponse, } from "./run-routes.js";
+import { cli } from "../cli/invocation.js";
 const OBSERVER_SCHEMA = "humanish.observer-result.v1";
 const observerRuntimeStreamUrls = new WeakMap();
 const observerPreparedRunPaths = new WeakMap();
@@ -136,7 +137,7 @@ export async function renderObserver(cwdInput, runInput, options = {}) {
             loaded.bundle.mode === "live"
                 ? "Observer renders verified local evidence artifacts; runtime stream auth URLs are not persisted."
                 : "This is a dry run: its participants are synthetic and no product behavior was tested.",
-            "Before filing public feedback, use `humanish feedback issue` so redaction and public-safety checks gate the payload.",
+            `Before filing public feedback, use \`${cli("feedback issue")}\` so redaction and public-safety checks gate the payload.`,
             ...(openResult.warning ? [openResult.warning] : []),
         ],
     };

package/dist/observer/run-routes.js

@@ -4,6 +4,7 @@
 import path from "node:path";
 import { isAnalysisRecordPath, projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadAnalysis } from "../analysis/load.js";
+import { isLocalOnlyRunFile, isLocalOnlyRunFileIdentity } from "../run/local-only-files.js";
 import { listRuns } from "../run/stored-runs.js";
 import { readAnalysisAccounting } from "../run/costs.js";
 import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
@@ -70,9 +71,11 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
     // file serving bypass its current-content checks or a warmed source-only admission cache.
     const derivedRoot = cleanedRelativePath.split("/")[0];
     const derivedLeaf = path.posix.basename(cleanedRelativePath);
+    // Local-only files (raw sandbox ids, the recording pid) are read in process, never served.
     if (derivedRoot === ".analysis-lock" ||
         derivedLeaf.startsWith(".humanish-write-") ||
-        isAnalysisRecordPath(cleanedRelativePath)) {
+        isAnalysisRecordPath(cleanedRelativePath) ||
+        isLocalOnlyRunFile(cleanedRelativePath)) {
         writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
         return;
     }
@@ -103,6 +106,10 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         await serveContainedMedia(runRoot, filePath, response, request);
         return;
     }
+    if (await isLocalOnlyRunFileIdentity(root, filePath)) {
+        writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
+        return;
+    }
     try {
         const body = await readContainedFile(runRoot, filePath);
         if (!body) {

package/dist/observer/serve.js

@@ -10,6 +10,7 @@ import { buildServeSecurityHeaders, hostAllowed, parsePublicOrigin, } from "./ht
 import { isSafeRunIdSegment } from "../run/paths.js";
 import { listRuns } from "../run/stored-runs.js";
 import { verifyRun } from "../verify/verify.js";
+import { cli } from "../cli/invocation.js";
 export const SERVE_SCHEMA = "humanish.serve-result.v1";
 export function createShareSafetyAdmission(cwd, options = {}) {
     const verifyImpl = options.verifyImpl ?? verifyRun;
@@ -196,7 +197,7 @@ export async function serveObserverLibrary(cwdInput, options) {
             ok: false,
             error: {
                 code: "HUMANISH_RUN_NOT_FOUND",
-                message: "No run library found under .humanish/runs. Run `humanish watch` to create the first run.",
+                message: `No run library found under .humanish/runs. Run \`${cli("run first-run")}\` to create the first run.`,
             },
         };
     }

package/dist/routes/computer-use/participant-runs.d.ts

@@ -3,7 +3,7 @@ import { type StudyConfig } from "../../study/types.js";
 import { type ResolvedPersona } from "../../study/persona.js";
 import { type RunRerunLineage } from "../../run/bundle.js";
 import type { PreparedSelectedOutputDirectory } from "../../run/contained-output.js";
-import { type CuaActorStudyErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun } from "./types.js";
+import { type CuaActorStudyErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun, type ParticipantRunsAndPlan } from "./types.js";
 export declare function defaultSessionTimeoutMs(config: StudyConfig): number;
 /** Per-participant sandbox deadline (each one owns its own desktop). Mirrors the
  *  single-participant formula verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
@@ -21,17 +21,14 @@ export declare function resolveParticipantSandboxMs(config: StudyConfig): number
  */
 export declare function boundedConcurrency(declared: number | undefined, participantCount: number): number;
 /**
- * Pure pre-flight plan resolver (runs in dry-run and live). Returns the participant table, the
- * effective concurrency, the wave count, the per-participant session budget, and the worst-case total
- * sandbox-minutes, before any sandbox or provider call. The same plan appears in dry-run,
- * marked $0 (dryRun: true).
+ * Build the participant runs and the public plan from a computer-use plan (pure). The same plan
+ * appears in dry-run and live, marked $0 for a dry run. `env` may lower the planned concurrency;
+ * `personas` are the compiled committed personas the prompts carry.
  */
-export declare function resolveCuaParticipantPlan(config: StudyConfig, opts?: {
-    countOverride?: number;
+export declare function participantRunsAndPlan(plan: ComputerUsePlan, opts?: {
     env?: Record<string, string | undefined>;
-    dryRun?: boolean;
     personas?: Map<string, ResolvedPersona>;
-}): CuaParticipantPlan;
+}): ParticipantRunsAndPlan;
 /** Print the participant plan to stderr before any sandbox/provider call (public-safe: ids, devices,
  *  digests, and budgets only; no prompt text, no secrets). */
 export declare function emitPreflightPlan(participantPlan: CuaParticipantPlan, studyId: string): void;

package/dist/routes/computer-use/participant-runs.js

@@ -4,7 +4,6 @@
 // compiles the committed personas first and narrows a rerun to its selected participants.
 import { isLocalBrowserStudy, LOCAL_BROWSER_LIFETIME_MS, } from "../../substrates/local/runtime-config.js";
 import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
-import { computerUseParticipants, } from "../../study/plan-participants.js";
 import { resolveParticipant } from "../../run/participant.js";
 import {} from "../../study/types.js";
 import { scrubPersonaBrief } from "../../study/persona.js";
@@ -71,23 +70,17 @@ function envLoweredConcurrency(planned, participantCount, env) {
     }
     return { bound: planned };
 }
-/** The same inputs from a config, for callers that have no plan. */
-function plannedParticipantsOf(config, countOverride) {
-    const participants = computerUseParticipants(config, countOverride);
-    return {
-        participants,
-        concurrency: boundedConcurrency(config.execution?.concurrency, participants.length),
-        sessionBudgetMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config),
-        sandboxMs: resolveParticipantSandboxMs(config),
-        desktopCli: config.subject.source === "desktop-cli",
-    };
-}
-/** Build the participant runs and the public plan from the planned participants (pure). */
-function participantRunsAndPlan(planned, opts = {}) {
+/**
+ * Build the participant runs and the public plan from a computer-use plan (pure). The same plan
+ * appears in dry-run and live, marked $0 for a dry run. `env` may lower the planned concurrency;
+ * `personas` are the compiled committed personas the prompts carry.
+ */
+export function participantRunsAndPlan(plan, opts = {}) {
     const env = opts.env ?? {};
     // Who each participant is (id, persona, focus, device, limits) comes from the plan; this adds
     // what the route derives from it: the prompt, bundle ids and artifact paths.
-    const { participants } = planned;
+    const { participants } = plan.runner;
+    const desktopCli = plan.runner.subject.kind === "desktop-cli";
     const participantCount = participants.length;
     const runs = participants.map((participant) => {
         const mission = participant.assignment.mission ?? DEFAULT_MISSION;
@@ -102,7 +95,7 @@ function participantRunsAndPlan(planned, opts = {}) {
             ...(resolvedPersona === undefined ? {} : { resolvedPersona }),
             ...(focus === undefined ? {} : { instruction: focus }),
             device: { name: device.name, preset: device.preset },
-            ...(planned.desktopCli ? { surface: "desktop-cli" } : {}),
+            ...(desktopCli ? { surface: "desktop-cli" } : {}),
         });
         const run = resolveParticipant(participant, {
             persona: composed.persona,
@@ -119,9 +112,9 @@ function participantRunsAndPlan(planned, opts = {}) {
             traceArtifactPath: participantCount === 1 ? "actor.json" : `actors/${run.streamId}.json`,
         };
     });
-    const resolved = envLoweredConcurrency(planned.concurrency, participantCount, env);
+    const resolved = envLoweredConcurrency(plan.concurrency, participantCount, env);
     const concurrency = resolved.bound;
-    const { sessionBudgetMs, sandboxMs } = planned;
+    const { sessionBudgetMs, sandboxMs } = plan;
     const participantPlan = {
         strategy: CUA_FANOUT_STRATEGY,
         laneCount: participantCount,
@@ -132,7 +125,7 @@ function participantRunsAndPlan(planned, opts = {}) {
         waves: Math.ceil(participantCount / concurrency),
         perLaneSessionBudgetMs: sessionBudgetMs,
         worstCaseSandboxMinutes: Math.round((participantCount * sandboxMs) / 60_000),
-        dryRun: opts.dryRun === true,
+        dryRun: plan.dryRun,
         lanes: runs.map((spec) => ({
             id: spec.planned.id,
             ...(spec.planned.labels.actorType === undefined
@@ -162,16 +155,6 @@ function participantRunsAndPlan(planned, opts = {}) {
     };
     return { runs, participantPlan };
 }
-/**
- * Pure pre-flight plan resolver (runs in dry-run and live). Returns the participant table, the
- * effective concurrency, the wave count, the per-participant session budget, and the worst-case total
- * sandbox-minutes, before any sandbox or provider call. The same plan appears in dry-run,
- * marked $0 (dryRun: true).
- */
-export function resolveCuaParticipantPlan(config, opts = {}) {
-    const { countOverride, ...rest } = opts;
-    return participantRunsAndPlan(plannedParticipantsOf(config, countOverride), rest).participantPlan;
-}
 /** Print the participant plan to stderr before any sandbox/provider call (public-safe: ids, devices,
  *  digests, and budgets only; no prompt text, no secrets). */
 export function emitPreflightPlan(participantPlan, studyId) {
@@ -216,13 +199,10 @@ export async function loadCuaParticipants(args) {
     // Compile any committed personas before planning, so the plan builder stays pure and each participant's
     // prompt carries real behavioral directives rather than a bare `Persona: <id>.` label.
     const personas = await compileParticipantPersonas(args.projectRoot, participants.map((participant) => participant.personaId));
-    const { runs: participantRuns, participantPlan } = participantRunsAndPlan({
-        participants,
-        concurrency: plan.concurrency,
-        sessionBudgetMs: plan.sessionBudgetMs,
-        sandboxMs: plan.sandboxMs,
-        desktopCli: plan.runner.subject.kind === "desktop-cli",
-    }, { env: args.env, dryRun: plan.dryRun, personas });
+    const { runs: participantRuns, participantPlan } = participantRunsAndPlan(plan, {
+        env: args.env,
+        personas,
+    });
     const rerun = plan.rerun;
     if (!rerun)
         return { ok: true, participantRuns, participantPlan };

package/dist/routes/computer-use/plan.d.ts

@@ -1,7 +1,7 @@
 import { type CuaActorDescriptor } from "../../actors/registry.js";
 import type { ComputerUsePlan, ComputerUseRunner, RoutePlanResult, RouteRefusal } from "../../study/plan-types.js";
 import type { StudyConfig, StudySubjectState } from "../../study/types.js";
-import { type CuaActorStudyErrorCode, type RunCuaActorStudyOptions } from "./types.js";
+import { type ComputerUseRunInput, type CuaActorStudyErrorCode } from "./types.js";
 /** The error a computer-use study returns before a run starts. */
 export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActorStudyErrorCode> {
     /**
@@ -44,5 +44,5 @@ export declare function planComputerUseStudy(config: StudyConfig, input: {
     /** Which of the caller's driving homes are set; neither when absent. */
     readonly driving?: CallerDriving;
     readonly countOverride?: number;
-    readonly rerun?: RunCuaActorStudyOptions["rerun"];
+    readonly rerun?: ComputerUseRunInput["rerun"];
 }): ComputerUsePlanResult;

package/dist/routes/computer-use/plan.js

@@ -5,6 +5,7 @@
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
 import { isHttpUrl, isLoopbackUrl } from "../../study/parse/subject.js";
+import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { subjectStateInvalidReason } from "../../study/parse/subject-state.js";
 import { brainOf, callerBrainOf, capsOf, desktopRequirements, planBase, provisionedSubject, } from "../../study/plan-base.js";
 import { computerUseParticipants, declaredTargets } from "../../study/plan-participants.js";
@@ -134,6 +135,10 @@ function subjectStructureReason(config, subjectRoute) {
  */
 function entryTargetReason(config, subjectRoute) {
     const { desktopCliRoute, provisionedRoute, localAppSubject, appUrl } = subjectRoute;
+    // A library caller's config skips the parser, which refuses these first.
+    const credential = studyUrlCredentialReason(config);
+    if (credential)
+        return { code: "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE", message: credential };
     if (desktopCliRoute)
         return undefined;
     const allowPublicTargets = config.policies?.allowPublicTargets === true;
@@ -227,7 +232,7 @@ export function planComputerUseStudy(config, input) {
     // participants. It comes after the rules above, so a shared-world config that breaks one of them,
     // which runStudyWith sends here, still gets that rule's message.
     if (config.subject.topology === "shared-world")
-        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", "route: shared-world studies run every participant against one shared app on the shared-world route; this route runs independent participants. Run the study with runStudy or runConcurrentSharedWorld.", actor);
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", "route: shared-world studies run every participant against one shared app on the shared-world route; this route runs independent participants. The shared-world route takes subject.source clone or local-tree, or app-url with policies.allowPublicTargets: true, on execution.target e2b-desktop.", actor);
     // The in-process route drives subject.appUrl on this machine and creates no desktop, so it would
     // skip the subject a clone, local-tree or desktop-cli study declares.
     const source = config.subject.source;

package/dist/routes/computer-use/route.d.ts

@@ -1,33 +1,20 @@
+import { type RefusedStudy } from "../../run/route-shell.js";
 import type { ComputerUsePlan } from "../../study/plan-types.js";
 import type { AdmittedPlan } from "../../run-study.js";
 import type { StudyConfig } from "../../study/types.js";
 import { type ComputerUseRefusal } from "./plan.js";
-import { type ComputerUseRunInput, type CuaActorStudyResult, type RunCuaActorStudyOptions } from "./types.js";
-/**
- * Plans and runs a computer-use study in one call. It is not exported from src/index.ts; tests call
- * it. It plans the config with planComputerUseStudy and runs
- * the plan with runComputerUsePlan, whose run scope and withTransientCommsSecrets wrapper cover the
- * run and its analysis.
- */
-export declare function runCuaActorStudy(options: RunCuaActorStudyOptions): Promise<CuaActorStudyResult>;
+import { type ComputerUseRunInput, type CuaActorStudyResult } from "./types.js";
 /**
  * A refused computer-use study's result, at the refusal's stage: a before-scope refusal has its own
  * envelope and no analysis record; the others come after the cwd checks, and the participant cap after
  * the personas are read.
  */
-export declare function computerUseStudyRefusal(options: RunCuaActorStudyOptions, refusal: ComputerUseRefusal): Promise<CuaActorStudyResult>;
+export declare function computerUseStudyRefusal(options: ComputerUseRunInput & RefusedStudy, refusal: ComputerUseRefusal): Promise<CuaActorStudyResult>;
 /**
  * runStudyWith's step for a computer-use plan. It runs the plan's local checks (admitCuaRun: the
  * participants, the preflight plan, the keys, the local agent, subject env and caps, and the
  * local-tree archive) before any run scope opens, so the CLI can present their refusal before it
- * loads a declared scorer, and returns the run that continues from them with that scorer.
+ * loads a declared scorer, and returns the run that continues from them with that scorer. The
+ * run and its analysis share one scope for the email secrets it registers.
  */
 export declare function admitComputerUsePlan(plan: ComputerUsePlan, input: ComputerUseRunInput, config: StudyConfig): Promise<AdmittedPlan<"computer-use">>;
-/**
- * Run a computer-use plan: its local checks, then the run. The run scope in runAdmittedCuaRun
- * finalizes any status record the run opened, on every exit, so a test or library caller does not
- * leave the 5 s status cadence writing into a directory something else is deleting (an unrelated
- * ENOTEMPTY). Participants, the brain, the subject, the caps and the residual config come from the
- * plan. `config` is what the caller's createProvider and inProcess executor receive.
- */
-export declare function runComputerUsePlan(plan: ComputerUsePlan, input: ComputerUseRunInput, config: StudyConfig): Promise<CuaActorStudyResult>;