humanish 0.110.0 → 0.110.2

package/dist/study/doctor.js

@@ -2,11 +2,13 @@ import path from "node:path";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
+import { localAgentReady, localAgentVersionRefusal, } from "../actors/local-agent/cli.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
+import { cli } from "../cli/invocation.js";
 /** A ready row's message, with the schema values the launch recorded. */
 function readyMessage(message, readiness) {
     const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
@@ -211,7 +213,7 @@ async function localBrowserChecks(config, args) {
             ok: healthy,
             message: healthy
                 ? "Recipient inbox routes are ready. Point your app's email sends at this catch; delivery remains untested. No mailbox-provider credentials are needed, and this does not receive arbitrary internet mail."
-                : "Captured inbox is unavailable or outdated. Start or upgrade and restart humanish comms catch, then check comms.email.external.catchBaseUrl (and inboxBaseUrl if set). No participant was allocated.",
+                : `Captured inbox is unavailable or outdated. Start or upgrade and restart ${cli("comms catch")}, then check comms.email.external.catchBaseUrl (and inboxBaseUrl if set). No participant was allocated.`,
         });
     }
     return checks;
@@ -228,7 +230,7 @@ async function realEmailCheck(connection, keys, args) {
             ? "The selected email connection is missing or invalid. Open Connections in the TUI."
             : !args.keyPresent(name)
                 ? `Missing ${name} for the selected email connection. Provide it through process env or --dotenv. Authentication has not been checked.`
-                : "Fresh hosted inbox per participant. Local presence only; run humanish comms check --online to authenticate. Provider permissions/capacity and delivery remain untested.",
+                : `Fresh hosted inbox per participant. Local presence only; run ${cli("comms check --online")} to authenticate. Provider permissions/capacity and delivery remain untested.`,
     };
 }
 /** How the participant authenticates: the terminal model key, or a local agent's login. */
@@ -254,12 +256,14 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
     // that the operator's config, release and model admit a launch.
     if (choice === "codex" && agent?.authStatus === "authenticated")
         return [await hostedCodexParticipantCheck(args, config.actors[0])];
+    const outdated = agent === undefined ? undefined : localAgentVersionRefusal(agent);
     return [
         {
             name: "local participant authentication",
-            ok: agent?.authStatus === "authenticated",
+            ok: agent !== undefined && localAgentReady(agent),
             message: agent?.authStatus === "authenticated"
-                ? `${agent.label} reports authenticated on the host. E2B supplies the desktop; no OpenAI API key is required for this participant.`
+                ? (outdated ??
+                    `${agent.label}${agent.version === undefined ? "" : ` ${agent.version}`} reports authenticated on the host. E2B supplies the desktop; no OpenAI API key is required for this participant.`)
                 : agent
                     ? `${agent.label} ${agent.authStatus === "unauthenticated" ? "reports not signed in" : "authentication could not be checked"}. Run \`${choice === "codex" ? "codex login status" : "claude auth status"}\`; sign in or update the CLI before running.`
                     : `${choice} is not on this process's PATH. Install and sign in to that CLI, or choose openai-computer-use with OPENAI_API_KEY.`,

package/dist/study/init-templates.js

@@ -194,24 +194,6 @@ steps:
     expectation: The user sees a clear next state.
   - name: Capture review notes
     expectation: Notes are public-safe and evidence-backed.
-`,
-    },
-    {
-        path: "humanish/scenarios/onboarding-regression.yaml",
-        plane: "source",
-        contents: `schema: humanish.scenario.v1
-id: onboarding-regression
-title: Onboarding regression
-persona: skeptical-power-user
-goal: Exercise onboarding friction using synthetic inputs and explicit recovery checks.
-mode: dry-run
-steps:
-  - name: Start onboarding
-    expectation: Required information is clear.
-  - name: Use synthetic fixture data
-    expectation: No real user data is entered.
-  - name: Check recovery path
-    expectation: The user can back out or retry safely.
 `,
     },
     {
@@ -308,83 +290,6 @@ execution:
 #   allowPublicTargets: true      # required to drive a non-loopback app-url (a deployment you own)
 defaults:
   open: true
-`,
-    },
-    {
-        path: "humanish/studies/lobby-trivia-3player.yaml",
-        plane: "source",
-        contents: `schema: humanish.study.v3
-id: lobby-trivia-3player
-title: "Shared world on a public app: three mobile participants in one lobby"
-description: >-
-  A worked example of the external-public shared-world route: three participants on mobile layouts
-  play the same multiplayer lobby on a public deployment at the same time. The public site is the
-  shared plane, so there is no clone, subject sandbox or seed. The host participant creates the
-  lobby, humanish reads the session code from the host's page URL, and the other participants get
-  it in their missions and join through the app's own join flow. Starts as a dry run, which writes
-  one evidence bundle at no cost. A live run needs OPENAI_API_KEY, E2B_API_KEY and mode: live. Point appUrl and publicTarget at a public deployment you own or operate. Mobile layout:
-  Chrome's physical window is at least 500px wide and has no touch emulation, desktop pixel ratio
-  and a desktop user agent. Set execution.desktop.fidelity.mobileEmulation to true to request the
-  preset's CSS viewport, touch, pixel ratio and mobile user agent on Chrome or Chromium; the bundle
-  records the measured geometry and emulation fidelity. A run on a public site proves less than a
-  provisioned one: its provenance is external-public, it carries no synthetic-data attestation and
-  no authoritative shared-state proof, and concurrency rests on overlapping sessions and every
-  participant reaching the same lobby.
-route: shared-world
-mode: dry-run # a live run opens three mobile-layout desktops against the public app
-subject:
-  source: app-url # the public deployment is the shared plane: no clone and no getHost
-  appUrl: https://your-public-app.example/ # a deployment you own or operate
-  publicTarget: # required: your attestation that you own or operate this deployment
-    owner: your-org/your-app
-    authorized: true
-policies:
-  allowPublicTargets: true # required: the shared plane is a public, non-loopback deployment
-actor:
-  type: openai-computer-use
-  mission: You are one of several users on the same shared session at once. Play your role, then stop.
-participants: # at least two participants, exactly one with host: true
-  - id: host
-    host: true # this participant creates the shared session
-    device: mobile # 414x896 preset; physical window width floors to 500 (see emulation above)
-    instruction: Create a shared lobby, wait for the others to join, then start and play.
-  - id: player-2
-    device: mobile
-    instruction: Join the lobby you're told the code for, then play.
-  - id: player-3
-    device: small-mobile
-    instruction: Join the lobby you're told the code for, then play.
-execution:
-  target: e2b-desktop
-  # Each participant's session budget, which also bounds the host's handoff deadline. It has to
-  # cover provisioning, joining the shared session and play; 420000 ms (7 minutes) does.
-  timeoutMs: 420000
-  concurrency: 3 # all three participants at once, the default; lower it only to limit paid desktops
-  # desktop:
-  #   fidelity: { mobileEmulation: true } # opt into mobile CSS viewport, touch, DPR and user agent
-defaults:
-  open: true
-`,
-    },
-    {
-        path: "humanish/coverage-map.md",
-        plane: "source",
-        contents: `# Coverage Map
-
-This file should enumerate screens, roles, states, and paths before scenarios are treated as complete.
-
-Current starter coverage is intentionally minimal and synthetic.
-`,
-    },
-    {
-        path: "humanish/coverage-matrix.md",
-        plane: "source",
-        contents: `# Coverage Matrix
-
-| Area | Persona | Happy Path | Sad Path | Status |
-| --- | --- | --- | --- | --- |
-| First run | synthetic-new-user | planned | planned | starter |
-| Onboarding | skeptical-power-user | planned | planned | starter |
 `,
     },
 ];

package/dist/study/init.js

@@ -1,10 +1,14 @@
 import { realpath } from "node:fs/promises";
 import path from "node:path";
-import { AGENTS_SECTION_MARKER, agentsSection, firstRunGuidance, starterActorFor, starterLocalAgentFor, } from "../cli/first-run-path.js";
+import { agentsSection, firstRunGuidance, starterActorFor, starterLocalAgentFor, } from "../cli/first-run-path.js";
 import { detectLocalAgents } from "../actors/local-agent/cli.js";
+import { humanishCommand } from "../cli/invocation.js";
+import { replaceAgentsSection } from "./agents-section.js";
+import { probeLocalBrowserHost } from "./local-browser-host.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { DEFAULT_LOCAL_BROWSER_STARTER, runtimeDirectories, starterFilesFor, } from "./init-templates.js";
 import { assertPreparedSelectedOutputDirectory, prepareContainedOutputDirectory, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../run/contained-output.js";
+import { desktopPeerAdvice, humanishInstall, } from "../substrates/e2b/peer-install.js";
 import { validateCwd } from "../run/project.js";
 import { pathExists, readTextIfExists, validateInitProjectPaths } from "./init-paths.js";
 import { planGitignore, planPackageJson } from "./init-plan.js";
@@ -37,11 +41,11 @@ export async function runInit(options) {
     if (initialPathCheck) {
         return failed(initialPathCheck);
     }
-    await planAgentsFile(preparedProjectRoot, cwd, plan);
     // The starter live study is written for the brain this machine can actually use. Shipping it as
     // openai-computer-use on a machine with no provider key but a signed-in Codex would hand someone
     // a file that asks for a credential they were just told they do not need.
     const machine = await firstRunEnvironment(options.env ?? process.env, requestedCwd);
+    await planAgentsFile(preparedProjectRoot, cwd, plan, humanishCommand());
     const starterActor = starterActorFor(machine);
     await planStarterFiles(preparedProjectRoot, cwd, starterFilesFor(starterActor, localBrowser.value, starterLocalAgentFor(machine)), options.localBrowser !== undefined, plan);
     await planRuntimeDirectories(preparedProjectRoot, cwd, plan);
@@ -87,47 +91,40 @@ export async function runInit(options) {
 // `humanish init` is a coding agent doing setup on someone's behalf. Without this, the agent
 // that arrives tomorrow finds a humanish/ directory and no idea what to do with it.
 //
-// Append-only and idempotent: an existing `AGENTS.md` is a file someone wrote, so humanish adds its
-// own section once and never rewrites theirs.
-async function planAgentsFile(preparedProjectRoot, cwd, plan) {
+// An existing `AGENTS.md` is a file someone wrote. init appends its own section once, and on a
+// rerun replaces only that section, between its two markers, so the commands match the installed
+// humanish. Every byte outside the markers stays as it was.
+async function planAgentsFile(preparedProjectRoot, cwd, plan, humanish) {
     const agentsPath = "AGENTS.md";
     const existingAgents = await readTextIfExists(preparedProjectRoot, agentsPath);
-    const section = agentsSection();
-    if (existingAgents === null) {
-        plan.changes.push({
-            path: agentsPath,
-            action: "create",
-            target: "source",
-            reason: "how a coding agent runs humanish here",
-        });
+    const section = agentsSection(humanish);
+    const write = (contents, action, reason) => {
+        plan.changes.push({ path: agentsPath, action, target: "source", reason });
         plan.writes.push({
             absolutePath: path.join(cwd, agentsPath),
             relativePath: agentsPath,
-            contents: `# AGENTS.md\n${section}`,
+            contents,
             target: "source",
         });
+    };
+    const skip = (reason) => plan.changes.push({ path: agentsPath, action: "skip", target: "source", reason });
+    if (existingAgents === null) {
+        write(`# AGENTS.md\n${section}`, "create", "how a coding agent runs humanish here");
+        return;
     }
-    else if (existingAgents.includes(AGENTS_SECTION_MARKER)) {
-        plan.changes.push({
-            path: agentsPath,
-            action: "skip",
-            target: "source",
-            reason: "humanish section already present",
-        });
+    const replaced = replaceAgentsSection(existingAgents, section);
+    if (replaced.kind === "absent") {
+        write(`${existingAgents.replace(/\s*$/, "")}\n${section}`, "update", "append how a coding agent runs humanish");
+    }
+    else if (replaced.kind === "unknown") {
+        skip("humanish section edited by hand");
+        plan.warnings.push(`Left the humanish section of ${agentsPath} unchanged: it has no end marker and does not match a version init wrote, so it may hold your edits. To get the current section, delete it from the "## humanish" heading to the end of the section and run init again.`);
+    }
+    else if (replaced.contents === existingAgents) {
+        skip("humanish section is current");
     }
     else {
-        plan.changes.push({
-            path: agentsPath,
-            action: "update",
-            target: "source",
-            reason: "append how a coding agent runs humanish",
-        });
-        plan.writes.push({
-            absolutePath: path.join(cwd, agentsPath),
-            relativePath: agentsPath,
-            contents: `${existingAgents.replace(/\s*$/, "")}\n${section}`,
-            target: "source",
-        });
+        write(replaced.contents, "update", "refresh the humanish section");
     }
 }
 /** Create each starter file that is missing; never overwrite one that exists. */
@@ -270,6 +267,18 @@ function validateLocalBrowserStarter(input) {
         return { ok: false, message: "--local-mission must be 4,000 characters or fewer." };
     return { ok: true, value };
 }
+/**
+ * The first-run hint's peer install, ahead of `npx humanish`: beside humanish in its project, else
+ * humanish and the peer together here, where `npx humanish` then finds them. None where `npm i`
+ * would prune a node_modules that no package.json declares.
+ */
+function initDesktopPeerCommand(install) {
+    if (install.kind === "project")
+        return desktopPeerAdvice(install).command;
+    if ((install.kind === "one-shot" || install.kind === "other") && install.unmanagedCwd)
+        return undefined;
+    return "npm i -D humanish @e2b/desktop";
+}
 /**
  * What this machine can run, for the starter study and the next steps. Local CLI status is
  * classified without returning its output or reading its credential file. Provider keys go
@@ -297,18 +306,17 @@ async function firstRunEnvironment(env, cwd) {
     catch {
         hasDesktopSdk = false;
     }
-    const { fileURLToPath } = await import("node:url");
-    const here = fileURLToPath(import.meta.url);
     return {
-        installedInProject: here.startsWith(path.join(process.cwd(), "node_modules") + path.sep),
+        desktopPeerCommand: initDesktopPeerCommand(humanishInstall()),
         hasDesktopSdk,
         hasE2bKey: present("E2B_API_KEY"),
         hasProviderKey: present("OPENAI_API_KEY"),
         localAgents: agents
             .filter((agent) => agent.authStatus === "authenticated")
             .map((agent) => ({ id: agent.id, label: agent.label })),
+        localBrowserHost: await probeLocalBrowserHost(),
         platform: process.platform,
-        arch: process.arch,
+        humanish: humanishCommand(),
     };
 }
 function getMode(options) {

package/dist/study/keys.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Whether a dotted key path, such as `caps.maxUsd` or `participants[0].persona`, names a key a
+ * humanish.study.v3 file can set. A path below a leaf is not one: `scenario.ref`, where `scenario`
+ * is a string, and `review.analysis.question`, whose keys resolveAutomaticAnalysis checks.
+ */
+export declare function isStudyKeyPath(path: string): boolean;
+/**
+ * The dotted path of every key a humanish.study.v3 file can set, down to `depth` levels:
+ * `route`, `caps.maxUsd`, `participants.persona`. scripts/check-doc-study-fields.ts holds the
+ * study file reference to these paths.
+ */
+export declare function studyKeyPaths(depth: number): string[];
 /** The first key in `raw` that V2_KEYS does not list, as an error message; undefined if none. */
 export declare function findUnknownV2Key(raw: unknown): string | undefined;
 /** The first key in a humanish.study.v3 document that the format does not have; undefined if none. */

package/dist/study/keys.js

@@ -230,6 +230,38 @@ const STUDY_KEYS = {
     defaults: V2_KEYS.defaults,
     comms: V2_KEYS.comms,
 };
+/**
+ * Whether a dotted key path, such as `caps.maxUsd` or `participants[0].persona`, names a key a
+ * humanish.study.v3 file can set. A path below a leaf is not one: `scenario.ref`, where `scenario`
+ * is a string, and `review.analysis.question`, whose keys resolveAutomaticAnalysis checks.
+ */
+export function isStudyKeyPath(path) {
+    let shape = STUDY_KEYS;
+    for (const segment of path.replaceAll(/\[\d*\]/g, "").split(".")) {
+        if (shape === true || !Object.hasOwn(shape, segment))
+            return false;
+        shape = shape[segment];
+    }
+    return true;
+}
+/**
+ * The dotted path of every key a humanish.study.v3 file can set, down to `depth` levels:
+ * `route`, `caps.maxUsd`, `participants.persona`. scripts/check-doc-study-fields.ts holds the
+ * study file reference to these paths.
+ */
+export function studyKeyPaths(depth) {
+    const paths = [];
+    const visit = (shape, prefix, level) => {
+        for (const [key, child] of Object.entries(shape)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            paths.push(path);
+            if (child !== true && level < depth)
+                visit(child, path, level + 1);
+        }
+    };
+    visit(STUDY_KEYS, "", 1);
+    return paths;
+}
 /** The first key in `raw` that V2_KEYS does not list, as an error message; undefined if none. */
 export function findUnknownV2Key(raw) {
     return walk(raw, V2_KEYS, "", "study");

package/dist/study/local-browser-host.d.ts

@@ -0,0 +1,11 @@
+import type { LocalBrowserHost } from "../cli/first-run-path.js";
+export interface LocalBrowserHostProbe {
+    platform: NodeJS.Platform;
+    arch: string;
+    env: NodeJS.ProcessEnv;
+    /** Resolves when `file` can be opened with `mode`; rejects otherwise. */
+    access: (file: string, mode: number) => Promise<void>;
+    /** The Mac's chip name, as `sysctl -n machdep.cpu.brand_string` prints it. */
+    macChip: () => Promise<string>;
+}
+export declare function probeLocalBrowserHost(probe?: LocalBrowserHostProbe): Promise<LocalBrowserHost>;

package/dist/study/local-browser-host.js

@@ -0,0 +1,42 @@
+// init's quick read of whether this host can run a local browser study, so its next steps never
+// send someone to a route the host cannot run. It reads devices, `PATH` and the Mac chip name only;
+// it starts no container and no VM. `doctor --study local-browser` runs the full check, including
+// whether Docker is rootful and local.
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+const defaultProbe = () => ({
+    platform: process.platform,
+    arch: process.arch,
+    env: process.env,
+    access,
+    macChip: async () => (await exec("sysctl", ["-n", "machdep.cpu.brand_string"], { timeout: 5_000 })).stdout,
+});
+export async function probeLocalBrowserHost(probe = defaultProbe()) {
+    const can = async (file, mode) => probe.access(file, mode).then(() => true, () => false);
+    if (probe.platform === "linux" && probe.arch === "x64") {
+        // The same device checks doctor makes. The rootful Docker daemon opens these devices, so this
+        // user needs no access to them.
+        if (!(await can("/dev/kvm", constants.F_OK)))
+            return { ok: false, reason: "/dev/kvm is missing" };
+        if (!(await can("/dev/net/tun", constants.F_OK)))
+            return { ok: false, reason: "/dev/net/tun is missing" };
+        const dirs = (probe.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+        for (const dir of dirs)
+            if (await can(path.join(dir, "docker"), constants.X_OK))
+                return { ok: true };
+        return { ok: false, reason: "the docker command is not on the search path" };
+    }
+    if (probe.platform === "darwin" && probe.arch === "arm64") {
+        // The local route needs nested virtualization, which Apple added with the M3.
+        const chip = await probe.macChip().catch(() => "");
+        const generation = /^Apple M(\d+)/.exec(chip.trim());
+        if (generation !== null && Number(generation[1]) >= 3)
+            return { ok: true };
+        return { ok: false, reason: "they need an M3 or newer Mac" };
+    }
+    return { ok: false, reason: "they need Linux x64 or an M3-or-newer Mac" };
+}

package/dist/study/parse/actors.js

@@ -2,6 +2,7 @@ import { DEVICE_PRESET_NAMES, isDevicePresetName } from "../device-presets.js";
 import { isReasoningEffort, reasoningEffortNames } from "../../actors/reasoning-effort.js";
 import { isMaxOutputTokens } from "../../actors/output-token-limit.js";
 import { isHttpUrl } from "./subject.js";
+import { entryCredentialReason, urlCredentialReason } from "./url-credentials.js";
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
 import { invalid, posInt, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
@@ -265,13 +266,20 @@ function parseParticipantEntries(raw, actorIndex) {
             if (!isHttpUrl(target)) {
                 return invalid(`actors[${actorIndex}].lanes[${entryIndex}].target must be an absolute http(s) URL.`);
             }
+            const credential = urlCredentialReason(`actors[${actorIndex}].lanes[${entryIndex}].target`, target);
+            if (credential)
+                return invalid(credential);
             parsedEntry.target = target;
         }
         // `entry` is shape-captured here; the same-origin-with-serve.url check needs serve context, so
         // it runs in sharedWorldValidationReason (where the route + serve.url are known).
         const entryPath = str(entry.entry);
-        if (entryPath !== undefined)
+        if (entryPath !== undefined) {
+            const credential = entryCredentialReason(`actors[${actorIndex}].lanes[${entryIndex}].entry`, entryPath);
+            if (credential)
+                return invalid(credential);
             parsedEntry.entry = entryPath;
+        }
         // `host` marks the designated host on the external-public shared-world route; the
         // exactly-one-host check runs in externalPublicSharedWorldValidationReason (route context).
         if (entry.host !== undefined) {

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.");
@@ -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/persona.d.ts

@@ -26,6 +26,10 @@ export interface PersonaDirectives {
     /** Directives included in the prompt, not proof of behavioral adherence. */
     traitsApplied: string[];
 }
+/** The fields a persona file can set; any other warns and is not sent. The study file reference lists each. */
+export declare const PERSONA_FIELDS: Set<string>;
+/** The traits under `traits:` that become directives; any other warns and is not sent. */
+export declare const TRAIT_FIELDS: Set<string>;
 /** Legacy short fields keep their bounds, but every discarded value is diagnosed. */
 export declare function parseResolvedPersona(raw: unknown, fallback: {
     id: string;

package/dist/study/persona.js

@@ -9,7 +9,8 @@ export class PersonaConfigError extends Error {
     }
 }
 const LEVELS = ["low", "medium", "high"];
-const PERSONA_FIELDS = new Set([
+/** The fields a persona file can set; any other warns and is not sent. The study file reference lists each. */
+export const PERSONA_FIELDS = new Set([
     "schema",
     "id",
     "name",
@@ -18,7 +19,8 @@ const PERSONA_FIELDS = new Set([
     "traits",
     "constraints",
 ]);
-const TRAIT_FIELDS = new Set(["patience", "technical_confidence", "accessibility_needs"]);
+/** The traits under `traits:` that become directives; any other warns and is not sent. */
+export const TRAIT_FIELDS = new Set(["patience", "technical_confidence", "accessibility_needs"]);
 function cleanText(value) {
     return value
         .replace(/\r\n?/g, "\n")

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;