humanish 0.34.0 → 0.36.0

package/dist/cua-actor-lab.js

@@ -37,6 +37,7 @@ import { buildOriginMap } from "./comms-inbox.js";
 import { DEFAULT_DEVICE_PRESET, isDevicePresetName, resolveDevicePreset } from "./device-presets.js";
 import { cuaLaneValidationReason, isHttpUrl, isLoopbackUrl, MAX_CUA_LANES, subjectStateInvalidReason } from "./lab-config.js";
 import { mapWithConcurrency } from "./concurrency.js";
+import { appendSandboxReceipt } from "./sandbox-receipts.js";
 import { assertScreenshotEvidence } from "./image-evidence.js";
 import { buildObserverData } from "./observer-data.js";
 import { attachObserverRuntimeStreamUrls, renderObserver } from "./observer.js";
@@ -50,8 +51,6 @@ export const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
 // The only fan-out topology this slice ships: N lanes = N independent E2B desktop sandboxes,
 // each its own world (clone/serve + subject.state per lane). Shared-world is layer 7 (#164).
 export const CUA_FANOUT_STRATEGY = "per-lane-worlds";
-// Default in-flight lane bound when the config does not declare execution.concurrency.
-const DEFAULT_CUA_CONCURRENCY = 3;
 // Env override that may only LOWER the effective concurrency (never raise concurrent paid
 // desktops — invariant 3). Read names-only into a local; the value never persists.
 const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
@@ -115,17 +114,30 @@ export function composeLaneInstructions(args) {
  *  runtime loopback/getHost address (not secret), so — mirroring the lobby-code runtime injection — this
  *  augments only the instructions the model receives; the authored prompt + its digest are unchanged.
  *  Returns a new spec (never mutates). Shared by the CUA + concurrent shared-world routes. */
-export function withInboxMission(spec, inboxUrl) {
+export function withInboxMission(spec, inboxUrl, address) {
+    // The address is half the handoff (#351): the drain matches captured mail against the DECLARED
+    // address, so an actor that invents its own at signup gets an inbox that stays empty forever.
+    // Telling it which address to use is what makes the funnel deterministic end to end. The
+    // wait-steering sentence exists because a mid-flow model treats "we emailed you" as a blocker
+    // and ends its session — the exact give-up class a live run documented — unless told the wait
+    // is expected and the inbox is the next step.
+    const identity = address === undefined ? "" : ` Your email address is ${address} — when the app asks for an email address, enter exactly that.`;
     return {
         ...spec,
-        instructions: `${spec.instructions}\n\nEmail inbox: when the app tells you it has emailed you (a verification link, confirmation code, or magic link), open ${inboxUrl} in the browser to read that email and follow its link or enter its code. All email the app sends you arrives there.`
+        instructions: `${spec.instructions}\n\nEmail inbox:${identity} When the app tells you it has emailed you (a verification link, confirmation code, or magic link), open ${inboxUrl} in the browser to read that email and follow its link or enter its code. All email the app sends you arrives there. Waiting for an email is normal, not a blocker — do not end your session while waiting; open the inbox and refresh it until the email appears.`
     };
 }
+/** The lane's addressed comms recipient, when one exists — the gate AND the address source for the
+ *  inbox instruction (#351). A lane told to check an inbox it can never receive into would stall,
+ *  so no addressed recipient means no instruction. */
+export function inboxRecipientFor(commsEmail, laneId) {
+    return (commsEmail.recipients ?? []).find((recipient) => recipient.lane === laneId && recipient.address !== undefined);
+}
 /** True when a lane has a declared comms recipient WITH an address, so the drain can actually match the
  *  mail the persona will be told to read. Gates the inbox instruction to lanes that can receive mail —
  *  a lane told to check an inbox it can never receive into would just stall. */
 export function laneHasInboxRecipient(commsEmail, laneId) {
-    return (commsEmail.recipients ?? []).some((recipient) => recipient.lane === laneId && recipient.address !== undefined);
+    return inboxRecipientFor(commsEmail, laneId) !== undefined;
 }
 /** Mid-run inbox-surface render cadence (ms). Coarse enough that the per-tick `cat` + file writes stay
  *  cheap; fine enough that a verification email is visible seconds after the app sends it. */
@@ -195,20 +207,22 @@ function resolvePerLaneSandboxMs(config) {
         ?? timeoutMs + (provisionedRoute ? SUBJECT_PROVISION_BUDGET_MS + stateBudgetMs : 0) + SANDBOX_TIMEOUT_BUFFER_MS;
 }
 /**
- * Effective in-flight lane bound. Default min(laneCount, 3); a declared execution.concurrency
- * clamps to [1, laneCount]; the env override may only LOWER it (never raise concurrent paid
- * desktops — invariant 3). Pure given (config, laneCount, env).
+ * Effective in-flight lane bound. Defaults to laneCount — every declared seat runs at once,
+ * because a throttle nobody asked for silently turns "N actors live" into waves (#350); total
+ * session count and spend are the same either way, only wall-clock and simultaneity differ. A
+ * declared execution.concurrency is a CAP, clamped to [1, laneCount]; the env override may only
+ * LOWER it (never raise concurrent paid desktops — invariant 3), and a lowering is reported via
+ * envLoweredFrom so the plan never silently disagrees with the manifest. Pure given
+ * (config, laneCount, env).
  */
 function resolveCuaConcurrency(config, laneCount, env) {
     const declared = config.execution?.concurrency;
-    const base = declared !== undefined
-        ? Math.min(Math.max(1, declared), laneCount)
-        : Math.min(laneCount, DEFAULT_CUA_CONCURRENCY);
+    const base = Math.max(1, declared !== undefined ? Math.min(Math.max(1, declared), laneCount) : laneCount);
     const envLower = readPositiveInt(env[CUA_MAX_CONCURRENCY_ENV], 0);
-    if (envLower > 0) {
-        return Math.max(1, Math.min(base, envLower, laneCount));
+    if (envLower > 0 && envLower < base) {
+        return { bound: Math.max(1, Math.min(base, envLower, laneCount)), envLoweredFrom: base };
     }
-    return Math.max(1, base);
+    return { bound: base };
 }
 /** Build the lane specs AND the public plan from a config (pure). countOverride is the CLI
  *  --count for homogeneous fan-out (ignored when a `lanes` roster is declared). */
@@ -250,13 +264,15 @@ function laneSpecsAndPlan(config, opts = {}) {
             traceArtifactPath: laneCount === 1 ? "actor.json" : `actors/${streamId}.json`
         });
     }
-    const concurrency = resolveCuaConcurrency(config, laneCount, env);
+    const resolved = resolveCuaConcurrency(config, laneCount, env);
+    const concurrency = resolved.bound;
     const perLaneSessionBudgetMs = config.execution?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
     const perLaneSandboxMs = resolvePerLaneSandboxMs(config);
     const plan = {
         strategy: CUA_FANOUT_STRATEGY,
         laneCount,
         concurrency,
+        ...(resolved.envLoweredFrom === undefined ? {} : { envLoweredConcurrencyFrom: resolved.envLoweredFrom }),
         waves: Math.ceil(laneCount / concurrency),
         perLaneSessionBudgetMs,
         worstCaseSandboxMinutes: Math.round((laneCount * perLaneSandboxMs) / 60_000),
@@ -390,7 +406,7 @@ export function resolveCuaLanePlan(config, opts = {}) {
  *  digests, and budgets only — no prompt text, no secrets). */
 function emitPreflightPlan(plan, labId) {
     const lines = [];
-    lines.push(`humanish cua fan-out plan (${labId}): ${plan.laneCount} lane(s), strategy ${plan.strategy}, concurrency ${plan.concurrency}, ${plan.waves} wave(s).`);
+    lines.push(`humanish cua fan-out plan (${labId}): ${plan.laneCount} lane(s), strategy ${plan.strategy}, concurrency ${plan.concurrency}${plan.envLoweredConcurrencyFrom === undefined ? "" : ` (lowered from ${plan.envLoweredConcurrencyFrom} by ${CUA_MAX_CONCURRENCY_ENV})`}, ${plan.waves} wave(s).`);
     lines.push(`  per-lane session budget ${Math.round(plan.perLaneSessionBudgetMs / 1000)}s; worst-case ~${plan.worstCaseSandboxMinutes} sandbox-minutes total${plan.dryRun ? " (dry-run: $0)" : ""}.`);
     for (const lane of plan.lanes) {
         lines.push(`  - ${formatLanePlanEntry(lane)}`);
@@ -1145,6 +1161,9 @@ export async function runCuaLane(spec, deps) {
             lifecycle: { onTimeout: "kill" }
         }, config.execution?.desktop?.template);
         sandboxId = desktop.sandboxId;
+        // #358 salvage: journal the id to disk before any work — an interrupted run reclaims by
+        // exact recorded id (`humanish reclaim`), never by enumerating the account.
+        await appendSandboxReceipt(deps.artifactRoot, { at: new Date(deps.now()).toISOString(), laneId: spec.laneId, sandboxId, timeoutMs: deps.perLaneSandboxMs });
         // The billed span starts the instant the sandbox exists.
         sandboxCreatedAtMs = deps.now();
         if (deps.hooks.prepareDesktop) {
@@ -1318,7 +1337,7 @@ export async function runCuaLane(spec, deps) {
                 // Tell the persona where its inbox is — but only when comms is live AND this lane has a declared
                 // recipient it can actually receive mail into (else it would stall on an inbox that stays empty).
                 instructions: commsEmail && commsInboxUrl && deployedComms?.ready && laneHasInboxRecipient(commsEmail, spec.laneId)
-                    ? withInboxMission(spec, commsInboxUrl).instructions
+                    ? withInboxMission(spec, commsInboxUrl, inboxRecipientFor(commsEmail, spec.laneId)?.address).instructions
                     : spec.instructions,
                 persona: spec.persona,
                 timeoutMs: deps.timeoutMs,
@@ -1436,6 +1455,12 @@ export async function runCuaLane(spec, deps) {
                         // the address the app actually sends to (e.g. the one the persona surface will sign up with).
                         warnings.push(`Comms catch captured ${collected.captured} email send(s) but none matched a declared recipient inbox — no comms evidence written. Declare comms.email.recipients[].address to match the address the app sends to.`);
                     }
+                    else {
+                        // Zero captures is the silent-broken shape (#351): the app never posted to the catch at
+                        // all, so the personas stared at an empty inbox. Most common cause: the app does not
+                        // actually read the declared injectEnv var for its email API base URL.
+                        warnings.push(`Comms catch captured ZERO email sends — the app never delivered mail through the catch. Verify the app reads ${commsEmail.injectEnv} for its email API base URL (an SDK that ignores it sends real mail or throws) and that the flow reached an email step.`);
+                    }
                 }
                 catch (error) {
                     warnings.push(`Comms evidence collection failed (run continues; sandbox still torn down): ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
@@ -1468,6 +1493,18 @@ export async function runCuaLane(spec, deps) {
             // Close the billed span for BOTH the killed and kept-for-debug paths (a kept sandbox is
             // still billed until its server-side timeout, so the honest span ends here either way).
             sandboxTornDownAtMs = deps.now();
+            // The lane's live stream is now a dead page whichever teardown path ran (killed, kept, or
+            // kill-failed-awaiting-TTL) — tell the watch overlay so the tile falls back to recorded
+            // evidence instead of "sandbox not found" (#357). Guarded: a viewer callback must never
+            // break teardown.
+            if (streamUrl !== undefined) {
+                try {
+                    await deps.hooks.onRuntimeStreamEnded?.({ laneId: spec.laneId, simId: spec.simId, streamId: spec.streamId });
+                }
+                catch {
+                    // viewer-side only; nothing to record
+                }
+            }
         }
     }
     // Host-side approximation of the E2B desktop's billed lifetime; feeds the desktop-minute cost
@@ -1589,7 +1626,10 @@ async function runInProcessLane(spec, deps) {
  * pinned reason + a fail-fast event; mission verdicts never trip it). Each lane tears down ITS
  * OWN sandbox by id; nothing here ever enumerates.
  */
-async function runCuaLanes(laneSpecs, deps, concurrency) {
+/** Exported for the #342 total-runner tests: the injectable runner lets a test make one lane
+ *  THROW (the exact class the guard exists for) without a live sandbox. Production always uses
+ *  the default. */
+export async function runCuaLanes(laneSpecs, deps, concurrency, runLane = runCuaLane) {
     const failFast = { tripped: false, reason: "" };
     let resolveGate;
     let rejectGate;
@@ -1612,21 +1652,48 @@ async function runCuaLanes(laneSpecs, deps, concurrency) {
         if (failFast.tripped) {
             return blockedLaneOutcome(spec, `skipped: ${failFast.reason}`);
         }
-        const outcome = await runCuaLane(spec, {
-            ...deps,
-            ...(index === 0
-                ? {
-                    signalProvisioned: (ok) => {
-                        if (ok) {
-                            resolveGate?.();
-                        }
-                        else {
-                            rejectGate?.();
+        // The lane runner is TOTAL (#342): every exit path returns a recorded outcome. Without this
+        // guard, one lane's late throw (e.g. its trace write hitting ENOSPC after its own sandbox was
+        // already torn down) rejected the whole map while sibling workers kept launching sandboxes
+        // nobody would ever record — the run spent money and then reported nothing.
+        let outcome;
+        try {
+            outcome = await runLane(spec, {
+                ...deps,
+                ...(index === 0
+                    ? {
+                        signalProvisioned: (ok) => {
+                            if (ok) {
+                                resolveGate?.();
+                            }
+                            else {
+                                rejectGate?.();
+                            }
                         }
                     }
-                }
-                : {})
-        });
+                    : {})
+            });
+        }
+        catch (error) {
+            // Lane 0 may have thrown before signaling the provisioning gate — release the followers as
+            // blocked rather than leaving them awaiting a gate that will never settle.
+            if (index === 0)
+                rejectGate?.();
+            const detail = redactText(toErrorMessage(error));
+            outcome = {
+                spec,
+                killed: false,
+                streamUrlPresent: false,
+                screenshots: [],
+                stateStepRecords: [],
+                phaseRecords: [],
+                warnings: [],
+                noEngagement: false,
+                selfReportedBlocker: false,
+                harnessError: true,
+                sessionError: `lane runner threw outside the session guard: ${detail}`
+            };
+        }
         if (outcome.harnessError && !failFast.tripped) {
             failFast.tripped = true;
             failFast.reason = `a prior lane (${outcome.spec.laneId}) ended in a harness error (fail-fast)`;
@@ -1794,6 +1861,18 @@ export async function runCuaActorLab(options) {
             if (liveObserver) {
                 attachObserverRuntimeStreamUrls(liveObserver, runtimeStreamUrls);
             }
+        },
+        onRuntimeStreamEnded: async (stream) => {
+            await hooks.onRuntimeStreamEnded?.(stream);
+            // Mark, never remove: the tile needs to KNOW the live view ended (and say so) rather than
+            // have the stream silently vanish from the overlay (#357).
+            for (const entry of runtimeStreamUrls) {
+                if (entry.streamId === stream.streamId)
+                    entry.ended = true;
+            }
+            if (liveObserver) {
+                attachObserverRuntimeStreamUrls(liveObserver, runtimeStreamUrls);
+            }
         }
     };
     const env = hooks.env ?? process.env;