dsh-switchman 1.10.3 → 1.11.0

package/host/context-watch.js

@@ -53,7 +53,7 @@ import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { clearHandover, handoverOf, recordHandover } from "./handover-state.js";
 import { enumerateLiveSubagents, sessionRecordPath, sessionRecordsDir } from "./subagents.js";
-import { recentTrimViewTokensOf } from "./context-trim/index.js";
+import { recentTrimPromptTokensOf } from "./context-trim/index.js";
 
 /** Tools whose result text is accounted against the per-turn read budget. */
 const ACCOUNT_TOOLS = new Set(["read", "glob", "grep", "bash"]);
@@ -115,11 +115,6 @@ function levelOf(used, th) {
 	return "ok";
 }
 
-/** `42k`-style rounding for the anchor line. */
-function kilo(tokens) {
-	return `${Math.round(tokens / 1000)}k`;
-}
-
 /** Session id off an exec/invocation agent (shared agent/session id). */
 function sessionIdOf(agent) {
 	const id = agent?.session?.id ?? agent?.id;
@@ -141,7 +136,7 @@ function isRoot(ctx, agent) {
 function readThresholds(config) {
 	return {
 		soft: readNumber(config.wmSoftTokens, 80000),
-		hard: readNumber(config.wmHardTokens, 120000),
+		hard: readNumber(config.wmHardTokens, 95000),
 		force: readNumber(config.wmForceTokens, 150000),
 	};
 }
@@ -151,15 +146,21 @@ export function measureNow(ctx, agent) {
 	try {
 		const measurement = agent?.session ? ctx.tokenMeter?.measure?.(agent.session) : undefined;
 		const used = Number.isFinite(measurement?.totalTokens) ? measurement.totalTokens : null;
-		// Meter duality (design §8): prefer the trim layer's fresh outbound-view
-		// estimate when present — billion-context can fold far more away than the
-		// meter's stored tally admits, and the watermark must track what the
-		// model actually sees. Strictly additive + fail-open: any trim failure
-		// falls back to the stored measure.
+		// Meter duality (design §8): prefer the trim layer's wire-domain meter —
+		// max(fresh outbound view, last sampled MAIN-dispatch prompt), the same
+		// number the trim pressure tiers evaluate — when present. Each pure
+		// source has one bias: the stored tally is wire-domain but never
+		// re-prices splice-level folds (it keeps counting material the model no
+		// longer receives — high bias), while the bare view never counts the
+		// system/tool sections (low bias). max(view, wire) fixes both and puts
+		// the watermark tiers (soft/hard/force + read budget) on the SAME
+		// boundary as the fold engine — wmHardTokens 95k ≙ trim pressure 90k
+		// (c453b91) holds in units, not just in numbers. Strictly additive +
+		// fail-open: any trim failure falls back to the stored measure.
 		try {
 			const sessionId = agent?.session?.id ?? (typeof agent?.id === "string" ? agent.id : null);
-			const viewTokens = sessionId === null ? null : recentTrimViewTokensOf(sessionId);
-			if (viewTokens !== null) return viewTokens;
+			const promptTokens = sessionId === null ? null : recentTrimPromptTokensOf(sessionId);
+			if (promptTokens !== null) return promptTokens;
 		} catch {
 			// fall through to the stored measure
 		}
@@ -171,58 +172,53 @@ export function measureNow(ctx, agent) {
 
 // ---- watermark rendering (pure given state + measurement) ------------------
 
-/** 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`;
-}
+/** MODEL-VISIBILITY POLICY (docs/ladder-fold.md, bili lesson #2): the
+ * watermark NEVER shows the model a water level — no used-token counts, no
+ * budget values, no percentages, no cooldown minutes. A model told "you're
+ * at 20%" anchors on "looks healthy" and refuses to fold or wrap; with the
+ * numbers hidden, judgment roots in the task. Only BEHAVIORAL directives
+ * travel, and only when enforcement changes (a tier crossing or a handover
+ * phase change), which also keeps the runtime-context snapshot byte-stable
+ * between those events. The full numeric picture stays available to the
+ * human through the client badge. */
 
 /** 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. */
+ * invariant). */
 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 (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.",
+	"[SWITCHMAN:WATERMARK] protocol: this session's context is managed automatically (folding runs before you notice; a handover may run when needed). You will never receive token counts, percentages, or progress numbers — none exist in this protocol, and no pacing decision is yours to make from them.",
+	"Only BEHAVIORAL directives arrive, as [SWITCHMAN:WATERMARK] lines inside the appended runtime-context snapshot, when enforcement changes: a soft line asks you to prefer delegation over reading more context yourself; a hard line says broad reading is budget-limited this turn and it is time to start wrapping up; a force line is a MANDATORY wrap-up — produce the final answer from what you already hold. /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.",
+	"[SWITCHMAN:WATERMARK] protocol: this subagent session's context is managed automatically. You will never receive token counts, percentages, or progress numbers — judgment stays rooted in the task.",
+	"Only BEHAVIORAL directives arrive, as [SWITCHMAN:WATERMARK] lines inside the appended runtime-context snapshot, when enforcement changes: a soft line asks for narrow reads; a hard line says stop broad reading and wrap toward the final summary; a force line says stop reading and return the final summary now, ending the FINAL message with a HANDOFF block: completed / key findings (file:line) / remaining / next steps.",
 ].join("\n");
 
-/** Static paused line (numbers omitted on purpose: enforcement is off, and a
+/** Static paused line (never changes while paused: 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 renderRootWatermark(level, used, th, status) {
+/** Root-session live line: directive text only — no numbers (see the
+ * policy note above). "" while the session sits at the silent ok tier. */
+function renderRootWatermark(level, status) {
 	if (level === "ok") return "";
-	const head =
-		`[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."];
+	if (level === "soft") return "[SWITCHMAN:WATERMARK] soft tier: prefer delegating lightweight work (subagent/workflow) over reading more context yourself.";
+	if (level === "hard") return "[SWITCHMAN:WATERMARK] hard tier: stop broad reading (read/glob/grep are budget-limited this turn) and start wrapping up.";
+	const lines = ["[SWITCHMAN:WATERMARK] 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: writing the handover document…`);
 	} else if (phase === "compacting") {
-		lines.push(`context handover running: compaction attempt ${status?.attempt ?? "?"} (retries while the turn is still running)…`);
+		lines.push(`context handover running: compaction in progress (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.`
+			status?.cooldown
+				? `automatic handover is cooling down; run /ctx-handover${status?.tool ? " or call the ctx_handover tool" : ""} to force one now.`
 				: `an automatic context handover (document + compaction + continuation) is armed and will fire at the next step boundary${status?.tool ? "; calling the ctx_handover tool triggers it immediately" : ""}.`,
 		);
 	} else {
@@ -231,21 +227,16 @@ function renderRootWatermark(level, used, th, status) {
 	return lines.join("\n");
 }
 
-/** 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 renderSubWatermark(used, th) {
-	const level = levelOf(used, th);
+/** Subagent-session live line: the same tiers as the root line, directive
+ * text only — no numbers (see the policy note above). Pausing never
+ * applies to subagents (oc index.ts:187-190). */
+function renderSubWatermark(level) {
 	if (level === "ok") return "";
-	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.`;
+	if (level === "soft") return "[SWITCHMAN:WATERMARK] soft tier: keep reads narrow and drop bulky raw output.";
+	if (level === "hard") return "[SWITCHMAN:WATERMARK] hard 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.`
+		"[SWITCHMAN:WATERMARK] force 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."
 	);
 }
 
@@ -258,24 +249,24 @@ function renderWatermarkContext(ctx, config, state, agent) {
 		const th = readThresholds(config);
 		const used = measureNow(ctx, agent);
 		if (used === null) return "";
+		const level = levelOf(used, th);
+		if (level === "ok") return "";
 		if (!isRoot(ctx, agent)) {
 			// Subagents share the root soft/hard thresholds; the optional
 			// wmSubagentForceTokens override replaces only the force tier
 			// (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 renderSubWatermark(used, subTh);
+			return renderSubWatermark(levelOf(used, subTh));
 		}
 		if (state.paused.has(sessionId)) return PAUSED_LINE;
 		const live = handoverOf(sessionId);
 		const elapsed = Date.now() - (state.lastHandover.get(sessionId) ?? 0);
-		// 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, {
+		return renderRootWatermark(level, {
 			autoHandover: readBool(config.wmAutoHandover, true),
 			phase: live?.phase,
 			attempt: live?.attempt,
-			cooldownMin: Math.max(0, Math.ceil((HANDOVER_COOLDOWN_MS - elapsed) / 300_000) * 5),
+			cooldown: elapsed < HANDOVER_COOLDOWN_MS,
 			tool: state.handoverTool ?? undefined,
 		});
 	} catch {
@@ -846,16 +837,26 @@ function applyContextWatch(ctx, config) {
 						readString(config.wmDenyMode) !== "deny" &&
 						Array.isArray(result?.content)
 					) {
-						return {
-							kind: "accept",
-							content: [
-								...result.content,
-								{
-									type: "text",
-									text: `[SWITCHMAN:WATERMARK] read budget exceeded this turn (used ${Math.round(entry.used)}/${Math.round(ceiling)} tokens) — further reads may be denied; wrap up or delegate the remaining reading.`,
-								},
-							],
-						};
+						// [2026-11-07]-[the warning branch used to return without
+						// calling next()]-[that short-circuited every post-execute
+						// handler downstream of the watermark (trim fork-link
+						// accounting, subagent model annotation) on exactly the
+						// turns that read the most. Run the pipeline first, then
+						// append the warning to whatever the pipeline accepted.]
+						return (async () => {
+							const downstream = await next();
+							const base = downstream !== null && typeof downstream === "object" && downstream.kind === "accept" && Array.isArray(downstream.content) ? downstream : result;
+							return {
+								kind: "accept",
+								content: [
+									...base.content,
+									{
+										type: "text",
+										text: `[SWITCHMAN:WATERMARK] read budget exceeded this turn (used ${Math.round(entry.used)}/${Math.round(ceiling)} tokens) — further reads may be denied; wrap up or delegate the remaining reading.`,
+									},
+								],
+							};
+						})();
 					}
 				}
 			}
@@ -929,8 +930,15 @@ function applyContextWatch(ctx, config) {
 	ctx.commands.register({
 		name: "ctx-handover",
 		description: "Trigger a full context handover for this session now (document + compaction + continuation).",
+		// Signal deliberately dropped (inspection W20): a turn-scoped
+		// AbortSignal shared by every /compact retry turns a user cancel into
+		// six straight failures walking the full ~530 s backoff ladder with a
+		// misleading error text — the same reason the ctx_handover TOOL path
+		// drops its turn signal. sessionCompact fabricates a fresh un-aborted
+		// signal when none arrives; user cancel lets compaction finish, like
+		// the tool path.
 		handler: (invocation) =>
-			runHandover(invocation?.agent, sessionIdOf(invocation?.agent), invocation?.commandId, invocation?.signal, "manual"),
+			runHandover(invocation?.agent, sessionIdOf(invocation?.agent), invocation?.commandId, undefined, "manual"),
 	});
 
 	// --- E. ctx_handover: the agent-callable front door to the same
@@ -989,7 +997,6 @@ function applyContextWatch(ctx, config) {
 
 export {
 	applyContextWatch,
-	bucketKilo,
 	PAUSED_LINE,
 	PROTOCOL_ROOT_TEXT,
 	PROTOCOL_SUB_TEXT,

package/host/routes.js

@@ -95,6 +95,24 @@ const NUMBER_FIELDS = [
 	"wmReadBudgetTokens",
 	"wmSubagentForceTokens",
 ];
+/** Trim numbers carry their own schema bounds (host/config.js), so the
+ *  shared NUMBER_FIELDS coercion (which only rejects negatives) is too
+ *  loose — these validate against each field's declared min/max. This group
+ *  MUST mirror the client page's TRIM_NUMBER_FIELDS: a field coerced here
+ *  but never sent by the client fails every fenced write (and vice versa). */
+const TRIM_NUMBER_FIELDS = [
+	{ field: "trimGrowthTokens", min: 1000, max: Number.POSITIVE_INFINITY, def: 22500 },
+	{ field: "trimIncrementTokens", min: 1000, max: Number.POSITIVE_INFINITY, def: 50000 },
+	{ field: "trimPressurePercent", min: 5, max: 100, def: 60 },
+	{ field: "trimEmergencyPercent", min: 5, max: 100, def: 95 },
+	{ field: "trimWindowTokens", min: 0, max: Number.POSITIVE_INFINITY, def: 0 },
+	{ field: "trimProtectedTail", min: 0, max: 100, def: 6 },
+	{ field: "trimMaxFoldsPerHour", min: 1, max: 60, def: 6 },
+	{ field: "trimLadderT2Tokens", min: 1000, max: Number.POSITIVE_INFINITY, def: 8000 },
+	{ field: "trimLadderT2MinBlocks", min: 2, max: 200, def: 3 },
+	{ field: "trimLadderT3Tokens", min: 1000, max: Number.POSITIVE_INFINITY, def: 6000 },
+	{ field: "trimLadderT3MinBlocks", min: 2, max: 200, def: 2 },
+];
 const BOOLEAN_FIELDS = [
 	"wmAutoHandover",
 	"wmSubagentCap",
@@ -110,6 +128,10 @@ const BOOLEAN_FIELDS = [
 	"syncWhitelist",
 	// Intent recognition (mirrors the intent* group in host/config.js).
 	"intentEnabled",
+	// Context trim switches (mirrors the trim group in host/config.js).
+	"trimEnabled",
+	"trimLadderEnabled",
+	"surfaceFold",
 ];
 /** Intent numbers carry their own schema bounds (config.js), so the shared
  *  NUMBER_FIELDS coercion (which only rejects negatives) is too loose — these
@@ -125,7 +147,7 @@ const INTENT_NUMBER_FIELDS = [
 /** Intent route references: unlike pool routes they round-trip the "unset"
  *  {provider:"", model:""} pair, so they validate against the loosened
  *  cleanIntentRoute (both keys must be strings; either may be empty). */
-const INTENT_ROUTE_FIELDS = ["intentClassifierRoute", "intentFallbackRoute"];
+const INTENT_ROUTE_FIELDS = ["intentClassifierRoute", "intentFallbackRoute", "trimSideModel", "trimFoldFallbackModel"];
 /** Intent candidate list (route + optional effort/note per entry). */
 const INTENT_CANDIDATE_FIELDS = ["intentCandidates"];
 
@@ -144,7 +166,10 @@ const ENUM_FIELDS = {
 	dispatchEnforce: ["off", "advice", "enforce"],
 	wmDenyMode: ["cap", "deny"],
 	intentClassifierKind: ["chat", "systemone"],
+	trimMode: ["off", "advisory", "auto"],
 };
+/** Trim string fields (mirrors host/config.js strings). */
+const TRIM_STRING_FIELDS = ["trimStateDir"];
 
 /** JSON response helper. */
 function writeJson(res, status, payload) {
@@ -312,6 +337,7 @@ function cleanIntentCandidate(entry) {
 export function snapshotOf(config) {
 	const values = {};
 	for (const field of STRING_FIELDS) values[field] = String(rawOf(config?.[field]) ?? "");
+	for (const field of TRIM_STRING_FIELDS) values[field] = String(rawOf(config?.[field]) ?? "");
 	for (const field of POOL_FIELDS)
 		values[field] = Array.isArray(rawOf(config?.[field]))
 			? rawOf(config[field]).map(cleanRoute).filter(Boolean)
@@ -337,6 +363,11 @@ export function snapshotOf(config) {
 	values.dispatchEnforce = ENUM_FIELDS.dispatchEnforce.includes(rawOf(config?.dispatchEnforce))
 		? rawOf(config.dispatchEnforce)
 		: "advice";
+	values.trimMode = ENUM_FIELDS.trimMode.includes(rawOf(config?.trimMode)) ? rawOf(config.trimMode) : "auto";
+	for (const { field, def } of TRIM_NUMBER_FIELDS) {
+		const raw = Number(rawOf(config?.[field]));
+		values[field] = Number.isFinite(raw) ? raw : def;
+	}
 	for (const field of NUMBER_FIELDS) {
 		const raw = Number(rawOf(config?.[field]));
 		values[field] = Number.isFinite(raw) ? raw : 0;
@@ -407,6 +438,17 @@ export function coerceValues(input) {
 	values.langScope = input.langScope;
 	if (!ENUM_FIELDS.dispatchEnforce.includes(input.dispatchEnforce)) return null;
 	values.dispatchEnforce = input.dispatchEnforce;
+	if (!ENUM_FIELDS.trimMode.includes(input.trimMode)) return null;
+	values.trimMode = input.trimMode;
+	for (const field of TRIM_STRING_FIELDS) {
+		if (typeof input[field] !== "string") return null;
+		values[field] = input[field];
+	}
+	for (const { field, min, max } of TRIM_NUMBER_FIELDS) {
+		const raw = Number(input[field]);
+		if (!Number.isFinite(raw) || raw < min || raw > max) return null;
+		values[field] = raw;
+	}
 	for (const field of NUMBER_FIELDS) {
 		const raw = Number(input[field]);
 		if (!Number.isFinite(raw) || raw < 0) return null;
@@ -421,9 +463,27 @@ export function coerceValues(input) {
 	return values;
 }
 
-/** Deep-equal on the plain-JSON value shapes this module exchanges. */
-function sameValues(a, b) {
-	return JSON.stringify(a) === JSON.stringify(b);
+/** Stable JSON text: object keys sorted at every depth. snapshotOf and
+ *  coerceValues build the same fields in DIFFERENT insertion orders
+ *  (e.g. trimStateDir sits 7th in a snapshot but near the tail after
+ *  coercion), so a raw stringify compared key order, not content —
+ *  every fenced save 409'd ("settings changed elsewhere") even with no
+ *  intervening writer (2026-11-07 settings-save bug). */
+function canonicalJson(value) {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value !== null && typeof value === "object")
+		return `{${Object.keys(value)
+			.sort()
+			.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+			.join(",")}}`;
+	return JSON.stringify(value) ?? "undefined";
+}
+
+/** Deep-equal on the plain-JSON value shapes this module exchanges;
+ *  key-order insensitive (see canonicalJson). Exported for the smoke
+ *  suite alongside coerceValues — the fence predicate IS the contract. */
+export function sameValues(a, b) {
+	return canonicalJson(a) === canonicalJson(b);
 }
 
 /** Enumerate the model catalog from the host session controller. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dsh-switchman",
-	"version": "1.10.3",
+	"version": "1.11.0",
 	"description": "Autonomous Agent Teams doctrine for the four shipped DeepSeek Harness presets, plus language preferences, dispatch pools with model ranking, and context watermark control.",
 	"license": "MIT",
 	"keywords": [
@@ -28,7 +28,7 @@
 	"icon": "./icon.svg",
 	"engines": {
 		"node": ">=24",
-		"dsh": ">=0.2.1-rc.1"
+		"dsh": ">=0.2.2-rc.1"
 	},
 	"exports": {
 		".": "./index.js",