@dougbots/avenor-core 0.9.0 → 0.10.1

package/dist/index.js

@@ -6,6 +6,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
+import { umpire } from "@umpire/core";
+import { fromJson } from "@umpire/json";
 //#region src/client.ts
 function normalizeSubscribeOptions(options) {
 	if (!options) return void 0;
@@ -280,6 +282,107 @@ var Client = class {
 		const params = runtimeId ? { runtime_id: runtimeId } : void 0;
 		await this.call("cancel", params);
 	}
+	async workflowStatus(workflowId) {
+		return this.call("workflow.status", { workflow_id: workflowId });
+	}
+	async workflowWait(workflowId, timeoutMs) {
+		const params = { workflow_id: workflowId };
+		if (timeoutMs !== void 0) params.timeout_ms = timeoutMs;
+		return this.call("workflow.wait", params);
+	}
+	async workflowInspect(workflowId) {
+		return this.call("workflow.inspect", { workflow_id: workflowId });
+	}
+	async workflowEvents(workflowId, opts) {
+		const params = { workflow_id: workflowId };
+		if (opts?.afterSeq !== void 0) params.after_seq = opts.afterSeq;
+		if (opts?.limit !== void 0) params.limit = opts.limit;
+		return this.call("workflow.events", params);
+	}
+	async workflowCommand(workflowId, command) {
+		return this.call("workflow.command", {
+			workflow_id: workflowId,
+			command
+		});
+	}
+	async workflowComplete(params) {
+		const command = {
+			op: "complete",
+			node_id: params.node_id,
+			activation_id: params.activation_id,
+			attempt_id: params.attempt_id,
+			lease_id: params.lease_id,
+			owner_token: params.owner_token,
+			outcome: params.outcome
+		};
+		if (params.outputs !== void 0) command.outputs = params.outputs;
+		if (params.artifacts !== void 0) command.artifacts = params.artifacts;
+		return this.workflowCommand(params.workflow_id, command);
+	}
+	async workflowGate(params) {
+		const command = {
+			op: "gate",
+			node_id: params.node_id,
+			activation_id: params.activation_id,
+			gate_id: params.gate_id,
+			operation: params.operation
+		};
+		const optional = [
+			["actor", params.actor],
+			["reason", params.reason],
+			["outcome", params.outcome],
+			["subject", params.subject],
+			["poll_id", params.poll_id],
+			["source", params.source],
+			["result", params.result],
+			["response_hash", params.response_hash],
+			["observed_at", params.observed_at],
+			["evidence_ids", params.evidence_ids]
+		];
+		for (const [key, value] of optional) if (value !== void 0) command[key] = value;
+		return this.workflowCommand(params.workflow_id, command);
+	}
+	async workflowHeartbeat(params) {
+		const command = {
+			op: "heartbeat",
+			node_id: params.node_id,
+			lease_id: params.lease_id,
+			owner_token: params.owner_token
+		};
+		if (params.activation_id !== void 0) command.activation_id = params.activation_id;
+		return this.workflowCommand(params.workflow_id, command);
+	}
+	async brokerSend(fromRunId, toRunId, message, role) {
+		await this.call("broker_send", {
+			from_run_id: fromRunId,
+			to_run_id: toRunId,
+			message,
+			role: role ?? "agent"
+		});
+	}
+	async brokerAsk(toRunId, message, role) {
+		return await this.call("broker_ask", {
+			to_run_id: toRunId,
+			message,
+			role: role ?? "agent"
+		});
+	}
+	async brokerPeers() {
+		return (await this.call("broker_peers")).sessions ?? [];
+	}
+	async brokerCancel(messageId) {
+		await this.call("broker_cancel", { message_id: messageId });
+	}
+	async brokerReceive() {
+		return await this.call("broker_receive");
+	}
+	async brokerReply(toRunId, replyTo, message) {
+		await this.call("broker_reply", {
+			to_run_id: toRunId,
+			reply_to: replyTo,
+			message
+		});
+	}
 	isClosed() {
 		return this.closed || this.socket.destroyed || this.socket.writableEnded;
 	}
@@ -1074,6 +1177,95 @@ function observeRun(client, options = {}) {
 	};
 }
 //#endregion
+//#region ../../schemas/spawn_selection.umpire.json
+var spawn_selection_umpire_default = {
+	version: 1,
+	conditions: { "rosterConfigured": {
+		"type": "boolean",
+		"description": "Whether the caller has a configured roster context"
+	} },
+	fields: {
+		"agent": { "isEmpty": "string" },
+		"model": { "isEmpty": "string" },
+		"backend": { "isEmpty": "string" },
+		"roster_file": { "isEmpty": "string" },
+		"roster_entry": { "isEmpty": "string" }
+	},
+	rules: [
+		{
+			"type": "requires",
+			"field": "roster_file",
+			"dependency": "roster_entry",
+			"reason": "roster_file requires roster_entry"
+		},
+		{
+			"type": "fairWhen",
+			"field": "roster_entry",
+			"when": {
+				"op": "or",
+				"exprs": [{
+					"op": "present",
+					"field": "roster_file"
+				}, {
+					"op": "cond",
+					"condition": "rosterConfigured"
+				}]
+			},
+			"reason": "roster_entry requires roster_file unless a roster context is configured"
+		},
+		{
+			"type": "disables",
+			"source": "roster_entry",
+			"targets": [
+				"agent",
+				"model",
+				"backend"
+			],
+			"reason": "direct identity fields are disabled in roster mode"
+		}
+	]
+};
+//#endregion
+//#region src/spawn-selection.ts
+const selectorFields = [
+	"agent",
+	"model",
+	"backend",
+	"roster_file",
+	"roster_entry"
+];
+const selectorFieldSet = new Set(selectorFields);
+const parsedSchema = fromJson(spawn_selection_umpire_default);
+const spawnSelectionUmpire = umpire({
+	fields: parsedSchema.fields,
+	rules: parsedSchema.rules
+});
+function assertInput(input) {
+	if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error("invalid spawn selector: expected an object");
+	for (const key of Object.keys(input)) {
+		if (!selectorFieldSet.has(key)) throw new Error(`invalid spawn selector: unknown field "${key}"`);
+		const value = input[key];
+		if (value !== void 0 && typeof value !== "string") throw new Error(`invalid spawn selector: ${key} must be a string`);
+	}
+}
+/** Validate the direct-versus-roster selector contract. */
+function validateSpawnSelection(input, rosterConfigured = false) {
+	assertInput(input);
+	if (typeof rosterConfigured !== "boolean") throw new Error("invalid spawn selector: rosterConfigured must be a boolean");
+	const values = {};
+	for (const field of selectorFields) {
+		const value = input[field];
+		if (value !== void 0 && value !== "") values[field] = value;
+	}
+	const availability = spawnSelectionUmpire.check(values, { rosterConfigured });
+	for (const field of selectorFields) {
+		const value = values[field];
+		const status = availability[field];
+		if (value === void 0 || status?.enabled && status.fair) continue;
+		throw new Error(`invalid spawn selector: ${status?.reason ?? `${field} is disabled`}`);
+	}
+}
+//#endregion
 //#region src/paths.ts
 function avenorHome() {
 	return process.env.AVENOR_HOME || path.join(os.homedir(), ".avenor");
@@ -1098,6 +1290,37 @@ function ensureRunPaths(runId) {
 }
 //#endregion
 //#region src/supervisor.ts
+function retainLiveIdentity(runInfo, liveStatus) {
+	const value = (candidate) => typeof candidate === "string" && candidate.length > 0 ? candidate : void 0;
+	const liveIdentity = (effectiveKey, directKey) => {
+		if (typeof liveStatus[effectiveKey] === "string") return {
+			present: true,
+			value: value(liveStatus[effectiveKey])
+		};
+		if (typeof liveStatus[directKey] === "string") return {
+			present: true,
+			value: value(liveStatus[directKey])
+		};
+		return { present: false };
+	};
+	const effectiveAgent = liveIdentity("effective_agent", "agent");
+	const effectiveModel = liveIdentity("effective_model", "model");
+	const effectiveBackend = liveIdentity("effective_backend", "backend");
+	const sessionId = value(liveStatus.session_id);
+	const rosterFilePresent = typeof liveStatus.roster_file === "string";
+	const rosterFile = value(liveStatus.roster_file);
+	const rosterEntryPresent = typeof liveStatus.roster_entry === "string";
+	const rosterEntry = value(liveStatus.roster_entry);
+	const agentProfilePresent = typeof liveStatus.agent_profile === "string";
+	const agentProfile = value(liveStatus.agent_profile);
+	if (effectiveAgent.present) runInfo.agent = runInfo.effectiveAgent = effectiveAgent.value;
+	if (effectiveModel.present) runInfo.model = runInfo.effectiveModel = effectiveModel.value;
+	if (effectiveBackend.present) runInfo.backend = runInfo.effectiveBackend = effectiveBackend.value;
+	if (sessionId) runInfo.sessionId = sessionId;
+	if (rosterFilePresent) runInfo.rosterFile = rosterFile;
+	if (rosterEntryPresent) runInfo.rosterEntry = rosterEntry;
+	if (agentProfilePresent) runInfo.agentProfile = agentProfile;
+}
 function findAvenorBinary() {
 	const envBin = process.env.AVENOR_BIN;
 	if (envBin) try {
@@ -1154,6 +1377,7 @@ var Supervisor = class Supervisor {
 	crashed = false;
 	crashCode = null;
 	runs = /* @__PURE__ */ new Map();
+	aliases = /* @__PURE__ */ new Map();
 	binaryPath;
 	callTimeoutMs;
 	constructor(binaryPath, socketPath, opts) {
@@ -1292,7 +1516,14 @@ var Supervisor = class Supervisor {
 		}
 		return this.client;
 	}
-	async spawn(params, runId = crypto.randomUUID()) {
+	async spawn(params, runId = crypto.randomUUID(), metadata) {
+		if (!(typeof params.loop_file === "string" || typeof params.team_file === "string")) validateSpawnSelection({
+			agent: params.agent,
+			model: params.model,
+			backend: params.backend,
+			roster_file: params.roster_file,
+			roster_entry: params.roster_entry
+		});
 		const client = this.getClient();
 		const { sentinelPath, eventLogPath } = ensureRunPaths(runId);
 		const spawnParams = {
@@ -1301,26 +1532,60 @@ var Supervisor = class Supervisor {
 			sentinel_file: sentinelPath,
 			on_event: eventLogPath
 		};
+		if (spawnParams.roster_entry) {
+			for (const field of [
+				"agent",
+				"model",
+				"backend"
+			]) if (spawnParams[field] === "") delete spawnParams[field];
+		}
 		const result = await client.spawn(spawnParams);
+		let identityResult = result;
+		if (spawnParams.roster_entry && result.runtime_id) {
+			const hasBackend = [result.effective_backend, result.backend].some((value) => typeof value === "string" && value.length > 0);
+			const hasAgentOrModel = [
+				result.effective_agent,
+				result.agent,
+				result.effective_model,
+				result.model
+			].some((value) => typeof value === "string" && value.length > 0);
+			if (!(hasBackend && hasAgentOrModel)) try {
+				identityResult = {
+					...result,
+					...await client.status(result.runtime_id)
+				};
+			} catch {}
+		}
+		const value = (candidate) => typeof candidate === "string" && candidate.length > 0 ? candidate : void 0;
+		const effectiveAgent = metadata?.effectiveAgent ?? value(identityResult.effective_agent) ?? value(identityResult.agent) ?? value(spawnParams.agent);
+		const effectiveModel = metadata?.effectiveModel ?? value(identityResult.effective_model) ?? value(identityResult.model) ?? value(spawnParams.model);
+		const effectiveBackend = metadata?.effectiveBackend ?? value(identityResult.effective_backend) ?? value(identityResult.backend) ?? value(spawnParams.backend);
+		const rosterFile = metadata?.rosterFile ?? value(identityResult.roster_file) ?? value(spawnParams.roster_file);
+		const rosterEntry = metadata?.rosterEntry ?? value(identityResult.roster_entry) ?? value(spawnParams.roster_entry);
 		const runInfo = {
 			runId,
 			label: spawnParams.label ?? runId,
 			sentinelPath: result.sentinel_file ?? sentinelPath,
 			eventLogPath: result.on_event ?? eventLogPath,
-			runtimeId: result.runtime_id,
-			sessionId: result.session_id,
-			agent: spawnParams.agent ?? params.agent,
-			agentProfile: spawnParams.agent_profile,
-			backend: spawnParams.backend,
-			model: spawnParams.model,
+			runtimeId: value(identityResult.runtime_id),
+			sessionId: value(identityResult.session_id),
+			agent: effectiveAgent,
+			agentProfile: value(identityResult.agent_profile) ?? spawnParams.agent_profile,
+			backend: effectiveBackend,
+			model: effectiveModel,
+			effectiveAgent,
+			effectiveModel,
+			effectiveBackend,
+			rosterFile,
+			rosterEntry,
 			thinking: spawnParams.thinking,
 			dir: spawnParams.dir,
 			brokerUrl: result.broker_url,
 			parentToken: result.parent_token,
 			autoApprove: spawnParams.auto_approve
 		};
-		this.runs.set(runInfo.label, runInfo);
 		this.runs.set(runId, runInfo);
+		this.aliases.set(runInfo.label, runInfo);
 		return runInfo;
 	}
 	async close(options = {}) {
@@ -1343,6 +1608,7 @@ var Supervisor = class Supervisor {
 		this.crashed = false;
 		this.crashCode = null;
 		this.runs.clear();
+		this.aliases.clear();
 		Supervisor.instance = null;
 	}
 };
@@ -1369,6 +1635,9 @@ function validateSupervisorSocketPath(supervisorId) {
 	if (parent !== root || !/^avenor-mcp-[^/\\]+\.sock$/.test(basename)) throw new Error(`invalid supervisorId: ${supervisorId}`);
 	return path.join(parent, basename);
 }
+function validateObservedAt(observedAt) {
+	if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(observedAt)) throw new Error("observed_at must be an RFC3339 timestamp");
+}
 //#endregion
 //#region src/tools/get-supervisor-client.ts
 async function getSupervisorClient(supervisorId) {
@@ -1388,8 +1657,125 @@ async function getSupervisorClient(supervisorId) {
 	};
 }
 //#endregion
+//#region src/tools/run-registry.ts
+const externalRuns = /* @__PURE__ */ new Map();
+function runsFor(supervisorId) {
+	let runs = externalRuns.get(supervisorId);
+	if (!runs) {
+		runs = {
+			byRunId: /* @__PURE__ */ new Map(),
+			byAlias: /* @__PURE__ */ new Map()
+		};
+		externalRuns.set(supervisorId, runs);
+	}
+	return runs;
+}
+function indexRun(runInfo) {
+	const runs = runsFor(runInfo.supervisorId);
+	runs.byRunId.set(runInfo.runId, runInfo);
+	runs.byAlias.set(runInfo.label, runInfo);
+	if (runInfo.runtimeId) runs.byAlias.set(runInfo.runtimeId, runInfo);
+}
+function isSafeRunReference(reference) {
+	return /^[a-zA-Z0-9_-]+$/.test(reference);
+}
+function externalRunMetadataPath(runId) {
+	if (!isSafeRunReference(runId)) throw new Error(`unsafe external run reference: ${runId}`);
+	return path.join(runsRoot(), runId, "run.json");
+}
+function optionalString(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function readPersistedRun(supervisorId, runId) {
+	if (!isSafeRunReference(runId)) return void 0;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(externalRunMetadataPath(runId), "utf-8"));
+		if (parsed.schemaVersion !== 1 || parsed.runId !== runId || parsed.supervisorId !== supervisorId || typeof parsed.label !== "string") return;
+		const runDir = path.join(runsRoot(), runId);
+		const runInfo = {
+			runId,
+			label: parsed.label,
+			supervisorId,
+			sentinelPath: path.join(runDir, "sentinel.done"),
+			eventLogPath: path.join(runDir, "events.log"),
+			runtimeId: optionalString(parsed.runtimeId),
+			sessionId: optionalString(parsed.sessionId),
+			agent: optionalString(parsed.agent),
+			agentProfile: optionalString(parsed.agentProfile),
+			backend: optionalString(parsed.backend),
+			model: optionalString(parsed.model),
+			effectiveAgent: optionalString(parsed.effectiveAgent),
+			effectiveModel: optionalString(parsed.effectiveModel),
+			effectiveBackend: optionalString(parsed.effectiveBackend),
+			rosterFile: optionalString(parsed.rosterFile),
+			rosterEntry: optionalString(parsed.rosterEntry),
+			thinking: parsed.thinking,
+			dir: optionalString(parsed.dir),
+			brokerUrl: optionalString(parsed.brokerUrl),
+			parentToken: optionalString(parsed.parentToken),
+			autoApprove: typeof parsed.autoApprove === "boolean" ? parsed.autoApprove : void 0
+		};
+		indexRun(runInfo);
+		return runInfo;
+	} catch {
+		return;
+	}
+}
+/** Persist the public-to-runtime identity for runs spawned through an external supervisor. */
+function registerExternalRun(runInfo) {
+	const persisted = {
+		schemaVersion: 1,
+		...runInfo,
+		parentToken: void 0
+	};
+	const metadataPath = externalRunMetadataPath(runInfo.runId);
+	const temporaryPath = `${metadataPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+	fs.writeFileSync(temporaryPath, `${JSON.stringify(persisted, null, 2)}\n`, {
+		mode: 384,
+		flag: "wx"
+	});
+	try {
+		fs.renameSync(temporaryPath, metadataPath);
+	} catch (error) {
+		try {
+			fs.unlinkSync(temporaryPath);
+		} catch {}
+		throw error;
+	}
+	indexRun(runInfo);
+}
+function findExternalRun(supervisorId, reference) {
+	const exact = externalRuns.get(supervisorId)?.byRunId.get(reference);
+	if (exact) return exact;
+	const persisted = readPersistedRun(supervisorId, reference);
+	if (persisted) return persisted;
+	listExternalRuns(supervisorId);
+	return externalRuns.get(supervisorId)?.byAlias.get(reference);
+}
+function listExternalRuns(supervisorId) {
+	try {
+		for (const entry of fs.readdirSync(runsRoot(), { withFileTypes: true })) if (entry.isDirectory()) readPersistedRun(supervisorId, entry.name);
+	} catch {}
+	return [...externalRuns.get(supervisorId)?.byRunId.values() ?? []];
+}
+function forgetExternalRuns(supervisorId) {
+	externalRuns.delete(supervisorId);
+}
+function clearExternalRuns(supervisorId) {
+	const runs = listExternalRuns(supervisorId);
+	forgetExternalRuns(supervisorId);
+	return runs;
+}
+//#endregion
 //#region src/tools/spawn.ts
-async function spawnTool(args) {
+async function executeSpawnTool(args, getSupervisorClient) {
+	validateSpawnSelection({
+		agent: args.agent,
+		model: args.model,
+		backend: args.backend,
+		roster_file: args.rosterFile,
+		roster_entry: args.rosterEntry
+	});
 	const runId = crypto.randomUUID();
 	const label = args.label ?? runId;
 	const baseParams = {
@@ -1405,10 +1791,23 @@ async function spawnTool(args) {
 		session_id: args.sessionId,
 		parent_run_id: args.parent_run_id
 	};
+	if (args.rosterFile) baseParams.roster_file = args.rosterFile;
+	if (args.rosterEntry) baseParams.roster_entry = args.rosterEntry;
 	if (args.agent) baseParams.agent = args.agent;
 	if (args.thinking !== void 0) baseParams.thinking = args.thinking;
 	if (args.supervisorId) {
-		const { client, isSingleton, supervisorId } = await getSupervisorClient(args.supervisorId);
+		const { client, isSingleton, sup, supervisorId } = await getSupervisorClient(args.supervisorId);
+		if (isSingleton && sup) {
+			const runInfo = await sup.spawn(baseParams, runId);
+			return {
+				run_id: runInfo.runId,
+				label: runInfo.label,
+				supervisor_id: supervisorId,
+				runtime_id: runInfo.runtimeId,
+				broker_url: runInfo.brokerUrl,
+				parent_token: runInfo.parentToken
+			};
+		}
 		const { sentinelPath, eventLogPath } = ensureRunPaths(runId);
 		try {
 			const result = await client.spawn({
@@ -1416,13 +1815,37 @@ async function spawnTool(args) {
 				sentinel_file: sentinelPath,
 				on_event: eventLogPath
 			});
+			const stringValue = (candidate) => typeof candidate === "string" && candidate.length > 0 ? candidate : void 0;
+			const runtimeId = stringValue(result.runtime_id);
+			registerExternalRun({
+				runId,
+				label,
+				supervisorId,
+				sentinelPath,
+				eventLogPath,
+				runtimeId,
+				sessionId: stringValue(result.session_id),
+				agent: stringValue(result.effective_agent) ?? stringValue(result.agent) ?? baseParams.agent,
+				model: stringValue(result.effective_model) ?? stringValue(result.model) ?? baseParams.model,
+				backend: stringValue(result.effective_backend) ?? stringValue(result.backend) ?? baseParams.backend,
+				effectiveAgent: stringValue(result.effective_agent) ?? stringValue(result.agent) ?? baseParams.agent,
+				effectiveModel: stringValue(result.effective_model) ?? stringValue(result.model) ?? baseParams.model,
+				effectiveBackend: stringValue(result.effective_backend) ?? stringValue(result.backend) ?? baseParams.backend,
+				agentProfile: stringValue(result.agent_profile) ?? baseParams.agent_profile,
+				rosterFile: stringValue(result.roster_file) ?? baseParams.roster_file,
+				rosterEntry: stringValue(result.roster_entry) ?? baseParams.roster_entry,
+				thinking: baseParams.thinking,
+				dir: baseParams.dir,
+				brokerUrl: stringValue(result.broker_url),
+				parentToken: stringValue(result.parent_token)
+			});
 			return {
-				run_id: result.runtime_id ?? runId,
+				run_id: runId,
 				label,
 				supervisor_id: supervisorId,
-				runtime_id: result.runtime_id,
-				broker_url: result.broker_url,
-				parent_token: result.parent_token
+				runtime_id: runtimeId,
+				broker_url: stringValue(result.broker_url),
+				parent_token: stringValue(result.parent_token)
 			};
 		} finally {
 			if (!isSingleton) client.close();
@@ -1439,14 +1862,251 @@ async function spawnTool(args) {
 		parent_token: runInfo.parentToken
 	};
 }
+function createSpawnTool(getSupervisorClient) {
+	return (args) => executeSpawnTool(args, getSupervisorClient);
+}
+const spawnTool = createSpawnTool(getSupervisorClient);
 //#endregion
-//#region src/tools/status.ts
-function findRunByLabel$3(sup, runId) {
-	const runs = sup.runs;
-	const byKey = runs.get(runId);
-	if (byKey) return byKey;
-	for (const info of runs.values()) if (info.label === runId) return info;
+//#region ../../schemas/thinking_policy.umpire.json
+var thinking_policy_umpire_default = {
+	version: 1,
+	conditions: {
+		"backend": {
+			"type": "string",
+			"description": "Backend identifier (e.g. codex-app-server, pi, claude)."
+		},
+		"resume": {
+			"type": "boolean",
+			"description": "Whether the value is being applied on an explicit resume rather than a fresh start."
+		}
+	},
+	fields: { "thinking": {
+		"isEmpty": "string",
+		"description": "Canonical thinking level, or empty to use the backend default."
+	} },
+	rules: [{
+		"type": "check",
+		"field": "thinking",
+		"check": {
+			"op": "in",
+			"field": "thinking",
+			"value": [
+				"off",
+				"minimal",
+				"low",
+				"medium",
+				"high",
+				"xhigh",
+				"max"
+			]
+		},
+		"reason": "not a canonical thinking value (off, minimal, low, medium, high, xhigh, max)"
+	}, {
+		"type": "eitherOf",
+		"group": "thinkingPolicy",
+		"field": "thinking",
+		"branches": {
+			"empty": [{
+				"type": "fairWhen",
+				"field": "thinking",
+				"when": {
+					"op": "absent",
+					"field": "thinking"
+				},
+				"reason": "thinking is empty (backend default)"
+			}],
+			"fullSupport": [{
+				"type": "fairWhen",
+				"field": "thinking",
+				"when": {
+					"op": "and",
+					"exprs": [{
+						"op": "condIn",
+						"condition": "backend",
+						"values": ["codex-app-server", "pi"]
+					}, {
+						"op": "in",
+						"field": "thinking",
+						"values": [
+							"off",
+							"minimal",
+							"low",
+							"medium",
+							"high",
+							"xhigh",
+							"max"
+						]
+					}]
+				},
+				"reason": "codex-app-server and pi support all canonical thinking values on start and resume"
+			}],
+			"claudeStart": [{
+				"type": "fairWhen",
+				"field": "thinking",
+				"when": {
+					"op": "and",
+					"exprs": [
+						{
+							"op": "condIn",
+							"condition": "backend",
+							"values": ["claude", "claude-channel"]
+						},
+						{
+							"op": "condEq",
+							"condition": "resume",
+							"value": false
+						},
+						{
+							"op": "in",
+							"field": "thinking",
+							"values": [
+								"low",
+								"medium",
+								"high",
+								"xhigh",
+								"max"
+							]
+						}
+					]
+				},
+				"reason": "claude and claude-channel support low through max only on a new session"
+			}]
+		}
+	}]
+};
+//#endregion
+//#region src/thinking-policy.ts
+/**
+* Portable thinking-policy contract.
+*
+* THINKING_LEVELS is the single TypeScript source for the canonical tuple and
+* is exported for hosts (MCP, OpenCode, Pi) to derive their enums from. It is
+* verified against schemas/thinking_policy.umpire.json and the Go tuple by
+* introspection and conformance tests so all languages agree.
+*
+* The backend policy (which canonical values each backend supports, on start
+* vs. explicit resume) is modelled directly in the Umpire schema's eitherOf
+* branches with fairWhen rules and conditions (backend, resume). Both Go and
+* TypeScript derive the policy from the schema, eliminating hand-written
+* policy tables that could drift apart.
+*/
+const THINKING_LEVELS = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+];
+function isThinkingLevel(value) {
+	return THINKING_LEVELS.includes(value);
+}
+/** Accepts an empty value (backend default) or a canonical thinking level. */
+function validateThinking(value) {
+	if (value === void 0 || value === "") return;
+	if (typeof value !== "string" || !isThinkingLevel(value)) throw new Error(`invalid thinking value ${JSON.stringify(value)} (allowed: ${THINKING_LEVELS.join(", ")})`);
+}
+const thinkingSchema = thinking_policy_umpire_default;
+thinkingSchema.rules.find((r) => r.check?.op === "in")?.check?.value;
+const policyBranches = (() => {
+	const eitherOf = thinkingSchema.rules.find((r) => r.type === "eitherOf");
+	if (!eitherOf?.branches) return [];
+	const branches = [];
+	for (const branchRules of Object.values(eitherOf.branches)) for (const rule of branchRules) if (rule.type === "fairWhen") branches.push({
+		when: rule.when,
+		reason: rule.reason
+	});
+	return branches;
+})();
+const supportedBackends = (() => {
+	const backends = /* @__PURE__ */ new Set();
+	for (const branch of policyBranches) collectBackends(branch.when, backends);
+	return backends;
+})();
+function collectBackends(expr, backends) {
+	if (expr.op === "condIn" && expr.condition === "backend") {
+		for (const v of expr.values) backends.add(v);
+		return;
+	}
+	if (expr.op === "and" || expr.op === "or") for (const sub of expr.exprs) collectBackends(sub, backends);
+}
+function evalExpr(expr, value, backend, resume) {
+	switch (expr.op) {
+		case "absent": return value === "";
+		case "in": return expr.values.includes(value);
+		case "condIn": return expr.condition === "backend" && expr.values.includes(backend);
+		case "condEq":
+			if (expr.condition === "backend") return backend === expr.value;
+			if (expr.condition === "resume") return resume === expr.value;
+			return false;
+		case "and": return expr.exprs.every((e) => evalExpr(e, value, backend, resume));
+		case "or": return expr.exprs.some((e) => evalExpr(e, value, backend, resume));
+		default: return false;
+	}
+}
+/** Evaluates the schema-derived backend policy for a (backend, value, resume) combination. */
+function evaluateThinkingPolicy(backend, value, resume = false) {
+	if (value === "") return "ok";
+	if (policyBranches.some((b) => evalExpr(b.when, value, backend, resume))) return "ok";
+	if (!supportedBackends.has(backend)) return "unsupportedCapability";
+	if (resume) {
+		if (policyBranches.some((b) => evalExpr(b.when, value, backend, false))) return "startOnly";
+	}
+	return "unsupportedValue";
+}
+/** Returns the canonical values supported by backend on a fresh start. */
+function startValues(backend) {
+	if (!supportedBackends.has(backend)) return [];
+	return THINKING_LEVELS.filter((v) => policyBranches.some((b) => evalExpr(b.when, v, backend, false)));
+}
+/** Returns the canonical values supported by backend on an explicit resume. */
+function resumeValues(backend) {
+	if (!supportedBackends.has(backend)) return [];
+	return THINKING_LEVELS.filter((v) => policyBranches.some((b) => evalExpr(b.when, v, backend, true)));
+}
+/** Accepts a value iff it is valid under the static backend policy (start). */
+function validateThinkingForBackend(backend, value) {
+	validateThinking(value);
+	const v = value === void 0 ? "" : String(value);
+	if (v === "") return;
+	const outcome = evaluateThinkingPolicy(backend, v, false);
+	if (outcome === "ok") return;
+	if (outcome === "unsupportedValue") {
+		const allowed = startValues(backend).join(", ");
+		throw new Error(`backend ${JSON.stringify(backend)} does not support thinking value ${JSON.stringify(v)} (allowed: ${allowed})`);
+	}
+	throw new Error(`backend ${JSON.stringify(backend)} does not support parameter "thinking"`);
+}
+/** Accepts a value iff it is valid on an explicit resume for the backend. */
+function validateThinkingForBackendResume(backend, value) {
+	validateThinking(value);
+	const v = value === void 0 ? "" : String(value);
+	if (v === "") return;
+	const outcome = evaluateThinkingPolicy(backend, v, true);
+	if (outcome === "ok") return;
+	if (outcome === "startOnly") throw new Error(`backend ${JSON.stringify(backend)} supports parameter "thinking" only when starting a session`);
+	if (outcome === "unsupportedValue") {
+		const allowed = resumeValues(backend).join(", ");
+		throw new Error(`backend ${JSON.stringify(backend)} does not support thinking value ${JSON.stringify(v)} (allowed: ${allowed})`);
+	}
+	throw new Error(`backend ${JSON.stringify(backend)} does not support parameter "thinking"`);
 }
+//#endregion
+//#region src/tools/run-resolution.ts
+/** Resolve a local public run ID before considering a label alias. */
+function findLocalRunByReference(sup, reference) {
+	const { runs, aliases } = sup;
+	return runs.get(reference) ?? aliases.get(reference);
+}
+/** Match a supervisor list entry to its stored runtime identity. */
+function findLocalRunByRuntimeId(sup, runtimeId) {
+	if (!runtimeId) return void 0;
+	const { runs } = sup;
+	for (const runInfo of runs.values()) if (runInfo.runtimeId === runtimeId) return runInfo;
+}
+//#endregion
+//#region src/tools/status.ts
 async function parseSentinel$1(filePath) {
 	try {
 		const content = (await fs.promises.readFile(filePath, "utf-8")).trim();
@@ -1534,6 +2194,15 @@ function extractPendingPermission(liveStatus) {
 	return normalizePermission(asRecord(pendingPermission));
 }
 function buildBaseStatus(source, fallback, translatedStatus) {
+	const identity = fallback.identity;
+	const authoritativeValue = (effectiveKey, directKey, fallbackEffective, fallbackDirect) => {
+		if (typeof source[effectiveKey] === "string") return stringField(source, effectiveKey);
+		if (typeof source[directKey] === "string") return stringField(source, directKey);
+		return fallbackEffective ?? fallbackDirect;
+	};
+	const effectiveAgent = authoritativeValue("effective_agent", "agent", identity?.effective_agent, identity?.agent);
+	const effectiveModel = authoritativeValue("effective_model", "model", identity?.effective_model, identity?.model);
+	const effectiveBackend = authoritativeValue("effective_backend", "backend", identity?.effective_backend, identity?.backend);
 	return {
 		run_id: fallback.prefer_fallback_run_id ? fallback.run_id : stringField(source, "run_id") ?? fallback.run_id,
 		label: stringField(source, "label") ?? fallback.label,
@@ -1544,9 +2213,15 @@ function buildBaseStatus(source, fallback, translatedStatus) {
 		pending_permission: extractPendingPermission(source),
 		session_id: stringField(source, "session_id") ?? fallback.session_id,
 		stop_reason: stringField(source, "stop_reason") ?? fallback.stop_reason,
-		backend: stringField(source, "backend"),
-		agent: stringField(source, "agent"),
-		model: stringField(source, "model"),
+		roster_file: typeof source.roster_file === "string" ? stringField(source, "roster_file") : identity?.roster_file,
+		roster_entry: typeof source.roster_entry === "string" ? stringField(source, "roster_entry") : identity?.roster_entry,
+		backend: effectiveBackend,
+		agent: effectiveAgent,
+		model: effectiveModel,
+		agent_profile: typeof source.agent_profile === "string" ? stringField(source, "agent_profile") : identity?.agent_profile,
+		effective_backend: effectiveBackend,
+		effective_agent: effectiveAgent,
+		effective_model: effectiveModel,
 		dir: stringField(source, "dir"),
 		parent_id: stringField(source, "parent_id", "parentId"),
 		children: stringArrayField(source, "children"),
@@ -1573,6 +2248,7 @@ function shapeStatusResult(result, view = "full") {
 	};
 }
 async function buildRunStatus(runInfo, liveStatus) {
+	if (liveStatus) retainLiveIdentity(runInfo, liveStatus);
 	let sentinel = null;
 	if (await sentinelExists(runInfo.sentinelPath)) sentinel = await parseSentinel$1(runInfo.sentinelPath);
 	const translated = translateStatus(rawStatusPhase(liveStatus), sentinel);
@@ -1582,7 +2258,18 @@ async function buildRunStatus(runInfo, liveStatus) {
 		prefer_fallback_run_id: true,
 		runtime_id: runInfo.runtimeId,
 		session_id: sentinel?.SESSION ?? liveStatus?.session_id ?? runInfo.sessionId,
-		stop_reason: sentinel?._status
+		stop_reason: sentinel?.STOP_REASON,
+		identity: {
+			roster_file: runInfo.rosterFile,
+			roster_entry: runInfo.rosterEntry,
+			agent: runInfo.agent,
+			model: runInfo.model,
+			backend: runInfo.backend,
+			agent_profile: runInfo.agentProfile,
+			effective_agent: runInfo.effectiveAgent,
+			effective_model: runInfo.effectiveModel,
+			effective_backend: runInfo.effectiveBackend
+		}
 	}, translated);
 }
 async function queryLiveStatus(client, runtimeId) {
@@ -1595,11 +2282,11 @@ async function queryLiveStatus(client, runtimeId) {
 }
 async function executeStatusTool(args, getSupervisorClient) {
 	if (args.supervisorId) {
-		const { client, isSingleton, sup } = await getSupervisorClient(args.supervisorId);
+		const { client, isSingleton, sup, supervisorId } = await getSupervisorClient(args.supervisorId);
 		try {
 			if (args.runId) {
 				validateRunId(args.runId);
-				const runInfo = isSingleton && sup ? findRunByLabel$3(sup, args.runId) : void 0;
+				const runInfo = isSingleton && sup ? findLocalRunByReference(sup, args.runId) : findExternalRun(supervisorId, args.runId);
 				if (runInfo) return shapeStatusResult(await buildRunStatus(runInfo, await queryLiveStatus(client, runInfo.runtimeId)), args.view);
 				let liveStatus = await queryLiveStatus(client, args.runId);
 				if (!liveStatus) try {
@@ -1617,17 +2304,30 @@ async function executeStatusTool(args, getSupervisorClient) {
 				return shapeStatusResult(buildBaseStatus(liveStatus ?? {}, {
 					run_id: args.runId,
 					label: args.runId,
+					prefer_fallback_run_id: true,
 					runtime_id: stringField(liveStatus ?? {}, "runtime_id", "id"),
 					session_id: sentinel?.SESSION ?? liveStatus?.session_id,
-					stop_reason: sentinel?._status
+					stop_reason: sentinel?.STOP_REASON
 				}, translateStatus(rawStatusPhase(liveStatus), sentinel)), args.view);
 			}
-			return (await client.list()).map((entry) => shapeStatusResult(buildBaseStatus(entry, {
-				run_id: String(entry.run_id ?? entry.runtime_id ?? entry.id ?? ""),
-				label: String(entry.label ?? entry.runtime_id ?? entry.id ?? ""),
-				runtime_id: String(entry.runtime_id ?? entry.id ?? ""),
-				session_id: entry.session_id
-			}, translateStatus(rawStatusPhase(entry), null)), args.view));
+			const list = await client.list();
+			if (!isSingleton) listExternalRuns(supervisorId);
+			const results = [];
+			for (const entry of list) {
+				const entryId = String(entry.runtime_id ?? entry.id ?? "");
+				const runInfo = !isSingleton ? findExternalRun(supervisorId, entryId) ?? findExternalRun(supervisorId, String(entry.run_id ?? "")) ?? findExternalRun(supervisorId, String(entry.label ?? "")) : void 0;
+				if (runInfo) {
+					results.push(shapeStatusResult(await buildRunStatus(runInfo, entry), args.view));
+					continue;
+				}
+				results.push(shapeStatusResult(buildBaseStatus(entry, {
+					run_id: String(entry.run_id ?? entryId),
+					label: String(entry.label ?? entryId),
+					runtime_id: entryId,
+					session_id: entry.session_id
+				}, translateStatus(rawStatusPhase(entry), null)), args.view));
+			}
+			return results;
 		} finally {
 			if (!isSingleton) client.close();
 		}
@@ -1635,7 +2335,7 @@ async function executeStatusTool(args, getSupervisorClient) {
 	const sup = await Supervisor.get();
 	const client = sup.getClient();
 	if (args.runId) {
-		const runInfo = findRunByLabel$3(sup, args.runId);
+		const runInfo = findLocalRunByReference(sup, args.runId);
 		if (runInfo) return shapeStatusResult(await buildRunStatus(runInfo, await queryLiveStatus(client, runInfo.runtimeId)), args.view);
 		validateRunId(args.runId);
 		const liveStatus = await queryLiveStatus(client, args.runId);
@@ -1647,7 +2347,7 @@ async function executeStatusTool(args, getSupervisorClient) {
 			label: args.runId,
 			runtime_id: stringField(liveStatus ?? {}, "runtime_id", "id"),
 			session_id: sentinel?.SESSION ?? liveStatus?.session_id,
-			stop_reason: sentinel?._status
+			stop_reason: sentinel?.STOP_REASON
 		}, translateStatus(rawStatusPhase(liveStatus), sentinel)), args.view);
 	}
 	const list = await client.list();
@@ -1655,9 +2355,9 @@ async function executeStatusTool(args, getSupervisorClient) {
 	for (const entry of list) {
 		const entryId = String(entry.runtime_id ?? entry.id ?? "");
 		const entryLabel = String(entry.label ?? entryId);
-		const runInfo = findRunByLabel$3(sup, entryId) ?? findRunByLabel$3(sup, entryLabel);
+		const runInfo = findLocalRunByRuntimeId(sup, entryId) ?? findLocalRunByReference(sup, entryId) ?? findLocalRunByReference(sup, entryLabel);
 		const liveStatus = runInfo ? await queryLiveStatus(client, runInfo.runtimeId) : null;
-		if (runInfo && liveStatus) results.push(shapeStatusResult(await buildRunStatus(runInfo, liveStatus), args.view));
+		if (runInfo) results.push(shapeStatusResult(await buildRunStatus(runInfo, liveStatus), args.view));
 		else results.push(shapeStatusResult(buildBaseStatus(entry, {
 			run_id: String(entry.run_id ?? entryId),
 			label: entryLabel,
@@ -1677,12 +2377,6 @@ const MAX_EVENT_LIMIT = 1e3;
 const MAX_STRING_CHARS = 4e3;
 const MAX_ARRAY_ITEMS = 32;
 const MAX_OBJECT_KEYS = 64;
-function findRunByLabel$2(sup, runId) {
-	const runs = sup.runs;
-	const byKey = runs.get(runId);
-	if (byKey) return byKey;
-	for (const info of runs.values()) if (info.label === runId) return info;
-}
 function normalizeLimit(limit) {
 	return Math.max(1, Math.min(MAX_EVENT_LIMIT, Math.trunc(limit ?? 50)));
 }
@@ -1752,8 +2446,8 @@ async function readNdjsonEvents(filePath, args) {
 }
 async function resolveRun(args, getSupervisorClient) {
 	if (args.supervisorId) {
-		const { client, isSingleton, sup } = await getSupervisorClient(args.supervisorId);
-		const runInfo = isSingleton && sup ? findRunByLabel$2(sup, args.runId) : void 0;
+		const { client, isSingleton, sup, supervisorId } = await getSupervisorClient(args.supervisorId);
+		const runInfo = isSingleton && sup ? findLocalRunByReference(sup, args.runId) : findExternalRun(supervisorId, args.runId);
 		if (runInfo) return {
 			client,
 			isSingleton,
@@ -1796,7 +2490,7 @@ async function resolveRun(args, getSupervisorClient) {
 		};
 	}
 	const sup = await Supervisor.get();
-	const runInfo = findRunByLabel$2(sup, args.runId);
+	const runInfo = findLocalRunByReference(sup, args.runId);
 	if (runInfo) return {
 		client: sup.getClient(),
 		isSingleton: true,
@@ -1822,6 +2516,7 @@ async function resolveRun(args, getSupervisorClient) {
 	};
 }
 async function executeEventsTool(args, getSupervisorClient) {
+	validateRunId(args.runId);
 	const limit = normalizeLimit(args.limit);
 	const resolved = await resolveRun(args, getSupervisorClient);
 	try {
@@ -2030,12 +2725,6 @@ async function resultTool(args) {
 }
 //#endregion
 //#region src/tools/answer-permission.ts
-function findRunByLabel$1(sup, runId) {
-	const runs = sup.runs;
-	const byKey = runs.get(runId);
-	if (byKey) return byKey;
-	for (const info of runs.values()) if (info.label === runId) return info;
-}
 function pendingPermissionRequestID(liveStatus) {
 	const status = asRecord(liveStatus);
 	if (!status) return void 0;
@@ -2055,7 +2744,7 @@ async function answerPermissionTool(args) {
 	}
 	try {
 		validateRunId(args.runId);
-		const runtimeId = (sup ? findRunByLabel$1(sup, args.runId) : void 0)?.runtimeId ?? args.runId;
+		const runtimeId = (sup ? findLocalRunByReference(sup, args.runId) : supervisorId ? findExternalRun(supervisorId, args.runId) : void 0)?.runtimeId ?? args.runId;
 		if (!requestId) {
 			requestId = pendingPermissionRequestID(await client.status(runtimeId));
 			if (!requestId) throw new Error("no pending permission request for this run");
@@ -2068,20 +2757,18 @@ async function answerPermissionTool(args) {
 }
 //#endregion
 //#region src/tools/follow-up.ts
-function findRunByLabel(sup, runId) {
-	const runs = sup.runs;
-	const byKey = runs.get(runId);
-	if (byKey) return byKey;
-	for (const info of runs.values()) if (info.label === runId) return info;
-}
 function resolveAutoApprove(liveStatus, runInfo) {
 	const liveAutoApprove = liveStatus?.auto_approve;
 	if (typeof liveAutoApprove === "boolean") return liveAutoApprove;
 	return typeof runInfo?.autoApprove === "boolean" ? runInfo.autoApprove : void 0;
 }
-function requireResumableAgent(agent) {
-	if (agent === void 0) throw new Error("run has no agent to resume");
-	return agent;
+function value(candidate) {
+	return typeof candidate === "string" && candidate.length > 0 ? candidate : void 0;
+}
+function resolvedIdentity(liveStatus, effectiveKey, directKey, fallbackEffective, fallbackDirect) {
+	if (liveStatus && typeof liveStatus[effectiveKey] === "string") return value(liveStatus[effectiveKey]);
+	if (liveStatus && typeof liveStatus[directKey] === "string") return value(liveStatus[directKey]);
+	return fallbackEffective ?? fallbackDirect;
 }
 async function parseSentinel(filePath) {
 	try {
@@ -2101,85 +2788,144 @@ async function parseSentinel(filePath) {
 		return null;
 	}
 }
+function rejectSessionConflict(sentinel, liveStatus) {
+	const sentinelStopReason = value(sentinel?.STOP_REASON);
+	const liveStopReason = value(liveStatus?.stop_reason);
+	if (sentinelStopReason === "session_id_conflict" || liveStopReason === "session_id_conflict") throw new Error("run is not resumable: session_id_conflict");
+}
 async function executeFollowUpTool(args, getSupervisorClient) {
 	if (args.supervisorId) {
-		const { client, isSingleton, sup } = await getSupervisorClient(args.supervisorId);
+		const { client, isSingleton, sup, supervisorId } = await getSupervisorClient(args.supervisorId);
 		try {
 			validateRunId(args.runId);
 			let runInfo;
-			if (isSingleton && sup) runInfo = findRunByLabel(sup, args.runId);
+			if (isSingleton && sup) runInfo = findLocalRunByReference(sup, args.runId);
+			else runInfo = findExternalRun(supervisorId, args.runId);
 			const fallbackSessionId = runInfo?.sessionId;
 			let liveStatus = null;
 			try {
 				liveStatus = await client.status(runInfo?.runtimeId ?? args.runId);
 			} catch {}
-			const sessionId = (await parseSentinel(liveStatus?.sentinel_file ?? path.join(runsRoot(), args.runId, "sentinel.done")))?.SESSION ?? liveStatus?.session_id ?? fallbackSessionId;
+			const sentinel = await parseSentinel(liveStatus?.sentinel_file ?? runInfo?.sentinelPath ?? path.join(runsRoot(), args.runId, "sentinel.done"));
+			rejectSessionConflict(sentinel, liveStatus);
+			const sessionId = sentinel?.SESSION ?? liveStatus?.session_id ?? fallbackSessionId;
 			if (!sessionId) throw new Error("run has no session to resume");
-			const agent = requireResumableAgent(liveStatus?.agent ?? runInfo?.agent);
-			const backend = liveStatus?.backend ?? runInfo?.backend;
-			const model = liveStatus?.model ?? runInfo?.model;
+			const agent = resolvedIdentity(liveStatus, "effective_agent", "agent", runInfo?.effectiveAgent, runInfo?.agent);
+			const model = resolvedIdentity(liveStatus, "effective_model", "model", runInfo?.effectiveModel, runInfo?.model);
+			const backend = resolvedIdentity(liveStatus, "effective_backend", "backend", runInfo?.effectiveBackend, runInfo?.backend);
+			if (runInfo && liveStatus) retainLiveIdentity(runInfo, liveStatus);
 			const thinking = liveStatus?.thinking ?? runInfo?.thinking;
 			const dir = liveStatus?.dir ?? runInfo?.dir;
 			const agentProfile = liveStatus?.agent_profile ?? runInfo?.agentProfile;
 			const autoApprove = resolveAutoApprove(liveStatus, runInfo);
 			const followUpRunId = crypto.randomUUID();
 			const followUpLabel = args.label ?? `${args.runId}-followup`;
-			const { sentinelPath: followUpSentinelPath, eventLogPath } = ensureRunPaths(followUpRunId);
 			const spawnParams = {
-				agent,
 				prompt: args.message,
 				label: followUpLabel,
-				session_id: sessionId,
-				sentinel_file: followUpSentinelPath,
-				on_event: eventLogPath
+				session_id: sessionId
 			};
+			if (agent) spawnParams.agent = agent;
 			if (backend) spawnParams.backend = backend;
 			if (model) spawnParams.model = model;
 			if (thinking) spawnParams.thinking = thinking;
 			if (dir) spawnParams.dir = dir;
 			if (agentProfile) spawnParams.agent_profile = agentProfile;
 			if (autoApprove === true) spawnParams.auto_approve = true;
+			if (isSingleton && sup) {
+				const followUpRun = await sup.spawn(spawnParams, followUpRunId, {
+					rosterFile: runInfo?.rosterFile,
+					rosterEntry: runInfo?.rosterEntry,
+					effectiveAgent: agent,
+					effectiveModel: model,
+					effectiveBackend: backend
+				});
+				return {
+					run_id: followUpRun.runId,
+					label: followUpRun.label,
+					runtime_id: followUpRun.runtimeId
+				};
+			}
+			const { sentinelPath: followUpSentinelPath, eventLogPath } = ensureRunPaths(followUpRunId);
+			spawnParams.sentinel_file = followUpSentinelPath;
+			spawnParams.on_event = eventLogPath;
+			const result = await client.spawn(spawnParams);
+			const runtimeId = value(result.runtime_id);
+			registerExternalRun({
+				runId: followUpRunId,
+				label: followUpLabel,
+				supervisorId,
+				sentinelPath: followUpSentinelPath,
+				eventLogPath,
+				runtimeId,
+				sessionId: value(result.session_id) ?? sessionId,
+				agent,
+				model,
+				backend,
+				effectiveAgent: agent,
+				effectiveModel: model,
+				effectiveBackend: backend,
+				rosterFile: runInfo?.rosterFile,
+				rosterEntry: runInfo?.rosterEntry,
+				thinking,
+				dir,
+				agentProfile,
+				autoApprove
+			});
 			return {
-				run_id: (await client.spawn(spawnParams)).runtime_id ?? followUpRunId,
-				label: followUpLabel
+				run_id: followUpRunId,
+				label: followUpLabel,
+				runtime_id: runtimeId
 			};
 		} finally {
 			if (!isSingleton) client.close();
 		}
 	}
 	const sup = await Supervisor.get();
-	const runInfo = findRunByLabel(sup, args.runId);
+	const runInfo = findLocalRunByReference(sup, args.runId);
 	if (!runInfo) throw new Error(`run not found: ${args.runId}`);
-	const sessionId = (await parseSentinel(runInfo.sentinelPath))?.SESSION ?? runInfo.sessionId;
+	const sentinel = await parseSentinel(runInfo.sentinelPath);
+	rejectSessionConflict(sentinel, null);
+	const sessionId = sentinel?.SESSION ?? runInfo.sessionId;
 	if (!sessionId) throw new Error("run has no session to resume");
 	const client = sup.getClient();
 	let liveStatus = null;
 	if (runInfo.runtimeId) try {
 		liveStatus = await client.status(runInfo.runtimeId);
 	} catch {}
-	const agent = requireResumableAgent(liveStatus?.agent ?? runInfo.agent);
-	const backend = liveStatus?.backend ?? runInfo.backend;
-	const model = liveStatus?.model ?? runInfo.model;
+	rejectSessionConflict(sentinel, liveStatus);
+	const agent = resolvedIdentity(liveStatus, "effective_agent", "agent", runInfo.effectiveAgent, runInfo.agent);
+	const model = resolvedIdentity(liveStatus, "effective_model", "model", runInfo.effectiveModel, runInfo.model);
+	const backend = resolvedIdentity(liveStatus, "effective_backend", "backend", runInfo.effectiveBackend, runInfo.backend);
+	if (liveStatus) retainLiveIdentity(runInfo, liveStatus);
 	const thinking = liveStatus?.thinking ?? runInfo.thinking;
 	const dir = liveStatus?.dir ?? runInfo.dir;
 	const agentProfile = liveStatus?.agent_profile ?? runInfo.agentProfile;
 	const autoApprove = resolveAutoApprove(liveStatus, runInfo);
 	const followUpLabel = args.label ?? `${runInfo.label}-followup`;
-	const followUpRun = await sup.spawn({
-		agent,
-		backend,
-		model,
-		thinking,
-		dir,
-		agent_profile: agentProfile,
+	const followUpParams = {
+		...agent ? { agent } : {},
+		...backend ? { backend } : {},
+		...model ? { model } : {},
+		...thinking ? { thinking } : {},
+		...dir ? { dir } : {},
+		...agentProfile ? { agent_profile: agentProfile } : {},
 		prompt: args.message,
 		session_id: sessionId,
 		label: followUpLabel,
 		...autoApprove === true ? { auto_approve: true } : {}
+	};
+	const followUpRun = await sup.spawn(followUpParams, void 0, {
+		rosterFile: runInfo.rosterFile,
+		rosterEntry: runInfo.rosterEntry,
+		effectiveAgent: agent,
+		effectiveModel: model,
+		effectiveBackend: backend
 	});
 	return {
 		run_id: followUpRun.runId,
-		label: followUpRun.label
+		label: followUpRun.label,
+		runtime_id: followUpRun.runtimeId
 	};
 }
 function createFollowUpTool(getSupervisorClient) {
@@ -2212,9 +2958,24 @@ async function shutdownTool(args) {
 			const client = await dial(supervisorId);
 			try {
 				await client.shutdown(args.force ? "force" : "graceful");
-			} catch {} finally {
+			} finally {
 				client.close();
 			}
+			for (const info of clearExternalRuns(supervisorId)) {
+				try {
+					await fs.promises.unlink(info.sentinelPath);
+					cleanedUp.push(info.sentinelPath);
+				} catch {}
+				try {
+					await fs.promises.unlink(info.eventLogPath);
+					cleanedUp.push(info.eventLogPath);
+				} catch {}
+				const metadataPath = externalRunMetadataPath(info.runId);
+				try {
+					await fs.promises.unlink(metadataPath);
+					cleanedUp.push(metadataPath);
+				} catch {}
+			}
 		}
 		return {
 			ok: true,
@@ -2243,4 +3004,184 @@ async function shutdownTool(args) {
 	};
 }
 //#endregion
-export { DEFAULT_RUN_REDUCER_LIMITS, RunReducer, Supervisor, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, normalizeRunEvent, observeRun, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool };
+//#region src/tools/ask.ts
+function extractReplyMessage(result) {
+	if (result.timeout === true) return "(timeout: no reply received)";
+	if (result.cancelled === true) return "(cancelled)";
+	const payload = result.payload;
+	if (payload && typeof payload === "object") {
+		const msg = payload.message;
+		if (typeof msg === "string" && msg) return msg;
+	}
+	return JSON.stringify(result);
+}
+async function executeAskTool(args, getSupervisorClient) {
+	const { client, isSingleton } = await getSupervisorClient(args.supervisorId);
+	try {
+		const result = await client.brokerAsk(args.toRunId, args.message);
+		return {
+			reply: extractReplyMessage(result),
+			from_run_id: result.from_run_id ?? ""
+		};
+	} finally {
+		if (!isSingleton) client.close();
+	}
+}
+function createAskTool(getSupervisorClient) {
+	return (args) => executeAskTool(args, getSupervisorClient);
+}
+const askTool = createAskTool(getSupervisorClient);
+//#endregion
+//#region src/tools/peers.ts
+async function executePeersTool(args, getSupervisorClient) {
+	const { client, isSingleton } = await getSupervisorClient(args.supervisorId);
+	try {
+		return { peers: await client.brokerPeers() };
+	} finally {
+		if (!isSingleton) client.close();
+	}
+}
+function createPeersTool(getSupervisorClient) {
+	return (args) => executePeersTool(args, getSupervisorClient);
+}
+const peersTool = createPeersTool(getSupervisorClient);
+//#endregion
+//#region src/tools/cancel.ts
+async function executeCancelTool(args, getSupervisorClient) {
+	const { client, isSingleton } = await getSupervisorClient(args.supervisorId);
+	try {
+		await client.brokerCancel(args.messageId);
+		return { cancelled: true };
+	} finally {
+		if (!isSingleton) client.close();
+	}
+}
+function createCancelTool(getSupervisorClient) {
+	return (args) => executeCancelTool(args, getSupervisorClient);
+}
+const cancelTool = createCancelTool(getSupervisorClient);
+//#endregion
+//#region src/tools/broker-receive.ts
+async function executeBrokerReceive(args, getSupervisorClient) {
+	const { client, isSingleton } = await getSupervisorClient(args.supervisorId);
+	try {
+		return { asks: await client.brokerReceive() };
+	} finally {
+		if (!isSingleton) client.close();
+	}
+}
+function createBrokerReceiveTool(getSupervisorClient) {
+	return (args) => executeBrokerReceive(args, getSupervisorClient);
+}
+const brokerReceiveTool = createBrokerReceiveTool(getSupervisorClient);
+//#endregion
+//#region src/tools/broker-reply.ts
+async function executeBrokerReply(args, getSupervisorClient) {
+	const { client, isSingleton } = await getSupervisorClient(args.supervisorId);
+	try {
+		await client.brokerReply(args.toRunId, args.replyTo, args.message);
+		return { ok: true };
+	} finally {
+		if (!isSingleton) client.close();
+	}
+}
+function createBrokerReplyTool(getSupervisorClient) {
+	return (args) => executeBrokerReply(args, getSupervisorClient);
+}
+const brokerReplyTool = createBrokerReplyTool(getSupervisorClient);
+//#endregion
+//#region src/tools/workflow-client.ts
+/**
+* Run `work` against the client for the given supervisor, or the singleton when none is
+* supplied. External supervisors are dialed on demand and closed again; the singleton client is
+* reused. Workflow host tools correlate by supervisor ID so runtime ids (e.g. rt_1) that collide
+* across supervisors never route to the wrong host.
+*/
+async function withWorkflowClient(supervisorId, work, getSupervisorClient$1 = getSupervisorClient) {
+	if (supervisorId) {
+		const { client, isSingleton } = await getSupervisorClient$1(supervisorId);
+		try {
+			return await work(client);
+		} finally {
+			if (!isSingleton) client.close();
+		}
+	}
+	return work((await Supervisor.get()).getClient());
+}
+//#endregion
+//#region src/tools/workflow-status.ts
+function createWorkflowStatusTool(getSupervisorClient) {
+	return async (args) => {
+		if (!args.workflowId) throw new Error("workflowId is required");
+		return withWorkflowClient(args.supervisorId, (client) => client.workflowStatus(args.workflowId), getSupervisorClient);
+	};
+}
+const workflowStatusTool = createWorkflowStatusTool(getSupervisorClient);
+//#endregion
+//#region src/tools/workflow-wait.ts
+function createWorkflowWaitTool(getSupervisorClient) {
+	return async (args) => {
+		if (!args.workflowId) throw new Error("workflowId is required");
+		const timeoutMs = args.timeout ? validateTimeout(args.timeout) * 1e3 : 3e4;
+		return withWorkflowClient(args.supervisorId, (client) => client.workflowWait(args.workflowId, timeoutMs), getSupervisorClient);
+	};
+}
+const workflowWaitTool = createWorkflowWaitTool(getSupervisorClient);
+//#endregion
+//#region src/tools/workflow-inspect.ts
+function createWorkflowInspectTool(getSupervisorClient) {
+	return async (args) => {
+		if (!args.workflowId) throw new Error("workflowId is required");
+		return withWorkflowClient(args.supervisorId, (client) => client.workflowInspect(args.workflowId), getSupervisorClient);
+	};
+}
+const workflowInspectTool = createWorkflowInspectTool(getSupervisorClient);
+//#endregion
+//#region src/tools/workflow-events.ts
+function createWorkflowEventsTool(getSupervisorClient) {
+	return async (args) => {
+		if (!args.workflowId) throw new Error("workflowId is required");
+		return withWorkflowClient(args.supervisorId, (client) => client.workflowEvents(args.workflowId, {
+			afterSeq: args.afterSeq,
+			limit: args.limit
+		}), getSupervisorClient);
+	};
+}
+const workflowEventsTool = createWorkflowEventsTool(getSupervisorClient);
+//#endregion
+//#region src/tools/workflow-complete.ts
+function createWorkflowCompleteTool(getSupervisorClient) {
+	return async (args) => {
+		if (!args.workflow_id) throw new Error("workflow_id is required");
+		if (!args.node_id) throw new Error("node_id is required");
+		if (!args.activation_id) throw new Error("activation_id is required");
+		if (!args.attempt_id) throw new Error("attempt_id is required");
+		if (!args.lease_id) throw new Error("lease_id is required");
+		if (!args.owner_token) throw new Error("owner_token is required");
+		if (!args.outcome) throw new Error("outcome is required");
+		return withWorkflowClient(args.supervisorId, (client) => client.workflowComplete(args), getSupervisorClient);
+	};
+}
+const workflowCompleteTool = createWorkflowCompleteTool(getSupervisorClient);
+//#endregion
+//#region src/tools/workflow-gate.ts
+function createWorkflowGateTool(getSupervisorClient) {
+	return async (args) => {
+		if (!args.workflow_id) throw new Error("workflow_id is required");
+		if (!args.node_id) throw new Error("node_id is required");
+		if (!args.gate_id) throw new Error("gate_id is required");
+		if (!args.activation_id) throw new Error("activation_id is required");
+		if (!args.operation) throw new Error("operation is required");
+		if (![
+			"satisfy",
+			"reject",
+			"waive",
+			"external_result"
+		].includes(args.operation)) throw new Error(`unknown gate operation "${args.operation}" (allowed: satisfy, reject, waive, external_result)`);
+		if (args.observed_at) validateObservedAt(args.observed_at);
+		return withWorkflowClient(args.supervisorId, (client) => client.workflowGate(args), getSupervisorClient);
+	};
+}
+const workflowGateTool = createWorkflowGateTool(getSupervisorClient);
+//#endregion
+export { DEFAULT_RUN_REDUCER_LIMITS, RunReducer, Supervisor, THINKING_LEVELS, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, createRunSnapshot, createWorkflowCompleteTool, createWorkflowEventsTool, createWorkflowGateTool, createWorkflowInspectTool, createWorkflowStatusTool, createWorkflowWaitTool, dial, evaluateThinkingPolicy, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, isThinkingLevel, normalizeRunEvent, observeRun, peersTool, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, validateThinking, validateThinkingForBackend, validateThinkingForBackendResume, workflowCompleteTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowStatusTool, workflowWaitTool };