@gr8ful/spf 0.9.2 → 0.10.0

package/dist/core/data_types.d.ts

@@ -408,6 +408,173 @@ export declare const PromptEngineeringSchema: v.ObjectSchema<{
 export type PromptEngineering = v.InferOutput<typeof PromptEngineeringSchema>;
 export declare const ThinkingLevelSchema: v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>;
 export type ThinkingLevel = v.InferOutput<typeof ThinkingLevelSchema>;
+export declare const SandboxBackendSchema: v.PicklistSchema<["local", "opensandbox", "cloudflare"], undefined>;
+export type SandboxBackend = v.InferOutput<typeof SandboxBackendSchema>;
+/**
+ * "agent" (the DEFAULT) — one sandbox per (Run, agent), so a container's
+ * process env (fixed at create time) is built from exactly one agent's
+ * allowlist. "run" — one sandbox for the whole Run; admitted only when
+ * every required agent resolves to an IDENTICAL env spec, enforced by
+ * `agents.ts`'s `validateSandboxRunScope`.
+ */
+export declare const SandboxScopeSchema: v.PicklistSchema<["run", "agent"], undefined>;
+export type SandboxScope = v.InferOutput<typeof SandboxScopeSchema>;
+export declare const SandboxEgressSchema: v.ObjectSchema<{
+    readonly default: v.OptionalSchema<v.PicklistSchema<["deny", "allow"], undefined>, "deny">;
+    readonly allow: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+}, undefined>;
+export type SandboxEgressConfig = v.InferOutput<typeof SandboxEgressSchema>;
+/**
+ * `max_mirror_bytes` caps the handoff mirror (§5.3 point 2), EACH direction,
+ * per file. `max_patch_bytes`/`max_seed_bytes` cap the code-plane transport
+ * (§5.2). Exceeding any of them FAILS the phase; none of them ever truncate.
+ */
+export declare const SandboxTransportSchema: v.ObjectSchema<{
+    readonly max_patch_bytes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 8388608>;
+    readonly max_seed_bytes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 134217728>;
+    readonly max_mirror_bytes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 4194304>;
+    readonly mirror: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+}, undefined>;
+export type SandboxTransportConfig = v.InferOutput<typeof SandboxTransportSchema>;
+/**
+ * A plain string, not a picklist — a future broker (design §6.3, e.g.
+ * `openrouter`) registers itself in code (`sandbox.ts`'s
+ * `KNOWN_CREDENTIAL_BROKER_IDS`), so accepting new ids here must not also
+ * require a schema change in lockstep. "static" is the only broker
+ * REGISTERED in this build (PR A ships none at all — see sandbox.ts); an
+ * unknown name is a `validateSandboxConfig` failure (agents.ts), never a
+ * silent fallback to "static" — see design §6.1.
+ */
+export declare const SandboxCredentialsSchema: v.ObjectSchema<{
+    readonly broker: v.OptionalSchema<v.StringSchema<undefined>, "static">;
+}, undefined>;
+export type SandboxCredentialsConfig = v.InferOutput<typeof SandboxCredentialsSchema>;
+export declare const SandboxOpenSandboxSchema: v.ObjectSchema<{
+    readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "http://127.0.0.1:8090">;
+    readonly api_key_env: v.OptionalSchema<v.StringSchema<undefined>, "OPENSANDBOX_API_KEY">;
+    readonly use_server_proxy: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+    readonly metadata_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+}, undefined>;
+export type SandboxOpenSandboxConfig = v.InferOutput<typeof SandboxOpenSandboxSchema>;
+export declare const SandboxCloudflareSchema: v.ObjectSchema<{
+    readonly bridge_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly api_token_env: v.OptionalSchema<v.StringSchema<undefined>, "CLOUDFLARE_API_TOKEN">;
+    readonly sandbox_name: v.OptionalSchema<v.StringSchema<undefined>, "">;
+}, undefined>;
+export type SandboxCloudflareConfig = v.InferOutput<typeof SandboxCloudflareSchema>;
+export declare const SandboxConfigSchema: v.ObjectSchema<{
+    readonly backend: v.OptionalSchema<v.PicklistSchema<["local", "opensandbox", "cloudflare"], undefined>, "local">;
+    readonly scope: v.OptionalSchema<v.PicklistSchema<["run", "agent"], undefined>, "agent">;
+    readonly workspace_dir: v.OptionalSchema<v.StringSchema<undefined>, "/workspace">;
+    readonly handoff_dir: v.OptionalSchema<v.StringSchema<undefined>, "/spf/handoff">;
+    readonly scratch_dir: v.OptionalSchema<v.StringSchema<undefined>, "/spf/tmp">;
+    readonly image: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly setup: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    readonly request_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 960>;
+    readonly lifetime_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 3600>;
+    readonly max_total_lifetime_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 21600>;
+    readonly exec_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 900>;
+    readonly env_allowlist: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    readonly credentials: v.OptionalSchema<v.ObjectSchema<{
+        readonly broker: v.OptionalSchema<v.StringSchema<undefined>, "static">;
+    }, undefined>, () => {
+        broker: string;
+    }>;
+    readonly egress: v.OptionalSchema<v.ObjectSchema<{
+        readonly default: v.OptionalSchema<v.PicklistSchema<["deny", "allow"], undefined>, "deny">;
+        readonly allow: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    }, undefined>, () => {
+        default: "allow" | "deny";
+        allow: string[];
+    }>;
+    readonly transport: v.OptionalSchema<v.ObjectSchema<{
+        readonly max_patch_bytes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 8388608>;
+        readonly max_seed_bytes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 134217728>;
+        readonly max_mirror_bytes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 4194304>;
+        readonly mirror: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    }, undefined>, () => {
+        max_patch_bytes: number;
+        max_seed_bytes: number;
+        max_mirror_bytes: number;
+        mirror: string[];
+    }>;
+    readonly fanout: v.OptionalSchema<v.PicklistSchema<["worktree", "sandbox"], undefined>, "worktree">;
+    readonly opensandbox: v.OptionalSchema<v.ObjectSchema<{
+        readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "http://127.0.0.1:8090">;
+        readonly api_key_env: v.OptionalSchema<v.StringSchema<undefined>, "OPENSANDBOX_API_KEY">;
+        readonly use_server_proxy: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly metadata_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+    }, undefined>, () => {
+        base_url: string;
+        api_key_env: string;
+        use_server_proxy: boolean;
+        metadata_prefix: string;
+    }>;
+    readonly cloudflare: v.OptionalSchema<v.ObjectSchema<{
+        readonly bridge_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly api_token_env: v.OptionalSchema<v.StringSchema<undefined>, "CLOUDFLARE_API_TOKEN">;
+        readonly sandbox_name: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    }, undefined>, () => {
+        bridge_url: string;
+        api_token_env: string;
+        sandbox_name: string;
+    }>;
+}, undefined>;
+export type SandboxConfig = v.InferOutput<typeof SandboxConfigSchema>;
+/**
+ * Pure, sync, derived from config + the run — see `agents.ts`'s
+ * `sandboxSpecFor`. Carried on `AgentRequest.sandbox` below. Lives HERE
+ * (not in `core/sandbox.ts`) so this leaf module keeps importing nothing
+ * but valibot, while fourteen-plus other core modules import it — see
+ * `core/sandbox.ts`'s module comment for the full placement rationale
+ * (SPF #15 design doc §4.3's placement table).
+ */
+export interface SandboxSpec {
+    backend: SandboxBackend;
+    /** Identity available at spec-construction time — BEFORE agentSessionId(). */
+    adw_id: string;
+    agent: string;
+    /**
+     * Lease identity. `<adw_id>/<agent>` when scope=agent (the DEFAULT),
+     * `<adw_id>` when scope=run. INVARIANT: the key is at least as
+     * fine-grained as `env` below, because a container's env is fixed at
+     * create time and a cache hit never re-creates.
+     */
+    lease_key: string;
+    scope: SandboxScope;
+    /** Host side: the tree that is the record of truth. run.repo_root. */
+    host_root: string;
+    /** Sandbox side: workspace_dir. Equals host_root when backend === "local" (never constructed then — see sandboxSpecFor). */
+    workspace_dir: string;
+    /**
+     * Host + sandbox paths for the handoff plane. INVARIANT (enforced by
+     * validateSandboxConfig): handoff_sandbox is NOT under workspace_dir.
+     * SHAPE INVARIANT: handoff_sandbox is
+     * `<handoff_dir>/sessions/<adw_id>/context_handoff`, mirroring
+     * handoff_host = `<data_dir>/sessions/<adw_id>/context_handoff`
+     * (`runner.ts`) — two shipped prompts parse `<adw_id>` out of this shape.
+     */
+    handoff_host: string;
+    handoff_sandbox: string;
+    /**
+     * The TRANSPORT'S OWN scratch plane inside the sandbox: seed.tar,
+     * seed.patch[.b64], out.patch[.b64]. SAME INVARIANT, same enforcement,
+     * same reason as handoff_sandbox: NOT under workspace_dir.
+     */
+    scratch_dir: string;
+    /** THIS AGENT's resolved keys: sandbox.env_allowlist ∩ (agent.env_allowlist ?? all). Already filtered; may be {}. */
+    env: Record<string, string>;
+    image: string;
+    setup: string[];
+    egress: SandboxEgressConfig;
+    lifetime_seconds: number;
+    max_total_lifetime_seconds: number;
+    request_timeout_seconds: number;
+    exec_timeout_seconds: number;
+    transport: SandboxTransportConfig;
+    opensandbox: SandboxOpenSandboxConfig;
+    cloudflare: SandboxCloudflareConfig;
+}
 export declare const AgentConfigSchema: v.ObjectSchema<{
     readonly name: v.StringSchema<undefined>;
     readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
@@ -423,6 +590,7 @@ export declare const AgentConfigSchema: v.ObjectSchema<{
     readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+    readonly sandbox: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["local", "opensandbox", "cloudflare"], undefined>, undefined>, undefined>;
 }, undefined>;
 export type AgentConfig = v.InferOutput<typeof AgentConfigSchema>;
 export declare const ConfigDefaultsSchema: v.ObjectSchema<{
@@ -612,6 +780,37 @@ export declare const WatchRefineConfigSchema: v.ObjectSchema<{
     readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
 }, undefined>;
 export type WatchRefineConfig = v.InferOutput<typeof WatchRefineConfigSchema>;
+/**
+ * Best-of-N per claimed issue — `core/fanout.ts`'s proven machinery pointed at
+ * watch's per-issue dispatch. `n: 1` (the DEFAULT) leaves the daemon's
+ * behaviour untouched: `core/watch.ts`'s `runIssue` takes its existing
+ * single-dispatch path, same adw_id (`issue-<id>`), same one worktree, same
+ * everything. (`spf doctor` gains one informational line either way — see
+ * that command; nothing about a running daemon changes.)
+ *
+ * `concurrency` is DELIBERATELY NOT `watch.concurrency`, which counts ISSUES in
+ * flight (`core/watch.ts`'s `state.inflight`, a set of issue ids). This one
+ * counts ATTEMPTS in flight WITHIN one issue. The two multiply — see
+ * `spf doctor`'s `watch.fanout budget` line, which prints the product rather
+ * than leaving an operator to discover it on an invoice. Same "each axis of
+ * parallelism gets its own named budget" rule `refine.concurrency` already
+ * follows (see `WatchRunState.refining`'s doc comment).
+ *
+ * NOTE that `concurrency` bounds attempts IN FLIGHT, not worktrees ON DISK: a
+ * successful attempt's tree is KEPT until every sibling has settled (it is a
+ * selection candidate), so peak disk is `n` trees per issue regardless of this
+ * number. Doctor prints both.
+ *
+ * The `n` ceiling is 8, the twin of `MAX_N` in `cli/commands/fanout.ts` — kept
+ * as a literal here rather than imported because this module imports nothing
+ * but valibot, on purpose (see `SandboxSpec`'s placement note). A daemon typing
+ * a bigger number is strictly worse than an interactive command doing so.
+ */
+export declare const WatchFanoutConfigSchema: v.ObjectSchema<{
+    readonly n: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 8, undefined>]>, 1>;
+    readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+}, undefined>;
+export type WatchFanoutConfig = v.InferOutput<typeof WatchFanoutConfigSchema>;
 export declare const WatchConfigSchema: v.ObjectSchema<{
     readonly issue_provider: v.OptionalSchema<v.PicklistSchema<["github", "jira"], undefined>, "github">;
     readonly code_host: v.OptionalSchema<v.PicklistSchema<["github", "bitbucket"], undefined>, "github">;
@@ -674,6 +873,13 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
         chain: string;
         concurrency: number;
     }>;
+    readonly fanout: v.OptionalSchema<v.ObjectSchema<{
+        readonly n: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 8, undefined>]>, 1>;
+        readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+    }, undefined>, () => {
+        n: number;
+        concurrency: number;
+    }>;
 }, undefined>;
 export type WatchConfig = v.InferOutput<typeof WatchConfigSchema>;
 /**
@@ -904,6 +1110,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+        readonly sandbox: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["local", "opensandbox", "cloudflare"], undefined>, undefined>, undefined>;
     }, undefined>, undefined>, () => never[]>;
     readonly quality: v.OptionalSchema<v.ObjectSchema<{
         readonly checks: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
@@ -988,6 +1195,13 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             chain: string;
             concurrency: number;
         }>;
+        readonly fanout: v.OptionalSchema<v.ObjectSchema<{
+            readonly n: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 8, undefined>]>, 1>;
+            readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+        }, undefined>, () => {
+            n: number;
+            concurrency: number;
+        }>;
     }, undefined>, () => {
         issue_provider: "github" | "jira";
         code_host: "bitbucket" | "github";
@@ -1017,6 +1231,10 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             chain: string;
             concurrency: number;
         };
+        fanout: {
+            n: number;
+            concurrency: number;
+        };
     }>;
     readonly notifications: v.OptionalSchema<v.ObjectSchema<{
         readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, "off">;
@@ -1063,6 +1281,102 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             [x: string]: string;
         };
     }>;
+    readonly sandbox: v.OptionalSchema<v.ObjectSchema<{
+        readonly backend: v.OptionalSchema<v.PicklistSchema<["local", "opensandbox", "cloudflare"], undefined>, "local">;
+        readonly scope: v.OptionalSchema<v.PicklistSchema<["run", "agent"], undefined>, "agent">;
+        readonly workspace_dir: v.OptionalSchema<v.StringSchema<undefined>, "/workspace">;
+        readonly handoff_dir: v.OptionalSchema<v.StringSchema<undefined>, "/spf/handoff">;
+        readonly scratch_dir: v.OptionalSchema<v.StringSchema<undefined>, "/spf/tmp">;
+        readonly image: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly setup: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+        readonly request_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 960>;
+        readonly lifetime_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 3600>;
+        readonly max_total_lifetime_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 21600>;
+        readonly exec_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 900>;
+        readonly env_allowlist: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+        readonly credentials: v.OptionalSchema<v.ObjectSchema<{
+            readonly broker: v.OptionalSchema<v.StringSchema<undefined>, "static">;
+        }, undefined>, () => {
+            broker: string;
+        }>;
+        readonly egress: v.OptionalSchema<v.ObjectSchema<{
+            readonly default: v.OptionalSchema<v.PicklistSchema<["deny", "allow"], undefined>, "deny">;
+            readonly allow: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+        }, undefined>, () => {
+            default: "allow" | "deny";
+            allow: string[];
+        }>;
+        readonly transport: v.OptionalSchema<v.ObjectSchema<{
+            readonly max_patch_bytes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 8388608>;
+            readonly max_seed_bytes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 134217728>;
+            readonly max_mirror_bytes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 4194304>;
+            readonly mirror: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+        }, undefined>, () => {
+            max_patch_bytes: number;
+            max_seed_bytes: number;
+            max_mirror_bytes: number;
+            mirror: string[];
+        }>;
+        readonly fanout: v.OptionalSchema<v.PicklistSchema<["worktree", "sandbox"], undefined>, "worktree">;
+        readonly opensandbox: v.OptionalSchema<v.ObjectSchema<{
+            readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "http://127.0.0.1:8090">;
+            readonly api_key_env: v.OptionalSchema<v.StringSchema<undefined>, "OPENSANDBOX_API_KEY">;
+            readonly use_server_proxy: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+            readonly metadata_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+        }, undefined>, () => {
+            base_url: string;
+            api_key_env: string;
+            use_server_proxy: boolean;
+            metadata_prefix: string;
+        }>;
+        readonly cloudflare: v.OptionalSchema<v.ObjectSchema<{
+            readonly bridge_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
+            readonly api_token_env: v.OptionalSchema<v.StringSchema<undefined>, "CLOUDFLARE_API_TOKEN">;
+            readonly sandbox_name: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        }, undefined>, () => {
+            bridge_url: string;
+            api_token_env: string;
+            sandbox_name: string;
+        }>;
+    }, undefined>, () => {
+        backend: "cloudflare" | "local" | "opensandbox";
+        scope: "agent" | "run";
+        workspace_dir: string;
+        handoff_dir: string;
+        scratch_dir: string;
+        image: string;
+        setup: string[];
+        request_timeout_seconds: number;
+        lifetime_seconds: number;
+        max_total_lifetime_seconds: number;
+        exec_timeout_seconds: number;
+        env_allowlist: string[];
+        credentials: {
+            broker: string;
+        };
+        egress: {
+            default: "allow" | "deny";
+            allow: string[];
+        };
+        transport: {
+            max_patch_bytes: number;
+            max_seed_bytes: number;
+            max_mirror_bytes: number;
+            mirror: string[];
+        };
+        fanout: "sandbox" | "worktree";
+        opensandbox: {
+            base_url: string;
+            api_key_env: string;
+            use_server_proxy: boolean;
+            metadata_prefix: string;
+        };
+        cloudflare: {
+            bridge_url: string;
+            api_token_env: string;
+            sandbox_name: string;
+        };
+    }>;
 }, undefined>;
 export type SFConfig = v.InferOutput<typeof SFConfigSchema>;
 /** The full set of event kinds any tracer.event()/makeEventRecord() call site emits — kept in sync with src/ui/shared/types.ts's EventType. */
@@ -1116,6 +1430,8 @@ export interface AgentRequest {
     cwd: string;
     flue_db_path: string;
     env?: Record<string, string>;
+    /** Absent (the default) => local(), byte-identical to before this field existed. See sandbox.ts. */
+    sandbox?: SandboxSpec;
 }
 /**
  * Tokens and the dollars they cost, per component, summed over a call.

package/dist/core/data_types.js

@@ -302,6 +302,110 @@ export const PromptEngineeringSchema = v.object({
     user: v.string(), // path to user.md
 });
 export const ThinkingLevelSchema = v.picklist(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+// ── Sandbox (SPF #15 — remote sandbox backends) ─────────────────────────────
+//
+// Absent `sandbox:` block entirely => backend: "local", byte-identical to
+// SPF before this feature existed — see agents.ts's `mergeRawConfig` (the
+// `sandbox` line) and `SFConfigSchema` below, whose own `v.optional` default
+// makes `cfg.sandbox` always defined even with no config file naming it. See
+// `assets/skill/references/config.md`'s `### sandbox` section for the
+// field-by-field rationale; this schema only encodes shape and defaults.
+export const SandboxBackendSchema = v.picklist(["local", "opensandbox", "cloudflare"]);
+/**
+ * "agent" (the DEFAULT) — one sandbox per (Run, agent), so a container's
+ * process env (fixed at create time) is built from exactly one agent's
+ * allowlist. "run" — one sandbox for the whole Run; admitted only when
+ * every required agent resolves to an IDENTICAL env spec, enforced by
+ * `agents.ts`'s `validateSandboxRunScope`.
+ */
+export const SandboxScopeSchema = v.picklist(["run", "agent"]);
+export const SandboxEgressSchema = v.object({
+    default: v.optional(v.picklist(["deny", "allow"]), "deny"),
+    allow: v.optional(v.array(v.string()), () => []),
+});
+/**
+ * `max_mirror_bytes` caps the handoff mirror (§5.3 point 2), EACH direction,
+ * per file. `max_patch_bytes`/`max_seed_bytes` cap the code-plane transport
+ * (§5.2). Exceeding any of them FAILS the phase; none of them ever truncate.
+ */
+export const SandboxTransportSchema = v.object({
+    max_patch_bytes: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 8_388_608),
+    max_seed_bytes: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 134_217_728),
+    max_mirror_bytes: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 4_194_304),
+    // Extra repo-relative paths to sync out of the sandbox that git cannot
+    // carry (gitignored artifacts you want back).
+    mirror: v.optional(v.array(v.string()), () => []),
+});
+/**
+ * A plain string, not a picklist — a future broker (design §6.3, e.g.
+ * `openrouter`) registers itself in code (`sandbox.ts`'s
+ * `KNOWN_CREDENTIAL_BROKER_IDS`), so accepting new ids here must not also
+ * require a schema change in lockstep. "static" is the only broker
+ * REGISTERED in this build (PR A ships none at all — see sandbox.ts); an
+ * unknown name is a `validateSandboxConfig` failure (agents.ts), never a
+ * silent fallback to "static" — see design §6.1.
+ */
+export const SandboxCredentialsSchema = v.object({
+    broker: v.optional(v.string(), "static"),
+});
+export const SandboxOpenSandboxSchema = v.object({
+    base_url: v.optional(v.string(), "http://127.0.0.1:8090"),
+    // env KEY NAME, never the key itself — matches the GITHUB_TOKEN style.
+    api_key_env: v.optional(v.string(), "OPENSANDBOX_API_KEY"),
+    use_server_proxy: v.optional(v.boolean(), false),
+    metadata_prefix: v.optional(v.string(), "spf"),
+});
+export const SandboxCloudflareSchema = v.object({
+    bridge_url: v.optional(v.string(), ""), // a deployed @cloudflare/sandbox bridge
+    api_token_env: v.optional(v.string(), "CLOUDFLARE_API_TOKEN"),
+    sandbox_name: v.optional(v.string(), ""), // optional stable name; default derives from session id
+});
+export const SandboxConfigSchema = v.object({
+    backend: v.optional(SandboxBackendSchema, "local"),
+    scope: v.optional(SandboxScopeSchema, "agent"),
+    workspace_dir: v.optional(v.string(), "/workspace"), // absolute path INSIDE the sandbox
+    // The ROOT of the handoff plane inside the sandbox. The per-run dir the
+    // prompts actually see is DERIVED from it: `<handoff_dir>/sessions/<adw_id>/
+    // context_handoff`, mirroring `handoff_host` (`runner.ts`'s
+    // `context_handoff_dir`) — see `SandboxSpec.handoff_sandbox` below. MUST
+    // NOT be under `workspace_dir` — enforced by `validateSandboxConfig`.
+    handoff_dir: v.optional(v.string(), "/spf/handoff"),
+    // The TRANSPORT'S OWN scratch plane (seed.tar, seed.patch[.b64],
+    // out.patch[.b64]) — same "not under workspace_dir" rule, same reason,
+    // same enforcement as handoff_dir.
+    scratch_dir: v.optional(v.string(), "/spf/tmp"),
+    // opensandbox only. NO DEFAULT: `validateSandboxConfig` rejects an empty
+    // `image` when the resolved backend is "opensandbox" — it MUST contain
+    // git + tar + base64 (the transport shells out to all three).
+    image: v.optional(v.string(), ""),
+    setup: v.optional(v.array(v.string()), () => []), // shell commands run ONCE per sandbox, after seeding
+    // ConnectionConfig.requestTimeoutSeconds — the SDK's CLIENT-SIDE HTTP
+    // timeout, applied to every control-plane call. NOT the bound on a long
+    // agent command (exec is driven with streaming handlers) — see sandbox.ts.
+    request_timeout_seconds: v.optional(v.pipe(v.number(), v.minValue(1)), 960),
+    lifetime_seconds: v.optional(v.pipe(v.number(), v.minValue(1)), 3_600), // provider-side expiry, renewed while a lease is live
+    max_total_lifetime_seconds: v.optional(v.pipe(v.number(), v.minValue(1)), 21_600), // HARD ceiling from creation; renew refuses past it
+    // The DEFAULT per-command deadline, applied only when the caller supplies
+    // none. NOT a ceiling — a caller-supplied timeoutMs passes through
+    // unmodified, exactly as it does on backend: local. See sandbox.ts.
+    exec_timeout_seconds: v.optional(v.pipe(v.number(), v.minValue(1)), 900),
+    // Credentials handed to the sandbox process environment at create time.
+    // DEFAULT IS EMPTY — deliberately NOT the operator env local() gets today.
+    // The set that actually reaches a given container is the intersection of
+    // this list with THAT AGENT's own env_allowlist (unset = no further
+    // narrowing) — see agents.ts's sandboxSpecFor.
+    env_allowlist: v.optional(v.array(v.string()), () => []),
+    credentials: v.optional(SandboxCredentialsSchema, () => v.parse(SandboxCredentialsSchema, {})),
+    egress: v.optional(SandboxEgressSchema, () => v.parse(SandboxEgressSchema, {})),
+    transport: v.optional(SandboxTransportSchema, () => v.parse(SandboxTransportSchema, {})),
+    // worktree (default, honored) | sandbox (fan-out THROUGH sandboxes — PR B).
+    // Parsed and schema-valid here in PR A; agents.ts's validateSandboxConfig
+    // hard-rejects "sandbox" until PR B lands, naming the key — never a silent
+    // degrade back to worktrees.
+    fanout: v.optional(v.picklist(["worktree", "sandbox"]), "worktree"),
+    opensandbox: v.optional(SandboxOpenSandboxSchema, () => v.parse(SandboxOpenSandboxSchema, {})),
+    cloudflare: v.optional(SandboxCloudflareSchema, () => v.parse(SandboxCloudflareSchema, {})),
+});
 export const AgentConfigSchema = v.object({
     name: v.string(),
     coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
@@ -330,6 +434,13 @@ export const AgentConfigSchema = v.object({
     // (PATH/HOME/USER/LANG/TERM/TMPDIR) that agent_flue.ts's local() sandbox
     // would keep anyway.
     env_allowlist: v.optional(v.nullable(v.array(v.string()))),
+    // Per-agent sandbox backend override (SPF #15) — a bare backend name, not
+    // a nested block; everything else (image, egress, transport, credentials
+    // POLICY) stays repo-scoped on `sandbox:` above.
+    //   unset  -> inherit sandbox.backend
+    //   "local" -> force local for this agent
+    //   null    -> same as unset (the writes/env_allowlist spelling)
+    sandbox: v.optional(v.nullable(SandboxBackendSchema)),
 });
 export const ConfigDefaultsSchema = v.object({
     coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
@@ -504,6 +615,36 @@ export const WatchRefineConfigSchema = v.object({
     chain: v.optional(v.string(), "refine"),
     concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 1),
 });
+/**
+ * Best-of-N per claimed issue — `core/fanout.ts`'s proven machinery pointed at
+ * watch's per-issue dispatch. `n: 1` (the DEFAULT) leaves the daemon's
+ * behaviour untouched: `core/watch.ts`'s `runIssue` takes its existing
+ * single-dispatch path, same adw_id (`issue-<id>`), same one worktree, same
+ * everything. (`spf doctor` gains one informational line either way — see
+ * that command; nothing about a running daemon changes.)
+ *
+ * `concurrency` is DELIBERATELY NOT `watch.concurrency`, which counts ISSUES in
+ * flight (`core/watch.ts`'s `state.inflight`, a set of issue ids). This one
+ * counts ATTEMPTS in flight WITHIN one issue. The two multiply — see
+ * `spf doctor`'s `watch.fanout budget` line, which prints the product rather
+ * than leaving an operator to discover it on an invoice. Same "each axis of
+ * parallelism gets its own named budget" rule `refine.concurrency` already
+ * follows (see `WatchRunState.refining`'s doc comment).
+ *
+ * NOTE that `concurrency` bounds attempts IN FLIGHT, not worktrees ON DISK: a
+ * successful attempt's tree is KEPT until every sibling has settled (it is a
+ * selection candidate), so peak disk is `n` trees per issue regardless of this
+ * number. Doctor prints both.
+ *
+ * The `n` ceiling is 8, the twin of `MAX_N` in `cli/commands/fanout.ts` — kept
+ * as a literal here rather than imported because this module imports nothing
+ * but valibot, on purpose (see `SandboxSpec`'s placement note). A daemon typing
+ * a bigger number is strictly worse than an interactive command doing so.
+ */
+export const WatchFanoutConfigSchema = v.object({
+    n: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(8)), 1),
+    concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 2),
+});
 export const WatchConfigSchema = v.object({
     issue_provider: v.optional(WatchIssueProviderSchema, "github"),
     code_host: v.optional(WatchCodeHostSchema, "github"),
@@ -532,6 +673,7 @@ export const WatchConfigSchema = v.object({
     chain_options: v.optional(v.record(v.string(), v.string()), () => ({})),
     jira: v.optional(WatchJiraConfigSchema, () => v.parse(WatchJiraConfigSchema, {})),
     refine: v.optional(WatchRefineConfigSchema, () => v.parse(WatchRefineConfigSchema, {})),
+    fanout: v.optional(WatchFanoutConfigSchema, () => v.parse(WatchFanoutConfigSchema, {})),
 });
 /**
  * Optional outbound push for unattended work (`spf watch`, any chain run) —
@@ -666,6 +808,7 @@ export const SFConfigSchema = v.object({
     notifications: v.optional(NotificationsConfigSchema, () => v.parse(NotificationsConfigSchema, {})),
     review: v.optional(ReviewConfigSchema, () => v.parse(ReviewConfigSchema, {})),
     tiering: v.optional(TieringConfigSchema, () => v.parse(TieringConfigSchema, {})),
+    sandbox: v.optional(SandboxConfigSchema, () => v.parse(SandboxConfigSchema, {})),
 });
 // ── Tracing ──────────────────────────────────────────────────────────────────
 /** The full set of event kinds any tracer.event()/makeEventRecord() call site emits — kept in sync with src/ui/shared/types.ts's EventType. */