dsh-switchman 1.3.0 → 1.5.0

package/cordis.patch.yml

@@ -3,12 +3,20 @@
 #
 # One bundle, four preset overrides: each of the four shipped Web presets
 # (standard / ptc / minimal / cordis) keeps its exact shipped plugin list and
-# gains, in its persona suffix, the dsh-switchman autonomous Agent Teams
-# doctrine. The persona suffix renders as the LAST system-prompt section
+# gains, in its persona suffix, the dsh-switchman base dispatch doctrine
+# (delegation discipline, orchestration/token rules, tiered verification).
+# The persona suffix renders as the LAST system-prompt section
 # (DEPLOYMENT_PERSONA_SUFFIX, order 10200), after the conservative TEAM_POLICY
 # section (order 600) contributed by the Host-level
 # @deepseek-ai/dsh-experimental-tool-agent-team, so this doctrine is the
-# operative team policy for sessions of every preset.
+# operative discipline for sessions of every preset.
+#
+# The Agent Teams clauses (conservative-policy reversal, spawn_teammate
+# trigger conditions, shared task-board discipline) are NOT static: the Host
+# half (host/teams.js) carries them in a dynamic `[SWITCHMAN:TEAMS]` section
+# (order 10250, between this suffix and the language section) that is only
+# injected while the teamsMode setting is ON. OFF leaves the factory
+# conservative team policy in charge; nothing here changes.
 #
 # The Agent Teams tools themselves (spawn_teammate, team_task_*, send_message,
 # wait_agent, …) come from the Host composition, i.e. the shipped
@@ -25,6 +33,17 @@
 # the shipped presets, re-sync these lists from the new preset files, then
 # reinstall this bundle.
 #
+# NEVER set `modelSelectionSettings: true` on the tool-subagent-fork row (any
+# preset). Only the spawn row may carry it: while the subagent model-selection
+# whitelist is enabled, every `@deepseek-ai/dsh-tool-subagent` instance with
+# modelSelectionSettings registers `list_subagent_models` into each new Agent's
+# scope, and a second instance makes session composition throw
+# `tool "list_subagent_models" is already registered in this scope` — breaking
+# creation of ALL new sessions and the recomposition of old ones. The shipped
+# presets (verified against installed dsh-web-app 0.2.0-rc.2 and the fork's
+# 0.2.1-alpha.1) enable it on the spawn row only; fork-side explicit routing
+# is not a factory capability.
+#
 # Known consequences of overriding:
 # - plugin_manager `set_plugin` on these preset rows reports `overridden`.
 # - An edit saved from the Web preset editor lands in the profile patch layer,
@@ -52,14 +71,11 @@
 
             总纲：在准确理解需求、严谨思考、最优质量、最低返工率的前提下最小化总 token 消耗。返工是最贵的 token——过程与铺陈可以省，验证与关键推理绝不省。
 
-            系统提示词前文的默认团队策略写的是「仅当用户明确要求时才创建 teammate」。该默认策略在当前 profile 下不适用：用户安装 dsh-switchman 即预先授权，你应当自主判断、自主触发，无需再询问用户。
-
             ## 一、默认委派，例外亲做（delegate by default）
             - 委派只消耗一个全新子上下文、只收回一份摘要；亲自读写每一份都会膨胀本会话上下文，长期更贵。长或重的上下文偏向委派，琐碎小事留在手里。
             - 仅当满足全部条件才亲自做：认知负载低或中、读取合计 <200 行、改动 <50 行；强迭代小步试错（每步都要立刻用上一步结果）；期望收益 <3k token 的收尾。
             - 位置不确定的检索、跨多文件调查、大范围重构、独立研究或方案对比：一律委派，侦察优先派 economy 泳道。
             - 任务开始时判断一次，中途规模或结构变化时重做；结论不必请示用户。
-            - 需要多成员持久协作、共享任务板、消息往来的用 Agent Teams（满足任一即触发 spawn_teammate：可并行的多个独立子任务；量大且自包含；主上下文水位已高；需要角色分离）；一次性、无需共享状态的单点调查用 subagent。
 
             ## 二、编排与 token 纪律（Lead 职责）
             - prompt 必须自包含：目标、已知事实与结论、文件路径、期望输出与验收标准；已查明的事实不让对方重查；固定段在前、可变段在后。
@@ -68,11 +84,11 @@
             - 禁止复活死会话：子智能体达 cap 终止后，用自包含 prompt 新派一个，不 resume 旧壳。
             - 广搜先问：首次整项目范围的搜索先向用户澄清范围，定点检索不受此限。
             - 大额派发先估成本：预计 ≥3 个成员或总消耗 >100k token 时，先报规模与预估请用户确认。
-            - 写作域隔离：共享任务上写明互不重叠的 write_scopes；用 team_task_* 维护任务板与依赖顺序；Lead 汇总最终 diff、复核关键改动并运行测试；用 wait_agent 等到必需的 teammate 完成，绝不在结果未回前下最终结论。
+            - 子路由两通道：显式传 provider/model/effort 任一字段会经 DSH 会话级授权白名单校验（设置页「允许 Agent 为子智能体选择模型」勾选的授权列表，与泳道池无关）；被拒时用 list_subagent_models 查实际可用路由再派，或改为完全不传三字段走隐式继承（不受校验，子智能体用默认值或继承主会话路由）。泳道池只是偏好排序，授权边界以 DSH 设置为准，不试图改写它。
 
             ## 三、分级验证（质量下限，不可省）
             - 改动 >20 行或涉及多个调用点：交 tester 验证。
-            - 改动 >300 行，或触及核心/安全/数据一致性逻辑：交 reviewer 独立复审。复审池有多个模型时优先选与主会话不同的模型；复审池只有与主会话相同的模型、或确需复用时，允许同模型复审，只需在结论中声明 DOWNGRADED。
+            - 改动 >300 行，或触及核心/安全/数据一致性逻辑：交 reviewer 独立复审。复审独立性以「代码作者」为锚而非主会话：作者模型 = 写出该改动的智能体的模型（子智能体按派发时显式路由记，未显式指定按继承记为主会话模型）。优先选与作者模型不同的复审模型；能同时避开主会话模型更佳（其集成复核视角已覆盖）。池内确实避不开作者模型时允许同模型复审，在结论中声明 DOWNGRADED 并注明相对作者还是相对主会话降级。
             - 任何降到更弱模型或更省验证的决定都必须显式声明；沉默放弃验证禁止。
 
             ## 四、边界

package/host/config.js

@@ -11,6 +11,7 @@
  * - lang*        project language preference (Phase 1)
  * - pool/rank    dispatch pools and capability ranking (Phase 2)
  * - wm*          context watermark control (Phase 3)
+ * - teams*       Agent Teams doctrine mode + whitelist sync (teams mode)
  *
  * Ported from opencode-switchman's opencode-switchman.jsonc surface
  * (oc/src/config.ts:23-51, oc/src/types.ts:281-344) onto DSH settings.
@@ -46,6 +47,10 @@ export const EffortEntrySchema = z.object({
 /** All dsh-switchman settings. Field names are the settings mutation paths. */
 export const Config = z.object({
 	// --- Phase 1: project language preference -----------------------------
+	/** Where the three language slots live: "global" = these profile-level
+	 *  fields below; "project" = each project's .switchman/lang.json (per
+	 *  session cwd; missing file = ask once per session and save there). */
+	langScope: z.union(["global", "project"]).default("global").volatile(),
 	/** Language for conversational replies. Empty = ask once, then remember. */
 	langConversation: z.string().default("").volatile(),
 	/** Language for code comments. Empty = follow langConversation. */
@@ -101,6 +106,24 @@ export const Config = z.object({
 	wmSubagentCap: z.boolean().default(true).volatile(),
 	/** Subagent hard cap; 0 = share wmForceTokens. */
 	wmSubagentForceTokens: z.number().min(0).default(0).volatile(),
+
+	// --- Teams mode: doctrine injection + whitelist sync -------------------
+	/** Agent Teams master switch. ON = inject the `[SWITCHMAN:TEAMS]` doctrine
+	 *  section (order 10250), keep the DSH child-model whitelist detection in
+	 *  the pools table, and asynchronously ensure the agent-team-profile
+	 *  bundle is enabled. OFF = plain subagent dispatch mode: no teams
+	 *  doctrine, no whitelist detection (the DSH factory conservative team
+	 *  policy takes over); the bundle is never disabled and the whitelist is
+	 *  never cleared. */
+	teamsMode: z.boolean().default(false).volatile(),
+	/** Replace-sync the six-pool union into DSH's subagent model-selection
+	 *  whitelist (`subagent-model-selection-settings`) whenever the teams
+	 *  orchestration runs — an INDEPENDENT switch: it does not require
+	 *  teamsMode, and teamsMode alone does not sync. switchman is the single
+	 *  source of truth: the deduplicated union overwrites allowedModels
+	 *  wholesale. The whitelist only applies to top-level sessions composed
+	 *  afterwards. */
+	syncWhitelist: z.boolean().default(false).volatile(),
 });
 
 /** The six dispatch lanes, in display order. */

package/host/context-watch.js

@@ -18,14 +18,19 @@
  *   compaction only inside each preset's isolated per-agent group
  *   (isolate: { compaction: true }), so no root-level inject or lookup can
  *   reach it — the borrowed handler's closure carries the right composition.
- *   Auto handover is fire-and-forget with a session-level in-flight flag
- *   plus a 10-minute cooldown. Manual /ctx-handover is the full four-step
- *   flow: fork a dormant backup session (subagents' fork provider, economy
- *   pool model), write the handover document skeleton, compact, then wake
- *   this session (agent.followup + sessions.flush, the schedule service's
- *   delivery channel) to fill in the document and continue the unfinished
- *   task. /ctx-pause and /ctx-resume toggle process-lifetime pause
- *   state (a restart resumes enforcement — the safe side).
+ *   Every handover trigger — the force-tier automation (fire-and-forget,
+ *   session-level in-flight flag plus a 10-minute cooldown) and manual
+ *   /ctx-handover — shares one four-step flow: fork a dormant backup
+ *   session (subagents' fork provider, economy pool model), write the
+ *   handover document skeleton, compact via the borrowed per-agent
+ *   /compact (retried on a growing backoff until the agent goes idle,
+ *   because the automation fires mid-turn), then wake this session
+ *   (agent.followup + sessions.flush, the schedule service's delivery
+ *   channel) to fill in the document and continue the unfinished task.
+ *   The live handover phase feeds the force-tier banner so progress is
+ *   visible instead of silent. /ctx-pause and /ctx-resume toggle
+ *   process-lifetime pause state (a restart resumes enforcement — the
+ *   safe side).
  *
  * All session state is in-process Maps; every path is fail-open (a failing
  * measurement or missing service degrades the banner to "" or the gate to
@@ -35,6 +40,8 @@
 import { randomUUID } from "node:crypto";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { clearHandover, handoverOf, recordHandover } from "./handover-state.js";
+import { enumerateRunningSubagents, sessionRecordPath, sessionRecordsDir } from "./subagents.js";
 
 /** Tools whose result text is accounted against the per-turn read budget. */
 const ACCOUNT_TOOLS = new Set(["read", "glob", "grep", "bash"]);
@@ -140,8 +147,9 @@ function measureNow(ctx, agent) {
 
 // ---- banner rendering (pure given state + measurement) ---------------------
 
-/** Root-session banner: byte-stable anchor line + tier advice lines. */
-function renderRootBanner(level, used, th, autoHandover) {
+/** Root-session banner: byte-stable anchor line + tier advice lines plus
+ * the live handover progress (phase/attempt) and auto-cooldown state. */
+function renderRootBanner(level, used, th, status) {
 	const head =
 		`[SWITCHMAN:WATERMARK] level=${level} used=${kilo(used)}` +
 		` budget=${kilo(th.soft)}/${kilo(th.hard)}/${kilo(th.force)}`;
@@ -153,11 +161,22 @@ function renderRootBanner(level, used, th, autoHandover) {
 	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.`);
-		lines.push(
-			autoHandover
-				? `an automatic context handover (compaction) is armed and will fire at the next step boundary.`
-				: `run /ctx-handover to trigger a manual context handover.`,
-		);
+		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");
 }
@@ -199,7 +218,15 @@ function renderBanner(ctx, config, state, agent) {
 			return renderSubBanner(used, subTh);
 		}
 		const level = state.paused.has(sessionId) ? "paused" : levelOf(used, th);
-		return renderRootBanner(level, used, th, readBool(config.wmAutoHandover, true));
+		const live = handoverOf(sessionId);
+		const elapsed = Date.now() - (state.lastHandover.get(sessionId) ?? 0);
+		return renderRootBanner(level, 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)),
+			tool: state.handoverTool ?? undefined,
+		});
 	} catch {
 		return "";
 	}
@@ -260,6 +287,7 @@ function applyContextWatch(ctx, config) {
 	const state = {
 		paused: new Set(),
 		inflight: new Set(),
+		handoverTool: null,
 		lastHandover: new Map(),
 		readUsed: new Map(),
 	};
@@ -282,46 +310,32 @@ function applyContextWatch(ctx, config) {
 	// ctx.commands.find(agent, "compact") merges that agent's scoped layer and
 	// returns the definition whose handler closure already carries the right
 	// composition context with compaction injected.
-	const sessionCompact = (agent, commandId, signal) => {
-		let definition;
+	/** Find the agent's scoped /compact definition without invoking it. */
+	const compactDefinition = (agent) => {
 		try {
-			definition = ctx.commands?.find?.(agent, "compact");
+			const definition = ctx.commands?.find?.(agent, "compact");
+			return typeof definition?.handler === "function" ? definition : undefined;
 		} catch {
-			definition = undefined;
+			return undefined;
 		}
-		if (definition === undefined || typeof definition.handler !== "function") return undefined;
+	};
+
+	const sessionCompact = (agent, commandId, signal) => {
+		const definition = compactDefinition(agent);
+		if (definition === undefined) return undefined;
 		const invocation = Object.freeze({
 			commandId,
 			agent,
 			rawInput: "",
 			attachments: Object.freeze([]),
-			signal,
+			// The borrowed /compact handler (and compactNow behind it) touches
+			// signal.throwIfAborted()/aborted unconditionally; the auto path
+			// has no real signal, so always carry a fresh un-aborted one.
+			signal: signal ?? new AbortController().signal,
 		});
 		return Promise.resolve(definition.handler(invocation));
 	};
 
-	const startHandover = (agent, sessionId) => {
-		state.inflight.add(sessionId);
-		let promise;
-		try {
-			promise = sessionCompact(agent, `switchman-auto-${sessionId}`, undefined);
-			if (promise === undefined)
-				warn(`auto handover found no per-agent /compact command for session ${sessionId} — nothing to do`);
-		} catch (error) {
-			warn(`handover failed to start: ${error?.message ?? error}`);
-			promise = undefined;
-		}
-		const settle = () => state.inflight.delete(sessionId);
-		if (promise !== undefined && typeof promise.then === "function") {
-			promise.then(
-				() => ctx.logger?.info?.(`dsh-switchman: context handover settled for session ${sessionId}`),
-				(error) => warn(`context handover failed for session ${sessionId}: ${error?.message ?? error}`),
-			).then(settle, settle);
-		} else {
-			settle();
-		}
-	};
-
 	/** First {provider, model} route of a volatile pool field, or null. */
 	const firstPoolRoute = (field) => {
 		const raw = readValue(field);
@@ -378,14 +392,30 @@ function applyContextWatch(ctx, config) {
 	 *  the session's working directory. The mechanical facts land now (before
 	 *  compaction); the agent's continuation turn fills in the task-state
 	 *  summary using the compaction summary it can still see. Null when the
-	 *  session exposes no usable cwd or the write fails. */
-	const writeHandoverSkeleton = (agent, sessionId, backupId, used) => {
+	 *  session exposes no usable cwd or the write fails. Any still-running
+	 *  background subagents are recorded too: compaction orphans them from
+	 *  every plugin-visible registry, so without this section the compacted
+	 *  agent cannot know its dispatched work is alive (and double-dispatches).
+	 *  */
+	const writeHandoverSkeleton = (agent, sessionId, backupId, used, running) => {
 		const cwd = agent?.session?.header?.cwd;
 		if (typeof cwd !== "string" || cwd === "") return null;
 		const stamp = new Date().toISOString().replace(/[:.]/gu, "-");
 		const directory = join(cwd, ".dsh-switchman", "handover");
 		const short = sessionId.replace(/^session-/u, "").slice(0, 8) || sessionId;
 		const path = join(directory, `${stamp}-${short}.md`);
+		const runningSection =
+			Array.isArray(running) && running.length > 0
+				? [
+						`## Running background subagents (captured before compaction — still alive)`,
+						``,
+						...running.map(
+							(child) =>
+								`- \`${child.id}\`${child.label ? ` — ${child.label}` : ""}${child.mode ? ` (${child.mode})` : ""} — STILL RUNNING. Collect its report when it settles (in-session completion notice, or read its session record at ${sessionRecordPath(child.id)}) before re-dispatching anything similar — do not duplicate live work.`,
+						),
+						``,
+					]
+				: [];
 		try {
 			mkdirSync(directory, { recursive: true });
 			writeFileSync(
@@ -397,6 +427,7 @@ function applyContextWatch(ctx, config) {
 					`- context used before compaction: ~${used ?? "unknown"} tokens`,
 					`- backup fork session: ${backupId ?? "(fork failed — the full history remains in this session's append-only log)"}`,
 					``,
+					...runningSection,
 					`## Task state (filled in by the agent right after the handover)`,
 					``,
 					`- goal / objective in flight:`,
@@ -420,11 +451,23 @@ function applyContextWatch(ctx, config) {
 	 *  uses: agent.followup + sessions.flush) instructing the agent to fill
 	 *  in the handover document from the compaction summary now in context
 	 *  and continue the unfinished task. */
-	const armContinuation = async (agent, backupId, docPath) => {
+	const armContinuation = async (agent, backupId, docPath, running) => {
 		if (typeof agent?.followup !== "function") {
 			warn("handover continuation skipped: agent exposes no followup()");
 			return;
 		}
+		const runningCount = Array.isArray(running) ? running.length : 0;
+		const runningSentence =
+			runningCount === 0
+				? `No background subagents were detected running at handover time.`
+				: docPath !== null
+					? `${runningCount} background subagent(s) dispatched earlier are STILL RUNNING and are listed in the handover document — collect their results (in-session completion notices, or their session records) instead of re-dispatching duplicate work.`
+					: `${runningCount} background subagent(s) dispatched earlier are STILL RUNNING (the handover document could not be written; inline list): ${running
+							.map(
+								(child) =>
+									`${child.id}${child.label ? ` (${child.label})` : ""} → record ${sessionRecordPath(child.id)}`,
+							)
+							.join("; ")} — collect their results instead of re-dispatching duplicate work (records live under ${sessionRecordsDir()}/<childId>.json).`;
 		const instruction = [
 			"[SWITCHMAN:HANDOVER] A context handover just completed for this session.",
 			backupId !== null
@@ -433,6 +476,7 @@ function applyContextWatch(ctx, config) {
 			docPath !== null
 				? `The handover document skeleton is at ${docPath}.`
 				: `Create the handover document under .dsh-switchman/handover/ in the working directory.`,
+			runningSentence,
 			"Using the compaction summary now in your context, fill in the handover document (goal, completed, in progress, next steps, files), then continue the unfinished task — do not wait for further instructions.",
 		].join(" ");
 		try {
@@ -448,39 +492,134 @@ function applyContextWatch(ctx, config) {
 		}
 	};
 
-	/** Manual /ctx-handover — the full opencode-switchman handover flow on
-	 *  DSH primitives: (1) fork a dormant backup session, (2) write the
-	 *  handover document skeleton, (3) compact via the session's own
-	 *  per-agent /compact handler (borrowed through ctx.commands.find; the
-	 *  preset isolates compaction per agent, so no root-level access exists),
-	 *  and (4) wake this session to fill in the document and continue the
-	 *  unfinished task. Every step degrades independently; compaction is the
-	 *  only mandatory one. */
-	const manualHandover = async (agent, sessionId, commandId, signal) => {
+	/** The shared four-step handover (see the header comment), used by
+	 *  manual /ctx-handover and the force-tier automation alike. The
+	 *  compaction step retries on a growing backoff: both triggers usually
+	 *  fire mid-turn, the runMaintenance behind the borrowed /compact only
+	 *  accepts an IDLE agent, and "busy" arrives as a RESOLVED
+	 *  {kind:"error"} (not a rejection) — so both branches funnel into
+	 *  retryOrFail. Once the agent goes idle the compact lands before the
+	 *  next turn's driver (maintenance latches wake requests by design).
+	 *  The per-session phase map feeds the force-tier banner so the wait is
+	 *  visible instead of silent. */
+	const runHandover = async (agent, sessionId, commandId, signal, source = "manual") => {
 		if (sessionId === null || agent?.session === undefined)
 			return { kind: "error", text: "/ctx-handover: no active session" };
 		if (state.inflight.has(sessionId))
 			return { kind: "success", text: "[SWITCHMAN:WATERMARK] a handover is already in progress for this session." };
-		const borrowed = sessionCompact(agent, commandId, signal);
-		if (borrowed === undefined)
+		if (compactDefinition(agent) === undefined)
 			return {
 				kind: "error",
 				text: "/ctx-handover: this session's preset exposes no /compact command, so no compaction backend is reachable.",
 			};
 		state.inflight.add(sessionId);
 		try {
+			recordHandover(sessionId, { phase: "backup", source, at: Date.now() });
 			const backup = await forkBackup(agent, sessionId, signal);
 			const backupId = backup.childId;
-			const docPath = writeHandoverSkeleton(agent, sessionId, backupId, measureNow(ctx, agent));
-			const result = await borrowed;
-			if (result?.kind === "error")
+			// Snapshot the live background children BEFORE compaction — a
+			// dispatch racing the handover would otherwise be missed, and the
+			// same snapshot feeds both the document section and the
+			// continuation instruction. The sanctioned services answer first
+			// (live registry, no flush lag); the projcache disk scan below is
+			// the fail-open fallback.
+			const runningSubagents = await enumerateRunningSubagents(ctx, sessionId);
+			const docPath = writeHandoverSkeleton(agent, sessionId, backupId, measureNow(ctx, agent), runningSubagents);
+			const delays = [5_000, 15_000, 30_000, 60_000, 120_000, 300_000];
+			const outcome = await new Promise((resolve) => {
+				let attempts = 0;
+				let attempting = false;
+				let timer = null;
+				let watchdog = null;
+				let finished = false;
+				let offStatus = null;
+				const finish = (ok, reason) => {
+					if (finished) return;
+					finished = true;
+					if (timer !== null) clearTimeout(timer);
+					if (watchdog !== null) clearTimeout(watchdog);
+					if (offStatus !== null) {
+						try {
+							offStatus();
+						} catch {
+							/* best-effort listener dispose */
+						}
+					}
+					resolve({ ok, reason });
+				};
+				const attempt = () => {
+					if (finished || attempting) return;
+					attempting = true;
+					attempts += 1;
+					if (timer !== null) {
+						clearTimeout(timer);
+						timer = null;
+					}
+					recordHandover(sessionId, { phase: "compacting", source, attempt: attempts, at: Date.now() });
+					let promise;
+					try {
+						promise = sessionCompact(agent, commandId ?? `switchman-${source}-${sessionId}`, signal);
+					} catch (error) {
+						attempting = false;
+						finish(false, `handover failed to start: ${error?.message ?? error}`);
+						return;
+					}
+					if (promise === undefined) {
+						attempting = false;
+						finish(false, "the per-agent /compact command disappeared");
+						return;
+					}
+					const settleAttempt = (ok, reason) => {
+						attempting = false;
+						if (ok) {
+							finish(true);
+							return;
+						}
+						if (attempts <= delays.length) timer = setTimeout(attempt, delays[attempts - 1]);
+						else finish(false, String(reason));
+					};
+					promise.then(
+						(value) => {
+							if (value !== null && typeof value === "object" && value.kind === "error") {
+								settleAttempt(false, value.text ?? "compact returned an error result");
+								return;
+							}
+							settleAttempt(true);
+						},
+						(error) => settleAttempt(false, error?.message ?? String(error)),
+					);
+				};
+				// Promptness: the agent/status idle transition (the same event
+				// the official compaction layer uses for overflow-retry
+				// cleanup) attempts the moment the turn really ends; the
+				// timers above stay as the backstop for missed or filtered
+				// events. Status reads "idle" externally while our own
+				// maintenance runs, and the `attempting` latch collapses
+				// those re-entrant events.
+				try {
+					offStatus = ctx.on("agent/status", (payload) => {
+						if (payload?.agent === agent && payload?.status === "idle") attempt();
+					});
+				} catch {
+					/* timer-only fallback */
+				}
+				// Watchdog: a borrowed /compact that never settles would hold
+				// the in-flight latch (and this listener) forever; 20 min is
+				// far beyond any real compaction (~2 min observed) yet finite.
+				watchdog = setTimeout(
+					() => finish(false, "handover watchdog timeout — the borrowed /compact never settled"),
+					20 * 60_000,
+				);
+				attempt();
+			});
+			if (!outcome.ok)
 				return {
 					kind: "error",
-					text: `/ctx-handover: compaction failed after backup ${backupId ?? "n/a"} — ${result.text ?? "unknown error"}`,
+					text: `/ctx-handover: compaction failed after backup ${backupId ?? "n/a"} — ${outcome.reason}`,
 				};
-			await armContinuation(agent, backupId, docPath);
-			const backupText =
-				backupId ?? `n/a (${backup.reason ?? "log retains full history"})`;
+			recordHandover(sessionId, { phase: "continuation", source, at: Date.now() });
+			await armContinuation(agent, backupId, docPath, runningSubagents);
+			const backupText = backupId ?? `n/a (${backup.reason ?? "log retains full history"})`;
 			return {
 				kind: "success",
 				text: `[SWITCHMAN:WATERMARK] handover complete — backup ${backupText}, document ${docPath ?? "agent-created"}, compaction done, continuation armed.`,
@@ -488,6 +627,7 @@ function applyContextWatch(ctx, config) {
 		} catch (error) {
 			return { kind: "error", text: `/ctx-handover failed: ${error?.message ?? error}` };
 		} finally {
+			clearHandover(sessionId);
 			state.inflight.delete(sessionId);
 		}
 	};
@@ -504,7 +644,13 @@ function applyContextWatch(ctx, config) {
 			const used = measureNow(ctx, agent);
 			if (used === null || levelOf(used, readThresholds(config)) !== "force") return;
 			state.lastHandover.set(sessionId, now);
-			startHandover(agent, sessionId);
+			runHandover(agent, sessionId, `switchman-auto-${sessionId}`, undefined, "auto").then(
+				(result) =>
+					ctx.logger?.[result?.kind === "error" ? "warn" : "info"]?.(
+						`dsh-switchman: ${result?.text ?? "handover ended"}`,
+					),
+				(error) => warn(`auto handover crashed: ${error?.message ?? error}`),
+			);
 		} catch {
 			/* fail-open: the banner still reports force */
 		}
@@ -611,10 +757,63 @@ function applyContextWatch(ctx, config) {
 	});
 	ctx.commands.register({
 		name: "ctx-handover",
-		description: "Trigger a manual context handover (compaction) for this session now.",
+		description: "Trigger a full context handover for this session now (backup fork + document + compaction + continuation).",
 		handler: (invocation) =>
-			manualHandover(invocation?.agent, sessionIdOf(invocation?.agent), invocation?.commandId, invocation?.signal),
+			runHandover(invocation?.agent, sessionIdOf(invocation?.agent), invocation?.commandId, invocation?.signal, "manual"),
 	});
+
+	// --- E. ctx_handover: the agent-callable front door to the same
+	// four-step handover. The definition uses the register-level shape —
+	// bare ctx.tools.register does not run defineTool's DSL compilation,
+	// so parameters is a full object-root JSON Schema — and registers
+	// best-effort: a validation rejection only skips the tool, never the
+	// plugin. execute returns
+	// fast on purpose — awaiting the compaction here would keep the agent
+	// busy and starve the idle-only /compact — so the flow runs detached
+	// and the result tells the model to end its turn immediately.
+	try {
+		ctx.tools?.register?.({
+			name: "ctx_handover",
+			description:
+				"Trigger a full dsh-switchman context handover for this session NOW: fork a dormant backup session, write the handover document, compact this session at the idle boundary, then wake it to fill in the document and continue the task. Call it when the watermark banner reaches the force tier or the user asks for a handover, then END the turn immediately.",
+			parameters: {
+				type: "object",
+				properties: {
+					reason: {
+						type: "string",
+						description: "Why the handover is triggered now (e.g. 'force tier watermark reached', 'user request'). Optional.",
+					},
+				},
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{ type: "text", text: value }],
+			},
+			async execute(_args, exec) {
+				const agent = exec?.agent;
+				const sessionId = sessionIdOf(agent);
+				// No exec.signal here on purpose: the compact must outlive the
+				// calling turn, and a turn-scoped AbortSignal could abort it.
+				runHandover(agent, sessionId, `switchman-tool-${sessionId ?? "session"}`, undefined, "tool").then(
+					(result) =>
+						ctx.logger?.[result?.kind === "error" ? "warn" : "info"]?.(
+							`dsh-switchman: ${result?.text ?? "handover ended"}`,
+						),
+					(error) => warn(`ctx_handover handover crashed: ${error?.message ?? error}`),
+				);
+				return "[SWITCHMAN:WATERMARK] ctx_handover scheduled: backup fork + handover document + compaction + continuation are running. END this turn now — reply briefly and call no more tools, so the compaction lands at the idle boundary. Your closing line must tell the user the handover is running in the background and will continue automatically (the session-header badge shows the live state) — otherwise the GUI looks idle during fork+compact.";
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: "Switchman context handover",
+				kind: "other",
+				rawInput: args,
+			}),
+		});
+		state.handoverTool = "ctx_handover";
+	} catch (error) {
+		warn(`ctx_handover tool registration failed: ${error?.message ?? error}`);
+	}
 }
 
 export { applyContextWatch };