@dougbots/avenor-core 0.8.3 → 0.10.0

package/README.md

@@ -50,7 +50,33 @@ const result = await spawnTool({
 // { run_id: '...', label: 'reverse-string', supervisor_id: '/path/to/socket' }
 ```
 
-Accepts `agent`, `prompt`, `promptFile`, `label`, `dir`, `timeout`, `model`, `backend`, `serverUrl`, `sessionId`, and `supervisorId` (to target a specific socket).
+Accepts `agent`, `prompt`, `promptFile`, `label`, `dir`, `timeout`, `model`, `thinking`, `backend`, `rosterFile`, `rosterEntry`, `serverUrl`, `sessionId`, and `supervisorId` (to target a specific socket).
+
+### Roster selection
+
+`rosterFile` is the path to a top-level JSON roster map and `rosterEntry` is the key selected from it. Each entry must contain `backend` and at least one of `agent` or `model`:
+
+```json
+{
+  "planner": {
+    "backend": "opencode-acp",
+    "model": "provider/planner"
+  }
+}
+```
+
+A direct roster spawn forwards both selectors and must not also provide `agent`, `model`, or `backend`. Direct mode without a roster allows each of those identity fields to be omitted independently, including a backend-only request; the selected runtime supplies defaults for omitted values. `thinking` is run-level, not a roster field, and is checked against the effective backend. The shared selector validation rejects missing selector pairs, mixed direct/roster fields, and unknown selector keys. Roster-file loading rejects deferred entry fields such as `system`; `thinking` remains a valid run-level option but is never read from a roster entry.
+
+```ts
+await spawnTool({
+  prompt: 'Analyze the repository',
+  dir: '/repo',
+  rosterFile: '/repo/roster.json',
+  rosterEntry: 'planner',
+})
+```
+
+Roster phase selection is resolved by Avenor's Go workflow runners. A roster entry may override backend/agent/model per phase. CLI workflow fallback and nested roster inheritance are CLI-only; stable nesting keeps its existing behavior. A resumed session must use the same effective backend as the original session.
 
 ### `statusTool`
 

package/dist/index.d.ts

@@ -24,6 +24,7 @@ interface HistoryResult<TEvent = Event> {
   events: TEvent[];
   latest_seq?: number;
 }
+type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 interface SpawnParams {
   agent?: string;
   prompt_file?: string;
@@ -32,8 +33,11 @@ interface SpawnParams {
   label?: string;
   timeout?: number;
   model?: string;
+  thinking?: ThinkingLevel;
   agent_profile?: string;
   backend?: string;
+  roster_file?: string;
+  roster_entry?: string;
   server_url?: string;
   session_id?: string;
   sentinel_file?: string;
@@ -41,9 +45,28 @@ interface SpawnParams {
   auto_approve?: boolean;
   [key: string]: unknown;
 }
+interface SpawnResult {
+  runtime_id?: string;
+  session_id?: string;
+  on_event?: string;
+  sentinel_file?: string;
+  broker_url?: string;
+  parent_token?: string;
+  agent?: string;
+  agent_profile?: string;
+  model?: string;
+  backend?: string;
+  roster_file?: string;
+  roster_entry?: string;
+  effective_agent?: string;
+  effective_model?: string;
+  effective_backend?: string;
+  [key: string]: unknown;
+}
 declare class Client {
   private socket;
   private rl;
+  private closed;
   private nextID;
   private pending;
   private started;
@@ -66,12 +89,13 @@ declare class Client {
   status(runtimeId?: string): Promise<Record<string, unknown>>;
   result(runtimeId?: string): Promise<Record<string, unknown>>;
   list(): Promise<Array<Record<string, unknown>>>;
-  spawn(params: SpawnParams): Promise<Record<string, unknown>>;
+  spawn(params: SpawnParams): Promise<SpawnResult>;
   shutdown(mode: string): Promise<void>;
   answerPermission(runtimeId: string, requestId: string, optionId: string, message?: string): Promise<void>;
   prompt(runtimeId: string, text: string): Promise<void>;
   interruptAndPrompt(runtimeId: string, text: string, keepQueue?: boolean): Promise<void>;
   cancel(runtimeId?: string): Promise<void>;
+  isClosed(): boolean;
   close(): void;
 }
 declare function dial(socketPath: string, opts?: {
@@ -241,6 +265,12 @@ interface RunInfo {
   agentProfile?: string;
   backend?: string;
   model?: string;
+  effectiveAgent?: string;
+  effectiveModel?: string;
+  effectiveBackend?: string;
+  rosterFile?: string;
+  rosterEntry?: string;
+  thinking?: ThinkingLevel;
   dir?: string;
   brokerUrl?: string;
   parentToken?: string;
@@ -250,6 +280,14 @@ interface SupervisorOptions {
   binaryPath?: string;
   callTimeoutMs?: number;
 }
+/** Metadata retained locally when a follow-up uses a resolved direct identity. */
+interface SpawnMetadata {
+  rosterFile?: string;
+  rosterEntry?: string;
+  effectiveAgent?: string;
+  effectiveModel?: string;
+  effectiveBackend?: string;
+}
 declare function findAvenorBinary(): string;
 declare class Supervisor {
   private static instance;
@@ -262,6 +300,7 @@ declare class Supervisor {
   private crashed;
   private crashCode;
   private runs;
+  private aliases;
   private binaryPath;
   private callTimeoutMs;
   private constructor();
@@ -272,7 +311,7 @@ declare class Supervisor {
   static isCurrentInstance(supervisorId: string): boolean;
   static currentInstance(): Supervisor | null;
   getClient(): Client;
-  spawn(params: SpawnParams, runId?: `${string}-${string}-${string}-${string}-${string}`): Promise<RunInfo>;
+  spawn(params: SpawnParams, runId?: `${string}-${string}-${string}-${string}-${string}`, metadata?: SpawnMetadata): Promise<RunInfo>;
   close(options?: {
     skipShutdown?: boolean;
   }): Promise<void>;
@@ -282,7 +321,7 @@ declare class Supervisor {
 declare function socketsRoot(): string;
 //#endregion
 //#region src/tools/spawn.d.ts
-declare function spawnTool(args: {
+interface SpawnToolArgs {
   agent?: string;
   prompt?: string;
   promptFile?: string;
@@ -290,20 +329,36 @@ declare function spawnTool(args: {
   dir?: string;
   timeout?: string;
   model?: string;
+  thinking?: ThinkingLevel;
   agentProfile?: string;
   backend?: string;
+  rosterFile?: string;
+  rosterEntry?: string;
   serverUrl?: string;
   sessionId?: string;
   supervisorId?: string;
   parent_run_id?: string;
-}): Promise<{
+}
+interface SpawnToolResult {
   run_id: string;
   label: string;
   supervisor_id: string;
   runtime_id?: string;
   broker_url?: string;
   parent_token?: string;
-}>;
+}
+declare const spawnTool: (args: SpawnToolArgs) => Promise<SpawnToolResult>;
+//#endregion
+//#region src/spawn-selection.d.ts
+interface SpawnSelectionInput {
+  agent?: string;
+  model?: string;
+  backend?: string;
+  roster_file?: string;
+  roster_entry?: string;
+}
+/** Validate the direct-versus-roster selector contract. */
+declare function validateSpawnSelection(input: unknown, rosterConfigured?: boolean): void;
 //#endregion
 //#region src/tools/status.d.ts
 type StatusView = 'lifecycle' | 'full';
@@ -331,9 +386,15 @@ interface StatusResult {
   };
   session_id?: string;
   stop_reason?: string;
+  roster_file?: string;
+  roster_entry?: string;
   backend?: string;
   agent?: string;
   model?: string;
+  agent_profile?: string;
+  effective_backend?: string;
+  effective_agent?: string;
+  effective_model?: string;
   dir?: string;
   parent_id?: string;
   children?: string[];
@@ -430,6 +491,7 @@ interface FollowUpToolArgs {
 interface FollowUpToolResult {
   run_id: string;
   label: string;
+  runtime_id?: string;
 }
 declare const followUpTool: (args: FollowUpToolArgs) => Promise<FollowUpToolResult>;
 //#endregion
@@ -442,4 +504,4 @@ declare function shutdownTool(args: {
   cleaned_up: string[];
 }>;
 //#endregion
-export { type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type HistoryOptions, type HistoryResult, type InspectResult, type NormalizedRunEvent, type ObserveRunOptions, type ResultResult, type ResultToolArgs, type RunChunkRole, type RunIdentity, type RunInfo, type RunObserver, type RunObserverClient, type RunPermissionOption, type RunPermissionSummary, RunReducer, type RunReducerLimits, type RunSnapshot, type RunSnapshotSeed, type RunToolState, type RunToolSummary, type RunTranscriptEntry, type SpawnParams, type StatusResult, type StatusView, type SubscribeOptions, Supervisor, type SupervisorOptions, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, normalizeRunEvent, observeRun, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool };
+export { type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type FollowUpToolArgs, type FollowUpToolResult, type HistoryOptions, type HistoryResult, type InspectResult, type NormalizedRunEvent, type ObserveRunOptions, type ResultResult, type ResultToolArgs, type RunChunkRole, type RunIdentity, type RunInfo, type RunObserver, type RunObserverClient, type RunPermissionOption, type RunPermissionSummary, RunReducer, type RunReducerLimits, type RunSnapshot, type RunSnapshotSeed, type RunToolState, type RunToolSummary, type RunTranscriptEntry, type SpawnMetadata, type SpawnParams, type SpawnResult, type SpawnSelectionInput, type SpawnToolArgs, type SpawnToolResult, type StatusResult, type StatusToolArgs, type StatusView, type SubscribeOptions, Supervisor, type SupervisorOptions, type ThinkingLevel, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, normalizeRunEvent, observeRun, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection };

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;
@@ -26,6 +28,7 @@ function removeResolver(resolvers, target) {
 var Client = class {
 	socket;
 	rl;
+	closed = false;
 	nextID = 0;
 	pending = /* @__PURE__ */ new Map();
 	started = false;
@@ -44,11 +47,15 @@ var Client = class {
 		});
 		this.callTimeout = opts?.callTimeoutMs ?? 3e4;
 		this.socket.on("error", (err) => {
+			this.closed = true;
 			this.pushEvent({
 				event: "protocol-error",
 				message: err.message
 			});
 		});
+		this.socket.on("close", () => {
+			this.closed = true;
+		});
 	}
 	startReadLoop() {
 		if (this.started) return;
@@ -85,6 +92,7 @@ var Client = class {
 			}
 		});
 		this.rl.on("close", () => {
+			this.closed = true;
 			for (const [, pc] of this.pending) {
 				clearTimeout(pc.timer);
 				pc.reject(/* @__PURE__ */ new Error("read response: connection closed"));
@@ -116,6 +124,7 @@ var Client = class {
 		else this.dropped++;
 	}
 	async call(method, params) {
+		if (this.isClosed()) throw new Error("control socket is closed");
 		this.startReadLoop();
 		const id = ++this.nextID;
 		const req = {
@@ -137,6 +146,7 @@ var Client = class {
 			});
 			this.socket.write(data, (err) => {
 				if (err) {
+					this.closed = true;
 					clearTimeout(timer);
 					this.pending.delete(id);
 					reject(/* @__PURE__ */ new Error(`write request: ${err.message}`));
@@ -272,7 +282,11 @@ var Client = class {
 		const params = runtimeId ? { runtime_id: runtimeId } : void 0;
 		await this.call("cancel", params);
 	}
+	isClosed() {
+		return this.closed || this.socket.destroyed || this.socket.writableEnded;
+	}
 	close() {
+		this.closed = true;
 		this.rl.close();
 		this.socket.destroy();
 	}
@@ -1062,6 +1076,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");
@@ -1086,6 +1189,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 {
@@ -1142,6 +1276,7 @@ var Supervisor = class Supervisor {
 	crashed = false;
 	crashCode = null;
 	runs = /* @__PURE__ */ new Map();
+	aliases = /* @__PURE__ */ new Map();
 	binaryPath;
 	callTimeoutMs;
 	constructor(binaryPath, socketPath, opts) {
@@ -1150,7 +1285,14 @@ var Supervisor = class Supervisor {
 		this.callTimeoutMs = opts?.callTimeoutMs ?? 3e4;
 	}
 	static get(opts) {
-		if (Supervisor.instance && !Supervisor.instance.crashed) return Promise.resolve(Supervisor.instance);
+		const current = Supervisor.instance;
+		if (current && !current.crashed) {
+			if (current.client && !current.client.isClosed()) return Promise.resolve(current);
+			current.crashed = true;
+			current.crashCode = 0;
+			current.client?.close();
+			current.client = null;
+		}
 		if (Supervisor.starting) return Supervisor.starting;
 		const starting = Supervisor.start(opts);
 		Supervisor.starting = starting;
@@ -1216,15 +1358,13 @@ var Supervisor = class Supervisor {
 					reject(/* @__PURE__ */ new Error(`avenor exited with code ${code}${signal ? " signal " + signal : ""} during startup`));
 					return;
 				}
-				if (code !== 0 || signal) {
-					this.crashed = true;
-					this.crashCode = code ?? -1;
-					if (this.client) {
-						try {
-							this.client.close();
-						} catch {}
-						this.client = null;
-					}
+				this.crashed = true;
+				this.crashCode = code ?? -1;
+				if (this.client) {
+					try {
+						this.client.close();
+					} catch {}
+					this.client = null;
 				}
 			});
 			this.childProcess.on("error", (err) => {
@@ -1262,11 +1402,27 @@ var Supervisor = class Supervisor {
 		return Supervisor.instance;
 	}
 	getClient() {
-		if (this.crashed) throw new Error(`avenor supervisor crashed (exit code ${this.crashCode}). Call avenor_shutdown to clean up and retry.`);
+		if (this.crashed) {
+			const state = this.crashCode === 0 ? "exited" : "crashed";
+			throw new Error(`avenor supervisor ${state} (exit code ${this.crashCode}). Call avenor_shutdown to clean up and retry.`);
+		}
 		if (!this.client) throw new Error("supervisor not started");
+		if (this.client.isClosed()) {
+			this.crashed = true;
+			this.crashCode = 0;
+			this.client = null;
+			throw new Error("avenor supervisor connection closed");
+		}
 		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 = {
@@ -1275,25 +1431,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 = {}) {
@@ -1316,6 +1507,7 @@ var Supervisor = class Supervisor {
 		this.crashed = false;
 		this.crashCode = null;
 		this.runs.clear();
+		this.aliases.clear();
 		Supervisor.instance = null;
 	}
 };
@@ -1361,8 +1553,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 = {
@@ -1378,9 +1687,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({
@@ -1388,13 +1711,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();
@@ -1411,14 +1758,25 @@ 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 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();
@@ -1506,6 +1864,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,
@@ -1516,9 +1883,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"),
@@ -1545,6 +1918,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);
@@ -1554,7 +1928,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) {
@@ -1567,11 +1952,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 {
@@ -1589,17 +1974,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();
 		}
@@ -1607,7 +2005,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);
@@ -1619,7 +2017,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();
@@ -1627,9 +2025,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,
@@ -1649,12 +2047,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)));
 }
@@ -1724,8 +2116,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,
@@ -1768,7 +2160,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,
@@ -1794,6 +2186,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 {
@@ -2002,12 +2395,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;
@@ -2027,7 +2414,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");
@@ -2040,20 +2427,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 {
@@ -2073,81 +2458,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,
-		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) {
@@ -2180,9 +2628,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,
@@ -2211,4 +2674,4 @@ 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 };
+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, validateSpawnSelection };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougbots/avenor-core",
-  "version": "0.8.3",
+  "version": "0.10.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -34,5 +34,9 @@
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3",
     "unrun": "^0.3.0"
+  },
+  "dependencies": {
+    "@umpire/core": "1.0.1",
+    "@umpire/json": "1.0.0"
   }
 }