humanish 0.125.0 → 0.126.0

package/dist/verify/pages.js

@@ -0,0 +1,50 @@
+import { REDACTION_MARKERS } from "../evidence/redaction.js";
+import { isRecord } from "../run/type-guards.js";
+// A recorded page (`items[].page`, `finalPage`) keeps a URL's origin and path only. The text scan
+// finds secret shapes in it as in any trace text, but a query string, a fragment or user info can
+// carry a short token no pattern matches, so a page holding one is a public-safety finding.
+// The markers that can stand for a whole origin, such as a withheld sandbox host.
+const MARKERS = new Set(Object.values(REDACTION_MARKERS));
+// `scheme:` alone (a non-web URL) or `scheme://host[:port]`, with nothing after the host. The URL
+// parser reads a backslash there as a slash, so a backslash counts as a path too.
+const ORIGIN = /^[a-z][a-z0-9+.-]*:(?:\/\/[^/\\?#@]*)?$/i;
+/** What is wrong with a recorded page, or undefined when it holds an origin and a path only. */
+function pageProblem(page) {
+    if (!isRecord(page) || typeof page.origin !== "string" || typeof page.path !== "string")
+        return "is not an origin and a path";
+    if (/[?#]/.test(page.path))
+        return "has a query string or fragment in its path";
+    if (!MARKERS.has(page.origin) && !ORIGIN.test(page.origin))
+        return "has an origin with user info, a path, a query string or a fragment";
+    return undefined;
+}
+/**
+ * One finding per recorded page that holds more than an origin and a path, in each finished
+ * trace's items and summary and each running participant's items. A finding names where the page
+ * is, never what it says.
+ */
+export function pageFindings(bundle) {
+    const findings = [];
+    const check = (where, page) => {
+        if (page === undefined)
+            return;
+        const problem = pageProblem(page);
+        if (problem !== undefined)
+            findings.push(`${where} ${problem}`);
+    };
+    // The shape guard admits items that are not records, so each is read as unknown.
+    const checkItems = (where, items) => {
+        if (!Array.isArray(items))
+            return;
+        items.forEach((item, index) => {
+            if (isRecord(item))
+                check(`${where}[${index}].page`, item.page);
+        });
+    };
+    for (const stream of bundle.streams) {
+        checkItems(`${stream.id} items`, stream.actor?.items);
+        check(`${stream.id} finalPage`, stream.actor?.finalPage);
+        checkItems(`${stream.id} liveActor.items`, stream.liveActor?.items);
+    }
+    return findings;
+}

package/dist/verify/verify.js

@@ -16,6 +16,7 @@ import { runNotFoundMessage } from "../run/run-not-found.js";
 import { actorVerdictConsistencyFindings, noEngagementActorFindings, validateCodexAppServerEvidence, validateTerminalProductEvidence, } from "./actor.js";
 import { invalidRunEvidenceReferences, MAX_REPORTED_FINDINGS, missingLocalEvidenceArtifacts, rawScreenshotPostureWarnings, rawScreenshotStreamIds, redactedShapeFramePaths, scanRunPublicSafetyArtifacts, scanSourceEvidence, streamScreenshotPaths, unscannedMessage, } from "./artifacts.js";
 import { flatContextWarnings } from "./context-growth.js";
+import { pageFindings } from "./pages.js";
 import { runNotFinished } from "./liveness.js";
 import { costAndReceiptFindings } from "./costs.js";
 import { rerunLineageFindings } from "./rerun.js";
@@ -229,7 +230,7 @@ function evidenceArtifactsCheck(shaped, problems) {
 async function loadTraces(runPaths, stored) {
     const scanned = { sensitive: [], opaque: [] };
     if (!isRunBundle(stored))
-        return { bundle: stored, refusedTraces: [], ...scanned };
+        return { bundle: stored, refusedTraces: [], ...scanned, pages: [] };
     // Each trace is source evidence: scanned by the bytes it was joined from, apart from the
     // directory walk and any path exemption the walk makes.
     const { bundle, refused } = await loadStreamTraces(runPaths, stored, {
@@ -239,9 +240,14 @@ async function loadTraces(runPaths, stored) {
                 scanned[scan === "sensitive" ? "sensitive" : "opaque"].push(file);
         },
     });
-    return { bundle, refusedTraces: refused.map((error) => error.message), ...scanned };
+    return {
+        bundle,
+        refusedTraces: refused.map((error) => error.message),
+        ...scanned,
+        pages: pageFindings(bundle),
+    };
 }
-/** The trace scan's results, beside the walk's: each file named once. */
+/** The trace scan's results, beside the walk's: each file named once, then each page finding. */
 function addTraceScan(traces, findings, unscanned) {
     for (const file of traces.sensitive)
         if (!findings.includes(`sensitive text ${file}`))
@@ -249,6 +255,7 @@ function addTraceScan(traces, findings, unscanned) {
     for (const file of traces.opaque)
         if (!unscanned.files.includes(file))
             unscanned.files.push(file);
+    findings.push(...traces.pages);
 }
 /** The top-level run.json sections the shape guard requires. */
 const REQUIRED_SECTIONS = [

package/docs/architecture/actor-contract.md

@@ -167,6 +167,7 @@ export interface ActorTraceItem {
   command?: { text?: string; cwd?: string; exitCode?: number; outputTail?: string };
   screenshotRef?: { path: string; redaction: "blurred" | "ocr_scrubbed" | "none" };
   text?: string; // redacted
+  page?: { origin: string; path: string }; // computer-use screenshot items; redacted, no query
 }
 
 export interface ActorCapabilities {
@@ -204,6 +205,7 @@ export interface ActorTrace {
   ids: { sessionId?: string; threadId?: string; turnId?: string; model?: string };
   counts: Record<string, number>;
   items: ActorTraceItem[];
+  finalPage?: { origin: string; path: string }; // computer-use: the last observation's page
   tokenUsage?: { input?: number; output?: number; total?: number; costUsd?: number };
   estimatedCost?: ActorEstimatedCost; // humanish.actor-estimated-cost.v1 (additive)
   capabilities: ActorCapabilities;

package/docs/architecture/external-public-shared-world.md

@@ -120,7 +120,10 @@ The runtime `location.href` (and the 6-char code inside it) is never persisted r
 runtime-only; the threaded code flows only into the follower's composed prompt (never a raw bundle
 field) and is scrubbed from all narration once latched; the shared origin and lobby path persist only
 as sha256-16 digests (`publicOriginDigest`, `lobbyConvergenceDigest`). This matches the existing
-e2b-URL / host-digest redaction discipline.
+e2b-URL / host-digest redaction discipline. The computer-use loop records each observation's page
+origin and path by default; the shared-world runner (`participantRunDeps` in
+`src/routes/shared-world/participant-specs.ts`) runs every session with `recordPages: false`, on
+both planes, so no page and no `finalPage` reaches a shared-world trace.
 
 ## Mobile fidelity caveat
 

package/docs/architecture/observer.md

@@ -74,7 +74,16 @@ public-safe metadata.
 
 The browser polls `observer-feed.json` with `no-store` caching: the server's
 projection of the run as `{ data, items }`, observer-data.json's content and the
-items, from one read of the run per poll. Static
+items, from one read of the run per poll. While a participant runs, its entry in
+`items` carries `live`, a cursor `<position>.<generation>.<items>.<bytes>` naming its
+live file (`live/<position>.<generation>.ndjson`) and how far the list goes. The page
+sends the cursors of its last body back as `?after=<cursor>,<cursor>`, and the server
+then reads and sends only the items past each one, marking that entry with
+`liveAfter`, the cursor they follow (`src/observer/feed-cursors.ts`). A cursor for an
+earlier generation, past the index or off a line end gets the participant's full list,
+and so does every participant of a finished run. A tail is checked for line ends and
+its line count; the sha256 run.json records is checked whenever a list is read whole.
+A page that cannot join a body sends no cursors with its next poll. Static
 `file://` opening still works for immutable review, but follow mode is the
 operator path. Agents and CI should use `humanish watch --json --no-open` for
 the same fresh evidence without browser open or a long-running process.

package/docs/contracts/policy.md

@@ -146,6 +146,13 @@ certification that the artifact is free of every class in the policy below. A
 first-class PII/PHI detector is [planned](https://github.com/danielgwilson/humanish/issues/108) and would move the listed
 PII classes from author-responsibility to enforced.
 
+The same scan reads the page each computer-use observation recorded (`items[].page`,
+`finalPage`). verify also reports a page whose path holds a query string or fragment, or whose
+origin holds user info or anything after the host, since such a part can carry a short token no
+pattern matches. The recorder withholds email- and token-shaped path segments
+([schemas.md](schemas.md#actor-trace)); a name or other personal data in a readable path is not
+detected.
+
 Required redaction gates:
 
 - run bundle verification;

package/docs/contracts/run-bundle.md

@@ -332,7 +332,7 @@ An actor trace may include `stopCause` alongside its unchanged `status`,
 `completionReason` and verbatim `reason`. Computer-use sessions distinguish
 `provider_output_limit`, `provider_token_limit`, `time_limit`, `spend_limit`,
 `study_spend_limit`, `adapter_limit`, `provider_incomplete`, `provider_status`,
-`provider_refused_prompt`, `harness_aborted`, `usage_unreported`, and `scheduled_end`. Absence means the route or
+`provider_refused_prompt`, `harness_aborted`, `usage_unreported`, `scheduled_end`, and `session_cap`. Absence means the route or
 recording did not retain this precise field; it does not mean the participant
 finished.
 
@@ -454,6 +454,36 @@ contain the older requested-screen `stream.viewport` shape without `desktopGeome
 Deterministic Playwright-style adapters remain free to declare a viewport that they also render
 exactly; this hosted-desktop rule does not change that contract.
 
+## Desktop Files
+
+A hosted computer-use participant's stream carries `desktopFiles` when its study gave it
+`participants[].files`: one entry per file confirmed on the desktop before the participant
+started, in the order they landed.
+
+```yaml
+desktopFiles:
+  - as: Downloads/insurance-card.png
+    size: 251
+    sha256: <64 hex characters>
+```
+
+`as` is relative to the desktop user's home folder. `size` is the byte count humanish copied,
+which `files.getInfo` on the desktop matched. `sha256` is the digest of those bytes, read on the
+host before any sandbox existed. The contents and the `from` path are not recorded. A participant
+whose copy failed records the files confirmed before the failure. No `desktopFiles` means no file
+was confirmed on that desktop: the study gave the participant none, the run was a dry run, or the
+copy failed before the first file was confirmed. A copy that failed records a `warn` event of type
+`cua-lab.desktop.files.completed`.
+
+## Participant Time Zone
+
+A computer-use or shared-world participant's stream carries `timeZone`, a tz database name such as
+`Europe/London`, when its study gave it one: `participants[].clock.timeZone`, else
+`actor.clock.timeZone`. Its turns gave the local time in that zone, and on a hosted desktop its
+browser launched with `TZ` set to it. The field records the declared zone, also on a dry run; it is
+not read back from the browser. No `timeZone` means the participant had none, and its hosted
+browser ran in the desktop's UTC.
+
 ## Subject Provenance
 
 `subject` is an optional, additive top-level field: structured provenance for

package/docs/contracts/schemas.md

@@ -210,6 +210,24 @@ The rest of this section names keys by their v3 spelling:
   Public/non-loopback targets still require `policies.allowPublicTargets: true`.
   `target` is mutually exclusive with `entry`: `target` is an absolute app-url
   browser target; `entry` is a shared-world participant's same-origin path;
+- `participants[].files` (computer-use on `execution.target: e2b-desktop` only):
+  1 to 20 `{ from, as }` entries, each a file copied onto that participant's desktop
+  before its browser opens. `from` is relative to the folder that holds the study file
+  (`cwd` for a library config); `as` is relative to the desktop user's home folder.
+  The parser refuses an absolute path, a `.`, `..` or empty part, a backslash, an `as`
+  that starts with `~`, lands in `subject/` or on a name starting with `.humanish`, looks
+  like a secret, a local path or encoded text, repeats another `as` or is its folder,
+  and a `from` the local-tree denylist names in any case (`isLocalTreeDenylisted` in
+  `src/subject/local-tree-archive.ts`). The route also refuses an `as` that holds a
+  value from the run's environment, such as a key. The route reads each distinct `from` once, before
+  any sandbox and on dry runs too, with `readContainedRegularFile`: a missing file, a
+  folder, a symbolic or hard link, a path out of the folder, a file above 10 MiB, more
+  than 25 MiB for one participant or 100 MiB of distinct files for the study is
+  refused with `HUMANISH_COMPUTER_USE_DESKTOP_FILES_INVALID` (`readDesktopFiles` in
+  `src/study/desktop-files.ts`). Each file
+  is written with the E2B SDK's `files.write` and its `files.getInfo` size must match, or
+  the participant fails before its first turn. The stream records `desktopFiles`
+  ([run-bundle.md](run-bundle.md#desktop-files)). Other routes refuse the field;
 - a `participants` entry with `count: n` (computer-use E2B route): a group of
   repeated participants. It needs an `id` and the parser expands it to
   `<id>-01` … `<id>-NN`, even when n is 1, before the engine runs (`viewer-01`,
@@ -235,17 +253,42 @@ The rest of this section names keys by their v3 spelling:
   participant's session budget is its window plus 5 minutes (`participantSessionMs` in
   `src/study/arrivals.ts`) in place of `execution.timeoutMs`, and its sandbox deadline adds the
   route's headroom to that. At the end the loop requests the closing report (`debrief.trigger:
-  scheduled_end`) and the session ends `goal_satisfied` with `stopCause: scheduled_end`. Before
+  scheduled_end`) and the session ends `goal_satisfied` with `stopCause: scheduled_end`. The
+  outcome an accepted report declares, its `outcome` field or the first line of its summary, is
+  the trace's `declaredOutcome`. The blocker rule reads a declared `reached` or `blocked` before
+  the summary, and after a declared `not_reached` it reads the summary. Before
   the end, a turn that requests no action does not end the session: the trace records a
   `participant ended before its scheduled end` notice, the next request says the time left, and
   the turn counts toward the idle backstop. Before the end, a turn that only waits or takes
   screenshots counts toward neither backstop streak (`advanceBackstop`'s `waitingIsTheTask`). The
   plan entry carries `endAfterMs`, and `study check` prints a `windows` row;
+- `participants[].maxSessionMs` (computer-use only, also on `count:` groups): the longest the
+  participant's session lasts, in whole milliseconds from 1 to 86,400,000, counted from the start
+  of its own session. `windDownMs` applies to it as to `endAfterMs`. Refused: a value outside that
+  range, `maxSessionMs` beside `endAfterMs` on one participant, `maxSessionMs` on `shared-world`,
+  and a cap whose sandbox deadline passes the sandbox ceiling. The session budget is the cap plus
+  5 minutes (`participantSessionMs`) in place of `execution.timeoutMs`, and the schedule holds the
+  participant's slot that long. The route reads the cap's end when the session starts
+  (`participantEnd` in `src/study/arrivals.ts`, `participantClock` in
+  `src/routes/computer-use/participant-model.ts`) and passes it to the loop as
+  `clock.end` with `kind: session_cap`. The participant may end its session before the cap, and
+  its waiting turns count toward the backstops. At the cap the loop requests the closing report
+  (`debrief.trigger: session_cap`) and the session ends `goal_satisfied` with
+  `stopCause: session_cap`, its report's declared outcome read as at a scheduled end. The plan
+  entry carries `maxSessionMs`, and the plan line shows
+  `cap=<duration>`;
 - `participants[].idleWaitMs` (computer-use and shared-world, also on `count:` groups): this
   participant's `actor.idleWaitMs`, in the same range and refused above an explicit
   `actor.maxWaitMs` (`waitLimitValidationReason`). Its trace records it in `waitSettings`;
-- `actor.clock.timeZone` (computer-use): a tz database time zone name, such as `Europe/London`. Each turn's context hint carries
-  the local time in it, and a scheduled end is given in it (UTC without it);
+- `actor.clock.timeZone` (computer-use and shared-world): a tz database time zone name, such as `Europe/London`. Each turn's context hint carries
+  the local time in it, and a scheduled end or session cap is given in it (UTC without it). On a hosted desktop the
+  participant's browser launches with `TZ` set to it (`openParticipantSurface` in
+  `src/routes/computer-use/e2b-desktop/start.ts`). `parseClock` in `src/study/parse/clock.ts` refuses a name Intl does not know, a
+  UTC offset and a case variant of Intl's spelling, which Chrome's ICU reads as UTC or `Etc/Unknown`. The computer-use planner
+  refuses a zone on the local runtime and the in-process route with `HUMANISH_COMPUTER_USE_TIME_ZONE_UNSUPPORTED`;
+- `participants[].clock.timeZone` (computer-use and shared-world, also on `count:` groups): this participant's `actor.clock`,
+  with the same rule. The plan's `limits.timeZone` is the participant's zone, else the actor's. `study check` prints a
+  `time zones` row, and each participant's stream in `run.json` records `timeZone`;
 - `execution.concurrency` (computer-use E2B routes, including shared-world): a
   cap on participants in flight at once. When omitted, every participant runs
   simultaneously: both routes resolve it when they plan, from the final participant count
@@ -1011,6 +1054,32 @@ Core-owned fields:
   click-like `ui_action` items, structured `coord` (`x`/`y`). Both are additive:
   absent on older bundles and non-stamping producers, and absence means
   "timing/position unrecorded", never zero
+- optional `items[].page` and `finalPage` (`{ origin, path }`, `TracePage` in
+  `src/actors/contract.ts`): where a computer-use participant's browser was. The loop puts `page`
+  on the `screenshot` item of each observation that read a URL: `turn-00-start` is the page before
+  any action, `turn-01` the page after turn 1's actions, and dwell frames have their own.
+  `finalPage` is the page of the session's last observation, which is a closing observation with
+  no item when tasks are declared; it is absent when that observation read no URL. The screenshot
+  items with a `page`, in item order, then `finalPage`, list the participant's path through the
+  app. `origin` is the URL's scheme, host and port; `path` is its percent-encoded path. A query
+  string, fragment and user info are never kept, and a non-web URL keeps its scheme only
+  (`{ origin: "about:", path: "" }`). Redaction (`tracePage` in `src/evidence/trace-page.ts`):
+  a path segment becomes `[REDACTED_URL_PART]` when it percent-encodes a letter, digit, `-`, `.`,
+  `_`, `~` or `%`, or when any decoded reading of it is email-shaped, holds a run of 16 or more letters,
+  digits, `-` and `_` with a piece of 8 or more characters mixing letters and digits, or changes
+  under the trace text redaction (the study's secrets, then `redactText`). The whole path then
+  goes through that redaction, is cut to 1024 characters ending `[TRUNCATED]`, and is withheld
+  whole when verify's trace scan would still read it as sensitive or opaque. A host label
+  shaped like that token run becomes `[REDACTED_URL_PART]`, then the origin goes through the same
+  redaction (an E2B sandbox host becomes `[REDACTED_SECRET]`). When origin and path together
+  still change under that redaction (a study secret that is a whole link), both become
+  `[REDACTED_URL_PART]`. A token shorter than 16 characters, an
+  all-digit id and personal data in readable words stay, so the sharing rules for synthetic data
+  still apply. Pages come from the browser-state probe, which hosted runs have on Chrome and
+  Chromium only; a Firefox participant, or one whose probe is unavailable, has screenshots without
+  pages. The local browser route and the shared-world route record none. verify reports a page
+  whose path holds `?` or `#`, or whose origin is neither a redaction marker nor a scheme with an
+  optional host and port, as a public-safety finding. Both fields are additive; absence means "page not recorded"
 - optional `modelSettings` (`humanish.model-settings.v1`): how the model was
   asked to run, alongside `ids.model` which says which model it was.
   `reasoningEffort` records the value the request actually carried,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.125.0",
+  "version": "0.126.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",
@@ -96,7 +96,7 @@
     "comms:agentmail:contract": "node --import tsx scripts/agentmail-contract-check.mjs",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "lint": "node scripts/check-lint-cap.mjs --max-warnings=424",
+    "lint": "node scripts/check-lint-cap.mjs --max-warnings=411",
     "knip": "knip",
     "prose:check": "node scripts/check-code-prose.mjs",
     "vocabulary:check": "tsx scripts/check-retired-words.ts",