dsh-tower 2.0.4 → 2.1.0

package/lib/archive.js

@@ -0,0 +1,279 @@
+// Terminal-mission archive storage (#73).
+//
+// Layout, under the Tower state directory:
+//
+//   archive/index.json      compact entries; tower_status pages from here
+//   archive/<year>.json     full missions plus their linked reviews/findings
+//
+// Both files carry `archiveVersion` (independent of the state SCHEMA_VERSION).
+// Reads are deliberately tolerant: a truncated or foreign archive returns a
+// diagnostic result and never throws, so `tower_status` still renders the hot
+// state. Writes happen before the state document is compacted, and dedupe by
+// mission id, so a crash between the two files is recoverable on the next
+// mutation instead of losing a mission.
+import path from 'node:path'
+import { fsp } from '../adapters/store-fs.js'
+import {
+  ARCHIVE_VERSION,
+  archiveDocumentError,
+  dedupeById,
+  indexEntryFromArchived,
+} from '../domain/state/archive.js'
+
+/** @typedef {import('../types/index.js').Mission} Mission */
+
+/**
+ * @param {{ dir: string }} paths
+ * @returns {{ dir: string, index: string, year: (year: number) => string }}
+ */
+export function archivePaths(paths) {
+  const dir = path.join(paths.dir, 'archive')
+  return { dir, index: path.join(dir, 'index.json'), year: (year) => path.join(dir, `${year}.json`) }
+}
+
+/**
+ * @param {any} error
+ * @returns {boolean}
+ */
+function isMissing(error) {
+  return error?.code === 'ENOENT'
+}
+
+/**
+ * @param {string} where
+ * @param {string} message
+ * @returns {string}
+ */
+function diagnostic(where, message) {
+  return `tower archive is unreadable at ${where}: ${message}`
+}
+
+/**
+ * Read `archive/index.json` without throwing. A missing index means "no
+ * archive yet"; a corrupt one is reported as `ok:false` with the diagnostic.
+ * @param {{ readJson: (file: string) => Promise<any> }} store
+ * @param {{ dir: string }} paths
+ * @returns {Promise<{ ok: boolean, file: string, missions: any[], error?: string, exists: boolean }>}
+ */
+export async function readArchiveIndex(store, paths) {
+  const file = archivePaths(paths).index
+  let document
+  try {
+    document = await store.readJson(file)
+  } catch (error) {
+    if (isMissing(error)) return { ok: true, file, missions: [], exists: false }
+    return { ok: false, file, missions: [], error: diagnostic(file, String(error?.message ?? error)), exists: true }
+  }
+  const error = archiveDocumentError(document, 'index', ` at ${file}`)
+  if (error) return { ok: false, file, missions: [], error, exists: true }
+  return { ok: true, file, missions: document.missions, exists: true }
+}
+
+/**
+ * @param {{ readJson: (file: string) => Promise<any> }} store
+ * @param {{ dir: string }} paths
+ * @param {number} year
+ * @returns {Promise<{ ok: boolean, file: string, missions: any[], error?: string, exists: boolean }>}
+ */
+export async function readArchiveYear(store, paths, year) {
+  const file = archivePaths(paths).year(year)
+  let document
+  try {
+    document = await store.readJson(file)
+  } catch (error) {
+    if (isMissing(error)) return { ok: true, file, missions: [], exists: false }
+    return { ok: false, file, missions: [], error: diagnostic(file, String(error?.message ?? error)), exists: true }
+  }
+  const error = archiveDocumentError(document, 'year', ` at ${file}`)
+  if (error) return { ok: false, file, missions: [], error, exists: true }
+  return { ok: true, file, missions: document.missions, exists: true }
+}
+
+/**
+ * Append full entries to their year files, then to the index. Returns
+ * `ok:false` (and writes nothing for the index) when an existing archive file
+ * is unreadable, so a corrupt archive is never silently replaced.
+ * @param {{ readJson: (file: string) => Promise<any>, writeJsonAtomic: (file: string, value: unknown) => Promise<void>, ensureDir: (dir: string) => Promise<void> }} store
+ * @param {{ dir: string }} paths
+ * @param {{ entries: Array<Record<string, any>>, now: number }} input
+ * @returns {Promise<{ ok: boolean, count: number, files: string[], error?: string }>}
+ */
+export async function writeArchiveEntries(store, paths, { entries, now }) {
+  if (entries.length === 0) return { ok: true, count: 0, files: [] }
+  const target = archivePaths(paths)
+
+  // Read the index first: if it is corrupt, refusing to write keeps the old
+  // history byte-identical and leaves the state missions intact for a retry.
+  const index = await readArchiveIndex(store, paths)
+  if (!index.ok) return { ok: false, count: 0, files: [], error: index.error }
+
+  /** @type {Map<number, Array<Record<string, any>>>} */
+  const byYear = new Map()
+  for (const entry of entries) {
+    const year = entry.archivedYear
+    if (!Number.isInteger(year)) return { ok: false, count: 0, files: [], error: `archive entry ${entry.id} has no archivedYear` }
+    const bucket = byYear.get(year) ?? []
+    bucket.push(entry)
+    byYear.set(year, bucket)
+  }
+
+  /** @type {Array<{ year: number, file: string, missions: any[] }>} */
+  const yearDocuments = []
+  for (const [year, batch] of [...byYear.entries()].sort((left, right) => left[0] - right[0])) {
+    const existing = await readArchiveYear(store, paths, year)
+    if (!existing.ok) return { ok: false, count: 0, files: [], error: existing.error }
+    yearDocuments.push({
+      year,
+      file: existing.file,
+      missions: dedupeById([...existing.missions, ...batch]),
+    })
+  }
+
+  await store.ensureDir(target.dir)
+  for (const document of yearDocuments) {
+    await store.writeJsonAtomic(document.file, {
+      archiveVersion: ARCHIVE_VERSION,
+      year: document.year,
+      updatedAt: now,
+      missions: document.missions,
+    })
+  }
+
+  const indexed = dedupeById([...index.missions, ...entries.map(indexEntryFromArchived)])
+  await store.writeJsonAtomic(target.index, {
+    archiveVersion: ARCHIVE_VERSION,
+    updatedAt: now,
+    missions: indexed,
+  })
+
+  return {
+    ok: true,
+    count: entries.length,
+    files: [...yearDocuments.map((document) => document.file), target.index],
+  }
+}
+
+/**
+ * Load one archived mission with its linked reviews/findings.
+ * @param {{ readJson: (file: string) => Promise<any> }} store
+ * @param {{ dir: string }} paths
+ * @param {string} missionId
+ * @returns {Promise<{ ok: boolean, entry?: Record<string, any>, unreadable?: boolean, missing?: boolean, error?: string }>}
+ */
+export async function readArchivedEntry(store, paths, missionId) {
+  const index = await readArchiveIndex(store, paths)
+  if (!index.ok) return { ok: false, unreadable: true, error: index.error }
+  const indexEntry = index.missions.find((entry) => entry.id === missionId)
+  if (!indexEntry) return { ok: false, missing: true }
+  const year = await readArchiveYear(store, paths, indexEntry.archivedYear)
+  if (!year.ok) return { ok: false, unreadable: true, error: year.error }
+  const entry = year.missions.find((candidate) => candidate.id === missionId)
+  if (!entry) {
+    return {
+      ok: false,
+      unreadable: true,
+      error: `tower archive index lists ${missionId} in ${year.file}, but the year file has no such entry`,
+    }
+  }
+  return { ok: true, entry }
+}
+
+/**
+ * @param {string} file
+ * @param {string} kind
+ * @returns {Promise<{ file: string, kind: string, ok: boolean, bytes: number, missions: number, error?: string, document?: any }>}
+ */
+async function inspectFile(file, kind) {
+  let text
+  try {
+    text = await fsp.readFile(file, 'utf8')
+  } catch (error) {
+    return { file, kind, ok: false, bytes: 0, missions: 0, error: diagnostic(file, String(error?.message ?? error)) }
+  }
+  const bytes = Buffer.byteLength(text)
+  let document
+  try {
+    document = JSON.parse(text)
+  } catch (error) {
+    return { file, kind, ok: false, bytes, missions: 0, error: diagnostic(file, `invalid JSON (${error.message})`) }
+  }
+  const error = archiveDocumentError(document, /** @type {'index'|'year'} */ (kind), ` at ${file}`)
+  if (error) return { file, kind, ok: false, bytes, missions: 0, error, document }
+  return { file, kind, ok: true, bytes, missions: document.missions.length, document }
+}
+
+/**
+ * Read-only inventory for `tower_doctor`: file sizes, mission counts, year
+ * files and every unreadable file's diagnostic. A missing archive directory is
+ * a healthy empty archive, not an error.
+ * @param {{ dir: string, state?: string }} paths
+ * @returns {Promise<{
+ *   dir: string, exists: boolean, bytes: number, missions: number, years: number[],
+ *   files: Array<Record<string, any>>, unreadable: string[],
+ *   index: { ok: boolean, count: number, error?: string } | null,
+ * }>}
+ */
+export async function inspectArchive(paths) {
+  const target = archivePaths(/** @type {{ dir: string }} */ (paths))
+  let names
+  try {
+    names = await fsp.readdir(target.dir)
+  } catch (error) {
+    if (isMissing(error)) {
+      return { dir: target.dir, exists: false, bytes: 0, missions: 0, years: [], files: [], unreadable: [], index: null }
+    }
+    return {
+      dir: target.dir,
+      exists: true,
+      bytes: 0,
+      missions: 0,
+      years: [],
+      files: [],
+      unreadable: [diagnostic(target.dir, String(error?.message ?? error))],
+      index: null,
+    }
+  }
+
+  const jsonFiles = names.filter((name) => name.endsWith('.json')).sort()
+  const files = []
+  let bytes = 0
+  let index = null
+  const yearIds = new Set()
+  for (const name of jsonFiles) {
+    const file = path.join(target.dir, name)
+    const kind = name === 'index.json' ? 'index' : 'year'
+    const inspected = await inspectFile(file, kind)
+    files.push({
+      file,
+      kind,
+      ok: inspected.ok,
+      bytes: inspected.bytes,
+      missions: inspected.missions,
+      ...(inspected.error ? { error: inspected.error } : {}),
+    })
+    bytes += inspected.bytes
+    if (kind === 'index') {
+      index = { ok: inspected.ok, count: inspected.missions, ...(inspected.error ? { error: inspected.error } : {}) }
+    } else if (inspected.ok) {
+      for (const entry of inspected.document.missions) yearIds.add(entry.id)
+    }
+  }
+  const unreadable = files
+    .filter((file) => !file.ok && typeof file.error === 'string')
+    .map((file) => /** @type {string} */ (file.error))
+  const years = files
+    .filter((file) => file.kind === 'year' && file.ok)
+    .map((file) => Number(path.basename(file.file, '.json')))
+    .filter((year) => Number.isInteger(year))
+    .sort((left, right) => left - right)
+  return {
+    dir: target.dir,
+    exists: true,
+    bytes,
+    missions: index?.ok ? index.count : yearIds.size,
+    years,
+    files,
+    unreadable,
+    index,
+  }
+}

package/lib/briefing.js

@@ -0,0 +1,176 @@
+// Mission briefings: pure text builders for worker/reviewer prompts.
+
+function clip(text, max = 2000) {
+  const value = String(text ?? '')
+  return value.length > max ? `${value.slice(0, max)}\n… truncated` : value
+}
+
+export function workerBriefing({
+  repoRoot,
+  base,
+  mission,
+  deps,
+  worktree,
+  instructions,
+  reviews = [],
+  findings = [],
+  completionReport = null,
+}) {
+  const completion = /** @type {import('../types/index.js').CompletionReport | null} */ (completionReport)
+  const lines = []
+  lines.push(`# Tower mission ${mission.id} — ${mission.title}`)
+  lines.push('')
+  lines.push(`You are the tower worker for mission ${mission.id} in repository ${repoRoot}.`)
+  lines.push('')
+  lines.push(`Work ONLY in this git worktree: ${worktree.path}`)
+  lines.push(`Branch: ${worktree.branch} (based on ${base} @ ${String(worktree.baseCommit).slice(0, 12)})`)
+  lines.push('')
+  lines.push(`Kind: ${mission.kind}`)
+  lines.push(
+    `Scope (only files you may touch): ${mission.scope.length > 0 ? mission.scope.join(', ') : '(none — survey is read-only)'}`,
+  )
+  if (mission.tasks.length > 0) {
+    lines.push('Tasks:')
+    for (const task of mission.tasks) lines.push(`- [${task.status}] ${task.text}`)
+  }
+  if (deps.length > 0) {
+    lines.push('Dependencies:')
+    for (const dep of deps) lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status})`)
+  }
+  if (mission.context) {
+    lines.push('Context (verbatim from the user):')
+    lines.push(mission.context)
+  }
+  if ((mission.references ?? []).length > 0) {
+    lines.push('References (read-only pointers; read them before deciding):')
+    for (const reference of mission.references) lines.push(`- ${reference}`)
+  }
+  if (mission.reviewPolicy === 'none') {
+    lines.push(`Review policy: none (user exemption: ${mission.reviewExemptionReason ?? 'missing reason'})`)
+  }
+  if (completion) {
+    lines.push('')
+    lines.push(`Previous completion report (by ${completion.by ?? 'worker'}):`)
+    lines.push(clip(completion.report, 1500))
+    if ((completion.checks ?? []).length > 0) {
+      lines.push('Previous checks:')
+      for (const check of completion.checks ?? []) lines.push(`- ${check.name}${check.exitCode !== undefined ? ` (exit ${check.exitCode})` : ''}`)
+    }
+  }
+  if (reviews.length > 0) {
+    lines.push('')
+    lines.push('Previous review rounds for this branch (newest first) — address every finding:')
+    for (const review of reviews) {
+      lines.push(`- R${review.round} by ${review.reviewer}: ${review.status} / ${review.mergeVerdict}`)
+      if (review.findings) lines.push(`  findings: ${clip(review.findings, 1200).replaceAll('\n', '\n  ')}`)
+      if (review.decision) lines.push(`  decision: ${clip(review.decision, 600)}`)
+    }
+  }
+  if (findings.length > 0) {
+    lines.push('')
+    lines.push('Findings related to this mission:')
+    for (const finding of findings) lines.push(`- ${finding.id} [${finding.status}] ${finding.severity ?? 'severity?'} ${finding.title}`)
+  }
+  lines.push('')
+  lines.push('Rules:')
+  lines.push(`- Pass workdir="${worktree.path}" on every shell command; never edit the main checkout.`)
+  lines.push('- Stay inside the declared scope; out-of-scope changes are rejected later.')
+  lines.push('- Commit your work on the mission branch. Do not merge, push, or spawn other agents.')
+  lines.push(
+    `- Update progress: tower_mission({repoRoot:"${repoRoot}",id:"${mission.id}",task_done:"..."}) or blocker:"...".`,
+  )
+  lines.push(
+    `- When the work is finished and every task is closed, call tower_complete({repoRoot:"${repoRoot}",missionId:"${mission.id}",report:"<full handoff>",checks:[{name,command,exitCode,evidence}]}). Unread inbox messages block completion, so read them with tower_inbox first.`,
+  )
+  lines.push('- Your final message is the full handoff: files changed, how you verified, what remains.')
+  if (instructions) {
+    lines.push('')
+    lines.push('Extra tower instructions:')
+    lines.push(instructions)
+  }
+  return lines.join('\n')
+}
+
+export function reviewerBriefing({
+  repoRoot,
+  base,
+  mission,
+  deps,
+  worktree,
+  instructions,
+  reviews = [],
+  findings = [],
+  completionReport = null,
+}) {
+  const completion = /** @type {import('../types/index.js').CompletionReport | null} */ (completionReport)
+  const lines = []
+  lines.push(`# Tower review — mission ${mission.id} — ${mission.title}`)
+  lines.push('')
+  lines.push(`You are the independent reviewer for mission ${mission.id} in repository ${repoRoot}.`)
+  lines.push('')
+  lines.push(`Review branch: ${worktree.branch}`)
+  lines.push(`Worktree: ${worktree.path}`)
+  lines.push(`Reviewed base: ${base} @ ${String(worktree.baseCommit).slice(0, 12)}`)
+  lines.push('')
+  lines.push(`Kind: ${mission.kind}`)
+  if (mission.tasks.length > 0) {
+    lines.push('The worker was asked to complete:')
+    for (const task of mission.tasks) lines.push(`- [${task.status}] ${task.text}`)
+  }
+  if (deps.length > 0) {
+    lines.push('Dependencies:')
+    for (const dep of deps) lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status})`)
+  }
+  if (mission.context) {
+    lines.push('Context (verbatim from the user):')
+    lines.push(mission.context)
+  }
+  if ((mission.references ?? []).length > 0) {
+    lines.push('References (read-only pointers):')
+    for (const reference of mission.references) lines.push(`- ${reference}`)
+  }
+  if (completion) {
+    lines.push('')
+    lines.push(`Completion report (by ${completion.by ?? 'worker'}):`)
+    lines.push(clip(completion.report, 2000))
+    if ((completion.checks ?? []).length > 0) {
+      lines.push('Completion checks the worker ran:')
+      for (const check of completion.checks ?? []) {
+        lines.push(
+          `- ${check.name}${check.exitCode !== undefined ? ` (exit ${check.exitCode})` : ''}${check.evidence ? ` — ${clip(check.evidence, 400)}` : ''}`,
+        )
+      }
+    }
+  }
+  if (reviews.length > 0) {
+    lines.push('')
+    lines.push('Prior review rounds for this branch (newest first):')
+    for (const review of reviews) {
+      lines.push(`- R${review.round} by ${review.reviewer}: ${review.status} / ${review.mergeVerdict}`)
+      if (review.findings) lines.push(`  findings: ${clip(review.findings, 1200).replaceAll('\n', '\n  ')}`)
+    }
+  }
+  if (findings.length > 0) {
+    lines.push('')
+    lines.push('Related findings:')
+    for (const finding of findings) lines.push(`- ${finding.id} [${finding.status}] ${finding.severity ?? 'severity?'} ${finding.title}`)
+  }
+  lines.push('')
+  lines.push('Rules:')
+  lines.push('- Read-only: do not modify files, commit, or merge.')
+  lines.push('- Inspect the diff from the reviewed base to the branch tip and map every task to the diff.')
+  lines.push('- Check scope, correctness, tests, and security. Report severity and concrete evidence.')
+  lines.push(
+    `- Submit the formal verdict with tower_review({repoRoot:"${repoRoot}",missionId:"${mission.id}",status:"clean",merge:"merge",findings:"none",checks:["..."],decision:"..."}). Use status "p1-Nitems"/"p2-Nitems" and merge "fix-then-merge"/"hold" for problems; a non-clean verdict returns the mission to active.`,
+  )
+  lines.push(
+    `- File out-of-scope issues with tower_finding({repoRoot:"${repoRoot}",type:"bug",title:"...",summary:"...",details:"...",suggested_fix:"..."}) instead of fixing them.`,
+  )
+  lines.push('- Your final message is the review report; the tool call above is the formal verdict.')
+  if (instructions) {
+    lines.push('')
+    lines.push('Extra tower instructions:')
+    lines.push(instructions)
+  }
+  return lines.join('\n')
+}

package/lib/caseSensitivity.js

@@ -0,0 +1,66 @@
+// Case-insensitive-filesystem detection (#90).
+//
+// On Windows and macOS the checkout's filesystem folds case, while Git reports
+// the casing stored in the index. Scope matching has to know which world it is
+// in, so `tower_init` probes once and records the answer in state.
+//
+// The probe creates one uniquely-named mixed-case file in the checkout root
+// (the filesystem scope matching actually compares) and looks its lower-cased
+// name up. It returns:
+//   true   the lookup found the file: the filesystem folds case;
+//   false  the lookup was ENOENT: the filesystem is case-sensitive;
+//   null   the probe could not run (read-only checkout, EPERM, an unexpected
+//          stat failure). "Unknown" is deliberately not "case-sensitive": init
+//          keeps working and `tower_doctor` reports the safe default.
+import path from 'node:path'
+import { fsp } from '../adapters/store-fs.js'
+
+/** Prefix is public so tests and support code can recognise a leaked probe. */
+export const CASE_PROBE_PREFIX = '.tower-case-probe-'
+
+/**
+ * A name that is guaranteed to differ from its lower-cased form, so the lookup
+ * actually distinguishes the two filesystem behaviours.
+ * @param {() => number} random
+ * @returns {string}
+ */
+function probeName(random) {
+  return `${CASE_PROBE_PREFIX}Z${random().toString(36).slice(2, 10)}`
+}
+
+/**
+ * @param {string} dir directory on the filesystem under test
+ * @param {{ fs?: typeof fsp, name?: string, random?: () => number }} [options]
+ *   `fs` is a seam for the failure branches, which cannot be produced portably
+ *   by permissions on every OS (Windows does not honour chmod the way POSIX does).
+ * @returns {Promise<boolean | null>}
+ */
+export async function detectCaseSensitivity(dir, options = {}) {
+  const fs = options.fs ?? fsp
+  const name = options.name ?? probeName(options.random ?? Math.random)
+  const probePath = path.join(dir, name)
+  const lowerPath = path.join(dir, name.toLowerCase())
+  if (lowerPath === probePath) return null
+
+  try {
+    await fs.writeFile(probePath, '')
+  } catch {
+    return null
+  }
+
+  try {
+    await fs.stat(lowerPath)
+    return true
+  } catch (error) {
+    const code = /** @type {{ code?: string }} */ (error)?.code
+    return code === 'ENOENT' ? false : null
+  } finally {
+    // Best effort: a leaked probe would dirty `git status` of the state dir and
+    // the detection result is already known.
+    try {
+      await fs.unlink(probePath)
+    } catch {
+      // the probe file may already be gone (or the failure branch never wrote it)
+    }
+  }
+}

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
+}