create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/session-create/dsh-session.js

@@ -0,0 +1,930 @@
+'use strict';
+
+// WP-2 (docs/deepseek-harness-acp-agent-2026-10-28.html §5 D-1/D-2/D-17, §9 S-11; §6.3).
+//
+// The create strategy for a `dsh` (DeepSeek Harness) session: no PTY, no terminal — one ACP child
+// driven by lib/acp/dsh-session-runtime.js (see lib/session-create/structured-session.js for the
+// dispatcher that reaches this after the Wall-E strategy declines the request).
+//
+// WP-3 adds the CTM-owned transcript: one writer per session (lib/acp/dsh-transcript.js) whose path is
+// the session's `jsonlPath`, registered with the session stream through `linkSession` (D-8).
+//
+// WP-4 adds prompts/approvals/status (lib/acp/dsh-prompt-lane.js). WP-5 adds the lifecycle: a `dsh`
+// startup task is written at create (D-B), the restore classifies 'defer' so boot spawns nothing and
+// builds a childless placeholder instead, and `restoreDshSession` (below) is the ONE activation path
+// that resumes the same ACP session on attach/input (D-9/S-40). A child that dies on its own leaves
+// the session in the map restartable (D-5); kill retires the startup task and unlinks nothing (D-10).
+//
+// WP-6 (docs/deepseek-harness-acp-agent-2026-10-28.html §6.6): routed model access. Before the child
+// starts, the create payload's `{routeAlias, model}` (or the OQ-4 default route) is turned into a
+// 0600 patch plus a session token by lib/acp/dsh-route-patch.js; the token is released exactly once,
+// on the child's exit or on a failed start. A create with no usable route is REFUSED with
+// `dsh_route_unavailable` — never a silent fall back to dsh's own key (D-12).
+
+const path = require('node:path');
+const fsp = require('node:fs/promises');
+const { createDshTranscriptWriter, dshTranscriptDir } = require('../acp/dsh-transcript');
+const { prepareDshRoute, releaseDshRoute } = require('../acp/dsh-route-patch');
+const { toAcpMcpServers, withWalleCaller } = require('../acp/dsh-mcp-servers');
+const { parseJsonMcpServers } = require('../mcp-annotations');
+const { getSessionAgentCapabilities } = require('../agent-capabilities');
+const { strFlag } = require('../env-flags');
+const {
+  resolveMcpProfile, normalizeMcpProfile, selectClaudeMcpServers, CORE_MCP_SERVERS, MCP_PROFILE_FULL, MCP_PROFILE_NONE,
+} = require('../lifecycle-wake-experiment');
+
+let _getDeps = null;
+
+function configure(getDeps) {
+  if (typeof getDeps !== 'function') throw new TypeError('session-create dsh requires a dependency getter');
+  _getDeps = getDeps;
+}
+
+// ============================================================================================
+// WP-10 step A (C-6/D-16, OQ-12) — the session's MCP servers reach the ACP child
+// ============================================================================================
+//
+// A dsh session starts with the SAME MCP profile a Claude session in that CTM session would get:
+// the per-session setting (`mcp_profile` on the create frame, persisted onto the durable
+// `startup_tasks` row), else the host default (`CTM_MCP_PROFILE`), else 'core' — `resolveMcpProfile`'s
+// own order, reused rather than re-derived. The Claude path turns that profile into
+// `--strict-mcp-config --mcp-config {mcpServers}` with the map read out of the USER's own
+// ~/.claude.json (lib/lifecycle-wake-experiment.js `resolveCoreClaudeMcpServers`); dsh has no config
+// file of its own, so the same map is materialized here and converted to ACP entries by
+// lib/acp/dsh-mcp-servers.js.
+//
+// The Wall-E server authenticates the CTM session it serves with CTM_SESSION_ID + WALL_E_API_TOKEN
+// from the SAME env seam every other CTM child reads (lib/env-flags.js; never a raw process.env read).
+// Both values ride the ACP JSON-RPC request on the child's stdin ONLY — never the child's process
+// env, argv, a file or a log line (never logged here, and toAcpMcpServers logs reasons only).
+
+// `<homeDir>/.claude.json` parsed, or null. A missing, unreadable or invalid file is "the user
+// declared no MCP servers", never an error worth surfacing. The parsed text is deliberately not held
+// in a variable named `content`/`blob`/`transcript` (main-thread lint's JSON.parse hot-path pattern).
+async function readClaudeJson(homeDir) {
+  if (!homeDir) return null;
+  let raw = '';
+  try {
+    raw = await fsp.readFile(path.join(homeDir, '.claude.json'), 'utf8');
+  } catch { /* expected: no ~/.claude.json (a host where Claude Code never ran) -- no MCP servers to forward */
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch { /* expected: a torn or hand-broken ~/.claude.json -- Claude itself would refuse it too; forward none */
+    return null;
+  }
+}
+
+/**
+ * The normalized MCP server map for `profile`, read the way the Claude path reads it: the USER's own
+ * `<homeDir>/.claude.json`, user scope (`mcpServers`) then project scope (`projects[cwd].mcpServers`,
+ * which wins). `<cwd>/.mcp.json` is NEVER consulted — it is repo-controlled, so a checked-out branch
+ * could point `command` at anything (the same two scopes, and the same reasoning, as the security
+ * note on `resolveCoreClaudeMcpServers`).
+ *
+ *   'none' -> {}                     (dsh's own key, no MCP server at all)
+ *   'core' -> CORE_MCP_SERVERS only  (the WP-1 cheap default: wall-e, codebase-memory-mcp)
+ *   'full' -> everything the user's config declares (dsh has no config file to inherit, so 'full'
+ *             must be materialized here instead of being left to the CLI as it is for Claude)
+ *
+ * Async fs only: this runs on the interactive create/restore path (main-thread lint).
+ */
+async function resolveProfileMcpServers({ profile, homeDir = '', cwd = '' } = {}) {
+  const normalized = normalizeMcpProfile(profile) || 'core';
+  if (normalized === MCP_PROFILE_NONE) return {};
+  const claudeJson = await readClaudeJson(homeDir);
+  if (!claudeJson) return {};
+  const selected = selectClaudeMcpServers(claudeJson, normalized === MCP_PROFILE_FULL ? null : CORE_MCP_SERVERS, { cwd });
+  return parseJsonMcpServers({ mcpServers: selected });
+}
+
+/**
+ * The ACP `mcpServers` list (and the profile it came from) for ONE dsh start. `profileSource.mcpProfile`
+ * is the raw session setting — `mcp_profile ?? mcpProfile`, exactly what server.js's
+ * `_sessionMcpProfileSetting` reads on the Claude path.
+ *
+ * Never throws: a resolver failure leaves the child with no forwarded servers (its own key) rather
+ * than costing the session its start.
+ *
+ * @returns {Promise<{profile: string, mcpServers: Array<object>}>}
+ */
+async function buildDshMcpServers(deps, { profileSource = {}, env = {}, cwd = '', ctmSessionId = '' } = {}) {
+  const resolve = typeof deps.resolveMcpServers === 'function' ? deps.resolveMcpServers : resolveProfileMcpServers;
+  const { profile } = resolveMcpProfile({ mcpProfile: profileSource.mcpProfile, env });
+  let servers = {};
+  try {
+    servers = await resolve({ profile, homeDir: String(env.HOME || ''), cwd, ctmSessionId });
+  } catch (error) {
+    /* REPORT: this start forwards no MCP servers; the session itself must still come up. */
+    deps.logError(`[dsh-session] MCP server resolution failed (${(error && error.message) || 'error'}); starting with no forwarded MCP servers`);
+    servers = {};
+  }
+  const entries = toAcpMcpServers(servers, {
+    // A dropped declaration is a fact about the user's config, reported once per start, by NAME and
+    // reason — toAcpMcpServers never puts an env/header VALUE in a line.
+    log: (message) => deps.logError(`[dsh-session] ${message}`),
+  });
+  return { profile, mcpServers: withWalleCaller(entries, { ctmSessionId, walleToken: strFlag('WALL_E_API_TOKEN', '') }) };
+}
+
+// Persist an EXPLICIT per-session profile onto the startup_tasks row `addStartupTaskWithRetry` just
+// wrote, so a deferred restore resolves the SAME servers (the Claude path's own contract:
+// lib/session-create/provider-process.js writes this column post-create). '' ("no opinion", or a
+// value normalizeMcpProfile collapsed) is deliberately NOT written — the column's DEFAULT '' already
+// means "no opinion" and old rows must keep reading that way. Best-effort: never fails a create.
+function persistDshMcpProfile(deps, sessionId, profile) {
+  if (!profile || typeof deps.dbModule?.updateStartupTaskMcpProfile !== 'function') return undefined;
+  // The owner write may be sync or async (owner client); the chain catches both.
+  return Promise.resolve().then(() => deps.dbModule.updateStartupTaskMcpProfile(sessionId, profile)).catch((error) => {
+    /* REPORT: only the next restore's profile is affected; it falls back to the default. */
+    deps.logError(`[dsh-session] mcp_profile persist failed (${(error && error.message) || 'error'})`);
+  });
+}
+
+// The model the bridge reports as current (`configOptions` category/id `model`) — the ACP session's
+// own choice, surfaced on the session row and the index. Anything unexpected reads as null.
+//
+// WP-8 (§9b M-12): the ACP `model` option's `currentValue` is a JSON PAIR STRING — `["<group>","<model>"]`
+// (see tests/fixtures/acp/dsh-0.2.1-rc.2-turn.jsonl) — so the plain model id is the pair's SECOND
+// element, never the raw JSON text (the rev-5 cosmetic bug: an own-key route stored the JSON pair as
+// `model_id`). A plain (non-JSON) value is returned unchanged.
+function plainModelIdFromConfigValue(value) {
+  if (typeof value !== 'string' || !value) return null;
+  if (value[0] === '[') {
+    try {
+      const parsed = JSON.parse(value);
+      if (Array.isArray(parsed) && parsed.length >= 2 && typeof parsed[1] === 'string' && parsed[1]) return parsed[1];
+    } catch { /* expected: a non-JSON currentValue is just the plain model id */ }
+  }
+  return value;
+}
+
+// The ACP `model` config option, or null. ONE finder: the owner bind, the runtime's `setModel` and the
+// lead-model controller all ask here instead of re-deriving the match.
+function findModelOption(configOptions) {
+  if (!Array.isArray(configOptions)) return null;
+  return configOptions.find((option) => option
+    && (option.category === 'model' || option.id === 'model')) || null;
+}
+
+function modelIdFromConfigOptions(configOptions) {
+  const entry = findModelOption(configOptions);
+  return entry ? plainModelIdFromConfigValue(entry.currentValue) : null;
+}
+
+// Every selectable entry of an ACP config option, flattened across the bridge's NESTED group shape
+// (`options: [{group, name, options: [{value, name}]}]`, see tests/fixtures/acp/dsh-0.2.1-rc.2-turn.jsonl)
+// — the ONE place that nesting is read. `value` is the OPAQUE value the wire expects (for the model
+// option it is the JSON pair string); `name` is the display label the child also accepts by identity.
+function configOptionEntries(option) {
+  const out = [];
+  const push = (item) => {
+    if (!item || typeof item !== 'object') return;
+    if (typeof item.value === 'string' && item.value) {
+      out.push({ value: item.value, name: typeof item.name === 'string' ? item.name : '' });
+    }
+    if (Array.isArray(item.options)) for (const child of item.options) push(child);
+  };
+  if (option && Array.isArray(option.options)) for (const item of option.options) push(item);
+  return out;
+}
+
+/**
+ * The OPAQUE ACP option value for a plain model id: the entry whose JSON pair's second element (or
+ * whose display name) IS the pick. Null when the bridge does not offer it — the caller refuses
+ * `dsh_option_unavailable` rather than sending a hand-built string (D-12).
+ */
+function configValueForModelId(option, modelId) {
+  const wanted = String(modelId == null ? '' : modelId).trim();
+  if (!wanted) return null;
+  for (const entry of configOptionEntries(option)) {
+    if (plainModelIdFromConfigValue(entry.value) === wanted || (entry.name && entry.name === wanted)) return entry.value;
+  }
+  return null;
+}
+
+/**
+ * The OPAQUE ACP option value for an effort LEVEL (`'' | 'off' | 'low' | 'high' | 'max'`). A plain
+ * (non-JSON) value is matched exactly; the display name is only consulted for a NON-empty level, so an
+ * unnamed entry can never be matched by the empty default level.
+ */
+function configValueForOptionLevel(option, level) {
+  const wanted = String(level == null ? '' : level);
+  for (const entry of configOptionEntries(option)) {
+    if (entry.value === wanted) return entry.value;
+    if (wanted && (plainModelIdFromConfigValue(entry.value) === wanted || entry.name === wanted)) return entry.value;
+  }
+  return null;
+}
+
+// ============================================================================================
+// WP-8 (§9b M-7/M-16, D-12/D-13) — the dsh session joins the durable session-model owner store
+// ============================================================================================
+//
+// dsh does NOT defer (M-7): there is no CLI hook and no native transcript to scan, and the child is
+// an ACP process, never a PTY — so the owner binds from the bridge's OWN `configOptions` at session
+// start (session/new and session/resume both return it) and again on every `config_option_update`.
+// Everything here is a no-op when the runtime is not wired, so a unit harness that passes no
+// `modelStateRuntime` still exercises the create/restore lifecycle unchanged.
+
+// The model-owner SOURCE for this harness (lib/coding-session-model-state.js SOURCE_GROUPS.dsh).
+const DSH_CONFIG_OPTION_SOURCE = 'dsh:config-option';
+// WP-8 step 3 (D-13): the SOURCE of the ONE `completed-turn` observation a settled turn writes.
+const DSH_TURN_SOURCE = 'dsh:turn';
+
+// The ACP effort config option, or null. dsh's own effort option id is the ACP `reasoning_effort`; ONE
+// finder so the picker read, the runtime's `setEffort` and the lead-model controller agree on the id
+// they write (WP-8 §6.7).
+function findEffortOption(configOptions) {
+  if (!Array.isArray(configOptions)) return null;
+  return configOptions.find((entry) => entry && typeof entry === 'object'
+    && (entry.id === 'reasoning_effort' || entry.id === 'reasoning-effort' || entry.category === 'reasoning_effort')) || null;
+}
+
+// The effort the picker must show, when the bridge declares one. Anything else (or a non-string value)
+// reads as "not reported".
+function effortFromConfigOptions(configOptions) {
+  const option = findEffortOption(configOptions);
+  const value = option && typeof option.currentValue === 'string' ? option.currentValue.trim() : '';
+  return value && value.length <= 64 ? value : null;
+}
+
+/*
+ * The durable per-lifetime process generation. This is the SAME allocator the PTY launch plan and the
+ * API-attach path use (lib/coding-session-generation-runtime.js), never a process-local counter: the
+ * model-owner store fences rebinds numerically (`owner.processGeneration < current` is `stale`, and
+ * the adoption fence only admits the LATEST reservation), so a counter that restarts at 1 after a CTM
+ * restart would refuse every re-bind of a surviving ACP session. A host without the runtime, or a
+ * failed reservation, yields NO generation — the session then stays unbound (`dsh_presession`) rather
+ * than binding a made-up number, and the create/restore is never failed by this bookkeeping write.
+ */
+async function _allocateDshGeneration(ctmSessionId) {
+  const deps = _getDeps();
+  const runtime = deps.codingSessionGenerationRuntime;
+  if (!runtime || typeof runtime.allocateGeneration !== 'function') return null;
+  try {
+    const result = await runtime.allocateGeneration({ sessionId: ctmSessionId });
+    return Number.isSafeInteger(result?.generation) && result.generation >= 0 ? result.generation : null;
+  } catch (error) {
+    deps.logError(`[dsh-session] generation allocation failed for ${String(ctmSessionId).slice(0, 8)}: ${(error && error.message) || error}`);
+    return null;
+  }
+}
+
+/*
+ * Bind (or re-bind) the durable owner row for a dsh session from its ACP config options.
+ *
+ * The owner tuple is the model runtime's OWN `snapshot()` (one declaration —
+ * lib/coding-session-model-owner.js) so a hand-built literal can never disagree with the collector.
+ * A session with no generation has no owner yet and is skipped explicitly. A null model still binds
+ * the OWNER (the row exists; it simply carries no fact) — that is what distinguishes "bound, nothing
+ * observed yet" from `dsh_presession`.
+ */
+async function bindDshModelOwner(session, configOptions) {
+  // Never fatal, never an unhandled rejection: the config-option observer calls this fire-and-forget,
+  // and a failed owner write must leave the session running (unbound = `dsh_presession`).
+  try {
+    return await _bindDshModelOwner(session, configOptions);
+  } catch (error) {
+    _getDeps().logError(`[dsh-session] model owner bind failed for ${String(session && session.id).slice(0, 8)}: ${(error && error.message) || error}`);
+    return false;
+  }
+}
+
+async function _bindDshModelOwner(session, configOptions) {
+  const runtime = _getDeps().modelStateRuntime;
+  if (!session || !runtime || typeof runtime.applyResult !== 'function') return false;
+  const owner = runtime.snapshot(session, 'dsh');
+  if (!owner) return false;
+  const observations = [];
+  const modelId = modelIdFromConfigOptions(configOptions);
+  if (modelId) {
+    // ONE selection + ONE resolved observation, same value and timestamp: the bridge reports what it
+    // is actually running (there is no alias stage to wait out), so both slots carry concrete
+    // evidence. `Date.now()` (not the injected create clock) is the observation time the reducer
+    // orders on, and a `config_option_update` is always NEWER than the fact it replaces.
+    const observedAtMs = Date.now();
+    const effort = effortFromConfigOptions(configOptions);
+    const base = {
+      ctmSessionId: owner.ctmSessionId,
+      agentType: owner.agentType,
+      providerSessionId: owner.providerSessionId,
+      processGeneration: owner.processGeneration,
+    };
+    for (const kind of ['selection', 'resolved']) {
+      observations.push({
+        ...base, kind, value: modelId, providerId: 'dsh', selectionKind: 'concrete',
+        effort, source: DSH_CONFIG_OPTION_SOURCE, sourceRevision: null, outcome: null, observedAtMs,
+      });
+    }
+  }
+  const outcome = await runtime.applyResult(session, { id: String(session.id || ''), owner, observations });
+  /*
+   * A bare `applyResult` (origin 'legacy') deliberately publishes NO health claim — it is not an
+   * acknowledged collector read. Without the read below the public envelope would answer
+   * `owner_unavailable` for a session whose row IS bound, so the durable restore read publishes this
+   * owner's own state: `restored` with facts, `no_model_evidence` without. This is exactly what the
+   * periodic model-sync hydrate does for every other native session, one tick later.
+   */
+  await runtime.hydrate(session);
+  return outcome;
+}
+
+function isDshRequest(state, deps) {
+  const agentType = state.agentType || state.msg?.agentType;
+  if (deps.normalizeAgentType(agentType) === 'dsh') return true;
+  const cmd = (state.launchParams && state.launchParams.cmd) || state.msg?.cmd;
+  return deps.detectAgentType(cmd) === 'dsh';
+}
+
+async function createDshSession(state) {
+  const deps = _getDeps();
+  if (!isDshRequest(state, deps)) return false;
+
+  const { id, ws } = state;
+  const launch = state.launchParams || {};
+  const msg = state.msg || {};
+  const cwd = state.cwd || launch.cwd || '';
+  const title = launch.title || 'DeepSeek Harness';
+  // WP-14 (docs/deepseek-harness-acp-agent-2026-10-28.html §9b W-2/W-3, D-21). A DELEGATED WORKER
+  // reaches this same create path (delegate-worker.js's deps.createSession -> handleCreatePrepared ->
+  // handleCreate -> structured-session.js, routed here by `agentType:'dsh'`). Instead of an argv it
+  // carries ACP start params (resolve-launch-params.js's dsh branch): the brief as the FIRST PROMPT,
+  // the routed pick, the report path and the MCP set. Its proxy credential is the WORKER token the
+  // delegate path already minted (budgeted; leases apply) and that rides the request's own resolved
+  // launch env — so the lead token `prepareDshRoute` would otherwise mint is not wanted here (see the
+  // credential block below). `workerCreate` is derived from the create request itself; an interactive
+  // dsh card never carries it and its behaviour is byte-for-byte unchanged.
+  const acpLaunch = (msg.acp && typeof msg.acp === 'object' && !Array.isArray(msg.acp))
+    ? msg.acp
+    : (launch.acp && typeof launch.acp === 'object' && !Array.isArray(launch.acp) ? launch.acp : null);
+  const workerCreate = msg.agentRole === 'worker' || !!acpLaunch;
+  const launchEnv = deps.buildLaunchEnv(state);
+  const workerCredential = workerCreate && launchEnv && typeof launchEnv.ANTHROPIC_AUTH_TOKEN === 'string'
+    ? launchEnv.ANTHROPIC_AUTH_TOKEN : '';
+
+  // WP-6 (OQ-4): the card's Model select sends `{routeAlias, model}` on the create payload; absent,
+  // dsh-route-patch picks the default (first DeepSeek-model Portkey route serving anthropic-messages).
+  // `routeAlias:'dsh-own-key'` is the explicit opt-out that keeps dsh on its own provider.
+  const routeDeps = deps.dshRouteDeps || null;
+  const route = await prepareDshRoute({
+    ctmSessionId: id,
+    routeAlias: msg.routeAlias || msg.route_alias || launch.routeAlias || null,
+    model: msg.model || msg.routeModel || null,
+    deps: routeDeps,
+  });
+  if (!route || !route.ok) {
+    deps.wsSend(ws, JSON.stringify({
+      type: 'error',
+      id,
+      code: (route && route.reason) || 'dsh_route_unavailable',
+      message: (route && route.detail) || 'No model route is available for the DeepSeek Harness.',
+    }));
+    return true;
+  }
+  // WP-10 step A (C-6/D-16): the create frame's own profile setting (`mcp_profile`, '' = no
+  // opinion), the same field server.js's _sessionMcpProfileSetting reads on the Claude path. The
+  // RESOLVED profile (setting -> host default -> 'core') is what the servers come from; only the
+  // explicit setting is persisted onto the durable row below.
+  const mcpProfileSetting = normalizeMcpProfile(msg.mcp_profile ?? msg.mcpProfile ?? launch.mcp_profile ?? launch.mcpProfile);
+  const mcp = await buildDshMcpServers(deps, {
+    profileSource: { mcpProfile: mcpProfileSetting },
+    env: launchEnv,
+    cwd,
+    ctmSessionId: id,
+  });
+  // WP-14: a worker create keeps the credential its own launch env carries (the budgeted worker
+  // token) instead of the lead token registered a moment ago — an unused registration is an artifact
+  // CTM should not leave live. The patch is still written and kept (D-10: CTM never deletes
+  // artifacts; it declares the loopback baseURL the child must use), and the worker token is released
+  // by the worker-exit path (delegate-worker.js / server.js), never here.
+  let routeToken = route.token;
+  if (workerCredential && routeToken) {
+    await releaseDshRoute({ ctmSessionId: id, token: routeToken, deps: routeDeps });
+    routeToken = null;
+  }
+  // WP-10 step A: a worker create's own resolved MCP map (the map delegate-worker hands
+  // resolveWorkerLaunchParams, which the launch spec carries as `acp.mcpServers`) is converted here the
+  // same way the profile map is; absent one, the dsh profile resolution above stands.
+  const workerMcpMap = workerCreate && acpLaunch && acpLaunch.mcpServers && typeof acpLaunch.mcpServers === 'object'
+    && !Array.isArray(acpLaunch.mcpServers) && Object.keys(acpLaunch.mcpServers).length ? acpLaunch.mcpServers : null;
+  // A worker never carries the CTM runtime bearer (agent-presets.js's worker strip, C-8/W-7), so its
+  // wall-e entry is stamped with its own session id only; and a worker with no MCP map gets NONE (the
+  // strict-MCP diet a claude/codex worker gets), never the lead profile's servers.
+  const acpMcpServers = workerCreate
+    ? (workerMcpMap ? withWalleCaller(toAcpMcpServers(workerMcpMap, { log: (message) => deps.logError(`[dsh-session] ${message}`) }), { ctmSessionId: id }) : [])
+    : null;
+  // WP-8 (M-16): the live session object does not exist until below; an update that arrives in the
+  // meantime (the child is already talking) is bound against whatever `bindSession` holds by then.
+  let bindSession = null;
+  const result = await deps.dshRuntime.start({
+    ctmSessionId: id,
+    cwd,
+    env: { ...launchEnv, ...(route.env || {}), ...(workerCredential ? { ANTHROPIC_AUTH_TOKEN: workerCredential } : {}) },
+    mcpServers: acpMcpServers || mcp.mcpServers,
+    ...(route.patchPath ? { patchPath: route.patchPath } : {}),
+    // D-12: a live pick is `session/set_config_option`; the bridge answers with a
+    // `config_option_update` carrying the new list, which is the model-owner evidence.
+    onConfigOptions: (_id, configOptions) => { if (bindSession) void bindDshModelOwner(bindSession, configOptions); },
+    // WP-6: the runtime fires this exactly once, on whichever path the child dies. A start that
+    // FAILS never fires it (the token is released below instead), so there is no double revoke.
+    // WP-14: null for a worker create (its own credential was released above).
+    ...(routeToken ? { onStopped: () => { void releaseDshRoute({ ctmSessionId: id, token: routeToken, deps: routeDeps }); } } : {}),
+  });
+  if (!result || !result.ok) {
+    // A token whose child never started would otherwise stay live in the proxy until a restart.
+    if (route.token) await releaseDshRoute({ ctmSessionId: id, token: route.token, deps: routeDeps });
+    // Same frame the existing create path sends for a create that could not start: type 'error'
+    // with the machine `code` (see lib/session-create/provider-process.js's spawn-failure frame).
+    deps.wsSend(ws, JSON.stringify({
+      type: 'error',
+      id,
+      code: (result && result.code) || 'dsh_start_failed',
+      message: (result && result.message) || 'DeepSeek Harness could not be started.',
+    }));
+    return true;
+  }
+
+  const now = deps.now();
+  const modelId = modelIdFromConfigOptions(result.configOptions);
+  // D-8: CTM owns the transcript — `<dataDir>/dsh-transcripts/<acpSessionId>.jsonl`, appended to by every
+  // ACP update (server.js forwards them to this writer) and by every user prompt (WP-4). The file is never
+  // read back here, never truncated and never unlinked (D-10).
+  const transcript = createDshTranscriptWriter({
+    dataDir: deps.getDataDir(),
+    acpSessionId: result.acpSessionId,
+    cwd,
+  });
+  transcript.setModel(modelId);
+  const session = {
+    id,
+    type: 'dsh',
+    transport: 'acp',
+    agentType: 'dsh',
+    cmd: 'dsh',
+    args: [],
+    // WP-11 (D-20): the LIVE capability record of this child — `input.attachments` is true exactly
+    // when the child's own `initialize` advertised image prompt support
+    // (lib/acp/dsh-session-runtime.js `get().imageInput`; the static table row stays false).
+    agentCapabilities: getSessionAgentCapabilities('dsh', { imageInput: result.imageInput === true }),
+    title,
+    label: title,
+    cwd,
+    clients: ws ? [ws] : [],
+    createdAt: now,
+    lastActivity: now,
+    lastMeaningfulActivityAt: now,
+    agentSessionId: result.acpSessionId,
+    model_id: modelId,
+    model_provider: 'dsh',
+    userRenamed: false,
+    jsonlPath: transcript.path,
+    // The delivery target's process identity (lib/remote-terminal-target.js); cleared on child exit.
+    _acpProcess: Object.freeze({ acpSessionId: result.acpSessionId }),
+  };
+  session._dshTranscript = transcript;
+  // WP-14 (§9b W-3, D-21): the live report source for a delegated dsh worker — the last assistant
+  // text of the turn this session last ran, read from the ACP runtime (lib/acp/dsh-session-runtime.js
+  // `get().finalText`). delegate-worker.js's getWorkerStatus reads exactly this property as the
+  // `final_result` source, the same way it reads a PTY worker's turn counter. NON-ENUMERABLE, like
+  // `_dshRoute` below: it is a read-through accessor, not part of the session row a client sees. A
+  // gone child reads '' (never a throw), so a status read after an exit degrades to the value the
+  // exit path stamped into the worker row instead.
+  Object.defineProperty(session, '_dshFinalText', {
+    get: () => {
+      const live = deps.dshRuntime.get(id);
+      return live && typeof live.finalText === 'string' ? live.finalText : '';
+    },
+    enumerable: false,
+    configurable: true,
+  });
+  // WP-10 step A: the RESOLVED MCP profile this child was started with, kept on the live row so the
+  // restart-through-the-map path (markDshRestartable) resumes the same servers. Not secret, and never
+  // sent to a client (the session row's own field list decides what leaves CTM).
+  session._mcpProfile = mcp.profile;
+  // WP-8 (M-7/M-16): the durable per-lifetime generation the owner store fences rebinds with — the
+  // SAME allocator the PTY launch plan and the API-attach path use. Set BEFORE the bind below:
+  // without it `snapshot()` is null and the owner stays unbound (`dsh_presession`).
+  const generation = await _allocateDshGeneration(id);
+  if (generation !== null) session._modelProcessGeneration = generation;
+  bindSession = session;
+  // WP-6: the live routed token/alias/model, held in memory ONLY. NON-ENUMERABLE on purpose: no
+  // Object.keys/for-in/spread/JSON.stringify of a session row can ever carry the token into a client
+  // frame, a broadcast or the DB — only code that names `_dshRoute` can read it.
+  if (route.token) {
+    Object.defineProperty(session, '_dshRoute', {
+      value: Object.freeze({ token: route.token, alias: route.alias, model: route.model }),
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+  deps.setSessionAttentionFields(session, {});
+  deps.setSession(id, session);
+  deps.setupQueueForSession(id);
+  deps.telemetry.track('ctm_session', { type: 'dsh' });
+  try {
+    await deps.detachOwnerMutation('dsh-session-created', () => deps.dbModule.upsertSession(id, {
+      agentSessionId: result.acpSessionId,
+      provider: 'dsh',
+      cwd,
+      projectPath: cwd,
+      title,
+      jsonlPath: transcript.path,
+      fileSize: 0,
+      modifiedAt: '',
+      model: modelId || '',
+      hostname: deps.hostname,
+    }));
+  } catch (error) {
+    deps.logError('[dsh-session] index create error:', error.message);
+  }
+  // WP-8 (M-16): the child is up AND its `agent_sessions` row exists (`provider:'dsh'`,
+  // `agent_session_id` = the ACP id — the row the store's bind requires), so the model owner can bind.
+  // Never fatal: an unbound owner is exactly the `dsh_presession` state the public envelope names.
+  await bindDshModelOwner(session, result.configOptions);
+  // S-26: the session stream maps CTM session -> ACP session (+ transcript path) so the live Conv tail
+  // reads the file this writer appends to.
+  deps.linkSession(id, result.acpSessionId, transcript.path);
+  // WP-5 (D-B, S-40/S-41): the durable restore record. dsh's argv is built by the runtime from
+  // `--profile acp` (+ the patch), NEVER from this array, so the array is free to carry the ROUTED
+  // PICK: `args[0]` is the route alias (`'dsh-own-key'` for the explicit own-key opt-out) and
+  // `chat_session_id` is the ACP session id to `session/resume`. The row carries model_id too.
+  // It NEVER carries the token or any provider key — nothing secret is ever written to startup_tasks.
+  if (!msg._isRestore) {
+    const taskWrite = deps.addStartupTaskWithRetry('dsh', [
+      id, title, 'dsh', [route.alias || 'dsh-own-key'], cwd, route.model || modelId || null, 'dsh', result.acpSessionId,
+    ]);
+    // WP-10 step A: the profile rides the row the write above creates (never the write's own args —
+    // nothing about MCP changes the startup_tasks schema), chained so the UPDATE cannot run before
+    // the row exists. An explicit setting only: see persistDshMcpProfile.
+    if (mcpProfileSetting) {
+      void Promise.resolve(taskWrite).then(() => persistDshMcpProfile(deps, id, mcpProfileSetting));
+    }
+  }
+  const live = deps.dshRuntime.get(id);
+  deps.sendCreated(ws, session, { pid: live ? live.pid : undefined });
+  deps.broadcastSessionList(true, { reason: 'dsh-created' });
+  // WP-14 (§9b W-2): the delegated dsh worker's OTHER half of the launch spec — the brief as the FIRST
+  // PROMPT. There is no argv to carry it (that is the whole point of the dsh branch in
+  // resolve-launch-params.js) and no user at the keyboard, so the create delivers it itself, once, as
+  // soon as the child is up. Deliberately AFTER the created frame/list broadcast (the session exists and
+  // is visible whether or not the prompt lands) and non-fatal: a prompt that cannot be written leaves
+  // the worker with an empty report and its own failure classified at exit — never a half-created
+  // session. The runtime resets the turn's finalText on this call, so the report is THIS turn's text.
+  const firstPrompt = workerCreate && acpLaunch && typeof acpLaunch.prompt === 'string' ? acpLaunch.prompt : '';
+  if (firstPrompt) {
+    const delivery = await deps.dshRuntime.prompt(id, { text: firstPrompt });
+    if (!delivery || delivery.ok !== true) {
+      deps.logError(`[dsh-session] worker brief prompt refused (${(delivery && delivery.code) || 'dsh_prompt_failed'})`);
+    } else {
+      // The prompt is on the wire; the turn settles in the runtime. A rejection is the child's own turn
+      // failure and is reported through the transcript/status path, never as an unhandled rejection here.
+      void delivery.prompt.catch((error) => deps.logError(`[dsh-session] worker brief turn failed (${(error && error.message) || 'error'})`));
+    }
+  }
+  return true;
+}
+
+// ============================================================================================
+// WP-5 — lifecycle: restore on attach, child-exit restartability, kill
+// ============================================================================================
+
+/** The CTM-owned transcript path for an ACP session id (`<dataDir>/dsh-transcripts/<id>.jsonl`). */
+function dshTranscriptPathFor(acpSessionId) {
+  const deps = _getDeps();
+  return path.join(dshTranscriptDir(deps.getDataDir()), `${String(acpSessionId || '')}.jsonl`);
+}
+
+// D-D (AC-5c): a dsh child that died on its own leaves the session in the map, restartable. The
+// session becomes an ordinary deferred placeholder, so the NEXT Send reaches it through the existing
+// queued-input → _startDeferredRestoreSession path and resumes the SAME ACP session.
+function markDshRestartable(session) {
+  if (!session || session.type !== 'dsh') return false;
+  const existing = session._restoreTask;
+  if (existing && existing.type === 'dsh') {
+    session._restoreDeferred = true;
+    return true;
+  }
+  session._restoreTask = {
+    type: 'dsh',
+    session_id: session.id,
+    cwd: session.cwd || '',
+    label: session.label || session.title || 'DeepSeek Harness',
+    // The routed pick the next mint must reuse: the live in-memory route alias, else the own-key opt-out.
+    args: [(session._dshRoute && session._dshRoute.alias) || 'dsh-own-key'],
+    model_id: session.model_id || null,
+    chat_session_id: session.agentSessionId || null,
+    // WP-10 step A: the profile this child was started with, so the next activation forwards the
+    // same MCP servers (the durable path reads the same field off the startup_tasks row).
+    mcp_profile: session._mcpProfile || '',
+  };
+  session._restoreDeferred = true;
+  return true;
+}
+
+// The failure half of a restore: the session STAYS in the map (restartable) and the reason is visible
+// to every attached client. It is deliberately NOT a silent own-key fallback (D-12).
+function _failDshRestore(session, code, message) {
+  const deps = _getDeps();
+  session._dshExitReason = { code, message };
+  session._exited = true;
+  session._lifecycleState = 'exited';
+  session._restoreDeferred = true; // stays restartable: a later attach/Send retries the same path
+  const payload = JSON.stringify({ type: 'exit', id: session.id, exitCode: null, signal: null, reason: code, message });
+  for (const client of session.clients || []) {
+    try {
+      if (client && client.readyState === 1) deps.wsSend(client, payload);
+    } catch (error) {
+      // expected: a dead socket must never break the restore failure path.
+      void error;
+    }
+  }
+  try { deps.broadcastSessionList(true, { reason: 'dsh-restore-failed' }); } catch (error) { void error; }
+  deps.logError(`[dsh-session] restore failed for ${String(session.id || '').slice(0, 8)}: ${code}`);
+  return false;
+}
+
+// The success half of a restore, split out so restoreDshSession can keep one promise identity.
+async function _runDshRestore(session, ctx) {
+  const deps = _getDeps();
+  const { id, cwd, routeAlias, model, acpSessionId } = ctx;
+  const routeDeps = deps.dshRouteDeps || null;
+  // D-9: a FRESH token is minted from the stored pick on every restore (the old one died with the
+  // previous CTM process). A refusal surfaces as this session's exit reason — never a silent fallback.
+  const route = await prepareDshRoute({ ctmSessionId: id, routeAlias, model, deps: routeDeps });
+  if (!route || !route.ok) {
+    return _failDshRestore(session, (route && route.reason) || 'dsh_route_unavailable',
+      (route && route.detail) || 'No model route is available for the DeepSeek Harness.');
+  }
+  // WP-10 step A (C-6/D-16): the SAME profile the create resolved — the durable `startup_tasks` row
+  // the create wrote it onto (`mcp_profile`), else the live row's copy (a restart through the map).
+  const launchEnv = deps.buildLaunchEnv({});
+  const task = session._restoreTask || {};
+  const mcp = await buildDshMcpServers(deps, {
+    profileSource: { mcpProfile: task.mcp_profile ?? task.mcpProfile ?? session._mcpProfile },
+    env: launchEnv,
+    cwd,
+    ctmSessionId: id,
+  });
+  const result = await deps.dshRuntime.start({
+    ctmSessionId: id,
+    cwd,
+    env: { ...launchEnv, ...(route.env || {}) },
+    mcpServers: mcp.mcpServers,
+    ...(route.patchPath ? { patchPath: route.patchPath } : {}),
+    // D-9: resume the SAME ACP session — `session/resume`, never `session/new`. History is NOT
+    // replayed; the CTM transcript already holds it (that is the whole point of D-8).
+    ...(acpSessionId ? { resumeAcpSessionId: acpSessionId } : {}),
+    // WP-8 (M-16): `session/resume` returns the configOptions too, and every later
+    // `config_option_update` re-binds through the SAME observer.
+    onConfigOptions: (_id, configOptions) => { void bindDshModelOwner(session, configOptions); },
+    ...(route.token ? { onStopped: () => { void releaseDshRoute({ ctmSessionId: id, token: route.token, deps: routeDeps }); } } : {}),
+  });
+  if (!result || !result.ok) {
+    if (route.token) await releaseDshRoute({ ctmSessionId: id, token: route.token, deps: routeDeps });
+    return _failDshRestore(session, (result && result.code) || 'dsh_start_failed',
+      (result && result.message) || 'DeepSeek Harness could not be restarted.');
+  }
+
+  const resolvedAcpId = result.acpSessionId || acpSessionId;
+  const modelId = modelIdFromConfigOptions(result.configOptions) || model || null;
+  // The SAME file, reopened append-only (its tail read re-seeds the parentUuid chain, so the restored
+  // rows continue the existing conversation instead of starting a second chain).
+  const transcript = createDshTranscriptWriter({ dataDir: deps.getDataDir(), acpSessionId: resolvedAcpId, cwd });
+  transcript.setModel(modelId);
+  const live = deps.dshRuntime.get(id);
+  // In-place mutation: same id, same `clients` array, so every attached tab keeps its socket.
+  session.transport = 'acp';
+  session.agentType = 'dsh';
+  // WP-11 (D-20): a resumed child is a NEW process lifetime, so the live image capability is
+  // re-stamped from THIS start's initialize answer, exactly like the create path.
+  session.agentCapabilities = getSessionAgentCapabilities('dsh', { imageInput: result.imageInput === true });
+  session.agentSessionId = resolvedAcpId;
+  session.jsonlPath = transcript.path;
+  session.model_id = modelId;
+  session.model_provider = 'dsh';
+  session._dshTranscript = transcript;
+  session._dshExitReason = null;
+  session._exited = false;
+  session._lifecycleState = 'live';
+  session._restoreDeferred = false;
+  session.pid = live ? live.pid : session.pid;
+  // Fresh per-child process identity for the delivery target (set per child, cleared on child exit).
+  session._acpProcess = Object.freeze({ acpSessionId: resolvedAcpId });
+  if (route.token) {
+    Object.defineProperty(session, '_dshRoute', {
+      value: Object.freeze({ token: route.token, alias: route.alias, model: route.model }),
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+  deps.setSession(id, session);
+  deps.linkSession(id, resolvedAcpId, transcript.path);
+  // WP-8 (M-7/M-16): the resumed child is a NEW process lifetime, so it gets a fresh durable
+  // generation (the allocator is monotonic — the store fences rebinds numerically), and the owner is
+  // bound again for the SAME ACP session id from the configOptions `session/resume` just returned.
+  const generation = await _allocateDshGeneration(id);
+  if (generation !== null) session._modelProcessGeneration = generation;
+  await bindDshModelOwner(session, result.configOptions);
+  deps.broadcastSessionList(true, { reason: 'dsh-resumed' });
+  return true;
+}
+
+/**
+ * D-C/D-9/S-40 — the ONE activation path for a restored dsh session.
+ *
+ * The boot loop classifies a `dsh` startup task `'defer'` (lib/resume-admission.js), so boot builds a
+ * CHILDLESS placeholder and spawns nothing. A client attach or a queued Send funnels through
+ * server.js's `_startDeferredRestoreSessionNow`, which prefixes this call. The existing placeholder
+ * object is mutated in place — never replaced — so its id and its attached clients survive.
+ *
+ * @param {object} session  the deferred placeholder (`type: 'dsh'`)
+ * @param {object} [opts]
+ * @returns {Promise<boolean>} true when the child is up and the session is live again
+ */
+async function restoreDshSession(session, opts = {}) {
+  const deps = _getDeps();
+  if (!session || session.type !== 'dsh') return false;
+  const id = String(session.id || '');
+  if (!id) return false;
+  // Already live (a racing wake won): nothing to do, and specifically no second token minted.
+  if (deps.dshRuntime.isRunning(id)) return true;
+  if (session._dshRestorePromise) return session._dshRestorePromise;
+  const task = session._restoreTask || {};
+  const cwd = session.cwd || task.cwd || '';
+  const routeAlias = Array.isArray(task.args) && task.args.length ? task.args[0] : null;
+  const model = task.model_id || session.model_id || null;
+  const acpSessionId = String(task.chat_session_id || session.agentSessionId || '');
+  session._restoreStarting = true;
+  void opts; // the activation source is recorded by the caller's own lifecycle stamps
+  const pending = _runDshRestore(session, { id, cwd, routeAlias, model, acpSessionId })
+    .then((started) => { session._restoreStarting = false; return started; })
+    .catch((error) => {
+      session._restoreStarting = false;
+      return _failDshRestore(session, 'dsh_start_failed',
+        (error && error.message) || 'DeepSeek Harness could not be restarted.');
+    });
+  session._dshRestorePromise = pending;
+  try {
+    return await pending;
+  } finally {
+    if (session._dshRestorePromise === pending) session._dshRestorePromise = null;
+  }
+}
+
+// ============================================================================================
+// WP-8 step 3 (§6.7, §9b M-15/M-16; D-12/D-13) — the live pick: effort/model write, route relaunch
+// ============================================================================================
+
+/*
+ * ONE `completed-turn` observation when a prompt turn settles `completed` (D-13 semantics, the SAME
+ * `applyResult` path `bindDshModelOwner` uses — the store admits `dsh:turn` for that kind already).
+ *
+ * The value is the session's CURRENT model read from the live runtime entry's `configOptions` (the
+ * bridge is the only truth for what actually ran), falling back to the session row. A turn with no
+ * model evidence writes nothing: the store's own rule for this kind requires a concrete value, and
+ * inventing one would be worse than staying silent. Never fatal — a failed observation write must
+ * never turn a completed turn into a failed one.
+ */
+async function observeDshCompletedTurn(session, configOptions) {
+  try {
+    return await _observeDshCompletedTurn(session, configOptions);
+  } catch (error) {
+    _getDeps().logError(`[dsh-session] completed-turn observation failed for ${String(session && session.id).slice(0, 8)}: ${(error && error.message) || error}`);
+    return false;
+  }
+}
+
+async function _observeDshCompletedTurn(session, configOptions) {
+  const deps = _getDeps();
+  const runtime = deps.modelStateRuntime;
+  if (!session || !runtime || typeof runtime.applyResult !== 'function') return false;
+  const owner = runtime.snapshot(session, 'dsh');
+  if (!owner) return false;
+  const live = typeof deps.dshRuntime?.get === 'function' ? deps.dshRuntime.get(session.id) : null;
+  const options = Array.isArray(configOptions) ? configOptions : (live ? live.configOptions : null);
+  const value = modelIdFromConfigOptions(options) || session.model_id || null;
+  if (!value) return false;
+  const observation = {
+    ctmSessionId: owner.ctmSessionId,
+    agentType: owner.agentType,
+    providerSessionId: owner.providerSessionId,
+    processGeneration: owner.processGeneration,
+    kind: 'completed-turn',
+    value,
+    providerId: 'dsh',
+    selectionKind: 'concrete',
+    effort: effortFromConfigOptions(options),
+    source: DSH_TURN_SOURCE,
+    sourceRevision: null,
+    outcome: 'completed',
+    observedAtMs: Date.now(),
+  };
+  return runtime.applyResult(session, { id: String(session.id || ''), owner, observations: [observation] });
+}
+
+/**
+ * D-12: a pick that names a DIFFERENT gateway route cannot be applied in place — the ACP child holds
+ * ONE route's patch and ONE session token — so the child is STOPPED and a fresh one is started
+ * through the SAME restore path, resuming the SAME ACP session id (`session/resume`, never
+ * `session/new`), while `prepareDshRoute` mints the new route's token and the runtime's one-shot
+ * `onStopped` hook releases the old one.
+ *
+ * The stop is INTENTIONAL by construction: the runtime marks the exit `intentional`, so server.js's
+ * `_onDshChildExit` returns before `markDshRestartable` — a route switch is not a crash, and the
+ * session must NOT come out of it looking asleep.
+ *
+ * A refused/failed relaunch surfaces through `_failDshRestore` (the same reason code every restore
+ * failure publishes) and is returned here as `{ ok:false, code }`, never thrown.
+ *
+ * @returns {Promise<{ok: true}|{ok: false, code: string, message: string}>}
+ */
+async function relaunchDshSession(session, opts = {}) {
+  const deps = _getDeps();
+  if (!session || session.type !== 'dsh') {
+    return { ok: false, code: 'dsh_session_unavailable', message: 'This DeepSeek Harness session is not available.' };
+  }
+  const id = String(session.id || '');
+  if (!id) return { ok: false, code: 'dsh_session_unavailable', message: 'This DeepSeek Harness session is not available.' };
+  if (session._dshRestorePromise) return session._dshRestorePromise;
+  const cwd = session.cwd || (session._restoreTask && session._restoreTask.cwd) || '';
+  const acpSessionId = String(session.agentSessionId || (session._restoreTask && session._restoreTask.chat_session_id) || '');
+  const routeAlias = opts.routeAlias || null;
+  const model = opts.model || null;
+  session._restoreStarting = true;
+  const pending = (async () => {
+    // Intentional stop WITHOUT session/close (§6.7: the next child resumes this ACP session). The old
+    // route's token is released by the runtime's one-shot onStopped hook, and the exit is never
+    // reported as a crash (see _onDshChildExit's `intentional` early return).
+    await deps.dshRuntime.stop(id, { reason: 'dsh_route_switch', closeAcpSession: false });
+    const started = await _runDshRestore(session, { id, cwd, routeAlias, model, acpSessionId });
+    if (!started) {
+      const reason = session._dshExitReason || {};
+      return { ok: false, code: reason.code || 'dsh_start_failed', message: reason.message || 'DeepSeek Harness could not be restarted.' };
+    }
+    // The durable CTM-restart record follows the switch, so a later boot resumes on the NEW route:
+    // the startup-task `args[0]` is exactly what `_runDshRestore` reads back as `routeAlias`.
+    persistDshRouteAlias(session, { routeAlias, model });
+    return { ok: true };
+  })().then(
+    (result) => { session._restoreStarting = false; return result; },
+    (error) => {
+      session._restoreStarting = false;
+      _failDshRestore(session, 'dsh_start_failed', (error && error.message) || 'DeepSeek Harness could not be restarted.');
+      return { ok: false, code: 'dsh_start_failed', message: (error && error.message) || 'DeepSeek Harness could not be restarted.' };
+    },
+  );
+  session._dshRestorePromise = pending;
+  try {
+    return await pending;
+  } finally {
+    if (session._dshRestorePromise === pending) session._dshRestorePromise = null;
+  }
+}
+
+/**
+ * The durable route record for a dsh session — the SAME `startup_tasks` row `createDshSession` writes
+ * (INSERT OR REPLACE on `ctm_session_id`, so this rewrites it in place). `args[0]` is the route alias
+ * and `chat_session_id` the ACP id to resume; NOTHING secret is ever stored (the token lives only in
+ * the non-enumerable in-memory `_dshRoute`). Never fatal: a failed write leaves the previous record.
+ */
+function persistDshRouteAlias(session, { routeAlias, model } = {}) {
+  const deps = _getDeps();
+  const id = session ? String(session.id || '') : '';
+  if (!id || typeof deps.addStartupTaskWithRetry !== 'function') return false;
+  try {
+    void deps.addStartupTaskWithRetry('dsh', [
+      id, session.label || session.title || 'DeepSeek Harness', 'dsh',
+      [routeAlias || 'dsh-own-key'], session.cwd || '', model || session.model_id || null, 'dsh',
+      session.agentSessionId || null,
+    ]);
+    return true;
+  } catch (error) {
+    deps.logError(`[dsh-session] route persist failed for ${id.slice(0, 8)}: ${(error && error.message) || error}`);
+    return false;
+  }
+}
+
+module.exports = {
+  configure,
+  createDshSession,
+  markDshRestartable,
+  modelIdFromConfigOptions,
+  effortFromConfigOptions,
+  findModelOption,
+  findEffortOption,
+  configValueForModelId,
+  configValueForOptionLevel,
+  plainModelIdFromConfigValue,
+  configOptionEntries,
+  bindDshModelOwner,
+  observeDshCompletedTurn,
+  relaunchDshSession,
+  persistDshRouteAlias,
+  restoreDshSession,
+  dshTranscriptPathFor,
+};