humanish 0.111.0 → 0.111.2

package/dist/run/dry-run.js

@@ -67,6 +67,7 @@ async function runDryRunInScope(options, scope) {
         mintRunId: () => `dryrun-${createdAt.replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`,
         mode: options.dryRun ? "dry-run" : "live",
         study: options.study,
+        warnings: options.warnings,
         renderReview: renderReviewMarkdown,
         // The run starts at the time its id and source were stamped with.
         now: () => Date.parse(createdAt),

package/dist/run/results.d.ts

@@ -5,6 +5,8 @@ export declare const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";
 export interface RunOptions {
     /** Which manifest produced this run. */
     study?: RunStudyProvenance;
+    /** Warnings about the study's own fields, recorded in the bundle as warn events. */
+    warnings?: readonly string[];
     cwd: string;
     dryRun?: boolean;
     runId?: string;

package/dist/run/run.d.ts

@@ -22,6 +22,8 @@ interface StartRunOptions {
     };
     /** Clock for `createdAt` and the latest pointer. */
     now?: (() => number) | undefined;
+    /** Warnings about the study's own fields. Every bundle write records each as a warn event. */
+    warnings?: readonly string[] | undefined;
 }
 /** How a run ended as an execution, as run.json records it: the result's ok and execution outcome. */
 interface RecordedOutcome {

package/dist/run/run.js

@@ -5,7 +5,7 @@
 import { redactText } from "../evidence/redaction.js";
 import { buildObserverData } from "../observer/data.js";
 import { renderObserver } from "../observer/render.js";
-import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD } from "./bundle.js";
+import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, } from "./bundle.js";
 import { judgeExecution, } from "./judge.js";
 import {} from "./results.js";
 import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
@@ -112,8 +112,20 @@ function observerTarget(options) {
         };
 }
 function runPublisher(args) {
-    const { options, runId, paths, runStatus, now, admit, participantsRan } = args;
+    const { options, runId, createdAt, paths, runStatus, now, admit, participantsRan } = args;
     const observer = observerTarget(options);
+    // The study's warnings join whatever events the route wrote, once, in every write.
+    const studyWarnings = (options.warnings ?? []).map((message, index) => ({
+        id: `event-study-warning-${String(index + 1).padStart(3, "0")}`,
+        at: createdAt,
+        level: "warn",
+        type: "study.warning",
+        message,
+    }));
+    const withStudyWarnings = (events) => [
+        ...events.filter((event) => !studyWarnings.some((warning) => warning.id === event.id)),
+        ...studyWarnings,
+    ];
     let pointerWritten = false;
     // The bundle of the last write asked for, and the outcome every later write carries once a
     // signal stopped the run, so no write after the interrupt can drop it.
@@ -145,6 +157,7 @@ function runPublisher(args) {
         const recorded = interrupted ?? outcome;
         const publicBundle = await withPublicSandboxIds(paths, {
             ...evidence,
+            events: withStudyWarnings(evidence.events),
             cwd: PUBLIC_TARGET_CWD,
             ...(recorded === undefined ? {} : { outcome: recorded }),
         });
@@ -271,6 +284,7 @@ export async function runScope(fn) {
         const publisher = runPublisher({
             options,
             runId,
+            createdAt,
             paths,
             runStatus,
             now,

package/dist/run/terminal-contract.d.ts

@@ -22,4 +22,14 @@ type ActorVerdict = "passed" | "blocked" | "failed";
  * divergent verdict logic would let the two routes disagree about what "passed" means.
  */
 export declare function extractLocalActorVerdict(transcript: string, verdictNonce: string): ActorVerdict | null;
+/**
+ * The same search over text that arrives in pieces and is not kept: the terminal route reads
+ * output past its transcript cap through this. Each piece is normalized and loses its whitespace
+ * as the whole transcript does above, and the end of the previous piece is carried so a marker
+ * split between pieces is found. The first marker wins, as above.
+ */
+export declare function createLocalActorVerdictScanner(verdictNonce: string): {
+    push(text: string): void;
+    verdict(): ActorVerdict | null;
+};
 export {};

package/dist/run/terminal-contract.js

@@ -27,6 +27,9 @@ export function normalizeLocalActorTranscript(transcript) {
         .replace(/\r/g, "\n")
         .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
 }
+// The nonce is mandatory: a bare HUMANISH_ACTOR_VERDICT=<status> marker echoed by an actor (or
+// replayed from untrusted text) must never satisfy verdict extraction.
+const verdictPattern = (verdictNonce) => new RegExp(`HUMANISH_ACTOR_VERDICT=(passed|blocked|failed)HUMANISH_ACTOR_NONCE=${escapeRegExp(verdictNonce)}`, "i");
 /**
  * Extract the per-run verdict from a normalized transcript: the agent must print exactly
  * `HUMANISH_ACTOR_VERDICT=<status> HUMANISH_ACTOR_NONCE=<nonce>`, and the nonce is mandatory so a
@@ -35,13 +38,28 @@ export function normalizeLocalActorTranscript(transcript) {
  * divergent verdict logic would let the two routes disagree about what "passed" means.
  */
 export function extractLocalActorVerdict(transcript, verdictNonce) {
-    const compactTranscript = transcript.replace(/\s+/g, "");
-    // The per-run nonce is mandatory: a bare HUMANISH_ACTOR_VERDICT=<status>
-    // marker echoed by an actor (or replayed from untrusted text) must never
-    // satisfy verdict extraction.
-    const match = new RegExp(`HUMANISH_ACTOR_VERDICT=(passed|blocked|failed)HUMANISH_ACTOR_NONCE=${escapeRegExp(verdictNonce)}`, "i").exec(compactTranscript);
-    if (!match) {
-        return null;
-    }
-    return match[1]?.toLowerCase();
+    const match = verdictPattern(verdictNonce).exec(transcript.replace(/\s+/g, ""));
+    return match?.[1]?.toLowerCase() ?? null;
+}
+/**
+ * The same search over text that arrives in pieces and is not kept: the terminal route reads
+ * output past its transcript cap through this. Each piece is normalized and loses its whitespace
+ * as the whole transcript does above, and the end of the previous piece is carried so a marker
+ * split between pieces is found. The first marker wins, as above.
+ */
+export function createLocalActorVerdictScanner(verdictNonce) {
+    const pattern = verdictPattern(verdictNonce);
+    const carried = `HUMANISH_ACTOR_VERDICT=blockedHUMANISH_ACTOR_NONCE=${verdictNonce}`.length - 1;
+    let tail = "";
+    let found = null;
+    return {
+        push(text) {
+            if (found)
+                return;
+            const window = tail + normalizeLocalActorTranscript(text).replace(/\s+/g, "");
+            found = pattern.exec(window)?.[1]?.toLowerCase() ?? null;
+            tail = window.slice(-carried);
+        },
+        verdict: () => found,
+    };
 }

package/dist/study/composition-rules.js

@@ -10,7 +10,7 @@ import { REPO_SLUG_PATTERN } from "./parse/values.js";
 import { declaredTargets } from "./plan-participants.js";
 import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, computerUseParticipantCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
 import { cloneTargetValidationReason, computerUseValidationReason, sharedWorldValidationReason, } from "./validation.js";
-import { actorOf, participantList, declaredParticipantCount, surfaceCount, modeOf, scenarioRefOf, declaresSharedWorld, } from "./study-fields.js";
+import { participantList, declaredParticipantCount } from "./study-fields.js";
 /**
  * The count a scripted or terminal composition reads: its surfaces, or a participant count.
  * parse/front.ts refuses `participants` on route: scripted and route: terminal, and `surfaces` off
@@ -18,7 +18,7 @@ import { actorOf, participantList, declaredParticipantCount, surfaceCount, modeO
  * run before parseStudy compares the two. migrate's view of a v2 file reaches them the same way.
  */
 function participantOrSurfaceCount(config) {
-    return declaredParticipantCount(config) ?? surfaceCount(config);
+    return declaredParticipantCount(config) ?? config.surfaces?.length;
 }
 /** The first composition rule a config breaks, in the parser's order, or null. */
 export function compositionReason(config) {
@@ -34,7 +34,7 @@ export function compositionReason(config) {
         (isComputerUseComposition(config) ? computerUseValidationReason(config) : null) ??
         // Whenever shared world is declared, not only when it routes, so a half-declared shared world
         // fails with a precise reason instead of running as independent participants.
-        (declaresSharedWorld(config) ? sharedWorldValidationReason(config) : null) ??
+        (config.route === "shared-world" ? sharedWorldValidationReason(config) : null) ??
         desktopCliValidationReason(config) ??
         terminalValidationReason(config) ??
         cloneActorValidationReason(config));
@@ -48,7 +48,7 @@ function thisRepoValidationReason(config) {
         if (config.execution?.target) {
             return "`execution.target` applies only to clone/app-url/local-app subjects; this-repo studies run locally.";
         }
-        if (modeOf(config) === "live") {
+        if (config.mode === "live") {
             return THIS_REPO_DRY_RUN_ONLY;
         }
     }
@@ -63,7 +63,7 @@ function thisRepoValidationReason(config) {
 // planComputerUseStudy refuses it with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
-        const type = actorOf(config)?.type ?? "";
+        const type = config.actor?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "local") {
             return "A local-app subject drives a local dev server in this process, with no E2B desktop. Set `execution.target: local` or omit it. To run on a hosted desktop, use an app-url subject with `execution.target: e2b-desktop`.";
         }
@@ -87,14 +87,14 @@ function localAppValidationReason(config) {
 // app; a computer-use actor drives a hosted desktop browser. Fail closed on mis-configs.
 function appUrlValidationReason(config) {
     if (config.subject.source === "app-url") {
-        const type = actorOf(config)?.type ?? "";
+        const type = config.actor?.type ?? "";
         if (actorResolvesToScriptedBrowser(type)) {
             // Scripted-browser route (all fail-closed, so claims match mechanism: a field that cannot act on
             // this route is rejected, never silently ignored).
             if (config.execution?.target !== undefined && config.execution.target !== "local") {
                 return "A scripted-browser actor on an app-url subject runs on this machine. Set `execution.target: local` or omit it. To run scripted steps on a hosted desktop, use a clone subject.";
             }
-            if (!scenarioRefOf(config)) {
+            if (!config.scenario) {
                 return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
             }
             if ((participantOrSurfaceCount(config) ?? 1) > 2) {
@@ -132,8 +132,7 @@ function appUrlValidationReason(config) {
 }
 // Scripted-browser actors on any other subject: only a provisioned clone on e2b-desktop.
 function scriptedBrowserValidationReason(config) {
-    if (config.subject.source !== "app-url" &&
-        actorResolvesToScriptedBrowser(actorOf(config)?.type)) {
+    if (config.subject.source !== "app-url" && actorResolvesToScriptedBrowser(config.actor?.type)) {
         if (config.subject.source !== "clone") {
             return "scripted-browser actors require `subject.source: app-url` (a running app at a loopback URL) or `subject.source: clone` with `execution.target: e2b-desktop` (a provisioned synthetic subject).";
         }
@@ -152,13 +151,13 @@ function scriptedBrowserValidationReason(config) {
         }
         // migrate converts a v2 file's `subject.topology: shared-world` to `route: shared-world`, and
         // refuses it here with the v2 parser's message.
-        if (declaresSharedWorld(config)) {
+        if (config.route === "shared-world") {
             return "A clone scripted-browser study does not support `subject.topology` yet: it runs one synthetic subject for its scripted actor. Remove `subject.topology`.";
         }
         if (config.subject.clone?.fanout !== undefined || config.subject.clone?.keep === true) {
             return "A clone scripted-browser study does not support `subject.clone.fanout` or `subject.clone.keep` yet: its subject is always one sandbox, removed after the run.";
         }
-        if (!scenarioRefOf(config)) {
+        if (!config.scenario) {
             return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
         }
         if ((participantOrSurfaceCount(config) ?? 1) > 2) {
@@ -193,7 +192,7 @@ function scriptedBrowserValidationReason(config) {
 function cloneComputerUseValidationReason(config) {
     if (config.subject.source === "clone" &&
         config.execution?.target === "e2b-desktop" &&
-        actorResolvesToComputerUse(actorOf(config)?.type)) {
+        actorResolvesToComputerUse(config.actor?.type)) {
         if (!config.subject.serve) {
             return "A clone subject on the computer-use route needs `subject.serve` (start and url): humanish starts the app in the sandbox before the participant opens it.";
         }
@@ -220,8 +219,8 @@ function localTreeValidationReason(config) {
         if (config.execution?.target !== "e2b-desktop") {
             return "local-tree subjects require `execution.target: e2b-desktop`: the packed working tree is provisioned and served inside a hosted desktop sandbox; there is no local route for a local-tree subject.";
         }
-        if (!actorResolvesToComputerUse(actorOf(config)?.type)) {
-            return `actor.type must be a registered computer-use actor for local-tree subjects (one of: ${registeredComputerUseActors().join(", ")}); the actor drives the hosted desktop that serves the packed working tree. Got "${actorOf(config)?.type ?? ""}".`;
+        if (!actorResolvesToComputerUse(config.actor?.type)) {
+            return `actor.type must be a registered computer-use actor for local-tree subjects (one of: ${registeredComputerUseActors().join(", ")}); the actor drives the hosted desktop that serves the packed working tree. Got "${config.actor?.type ?? ""}".`;
         }
     }
     return null;
@@ -248,7 +247,7 @@ function desktopCliValidationReason(config) {
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-desktop") {
             return "A desktop-cli subject runs on a hosted desktop. Set `execution.target: e2b-desktop` or omit it.";
         }
-        if (!actorResolvesToComputerUse(actorOf(config)?.type ?? "")) {
+        if (!actorResolvesToComputerUse(config.actor?.type ?? "")) {
             return "desktop-cli subjects need a registered computer-use actor: the participant reads the screen and types, which is what makes an interactive surface studiable at all.";
         }
         const install = config.subject.product.install;
@@ -265,7 +264,7 @@ function desktopCliValidationReason(config) {
 // fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
-        const type = actorOf(config)?.type ?? "";
+        const type = config.actor?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-terminal") {
             return "A terminal-product subject runs its agent in an E2B shell. Set `execution.target: e2b-terminal` or omit it; `local` and `e2b-desktop` are not supported.";
         }
@@ -281,7 +280,7 @@ function terminalValidationReason(config) {
         // mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
         return "`execution.target: e2b-terminal` requires `subject.source: terminal-product` with a registered terminal actor.";
     }
-    else if (actorResolvesToTerminal(actorOf(config)?.type)) {
+    else if (actorResolvesToTerminal(config.actor?.type)) {
         // A registered terminal actor on a non-terminal-product subject: rejected, never ignored (the
         // terminal agent only studies a declared terminal-product from public surfaces).
         return "terminal actors require `subject.source: terminal-product` (a CLI/product the agent studies from public surfaces); other subjects are not supported on this route.";
@@ -293,7 +292,7 @@ function terminalValidationReason(config) {
 // Terminal actors were already refused above with their own message.
 function cloneActorValidationReason(config) {
     if (config.subject.source === "clone") {
-        const type = actorOf(config)?.type ?? "";
+        const type = config.actor?.type ?? "";
         if (!actorResolvesToComputerUse(type) && !actorResolvesToScriptedBrowser(type)) {
             return `clone subjects need a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}) or scripted-browser actor (one of: ${registeredScriptedBrowserActors().join(", ")}); humanish clones and serves the app for that participant to drive. Got "${type}".`;
         }

package/dist/study/doctor.js

@@ -9,7 +9,6 @@ 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";
-import { actorOf } from "./study-fields.js";
 /** A ready row's message, with the schema values the launch recorded. */
 function readyMessage(message, readiness) {
     const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
@@ -152,7 +151,7 @@ export async function studySetupChecks(args) {
         {
             name: "study route",
             ok: true,
-            message: `${config.id}: ${actorOf(config)?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
+            message: `${config.id}: ${config.actor?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
         },
     ];
     if (dryRun)
@@ -247,16 +246,16 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
         ];
     }
     if ((route !== "computer-use" && route !== "shared-world") ||
-        actorOf(config)?.type !== "local-agent")
+        config.actor?.type !== "local-agent")
         return [];
-    const choice = actorOf(config)?.localAgent ?? "codex";
+    const choice = config.actor?.localAgent ?? "codex";
     const agent = args.agents.find((entry) => entry.id === choice);
     if (local)
         return [await localCodexParticipantCheck({ env: args.env, readiness: checkAccount })];
     // A signed-in hosted Codex gets the operator handshake; its sign-in status alone does not show
     // that the operator's config, release and model admit a launch.
     if (choice === "codex" && agent?.authStatus === "authenticated")
-        return [await hostedCodexParticipantCheck(args, actorOf(config))];
+        return [await hostedCodexParticipantCheck(args, config.actor)];
     const outdated = agent === undefined ? undefined : localAgentVersionRefusal(agent);
     return [
         {

package/dist/study/migrate/v2.d.ts

@@ -7,6 +7,11 @@ export declare const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study,
 type Raw = Record<string, unknown>;
 /** Where each humanish 0.110 StudyConfig field a config still sets went; empty when it sets none. */
 export declare function v2FieldMoves(config: unknown): string[];
+/**
+ * The v2 key a hand-converted humanish.study.v3 file is most likely to keep, with where it went;
+ * undefined when the file keeps none. parse/front.ts refuses the file with it.
+ */
+export declare function movedV2KeyReason(raw: Raw): string | undefined;
 type Read<T> = {
     ok: true;
     value: T;

package/dist/study/migrate/v2.js

@@ -57,6 +57,29 @@ export function v2FieldMoves(config) {
         return [];
     return V2_FIELDS.filter((field) => field.present(config)).map((field) => field.move);
 }
+/**
+ * The v2 key a hand-converted humanish.study.v3 file is most likely to keep, with where it went;
+ * undefined when the file keeps none. parse/front.ts refuses the file with it.
+ */
+export function movedV2KeyReason(raw) {
+    if (raw.actors !== undefined) {
+        return "A study has one `actor:` object, and its participants go in `participants:`. `actors:` is the humanish.lab.v2 spelling.";
+    }
+    if (isRecord(raw.actor)) {
+        for (const key of ["count", "lanes", "roster", "laneFocus"]) {
+            if (raw.actor[key] !== undefined) {
+                return `\`actor.${key}\` moved to \`participants:\`: a count, \`{ count, instruction }\`, or a list of participants.`;
+            }
+        }
+    }
+    if (isRecord(raw.subject) && raw.subject.topology !== undefined) {
+        return "`subject.topology` moved to `route:`. A shared world is `route: shared-world`.";
+    }
+    if (isRecord(raw.execution) && raw.execution.caps !== undefined) {
+        return "`execution.caps` moved to a top-level `caps:` block.";
+    }
+    return undefined;
+}
 // The keys of a humanish.lab.v2 file, in the order its parser listed them: the v3 sections with
 // `subject.topology`, the actor list with its participant keys, `execution.caps`, `personas` and
 // the `scenario` object.

package/dist/study/parse/front.js

@@ -3,6 +3,7 @@
 // sections after these checks pass.
 import { isRecord } from "../../run/type-guards.js";
 import { findUnknownStudyKey } from "../keys.js";
+import { movedV2KeyReason } from "../migrate/v2.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./actors.js";
 import { invalid, posInt } from "./values.js";
 // The values `route:` takes: every route routeOf can return.
@@ -39,7 +40,7 @@ export function routeNameReason(route) {
  * parser does.
  */
 export function readStudyFront(raw, anySharedWorldParticipants = false) {
-    const moved = movedKeyReason(raw);
+    const moved = movedV2KeyReason(raw);
     if (moved)
         return invalid(moved);
     const unknownKey = findUnknownStudyKey(raw);
@@ -74,26 +75,6 @@ export function readStudyFront(raw, anySharedWorldParticipants = false) {
         value: { route, actor: raw.actor, participants: participants.value, surfaces: surfaces.value },
     };
 }
-// The v2 keys a hand-converted file is most likely to keep, each with where it went.
-function movedKeyReason(raw) {
-    if (raw.actors !== undefined) {
-        return "A study has one `actor:` object, and its participants go in `participants:`. `actors:` is the humanish.lab.v2 spelling.";
-    }
-    if (isRecord(raw.actor)) {
-        for (const key of ["count", "lanes", "roster", "laneFocus"]) {
-            if (raw.actor[key] !== undefined) {
-                return `\`actor.${key}\` moved to \`participants:\`: a count, \`{ count, instruction }\`, or a list of participants.`;
-            }
-        }
-    }
-    if (isRecord(raw.subject) && raw.subject.topology !== undefined) {
-        return "`subject.topology` moved to `route:`. A shared world is `route: shared-world`.";
-    }
-    if (isRecord(raw.execution) && raw.execution.caps !== undefined) {
-        return "`execution.caps` moved to a top-level `caps:` block.";
-    }
-    return undefined;
-}
 function participantsOf(route, raw) {
     if (raw === undefined) {
         if (route === "shared-world")

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

@@ -1,8 +1,8 @@
 /**
  * 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.
+ * holds a credential verify flags, 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. */

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

@@ -1,14 +1,52 @@
 // 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.
+// such as a filter or a page number, stay as they are. So does an E2B app URL in a parameter, such
+// as a sign-in return address: its host names a sandbox, as the target's own host may, and holds no
+// credential. verify keeps sandbox URLs out of a shared run.
 import { scanEncodedText } from "../../evidence/encoded-text.js";
+import { readPlainText } from "../../evidence/plain-text.js";
+import { containsCredential } from "../../evidence/redaction.js";
 // A relative participant entry is resolved against this before it is read.
 const ENTRY_BASE = "http://127.0.0.1/";
+// A URL in a decoded parameter value, the fragment or a path segment, such as a sign-in return
+// address, is read as the study URL is, this many levels deep. It is parsed, so its user info and
+// its own parameters keep their boundaries; a scan of the decoded text alone would read the next
+// parameter of the outer URL as part of it.
+const MAX_NESTED_DEPTH = 4;
+// A URL inside one decoded value. It runs to the next space, as the value is one parameter's.
+const NESTED_URL = /[a-z][a-z0-9+.-]{0,31}:\/\/\S+/gi;
+// A URL in text decoded from a whole value or from base64, which may join several values or be
+// JSON: it runs to the next space, `&`, or character no URL may hold as written (`"`, `<`, `>`, `\`
+// and a backtick), which ends a JSON string. An apostrophe may be part of user info.
+const URL_IN_TEXT = /[a-z][a-z0-9+.-]{0,31}:\/\/[^\s&"<>\\`]+/gi;
+// A raw `&` that ends a parameter value. One that starts an HTML character reference, such as
+// `&#61;` for `=`, is part of the text around it.
+const VALUE_END = /(?=&(?![a-z]+;|#))/i;
+/** Whether a URL in the text, parsed, has a user name or password. */
+function holdsUserInfo(text) {
+    return [...text.matchAll(URL_IN_TEXT)].some(([candidate]) => {
+        try {
+            const url = new URL(candidate);
+            return url.username !== "" || url.password !== "";
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * A credential verify flags, or a URL with user info, in text as written or in any decoding, and
+ * with tabs and line breaks dropped, as the URL parser drops them from a URL.
+ */
+function holdsCredential(text) {
+    const joined = text.replace(/[\t\n\r]/g, "");
+    return containsCredential(text) || containsCredential(joined) || holdsUserInfo(joined);
+}
 /**
  * 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.
+ * holds a credential verify flags, 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;
@@ -23,7 +61,7 @@ export function urlCredentialReason(field, value, base) {
         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))
+    if (urlPartsHoldCredential(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;
 }
@@ -32,19 +70,123 @@ 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.
+ * Whether the URL's path, query or fragment holds a credential: as the parser normalized it and as
+ * written (`..` segments can drop a segment from the normalized path). Each is matched whole as it
+ * stands, then decoded up to each raw `&`, which ends a parameter value, so a decoded value is not
+ * read into the next parameter; then one segment, value or fragment piece at a time, so the text
+ * around an encoded key cannot shift its decoding. A URL nested in it is read the same way.
  */
-function urlPartsHoldSecret(value, url) {
+function urlPartsHoldCredential(value, url, depth = 0) {
     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(VALUE_END),
+        ...normalized.split(VALUE_END),
         ...written.split(/[/?#&=;]/),
         ...normalized.split(/[/?#&=;]/),
     ];
-    return pieces.some((piece) => piece.length > 0 &&
-        scanEncodedText(piece, { secretsOnly: true, allowOpaqueBase64: true }).sensitive);
+    if (holdsCredential(written) ||
+        holdsCredential(normalized) ||
+        pieces.some((piece) => piece.length > 0 &&
+            scanEncodedText(piece, { matches: holdsCredential, allowOpaqueBase64: true }).sensitive))
+        return true;
+    return (depth < MAX_NESTED_DEPTH &&
+        nestedUrls(url).some((nested) => nested.url.username !== "" ||
+            nested.url.password !== "" ||
+            urlPartsHoldCredential(nested.text, nested.url, depth + 1)));
+}
+function decoded(text) {
+    try {
+        return decodeURIComponent(text);
+    }
+    catch {
+        return text;
+    }
+}
+// A hex, base64 or base64url value long enough to hold a URL, such as an OAuth `state`.
+const HEX_VALUE = /^(?:[0-9a-f]{2}){16}(?:[0-9a-f]{2})*$/i;
+const BASE64_VALUE = /^[A-Za-z0-9+/_-]{16}[A-Za-z0-9+/_-]*={0,2}$/;
+// Hex or base64 inside hex or base64 is read this many levels deep, as verify's scan reads it.
+const MAX_ENCODED_DEPTH = 2;
+/** The text a hex, base64 or base64url value decodes to, when it is text, and what that decodes to. */
+function encodedText(value, depth = 1) {
+    const bytes = [
+        ...(HEX_VALUE.test(value) ? [Buffer.from(value, "hex")] : []),
+        ...(BASE64_VALUE.test(value)
+            ? [Buffer.from(value, /[-_]/.test(value) ? "base64url" : "base64")]
+            : []),
+    ];
+    const texts = bytes.flatMap((decoded) => {
+        const plain = readPlainText(decoded);
+        return plain.ok ? [plain.text] : [];
+    });
+    return depth < MAX_ENCODED_DEPTH
+        ? [...texts, ...texts.flatMap((text) => encodedText(text.trim(), depth + 1))]
+        : texts;
+}
+/**
+ * The absolute URLs in `url`'s decoded parameter names and values, its fragment's and its path
+ * segments, each read as decoded once and twice and from hex or base64, so an encoded URL inside an
+ * encoded value is found. The fragment and the path are also read as written: a URL written there
+ * whole keeps its `://`, which splitting would cut. The fragment is cut at each `&`, so a value is
+ * not read into the next parameter.
+ */
+function nestedUrls(url) {
+    const fragment = url.hash.slice(1);
+    // A fragment may be a route with its own query (`#/callback?next=...`) or a query itself. A
+    // fragment with neither `=` nor `&` reads as one parameter name.
+    const fragmentQuery = new URLSearchParams(fragment.slice(fragment.indexOf("?") + 1));
+    const once = [
+        ...[...url.searchParams, ...fragmentQuery].flat(),
+        ...url.pathname.split("/").map(decoded),
+        ...fragment.split("&"),
+        url.pathname,
+    ];
+    const twice = once.map(decoded);
+    const values = [...new Set([...once, ...twice])];
+    // The URL parser drops tabs and line breaks anywhere in a URL, so they are dropped before a URL is
+    // looked for: `pass<tab>word=` is read as the parser reads it.
+    const parsed = (pattern) => (text) => [...text.replace(/[\t\n\r]/g, "").matchAll(pattern)].flatMap(([candidate]) => {
+        try {
+            return [{ text: candidate, url: new URL(candidate) }];
+        }
+        catch {
+            return [];
+        }
+    });
+    // A JSON value, such as an OAuth `state`, is read string by string, so a URL in one string does
+    // not run into the next. Other text decoded from hex or base64 is one URL when it starts with a
+    // scheme, and may be a query otherwise, so its URLs end at `&`.
+    const read = (pattern) => (text) => jsonStrings(text)?.flatMap(parsed(NESTED_URL)) ?? parsed(pattern(text))(text);
+    const oneUrl = (text) => /^\s*[a-z][a-z0-9+.-]{0,31}:\/\//i.test(text) ? NESTED_URL : URL_IN_TEXT;
+    return [
+        ...values.flatMap(read(() => NESTED_URL)),
+        ...values.flatMap((value) => encodedText(value)).flatMap(read(oneUrl)),
+    ];
+}
+/** The strings in a JSON object or array, keys included, or undefined for text that is not one. */
+function jsonStrings(text) {
+    if (!/^\s*[[{]/.test(text))
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const strings = [];
+    const visit = (node) => {
+        if (typeof node === "string")
+            strings.push(node);
+        else if (Array.isArray(node))
+            node.forEach(visit);
+        else if (node !== null && typeof node === "object")
+            for (const [key, child] of Object.entries(node)) {
+                strings.push(key);
+                visit(child);
+            }
+    };
+    visit(value);
+    return strings;
 }

package/dist/study/persona-resolve.js

@@ -5,7 +5,7 @@ import { parseResolvedPersona, PersonaConfigError } from "./persona.js";
 import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
 import { digestText, redactText } from "../evidence/redaction.js";
 import { realpath } from "node:fs/promises";
-import { actorOf, participantList } from "./study-fields.js";
+import { participantList } from "./study-fields.js";
 /** Persona ids are file-name segments, never paths: the same grammar the terminal route enforces. */
 const PERSONA_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 /** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
@@ -86,7 +86,7 @@ export async function resolveCommittedPersonas(projectRoot, personaIds) {
  */
 export function studyPersonaIds(config) {
     const ids = [];
-    const persona = actorOf(config)?.persona;
+    const persona = config.actor?.persona;
     if (persona)
         ids.push(persona);
     for (const entry of participantList(config) ?? []) {