humanish 0.107.0 → 0.108.0

package/dist/substrates/e2b/cdp-probe.js

@@ -1,22 +1,19 @@
 // The in-sandbox Chrome DevTools probe behind every URL / page-text / viewport observation.
 //
-// It runs on python3, stdlib only. It used to run on node, and that was the #514 root cause: the
-// stock E2B desktop template ships python3 and curl but NO Node, and Node only arrives when a
-// subject's serve pipeline needs it (src/subject/runtime.ts). So on the app-url route, and on any
-// subject served by something other than Node (the taskly benchmark is `python3 -m http.server`),
-// `node -e` exited 127 on every turn, the probe degraded to `{}`, and every urlIncludes /
-// textIncludes stop condition and task criterion went blind for the whole session. The only trace
-// was a geometry warning that the CSS viewport "could not be measured", which named the symptom
-// and not the cause. The tab-pinning fix that preceded this one (prefer "active") was diagnosed on
-// a Node subject, where the probe happened to work.
+// It runs on python3, stdlib only. The stock E2B desktop template ships python3 and curl but no
+// Node, and Node only arrives when a subject's serve pipeline needs it (src/subject/runtime.ts).
+// So on the app-url route, and on any subject served by something other than Node (the taskly
+// benchmark is `python3 -m http.server`), a `node -e` probe exits 127 on every turn, degrades to
+// `{}`, and blinds every urlIncludes / textIncludes stop condition and task criterion for the
+// whole session, with only a geometry warning that the CSS viewport "could not be measured".
 //
 // The same lesson was learned once already: the comms catch was rewritten from node to python3 in
 // 0.29.0 (comms/sandbox-catch.ts). This is the third in-sandbox runtime dependency to move.
 //
-// The script takes ONE JSON argument and prints ONE JSON line. Failures print
-// `{"unavailable": "<reason>"}` with exit 0 so the caller can say WHY the channel is dark instead
+// The script takes one JSON argument and prints one JSON line. Failures print
+// `{"unavailable": "<reason>"}` with exit 0 so the caller can say why the channel is dark instead
 // of swallowing an exit code; the TypeScript side turns that into a participant warning that names the
-// consequence ("url/text criteria will read as NEVER MEASURED").
+// consequence ("url/text criteria will read as never measured").
 import { shellQuote } from "../shell.js";
 /**
  * The probe itself. Kept as one string so the shipped command is exactly what the tests execute
@@ -24,9 +21,9 @@ import { shellQuote } from "../shell.js";
  * headless Chrome).
  *
  * WebSocket is hand-rolled because python's stdlib has no client: one masked text frame out, frames
- * in until the reply with id 1 arrives, 1.5 s budget, and NO Origin header (Chrome refuses
+ * in until the reply with id 1 arrives, 1.5 s budget, and no Origin header (Chrome refuses
  * cross-origin DevTools sockets unless --remote-allow-origins is set; a header-less client is a
- * local one). urllib is opened WITHOUT proxy handlers so a sandbox-wide http_proxy cannot redirect
+ * local one). urllib is opened without proxy handlers so a sandbox-wide http_proxy cannot redirect
  * a loopback read.
  */
 export const CHROME_CDP_PROBE_PY = String.raw `
@@ -277,7 +274,7 @@ def browser_ws_url(port):
 
 def hold(port, page, request):
     """Emulate the launch page and then every page target Chrome opens later, for as long as this
-    process lives (#221, #623). One browser-level socket with flattened sessions: the launch page is
+    process lives. One browser-level socket with flattened sessions: the launch page is
     attached by id and reloaded so scripts that read the UA at load see it; a target that appears
     later is attached the moment it exists, sent the same overrides, and reloaded once after its
     first real navigation commits (touch emulation reaches a document only when it loads under it).
@@ -387,7 +384,7 @@ def main():
     page = select_page(pages, args)
     # A listing with targets but no http page is usually an instant: a reload in flight, a tab
     # between about:blank and its navigation. Ask again for up to a second before calling it
-    # unavailable (#653): the lane's observer would otherwise lose one turn of url/text evidence,
+    # unavailable: the lane's observer would otherwise lose one turn of url/text evidence,
     # and a test on a loaded runner saw exactly this twice in one evening.
     for _ in range(4):
         if page is not None or not pages:
@@ -465,7 +462,7 @@ export function chromeCdpProbeCommand(args) {
 /**
  * Narrow one probe's stdout. A parse failure is reported as unavailable with the reason, never as
  * an empty success: the difference between "nothing to observe" and "could not observe" is the
- * whole point of #514.
+ * whole point.
  */
 export function parseChromeCdpProbeOutput(stdout) {
     const trimmed = (stdout ?? "").trim();

package/dist/substrates/e2b/desktop-browser.d.ts

@@ -29,7 +29,7 @@ export declare function parseChromeDevToolsReadiness(stdout: string): ChromeDevT
 export interface DesktopBrowserEvidence {
     requested: LabDesktopBrowser;
     resolved?: string;
-    /** Synthetic media devices the browser was launched with (#509), and how permission is answered. */
+    /** Synthetic media devices the browser was launched with, and how permission is answered. */
     media?: DesktopMediaEvidence;
 }
 export type DesktopBrowserFamily = "chromium" | "firefox" | "unknown";
@@ -66,7 +66,7 @@ export declare function buildFillDesktopWindowCommand(windowId: string, width: n
  */
 export declare function fillDesktopBrowserWindow(desktop: E2BDesktopSandbox, windowId: string, resolution: readonly [number, number], requestTimeoutMs: number): Promise<void>;
 export declare function openDesktopBrowserTarget(desktop: E2BDesktopSandbox, targetUrl: string, requestTimeoutMs: number, browserPreference: LabDesktopBrowser | undefined, 
-/** Launch-time flags that make mobile fidelity (#221) hold across every tab: the user agent and
+/** Launch-time flags that make mobile fidelity hold across every tab: the user agent and
  *  touch events are browser-wide here, where the CDP holder covers only the launch page. */
 extraChromiumFlags?: readonly string[], environment?: Readonly<Record<string, string>>): Promise<DesktopBrowserLaunchResult>;
 /**

package/dist/substrates/e2b/desktop-browser.js

@@ -111,7 +111,7 @@ export function parseChromeDevToolsReadiness(stdout) {
 export async function findVisibleBrowserWindowId(desktop, requestTimeoutMs, browserFamily, launchIdentity) {
     if (browserFamily === "unknown")
         return undefined;
-    // The candidate loop keeps the LAST identity match: with a launch identity the match is
+    // The candidate loop keeps the last identity match: with a launch identity the match is
     // unique anyway, and without one every family candidate matches, so the newest visible
     // window of the launched family wins (the window this participant just opened).
     const finder = browserFamily === "firefox"
@@ -197,7 +197,7 @@ export async function fillDesktopBrowserWindow(desktop, windowId, resolution, re
         .catch(() => undefined);
 }
 export async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, browserPreference, 
-/** Launch-time flags that make mobile fidelity (#221) hold across every tab: the user agent and
+/** Launch-time flags that make mobile fidelity hold across every tab: the user agent and
  *  touch events are browser-wide here, where the CDP holder covers only the launch page. */
 extraChromiumFlags = [], environment) {
     const requestedBrowser = browserPreference ?? "default";
@@ -242,10 +242,10 @@ extraChromiumFlags = [], environment) {
             "  fi",
             "  return 1",
             "}",
-            // Fixed CDP port (not :0/random): each seat has its OWN desktop sandbox, so a known port
-            // cannot conflict, and it makes the observer's port resolution deterministic. With :0 the
-            // real port lives only in DevToolsActivePort; when the launch-time capture misses on a cold
-            // start the observer falls back to 9222 and — being wrong — every CDP read fails for the
+            // Fixed CDP port (not :0/random): each participant has its own desktop sandbox, so a known
+            // port cannot conflict, and it makes the observer's port resolution deterministic. With :0
+            // the real port lives only in DevToolsActivePort; when the launch-time capture misses on a
+            // cold start the observer falls back to 9222 and, being wrong, every CDP read fails for the
             // whole run (the lobby-code handoff then never sees the host's /lobby URL). 9222 is already
             // the fallback, so making it the actual port aligns launch, capture, and fallback.
             `chrome_debug_flags=(--remote-debugging-address=127.0.0.1 --remote-debugging-port=${CHROME_DEVTOOLS_PORT} ${chromiumFlags})`,
@@ -375,9 +375,9 @@ export async function openDesktopTerminal(desktop, requestTimeoutMs, workdir) {
         command: [
             "for candidate in x-terminal-emulator xfce4-terminal gnome-terminal konsole xterm; do",
             '  if command -v "$candidate" >/dev/null 2>&1; then',
-            // LANG is set on the terminal we open, not globally: the stock image declares no locale, and
+            // `LANG` is set on the terminal we open, not globally: the stock image declares no locale, and
             // a study that measures our own mojibake against an unconfigured template would be measuring
-            // the template. The PRODUCT-side fix (an ASCII fallback when the locale is not UTF-8) is in
+            // the template. The product-side fix (an ASCII fallback when the locale is not UTF-8) is in
             // src/routes/terminal/encoding.ts, and it is the one that matters for real users.
             `    (cd ${shellQuote(dir)} 2>/dev/null || cd /home/user; DISPLAY=:0 LANG=C.UTF-8 LC_ALL=C.UTF-8 HUMANISH_STUDY_PARTICIPANT=1 nohup "$candidate" >/dev/null 2>&1 &)`,
             "    sleep 3",

package/dist/substrates/e2b/desktop-cdp.d.ts

@@ -3,7 +3,7 @@ import type { RunDesktopGeometry } from "../../run/streams.js";
 import type { E2BDesktopSandbox } from "./sdk.js";
 /**
  * Runtime-only CDP endpoint attribution for the exact chromium this participant launched. Port
- * resolution at OBSERVE time: the cached launch-time `cdpPort` wins; absent that, the observer
+ * resolution at observe time: the cached launch-time `cdpPort` wins; absent that, the observer
  * probe re-reads `profileDir`'s DevToolsActivePort marker (a slow cold start can publish it
  * after the launch-time poll gave up); absent both it uses 9222, the port every participant launches
  * Chrome with, where a dead endpoint degrades into a warning that names the cause.
@@ -16,7 +16,7 @@ export interface ChromeCdpEndpoint {
     targetUrl: string;
 }
 /**
- * Mobile emulation on later tabs (#623): the holder attaches to every page target Chrome opens
+ * Mobile emulation on later tabs: the holder attaches to every page target Chrome opens
  * after the launch page, so a tab the participant opens later should lay out at the phone width
  * too. The first observation on each new target reads that page's own report; a target that
  * reports the requested width is recorded through `onCovered`, and one that does not (or cannot be
@@ -37,15 +37,15 @@ export interface ChromeEmulationDrift {
 /**
  * The URL / title / page-text / scroll observer behind stopWhen and task criteria. One probe per
  * observation, run on the sandbox's python3 (see src/substrates/e2b/cdp-probe.ts for why not
- * node: #514).
+ * node).
  *
- * "active": follow the participant to whatever tab they are driving now — never pin the state
- * observer to the launch tab (a verification link that opened in a NEW tab left a pinned observer
+ * "active": follow the participant to whatever tab they are driving now; never pin the state
+ * observer to the launch tab (a verification link that opened in a new tab left a pinned observer
  * reading the old tab forever).
  *
- * `onUnavailable` fires ONCE, on the first probe that could not read the page, with the reason.
+ * `onUnavailable` fires once, on the first probe that could not read the page, with the reason.
  * The observer still degrades to `{}` for the loop; the callback is how a participant says out loud that
- * url/text criteria are not being measured, instead of letting the funnel report 0/N (#514).
+ * url/text criteria are not being measured, instead of letting the funnel report 0/N.
  */
 export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbox, requestTimeoutMs: number, endpoint: ChromeCdpEndpoint, options?: {
     /** The page target to prefer before the participant switches tabs. */
@@ -62,8 +62,8 @@ export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbo
 /** The user agent a mobile-emulated participant presents unless the lab sets its own. */
 export declare const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
 /**
- * Apply mobile emulation (#221) to the participant's launch page and read back what the page reports.
- * Fails CLOSED: a request that cannot be applied throws, because a desktop run labelled mobile is
+ * Apply mobile emulation to the participant's launch page and read back what the page reports.
+ * Fails closed: a request that cannot be applied throws, because a desktop run labelled mobile is
  * the over-trust this feature exists to prevent. A read-back that cannot be taken is a warning
  * (the emulation was applied; only the proof is missing).
  */

package/dist/substrates/e2b/desktop-cdp.js

@@ -7,15 +7,15 @@ import { e2bShell } from "./shell.js";
 /**
  * The URL / title / page-text / scroll observer behind stopWhen and task criteria. One probe per
  * observation, run on the sandbox's python3 (see src/substrates/e2b/cdp-probe.ts for why not
- * node: #514).
+ * node).
  *
- * "active": follow the participant to whatever tab they are driving now — never pin the state
- * observer to the launch tab (a verification link that opened in a NEW tab left a pinned observer
+ * "active": follow the participant to whatever tab they are driving now; never pin the state
+ * observer to the launch tab (a verification link that opened in a new tab left a pinned observer
  * reading the old tab forever).
  *
- * `onUnavailable` fires ONCE, on the first probe that could not read the page, with the reason.
+ * `onUnavailable` fires once, on the first probe that could not read the page, with the reason.
  * The observer still degrades to `{}` for the loop; the callback is how a participant says out loud that
- * url/text criteria are not being measured, instead of letting the funnel report 0/N (#514).
+ * url/text criteria are not being measured, instead of letting the funnel report 0/N.
  */
 export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, options = {}) {
     const { targetId, onUnavailable, drift } = options;
@@ -100,8 +100,8 @@ export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoi
 /** The user agent a mobile-emulated participant presents unless the lab sets its own. */
 export const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
 /**
- * Apply mobile emulation (#221) to the participant's launch page and read back what the page reports.
- * Fails CLOSED: a request that cannot be applied throws, because a desktop run labelled mobile is
+ * Apply mobile emulation to the participant's launch page and read back what the page reports.
+ * Fails closed: a request that cannot be applied throws, because a desktop run labelled mobile is
  * the over-trust this feature exists to prevent. A read-back that cannot be taken is a warning
  * (the emulation was applied; only the proof is missing).
  */
@@ -153,7 +153,7 @@ export async function applyMobileEmulation(desktop, requestTimeoutMs, endpoint,
     }
     const applied = announced;
     // Viewport/touch read-back proves context settings, not gesture equivalence. Two hosted
-    // replicas and a native-X conversion-toggle control reproduced reset click counts (#676).
+    // replicas and a native-X conversion-toggle control reproduced reset click counts.
     const warnings = request.touch
         ? [
             "Mobile emulation uses desktop pointer-to-touch conversion, which can differ for repeated taps. Confirm gesture failures with direct or native touch input before attributing them to the app.",

package/dist/substrates/e2b/desktop-executor.d.ts

@@ -17,7 +17,7 @@ export interface E2BDesktopLike {
             stdout?: string;
         }>;
     };
-    /** Optional file surface used to transfer typed text without shell-quoting it. */
+    /** Optional file surface for transferring typed text without shell-quoting it. */
     files?: {
         write(path: string, data: string | ArrayBuffer, options?: {
             requestTimeoutMs?: number;

package/dist/substrates/e2b/desktop-executor.js

@@ -9,7 +9,7 @@ const TYPE_COMMAND_TIMEOUT_MS = 15_000;
 const HELD_KEYS_TIMEOUT_MS = 15_000;
 const CURSOR_READ_TIMEOUT_MS = 500;
 /**
- * The stock image's xdotool waits ~15s on a synchronized move to its current position (#681).
+ * The stock image's xdotool waits ~15s on a synchronized move to its current position.
  * Only an exact integer match can omit that move; fractional actions keep the SDK's own
  * coordinate conversion. Read every time: another action or sequential role may move it.
  * The SDK's getCursorPosition (2.3 through 2.4.0) takes no timeout or signal. Bound our wait, observe late

package/dist/substrates/e2b/desktop-geometry.d.ts

@@ -5,10 +5,10 @@ import { type DesktopBrowserFamily, type DesktopBrowserLaunchIdentity } from "./
 import type { ChromeCdpEndpoint } from "./desktop-cdp.js";
 import type { E2BDesktopSandbox } from "./sdk.js";
 /**
- * The DECLARED preset to record alongside the rendered screen, or undefined when the preset
+ * The declared preset to record alongside the rendered screen, or undefined when the preset
  * rendered faithfully.
  *
- * `desktopGeometry.screen.verified` compares the FLOORED number with itself, so on its own a
+ * `desktopGeometry.screen.verified` compares the floored number with itself, so on its own a
  * floored run is indistinguishable from a faithful one: a reader sees requested 500 / verified 500
  * and concludes a 500-wide screen was asked for. Recording the declared preset is what makes
  * "the preset width did not render" legible in the bundle.
@@ -19,7 +19,7 @@ export declare function declaredScreenForRender(preset: DevicePreset, presetName
     preset: string;
 } | undefined;
 /**
- * Verify the desktop screen geometry IN-SANDBOX (the participant's device claim is checked, never
+ * Verify the desktop screen geometry in-sandbox (the participant's device claim is checked, never
  * assumed). A parseable mismatch fails closed. Unavailable/unparseable evidence is returned as
  * an explicit warning: the participant may still run, but its bundle records only the requested screen
  * and never upgrades that request into a verified measurement.

package/dist/substrates/e2b/desktop-geometry.js

@@ -8,10 +8,10 @@ import { shellQuote } from "../shell.js";
 import { e2bShell } from "./shell.js";
 import { findVisibleBrowserWindowId, fillDesktopBrowserWindow, } from "./desktop-browser.js";
 /**
- * The DECLARED preset to record alongside the rendered screen, or undefined when the preset
+ * The declared preset to record alongside the rendered screen, or undefined when the preset
  * rendered faithfully.
  *
- * `desktopGeometry.screen.verified` compares the FLOORED number with itself, so on its own a
+ * `desktopGeometry.screen.verified` compares the floored number with itself, so on its own a
  * floored run is indistinguishable from a faithful one: a reader sees requested 500 / verified 500
  * and concludes a 500-wide screen was asked for. Recording the declared preset is what makes
  * "the preset width did not render" legible in the bundle.
@@ -22,7 +22,7 @@ export function declaredScreenForRender(preset, presetName, rendered) {
     return { width: preset.width, height: preset.height, preset: presetName };
 }
 /**
- * Verify the desktop screen geometry IN-SANDBOX (the participant's device claim is checked, never
+ * Verify the desktop screen geometry in-sandbox (the participant's device claim is checked, never
  * assumed). A parseable mismatch fails closed. Unavailable/unparseable evidence is returned as
  * an explicit warning: the participant may still run, but its bundle records only the requested screen
  * and never upgrades that request into a verified measurement.
@@ -52,7 +52,7 @@ export async function inspectDesktopScreenGeometry(args) {
     }
     return {
         verified: { width, height, source: "xdpyinfo" },
-        error: `HUMANISH_CUA_LAB_DEVICE_GEOMETRY: participant ${args.participantId} requested a ${expectedWidth}x${expectedHeight} desktop but xdpyinfo reports ${width}x${height} in-sandbox; the participant's device geometry is unverified (fail-closed).`,
+        error: `HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY: participant ${args.participantId} requested a ${expectedWidth}x${expectedHeight} desktop but xdpyinfo reports ${width}x${height} in the sandbox. The participant stops, because its screen does not match the device it declared.`,
     };
 }
 /**
@@ -298,8 +298,8 @@ export async function captureDesktopBrowserGeometry(args) {
         : undefined;
     const browserWindow = physicalWindow ?? chromeGeometry?.browserWindow;
     const viewport = chromeGeometry?.viewport;
-    // The fill check reads the X window when it was measured: under mobile emulation (#221) the
-    // page's window.outerWidth reports the EMULATED screen (414), which is not a fill failure.
+    // The fill check reads the X window when it was measured: under mobile emulation the
+    // page's window.outerWidth reports the emulated screen (414), which is not a fill failure.
     const fillBounds = physicalWindow;
     if (!browserWindow) {
         warnings.push(`Browser outer bounds could not be measured for participant ${args.participantId}.`);
@@ -314,7 +314,7 @@ export async function captureDesktopBrowserGeometry(args) {
     }
     if (!viewport) {
         // Name the cause, not only the symptom: the same dead DevTools channel that loses the viewport
-        // loses every url/text observation, and a reader of the bundle should learn that here (#514).
+        // loses every url/text observation, and a reader of the bundle should learn that here.
         const cause = cdpUnavailable === undefined ? "" : ` DevTools probe: ${redactText(cdpUnavailable)}.`;
         warnings.push(args.browserFamily === "firefox"
             ? `Browser CSS viewport measurement is unavailable in Firefox for participant ${args.participantId}; stream.viewport is omitted instead of reading a different browser's CDP endpoint.`

package/dist/substrates/e2b/desktop-media.d.ts

@@ -22,7 +22,7 @@ export interface DesktopMediaEvidence {
 }
 /**
  * Put the declared camera feed in the sandbox and return the Chromium flags that present it as a
- * capture device (#509). Fails CLOSED: a feed that cannot be produced (no ffmpeg on the image, an
+ * capture device. Fails closed: a feed that cannot be produced (no ffmpeg on the image, an
  * unreadable host file) is named before the browser launches, because a participant told it has
  * a camera and finds none reports the instrument's gap as the product's.
  */

package/dist/substrates/e2b/desktop-media.js

@@ -91,7 +91,7 @@ const SANDBOX_CAMERA_PATH = `${SANDBOX_MEDIA_DIR}/camera.y4m`;
 const SYNTHETIC_CAMERA_COMMAND = `mkdir -p ${SANDBOX_MEDIA_DIR} && ffmpeg -y -loglevel error -f lavfi -i testsrc=size=640x480:rate=10 -t 6 -pix_fmt yuv420p ${SANDBOX_CAMERA_PATH}`;
 /**
  * Put the declared camera feed in the sandbox and return the Chromium flags that present it as a
- * capture device (#509). Fails CLOSED: a feed that cannot be produced (no ffmpeg on the image, an
+ * capture device. Fails closed: a feed that cannot be produced (no ffmpeg on the image, an
  * unreadable host file) is named before the browser launches, because a participant told it has
  * a camera and finds none reports the instrument's gap as the product's.
  */

package/dist/substrates/e2b/desktop-screenshot-cleanup.d.ts

@@ -4,12 +4,12 @@ export declare function desktopScreenshotCleanupFailures(desktop: object): numbe
 /**
  * @e2b/desktop 2.3.3 screenshot() awaits capture and files.read(path), then discards the
  * files.remove(path) promise. A removal that races sandbox teardown can therefore crash Node
- * AFTER valid bytes were returned. Installed-SDK conformance tests pin that behavior (#662).
+ * after valid bytes were returned. Installed-SDK conformance tests pin that behavior.
  *
- * Observe only removal of a file successfully read within THIS screenshot invocation. The
+ * Observe only removal of a file successfully read within this screenshot invocation. The
  * exact path comes from the SDK, not a guessed filename pattern. AsyncLocalStorage isolates
  * concurrent screenshots and unrelated file operations without changing SDK method receivers.
- * The ORIGINAL removal promise is returned: an SDK version (or caller) that awaits it still
+ * The original removal promise is returned: an SDK version (or caller) that awaits it still
  * receives the original rejection. No process-wide rejection handler or filesystem retry.
  */
 export declare function protectDesktopScreenshotCleanup<T extends E2BDesktopSandbox>(desktop: T): T;

package/dist/substrates/e2b/desktop-screenshot-cleanup.js

@@ -11,12 +11,12 @@ export function desktopScreenshotCleanupFailures(desktop) {
 /**
  * @e2b/desktop 2.3.3 screenshot() awaits capture and files.read(path), then discards the
  * files.remove(path) promise. A removal that races sandbox teardown can therefore crash Node
- * AFTER valid bytes were returned. Installed-SDK conformance tests pin that behavior (#662).
+ * after valid bytes were returned. Installed-SDK conformance tests pin that behavior.
  *
- * Observe only removal of a file successfully read within THIS screenshot invocation. The
+ * Observe only removal of a file successfully read within this screenshot invocation. The
  * exact path comes from the SDK, not a guessed filename pattern. AsyncLocalStorage isolates
  * concurrent screenshots and unrelated file operations without changing SDK method receivers.
- * The ORIGINAL removal promise is returned: an SDK version (or caller) that awaits it still
+ * The original removal promise is returned: an SDK version (or caller) that awaits it still
  * receives the original rejection. No process-wide rejection handler or filesystem retry.
  */
 export function protectDesktopScreenshotCleanup(desktop) {

package/dist/substrates/e2b/sandbox.d.ts

@@ -89,7 +89,7 @@ export declare const TRANSIENT_RETRY_DELAY_MS = 3000;
  *   describing, the same routing gap seen from the upload side.
  * - transport resets (`fetch failed`, `ECONNRESET`, `socket hang up`, 502/503/504).
  *
- * NOT retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
+ * Not retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
  * that hit the limit should be spaced, not repeated), and anything that names the request as wrong.
  */
 export declare function isTransientE2BError(error: unknown): boolean;

package/dist/substrates/e2b/sandbox.js

@@ -181,7 +181,7 @@ export const TRANSIENT_RETRY_DELAY_MS = 3_000;
  *   describing, the same routing gap seen from the upload side.
  * - transport resets (`fetch failed`, `ECONNRESET`, `socket hang up`, 502/503/504).
  *
- * NOT retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
+ * Not retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
  * that hit the limit should be spaced, not repeated), and anything that names the request as wrong.
  */
 export function isTransientE2BError(error) {

package/dist/substrates/e2b/sdk.d.ts

@@ -3,7 +3,7 @@ export interface E2BDesktopModule {
         /** The stock `desktop` template (no custom image). */
         create(options: E2BDesktopCreateOptions): Promise<E2BDesktopSandbox>;
         /**
-         * Launch on a CUSTOM E2B desktop template (image) by NAME or ID — the SDK's
+         * Launch on a custom E2B desktop template (image) by name or ID: the SDK's
          * `Sandbox.create(template, opts)` overload. Lets a lab run on an adopter-maintained image
          * with extra runtimes baked in (e.g. node/bun/a local Postgres the stock `desktop` template
          * lacks), instead of the stock template. The base @e2b/desktop SDK implements this; the
@@ -11,17 +11,17 @@ export interface E2BDesktopModule {
          */
         create(template: string, options: E2BDesktopCreateOptions): Promise<E2BDesktopSandbox>;
         /**
-         * Kill the sandbox specified by exact id. Returns true iff THAT sandbox was found and
-         * killed, false otherwise (the SDK's own doc comment). This boolean is the PRIMARY by-id
+         * Kill the sandbox specified by exact id. Returns true iff that sandbox was found and
+         * killed, false otherwise (the SDK's own doc comment). This boolean is the primary by-id
          * cleanup proof: a caller never needs to re-list to confirm reclamation.
          */
         kill?(sandboxId: string, options?: {
             requestTimeoutMs?: number;
         }): Promise<boolean>;
         /**
-         * Fetch ONE sandbox by its exact id (never account-wide). Throws a SandboxNotFoundError-
+         * Fetch one sandbox by its exact id (never account-wide). Throws a SandboxNotFoundError-
          * shaped error (see isSandboxNotFoundError below) when the id no longer exists; that thrown
-         * error IS the by-id confirmation that a killed sandbox is gone. Optional: older SDKs may
+         * error is the by-id confirmation that a killed sandbox is gone. Optional: older SDKs may
          * lack it, so callers fall back to kill()'s own boolean rather than ever calling Sandbox.list.
          */
         getInfo?(sandboxId: string, options?: {
@@ -123,10 +123,10 @@ export interface E2BDesktopSandbox {
     /** Open a file or URL with the desktop's default application (present on @e2b/desktop >= 1.x). */
     open?(fileOrUrl: string): Promise<void>;
     /**
-     * Map an in-sandbox port to a reachable host URL — `https://<port>-<sandboxId>.e2b.app`,
-     * TOKENLESS (no authKey, unlike `stream.getUrl`). The base `e2b` SDK (v2.27.0) implements this;
-     * the wrapper just exposes it. Used by the CONCURRENT shared-world topology (#164 phase 2) to
-     * expose the ONE subject service plane to N actor sandboxes. Optional: older SDKs may lack it, so
+     * Map an in-sandbox port to a reachable host URL, `https://<port>-<sandboxId>.e2b.app`,
+     * tokenless (no authKey, unlike `stream.getUrl`). The base `e2b` SDK (v2.27.0) implements this;
+     * the wrapper just exposes it. Used by the concurrent shared-world topology to
+     * expose the one subject service plane to N actor sandboxes. Optional: older SDKs may lack it, so
      * the concurrent backend fails closed when it is absent rather than calling a missing method.
      */
     getHost?(port: number): string;
@@ -169,7 +169,7 @@ export declare class E2BDesktopStartupError extends Error {
     constructor(error: unknown, cleanup: DesktopCreateCleanup, cleanupDetail?: string | undefined);
 }
 /**
- * Preserve ownership before the desktop SDK starts Xvfb/XFCE (#581). Its public generic create
+ * Preserve ownership before the desktop SDK starts Xvfb/XFCE. Its public generic create
  * constructs `new this(...)` through the base SDK, then awaits desktop startup. Newer SDKs
  * attempt their own kill before rejecting create; older SDKs leave cleanup to the caller.
  * Both paths share one bounded cleanup result so an internal kill cannot delay our deadline
@@ -183,7 +183,7 @@ export declare class E2BDesktopStartupError extends Error {
  */
 export declare function guardDesktopSandboxCreate(module: E2BDesktopModule): E2BDesktopModule;
 /**
- * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, WITHOUT importing
+ * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, without importing
  * its class (this module stays optional-peer / lazily-loaded, same as everything else here).
  * The real SDK sets `this.name = "SandboxNotFoundError"` on the class (it extends the
  * deprecated NotFoundError), so checking `.name` is the stable, import-free detection contract.

package/dist/substrates/e2b/sdk.js

@@ -18,8 +18,8 @@ export async function loadE2BDesktopModule() {
                 ? "Live E2B desktop launch requires the optional peer @e2b/desktop. Install it beside humanish " +
                     "in this project: `npm i -D @e2b/desktop`."
                 : "Live E2B desktop launch requires the optional peer @e2b/desktop, and humanish is running from an " +
-                    "npx cache rather than from this project — so installing the peer here cannot help, because Node " +
-                    "resolves it relative to humanish itself. Install BOTH into the project and run it from there: " +
+                    "npx cache. Node resolves the peer relative to humanish itself, so a copy installed in this project " +
+                    "is not found. Install both into the project and run it from there: " +
                     "`npm i -D humanish @e2b/desktop` then `npx humanish run <lab>`.");
         }
         throw error;
@@ -44,7 +44,7 @@ export class E2BDesktopStartupError extends Error {
     }
 }
 /**
- * Preserve ownership before the desktop SDK starts Xvfb/XFCE (#581). Its public generic create
+ * Preserve ownership before the desktop SDK starts Xvfb/XFCE. Its public generic create
  * constructs `new this(...)` through the base SDK, then awaits desktop startup. Newer SDKs
  * attempt their own kill before rejecting create; older SDKs leave cleanup to the caller.
  * Both paths share one bounded cleanup result so an internal kill cannot delay our deadline
@@ -147,8 +147,8 @@ async function reclaimFailedDesktopCreate(kill, timeoutMs) {
 /**
  * Is humanish running from this project's node_modules, or from an npx cache?
  *
- * It decides which advice is TRUE. `npx humanish@latest` resolves its optional peer relative to
- * ITSELF, so "install @e2b/desktop in this project" is advice that cannot work there — and that
+ * It decides which advice is true. `npx humanish@latest` resolves its optional peer relative to
+ * itself, so "install @e2b/desktop in this project" is advice that cannot work there, and that
  * message cost two cold verification runs before the difference was noticed. A one-shot npx
  * invocation cannot do a live desktop run at all; humanish has to be installed alongside the peer.
  */
@@ -161,7 +161,7 @@ function isMissingE2BDesktopDependency(error) {
     return value.code === "ERR_MODULE_NOT_FOUND" && value.message?.includes("@e2b/desktop") === true;
 }
 /**
- * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, WITHOUT importing
+ * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, without importing
  * its class (this module stays optional-peer / lazily-loaded, same as everything else here).
  * The real SDK sets `this.name = "SandboxNotFoundError"` on the class (it extends the
  * deprecated NotFoundError), so checking `.name` is the stable, import-free detection contract.

package/dist/tui/actions.d.ts

@@ -25,7 +25,7 @@ export declare function createTuiObserverSession(cwdInput: string, options?: {
  * The counterpart to starting one: a study that is going nowhere costs money every turn, and until
  * now the only way to end it was to find the pid yourself.
  *
- * It signals the PROCESS GROUP, not the process. A run is spawned detached — its own group — and it
+ * It signals the process group, not the process. A run is spawned detached, in its own group, and it
  * has children: the CLI, and whatever it spawned to reach the sandbox. Signalling only the parent
  * leaves those orphaned and still working.
  *

package/dist/tui/actions.js

@@ -1,9 +1,9 @@
 import { requestAutomaticAnalysisCancellation } from "../analysis/automatic.js";
-// The two things a run card can DO (#455 rev 8).
+// The two things a run card can do.
 //
-// The mock's run screen is an outcome CARD with actions, not a field list, and an action that does
-// nothing is worse than no action — so this ships the two that are genuinely implementable today
-// and nothing else. `Share…` waits for the export contract (#471) rather than appearing as a
+// The mock's run screen is an outcome card with actions, not a field list, and an action that does
+// nothing is worse than no action, so this ships the two that are genuinely implementable today
+// and nothing else. `Share…` waits for the export contract rather than appearing as a
 // control that fails.
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -32,7 +32,7 @@ export function createTuiObserverSession(cwdInput, options = {}) {
     return {
         async open(targetCwd, observerPath) {
             if (closed)
-                return result(false, "this terminal session has closed — reopen humanish tui to view the run");
+                return result(false, "this terminal session has closed; reopen `humanish tui` to view the run");
             if (path.resolve(targetCwd) !== cwd)
                 return result(false, "Observer can only open runs from this terminal session's project");
             // The capability takes the run-card path, not an arbitrary file, URL, or second project.
@@ -58,7 +58,7 @@ export function createTuiObserverSession(cwdInput, options = {}) {
                 return result(false, "this run's evidence directory is missing or unsafe to open");
             }
             if (closed)
-                return result(false, "this terminal session has closed — reopen humanish tui to view the run");
+                return result(false, "this terminal session has closed; reopen `humanish tui` to view the run");
             try {
                 // Share the pending start too: two quick selections must not create two listeners.
                 serverPromise ??= serveObserverLibrary(cwd, {
@@ -78,13 +78,13 @@ export function createTuiObserverSession(cwdInput, options = {}) {
                 });
                 const server = await serverPromise;
                 if (closed)
-                    return result(false, "this terminal session has closed — reopen humanish tui to view the run");
+                    return result(false, "this terminal session has closed; reopen `humanish tui` to view the run");
                 const url = new URL(`_humanish/runs/${encodeURIComponent(runId)}/observer/index.html`, server.url).href;
                 const opened = open(url);
-                return result(true, `${url} — follows saved captures; keep this TUI open.${opened.warning ? ` ${opened.warning}` : " If no browser appeared, open this URL on this machine or forward its port over SSH."}`);
+                return result(true, `${url} follows saved captures while you keep this TUI open.${opened.warning ? ` ${opened.warning}` : " If no browser appeared, open this URL on this machine or forward its port over SSH."}`);
             }
             catch {
-                return result(false, "Observer could not start — try humanish observe --run with this run's id in another terminal");
+                return result(false, "Observer could not start; run `humanish observe --run <run id>` in another terminal");
             }
         },
         close() {
@@ -104,7 +104,7 @@ export function createTuiObserverSession(cwdInput, options = {}) {
  * The counterpart to starting one: a study that is going nowhere costs money every turn, and until
  * now the only way to end it was to find the pid yourself.
  *
- * It signals the PROCESS GROUP, not the process. A run is spawned detached — its own group — and it
+ * It signals the process group, not the process. A run is spawned detached, in its own group, and it
  * has children: the CLI, and whatever it spawned to reach the sandbox. Signalling only the parent
  * leaves those orphaned and still working.
  *
@@ -144,7 +144,7 @@ export async function stopRun(cwd, runId, intent = "run") {
         return {
             schema: TUI_ACTION_SCHEMA,
             ok: false,
-            message: "this run has no status record, so there is no pid to stop — it predates the contract or never started",
+            message: "this run has no status record, so there is no pid to stop; it predates status records or never started",
         };
     }
     if (!isRunStatusRecord(record)) {
@@ -177,7 +177,7 @@ export async function stopRun(cwd, runId, intent = "run") {
         return { schema: TUI_ACTION_SCHEMA, ok: false, message: "this run recorded no usable pid" };
     }
     // Is it actually still there? A pid whose process is already gone means the run died without
-    // finalizing — nothing to stop, and the record will read as interrupted on its own.
+    // finalizing: nothing to stop, and the record will read as interrupted on its own.
     try {
         process.kill(pid, 0);
     }
@@ -185,7 +185,7 @@ export async function stopRun(cwd, runId, intent = "run") {
         return {
             schema: TUI_ACTION_SCHEMA,
             ok: false,
-            message: `nothing is running under pid ${pid} — it has already stopped, and its record will read as interrupted`,
+            message: `nothing is running under pid ${pid}; it has already stopped, and its record will read as interrupted`,
         };
     }
     try {