dsh-switchman 1.7.0 → 1.8.0

package/host/config.js

@@ -12,6 +12,7 @@
  * - pool/rank    dispatch pools and capability ranking (Phase 2)
  * - wm*          context watermark control (Phase 3)
  * - teams*       Agent Teams doctrine mode + whitelist sync (teams mode)
+ * - intent*      intent-routing "auto" pseudo-model (classifier + candidates)
  *
  * Ported from opencode-switchman's opencode-switchman.jsonc surface
  * (oc/src/config.ts:23-51, oc/src/types.ts:281-344) onto DSH settings.
@@ -44,6 +45,34 @@ export const EffortEntrySchema = z.object({
 	effort: z.string().min(1).required(),
 });
 
+/** One intent-routing candidate: a real model route the classifier may pick,
+ *  plus an optional reasoning-effort pin and a capability note the classifier
+ *  reads. Every row carries a stable id; preset rows (id owned by
+ *  host/intent-presets.js) keep a code-owned immutable note, while enabled /
+ *  provider / model / effort are user-configured — provider/model may be
+ *  empty while a preset waits for its route. effort/note follow
+ *  RankEntrySchema.tier's optional style (no `.required()`: schemastery
+ *  passes undefined through, so entries may omit either key). */
+export const IntentCandidateSchema = z.object({
+	id: z.string(),
+	preset: z.boolean(),
+	enabled: z.boolean(),
+	provider: z.string(),
+	model: z.string(),
+	effort: z.string(),
+	note: z.string(),
+});
+
+/** One intent-layer route reference (classifier or fallback). Unlike
+ *  ModelRouteSchema this accepts the "unset" `{provider:"", model:""}`
+ *  pair the settings page round-trips — ModelRouteSchema's `.min(1)`
+ *  would reject that exact declared default on every settings write.
+ *  Consumers validate non-empty before trusting the route. */
+const IntentRouteSchema = z.object({
+	provider: z.string(),
+	model: z.string(),
+});
+
 /** All dsh-switchman settings. Field names are the settings mutation paths. */
 export const Config = z.object({
 	// --- Phase 0: UI locale ------------------------------------------------
@@ -99,13 +128,13 @@ export const Config = z.object({
 
 	// --- Phase 3: context watermark control --------------------------------
 	/** Soft watermark: advisory banner + delegation nudge (tokens). */
-	wmSoftTokens: z.number().min(1000).default(50000).volatile(),
+	wmSoftTokens: z.number().min(1000).default(80000).volatile(),
 	/** Hard watermark: read budget tightens, wrap-up advised (tokens). */
-	wmHardTokens: z.number().min(2000).default(90000).volatile(),
+	wmHardTokens: z.number().min(2000).default(120000).volatile(),
 	/** Force watermark: backup + compaction handover (tokens). */
-	wmForceTokens: z.number().min(3000).default(130000).volatile(),
+	wmForceTokens: z.number().min(3000).default(150000).volatile(),
 	/** Per-call read budget for read/glob/grep (tokens). */
-	wmReadBudgetTokens: z.number().min(200).default(1500).volatile(),
+	wmReadBudgetTokens: z.number().min(200).default(3000).volatile(),
 	/** Hard-tier behavior: cap reads and advise, or deny outright. */
 	wmDenyMode: z.union(["cap", "deny"]).default("cap").volatile(),
 	/** Force tier triggers backup + compaction automatically. */
@@ -132,6 +161,66 @@ export const Config = z.object({
 	 *  wholesale. The whitelist only applies to top-level sessions composed
 	 *  afterwards. */
 	syncWhitelist: z.boolean().default(false).volatile(),
+
+	// --- Intent recognition: classifier-routed "auto" model ----------------
+	/** Master switch for intent routing (design: .dsh-switchman/plans/
+	 *  intent-routing.md §2). The adapter stays mounted either way; OFF
+	 *  only hides the catalog entry (listModels returns [], the selector
+	 *  drops the empty group) — a session already on Auto routes through
+	 *  the documented fallback chain (routedCurrent → intentFallbackRoute
+	 *  → first candidate) with NO classifier call. */
+	intentEnabled: z.boolean().default(false).volatile(),
+	/** Small-model route that classifies the conversation against the
+	 *  candidates. Empty = unset; classification is skipped (fail-open). */
+	intentClassifierRoute: IntentRouteSchema.default({ provider: "", model: "" }).volatile(),
+	/** Optional reasoning-effort pin for the classifier call ("" = adapter
+	 *  default). */
+	intentClassifierEffort: z.string().default("").volatile(),
+	/** Classifier channel; must be an explicit choice. "chat" calls the
+	 *  intentClassifierRoute above through its provider's standard chat
+	 *  API with a strict-JSON instruction. "systemone" = direct HTTP to a
+	 *  hand-configured ollama /v1/systemone decision endpoint — no
+	 *  provider, uses intentClassifierEndpoint +
+	 *  intentClassifierSystemoneModel. */
+	intentClassifierKind: z.union(["chat", "systemone"]).default("chat").volatile(),
+	/** Full URL of the ollama /v1/systemone endpoint for kind "systemone"
+	 *  (e.g. http://127.0.0.1:11434/v1/systemone). Empty = unset; that
+	 *  kind fails open to the fallback chain. */
+	intentClassifierEndpoint: z.string().default("").volatile(),
+	/** Model name sent to the decision endpoint for kind "systemone"
+	 *  (free text, e.g. tev1:4b-mxfp8). Independent of the llm provider
+	 *  catalog — no provider registration needed. Empty = unset; that
+	 *  kind fails open to the fallback chain. */
+	intentClassifierSystemoneModel: z.string().default("").volatile(),
+	/** Independent candidate list the "auto" pseudo-model may route to (NOT
+	 *  poolMain). Each entry: {id, preset?, enabled?, provider, model,
+	 *  effort?, note?}; readers merge the built-in presets from
+	 *  host/intent-presets.js (see mergeIntentCandidates). */
+	intentCandidates: z.array(IntentCandidateSchema).default([]).volatile(),
+	/** Provider prompt-cache reuse window: while the current route stays
+	 *  below the switch-confidence threshold, keep it for this many
+	 *  seconds since the last applied routing. */
+	intentCacheTtlSeconds: z.number().min(0).default(300).volatile(),
+	/** Classifier confidence (0-100) required to leave the current model. */
+	intentSwitchConfidence: z.number().min(0).max(100).default(80).volatile(),
+	/** Classification-call budget in ms; timeout/abort fails open to the
+	 *  fallback chain. */
+	intentTimeoutMs: z.number().min(200).default(60000).volatile(),
+	/** Recent user/assistant messages fed to the classifier. */
+	intentHistoryMessages: z.number().min(1).max(20).default(6).volatile(),
+	/** Total character budget for that conversation excerpt. */
+	intentHistoryMaxChars: z.number().min(200).max(20000).default(2400).volatile(),
+	/** Context window (tokens) declared by the "auto" pseudo-model. Purely
+	 *  advisory metadata: drives the usage popover and the auto-compaction
+	 *  pressure math for sessions routed through Auto. While wmAutoHandover
+	 *  is on, the effective declared value is floored at
+	 *  ceil(wmForceTokens / 0.8) so the smooth handover always fires before
+	 *  the 0.8×-window auto-compaction (see effectiveContextWindow in
+	 *  host/intent.js). */
+	intentContextWindow: z.number().min(1024).default(200000).volatile(),
+	/** Optional last-resort route when the classifier fails and no previous
+	 *  routed model exists; empty = the first candidate. */
+	intentFallbackRoute: IntentRouteSchema.default({ provider: "", model: "" }).volatile(),
 });
 
 /** The six dispatch lanes, in display order. */

package/host/context-watch.js

@@ -4,11 +4,17 @@
  * src/index.ts:386-459 (banner rendering) and 2066-2110 (auto-handover with
  * its anti-deadlock lesson) onto DSH services:
  *
- * - One dynamic systemPrompt section 'switchman:watermark' (order 10500)
- *   renders the `[SWITCHMAN:WATERMARK]` banner from the live token meter
- *   (ctx.tokenMeter.measure(agent.session).totalTokens). Root sessions get
- *   the tiered banner (ok/soft/hard/force/paused); subagent sessions get a
- *   compact cap-aware banner. The text function is side-effect free.
+ * - KV-cache invariant: the systemPrompt section 'switchman:watermark'
+ *   (order 10500) carries only byte-stable protocol text (root/subagent
+ *   variants, no live numbers), so the request head never changes
+ *   mid-session; the live tier + bucketed used reading travel as the
+ *   'switchman:watermark' runtime context (ctx.systemPrompt.context,
+ *   order 300, required) — DSH renders contexts into the tail-appended
+ *   "Current runtime context" snapshot, which is emitted as a new trailing
+ *   user message only when its text changes, preserving the cached prefix
+ *   by construction. Root sessions get tiers ok (silent)/soft/hard/force
+ *   plus a static paused line; subagent sessions get soft/hard/force with
+ *   their own force cap. Both text functions are side-effect free.
  * - Read budget double gate: `tools/post-execute` accounts read/glob/grep/
  *   bash result text (~len/3.5 tokens) per session per turn; `tools/
  *   pre-execute` denies or caps read/glob/grep once the budget is exhausted
@@ -133,9 +139,9 @@ function isRoot(ctx, agent) {
 /** Live threshold snapshot from the volatile settings. */
 function readThresholds(config) {
 	return {
-		soft: readNumber(config.wmSoftTokens, 50000),
-		hard: readNumber(config.wmHardTokens, 90000),
-		force: readNumber(config.wmForceTokens, 130000),
+		soft: readNumber(config.wmSoftTokens, 80000),
+		hard: readNumber(config.wmHardTokens, 120000),
+		force: readNumber(config.wmForceTokens, 150000),
 	};
 }
 
@@ -150,64 +156,89 @@ function measureNow(ctx, agent) {
 	}
 }
 
-// ---- banner rendering (pure given state + measurement) ---------------------
+// ---- watermark rendering (pure given state + measurement) ------------------
 
-/** Root-session banner: byte-stable anchor line + tier advice lines plus
+/** Bucket width for the live used reading. 5k steps keep the tail snapshot
+ * emission rate low (the snapshot re-emits only when its joined text
+ * changes); tier crossings change the line immediately regardless. */
+const USED_BUCKET_TOKENS = 5000;
+
+/** `~50k`-style bucketed reading for the live watermark line. */
+function bucketKilo(tokens) {
+	return `${Math.round(tokens / USED_BUCKET_TOKENS) * (USED_BUCKET_TOKENS / 1000)}k`;
+}
+
+/** Byte-stable protocol text for root sessions: no live numbers, so the
+ * request head stays byte-identical for the whole session (KV-cache
+ * invariant); the numbers live in the tail context line only. */
+const PROTOCOL_ROOT_TEXT = [
+	"[SWITCHMAN:WATERMARK] protocol: this session is guarded by a context watermark measured every step.",
+	"ok tier is silent. soft tier: prefer delegating lightweight work (subagent/workflow) over reading more context yourself. hard tier: stop broad reading (read/glob/grep are budget-limited and may be denied) and start wrapping up. force tier: MANDATORY wrap-up now — produce the final answer from what you already hold; an automatic context handover (backup + document + compaction + continuation) may run and will tell you to end the turn.",
+	"The live tier and the bucketed used-token reading (against the soft/hard/force budget) arrive ONLY as [SWITCHMAN:WATERMARK] lines inside the appended runtime-context snapshot at the conversation tail; a tier change is announced on the step it happens. /ctx-pause pauses every watermark enforcement (measurement continues), /ctx-resume restores it, /ctx-handover starts a handover immediately.",
+].join("\n");
+
+/** Byte-stable protocol text for subagent sessions (same invariant). */
+const PROTOCOL_SUB_TEXT = [
+	"[SWITCHMAN:WATERMARK] protocol: this subagent session is guarded by a context watermark measured every step.",
+	"ok tier is silent. soft tier: keep reads narrow and drop bulky raw output. hard tier: stop broad reading; wrap toward the final summary. force tier: stop reading and return the final summary now — end the FINAL message with a HANDOFF block: completed / key findings (file:line) / remaining / next steps.",
+	"The live tier and the bucketed used-token reading arrive ONLY as [SWITCHMAN:WATERMARK] lines inside the appended runtime-context snapshot; a tier change is announced on the step it happens.",
+].join("\n");
+
+/** Static paused line (numbers omitted on purpose: enforcement is off, and a
+ * frozen string emits once and never churns the snapshot again). */
+const PAUSED_LINE =
+	"[SWITCHMAN:WATERMARK] paused — measurement continues, but every watermark enforcement stays off until /ctx-resume.";
+
+/** Root-session live line: "" at ok (token economy), tier advice lines plus
  * the live handover progress (phase/attempt) and auto-cooldown state. */
-function renderRootBanner(level, used, th, status) {
+function renderRootWatermark(level, used, th, status) {
+	if (level === "ok") return "";
 	const head =
-		`[SWITCHMAN:WATERMARK] level=${level} used=${kilo(used)}` +
-		` budget=${kilo(th.soft)}/${kilo(th.hard)}/${kilo(th.force)}`;
-	if (level === "ok") return head;
-	if (level === "paused")
-		return `${head}\nPAUSED by /ctx-pause — measurement continues, but every watermark enforcement stays off until /ctx-resume.`;
-	const lines = [head];
-	if (level === "soft") lines.push(`soft tier: prefer delegating lightweight work (subagent/workflow) over reading more context yourself.`);
-	if (level === "hard") lines.push(`hard tier: stop broad reading (read/glob/grep are budget-limited this turn) and start wrapping up.`);
-	if (level === "force") {
-		lines.push(`force tier: MANDATORY wrap-up now — produce the final answer from what you already hold.`);
-		const phase = status?.phase;
-		if (phase === "backup") {
-			lines.push(`context handover running: forking the backup session and writing the handover document…`);
-		} else if (phase === "compacting") {
-			lines.push(`context handover running: compaction attempt ${status?.attempt ?? "?"} (retries while the turn is still running)…`);
-		} else if (phase === "continuation") {
-			lines.push(`context handover completing: waking this session to fill in the document and continue the task…`);
-		} else if (status?.autoHandover) {
-			lines.push(
-				status?.cooldownMin > 0
-					? `automatic handover cooldown: ${status.cooldownMin} min left; run /ctx-handover${status?.tool ? " or call the ctx_handover tool" : ""} to force one now.`
-					: `an automatic context handover (backup + document + compaction + continuation) is armed and will fire at the next step boundary${status?.tool ? "; calling the ctx_handover tool triggers it immediately" : ""}.`,
-			);
-		} else {
-			lines.push(`run /ctx-handover${status?.tool ? " or call the ctx_handover tool" : ""} to trigger a manual context handover.`);
-		}
+		`[SWITCHMAN:WATERMARK] ${level} tier — used ~${bucketKilo(used)}` +
+		` of budget ${kilo(th.soft)}/${kilo(th.hard)}/${kilo(th.force)}`;
+	if (level === "soft") return `${head}\nsoft tier: prefer delegating lightweight work (subagent/workflow) over reading more context yourself.`;
+	if (level === "hard") return `${head}\nhard tier: stop broad reading (read/glob/grep are budget-limited this turn) and start wrapping up.`;
+	const lines = [head, "force tier: MANDATORY wrap-up now — produce the final answer from what you already hold."];
+	const phase = status?.phase;
+	if (phase === "backup") {
+		lines.push(`context handover running: forking the backup session and writing the handover document…`);
+	} else if (phase === "compacting") {
+		lines.push(`context handover running: compaction attempt ${status?.attempt ?? "?"} (retries while the turn is still running)…`);
+	} else if (phase === "continuation") {
+		lines.push(`context handover completing: waking this session to fill in the document and continue the task…`);
+	} else if (status?.autoHandover) {
+		lines.push(
+			status?.cooldownMin > 0
+				? `automatic handover cooldown: ${status.cooldownMin} min left; run /ctx-handover${status?.tool ? " or call the ctx_handover tool" : ""} to force one now.`
+				: `an automatic context handover (backup + document + compaction + continuation) is armed and will fire at the next step boundary${status?.tool ? "; calling the ctx_handover tool triggers it immediately" : ""}.`,
+		);
+	} else {
+		lines.push(`run /ctx-handover${status?.tool ? " or call the ctx_handover tool" : ""} to trigger a manual context handover.`);
 	}
 	return lines.join("\n");
 }
 
-/** Subagent-session banner: the same soft/hard/force absolute-token tiers
- *  as the root banner ("" while ok — token economy), with subagent-flavored
+/** Subagent-session live line: the same soft/hard/force absolute-token tiers
+ *  as the root line ("" while ok — token economy), with subagent-flavored
  *  advice and the HANDOFF block due at the force tier. Pausing never applies
  *  to subagents (oc index.ts:187-190). */
-function renderSubBanner(used, th) {
+function renderSubWatermark(used, th) {
 	const level = levelOf(used, th);
-	const head =
-		`[SWITCHMAN:WATERMARK] subagent level=${level} used=${kilo(used)}` +
-		` budget=${kilo(th.soft)}/${kilo(th.hard)}/${kilo(th.force)}`;
 	if (level === "ok") return "";
-	if (level === "soft")
-		return `${head}\nsoft tier: keep reads narrow and drop bulky raw output.`;
-	if (level === "hard")
-		return `${head}\nhard tier: stop broad reading; start wrapping toward the final summary.`;
+	const head =
+		`[SWITCHMAN:WATERMARK] subagent ${level} tier — used ~${bucketKilo(used)}` +
+		` of budget ${kilo(th.soft)}/${kilo(th.hard)}/${kilo(th.force)}`;
+	if (level === "soft") return `${head}\nsoft tier: keep reads narrow and drop bulky raw output.`;
+	if (level === "hard") return `${head}\nhard tier: stop broad reading; start wrapping toward the final summary.`;
 	return (
 		`${head}\nforce tier: stop reading and return the final summary now.\n` +
 		`End the FINAL message with a HANDOFF block: completed / key findings (file:line) / remaining / next steps.`
 	);
 }
 
-/** Whole banner for one assembly; "" whenever anything needed is missing. */
-function renderBanner(ctx, config, state, agent) {
+/** Whole live line for one assembly (the tail context); "" whenever anything
+ * needed is missing or the session sits at the silent ok tier. */
+function renderWatermarkContext(ctx, config, state, agent) {
 	try {
 		const sessionId = sessionIdOf(agent);
 		if (sessionId === null || agent.session === undefined) return "";
@@ -220,16 +251,18 @@ function renderBanner(ctx, config, state, agent) {
 			// (enabled by the wmSubagentCap toggle, 0/0 = follow the root set).
 			const subForce = readBool(config.wmSubagentCap, true) ? readNumber(config.wmSubagentForceTokens, 0) : 0;
 			const subTh = subForce > 0 ? { ...th, force: subForce } : th;
-			return renderSubBanner(used, subTh);
+			return renderSubWatermark(used, subTh);
 		}
-		const level = state.paused.has(sessionId) ? "paused" : levelOf(used, th);
+		if (state.paused.has(sessionId)) return PAUSED_LINE;
 		const live = handoverOf(sessionId);
 		const elapsed = Date.now() - (state.lastHandover.get(sessionId) ?? 0);
-		return renderRootBanner(level, used, th, {
+		// Cooldown quantized to 5-minute steps so the emitted line stays
+		// byte-stable between steps (snapshot re-emits only on change).
+		return renderRootWatermark(levelOf(used, th), used, th, {
 			autoHandover: readBool(config.wmAutoHandover, true),
 			phase: live?.phase,
 			attempt: live?.attempt,
-			cooldownMin: Math.max(0, Math.ceil((HANDOVER_COOLDOWN_MS - elapsed) / 60_000)),
+			cooldownMin: Math.max(0, Math.ceil((HANDOVER_COOLDOWN_MS - elapsed) / 300_000) * 5),
 			tool: state.handoverTool ?? undefined,
 		});
 	} catch {
@@ -298,13 +331,40 @@ function applyContextWatch(ctx, config) {
 	};
 	const warn = (message) => ctx.logger?.warn?.(`dsh-switchman: ${message}`);
 
-	// --- A. watermark banner -------------------------------------------------
+	// --- A. watermark: byte-stable head protocol + live tail context --------
+	// KV-cache invariant (see the file header): everything before the
+	// conversation history must stay byte-identical for the whole session,
+	// so the head section carries only static protocol text while ALL live
+	// numbers travel as runtime context. DSH joins contexts into the
+	// "Current runtime context" snapshot and appends it at the tail as a new
+	// user message only when its text changes — append-only by construction,
+	// the cached prefix is never touched.
 	ctx.systemPrompt.section({
 		name: "switchman:watermark",
 		order: 10500,
 		interpolate: false,
-		text: (context) => renderBanner(ctx, config, state, context?.agent),
+		text: (context) => (isRoot(ctx, context?.agent) ? PROTOCOL_ROOT_TEXT : PROTOCOL_SUB_TEXT),
 	});
+	// Capability check first: on a host without the runtime-context API an
+	// optional chain would short-circuit silently — the live watermark line
+	// would vanish with no log at all. Warn once so it stays diagnosable.
+	if (typeof ctx.systemPrompt?.context !== "function") {
+		warn("systemPrompt.context API unavailable on this DSH host — live watermark line disabled (static head protocol remains)");
+	} else {
+		try {
+			ctx.systemPrompt.context({
+				name: "switchman:watermark",
+				// After the core placements (WORKING_DIRECTORY 100 … WEB_SURFACE
+				// 210), so the watermark line closes the snapshot.
+				order: 300,
+				required: true,
+				interpolate: false,
+				text: (context) => renderWatermarkContext(ctx, config, state, context?.agent),
+			});
+		} catch (error) {
+			warn(`watermark context registration failed: ${error?.message ?? error}`);
+		}
+	}
 
 	// --- C. handover execution: borrow the session's own /compact -----------
 	// The desktop profile provides compaction ONLY inside each preset's
@@ -805,7 +865,7 @@ function applyContextWatch(ctx, config) {
 			if (sessionId !== null && ACCOUNT_TOOLS.has(exec?.name ?? "")) {
 				const entry = accountRead(state, sessionId, resultTokens(result));
 				if (GATED_TOOLS.has(exec.name) && !state.paused.has(sessionId)) {
-					const budget = readNumber(config.wmReadBudgetTokens, 1500);
+					const budget = readNumber(config.wmReadBudgetTokens, 3000);
 					const ceiling = budget * CEILING_MULTIPLE;
 					const used = measureNow(ctx, exec.agent);
 					const th = readThresholds(config);
@@ -841,7 +901,7 @@ function applyContextWatch(ctx, config) {
 			if (!GATED_TOOLS.has(exec?.name ?? "")) return next();
 			const sessionId = sessionIdOf(exec?.agent);
 			if (sessionId === null || state.paused.has(sessionId)) return next();
-			const budget = readNumber(config.wmReadBudgetTokens, 1500);
+			const budget = readNumber(config.wmReadBudgetTokens, 3000);
 			if (turnUsed(state, sessionId) < budget * CEILING_MULTIPLE) return next();
 			const used = measureNow(ctx, exec.agent);
 			if (used === null) return next();
@@ -957,4 +1017,12 @@ function applyContextWatch(ctx, config) {
 	}
 }
 
-export { applyContextWatch };
+export {
+	applyContextWatch,
+	bucketKilo,
+	PAUSED_LINE,
+	PROTOCOL_ROOT_TEXT,
+	PROTOCOL_SUB_TEXT,
+	renderRootWatermark,
+	renderSubWatermark,
+};

package/host/intent-presets.js

@@ -0,0 +1,163 @@
+/** Preset intent categories for the "auto" pseudo-model's candidate list.
+ *
+ * A preset row ALWAYS exists in the merged candidate list: its note (the
+ * text the classifier reads) is code-owned and immutable by mandate —
+ * upgrades ship new wording without any settings migration — while the
+ * route fields (provider/model/effort) and the enabled toggle stay
+ * user-configured. Presets ship enabled with an empty model, so filling
+ * the model is the single step that activates one.
+ *
+ * Descriptions are deliberately written FOR the classifier, not for
+ * humans: each one states which user messages belong to the lane and
+ * carries a contrastive anchor against its neighbours, because a small
+ * local model needs explicit discrimination cues far more than prose
+ * polish does. English by mandate. */
+
+export const INTENT_PRESETS = [
+	{
+		id: "quick-chat",
+		label: "Casual chat & quick Q&A",
+		note: "Casual conversation, greetings, quick factual or meta questions about the session itself, and follow-up chatter. No code changes and no deep reasoning required; speed and cost matter most.",
+	},
+	{
+		id: "mechanical-edit",
+		label: "Mechanical edits & chores",
+		note: "Small, fully specified changes: renames, typo and formatting fixes, config tweaks, license headers, running a known command, repetitive boilerplate edits. The plan is already given; execution is trivial.",
+	},
+	{
+		id: "codebase-exploration",
+		label: "Read-only codebase exploration",
+		note: "Read-only investigation of the repository: locating code, tracing call paths, grepping symbols, summarizing how a subsystem works, or answering where/how something is implemented. Output is an explanation, not a diff.",
+	},
+	{
+		id: "general-coding",
+		label: "Everyday implementation",
+		note: "Regular feature work and bug fixing: implementing a clear requirement across a few files, ordinary debugging, writing or updating tests and small scripts. The default lane for hands-on code changes.",
+	},
+	{
+		id: "deep-reasoning",
+		label: "Architecture & hard problems",
+		note: "Decisions and problems that need careful, long thinking: architecture and design choices, multi-step orchestration, tricky cross-component bugs, algorithmic or concurrency issues, security-sensitive changes, anything with high rework cost if answered shallowly.",
+	},
+	{
+		id: "code-review",
+		label: "Review & verification",
+		note: "Reading and judging existing changes or output: diff and PR review, adversarial verification of another agent's work, spotting regressions or spec violations, explaining whether and why a change is correct.",
+	},
+	{
+		id: "docs-writing",
+		label: "Docs, translation & wording",
+		note: "Producing or polishing prose: documentation, READMEs, changelogs, commit messages, translation between languages, tone and clarity improvements. Language quality matters more than reasoning depth.",
+	},
+	{
+		id: "vision-input",
+		label: "Image understanding",
+		note: "Turns whose input includes screenshots, photos, diagrams, charts, or UI mockups that must be visually interpreted to proceed.",
+	},
+];
+
+const PRESET_BY_ID = new Map(INTENT_PRESETS.map((preset) => [preset.id, preset]));
+
+function stringOf(value) {
+	return typeof value === "string" ? value.trim() : "";
+}
+
+/** Deterministic id for a stored entry that predates ids (legacy rows keep
+ * a stable identity across restarts even before the next settings save
+ * persists one). Route-key based, with a numeric suffix on collisions. */
+function derivedId(provider, model, used) {
+	const base = `user:${provider}/${model}`;
+	if (!used.has(base)) return base;
+	let n = 2;
+	while (used.has(`${base}#${n}`)) n += 1;
+	return `${base}#${n}`;
+}
+
+/** Merge the stored candidate entries with the built-in presets into the
+ * unified list the settings UI renders and the router filters.
+ *
+ * Rules:
+ * - presets come first, in INTENT_PRESETS order, always all present;
+ * - a stored entry whose id names a preset overrides that preset's
+ *   route/effort/enabled, but its note is ALWAYS the code value;
+ * - stored entries with unknown ids survive as user rows (graceful
+ *   downgrade when a future preset id is removed again);
+ * - legacy entries without ids get deterministic derived ids;
+ * - fully-empty legacy junk (no id, no route, no note) is dropped, while
+ *   any entry carrying an id survives as-is — a half-edited new row must
+ *   not vanish from under the user between save and snapshot. */
+export function mergeIntentCandidates(stored) {
+	const list = Array.isArray(stored) ? stored : [];
+	const presetOverrides = new Map();
+	const userRows = [];
+	// Pass 1 claims every explicit id BEFORE any derived id is minted, so a
+	// later explicit row can never collide with an earlier legacy row's
+	// derived `user:<provider>/<model>` name.
+	const usedIds = new Set();
+	for (const entry of list) {
+		if (entry === null || typeof entry !== "object") continue;
+		const id = stringOf(entry.id);
+		if (id !== "") usedIds.add(id);
+	}
+	for (const entry of list) {
+		if (entry === null || typeof entry !== "object") continue;
+		const id = stringOf(entry.id);
+		const provider = stringOf(entry.provider);
+		const model = stringOf(entry.model);
+		const effort = stringOf(entry.effort);
+		const note = stringOf(entry.note);
+		const enabled = entry.enabled !== false;
+		const preset = id === "" ? null : PRESET_BY_ID.get(id);
+		if (preset !== null && preset !== undefined) {
+			presetOverrides.set(preset.id, { provider, model, effort, enabled });
+			usedIds.add(preset.id);
+			continue;
+		}
+		if (id === "" && provider === "" && model === "" && note === "" && effort === "") continue;
+		const row = {
+			id: id !== "" ? id : derivedId(provider, model, usedIds),
+			preset: false,
+			enabled,
+			provider,
+			model,
+		};
+		if (effort !== "") row.effort = effort;
+		if (note !== "") row.note = note;
+		usedIds.add(row.id);
+		userRows.push(row);
+	}
+	const rows = [];
+	for (const preset of INTENT_PRESETS) {
+		const override = presetOverrides.get(preset.id);
+		const row = {
+			id: preset.id,
+			preset: true,
+			enabled: override ? override.enabled : true,
+			provider: override ? override.provider : "",
+			model: override ? override.model : "",
+			note: preset.note,
+			label: preset.label,
+		};
+		if (override && override.effort !== "") row.effort = override.effort;
+		rows.push(row);
+	}
+	for (const row of userRows) rows.push(row);
+	return rows;
+}
+
+/** Only rows that actually participate in routing: enabled AND a complete
+ * route. A preset still waiting for its model (or a freshly added custom
+ * row) stays visible in the UI but outside the classifier's list. */
+export function effectiveIntentCandidates(rows) {
+	const list = Array.isArray(rows) ? rows : [];
+	return list.filter(
+		(entry) =>
+			entry !== null &&
+			typeof entry === "object" &&
+			entry.enabled !== false &&
+			typeof entry.provider === "string" &&
+			entry.provider.trim() !== "" &&
+			typeof entry.model === "string" &&
+			entry.model.trim() !== "",
+	);
+}