@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/tools/worktree-root.ts

@@ -0,0 +1,252 @@
+/**
+ * Where a task worktree's working tree lives (`fleet.worktrees.root`).
+ *
+ * `disk` is the project-root location, `<root>/.clio-coder/worktrees`, and the
+ * default. `tmpfs` puts the working tree on a RAM-backed mount, `auto` does so
+ * when one exists and has room, and an absolute path names any other
+ * directory. Only the working tree moves: git objects, the index, the branch,
+ * and the ownership claim stay with the parent repository on disk, so a tmpfs
+ * root lost at reboot loses uncommitted files and nothing else.
+ *
+ * An off-disk root applies to local placement only. A remote node reaches a
+ * worktree by the same path the orchestrator uses, and doctor's preflight
+ * proves path parity for the project root alone, so a fleet with nodes keeps
+ * every task worktree under the project root.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, statfsSync } from "node:fs";
+import { userInfo } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+export type WorktreeRootSetting = "auto" | "tmpfs" | "disk" | (string & {});
+
+/** Headroom on top of twice the tracked tree: a worker builds in its worktree. */
+export const WORKTREE_FREE_SPACE_MARGIN_BYTES = 256 * 1024 * 1024;
+
+/** Host facts the resolver reads, injectable so tests need no tmpfs and no full disk. */
+export interface WorktreeRootFacts {
+	/** Directories to try for `tmpfs` and `auto`, in order. */
+	tmpfsCandidates(): string[];
+	/** Filesystem type of the mount holding `path`, or null when unknown. */
+	filesystemType(path: string): string | null;
+	/** Bytes available to this user on the filesystem holding `path`, or null. */
+	freeBytes(path: string): number | null;
+	/** Bytes of the tracked files a new worktree checks out, or null. */
+	workingTreeBytes(projectRoot: string): number | null;
+	/** Stable per-user segment, so users sharing /dev/shm never share a directory. */
+	userSegment(): string;
+}
+
+function unescapeMountField(field: string): string {
+	return field.replace(/\\([0-7]{3})/gu, (_match, octal: string) => String.fromCharCode(Number.parseInt(octal, 8)));
+}
+
+/** Longest mount point that is `path` or an ancestor of it, from /proc/mounts. */
+function procMountsType(path: string): string | null {
+	let text: string;
+	try {
+		text = readFileSync("/proc/mounts", "utf8");
+	} catch {
+		return null;
+	}
+	const target = resolve(path);
+	let best: { point: string; type: string } | null = null;
+	for (const line of text.split("\n")) {
+		const fields = line.split(" ");
+		const point = unescapeMountField(fields[1] ?? "");
+		const type = fields[2];
+		if (point.length === 0 || type === undefined) continue;
+		const covers = target === point || target.startsWith(point === "/" ? "/" : `${point}/`);
+		// A later line for the same point is the mount on top.
+		if (covers && (best === null || point.length >= best.point.length)) best = { point, type };
+	}
+	return best?.type ?? null;
+}
+
+export const HOST_WORKTREE_ROOT_FACTS: WorktreeRootFacts = {
+	tmpfsCandidates() {
+		const runtime = process.env.XDG_RUNTIME_DIR;
+		return [...(runtime !== undefined && isAbsolute(runtime) ? [runtime] : []), "/dev/shm"];
+	},
+	filesystemType: procMountsType,
+	freeBytes(path) {
+		try {
+			const stats = statfsSync(path);
+			return stats.bavail * stats.bsize;
+		} catch {
+			return null;
+		}
+	},
+	workingTreeBytes(projectRoot) {
+		try {
+			const listing = execFileSync("git", ["-C", projectRoot, "ls-tree", "-r", "-l", "-z", "HEAD"], {
+				stdio: ["ignore", "pipe", "ignore"],
+				timeout: 30_000,
+				maxBuffer: 256 * 1024 * 1024,
+			}).toString("utf8");
+			let total = 0;
+			for (const entry of listing.split("\0")) {
+				// `<mode> <type> <object> <size>\t<path>`; a submodule's size is `-`.
+				const size = Number.parseInt(entry.slice(0, entry.indexOf("\t")).trim().split(/\s+/u)[3] ?? "", 10);
+				if (Number.isSafeInteger(size)) total += size;
+			}
+			return total;
+		} catch {
+			return null;
+		}
+	},
+	userSegment() {
+		try {
+			return `clio-coder-${userInfo().uid}`;
+		} catch {
+			return "clio-coder";
+		}
+	},
+};
+
+export interface ResolvedWorktreeRoot {
+	/** Directory a task worktree is created in, as `<parent>/<runId>`. */
+	parent: string;
+	kind: "disk" | "tmpfs" | "path";
+	/** The mount or configured directory `parent` sits under; absent for disk. */
+	base?: string;
+	/** Why the setting did not get what it asked for; absent when it did. */
+	notice?: string;
+}
+
+export function diskWorktreeParent(projectRoot: string): string {
+	return join(projectRoot, ".clio-coder", "worktrees");
+}
+
+/** Worktrees of different checkouts never share a directory under a shared root. */
+function repositoryKey(projectRoot: string): string {
+	return createHash("sha256").update(projectRoot).digest("hex").slice(0, 16);
+}
+
+function tmpfsParent(base: string, projectRoot: string, facts: WorktreeRootFacts): string {
+	return join(base, facts.userSegment(), "worktrees", repositoryKey(projectRoot));
+}
+
+function customParent(base: string, projectRoot: string): string {
+	return join(resolve(base), repositoryKey(projectRoot));
+}
+
+/**
+ * Every directory a task worktree of this checkout may live in: the disk
+ * location, this user's directory on each tmpfs candidate, and the configured
+ * absolute path. Ownership checks accept a path under one of these and nothing
+ * else. The tmpfs directories count whatever the setting says now, so a
+ * worktree created under `tmpfs` is still recognized after a switch to `disk`.
+ */
+export function allowedWorktreeParents(
+	setting: WorktreeRootSetting,
+	projectRoot: string,
+	facts: WorktreeRootFacts = HOST_WORKTREE_ROOT_FACTS,
+): string[] {
+	const parents = [diskWorktreeParent(projectRoot)];
+	for (const base of facts.tmpfsCandidates()) parents.push(tmpfsParent(base, projectRoot, facts));
+	if (isAbsolute(setting)) parents.push(customParent(setting, projectRoot));
+	return parents;
+}
+
+function formatMiB(bytes: number): string {
+	return `${Math.ceil(bytes / (1024 * 1024))} MiB`;
+}
+
+/** Null when `base` has room for a worktree of this checkout, else why not. */
+function shortOfSpace(base: string, projectRoot: string, facts: WorktreeRootFacts): string | null {
+	const tree = facts.workingTreeBytes(projectRoot);
+	const free = facts.freeBytes(base);
+	if (tree === null) return "the working tree could not be sized";
+	if (free === null) return `free space on ${base} could not be read`;
+	const needed = tree * 2 + WORKTREE_FREE_SPACE_MARGIN_BYTES;
+	return free >= needed ? null : `${base} has ${formatMiB(free)} free and a worktree needs ${formatMiB(needed)}`;
+}
+
+export interface ResolveWorktreeRootInput {
+	setting: WorktreeRootSetting;
+	/** Canonical checkout root. */
+	projectRoot: string;
+	/** True when the fleet has nodes, so the run may be placed on another host. */
+	remoteEligible: boolean;
+	facts?: WorktreeRootFacts;
+}
+
+/**
+ * Pick the parent directory for the next task worktree. Every way an off-disk
+ * root can fall through lands on the disk location with a notice naming why,
+ * so a worktree is always created somewhere it can be used.
+ */
+export function resolveWorktreeRoot(input: ResolveWorktreeRootInput): ResolvedWorktreeRoot {
+	const facts = input.facts ?? HOST_WORKTREE_ROOT_FACTS;
+	const disk: ResolvedWorktreeRoot = { parent: diskWorktreeParent(input.projectRoot), kind: "disk" };
+	const { setting } = input;
+	if (setting === "disk") return disk;
+	if (input.remoteEligible) {
+		return { ...disk, notice: "fleet nodes are configured, so task worktrees stay under the project root" };
+	}
+	if (isAbsolute(setting)) {
+		const short = shortOfSpace(setting, input.projectRoot, facts);
+		if (short !== null) return { ...disk, notice: `${short}; using the project root` };
+		return { parent: customParent(setting, input.projectRoot), kind: "path", base: resolve(setting) };
+	}
+	const reasons: string[] = [];
+	let sawTmpfs = false;
+	for (const base of facts.tmpfsCandidates()) {
+		const type = facts.filesystemType(base);
+		if (type !== "tmpfs") {
+			reasons.push(`${base} is ${type ?? "not a readable mount"}, not tmpfs`);
+			continue;
+		}
+		sawTmpfs = true;
+		const short = shortOfSpace(base, input.projectRoot, facts);
+		if (short !== null) {
+			reasons.push(short);
+			continue;
+		}
+		return { parent: tmpfsParent(base, input.projectRoot, facts), kind: "tmpfs", base };
+	}
+	// `auto` means "tmpfs when it is there": on a host without one, disk is its
+	// second answer, not a failure. A tmpfs that is short of room is reported.
+	if (setting === "auto" && !sawTmpfs) return disk;
+	return { ...disk, notice: `no usable tmpfs (${reasons.join("; ") || "no candidates"}); using the project root` };
+}
+
+/**
+ * Create an off-disk parent so that it is ours alone. `/dev/shm` is
+ * world-writable, so another user can plant `clio-coder-<uid>` there first as
+ * a link or as a directory they own, and a worktree created beneath it would
+ * be theirs to read and rewrite. Every directory between the base and the
+ * parent must be a real directory owned by this user; each one created here
+ * is mode 0700. Returns why the parent cannot be trusted, or null.
+ */
+export function prepareWorktreeParent(resolved: ResolvedWorktreeRoot): string | null {
+	if (resolved.kind === "disk" || resolved.base === undefined) return null;
+	const rel = relative(resolved.base, resolved.parent);
+	if (rel.length === 0 || rel.startsWith("..") || isAbsolute(rel))
+		return `${resolved.parent} is not under ${resolved.base}`;
+	const uid = typeof process.getuid === "function" ? process.getuid() : null;
+	let cursor = resolved.base;
+	for (const segment of rel.split(sep)) {
+		cursor = join(cursor, segment);
+		try {
+			mkdirSync(cursor, { mode: 0o700 });
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+				return `${cursor} could not be created: ${(error as Error).message}`;
+			}
+		}
+		let stats: ReturnType<typeof lstatSync>;
+		try {
+			stats = lstatSync(cursor);
+		} catch (error) {
+			return `${cursor} could not be inspected: ${(error as Error).message}`;
+		}
+		if (!stats.isDirectory()) return `${cursor} is not a plain directory`;
+		if (uid !== null && stats.uid !== uid) return `${cursor} belongs to another user`;
+		if ((stats.mode & 0o022) !== 0) return `${cursor} is writable by other users`;
+	}
+	return null;
+}

package/src/tools/write.ts

@@ -3,7 +3,7 @@ import { Type } from "typebox";
 import { ToolNames } from "../core/tool-names.js";
 import { generateDiffString } from "./edit-diff.js";
 import { publishFileAtomically, withFileMutationQueue } from "./file-mutation-queue.js";
-import { resolveToCwd } from "./path-utils.js";
+import { resolveMutationTarget } from "./path-utils.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
 
 export const writeTool: ToolSpec = {
@@ -22,39 +22,43 @@ export const writeTool: ToolSpec = {
 		const content =
 			typeof args.content === "string" ? args.content : args.content === undefined ? null : String(args.content);
 		if (content === null) return { kind: "error", message: "write: missing content argument" };
-		const filePath = resolveToCwd(pathArg);
+		const { path: filePath, physical } = resolveMutationTarget(pathArg);
 		try {
 			const bytes = Buffer.byteLength(content, "utf8");
-			const { file, diff, previousEndedWithNewline, skipDiff } = await withFileMutationQueue(filePath, async () => {
-				const previous = await stat(filePath).catch((error: NodeJS.ErrnoException) => {
-					if (error.code === "ENOENT") return null;
-					throw error;
-				});
-				if (previous && !previous.isFile()) throw new Error("Refusing directory or non-file target");
-				let skipDiff = Math.max(previous?.size ?? 0, bytes) > 1024 * 1024;
-				let previousContent = "";
-				if (previous && !skipDiff) {
-					const handle = await open(filePath, "r");
-					try {
-						// The sentinel bounds the actual read even if an external writer
-						// grows or replaces the file after the earlier metadata check.
-						const buffer = Buffer.allocUnsafe(1024 * 1024 + 1);
-						let total = 0;
-						while (total < buffer.length) {
-							const { bytesRead } = await handle.read(buffer, total, buffer.length - total, total);
-							if (bytesRead === 0) break;
-							total += bytesRead;
+			const { file, diff, previousEndedWithNewline, skipDiff } = await withFileMutationQueue(
+				filePath,
+				async () => {
+					const previous = await stat(filePath).catch((error: NodeJS.ErrnoException) => {
+						if (error.code === "ENOENT") return null;
+						throw error;
+					});
+					if (previous && !previous.isFile()) throw new Error("Refusing directory or non-file target");
+					let skipDiff = Math.max(previous?.size ?? 0, bytes) > 1024 * 1024;
+					let previousContent = "";
+					if (previous && !skipDiff) {
+						const handle = await open(filePath, "r");
+						try {
+							// The sentinel bounds the actual read even if an external writer
+							// grows or replaces the file after the earlier metadata check.
+							const buffer = Buffer.allocUnsafe(1024 * 1024 + 1);
+							let total = 0;
+							while (total < buffer.length) {
+								const { bytesRead } = await handle.read(buffer, total, buffer.length - total, total);
+								if (bytesRead === 0) break;
+								total += bytesRead;
+							}
+							skipDiff = total > 1024 * 1024;
+							if (!skipDiff) previousContent = buffer.toString("utf8", 0, total);
+						} finally {
+							await handle.close();
 						}
-						skipDiff = total > 1024 * 1024;
-						if (!skipDiff) previousContent = buffer.toString("utf8", 0, total);
-					} finally {
-						await handle.close();
 					}
-				}
-				const diff = skipDiff ? undefined : generateDiffString(previousContent, content).diff;
-				const file = await publishFileAtomically(filePath, content);
-				return { file, diff, previousEndedWithNewline: previousContent.endsWith("\n"), skipDiff };
-			});
+					const diff = skipDiff ? undefined : generateDiffString(previousContent, content).diff;
+					const file = await publishFileAtomically(filePath, content);
+					return { file, diff, previousEndedWithNewline: previousContent.endsWith("\n"), skipDiff };
+				},
+				physical,
+			);
 			let output = `wrote ${bytes}B to ${pathArg}`;
 			if (skipDiff) output += "\nnote: diff skipped because the previous or new file exceeds 1 MiB";
 			if (file.durabilityWarning) output += `\n${file.durabilityWarning}`;

package/src/worker/entry.ts

@@ -40,7 +40,11 @@ deleteInjectedCompileCacheFrom(process.env);
 // the worker's own environment.
 process.env.CLIO_CODER_WORKER_RUN = "1";
 
-import { setProtectedModelsProvider, setResidencyNoticeSink } from "../engine/apis/residency.js";
+import {
+	setModelLoadReportSink,
+	setProtectedModelsProvider,
+	setResidencyNoticeSink,
+} from "../engine/apis/residency.js";
 import { startWorkerRun, type WorkerRunInput, workerProviderSupportsTools } from "../engine/worker-runtime.js";
 import { attestedToolSignature } from "../engine/worker-tools.js";
 import { emitControlFrame } from "./control-lane.js";
@@ -106,6 +110,7 @@ function announceWorker(spec: WorkerSpec, input: WorkerRunInput): void {
 			toolSignature: attestedToolSignature({
 				allowedTools: spec.allowedTools,
 				toolsSupported: workerProviderSupportsTools(input),
+				...(spec.helperResult === true ? { helperResult: true } : {}),
 				...(spec.toolProfile !== undefined ? { toolProfile: spec.toolProfile } : {}),
 				agentId: spec.agentId,
 				task: spec.task,
@@ -125,6 +130,16 @@ async function main(): Promise<number> {
 			emitEvent({ type: "clio_coder_run_outcome", payload: { outcomeCode: "vram_capacity_fit_failure" } });
 		}
 	});
+	// The orchestrator owns the release of every model this worker loads
+	// (#379): a worker that released on its own exit would reload the model for
+	// each sequential dispatch and pull it from under a parallel sibling. Only
+	// ids cross the lane; the orchestrator resolves the endpoint itself.
+	setModelLoadReportSink((load) => {
+		emitControlFrame({
+			kind: "model_loaded",
+			load: { targetId: load.targetId, modelId: load.modelId, aliasIds: load.aliasIds },
+		});
+	});
 	const demux = createWorkerStdinDemux();
 	process.stdin.setEncoding("utf8");
 	process.stdin.on("data", (chunk: string) => demux.feed(chunk));
@@ -189,6 +204,7 @@ async function main(): Promise<number> {
 		allowedTools: spec.allowedTools,
 		budget: spec.budget,
 		...(spec.noSkills !== undefined ? { noSkills: spec.noSkills } : {}),
+		...(spec.turnConstraints !== undefined ? { turnConstraints: spec.turnConstraints } : {}),
 		...(spec.skillPaths !== undefined ? { skillPaths: [...spec.skillPaths] } : {}),
 		...(spec.agentSkills !== undefined ? { agentSkills: [...spec.agentSkills] } : {}),
 		...(spec.trustProjectCompatRoots !== undefined ? { trustProjectCompatRoots: spec.trustProjectCompatRoots } : {}),
@@ -207,6 +223,7 @@ async function main(): Promise<number> {
 			: {}),
 		...(spec.responseSchema !== undefined ? { responseSchema: spec.responseSchema } : {}),
 		...(spec.resultContract !== undefined ? { resultContract: spec.resultContract } : {}),
+		...(spec.helperResult === true ? { helperResult: true } : {}),
 		...(spec.product !== undefined ? { product: spec.product } : {}),
 		agentLedger: ledgerPort,
 		cwd: process.cwd(),

package/src/worker/protocol.ts

@@ -24,6 +24,16 @@
 import { createHash } from "node:crypto";
 import { normalizeClioCoderEventRecord } from "../core/naming-events.js";
 
+/** Internal JSON handoffs; artifact and mutation contracts keep their existing delivery paths. */
+export const INTERNAL_HELPER_RESULT_KINDS = [
+	"scout-report",
+	"research-report",
+	"world-knowledge-report",
+	"provenance-report",
+	"oracle-report",
+	"context-handbook",
+] as const;
+
 /** Current wire protocol. A peer announcing anything else is not executed. */
 export const WORKER_PROTOCOL_VERSION = 1;
 
@@ -273,11 +283,30 @@ export interface AgentLedgerPort {
 	read(): { open: boolean; watermark: number; entries: ReadonlyArray<AgentLedgerEntry> } | null;
 }
 
+/**
+ * A model the worker's own request loaded and pinned. The orchestrator owns the
+ * release of worker loads (#379), so the worker reports each one and the
+ * orchestrator releases it when it exits. Only ids cross the wire: the
+ * orchestrator resolves the endpoint and any headers from its own settings for
+ * the admitted target, so no credential ever travels on the control lane.
+ */
+export interface WorkerModelLoad {
+	targetId: string;
+	modelId: string;
+	/** Other names the server answered for the same model, such as a `:latest` tag. */
+	aliasIds: ReadonlyArray<string>;
+}
+
+/** Bounds on one model load report. */
+export const WORKER_MODEL_LOAD_ID_MAX_CHARS = 256;
+export const WORKER_MODEL_LOAD_ALIAS_MAX = 8;
+
 export type WorkerControlFrame =
 	| { kind: "announce"; attestation: WorkerAttestation }
 	| { kind: "heartbeat" }
 	| { kind: "cancel_ack"; at: number }
-	| { kind: "ledger_post"; body: AgentLedgerBody };
+	| { kind: "ledger_post"; body: AgentLedgerBody }
+	| { kind: "model_loaded"; load: WorkerModelLoad };
 
 function sha256Hex(input: string): string {
 	return createHash("sha256").update(input, "utf8").digest("hex");
@@ -468,6 +497,24 @@ function parseAttestation(value: unknown): FrameParseResult<WorkerAttestation> {
 	};
 }
 
+function isModelLoadId(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0 && value.length <= WORKER_MODEL_LOAD_ID_MAX_CHARS;
+}
+
+function parseModelLoad(value: unknown): FrameParseResult<WorkerModelLoad> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return { ok: false, reason: "model_loaded load is not an object" };
+	}
+	const record = value as Record<string, unknown>;
+	if (!isModelLoadId(record.targetId)) return { ok: false, reason: "model_loaded targetId is missing or too long" };
+	if (!isModelLoadId(record.modelId)) return { ok: false, reason: "model_loaded modelId is missing or too long" };
+	const aliases = record.aliasIds ?? [];
+	if (!Array.isArray(aliases) || aliases.length > WORKER_MODEL_LOAD_ALIAS_MAX || !aliases.every(isModelLoadId)) {
+		return { ok: false, reason: "model_loaded aliasIds must be a short list of model ids" };
+	}
+	return { ok: true, value: { targetId: record.targetId, modelId: record.modelId, aliasIds: [...aliases] } };
+}
+
 /**
  * Parse one marked stderr line into a control frame. The caller has already
  * established that the line carries the marker.
@@ -497,6 +544,11 @@ export function parseControlFrame(line: string): FrameParseResult<WorkerControlF
 			if (!body.ok) return { ok: false, reason: `ledger_post frame rejected: ${body.reason}` };
 			return { ok: true, value: { kind: "ledger_post", body: body.body } };
 		}
+		case "model_loaded": {
+			const load = parseModelLoad(record.load);
+			if (!load.ok) return load;
+			return { ok: true, value: { kind: "model_loaded", load: load.value } };
+		}
 		default:
 			return { ok: false, reason: `unknown control frame kind ${String(record.kind)}` };
 	}
@@ -508,6 +560,7 @@ export function parseControlFrame(line: string): FrameParseResult<WorkerControlF
  * pressure.
  */
 const RECEIPT_BEARING_BULK_TYPES = new Set([
+	"clio_coder_helper_result",
 	"message_end",
 	"clio_coder_run_outcome",
 	"clio_coder_permission_escalated",

package/src/worker/spec-contract.ts

@@ -2,6 +2,7 @@ import { THINKING_LEVELS } from "../core/defaults.js";
 import type { ProtectedModelRef, ResidencyRole } from "../core/residency-protection.js";
 import { assertValidResponseSchema, runtimeSpeaksResponseSchemaDialect } from "../core/response-schema.js";
 import type { ToolName } from "../core/tool-names.js";
+import { snapshotTurnConstraints, type TurnConstraints } from "../core/turn-constraints.js";
 import type { ResultContract } from "../domains/agents/result-contract.js";
 import type { AgentProduct } from "../domains/agents/spec.js";
 import type { WorkerContextSeed } from "../domains/context/worker/contract.js";
@@ -20,6 +21,7 @@ import type { AutonomyLevel } from "../domains/safety/autonomy.js";
 import type { ProtectedArtifact } from "../domains/safety/protected-artifacts.js";
 import type { ToolProfileName } from "../tools/profiles.js";
 import { parseWorkerContextSeed } from "./context-seed.js";
+import { INTERNAL_HELPER_RESULT_KINDS } from "./protocol.js";
 
 /** Current attested, budget-bearing dispatch document emitted by this release. */
 export const WORKER_SPEC_VERSION = 4;
@@ -71,6 +73,7 @@ export interface WorkerBudget {
 }
 
 interface WorkerSpecFields {
+	turnConstraints?: TurnConstraints;
 	/**
 	 * sha256 of the immutable settings snapshot this dispatch was admitted
 	 * under. The worker echoes it in its announcement so the orchestrator can
@@ -104,6 +107,8 @@ interface WorkerSpecFields {
 	 * first and only notice that its result was the wrong shape.
 	 */
 	resultContract?: ResultContract;
+	/** Host-selected internal JSON handoff mode; never a caller-supplied authority grant. */
+	helperResult?: true;
 	/**
 	 * What this run delivers. It widens the reserve window's delivery-tool set,
 	 * so it is validated here like every other closed field on the wire rather
@@ -387,9 +392,15 @@ function validateTarget(value: unknown, runtimeId: string, runtimeAliases: Reado
 		if (cache.deployment !== undefined) {
 			const binding = readRecord(cache.deployment, "WorkerSpec.target.cache.deployment");
 			readString(binding.backend, "WorkerSpec.target.cache.deployment.backend");
-			readOptionalEnum(binding, "backend", "WorkerSpec.target.cache.deployment", ["llamacpp", "vllm"] as const);
-			for (const key of ["controlUrl", "model", "build"])
+			readOptionalEnum(binding, "backend", "WorkerSpec.target.cache.deployment", [
+				"llamacpp",
+				"vllm",
+				"lmstudio",
+			] as const);
+			for (const key of ["controlUrl", "model", "build"]) {
+				if (key === "build" && binding.backend === "lmstudio" && binding[key] === undefined) continue;
 				readString(binding[key], `WorkerSpec.target.cache.deployment.${key}`);
+			}
 			readOptionalString(binding, "gatewayDeploymentId", "WorkerSpec.target.cache.deployment");
 			const url = new URL(readString(binding.controlUrl, "WorkerSpec.target.cache.deployment.controlUrl"));
 			if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash)
@@ -399,6 +410,7 @@ function validateTarget(value: unknown, runtimeId: string, runtimeAliases: Reado
 		}
 		if (cache.warm !== undefined) {
 			const warm = readRecord(cache.warm, "WorkerSpec.target.cache.warm");
+			readOptionalBoolean(warm, "startup", "WorkerSpec.target.cache.warm");
 			for (const key of ["maxInputTokens", "maxDurationMs", "cooldownMs"]) {
 				if (
 					warm[key] !== undefined &&
@@ -678,6 +690,13 @@ export function parseWorkerSpec(value: unknown): WorkerSpec {
 		}
 	}
 	validateAllowedTools(spec.allowedTools);
+	if (spec.helperResult !== undefined) {
+		if (spec.helperResult !== true) throw new Error("WorkerSpec.helperResult must be true when present");
+		const contract = readRecord(spec.resultContract, "WorkerSpec.resultContract");
+		if (!(INTERNAL_HELPER_RESULT_KINDS as readonly unknown[]).includes(contract.kind)) {
+			throw new Error("WorkerSpec.helperResult requires a supported internal JSON result contract");
+		}
+	}
 	validateWorkerBudget(spec.budget);
 	validateProtectedModels(spec.protectedModels);
 	validateRuntimeResolution(spec.runtimeResolution);
@@ -686,6 +705,7 @@ export function parseWorkerSpec(value: unknown): WorkerSpec {
 	if (spec.noSkills !== undefined && typeof spec.noSkills !== "boolean") {
 		throw new Error("WorkerSpec.noSkills must be a boolean");
 	}
+	if (spec.turnConstraints !== undefined) snapshotTurnConstraints(spec.turnConstraints as TurnConstraints);
 	if (spec.skillPaths !== undefined) {
 		readStringArray(spec.skillPaths, "WorkerSpec.skillPaths");
 	}