humanish 0.141.0 → 0.142.0

package/dist/remote/reattach.js

@@ -0,0 +1,81 @@
+// Coming back to a remote run whose launcher let it go (a closed terminal): find its runner from
+// the run directory here, serve its live Observer again and follow it to the end, as the launcher
+// would have.
+import { readContainedRegularFile } from "../run/contained-output.js";
+import { bindExistingRunArtifactPaths } from "../run/paths.js";
+import { isSandboxProviderId, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "../run/sandbox-receipts.js";
+import { loadE2BBaseModule } from "../substrates/e2b/base-module.js";
+import { e2bConnection } from "../substrates/e2b/connection.js";
+import { isSandboxNotFoundError } from "../substrates/e2b/sdk.js";
+import { loadModalShellModule } from "../substrates/modal/sandbox.js";
+import { followRemoteRun, watchSignals } from "./launch.js";
+import { serveObserverProxy } from "./observer-proxy.js";
+import { RUNNER_OBSERVER_PORT, runnerOf } from "./runner.js";
+/**
+ * The remote run `runId` names, when its directory here has a remote.json and no run.json yet;
+ * undefined for any other run, which the Observer serves from its files as before.
+ */
+export async function remoteRunHere(cwd, runId) {
+    let paths;
+    try {
+        paths = await bindExistingRunArtifactPaths(cwd, runId);
+    }
+    catch {
+        return undefined;
+    }
+    if ((await readText(paths, "run.json")) !== undefined)
+        return undefined;
+    const record = await readText(paths, "remote.json");
+    if (record === undefined)
+        return undefined;
+    const provider = JSON.parse(record).provider;
+    if (typeof provider !== "string" || !isSandboxProviderId(provider))
+        return undefined;
+    const journal = (await readText(paths, SANDBOX_RECEIPTS_ARTIFACT)) ?? "";
+    // Until the run is copied back, this directory's journal holds one receipt: the runner's, the
+    // only sandbox this machine creates for a remote run.
+    const [runner, ...others] = parseSandboxReceipts(journal);
+    if (runner === undefined || others.length > 0)
+        return undefined;
+    return { paths, runId, provider, runnerId: runner.sandboxId };
+}
+async function readText(root, file) {
+    const read = await readContainedRegularFile(root, file, 16 * 1024 * 1024);
+    return read.status === "read" ? Buffer.from(read.bytes).toString("utf8") : undefined;
+}
+/** Reconnect to `run`'s runner, serve its Observer on 127.0.0.1:`port` and follow it to the end. */
+export async function reattachRemoteRun(context, run, port) {
+    const module = run.provider === "modal" ? await loadModalShellModule(context.env) : await loadE2BBaseModule();
+    let sandbox;
+    try {
+        // A Modal module takes its connection from context.env and ignores this one.
+        sandbox = await module.Sandbox.connect(run.runnerId, e2bConnection(context.env));
+    }
+    catch (error) {
+        if (!isSandboxNotFoundError(error))
+            throw error;
+        return {
+            runId: run.runId,
+            exitCode: 2,
+            error: `its runner sandbox is gone, so the run was not copied back. Stop anything it left with humanish reclaim --run ${run.runId}`,
+        };
+    }
+    const runner = runnerOf(sandbox);
+    const signals = watchSignals();
+    const proxy = await serveObserverProxy(await runner.sandbox.portAccess(RUNNER_OBSERVER_PORT), port);
+    try {
+        context.say(`Reconnected to run ${run.runId} on its runner.`);
+        return await followRemoteRun({
+            launch: context,
+            runner,
+            paths: run.paths,
+            runId: run.runId,
+            signals,
+            proxyUrl: proxy.url,
+        });
+    }
+    finally {
+        signals.dispose();
+        await proxy.close();
+    }
+}

package/dist/remote/runner.d.ts

@@ -0,0 +1,68 @@
+import type { E2BDesktopSandbox } from "../substrates/e2b/sdk.js";
+import { type Shell } from "../substrates/shell.js";
+/** The port the runner's Observer listens on. */
+export declare const RUNNER_OBSERVER_PORT = 7000;
+/** A runner sandbox and the shell into it. */
+export interface Runner {
+    readonly sandbox: E2BDesktopSandbox;
+    readonly shell: Shell;
+}
+export declare function runnerOf(sandbox: E2BDesktopSandbox): Runner;
+/**
+ * Install Node and the humanish package `tarball` (this machine's own humanish, packed), with the
+ * provider SDKs its participants need at `peers` (name@version). Returns the installed version.
+ */
+export declare function installHumanish(runner: Runner, tarball: Uint8Array, peers: readonly string[]): Promise<string>;
+/**
+ * Upload each project-relative file in `files`, and every file under each directory in
+ * `directories` that exists here, to the same place in the runner's project.
+ */
+export declare function uploadProject(runner: Runner, cwd: string, files: readonly string[], directories: readonly string[]): Promise<number>;
+/** What the runner's run is started with. */
+export interface RemoteRunStart {
+    /** The study file, relative to the project. */
+    study: string;
+    runId: string;
+    ownerKey: string;
+    /** Only these names reach the run, each with its value from this machine. */
+    env: Readonly<Record<string, string>>;
+}
+/**
+ * Start the study's run in the runner as `humanish watch --serve`, so the run process itself serves
+ * the Observer with its live desktop streams, and writes its result to a file the launcher reads.
+ */
+export declare function startRemoteRun(runner: Runner, start: RemoteRunStart): Promise<void>;
+/** How the runner's run is going, read from its own files. */
+export interface RemoteRunState {
+    /** status.json's `state`, once the run has written one. */
+    state?: string;
+    /** The result the run wrote when it ended, with the exit code the command would return. */
+    result?: {
+        exitCode: number;
+        result: unknown;
+    };
+    /** Whether the run's process is still alive in the runner. */
+    alive: boolean;
+    /** The last lines the run wrote to stderr. */
+    errTail: string;
+}
+export declare function readRemoteRun(runner: Runner, runId: string): Promise<RemoteRunState>;
+/** One file of the runner's run directory: its path in the directory and its sha256. */
+export interface RemoteFile {
+    path: string;
+    sha256: string;
+}
+/**
+ * The regular files of the runner's run directory and their digests. Refuses a directory that holds
+ * a link, which a run never writes.
+ */
+export declare function listRemoteRun(runner: Runner, runId: string): Promise<RemoteFile[]>;
+/** sha256sum lines, `<hex>  ./<path>`, as RemoteFiles with paths relative to the directory. */
+export declare function parseDigests(output: string): RemoteFile[];
+/** The bytes of one file of the runner's run directory, checked against its listed digest. */
+export declare function readRemoteFile(runner: Runner, runId: string, file: RemoteFile): Promise<Uint8Array>;
+/**
+ * Ask the runner's run to stop as a signal would, so it reclaims its participants and ends. The
+ * `[h]` keeps the pattern from matching the shell that runs it.
+ */
+export declare function stopRemoteRun(runner: Runner): Promise<void>;

package/dist/remote/runner.js

@@ -0,0 +1,216 @@
+// What the launcher does inside a runner sandbox, over the sandbox port's commands and files: install
+// Node and this humanish, upload the study's files, start its run, read how it is going, and copy
+// the finished run back.
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { e2bShell } from "../substrates/e2b/shell.js";
+import { shellQuote } from "../substrates/shell.js";
+import { tailOf } from "../substrates/shell.js";
+/** The project directory in the runner, under the sandbox user's home on both providers. */
+const RUNNER_PROJECT = "project";
+/** Where the runner keeps the launcher's own files: the result file and the run's output. */
+const RUNNER_STATE = ".humanish-remote";
+/** The port the runner's Observer listens on. */
+export const RUNNER_OBSERVER_PORT = 7000;
+/**
+ * The Node release the runner runs humanish on, with the sha256 nodejs.org publishes for each
+ * build (SHASUMS256.txt). The runner checks the download against it before extracting.
+ */
+const NODE = {
+    version: "22.23.4",
+    sha256: {
+        x64: "b8492284c76a54baf58d61668dd0e41ee0fc98adabf9503d30f05d08f55b4406",
+        arm64: "f7a1e486dbc8b286847815b477d4fb5e9fb963ed4489c3e1588853d685f589f9",
+    },
+};
+export function runnerOf(sandbox) {
+    return { sandbox, shell: e2bShell(sandbox) };
+}
+/** A command failed in the runner; the message carries its exit code and output tail. */
+class RunnerCommandError extends Error {
+    constructor(step, result) {
+        super(`${step} failed in the runner sandbox (exit ${result.exitCode}): ${tailOf(result.stderr || result.stdout)}`);
+        this.name = "RunnerCommandError";
+    }
+}
+async function runOrFail(runner, step, command, timeoutMs) {
+    const result = await runner.shell.run(command, { timeoutMs });
+    if (result.exitCode !== 0)
+        throw new RunnerCommandError(step, result);
+    return result;
+}
+/**
+ * Install Node and the humanish package `tarball` (this machine's own humanish, packed), with the
+ * provider SDKs its participants need at `peers` (name@version). Returns the installed version.
+ */
+export async function installHumanish(runner, tarball, peers) {
+    await runner.shell.writeFile(`${RUNNER_STATE}/humanish.tgz`, toArrayBuffer(tarball));
+    const { version, sha256 } = NODE;
+    const script = [
+        "set -eu",
+        `cd "$HOME/${RUNNER_STATE}"`,
+        'case "$(uname -m)" in x86_64) arch=x64;; aarch64|arm64) arch=arm64;; *) echo "unsupported CPU $(uname -m)" >&2; exit 1;; esac',
+        `if [ "$arch" = x64 ]; then sum=${sha256.x64}; else sum=${sha256.arm64}; fi`,
+        `curl -fsSL -o node.tgz "https://nodejs.org/dist/v${version}/node-v${version}-linux-$arch.tar.gz"`,
+        'echo "$sum  node.tgz" | sha256sum -c - >/dev/null',
+        "mkdir -p node && tar -xzf node.tgz --strip-components=1 -C node && rm node.tgz",
+        `export PATH="$HOME/${RUNNER_STATE}/node/bin:$PATH" npm_config_prefix="$HOME/${RUNNER_STATE}/node"`,
+        `npm install -g --no-fund --no-audit --loglevel=error ./humanish.tgz ${peers.map(shellQuote).join(" ")}`,
+        "humanish --version",
+    ].join("\n");
+    const result = await runOrFail(runner, "Installing humanish", `bash -c ${shellQuote(script)}`, 600_000);
+    return result.stdout.trim().split("\n").at(-1) ?? "";
+}
+/**
+ * Upload each project-relative file in `files`, and every file under each directory in
+ * `directories` that exists here, to the same place in the runner's project.
+ */
+export async function uploadProject(runner, cwd, files, directories) {
+    const all = new Set(files);
+    for (const directory of directories)
+        for (const file of await filesUnder(cwd, directory))
+            all.add(file);
+    const root = await realpath(cwd);
+    for (const file of all) {
+        // A link could hand the runner a file from anywhere on this machine, such as a key file, so
+        // only a regular file whose real path is where the study names it is uploaded.
+        const real = await realpath(path.join(cwd, file)).catch(() => undefined);
+        if (real !== path.join(root, file) || !(await lstat(real)).isFile())
+            throw new Error(`${file} is a link or not a regular file, so it is not uploaded to the runner.`);
+        const bytes = await readFile(real);
+        await runner.shell.writeFile(`${RUNNER_PROJECT}/${file}`, toArrayBuffer(bytes));
+    }
+    return all.size;
+}
+async function filesUnder(cwd, directory) {
+    let entries;
+    try {
+        entries = await readdir(path.join(cwd, directory), { recursive: true, withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => path.relative(cwd, path.join(entry.parentPath, entry.name)).split(path.sep).join("/"));
+}
+/**
+ * Start the study's run in the runner as `humanish watch --serve`, so the run process itself serves
+ * the Observer with its live desktop streams, and writes its result to a file the launcher reads.
+ */
+export async function startRemoteRun(runner, start) {
+    const args = [
+        "humanish",
+        "watch",
+        start.study,
+        "--serve",
+        "--no-open",
+        "--port",
+        String(RUNNER_OBSERVER_PORT),
+        "--all-interfaces",
+        "--result-file",
+        `$HOME/${RUNNER_STATE}/result.json`,
+        "--run-id",
+        start.runId,
+        "--owner-key",
+        start.ownerKey,
+    ];
+    const line = [
+        `cd "$HOME/${RUNNER_PROJECT}"`,
+        `export PATH="$HOME/${RUNNER_STATE}/node/bin:$PATH"`,
+        `exec ${args.map((arg) => (arg.startsWith("$HOME") ? `"${arg}"` : shellQuote(arg))).join(" ")} > "$HOME/${RUNNER_STATE}/watch.out" 2> "$HOME/${RUNNER_STATE}/watch.err"`,
+    ].join("; ");
+    const env = { ...start.env, DO_NOT_TRACK: "1", HUMANISH_TELEMETRY_DISABLED: "1" };
+    const result = await runner.shell.start(`bash -c ${shellQuote(line)}`, {
+        env,
+        timeoutMs: 60_000,
+    });
+    if (result.exitCode !== 0)
+        throw new RunnerCommandError("Starting the run", result);
+}
+export async function readRemoteRun(runner, runId) {
+    const read = async (file) => {
+        const result = await runner.shell.run(`cat -- ${shellQuote(file)} 2>/dev/null`, {
+            timeoutMs: 30_000,
+        });
+        return result.exitCode === 0 ? result.stdout : undefined;
+    };
+    const status = parseJson(await read(`${RUNNER_PROJECT}/.humanish/runs/${runId}/status.json`));
+    const result = parseJson(await read(`${RUNNER_STATE}/result.json`));
+    const err = await runner.shell.run(`tail -c 2000 ${RUNNER_STATE}/watch.err 2>/dev/null`, {
+        timeoutMs: 30_000,
+    });
+    const alive = await runner.shell.run("pgrep -f '[h]umanish watch' >/dev/null", {
+        timeoutMs: 30_000,
+    });
+    return {
+        ...(typeof status?.state === "string" ? { state: status.state } : {}),
+        ...(typeof result?.exitCode === "number"
+            ? { result: { exitCode: result.exitCode, result: result.result } }
+            : {}),
+        alive: alive.exitCode === 0,
+        errTail: tailOf(err.stdout),
+    };
+}
+function parseJson(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        const value = JSON.parse(text);
+        return value !== null && typeof value === "object"
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The regular files of the runner's run directory and their digests. Refuses a directory that holds
+ * a link, which a run never writes.
+ */
+export async function listRemoteRun(runner, runId) {
+    const dir = `${RUNNER_PROJECT}/.humanish/runs/${runId}`;
+    const links = await runOrFail(runner, "Listing the run", `cd ${shellQuote(dir)} && find . ! -type f ! -type d -print -quit`, 60_000);
+    if (links.stdout.trim() !== "")
+        throw new Error(`The runner's run directory holds something other than files and folders (${tailOf(links.stdout)}), so it is not copied.`);
+    const listed = await runOrFail(runner, "Listing the run", `cd ${shellQuote(dir)} && find . -type f -print0 | xargs -0 -r sha256sum`, 300_000);
+    return parseDigests(listed.stdout);
+}
+/** sha256sum lines, `<hex>  ./<path>`, as RemoteFiles with paths relative to the directory. */
+export function parseDigests(output) {
+    const files = [];
+    for (const line of output.split("\n")) {
+        const match = /^([0-9a-f]{64}) [ *]\.\/(.+)$/.exec(line);
+        if (match === null)
+            continue;
+        files.push({ sha256: match[1], path: match[2] });
+    }
+    return files;
+}
+/** The bytes of one file of the runner's run directory, checked against its listed digest. */
+export async function readRemoteFile(runner, runId, file) {
+    const read = runner.sandbox.files.read;
+    if (read === undefined)
+        throw new Error("This sandbox cannot read files back.");
+    const stream = await read.call(runner.sandbox.files, `${RUNNER_PROJECT}/.humanish/runs/${runId}/${file.path}`, { format: "stream", requestTimeoutMs: 300_000 });
+    const parts = [];
+    for await (const chunk of stream)
+        parts.push(chunk);
+    const bytes = Buffer.concat(parts);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== file.sha256)
+        throw new Error(`${file.path} changed or arrived damaged while it was copied from the runner.`);
+    return bytes;
+}
+/**
+ * Ask the runner's run to stop as a signal would, so it reclaims its participants and ends. The
+ * `[h]` keeps the pattern from matching the shell that runs it.
+ */
+export async function stopRemoteRun(runner) {
+    await runner.shell.run("pkill -TERM -f '[h]umanish watch' || true", { timeoutMs: 30_000 });
+}
+function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}

package/dist/routes/computer-use/e2b-desktop/start.js

@@ -203,7 +203,7 @@ export async function startParticipantStream(ctx, state, desktop) {
         // A browser participant streams its browser window when one was found. A CLI participant has
         // no window id and streams the whole desktop: a person studying a terminal app opens other windows, and
         // a stream bound to the first one would quietly stop being evidence.
-        await startDesktopStream(desktop, state.browserWindowId);
+        await startDesktopStream(desktop, state.browserWindowId, deps.requestTimeoutMs);
         const candidateStreamUrl = desktop.stream.getUrl({
             authKey: desktop.stream.getAuthKey(),
             autoConnect: true,

package/dist/routes/computer-use/types.d.ts

@@ -59,6 +59,8 @@ export interface ComputerUseRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
+    /** The run key its sandboxes carry; see InternalRunStudyOptions.ownerKey. */
+    ownerKey?: string;
     /** CLI `--count` override for the homogeneous fan-out participant count (ignored when a `participants`
      *  list is declared; a roster's length is authoritative). */
     countOverride?: number;

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

@@ -15,6 +15,8 @@ export interface ScriptedRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
+    /** The run key its sandboxes carry; see InternalRunStudyOptions.ownerKey. */
+    ownerKey?: string;
     /** Keys and subject env for the run. Defaults to process.env. Values are scrubbed; names persist. */
     env?: Readonly<Record<string, string | undefined>>;
     /** Runs after a clone subject's sandbox exists and before provisioning. */

package/dist/routes/shared-world/types.d.ts

@@ -31,6 +31,8 @@ export interface SharedWorldRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
+    /** The run key its sandboxes carry; see InternalRunStudyOptions.ownerKey. */
+    ownerKey?: string;
     onObserverReady?: (observer: ObserverResult & {
         ok: true;
     }) => Promise<void> | void;

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

@@ -106,6 +106,8 @@ export interface TerminalRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
+    /** The run key its sandboxes carry; see InternalRunStudyOptions.ownerKey. */
+    ownerKey?: string;
     /**
      * The operator environment the route reads the runtime key from (and from which it asserts no
      * banned credential is requested). Defaults to process.env. The runtime key goes only

package/dist/run/costs.d.ts

@@ -1,5 +1,6 @@
 import { type PreparedRunArtifactPaths } from "./paths.js";
 import type { RunIndexEntry } from "./run-index.js";
+import type { AnalysisProviderName } from "../analysis/types.js";
 /** Additive accounting for retained attempts. Null means no estimate, never an invented zero. */
 export interface CostTotals {
     estimatedTotalUsd: number | null;
@@ -39,7 +40,7 @@ export interface AnalysisAccounting {
     /** The known estimates of the dispatched attempts; 0 when every attempt sent nothing. */
     estimatedUsd: number | null;
     /** Who billed the dispatched attempts. */
-    providers: Array<"openai" | "codex">;
+    providers: AnalysisProviderName[];
     /** History that could not be read whole; ANALYSIS_HISTORY_NOT_RECORDED when there is none. */
     warnings: string[];
 }

package/dist/run/pricing.d.ts

@@ -25,6 +25,11 @@ export interface ModelRate {
         inputMultiplier: number;
         outputMultiplier: number;
     };
+    /** The last day (`YYYY-MM-DD`, UTC) these rates apply, when the sheet already publishes the
+     *  rates that follow. A request is priced at the rates of the day it is sent. */
+    until?: string;
+    /** The rates the sheet publishes from the day after `until`. */
+    after?: Pick<ModelRate, "inputUsdPerToken" | "outputUsdPerToken" | "cachedInputUsdPerToken">;
     /** The `YYYY-MM-DD` date the entry was last checked against `source`. */
     asOf: string;
     /** Public pricing page the number came from (a comment/URL, never a secret). */
@@ -32,6 +37,8 @@ export interface ModelRate {
     /** true = a stand-in that was not copied from a live sheet; the estimate carries this flag so a
      *  placeholder rate is never mistaken for a confirmed one. */
     placeholder?: boolean;
+    /** true = priced for study analysis only: no participant route runs this model. */
+    analysisOnly?: true;
 }
 export interface DesktopRate {
     usdPerMinute: number;
@@ -120,6 +127,8 @@ export declare const MODAL_SANDBOX_RESOURCE_RATE: DesktopResourceRate;
  * since an npm install cannot edit this file.
  */
 export declare function unpricedCapMessage(model: string): string;
+/** A participant model's rate; undefined for a model without one or priced for analysis only. */
+export declare function participantRate(model: string): ModelRate | undefined;
 export declare const DESKTOP_RATE: DesktopRate;
 export declare function isDesktopResources(value: unknown): value is DesktopResources;
 /** Price one observed allocation. Missing quantities/rates stay unknown, never a stock guess. */
@@ -141,7 +150,10 @@ export declare function estimateActorCostForExecution(usage: ActorTokenUsage | u
  * whole turn, so the per-turn records are dropped and the totals price on the base tier.
  */
 export declare function estimateAggregatedTurnCost(tokenUsage: ActorTokenUsage | undefined, modelId: string | undefined): ActorEstimatedCost;
-export declare function estimateActorCost(tokenUsage: ActorTokenUsage | undefined, modelId: string | undefined, rates?: Record<string, ModelRate>): ActorEstimatedCost;
+/** A model's rates on the day of `at` (UTC), or undefined when the table has none. Lookup is
+ *  case-insensitive on a trimmed id. */
+export declare function modelRate(modelId: string, at?: Date, rates?: Record<string, ModelRate>): ModelRate | undefined;
+export declare function estimateActorCost(tokenUsage: ActorTokenUsage | undefined, modelId: string | undefined, rates?: Record<string, ModelRate>, at?: Date): ActorEstimatedCost;
 /**
  * Estimate the E2B desktop-minute cost from a host-side create->teardown span (minutes). The rate
  * is injectable. Returns a declared-absent estimate (null + "no_duration") when no duration was

package/dist/run/pricing.js

@@ -21,7 +21,8 @@ const LONG_CONTEXT_TIER_272K = {
 };
 const GPT56_SOURCE = "developers.openai.com/api/docs/pricing (gpt-5.6 family, standard tier)";
 const GPT6_ASTRA_SOURCE = "developers.openai.com/api/docs/pricing (gpt-6-astra, standard tier)";
-// One entry for a model on the gpt-5.6 pricing mechanics (the 5.6 family and gpt-6-astra): rates
+const GPT6_SOL_LUNA_SOURCE = "developers.openai.com/api/docs/pricing (gpt-6.1-sol and gpt-6-luna, standard tier)";
+// One entry for a model on the gpt-5.6 pricing mechanics (the 5.6 and 6 families): rates
 // in USD-per-1M for legibility, converted once. Cache writes bill at 1.25x the uncached input rate
 // (`cache_write_tokens`, prompt-caching guide), and the 272K long-context tier applies. The
 // built-in `computer` tool has no per-call fee on the live sheet.
@@ -36,10 +37,28 @@ function rateWithLongContextTier(inPer1M, cachedPer1M, writePer1M, outPer1M, asO
         source,
     };
 }
+/** Gemini prices per 1M tokens: input, cached input and output (thinking included). */
+function geminiPrices(inPer1M, cachedPer1M, outPer1M) {
+    return {
+        inputUsdPerToken: inPer1M * 1e-6,
+        cachedInputUsdPerToken: cachedPer1M * 1e-6,
+        outputUsdPerToken: outPer1M * 1e-6,
+    };
+}
+function geminiRate(inPer1M, cachedPer1M, outPer1M, change = {}) {
+    return {
+        ...geminiPrices(inPer1M, cachedPer1M, outPer1M),
+        ...change,
+        analysisOnly: true,
+        asOf: "2026-10-21",
+        source: "ai.google.dev/gemini-api/docs/pricing (paid tier, standard)",
+    };
+}
 // gpt-5.6-sol promotional rates (live sheet 2026-09-03: $4 / $0.40 cached / $5 write / $20 out,
 // "available at least through November 21, 2026"). Re-verify against the sheet after Nov 21.
 const GPT56_SOL_PROMO_AS_OF = "2026-09-03";
 const GPT6_ASTRA_AS_OF = "2026-09-03";
+const GPT6_SOL_LUNA_AS_OF = "2026-10-21";
 // Per-model rates, keyed on the model id that lands in trace.ids.model (lookup is
 // case-insensitive on a trimmed id). An id missing here is declared absent, never guessed.
 export const MODEL_RATES = {
@@ -82,6 +101,17 @@ export const MODEL_RATES = {
     // output ($20 / $2 / $25 / $75 long-context columns). These rates cover explicit study
     // model choices and the study-analysis default; the computer-use default is separate.
     "gpt-6-astra": rateWithLongContextTier(10, 1, 12.5, 50, GPT6_ASTRA_AS_OF, GPT6_ASTRA_SOURCE),
+    // gpt-6.1-sol and gpt-6-luna: the same write and long-context mechanics on the sheet and each
+    // model page. 6.1 Sol bills cache reads at 5% of input ($0.10), where the others bill 10%.
+    "gpt-6.1-sol": rateWithLongContextTier(2, 0.1, 2.5, 10, GPT6_SOL_LUNA_AS_OF, GPT6_SOL_LUNA_SOURCE),
+    "gpt-6-luna": rateWithLongContextTier(0.1, 0.01, 0.125, 0.5, GPT6_SOL_LUNA_AS_OF, GPT6_SOL_LUNA_SOURCE),
+    // Gemini analysis models, paid standard tier. Thinking tokens bill as output. No long-context
+    // tier is published for them. Cached input is the implicit context-cache rate. On the free tier
+    // these requests bill nothing, so the estimate is the paid-tier cost.
+    "gemini-3.8-flash": geminiRate(0.75, 0.075, 3.75, {
+        until: "2026-12-31",
+        after: geminiPrices(1.5, 0.15, 7.5),
+    }),
 };
 // Current public incremental running-compute rates. Subscription fees/credits, negotiated
 // enterprise prices, and unobserved allocation/startup time are outside this estimate.
@@ -114,7 +144,13 @@ export const MODAL_SANDBOX_RESOURCE_RATE = {
  * since an npm install cannot edit this file.
  */
 export function unpricedCapMessage(model) {
-    return `caps sets a spend cap (maxUsd or maxTotalUsd), but humanish has no rate for model "${model}", so it cannot enforce the cap and refuses to start. Priced models: ${Object.keys(MODEL_RATES).sort().join(", ")}. Use one of them, or remove maxUsd and maxTotalUsd to run without a cap.`;
+    const priced = Object.keys(MODEL_RATES).filter((id) => participantRate(id) !== undefined);
+    return `caps sets a spend cap (maxUsd or maxTotalUsd), but humanish has no rate for model "${model}", so it cannot enforce the cap and refuses to start. Priced models: ${priced.sort().join(", ")}. Use one of them, or remove maxUsd and maxTotalUsd to run without a cap.`;
+}
+/** A participant model's rate; undefined for a model without one or priced for analysis only. */
+export function participantRate(model) {
+    const rate = MODEL_RATES[model.trim().toLowerCase()];
+    return rate?.analysisOnly ? undefined : rate;
 }
 export const DESKTOP_RATE = {
     usdPerMinute: 0.00888,
@@ -204,7 +240,17 @@ export function estimateAggregatedTurnCost(tokenUsage, modelId) {
         ? estimate
         : { ...estimate, basis: "aggregated_turns_base_rate" };
 }
-export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
+/** A model's rates on the day of `at` (UTC), or undefined when the table has none. Lookup is
+ *  case-insensitive on a trimmed id. */
+export function modelRate(modelId, at = new Date(), rates = MODEL_RATES) {
+    const rate = rates[modelId.trim().toLowerCase()];
+    if (rate?.until === undefined || at.toISOString().slice(0, 10) <= rate.until)
+        return rate;
+    const { until: _until, after, cachedInputUsdPerToken: _cached, ...rest } = rate;
+    // Past its last day with no published successor, the entry no longer prices anything.
+    return after === undefined ? undefined : { ...rest, ...after };
+}
+export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES, at = new Date()) {
     if (!tokenUsage || (tokenUsage.input === undefined && tokenUsage.output === undefined)) {
         return {
             schema: ACTOR_ESTIMATED_COST_SCHEMA,
@@ -213,7 +259,7 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
             ratesAsOf: null,
         };
     }
-    const rate = modelId ? rates[modelId.trim().toLowerCase()] : undefined;
+    const rate = modelId ? modelRate(modelId, at, rates) : undefined;
     if (!rate) {
         return {
             schema: ACTOR_ESTIMATED_COST_SCHEMA,

package/dist/run/results.d.ts

@@ -32,7 +32,7 @@ export interface RunResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_RUN_OPTION_CONFLICT" | "HUMANISH_OBSERVE_OPTION_CONFLICT" | "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_RUN_OPTION_CONFLICT" | "HUMANISH_OBSERVE_OPTION_CONFLICT" | "HUMANISH_REMOTE_REFUSED" | "HUMANISH_REMOTE_FAILED" | "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
         message: string;
     };
 }

package/dist/run/run-cost.d.ts

@@ -1,6 +1,7 @@
 import type { RunCostSummary } from "./bundle.js";
 import type { AnalysisAccounting } from "./costs.js";
 import type { RunIndexEntry } from "./run-index.js";
+import type { AnalysisProviderName } from "../analysis/types.js";
 /** The fields of run.json's `cost` that the run cost reads. Completeness is unknown when absent. */
 export type RunCostSubtotal = Pick<RunCostSummary, "estimatedTotalUsd"> & Partial<Pick<RunCostSummary, "fullyEstimated" | "ratesAsOf" | "placeholder">>;
 /** A run's analysis spend, every attempt counted once, as `readAnalysisAccounting` reads it. */
@@ -12,7 +13,7 @@ export interface RunAnalysisCost {
     /** True when every request has a complete price and the history was read whole. */
     complete: boolean;
     /** Who billed the requests that recorded usage. */
-    providers: Array<"openai" | "codex">;
+    providers: AnalysisProviderName[];
 }
 /** Complete, a lower bound, or unknown (`null`) when only the subtotal's dollars are at hand. */
 type Completeness = boolean | null;

package/dist/run/run-cost.js

@@ -77,8 +77,13 @@ function estimateText(usd, complete) {
 function analysesNoun(requests) {
     return requests === 1 ? "analysis" : `${requests} analyses`;
 }
+const BILLED_BY = {
+    openai: "OpenAI API key",
+    gemini: "Gemini API key",
+    codex: "Codex account",
+};
 function billedBy(providers) {
-    const names = providers.map((provider) => provider === "openai" ? "OpenAI API key" : "Codex account");
+    const names = providers.map((provider) => BILLED_BY[provider]);
     return names.length === 0 ? "" : ` (${names.join(" and ")})`;
 }
 /**

package/dist/run/run.d.ts

@@ -11,6 +11,12 @@ interface StartRunOptions {
     cwd: string;
     /** Caller-supplied id (`--run-id`, library `runId`); `mintRunId` runs when it is absent. */
     runId?: string | undefined;
+    /**
+     * The run key every sandbox of this run carries (16 lowercase hex), in place of the one derived
+     * from the run directory. A remote run's launcher chooses it, so its own directory and the
+     * remote one name the same sandboxes.
+     */
+    ownerKey?: string | undefined;
     mintRunId: () => string;
     mode: "dry-run" | "live";
     study?: RunStudyProvenance | undefined;
@@ -44,6 +50,8 @@ interface StartRunPlan {
 interface StartRunInput {
     /** Caller-supplied id (`--run-id`, library `runId`); one is minted from the prefix when absent. */
     readonly runId?: string | undefined;
+    /** The run key its sandboxes carry; see StartRunOptions.ownerKey. */
+    readonly ownerKey?: string | undefined;
     /** Open the Observer page once it renders. */
     readonly open?: boolean | undefined;
     /**
@@ -215,4 +223,9 @@ export declare function runScope<T>(fn: (scope: RunScope) => Promise<T>, hooks?:
     result: T;
     finished: FinishedRun | undefined;
 }>;
+/**
+ * Make `runId` the project's latest run. A published run does it as it finishes, and a remote run's
+ * launcher once the run is copied back; this is the only writer of the pointer.
+ */
+export declare function pointLatestRunAt(paths: PreparedRunArtifactPaths, runId: string, now?: () => number): Promise<void>;
 export {};