humanish 0.106.1 → 0.108.0

package/dist/study/owned-files.d.ts

@@ -0,0 +1,38 @@
+export interface FileIdentity {
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly size: bigint;
+    readonly sha256: string;
+}
+export interface DirectoryIdentity {
+    readonly physicalPath: string;
+    readonly dev: bigint;
+    readonly ino: bigint;
+}
+interface Inode {
+    readonly dev: bigint;
+    readonly ino: bigint;
+}
+/**
+ * A file this run creates. `inode` is set the moment the exclusive create succeeds, so a name that
+ * was already taken is never treated as this run's. `identity` is set once the bytes are written
+ * and read back through the same descriptor.
+ */
+export interface OwnedFile {
+    readonly path: string;
+    inode?: Inode | undefined;
+    identity?: FileIdentity | undefined;
+}
+export type LinkFile = (from: string, to: string) => Promise<void>;
+export declare function sha256(bytes: Buffer): string;
+export declare function fileIdentity(absolutePath: string, ours?: boolean): Promise<FileIdentity>;
+export declare function sameFile(left: FileIdentity, right: FileIdentity): boolean;
+export declare function bindDirectory(root: string, relativeDir: string, created?: string[]): Promise<DirectoryIdentity | undefined>;
+export declare function assertDirectory(directory: DirectoryIdentity, root: string): Promise<void>;
+export declare function exists(absolutePath: string): Promise<boolean>;
+export declare function writeOwned(owned: OwnedFile, bytes: Buffer | string, mode: number): Promise<void>;
+export declare function removeChecked(file: string, matches: (current: FileIdentity) => boolean, linkFile: LinkFile): Promise<string | undefined>;
+export declare function removeOwned(owned: OwnedFile, linkFile: LinkFile): Promise<string | undefined>;
+export declare const NO_HARD_LINKS: Set<string>;
+export declare function restoreName(from: string, to: string, linkFile: LinkFile): Promise<boolean>;
+export {};

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,9 +1,9 @@
 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
+ * 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
  * screen. Omitting install deliberately studies product installation; Node/npm remain a
  * harness prerequisite so the participant can follow the product's public npm instructions.

package/dist/subject/desktop-cli.js

@@ -4,9 +4,9 @@ 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
+ * 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
  * screen. Omitting install deliberately studies product installation; Node/npm remain a
  * harness prerequisite so the participant can follow the product's public npm instructions.
@@ -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.d.ts

@@ -74,7 +74,7 @@ export declare function createLocalTreeArchive(root: string, options?: CreateLoc
 /**
  * Normalize an author-supplied exclude entry to the relPath shape enumeration
  * produces (no leading "./", no trailing "/"). Absolute paths and glob syntax
- * are REJECTED, not silently no-op'd: an exclude the author believed in but
+ * are rejected instead of silently ignored: an exclude the author believed in but
  * that never matches anything is a leak vector, so unusable shapes fail
  * closed at the packing boundary (and, for lab manifests, already at parse
  * time in src/lab/parse/subject.ts).

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

@@ -1,6 +1,6 @@
 // Local working-tree packaging for `subject.source: local-tree`.
 //
-// Enumeration produces ONE file list that drives BOTH the tar archive and the
+// Enumeration produces one file list that drives both the tar archive and the
 // content digest (archiveSha256), so the digest can never diverge from what
 // actually gets packed. A prior in-house harness reimplemented exclusion in a
 // second, independent digest walker that could drift from what its tar
@@ -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";
@@ -113,7 +113,7 @@ export function createLocalTreeArchive(root, options = {}) {
             (extraExclude.length > 0 ? " and extraExclude" : "") +
             "; local-tree packing requires at least one non-denylisted file or symlink. (Paths in this message are basenames only; the packed root is the lab resolution cwd.)");
     }
-    // Check the cap from enumerated sizes BEFORE reading/hashing file bytes, so
+    // Check the cap from enumerated sizes before reading/hashing file bytes, so
     // an oversized tree fails closed without the cost of hashing all of it.
     const enumeratedBytes = entries.reduce((sum, entry) => (entry.kind === "file" ? sum + entry.size : sum), 0);
     if (enumeratedBytes > maxArchiveBytes) {
@@ -200,7 +200,7 @@ function captureGitInfo(root) {
         return undefined;
     }
     // Pathspec-scoped to the packed root: `git status --porcelain` without a
-    // pathspec reports the WHOLE enclosing repository, which would report a
+    // pathspec reports the whole enclosing repository, which would report a
     // clean packed subtree as dirty whenever an unrelated sibling package in a
     // monorepo has in-progress changes.
     const status = execFileSync("git", ["status", "--porcelain", "--", "."], {
@@ -290,7 +290,7 @@ function isDenylistedSegment(relPath) {
 /**
  * Normalize an author-supplied exclude entry to the relPath shape enumeration
  * produces (no leading "./", no trailing "/"). Absolute paths and glob syntax
- * are REJECTED, not silently no-op'd: an exclude the author believed in but
+ * are rejected instead of silently ignored: an exclude the author believed in but
  * that never matches anything is a leak vector, so unusable shapes fail
  * closed at the packing boundary (and, for lab manifests, already at parse
  * time in src/lab/parse/subject.ts).

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

@@ -5,20 +5,20 @@ import type { Shell } from "../substrates/shell.js";
 import { type SubjectPhaseEvent } from "./steps.js";
 /**
  * Provision a local-tree subject inside the sandbox: upload the once-per-run packed archive
- * (identical bytes across every fan-out lane) → extract it into SUBJECT_DIR → the
+ * (identical bytes across every fan-out participant) → extract it into SUBJECT_DIR → the
  * same shared serve pipeline provisionCloneSubject uses. Unlike the clone route there is no
  * in-sandbox git refresh: the archive excludes .git entirely (see local-tree-archive.ts), so
  * subject identity is the host-side LocalTreeArchive captured at pack time, never anything
  * resolved in-sandbox.
  */
 export declare function provisionLocalTreeSubject(shell: Shell, args: {
-    /** The once-per-run packed archive bytes (shared byte-identically across every lane). */
+    /** The once-per-run packed archive bytes (shared byte-identically across every participant). */
     archiveBuffer: ArrayBuffer;
     serve: LabSubjectServe;
     /** 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/local-tree.js

@@ -7,7 +7,7 @@ import { SOURCE_TIMEOUT_MS, emitPhaseCompleted, emitPhaseStarted, SUBJECT_DIR, }
 const LOCAL_TREE_REMOTE_ARCHIVE_PATH = "/home/user/.humanish-source.tar.gz";
 /**
  * Provision a local-tree subject inside the sandbox: upload the once-per-run packed archive
- * (identical bytes across every fan-out lane) → extract it into SUBJECT_DIR → the
+ * (identical bytes across every fan-out participant) → extract it into SUBJECT_DIR → the
  * same shared serve pipeline provisionCloneSubject uses. Unlike the clone route there is no
  * in-sandbox git refresh: the archive excludes .git entirely (see local-tree-archive.ts), so
  * subject identity is the host-side LocalTreeArchive captured at pack time, never anything

package/dist/subject/node-bootstrap.d.ts

@@ -6,7 +6,7 @@ export declare const NODE_NPM_PREFIX_SCRIPT: string;
 export declare const NODE_BOOTSTRAP_TIMEOUT_MS: number;
 /**
  * Install Node from the pinned official archive when the desktop has no working Node >=20 and
- * npm. The terminal lane, desktop CLI studies and the subject serve pipeline share it. It needs no
+ * npm. The terminal route, desktop CLI studies and the subject serve pipeline share it. It needs no
  * apt: every network call is one bounded curl, so a stalled mirror fails the step within minutes.
  */
 export declare const NODE_BOOTSTRAP_COMMAND: string;

package/dist/subject/node-bootstrap.js

@@ -20,7 +20,7 @@ export const NODE_NPM_PREFIX_SCRIPT = [
 export const NODE_BOOTSTRAP_TIMEOUT_MS = 5 * 60_000;
 /**
  * Install Node from the pinned official archive when the desktop has no working Node >=20 and
- * npm. The terminal lane, desktop CLI studies and the subject serve pipeline share it. It needs no
+ * npm. The terminal route, desktop CLI studies and the subject serve pipeline share it. It needs no
  * apt: every network call is one bounded curl, so a stalled mirror fails the step within minutes.
  */
 export const NODE_BOOTSTRAP_COMMAND = [
@@ -54,13 +54,13 @@ 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",
     `node -e 'process.exit(Number(process.versions.node.split(".")[0]) >= 20 ? 0 : 1)' && npm --version >/dev/null`,
-    // Product installation already uses sudo; detect a template whose sudo PATH cannot see Node
-    // rather than changing global PATH or permissions to make it look supported.
+    // Product installation already uses sudo; detect a template whose sudo `PATH` cannot see Node
+    // rather than changing global `PATH` or permissions to make it look supported.
     `sudo -n node -e 'process.exit(Number(process.versions.node.split(".")[0]) >= 20 ? 0 : 1)' && sudo -n npm --version >/dev/null`,
     "fi",
 ].join("\n");

package/dist/subject/runtime.js

@@ -1,18 +1,17 @@
-// 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 lane 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 posture here is PROVIDE, not warn. 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
-// lane already treats it that way. Detection is conservative and the bootstrap is skipped whenever
+// 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
+// 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. */
 const NODE_COMMANDS = ["npm", "npx", "pnpm", "yarn", "bun", "node", "vite", "next", "tsx"];

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.
@@ -114,14 +114,14 @@ export async function runSubjectServePipeline(shell, args) {
     await refresh();
     await startSubject(step);
     await waitForSubjectReady(step);
-    // after-ready: fixture loading through the RUNNING app (loopback curl from in-sandbox:
+    // after-ready: fixture loading through the running app (loopback curl from in-sandbox:
     // steps are author-trusted provisioning, not actors, so no new URL policy surface). These
     // complete before the caller opens the browser and the session timer starts.
     await runState("after-ready");
     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

@@ -24,14 +24,14 @@ export declare function isoNow(now: () => number): string;
 export declare function emitPhaseStarted(onPhase: ((event: SubjectPhaseEvent) => void) | undefined, now: () => number, phase: string, message: string): void;
 /** 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 lane id ONLY
- *  when laneCount > 1. Single-lane emission is unconditional: total single-lane silence for the
- *  whole clone/install/build/ready boot is the bug this event stream exists to close.
- *  Overridable via CuaActorLabHooks.onPhase so deterministic tests capture instead of writing to
+/** Default phase-boundary sink (stderr): one line per event, prefixed with the participant id
+ *  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 lane prefix. */
+/** 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

@@ -22,17 +22,17 @@ export function emitPhaseCompleted(onPhase, now, startedAt, phase, ok, message)
         message,
     });
 }
-/** Default phase-boundary sink (stderr): one line per event, prefixed with the lane id ONLY
- *  when laneCount > 1. Single-lane emission is unconditional: total single-lane silence for the
- *  whole clone/install/build/ready boot is the bug this event stream exists to close.
- *  Overridable via CuaActorLabHooks.onPhase so deterministic tests capture instead of writing to
+/** Default phase-boundary sink (stderr): one line per event, prefixed with the participant id
+ *  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 cua [${ctx.laneId}]` : "humanish cua";
+    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 lane prefix. */
+/** The shared-world subject's phase line: one shared plane, so no participant prefix. */
 export function defaultSharedWorldPhaseSink(event) {
     const durationSuffix = event.durationMs === undefined ? "" : ` (${event.durationMs}ms)`;
     process.stderr.write(`humanish shared-world (concurrent): ${event.message}${durationSuffix}\n`);

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: {