humanish 0.111.1 → 0.111.3

package/dist/substrates/e2b/subject-sandbox.js

@@ -0,0 +1,94 @@
+// The subject sandbox of a provisioned clone: the one E2B desktop that serves the app, on the
+// scripted clone route and the shared-world provisioned plane. Both routes create, measure and
+// release it through this class, so a change to its request, its size check or its release
+// reading is one edit. What runs inside the sandbox (the caller's prepare hook, provisioning,
+// getHost) stays with each route.
+import { redactText } from "../../evidence/redaction.js";
+import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
+import { observeDesktopResources } from "./desktop-resources.js";
+import { SANDBOX_TIMEOUT_BUFFER_MS, SUBJECT_PROVISION_BUDGET_MS } from "./lifetime.js";
+import { acquireE2BDesktopSandbox, readE2BRelease } from "./sandbox.js";
+export class E2BSubjectSandbox {
+    sandboxId;
+    killed = false;
+    /** The scrubbed release warning when the release is unconfirmed. */
+    releaseWarning;
+    run;
+    allocation;
+    createdAtMs;
+    tornDownAtMs;
+    resources;
+    constructor(run) {
+        this.run = run;
+    }
+    /**
+     * Creates the sandbox and reads its size. The receipt is on disk before this returns, so
+     * `humanish reclaim` can kill the sandbox by exact id if the process dies during provisioning.
+     */
+    async acquire(request) {
+        const { envs } = request;
+        const { warnings, scrub } = this.run;
+        const timeoutMs = request.sessionTimeoutMs +
+            SUBJECT_PROVISION_BUDGET_MS +
+            request.seed.reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0) +
+            SANDBOX_TIMEOUT_BUFFER_MS;
+        const subject = await acquireE2BDesktopSandbox({
+            module: request.module,
+            options: {
+                apiKey: request.apiKey,
+                requestTimeoutMs: request.requestTimeoutMs,
+                timeoutMs,
+                metadata: request.metadata,
+                ...(Object.keys(envs).length > 0 ? { envs } : {}),
+                dpi: 96,
+                lifecycle: { onTimeout: "kill" },
+            },
+            template: request.template,
+            retry: {
+                // A failed first attempt may have allocated a sandbox whose id never reached this run;
+                // its own kill-on-timeout reclaims it.
+                onRetry: (reason) => {
+                    warnings.push(`Subject sandbox create retried once after a transient provider error (${redactText(scrub(reason))}). A sandbox the failed attempt may have allocated is reclaimed by its ${timeoutMs} ms timeout.`);
+                },
+            },
+            receipt: { root: request.root, participantId: "subject" },
+        });
+        this.allocation = subject.allocation;
+        this.sandboxId = subject.allocation.resourceId;
+        this.createdAtMs = this.run.now();
+        const resources = await observeDesktopResources(subject.sandbox);
+        this.resources = resources;
+        if ("reason" in resources)
+            warnings.push(`Subject sandbox resource size unavailable (${resources.reason}); its compute cost remains unpriced.`);
+        return subject.sandbox;
+    }
+    /** Releases the sandbox by exact id, when one was acquired. An unconfirmed release is reported. */
+    async release() {
+        const { warnings, scrub, now } = this.run;
+        if (this.allocation === undefined)
+            return;
+        const released = await this.allocation.close();
+        const reading = readE2BRelease(released, { label: "Subject sandbox", scrub, costSpan: true });
+        this.killed = reading.released;
+        if (reading.warning)
+            warnings.push(reading.warning);
+        if (!reading.released)
+            this.releaseWarning = reading.warning ?? "Subject sandbox release is unconfirmed.";
+        // Without a kill method, or in E2B debug mode, no kill reached E2B, so there is no teardown
+        // time to record.
+        if (released.status !== "unconfirmed" || released.reason !== "release_unavailable")
+            this.tornDownAtMs = now();
+    }
+    /** The billed span and size, when a sandbox was acquired. */
+    desktopUsage() {
+        if (this.sandboxId === undefined)
+            return undefined;
+        return {
+            durationMs: this.createdAtMs === undefined || this.tornDownAtMs === undefined
+                ? undefined
+                : Math.max(0, this.tornDownAtMs - this.createdAtMs),
+            observation: this.resources,
+            killed: this.killed,
+        };
+    }
+}

package/docs/contracts/core.md

@@ -1,9 +1,10 @@
 # Core Contract
 
-Each route mints its run id and builds its bundle, and starts the run
-through the run scope in `src/run/run.ts`. `startRun` creates
-`.humanish/runs/<id>` and begins `status.json`; the `Run` it returns publishes
-`run.json`, its projections and the latest pointer. `src/run/paths.ts` holds the
+Each route builds its bundle and starts the run through the run scope in
+`src/run/run.ts`. `startRun` takes the caller's run id or mints one from the
+route's prefix, creates `.humanish/runs/<id>`, begins `status.json` and captures
+the run's source; preview mints its own id and builds its source first. The
+`Run` it returns publishes `run.json`, its projections and the latest pointer. `src/run/paths.ts` holds the
 shared path rules and `src/run/git-state.ts` captures git state. The table
 below lists the records current bundles write.
 

package/docs/contracts/feedback.md

@@ -50,16 +50,23 @@ humanish feedback issue-url --run latest --repo owner/repo
 ### `list`
 
 Reads feedback candidates from the run bundle. Does not mutate. Candidates come
-from the computer-use route, when a participant reports friction or abandons the
-study goal, and from an adapter's `deriveFeedback` hook.
+from the computer-use and shared-world routes, when a participant reports
+friction or abandons the study goal, and from an adapter's `deriveFeedback` hook.
+Both routes build them with `participantFeedbackCandidates`
+(`src/routes/computer-use/participant-feedback.ts`): one candidate per reporting
+participant, named by its participant id, with that participant's own
+instructions as `expected` and no merging of reports that match.
+A shared-world candidate also cites the run's comms thread when the study
+captured one, since that thread belongs to the shared app. Adapter candidates
+follow the participant candidates.
 
 The list also shows any saved draft. An empty `candidates` array means no usable
 candidate was recorded; it does not mean a run-summary draft is unavailable.
 Listing does not create a draft or check public-sharing eligibility.
 
-For completed computer-use sessions, participant-reported friction comes from
-the redacted closing report, a completed debrief's `frictionReports`, and
-observed-report clauses in earlier messages.
+For completed computer-use and shared-world sessions, participant-reported
+friction comes from the redacted closing report, a completed debrief's
+`frictionReports`, and observed-report clauses in earlier messages.
 Matching `stopWhen` or ending a dwell window does not discard an earlier
 report or change the successful completion verdict. Exact repeated reports
 appear once in the participant's candidate. Harness notices, reasoning, and observed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.111.1",
+  "version": "0.111.3",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",