humanish 0.111.2 → 0.111.3

package/dist/study/requirements.d.ts

@@ -1,8 +1,5 @@
-import type { StudyPlan, Requirement } from "./plan-types.js";
-/** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
-export declare function missingKeys(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
-/** The subject env names the requirements list and `env` lacks, in declaration order. */
-export declare function missingSubjectEnv(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
+import { type LocalAgentRefusal } from "../actors/local-agent/readiness.js";
+import type { Brain, StudyPlan, Requirement } from "./plan-types.js";
 /**
  * The provider keys the requirements name, in plan order. A `key-one-of` names the first of its
  * keys that `isPresent` reports, else OPENAI_API_KEY.
@@ -18,3 +15,61 @@ export declare function requiredSubjectEnv(requirements: readonly Requirement[])
  * a declared scorer's host code, are not in the plan.
  */
 export declare function keyNamesOf(plan: StudyPlan): ReadonlySet<string>;
+/** A live check's refusal, in its route's error code. */
+export interface LiveRefusal<C extends string> {
+    readonly code: C;
+    readonly message: string;
+}
+/** One live check: its refusal, or undefined when this machine passes it. */
+export type LiveCheck<C extends string> = () => LiveRefusal<C> | undefined | Promise<LiveRefusal<C> | undefined>;
+/**
+ * The first refusal of `checks`, run one at a time in the order given. Which check comes first
+ * decides which error a run with two problems reports, so each route keeps its own order.
+ */
+export declare function firstLiveRefusal<C extends string>(checks: readonly LiveCheck<C>[]): Promise<LiveRefusal<C> | undefined>;
+/**
+ * Refuses a run whose environment lacks a provider key the requirements list. `need` writes the
+ * route's sentence for the missing names ("OPENAI_API_KEY and E2B_API_KEY"); the message goes on
+ * to say where discovery looked and what fills each key. With `suggestLocalAgent`, a missing
+ * OPENAI_API_KEY also names each coding agent signed in on this machine: someone new meets this
+ * refusal first, and an agent they already use runs the participants without a key.
+ */
+export declare function keysCheck<C extends string>(args: {
+    readonly requirements: readonly Requirement[];
+    readonly env: Record<string, string | undefined>;
+    readonly code: C;
+    readonly need: (names: string) => string;
+    readonly suggestLocalAgent?: boolean;
+}): Promise<LiveRefusal<C> | undefined>;
+/**
+ * Refuses a local-agent brain whose CLI is missing, signed out, too old, or cannot honor the
+ * caps, before any sandbox is paid for. `codes` names the route's code for each kind of refusal.
+ */
+export declare function localAgentCheck<C extends string>(args: {
+    readonly brain: Brain;
+    readonly env: Record<string, string | undefined>;
+    readonly caps: {
+        readonly maxUsd?: number;
+        readonly maxTotalUsd?: number;
+    };
+    readonly codes: Readonly<Record<LocalAgentRefusal["kind"], C>>;
+}): Promise<LiveRefusal<C> | undefined>;
+/** Refuses a run whose environment lacks a subject env name the requirements list. */
+export declare function subjectEnvCheck<C extends string>(args: {
+    readonly requirements: readonly Requirement[];
+    readonly env: Record<string, string | undefined>;
+    readonly code: C;
+}): LiveRefusal<C> | undefined;
+/**
+ * Refuses a maxUsd or maxTotalUsd cap on a model with no rate in src/run/pricing.ts. The loop
+ * could not measure spend against the cap, and running uncapped would drop the protection the
+ * cap promised; the operator picks a priced model or removes the cap.
+ */
+export declare function unpricedCapCheck<C extends string>(args: {
+    readonly caps: {
+        readonly maxUsd?: number;
+        readonly maxTotalUsd?: number;
+    };
+    readonly model: string;
+    readonly code: C;
+}): LiveRefusal<C> | undefined;

package/dist/study/requirements.js

@@ -1,13 +1,23 @@
+// The keys and subject env a live plan's requirements list, and the live checks that read them.
+// Each route lists the checks below (keysCheck, localAgentCheck, subjectEnvCheck,
+// unpricedCapCheck) in its own order, with its own error codes. Doctor and the TUI ask
+// requiredKeys and requiredSubjectEnv which names to report, and `run` asks keyNamesOf which
+// key-source lines to print, so the planner alone decides what a run needs. The terminal runtime
+// key (`key-one-of`) stays with buildRuntimeAuth at run time, which also picks its placement.
+import { detectLocalAgents } from "../actors/local-agent/cli.js";
+import { localAgentRefusal } from "../actors/local-agent/readiness.js";
+import { describeMissingKeys } from "../keys/key-resolution.js";
+import { MODEL_RATES, unpricedCapMessage } from "../run/pricing.js";
 /** Provider keys in the order the routes name them in a refusal. */
 const KEY_ORDER = ["OPENAI_API_KEY", "E2B_API_KEY"];
 const present = (env, name) => (env[name]?.trim() ?? "") !== "";
 /** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
-export function missingKeys(requirements, env) {
+function missingKeys(requirements, env) {
     const required = new Set(requirements.flatMap((requirement) => (requirement.kind === "key" ? [requirement.name] : [])));
     return KEY_ORDER.filter((name) => required.has(name) && !present(env, name));
 }
 /** The subject env names the requirements list and `env` lacks, in declaration order. */
-export function missingSubjectEnv(requirements, env) {
+function missingSubjectEnv(requirements, env) {
     return requiredSubjectEnv(requirements).filter((name) => !present(env, name));
 }
 /**
@@ -52,3 +62,79 @@ export function keyNamesOf(plan) {
         names.add("OPENAI_API_KEY");
     return names;
 }
+/**
+ * The first refusal of `checks`, run one at a time in the order given. Which check comes first
+ * decides which error a run with two problems reports, so each route keeps its own order.
+ */
+export async function firstLiveRefusal(checks) {
+    for (const check of checks) {
+        const refusal = await check();
+        if (refusal !== undefined)
+            return refusal;
+    }
+    return undefined;
+}
+/**
+ * Refuses a run whose environment lacks a provider key the requirements list. `need` writes the
+ * route's sentence for the missing names ("OPENAI_API_KEY and E2B_API_KEY"); the message goes on
+ * to say where discovery looked and what fills each key. With `suggestLocalAgent`, a missing
+ * OPENAI_API_KEY also names each coding agent signed in on this machine: someone new meets this
+ * refusal first, and an agent they already use runs the participants without a key.
+ */
+export async function keysCheck(args) {
+    const { env } = args;
+    const missing = missingKeys(args.requirements, env);
+    if (missing.length === 0)
+        return undefined;
+    const suggestion = args.suggestLocalAgent === true && missing.includes("OPENAI_API_KEY")
+        ? await signedInAgentSuggestion(env)
+        : "";
+    return {
+        code: args.code,
+        message: `${args.need(missing.join(" and "))} ${describeMissingKeys(missing, env)}${suggestion}`,
+    };
+}
+/** The sentence naming the coding agents signed in on this machine, or "" when none is. */
+async function signedInAgentSuggestion(env) {
+    const ready = (await detectLocalAgents({ env })).filter((agent) => agent.authStatus === "authenticated");
+    if (ready.length === 0)
+        return "";
+    const labels = ready.map((agent) => agent.label).join(" and ");
+    return ` ${labels} reports authenticated on this machine. Set actor.type: local-agent to use ${ready.length === 1 ? "it" : "one"} instead of a key.`;
+}
+/**
+ * Refuses a local-agent brain whose CLI is missing, signed out, too old, or cannot honor the
+ * caps, before any sandbox is paid for. `codes` names the route's code for each kind of refusal.
+ */
+export async function localAgentCheck(args) {
+    const { brain, env, caps } = args;
+    if (brain.kind !== "local-agent")
+        return undefined;
+    const refusal = await localAgentRefusal({ agent: brain.agent, env, caps });
+    return refusal === undefined
+        ? undefined
+        : { code: args.codes[refusal.kind], message: refusal.message };
+}
+/** Refuses a run whose environment lacks a subject env name the requirements list. */
+export function subjectEnvCheck(args) {
+    const unset = missingSubjectEnv(args.requirements, args.env);
+    if (unset.length === 0)
+        return undefined;
+    return {
+        code: args.code,
+        message: `subject.env declares ${unset.join(", ")} but the environment does not provide ${unset.length === 1 ? "it" : "them"} (pass via --dotenv; values are never persisted).`,
+    };
+}
+/**
+ * Refuses a maxUsd or maxTotalUsd cap on a model with no rate in src/run/pricing.ts. The loop
+ * could not measure spend against the cap, and running uncapped would drop the protection the
+ * cap promised; the operator picks a priced model or removes the cap.
+ */
+export function unpricedCapCheck(args) {
+    const { caps, model } = args;
+    if (caps.maxUsd === undefined && caps.maxTotalUsd === undefined)
+        return undefined;
+    if (MODEL_RATES[model.trim().toLowerCase()])
+        return undefined;
+    return { code: args.code, message: unpricedCapMessage(model) };
+}

package/dist/study/run-study-events.d.ts

@@ -1,3 +1,4 @@
+import { RunSecrets } from "../run/secrets.js";
 import type { CuaParticipantPlan } from "../routes/computer-use/types.js";
 import type { SubjectPhaseEvent } from "../subject/steps.js";
 import type { InternalRunStudyOptions } from "../run-study.js";
@@ -50,12 +51,12 @@ export type StudyEvent = {
  * analysis API key. A callback can hold any of them, and its warning is appended after the route
  * sanitized its own.
  */
-export declare function knownSecretValues(config: StudyConfig, options: InternalRunStudyOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): string[];
+export declare function knownSecrets(config: StudyConfig, options: InternalRunStudyOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): RunSecrets;
 /**
  * The emitter the route hook bags call, or undefined without onEvent. It calls onEvent and never
- * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secretValues`.
+ * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secrets`.
  */
-export declare function studyEventEmitter(onEvent: ((event: StudyEvent) => void | Promise<void>) | undefined, warnings: string[], secretValues: () => string[]): ((event: StudyEvent) => void) | undefined;
+export declare function studyEventEmitter(onEvent: ((event: StudyEvent) => void | Promise<void>) | undefined, warnings: string[], secrets: () => RunSecrets): ((event: StudyEvent) => void) | undefined;
 /** The computer-use participant plan as a `plan` event: ids, personas, devices and digests. */
 export declare function planEvent(plan: CuaParticipantPlan): StudyEvent;
 export declare function phaseEvent(event: SubjectPhaseEvent, target: SetupTarget): StudyEvent;

package/dist/study/run-study-events.js

@@ -1,32 +1,28 @@
 // What a run reports through RunStudyOptions.onEvent, and how a callback failure becomes a run
 // warning. normalizeRunStudyOptions (run-study-options.ts) builds the emitter and hands it to the
 // route hook bags it maps; the event values are built here.
-import { redactText, scrubLiterals, toErrorMessage } from "../evidence/redaction.js";
+import { redactText, toErrorMessage } from "../evidence/redaction.js";
+import { RunSecrets } from "../run/secrets.js";
 /**
  * The literal values to scrub from an onEvent warning: the provider keys and the declared subject
  * env from every env the run could read (the `env` option and process.env), and the
  * analysis API key. A callback can hold any of them, and its warning is appended after the route
  * sanitized its own.
  */
-export function knownSecretValues(config, options, forwardedEnv) {
+export function knownSecrets(config, options, forwardedEnv) {
     const sources = [forwardedEnv, options.env, process.env];
     const names = ["OPENAI_API_KEY", "E2B_API_KEY", "CODEX_API_KEY", ...(config.subject.env ?? [])];
-    const values = new Set();
-    const add = (value) => {
-        const trimmed = value?.trim() ?? "";
-        if (trimmed.length >= 4)
-            values.add(trimmed);
-    };
+    const secrets = new RunSecrets([]);
     for (const env of sources)
         for (const name of names)
-            add(env?.[name]);
-    return [...values];
+            secrets.add([env?.[name]?.trim() ?? ""]);
+    return secrets;
 }
 /**
  * The emitter the route hook bags call, or undefined without onEvent. It calls onEvent and never
- * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secretValues`.
+ * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secrets`.
  */
-export function studyEventEmitter(onEvent, warnings, secretValues) {
+export function studyEventEmitter(onEvent, warnings, secrets) {
     if (onEvent === undefined)
         return undefined;
     return (event) => {
@@ -37,8 +33,7 @@ export function studyEventEmitter(onEvent, warnings, secretValues) {
             let detail;
             try {
                 // Read here, not up front: a run with no failing callback never touches the env.
-                const scrub = scrubLiterals(secretValues());
-                detail = redactText(scrub(toErrorMessage(error)));
+                detail = redactText(secrets().scrub(toErrorMessage(error)));
             }
             catch {
                 detail = "the thrown value has no message";

package/dist/study/run-study-options.d.ts

@@ -23,6 +23,9 @@ export declare function removedOptionRefusal(options: RunStudyOptions): Refusal
  * Nothing here touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
  */
 export declare function normalizeRunStudyOptions(config: StudyConfig, route: StudyRoute, options: InternalRunStudyOptions): Normalized | Refusal;
-/** A refusal in the route's own result envelope, before any run exists. */
+/**
+ * A refusal in the route's own result envelope, before any run exists. Each route's own fields come
+ * after `error` here.
+ */
 export declare function optionRefusalOutcome(config: StudyConfig, route: StudyRoute, options: RunStudyOptions, refusal: Refusal): StudyOutcome;
 export {};

package/dist/study/run-study-options.js

@@ -5,8 +5,8 @@
 import path from "node:path";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { resolveStudyDryRun } from "./plan.js";
-import { knownSecretValues, studyEventEmitter } from "./run-study-events.js";
-import { studyResultIdentity } from "../run/study-result.js";
+import { knownSecrets, studyEventEmitter } from "./run-study-events.js";
+import { refusedResult } from "../run/study-result.js";
 import { participantList } from "./study-fields.js";
 const unsupported = (option, route, reason) => ({
     ok: false,
@@ -93,7 +93,7 @@ export function normalizeRunStudyOptions(config, route, options) {
     // The route gets this copy, so it is the env a warning is scrubbed against, whatever the caller
     // does to its own object afterwards.
     const forwardedEnv = env === undefined ? undefined : { ...env };
-    const emit = studyEventEmitter(onEvent, warnings, () => knownSecretValues(config, options, forwardedEnv));
+    const emit = studyEventEmitter(onEvent, warnings, () => knownSecrets(config, options, forwardedEnv));
     // Every route reads its typed options directly, and onEvent reaches it as `emit`. unsupportedOption
     // already refused an option no route reads; the preview route reads no env.
     const normalized = { ...forwarded };
@@ -101,33 +101,29 @@ export function normalizeRunStudyOptions(config, route, options) {
         normalized.env = forwardedEnv;
     return { ok: true, options: normalized, warnings, emit };
 }
-/** A refusal in the route's own result envelope, before any run exists. */
+/**
+ * A refusal in the route's own result envelope, before any run exists. Each route's own fields come
+ * after `error` here.
+ */
 export function optionRefusalOutcome(config, route, options, refusal) {
-    const cwd = path.resolve(options.cwd);
-    const error = { code: refusal.code, message: refusal.message };
-    const actor = config.actor?.type ?? "";
-    const dryRun = resolveStudyDryRun(config, options.dryRun, true) ?? true;
-    const runId = options.runId ?? "not-created";
-    const common = { ok: false, cwd, actor, dryRun, runId, warnings: [], error };
+    const base = {
+        studyId: config.id,
+        cwd: path.resolve(options.cwd),
+        error: { code: refusal.code, message: refusal.message },
+    };
+    const common = {
+        actor: config.actor?.type ?? "",
+        dryRun: resolveStudyDryRun(config, options.dryRun, true) ?? true,
+        runId: options.runId ?? "not-created",
+    };
     switch (route) {
         case "preview":
-            return {
-                route: "preview",
-                result: {
-                    ...studyResultIdentity("preview", config.id),
-                    ok: false,
-                    cwd,
-                    warnings: [],
-                    error,
-                },
-            };
+            return { route: "preview", result: refusedResult("preview", base, {}) };
         case "computer-use":
             return {
                 route: "computer-use",
                 result: {
-                    ...studyResultIdentity("computer-use", config.id),
-                    ...common,
-                    ok: false,
+                    ...refusedResult("computer-use", base, common),
                     appUrl: config.subject.appUrl ?? config.subject.serve?.url ?? "",
                     lanes: [],
                 },
@@ -136,9 +132,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             return {
                 route: "scripted",
                 result: {
-                    ...studyResultIdentity("scripted", config.id),
-                    ...common,
-                    ok: false,
+                    ...refusedResult("scripted", base, common),
                     appUrl: config.subject.appUrl ?? "",
                     sessions: [],
                 },
@@ -147,9 +141,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             return {
                 route: "terminal",
                 result: {
-                    ...studyResultIdentity("terminal", config.id),
-                    ...common,
-                    ok: false,
+                    ...refusedResult("terminal", base, common),
                     product: config.subject.product?.name ?? "",
                 },
             };
@@ -158,9 +150,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             return {
                 route: "shared-world",
                 result: {
-                    ...studyResultIdentity("shared-world", config.id),
-                    ...common,
-                    ok: false,
+                    ...refusedResult("shared-world", base, common),
                     topology: "shared-world",
                     topologyMode: "concurrent",
                     roleCount: participantCount,

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

@@ -0,0 +1,58 @@
+import type { PreparedOutputRoot } from "../../run/contained-output.js";
+import { type DesktopResourceObservation } from "./desktop-resources.js";
+import type { E2BDesktopModule, E2BDesktopSandbox } from "./sdk.js";
+/** The subject desktop's billed span and size, for the run's cost estimate. */
+export interface SubjectDesktopUsage {
+    durationMs: number | undefined;
+    observation: DesktopResourceObservation | undefined;
+    killed: boolean;
+}
+/** The run the subject sandbox reports to. */
+export interface SubjectSandboxRun {
+    /** The run's warnings. Acquisition and release append to it. */
+    warnings: string[];
+    scrub: (text: string) => string;
+    now: () => number;
+}
+/** How to create the subject sandbox. */
+export interface SubjectSandboxRequest {
+    module: E2BDesktopModule;
+    apiKey: string;
+    requestTimeoutMs: number;
+    /**
+     * The participants' session budget. The sandbox outlives it by the provision budget, each seed
+     * step's budget and the reclamation buffer, so E2B kills it only after the run is done with it.
+     */
+    sessionTimeoutMs: number;
+    seed: readonly {
+        readonly timeoutMs?: number | undefined;
+    }[];
+    /** The route's labels. Acquisition adds the run's owner tags. */
+    metadata: Record<string, string>;
+    /** The subject's environment at create; an empty record sets none. */
+    envs: Record<string, string>;
+    template: string | undefined;
+    /** Where the receipt goes, under the participant label `subject`. */
+    root: PreparedOutputRoot;
+}
+export declare class E2BSubjectSandbox {
+    sandboxId: string | undefined;
+    killed: boolean;
+    /** The scrubbed release warning when the release is unconfirmed. */
+    releaseWarning: string | undefined;
+    private readonly run;
+    private allocation;
+    private createdAtMs;
+    private tornDownAtMs;
+    private resources;
+    constructor(run: SubjectSandboxRun);
+    /**
+     * 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.
+     */
+    acquire(request: SubjectSandboxRequest): Promise<E2BDesktopSandbox>;
+    /** Releases the sandbox by exact id, when one was acquired. An unconfirmed release is reported. */
+    release(): Promise<void>;
+    /** The billed span and size, when a sandbox was acquired. */
+    desktopUsage(): SubjectDesktopUsage | undefined;
+}

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.2",
+  "version": "0.111.3",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",