humanish 0.45.0 → 0.47.0

package/dist/cua-actor-lab.js

@@ -579,6 +579,7 @@ function blockedLaneOutcome(spec, reason) {
         skippedReason: reason,
         noEngagement: false,
         selfReportedBlocker: false,
+        reportedFriction: false,
         harnessError: false
     };
 }
@@ -1073,13 +1074,47 @@ async function startDesktopStream(desktop, browserWindowId) {
         await desktop.stream.start({ requireAuth: true });
     }
 }
-function completionReasonContradictsGoal(reason) {
-    const text = stripQuotedSpans(stripNegatedNonBlockerPhrases(reason.toLowerCase()));
+function hasBlockerLanguage(text) {
     return /\b(can'?t|cannot|could not|unable|blocked|blocker|failed|invalid|not set)\b/.test(text)
         || /\b(shows|showing|hit|encountered|returned|got)\b.{0,80}\berror\b/.test(text)
         || /\berror[:.]/.test(text)
         || /what would you like me to do|please tell me|need (the )?(task|credentials|instructions)/.test(text);
 }
+/** The friction scan (inclusive): does the narrative report ANY blocker-shaped language,
+ *  resolved or not? Feeds the participants `reportedFriction` tally and feedback candidates. */
+function completionReasonContradictsGoal(reason) {
+    return hasBlockerLanguage(stripQuotedSpans(stripNegatedNonBlockerPhrases(reason.toLowerCase())));
+}
+/** The verdict scan (strict): like the friction scan, but resolved-arc segments are stripped
+ *  first — failure narration the participant itself reports as overcome is friction on the
+ *  road, not a blocker at the destination (#453). */
+function completionReasonBlocksVerdict(reason) {
+    return hasBlockerLanguage(stripResolvedArcSegments(stripQuotedSpans(stripNegatedNonBlockerPhrases(reason.toLowerCase()))));
+}
+// A failure segment counts as a resolved arc when the recovery is self-reported either in the
+// SAME segment ("the import failed but then went through") or — the common report shape — in the
+// immediately FOLLOWING segment as a retry/alternative that succeeded ("my first import failed
+// with a parser error. A simpler SQL import succeeded."). The lookahead demands the retry flavor
+// on purpose: unrelated praise ("Separately, the search box worked") must never launder an
+// unresolved failure. "Login failed so I gave up" has no recovery anywhere and stays a blocker.
+// (#453 — the run-1 false negative: a defect report after demonstrated success failed the lane,
+// an incentive inversion against exactly the participant behavior a study wants most.)
+const RESOLUTION_TERMS = /\b(succeed(?:ed|s)?|success(?:ful|fully)?|worked|works around|then worked|now works?|resolved|fixed|recovered|got it working|went through)\b/;
+const RETRY_RESOLUTION = /\b(simpler|simplified|retry(?:ing)?|retried|second (?:attempt|try)|another (?:attempt|try|approach)|different (?:approach|way|route)|instead|then|eventually|after that)\b[^.!?\n]{0,80}\b(succeed(?:ed|s)?|success(?:ful|fully)?|worked|went through|completed|passed)\b/;
+/** Drop sentence/bullet segments whose failure language is part of a self-reported RESOLVED arc. */
+function stripResolvedArcSegments(text) {
+    const segments = text.split(/(?<=[.!?])\s+|\n+/);
+    return segments
+        .filter((segment, index) => {
+        if (!hasBlockerLanguage(segment))
+            return true;
+        if (RESOLUTION_TERMS.test(segment))
+            return false;
+        const next = segments[index + 1];
+        return !(next !== undefined && RETRY_RESOLUTION.test(next));
+    })
+        .join(" ");
+}
 function stripNegatedNonBlockerPhrases(text) {
     return text
         .replace(/\bno\s+(?:real\s+|remaining\s+|actual\s+)?(?:blocker|blockers|blocking issue|blocking issues|error|errors|failure|failures)\s+(?:was\s+|were\s+)?(?:encountered|observed|found|hit|seen|reported|detected)\b/g, "")
@@ -1108,9 +1143,23 @@ function traceHasStopWhenMatch(session) {
  * the goal AND the run's own stop predicate did NOT fire. A matched stopWhen is independent,
  * structured completion evidence, so it overrides a text scan of the free-form narrative — which can
  * otherwise trip on the subject app's OWN quoted copy (e.g. a relayed "cannot be undone" banner).
- * Returns the offending reason, or undefined when the lane is a clean pass. Exported for testing.
+ * Resolved-arc segments never block the verdict (#453). Returns the offending reason, or undefined
+ * when the lane is a clean pass. Exported for testing.
  */
 export function resolveSelfReportedBlocker(session) {
+    return session?.completionReason === "goal_satisfied"
+        && completionReasonBlocksVerdict(session.reason)
+        && !traceHasStopWhenMatch(session)
+        ? session.reason
+        : undefined;
+}
+/**
+ * The friction read of the same narrative (#453): everything the verdict scan counts PLUS
+ * resolved arcs — a participant who hit a wall, got past it, and said so has reported friction
+ * worth a tally count and a feedback candidate, without costing the lane its pass. Same
+ * quoted-copy and stopWhen discipline as the verdict resolver. Exported for testing.
+ */
+export function resolveSelfReportedFriction(session) {
     return session?.completionReason === "goal_satisfied"
         && completionReasonContradictsGoal(session.reason)
         && !traceHasStopWhenMatch(session)
@@ -1498,7 +1547,10 @@ export async function runCuaLane(spec, deps) {
                     }),
                 ...(deps.onObservedUrl === undefined ? {} : { onObservedUrl: deps.onObservedUrl }),
                 ...(deps.onMessage === undefined ? {} : { onMessage: deps.onMessage }),
-                ...(deps.onScreenshot === undefined ? {} : { onScreenshot: deps.onScreenshot })
+                ...(deps.onScreenshot === undefined ? {} : { onScreenshot: deps.onScreenshot }),
+                ...(deps.onTrace === undefined
+                    ? {}
+                    : { onTrace: (items) => deps.onTrace?.(spec.laneId, items) })
             };
             session = await deps.runSession(sessionOptions);
         }
@@ -1663,6 +1715,7 @@ export async function runCuaLane(spec, deps) {
     }
     const blockerReason = resolveSelfReportedBlocker(session);
     const selfReportedBlocker = blockerReason !== undefined;
+    const reportedFriction = resolveSelfReportedFriction(session) !== undefined;
     if (selfReportedBlocker) {
         warnings.push(`Actor returned goal_satisfied while its final message describes a blocker or asks for missing instructions — NOT counted as a pass: ${redactText(deps.scrubKnownValues(blockerReason))}`);
     }
@@ -1684,6 +1737,7 @@ export async function runCuaLane(spec, deps) {
         warnings,
         noEngagement,
         selfReportedBlocker,
+        reportedFriction,
         harnessError,
         ...(failureCode === undefined ? {} : { failureCode }),
         ...(commsArtifactPath === undefined ? {} : { commsArtifactPath })
@@ -1732,6 +1786,7 @@ async function runInProcessLane(spec, deps) {
     }
     const blockerReason = resolveSelfReportedBlocker(session);
     const selfReportedBlocker = blockerReason !== undefined;
+    const reportedFriction = resolveSelfReportedFriction(session) !== undefined;
     if (selfReportedBlocker) {
         warnings.push(`Actor returned goal_satisfied while its final message describes a blocker or asks for missing instructions — NOT counted as a pass: ${blockerReason}`);
     }
@@ -1747,6 +1802,7 @@ async function runInProcessLane(spec, deps) {
         warnings,
         noEngagement,
         selfReportedBlocker,
+        reportedFriction,
         harnessError: sessionError !== undefined || session?.completionReason === "harness_error",
         entryKind: "local-app"
     };
@@ -1821,6 +1877,7 @@ export async function runCuaLanes(laneSpecs, deps, concurrency, runLane = runCua
                 warnings: [],
                 noEngagement: false,
                 selfReportedBlocker: false,
+                reportedFriction: false,
                 harnessError: true,
                 sessionError: `lane runner threw outside the session guard: ${detail}`
             };
@@ -2246,7 +2303,13 @@ export async function runCuaActorLab(options) {
             return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", `local-tree packing failed: ${redactText(scrubKnownValues(toErrorMessage(error)))}`, descriptor.id);
         }
     }
+    // Live-trace flush seam (#441): assigned by the attached-Observer block below when a live
+    // run has an in-progress bundle to grow; lanes call it through deps.onTrace. Declared here
+    // (before deps) so deps can reference it as a stable indirection.
+    let flushLiveTrace;
+    let stopLiveFlush;
     const deps = {
+        onTrace: (laneId, items) => flushLiveTrace?.(laneId, items),
         config,
         descriptor,
         appUrl,
@@ -2335,6 +2398,79 @@ export async function runCuaActorLab(options) {
             "Live CUA Observer is attached before final verification; stream auth URLs are runtime-only and are not persisted."
         ]);
         await options.onObserverReady(liveObserver);
+        // Incremental live flush (#441): as each lane's loop reports its recorded-so-far items,
+        // rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
+        // Observer's 5s poll sees the timeline grow. Throttled (one write per interval, trailing
+        // write guaranteed), serialized (never two writers), and CLOSED before the final artifact
+        // write so a stale flush can never resurrect the in-progress bundle. A flush failure is
+        // swallowed: mid-run observability must never break the run itself.
+        const streamIdByLane = new Map(laneSpecs.map((spec) => [spec.laneId, spec.streamId]));
+        const liveItemsByStream = new Map();
+        let flushWriting;
+        let flushDirty = false;
+        let flushClosed = false;
+        let flushTimer;
+        let lastFlushAtMs = 0;
+        const FLUSH_MIN_INTERVAL_MS = 2_000;
+        const flushNow = async () => {
+            while (flushDirty && !flushClosed) {
+                flushDirty = false;
+                lastFlushAtMs = Date.now();
+                const updatedAt = new Date(lastFlushAtMs).toISOString();
+                const patched = {
+                    ...inProgressBundle,
+                    streams: inProgressBundle.streams.map((stream) => {
+                        const liveItems = liveItemsByStream.get(stream.id);
+                        return liveItems === undefined
+                            ? stream
+                            : { ...stream, liveActor: { schema: "humanish.live-actor.v1", updatedAt, items: [...liveItems] } };
+                    })
+                };
+                try {
+                    await writeCuaRunArtifacts(patched, createdAt, runPaths);
+                }
+                catch {
+                    // Swallowed by design; the final write is the evidence of record.
+                }
+            }
+            flushWriting = undefined;
+        };
+        const scheduleFlush = () => {
+            if (flushClosed || flushWriting !== undefined)
+                return;
+            const sinceMs = Date.now() - lastFlushAtMs;
+            if (sinceMs >= FLUSH_MIN_INTERVAL_MS) {
+                flushWriting = flushNow();
+                return;
+            }
+            if (flushTimer === undefined) {
+                flushTimer = setTimeout(() => {
+                    flushTimer = undefined;
+                    scheduleFlush();
+                }, FLUSH_MIN_INTERVAL_MS - sinceMs);
+                flushTimer.unref?.();
+            }
+        };
+        flushLiveTrace = (laneId, items) => {
+            // An empty snapshot (the initial observation on a frameless route) carries no
+            // evidence worth a disk write; the first real item triggers the first flush.
+            if (items.length === 0)
+                return;
+            const streamId = streamIdByLane.get(laneId);
+            if (streamId === undefined)
+                return;
+            liveItemsByStream.set(streamId, items.slice());
+            flushDirty = true;
+            scheduleFlush();
+        };
+        stopLiveFlush = async () => {
+            flushClosed = true;
+            if (flushTimer !== undefined) {
+                clearTimeout(flushTimer);
+                flushTimer = undefined;
+            }
+            await flushWriting;
+        };
     }
     // Run lanes (dry-run runs none). In-process is always one lane.
     let outcomes;
@@ -2352,6 +2488,10 @@ export async function runCuaActorLab(options) {
             failFastReason = ran.failFastReason;
         }
     }
+    // Close the live flush BEFORE any final artifact work: no new flush may start, and an
+    // in-flight one is awaited, so the final bundle write can never race a stale in-progress
+    // rewrite (which would resurrect `liveActor` after completion).
+    await stopLiveFlush?.();
     const externalCommsWarnings = [];
     // Adopter-hosted drain (#380): once per RUN, after every lane finished — the catch is one
     // shared external endpoint, not a per-sandbox file. Same routing and digest-only artifact as
@@ -3172,7 +3312,7 @@ export function participantFeedbackCandidates(args) {
         const session = lane.session;
         if (session === undefined)
             continue;
-        const friction = resolveSelfReportedBlocker(session);
+        const friction = resolveSelfReportedFriction(session);
         const abandoned = session.status === "abandoned";
         if (friction === undefined && !abandoned)
             continue;
@@ -3873,7 +4013,7 @@ export function buildCuaFanoutBundle(args) {
         ? tallyParticipantOutcomes(terminalOutcomes.map((outcome) => outcome.session.status), 
         // A participant who reached the goal AND told you the road there was broken is the most
         // useful result a study produces; reporting only the outcome would bury it.
-        terminalOutcomes.map((outcome) => outcome.selfReportedBlocker === true))
+        terminalOutcomes.map((outcome) => outcome.reportedFriction === true))
         : undefined;
     // The study funnel: per-task completion rates across every session that measured one. This is
     // "where did people get stuck" as data, next to WHO got stuck (participants) above.