humanish 0.114.0 → 0.116.0

package/dist/verify/artifacts.d.ts

@@ -2,6 +2,11 @@ import { type PreparedRunArtifactPaths } from "../run/paths.js";
 import type { RunBundle } from "../run/bundle.js";
 /** Public-safety and evidence-reference findings stop at this many per list. */
 export declare const MAX_REPORTED_FINDINGS = 50;
+/**
+ * The most entries, files and directories, the public-safety scan visits in one run. Bundle export
+ * refuses a run with more, so the scan never passes a run whose files it did not all read.
+ */
+export declare const MAX_RUN_ENTRIES = 10000;
 export declare function missingLocalEvidenceArtifacts(runPaths: PreparedRunArtifactPaths, bundle: RunBundle): Promise<string[]>;
 /**
  * The PNG frames that actor traces register as stream screenshots, relative to the run root.
@@ -44,8 +49,10 @@ interface RegisteredStreamMedia {
 }
 /**
  * Scans every run file for secret and path patterns and returns the findings. A file that is not
- * registered stream media and that the scan cannot read as text (readPlainText), or cannot read at
- * all, goes to `unscanned`, so the caller can keep the run from grading share_ready.
+ * registered stream media and that the scan cannot read as text (readPlainText), cannot read at
+ * all, or that holds more than RUN_ARTIFACT_MAX_BYTES goes to `unscanned`, so the caller can keep
+ * the run from grading share_ready. So does a directory it cannot list, and the rest of the run
+ * after MAX_RUN_ENTRIES entries.
  */
 export declare function scanRunPublicSafetyArtifacts(runPaths: PreparedRunArtifactPaths, derivedFindings: string[], media: RegisteredStreamMedia, unscanned: string[]): Promise<string[]>;
 export {};

package/dist/verify/artifacts.js

@@ -6,15 +6,20 @@ import { scanEncodedTextCached } from "../evidence/encoded-text.js";
 import { readPlainText } from "../evidence/plain-text.js";
 import { containsSensitive } from "../evidence/redaction.js";
 import { isLocalEvidenceArtifactPath, isRiskyPublicArtifactPath, validatePreparedRunArtifactPaths, } from "../run/paths.js";
-import { openContainedRegularFile } from "../run/contained-output.js";
+import { openContainedRegularFile, RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
 import { holdsKeyedSandboxId } from "../run/sandbox-ids.js";
 import { SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
-import { readSafeRunArtifactBytes, readSafeRunArtifactJson } from "../run/locate.js";
+import { readSafeRunArtifact, readSafeRunArtifactBytes, readSafeRunArtifactJson, } from "../run/locate.js";
 import { isRecord } from "../run/type-guards.js";
 import { TERMINAL_EVENTS_ARTIFACT } from "../run/terminal-contract.js";
 import { isZeroEventTerminalTrace } from "./actor.js";
 /** Public-safety and evidence-reference findings stop at this many per list. */
 export const MAX_REPORTED_FINDINGS = 50;
+/**
+ * The most entries, files and directories, the public-safety scan visits in one run. Bundle export
+ * refuses a run with more, so the scan never passes a run whose files it did not all read.
+ */
+export const MAX_RUN_ENTRIES = 10_000;
 export async function missingLocalEvidenceArtifacts(runPaths, bundle) {
     const recordings = new Map(bundle.streams.flatMap((stream) => stream.recording ? [[stream.recording.path, stream.recording]] : []));
     const requiredPaths = new Map();
@@ -97,13 +102,18 @@ export async function missingLocalEvidenceArtifacts(runPaths, bundle) {
             }
             continue;
         }
-        const bytes = await readSafeRunArtifactBytes(runPaths, artifactPath);
-        if (!bytes || (bytes.length === 0 && !requirements.allowEmpty)) {
+        const artifact = await readSafeRunArtifact(runPaths, artifactPath);
+        if (artifact.state === "limit") {
+            missing.push(`${artifactPath} (larger than the ${RUN_ARTIFACT_MAX_BYTES} bytes verify reads)`);
+            continue;
+        }
+        if (artifact.state === "unavailable" ||
+            (artifact.bytes.length === 0 && !requirements.allowEmpty)) {
             missing.push(artifactPath);
             continue;
         }
         if (requirements.screenshot) {
-            const imageError = screenshotEvidenceError(artifactPath, bytes);
+            const imageError = screenshotEvidenceError(artifactPath, artifact.bytes);
             if (imageError) {
                 missing.push(`${artifactPath} (${imageError})`);
             }
@@ -280,17 +290,21 @@ export function rawScreenshotStreamIds(bundle, redactedShapeFrames) {
 }
 /**
  * Scans every run file for secret and path patterns and returns the findings. A file that is not
- * registered stream media and that the scan cannot read as text (readPlainText), or cannot read at
- * all, goes to `unscanned`, so the caller can keep the run from grading share_ready.
+ * registered stream media and that the scan cannot read as text (readPlainText), cannot read at
+ * all, or that holds more than RUN_ARTIFACT_MAX_BYTES goes to `unscanned`, so the caller can keep
+ * the run from grading share_ready. So does a directory it cannot list, and the rest of the run
+ * after MAX_RUN_ENTRIES entries.
  */
 export async function scanRunPublicSafetyArtifacts(runPaths, derivedFindings, media, unscanned) {
     const findings = [];
     await validatePreparedRunArtifactPaths(runPaths);
-    await scanRunPublicSafetyDirectory(runPaths, "", findings, derivedFindings, media, unscanned);
+    await scanRunPublicSafetyDirectory(runPaths, "", findings, derivedFindings, media, unscanned, {
+        entries: 0,
+    });
     await validatePreparedRunArtifactPaths(runPaths);
     return findings;
 }
-async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, findings, derivedFindings, media, unscanned) {
+async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, findings, derivedFindings, media, unscanned, walk) {
     // Each authority has its own finding budget. Derived files must never consume
     // the source scan's budget and make an unscanned recording appear verified.
     if (findings.length >= MAX_REPORTED_FINDINGS && derivedFindings.length >= MAX_REPORTED_FINDINGS) {
@@ -299,8 +313,18 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
     const current = relativeDirectory
         ? path.join(runPaths.physicalRunRoot, ...relativeDirectory.split("/"))
         : runPaths.physicalRunRoot;
-    const entries = await readdir(current).catch(() => []);
+    const entries = await readdir(current).catch(() => null);
+    if (entries === null) {
+        unscanned.push(`${relativeDirectory || "."}/ (could not be listed)`);
+        return;
+    }
     for (const entryName of entries) {
+        walk.entries += 1;
+        if (walk.entries > MAX_RUN_ENTRIES) {
+            if (walk.entries === MAX_RUN_ENTRIES + 1)
+                unscanned.push(`${relativeDirectory || "."}/ (the scan stops after ${MAX_RUN_ENTRIES} entries)`);
+            return;
+        }
         const relativePath = relativeDirectory ? `${relativeDirectory}/${entryName}` : entryName;
         const stats = await lstat(path.join(current, entryName), { bigint: true }).catch(() => null);
         const selectedFindings = !stats?.isDirectory() &&
@@ -328,7 +352,7 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
         if (stats.isDirectory()) {
             // A directory named analysis.json is not an owned record. Its children
             // can contain source evidence even after derived findings are saturated.
-            await scanRunPublicSafetyDirectory(runPaths, relativePath, findings, derivedFindings, media, unscanned);
+            await scanRunPublicSafetyDirectory(runPaths, relativePath, findings, derivedFindings, media, unscanned, walk);
             continue;
         }
         if (selectedFindings.length >= MAX_REPORTED_FINDINGS)
@@ -342,8 +366,8 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
         if (media.recordingPaths.has(relativePath) || media.screenshotPaths.has(relativePath)) {
             continue;
         }
-        // The scan reads a file by its bytes, not its name. A file that is not text, or that could
-        // not be read at all, holds bytes the scan never saw.
+        // The scan reads a file by its bytes, not its name. A file that is not text, that could not
+        // be read, or that is over the read limit holds bytes the scan never saw.
         const bytes = await readSafeRunArtifactBytes(runPaths, relativePath).catch(() => null);
         const decoded = bytes === null ? undefined : readPlainText(bytes);
         if (decoded === undefined || !decoded.ok) {

package/dist/verify/liveness.js

@@ -4,7 +4,8 @@
 // `ok: true` is not read as "the run finished" or "its sandboxes stopped". It never flips `ok`.
 import { sandboxIdDigest } from "../evidence/redaction.js";
 import path from "node:path";
-import { readRunJsonIfExists, readRunTextIfExists } from "../run/locate.js";
+import { refusalText } from "../run/contained-output.js";
+import { readRunJsonIfExists, readRunTextIfExists, runJsonValue } from "../run/locate.js";
 import { isRecord } from "../run/type-guards.js";
 import { RECLAIM_RECEIPT_ARTIFACT } from "../run/reclaim.js";
 import { runLiveness } from "../run/liveness.js";
@@ -22,7 +23,8 @@ const GONE_STATES = new Set(["killed", "already-gone"]);
  */
 export async function runNotFinished(runPaths, bundle, nowMs = Date.now()) {
     const runId = path.basename(runPaths.absoluteRunRoot);
-    const status = await readRunJsonIfExists(runPaths, RUN_STATUS_FILE);
+    // A status.json it refuses is no usable status, as a missing one is: the bundle decides.
+    const status = runJsonValue(await readRunJsonIfExists(runPaths, RUN_STATUS_FILE));
     const { liveness, record } = runLiveness(runId, status, bundle, nowMs);
     if (liveness === "finished")
         return { warnings: [] };
@@ -56,11 +58,23 @@ export async function runNotFinished(runPaths, bundle, nowMs = Date.now()) {
 /** What the reclaim receipt says about this run's sandboxes, and what to run. */
 async function reclaimState(runPaths, runId) {
     const journal = await readRunTextIfExists(runPaths, SANDBOX_RECEIPTS_ARTIFACT);
+    const command = `\`${cli(`reclaim --run ${runId}`)}\``;
+    // A journal it cannot read hides which sandboxes the run made, so no receipt can cover them.
+    if (journal.status === "refused")
+        return {
+            sandboxes: "unconfirmed",
+            text: `Sandboxes unconfirmed: ${refusalText(SANDBOX_RECEIPTS_ARTIFACT, journal)}, so the sandboxes it journaled are not known; check the file, then run ${command}.`,
+        };
     // Matched by digest: a reclaim receipt names each sandbox by digest, and one written before it
     // did holds the raw id, which is digested here.
-    const journaled = new Set((journal === null ? [] : parseSandboxReceipts(journal)).map((receipt) => sandboxIdDigest(receipt.sandboxId)));
-    const command = `\`${cli(`reclaim --run ${runId}`)}\``;
-    const receipt = reclaimReceipt(await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT), runId);
+    const journaled = new Set((journal.status === "missing" ? [] : parseSandboxReceipts(journal.text)).map((receipt) => sandboxIdDigest(receipt.sandboxId)));
+    const receiptRead = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
+    if (receiptRead.status === "refused")
+        return {
+            sandboxes: "unknown",
+            text: `Sandboxes unknown: ${refusalText(RECLAIM_RECEIPT_ARTIFACT, receiptRead)}, and the run journaled ${plural(journaled.size, "sandbox", "sandboxes")}; check the file, then run ${command}.`,
+        };
+    const receipt = reclaimReceipt(runJsonValue(receiptRead), runId);
     if (receipt === undefined)
         return {
             sandboxes: "unknown",

package/dist/verify/verify.js

@@ -6,8 +6,10 @@ import { containsSensitive, REDACTED_SANDBOX_ID } from "../evidence/redaction.js
 import { keyedSandboxIds, readRunSandboxIds } from "../run/sandbox-ids.js";
 import { validatePreparedRunArtifactPaths } from "../run/paths.js";
 import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA } from "../run/bundle.js";
+import { ContainedReadRefusedError, refusalText } from "../run/contained-output.js";
 import { isCleanupResult, isRunBundle } from "../run/bundle-shape.js";
-import { readRunJsonIfExists, readRunTextIfExists, resolveRunPath } from "../run/locate.js";
+import { readRunJsonIfExists, readRunTextIfExists, resolveRunPath, runJsonValue, } from "../run/locate.js";
+import { SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
 import { isRecord } from "../run/type-guards.js";
 import { runNotFoundMessage } from "../run/run-not-found.js";
 import { actorVerdictConsistencyFindings, noEngagementActorFindings, validateCodexAppServerEvidence, validateTerminalProductEvidence, } from "./actor.js";
@@ -75,26 +77,34 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         };
     }
     const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
-    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
-    const cleanupJson = await readRunJsonIfExists(runPaths, "cleanup.json");
-    const reviewJson = await readRunJsonIfExists(runPaths, "review.json");
-    const reviewMarkdown = await readRunTextIfExists(runPaths, "review.md");
-    checks.push(...bundlePresenceChecks(bundle, {
-        json: reviewJson !== null,
-        markdown: reviewMarkdown !== null,
-    }));
+    const bundleRead = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const bundle = runJsonValue(bundleRead);
+    const cleanupRead = await readRunJsonIfExists(runPaths, "cleanup.json");
+    const review = {
+        json: await readRunJsonIfExists(runPaths, "review.json"),
+        markdown: await readRunTextIfExists(runPaths, "review.md"),
+    };
+    checks.push(...bundlePresenceChecks(bundleRead, review));
     const derivedPublicSafetyFindings = [];
     const unscannedArtifacts = [];
     const sandboxIdFiles = [];
+    let journaledSandboxIds = [];
+    try {
+        journaledSandboxIds = await readRunSandboxIds(runPaths);
+    }
+    catch (error) {
+        if (!(error instanceof ContainedReadRefusedError))
+            throw error;
+        // Without the journal's ids, verify cannot clear any file of naming one.
+        unscannedArtifacts.push(SANDBOX_RECEIPTS_ARTIFACT);
+    }
     const publicSafetyFindings = await scanRunPublicSafetyArtifacts(runPaths, derivedPublicSafetyFindings, {
         recordingPaths: new Set(isRunBundle(bundle)
             ? bundle.streams.flatMap((stream) => (stream.recording ? [stream.recording.path] : []))
             : []),
         screenshotPaths: isRunBundle(bundle) ? streamScreenshotPaths(bundle) : new Set(),
         // A run from before 0.110 with no receipts still names its ids in run.json.
-        sandboxIds: [
-            ...new Set([...(await readRunSandboxIds(runPaths)), ...keyedSandboxIds(bundle)]),
-        ],
+        sandboxIds: [...new Set([...journaledSandboxIds, ...keyedSandboxIds(bundle)])],
         sandboxIdFiles,
     }, unscannedArtifacts);
     // JSON escapes can hide a sensitive value from the byte scan while the
@@ -129,7 +139,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
                 ? `invalid evidence artifact references: ${invalidEvidenceReferences.join(", ")}`
                 : `missing local evidence artifacts: ${missingEvidenceArtifacts.join(", ")}`,
     });
-    checks.push(...(await evidenceChecks(runPaths, bundle, cleanupJson)));
+    checks.push(...(await evidenceChecks(runPaths, bundle, cleanupRead)));
     const recordingOk = checks.every((check) => check.ok);
     if (derivedPublicSafetyFindings.length > 0)
         checks.push({
@@ -219,7 +229,8 @@ const REQUIRED_SECTIONS = [
  * Whether run.json, its schema, shape and redaction, and the review artifacts are present. Each
  * check says what it found, so a failing row never prints the rule it enforces.
  */
-function bundlePresenceChecks(bundle, review) {
+function bundlePresenceChecks(bundleRead, review) {
+    const bundle = runJsonValue(bundleRead);
     const record = isRecord(bundle) ? bundle : undefined;
     const schema = record?.schema;
     const schemaOk = schema === RUN_BUNDLE_SCHEMA;
@@ -227,14 +238,26 @@ function bundlePresenceChecks(bundle, review) {
     const redaction = isRecord(redactionRecord) ? redactionRecord.status : undefined;
     const missingSections = REQUIRED_SECTIONS.filter((key) => record?.[key] === undefined);
     const missingReview = [
-        ...(review.json ? [] : ["review.json is missing or not valid JSON"]),
-        ...(review.markdown ? [] : ["review.md is missing"]),
+        ...(review.json.status === "refused"
+            ? [refusalText("review.json", review.json)]
+            : runJsonValue(review.json) === null
+                ? ["review.json is missing or not valid JSON"]
+                : []),
+        ...(review.markdown.status === "refused"
+            ? [refusalText("review.md", review.markdown)]
+            : review.markdown.status === "missing"
+                ? ["review.md is missing"]
+                : []),
     ];
     return [
         {
             name: "run.json exists",
             ok: bundle !== null,
-            message: bundle === null ? "run.json is missing or not valid JSON" : "run.json is present",
+            message: bundleRead.status === "refused"
+                ? refusalText(RUN_BUNDLE_FILE, bundleRead)
+                : bundle === null
+                    ? "run.json is missing or not valid JSON"
+                    : "run.json is present",
         },
         {
             name: "run schema",
@@ -310,7 +333,8 @@ function findingsCheck(name, findings, okMessage, failLabel) {
  */
 const SHAPE_UNCHECKED = "not checked, because run.json failed the shape check";
 /** The bundle-content checks, in report order. A bundle that fails its shape guard has no findings. */
-async function evidenceChecks(runPaths, bundle, cleanupJson) {
+async function evidenceChecks(runPaths, bundle, cleanupRead) {
+    const cleanupJson = runJsonValue(cleanupRead);
     const valid = isRunBundle(bundle) ? bundle : null;
     const pass = (message) => (valid ? message : SHAPE_UNCHECKED);
     const checks = [
@@ -322,14 +346,17 @@ async function evidenceChecks(runPaths, bundle, cleanupJson) {
         findingsCheck("shared-world evidence", valid ? sharedWorldEvidenceFindings(valid) : [], pass("live shared-world evidence is well formed for its mode, with single-plane provenance, digest-only checkpoints and attributionLimits, or the run has none"), "shared-world findings"),
         {
             name: "cleanup receipt",
-            ok: cleanupJson === null || (isCleanupResult(cleanupJson) && cleanupJson.ok),
-            message: cleanupJson === null
-                ? "no cleanup.json; cleanup was not requested"
-                : !isCleanupResult(cleanupJson)
-                    ? "cleanup.json is malformed"
-                    : cleanupJson.ok
-                        ? "cleanup.json records a successful cleanup"
-                        : "cleanup.json records a failed cleanup",
+            ok: cleanupRead.status !== "refused" &&
+                (cleanupJson === null || (isCleanupResult(cleanupJson) && cleanupJson.ok)),
+            message: cleanupRead.status === "refused"
+                ? `${refusalText("cleanup.json", cleanupRead)}, so verify cannot say how cleanup went`
+                : cleanupJson === null
+                    ? "no cleanup.json; cleanup was not requested"
+                    : !isCleanupResult(cleanupJson)
+                        ? "cleanup.json is malformed"
+                        : cleanupJson.ok
+                            ? "cleanup.json records a successful cleanup"
+                            : "cleanup.json records a failed cleanup",
         },
         findingsCheck("rerun lineage", valid ? rerunLineageFindings(valid) : [], pass("rerun participants link to their prior status and a fan-out rerun event, or this run is not a rerun"), "rerun lineage findings"),
         // Cost is advisory on magnitude and fail-closed on labeling/provenance (claims match mechanism).
@@ -371,7 +398,7 @@ function buildShareSafety(args) {
         });
     }
     if (args.unscannedArtifacts.length > 0) {
-        const paths = [...args.unscannedArtifacts].sort();
+        const paths = [...new Set(args.unscannedArtifacts)].sort();
         const shown = paths.slice(0, MAX_LISTED_UNSCANNED).join(", ");
         const more = paths.length - MAX_LISTED_UNSCANNED;
         reasons.push({

package/docs/architecture/actor-contract.md

@@ -57,7 +57,7 @@ API surface.
 1. **Transport-agnostic contract; Codex stays the reference implementation.** The
    contract describes lifecycle and evidence, not transport. An adapter may be a
    subprocess protocol (Codex stdio JSON-RPC, `pi --mode rpc`, `claude -p
---output-format stream-json`) or an in-process SDK (`pi-agent-core`, Claude
+   --output-format stream-json`) or an in-process SDK (`pi-agent-core`, Claude
    Agent SDK, Stagehand). The existing Codex app-server integration is the
    reference adapter. `pi-agent-core` was planned as the first in-process-SDK
    adapter to prove both shapes early; it shipped only as a trace mapper with no
@@ -325,7 +325,7 @@ the computer-use loop distinguishes two ways to hit the cap:
 
 - **`budget_reached`**: the deadline was reached after at least one material (non-idle)
   action, or a spend, adapter or token limit ended the session. This maps to `ActorStatus:
-"incomplete"`: the participant did not reach the goal, and the harness did not fail.
+  "incomplete"`: the participant did not reach the goal, and the harness did not fail.
   `participantOutcomeOk` is false, the verdict is `fail`, and the CLI exits `2`. The trace
   `reason` and optional `stopCause` say which limit ended the session.
 - **`timed_out`**: the deadline was reached with zero material actions (a hung provider, an
@@ -422,7 +422,7 @@ returns the full `resolvedPersona` from `parseResolvedPersona`.
 Plan:
 
 1. **Parse the whole persona** into a `ResolvedPersona`: `{ id, name, summary, goals[],
-traits: { patience, skill, accessibilityNeeds? }, constraints[], sourceDigest }` (map
+   traits: { patience, skill, accessibilityNeeds? }, constraints[], sourceDigest }` (map
    `technical_confidence` to `skill`). The shipped shape in `src/study/persona.ts` has no
    `goals`, adds `background`, and makes every trait optional.
 2. **Compile traits into actor-neutral directives**, not prose, via a pure

package/docs/architecture/guest-desktop.md

@@ -18,8 +18,13 @@ Progress detection uses the same coarse frame signature as the hosted desktop.
 The actor receives the existing finite action union. Native tool paths, display,
 Xauthority and guest temporary directory come from the owner. Key names map to a
 closed list before reaching xdotool, whose own command syntax must never receive
-arbitrary participant strings. A native wheel step is not an exact pixel-scroll
-promise; one action permits at most 100 wheel steps. The entire drag is checked
+arbitrary participant strings. The list is `src/guest/desktop-keys.ts`, and the hosted
+E2B desktop translates through it too, so a key name works on both desktops or is
+refused on both. It holds OpenAI's computer-use key names, the names `@e2b/desktop`'s
+`press()` mapped, and every printable ASCII punctuation character as its keysym
+(`?` is `question`). A refused name reaches the participant as a rejected action.
+A native wheel step is not an exact pixel-scroll promise; one action permits at most
+100 wheel steps. The entire drag is checked
 before its first input. A pointer action's held keys must be modifiers (Shift,
 Ctrl, Alt, Super). They go down with one `keydown` before the action and up with
 one `keyup` after it. When an input fails, the `keyup` is still sent once, unless

package/docs/architecture/restricted-codex-analysis.md

@@ -176,7 +176,7 @@ the following, on Linux x64:
    runs this check; see "The qualifier" below.
 3. One hosted participant study with the candidate first on `PATH` (for example
    `PATH=<evidence>/npm-<version>/node_modules/.bin:$PATH pnpm humanish run <study>
---dotenv <file with E2B_API_KEY only>`) reached its goal in the final capture, with a
+   --dotenv <file with E2B_API_KEY only>`) reached its goal in the final capture, with a
    verified request receipt, `humanish verify --run <id>` passing and the automatic Codex
    analysis recording the release. Keep `OPENAI_API_KEY` out of that environment so the
    participant stays on ChatGPT-account billing.

package/docs/architecture/state-driven-executor.md

@@ -75,10 +75,12 @@ graphically dense (pixel-art) UI. `stableProgressKey(appState)`:
 ## A single desktop command failure is a recoverable skipped action
 
 `execute(action)` runs against a real substrate, and the real `@e2b/desktop`
-Sandbox **throws** `CommandExitError` on **any** non-zero exit. A `press`,
+Sandbox **throws** `CommandExitError` on **any** non-zero exit. A keypress,
 `scroll`, `drag`, `moveMouse`, or `click` can exit non-zero for reasons that have
 nothing to do with the run's health (a `Ctrl+Minus` zoom keypress exiting `2` was
-the reproduced case). The loop treats one such failure as a **recoverable skipped
+the reproduced case). xdotool also skips a key name it cannot resolve with a `No such
+key name` warning and exits `0`; the E2B executor turns that warning into an error with
+exit code `0` and xdotool's stderr. The loop treats one such failure as a **recoverable skipped
 action**, not a fatal error:
 
 - The per-action `execute()` call is wrapped at the loop boundary, in `runActionBatch`
@@ -86,7 +88,7 @@ action**, not a fatal error:
   uniformly. When the caught error `isCommandExitError`
   (`src/substrates/command-failure.ts`; it matches the SDK class name or any object carrying
   a numeric `exitCode`), the loop records a `notice` item (`status: "error"`, title `action
-skipped: desktop command failed`, text = the public-safe action label + exit code + a
+  skipped: desktop command failed`, text = the public-safe action label + exit code + a
   redacted `stderrTail`), does **not** count the action as a material action, and
   **continues**. The next `observe()` hands the model a fresh screenshot/state to adapt to.
 - An executor error declared as `action_rejected` with disposition `not_dispatched` also

package/docs/contracts/run-bundle.md

@@ -305,14 +305,16 @@ exactly; this hosted-desktop rule does not change that contract.
 `subject` is an optional, additive top-level field: structured provenance for
 what the computer-use, shared-world or scripted route actually drove (code pin plus state story). It
 is absent on pre-existing bundles and on bundles from routes that have not
-adopted it. The field shape, its three sources (`clone`, `app-url`,
-`local-tree`), and the `humanish verify` checks that guard it are the schema doc's
+adopted it. The field shape, its four sources (`clone`, `app-url`,
+`local-tree`, `desktop-cli`), and the `humanish verify` checks that guard it are the schema doc's
 job, not this one: see the `subject` entry under
 [`schemas.md`](schemas.md#run-bundle). In short, `clone` carries a
 `repo`/`commit` pin, `local-tree` carries an `archiveSha256`/`dirty` pin
-instead (a dirty working tree cannot be commit-pinned), and `app-url` carries
-no code pin at all. No path, basename, or other host-machine string ever
-enters this field; identity is digests, a sha, a boolean, and counts.
+instead (a dirty working tree cannot be commit-pinned), `desktop-cli` carries the
+declared `product` name, and `app-url` carries no code pin at all. A computer-use run
+of a desktop-cli study saved before `desktop-cli` was recorded says `app-url`, and
+readers accept it. No path, basename, or other host-machine string ever
+enters this field; identity is digests, a sha, a boolean, counts and the declared product name.
 
 ## Cost Estimate (advisory)
 
@@ -617,9 +619,13 @@ Each note a person adds while reviewing a run is its own file in the run directo
 - `author`: `"you"` in this version.
 - `createdAt`, `editedAt`: ISO-8601. Notes cannot be edited yet, so `editedAt` is `null`.
 
-A note file is written once and never rewritten: its bytes go to a temporary file inside
-`notes/`, which `link` gives the note's name only when no file has that name, and a taken name
-gets a new id. Adding a note reads no other note, so notes added at the same time from any
+A note file is created once under its own name, only when no file has that name (`O_CREAT` with
+`O_EXCL`), filled in one write and never rewritten; a taken name gets a new id. No temporary
+file or second link is made, so the run directory passes the single-link check that `verify`,
+serving and adding a note run while a note is added. A reader can find a note while it is being
+written, as an empty or short file; it skips and names that file like any unreadable note, and
+the next read finds the whole note. A writer stopped mid-write leaves such a file, which readers
+keep skipping. Adding a note reads no other note, so notes added at the same time from any
 process are all kept, and there is no lock. Readers list at most 1000 entries of `notes/` and
 read at most 500 notes, each within 16 KiB and refused before reading past that; any other
 entry, or a file that is not a note of the run, is skipped and named. The Observer servers serve
@@ -719,11 +725,17 @@ a file for secret and path patterns only when the bytes are strict UTF-8 with no
 control bytes other than tab, line feed and carriage return, the rule bundle
 export uses for text. `RAW_SCREENSHOTS` and `CONTINUOUS_MEDIA` grade the stream
 screenshots that actor traces reference under `screenshots/`, where the harness
-writes every frame, and the recordings `streams[].recording` registers. Every other file the scan cannot read as text, or cannot read at all,
-contributes `UNSCANNED_ARTIFACT`. The reason's message lists the paths, and it keeps
-otherwise valid evidence `local_only`. This includes images that only feedback
-candidates, adapter artifacts or stream artifact entries cite, and a PNG an actor
-trace references outside `screenshots/`. An unregistered
+writes every frame, and the recordings `streams[].recording` registers. Every
+other file the scan cannot read as text, cannot read at all, or that is larger
+than 32 MiB (verify reads at most that much of one file) contributes
+`UNSCANNED_ARTIFACT`. So does a folder the scan cannot list, and the rest of a
+run past its first 10,000 files and folders, the most `export --format bundle`
+takes. The reason's message lists the paths, and it keeps otherwise valid
+evidence `local_only`. This includes images that only feedback candidates,
+adapter artifacts or stream artifact entries cite, and a PNG an actor trace
+references outside `screenshots/`. An adapter artifact larger than 32 MiB grades
+the run `local_only` when nothing cites it, and `blocked` when the bundle cites
+it as evidence, because the evidence check cannot read it. An unregistered
 `.mp4`, and a file or directory whose name contains `\`, are public-safety
 findings and block the run.