humanish 0.115.0 → 0.117.0

package/dist/routes/terminal/ledger.js

@@ -4,48 +4,21 @@ import { COST_CATEGORIES } from "../../run/terminal-contract.js";
 /**
  * Build the spend ledger from the captured session. The null discipline:
  *   - The `provider` line is populated from the actor trace's tokenUsage.costUsd when the trace
- *     carries it (a measured value, incl. a measured 0). When the trace carries no costUsd, the
- *     provider line is `null` = not measured (never guessed to 0 just because no-spend was intended).
+ *     carries it (a measured value, incl. a measured 0). Otherwise its `usd` is null = not
+ *     measured, and when the trace's `estimatedCost` prices the tokens, the line carries that
+ *     price as `estimatedUsd`: the figure run.json's model-tokens line gives, from the same
+ *     object. Tokens with no rate, and a run with no token count, say so in the note.
  *   - product/media/payment are `null` by default: core has no signal for those categories, and
  *     only a test can supply one, through `StudyDeps.costProbe`.
  * `injectedLines` lets a test supply known spend for a category,
  * exercising the fail-closed cap enforcement deterministically without a real billable run.
  */
 export function buildCostLedger(args) {
-    const providerLine = typeof args.tokenCostUsd === "number"
-        ? {
-            usd: args.tokenCostUsd,
-            source: "provider-token-usage",
-            note: `Provider spend metered from the actor trace tokenUsage.costUsd (${args.tokenCostUsd} USD).`,
-        }
-        : args.tokenUsage
-            ? {
-                // Tokens counted, no rate to price them. This stays `usd: null` because a guessed
-                // dollar figure would be worse than none, but the note carries the measured fact so a
-                // reader never mistakes "no charge recorded" for "nothing was consumed".
-                usd: null,
-                source: "unpriced-token-usage",
-                note: `Provider spend unpriced: the run consumed ${describeTokenUsage(args.tokenUsage)}, ` +
-                    "but the terminal participant records the model as `codex` and humanish has no rate " +
-                    "for it, so no dollar figure is given. The token count is measured; the price is " +
-                    "not known. Recorded as null, never guessed as 0.",
-            }
-            : {
-                usd: null,
-                source: "unmeasured",
-                note: "Provider spend not measured: the actor trace carried no tokenUsage.costUsd in this run, so it is recorded as null and not guessed as 0.",
-            };
-    const unmeasured = (category) => ({
-        usd: null,
-        count: null,
-        source: "unmeasured",
-        note: `${category} spend not measured: humanish has no ${category} spend signal, and a study cannot supply one. Recorded as null, never guessed as 0.`,
-    });
     const lines = {
         product: args.injectedLines?.product ?? unmeasured("product"),
         media: args.injectedLines?.media ?? unmeasured("media"),
         payment: args.injectedLines?.payment ?? unmeasured("payment"),
-        provider: args.injectedLines?.provider ?? providerLine,
+        provider: args.injectedLines?.provider ?? providerLine(args.trace),
     };
     // knownTotalUsd sums only the non-null lines. A null line contributes nothing and is never
     // coerced to 0 (that would let an unmeasured category masquerade as a measured zero).
@@ -68,6 +41,51 @@ export function buildCostLedger(args) {
         fullyMeasured,
     };
 }
+function unmeasured(category) {
+    return {
+        usd: null,
+        count: null,
+        source: "unmeasured",
+        note: `${category} spend not measured: humanish has no ${category} spend signal, and a study cannot supply one. Recorded as null, never guessed as 0.`,
+    };
+}
+/** The participant's model tokens: a measured charge, an estimate, unpriced, or not counted. */
+function providerLine(trace) {
+    const { tokenUsage, estimatedCost } = trace;
+    if (typeof tokenUsage?.costUsd === "number")
+        return {
+            usd: tokenUsage.costUsd,
+            source: "provider-token-usage",
+            note: `Provider spend metered from the actor trace tokenUsage.costUsd (${tokenUsage.costUsd} USD).`,
+        };
+    if (tokenUsage === undefined)
+        return {
+            usd: null,
+            source: "unmeasured",
+            note: "Provider spend not measured: the actor trace carried no tokenUsage.costUsd in this run, so it is recorded as null and not guessed as 0.",
+        };
+    if (estimatedCost !== undefined && estimatedCost.estimatedCostUsd !== null)
+        return {
+            usd: null,
+            estimatedUsd: estimatedCost.estimatedCostUsd,
+            source: "estimated-token-usage",
+            note: `Provider spend estimated at ${estimatedCost.estimatedCostUsd} USD: the run consumed ` +
+                `${describeTokenUsage(tokenUsage)}, priced at ${estimatedCost.modelId ?? "the participant model's"} ` +
+                `rates as of ${estimatedCost.ratesAsOf}, as run.json's cost summary prices them. No provider ` +
+                "charge was measured, so usd stays null and caps.maxUsd does not count the estimate.",
+        };
+    // Tokens counted, no rate to price them. A guessed dollar figure would be worse than none, but
+    // the note carries the measured fact so a reader never mistakes "no charge recorded" for
+    // "nothing was consumed".
+    return {
+        usd: null,
+        source: "unpriced-token-usage",
+        note: `Provider spend unpriced: the run consumed ${describeTokenUsage(tokenUsage)}, but humanish ` +
+            `has no rate for ${estimatedCost?.modelId === undefined ? "the participant's model" : `the model ${estimatedCost.modelId}`}, ` +
+            "so no dollar figure is given. The token count is measured; the price is not known. " +
+            "Recorded as null, never guessed as 0.",
+    };
+}
 /** True when no cost line carries a dollar value, so a no-spend proof has nothing to stand on. */
 export function noSpendLineMeasured(proof) {
     return proof.knownZeroLines.length + proof.knownNonZeroLines.length === 0;
@@ -80,19 +98,24 @@ export function noSpendNotEstablished(maxUsd) {
     return `No-spend proof not established for maxUsd=${maxUsd}: no spend line was measured.`;
 }
 /**
- * What the ledger measured, in words: the dollar lines it knows, provider tokens it counted but
- * could not price, and the lines it has no signal for. A reader of a maxUsd=0 run must not take
- * an all-null ledger for a proven $0.
+ * What the ledger measured, in words: the dollar lines it knows, the provider tokens it counted
+ * with their estimate or as unpriced, and the lines it has no signal for. A reader of a maxUsd=0
+ * run must not take an all-null ledger for a proven $0.
  */
 export function describeMeasuredSpend(ledger, tokenUsage) {
     const measured = COST_CATEGORIES.filter((c) => ledger.lines[c].usd !== null).map((c) => `${c} ${ledger.lines[c].usd} USD`);
-    const unpricedProvider = ledger.lines.provider.source === "unpriced-token-usage";
-    const unmeasured = COST_CATEGORIES.filter((c) => ledger.lines[c].usd === null && !(c === "provider" && unpricedProvider));
+    const provider = ledger.lines.provider;
+    const countedProvider = provider.usd === null &&
+        (provider.source === "unpriced-token-usage" || provider.source === "estimated-token-usage");
+    const unmeasured = COST_CATEGORIES.filter((c) => ledger.lines[c].usd === null && !(c === "provider" && countedProvider));
+    const counts = tokenUsage === undefined ? "" : ` (${describeTokenUsage(tokenUsage)})`;
     return [
         measured.length > 0 ? `Measured: ${measured.join(", ")}.` : "",
-        unpricedProvider
-            ? `Provider tokens were consumed${tokenUsage === undefined ? "" : ` (${describeTokenUsage(tokenUsage)})`} and are unpriced, not zero.`
-            : "",
+        !countedProvider
+            ? ""
+            : provider.estimatedUsd === undefined
+                ? `Provider tokens were consumed${counts} and are unpriced, not zero.`
+                : `Provider tokens${counts} are estimated at ${provider.estimatedUsd} USD, the participant's model cost, which caps.maxUsd does not count.`,
         unmeasured.length > 0 ? `Not measured (null, not claimed zero): ${unmeasured.join(", ")}.` : "",
     ]
         .filter((part) => part.length > 0)

package/dist/routes/terminal/live-finish.js

@@ -81,17 +81,13 @@ async function settleLiveLedgers(inputs, trace, normalizedTranscript) {
     const { recordLifecycle, lifecycle, commandLog, interventions, terminalEvents } = inputs.recorder;
     // --- Spend ledger + no-spend proof + full caps enforcement (fail-closed). ---
     // The cost ledger is derived, with the null discipline: provider spend from the trace's
-    // tokenUsage.costUsd when present (else null = not measured), product/media/payment null by
-    // default (core has no signal). The costProbe hook lets tests inject known
-    // spend to exercise the fail-closed cap without a real billable run.
+    // tokenUsage.costUsd when present, else null with the trace's token estimate beside it, and
+    // product/media/payment null by default (core has no signal). The costProbe hook lets tests
+    // inject known spend to exercise the fail-closed cap without a real billable run.
     const injectedLines = costProbe?.(trace.tokenUsage?.costUsd === undefined ? {} : { tokenCostUsd: trace.tokenUsage.costUsd });
     if (costProbe)
         await validatePreparedRunArtifactPaths(runPaths);
-    const cost = buildCostLedger({
-        ...(trace.tokenUsage?.costUsd === undefined ? {} : { tokenCostUsd: trace.tokenUsage.costUsd }),
-        ...(trace.tokenUsage === undefined ? {} : { tokenUsage: trace.tokenUsage }),
-        ...(injectedLines ? { injectedLines } : {}),
-    });
+    const cost = buildCostLedger({ trace, ...(injectedLines ? { injectedLines } : {}) });
     const noSpendProof = buildNoSpendProof(cost, maxUsd ?? null, trace.tokenUsage);
     const proofVerdict = !noSpendProof.satisfied
         ? `No-spend proof not satisfied for maxUsd=${maxUsd ?? "null"}.`
@@ -138,8 +134,9 @@ export async function finishLiveTerminalSession(inputs) {
     const participant = terminalParticipantFacts(trace, session.error);
     const judgment = judgeTerminal({ dryRun: false, participant });
     // The run cost summary, as the computer-use route records it: the sandbox's compute time from
-    // its span and observed size, and the participant's tokens (unpriced for Codex). It is not part
-    // of the cap ledger above, whose lines sum against caps.maxUsd.
+    // its span and observed size, and the participant's tokens at trace.estimatedCost, the price the
+    // ledger's provider line also carries. It is not part of the cap ledger above, whose lines sum
+    // against caps.maxUsd.
     const desktops = session.runCostDesktops();
     const runCost = buildRunCostSummary({
         participants: [{ trace }],

package/dist/routes/terminal/live-sandbox.d.ts

@@ -45,7 +45,7 @@ export declare class LiveTerminalSandbox {
     private readonly wallClockMs;
     private readonly sandboxTimeoutMs;
     private sandbox;
-    private module;
+    private account;
     private allocation;
     private startupCleanup;
     private startupCleanupDetail;

package/dist/routes/terminal/live-sandbox.js

@@ -11,6 +11,7 @@ import { extractLocalActorVerdict, normalizeLocalActorTranscript, } from "../../
 import { NODE_BOOTSTRAP_COMMAND, NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { observeDesktopResources, } from "../../substrates/e2b/desktop-resources.js";
 import { acquireE2BShellSandbox } from "../../substrates/e2b/sandbox.js";
+import { e2bAccount } from "../../substrates/e2b/connection.js";
 import { E2BDesktopStartupError, loadE2BDesktopModule, } from "../../substrates/e2b/sdk.js";
 import { shellQuote } from "../../substrates/shell.js";
 import { buildOpenAiEgressNetwork } from "./runtime-auth.js";
@@ -36,7 +37,7 @@ export class LiveTerminalSandbox {
     wallClockMs;
     sandboxTimeoutMs;
     sandbox;
-    module;
+    account;
     allocation;
     startupCleanup;
     startupCleanupDetail;
@@ -60,7 +61,6 @@ export class LiveTerminalSandbox {
         // Declared egress allowlist, or undefined for the historical unrestricted default.
         const egressAllow = plan.egressAllow;
         const sandboxModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
-        this.module = sandboxModule;
         await validatePreparedRunArtifactPaths(runPaths);
         // No sandbox-global env in either mode. In openai-egress, only this host-side SDK request
         // carries the real runtime key; participant commands receive an inert placeholder. The proxy
@@ -71,16 +71,19 @@ export class LiveTerminalSandbox {
         const network = runtimeEnv.mode === "openai-egress"
             ? buildOpenAiEgressNetwork(runtimeEnv.keyValue, routing)
             : routing;
+        const options = {
+            apiKey: e2bApiKey,
+            requestTimeoutMs,
+            timeoutMs: sandboxTimeoutMs,
+            metadata,
+            ...(network === undefined ? {} : { network }),
+            lifecycle: { onTimeout: "kill" },
+        };
+        // Teardown's check by id reaches the account the create used, whatever process.env names.
+        this.account = e2bAccount(sandboxModule, options);
         const acquired = await acquireE2BShellSandbox({
             module: sandboxModule,
-            options: {
-                apiKey: e2bApiKey,
-                requestTimeoutMs,
-                timeoutMs: sandboxTimeoutMs,
-                metadata,
-                ...(network === undefined ? {} : { network }),
-                lifecycle: { onTimeout: "kill" },
-            },
+            options,
             retry: {
                 // A failed first attempt may have allocated a sandbox whose id never reached this run;
                 // its own kill-on-timeout reclaims it.
@@ -418,7 +421,7 @@ export class LiveTerminalSandbox {
         // --- Proven cleanup, by exact id, never Sandbox.list. ---
         this.cleanup = await teardownSandbox({
             allocation: this.allocation,
-            sandboxModule: this.module,
+            account: this.account,
             ...(this.startupCleanup === undefined ? {} : { startupCleanup: this.startupCleanup }),
             startupCleanupDetail: this.startupCleanupDetail,
             requestTimeoutMs,

package/dist/routes/terminal/plan.d.ts

@@ -1,5 +1,6 @@
 import type { RoutePlanResult, RouteRefusal, TerminalPlan } from "../../study/plan-types.js";
 import type { StudyConfig } from "../../study/types.js";
+import { type SandboxCeiling } from "../../substrates/e2b/lifetime.js";
 import { type TerminalProductStudyResult } from "./types.js";
 /** The error a terminal study returns before a run starts. `actor` names the registered actor. */
 export interface TerminalRefusal extends RouteRefusal<"terminal", NonNullable<TerminalProductStudyResult["error"]>["code"]> {
@@ -14,4 +15,6 @@ export declare function planTerminalStudy(config: StudyConfig, input: {
     readonly dryRun: boolean;
     /** A test's costProbe can measure spend lines, so a positive maxUsd can trip. */
     readonly hasCostProbe?: boolean;
+    /** The longest sandbox lifetime the operator's E2B plan allows (sandboxCeiling). */
+    readonly sandboxCeiling: SandboxCeiling;
 }): TerminalPlanResult;

package/dist/routes/terminal/plan.js

@@ -8,7 +8,7 @@ import { actorRegistry, isTerminalActorDescriptor } from "../../actors/registry.
 import { isNonEmpty, planBase } from "../../study/plan-base.js";
 import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { desktopMediaValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
-import { MAX_SANDBOX_MS } from "../../substrates/e2b/lifetime.js";
+import { ceilingAdvice } from "../../substrates/e2b/lifetime.js";
 import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { terminalSandboxTimeoutMs } from "./lifetime.js";
 import { isExactRuntimeVersion, TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./runtime.js";
@@ -105,13 +105,16 @@ export function planTerminalStudy(config, input) {
     if (maxUsd > 0 && input.hasCostProbe !== true)
         return refuse("HUMANISH_TERMINAL_UNPRICED_CAP", `caps.maxUsd=${maxUsd} cannot be enforced: Codex reports no provider cost for the participant (its token cost is only estimated after the run) and no product, media or payment spend is measured, so a positive dollar cap can never trip. Set caps.maxUsd to 0 and bound the run with caps.maxMinutes, the codex command's wall-clock kill. No sandbox was created and the runtime key was not used.`, descriptor.id);
     // The sandbox's timeout covers the steps before the codex command, maxMinutes and the teardown
-    // buffer, and E2B refuses a sandbox over an hour. Refuse here, with the arithmetic, rather than
-    // after the plan prints, from a provider 400 that names neither knob.
+    // buffer, and E2B refuses a sandbox past the plan's ceiling. Refuse here, with the arithmetic,
+    // rather than after the plan prints, from a provider 400 that names neither knob.
+    const ceiling = input.sandboxCeiling;
+    if (!ceiling.ok)
+        return refuse("HUMANISH_TERMINAL_CAPS_INVALID", ceiling.message, descriptor.id);
     const productInstall = shared.product.install !== undefined;
     const sandboxTimeoutMs = terminalSandboxTimeoutMs({ maxMinutes, productInstall });
-    if (sandboxTimeoutMs > MAX_SANDBOX_MS) {
+    if (sandboxTimeoutMs > ceiling.ms) {
         const headroomMinutes = (sandboxTimeoutMs - maxMinutes * 60_000) / 60_000;
-        return refuse("HUMANISH_TERMINAL_CAPS_INVALID", `caps.maxMinutes ${maxMinutes} derives a ${sandboxTimeoutMs / 60_000}m sandbox deadline, and a sandbox may not live longer than ${MAX_SANDBOX_MS / 60_000}m. The deadline is maxMinutes plus ${headroomMinutes}m: the Node bootstrap (${NODE_BOOTSTRAP_TIMEOUT_MS / 60_000}m), the runtime version check (${TERMINAL_RUNTIME_VERSION_TIMEOUT_MS / 60_000}m)${productInstall ? `, the product setup (${PRODUCT_SETUP_TIMEOUT_MS / 60_000}m)` : ""} and the teardown buffer (${TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS / 60_000}m). Lower caps.maxMinutes to at most ${MAX_SANDBOX_MS / 60_000 - headroomMinutes}. No sandbox was created and the runtime key was not used.`, descriptor.id);
+        return refuse("HUMANISH_TERMINAL_CAPS_INVALID", `caps.maxMinutes ${maxMinutes} derives a ${sandboxTimeoutMs / 60_000}m sandbox deadline, and a sandbox may not live longer than ${ceiling.ms / 60_000}m. The deadline is maxMinutes plus ${headroomMinutes}m: the Node bootstrap (${NODE_BOOTSTRAP_TIMEOUT_MS / 60_000}m), the runtime version check (${TERMINAL_RUNTIME_VERSION_TIMEOUT_MS / 60_000}m)${productInstall ? `, the product setup (${PRODUCT_SETUP_TIMEOUT_MS / 60_000}m)` : ""} and the teardown buffer (${TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS / 60_000}m). Lower caps.maxMinutes to at most ${ceiling.ms / 60_000 - headroomMinutes}.${ceilingAdvice(sandboxTimeoutMs)} No sandbox was created and the runtime key was not used.`, descriptor.id);
     }
     return {
         ok: true,

package/dist/routes/terminal/sandbox.d.ts

@@ -1,5 +1,6 @@
 import type { OwnedDesktopAllocation } from "../../substrates/desktop-session.js";
-import { E2BDesktopStartupError, type E2BDesktopModule } from "../../substrates/e2b/sdk.js";
+import type { E2BAccount } from "../../substrates/e2b/connection.js";
+import { E2BDesktopStartupError } from "../../substrates/e2b/sdk.js";
 import type { TerminalLedgers } from "./types.js";
 /**
  * Tear the sandbox down and prove it by exact id, never by Sandbox.list (humanish must never
@@ -14,8 +15,8 @@ import type { TerminalLedgers } from "./types.js";
 export declare function teardownSandbox(args: {
     /** The allocation from acquisition; its release kills the exact id it captured. */
     allocation: OwnedDesktopAllocation | undefined;
-    /** For the Sandbox.getInfo(id) re-check only. */
-    sandboxModule: E2BDesktopModule | undefined;
+    /** The account the create used, for the Sandbox.getInfo(id) re-check only. */
+    account: E2BAccount | undefined;
     startupCleanup?: E2BDesktopStartupError["cleanup"];
     /** Why the startup guard's cleanup is unconfirmed, when it knows. */
     startupCleanupDetail?: string | undefined;

package/dist/routes/terminal/sandbox.js

@@ -1,5 +1,5 @@
 import { toErrorMessage } from "../../evidence/redaction.js";
-import { E2BDesktopStartupError, isSandboxNotFoundError, } from "../../substrates/e2b/sdk.js";
+import { E2BDesktopStartupError, isSandboxNotFoundError } from "../../substrates/e2b/sdk.js";
 import { releaseUnavailableDetail } from "../../substrates/e2b/sandbox.js";
 /**
  * Tear the sandbox down and prove it by exact id, never by Sandbox.list (humanish must never
@@ -12,8 +12,8 @@ import { releaseUnavailableDetail } from "../../substrates/e2b/sandbox.js";
  * fails closed on an unproven teardown.
  */
 export async function teardownSandbox(args) {
-    const { allocation, sandboxModule, startupCleanup, startupCleanupDetail, requestTimeoutMs, sanitize, recordLifecycle, warnings, } = args;
-    if (allocation === undefined || !sandboxModule) {
+    const { allocation, account, startupCleanup, startupCleanupDetail, requestTimeoutMs, sanitize, recordLifecycle, warnings, } = args;
+    if (allocation === undefined || account === undefined) {
         // create() can reject after its constructor acquired a handle. The default loader retains
         // that authority and reclaims it before rejecting; the route itself never receives its ID.
         if (startupCleanup === "killed" || startupCleanup === "already_gone") {
@@ -58,7 +58,7 @@ export async function teardownSandbox(args) {
     const killNote = released.reason === "terminated"
         ? "kill(id) returned true (found and killed)"
         : "kill(id) found the exact sandbox already gone (404)";
-    if (typeof sandboxModule.Sandbox.getInfo !== "function") {
+    if (account.getInfo === undefined) {
         recordLifecycle("terminal-lab.cleanup.killed", `Sandbox ${sandboxId} reclaimed: ${killNote}; the installed SDK has no getInfo(id) to re-verify, so kill(id)'s own result is the proof.`);
         return {
             killed: true,
@@ -67,7 +67,7 @@ export async function teardownSandbox(args) {
         };
     }
     try {
-        const info = await sandboxModule.Sandbox.getInfo(sandboxId, { requestTimeoutMs });
+        const info = await account.getInfo(sandboxId, { requestTimeoutMs });
         const state = info.state ?? "unknown";
         recordLifecycle("terminal-lab.cleanup.unconfirmed", `Sandbox ${sandboxId} ${killNote}, but getInfo(id) still reports state=${state} (not confirmed reclaimed by id).`);
         return {

package/dist/routes/terminal/token-usage.d.ts

@@ -13,6 +13,5 @@ export declare function terminalUsageRecords(lines: string): string[];
  */
 export declare function parseTerminalTokenUsage(transcript: string): ActorTokenUsage | undefined;
 /** Human-readable token statement for the cost ledger and the no-spend proof. Reports what was
- *  counted and says plainly that it is unpriced, so a reader never reads "no charge recorded" as
- *  "nothing was consumed". */
+ *  counted, so a reader never reads "no charge recorded" as "nothing was consumed". */
 export declare function describeTokenUsage(usage: ActorTokenUsage): string;

package/dist/routes/terminal/token-usage.js

@@ -9,10 +9,9 @@
 //   {"type":"turn.completed","usage":{"input_tokens":201536,"cached_input_tokens":170558,
 //    "cache_write_input_tokens":30951,"output_tokens":2283,"reasoning_output_tokens":902}}
 //
-// So the route can record a measured token fact even when it cannot record a priced one. Rates stay
-// out of this module deliberately: pricing lives in src/run/pricing.ts, and the terminal route has no
-// real model id to price against (it records `model: "codex"`), so the output is
-// tokens-known-rate-unknown rather than a guessed dollar figure.
+// So the route records a measured token fact whether or not a rate prices it. Rates stay out of this
+// module: the route prices these counts once, from the model it passed to Codex, with
+// src/run/pricing.ts (live-finish.ts), and the ledger and run.json both read that estimate.
 // Bounded to a single line on purpose. `[^}]*` would run past a truncated record's missing brace
 // and swallow the next, valid record's body, silently dropping a real turn from the count.
 const USAGE_RE = /"type"\s*:\s*"turn\.completed"\s*,\s*"usage"\s*:\s*(\{[^}\n]*\})/g;
@@ -81,8 +80,7 @@ export function parseTerminalTokenUsage(transcript) {
     };
 }
 /** Human-readable token statement for the cost ledger and the no-spend proof. Reports what was
- *  counted and says plainly that it is unpriced, so a reader never reads "no charge recorded" as
- *  "nothing was consumed". */
+ *  counted, so a reader never reads "no charge recorded" as "nothing was consumed". */
 export function describeTokenUsage(usage) {
     const parts = [];
     if (usage.input !== undefined)

package/dist/routes/terminal/types.d.ts

@@ -232,6 +232,11 @@ export interface InterventionRecord {
 export interface CostLine {
     /** known zero (0) | not measured (null). The key is always present when the line is applicable. */
     usd: number | null;
+    /** The provider line's price for its counted tokens, from the trace's `estimatedCost` (the
+     *  figure run.json's model-tokens line gives), when no charge was measured. An estimate from a
+     *  rate table: `usd` stays null, and neither `knownTotalUsd` nor caps.maxUsd counts it. Present
+     *  only with source `estimated-token-usage`. */
+    estimatedUsd?: number;
     /** Optional billable-unit count, same discipline: a known count, or null = not measured. */
     count?: number | null;
     /** How this line's value was established (provenance for the verifier + the human reviewer). */
@@ -239,7 +244,10 @@ export interface CostLine {
     /** Tokens were counted but no rate could price them, so `usd` stays null while the note
      *  carries the measured token totals. Distinct from "unmeasured", which means no
      *  signal at all. */
-     | "unpriced-token-usage";
+     | "unpriced-token-usage"
+    /** Tokens were counted and priced from a rate table: `estimatedUsd` holds the estimate and
+     *  `usd` stays null, since no charge was measured. */
+     | "estimated-token-usage";
     /** A short, public-safe note (never a secret value). */
     note: string;
 }

package/dist/run/bundle-shape.js

@@ -213,10 +213,15 @@ export const ARCHIVE_SHA256_PATTERN = /^[a-f0-9]{64}$/;
 function isRunSubjectProvenance(value) {
     if (!isRecord(value))
         return false;
-    if (value.source !== "clone" && value.source !== "app-url" && value.source !== "local-tree")
+    if (value.source !== "clone" &&
+        value.source !== "app-url" &&
+        value.source !== "local-tree" &&
+        value.source !== "desktop-cli")
         return false;
     if (value.repo !== undefined && typeof value.repo !== "string")
         return false;
+    if (value.product !== undefined && typeof value.product !== "string")
+        return false;
     if (value.commit !== undefined && typeof value.commit !== "string")
         return false;
     if (value.archiveSha256 !== undefined &&

package/dist/run/bundle.d.ts

@@ -158,9 +158,11 @@ export interface RunSubjectStateStepRecord {
  * pre-existing bundles).
  */
 export interface RunSubjectProvenance {
-    source: "clone" | "app-url" | "local-tree";
+    source: "clone" | "app-url" | "local-tree" | "desktop-cli";
     /** Clone-route only. Honors policies.redactRepos exactly as the provenance event does. */
     repo?: string;
+    /** Desktop-cli only: the product the study declares in `subject.product.name`. */
+    product?: string;
     /** Clone-route: the cloned commit SHA. Local-tree route: the host-side HEAD at pack time,
      *  when the packed root was a git work tree. */
     commit?: string;
@@ -184,8 +186,8 @@ export interface RunSubjectProvenance {
          *   an external DB is still unpinned overall).
          * declared-not-run: steps declared but not (all) executed ok: dry-run contract bundles
          *   and failed live provisioning.
-         * undeclared: no subject.state block (stateless apps, app-url subjects), the explicit
-         *   "absence declared" marker that provenance requires when there is none.
+         * undeclared: no subject.state block (stateless apps, app-url and desktop-cli subjects),
+         *   the explicit "absence declared" marker that provenance requires when there is none.
          * external-public: an operator-declared, operator-owned public deployment used
          *   directly as the shared plane; humanish neither provisioned nor seeded it (no getHost, no
          *   clone, no in-sandbox filesystem). It is not "seeded" (nothing was seeded) and not "unpinned" (this is

package/dist/run/contained-output.d.ts

@@ -46,13 +46,61 @@ export declare function writeContainedOutputFile(rootInput: PreparedOutputRoot,
  * writeContainedOutputFile renames a finished file into place instead, replacing what is there.
  */
 export declare function createContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string): Promise<void>;
-/** Read one regular file only when both lexical and physical paths stay in root. */
-export declare function readContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<Buffer | null>;
 /**
- * Whether a contained path is confirmed absent. A present entry that readContainedRegularFile
- * refuses or fails to read is not absent.
+ * A file in a run directory or a preflight journal. verify reads every run file whole to scan it,
+ * and a frame whole to check it, so this covers the largest screenshot src/evidence/image.ts
+ * accepts (32 MiB). Every other reader of a run file uses the same limit, so no command reads a
+ * run file that verify could not scan.
  */
-export declare function containedPathAbsent(rootInput: PreparedOutputRoot, relativePath: string): Promise<boolean>;
+export declare const RUN_ARTIFACT_MAX_BYTES: number;
+/** `.humanish/runs/latest.json`: a run id and a path. */
+export declare const LATEST_POINTER_MAX_BYTES: number;
+/** A file a person writes in the project: study, persona and scenario YAML, package.json, agent instructions. */
+export declare const PROJECT_FILE_MAX_BYTES: number;
+/**
+ * Why a contained read did not read a file that is there. `too-large`: it holds more than the
+ * limit. `changed`: it, its folder or the root changed while it was opened or read, which
+ * includes growing past the limit. `directory`: a folder is at the path. `not-regular`: a link, a
+ * hard link or a special file. `unsafe-path`: the path leaves the root or passes through a link.
+ * `unreadable`: the system refused the open or the read.
+ */
+export type ContainedRefusalReason = "too-large" | "changed" | "directory" | "not-regular" | "unsafe-path" | "unreadable";
+/** A file that is there and was not read: why, and the most the read would have taken. */
+export interface ContainedRefusal {
+    readonly status: "refused";
+    readonly reason: ContainedRefusalReason;
+    readonly limit: number;
+}
+/** What a contained read found: the bytes, nothing at the path, or a file it refused. */
+export type ContainedRead = {
+    readonly status: "read";
+    readonly bytes: Buffer;
+} | {
+    readonly status: "missing";
+} | ContainedRefusal;
+/** `relativePath` and why it was refused, as a clause: "x.yaml is larger than 4194304 bytes, ...". */
+export declare function refusalText(relativePath: string, refusal: ContainedRefusal): string;
+/** A refused contained read, for a caller that stops on one. The message names the file. */
+export declare class ContainedReadRefusedError extends Error {
+    readonly relativePath: string;
+    readonly refusal: ContainedRefusal;
+    constructor(relativePath: string, refusal: ContainedRefusal);
+}
+/**
+ * Read one regular file only when both lexical and physical paths stay in root and it holds at
+ * most `maxBytes`. A larger file is refused without being read, and one that grows past
+ * `maxBytes` while it is read is refused after at most `maxBytes + 1` bytes. `missing` means
+ * nothing is at the path, or a folder on it is missing.
+ */
+export declare function readContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<ContainedRead>;
+/**
+ * At most `maxBytes` from the start of an opened file, or null when it holds more. It reads by
+ * position, in chunks of up to 64 KiB, and stops one byte past the limit, so a file that grew
+ * after it was opened is never read whole.
+ */
+export declare function readOpenedAtMost(handle: FileHandle, maxBytes: number): Promise<Buffer | null>;
 /** The caller owns this checked descriptor and must close it after reading/streaming. */
 export declare function openContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<FileHandle | null>;
 export declare function assertSafeOutputPathSegment(value: string, label?: string): void;
+/** A non-empty relative path with no empty, `.` or `..` segment: the names a contained read accepts. */
+export declare function isSafeRelativeFilePath(value: string): boolean;