@aloud/runner 0.2.2 → 0.2.4

package/dist/cli.js

@@ -59,6 +59,16 @@ var init_ids = __esm({
       ledgerEntry: "led",
       // BILLING_PLAN 2.1: a grant of credit with its own expiry, which is what a balance is made of.
       creditLot: "clt",
+      // BILLING_PLAN 3: the estimate range and approved ceiling a run was authorised under. Stored
+      // rather than displayed, because a variable meter with no recorded agreement is a dispute.
+      quote: "qte",
+      // BILLING_PLAN 4: the billing period a workspace was on. The tier belongs to the period rather
+      // than to the workspace row, because a workspace outlives its plan.
+      plan: "pln",
+      // BILLING_PLAN 4: one meter event owed to Stripe. This is the row identity the drain worker
+      // uses, NOT what is sent as the dedup identifier: that is the ledger entry id the row carries,
+      // so that Stripe deduplication and the local unique index agree on what a duplicate is.
+      outboxEvent: "obx",
       rateCard: "rtc",
       auditEvent: "aud",
       job: "job",
@@ -1107,41 +1117,110 @@ var init_moment = __esm({
   }
 });
 
-// ../core/src/schemas/study.ts
+// ../core/src/schemas/session.ts
 import { z as z9 } from "zod";
+var SessionLimits, SessionError, SessionEndReason, Session;
+var init_session = __esm({
+  "../core/src/schemas/session.ts"() {
+    "use strict";
+    init_persona();
+    init_patience();
+    init_machines();
+    init_action();
+    SessionLimits = z9.object({
+      maxActions: z9.number().int().positive(),
+      maxElapsedMs: z9.number().int().positive(),
+      maxTokens: z9.number().int().positive()
+    });
+    SessionError = z9.object({
+      kind: z9.enum(["browser", "model", "policy", "timeout", "storage", "internal"]),
+      message: z9.string(),
+      retryable: z9.boolean(),
+      occurredAt: z9.string()
+    });
+    SessionEndReason = z9.enum([
+      "finished",
+      "abandoned",
+      "cap_actions",
+      "cap_elapsed",
+      "cap_tokens",
+      "error",
+      "canceled"
+    ]);
+    Session = z9.object({
+      id: z9.string(),
+      runId: z9.string(),
+      workspaceId: z9.string(),
+      persona: PersonaBrief,
+      personaId: z9.string().nullable(),
+      status: SessionStatus,
+      /** SPEC FR-054: recorded as evidence, never the reported result. */
+      selfReportedOutcome: SessionOutcome.nullable(),
+      selfReportedReason: z9.string().nullable(),
+      patienceBudget: PatienceBudget,
+      patienceState: PatienceState,
+      limits: SessionLimits,
+      startedAt: z9.string().nullable(),
+      endedAt: z9.string().nullable(),
+      error: SessionError.nullable(),
+      /** SPEC 14.4: set when integrity checks exclude or flag this session. */
+      contamination: z9.object({
+        contaminated: z9.boolean(),
+        flaggedOnly: z9.boolean(),
+        signals: z9.array(z9.string())
+      }).nullable(),
+      momentCount: z9.number().int().nonnegative().default(0),
+      /**
+       * Why the loop stopped. Null only for a session recorded before this field existed.
+       *
+       * Nullable rather than defaulted, per BILLING_PLAN Part 4 ("new nullable columns", additive only):
+       * a historical session has no honest value, and inventing one from its status would manufacture
+       * exactly the signal this field exists to stop anybody guessing at. Null therefore means "not
+       * recorded", never "ended cleanly".
+       */
+      endReason: SessionEndReason.nullable(),
+      /** Which browser worker ran it, for the isolation audit trail (SPEC FR-040). */
+      workerId: z9.string().nullable()
+    });
+  }
+});
+
+// ../core/src/schemas/study.ts
+import { z as z10 } from "zod";
 var EnvironmentType, ActionPolicy, Viewport, VIEWPORT_PRESETS, Environment, Product, SuccessCriterion, StudyStatus, Study, StudySnapshot;
 var init_study = __esm({
   "../core/src/schemas/study.ts"() {
     "use strict";
     init_persona();
-    EnvironmentType = z9.enum(["production", "staging", "preview", "local", "benchmark"]);
-    ActionPolicy = z9.object({
-      blockConsequentialActions: z9.boolean().default(true),
-      allowFormSubmission: z9.boolean().default(false),
-      allowedDomains: z9.array(z9.string()).default([]),
+    init_session();
+    EnvironmentType = z10.enum(["production", "staging", "preview", "local", "benchmark"]);
+    ActionPolicy = z10.object({
+      blockConsequentialActions: z10.boolean().default(true),
+      allowFormSubmission: z10.boolean().default(false),
+      allowedDomains: z10.array(z10.string()).default([]),
       /** SPEC FR-014: redirects outside allowed domains are blocked or need approval. */
-      blockOffDomainNavigation: z9.boolean().default(true),
+      blockOffDomainNavigation: z10.boolean().default(true),
       /** SPEC FR-050/FR-055: raw secret entry by the participant is always blocked. */
-      allowSecretEntry: z9.literal(false).default(false)
+      allowSecretEntry: z10.literal(false).default(false)
     });
-    Viewport = z9.object({
-      width: z9.number().int().min(320).max(3840),
-      height: z9.number().int().min(480).max(2160),
-      deviceScaleFactor: z9.number().min(1).max(3).default(1),
-      isMobile: z9.boolean().default(false)
+    Viewport = z10.object({
+      width: z10.number().int().min(320).max(3840),
+      height: z10.number().int().min(480).max(2160),
+      deviceScaleFactor: z10.number().min(1).max(3).default(1),
+      isMobile: z10.boolean().default(false)
     });
     VIEWPORT_PRESETS = {
       desktop: { width: 1440, height: 900, deviceScaleFactor: 1, isMobile: false },
       mobile_web: { width: 390, height: 844, deviceScaleFactor: 2, isMobile: true }
     };
-    Environment = z9.object({
-      id: z9.string(),
-      workspaceId: z9.string(),
-      productId: z9.string(),
-      name: z9.string().min(1).max(120),
-      baseUrl: z9.string().url(),
+    Environment = z10.object({
+      id: z10.string(),
+      workspaceId: z10.string(),
+      productId: z10.string(),
+      name: z10.string().min(1).max(120),
+      baseUrl: z10.string().url(),
       type: EnvironmentType,
-      allowedDomains: z9.array(z9.string()).default([]),
+      allowedDomains: z10.array(z10.string()).default([]),
       defaultViewport: DeviceContext.default("desktop"),
       actionPolicy: ActionPolicy,
       /**
@@ -1149,147 +1228,163 @@ var init_study = __esm({
        * A promise that secrets never appear in a screenshot is not enforceable against a live app, so
        * the policy is environment-scoped rather than absolute.
        */
-      redactionRequired: z9.boolean(),
-      createdAt: z9.string(),
+      redactionRequired: z10.boolean(),
+      createdAt: z10.string(),
       /** Marked when the system inferred this rather than the user configuring it (SPEC 9.0). */
-      inferred: z9.boolean().default(false)
+      inferred: z10.boolean().default(false)
     });
-    Product = z9.object({
-      id: z9.string(),
-      workspaceId: z9.string(),
-      name: z9.string().min(1).max(120),
-      description: z9.string().max(2e3).default(""),
-      createdAt: z9.string(),
-      inferred: z9.boolean().default(false)
+    Product = z10.object({
+      id: z10.string(),
+      workspaceId: z10.string(),
+      name: z10.string().min(1).max(120),
+      description: z10.string().max(2e3).default(""),
+      createdAt: z10.string(),
+      inferred: z10.boolean().default(false)
     });
-    SuccessCriterion = z9.object({
-      id: z9.string(),
+    SuccessCriterion = z10.object({
+      id: z10.string(),
       /** What a judge could confirm from a screenshot, in plain language. */
-      statement: z9.string().min(1).max(400),
+      statement: z10.string().min(1).max(400),
       /** Which visible signal confirms it. */
-      observableSignal: z9.string().min(1).max(400),
-      required: z9.boolean().default(true),
+      observableSignal: z10.string().min(1).max(400),
+      required: z10.boolean().default(true),
       /** Marked when the system proposed it (SPEC FR-026). */
-      proposed: z9.boolean().default(false)
+      proposed: z10.boolean().default(false)
     });
-    StudyStatus = z9.enum(["draft", "ready", "archived"]);
-    Study = z9.object({
-      id: z9.string(),
-      workspaceId: z9.string(),
-      productId: z9.string(),
-      environmentId: z9.string(),
-      name: z9.string().min(1).max(160),
+    StudyStatus = z10.enum(["draft", "ready", "archived"]);
+    Study = z10.object({
+      id: z10.string(),
+      workspaceId: z10.string(),
+      productId: z10.string(),
+      environmentId: z10.string(),
+      name: z10.string().min(1).max(160),
       /** SPEC FR-020: the flow under test. */
-      targetFlow: z9.string().min(1).max(400),
-      scenario: z9.string().min(1).max(2e3),
+      targetFlow: z10.string().min(1).max(400),
+      scenario: z10.string().min(1).max(2e3),
       /** In user language. Never a step-by-step script (SPEC 26 research integrity). */
-      goal: z9.string().min(1).max(600),
-      successCriteria: z9.array(SuccessCriterion).min(1),
+      goal: z10.string().min(1).max(600),
+      successCriteria: z10.array(SuccessCriterion).min(1),
       device: DeviceContext,
-      participantCount: z9.number().int().min(1).max(12),
+      participantCount: z10.number().int().min(1).max(12),
       /** Drives patience budget compilation (SPEC 14.5). */
-      expectedSteps: z9.number().int().min(1).max(60).default(6),
-      startUrl: z9.string().url(),
+      expectedSteps: z10.number().int().min(1).max(60).default(6),
+      startUrl: z10.string().url(),
       status: StudyStatus,
-      createdAt: z9.string(),
-      updatedAt: z9.string(),
-      inferred: z9.boolean().default(false)
+      createdAt: z10.string(),
+      updatedAt: z10.string(),
+      inferred: z10.boolean().default(false)
     });
-    StudySnapshot = z9.object({
+    StudySnapshot = z10.object({
       study: Study,
       environment: Environment,
-      cast: z9.array(PersonaBrief).min(1),
+      cast: z10.array(PersonaBrief).min(1),
       viewport: Viewport,
-      promptVersion: z9.string(),
-      actionSchemaVersion: z9.string(),
-      capturedAt: z9.string()
+      promptVersion: z10.string(),
+      actionSchemaVersion: z10.string(),
+      /**
+       * BILLING_PLAN 3: the per-session ceiling this run was authorised under, derived from the
+       * approved quote's cap by `maxActionsForCap`.
+       *
+       * It belongs in the snapshot for the same reason the cast and the environment do. FR-025 freezes
+       * a run's configuration so that editing the study afterwards cannot change what an existing
+       * report claims was tested, and the ceiling an operator approved is part of that configuration:
+       * re-quoting a study next month must not retroactively widen or narrow a run that already
+       * happened. It is also what carries the cap to a local runner, which works from the lease's
+       * snapshot and never sees `study_quotes`.
+       *
+       * Optional, and null-safe on read. Runs that predate BILLING_PLAN 3 carry no quote, and a stored
+       * snapshot is not rewritten to add one; those fall back to the platform default in the
+       * coordinator rather than being refused years later.
+       */
+      sessionLimits: SessionLimits.optional(),
+      capturedAt: z10.string()
     });
   }
 });
 
 // ../core/src/schemas/product-context.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var ProductEvidenceKind, ProductEvidenceRef, AudienceSegment, ProductFlow, ProductProfile, PersonaProposal, DiscoveryLink, DiscoveryPage, ProductDiscoveryEvidence, StudySetupStatus, StudySetupJob;
 var init_product_context = __esm({
   "../core/src/schemas/product-context.ts"() {
     "use strict";
     init_persona();
-    ProductEvidenceKind = z10.enum([
+    ProductEvidenceKind = z11.enum([
       "rendered_page",
       "user_statement",
       "agent_summary",
       "local_manifest"
     ]);
-    ProductEvidenceRef = z10.object({
-      id: z10.string(),
+    ProductEvidenceRef = z11.object({
+      id: z11.string(),
       kind: ProductEvidenceKind,
       /** A human-readable source name, such as "Pricing" or "Project summary". */
-      label: z10.string().min(1).max(160),
+      label: z11.string().min(1).max(160),
       /** URL for rendered evidence; a non-sensitive logical locator for local context. */
-      locator: z10.string().min(1).max(1e3),
+      locator: z11.string().min(1).max(1e3),
       /** Only customer-facing copy may be retained here. Raw repository source never belongs here. */
-      excerpt: z10.string().max(800).nullable().default(null),
-      contentHash: z10.string().max(128).nullable().default(null),
-      capturedAt: z10.string()
+      excerpt: z11.string().max(800).nullable().default(null),
+      contentHash: z11.string().max(128).nullable().default(null),
+      capturedAt: z11.string()
     });
-    AudienceSegment = z10.object({
-      id: z10.string(),
-      label: z10.string().min(1).max(120),
-      description: z10.string().min(1).max(600),
-      roles: z10.array(z10.string().min(1).max(120)).max(12).default([]),
-      jobsToBeDone: z10.array(z10.string().min(1).max(400)).max(12).default([]),
-      evidenceIds: z10.array(z10.string()).min(1),
-      confidence: z10.number().min(0).max(1)
+    AudienceSegment = z11.object({
+      id: z11.string(),
+      label: z11.string().min(1).max(120),
+      description: z11.string().min(1).max(600),
+      roles: z11.array(z11.string().min(1).max(120)).max(12).default([]),
+      jobsToBeDone: z11.array(z11.string().min(1).max(400)).max(12).default([]),
+      evidenceIds: z11.array(z11.string()).min(1),
+      confidence: z11.number().min(0).max(1)
     });
-    ProductFlow = z10.object({
-      label: z10.string().min(1).max(160),
-      outcome: z10.string().min(1).max(400),
-      evidenceIds: z10.array(z10.string()).min(1)
+    ProductFlow = z11.object({
+      label: z11.string().min(1).max(160),
+      outcome: z11.string().min(1).max(400),
+      evidenceIds: z11.array(z11.string()).min(1)
     });
-    ProductProfile = z10.object({
-      id: z10.string(),
-      workspaceId: z10.string(),
-      productId: z10.string(),
-      version: z10.number().int().positive(),
-      name: z10.string().min(1).max(120),
-      category: z10.string().min(1).max(160),
-      summary: z10.string().min(1).max(1200),
-      valueProposition: z10.string().max(800).default(""),
-      customerTypes: z10.array(z10.string().min(1).max(160)).max(12).default([]),
-      audiences: z10.array(AudienceSegment).max(16).default([]),
-      keyFlows: z10.array(ProductFlow).max(20).default([]),
-      domainVocabulary: z10.array(z10.string().min(1).max(100)).max(80).default([]),
-      evidence: z10.array(ProductEvidenceRef).max(80).default([]),
-      confidence: z10.number().min(0).max(1),
-      sourceFingerprint: z10.string().min(1).max(128),
-      supersedesId: z10.string().nullable(),
-      createdBy: z10.enum(["system", "user", "agent"]),
-      createdAt: z10.string()
+    ProductProfile = z11.object({
+      id: z11.string(),
+      workspaceId: z11.string(),
+      productId: z11.string(),
+      version: z11.number().int().positive(),
+      name: z11.string().min(1).max(120),
+      category: z11.string().min(1).max(160),
+      summary: z11.string().min(1).max(1200),
+      valueProposition: z11.string().max(800).default(""),
+      customerTypes: z11.array(z11.string().min(1).max(160)).max(12).default([]),
+      audiences: z11.array(AudienceSegment).max(16).default([]),
+      keyFlows: z11.array(ProductFlow).max(20).default([]),
+      domainVocabulary: z11.array(z11.string().min(1).max(100)).max(80).default([]),
+      evidence: z11.array(ProductEvidenceRef).max(80).default([]),
+      confidence: z11.number().min(0).max(1),
+      sourceFingerprint: z11.string().min(1).max(128),
+      supersedesId: z11.string().nullable(),
+      createdBy: z11.enum(["system", "user", "agent"]),
+      createdAt: z11.string()
     });
-    PersonaProposal = z10.object({
+    PersonaProposal = z11.object({
       brief: PersonaBrief,
-      audienceSegmentId: z10.string().nullable(),
-      rationale: z10.string().min(1).max(600),
-      evidenceIds: z10.array(z10.string()).default([]),
-      confidence: z10.number().min(0).max(1)
+      audienceSegmentId: z11.string().nullable(),
+      rationale: z11.string().min(1).max(600),
+      evidenceIds: z11.array(z11.string()).default([]),
+      confidence: z11.number().min(0).max(1)
     });
-    DiscoveryLink = z10.object({
-      href: z10.string().url(),
-      text: z10.string().max(240)
+    DiscoveryLink = z11.object({
+      href: z11.string().url(),
+      text: z11.string().max(240)
     });
-    DiscoveryPage = z10.object({
-      url: z10.string().url(),
-      title: z10.string().max(300),
-      headings: z10.array(z10.string().max(300)).max(80),
-      visibleText: z10.string().max(3e4),
-      links: z10.array(DiscoveryLink).max(200)
+    DiscoveryPage = z11.object({
+      url: z11.string().url(),
+      title: z11.string().max(300),
+      headings: z11.array(z11.string().max(300)).max(80),
+      visibleText: z11.string().max(3e4),
+      links: z11.array(DiscoveryLink).max(200)
     });
-    ProductDiscoveryEvidence = z10.object({
-      pages: z10.array(DiscoveryPage).min(1).max(8),
-      sourceFingerprint: z10.string().min(1).max(128),
-      capturedAt: z10.string()
+    ProductDiscoveryEvidence = z11.object({
+      pages: z11.array(DiscoveryPage).min(1).max(8),
+      sourceFingerprint: z11.string().min(1).max(128),
+      capturedAt: z11.string()
     });
-    StudySetupStatus = z10.enum([
+    StudySetupStatus = z11.enum([
       "awaiting_runner",
       "discovering",
       "analysing",
@@ -1299,77 +1394,27 @@ var init_product_context = __esm({
       "failed",
       "expired"
     ]);
-    StudySetupJob = z10.object({
-      id: z10.string(),
-      workspaceId: z10.string(),
-      url: z10.string().url(),
-      goal: z10.string().min(1).max(600),
+    StudySetupJob = z11.object({
+      id: z11.string(),
+      workspaceId: z11.string(),
+      url: z11.string().url(),
+      goal: z11.string().min(1).max(600),
       device: DeviceContext,
-      participantCount: z10.number().int().min(1).max(8),
-      allowedHosts: z10.array(z10.string()).min(1),
+      participantCount: z11.number().int().min(1).max(8),
+      allowedHosts: z11.array(z11.string()).min(1),
       status: StudySetupStatus,
-      runnerId: z10.string().nullable(),
+      runnerId: z11.string().nullable(),
       discoveryEvidence: ProductDiscoveryEvidence.nullable(),
-      productId: z10.string().nullable(),
-      profileId: z10.string().nullable(),
-      studyId: z10.string().nullable(),
-      personaProposals: z10.array(PersonaProposal).default([]),
-      degradedReason: z10.string().max(1e3).nullable(),
-      failureReason: z10.string().max(1e3).nullable(),
-      createdAt: z10.string(),
-      claimedAt: z10.string().nullable(),
-      expiresAt: z10.string(),
-      completedAt: z10.string().nullable()
-    });
-  }
-});
-
-// ../core/src/schemas/session.ts
-import { z as z11 } from "zod";
-var SessionLimits, SessionError, Session;
-var init_session = __esm({
-  "../core/src/schemas/session.ts"() {
-    "use strict";
-    init_persona();
-    init_patience();
-    init_machines();
-    init_action();
-    SessionLimits = z11.object({
-      maxActions: z11.number().int().positive(),
-      maxElapsedMs: z11.number().int().positive(),
-      maxTokens: z11.number().int().positive()
-    });
-    SessionError = z11.object({
-      kind: z11.enum(["browser", "model", "policy", "timeout", "storage", "internal"]),
-      message: z11.string(),
-      retryable: z11.boolean(),
-      occurredAt: z11.string()
-    });
-    Session = z11.object({
-      id: z11.string(),
-      runId: z11.string(),
-      workspaceId: z11.string(),
-      persona: PersonaBrief,
-      personaId: z11.string().nullable(),
-      status: SessionStatus,
-      /** SPEC FR-054: recorded as evidence, never the reported result. */
-      selfReportedOutcome: SessionOutcome.nullable(),
-      selfReportedReason: z11.string().nullable(),
-      patienceBudget: PatienceBudget,
-      patienceState: PatienceState,
-      limits: SessionLimits,
-      startedAt: z11.string().nullable(),
-      endedAt: z11.string().nullable(),
-      error: SessionError.nullable(),
-      /** SPEC 14.4: set when integrity checks exclude or flag this session. */
-      contamination: z11.object({
-        contaminated: z11.boolean(),
-        flaggedOnly: z11.boolean(),
-        signals: z11.array(z11.string())
-      }).nullable(),
-      momentCount: z11.number().int().nonnegative().default(0),
-      /** Which browser worker ran it, for the isolation audit trail (SPEC FR-040). */
-      workerId: z11.string().nullable()
+      productId: z11.string().nullable(),
+      profileId: z11.string().nullable(),
+      studyId: z11.string().nullable(),
+      personaProposals: z11.array(PersonaProposal).default([]),
+      degradedReason: z11.string().max(1e3).nullable(),
+      failureReason: z11.string().max(1e3).nullable(),
+      createdAt: z11.string(),
+      claimedAt: z11.string().nullable(),
+      expiresAt: z11.string(),
+      completedAt: z11.string().nullable()
     });
   }
 });
@@ -1850,7 +1895,7 @@ var init_recommendation = __esm({
 
 // ../core/src/schemas/billing.ts
 import { z as z18 } from "zod";
-var RateCard, ChargeLineKind, ChargeLine;
+var RateCard, ChargeLineKind, ChargeLine, StudyEstimate, EstimateBasis, StudyQuote;
 var init_billing = __esm({
   "../core/src/schemas/billing.ts"() {
     "use strict";
@@ -1892,6 +1937,44 @@ var init_billing = __esm({
        */
       idempotencyKey: z18.string()
     });
+    StudyEstimate = z18.object({
+      /** The optimistic end: participants who move through the flow faster than predicted. */
+      low: z18.number().int().nonnegative(),
+      /** The midpoint, priced at the predicted moment count exactly. */
+      expected: z18.number().int().nonnegative(),
+      /** The pessimistic end: participants who flounder, which is also where the findings are. */
+      high: z18.number().int().nonnegative(),
+      /** At or above `high` with headroom. See CAP_HEADROOM in ../billing.ts for the policy. */
+      cap: z18.number().int().nonnegative()
+    });
+    EstimateBasis = z18.enum(["archetype", "history"]);
+    StudyQuote = z18.object({
+      id: z18.string(),
+      workspaceId: z18.string(),
+      /** The run this quote priced. Not a foreign key in the schema: an agreement outlives its run. */
+      runId: z18.string(),
+      /** I6: the immutable card the range was computed under, so the range stays reproducible. */
+      rateCardVersion: z18.string(),
+      /** Non-negative rather than positive: a zero-participant study still reaches synthesis, and a
+       * rate card is free to price any fixed line at zero. Negative is the only impossible value. */
+      estimateLowCredits: z18.number().int().nonnegative(),
+      estimateHighCredits: z18.number().int().nonnegative(),
+      /** The ceiling the operator approves, and the number SessionLimits.maxActions is derived from. */
+      approvedCapCredits: z18.number().int().nonnegative(),
+      /** Null until an operator agrees. Both approval fields are set together or not at all. */
+      approvedBy: z18.string().nullable(),
+      approvedAt: z18.string().nullable(),
+      createdAt: z18.string()
+    }).refine((q) => q.estimateLowCredits <= q.estimateHighCredits, {
+      message: "estimateLowCredits must not exceed estimateHighCredits",
+      path: ["estimateLowCredits"]
+    }).refine((q) => q.approvedCapCredits >= q.estimateHighCredits, {
+      message: "approvedCapCredits must be at least estimateHighCredits",
+      path: ["approvedCapCredits"]
+    }).refine((q) => q.approvedBy === null === (q.approvedAt === null), {
+      message: "approvedBy and approvedAt are set together or not at all",
+      path: ["approvedAt"]
+    });
   }
 });
 
@@ -2666,7 +2749,7 @@ function alive(pid) {
 }
 
 // src/version.ts
-var RUNNER_VERSION = "0.2.2";
+var RUNNER_VERSION = "0.2.4";
 var RUNNER_VERSION_HEADER = "x-aloud-runner-version";
 
 // src/protocol/client.ts
@@ -3988,6 +4071,7 @@ var ParticipantSession = class {
     const startedAt = this.deps.clock.nowIso();
     this.startedAtMs = this.deps.clock.monotonicMs();
     let status2 = "active";
+    let endReason = "error";
     let error = null;
     try {
       this.emit({ type: "session.started", sessionId: this.input.sessionId, persona: this.persona.name });
@@ -3995,12 +4079,14 @@ var ParticipantSession = class {
       this.lastCapture = first;
       this.visited.push(first.digest);
       await this.recordFirstImpression(first);
-      status2 = await this.loop();
+      ({ status: status2, endReason } = await this.loop());
     } catch (thrown) {
       if (this.deps.signal?.aborted) {
         status2 = "canceled";
+        endReason = "canceled";
       } else {
         status2 = "error";
+        endReason = "error";
         const modelError = thrown instanceof ModelError ? thrown : null;
         error = {
           kind: modelError ? `model:${modelError.kind}` : "browser",
@@ -4015,6 +4101,7 @@ var ParticipantSession = class {
     return {
       sessionId: this.input.sessionId,
       status: status2,
+      endReason,
       moments: this.moments,
       evidenceAssets: this.evidenceAssets,
       selfReportedOutcome: this.selfReportedOutcome,
@@ -4037,12 +4124,23 @@ var ParticipantSession = class {
       throw error;
     }
   }
+  /**
+   * Returns both how the session ended and why.
+   *
+   * Both, rather than the status alone, because the status cannot carry the why: three of the exits
+   * below are all `partial`, and MONETIZATION "Refunds" bills two of them and refunds the third
+   * whole. This function is the only place in the system that knows which one was taken, so the
+   * reason leaves here as data rather than being reconstructed later from a moment count that reads
+   * identically either way.
+   */
   async loop() {
     const { limits } = this.input;
     for (let step = 0; step < limits.maxActions; step += 1) {
       this.checkCancelled();
-      if (this.elapsedMs() > limits.maxElapsedMs) return "partial";
-      if (this.deps.gateway.totalUsage().outputTokens > limits.maxTokens) return "partial";
+      if (this.elapsedMs() > limits.maxElapsedMs) return { status: "partial", endReason: "cap_elapsed" };
+      if (this.deps.gateway.totalUsage().outputTokens > limits.maxTokens) {
+        return { status: "partial", endReason: "cap_tokens" };
+      }
       const capture = this.lastCapture;
       const momentId = newId("moment");
       const decision = await this.decide(capture, momentId);
@@ -4058,12 +4156,12 @@ var ParticipantSession = class {
           confidence: decision.confidence,
           capture
         });
-        return decision.action.outcome === "abandoned" ? "abandoned" : "partial";
+        return decision.action.outcome === "abandoned" ? { status: "abandoned", endReason: "abandoned" } : { status: "partial", endReason: "finished" };
       }
       const outcome = await this.act(decision, capture, momentId);
-      if (outcome === "stop") return "abandoned";
+      if (outcome === "stop") return { status: "abandoned", endReason: "abandoned" };
     }
-    return "partial";
+    return { status: "partial", endReason: "cap_actions" };
   }
   async decide(capture, momentId) {
     const result = await this.deps.gateway.generate({
@@ -5022,6 +5120,11 @@ var RunEventLog = class {
 
 // ../engine/src/orchestrator/coordinator.ts
 init_src();
+var DEFAULT_SESSION_LIMITS = {
+  maxActions: 40,
+  maxElapsedMs: 15 * 6e4,
+  maxTokens: 4e5
+};
 var RunCoordinator = class {
   constructor(input, deps) {
     this.input = input;
@@ -5160,6 +5263,7 @@ var RunCoordinator = class {
    */
   async runSessions(budgets) {
     const { snapshot } = this.input;
+    const limits = snapshot.sessionLimits ?? DEFAULT_SESSION_LIMITS;
     const limit = Math.max(1, this.deps.maxConcurrentSessions ?? snapshot.cast.length);
     const results = new Array(snapshot.cast.length);
     let cursor = 0;
@@ -5181,7 +5285,7 @@ var RunCoordinator = class {
           persona,
           snapshot,
           patienceBudget: budgets[index],
-          limits: { maxActions: 40, maxElapsedMs: 15 * 6e4, maxTokens: 4e5 }
+          limits
         },
         {
           gateway: this.deps.gateway,
@@ -5223,12 +5327,17 @@ var RunCoordinator = class {
         selfReportedReason: result.selfReportedReason,
         patienceBudget: budgets[index],
         patienceState: result.patienceState,
-        limits: { maxActions: 40, maxElapsedMs: 15 * 6e4, maxTokens: 4e5 },
+        limits,
         startedAt: result.startedAt,
         endedAt: result.endedAt,
         error: result.error ? { kind: "internal", message: result.error.message, retryable: result.error.retryable, occurredAt: result.endedAt } : null,
         contamination: null,
         momentCount: result.moments.length,
+        // Carried straight from the loop rather than derived from `status`, which cannot say: a
+        // clean finish and an exhausted action budget are both `partial`. MONETIZATION "Refunds"
+        // bills the first and refunds the second whole, so the distinction has to survive the trip
+        // into the persisted record.
+        endReason: result.endReason,
         workerId: worker.id
       };
       this.sessionsByPersonaIndex.set(index, session);
@@ -6246,6 +6355,9 @@ function failureFrom(outcome) {
 }
 function describeOutcome(result) {
   if (result.status === "error") return "the browser stopped unexpectedly";
+  if (result.endReason === "cap_actions") return "ran out of actions before finishing";
+  if (result.endReason === "cap_elapsed") return "ran out of time before finishing";
+  if (result.endReason === "cap_tokens") return "ran out of its token budget before finishing";
   if (result.selfReportedOutcome === "success") return "reached the goal";
   if (result.selfReportedOutcome === "abandoned") return result.selfReportedReason ?? "gave up";
   return result.selfReportedOutcome ?? "finished";
@@ -6639,6 +6751,10 @@ var StudyDesignProposalResponse = z23.object({
 // ../app/src/services/billing.ts
 init_src();
 
+// ../app/src/services/billing-outbox.ts
+init_src();
+var DAY_MS = 24 * 60 * 60 * 1e3;
+
 // ../app/src/application.ts
 var PreflightFailedError = class extends Error {
   constructor(preflight2) {
@@ -6651,6 +6767,9 @@ var PreflightFailedError = class extends Error {
   preflight;
 };
 
+// ../app/src/services/billing-webhooks.ts
+init_src();
+
 // ../app/src/services/export.ts
 var DEFAULT_MAX_EMBEDDED_BYTES = 24 * 1024 * 1024;
 
@@ -6875,6 +6994,8 @@ var MCP_TOOLS = [
   "propose_personas",
   "approve_personas",
   "run_preflight",
+  "quote_study",
+  "approve_quote",
   "start_study",
   "get_run_status",
   "cancel_run",
@@ -6890,6 +7011,12 @@ var MUTATING_TOOLS = {
   propose_personas: { mutates: false, capability: "study.write", idempotent: true },
   approve_personas: { mutates: true, capability: "study.write", idempotent: true },
   run_preflight: { mutates: false, capability: "study.write", idempotent: true },
+  // BILLING_PLAN 3. Quoting is a builder operation and changes no money, so it is authorised the
+  // same way `run_preflight` is. Approving the ceiling is what commits a run to spend, so it is
+  // authorised as `run.start`: an operator can start runs and cannot manage billing, and requiring
+  // `billing.manage` here would mean no operator could ever start a study.
+  quote_study: { mutates: true, capability: "study.write", idempotent: false },
+  approve_quote: { mutates: true, capability: "run.start", idempotent: true },
   start_study: { mutates: true, capability: "run.start", idempotent: false },
   get_run_status: { mutates: false, capability: "report.read", idempotent: true },
   cancel_run: { mutates: true, capability: "run.cancel", idempotent: true },
@@ -6937,8 +7064,25 @@ var StartStudyInput = z25.object({
   productId: z25.string(),
   /** SPEC FR-116: supplied by the client so a retry finds the run rather than making a second. */
   idempotencyKey: z25.string().min(1).max(120),
-  maxCostCents: z25.number().positive().nullable().default(null)
+  maxCostCents: z25.number().positive().nullable().default(null),
+  /**
+   * BILLING_PLAN 3: the run `quote_study` priced and `approve_quote` authorised.
+   *
+   * Optional in the schema and required in effect: a start with no run id gets a fresh one, which
+   * by construction carries no approved quote, and `@aloud/app` refuses it. Typed as optional so
+   * the refusal comes from the one authorization path rather than from an argument parser here,
+   * which is SPEC FR-110: two enforcement points is one too many.
+   */
+  runId: z25.string().optional()
 });
+var QuoteStudyInput = z25.object({
+  studyId: z25.string(),
+  /** Re-quotes an existing prospective run instead of pricing a new one. */
+  runId: z25.string().optional(),
+  /** Overrides the archetype prediction of moments per participant. */
+  momentsEach: z25.number().int().min(1).max(400).optional()
+});
+var ApproveQuoteInput = z25.object({ runId: z25.string() });
 var RunIdInput = z25.object({ runId: z25.string() });
 var FindingInput = z25.object({ runId: z25.string(), findingId: z25.string() });
 var ShareLinkInput = z25.object({
@@ -7025,7 +7169,7 @@ async function handleTool(context, name, input, execute) {
         castComposition: draft.cast.compositionFloor,
         preflight: summarisePreflight(draft.preflight),
         estimateCents: app.estimateFor(draft.study),
-        note: "Nothing has run yet. Approve the cast, then start the study."
+        note: "Nothing has run yet. Approve the cast, quote the study, get the ceiling approved, then start the run the quote named."
       });
     }
     case "get_product_profile": {
@@ -7077,6 +7221,50 @@ async function handleTool(context, name, input, execute) {
       const preflight2 = await app.preflight(actor, { workspaceId, studyId: parsed.studyId });
       return json(summarisePreflight(preflight2));
     }
+    /**
+     * BILLING_PLAN 3: "The MCP path enforces the same gate as the web path, through the one
+     * authorization path in `@aloud/app`."
+     *
+     * That sentence is why this is three calls rather than one convenient one. An agent that could
+     * start a study without a recorded agreement would be a way around the gate, and the whole
+     * point of the gate is that a variable meter needs an agreement somebody actually made. So the
+     * agent quotes, shows the human the range, gets the ceiling approved, and starts the run the
+     * quote named.
+     */
+    case "quote_study": {
+      const parsed = QuoteStudyInput.parse(input);
+      const quoted = await app.quoteStudy(actor, { workspaceId, ...parsed });
+      return json({
+        quoteId: quoted.quote.id,
+        // Carried into approve_quote and start_study. The agreement names the run, so the run has
+        // to be named before it exists.
+        runId: quoted.quote.runId,
+        resource: RESOURCE_SCHEMES.run(quoted.quote.runId),
+        rateCardVersion: quoted.quote.rateCardVersion,
+        estimateLowCredits: quoted.quote.estimateLowCredits,
+        estimateHighCredits: quoted.quote.estimateHighCredits,
+        approvedCapCredits: quoted.quote.approvedCapCredits,
+        // MONETIZATION.md, "Quoting a study": the range is what a customer is promised and the
+        // basis is how much that promise is worth, so the two travel together.
+        basis: quoted.basis,
+        observations: quoted.observations,
+        approved: false,
+        note: "Nothing is committed. Moment count is not knowable in advance, so this is a range and a ceiling rather than a price. Show it to a person, then call approve_quote with this runId, then start_study with the same runId."
+      });
+    }
+    case "approve_quote": {
+      const parsed = ApproveQuoteInput.parse(input);
+      const quote = await app.approveQuote(actor, { workspaceId, runId: parsed.runId });
+      return json({
+        quoteId: quote.id,
+        runId: quote.runId,
+        approvedCapCredits: quote.approvedCapCredits,
+        approvedBy: quote.approvedBy,
+        approvedAt: quote.approvedAt,
+        rateCardVersion: quote.rateCardVersion,
+        note: "This run may never spend more than the approved ceiling. It becomes the per-session action limit, so the cost control and the honest-abandonment guarantee are one mechanism."
+      });
+    }
     case "start_study": {
       const parsed = StartStudyInput.parse(input);
       let outcome;
@@ -7085,7 +7273,10 @@ async function handleTool(context, name, input, execute) {
           workspaceId,
           studyId: parsed.studyId,
           idempotencyKey: parsed.idempotencyKey,
-          maxCostCents: parsed.maxCostCents
+          maxCostCents: parsed.maxCostCents,
+          // BILLING_PLAN 3: the run the approved quote priced. Omitted, the gate in `@aloud/app`
+          // refuses, which is the same refusal the web path gets.
+          ...parsed.runId ? { runId: parsed.runId } : {}
         });
       } catch (error) {
         if (error instanceof PreflightFailedError) {
@@ -7238,7 +7429,9 @@ var TOOL_DESCRIPTIONS = {
   propose_personas: "Propose a cast of behaviourally distinct participants for an existing study, derived only from what a visitor to the site could see.",
   approve_personas: "Approve the cast a study will run with. Required before a study can start.",
   run_preflight: "Check a study is safe and ready to run. Names the exact failing check rather than a generic failure.",
-  start_study: "Start a study. Returns a run id immediately; the study runs in the background. Requires an idempotency key so a retry finds the existing run instead of starting a second.",
+  quote_study: "Price a study before it runs. Moment count is not knowable in advance, so this returns an estimate range and a ceiling rather than a price, plus the runId the quote is recorded against. Show the range to a person before approving it.",
+  approve_quote: "Record that the operator agreed to a study's ceiling. Required before the run can start, and it becomes the per-session action limit so the run can never exceed what was approved.",
+  start_study: "Start a study. Returns a run id immediately; the study runs in the background. Requires an idempotency key so a retry finds the existing run instead of starting a second, and the runId from an approved quote.",
   get_run_status: "Read a run's current status, its participants, and its report if one exists yet.",
   cancel_run: "Stop a run. Browsers are closed and no further model spend happens.",
   list_findings: "List the findings from a completed run, with the participant count behind each one and the study's stated limitations.",
@@ -7299,11 +7492,18 @@ var TOOL_SHAPES = {
   },
   approve_personas: { studyId: z26.string(), cast: z26.array(z26.record(z26.string(), z26.unknown())) },
   run_preflight: { studyId: z26.string() },
+  quote_study: {
+    studyId: z26.string(),
+    runId: z26.string().describe("Re-quote a prospective run instead of pricing a new one.").optional(),
+    momentsEach: z26.number().int().min(1).max(400).describe("Override the predicted moments per participant.").optional()
+  },
+  approve_quote: { runId: z26.string().describe("The runId quote_study returned.") },
   start_study: {
     studyId: z26.string(),
     productId: z26.string(),
     idempotencyKey: z26.string().describe("Reuse this on a retry so it finds the run rather than starting a second."),
-    maxCostCents: z26.number().positive().nullable().optional()
+    maxCostCents: z26.number().positive().nullable().optional(),
+    runId: z26.string().describe("The runId from the approved quote. A run cannot start without one.").optional()
   },
   get_run_status: { runId: z26.string() },
   cancel_run: { runId: z26.string(), reason: z26.string().optional() },
@@ -7328,6 +7528,11 @@ function createMcpServer(options) {
         "not reports from real customers, and every response says how many participants hit a thing",
         "rather than what share of users would.",
         "",
+        "A study costs money to run, so it cannot start until somebody has agreed to a ceiling.",
+        "Call quote_study, show a person the range and the cap it returns, call approve_quote, then",
+        "start_study with the same runId. The estimate is a range because how far a participant gets",
+        "is the thing being measured, so there is no single price to quote.",
+        "",
         "start_study returns immediately. Poll get_run_status; nothing is lost if this connection drops.",
         "",
         "When you are running beside a product repository, call upsert_product_context with derived",
@@ -7658,6 +7863,25 @@ async function login(argv) {
   const server = stringOption(argv, "--server") ?? DEFAULT_SERVER;
   let token = stringOption(argv, "--token");
   if (!token) {
+    if (!process.stdin.isTTY) {
+      process.stderr.write(
+        [
+          "",
+          "There is no terminal attached here, so there is nowhere to paste a token.",
+          "",
+          "If you are an agent: stop and hand this back. The person runs `aloud login` in their",
+          "own terminal and pastes the token at the prompt. Do not ask them to paste it to you.",
+          "",
+          "To connect without a terminal, set both of these instead and skip login entirely:",
+          `  export ALOUD_SERVER=${server}`,
+          "  export ALOUD_RUNNER_TOKEN=utar_...",
+          "",
+          `A token comes from ${server}/app/settings/runners and is shown once.`,
+          ""
+        ].join("\n")
+      );
+      return 1;
+    }
     process.stdout.write(`
 Open ${server}/app/settings/runners and create a runner.
 `);
@@ -7718,27 +7942,46 @@ async function setup() {
   const installed = onPath("aloud");
   const latest = await latestVersion();
   const stale = latest !== null && latest !== RUNNER_VERSION;
+  const signedIn = await signedInState(credentials);
   const out = (line = "") => process.stdout.write(line + "\n");
   out();
   out("Aloud runner setup. You are looking at the state of this machine.");
   out();
   out(`  installed      ${installed ? `yes (${RUNNER_VERSION})` : "no"}`);
   out(`  up to date     ${latest === null ? "unknown, could not reach the registry" : stale ? `no, ${latest} is out` : "yes"}`);
-  out(`  signed in      ${credentials ? credentials.runnerName : "no"}`);
+  out(
+    `  signed in      ${signedIn.state === "ok" ? signedIn.name : signedIn.state === "revoked" ? `no. The saved token for ${credentials?.runnerName ?? "this machine"} was revoked` : signedIn.state === "unreachable" ? `cannot tell, ${signedIn.server} did not answer` : "no"}`
+  );
   out(`  chromium       ${checks.chromiumInstalled ? "ready" : "downloads on first start, about 350 MB"}`);
   out(`  running        ${running ? `yes (pid ${running.pid})` : "no"}`);
   out();
   const steps = [];
   if (!installed) {
-    steps.push("npm install -g @aloud/runner");
+    steps.push(["npm install -g @aloud/runner"]);
   } else if (stale) {
-    steps.push(`npm install -g @aloud/runner@latest    # ${RUNNER_VERSION} is installed, ${latest} is out`);
+    steps.push([`npm install -g @aloud/runner@latest`, `${RUNNER_VERSION} is installed, ${latest} is out.`]);
   }
-  if (!credentials) {
-    steps.push("aloud login    # prompts for a token. The person, not you, pastes it in here.");
+  if (signedIn.state === "revoked") {
+    steps.push([
+      `Create a new token at ${credentials?.server ?? DEFAULT_SERVER}/app/settings/runners`,
+      "The saved one was revoked and cannot be reused."
+    ]);
+  }
+  if (signedIn.state === "none" || signedIn.state === "revoked") {
+    steps.push([
+      "aloud login",
+      "Needs a terminal. If you are an agent, hand this step to the person: they run it",
+      "themselves and paste the token at the prompt. Do not ask them to paste it to you."
+    ]);
   }
   if (!running) {
-    steps.push("aloud start    # in a background shell. It never exits.");
+    steps.push(["aloud start", "In a background shell. It never exits, so do not block on it."]);
+  }
+  if (steps.length === 0 && signedIn.state === "unreachable") {
+    out(`Cannot reach ${signedIn.server}, so there is nothing useful to say about what is left.`);
+    out("Check the connection and run this again.");
+    out();
+    return 1;
   }
   if (steps.length === 0) {
     out("Nothing to do. This machine is set up and waiting for studies.");
@@ -7747,8 +7990,12 @@ async function setup() {
   }
   out("Do these, in order:");
   out();
-  for (const [index, step] of steps.entries()) out(`  ${index + 1}. ${step}`);
-  out(`  ${steps.length + 1}. aloud status    # exits non-zero until all of the above are true`);
+  for (const [index, [command, ...notes]] of steps.entries()) {
+    out(`  ${index + 1}. ${command}`);
+    for (const note of notes) out(`     ${note}`);
+  }
+  out(`  ${steps.length + 1}. aloud status`);
+  out("     Exits non-zero until all of the above are true.");
   out();
   out("Rules, if you are an agent doing this:");
   out();
@@ -7772,6 +8019,20 @@ async function setup() {
   }
   return 1;
 }
+async function signedInState(credentials) {
+  if (!credentials) return { state: "none" };
+  try {
+    const response = await fetch(new URL("api/runner/me", credentials.server + "/"), {
+      headers: { authorization: `Bearer ${credentials.token}` },
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (response.status === 401 || response.status === 403) return { state: "revoked" };
+    if (!response.ok) return { state: "unreachable", server: credentials.server };
+    return { state: "ok", name: credentials.runnerName };
+  } catch {
+    return { state: "unreachable", server: credentials.server };
+  }
+}
 async function npmPrefix() {
   const path = await new Promise((resolve) => {
     const child = spawn2("npm", ["config", "get", "prefix"], { stdio: ["ignore", "pipe", "ignore"] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Run Aloud usability studies in a real browser on your own machine, so a study can reach localhost and anything else behind your network.",
   "license": "ISC",
   "repository": {

package/src/cli.ts

@@ -106,6 +106,30 @@ async function login(argv: readonly string[]): Promise<number> {
   let token = stringOption(argv, "--token");
 
   if (!token) {
+    // An agent runs commands in a shell with nothing attached to stdin, so the prompt below would
+    // read end-of-file and the token would come back empty. That used to surface as "that does not
+    // look like a runner token", which blames the wrong thing and tells nobody what to do. This is
+    // the single step of setup that a person has to perform, so it is worth saying so precisely.
+    if (!process.stdin.isTTY) {
+      process.stderr.write(
+        [
+          "",
+          "There is no terminal attached here, so there is nowhere to paste a token.",
+          "",
+          "If you are an agent: stop and hand this back. The person runs `aloud login` in their",
+          "own terminal and pastes the token at the prompt. Do not ask them to paste it to you.",
+          "",
+          "To connect without a terminal, set both of these instead and skip login entirely:",
+          `  export ALOUD_SERVER=${server}`,
+          "  export ALOUD_RUNNER_TOKEN=utar_...",
+          "",
+          `A token comes from ${server}/app/settings/runners and is shown once.`,
+          "",
+        ].join("\n"),
+      );
+      return 1;
+    }
+
     process.stdout.write(`\nOpen ${server}/app/settings/runners and create a runner.\n`);
     process.stdout.write("It shows you a token once. Paste it here.\n\n");
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -186,6 +210,7 @@ async function setup(): Promise<number> {
   const installed = onPath("aloud");
   const latest = await latestVersion();
   const stale = latest !== null && latest !== RUNNER_VERSION;
+  const signedIn = await signedInState(credentials);
 
   const out = (line = "") => process.stdout.write(line + "\n");
 
@@ -194,22 +219,52 @@ async function setup(): Promise<number> {
   out();
   out(`  installed      ${installed ? `yes (${RUNNER_VERSION})` : "no"}`);
   out(`  up to date     ${latest === null ? "unknown, could not reach the registry" : stale ? `no, ${latest} is out` : "yes"}`);
-  out(`  signed in      ${credentials ? credentials.runnerName : "no"}`);
+  out(
+    `  signed in      ${
+      signedIn.state === "ok"
+        ? signedIn.name
+        : signedIn.state === "revoked"
+          ? `no. The saved token for ${credentials?.runnerName ?? "this machine"} was revoked`
+          : signedIn.state === "unreachable"
+            ? `cannot tell, ${signedIn.server} did not answer`
+            : "no"
+    }`,
+  );
   out(`  chromium       ${checks.chromiumInstalled ? "ready" : "downloads on first start, about 350 MB"}`);
   out(`  running        ${running ? `yes (pid ${running.pid})` : "no"}`);
   out();
 
-  const steps: string[] = [];
+  // Each step is a command plus the lines that qualify it. Only the command gets a number, or a
+  // continuation reads as a step of its own, and an agent following "step 2" ends up pasting a URL
+  // into a shell.
+  const steps: string[][] = [];
   if (!installed) {
-    steps.push("npm install -g @aloud/runner");
+    steps.push(["npm install -g @aloud/runner"]);
   } else if (stale) {
-    steps.push(`npm install -g @aloud/runner@latest    # ${RUNNER_VERSION} is installed, ${latest} is out`);
+    steps.push([`npm install -g @aloud/runner@latest`, `${RUNNER_VERSION} is installed, ${latest} is out.`]);
   }
-  if (!credentials) {
-    steps.push("aloud login    # prompts for a token. The person, not you, pastes it in here.");
+  if (signedIn.state === "revoked") {
+    steps.push([
+      `Create a new token at ${credentials?.server ?? DEFAULT_SERVER}/app/settings/runners`,
+      "The saved one was revoked and cannot be reused.",
+    ]);
+  }
+  if (signedIn.state === "none" || signedIn.state === "revoked") {
+    steps.push([
+      "aloud login",
+      "Needs a terminal. If you are an agent, hand this step to the person: they run it",
+      "themselves and paste the token at the prompt. Do not ask them to paste it to you.",
+    ]);
   }
   if (!running) {
-    steps.push("aloud start    # in a background shell. It never exits.");
+    steps.push(["aloud start", "In a background shell. It never exits, so do not block on it."]);
+  }
+
+  if (steps.length === 0 && signedIn.state === "unreachable") {
+    out(`Cannot reach ${signedIn.server}, so there is nothing useful to say about what is left.`);
+    out("Check the connection and run this again.");
+    out();
+    return 1;
   }
 
   if (steps.length === 0) {
@@ -220,8 +275,12 @@ async function setup(): Promise<number> {
 
   out("Do these, in order:");
   out();
-  for (const [index, step] of steps.entries()) out(`  ${index + 1}. ${step}`);
-  out(`  ${steps.length + 1}. aloud status    # exits non-zero until all of the above are true`);
+  for (const [index, [command, ...notes]] of steps.entries()) {
+    out(`  ${index + 1}. ${command}`);
+    for (const note of notes) out(`     ${note}`);
+  }
+  out(`  ${steps.length + 1}. aloud status`);
+  out("     Exits non-zero until all of the above are true.");
   out();
   out("Rules, if you are an agent doing this:");
   out();
@@ -248,6 +307,32 @@ async function setup(): Promise<number> {
   return 1;
 }
 
+
+/**
+ * Whether the saved credential still works, asked of the server rather than assumed from the file.
+ *
+ * A credentials file proves a token was written here once, not that it is still good. Revoking a
+ * machine from the web app leaves the file exactly as it was, so reporting "signed in" from its
+ * presence sent an agent off to `aloud start`, which died on its first poll with a 401 and no
+ * explanation of what to do. This is the same endpoint `login` checks a token against.
+ */
+async function signedInState(
+  credentials: Credentials | null,
+): Promise<{ state: "none" } | { state: "ok"; name: string } | { state: "revoked" } | { state: "unreachable"; server: string }> {
+  if (!credentials) return { state: "none" };
+  try {
+    const response = await fetch(new URL("api/runner/me", credentials.server + "/"), {
+      headers: { authorization: `Bearer ${credentials.token}` },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (response.status === 401 || response.status === 403) return { state: "revoked" };
+    if (!response.ok) return { state: "unreachable", server: credentials.server };
+    return { state: "ok", name: credentials.runnerName };
+  } catch {
+    return { state: "unreachable", server: credentials.server };
+  }
+}
+
 /**
  * Where npm would put a global install, and whether it can be written to.
  *

package/src/run/execute.ts

@@ -336,8 +336,24 @@ function failureFrom(outcome: RunOutcome): string | null {
   return null;
 }
 
-function describeOutcome(result: { status: string; selfReportedOutcome?: string | null; selfReportedReason?: string | null }): string {
+/**
+ * The one line the person watching their own machine sees when a participant stops.
+ *
+ * The cap cases are named rather than folded into "finished", which is what they used to read as.
+ * A session the runtime cut off produced truncated evidence, and MONETIZATION treats that as a
+ * platform failure rather than a delivery, so the operator watching it happen should be told that
+ * plainly instead of being shown a word that means the opposite.
+ */
+function describeOutcome(result: {
+  status: string;
+  endReason?: string | null;
+  selfReportedOutcome?: string | null;
+  selfReportedReason?: string | null;
+}): string {
   if (result.status === "error") return "the browser stopped unexpectedly";
+  if (result.endReason === "cap_actions") return "ran out of actions before finishing";
+  if (result.endReason === "cap_elapsed") return "ran out of time before finishing";
+  if (result.endReason === "cap_tokens") return "ran out of its token budget before finishing";
   if (result.selfReportedOutcome === "success") return "reached the goal";
   if (result.selfReportedOutcome === "abandoned") return result.selfReportedReason ?? "gave up";
   return result.selfReportedOutcome ?? "finished";

package/src/version.ts

@@ -10,7 +10,7 @@
  * package.json beside it to read, and importing one into the source trips the composite build's
  * rootDir. `version.test.ts` asserts this matches, so the drift this invites cannot survive CI.
  */
-export const RUNNER_VERSION = "0.2.2";
+export const RUNNER_VERSION = "0.2.4";
 
 /** The header the server reads it from. */
 export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";