humanish 0.107.0 → 0.108.0

package/dist/study/owned-files.js

@@ -0,0 +1,182 @@
+// File operations for humanish migrate that never replace or delete a file the run did not create.
+// A new name is taken with an exclusive create or link(), which fail when the name is in use. A
+// file is removed by renaming it to a random name first and checking it there, so a file saved over
+// the name in the meantime keeps it.
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { isNodeError } from "../run/type-guards.js";
+export function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+// A source must be a single-link regular file. A file this run wrote may briefly have two links
+// while a move is committed, so `ours` relaxes that.
+export async function fileIdentity(absolutePath, ours = false) {
+    const stats = await lstat(absolutePath, { bigint: true });
+    if (!stats.isFile() || (!ours && stats.nlink !== 1n))
+        throw new Error("not a single-link regular file");
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        size: stats.size,
+        sha256: sha256(await readFile(absolutePath)),
+    };
+}
+export function sameFile(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.size === right.size &&
+        left.sha256 === right.sha256);
+}
+// Walk a directory below the project root one segment at a time, refusing a symbolic link or a
+// non-directory. `create` makes missing segments and records each one it made.
+export async function bindDirectory(root, relativeDir, created) {
+    let current = root;
+    for (const segment of relativeDir.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        let stats;
+        try {
+            stats = await lstat(current, { bigint: true });
+        }
+        catch (error) {
+            if (!(isNodeError(error) && error.code === "ENOENT") || created === undefined) {
+                if (isNodeError(error) && error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            }
+            await mkdir(current, { mode: 0o755 });
+            created.push(current);
+            stats = await lstat(current, { bigint: true });
+        }
+        if (stats.isSymbolicLink() || !stats.isDirectory())
+            throw new Error(`${path.relative(root, current)} is not a plain directory`);
+    }
+    const stats = await lstat(current, { bigint: true });
+    return { physicalPath: current, dev: stats.dev, ino: stats.ino };
+}
+export async function assertDirectory(directory, root) {
+    const again = await bindDirectory(root, path.relative(root, directory.physicalPath));
+    if (again === undefined || again.dev !== directory.dev || again.ino !== directory.ino)
+        throw new Error(`${path.relative(root, directory.physicalPath)} changed`);
+}
+export async function exists(absolutePath) {
+    try {
+        await lstat(absolutePath);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return false;
+        return true;
+    }
+}
+// Create a file exclusively and write it. Its inode is recorded the moment the create succeeds, so
+// a failed write is still known to be this run's and a taken name never is. The bytes are read back
+// through the same descriptor, so the identity recorded is this file's, whatever holds the name.
+export async function writeOwned(owned, bytes, mode) {
+    const data = Buffer.from(bytes);
+    const handle = await open(owned.path, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, mode);
+    try {
+        const opened = await handle.stat({ bigint: true });
+        owned.inode = { dev: opened.dev, ino: opened.ino };
+        await handle.writeFile(data);
+        await handle.sync();
+        const stats = await handle.stat({ bigint: true });
+        const back = Buffer.alloc(Number(stats.size));
+        await handle.read(back, 0, back.length, 0);
+        owned.identity = { dev: stats.dev, ino: stats.ino, size: stats.size, sha256: sha256(back) };
+    }
+    finally {
+        await handle.close();
+    }
+    if (owned.identity.sha256 !== sha256(data))
+        throw new Error(`${path.basename(owned.path)} did not read back as written`);
+}
+// Remove the file at `file` only if `matches` says it is the expected one. The name is first renamed
+// to a random one and the file checked there, so a file saved over the name in between is never
+// deleted: it gets its name back, or keeps the random one. Returns the path kept, or undefined once
+// the file is removed or was already gone.
+export async function removeChecked(file, matches, linkFile) {
+    const aside = `${file}.migrate-${randomUUID()}.del`;
+    try {
+        await rename(file, aside);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const current = await fileIdentity(aside, true).catch(() => undefined);
+    if (current !== undefined && matches(current)) {
+        await unlink(aside);
+        return undefined;
+    }
+    return (await restoreName(aside, file, linkFile)) ? file : aside;
+}
+// Remove a file this run created if it still holds this run's bytes, or was cut short while being
+// written. Returns the path kept, if any.
+export async function removeOwned(owned, linkFile) {
+    const inode = owned.inode;
+    if (inode === undefined)
+        return undefined;
+    return removeChecked(owned.path, (current) => current.dev === inode.dev &&
+        current.ino === inode.ino &&
+        (owned.identity === undefined || sameFile(current, owned.identity)), linkFile);
+}
+// Hard links need filesystem support. Without it a file is created exclusively and read back.
+export const NO_HARD_LINKS = new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "EXDEV"]);
+// Give the file at `from` the name `to` without replacing anything there: link() fails on a taken
+// name, and so does the exclusive create a filesystem without hard links gets instead. True once
+// `to` holds the file and `from` is gone. False when `to` was taken, or was replaced before `from`
+// could go, which leaves `from` as the file's only name.
+export async function restoreName(from, to, linkFile) {
+    let placed;
+    let copied;
+    let owned;
+    try {
+        await linkFile(from, to);
+        const stats = await lstat(from, { bigint: true });
+        placed = { dev: stats.dev, ino: stats.ino };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "EEXIST")
+            return false;
+        if (!(isNodeError(error) && NO_HARD_LINKS.has(error.code ?? "")))
+            throw error;
+        // Without hard links the file is copied. What was copied is recorded, so an edit made to
+        // `from` during the copy keeps `from`.
+        const stats = await lstat(from, { bigint: true });
+        // Only a regular file is copied; anything else keeps the name it has.
+        if (!stats.isFile())
+            return false;
+        const bytes = await readFile(from);
+        copied = { dev: stats.dev, ino: stats.ino, size: BigInt(bytes.length), sha256: sha256(bytes) };
+        const copy = { path: to };
+        try {
+            await writeOwned(copy, bytes, Number(stats.mode & 511n));
+        }
+        catch (copyError) {
+            if (copy.inode === undefined && isNodeError(copyError) && copyError.code === "EEXIST")
+                return false;
+            if (copy.inode !== undefined)
+                await removeOwned(copy, linkFile).catch(() => undefined);
+            throw copyError;
+        }
+        placed = copy.inode;
+        owned = copy;
+    }
+    const now = await lstat(to, { bigint: true }).catch(() => undefined);
+    if (now === undefined || now.dev !== placed.dev || now.ino !== placed.ino)
+        return false;
+    if (copied === undefined) {
+        await unlink(from);
+        return true;
+    }
+    const expected = copied;
+    if ((await removeChecked(from, (current) => sameFile(current, expected), linkFile)) === undefined)
+        return true;
+    // `from` changed during the copy: it stays, and the stale copy goes.
+    await removeOwned(owned, linkFile).catch(() => undefined);
+    return false;
+}

package/dist/subject/clone.d.ts

@@ -25,7 +25,7 @@ export declare function provisionCloneSubject(shell: Shell, args: {
     state?: LabSubjectState;
     hasGithubToken: boolean;
     requestTimeoutMs: number;
-    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    /** Literal scrubber for known provisioned values, applied to log tails pre-truncation. */
     scrub: (text: string) => string;
     /** Called the moment the cloned commit resolves, so provenance survives later failures. */
     onCommit?: (commit: string) => void;

package/dist/subject/desktop-cli.d.ts

@@ -1,7 +1,7 @@
 import type { Shell } from "../substrates/shell.js";
 import { type SubjectPhaseEvent } from "./steps.js";
 /**
- * Prepare a CLI study's runtime and, only when declared, its product (#495, #515).
+ * Prepare a CLI study's runtime and, only when declared, its product.
  *
  * The install runs unkeyed and before the session starts, for the same reason the clone route
  * provisions its subject first: what is being studied begins when the participant looks at the

package/dist/subject/desktop-cli.js

@@ -4,7 +4,7 @@ import { NODE_BOOTSTRAP_COMMAND, NODE_BOOTSTRAP_TIMEOUT_MS } from "./node-bootst
 import { runDetachedStep } from "../substrates/detached.js";
 import { emitPhaseCompleted, emitPhaseStarted, INSTALL_TIMEOUT_MS, } from "./steps.js";
 /**
- * Prepare a CLI study's runtime and, only when declared, its product (#495, #515).
+ * Prepare a CLI study's runtime and, only when declared, its product.
  *
  * The install runs unkeyed and before the session starts, for the same reason the clone route
  * provisions its subject first: what is being studied begins when the participant looks at the
@@ -44,7 +44,7 @@ export async function provisionDesktopCli(shell, args) {
     if (!result.ok) {
         // Fail closed: a participant handed a desktop where the product is not installed would produce
         // a transcript about a missing command, and that finding belongs to the harness, not the tool.
-        // The tail rides along, scrubbed before truncation like every other provisioning failure — a
+        // The tail rides along, scrubbed before truncation like every other provisioning failure. A
         // bare "install failed" is unactionable to whoever wrote the command.
         throw new Error(args.scrub(`desktop-cli install failed for "${args.product}" (${result.timedOut ? "timed out" : `exit ${result.exitCode ?? "?"}`}): ${failureTail(args.scrub(result.logTail))}`));
     }

package/dist/subject/local-tree-archive.js

@@ -8,7 +8,7 @@
 // that cannot happen: enumerateLocalTree() builds one entries array, and both
 // the hash and the tar file list are derived from that same array.
 //
-// See docs/goals/local-tree-subject/goal.md ("Packing design") for the full
+// See docs/history/goals/local-tree-subject/goal.md ("Packing design") for the full
 // contract implemented here. Node builtins only, no npm dependencies.
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";

package/dist/subject/local-tree.d.ts

@@ -18,7 +18,7 @@ export declare function provisionLocalTreeSubject(shell: Shell, args: {
     /** Declared subject state (seed steps; external declaration is provenance-only). */
     state?: LabSubjectState;
     requestTimeoutMs: number;
-    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    /** Literal scrubber for known provisioned values, applied to log tails pre-truncation. */
     scrub: (text: string) => string;
     /** Called the moment each state step finishes, success or failure. */
     onStateStep?: (record: RunSubjectStateStepRecord) => void;

package/dist/subject/node-bootstrap.js

@@ -54,7 +54,7 @@ export const NODE_BOOTSTRAP_COMMAND = [
     "for executable in node npm npx; do",
     `  sudo -n ln -sfn "$node_target/bin/$executable" "/usr/local/bin/$executable"`,
     "done",
-    // Keep global product executables on the existing ordinary/sudo `PATH` (#679). The new
+    // Keep global product executables on the existing ordinary/sudo `PATH`. The new
     // versioned distribution is the only config we modify; no user/global npmrc or profile.
     `sudo -n "$node_target/bin/node" -e '${NODE_NPM_PREFIX_SCRIPT}' "$node_target/lib/node_modules/npm/npmrc"`,
     "hash -r",

package/dist/subject/runtime.js

@@ -1,17 +1,16 @@
-// Provide the runtime a subject's serve pipeline needs, instead of failing at exit 127 (#371).
+// Provide the runtime a subject's serve pipeline needs, instead of failing at exit 127.
 //
-// The stock E2B `desktop` template ships python3 and curl but no Node. That fact has now been
-// rediscovered three times: the in-sandbox comms catch was rewritten from node to python3 in 0.29.0
-// for exactly this reason, the terminal route bootstraps Node explicitly, and the computer-use
-// clone/local-tree route did neither — so any lab whose `serve.install` runs npm or pnpm died with
-// `pnpm: command not found` after a sandbox had been created and paid for.
+// The stock E2B `desktop` template ships python3 and curl but no Node. So the in-sandbox comms
+// catch runs on python3, the terminal route bootstraps Node explicitly, and this module provides
+// Node for the computer-use clone/local-tree route. Without it, any study whose `serve.install`
+// runs npm or pnpm dies with `pnpm: command not found` after its sandbox is created and paid for.
 //
-// It failed invisibly up front: `lab inspect` was clean, the plan printed normally, the sandbox
-// provisioned, and the first signal was a shell exit code attributed to "subject install failed".
+// That failure is invisible up front: `lab inspect` is clean, the plan prints normally, the sandbox
+// provisions, and the first signal is a shell exit code attributed to "subject install failed".
 // Nobody can debug that from the outside.
 //
 // The harness provides the runtime instead of warning about it. An adopter writing a lab for a Node app should not have to
-// know which binaries the template happens to carry — that is the harness's job, and the terminal
+// know which binaries the template happens to carry. That is the harness's job, and the terminal
 // route already treats it that way. Detection is conservative and the bootstrap is skipped whenever
 // a runtime is already present, so a custom template that ships Node pays nothing.
 /** Package managers and runtimes whose absence on the stock template breaks a serve pipeline. */

package/dist/subject/serve.d.ts

@@ -25,7 +25,7 @@ export declare function runSubjectServePipeline(shell: Shell, args: {
     /** Declared subject state (seed steps; external declaration is provenance-only). */
     state?: LabSubjectState;
     requestTimeoutMs: number;
-    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    /** Literal scrubber for known provisioned values, applied to log tails pre-truncation. */
     scrub: (text: string) => string;
     /** Called the moment each state step finishes, success or failure. */
     onStateStep?: (record: RunSubjectStateStepRecord) => void;

package/dist/subject/serve.js

@@ -8,7 +8,7 @@ import { emitPhaseCompleted, emitPhaseStarted, INSTALL_TIMEOUT_MS, isoNow, SUBJE
 const BUILD_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_READY_TIMEOUT_MS = 180_000;
 /**
- * Run a provisioning step and, when it fails with an exit code, run it once more (#602): a
+ * Run a provisioning step and, when it fails with an exit code, run it once more: a
  * transient network error inside `npm install` is the common case. A timeout is not retried: its
  * budget is already spent, and a second wait would double it. The retry runs under its own step
  * name so both logs stay.
@@ -121,7 +121,7 @@ export async function runSubjectServePipeline(shell, args) {
     await refresh();
 }
 /**
- * Provide the runtime the pipeline needs before running it (#371). The stock desktop template
+ * Provide the runtime the pipeline needs before running it. The stock desktop template
  * ships python3 and curl but no Node. Probe first, so a template that ships its own Node pays
  * nothing.
  */
@@ -187,7 +187,7 @@ async function installSubject(step, command) {
             ? "subject install failed twice"
             : "subject install failed");
     if (!install.ok) {
-        // Lead with the line a person can act on; npm's own trace follows it (#602).
+        // Lead with the line a person can act on; npm's own trace follows it.
         const headline = install.timedOut
             ? `subject install timed out after ${step.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS}ms`
             : install.attempts === 2

package/dist/subject/state.d.ts

@@ -14,7 +14,7 @@ export declare function commandDigestOf(command: string): string;
 export declare function runStateSteps(shell: Shell, when: LabStateStepWhen, args: {
     state?: LabSubjectState;
     requestTimeoutMs: number;
-    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    /** Literal scrubber for known provisioned values, applied to log tails pre-truncation. */
     scrub: (text: string) => string;
     onStateStep?: (record: RunSubjectStateStepRecord) => void;
     onPhase?: (event: SubjectPhaseEvent) => void;

package/dist/subject/steps.d.ts

@@ -25,13 +25,13 @@ export declare function emitPhaseStarted(onPhase: ((event: SubjectPhaseEvent) =>
 /** Emit the matching phase-completed event: always carries ok and durationMs (>= 0). */
 export declare function emitPhaseCompleted(onPhase: ((event: SubjectPhaseEvent) => void) | undefined, now: () => number, startedAt: number, phase: string, ok: boolean, message: string): void;
 /** Default phase-boundary sink (stderr): one line per event, prefixed with the participant id
- *  only when laneCount > 1. Single-participant emission is unconditional: total single-participant silence for the
- *  whole clone/install/build/ready boot is the bug this event stream exists to close.
+ *  only when the run has more than one participant. A single participant still gets every line:
+ *  a silent clone, install, build and ready boot is the bug this event stream exists to close.
  *  Overridable via LabDeps.subjectPhaseSink so deterministic tests capture instead of writing to
  *  the real stderr. */
-export declare function defaultSubjectPhaseSink(event: SubjectPhaseEvent, ctx: {
-    laneId: string;
-    laneCount: number;
+export declare function defaultSubjectPhaseSink(event: SubjectPhaseEvent, participant: {
+    readonly id: string;
+    readonly count: number;
 }): void;
 /** The shared-world subject's phase line: one shared plane, so no participant prefix. */
 export declare function defaultSharedWorldPhaseSink(event: SubjectPhaseEvent): void;

package/dist/subject/steps.js

@@ -23,13 +23,13 @@ export function emitPhaseCompleted(onPhase, now, startedAt, phase, ok, message)
     });
 }
 /** Default phase-boundary sink (stderr): one line per event, prefixed with the participant id
- *  only when laneCount > 1. Single-participant emission is unconditional: total single-participant silence for the
- *  whole clone/install/build/ready boot is the bug this event stream exists to close.
+ *  only when the run has more than one participant. A single participant still gets every line:
+ *  a silent clone, install, build and ready boot is the bug this event stream exists to close.
  *  Overridable via LabDeps.subjectPhaseSink so deterministic tests capture instead of writing to
  *  the real stderr. */
-export function defaultSubjectPhaseSink(event, ctx) {
+export function defaultSubjectPhaseSink(event, participant) {
     const durationSuffix = event.durationMs === undefined ? "" : ` (${event.durationMs}ms)`;
-    const prefix = ctx.laneCount > 1 ? `humanish computer-use [${ctx.laneId}]` : "humanish computer-use";
+    const prefix = participant.count > 1 ? `humanish computer-use [${participant.id}]` : "humanish computer-use";
     process.stderr.write(`${prefix}: ${event.message}${durationSuffix}\n`);
 }
 /** The shared-world subject's phase line: one shared plane, so no participant prefix. */

package/dist/substrates/command-failure.d.ts

@@ -1,13 +1,13 @@
 /**
  * True when `error` is (structurally) the @e2b/desktop CommandExitError: a
- * non-zero substrate command exit that the real Sandbox surfaces as a THROW.
+ * non-zero substrate command exit that the real Sandbox surfaces as a throw.
  * Matches either the SDK class name (`name === "CommandExitError"`) or any object
  * carrying a numeric `exitCode` (the same field `commandFailureInfo` reads, so a
  * structural fake is covered without importing the SDK class).
  *
- * Deliberately conservative — it is the RECOVERABILITY predicate the CUA loop uses
+ * Deliberately conservative: it is the recoverability predicate the CUA loop uses
  * to skip a single failed desktop action instead of ending the whole run: it must
- * NOT match a deadline/abort control-flow signal (those subclass Error without a
+ * not match a deadline/abort control-flow signal (those subclass Error without a
  * name override or an exitCode) or a generic Error with no exit signal, so only a
  * genuine substrate-command failure is treated as recoverable.
  */

package/dist/substrates/command-failure.js

@@ -12,14 +12,14 @@
 import { tailOf } from "./shell.js";
 /**
  * True when `error` is (structurally) the @e2b/desktop CommandExitError: a
- * non-zero substrate command exit that the real Sandbox surfaces as a THROW.
+ * non-zero substrate command exit that the real Sandbox surfaces as a throw.
  * Matches either the SDK class name (`name === "CommandExitError"`) or any object
  * carrying a numeric `exitCode` (the same field `commandFailureInfo` reads, so a
  * structural fake is covered without importing the SDK class).
  *
- * Deliberately conservative — it is the RECOVERABILITY predicate the CUA loop uses
+ * Deliberately conservative: it is the recoverability predicate the CUA loop uses
  * to skip a single failed desktop action instead of ending the whole run: it must
- * NOT match a deadline/abort control-flow signal (those subclass Error without a
+ * not match a deadline/abort control-flow signal (those subclass Error without a
  * name override or an exitCode) or a generic Error with no exit signal, so only a
  * genuine substrate-command failure is treated as recoverable.
  */

package/dist/substrates/detached.d.ts

@@ -10,7 +10,7 @@ export declare function detachedTimersOf(options: DetachedTimers): DetachedTimer
 export interface DetachedStepOptions extends DetachedTimers {
     /** Short [a-z0-9-] label; names the script/status/log files under /tmp. */
     name: string;
-    /** The shell command to run (the lab author's own command — package.json-script trust). */
+    /** The shell command to run (the lab author's own command: package.json-script trust). */
     command: string;
     cwd?: string;
     /** Wall-clock budget for the step. */
@@ -22,19 +22,19 @@ export interface DetachedStepResult {
     ok: boolean;
     exitCode?: number;
     timedOut: boolean;
-    /** Capped, UNREDACTED log tail — redact before persisting. */
+    /** Capped, unredacted log tail; redact before persisting. */
     logTail: string;
 }
-/** Read the capped log tail for a step (raw — caller redacts). */
+/** Read the capped log tail for a step (raw; caller redacts). */
 export declare function readDetachedLog(shell: Shell, name: string, requestTimeoutMs?: number): Promise<string>;
 /**
- * Run a BOUNDED step (install/build) detached, polling its atomic status file until it
+ * Run a bounded step (install/build) detached, polling its atomic status file until it
  * exits or the budget runs out. On timeout the process group is killed and the log tail is
  * still captured so failures stay diagnosable.
  */
 export declare function runDetachedStep(shell: Shell, options: DetachedStepOptions): Promise<DetachedStepResult>;
 /**
- * Launch a LONG-LIVED process (the subject's server) fully detached and return immediately.
+ * Launch a long-lived process (the subject's server) fully detached and return immediately.
  * No status polling: liveness is the caller's readiness probe, and reclamation belongs to
  * the sandbox lifecycle (create with kill-on-timeout).
  */
@@ -45,7 +45,7 @@ export declare function startDetachedProcess(shell: Shell, options: {
     requestTimeoutMs?: number;
 }): Promise<void>;
 /**
- * Poll a URL from INSIDE the sandbox until it answers 2xx/3xx or the budget runs out.
+ * Poll a URL from inside the sandbox until it answers 2xx/3xx or the budget runs out.
  * Returns true when the subject is ready.
  */
 export declare function probeUrl(shell: Shell, url: string, options: {

package/dist/substrates/detached.js

@@ -1,17 +1,17 @@
 // Detached process management over a Shell, the primitive behind serving a subject app in the
 // sandbox. A foreground command hits its deadline on long-running work, so long work runs detached:
 //
-// - Scripts are written via `writeFile`, never heredocs — which eliminates the
+// - Scripts are written via `writeFile`, never heredocs, which eliminates the
 //   sentinel-collision bug class (a command line that equals the heredoc terminator) by
 //   construction.
-// - Bounded steps (install/build) run detached with an ATOMICALLY-written status file
+// - Bounded steps (install/build) run detached with an atomically-written status file
 //   (write tmp + mv), polled by short foreground commands; a timeout kills the process
 //   group and surfaces a capped log tail for the caller to redact and persist.
 // - Long-lived steps (a dev/prod server) launch fully detached through `Shell.start`; the
 //   sandbox lifecycle (kill-on-timeout) owns their reclamation.
 // - Readiness is an explicit curl probe against the declared URL.
 //
-// Log tails are returned RAW; callers must pass them through redaction before persisting
+// Log tails are returned raw; callers must pass them through redaction before persisting
 // (build output can echo env values and paths).
 import { runOrThrow, shellQuote, throwOnExit } from "./shell.js";
 const WORK_ROOT = "/tmp/humanish-subject";
@@ -62,14 +62,14 @@ async function writeAndLaunch(shell, name, command, cwd, requestTimeoutMs) {
     await shell.writeFile(scriptPath, wrapperScript(name, command, cwd));
     throwOnExit(await shell.start(`bash ${shellQuote(scriptPath)}`, { requestTimeoutMs }));
 }
-/** Read the capped log tail for a step (raw — caller redacts). */
+/** Read the capped log tail for a step (raw; caller redacts). */
 export async function readDetachedLog(shell, name, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
     assertName(name);
     const result = await runOrThrow(shell, `tail -c ${LOG_TAIL_BYTES} ${shellQuote(`${stepDir(name)}/log.txt`)} 2>/dev/null || true`, { requestTimeoutMs });
     return result.stdout;
 }
 /**
- * Run a BOUNDED step (install/build) detached, polling its atomic status file until it
+ * Run a bounded step (install/build) detached, polling its atomic status file until it
  * exits or the budget runs out. On timeout the process group is killed and the log tail is
  * still captured so failures stay diagnosable.
  */
@@ -105,7 +105,7 @@ export async function runDetachedStep(shell, options) {
     }
 }
 /**
- * Launch a LONG-LIVED process (the subject's server) fully detached and return immediately.
+ * Launch a long-lived process (the subject's server) fully detached and return immediately.
  * No status polling: liveness is the caller's readiness probe, and reclamation belongs to
  * the sandbox lifecycle (create with kill-on-timeout).
  */
@@ -113,7 +113,7 @@ export async function startDetachedProcess(shell, options) {
     await writeAndLaunch(shell, options.name, options.command, options.cwd, options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
 }
 /**
- * Poll a URL from INSIDE the sandbox until it answers 2xx/3xx or the budget runs out.
+ * Poll a URL from inside the sandbox until it answers 2xx/3xx or the budget runs out.
  * Returns true when the subject is ready.
  */
 export async function probeUrl(shell, url, options) {

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

@@ -11,29 +11,29 @@ export interface ChromeCdpProbeArgs {
     targetId?: string;
     /**
      * "pinned" (default): the launch-time target, for launch geometry and emulation attribution.
-     * "active": the tab the participant is driving NOW — Chrome's /json lists page
+     * "active": the tab the participant is driving now; Chrome's /json lists page
      * targets most-recently-focused first. The state observer must follow the participant: a
-     * verification link that opens in a NEW tab left a pinned observer reading the old tab forever,
+     * verification link that opens in a new tab left a pinned observer reading the old tab forever,
      * so the observed URL never changed again and stopWhen/task criteria went blind (a live run's
-     * funnel read reach-dashboard 0/2 under a screenshot OF the dashboard). Final geometry follows
+     * funnel read reach-dashboard 0/2 under a screenshot of the dashboard). Final geometry follows
      * this target too: a closed launch tab is unavailable, and a background tab may report stale
      * layout dimensions or zero outer bounds after navigation.
      */
     prefer?: ChromeCdpPagePreference;
     /**
      * "state": url/title/text/scrollY. "geometry": outer window + CSS viewport. "port": resolution
-     * only. "emulate": apply mobile emulation (#221) to the selected page and exit (the overrides that
+     * only. "emulate": apply mobile emulation to the selected page and exit (the overrides that
      * are session-scoped, UA / touch / DPR, lapse when the socket closes). "hold": the same over a browser-level
      * socket, then stay attached until killed (how a participant keeps them for its whole life) and attach
      * to every page target Chrome opens later, sending it the same overrides and a reload the moment
-     * it exists, never pausing it (#623). "fidelity": read
+     * it exists, never pausing it. "fidelity": read
      * back what the page reports about itself (UA, DPR, viewport, touch), the proof for the bundle.
      */
     mode: "state" | "geometry" | "port" | "emulate" | "hold" | "fidelity";
     /** For "emulate": what to apply. */
     emulation?: ChromeMobileEmulationRequest;
 }
-/** Mobile emulation request (#221): the CDP Emulation domain applied to one page target. */
+/** Mobile emulation request: the CDP Emulation domain applied to one page target. */
 export interface ChromeMobileEmulationRequest {
     width: number;
     height: number;
@@ -82,9 +82,9 @@ export interface ChromeCdpProbeResult {
  * 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 declare const CHROME_CDP_PROBE_PY: string;
@@ -93,7 +93,7 @@ export declare function chromeCdpProbeCommand(args: ChromeCdpProbeArgs): string;
 /**
  * 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 declare function parseChromeCdpProbeOutput(stdout: string | undefined): ChromeCdpProbeResult;
 export {};