dsh-llm-fallbacks 0.6.5 → 0.6.7

package/dist/index.js

@@ -1,6 +1,8 @@
 import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
 import { LlmAdapter, LlmError, boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm";
+import { randomUUID } from "node:crypto";
+import { PERSONA_PREFIX_SECTION } from "@deepseek-ai/dsh-system-prompt";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 //#region .build/host/selectors.js
 var SelectorError = class extends Error {
@@ -695,6 +697,11 @@ async function resolveRoleAtDispatch(agent, rules, roleIds, opts) {
 		const declared = roleIds.get(preset);
 		if (declared !== void 0) return declared;
 	}
+	const dispatch = opts.dispatchRole?.trim();
+	if (dispatch !== void 0 && dispatch !== "" && dispatch !== "inherit") {
+		const declared = roleIds.get(dispatch);
+		if (declared !== void 0) return declared;
+	}
 	const role = resolveRole(agent, rules, roleIds, opts.warn, opts.servedRoute);
 	if (role !== "inherit") return role;
 	if (opts.automatchEnabled && opts.automatch !== void 0) {
@@ -828,7 +835,7 @@ function buildRoleNotice(role, personaNotApplied) {
 		}
 	});
 }
-function errorMessage$2(error) {
+function errorMessage$3(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 function installRoleNotice(ctx, options) {
@@ -855,7 +862,7 @@ function installRoleNotice(ctx, options) {
 				messages: [...decision.messages, notice]
 			};
 		} catch (error) {
-			debug(`llm-fallbacks: role notice for agent "${agent.id}" skipped (contained, the step is unchanged): ${errorMessage$2(error)}`);
+			debug(`llm-fallbacks: role notice for agent "${agent.id}" skipped (contained, the step is unchanged): ${errorMessage$3(error)}`);
 			return decision;
 		}
 	}, { prepend: true });
@@ -863,6 +870,9 @@ function installRoleNotice(ctx, options) {
 //#endregion
 //#region .build/host/role-projection-key.js
 const ROLE_PROJECTION_KEY = "fallbacksSubagentRole";
+function readRoleProjectionValue(value) {
+	return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
 const ROLE_STATE_SCHEMA = { parse(value) {
 	if (value === null) return null;
 	if (typeof value === "object") {
@@ -942,7 +952,7 @@ const roleProjectionUnit = {
 		view: (state) => state === null ? null : state.role ?? null
 	}
 };
-function errorMessage$1(error) {
+function errorMessage$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 function installRoleProjection(ctx, options = {}) {
@@ -962,12 +972,12 @@ function installRoleProjection(ctx, options = {}) {
 				}
 				return registry.register(roleProjectionUnit);
 			} catch (error) {
-				debug(`llm-fallbacks: role projection not registered (contained): ${errorMessage$1(error)}`);
+				debug(`llm-fallbacks: role projection not registered (contained): ${errorMessage$2(error)}`);
 				return () => {};
 			}
 		});
 	} catch (error) {
-		debug(`llm-fallbacks: role projection install skipped (contained): ${errorMessage$1(error)}`);
+		debug(`llm-fallbacks: role projection install skipped (contained): ${errorMessage$2(error)}`);
 	}
 	return () => {
 		try {
@@ -1066,7 +1076,7 @@ function parentSessionIdOf(request) {
 function correlationKey(parentSessionId, label) {
 	return `${parentSessionId}\u0000${label}`;
 }
-function errorMessage(error) {
+function errorMessage$1(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 const subagentSeamStores = new WeakMap();
@@ -1082,6 +1092,9 @@ function seamStateFor(root) {
 	return created;
 }
 const subagentSeamRoots = new WeakSet();
+function subagentSeamOf(ctx) {
+	return subagentSeamStores.get(ctx);
+}
 function installSubagentSeam(ctx, options) {
 	const root = ctx.root;
 	const state = seamStateFor(root);
@@ -1100,20 +1113,20 @@ function installSubagentSeam(ctx, options) {
 		} catch {}
 	};
 	const reportDegrade = (error) => {
-		debug(`llm-fallbacks: subagent role seam degraded to the native path (start unaffected): ${errorMessage(error)}`);
+		debug(`llm-fallbacks: subagent role seam degraded to the native path (start unaffected): ${errorMessage$1(error)}`);
 	};
-	const recordChild = (childSessionId, role, at, personaNotApplied) => {
-		const existing = records.get(childSessionId);
-		records.set(childSessionId, {
+	const recordChild = (childId, role, at, personaMissed) => {
+		const existing = records.get(childId);
+		records.set(childId, {
 			role,
 			at,
 			firstNoticePending: existing?.firstNoticePending ?? true,
-			...personaNotApplied || existing?.personaNotApplied === true ? { personaNotApplied: true } : {}
+			...existing?.personaNotApplied === true || personaMissed === true ? { personaNotApplied: true } : {}
 		});
 	};
-	const beginCorrelation = (request, role, personaNotApplied) => {
-		const parentSessionId = parentSessionIdOf(request);
-		const label = typeof request?.label === "string" ? request.label : void 0;
+	const beginCorrelation = (spec, role, at) => {
+		const parentSessionId = parentSessionIdOf(spec?.request);
+		const label = typeof spec?.label === "string" ? spec.label : void 0;
 		if (parentSessionId === void 0 || label === void 0 || label === "") return void 0;
 		const key = correlationKey(parentSessionId, label);
 		if (!pending.has(key) && pending.size >= 64) {
@@ -1123,8 +1136,7 @@ function installSubagentSeam(ctx, options) {
 		pending.delete(key);
 		pending.set(key, {
 			role,
-			at: Date.now(),
-			personaNotApplied
+			at
 		});
 		return key;
 	};
@@ -1168,68 +1180,13 @@ function installSubagentSeam(ctx, options) {
 		}
 		onValue(result);
 	};
-	const personaGate = (service, providerName, surface) => {
-		if (typeof service.getProvider !== "function") return "unavailable";
-		const provider = service.getProvider(providerName);
-		if (provider === void 0) return "unknown";
-		if (surface === "one-shot") return provider.capabilities?.persona === true ? "ok" : "unsupported";
-		return typeof provider.prepareContinuable === "function" ? "ok" : "unsupported";
-	};
-	const withRolePersona = (service, providerName, request, role, surface) => {
-		if (request.persona !== void 0) return {
-			request,
-			personaNotApplied: false
-		};
-		const readRoles = options.roles;
-		if (readRoles === void 0) return {
-			request,
-			personaNotApplied: false
-		};
-		const persona = personaForRole(readRoles(), role);
-		if (persona === void 0) return {
-			request,
-			personaNotApplied: false
-		};
-		const gate = personaGate(service, providerName, surface);
-		if (gate === "unknown") {
-			debug(`llm-fallbacks: no subagent provider '${providerName}' is registered on the ${surface} start — role persona for '${role}' not delivered (the native start fails loud its own way)`);
-			return {
-				request,
-				personaNotApplied: true
-			};
-		}
-		if (gate === "unavailable") {
-			debug(`llm-fallbacks: role persona for '${role}' skipped on the ${surface} start — the '${SUBAGENT_SEAM_SERVICE}' runtime exposes no provider lookup, so the persona capability cannot be verified (the start proceeds unchanged)`);
-			return {
-				request,
-				personaNotApplied: true
-			};
-		}
-		if (gate === "unsupported") {
-			debug(surface === "one-shot" ? `llm-fallbacks: subagent provider '${providerName}' lacks the persona capability on the ${surface} start — role persona for '${role}' skipped (the start proceeds unchanged)` : `llm-fallbacks: subagent provider '${providerName}' does not support continuable children on the ${surface} surface — role persona for '${role}' skipped (the native continuable start fails loud its own way)`);
-			return {
-				request,
-				personaNotApplied: true
-			};
-		}
-		debug(`llm-fallbacks: role persona delivered via the native subagent persona channel for role '${role}' (${surface} start on provider '${providerName}')`);
-		return {
-			request: {
-				...request,
-				persona
-			},
-			personaNotApplied: false
-		};
-	};
-	const mergePersonaAtSeam = (service, providerName, request, role, surface) => {
+	const isLocalBackend = (service, providerName) => {
 		try {
-			return withRolePersona(service, providerName, request, role, surface);
+			if (typeof service.getProvider !== "function") return false;
+			return typeof service.getProvider(providerName)?.prepareContinuable === "function";
 		} catch (error) {
 			reportDegrade(error);
-			return {
-				request,
-				personaNotApplied: false
-			};
+			return false;
 		}
 	};
 	const wrapService = (value) => {
@@ -1241,61 +1198,71 @@ function installSubagentSeam(ctx, options) {
 			return value;
 		}
 		const service = value;
-		if (typeof service.start !== "function") {
+		if (typeof service.startActivation !== "function") {
 			if (!unreadableServiceLogged) {
 				unreadableServiceLogged = true;
-				debug(`llm-fallbacks: subagent role seam skipped — '${SUBAGENT_SEAM_SERVICE}' is not a start-capable runtime`);
+				debug(`llm-fallbacks: subagent role seam skipped — '${SUBAGENT_SEAM_SERVICE}' is not an activation-capable runtime`);
 			}
 			return value;
 		}
 		const cached = wrappers.get(value);
 		if (cached !== void 0) return cached;
 		const wrapper = Object.create(value);
-		wrapper.start = (name, request) => {
-			const role = resolveRoleAtSeam(request);
-			if (role === void 0) return service.start(name, request);
-			const persona = mergePersonaAtSeam(service, name, request, role, "one-shot");
+		wrapper.startActivation = (spec) => {
+			const role = resolveRoleAtSeam(spec?.request) ?? (typeof spec?.childId === "string" ? records.get(spec.childId)?.role : void 0);
+			if (role === void 0) return service.startActivation(spec);
+			const at = Date.now();
+			let effectiveSpec = spec;
+			let reservedId;
+			let reservationPersonaMissed;
+			try {
+				if (isLocalBackend(service, spec.provider)) {
+					reservedId = spec.childId ?? randomUUID();
+					if (reservedId !== spec.childId) effectiveSpec = {
+						...spec,
+						childId: reservedId
+					};
+					recordChild(reservedId, role, at);
+				}
+			} catch (error) {
+				if (reservedId !== void 0) records.delete(reservedId);
+				effectiveSpec = spec;
+				reservedId = void 0;
+				reportDegrade(error);
+				try {
+					reservationPersonaMissed = personaForRole(options.roles?.() ?? [], role) !== void 0;
+				} catch (personaError) {
+					reportDegrade(personaError);
+				}
+			}
 			let pendingKey;
 			try {
-				pendingKey = beginCorrelation(request, role, persona.personaNotApplied);
+				pendingKey = beginCorrelation(spec, role, at);
 			} catch (error) {
 				reportDegrade(error);
 			}
 			let result;
 			try {
-				result = service.start(name, persona.request);
+				result = service.startActivation(effectiveSpec);
 			} catch (error) {
 				endCorrelation(pendingKey);
+				if (reservedId !== void 0) records.delete(reservedId);
 				throw error;
 			}
 			try {
-				observeStartResult(result, (childSessionId) => {
+				observeStartResult(result, (childId) => {
+					endCorrelation(pendingKey);
+					recordChild(childId, role, at, reservationPersonaMissed);
+				}, () => {}, () => {
 					endCorrelation(pendingKey);
-					recordChild(childSessionId, role, Date.now(), persona.personaNotApplied);
-				}, () => {}, () => endCorrelation(pendingKey));
+					if (reservedId !== void 0) records.delete(reservedId);
+				});
 			} catch (error) {
 				endCorrelation(pendingKey);
 				reportDegrade(error);
 			}
 			return result;
 		};
-		const startContinuable = service.startContinuable;
-		if (typeof startContinuable === "function") wrapper.startContinuable = (spec) => {
-			const role = resolveRoleAtSeam(spec?.request) ?? (typeof spec?.childId === "string" ? records.get(spec.childId)?.role : void 0);
-			if (role === void 0) return startContinuable.call(service, spec);
-			const outcome = mergePersonaAtSeam(service, spec.provider, spec.request, role, "continuable");
-			const effectiveSpec = outcome.request === spec.request ? spec : {
-				...spec,
-				request: outcome.request
-			};
-			const result = startContinuable.call(service, effectiveSpec);
-			try {
-				observeStartResult(result, (childSessionId) => recordChild(childSessionId, role, Date.now(), outcome.personaNotApplied), () => {}, () => {});
-			} catch (error) {
-				reportDegrade(error);
-			}
-			return result;
-		};
 		wrappers.set(value, wrapper);
 		return wrapper;
 	};
@@ -1322,7 +1289,7 @@ function installSubagentSeam(ctx, options) {
 				const claim = pending.get(key);
 				if (claim === void 0) return;
 				pending.delete(key);
-				recordChild(childSessionId, claim.role, claim.at, claim.personaNotApplied);
+				recordChild(childSessionId, claim.role, claim.at);
 			} catch (error) {
 				reportDegrade(error);
 			}
@@ -1347,6 +1314,96 @@ function installSubagentSeam(ctx, options) {
 	return seam;
 }
 //#endregion
+//#region .build/host/role-persona.js
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+const rolePersonaStates = new WeakMap();
+function rolePersonaStateFor(root) {
+	const existing = rolePersonaStates.get(root);
+	if (existing !== void 0) return existing;
+	const created = new Map();
+	rolePersonaStates.set(root, created);
+	return created;
+}
+function installRolePersona(ctx, options) {
+	const root = ctx.root;
+	const registered = rolePersonaStateFor(root);
+	const owner = {};
+	const fibers = new Map();
+	const debug = (message) => {
+		try {
+			options.debug?.(message);
+		} catch {}
+	};
+	const contain = (agent, record, error) => {
+		debug(`llm-fallbacks: role persona for agent "${agent.id}" (role "${record.role}") not applied — contained, the child runs unchanged: ${errorMessage(error)}`);
+		record.personaNotApplied = true;
+	};
+	const release = (id) => {
+		const fiber = fibers.get(id);
+		if (fiber === void 0) return;
+		fibers.delete(id);
+		fiber.dispose().catch((error) => {
+			debug(`llm-fallbacks: role persona section for agent "${id}" not withdrawn (contained): ${errorMessage(error)}`);
+		});
+	};
+	const installPersona = async (agent) => {
+		const record = options.records.get(agent.id);
+		if (record === void 0) return;
+		if (registered.has(agent.id)) return;
+		let persona;
+		try {
+			persona = personaForRole(options.roles(), record.role);
+		} catch (error) {
+			debug(`llm-fallbacks: role persona for agent "${agent.id}" not resolved — contained, the child runs unchanged: ${errorMessage(error)}`);
+			return;
+		}
+		if (persona === void 0) return;
+		const text = persona;
+		registered.set(agent.id, owner);
+		try {
+			const fiber = agent.ctx.inject(["systemPrompt"], (scope) => {
+				try {
+					scope.systemPrompt.section({
+						name: PERSONA_PREFIX_SECTION,
+						order: scope.systemPrompt.getSectionOrder("DEPLOYMENT_PERSONA_PREFIX"),
+						text
+					});
+				} catch (error) {
+					if (error instanceof Error && error.message === `prompt section "${PERSONA_PREFIX_SECTION}" is already registered in this scope`) {
+						debug(`llm-fallbacks: role persona for agent "${agent.id}" not installed — a section named "${PERSONA_PREFIX_SECTION}" already exists in its scope: ${errorMessage(error)}`);
+						return;
+					}
+					contain(agent, record, error);
+				}
+			});
+			fibers.set(agent.id, fiber);
+			await fiber;
+		} catch (error) {
+			release(agent.id);
+			contain(agent, record, error);
+		}
+	};
+	const disposers = [];
+	disposers.push(ctx.on("agent/created", async ({ agent }) => {
+		await installPersona(agent);
+	}));
+	disposers.push(ctx.on("agent/disposed", ({ agent }) => {
+		release(agent.id);
+		registered.delete(agent.id);
+	}));
+	const agents = ctx.get("agents");
+	if (typeof agents?.list === "function") for (const agent of agents.list()) installPersona(agent);
+	const dispose = () => {
+		for (const off of disposers.splice(0)) off();
+		for (const id of [...fibers.keys()]) release(id);
+		for (const [id, holder] of [...registered]) if (holder === owner) registered.delete(id);
+	};
+	ctx.effect(() => dispose, "llm-fallbacks: role persona listener");
+	return { dispose };
+}
+//#endregion
 //#region .build/host/cooldown.js
 var CooldownStore = class {
 	entries = new Map();
@@ -3088,7 +3145,8 @@ function apply(ctx, config = defaultFallbacksConfig) {
 				detectLegacyKeys,
 				declareSeeds: (declarations, options) => seeds.declare(declarations, seedsIo, options?.set === void 0 ? void 0 : { set: options.set }),
 				getEffectiveRoles: () => seeds.effectiveRoles(seedsIo),
-				revertSeededPersona: (id) => seeds.revert(id, seedsIo)
+				revertSeededPersona: (id) => seeds.revert(id, seedsIo),
+				getAgentRole: (agentId) => subagentSeamOf(ctx)?.records.get(agentId)?.role ?? null
 			});
 			serviceOwned = true;
 		} catch (error) {
@@ -3151,6 +3209,11 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		debug: (message) => logger.debug(message)
 	});
 	if (!subagentSeam.ownsWrapper) ctx.logger("llm-fallbacks").debug("subagent role seam wrapper already installed on this context root — this fiber registers the notice emitter and the projection unit only (multi-fiber dedupe)");
+	installRolePersona(ctx, {
+		records: subagentSeam.records,
+		roles: () => source().roles.list,
+		debug: (message) => logger.debug(message)
+	});
 	try {
 		new FallbacksConfigGateway(ctx, bridge, seeds, () => {
 			try {
@@ -3345,6 +3408,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 						const role = await resolveRoleAtDispatch(agent, config.roles.rules, roleIds, {
 							automatchEnabled: config.roleAutoMatch ?? true,
 							automatch: (agent) => pickRoleByLlm(ctx, config.roles, agent, { warn: logger.warn }),
+							dispatchRole: subagentSeam.records.get(agent.id)?.role,
 							warn: logger.warn,
 							servedRoute: servedRouteFor(agent, config)
 						});
@@ -3513,4 +3577,4 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	});
 }
 //#endregion
-export { Config, FallbacksSeedManager, INHERIT_ROLE_ID, ROLE_ID_PATTERN, SelectorError, annotateCandidates, apply, blockedAttempts, chainHeads, countRetryEvents, createCandidateFilter, defaultFallbacksConfig, detectLegacyKeys, hasWildcardEntry, name, parseSelector, presetRoles, provide, resolveCandidate, resolveChain, resolveChainViews, resolveRole, selectCandidates, stateStore, validateFallbacksConfig };
+export { Config, FallbacksSeedManager, INHERIT_ROLE_ID, ROLE_ID_PATTERN, ROLE_PROJECTION_KEY, SelectorError, annotateCandidates, apply, blockedAttempts, chainHeads, countRetryEvents, createCandidateFilter, defaultFallbacksConfig, detectLegacyKeys, hasWildcardEntry, name, parseSelector, presetRoles, provide, readRoleProjectionValue, resolveCandidate, resolveChain, resolveChainViews, resolveRole, selectCandidates, stateStore, validateFallbacksConfig };

package/dist/role-persona.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Role-persona delivery over `agent/created` (plan dsh-021-subagent-seam-repair
+ * Task 1).
+ *
+ * rc.1 removed `SubagentStartRequest.persona`, so the resolved dispatch role's
+ * persona is delivered as a SCOPED system-prompt section on the CHILD's own
+ * context — the shipped `file-reference-local` pattern (no request mutation, no
+ * provider capability gate, no Agent Preset). The section carries the SAME name
+ * and order the global deployment persona uses (`SystemPrompt.section`: a
+ * scoped section shadows a global section with the same name), so the child's
+ * persona REPLACES the deployment prefix instead of stacking under it — the
+ * semantics the removed request slot had.
+ *
+ * Timing: `agent/created` is a serial event awaited before the child's first
+ * prompt assembly, and this listener AWAITS the injected section fiber: cordis
+ * activates a child fiber on a later tick, so awaiting it is what makes the
+ * persona observable by the time the dispatch resolves (the shipped
+ * `file-reference-local` shape). The seam's `agent/pre-step` notice emitter
+ * therefore always observes a child whose persona section is already
+ * registered; both surfaces read the SAME ROOT-shared record map, which is what
+ * keeps the ` (persona not applied)` suffix truthful.
+ *
+ * Ownership: the injected fiber belongs to the CHILD's scope, so it does not
+ * die with this listener's fiber — each listener holds ITS OWN fibers per agent
+ * and releases them on `agent/disposed`, on plugin-fiber teardown, and on
+ * explicit `dispose()`. The root-shared claim that dedupes sibling listeners
+ * records which listener owns it, so one installer's teardown never releases
+ * another's fibers or claims, and a repeated notification never replaces the
+ * handle to the fiber that holds the live registration.
+ *
+ * Containment (the seam's degrade-never-crash invariant, and required here
+ * because a throwing serial `agent/created` listener fails agent creation):
+ * only an agent whose id hits the shared record map is touched (a miss is a
+ * silent no-op), the registry's exact same-name SCOPED section duplicate means
+ * a persona section is already on that scope (one attribution-free debug line,
+ * no verdict — the registry cannot say who registered it), and every other
+ * throw — including a failed fiber activation — is contained to ONE debug line
+ * plus the record's sticky `personaNotApplied`.
+ *
+ * @module dsh-llm-fallbacks/role-persona
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SubagentSeamRecord } from './subagents-seam.ts';
+import type { FallbacksRole } from './config.ts';
+/** Options for {@link installRolePersona}. */
+export interface RolePersonaOptions {
+    /**
+     * The seam's ROOT-shared per-child records — the SAME map the notice
+     * emitter reads; the listener writes `personaNotApplied` verdicts back
+     * into it (sticky per the existing {@link SubagentSeamRecord} contract).
+     */
+    records: Map<string, SubagentSeamRecord>;
+    /** Live declared roles (`roles.list`) — the persona source, read per agent/created. */
+    roles: () => readonly FallbacksRole[];
+    /** Contained debug sink (at most one line per contained degrade). */
+    debug?: (message: string) => void;
+}
+/** The installed listener surface (explicit teardown; fiber teardown also stops it). */
+export interface RolePersona {
+    dispose(): void;
+}
+/**
+ * Install the role-persona listener on `ctx`: register the resolved role's
+ * persona as a scoped `deployment:persona-prefix` section on every created
+ * agent whose id hits the shared record map, plus a `agents.list()` backfill
+ * for children that already exist at install time.
+ *
+ * Returns the installed listener (its `dispose` withdraws this listener's OWN
+ * registrations; a fiber teardown stops it as well).
+ */
+export declare function installRolePersona(ctx: Context, options: RolePersonaOptions): RolePersona;

package/dist/role-resolution.d.ts

@@ -1,17 +1,23 @@
 /**
- * Dispatch-time three-stage role resolution (plan fallbacks-role-automatch
- * Task 2).
+ * Dispatch-time role resolution (plan fallbacks-role-automatch Task 2; the
+ * dispatch-role stage added by plan dsh-148-agent-team-role-delivery Task 1).
  *
- * Precedence (first hit wins):
+ * Precedence (first hit wins) across four ordered stages:
  * 1. explicit — `session.header.agentPreset` trimmed matches a declared role
  *    id → that role's DECLARED RAW id (via the `roleIds` trimmed-id map, the
  *    same canonicalization the rules path uses); the reserved `'inherit'`
  *    and undeclared presets are NEVER dispatchable explicit roles and fall
- *    through to rules;
- * 2. rules — the existing `resolveRole` passthrough, unchanged (a declared
+ *    through to the next stage;
+ * 2. dispatch — `opts.dispatchRole`: the role the dispatch seam resolved from
+ *    the Assignment/teammate prompt (`**Execute as**: <id>`, the single
+ *    parser in `src/subagents-seam.ts`), canonicalized by the same trim +
+ *    `roleIds` lookup. An absent, empty, `'inherit'` or no-longer-declared
+ *    reference falls through silently — a role removed after the dispatch is
+ *    not an error;
+ * 3. rules — the existing `resolveRole` passthrough, unchanged (a declared
  *    role wins; no-rule-match / an explicit rule targeting `'inherit'`
  *    resolve to `'inherit'`);
- * 3. auto-match — only when stage 2 resolved to `'inherit'` AND
+ * 4. auto-match — only when stage 3 resolved to `'inherit'` AND
  *    `opts.automatchEnabled`: call `opts.automatch` with the agent. The hook
  *    (Task 3 supplies the bounded LLM caller) MUST return a declared raw id
  *    or `null`; the resolver defensively validates the return against
@@ -35,10 +41,16 @@ import type { Selector } from './selectors.ts';
 export type { FallbacksRoleRule } from './config.ts';
 /** Options for {@link resolveRoleAtDispatch}. */
 export interface ResolveRoleAtDispatchOptions {
+    /**
+     * Dispatch-declared role: the DECLARED RAW id the seam resolved from the
+     * Assignment/teammate prompt (`**Execute as**: <id>`). Validated against the
+     * live `roleIds` map; absent, `inherit`, or no-longer-declared → skipped.
+     */
+    dispatchRole?: string;
     /**
      * Whether the auto-match stage may run (the `roleAutoMatch` config switch).
-     * When `false`, stage 3 never runs and the outcome is identical to the
-     * rules stage alone.
+     * When `false`, stage 4 never runs and the outcome is identical to the
+     * explicit/dispatch/rules stages alone.
      */
     automatchEnabled: boolean;
     /**
@@ -64,10 +76,11 @@ export interface ResolveRoleAtDispatchOptions {
     };
 }
 /**
- * Resolve the dispatch-time role for an agent across three ordered stages
- * (explicit → rules → auto-match hook). Never throws on its own inputs; the
- * hook's own rejection is deliberately NOT caught here (the Task-3/4 wiring
- * bounds the LLM call so it never throws out of the request path).
+ * Resolve the dispatch-time role for an agent across four ordered stages
+ * (explicit → dispatch → rules → auto-match hook). Never throws on its own
+ * inputs; the hook's own rejection is deliberately NOT caught here (the
+ * Task-3/4 wiring bounds the LLM call so it never throws out of the request
+ * path).
  *
  * `roleIds` is the canonical trimmed-id map (`trimmed id → declared raw id`,
  * built in `src/index.ts` apply()): every stage canonicalizes its reference

package/dist/roles.d.ts

@@ -3,10 +3,12 @@
  * Task 1).
  *
  * This module is the RULES stage. Dispatch-time role resolution
- * (plan fallbacks-role-automatch) is the three-stage resolver in
- * `role-resolution.ts` — explicit (`session.header.agentPreset`) → this
- * rules stage → an optional auto-match hook; `AgentLike` carries the additive
- * `session.header.agentPreset?` carrier for that explicit stage.
+ * (plan fallbacks-role-automatch; plan dsh-148 added the dispatch stage) is
+ * the four-stage resolver in `role-resolution.ts` — explicit
+ * (`session.header.agentPreset`) → dispatch-declared role (the seam record
+ * resolved from `**Execute as**`) → this rules stage → an optional auto-match
+ * hook; `AgentLike` carries the additive `session.header.agentPreset?`
+ * carrier for that explicit stage.
  *
  * Precedence (first hit wins):
  * 1. the first `rules` entry whose specified provider/model patterns match