humanish 0.126.0 → 0.127.0

package/dist/run/judge.d.ts

@@ -1,4 +1,5 @@
 import type { ActorCompletionReason, ActorStatus, ParticipantDeclaredOutcome } from "../actors/contract.js";
+import type { ClockEnd } from "../actors/goal-source.js";
 import type { ReviewSummary } from "./bundle.js";
 export type Verdict = ReviewSummary["verdict"];
 /** How a finished session ended, as the blocker rule reads it. */
@@ -43,6 +44,12 @@ export interface ParticipantFacts {
     noEngagement: boolean;
     /** selfReportedBlocker held for its session. */
     selfReportedBlocker: boolean;
+    /**
+     * Its session ran until its scheduled end or session cap without the participant declaring it
+     * reached the goal (ranUntilClockEnd). A pass counts under `ranUntilEnd` in place of
+     * `reachedGoal`.
+     */
+    ranUntil?: ClockEnd;
 }
 /** The participant facts its bundle and result can name. */
 export interface ParticipantRecordFacts extends ParticipantFacts {

package/dist/run/judge.js

@@ -68,12 +68,12 @@ export function judgeParticipantRecords(participants, wording = {}) {
                 : `${participant.id ?? "Participant"}: ${participant.skippedReason ?? participant.sessionError ?? participant.reason ?? "did not pass"}`,
         };
     });
-    const terminal = records.filter((_, index) => participants[index].status !== undefined && !participants[index].inProgress);
+    const ended = (participant) => participant.status !== undefined && !participant.inProgress;
+    const terminal = records.filter((_, index) => ended(participants[index]));
+    const terminalFacts = participants.filter(ended);
     return {
         participants: records,
-        tally: tallyParticipantOutcomes(terminal.map((participant) => participant.judgedStatus), participants
-            .filter((participant) => participant.status !== undefined && !participant.inProgress)
-            .map((participant) => participant.reportedFriction === true)),
+        tally: tallyParticipantOutcomes(terminal.map((participant) => participant.judgedStatus), terminalFacts.map((participant) => participant.reportedFriction === true), terminalFacts.map((participant) => participant.ranUntil !== undefined)),
     };
 }
 function participantNotPassedMessage(participant, wording) {

package/dist/run/notes.js

@@ -21,7 +21,7 @@ const refuse = (code, message) => ({
 });
 /**
  * The stream id a note's participant names: a stream id, or the participant's own id from the study
- * (`charge-nurse`). Both kinds of id are matched, so a name that is one stream's id and another
+ * (`support-lead`). Both kinds of id are matched, so a name that is one stream's id and another
  * stream's study id is refused, naming both, as is a study id that two streams record. Otherwise
  * the refusal names the run's participants by caption, with the id to type for each.
  */

package/dist/run/outcomes.d.ts

@@ -6,7 +6,13 @@ import type { ParticipantOutcomes, ReviewSummary, RunTaskFunnel } from "./bundle
  *  `total` but nowhere else, so the parts can never exceed the whole. */
 export declare function tallyParticipantOutcomes(statuses: readonly ActorStatus[], 
 /** Per-participant: did this one report friction or a defect? Same order as `statuses`. */
-reportedFriction?: readonly boolean[]): ParticipantOutcomes;
+reportedFriction?: readonly boolean[], 
+/**
+ * Per-participant: did its session run until its scheduled end or session cap without it
+ * declaring that it reached the goal (ranUntilClockEnd)? Same order as `statuses`. Such a pass
+ * counts under `ranUntilEnd` in place of `reachedGoal`.
+ */
+ranUntilEnd?: readonly boolean[]): ParticipantOutcomes;
 /** Roll per-participant funnels up into the study funnel. Undefined when nothing measured one. */
 export declare function aggregateTaskFunnels(funnels: readonly TaskFunnel[]): RunTaskFunnel | undefined;
 /** The funnel as one line, denominator on every number: `signup 2/2 · verify-email 1/2`. */
@@ -53,7 +59,7 @@ export declare function formatParticipantOutcomes(outcomes: ParticipantOutcomes,
 export declare function participantOutcomeDetails(streams: readonly {
     actor?: unknown;
     status?: unknown;
-}[]): ParticipantOutcomeDetail[];
+}[], goalSourceOf?: (actor: unknown, recordedStatus: unknown) => CuaGoalSource | undefined): ParticipantOutcomeDetail[];
 /** Refresh a CUA completion claim from recorded traces, leaving original evidence and enums intact. */
 export declare function withCuaReviewProvenance(review: ReviewSummary, streams: readonly {
     actor?: unknown;

package/dist/run/outcomes.js

@@ -1,13 +1,19 @@
 import { ACTOR_STATUSES } from "../actors/contract.js";
-import { cuaGoalSource, isCuaTrace, CUA_COMPLETION_NOTE, } from "../actors/goal-source.js";
-import { actorEnding } from "../actors/stop-cause.js";
+import { cuaEndpointSource, cuaGoalSource, isClockEnd, isCuaTrace, CUA_COMPLETION_NOTE, } from "../actors/goal-source.js";
+import { actorEnding, actorStopCauseLabel } from "../actors/stop-cause.js";
 import { plural } from "./text.js";
 import { isNonNegativeSafeInteger, isRecord } from "./type-guards.js";
 /** Tally participant outcomes from actor statuses. Statuses this does not recognise are counted in
  *  `total` but nowhere else, so the parts can never exceed the whole. */
 export function tallyParticipantOutcomes(statuses, 
 /** Per-participant: did this one report friction or a defect? Same order as `statuses`. */
-reportedFriction = []) {
+reportedFriction = [], 
+/**
+ * Per-participant: did its session run until its scheduled end or session cap without it
+ * declaring that it reached the goal (ranUntilClockEnd)? Same order as `statuses`. Such a pass
+ * counts under `ranUntilEnd` in place of `reachedGoal`.
+ */
+ranUntilEnd = []) {
     const tally = {
         total: statuses.length,
         reachedGoal: 0,
@@ -17,8 +23,11 @@ reportedFriction = []) {
         harnessFailed: 0,
         reportedFriction: reportedFriction.filter(Boolean).length,
     };
-    for (const status of statuses) {
-        if (status === "passed")
+    let clockEnds = 0;
+    statuses.forEach((status, index) => {
+        if (status === "passed" && ranUntilEnd[index] === true)
+            clockEnds += 1;
+        else if (status === "passed")
             tally.reachedGoal += 1;
         else if (status === "abandoned")
             tally.abandoned += 1;
@@ -28,8 +37,8 @@ reportedFriction = []) {
             tally.blocked += 1;
         else if (status === "failed")
             tally.harnessFailed += 1;
-    }
-    return tally;
+    });
+    return clockEnds === 0 ? tally : { ...tally, ranUntilEnd: clockEnds };
 }
 /** Roll per-participant funnels up into the study funnel. Undefined when nothing measured one. */
 export function aggregateTaskFunnels(funnels) {
@@ -86,15 +95,38 @@ export function formatRunTaskFunnel(funnel) {
     })
         .join(" · ");
 }
+/**
+ * "1 ran until its session cap", "2 ran until their scheduled end", grouped by clock end, most
+ * first. Clock ends the details cannot account for get one line that names both.
+ */
+function ranUntilPhrases(count, details) {
+    const words = (n, end) => n === 1 ? `1 ran until its ${end}` : `${n} ran until their ${end}`;
+    const ends = details.flatMap((entry) => (isClockEnd(entry.goalSource) ? [entry.goalSource] : []));
+    if (ends.length !== count)
+        return [words(count, "scheduled end or session cap")];
+    return ["session_cap", "scheduled_end"]
+        .map((end) => [end, ends.filter((entry) => entry === end).length])
+        .filter(([, n]) => n > 0)
+        .sort(([, m], [, n]) => n - m)
+        .map(([end, n]) => words(n, actorStopCauseLabel(end)));
+}
 function participantCompletionLine(outcomes, terminalCauses) {
-    const completions = terminalCauses.filter((entry) => entry.status === "passed");
+    const passed = terminalCauses.filter((entry) => entry.status === "passed");
+    // A bundle without `ranUntilEnd` either has no such clock end or predates the count and tallied
+    // its clock ends under reachedGoal. Those stay among its completions, and the breakdown names
+    // them, so a re-read never changes a recorded count.
+    const completions = outcomes.ranUntilEnd === undefined
+        ? passed
+        : passed.filter((entry) => !isClockEnd(entry.goalSource));
     const reported = completions.filter((entry) => entry.goalSource === "participant_report").length;
     const matched = completions.filter((entry) => entry.goalSource === "condition_matched").length;
+    const clockEnds = completions.filter((entry) => isClockEnd(entry.goalSource));
     let goalLine = outcomes.reachedGoal === 0
         ? `0/${outcomes.total} recorded completions`
         : `${outcomes.reachedGoal}/${outcomes.total} reached the goal`;
     if (outcomes.reachedGoal > 0 && terminalCauses.some((entry) => entry.goalSource !== undefined)) {
         const count = `${outcomes.reachedGoal}/${outcomes.total}`;
+        const other = outcomes.reachedGoal - reported - matched - clockEnds.length;
         goalLine =
             completions.length !== outcomes.reachedGoal
                 ? `${count} recorded completions (completion source unavailable)`
@@ -105,9 +137,8 @@ function participantCompletionLine(outcomes, terminalCauses) {
                         : `${count} recorded completions (${[
                             reported > 0 ? `${reported} participant-reported` : undefined,
                             matched > 0 ? `${matched} condition-matched` : undefined,
-                            outcomes.reachedGoal - reported - matched > 0
-                                ? `${outcomes.reachedGoal - reported - matched} other or unavailable source`
-                                : undefined,
+                            ...(clockEnds.length > 0 ? ranUntilPhrases(clockEnds.length, clockEnds) : []),
+                            other > 0 ? `${other} other or unavailable source` : undefined,
                         ]
                             .filter(Boolean)
                             .join(", ")})`;
@@ -124,6 +155,8 @@ export function sessionEndingInWords(trace) {
             const source = cuaGoalSource(trace);
             if (source === "participant_report")
                 return "reported reaching the goal";
+            if (isClockEnd(source))
+                return `ran until its ${actorStopCauseLabel(source)}`;
             return source === "condition_matched" ? "met its completion condition" : "reached the goal";
         }
         case "turn_completed":
@@ -178,6 +211,10 @@ export function formatParticipantOutcomes(outcomes, terminalCauses = []) {
     if (outcomes.total === 0)
         return "no participants reached a terminal state";
     const parts = [participantCompletionLine(outcomes, terminalCauses)];
+    // Passed at the clock without declaring that they reached the goal: next to the completions,
+    // and never counted among them.
+    if (outcomes.ranUntilEnd !== undefined && outcomes.ranUntilEnd > 0)
+        parts.push(...ranUntilPhrases(outcomes.ranUntilEnd, terminalCauses.filter((entry) => entry.status === "passed")));
     // Detail may explain a recorded outcome, but must never change its count or invent a match
     // between a tally and an incomplete set of traces.
     const append = (count, statuses, fallback) => {
@@ -212,12 +249,12 @@ export function formatParticipantOutcomes(outcomes, terminalCauses = []) {
     return parts.join(", ");
 }
 /** Presentation details tolerate optional legacy actor payloads without changing their tallies. */
-export function participantOutcomeDetails(streams) {
+export function participantOutcomeDetails(streams, goalSourceOf = cuaGoalSource) {
     return streams.flatMap((stream) => {
         if (!isRecord(stream.actor))
             return [];
         const actor = stream.actor;
-        const goalSource = cuaGoalSource(actor, stream.status);
+        const goalSource = goalSourceOf(actor, stream.status);
         if (!ACTOR_STATUSES.includes(String(actor.status))) {
             return goalSource === "unavailable" ? [{ status: "passed", goalSource }] : [];
         }
@@ -257,6 +294,9 @@ export function withCuaReviewProvenance(review, streams) {
     const { reachedGoal, total } = review.participants;
     const bareLine = `${reachedGoal}/${total} reached the goal`;
     const qualifiedLine = participantCompletionLine(review.participants, details);
+    // Earlier releases qualified the count with the endpoint source (cuaEndpointSource), which
+    // reads a clock end as a participant report.
+    const endpointLine = participantCompletionLine(review.participants, participantOutcomeDetails(streams, cuaEndpointSource));
     // A summary with no count gets it in a header. Earlier releases wrote a header in other words.
     const header = `${plural(total, "participant")} took part: ${outcomes}.${tasks} `;
     const olderHeader = `Run gate: ${review.verdict}. Participants: ${outcomes}.${tasks} Recorded summary: `;
@@ -266,7 +306,9 @@ export function withCuaReviewProvenance(review, streams) {
             ? review.summary.split(bareLine).join(qualifiedLine)
             : review.summary.includes(qualifiedLine)
                 ? review.summary
-                : `${header}${review.summary}`;
+                : review.summary.includes(endpointLine)
+                    ? review.summary.split(endpointLine).join(qualifiedLine)
+                    : `${header}${review.summary}`;
     return {
         ...review,
         summary,

package/dist/study/arrivals.d.ts

@@ -6,18 +6,41 @@ import type { RunParticipantArrival } from "../run/bundle.js";
 export declare const LATEST_START_AFTER_MS: number;
 /** Whether `value` is a start offset humanish runs: whole milliseconds from 0 to 24 hours. */
 export declare function isStartAfterMs(value: unknown): value is number;
-/** How long before its end a participant is told the time left, unless it declares `windDownMs`. */
-export declare const DEFAULT_WIND_DOWN_MS: number;
 /**
- * A participant's declared window: when it starts, and when it ends on the run's clock
- * (`endAfterMs`) or at the latest after its own session started (`maxSessionMs`).
+ * When a participant starts and how its session ends, resolved once from its participants entry
+ * when the plan builds the participant (participantSchedule). The plan, `study check`, the bundle
+ * estimate and the route read a participant's time from here.
  */
-export interface ParticipantWindow {
-    readonly id?: string;
+export interface ParticipantSchedule {
+    /** Its declared start, in ms after the run starts its participants; absent, with the run. */
     readonly startAfterMs?: number;
-    readonly endAfterMs?: number;
-    readonly maxSessionMs?: number;
-    readonly windDownMs?: number;
+    /**
+     * How its session ends, when it declares `endAfterMs` or `maxSessionMs`. Without either it works
+     * up to the study's session budget.
+     */
+    readonly end?: ScheduleEnd;
+}
+/**
+ * A declared end. A `scheduled_end` is `endAfterMs` on the run's clock and holds the participant
+ * until then; a `session_cap` is `maxSessionMs` from the start of the participant's own session,
+ * which it may end sooner. `windowMs` is how long it may work: from its start to its end, or its
+ * cap. `windDownMs` is how long before the end each turn tells it the time left. `sessionMs` is its
+ * session budget and how long it holds a slot: the window plus SCHEDULED_END_ROOM_MS.
+ */
+type ScheduleEnd = {
+    readonly windowMs: number;
+    readonly windDownMs: number;
+    readonly sessionMs: number;
+} & ({
+    readonly kind: "scheduled_end";
+    readonly endAfterMs: number;
+} | {
+    readonly kind: "session_cap";
+});
+/** A participant as the schedule's readers name it. */
+export interface ScheduledParticipant {
+    readonly id: string;
+    readonly schedule: ParticipantSchedule;
 }
 /**
  * Why a participant's declared end cannot run, or undefined: an end that is not a whole number of
@@ -33,11 +56,32 @@ export declare function windowReason(entry: {
     readonly windDownMs?: unknown;
 }, path: string): string | undefined;
 /**
- * A participant's session budget: with a declared end, its window plus SCHEDULED_END_ROOM_MS, and
- * with a cap, the cap plus the same room, in place of the study's `sessionMs` (execution.timeoutMs
- * or its default); else `sessionMs`.
+ * The schedule of a participants entry that windowReason accepts. A cap wins over an end, which
+ * windowReason refuses beside it anyway.
+ */
+export declare function participantSchedule(entry: {
+    readonly startAfterMs?: number;
+    readonly endAfterMs?: number;
+    readonly maxSessionMs?: number;
+    readonly windDownMs?: number;
+}): ParticipantSchedule;
+/**
+ * The schedule a rerun gives a participant: it starts with the rerun, and a scheduled end keeps its
+ * time on the rerun's clock and its wind-down, so its window runs from the rerun's start.
  */
-export declare function participantSessionMs(participant: ParticipantWindow, sessionMs: number): number;
+export declare function startingWithTheRun(schedule: ParticipantSchedule): ParticipantSchedule;
+/**
+ * A participant's own session budget and sandbox deadline. With an end or a cap it is the end's
+ * `sessionMs`, and the sandbox keeps the study sandbox's headroom over the study session on top;
+ * without one, the study's own.
+ */
+export declare function participantSession(schedule: ParticipantSchedule, study: {
+    readonly sessionMs: number;
+    readonly sandboxMs: number;
+}): {
+    sessionMs: number;
+    sandboxMs: number;
+};
 /**
  * When a participant's session ends: at a time on the run's clock, or at the latest a time after
  * its own session starts, which the route reads when the session starts.
@@ -53,25 +97,27 @@ export type ParticipantEnd = {
 };
 /**
  * How a participant that was due at `scheduledAt` (runOnSchedule's ScheduledStart) ends, or
- * undefined when it declares neither an end nor a cap. A participant that waited for a slot still
- * ends at its declared time, and still gets its whole cap.
+ * undefined without an end or a cap. A scheduled end comes its window after the participant's
+ * time, which is its `endAfterMs` on the run's clock, even when it waited for a slot; a cap is
+ * whole from wherever its session starts.
  */
-export declare function participantEnd(participant: ParticipantWindow, scheduledAt: number): ParticipantEnd | undefined;
+export declare function participantEnd(schedule: ParticipantSchedule, scheduledAt: number): ParticipantEnd | undefined;
 /**
  * Why the sandbox of the first participant whose window or cap passes `ceilingMs` cannot live that
- * long, or undefined. Its deadline is its session (participantSessionMs) plus `headroomMs`, what the
- * route adds to a session for setup and teardown (sandboxHeadroomMs).
+ * long, or undefined. Its deadline is its participantSession's, from the study's session budget and
+ * sandbox deadline.
  */
-export declare function windowDeadlineRefusal(participants: readonly ParticipantWindow[], sandbox: {
+export declare function windowDeadlineRefusal(participants: readonly ScheduledParticipant[], study: {
     readonly sessionMs: number;
-    readonly headroomMs: number;
+    readonly sandboxMs: number;
 }, ceilingMs: number): string | undefined;
 /**
  * Each participant's window for `study check`, when any participant declares an end or a cap: when
  * it starts and ends and when it is first told the time left, when it starts and its cap and how
- * far into its session it is first told the time left, or when it starts and its session budget.
+ * far into its session it is first told the time left, or when it starts and the study's
+ * `sessionMs`.
  */
-export declare function describeWindows(participants: readonly ParticipantWindow[], sessionMs: number): string | undefined;
+export declare function describeWindows(participants: readonly ScheduledParticipant[], sessionMs: number): string | undefined;
 /** The refusal of a start offset that is not one, naming its `field`. */
 export declare function startAfterMessage(field: string): string;
 /**
@@ -112,13 +158,13 @@ export interface StartQueue {
     readonly ownSlot?: number;
 }
 /**
- * The schedule a roster's declared offsets give under the queue (`undefined` is 0: the participant
- * starts with the run). Participants start in schedule order, by offset and then roster position,
- * each at its time or when a slot frees, whichever is later; this is the rule runOnSchedule
- * follows. `sessionsMs` gives a participant with a declared end its own session budget
- * (participantSessionMs); the others hold their slot for `queue.sessionMs`.
+ * The schedule a roster's participants give under the queue. Participants start in schedule order,
+ * by offset and then roster position, each at its time or when a slot frees, whichever is later;
+ * this is the rule runOnSchedule follows. A participant with an end or a cap holds its slot for its
+ * own session budget, and the others for `queue.sessionMs`. A participant whose slot would free
+ * only at or after its scheduled end takes none: the run skips it (pastEndReason).
  */
-export declare function planArrivals(offsets: readonly (number | undefined)[], queue: StartQueue, sessionsMs?: readonly number[]): ArrivalPlan;
+export declare function planArrivals(schedules: readonly ParticipantSchedule[], queue: StartQueue): ArrivalPlan;
 /**
  * The plan's schedule, after a "schedule:" label: the first and last start, and how many run at
  * once at the most.
@@ -128,13 +174,19 @@ export declare function describeArrivals(arrivals: ArrivalPlan): string;
  * A planner's arrival plan for its participants under the start queue, and the warnings the plan
  * records about it. A participant's desktop is created when it starts, so on computer use a late
  * start adds nothing to any sandbox's deadline; the provisioned shared world checks its app's
- * sandbox with servedScheduleRefusal. `lowered` is the warning that the E2B plan's limit runs the
- * roster in waves.
+ * sandbox with servedScheduleRefusal. `lowered` is participantsAtOnce's warning that the E2B plan's
+ * limit or HUMANISH_CUA_MAX_CONCURRENCY runs the roster in waves.
  */
-export declare function planStarts(participants: readonly ParticipantWindow[], queue: StartQueue, lowered: string | undefined): {
+export declare function planStarts(participants: readonly ScheduledParticipant[], queue: StartQueue, lowered: string | undefined): {
     arrivals: ArrivalPlan;
     warnings: string[];
 };
+/**
+ * Why a participant whose start comes at `nowMs` is skipped, or undefined: its scheduled end came
+ * while it waited, so its session would end before it began. The plan's simulation applies the
+ * same rule (planArrivals).
+ */
+export declare function pastEndReason(end: ParticipantEnd | undefined, nowMs: number): string | undefined;
 /**
  * Why a sandbox that serves the app until the last participant ends, the provisioned shared
  * world's subject sandbox, cannot live that long under `ceilingMs`; undefined when it can. Its
@@ -177,3 +229,4 @@ export declare function runOnSchedule<T, R>(items: readonly T[], options: {
     readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     readonly signal?: AbortSignal;
 }, start: (item: T, index: number, scheduled: ScheduledStart) => Promise<R>): Promise<R[]>;
+export {};