dsh-tower 2.0.3 → 2.1.0-beta.1

package/lib/compatibility.js

@@ -0,0 +1,108 @@
+// Release compatibility provenance. COMPATIBILITY.md is shipped in the package;
+// no network lookup is involved.
+import { fs } from '../adapters/store-fs.js'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+export function parseVersion(value) {
+  const text = String(value ?? '').trim()
+  const match = text.match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/)
+  if (!match) return null
+  return {
+    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ? match[4].split('.') : [],
+  }
+}
+
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length === 0) return 0
+  if (a.length === 0) return 1
+  if (b.length === 0) return -1
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    if (a[index] === undefined) return -1
+    if (b[index] === undefined) return 1
+    const aNumber = /^\d+$/.test(a[index])
+    const bNumber = /^\d+$/.test(b[index])
+    if (aNumber && bNumber) {
+      const delta = Number(a[index]) - Number(b[index])
+      if (delta !== 0) return delta
+    } else if (aNumber !== bNumber) {
+      return aNumber ? -1 : 1
+    } else if (a[index] !== b[index]) {
+      return a[index] < b[index] ? -1 : 1
+    }
+  }
+  return 0
+}
+
+export function compareVersions(a, b) {
+  const left = typeof a === 'string' ? parseVersion(a) : a
+  const right = typeof b === 'string' ? parseVersion(b) : b
+  if (!left || !right) return null
+  for (let index = 0; index < 3; index += 1) {
+    if (left.numbers[index] !== right.numbers[index]) return left.numbers[index] < right.numbers[index] ? -1 : 1
+  }
+  return comparePrerelease(left.prerelease, right.prerelease)
+}
+
+export function parseCompatibility(text) {
+  const rows = []
+  for (const line of String(text ?? '').split('\n')) {
+    if (!/^\|/.test(line)) continue
+    const cells = line.split('|').slice(1, -1).map((cell) => cell.trim())
+    if (cells.length < 4) continue
+    if (!parseVersion(cells[0])) continue
+    rows.push({ hostVersion: cells[0], commit: cells[1], verifiedOn: cells[2], ran: cells[3] })
+  }
+  return rows
+}
+
+export function readCompatibility(file = path.join(PACKAGE_ROOT, 'COMPATIBILITY.md')) {
+  try {
+    return parseCompatibility(fs.readFileSync(file, 'utf8'))
+  } catch {
+    return []
+  }
+}
+
+export function assessHostVersion(hostVersion, rows) {
+  const parsed = parseVersion(hostVersion)
+  if (!parsed) return { verdict: 'unknown', row: null, detail: 'cannot parse the running host version' }
+  const exact = rows.find((row) => compareVersions(row.hostVersion, parsed) === 0)
+  if (exact) return { verdict: 'verified', row: exact, detail: `${exact.hostVersion} verified on ${exact.verifiedOn}` }
+  const known = rows
+    .map((row) => ({ row, cmp: compareVersions(parsed, row.hostVersion) }))
+    .filter((entry) => entry.cmp !== null)
+  if (known.length === 0) return { verdict: 'unknown', row: null, detail: 'COMPATIBILITY.md has no version rows' }
+  const newest = known.reduce((best, entry) => (entry.cmp > best.cmp ? entry : best), known[0])
+  if (newest.cmp > 0) {
+    return {
+      verdict: 'untested-newer',
+      row: newest.row,
+      detail: `${hostVersion} is newer than every verified build (latest row ${newest.row.hostVersion})`,
+    }
+  }
+  return {
+    verdict: 'untested-older',
+    row: newest.row,
+    detail: `${hostVersion} is older than the verified builds (latest row ${newest.row.hostVersion})`,
+  }
+}
+
+export function detectHostVersion(ctx, env = process.env) {
+  for (const value of [env.DSH_VERSION, env.DSH_HOST_VERSION, env.npm_config_dsh_version]) {
+    if (typeof value === 'string' && parseVersion(value)) return value
+  }
+  for (const serviceName of ['app', 'runtime', 'host']) {
+    try {
+      const service = ctx?.get?.(serviceName)
+      const value = service && (service.version ?? service.build?.version)
+      if (typeof value === 'string' && parseVersion(value)) return value
+    } catch {
+      // defensive: a missing service is not a doctor failure
+    }
+  }
+  return null
+}

package/lib/config.js

@@ -1,317 +1,50 @@
-// Tower configuration: one declared schema, resolved defaults, and the
-// process-local effective snapshot consumed by the domain modules.
+// Tower configuration: process-local profile snapshot and repository layer.
 //
-// Layers, lowest precedence first:
-//   1. code defaults (the schemastery `.default(...)` values)
-//   2. profile config (the Cordis patch passes it to `apply()`)
-//   3. repository config: <git-common-dir>/dsh-tower/config.json
-//   4. per-tool arguments (e.g. worktreeRoot, timeoutMs)
+// The pure Schemastery schema, default resolution, and raw-config validation
+// live in domain/config/schema.js (#56 P2a). This module keeps only the layers
+// that need process or filesystem state:
 //
-// Defaults are exactly the 1.2.0 behavior; the shipped cordis patch keeps
-// `allowAgentControl: true` via the legacy top-level key.
-import fsp from 'node:fs/promises'
+//   profile -> the raw config `apply()` received, resolved with code defaults
+//              on every read (runtimeConfig)
+//   repo    -> <git-common-dir>/dsh-tower/config.json merged over the profile
+//
+// `Config` and `resolveTowerConfig` are re-exported for compatibility; new
+// code should import them from domain/config/schema.js.
+import { fsp } from '../adapters/store-fs.js'
 import path from 'node:path'
-import Schema from '@deepseek-ai/schemastery'
-import { TowerToolError } from './errors.js'
-
-export const DEFAULT_DENY_TOOLS = [
-  'create_goal',
-  'todo_write',
-  'team_task_create',
-  'team_task_update',
-  'team_task_reopen',
-  'team_task_list',
-  'spawn_teammate',
-  'wait_agent',
-  'workflow',
-  'ralph',
-  'subagent',
-  'subagent_fork',
-]
-
-const LEGACY_KEYS = ['section', 'allowAgentControl']
-const GROUP_KEYS = ['init', 'mode', 'review', 'merge', 'worktrees', 'spawn', 'send', 'tests', 'gates', 'docs', 'leases', 'dev']
+import {
+  Config,
+  DEFAULT_DENY_TOOLS,
+  assertKnownKeys,
+  assertSafeKeys,
+  clone,
+  deepMerge,
+  isPlainObject,
+  normalizeLegacy,
+  resolveTowerConfig,
+} from '../domain/config/schema.js'
+import { TowerToolError } from '../domain/errors.js'
+
+export { Config, DEFAULT_DENY_TOOLS, resolveTowerConfig }
 
-const ModelSchema = () =>
-  Schema.object({
-    provider: Schema.string().description('Provider route override for this role.'),
-    model: Schema.string().description('Model id override for this role.'),
-    reasoningEffort: Schema.string().description('Optional reasoning effort override.'),
-    maxTokens: Schema.natural().description('Optional output token cap.'),
-  })
-
-export const Config = Schema.object({
-  section: Schema.string().description(
-    'Legacy alias for mode.promptSection: replaces the whole Tower-mode system prompt text.',
-  ),
-  allowAgentControl: Schema.boolean().description(
-    'Legacy alias for mode.allowAgentControl: register tower_control so the model may toggle the mode.',
-  ),
-  init: Schema.object({
-    autoGitInit: Schema.boolean()
-      .default(false)
-      .description('tower_init may run git init and create an empty initial commit when the directory is not a repository.'),
-    snapshotDirty: Schema.boolean()
-      .default(false)
-      .description('tower_init may snapshot uncommitted tracked changes into a dangling commit used as the mission baseline.'),
-  })
-    .default({})
-    .description('Repository initialization policy.'),
-  mode: Schema.object({
-    promptSection: Schema.string().description('Replacement Tower-mode system prompt text. Empty keeps the built-in reminder.'),
-    sectionAppend: Schema.string().description('Extra text appended to the Tower-mode system prompt section (team conventions).'),
-    allowAgentControl: Schema.boolean().description('Register tower_control so the model may enter/leave the mode with a reason.'),
-    autoPauseGoal: Schema.boolean().default(true).description('Pause an active goal when entering Tower mode.'),
-    requireResumeAuthorization: Schema.boolean()
-      .default(false)
-      .description('Require an authorization reference when resuming a mission paused with pauseCause=user.'),
-    workspaceLock: Schema.boolean()
-      .default(false)
-      .description('Allow only one Tower session per repository (advisory <git-common-dir>/dsh-tower/tower.lock).'),
-    workspaceLockScope: Schema.union(['all', 'mutations'])
-      .default('all')
-      .description('all = every repo-scoped tool acquires the workspace lock; mutations = only tools that write state/worktrees do.'),
-    planModePolicy: Schema.union(['clear', 'refuse'])
-      .default('clear')
-      .description('On Tower entry: clear an active plan mode, or refuse to enter until the plan is exited.'),
-    workspaceStaleMs: Schema.natural()
-      .min(1000)
-      .default(300000)
-      .description('A workspace lock older than this is stale and can be taken over.'),
-    heartbeatMs: Schema.natural().min(1000).default(10000).description('Workspace-lock heartbeat interval while Tower mode is on.'),
-    denyTools: Schema.array(Schema.string())
-      .default(DEFAULT_DENY_TOOLS)
-      .description('Tools refused while Tower mode is active.'),
-    storePath: Schema.string().description('Directory for modes.json; defaults to $DSH_HOME/tower-mode.'),
-    maxEntries: Schema.natural().min(1).max(2000).default(200).description('Maximum persisted mode entries.'),
-  })
-    .default({})
-    .description('Tower-mode behavior and persistence.'),
-  review: Schema.object({
-    requireReview: Schema.boolean()
-      .default(false)
-      .description('Require an independent clean review before merge. Default false: review is optional; set true to enforce the review gate globally.'),
-    maxRoundsPerReviewer: Schema.natural().min(1).default(5).description('Review-round cap per reviewer per mission branch.'),
-  })
-    .default({})
-    .description('Review policy.'),
-  merge: Schema.object({
-    timeoutMs: Schema.natural().min(1000).default(900000).description('Default tower_merge timeout, including pre-merge hooks.'),
-    maxBufferBytes: Schema.natural().min(65536).default(67108864).description('Captured merge output buffer.'),
-  })
-    .default({})
-    .description('Merge execution policy.'),
-  worktrees: Schema.object({
-    root: Schema.string().description('Default parent directory for mission worktrees; empty derives <main-checkout-parent>/.dsh-tower-worktrees/<hash>.'),
-  })
-    .default({})
-    .description('Worktree placement.'),
-  spawn: Schema.object({
-    workerPreset: Schema.string().default('tower-worker').description('Agent preset for worker missions.'),
-    reviewerPreset: Schema.string().default('tower-reviewer').description('Agent preset for reviewers.'),
-    maxDepth: Schema.natural().min(1).default(1).description('Subagent depth requested when spawning tower agents.'),
-    provider: Schema.string().description('Subagent provider id; empty picks spawn, then the first registered provider.'),
-    workerModel: ModelSchema().description('Model route for workers; omitted inherits the parent session.'),
-    reviewerModel: ModelSchema().description('Model route for reviewers; omitted inherits the parent session (recommended).'),
-    maxLiveWorkers: Schema.natural()
-      .min(1)
-      .max(64)
-      .default(4)
-      .description('Maximum live worker entries allowed per repository at once.'),
-    staleMs: Schema.natural()
-      .min(0)
-      .default(15000)
-      .description('Roster entries with no catalog activity after this age are marked stale and block merge (0 disables).'),
-    maxWaitMs: Schema.natural()
-      .min(1000)
-      .max(600000)
-      .default(90000)
-      .description('Upper bound for tower_spawn waitMs (default 90s, Kimi-compatible).'),
-    requireLease: Schema.string().description('Optional lease name tower_spawn must hold before starting a worker.'),
-  })
-    .default({})
-    .description('Worker and reviewer presets plus model routing.'),
-  send: Schema.object({
-    maxPerMinute: Schema.natural()
-      .min(0)
-      .default(120)
-      .description('Per-repository tower_send rate limit per minute (0 disables).'),
-    interruptDefault: Schema.boolean()
-      .default(false)
-      .description('Default value of tower_send.interrupt when the caller omits it.'),
-  })
-    .default({})
-    .description('Message delivery policy.'),
-  tests: Schema.object({
-    enabled: Schema.boolean().default(true).description('Run declared test discovery when a mission configures it.'),
-    admission: Schema.union(['spawn', 'complete', 'off'])
-      .default('complete')
-      .description('Run discovery before spawning a worker, when completing, or only on explicit tower_test.'),
-    timeoutMs: Schema.natural().min(1000).max(1800000).default(60000).description('Per discovery command timeout.'),
-    maxBytes: Schema.natural().min(1024).max(16 * 1024 * 1024).default(16 * 1024 * 1024).description('Maximum captured stdout bytes per command.'),
-    autoChecks: Schema.boolean().default(true).description('Attach a tests check to the completion report when discovery runs.'),
-    allowPackageDiscovery: Schema.boolean()
-      .default(true)
-      .description('Allow package.json tower.testDiscovery commands from the mission worktree (executes repository code; see security docs).'),
-  })
-    .default({})
-    .description('Declared test discovery and admission.'),
-  gates: Schema.object({
-    requireChecks: Schema.boolean()
-      .default(false)
-      .description('Require at least one completion check (tower_complete.checks) before a mission can merge.'),
-    requireTests: Schema.boolean()
-      .default(false)
-      .description('Require a passing test-discovery receipt for the reviewed worktree tip before merge.'),
-    allowReviewExemption: Schema.boolean()
-      .default(false)
-      .description('Allow reviewPolicy:none missions with a non-empty reviewExemptionReason to skip review blockers.'),
-  })
-    .default({})
-    .description('Merge-gate strictness.'),
-  docs: Schema.object({
-    board: Schema.boolean()
-      .default(true)
-      .description('Write a human-readable MISSIONS.md after mission changes.'),
-    boardLocation: Schema.union(['common', 'repo'])
-      .default('common')
-      .description('common = <git-common-dir>/dsh-tower/MISSIONS.md; repo = <repoRoot>/MISSIONS.md.'),
-  })
-    .default({})
-    .description('Human-readable artifacts.'),
-  leases: Schema.object({
-    ttlMs: Schema.natural().min(1000).max(86400000).default(900000).description('Default advisory lease lifetime; expiry never auto-releases.'),
-  })
-    .default({})
-    .description('Advisory resource leases.'),
-  dev: Schema.object({
-    hotReload: Schema.boolean().default(true).description('Register tower_reload and /tower reload when the DSH HMR service is available.'),
-    reloadDelayMs: Schema.natural().min(1).max(5000).default(50).description('Delay before a scheduled reload, so the tool result is delivered first.'),
-    reloadRequiredIds: Schema.array(Schema.string())
-      .default(['tower', 'tower-skills', 'preset-tower-worker', 'preset-tower-reviewer'])
-      .description('Loader entry ids passed to reconcileProfile as required.'),
-  })
-    .default({})
-    .description('Development and hot-reload behavior.'),
-}).description('DSH Tower configuration')
+const REPO_CONFIG_MAX_BYTES = 1024 * 1024
 
-let effective = null
 // The last raw profile config `apply()` received; repository config is merged
 // over it so a repo can tune spawn/merge/review without editing the profile.
 let profileRaw = {}
 
-function clone(value) {
-  return value === undefined ? undefined : JSON.parse(JSON.stringify(value))
-}
-
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
-
-function deepMerge(base, override) {
-  if (override === undefined) return clone(base) ?? {}
-  if (!isPlainObject(base) || !isPlainObject(override)) return clone(override)
-  const out = clone(base)
-  for (const [key, value] of Object.entries(override)) {
-    out[key] = value === undefined ? out[key] : deepMerge(base[key], value)
-  }
-  return out
-}
-
-/** Move the legacy top-level aliases into their canonical group keys. */
-function normalizeLegacy(raw = {}) {
-  const out = clone(raw) ?? {}
-  if (out.section !== undefined) {
-    const mode = { ...(out.mode ?? {}) }
-    if (mode.promptSection === undefined) mode.promptSection = out.section
-    out.mode = mode
-    delete out.section
-  }
-  if (out.allowAgentControl !== undefined) {
-    const mode = { ...(out.mode ?? {}) }
-    if (mode.allowAgentControl === undefined) mode.allowAgentControl = out.allowAgentControl
-    out.mode = mode
-    delete out.allowAgentControl
-  }
-  return out
-}
-
-function assertKnownKeys(raw, label) {
-  const unknown = Object.keys(raw).filter((key) => !LEGACY_KEYS.includes(key) && !GROUP_KEYS.includes(key))
-  if (unknown.length > 0) {
-    throw new TowerToolError(
-      'config-unknown-key',
-      `${label} has unknown key(s) ${unknown.join(', ')} — config is { section?, allowAgentControl?, init?, mode?, review?, merge?, worktrees?, spawn?, send?, tests?, gates?, docs?, leases?, dev? }`,
-    )
-  }
-}
-
-const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
-const REPO_CONFIG_MAX_BYTES = 1024 * 1024
-
-/** Reject prototype-pollution style keys anywhere in a repository config. */
-function assertSafeKeys(value, label) {
-  if (Array.isArray(value)) {
-    for (const item of value) assertSafeKeys(item, label)
-    return
-  }
-  if (!isPlainObject(value)) return
-  for (const [key, child] of Object.entries(value)) {
-    if (FORBIDDEN_KEYS.has(key)) {
-      throw new TowerToolError('config-invalid', `${label} contains the forbidden key "${key}"`)
-    }
-    assertSafeKeys(child, label)
-  }
-}
-
-export function resolveTowerConfig(rawConfig) {
-  const raw = rawConfig ?? {}
-  if (raw !== null && typeof raw !== 'object') throw new Error('Tower config must be an object')
-  assertKnownKeys(raw, 'Tower config')
-  let parsed
-  try {
-    parsed = Config(raw)
-  } catch (error) {
-    throw new Error(`Tower config is invalid: ${String(error?.message ?? error)}`)
-  }
-  const mode = clone(parsed.mode ?? {})
-  // Canonical keys win; the legacy top-level aliases only fill gaps.
-  const rawMode = raw.mode ?? {}
-  if (rawMode.promptSection === undefined && raw.section !== undefined) mode.promptSection = raw.section
-  if (rawMode.allowAgentControl === undefined && raw.allowAgentControl !== undefined) {
-    mode.allowAgentControl = raw.allowAgentControl
-  }
-  // Apply the canonical default only after alias resolution: a validated
-  // Cordis config may omit this key, and an explicit legacy top-level
-  // `allowAgentControl:true` must not be shadowed by a schema default.
-  if (mode.allowAgentControl === undefined) mode.allowAgentControl = false
-  if (!Array.isArray(mode.denyTools) || mode.denyTools.length === 0) mode.denyTools = [...DEFAULT_DENY_TOOLS]
-  return {
-    section: mode.promptSection ?? '',
-    init: clone(parsed.init ?? {}),
-    mode,
-    review: clone(parsed.review ?? {}),
-    merge: clone(parsed.merge ?? {}),
-    worktrees: clone(parsed.worktrees ?? {}),
-    spawn: clone(parsed.spawn ?? {}),
-    send: clone(parsed.send ?? {}),
-    tests: clone(parsed.tests ?? {}),
-    gates: clone(parsed.gates ?? {}),
-    docs: clone(parsed.docs ?? {}),
-    leases: clone(parsed.leases ?? {}),
-    dev: clone(parsed.dev ?? {}),
-  }
-}
-
 export function configureRuntime(config) {
   profileRaw = clone(config ?? {}) ?? {}
-  effective = resolveTowerConfig(config)
-  return effective
+  return resolveTowerConfig(config)
 }
 
 export function runtimeConfig() {
-  if (!effective) effective = resolveTowerConfig({})
-  return effective
+  return resolveTowerConfig(profileRaw)
+}
+
+/** Raw profile config before defaults are materialized (for doctor warnings). */
+export function profileConfig() {
+  return clone(profileRaw) ?? {}
 }
 
 export function repoConfigPath(commonDir) {
@@ -373,7 +106,27 @@ export async function readRepoConfig(commonDir) {
 export async function resolveRepoConfig(repo) {
   const base = runtimeConfig()
   const layer = await readRepoConfig(repo.commonDir)
-  const merged = deepMerge(base, layer.config)
+  // The mode guard is a session/profile concern. A repository checkout may
+  // only tighten it, never weaken denyTools, workspaceLock, allowAgentControl,
+  // plan policy, or resume authorization.
+  const repoLayer = { ...layer.config }
+  delete repoLayer.mode
+  delete repoLayer.section
+  delete repoLayer.allowAgentControl
+  const merged = deepMerge(base, repoLayer)
+  const repoMode = layer.config.mode
+  if (repoMode && typeof repoMode === 'object' && !Array.isArray(repoMode)) {
+    merged.mode = { ...(merged.mode ?? {}) }
+    if (repoMode.requireResumeAuthorization === true) merged.mode.requireResumeAuthorization = true
+    if (repoMode.workspaceLock === true) merged.mode.workspaceLock = true
+    if (repoMode.autoPauseGoal === true) merged.mode.autoPauseGoal = true
+    if (repoMode.workspaceLockScope === 'all') merged.mode.workspaceLockScope = 'all'
+    if (repoMode.planModePolicy === 'refuse') merged.mode.planModePolicy = 'refuse'
+    if (repoMode.allowAgentControl === false) merged.mode.allowAgentControl = false
+    if (Array.isArray(repoMode.denyTools)) {
+      merged.mode.denyTools = [...new Set([...(base.mode?.denyTools ?? DEFAULT_DENY_TOOLS), ...repoMode.denyTools])]
+    }
+  }
   if (!Array.isArray(merged.mode?.denyTools) || merged.mode.denyTools.length === 0) {
     merged.mode = { ...(merged.mode ?? {}), denyTools: [...DEFAULT_DENY_TOOLS] }
   }
@@ -385,4 +138,3 @@ export async function resolveRepoConfig(repo) {
     profileConfigured: Object.keys(profileRaw).length > 0,
   }
 }
-

package/lib/doctor.js

@@ -1,9 +1,12 @@
 // Read-only environment contract and health checks for a Tower repository.
-import { execFile } from 'node:child_process'
+import { execFile } from '../adapters/vcs-git.js'
 import { promisify } from 'node:util'
 import path from 'node:path'
-import fsp from 'node:fs/promises'
+import { fsp } from '../adapters/store-fs.js'
 import { git } from './git.js'
+import { readStateLock } from './store.js'
+import { assessHostVersion, detectHostVersion, readCompatibility } from './compatibility.js'
+import { profileConfig } from './config.js'
 import { inspectWorkspaceLock } from './workspaceLock.js'
 
 const execFileAsync = promisify(execFile)
@@ -31,21 +34,83 @@ function check(id, status, detail, action) {
 }
 
 /** Run every read-only diagnostic; never writes state or takes the state lock. */
-export async function runDoctor({ tower, ctx, agent }) {
+export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityFile, loaderRows }) {
   const checks = []
   const version = await gitVersion()
   checks.push(version ? check('git', 'pass', version) : check('git', 'fail', 'git is not available', 'install Git and retry'))
 
+  const detectedHost = hostVersion ?? detectHostVersion(ctx)
+  const compatibilityRows = readCompatibility(compatibilityFile)
+  const hostAssessment = assessHostVersion(detectedHost, compatibilityRows)
+  checks.push(
+    check(
+      'host-version',
+      hostAssessment.verdict === 'verified' ? 'pass' : 'warn',
+      detectedHost
+        ? `${detectedHost}: ${hostAssessment.detail}`
+        : `unknown host version; ${hostAssessment.detail}. Include host version + COMPATIBILITY.md row in bug reports.`,
+      'see COMPATIBILITY.md for verified host builds',
+    ),
+  )
+
+  const rows = Array.isArray(loaderRows)
+    ? loaderRows
+    : (() => {
+        try {
+          const loader = ctx?.get?.('loader') ?? ctx?.loader
+          const source = loader?.entries ?? loader?.rows ?? loader?.store?.entries
+          if (Array.isArray(source)) return source
+          if (source && typeof source === 'object') return Object.values(source)
+        } catch {
+          // loader inventory is optional
+        }
+        return null
+      })()
+  if (rows === null) {
+    checks.push(check('loader-conflicts', 'warn', 'loader inventory unavailable; cannot detect co-installed Tower packages'))
+  } else {
+    const towerRows = rows.filter((row) => row && row.name === 'dsh-tower')
+    const foreign = towerRows.filter((row) => row.id !== 'tower')
+    checks.push(
+      towerRows.length > 1 || foreign.length > 0
+        ? check(
+            'loader-conflicts',
+            'fail',
+            `another loader row resolves to "dsh-tower" (${towerRows.map((row) => row.id ?? '?').join(', ')}); uninstall the conflicting dsh-plugins-tower row`,
+            'see README "Known conflicts"',
+          )
+        : check('loader-conflicts', 'pass', 'no conflicting dsh-tower loader rows'),
+    )
+  }
+
   checks.push(check('repository', 'pass', `${tower.root} (common ${tower.commonDir})`))
   let state = null
   try {
     state = await tower.load()
     checks.push(check('state', 'pass', `${tower.paths.state} revision ${state.revision}`))
+    checks.push(
+      state.towerAgentId
+        ? check('tower-owner', 'pass', `bound to ${String(state.towerAgentId)}`)
+        : check('tower-owner', 'warn', 'state has no towerAgentId; write tools will fail closed', 'run tower_init with the restored session to re-claim ownership'),
+    )
   } catch (error) {
     checks.push(check('state', 'fail', String(error?.message ?? error), 'run tower_init or restore the state file'))
   }
 
   const config = tower.config ?? {}
+  const profile = profileConfig()
+  const staleDefaults = []
+  if (profile.review && profile.review.requireReview === undefined) {
+    staleDefaults.push('review.requireReview now defaults to false (2.0.3)')
+  }
+  if (profile.mode && profile.mode.allowAgentControl === undefined) {
+    staleDefaults.push('mode.allowAgentControl now defaults to true (2.0.4)')
+  }
+  checks.push(
+    staleDefaults.length > 0
+      ? check('default-reversals', 'warn', staleDefaults.join('; '), 'pin the key explicitly in the profile if the old posture is required')
+      : check('default-reversals', 'pass', 'profile does not rely on a reversed default'),
+  )
   checks.push(
     check(
       'config',
@@ -78,11 +143,13 @@ export async function runDoctor({ tower, ctx, agent }) {
   checks.push(hmr ? check('hmr', 'pass', 'service mounted') : check('hmr', 'warn', 'HMR is not mounted; /tower reload is unavailable'))
 
   if (state) {
-    const stateLock = path.join(tower.paths.dir, 'state.lock')
+    const lock = await readStateLock(tower.paths)
     checks.push(
-      (await exists(stateLock))
-        ? check('state-lock', 'warn', `${stateLock} exists (a writer may be active or a crash left it behind)`)
-        : check('state-lock', 'pass', 'no state lock file'),
+      !lock.record
+        ? check('state-lock', 'pass', 'no state lock file')
+        : lock.alive === false
+          ? check('state-lock', 'warn', `stale state lock (pid ${lock.record.pid ?? 'unknown'} is gone); the next mutation reclaims it atomically`)
+          : check('state-lock', 'warn', `state lock held by pid ${lock.record.pid ?? 'unknown'}; retry after it finishes`),
     )
     const lockDir = path.join(tower.commonDir, 'dsh-tower', 'tower.lock')
     try {
@@ -95,7 +162,11 @@ export async function runDoctor({ tower, ctx, agent }) {
     }
 
     const live = (state.roster ?? []).filter((entry) => !['retired', 'failed', 'interrupted', 'missing', 'stale', 'inactive'].includes(entry.state))
-    checks.push(live.length > 0 ? check('roster', 'warn', `${live.length} live roster entr${live.length === 1 ? 'y' : 'ies'}`) : check('roster', 'pass', 'no live workers'))
+    checks.push(
+      live.length > 0
+        ? check('roster', 'pass', `${live.length} live roster entr${live.length === 1 ? 'y' : 'ies'}`)
+        : check('roster', 'pass', 'no live workers'),
+    )
 
     let missingWorktrees = 0
     let dirtyWorktrees = 0
@@ -121,7 +192,7 @@ export async function runDoctor({ tower, ctx, agent }) {
     const removedNote = removedWorktrees > 0 ? ` (${removedWorktrees} removed by teardown)` : ''
     checks.push(
       missingWorktrees > 0
-        ? check('worktrees', 'fail', `${missingWorktrees} mission worktree(s) are missing or invalid${removedNote}`, 'run tower_preflight or tower_recover')
+        ? check('worktrees', 'fail', `${missingWorktrees} mission worktree(s) are missing or invalid${removedNote}`, 'inspect tower_status, restore the worktree/branch, then re-run tower_doctor')
         : dirtyWorktrees > 0
           ? check('worktrees', 'warn', `${dirtyWorktrees} worktree(s) have uncommitted changes${removedNote}`)
           : check('worktrees', 'pass', `all registered worktrees are valid${removedNote}`),
@@ -155,6 +226,28 @@ export async function runDoctor({ tower, ctx, agent }) {
     )
   }
 
+  try {
+    const text = await fsp.readFile(path.join(tower.paths.dir, 'lock-holds.jsonl'), 'utf8')
+    const samples = text.split('\n').filter(Boolean).slice(-200).map((line) => JSON.parse(line).ms).filter((ms) => Number.isFinite(ms)).sort((a, b) => a - b)
+    if (samples.length === 0) {
+      checks.push(check('lock-holds', 'pass', 'no lock-hold samples yet'))
+    } else {
+      const p = (q) => samples[Math.min(samples.length - 1, Math.floor(q * samples.length))]
+      const p50 = p(0.5)
+      const p95 = p(0.95)
+      checks.push(
+        check(
+          'lock-holds',
+          p95 > 1000 ? 'warn' : 'pass',
+          `${samples.length} sample(s): p50 ${p50}ms, p95 ${p95}ms`,
+          p95 > 1000 ? 'a mutation is holding the state lock across slow work; inspect the activity/lock-holds log' : undefined,
+        ),
+      )
+    }
+  } catch {
+    checks.push(check('lock-holds', 'pass', 'no lock-hold samples yet'))
+  }
+
   const failed = checks.filter((item) => item.status === 'fail').length
   return {
     ok: failed === 0,
@@ -165,6 +258,12 @@ export async function runDoctor({ tower, ctx, agent }) {
       repoRoot: tower.root,
       commonDir: tower.commonDir,
       stateDir: tower.paths.dir,
+      gitTimeoutMs: Number(tower.config.git?.timeoutMs) || 15000,
+      mergeTimeoutMs: Number(tower.config.merge?.timeoutMs) || 900000,
+      testsAdmission: tower.config.tests?.admission ?? 'off',
+      hostVersion: detectedHost,
+      hostCompatibility: hostAssessment.verdict,
+      hostCompatibilityDetail: hostAssessment.detail,
     },
     mode: agent ? 'ready' : 'unknown',
   }