humanish 0.110.4 → 0.111.1

package/dist/study/parse/execution.js

@@ -33,14 +33,6 @@ export function parseExecution(raw) {
     }
     if (desktopResult.value)
         execution.desktop = desktopResult.value;
-    // Reuse the terminal route's caps parser (same shape, not a fork); a malformed budget is a hard
-    // error, never silently dropped (a cap that silently does nothing would be a safety lie).
-    const capsResult = parseCaps(raw.caps);
-    if (!capsResult.ok) {
-        return capsResult;
-    }
-    if (capsResult.value)
-        execution.caps = capsResult.value;
     const terminalResult = parseTerminal(raw.terminal);
     if (!terminalResult.ok) {
         return terminalResult;
@@ -217,40 +209,13 @@ function parseDesktop(raw) {
     }
     return { ok: true, value: Object.keys(desktop).length > 0 ? desktop : undefined };
 }
-export function parsePersonas(raw) {
-    if (!Array.isArray(raw)) {
-        return undefined;
-    }
-    const personas = raw.filter(isRecord);
-    return personas.length > 0 ? personas : undefined;
-}
-export function parseScenario(raw) {
-    if (!isRecord(raw)) {
-        return { ok: true, value: undefined };
-    }
-    const scenario = {};
-    const ref = str(raw.ref);
-    if (ref)
-        scenario.ref = ref;
-    if (isRecord(raw.inline))
-        scenario.inline = raw.inline;
-    const mode = str(raw.mode);
-    if (mode === "dry-run" || mode === "live")
-        scenario.mode = mode;
-    const capsResult = parseCaps(raw.caps);
-    if (!capsResult.ok) {
-        return capsResult;
-    }
-    if (capsResult.value)
-        scenario.caps = capsResult.value;
-    return { ok: true, value: Object.keys(scenario).length > 0 ? scenario : undefined };
-}
 /**
- * Parse `scenario.caps`. Returns a parse failure on a malformed value rather than silently
+ * Parse a `caps` block's values. Returns a parse failure on a malformed value rather than silently
  * dropping a budget declaration (a cap that silently does nothing would claim protection it
- * does not give). Each cap must be a non-negative finite number.
+ * does not give). Each cap must be a non-negative finite number. readStudyFront has checked the
+ * keys against the route; migrate checks a v2 file's two caps blocks with it.
  */
-function parseCaps(raw) {
+export function parseCaps(raw) {
     if (raw === undefined) {
         return { ok: true, value: undefined };
     }

package/dist/study/parse/{study-v3.d.ts → front.d.ts}

@@ -1,12 +1,5 @@
 import type { StudyRoute } from "../routing.js";
-import { type StudyParseFailure } from "../types.js";
-export interface StudyDocument {
-    readonly route: StudyRoute;
-    /** The same document in the humanish.lab.v2 spelling. */
-    readonly v2: Record<string, unknown>;
-    /** For each expanded participant, the index of the `participants` entry it came from. */
-    readonly participantSource: readonly number[];
-}
+import type { StudyParseFailure, StudySurfaces } from "../types.js";
 /** A document's `participants`, read before the participant entries parse. */
 export interface Participants {
     count?: number;
@@ -21,15 +14,16 @@ export interface StudyFront {
     readonly route: StudyRoute;
     readonly actor: Record<string, unknown>;
     readonly participants: Participants;
-    /** The scripted surfaces as a count: 1 is desktop, 2 adds mobile. */
-    readonly surfaces: number | undefined;
+    readonly surfaces: StudySurfaces | undefined;
 }
 type Parsed<T> = {
     ok: true;
     value: T;
 } | StudyParseFailure;
-/** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
-export declare function studyToV2(raw: Record<string, unknown>): Parsed<StudyDocument>;
+/** The refusal for a study with no `actor` object. */
+export declare const ACTOR_REQUIRED = "A study needs `actor:`, an object with at least `type`.";
+/** Why `route` is not a route a study can declare, or undefined when it is one. */
+export declare function routeNameReason(route: unknown): string | undefined;
 /**
  * The checks a v3 document passes before its sections parse: no v2 key and no unknown key, a
  * route, a mode, an `actor` object, a scenario string, and the `participants`, `surfaces` and
@@ -39,9 +33,4 @@ export declare function studyToV2(raw: Record<string, unknown>): Parsed<StudyDoc
  * parser does.
  */
 export declare function readStudyFront(raw: Record<string, unknown>, anySharedWorldParticipants?: boolean): Parsed<StudyFront>;
-/**
- * Spell a v2 parser message the way the study file is written: `actors[0].lanes[3]` becomes the
- * `participants` entry it came from, `execution.caps` and `scenario.caps` become `caps`, and so on.
- */
-export declare function studySpelling(message: string, route: StudyRoute, participantSource: readonly number[]): string;
 export {};

package/dist/study/parse/{study-v3.js → front.js}

@@ -1,10 +1,9 @@
-// humanish.study.v3, the study format. A study declares its route, one `actor`, its `participants`
-// and one `caps` block. studyToV2 rewrites a v3 document into the v2 spelling, so both formats run
-// through one parser and parse into the same StudyConfig. parseStudy then checks the declared
-// route against the one the config takes, and refuses any field that route does not read.
+// What a humanish.study.v3 document declares before its sections parse: its route, one `actor`,
+// its `participants` or `surfaces`, and the `caps` keys the route reads. config.ts parses the
+// sections after these checks pass.
 import { isRecord } from "../../run/type-guards.js";
 import { findUnknownStudyKey } from "../keys.js";
-import { V2_SCHEMA } from "../types.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.
@@ -24,53 +23,13 @@ const CAPS_KEYS = {
     terminal: ["maxUsd", "maxJobs", "maxMinutes"],
     scripted: [],
 };
-/** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
-export function studyToV2(raw) {
-    const front = readStudyFront(raw);
-    if (!front.ok)
-        return front;
-    const { route } = front.value;
-    const { count, instruction, entries, source } = front.value.participants;
-    // The v2 actor keys that hold participants.
-    const v2Participants = [
-        ["count", count ?? front.value.surfaces],
-        ["laneFocus", instruction === undefined ? undefined : { instruction }],
-        ["lanes", entries],
-    ];
-    const actor = { ...front.value.actor };
-    for (const [key, value] of v2Participants)
-        if (value !== undefined)
-            actor[key] = value;
-    const caps = raw.caps;
-    const scenario = {};
-    if (raw.scenario !== undefined)
-        scenario.ref = raw.scenario;
-    if (raw.mode !== undefined)
-        scenario.mode = raw.mode;
-    if (caps !== undefined && route === "terminal")
-        scenario.caps = caps;
-    const execution = caps !== undefined && route !== "terminal"
-        ? withKey(raw.execution, "caps", caps)
-        : raw.execution;
-    const subject = route === "shared-world" ? withKey(raw.subject, "topology", "shared-world") : raw.subject;
-    const v2 = { schema: V2_SCHEMA };
-    const fields = [
-        ["id", raw.id],
-        ["title", raw.title],
-        ["description", raw.description],
-        ["subject", subject],
-        ["actors", [actor]],
-        ["execution", execution],
-        ["scenario", Object.keys(scenario).length > 0 ? scenario : undefined],
-        ["policies", raw.policies],
-        ["review", raw.review],
-        ["defaults", raw.defaults],
-        ["comms", raw.comms],
-    ];
-    for (const [key, value] of fields)
-        if (value !== undefined)
-            v2[key] = value;
-    return { ok: true, value: { route, v2, participantSource: source } };
+/** The refusal for a study with no `actor` object. */
+export const ACTOR_REQUIRED = "A study needs `actor:`, an object with at least `type`.";
+/** Why `route` is not a route a study can declare, or undefined when it is one. */
+export function routeNameReason(route) {
+    return ROUTES.some((name) => name === route)
+        ? undefined
+        : `A study needs \`route:\`, one of ${ROUTES.join(", ")}.`;
 }
 /**
  * The checks a v3 document passes before its sections parse: no v2 key and no unknown key, a
@@ -81,35 +40,33 @@ export function studyToV2(raw) {
  * 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);
     if (unknownKey)
         return invalid(unknownKey);
     const route = ROUTES.find((name) => name === raw.route);
-    if (route === undefined) {
-        return invalid(`A study needs \`route:\`, one of ${ROUTES.join(", ")}.`);
-    }
+    if (route === undefined)
+        return invalid(routeNameReason(raw.route));
     if (raw.mode !== undefined && raw.mode !== "dry-run" && raw.mode !== "live") {
         return invalid("`mode` must be `dry-run` or `live`. Leave it out for a dry run.");
     }
-    if (!isRecord(raw.actor)) {
-        return invalid("A study needs `actor:`, an object with at least `type`.");
-    }
+    if (!isRecord(raw.actor))
+        return invalid(ACTOR_REQUIRED);
     if (raw.scenario !== undefined && typeof raw.scenario !== "string") {
         return invalid("`scenario` is a scenario id or a path to one, as a string.");
     }
     const participants = participantsOf(anySharedWorldParticipants && route === "shared-world" ? "computer-use" : route, raw.participants);
     if (!participants.ok)
         return participants;
-    const surfaces = surfaceCount(route, raw.surfaces);
+    const surfaces = surfacesOf(route, raw.surfaces);
     if (!surfaces.ok)
         return surfaces;
     const capsReason = capsKeysReason(route, raw.caps);
     if (capsReason)
         return invalid(capsReason);
-    // The v2 inert-field table does not list this one, but the terminal planner never reads it.
+    // The inert-field rows (warnings.ts) do not list this one; the terminal planner never reads it.
     if (route === "terminal" && isRecord(raw.execution) && raw.execution.timeoutMs !== undefined) {
         return invalid("route: terminal does not read `execution.timeoutMs`: `caps.maxMinutes` is the command deadline. Remove it.");
     }
@@ -118,44 +75,6 @@ export function readStudyFront(raw, anySharedWorldParticipants = false) {
         value: { route, actor: raw.actor, participants: participants.value, surfaces: surfaces.value },
     };
 }
-/**
- * Spell a v2 parser message the way the study file is written: `actors[0].lanes[3]` becomes the
- * `participants` entry it came from, `execution.caps` and `scenario.caps` become `caps`, and so on.
- */
-export function studySpelling(message, route, participantSource) {
-    return (message
-        .replaceAll(/actors\[0\]\.lanes\[(\d+)\]/g, (_match, index) => `participants[${participantSource[Number(index)] ?? index}]`)
-        // "an `actors[0].lanes` roster" reads "a `participants` list" in a v3 file.
-        .replaceAll(/\ban `actors\[0\]\.(lanes|roster)` roster\b/g, "a `participants` list")
-        .replaceAll(/actors\[0\]\.(lanes|roster)\b/g, "participants")
-        .replaceAll(/actors\[0\]\.laneFocus(\.instruction)?/g, "participants.instruction")
-        .replaceAll(/actors\[0\]\.count\b/g, route === "scripted" ? "surfaces" : "participants")
-        .replaceAll("actors[0]", "actor")
-        .replaceAll(/\b(execution|scenario)\.caps\b/g, "caps")
-        .replaceAll(/\bscenario\.mode\b/g, "mode")
-        .replaceAll(/\bscenario\.ref\b/g, "scenario")
-        .replaceAll("subject.topology: shared-world", "route: shared-world"));
-}
-// 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")
@@ -212,7 +131,7 @@ function homogeneousOf(raw) {
     return { ok: true, value: participants };
 }
 // A list entry with `count: n` is a group: n participants `<id>-01` to `<id>-NN`, even when n is 1.
-// The v2 parser then checks every entry and the expanded ids for collisions.
+// config.ts then checks every entry and the expanded ids for collisions.
 function entriesOf(raw) {
     const entries = [];
     const source = [];
@@ -241,17 +160,17 @@ function entriesOf(raw) {
     }
     return { ok: true, value: { entries, source } };
 }
-// Scripted surfaces become the v2 count: 1 is desktop, 2 adds mobile.
-function surfaceCount(route, raw) {
+function surfacesOf(route, raw) {
     if (raw === undefined)
         return { ok: true, value: undefined };
     if (route !== "scripted") {
         return invalid(`\`surfaces\` belongs to route: scripted. This study's route is ${route}; remove it.`);
     }
-    if (Array.isArray(raw) && raw.length === 1 && raw[0] === "desktop")
-        return { ok: true, value: 1 };
+    if (Array.isArray(raw) && raw.length === 1 && raw[0] === "desktop") {
+        return { ok: true, value: ["desktop"] };
+    }
     if (Array.isArray(raw) && raw.length === 2 && raw[0] === "desktop" && raw[1] === "mobile") {
-        return { ok: true, value: 2 };
+        return { ok: true, value: ["desktop", "mobile"] };
     }
     return invalid("`surfaces` must be [desktop] or [desktop, mobile].");
 }
@@ -268,10 +187,3 @@ function capsKeysReason(route, raw) {
         return undefined;
     return `route: ${route} reads only ${read.map((key) => `caps.${key}`).join(", ")}. Remove ${unread.map((key) => `caps.${key}`).join(", ")}.`;
 }
-// Add one key to a section. A section that is not an object passes through unchanged, so the v2
-// parser refuses it with its own message.
-function withKey(section, key, value) {
-    if (section === undefined)
-        return { [key]: value };
-    return isRecord(section) ? { ...section, [key]: value } : section;
-}

package/dist/study/parse/subject.d.ts

@@ -1,4 +1,6 @@
 import type { StudyParseFailure, StudySubject } from "../types.js";
+/** True when `raw` is a subject mapping whose `source` parseSubject accepts. */
+export declare function hasSubjectSource(raw: unknown): boolean;
 export declare function parseSubject(raw: unknown): {
     ok: true;
     value: StudySubject;

package/dist/study/parse/subject.js

@@ -3,31 +3,28 @@ 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";
+const SOURCES = [
+    "this-repo",
+    "clone",
+    "app-url",
+    "local-app",
+    "desktop-cli",
+    "terminal-product",
+    "local-tree",
+];
+/** True when `raw` is a subject mapping whose `source` parseSubject accepts. */
+export function hasSubjectSource(raw) {
+    return isRecord(raw) && SOURCES.some((name) => name === str(raw.source));
+}
 export function parseSubject(raw) {
     if (!isRecord(raw)) {
         return invalid("`subject` is required and must be an object.");
     }
-    const source = str(raw.source);
-    if (source !== "this-repo" &&
-        source !== "clone" &&
-        source !== "app-url" &&
-        source !== "local-app" &&
-        source !== "desktop-cli" &&
-        source !== "terminal-product" &&
-        source !== "local-tree") {
+    const source = SOURCES.find((name) => name === str(raw.source));
+    if (source === undefined) {
         return invalid("`subject.source` must be one of: this-repo, clone, app-url, local-app, terminal-product, desktop-cli, local-tree.");
     }
     const subject = { source };
-    // topology is enum-validated everywhere; its semantics (shared-world requires clone × e2b-desktop
-    // × a ≥2 roster) are enforced in the shared-world cross-validation below, and a set-but-unconsumed
-    // topology warns as inert off the shared-world route.
-    if (raw.topology !== undefined) {
-        const topology = str(raw.topology);
-        if (topology !== "per-lane-worlds" && topology !== "shared-world") {
-            return invalid("`subject.topology` must be per-lane-worlds (the default) or shared-world.");
-        }
-        subject.topology = topology;
-    }
     // exposure is enum-validated everywhere; it is required on the concurrent shared-world route (the
     // getHost synthetic-subject attestation) and warns inert elsewhere.
     if (raw.exposure !== undefined) {

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,8 +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 { rosterOf } from "./parse/actors.js";
-import { actorsOf } 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`). */
@@ -87,13 +86,12 @@ export async function resolveCommittedPersonas(projectRoot, personaIds) {
  */
 export function studyPersonaIds(config) {
     const ids = [];
-    for (const actor of actorsOf(config)) {
-        if (actor.persona)
-            ids.push(actor.persona);
-        for (const entry of rosterOf(actor) ?? []) {
-            if (entry.persona)
-                ids.push(entry.persona);
-        }
+    const persona = config.actor?.persona;
+    if (persona)
+        ids.push(persona);
+    for (const entry of participantList(config) ?? []) {
+        if (entry.persona)
+            ids.push(entry.persona);
     }
     return [...new Set(ids)];
 }

package/dist/study/plan-base.d.ts

@@ -2,7 +2,7 @@ import type { Brain, ComputerUsePlan, NonEmpty, PlannedAnalysis, ProvisionedSubj
 import type { StudyConfig } from "./types.js";
 export type Base = Omit<ComputerUsePlan, "route" | "actor" | "runner" | "concurrency" | "sessionBudgetMs" | "sandboxMs" | "caps" | "rerun">;
 export declare function isNonEmpty<T>(values: readonly T[]): values is NonEmpty<T>;
-export declare function planCaps(config: StudyConfig, route: "computer-use" | "shared-world"): ComputerUsePlan["caps"];
+export declare function planCaps(config: StudyConfig): ComputerUsePlan["caps"];
 export declare function provisionedSubject(config: StudyConfig): ProvisionedSubject | undefined;
 /** Keys, env and local tools a live run checks right before it acquires anything. */
 export declare function desktopRequirements(config: StudyConfig, args: {