@hue-run/sdk 0.3.0 → 0.3.1

package/CLI.md

@@ -0,0 +1,52 @@
+# Hue setup-session CLI contract
+
+Unreleased TypeScript `0.3.1` includes the merged local setup-session CLI core:
+
+```sh
+hue setup
+hue setup --agent
+hue resume
+hue status
+hue claim # reports account attachment unavailable in this local core
+```
+
+These commands belong only to an installer setup session. They do not create or launch a Hue Run,
+Scenario, evaluation, or worker. `claim` only means attaching the anonymous setup project to an
+account; there is no generic `connect` command or local-agent connection in this CLI.
+
+`setup` only inspects bounded manifest and lockfile metadata. It does not execute repository code,
+change project files, open a browser, ask a question, create a trial, or contact Hue. `claim` also
+makes no network request in this build and reports that account attachment is unavailable. `resume`
+deterministically continues the same setup-session checkpoint; `status` reads it without changing
+it.
+
+Checkpoints are secret-free JSON files outside the project, under the operating system's user state
+directory. On POSIX, directories use mode `0700` and files use mode `0600`; Windows uses its
+per-user local state directory without interpreting POSIX mode bits. Writes are atomic, and a
+configured state location inside the project is rejected. Checkpoints contain project categories
+and hashes, never environment values, credentials, source contents, or claim URLs.
+
+`--agent` is explicitly noninteractive JSONL. It never uses ANSI, stdin, or a browser, and each
+invocation emits exactly one terminal `run.completed` or `run.failed` installer event. Those names
+describe the setup-session lifecycle, not a Hue Run. Human output is an append-only inline
+transcript. Plain and JSONL output contain no ANSI; `NO_COLOR`, `TERM=dumb`, CI, and non-TTY output
+select plain mode automatically.
+
+Every JSONL record carries `contractVersion: 1`. The TypeScript union is exported from
+`@hue-run/sdk/setup`; the JSON Schema is exported as
+`@hue-run/sdk/setup-events.schema.json`. Consumers must ignore neither unknown versions nor terminal
+failures.
+
+The future Fern implementation plugs into `SetupBackendAdapter`. Its three installer operations
+create an anonymous setup trial hard-pinned to `trial_metadata_v1`, verify instrumentation-only
+receipt evidence, and read account-claim state. Inputs carry deterministic idempotency keys and an
+optional abort signal. Adapter results must use bounded, non-secret IDs; claim URLs may be sensitive
+and therefore must never be checkpointed. Receipt verification does not prove that task or
+environment content was captured and must never authorize Scenario publication. The adapter must
+not create a Scenario, evaluation, worker, or Hue Run. No live implementation ships in this slice.
+
+The V1 handoff is deliberately staged: setup verifies the anonymous instrumentation trace; `hue claim`
+preserves the project and trace history; then the user performs an explicit content-approved capture
+or rerun, with a prepared tester as the first golden path. Only that content-approved trace passes to
+the separate review/publication flow for a Scenario. The actual URL and that handoff contract remain
+deferred. Setup itself does not capture content, create, publish, or run a Scenario.

package/ENVIRONMENTS.md

@@ -1,10 +1,9 @@
 # Simulated environments
 
-This guide documents the TypeScript `0.3.0` release candidate. Until registry acceptance, use
-the exact reviewed archive rather than requesting `0.3.0` from npm:
+The provider-aware environment APIs shipped in TypeScript `0.3.0` and are publicly available:
 
 ```bash
-npm install /path/to/reviewed/hue-run-sdk-0.3.0.tgz zod
+npm install @hue-run/sdk zod
 ```
 
 Your agent runs in your process while a disposable simulated world runs in Hue. The world is
@@ -192,7 +191,7 @@ arbitrary-step diffs are outside this interface.
 
 ## Candidate context migration
 
-This candidate-context restriction is part of the `@hue-run/sdk@0.3.0` release candidate.
+This candidate-context restriction shipped in `@hue-run/sdk@0.3.0`.
 
 `runSimulation` now supplies `context.item` as `{ id, externalKey }`. Read candidate inputs
 from the callback's first argument. Expected outcomes, case metadata and environment-version

package/EVALUATIONS.md

@@ -120,7 +120,11 @@ All declared metrics must appear exactly once and satisfy pinned types, bounds a
 
 ### Hosted and manual scorer pins
 
-The local runner leaves `llm_judge` and `manual` pins pending and reports their IDs in `deferredScorerVersionIds`. It does not upload a synthetic skipped result that would occupy their immutable result slot. Manual results require a human session. Hosted dispatch is an explicit separate API operation: inspect `getJudgeBudget()`, then call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
+In TypeScript `0.3.1` (unreleased), the local runner executes only the three known built-in entries and bound `local_code` scorers. It leaves every other pin pending and reports its ID in `deferredScorerVersionIds`, including kinds and built-in entries introduced by a newer server. It never uploads a placeholder result that would occupy the immutable result slot, including placeholders already saved in an older SDK's checkpoint. Direct `scoreLocally()` calls reject pins that require another executor.
+
+`world_outcome` pins run inside Hue and need no local callback or executable source digest. A supporting server owns their execution from saved world evidence. Legacy `local_code` pins still require the exact registered callback; changing the worker cannot convert those immutable pins into hosted ones.
+
+Manual results require a human session. Hosted model-judge dispatch is an explicit separate API operation: inspect `getJudgeBudget()`, then call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
 
 When present, the budget's `authentication` reports credential resolution only. An
 `available` status or `configured: true` does not prove that a provider accepted the
@@ -156,12 +160,10 @@ The runner stops scheduling more cases after an operational failure and waits fo
 
 ## Outbound local agent worker
 
-`runLocalAgent` is included in the `@hue-run/sdk@0.3.0` release candidate. Queue registration,
-claims, scoped MCP capabilities and sealed evidence require a supporting Hue server and project
-access; the package version alone does not establish hosted availability. Until registry
-acceptance, install the exact reviewed `hue-run-sdk-0.3.0.tgz` archive with the optional `zod`
-peer. `node packages/sdk-typescript/scripts/verify-package.mjs` creates and verifies that archive;
-do not request `0.3.0` from npm yet.
+`runLocalAgent` shipped in `@hue-run/sdk@0.3.0` and is publicly available. Install
+`npm install @hue-run/sdk zod`. Queue registration, claims, scoped MCP capabilities and sealed
+evidence require a supporting Hue server and project access; the package version alone does not
+establish hosted provider availability.
 
 `runLocalAgent` registers one fixed application callback and polls for queued runs. Hue selects
 the registered key/revision; it does not send executable code or shell commands. Keep the
@@ -183,6 +185,7 @@ try {
     hue,
     agent: { key: "support-agent", name: "Support agent", revision: "1" },
     checkpointDirectory: ".hue-checkpoints/support-agent",
+    scorers: [], // Hue-executed scorers require no local callback registration.
     target: (inputs, tools, context) => runMyAgent({ inputs, tools, config: context.config }),
   });
 } finally {

package/README.md

@@ -397,10 +397,9 @@ The optional `@hue-run/sdk/evals` entry point supports dataset/scorer registrati
 
 ### App-launched local workers
 
-The TypeScript `0.3.0` release candidate adds `runLocalAgent()` for a fixed local callback that
-claims app-launched simulation work while keeping the agent, provider orchestration and debugger
-in the developer's process. Until registry acceptance, test it only from the exact reviewed
-`hue-run-sdk-0.3.0.tgz` archive rather than requesting `0.3.0` from npm. It shares
+`runLocalAgent()` shipped in TypeScript `0.3.0` and is available from npm. It connects a fixed local
+callback to app-launched simulation work while keeping the agent and provider orchestration in
+the developer's process. It shares
 `runSimulation()`'s provider-aware world lifecycle, keeps scoped credentials in callback memory,
 skips target/scorer execution for incomplete environments, and never reacquires or replays after
 an uncertain preparation. See the
@@ -409,6 +408,13 @@ an uncertain preparation. See the
 an issued facade endpoint or the official Gmail service, and do not claim universal provider
 parity.
 
+Unreleased TypeScript `0.3.1` defers all scorers the SDK does not execute locally. Only built-ins
+and bound `local_code` callbacks run here; other pins remain pending for their authorized executor.
+See [scorer execution](EVALUATIONS.md#hosted-and-manual-scorer-pins).
+
+The [setup CLI](CLI.md) is a resumable local inspection core. Existing customers connect their
+agents with `runLocalAgent()`; setup does not register workers or launch Scenarios.
+
 ## Managed targets
 
 Start a frozen dataset run in Hue while your agent stays in your application. Expose a

package/dist/evals/runner.d.ts

@@ -90,7 +90,7 @@ export interface RunnerReport {
     subjectIds: string[];
     /** Result IDs uploaded by this call. */
     resultIds: string[];
-    /** `llm_judge` and `manual` pins left pending for hosted or human scoring. */
+    /** Pins without a local implementation, left pending for their authorized executor. */
     deferredScorerVersionIds: string[];
 }
 /**

package/dist/evals/runner.js

@@ -4,7 +4,7 @@ import { HueExportError } from "../transport.js";
 import { loadEnvironmentEvidence } from "./environment-evidence.js";
 import { CheckpointStore } from "./checkpoint.js";
 import { json, uuid } from "./json.js";
-import { persistedScore, scoreLocally, validateScorerBindings } from "./scorers.js";
+import { persistedScore, scoreLocally, validateScorerBindings, isLocallyExecutable, } from "./scorers.js";
 /**
  * Thrown when a case has a started attempt without a saved outcome. The runner never reruns the
  * target; inspect the execution and authorize a new attempt explicitly through `startExecution`.
@@ -105,7 +105,8 @@ async function pool(items, concurrency, execute) {
 async function scoresFor(versions, context, options, executionId) {
     const scores = [];
     let environmentUnavailable = false;
-    if (options.environmentEvidence === "required") {
+    if (options.environmentEvidence === "required" &&
+        versions.some((version) => isLocallyExecutable(version.definition))) {
         try {
             context = {
                 ...context,
@@ -117,8 +118,8 @@ async function scoresFor(versions, context, options, executionId) {
         }
     }
     for (const version of versions) {
-        // Hosted/manual pins remain pending for their authorized executor.
-        if (version.definition.kind === "llm_judge" || version.definition.kind === "manual")
+        // Every pin without a local implementation belongs to another executor.
+        if (!isLocallyExecutable(version.definition))
             continue;
         const score = persistedScore(environmentUnavailable && version.definition.kind === "local_code"
             ? { state: "error", error: { type: "EnvironmentEvidenceUnavailable" } }
@@ -136,8 +137,16 @@ async function scoresFor(versions, context, options, executionId) {
     }
     return scores;
 }
-async function uploadScores(options, runId, scores, save) {
-    for (const score of scores) {
+async function uploadScores(options, runId, scores, save, versions) {
+    // A previous SDK may have checkpointed a placeholder for an unknown kind.
+    // Keep its evidence intact, but never upload or report it as a local result.
+    const local = scores.filter((score) => {
+        const pin = versions.find((version) => version.id === score.payload.scorerVersionId);
+        if (!pin)
+            throw new Error("Saved result references an unpinned scorer version");
+        return isLocallyExecutable(pin.definition);
+    });
+    for (const score of local) {
         if (score.receipt)
             continue;
         if (!score.payload.evaluationItemId)
@@ -149,6 +158,7 @@ async function uploadScores(options, runId, scores, save) {
         score.receipt = result.ids;
         await save();
     }
+    return local.flatMap((score) => score.receipt ?? []);
 }
 /**
  * Runs every case of a frozen experiment through `target` on this machine, completes each
@@ -204,7 +214,7 @@ export async function runExperiment(options) {
         subjectIds: [],
         resultIds: [],
         deferredScorerVersionIds: versions
-            .filter((version) => ["llm_judge", "manual"].includes(version.definition.kind))
+            .filter((version) => !isLocallyExecutable(version.definition))
             .map((version) => version.id),
     };
     try {
@@ -352,9 +362,9 @@ export async function runExperiment(options) {
                     score.payload.evaluationItemId = prepared.completion.evaluationItemId;
                 await save();
             }
-            await uploadScores(options, experiment.evaluation.id, prepared.scores, save);
+            const results = await uploadScores(options, experiment.evaluation.id, prepared.scores, save, versions);
             report.subjectIds.push(prepared.completion.subjectId);
-            report.resultIds.push(...prepared.scores.flatMap((score) => score.receipt ?? []));
+            report.resultIds.push(...results);
         });
         let finish = await store.read("finish");
         if (!finish) {
@@ -395,7 +405,7 @@ export async function rescore(options) {
         subjectIds: [],
         resultIds: [],
         deferredScorerVersionIds: run.scorerVersions
-            .filter((version) => ["llm_judge", "manual"].includes(version.definition.kind))
+            .filter((version) => !isLocallyExecutable(version.definition))
             .map((version) => version.id),
     };
     try {
@@ -419,9 +429,9 @@ export async function rescore(options) {
                 await store.write(file, saved);
             }
             const current = saved;
-            await uploadScores(options, run.id, current.scores, () => store.write(file, current));
+            const results = await uploadScores(options, run.id, current.scores, () => store.write(file, current), run.scorerVersions);
             report.subjectIds.push(item.subjectId);
-            report.resultIds.push(...current.scores.flatMap((score) => score.receipt ?? []));
+            report.resultIds.push(...results);
         });
         return report;
     }

package/dist/evals/scorer-publication.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { json } from "./json.js";
+import { json, digest } from "./json.js";
 const metricName = z
     .string()
     .min(1)
@@ -21,6 +21,15 @@ const metric = z.discriminatedUnion("type", [
     }),
 ]);
 const metrics = z.array(metric).min(1);
+const worldOutcomeMetrics = [
+    "completed_run",
+    "saved_draft",
+    "correct_destination",
+    "content",
+    "unrelated_preserved",
+    "process_constraints",
+    "task_success",
+].map((name) => ({ name, type: "boolean" }));
 const jsonValue = z.custom((value) => {
     try {
         json(value);
@@ -73,6 +82,13 @@ const sdkScorerPublication = z.union([
         sourceDigest: z.string(),
         metrics,
     }),
+    z.strictObject({
+        kind: z.literal("world_outcome"),
+        entry: z.literal("hue.conversion_outcome.v1"),
+        metrics: metrics
+            .default(worldOutcomeMetrics)
+            .refine((value) => digest(value) === digest(worldOutcomeMetrics), "World outcome metrics are fixed by the pinned entry"),
+    }),
     z.strictObject({ kind: z.literal("manual"), metrics }),
     z.strictObject({ kind: z.literal("llm_judge"), config: judgeConfig, metrics }),
 ]);

package/dist/evals/scorers.d.ts

@@ -17,12 +17,18 @@ export declare function defineLocalScorer(options: {
 }): LocalScorer;
 /** Check local callbacks before target invocation; never execute downloaded source code. */
 export declare function validateScorerBindings(versions: ScorerVersion[], scorers?: LocalScorer[]): void;
+/** Only implementations this SDK owns may produce local results. Unknown pins are deferred. */
+export declare function isLocallyExecutable(definition: {
+    kind: string;
+    entry?: string;
+}): definition is Extract<ScorerDefinition, {
+    kind: "builtin" | "local_code";
+}>;
 /**
- * Scores one subject with a pinned scorer version on this machine: built-ins run here, `local_code`
- * pins run the matching callback from `options.scorers`, `manual` pins are skipped. Failures are
- * returned as sanitized error scores.
+ * Scores one subject locally using a known built-in or a bound `local_code` callback.
+ * Scorer failures are returned as sanitized error scores.
  *
- * @throws TypeError for an `llm_judge` pin, which must be dispatched through `createJudgeJobs`.
+ * @throws TypeError for pins without a local implementation; their authorized executor owns scoring.
  */
 export declare function scoreLocally(version: ScorerVersion, context: ScoreContext, options?: {
     scorers?: LocalScorer[];

package/dist/evals/scorers.js

@@ -99,17 +99,22 @@ export function validateScorerBindings(versions, scorers = []) {
             throw new Error("A pinned local scorer has no matching language/source/entrypoint/metric binding");
     }
 }
+/** Only implementations this SDK owns may produce local results. Unknown pins are deferred. */
+export function isLocallyExecutable(definition) {
+    return (definition.kind === "local_code" ||
+        (definition.kind === "builtin" &&
+            ["hue.exact_match.v1", "hue.includes.v1", "hue.json_schema.v1"].includes(definition.entry ?? "")));
+}
 /**
- * Scores one subject with a pinned scorer version on this machine: built-ins run here, `local_code`
- * pins run the matching callback from `options.scorers`, `manual` pins are skipped. Failures are
- * returned as sanitized error scores.
+ * Scores one subject locally using a known built-in or a bound `local_code` callback.
+ * Scorer failures are returned as sanitized error scores.
  *
- * @throws TypeError for an `llm_judge` pin, which must be dispatched through `createJudgeJobs`.
+ * @throws TypeError for pins without a local implementation; their authorized executor owns scoring.
  */
 export async function scoreLocally(version, context, options = {}) {
     const definition = version.definition;
-    if (definition.kind === "llm_judge")
-        throw new TypeError("Hosted judge pins require dispatch through createJudgeJobs; do not submit a local result");
+    if (!isLocallyExecutable(definition))
+        throw new TypeError("This scorer must be deferred to its authorized executor; do not submit a local result");
     const timeout = options.schemaTimeoutMillis ?? 2000;
     if (!Number.isInteger(timeout) || timeout < 100 || timeout > 60_000)
         throw new RangeError("schemaTimeoutMillis must be 100–60000");
@@ -133,8 +138,6 @@ export async function scoreLocally(version, context, options = {}) {
         if (environment !== undefined)
             validateEnvironmentEvidence(environment);
         const owned = structuredClone(context);
-        if (definition.kind === "manual")
-            return skip("Manual scoring requires a human session");
         if (definition.kind === "local_code") {
             const binding = options.scorers?.find((local) => digest(local.definition) === digest(definition));
             if (!binding)

package/dist/evals/types.d.ts

@@ -119,7 +119,7 @@ export type MetricDefinition = {
     /** Allowed values. */
     categories: string[];
 };
-/** A pinned scorer definition: a Hue built-in, trusted local code, a manual rubric or a hosted judge. */
+/** A pinned scorer definition executed locally, by a person, or by Hue. */
 export type ScorerDefinition = {
     /** Hue built-in scorer. */
     kind: "builtin";
@@ -158,6 +158,13 @@ export type ScorerDefinition = {
     sourceDigest: string;
     /** Metrics the callback reports. */
     metrics: MetricDefinition[];
+} | {
+    /** Scored inside Hue using immutable world evidence; the local runner defers it. */
+    kind: "world_outcome";
+    /** Pinned Hue-executed outcome evaluator. */
+    entry: "hue.conversion_outcome.v1";
+    /** The seven fixed boolean metrics defined by the entry. */
+    metrics: MetricDefinition[];
 } | {
     /** Scored by a person in Hue; the local runner defers it. */
     kind: "manual";

package/dist/setup/checkpoint.d.ts

@@ -0,0 +1,14 @@
+import type { SetupCheckpointAdapter } from "./runner.js";
+import type { SetupMachineState } from "./machine.js";
+export declare function defaultSetupStateDirectory(env?: NodeJS.ProcessEnv): string;
+/** Stable installer-session identifier; it is not a Hue Run and reveals no path or file contents. */
+export declare function setupRunId(projectRoot: string): string;
+export declare class FileSetupCheckpointAdapter implements SetupCheckpointAdapter {
+    readonly directory: string;
+    private readonly runtimePlatform;
+    constructor(directory?: string, runtimePlatform?: NodeJS.Platform);
+    private get enforcesPosixPermissions();
+    private pathFor;
+    load(runId: string, projectRoot: string): Promise<SetupMachineState | undefined>;
+    save(state: SetupMachineState): Promise<void>;
+}

package/dist/setup/checkpoint.js

@@ -0,0 +1,186 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, realpath, rename } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+const MAX_CHECKPOINT_BYTES = 256 * 1024;
+const STEPS = ["detect-project", "configure-telemetry", "verify-receipt", "claim-project"];
+function isInside(parent, child) {
+    const path = relative(parent, child);
+    return path === "" || (!path.startsWith("..") && !isAbsolute(path));
+}
+export function defaultSetupStateDirectory(env = process.env) {
+    if (platform() === "darwin")
+        return join(homedir(), "Library", "Application Support", "Hue", "setup");
+    if (platform() === "win32")
+        return join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "Hue", "setup");
+    return join(env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"), "hue", "setup");
+}
+/** Stable installer-session identifier; it is not a Hue Run and reveals no path or file contents. */
+export function setupRunId(projectRoot) {
+    return `setup_${createHash("sha256")
+        .update(`hue-setup-v1\0${resolve(projectRoot)}`)
+        .digest("hex")
+        .slice(0, 24)}`;
+}
+function digest(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function hasExactKeys(value, keys) {
+    return Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+}
+function validDetection(value, projectRoot) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const item = value;
+    if (!hasExactKeys(item, [
+        "root",
+        "fingerprint",
+        "languages",
+        "packageManagers",
+        "frameworks",
+        "hue",
+        "openTelemetry",
+    ]))
+        return false;
+    const allowed = (items, values, maximum) => Array.isArray(items) &&
+        items.length <= maximum &&
+        new Set(items).size === items.length &&
+        items.every((entry) => typeof entry === "string" && values.includes(entry));
+    return (item.root === projectRoot &&
+        typeof item.fingerprint === "string" &&
+        /^[a-f0-9]{64}$/u.test(item.fingerprint) &&
+        allowed(item.languages, ["typescript", "python"], 2) &&
+        allowed(item.packageManagers, ["bun", "npm", "pnpm", "yarn", "uv", "poetry", "pip"], 7) &&
+        allowed(item.frameworks, ["nextjs", "nestjs", "express", "fastapi", "django", "flask", "vercel-ai-sdk"], 7) &&
+        ["absent", "typescript", "python", "multiple"].includes(item.hue) &&
+        ["absent", "typescript", "python", "multiple"].includes(item.openTelemetry));
+}
+function validState(value, runId, projectRoot) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const state = value;
+    if (state.format !== 1 || state.runId !== runId || state.projectRoot !== projectRoot)
+        return false;
+    if (state.phase === "created" || state.phase === "detecting")
+        return hasExactKeys(state, ["format", "phase", "runId", "projectRoot"]);
+    if (state.phase !== "local-ready" ||
+        !hasExactKeys(state, ["format", "phase", "runId", "projectRoot", "project", "plan"]) ||
+        !validDetection(state.project, projectRoot))
+        return false;
+    const plan = state.plan;
+    return (!!plan &&
+        typeof plan === "object" &&
+        !Array.isArray(plan) &&
+        hasExactKeys(plan, ["steps", "mutatesProject", "backendRequired"]) &&
+        JSON.stringify(plan.steps) === JSON.stringify(STEPS) &&
+        plan.mutatesProject === false &&
+        plan.backendRequired === true);
+}
+export class FileSetupCheckpointAdapter {
+    directory;
+    runtimePlatform;
+    constructor(directory = defaultSetupStateDirectory(), runtimePlatform = platform()) {
+        this.directory = directory;
+        this.runtimePlatform = runtimePlatform;
+    }
+    get enforcesPosixPermissions() {
+        return this.runtimePlatform !== "win32";
+    }
+    async pathFor(runId, projectRoot) {
+        if (!/^setup_[a-f0-9]{24}$/u.test(runId))
+            throw new Error("Invalid setup run identifier");
+        const root = resolve(this.directory);
+        const project = await realpath(projectRoot);
+        if (isInside(project, root))
+            throw new Error("Setup checkpoints must be outside the project repository");
+        let info;
+        try {
+            info = await lstat(root);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await mkdir(root, { recursive: true, mode: 0o700 });
+            info = await lstat(root);
+        }
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error("Setup checkpoint directory must be private (mode 0700, no symlink)");
+        if (this.enforcesPosixPermissions) {
+            await chmod(root, 0o700);
+            info = await lstat(root);
+            if ((info.mode & 0o077) !== 0)
+                throw new Error("Setup checkpoint directory must be private (mode 0700, no symlink)");
+        }
+        return join(root, `${runId}.json`);
+    }
+    async load(runId, projectRoot) {
+        const path = await this.pathFor(runId, projectRoot);
+        let handle;
+        try {
+            if (this.runtimePlatform === "win32") {
+                const entry = await lstat(path);
+                if (entry.isSymbolicLink())
+                    throw new Error("Unsafe setup checkpoint symlink");
+            }
+            const noFollow = this.runtimePlatform === "win32" ? 0 : constants.O_NOFOLLOW;
+            handle = await open(path, constants.O_RDONLY | noFollow);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() ||
+                info.size > MAX_CHECKPOINT_BYTES ||
+                (this.enforcesPosixPermissions && (info.mode & 0o077) !== 0))
+                throw new Error("Unsafe or oversized setup checkpoint");
+            const envelope = JSON.parse(await handle.readFile("utf8"));
+            if (!envelope ||
+                typeof envelope !== "object" ||
+                Array.isArray(envelope) ||
+                !hasExactKeys(envelope, ["state", "digest"]))
+                throw new Error("Invalid setup checkpoint envelope");
+            const { state, digest: expected } = envelope;
+            if (typeof expected !== "string" || expected !== digest(state))
+                throw new Error("Setup checkpoint integrity check failed");
+            if (!validState(state, runId, await realpath(projectRoot)))
+                throw new Error("Setup checkpoint identity or shape does not match this project");
+            return state;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async save(state) {
+        const path = await this.pathFor(state.runId, state.projectRoot);
+        const encoded = `${JSON.stringify({ state, digest: digest(state) })}\n`;
+        if (Buffer.byteLength(encoded) > MAX_CHECKPOINT_BYTES)
+            throw new Error("Setup checkpoint exceeds 256 KiB");
+        const temporary = join(dirname(path), `.${state.runId}.${randomUUID()}.tmp`);
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(encoded);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, path);
+        // Windows cannot open a directory as a file handle for fsync. The atomic rename and
+        // per-user state directory still provide resumability there; POSIX additionally fsyncs
+        // the containing directory so the rename survives a sudden interruption.
+        if (this.runtimePlatform !== "win32") {
+            await chmod(path, 0o600);
+            const directory = await open(dirname(path), "r");
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+    }
+}

package/dist/setup/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};