dsh-tower 2.1.0 → 2.4.0

package/{lib → host}/doctor.js

@@ -2,19 +2,34 @@
 import { execFile } from '../adapters/vcs-git.js'
 import { promisify } from 'node:util'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { fsp } from '../adapters/store-fs.js'
-import { git } from './git.js'
-import { readStateLock } from './store.js'
-import { inspectArchive } from './archive.js'
+import { git } from '../adapters/git.js'
+import { readStateLock, readGitLock, gitLockView } from '../adapters/store.js'
+import { lockTiming } from '../adapters/persistence.js'
+import { inspectArchive } from '../adapters/archive.js'
 import { inspectStateVersion } from '../domain/state.js'
 import { SCHEMA_VERSION } from '../domain/mission.js'
 import { DEFAULT_MAX_REPORT_BYTES, completionReportBytes } from '../domain/missions/completion.js'
 import { comparisonMode } from '../domain/scope.js'
+import { configSurface } from '../domain/config/schema.js'
+import { parseBaseline, surfaceLine, SURFACE_BASELINE_FILE } from '../domain/surface.js'
 import { assessHostVersion, detectHostVersion, readCompatibility } from './compatibility.js'
 import { profileConfig } from './config.js'
-import { inspectWorkspaceLock } from './workspaceLock.js'
+import { inspectWorkspaceLock } from '../adapters/workspaceLock.js'
+import { componentReport, componentSummary } from './capability-registry.js'
 
 const execFileAsync = promisify(execFile)
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+/** Read the committed concept-budget baseline read-only; null when absent. */
+async function readSurfaceBaseline() {
+  try {
+    return parseBaseline(await fsp.readFile(path.join(PACKAGE_ROOT, SURFACE_BASELINE_FILE), 'utf8'))
+  } catch {
+    return null
+  }
+}
 
 async function exists(target) {
   try {
@@ -38,6 +53,12 @@ function check(id, status, detail, action) {
   return { id, status, detail, ...(action ? { action } : {}) }
 }
 
+/** Render a lock age the same way the state-lock checker does. */
+function durationText(ms) {
+  if (!Number.isFinite(ms)) return 'an unknown duration'
+  return `${Math.max(0, Math.round(ms / 1000))} s`
+}
+
 /** Read the on-disk state version without loading, migrating, or locking. */
 async function inspectStateSchema(paths) {
   try {
@@ -116,9 +137,10 @@ function stateSchemaReport(info) {
 }
 
 /** Run every read-only diagnostic; never writes state or takes the state lock. */
-export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityFile, loaderRows }) {
+export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityFile, loaderRows, surface }) {
   const checks = []
   let reportsReport = null
+  let stateLockReport = null
   const version = await gitVersion()
   checks.push(version ? check('git', 'pass', version) : check('git', 'fail', 'git is not available', 'install Git and retry'))
 
@@ -167,6 +189,19 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
   }
 
   checks.push(check('repository', 'pass', `${tower.root} (common ${tower.commonDir})`))
+  // The repo-scoped git mutex can legally be held for a whole merge (15 min by
+  // default). Report the holder so a stalled tower has a visible cause (#93).
+  const gitLock = gitLockView(await readGitLock(tower.paths))
+  checks.push(
+    gitLock.held
+      ? check(
+          'git-lock',
+          'warn',
+          `held by pid ${gitLock.pid ?? 'unknown'}${gitLock.phase ? ` (${gitLock.phase})` : ''} for ${durationText(gitLock.heldMs)}; the repo-scoped git mutex is busy`,
+          'wait for the git mutation to finish; tower_status reports the same holder',
+        )
+      : check('git-lock', 'pass', 'free'),
+  )
   const schemaInfo = await inspectStateSchema(tower.paths)
   let state = null
   try {
@@ -226,17 +261,59 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
       'optional: add <git-common-dir>/dsh-tower/config.json',
     ),
   )
+  // #84: report the concept-budget surface instead of implying it. The counts
+  // are the live schema/tool surface; the date is the committed baseline, so a
+  // reader sees both the number and the decision it was frozen at.
+  const configCounts = configSurface()
+  const baseline = await readSurfaceBaseline()
+  const toolCount = Number.isInteger(surface?.tools) ? surface.tools : null
+  const surfaceCounts = {
+    configKeys: configCounts.count,
+    sections: configCounts.sections.length,
+    tools: toolCount,
+  }
+  const surfaceReport = {
+    ...surfaceCounts,
+    baselineDate: baseline?.date ?? null,
+    line: surfaceLine(surfaceCounts),
+  }
+  checks.push(
+    toolCount === null
+      ? check('surface', 'warn', `${surfaceReport.line} (tool count unavailable; pass the registered surface)`)
+      : check(
+          'surface',
+          'pass',
+          `${surfaceReport.line}${baseline?.date ? ` (baseline ${baseline.date})` : ''}`,
+          baseline?.date ? undefined : `commit ${SURFACE_BASELINE_FILE} so growth is compared against a decision`,
+        ),
+  )
   const presets = ctx.get?.('agentPresets')
+  const reviewerRequired = config.review?.requireReview === true
   if (presets && typeof presets.list === 'function') {
     try {
       const available = (await presets.list()).map((entry) => String(entry.id))
-      const missing = [config.spawn?.workerPreset ?? 'tower-worker', config.spawn?.reviewerPreset ?? 'tower-reviewer']
-        .filter((id) => !available.includes(id))
-      checks.push(
-        missing.length === 0
-          ? check('presets', 'pass', `worker=${config.spawn?.workerPreset ?? 'tower-worker'} reviewer=${config.spawn?.reviewerPreset ?? 'tower-reviewer'}`)
-          : check('presets', 'fail', `missing preset(s): ${missing.join(', ')}`, 'enable the Tower preset bundle and retry'),
-      )
+      const worker = config.spawn?.workerPreset ?? 'tower-worker'
+      const reviewer = config.spawn?.reviewerPreset ?? 'tower-reviewer'
+      const required = reviewerRequired ? [worker, reviewer] : [worker]
+      const missing = required.filter((id) => !available.includes(id))
+      // #121: `preset-tower-reviewer` is a conditional component. Its off state
+      // is supported while review.requireReview is false; with the gate on it is
+      // a fail, because no independent review can be dispatched.
+      if (missing.length === 0) {
+        const reviewerNote = available.includes(reviewer)
+          ? `reviewer=${reviewer}`
+          : `reviewer=${reviewer} (disabled by component preset-tower-reviewer)`
+        checks.push(check('presets', 'pass', `worker=${worker} ${reviewerNote}`))
+      } else {
+        checks.push(
+          check(
+            'presets',
+            'fail',
+            `missing preset(s): ${missing.join(', ')}${reviewerRequired && missing.includes(reviewer) ? ' (review.requireReview is true, so preset-tower-reviewer may not be off)' : ''}`,
+            'enable the Tower preset component and retry',
+          ),
+        )
+      }
     } catch (error) {
       checks.push(check('presets', 'warn', `preset registry unavailable: ${String(error?.message ?? error)}`))
     }
@@ -244,6 +321,16 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
     checks.push(check('presets', 'warn', 'agentPresets service is unavailable'))
   }
 
+  // #121: the optional component rows are a diagnostic fact. A disabled row is
+  // reported with the exact "disabled by component <id>" reason rather than
+  // disappearing silently from the tool surface.
+  const components = await componentReport(ctx)
+  checks.push(
+    components.disabled.length > 0
+      ? check('components', 'warn', componentSummary(components), 'enable the reported row in the plugin page and restart DSH')
+      : check('components', 'pass', componentSummary(components)),
+  )
+
   const subagents = ctx.get?.('subagents')
   checks.push(subagents ? check('subagents', 'pass', 'service mounted') : check('subagents', 'fail', 'subagents service is unavailable', 'enable the subagent bundle'))
   const hmr = ctx.get?.('hmr')
@@ -251,12 +338,45 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
 
   if (state) {
     const lock = await readStateLock(tower.paths)
+    const timing = lockTiming(lock.record)
+    stateLockReport = {
+      held: Boolean(lock.record),
+      pid: lock.record?.pid ?? null,
+      startedAt: lock.record?.startedAt ?? null,
+      at: lock.record?.at ?? null,
+      alive: lock.alive,
+      ageMs: timing.ageMs,
+      heartbeatAgeMs: timing.heartbeatAgeMs,
+      staleAfterMs: timing.staleAfterMs,
+      stale: timing.stale,
+    }
+    // The PID alone cannot distinguish a live writer from a recycled PID
+    // (#92); report the heartbeat age so a stuck tower is diagnosable without
+    // reading the file.
+    const heartbeatText =
+      timing.heartbeatAgeMs === null
+        ? 'no heartbeat timestamp'
+        : `last heartbeat ${timing.heartbeatAgeMs}ms ago (stale after ${timing.staleAfterMs}ms)`
     checks.push(
       !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`),
+          ? check(
+              'state-lock',
+              'warn',
+              `stale state lock (pid ${lock.record.pid ?? 'unknown'} is gone; ${heartbeatText}); the next mutation reclaims it atomically`,
+            )
+          : timing.stale
+            ? check(
+                'state-lock',
+                'warn',
+                `state lock pid ${lock.record.pid ?? 'unknown'} is alive but silent (${heartbeatText}); the next mutation reclaims it after byte verification, or tower_recover clear-stale-lock force:true moves it to a backup`,
+              )
+            : check(
+                'state-lock',
+                'warn',
+                `state lock held by pid ${lock.record.pid ?? 'unknown'}; ${heartbeatText}; retry after it finishes`,
+              ),
     )
     const lockDir = path.join(tower.commonDir, 'dsh-tower', 'tower.lock')
     try {
@@ -306,11 +426,15 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
     )
 
     const testConfigured = state.missions?.some((mission) => mission.testRuns !== undefined)
+    const testsDisabled =
+      config.tests?.enabled === false || components.disabled.some((entry) => entry.id === 'tower-tests')
     checks.push(
       check(
         'tests',
-        config.tests?.enabled === false ? 'warn' : 'pass',
-        config.tests?.enabled === false ? 'test discovery disabled' : `admission=${config.tests?.admission ?? 'complete'} timeoutMs=${config.tests?.timeoutMs ?? 60000}${testConfigured ? '; receipts present' : ''}`,
+        testsDisabled ? 'warn' : 'pass',
+        testsDisabled
+          ? `test discovery disabled${config.tests?.enabled === false ? ' (tests.enabled:false)' : ' (disabled by component tower-tests)'}`
+          : `admission=${config.tests?.admission ?? 'complete'} timeoutMs=${config.tests?.timeoutMs ?? 60000}${testConfigured ? '; receipts present' : ''}`,
       ),
     )
     checks.push(check('legacy', 'pass', `${state.legacySnapshots?.length ?? 0} legacy snapshot(s)`))
@@ -342,7 +466,7 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
   }
 
   try {
-    const { inspectLeases } = await import('./leases.js')
+    const { inspectLeases } = await import('../adapters/leases.js')
     const leases = await inspectLeases(tower.commonDir)
     checks.push(check('leases', leases.leases?.length ? 'warn' : 'pass', `${leases.leases?.length ?? 0} active lease(s)`))
   } catch (error) {
@@ -359,7 +483,18 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
 
   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)
+    // These percentiles are about the state lock. Git-mutex holds are logged
+    // too (kind: 'git' / the pre-#93 phase: 'git' form) and can legitimately
+    // span a merge, so they must not be counted as slow state mutations.
+    const samples = text
+      .split('\n')
+      .filter(Boolean)
+      .slice(-200)
+      .map((line) => JSON.parse(line))
+      .filter((hold) => hold.kind !== 'git' && hold.phase !== 'git')
+      .map((hold) => hold.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 {
@@ -410,9 +545,13 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
   return {
     ok: failed === 0,
     checks,
+    stateLock: stateLockReport,
+    gitLock,
     stateSchema: schemaReport.stateSchema,
 // reports (from #89) and archive (from #73) are both kept
     reports: reportsReport,
+    surface: surfaceReport,
+    components,
     archive: {
       missions: state ? state.missions.length : null,
       archivedMissions: archiveInventory.missions,

package/{lib → host}/hmr.js

@@ -20,13 +20,11 @@
 //   one, so a tool-triggered reload is safe.
 import { TowerToolError } from '../domain/errors.js'
 
-/** Entry ids Tower expects to be active after a reconciliation. */
+/** Entry ids Tower expects to be active after a reconciliation (#121 rows). */
 export const DEFAULT_REQUIRED_IDS = Object.freeze([
-  'tower-bundle',
   'tower',
-  'tower-skills',
+  'tower-host',
   'preset-tower-worker',
-  'preset-tower-reviewer',
 ])
 
 /** Debounce window for the dev hot-reload hook (milliseconds). */

package/{lib → host}/modeStore.js

@@ -6,7 +6,7 @@
 import { fs } from '../adapters/store-fs.js'
 import os from 'node:os'
 import path from 'node:path'
-import { acquireLockSync, readJsonSync, writeJsonAtomicSync } from './persistence.js'
+import { acquireLockSync, readJsonSync, writeJsonAtomicSync } from '../adapters/persistence.js'
 
 const DEFAULT_MAX_ENTRIES = 200
 

package/host/presets.js

@@ -0,0 +1,77 @@
+// Cross-field preset and component validation (#64, #121): fail before work
+// starts, not at spawn.
+//
+// Two invariants travel with the optional rows:
+//
+//   1. `preset-tower-worker` is a mandatory dependency: planning, mode entry and
+//      spawn must refuse when the worker preset is absent.
+//   2. `preset-tower-reviewer` is a *conditional* component. It may be off while
+//      `review.requireReview` is false (merge is unaffected); with the review
+//      gate on it must be locked with an explanatory error, never silently
+//      allowed.
+//
+// `tower-tests` adds a third: with the component row off there is no
+// `tower_test` tool and no receipt, so `gates.requireTests: true` is refused
+// here rather than left to fail at merge time with a misleading blocker.
+import { TowerToolError } from '../domain/errors.js'
+import { componentEnabled, disabledReason } from './capability-registry.js'
+
+export function presetIds(config = {}) {
+  return {
+    worker: String(config.spawn?.workerPreset ?? 'tower-worker'),
+    reviewer: String(config.spawn?.reviewerPreset ?? 'tower-reviewer'),
+  }
+}
+
+function rowId(preset) {
+  return preset === 'tower-worker' ? 'preset-tower-worker' : preset === 'tower-reviewer' ? 'preset-tower-reviewer' : preset
+}
+
+/**
+ * Resolve the presets against the profile's agentPresets service. Fail closed
+ * with preset-missing before mode entry/planning when a *required* preset is not
+ * registered. If the service is unavailable, doctor reports that separately and
+ * this check cannot make a claim either way.
+ *
+ * The reviewer preset is required only when `review.requireReview` is true; the
+ * off state is otherwise supported by the component contract.
+ */
+export async function assertPresetsAvailable(ctx, config = {}) {
+  const service = ctx?.get?.('agentPresets')
+  if (!service || typeof service.list !== 'function') return { checked: false, missing: [] }
+  const presets = presetIds(config)
+  const required = [presets.worker]
+  if (config.review?.requireReview === true) required.push(presets.reviewer)
+  const available = new Set((await service.list()).map((entry) => String(entry.id)))
+  const missing = required.filter((id) => !available.has(id))
+  if (missing.length === 0) return { checked: true, missing: [] }
+  const rows = [...new Set(missing.map(rowId))]
+  const reviewLock =
+    config.review?.requireReview === true && missing.includes(presets.reviewer)
+      ? ` review.requireReview is true, so the reviewer row may not be off; ${disabledReason(rowId(presets.reviewer))} is rejected`
+      : ''
+  throw new TowerToolError(
+    'preset-missing',
+    `required Tower agent preset(s) missing: ${missing.join(', ')}; re-enable ${rows.join(', ')} in the plugin page, then restart DSH.${reviewLock}`,
+  )
+}
+
+/**
+ * Every runtime invariant that depends on which component rows are mounted.
+ * Called before planning and before entering Tower mode, so a configuration
+ * that a component switch has invalidated is rejected with an explanation
+ * instead of failing later at merge time.
+ *
+ * @param {any} ctx
+ * @param {Record<string, any>} config
+ */
+export async function assertRuntimePreconditions(ctx, config = {}) {
+  const presets = await assertPresetsAvailable(ctx, config)
+  if (config.gates?.requireTests === true && !componentEnabled('tower-tests')) {
+    throw new TowerToolError(
+      'config-invalid',
+      `gates.requireTests is true but ${disabledReason('tower-tests')}; re-enable the tower-tests component or set gates.requireTests:false`,
+    )
+  }
+  return presets
+}