humanish 0.115.0 → 0.117.0

package/dist/run/sandbox-ids.d.ts

@@ -24,7 +24,10 @@ export declare function inventorySandboxIds(files: readonly {
 export declare function holdsKeyedSandboxId(file: string, text: string): boolean;
 /**
  * The raw sandbox ids a run's receipts journal, with any this process receipted whose append
- * failed; empty when there are none or the journal cannot be read.
+ * failed; none from the journal when it is missing or malformed, or when a folder is where it goes
+ * (a failed append can leave one, and the process still holds those ids). A journal refused for
+ * any other reason, a link or one too large to read say, throws ContainedReadRefusedError: every
+ * caller would otherwise write or grade a run's files without the ids it may hold.
  */
 export declare function readRunSandboxIds(root: PreparedOutputRoot): Promise<string[]>;
 /**
@@ -41,7 +44,9 @@ export declare function scrubSandboxIdBytes(file: string, bytes: Buffer, ids: re
  * Rewrite each file of a finished run that names one of its raw sandbox ids, apart from the
  * receipts, with the label in place of the id. Writers such as a participant's actor.json can
  * quote an SDK error that names the sandbox. Run.finish calls it before analysis reads the run.
- * Best effort: verify grades a file this misses.
+ * Best effort for writes and listings: verify grades a file this misses. A text file it refuses
+ * to read, or a journal it refuses, throws once the sweep ends, naming each, since such a file
+ * may still hold an id.
  */
 export declare function scrubRunSandboxIds(paths: PreparedRunArtifactPaths): Promise<void>;
 /**

package/dist/run/sandbox-ids.js

@@ -6,7 +6,7 @@ import { opendir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { readPlainText } from "../evidence/plain-text.js";
 import { collectSandboxIds, redactSandboxIds, sandboxIdDigest, REDACTED_SANDBOX_ID, } from "../evidence/redaction.js";
-import { readContainedRegularFile, writeContainedOutputFile, } from "./contained-output.js";
+import { ContainedReadRefusedError, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "./contained-output.js";
 import { bindExistingRunArtifactPaths, isSafeRunIdSegment, validatePreparedRunRootIdentity, } from "./paths.js";
 import { appendedSandboxIds, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "./sandbox-receipts.js";
 /** How text names a sandbox: the marker with the id's digest. */
@@ -96,14 +96,19 @@ export function holdsKeyedSandboxId(file, text) {
 }
 /**
  * The raw sandbox ids a run's receipts journal, with any this process receipted whose append
- * failed; empty when there are none or the journal cannot be read.
+ * failed; none from the journal when it is missing or malformed, or when a folder is where it goes
+ * (a failed append can leave one, and the process still holds those ids). A journal refused for
+ * any other reason, a link or one too large to read say, throws ContainedReadRefusedError: every
+ * caller would otherwise write or grade a run's files without the ids it may hold.
  */
 export async function readRunSandboxIds(root) {
+    const read = await readContainedRegularFile(root, SANDBOX_RECEIPTS_ARTIFACT, RUN_ARTIFACT_MAX_BYTES);
+    if (read.status === "refused" && read.reason !== "directory")
+        throw new ContainedReadRefusedError(SANDBOX_RECEIPTS_ARTIFACT, read);
     let journaled = [];
     try {
-        const bytes = await readContainedRegularFile(root, SANDBOX_RECEIPTS_ARTIFACT);
-        if (bytes)
-            journaled = receiptSandboxIds(bytes);
+        if (read.status === "read")
+            journaled = receiptSandboxIds(read.bytes);
     }
     catch {
         // The ids this process receipted still apply.
@@ -138,7 +143,9 @@ const MAX_SWEPT_ENTRIES = 10_000;
  * Rewrite each file of a finished run that names one of its raw sandbox ids, apart from the
  * receipts, with the label in place of the id. Writers such as a participant's actor.json can
  * quote an SDK error that names the sandbox. Run.finish calls it before analysis reads the run.
- * Best effort: verify grades a file this misses.
+ * Best effort for writes and listings: verify grades a file this misses. A text file it refuses
+ * to read, or a journal it refuses, throws once the sweep ends, naming each, since such a file
+ * may still hold an id.
  */
 export async function scrubRunSandboxIds(paths) {
     const ids = await readRunSandboxIds(paths);
@@ -147,12 +154,15 @@ export async function scrubRunSandboxIds(paths) {
     const valid = await validatePreparedRunRootIdentity(paths).then(() => true, () => false);
     if (!valid)
         return;
+    const refused = [];
     const scrub = async (file) => {
-        const bytes = await readContainedRegularFile(paths, file);
-        if (bytes === null)
+        const read = await readContainedRegularFile(paths, file, RUN_ARTIFACT_MAX_BYTES);
+        if (read.status === "refused")
+            refused.push(refusalText(file, read));
+        if (read.status !== "read")
             return;
-        const scrubbed = scrubSandboxIdBytes(file, bytes, ids);
-        if (scrubbed !== bytes)
+        const scrubbed = scrubSandboxIdBytes(file, read.bytes, ids);
+        if (scrubbed !== read.bytes)
             await writeContainedOutputFile(paths, file, scrubbed);
     };
     let seen = 0;
@@ -179,6 +189,8 @@ export async function scrubRunSandboxIds(paths) {
     await walk("").catch(() => {
         // A directory that changed while it was listed ends the sweep; verify names what it missed.
     });
+    if (refused.length > 0)
+        throw new Error(`The sandbox id sweep could not read every run file, so these may still name a sandbox: ${refused.join("; ")}.`);
 }
 /**
  * A run's result as it may be returned or printed: the same object when it names no sandbox,
@@ -187,12 +199,16 @@ export async function scrubRunSandboxIds(paths) {
 export async function publicRunResult(result, cwd) {
     let ids = [];
     if (typeof result.runId === "string" && isSafeRunIdSegment(result.runId)) {
+        let paths;
         try {
-            ids = await readRunSandboxIds(await bindExistingRunArtifactPaths(cwd, result.runId));
+            paths = await bindExistingRunArtifactPaths(cwd, result.runId);
         }
         catch {
             // A run that never created its directory has no receipts; the keys are still redacted.
         }
+        // A journal that is there and refused throws: the result cannot be printed without its ids.
+        if (paths !== undefined)
+            ids = await readRunSandboxIds(paths);
     }
     return publicSandboxView(result, ids);
 }

package/dist/run/secrets.d.ts

@@ -11,7 +11,8 @@ export declare class RunSecrets {
      * Replaces every held value with the marker, as written, in each encoded form, and where a URL
      * carries it partly percent-encoded or a terminal escape sequence splits it. It reads the values
      * on each call, so a value added after the scrub was handed to a participant or a subject is
-     * scrubbed from then on.
+     * scrubbed from then on. If the result still holds a value in any readingsOf, as when a marker
+     * written before `x` spells the value `SECRET]x`, the whole text becomes the marker.
      */
     readonly scrub: (text: string) => string;
     /** `seed` keeps its order; values shorter than the floor are dropped. */

package/dist/run/secrets.js

@@ -4,7 +4,8 @@
 // replaced as written and in the encoded forms a URL, a JSON body or a log line gives it;
 // redactText runs after the scrub and finds secrets by shape.
 import { scrubLiterals } from "../evidence/redaction.js";
-import { encodedForms } from "../evidence/secret-scrub.js";
+import { encodedForms, holdsSecretValue } from "../evidence/secret-scrub.js";
+import { escapeSequences } from "./escape-sequences.js";
 export class RunSecrets {
     // Private fields stay out of JSON.stringify and object spread, so a Run that reaches a writer
     // whole cannot carry the values with it.
@@ -12,11 +13,14 @@ export class RunSecrets {
     /** Every held value as written and encoded, longest first. */
     #forms = [];
     #minLength;
+    /** holdsSecretValue of the held values, built at its first use after `add` holds a new one. */
+    #holds;
     /**
      * Replaces every held value with the marker, as written, in each encoded form, and where a URL
      * carries it partly percent-encoded or a terminal escape sequence splits it. It reads the values
      * on each call, so a value added after the scrub was handed to a participant or a subject is
-     * scrubbed from then on.
+     * scrubbed from then on. If the result still holds a value in any readingsOf, as when a marker
+     * written before `x` spells the value `SECRET]x`, the whole text becomes the marker.
      */
     scrub;
     /** `seed` keeps its order; values shorter than the floor are dropped. */
@@ -30,7 +34,9 @@ export class RunSecrets {
         const literal = scrubLiterals(this.#forms, marker);
         this.scrub = (text) => {
             const scrubbed = literal(text);
-            return replaceSpans(scrubbed, viewSpans(scrubbed, this.#forms), marker);
+            const result = replaceSpans(scrubbed, viewSpans(scrubbed, this.#forms), marker);
+            this.#holds ??= holdsSecretValue(this.#held);
+            return this.#holds(result) ? marker : result;
         };
     }
     /** Holds each value the run learns while it runs, unless it is under the floor or already held. */
@@ -39,6 +45,7 @@ export class RunSecrets {
             if (value.length < this.#minLength || this.#held.includes(value))
                 continue;
             this.#held.push(value);
+            this.#holds = undefined;
             for (const form of encodedForms(value))
                 if (!this.#forms.includes(form))
                     this.#forms.push(form);
@@ -69,20 +76,9 @@ export class RunSecrets {
         return mergeSpans(found);
     }
 }
-// What a terminal draws with (operating-system commands, control sequences and two-byte escapes,
-// as written or JSON-escaped, as a JSON event carries a command's colored output) and what a URL
-// encodes with (runs of percent escapes). The view a value is looked for in drops the first and
-// decodes the second.
-const VIEW_SEQUENCE = new RegExp([
-    "\\x1b\\][^\\x07]*(?:\\x07|\\x1b\\\\)",
-    "\\x1b\\[[0-?]*[ -/]*[@-~]",
-    "\\x1b[78=>]",
-    "\\\\u001b\\][^\\\\]*(?:\\\\u0007|\\\\u001b\\\\\\\\)",
-    "\\\\u001b\\[[0-?]*[ -/]*[@-~]",
-    "(?:%[0-9A-Fa-f]{2})+",
-].join("|"), "g");
 /**
- * Where a value is found in the text's view. A browser encodes a space or a quote in a URL path
+ * Where a value is found in the text's view, which drops terminal escape sequences and decodes
+ * percent escapes (escapeSequences). A browser encodes a space or a quote in a URL path
  * and leaves a `/` or a `:` as written, so a value with both matches no single encoded form, and a
  * color code inside a value splits it. Each found value maps back to the span of `text` it came
  * from, so the text keeps every other character as written.
@@ -104,21 +100,21 @@ function viewSpans(text, values) {
     };
     let cursor = 0;
     let changed = false;
-    for (const sequence of text.matchAll(VIEW_SEQUENCE)) {
+    for (const [start, end] of escapeSequences(text)) {
         let plain = "";
-        if (sequence[0].startsWith("%")) {
+        if (text[start] === "%") {
             try {
-                plain = decodeURIComponent(sequence[0]);
+                plain = decodeURIComponent(text.slice(start, end));
             }
             catch {
                 // Not UTF-8: the run stays as written and is copied with the text after it.
                 continue;
             }
         }
-        copy(cursor, sequence.index);
-        cursor = sequence.index + sequence[0].length;
+        copy(cursor, start);
+        cursor = end;
         for (let unit = 0; unit < plain.length; unit += 1) {
-            starts.push(sequence.index);
+            starts.push(start);
             ends.push(cursor);
         }
         view += plain;

package/dist/run/stored-runs.js

@@ -2,12 +2,12 @@ import { lstat, readdir } from "node:fs/promises";
 import path from "node:path";
 import { redactText } from "../evidence/redaction.js";
 import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, } from "./contained-output.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, refusalText, } from "./contained-output.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isReviewSummary, isRunOutcome } from "./bundle-shape.js";
 import { bundleDisplayFacts, displayedReview, runDisplay, } from "./display.js";
 import { RUN_STATUS_FILE } from "./status.js";
-import { readLatest, readRunJsonIfExists, resolveRunPath } from "./locate.js";
+import { readLatest, readRunJsonIfExists, resolveRunPath, runJsonValue } from "./locate.js";
 import { withCuaReviewProvenance } from "./outcomes.js";
 import { isNodeError, isRecord } from "./type-guards.js";
 import { invalidRunStorageVerifyResult, verifyResolvedRun, } from "../verify/verify.js";
@@ -70,7 +70,8 @@ export async function listRuns(cwdInput) {
         if (runsRoot && entryRunPaths.physicalRunsRoot !== runsRoot.physicalPath) {
             return runsUnavailableResult(cwd, new Error("humanish runs root changed physical destination."));
         }
-        const bundle = await readRunJsonIfExists(entryRunPaths, RUN_BUNDLE_FILE);
+        // A listing shows what it can read: a run.json it refuses lists like a missing one.
+        const bundle = runJsonValue(await readRunJsonIfExists(entryRunPaths, RUN_BUNDLE_FILE));
         runs.push({
             runId: entryName,
             createdAt: isRecord(bundle) && typeof bundle.createdAt === "string" ? bundle.createdAt : null,
@@ -105,7 +106,7 @@ async function listedRunDisplay(runPaths, bundle) {
     if (displayed === undefined)
         return {};
     const status = displayed.outcome === undefined
-        ? await readRunJsonIfExists(runPaths, RUN_STATUS_FILE)
+        ? runJsonValue(await readRunJsonIfExists(runPaths, RUN_STATUS_FILE))
         : undefined;
     return { display: runDisplay(bundleDisplayFacts(displayed, status)) };
 }
@@ -155,18 +156,24 @@ export async function readReview(cwdInput, runInput) {
     if (!verified.ok || !verified.bundlePath) {
         return verified;
     }
-    const review = runPaths ? await readRunJsonIfExists(runPaths, "review.json") : null;
+    const reviewRead = runPaths ? await readRunJsonIfExists(runPaths, "review.json") : undefined;
+    const review = reviewRead === undefined ? null : runJsonValue(reviewRead);
     if (!isReviewSummary(review)) {
         return {
             ...verified,
             ok: false,
             error: {
                 code: "HUMANISH_INVALID_RUN_BUNDLE",
-                message: "review.json is missing or invalid.",
+                message: reviewRead?.status === "refused"
+                    ? `${refusalText("review.json", reviewRead)}.`
+                    : "review.json is missing or invalid.",
             },
         };
     }
-    const bundle = runPaths ? await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE) : null;
+    // The display reads what it can: a run.json refused here shows as a missing one does.
+    const bundle = runPaths
+        ? runJsonValue(await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE))
+        : null;
     const projected = isRecord(bundle) && Array.isArray(bundle.streams)
         ? withCuaReviewProvenance(review, bundle.streams.filter(isRecord))
         : review;

package/dist/run/transient-comms-secrets.js

@@ -1,7 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { REDACTION_MARKERS } from "../evidence/redaction.js";
-import { holdsSecretValue, scrubSecretValues } from "../evidence/secret-scrub.js";
-import { escapeRegExp } from "./text.js";
+import { holdsSecretValue, scrubSecretValues, scrubValuesAsWritten, } from "../evidence/secret-scrub.js";
 const scopes = new AsyncLocalStorage();
 const MAX_VALUES = 8192;
 const MAX_BYTES = 1024 * 1024;
@@ -15,7 +14,7 @@ function usable(scope) {
 function fail(scope) {
     scope.failed = true;
     scope.values.clear();
-    delete scope.pattern;
+    delete scope.literal;
     throw new Error("TRANSIENT_NARRATION_SECRET_LIMIT");
 }
 /** Enclose both participant execution and its automatic analysis in one scope. Nested runs isolate too. */
@@ -30,7 +29,7 @@ export async function withTransientCommsSecrets(work) {
         scope.closed = true;
         scope.values.clear();
         scope.bytes = 0;
-        delete scope.pattern;
+        delete scope.literal;
     }
 }
 export function registerTransientCommsSecrets(values) {
@@ -50,7 +49,7 @@ export function registerTransientCommsSecrets(values) {
             fail(scope);
         scope.values.add(value);
         scope.bytes += bytes;
-        delete scope.pattern;
+        delete scope.literal;
     }
 }
 /** Literal, longest-first replacement in one pass; replacement text is never matched recursively. */
@@ -59,18 +58,8 @@ export function scrubTransientCommsText(text) {
     if (!scope)
         return text;
     usable(scope);
-    if (!scope.values.size)
-        return text;
-    try {
-        scope.pattern ??= new RegExp([...scope.values]
-            .sort((a, b) => b.length - a.length)
-            .map(escapeRegExp)
-            .join("|"), "g");
-        return text.replace(scope.pattern, REDACTION_MARKERS.secret);
-    }
-    catch {
-        return fail(scope);
-    }
+    scope.literal ??= scrubValuesAsWritten([...scope.values]);
+    return scope.literal(text);
 }
 const REDACTED = REDACTION_MARKERS.secret;
 /**

package/dist/run-study.js

@@ -4,7 +4,6 @@
 // which runs the route's local checks that need no scorer (keys, subject env, the local agent) and
 // returns the route's run. prepareStudy is the same path in two steps, so the CLI can present either
 // refusal before it loads a declared review scorer.
-import { participantList } from "./study/study-fields.js";
 import { personaBackgroundWarnings } from "./study/warnings.js";
 import { resolveCommittedPersonasForCwd, studyPersonaIds } from "./study/persona-resolve.js";
 import { computerUseInput, scriptedInput, sharedWorldInput, terminalInput, } from "./study/route-inputs.js";
@@ -73,8 +72,12 @@ export async function prepareStudy(config, options, deps = {}) {
         outcome.result.warnings.push(...normalized.warnings);
         return { ok: false, outcome };
     }
-    const runWarnings = [...(planned.planned.plan.warnings ?? [])];
-    const plan = { ...planned.planned.plan, warnings: runWarnings };
+    // The run records the background warnings in its bundle with the plan's own.
+    const backgroundWarnings = await planBackgroundWarnings(planned.planned.plan, study, options.cwd);
+    const plan = {
+        ...planned.planned.plan,
+        warnings: [...(planned.planned.plan.warnings ?? []), ...backgroundWarnings],
+    };
     const admitted = await admitPlan(study, planning, plan, deps, normalized.emit);
     if (!admitted.ok) {
         await vm?.close();
@@ -97,16 +100,7 @@ export async function prepareStudy(config, options, deps = {}) {
                         return outcome;
                     }
                 }
-                // Admission keeps its refusal order; these warnings join the plan before its run scope opens.
-                const personas = route === "computer-use" || route === "shared-world"
-                    ? (await resolveCommittedPersonasForCwd(options.cwd, studyPersonaIds(study))).personas
-                    : new Map();
-                const backgroundWarnings = personaBackgroundWarnings(route === "computer-use" &&
-                    options.count !== undefined &&
-                    participantList(study) === undefined
-                    ? { ...study, participants: options.count }
-                    : study, personas);
-                runWarnings.splice(0, runWarnings.length, ...(planned.planned.plan.warnings ?? []), ...backgroundWarnings);
+                // A run's result lists the background warnings; a refusal before the run does not.
                 normalized.warnings.push(...backgroundWarnings);
                 // The route layers the scorer over the inputs it admitted, and the local study is not
                 // rebuilt for it. The admitted runSession, provider and participant desktop belong to this
@@ -125,6 +119,21 @@ export async function prepareStudy(config, options, deps = {}) {
         },
     };
 }
+/**
+ * A warning for each of the plan's participants whose persona has no background. Only
+ * computer-use and shared-world plans have participants; the committed personas are read for them.
+ */
+async function planBackgroundWarnings(plan, study, cwd) {
+    const participants = plan.route === "computer-use"
+        ? plan.runner.participants
+        : plan.route === "shared-world"
+            ? plan.plane.participants
+            : [];
+    if (participants.length === 0)
+        return [];
+    const { personas } = await resolveCommittedPersonasForCwd(cwd, studyPersonaIds(study));
+    return personaBackgroundWarnings(plan.studyId, participants, personas);
+}
 /** The route's admit function for a plan, with the route's input from the run's options. */
 async function admitPlan(config, options, plan, deps, emit) {
     switch (plan.route) {

package/dist/study/adapter-scorer-loader.js

@@ -18,7 +18,7 @@ import { realpath } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { digestText, redactText } from "../evidence/redaction.js";
-import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+import { prepareSelectedOutputDirectory, readContainedRegularFile, refusalText, PROJECT_FILE_MAX_BYTES, } from "../run/contained-output.js";
 /**
  * A scorer written for computer use and shared world, as `RunStudyOptions.scorer` takes it. Those
  * routes pass the browser context; another route that calls it passes a context it was not written
@@ -96,11 +96,13 @@ export async function loadAdapterScorer(args) {
     const relPosix = relative.split(path.sep).join("/");
     // Fail-closed containment gate on the entry file only: rejects symlink, nlink>1, realpath-escape,
     // TOCTOU. Its returned bytes are the digest input.
-    const bytes = await readContainedRegularFile(root, relPosix);
-    if (!bytes) {
+    const read = await readContainedRegularFile(root, relPosix, PROJECT_FILE_MAX_BYTES);
+    if (read.status === "refused" && read.reason === "too-large")
+        return fail("HUMANISH_STUDY_SCORER_NOT_FOUND", `review.scorer.ref "${trimmed}" could not be read: ${refusalText(relPosix, read)}.`);
+    if (read.status !== "read") {
         return fail("HUMANISH_STUDY_SCORER_NOT_FOUND", `review.scorer.ref "${trimmed}" could not be read as a regular file inside the project (${relPosix}). Use a plain file there: not a symlink or a hard link, and not a path that resolves outside the project.`);
     }
-    const digest = digestText(bytes.toString("utf8"));
+    const digest = digestText(read.bytes.toString("utf8"));
     // Import the entry module in a broad try/catch (ERR_MODULE_NOT_FOUND / SyntaxError / ERR_REQUIRE_ESM
     // / top-level throw). import() executes the transitive graph, and the cwd clamp guards only the entry
     // file; out-of-tree/transitive code is acceptable only because of the trust boundary above.

package/dist/study/config.js

@@ -40,7 +40,7 @@ import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./r
 import { declaredParticipantIds } from "./plan-participants.js";
 import { declaredParticipantCount, participantList } from "./study-fields.js";
 import { ID_PATTERN, STUDY_SCHEMA, } from "./types.js";
-import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, smtpValidationReason, taskProtocolValidationReason, } from "./validation.js";
+import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, smtpValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "./validation.js";
 import { forwardDeclaredWarnings, inertFieldLabels, inertFieldPaths } from "./warnings.js";
 import { plural } from "../run/text.js";
 /**
@@ -228,6 +228,9 @@ function checkStudyConfig(config) {
     const outputLimitReason = outputTokenLimitValidationReason(config);
     if (outputLimitReason)
         return invalid(outputLimitReason);
+    const waitLimitReason = waitLimitValidationReason(config);
+    if (waitLimitReason)
+        return invalid(waitLimitReason);
     // All-parallel default: a multi-participant study that does not declare execution.concurrency
     // runs every participant at once; the declared field is a cap the author chose, never a mode.
     // Independent computer-use participants resolve that default from the final participant count

package/dist/study/discover.js

@@ -1,4 +1,4 @@
-import { personaBackgroundWarnings } from "./warnings.js";
+import { personaBackgroundWarnings, plannedParticipants } from "./warnings.js";
 import { studyPersonaIds, resolveCommittedPersonasForCwd } from "./persona-resolve.js";
 import { personaBrief, PersonaConfigError } from "./persona.js";
 import { constants } from "node:fs";
@@ -7,7 +7,7 @@ import path from "node:path";
 import { parse } from "yaml";
 import { parseStudy } from "./config.js";
 import { V2_SCHEMA } from "./migrate/v2.js";
-import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareSelectedOutputDirectory, readContainedRegularFile, refusalText, PROJECT_FILE_MAX_BYTES, } from "../run/contained-output.js";
 import { isNodeError } from "../run/type-guards.js";
 import { studyFileCandidates, STUDY_DIRECTORIES } from "./files.js";
 const STUDY_LIST_SCHEMA = "humanish.study-list.v1";
@@ -197,7 +197,7 @@ export async function inspectStudyManifest(cwd, study) {
         warnings: [
             ...resolved.warnings,
             ...personaResolution.warnings,
-            ...personaBackgroundWarnings(resolved.config, personaResolution.personas),
+            ...personaBackgroundWarnings(resolved.config.id, plannedParticipants(resolved.config), personaResolution.personas),
         ],
     };
 }
@@ -279,14 +279,17 @@ async function readManagedManifest(projectRoot, relativePath) {
     if (inspected.status !== "ok") {
         return inspected;
     }
-    const contents = await readContainedRegularFile(projectRoot, relativePath.replace(/\\/g, "/"));
-    if (!contents) {
+    const contents = await readContainedRegularFile(projectRoot, relativePath.replace(/\\/g, "/"), PROJECT_FILE_MAX_BYTES);
+    if (contents.status === "refused" && contents.reason === "too-large")
+        return { status: "unsafe", message: `${refusalText("The study file", contents)}.` };
+    // Gone or swapped since it was inspected above.
+    if (contents.status !== "read") {
         return {
             status: "unsafe",
             message: "The study file changed or failed containment validation.",
         };
     }
-    return { status: "ok", contents: contents.toString("utf8") };
+    return { status: "ok", contents: contents.bytes.toString("utf8") };
 }
 async function readExplicitManifest(projectRoot, requestedPath) {
     try {

package/dist/study/init-paths.js

@@ -4,7 +4,7 @@
 import { lstat } from "node:fs/promises";
 import path from "node:path";
 import { runtimeDirectories, starterFiles } from "./init-templates.js";
-import { assertPreparedSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+import { assertPreparedSelectedOutputDirectory, ContainedReadRefusedError, readContainedRegularFile, PROJECT_FILE_MAX_BYTES, } from "../run/contained-output.js";
 import { isPathInside } from "../run/paths.js";
 import { isNodeError } from "../run/type-guards.js";
 export async function validateInitProjectPaths(cwd) {
@@ -54,10 +54,12 @@ function unsafeProjectPath(relativePath) {
     };
 }
 export async function readTextIfExists(projectRoot, relativePath) {
-    const bytes = await readContainedRegularFile(projectRoot, relativePath);
-    if (bytes !== null) {
-        return bytes.toString("utf8");
-    }
+    const read = await readContainedRegularFile(projectRoot, relativePath, PROJECT_FILE_MAX_BYTES);
+    if (read.status === "read")
+        return read.bytes.toString("utf8");
+    // A file over the limit is a size problem, not an unsafe path.
+    if (read.status === "refused" && read.reason === "too-large")
+        throw new ContainedReadRefusedError(relativePath, read);
     const target = path.join(projectRoot.physicalPath, relativePath);
     try {
         await lstat(target);

package/dist/study/keys.d.ts

@@ -107,6 +107,8 @@ export declare const ACTOR: {
     mission: true;
     model: true;
     maxOutputTokens: true;
+    maxWaitMs: true;
+    idleWaitMs: true;
     localAgent: true;
     reasoningEffort: true;
     stopWhen: {

package/dist/study/keys.js

@@ -94,6 +94,8 @@ export const ACTOR = {
     mission: true,
     model: true,
     maxOutputTokens: true,
+    maxWaitMs: true,
+    idleWaitMs: true,
     localAgent: true,
     reasoningEffort: true,
     stopWhen: STOP_WHEN,

package/dist/study/migrate/v2.js

@@ -95,7 +95,8 @@ const V2_KEYS = {
         lanes: PARTICIPANT_ENTRY,
         // Roster groups are participants with a count; the parser expanded them into `lanes[]`.
         roster: { ...PARTICIPANT_ENTRY, count: true },
-        ...without(ACTOR, "type"),
+        // maxWaitMs and idleWaitMs arrived after v2, so a v2 file cannot carry them.
+        ...without(ACTOR, "type", "maxWaitMs", "idleWaitMs"),
         laneFocus: { id: true, label: true, instruction: true },
     },
     execution: withAfter(EXECUTION, "egressAllow", { caps: CAPS }),

package/dist/study/parse/actors.js

@@ -1,6 +1,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 { waitFieldsReason } from "../../actors/computer-use/wait.js";
 import { isHttpUrl } from "./subject.js";
 import { entryCredentialReason, urlCredentialReason } from "./url-credentials.js";
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
@@ -54,6 +55,13 @@ export function parseActorFields(entry, path) {
             return invalid(`${path}.maxOutputTokens must be a positive safe integer.`);
         actor.maxOutputTokens = entry.maxOutputTokens;
     }
+    const waitReason = waitFieldsReason(entry, `${path}.`);
+    if (waitReason)
+        return invalid(waitReason);
+    if (typeof entry.maxWaitMs === "number")
+        actor.maxWaitMs = entry.maxWaitMs;
+    if (typeof entry.idleWaitMs === "number")
+        actor.idleWaitMs = entry.idleWaitMs;
     const localAgent = str(entry.localAgent);
     if (entry.localAgent !== undefined) {
         if (localAgent !== "codex" && localAgent !== "claude") {

package/dist/study/persona-resolve.d.ts

@@ -5,8 +5,8 @@ import type { StudyConfig } from "./types.js";
 export declare function personaTitleFromId(personaId: string): string;
 /**
  * Resolve one persona from `humanish/personas/`, then the ignored `.humanish/local/personas/`.
- * Returns `null` with a warning when the id is unsafe or no file exists. Invalid rich backgrounds
- * reject the study before execution.
+ * Returns `null` with a warning when the id is unsafe or no file exists. Invalid rich backgrounds,
+ * and a persona file that is there and cannot be read, reject the study before execution.
  */
 export declare function resolveCommittedPersona(projectRoot: PreparedSelectedOutputDirectory, personaId: string): Promise<{
     persona: ResolvedPersona | null;

package/dist/study/persona-resolve.js

@@ -2,7 +2,7 @@
 import { parse as parseYaml } from "yaml";
 import path from "node:path";
 import { parseResolvedPersona, PersonaConfigError } from "./persona.js";
-import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+import { prepareSelectedOutputDirectory, readContainedRegularFile, PROJECT_FILE_MAX_BYTES, refusalText, } from "../run/contained-output.js";
 import { digestText, redactText } from "../evidence/redaction.js";
 import { realpath } from "node:fs/promises";
 import { participantList } from "./study-fields.js";
@@ -23,8 +23,8 @@ const PERSONA_DIRECTORIES = [
 ];
 /**
  * Resolve one persona from `humanish/personas/`, then the ignored `.humanish/local/personas/`.
- * Returns `null` with a warning when the id is unsafe or no file exists. Invalid rich backgrounds
- * reject the study before execution.
+ * Returns `null` with a warning when the id is unsafe or no file exists. Invalid rich backgrounds,
+ * and a persona file that is there and cannot be read, reject the study before execution.
  */
 export async function resolveCommittedPersona(projectRoot, personaId) {
     if (!PERSONA_ID_PATTERN.test(personaId)) {
@@ -37,9 +37,13 @@ export async function resolveCommittedPersona(projectRoot, personaId) {
         path.posix.join(directory, `${personaId}.yaml`),
         path.posix.join(directory, `${personaId}.yml`),
     ])) {
-        const bytes = await readContainedRegularFile(projectRoot, candidate);
-        if (!bytes)
+        const read = await readContainedRegularFile(projectRoot, candidate, PROJECT_FILE_MAX_BYTES);
+        if (read.status === "missing")
             continue;
+        // A candidate that is there and refused stops resolution: the next file is another persona.
+        if (read.status === "refused")
+            throw new PersonaConfigError(`Persona ${redactText(personaId)}: ${refusalText(candidate, read)}. Fix or remove that file; a lower-priority persona file is not used in its place.`);
+        const bytes = read.bytes;
         let raw;
         try {
             raw = parseYaml(bytes.toString("utf8"));

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

@@ -36,6 +36,10 @@ interface DesktopParticipant extends Participant {
         readonly dwell?: DwellWindow;
         readonly reasoningEffort?: ReasoningEffort;
         readonly maxOutputTokens?: number;
+        /** actor.maxWaitMs: the longest one wait action lasts. */
+        readonly maxWaitMs?: number;
+        /** actor.idleWaitMs: how long a wait with no duration lasts while the participant only waits. */
+        readonly idleWaitMs?: number;
     };
 }
 /** Only independent computer-use participants consume a task protocol and their own target. */