dsh-switchman 1.3.1 → 1.6.0

package/host/routes.js

@@ -7,13 +7,28 @@
  * plugin established). This module owns that route family:
  *
  *   GET  /api/dsh-switchman/health   — liveness probe for the client page.
- *   GET  /api/dsh-switchman/config   — current settings values snapshot.
+ *   GET  /api/dsh-switchman/config   — current settings values snapshot plus
+ *                                      `whitelistSync` (null unless teamsMode
+ *                                      && syncWhitelist, else the teams
+ *                                      layer's last replace-sync outcome).
  *   POST /api/dsh-switchman/config   — { expected, values } fenced write
  *                                      through ctx.settings.update; a stale
  *                                      `expected` answers 409 + fresh values.
+ *                                      A successful write schedules the teams
+ *                                      orchestration (fire-and-forget).
  *   GET  /api/dsh-switchman/models   — model-catalog pass-through from the
  *                                      host sessionController (degrades to
  *                                      llm.listProviders, then []).
+ *   GET  /api/dsh-switchman/authorized — the session's DSH-authorized child
+ *                                      models ({enabled, routes}; both null
+ *                                      when the host service is unreadable).
+ *   GET  /api/dsh-switchman/vision-state — composer-dock hint; the optional
+ *                                      `session` query parameter judges image
+ *                                      capability against THAT session's
+ *                                      model (unknown/missing → root model).
+ *   POST /api/dsh-switchman/ui-locale — the client half reports its active
+ *                                      UI locale (feeds the ask guidance's
+ *                                      question language; no settings write).
  *
  * Every route carries the shared trust fence (loopback + same-origin browser
  * markers; a live remoteWebUiPairing cookie is an extra allow path), mirroring
@@ -21,17 +36,30 @@
  * settings, so unpaired LAN clients must not reach it.
  */
 
+import { authorizedChildRoutes } from "./dispatch.js";
+import { handoverSnapshot } from "./handover-state.js";
+import { pumpTeamsOrchestration, scheduleTeamsOrchestration, SWITCHMAN_SETTINGS_NS, teamsBundleState, teamsSyncSnapshot } from "./teams.js";
+import { reportedUiLocale, setReportedUiLocale } from "./ui-locale.js";
+import { visionStateOf } from "./vision.js";
+
 /** Route paths (client.js mirrors these literals). */
 const ROUTES = {
 	health: "/api/dsh-switchman/health",
 	config: "/api/dsh-switchman/config",
 	models: "/api/dsh-switchman/models",
+	authorized: "/api/dsh-switchman/authorized",
+	handoverState: "/api/dsh-switchman/handover-state",
+	visionState: "/api/dsh-switchman/vision-state",
+	uiLocale: "/api/dsh-switchman/ui-locale",
 };
 
 /** Settings namespace this plugin's writes target: the LOADER ENTRY id from
  * cordis.patch.yml (`- id: dsh-switchman-host`), not the plugin's `name`
- * export — dsh-settings' write() looks entries up by entry.options.id. */
-const NS = "dsh-switchman-host";
+ * export — dsh-settings' write() looks entries up by entry.options.id.
+ * Single-sourced as SWITCHMAN_SETTINGS_NS in host/teams.js (whose
+ * settings/document-updated listener keys on it); aliased here for the
+ * write call sites below. */
+const NS = SWITCHMAN_SETTINGS_NS;
 
 /** All settings field names, grouped for coercion (mirrors host/config.js). */
 const STRING_FIELDS = ["langConversation", "langComments", "langDocs"];
@@ -53,13 +81,16 @@ const NUMBER_FIELDS = [
 const BOOLEAN_FIELDS = [
 	"wmAutoHandover",
 	"wmSubagentCap",
-	// 以下六个 mirrors host/config.js 的 pool*Manual 开关
+	// The following six mirror the pool*Manual switches in host/config.js
 	"poolEconomyManual",
 	"poolMechanicalManual",
 	"poolMainManual",
 	"poolHardManual",
 	"poolVisionManual",
 	"poolReviewManual",
+	// Teams switches (mirrors the teams* group in host/config.js)
+	"teamsMode",
+	"syncWhitelist",
 ];
 /** Per-pool effort-route lists (mirrors host/config.js pool*Efforts). */
 const EFFORTS_FIELDS = [
@@ -71,6 +102,8 @@ const EFFORTS_FIELDS = [
 	"poolReviewEfforts",
 ];
 const ENUM_FIELDS = {
+	uiLocale: ["auto", "en", "zh", "zh-TW", "ja", "ko", "de", "es", "fr", "it", "pt", "ru"],
+	langScope: ["global", "project"],
 	dispatchEnforce: ["off", "advice", "enforce"],
 	wmDenyMode: ["cap", "deny"],
 };
@@ -156,9 +189,17 @@ function isAllowed(ctx, request) {
 	);
 }
 
-/** Read one volatile settings field's raw value (live `.get()` reference). */
+/** Read one volatile settings field's raw value (live `.get()` reference;
+ * undefined when the getter itself throws — same guard as teams.js's
+ * readValue, kept on this GET-config hot path). */
 function rawOf(field) {
-	if (field !== null && typeof field === "object" && typeof field.get === "function") return field.get();
+	if (field !== null && typeof field === "object" && typeof field.get === "function") {
+		try {
+			return field.get();
+		} catch {
+			return undefined;
+		}
+	}
 	return field;
 }
 
@@ -206,6 +247,8 @@ export function snapshotOf(config) {
 		values[field] = Array.isArray(rawOf(config?.[field]))
 			? rawOf(config[field]).map(cleanEffortEntry).filter(Boolean)
 			: [];
+	values.uiLocale = ENUM_FIELDS.uiLocale.includes(rawOf(config?.uiLocale)) ? rawOf(config.uiLocale) : "auto";
+	values.langScope = ENUM_FIELDS.langScope.includes(rawOf(config?.langScope)) ? rawOf(config.langScope) : "global";
 	values.dispatchEnforce = ENUM_FIELDS.dispatchEnforce.includes(rawOf(config?.dispatchEnforce))
 		? rawOf(config.dispatchEnforce)
 		: "advice";
@@ -220,6 +263,15 @@ export function snapshotOf(config) {
 	return values;
 }
 
+/** The whitelistSync status for config responses: null unless syncWhitelist
+ *  is ON (an INDEPENDENT switch — teamsMode is not required), else the teams
+ *  layer's last replace-sync outcome ({ ok, count, at, error? } — itself
+ *  null before the first sync). */
+function whitelistSyncOf(config) {
+	if (rawOf(config?.syncWhitelist) !== true) return null;
+	return teamsSyncSnapshot();
+}
+
 /** Coerce and validate a client-submitted values object; null when invalid. */
 function coerceValues(input) {
 	if (input === null || typeof input !== "object" || Array.isArray(input)) return null;
@@ -244,6 +296,10 @@ function coerceValues(input) {
 		if (efforts.some((entry) => entry === null)) return null;
 		values[field] = efforts;
 	}
+	if (!ENUM_FIELDS.uiLocale.includes(input.uiLocale)) return null;
+	values.uiLocale = input.uiLocale;
+	if (!ENUM_FIELDS.langScope.includes(input.langScope)) return null;
+	values.langScope = input.langScope;
 	if (!ENUM_FIELDS.dispatchEnforce.includes(input.dispatchEnforce)) return null;
 	values.dispatchEnforce = input.dispatchEnforce;
 	for (const field of NUMBER_FIELDS) {
@@ -327,7 +383,11 @@ export function makeRoutes(ctx, config) {
 					return;
 				}
 				if (req.method === "GET") {
-					writeJson(res, 200, { values: snapshotOf(config) });
+					// Clean-context retry pump: HTTP handlers never run inside an
+					// HMR transaction, so an orchestration deferred by the nested
+					// rejection re-runs here (no-op when nothing is pending).
+					pumpTeamsOrchestration(ctx, config);
+					writeJson(res, 200, { values: snapshotOf(config), whitelistSync: whitelistSyncOf(config), teamsBundle: teamsBundleState() });
 					return;
 				}
 				if (req.method !== "POST") {
@@ -363,7 +423,14 @@ export function makeRoutes(ctx, config) {
 					writeJson(res, 500, { error: error?.message ?? String(error) });
 					return;
 				}
-				writeJson(res, 200, { values: snapshotOf(config) });
+				// Teams orchestration hook (fire-and-forget: the teams layer defers
+				// the real work to a setImmediate turn, so the bundle enable +
+				// optional whitelist replace-sync never block this response; a
+				// nested-HMR rejection is retried from the next clean trigger —
+				// see host/teams.js). Runs when EITHER switch is on (they are
+				// independent); each half gates itself inside the orchestration.
+				scheduleTeamsOrchestration(ctx, config);
+				writeJson(res, 200, { values: snapshotOf(config), whitelistSync: whitelistSyncOf(config), teamsBundle: teamsBundleState() });
 			},
 		},
 		{
@@ -379,6 +446,74 @@ export function makeRoutes(ctx, config) {
 				}
 			},
 		},
+		{
+			kind: "exact",
+			path: ROUTES.authorized,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				try {
+					const snapshot = authorizedChildRoutes(ctx);
+					writeJson(
+						res,
+						200,
+						snapshot === null
+							? { enabled: null, routes: null }
+							: { enabled: snapshot.enabled, routes: snapshot.routes },
+					);
+				} catch (error) {
+					ctx.logger.warn(`dsh-switchman: authorized-models read failed: ${error?.message ?? error}`);
+					writeJson(res, 500, { error: error?.message ?? String(error) });
+				}
+			},
+		},
+		{
+			kind: "exact",
+			path: ROUTES.handoverState,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				// Read-only live registry: the client badge polls this during
+				// the otherwise-silent fork+compact window ({count, handovers}),
+				// so the GUI shows an animated "handover in progress" cue.
+				const handovers = handoverSnapshot();
+				writeJson(res, 200, { count: handovers.length, handovers });
+			},
+		},
+		{
+			kind: "exact",
+			path: ROUTES.visionState,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				pumpTeamsOrchestration(ctx, config); // clean-context retry pump (see GET config)
+				try {
+					// Optional `session` query parameter (a child session id):
+					// judge image capability against THAT session's model
+					// instead of the root's (the root verdict misreported for
+					// children on a different route). A missing or unknown
+					// session falls back to the root verdict.
+					const session = new URL(req.url ?? "/", "http://localhost").searchParams.get("session");
+					writeJson(res, 200, await visionStateOf(ctx, config, typeof session === "string" && session !== "" ? session : null));
+				} catch (error) {
+					ctx.logger.warn(`dsh-switchman: vision-state read failed: ${error?.message ?? error}`);
+					writeJson(res, 500, { error: error?.message ?? String(error) });
+				}
+			},
+		},
+		{
+			kind: "exact",
+			path: ROUTES.uiLocale,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				let body;
+				try {
+					body = await readJsonBody(req);
+				} catch (error) {
+					writeJson(res, 400, { error: error?.message ?? String(error) });
+					return;
+				}
+				setReportedUiLocale(body?.locale);
+				writeJson(res, 200, { ok: true, locale: reportedUiLocale() });
+			},
+		},
 	];
 }
 

package/host/subagent-model.js

@@ -0,0 +1,147 @@
+/** dsh-switchman subagent model-visibility layer.
+ *
+ * Parent-side model annotation for delegation results: a `tools/post-execute`
+ * waterfall listener (registered exactly like host/lang.js's capture) watches
+ * the `subagent` / `subagent_fork` tools and, when the call succeeded, reads
+ * the child session's `modelSelection` projection through the `sessionQuery`
+ * service (`observeSession` — cold sessions resolve without activating the
+ * child) and appends one `model: provider/model@effort` line to the accepted
+ * result content. DSH's own UI shows a child's model nowhere, so this line is
+ * the only place the parent learns which model actually runs each child.
+ *
+ * Shapes verified against dsh 0.2.1-alpha.1 sources:
+ * - Tool result values: `{kind:"continuable", subagentId}` (background
+ *   continuable — subagentId IS the durable child session id,
+ *   subagents.startContinuable's childId), `{kind:"foreground", runId,
+ *   output}` (SubagentRun.id equals the published child session id for local
+ *   providers; remote providers mint parent-namespaced ids, which simply fail
+ *   the cold read and pass through unannotated), and `{kind:"background",
+ *   jobId}` (a jobs id, not a session id — skipped).
+ * - `PostToolDecision` accept: `content` replaces the model-visible content
+ *   and cannot coexist with a `value` replacement (the runtime throws on
+ *   both), so only value-less accepts gain the line. `next()` is always
+ *   awaited first and its decision passed through untouched otherwise —
+ *   best-effort fail-open: an unreadable child projection means no
+ *   annotation, never an altered result.
+ */
+
+/** Child session id out of one subagent tool result value; null for shapes
+ *  without a session id (one-shot background jobs) or malformed values. */
+function childSessionIdOf(value) {
+	if (value === null || typeof value !== "object") return null;
+	if (value.kind === "continuable" && typeof value.subagentId === "string" && value.subagentId !== "")
+		return value.subagentId;
+	if (value.kind === "foreground" && typeof value.runId === "string" && value.runId !== "")
+		return value.runId;
+	return null;
+}
+
+/** Release one observation lease (explicit-resource-management protocol; both
+ *  the native Symbol.dispose and the TS-downlevel Symbol.for key are tried).
+ *  Prepared cuts pin an LRU cache entry, so a dropped lease would leak. */
+function disposeObservation(observation) {
+	if (observation === null || observation === undefined) return;
+	for (const key of [Symbol.dispose, Symbol.for("Symbol.dispose")]) {
+		const dispose = key === undefined ? undefined : observation[key];
+		if (typeof dispose === "function") {
+			try {
+				dispose.call(observation);
+			} catch {
+				/* lease release is best-effort */
+			}
+			return;
+		}
+	}
+}
+
+/**
+ * The effective model selection of one session, via the session-query
+ * observeSession channel (shared with host/vision.js's per-session verdict).
+ * @param {import("@deepseek-ai/cordis").Context} ctx - host plugin context.
+ * @param {string} sessionId - session id (live or persisted).
+ * @returns {Promise<{provider: string, model: string, reasoningEffort?: string} | null>}
+ *          null when the session is unknown, unreadable, or unselected yet.
+ */
+async function sessionModelSelectionOf(ctx, sessionId) {
+	if (typeof sessionId !== "string" || sessionId === "") return null;
+	let query;
+	try {
+		query = ctx.get?.("sessionQuery", false);
+	} catch {
+		return null;
+	}
+	if (query === undefined || query === null || typeof query.observeSession !== "function") return null;
+	let observation = null;
+	try {
+		observation = await query.observeSession(sessionId);
+		const selection = observation?.projections?.values?.modelSelection;
+		const route = selection?.next ?? selection?.lastUsed; // next already falls back to lastUsed
+		if (route === null || typeof route !== "object") return null;
+		if (typeof route.provider !== "string" || route.provider === "" || typeof route.model !== "string" || route.model === "")
+			return null;
+		return typeof route.reasoningEffort === "string" && route.reasoningEffort !== ""
+			? { provider: route.provider, model: route.model, reasoningEffort: route.reasoningEffort }
+			: { provider: route.provider, model: route.model };
+	} catch {
+		return null;
+	} finally {
+		disposeObservation(observation);
+	}
+}
+
+/** The appended annotation line, or null when the child's model is unknown. */
+function modelLineOf(selection) {
+	if (selection === null || typeof selection !== "object") return null;
+	const effort =
+		typeof selection.reasoningEffort === "string" && selection.reasoningEffort !== ""
+			? `@${selection.reasoningEffort}`
+			: "";
+	return `model: ${selection.provider}/${selection.model}${effort}`;
+}
+
+/** Await the downstream decision, then append the annotation line to a
+ *  value-less accept decision only. A next() rejection propagates (the
+ *  pipeline's own containment turns it into an error result); a failure in
+ *  the annotation logic after next() settled degrades to the untouched
+ *  decision — never a lost or re-run outcome. */
+async function annotate(ctx, exec, result, next, warn) {
+	const downstream = await next();
+	try {
+		if (downstream === null || typeof downstream !== "object" || downstream.kind !== "accept") return downstream;
+		// A value-replacing accept cannot also carry content (the runtime
+		// throws "cannot replace both value and content").
+		if (Object.hasOwn(downstream, "value")) return downstream;
+		const sessionId = childSessionIdOf(result?.value);
+		if (sessionId === null) return downstream;
+		const line = modelLineOf(await sessionModelSelectionOf(ctx, sessionId));
+		if (line === null) return downstream; // projection not ready/known — passthrough
+		const base = Array.isArray(downstream.content)
+			? downstream.content
+			: Array.isArray(result?.content)
+				? result.content
+				: [];
+		if (base.length === 0) return downstream; // nothing rendered to append to — never fabricate content
+		return { ...downstream, content: [...base, { type: "text", text: line }] };
+	} catch (error) {
+		// next() already settled — pass its decision through untouched (a
+		// failed annotation must never alter or fabricate an outcome).
+		warn(`subagent model annotation failed: ${error?.message ?? error}`);
+		return downstream;
+	}
+}
+
+/**
+ * Mount the subagent model-visibility layer (one post-execute listener).
+ * @param {import("@deepseek-ai/cordis").Context} ctx - host plugin context.
+ */
+function applySubagentModel(ctx) {
+	const warn = (message) => ctx.logger?.warn?.(`dsh-switchman: ${message}`);
+	ctx.on("tools/post-execute", (exec, result, next) => {
+		// Fast path: every non-subagent tool and every failed call stays
+		// exactly on the current pipeline (promise pass-through).
+		if ((exec?.name !== "subagent" && exec?.name !== "subagent_fork") || result?.isError === true) return next();
+		return annotate(ctx, exec, result, next, warn);
+	});
+}
+
+export { applySubagentModel, sessionModelSelectionOf };

package/host/subagents.js

@@ -0,0 +1,160 @@
+/** Enumeration of this session's dispatched background subagents.
+ *
+ * Why this exists: a context handover (compaction) preserves dispatched
+ * background subagents — they keep running. The parent's job registries
+ * never list continuable children, and while the Agent-Teams bundle is
+ * active send_message resolves teammate names only, so subagent-child
+ * ids cannot be addressed mid-run. An agent that mistakes "not
+ * addressable" for "dead" then double-dispatches. Recording the live
+ * children — plus how to read their state — into the handover document
+ * closes that gap.
+ *
+ * Redesign after the 2026-10-05 double-dispatch incident: dispatches
+ * issued in the turn that triggered the handover MATERIALIZE only when
+ * the session machinery resumes — the catalog entry and the child's
+ * session record are stamped minutes after the dispatching tool call,
+ * which was after the handover's own snapshot in the old flow. Neither
+ * the sanctioned registry nor the disk catalog could have listed them
+ * at snapshot time; the fix is timing (context-watch.js re-enumerates
+ * after compaction settles, immediately before waking the session) plus
+ * semantics: enumeration now answers "what dispatched work exists",
+ * never filters on a single "running" flag. A dispatched child whose
+ * record exists but has neither an open step nor a definite end
+ * boundary is PENDING work (queued / provisioning / interrupted) —
+ * exactly the state the incident's children were missed in.
+ *
+ * Disk format (verified against a packaged host's live records under
+ * <DSH_HOME>/storages/session_projcache/sessions/):
+ *
+ * - Parent record `<sessionId>.json` (sessionId carries the `session-`
+ *   prefix) -> { record: { rows: { subagentCatalog: { val: { head:
+ *   { values: [{ childId, childCreatedAt, mode, label }, ...] } } } } } }
+ *   — the append-only catalog of every subagent dispatched from the
+ *   session (labels are the dispatch `description`); entries appear
+ *   when the child MATERIALIZES, not when the tool call is made.
+ * - Child record `<childId>.json` (bare UUID) — the same rows map:
+ *   running iff record.rows.sessionStats.val.openStep is neither null
+ *   nor missing;
+ *   settled (delivered/aborted, nothing pending) iff
+ *   record.rows.turnBoundary.val.lastStepBoundary.kind === "end";
+ *   anything else with an existing record is pending.
+ *
+ * Every failure mode is fail-open to [] — enumeration is advisory
+ * context for the handover document, never a blocker. */
+
+/** Child states, in rough order of "how much work is outstanding".
+ * - "running": an open step exists right now.
+ * - "pending": dispatched (record exists) but no definite end — covers
+ *   queued/provisioning children and ones interrupted mid-flight.
+ * - "settled": last step boundary is a definite end; the child
+ *   delivered (or aborted) and holds no pending work.
+ * - "gone": no record — never materialized or pruned; not live work. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { dshHome } from "./lib/dsh-home.js";
+
+/** Parse one session-projcache record into its rows map, or null on any
+ * structural surprise (missing file, bad JSON, unexpected shape). */
+function readRows(path) {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		const rows = parsed?.record?.rows;
+		return rows !== null && typeof rows === "object" ? rows : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Directory holding the session-projcache records (advisory text). */
+export function sessionRecordsDir() {
+	return join(dshHome(), "storages", "session_projcache", "sessions");
+}
+
+/** Absolute path of one session's projcache record — advisory text for
+ * handover documents, so recorded collection paths honor DSH_HOME the
+ * same way the enumeration lookups do. */
+export function sessionRecordPath(id) {
+	return join(sessionRecordsDir(), `${id}.json`);
+}
+
+/** Candidate file names for a session record: the observed convention is
+ * `session-<uuid>.json` for conversation sessions and `<uuid>.json` for
+ * subagent children, but probing both keeps the lookup robust. */
+function recordPaths(directory, id) {
+	const names = new Set([`${id}.json`]);
+	const bare = id.replace(/^session-/u, "");
+	if (bare !== id) names.add(`${bare}.json`);
+	else names.add(`session-${id}.json`);
+	return [...names].map((name) => join(directory, name));
+}
+
+/** First parseable rows map for a session id, or null. */
+function rowsOf(directory, id) {
+	return recordPaths(directory, id).map((path) => readRows(path)).find((rows) => rows !== null) ?? null;
+}
+
+/** Disk state of one child from its rows map (see the state table in the
+ * header). A null record means "gone". */
+function childDiskState(childRows) {
+	if (childRows === null) return "gone";
+	if (childRows.sessionStats?.val?.openStep != null) return "running";
+	if (childRows.turnBoundary?.val?.lastStepBoundary?.kind === "end") return "settled";
+	return "pending";
+}
+
+/** Every cataloged child of a session with its disk state:
+ * [{ id, label, mode, childCreatedAt, state }]. The catalog is the
+ * authoritative "was ever dispatched" list; states come from each
+ * child's own record. Empty on any error — never throws. */
+export function catalogChildrenOf(sessionId) {
+	if (typeof sessionId !== "string" || sessionId === "") return [];
+	const directory = sessionRecordsDir();
+	const parentRows = rowsOf(directory, sessionId);
+	const entries = parentRows?.subagentCatalog?.val?.head?.values;
+	if (!Array.isArray(entries)) return [];
+	const children = [];
+	for (const entry of entries) {
+		if (entry === null || typeof entry !== "object") continue;
+		const childId = entry.childId;
+		if (typeof childId !== "string" || childId === "") continue;
+		const state = childDiskState(rowsOf(directory, childId));
+		children.push({
+			id: childId,
+			label: typeof entry.label === "string" ? entry.label : "",
+			mode: typeof entry.mode === "string" ? entry.mode : "",
+			childCreatedAt: typeof entry.childCreatedAt === "number" ? entry.childCreatedAt : null,
+			state,
+		});
+	}
+	return children;
+}
+
+/** Live (unresolved) dispatched children of a session as
+ * [{ id, label, mode, childCreatedAt, state }|{…, state: "running"}] —
+ * running OR pending, disk truth first. The sanctioned agents registry,
+ * when reachable, only ever UPGRADES a pending child to "running" (its
+ * live view has no flush lag); it can never demote disk truth, because
+ * a status vocabulary mismatch is precisely what missed the incident's
+ * queued children. Never throws. */
+export async function enumerateLiveSubagents(ctx, sessionId) {
+	if (typeof sessionId !== "string" || sessionId === "") return [];
+	let live;
+	try {
+		live = catalogChildrenOf(sessionId).filter((child) => child.state === "running" || child.state === "pending");
+	} catch {
+		return [];
+	}
+	if (live.length === 0) return [];
+	try {
+		const agents = typeof ctx?.get === "function" ? ctx.get("agents") : null;
+		if (agents !== null && typeof agents.get === "function") {
+			for (const child of live) {
+				if (child.state !== "pending") continue;
+				if (agents.get(child.id)?.status === "running") child.state = "running";
+			}
+		}
+	} catch {
+		/* registry overlay is best-effort */
+	}
+	return live;
+}