dsh-tower 2.0.4 → 2.1.0-beta.1

package/scripts/release-check.mjs

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+// Release gate (#97, #76): a tag is a claim, so make it cost evidence.
+//
+// The gate compares three facts on every run:
+//
+//   1. `package.json` version vs the previous reachable `v<semver>` tag,
+//   2. whether the CHANGELOG carries release content (a non-empty Unreleased
+//      section, or a non-empty section whose heading names the version),
+//   3. on a tag push, that the pushed tag is exactly `v<version>`.
+//
+// It always prints `git describe`, the previous tag, the commit count since
+// that tag and whether Unreleased is non-empty, so a large backlog is visible
+// before an audit finds it. On a PR/branch push findings are warnings (exit 0);
+// on a tag push a contradiction is an error (exit 1).
+//
+// Tag-push pitfall: `git describe --tags --abbrev=0` returns the *pushed* tag
+// itself (and otherwise the nearest tag of any shape), so the previous tag is
+// resolved from `<tag>^` and filtered to `v<semver>` (falling back to the newest
+// version tag that is an ancestor).
+//
+// Usage:
+//   node scripts/release-check.mjs [--mode pr|tag] [--tag <name>] [--json]
+//
+// On CI the mode comes from GITHUB_REF_TYPE (`tag` on a tag push) and the tag
+// name from GITHUB_REF_NAME. Locally, verify before tagging with
+// `npm run release:check -- --mode tag --tag v<version>`.
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { compareVersions } from '../lib/compatibility.js'
+import { findingRecorder, parseArgs, runMain, UsageError } from './lib/cli.mjs'
+
+const USAGE = `usage: node scripts/release-check.mjs [--mode pr|tag] [--tag <name>] [--json] [--help]
+
+  --mode       "pr" warns only (default); "tag" fails on a contradiction
+  --tag        pushed tag name (default: GITHUB_REF_NAME in tag mode)
+  --json       print the facts and findings as JSON
+  --help       print this text`
+
+const VERSION_TAG = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+
+// A version is stored without its tag prefix; a tag is `v` + that version. The
+// release gate talks about both, so the conversion lives in one place.
+function versionTag(version) {
+  return `v${stripTag(version)}`
+}
+
+function stripTag(tag) {
+  return String(tag).replace(/^v/i, '')
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function trimSection(lines) {
+  return lines.join('\n').trim()
+}
+
+function sectionBody(text, headingMatches) {
+  const lines = String(text ?? '').split(/\r?\n/)
+  const start = lines.findIndex((line) => /^##\s+/.test(line) && headingMatches(line))
+  if (start < 0) return null
+  const body = []
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index])) break
+    body.push(lines[index])
+  }
+  return trimSection(body)
+}
+
+export function unreleasedSection(changelog) {
+  return sectionBody(changelog, (line) => /unreleased|未发布/i.test(line))
+}
+
+export function versionSection(changelog, version) {
+  if (!version) return null
+  const pattern = new RegExp(`(?:^|[^0-9A-Za-z.-])${escapeRegExp(version)}(?![0-9A-Za-z.-])`)
+  return sectionBody(changelog, (line) => pattern.test(line.replace(/^##\s+/, '')))
+}
+
+// A section that only holds an HTML comment or a horizontal rule is a
+// placeholder, not release notes.
+export function hasContent(text) {
+  if (text === null || text === undefined) return false
+  const cleaned = String(text)
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/^\s*[-*_]{3,}\s*$/gm, '')
+    .trim()
+  return cleaned.length > 0
+}
+
+export function evaluateRelease(input = {}) {
+  const version = String(input.version ?? '').trim()
+  if (!version) throw new UsageError('package.json has no version')
+  const mode = input.mode ?? 'pr'
+  if (mode !== 'pr' && mode !== 'tag') throw new UsageError(`--mode must be "pr" or "tag", not ${JSON.stringify(mode)}`)
+  const tag = input.tag ? String(input.tag) : null
+  const previousTag = input.previousTag ? String(input.previousTag) : null
+  const changelog = input.changelog ?? ''
+  const commitsSince = Number.isFinite(input.commitsSince) ? input.commitsSince : null
+  const describe = input.describe ?? null
+  const isTag = mode === 'tag'
+  const level = isTag ? 'error' : 'warning'
+  const suffix = isTag ? '' : ' (warning only outside a tag push)'
+  const count = commitsSince === null ? 'unknown' : String(commitsSince)
+
+  const unreleasedText = unreleasedSection(changelog)
+  const unreleased = hasContent(unreleasedText)
+  const versionNotes = versionSection(changelog, version)
+  const notesKind = unreleased ? 'unreleased' : hasContent(versionNotes) ? 'version-section' : 'none'
+  const previousVersion = previousTag ? stripTag(previousTag) : null
+  const findings = []
+  const record = findingRecorder(findings)
+
+  if (!previousTag) {
+    record('no-baseline', 'warning', `no reachable previous tag; cannot compare version ${version} against a release${suffix}`)
+  } else {
+    const direction = compareVersions(version, previousVersion)
+    // An unparseable version pair is treated as "did not move": publishing a
+    // version the release math cannot reason about is not evidence.
+    if (direction === null || direction <= 0) {
+      const relation = direction === 0 || direction === null ? 'equals' : 'is older than'
+      record(
+        'version-not-bumped',
+        level,
+        `version did not move: package.json ${version} ${relation} the previous tag ${previousTag}; ` +
+          `${count} commits since that tag; Unreleased is ${unreleased ? 'non-empty' : 'empty'}${suffix}`,
+      )
+    }
+  }
+  if (notesKind === 'none') {
+    record(
+      'no-release-notes',
+      level,
+      `CHANGELOG has no release notes for ${version}: the Unreleased section is empty and there is ` +
+        `no non-empty "## ${version}（…）" section${suffix}`,
+    )
+  }
+
+  if (isTag) {
+    if (!tag) {
+      record('tag-missing', 'error', 'tag push mode needs the tag name (GITHUB_REF_NAME or --tag)')
+    } else if (tag !== versionTag(version)) {
+      record(
+        'tag-name-mismatch',
+        'error',
+        `tag ${tag} does not match package version ${version}; expected ${versionTag(version)}`,
+      )
+    }
+  }
+
+  const errors = findings.filter((finding) => finding.level === 'error').length
+  const warnings = findings.filter((finding) => finding.level === 'warning').length
+  return {
+    ok: errors === 0,
+    mode,
+    findings,
+    errors,
+    warnings,
+    facts: { version, mode, tag, previousTag, previousVersion, commitsSince, describe, unreleased, notesKind },
+  }
+}
+
+// --- Git facts ---------------------------------------------------------------
+
+function runGit(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' })
+  if (result.error || result.status !== 0) return null
+  return (result.stdout ?? '').trim()
+}
+
+function versionTags(root) {
+  const output = runGit(root, ['tag', '--list'])
+  if (!output) return []
+  return output.split('\n').map((line) => line.trim()).filter((tag) => VERSION_TAG.test(tag))
+}
+
+function newestAncestorTag(root, revision, exclude) {
+  const tags = versionTags(root).filter((tag) => tag !== exclude && runGit(root, ['merge-base', '--is-ancestor', tag, revision]) !== null)
+  tags.sort((left, right) => (compareVersions(right, left) ?? 0))
+  return tags[0] ?? null
+}
+
+// The latest reachable *version* tag. `git describe` happily reports any tag
+// near HEAD, so a maintenance tag (`ui-0.2.2`) must be filtered out here or the
+// release math compares a version against a non-version string.
+function describeVersionTag(root, revision) {
+  const described = runGit(root, ['describe', '--tags', '--abbrev=0', '--match', 'v[0-9]*', revision])
+  return described && VERSION_TAG.test(described) ? described : null
+}
+
+export function resolvePreviousTag(root, tag) {
+  const tagExists = tag ? runGit(root, ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`]) !== null : false
+  const revision = tag && tagExists ? tag : 'HEAD'
+  // Never compare against the pushed tag itself: it is the release, not its
+  // predecessor. `<tag>^` is the commit that was HEAD before the tag existed.
+  if (tagExists) {
+    const parent = describeVersionTag(root, `${tag}^`)
+    if (parent && parent !== tag) return parent
+  }
+  const described = describeVersionTag(root, revision)
+  if (described && described !== tag) return described
+  return newestAncestorTag(root, revision, tag)
+}
+
+export function collectFacts(root, options = {}) {
+  if (runGit(root, ['rev-parse', '--git-dir']) === null) {
+    throw new UsageError(`${root} is not a Git repository; the release gate compares the version against tags`)
+  }
+  const previousTag = options.previousTag ?? resolvePreviousTag(root, options.tag ?? null)
+  const commitsSince = previousTag ? Number(runGit(root, ['rev-list', '--count', `${previousTag}..HEAD`])) : null
+  const describe = runGit(root, ['describe', '--tags', '--always'])
+  return {
+    previousTag,
+    commitsSince: Number.isFinite(commitsSince) ? commitsSince : null,
+    describe: describe ?? null,
+  }
+}
+
+// --- CLI ---------------------------------------------------------------------
+
+function printFacts(facts) {
+  const dash = (value) => (value === null || value === undefined || value === '' ? '-' : value)
+  console.log(
+    `release-check: version=${facts.version} mode=${facts.mode} tag=${dash(facts.tag)} ` +
+      `previous-tag=${dash(facts.previousTag)} commits-since=${dash(facts.commitsSince)} ` +
+      `describe=${dash(facts.describe)} unreleased=${facts.unreleased ? 'yes' : 'no'} notes=${facts.notesKind}`,
+  )
+}
+
+function cli(argv) {
+  const options = parseArgs(argv, {
+    initial: { mode: null, tag: null, json: false, help: false },
+    values: { '--mode': 'mode', '--tag': 'tag' },
+    flags: { '--json': 'json', '--help': 'help', '-h': 'help' },
+  })
+  if (options.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const mode = options.mode ?? (process.env.GITHUB_REF_TYPE === 'tag' ? 'tag' : 'pr')
+  let tag = options.tag
+  if (!tag && mode === 'tag' && process.env.GITHUB_REF_TYPE === 'tag') tag = process.env.GITHUB_REF_NAME || null
+
+  const root = process.cwd()
+  const packagePath = path.join(root, 'package.json')
+  const changelogPath = path.join(root, 'CHANGELOG.md')
+  let version
+  try {
+    version = JSON.parse(fs.readFileSync(packagePath, 'utf8')).version
+  } catch (error) {
+    console.error(`release-check: cannot read ${packagePath}: ${error?.message ?? error}`)
+    return 2
+  }
+  let changelog
+  try {
+    changelog = fs.readFileSync(changelogPath, 'utf8')
+  } catch (error) {
+    console.error(`release-check: cannot read ${changelogPath}: ${error?.message ?? error}`)
+    return 2
+  }
+
+  let result
+  try {
+    const gitFacts = collectFacts(root, { tag })
+    result = evaluateRelease({ version, mode, tag, changelog, ...gitFacts })
+  } catch (error) {
+    console.error(`release-check: ${error.message}`)
+    return 2
+  }
+
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          root,
+          package: packagePath,
+          changelog: changelogPath,
+          ...result,
+        },
+        null,
+        2,
+      ),
+    )
+    return result.ok ? 0 : 1
+  }
+
+  printFacts(result.facts)
+  for (const finding of result.findings) console.log(`${finding.level} [${finding.code}] ${finding.message}`)
+  if (result.ok) {
+    console.log(
+      result.warnings > 0
+        ? `release-check: ok (${result.warnings} warning(s), no tag blocking this run)`
+        : 'release-check: ok',
+    )
+  } else {
+    console.log(`release-check: ${result.errors} error(s), ${result.warnings} warning(s); refusing the release claim`)
+  }
+  return result.ok ? 0 : 1
+}
+
+await runMain(import.meta.url, () => cli(process.argv.slice(2)), { errorPrefix: 'release-check', usage: USAGE })

package/tools/adopt.js

@@ -0,0 +1,72 @@
+// tower_adopt: reconcile the roster with the subagent catalog.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { AdoptInput } from '../domain/contracts/tool-inputs/index.js'
+import { PARENT_STATUS_OK, ROSTER_ACTIVITY, ROSTER_STATE } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any }} deps
+ */
+export function registerAdoptTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor } = deps
+  define(ctx, {
+    name: 'tower_adopt',
+    description:
+      'Reconcile the roster with the durable subagent catalog after a restart or new session. Agents that are provably gone are marked retired (records are kept) or missing (retireMissing:false, so the tower can inspect/take over); agents whose parent catalog cannot be read stay unknown and are never changed. Only the tower may adopt.',
+    parameters: AdoptInput,
+    aliases: { retire_missing: ['retireMissing'] },
+    output: output(SCHEMAS.adopt),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'adopt the roster')
+      const view = await tower.rosterView()
+      const subagents = ctx.get('subagents')
+      if (!subagents) throw new TowerToolError('spawn-unavailable', 'subagents service is unavailable; cannot adopt')
+
+      const parents = [...new Set(view.roster.map((entry) => entry.parentSessionId).filter(Boolean))]
+      const activity = new Map()
+      const parentStatus = {}
+      for (const parent of parents) {
+        try {
+          const rows = await subagents.listDescendants(parent)
+          for (const row of rows) activity.set(String(row.id), row.activity ?? ROSTER_ACTIVITY.unknown)
+          parentStatus[parent] = PARENT_STATUS_OK
+        } catch (error) {
+          parentStatus[parent] = `unavailable: ${String(error?.message ?? error)}`
+        }
+      }
+
+      const retiredCandidates = []
+      const presentIds = []
+      const absentIds = []
+      for (const entry of view.roster) {
+        if (entry.state === ROSTER_STATE.retired) continue
+        if (parentStatus[entry.parentSessionId] !== PARENT_STATUS_OK) continue
+        if (activity.has(entry.agentId)) {
+          presentIds.push(entry.agentId)
+        } else {
+          absentIds.push(entry.agentId)
+        }
+      }
+      const observations = await tower.recordRosterObservations({ present: presentIds, absent: absentIds, confirmations: 2 })
+      retiredCandidates.push(...observations.candidates)
+      const retireMissing = args.retireMissing !== false
+      const { retired } = retireMissing ? await tower.markRetired(retiredCandidates) : { retired: [] }
+      const { missing } = retireMissing ? { missing: [] } : await tower.markMissing(retiredCandidates)
+      const after = await tower.rosterView()
+      return {
+        retired,
+        missing,
+        unconfirmed: absentIds.filter((agentId) => !retiredCandidates.includes(agentId)),
+        skippedUnknownParents: Object.entries(parentStatus)
+          .filter(([, status]) => status !== PARENT_STATUS_OK)
+          .map(([parent]) => parent),
+        roster: after.roster,
+        parentStatus,
+      }
+    },
+  })
+}

package/tools/batch.js

@@ -0,0 +1,78 @@
+// tower_batch: finite evidence batches.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { BatchInput } from '../domain/contracts/tool-inputs/index.js'
+import { BATCH_ACTION } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any, summarizeBatch: any, verifyBatchReceiptFiles: any }} deps
+ */
+export function registerBatchTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor, summarizeBatch, verifyBatchReceiptFiles } = deps
+  define(ctx, {
+    name: 'tower_batch',
+    description:
+      'Manage finite evidence batches: create freezes missionIds/requiredChecks/receiptPaths, status summarizes members, close verifies every required check and receipt hash, abandon retires a stale open batch. Membership and exclusions are immutable after create; close/abandon never remove missions.',
+    parameters: BatchInput,
+    board: true,
+    output: output(SCHEMAS.batch),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      if (args.action === BATCH_ACTION.status) {
+        const state = await tower.load()
+        const batch = args.batchId
+          ? (state.batches ?? []).find((entry) => entry.id === args.batchId)
+          : null
+        if (args.batchId && !batch) throw new TowerToolError('invalid-argument', `unknown batch "${args.batchId}"`)
+        return {
+          ok: true,
+          action: BATCH_ACTION.status,
+          batches: (state.batches ?? []).map((entry) => summarizeBatch(state, entry)),
+          ...(batch ? { batch: summarizeBatch(state, batch) } : {}),
+          ...(args.batchId ? { summary: summarizeBatch(state, batch) } : {}),
+        }
+      }
+      requireTowerActor(actor, args.action === BATCH_ACTION.create ? 'create a batch' : args.action === BATCH_ACTION.abandon ? 'abandon a batch' : 'close a batch')
+      if (args.action === BATCH_ACTION.create) {
+        const batch = await tower.createBatch(args, actor.name)
+        return { ok: true, action: BATCH_ACTION.create, batch, batches: (await tower.batchStatus()).batches }
+      }
+      if (typeof args.batchId !== 'string' || args.batchId.trim().length === 0) {
+        throw new TowerToolError('invalid-argument', `tower_batch ${args.action} requires batchId`)
+      }
+      const batchId = args.batchId.trim()
+      if (args.action === BATCH_ACTION.abandon) {
+        const result = await tower.abandonBatch(batchId, actor.name, /** @type {any} */ (args.reason))
+        return { ok: true, action: BATCH_ACTION.abandon, batch: result.batch, blockers: [] }
+      }
+      const closeState = await tower.load()
+      const closeBatch = (closeState.batches ?? []).find((entry) => entry.id === batchId)
+      if (closeBatch) {
+        const receiptProblems = await verifyBatchReceiptFiles(tower.root, closeBatch, args)
+        if (receiptProblems.length > 0) {
+          return { ok: false, action: BATCH_ACTION.close, batch: closeBatch, blockers: receiptProblems, checks: [] }
+        }
+      }
+      const result = await tower.closeBatch(batchId, {
+        checks: args.checks,
+        treeTip: args.treeTip,
+        receiptHashes: args.receiptHashes,
+      }, actor.name)
+      return {
+        ok: result.ok,
+        action: BATCH_ACTION.close,
+        batch: result.batch,
+        blockers: (result.blockers ?? []).map((blocker) => ({
+          code: blocker.code ?? 'batch-invalid',
+          detail: blocker.detail ?? blocker.message ?? String(blocker),
+          ...(blocker.cleanup ? { cleanup: blocker.cleanup } : {}),
+          ...(blocker.timeout ? { timeout: true } : {}),
+        })),
+        checks: result.checks ?? [],
+      }
+    },
+  })
+}

package/tools/complete.js

@@ -0,0 +1,53 @@
+// tower_complete: worker completion admission.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { CompleteInput } from '../domain/contracts/tool-inputs/index.js'
+import { isCompleteAdmission } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, runMissionDiscovery: any }} deps
+ */
+export function registerCompleteTool(ctx, deps) {
+  const { define, runMissionDiscovery } = deps
+  define(ctx, {
+    name: 'tower_complete',
+    description:
+      'Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base, and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. Stores the full report; completion means ready for preflight and optional review, not merged.',
+    parameters: CompleteInput,
+    aliases: {"missionId":["id"]},
+    requiresMissionId: true,
+    board: true,
+    output: output(SCHEMAS.complete),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      // Validate authorization/state before executing repository-controlled
+      // test code or writing a test receipt.
+      await tower.checkCompletion({
+        missionId: args.missionId,
+        agentId: String(exec.agent.id),
+        report: args.report,
+      })
+      const context = await tower.missionContext(args.missionId)
+      const checks = [...(Array.isArray(args.checks) ? args.checks : [])]
+      const testsConfig = /** @type {any} */ (tower.config.tests ?? {})
+      if (testsConfig.enabled !== false && isCompleteAdmission(testsConfig.admission)) {
+        const discovery = await runMissionDiscovery(tower, { id: args.missionId, worktree: context.mission.worktree })
+        if (discovery.configured && discovery.receipt.ok !== true) {
+          throw new TowerToolError('tests-failed', `test discovery failed for ${args.missionId}: ${discovery.receipt.error}`)
+        }
+        if (discovery.configured && testsConfig.autoChecks !== false && discovery.check) {
+          if (checks.length >= 20) checks[19] = discovery.check
+          else checks.push(discovery.check)
+        }
+      }
+      return tower.complete({
+        missionId: args.missionId,
+        agentId: String(exec.agent.id),
+        report: args.report,
+        checks,
+      })
+    },
+  })
+}

package/tools/diff.js

@@ -0,0 +1,39 @@
+// The result is bound to the recorded reviewed tip only when requested.
+// Callers must treat the patch as read-only evidence.
+// The tool never checks out or mutates the mission branch.
+// Reviewers may use it without holding the state lock.
+// tower_diff — read-only mission branch view.
+// 
+// Input: DiffInput (missionId/id, maxBytes) from domain contracts.
+// Output: merge base, changed files, commits, capped patch.
+// Authorization: tower, reviewer, or assigned worker may inspect.
+// Side effects: none; it never writes state, git, or the repository.
+// Failure modes: unknown mission, missing worktree, stale branch.
+// Errors are classified as [tower:<code>] by the registry.
+// The patch cap is enforced by the pure read projection.
+// See docs/reference/tools.generated.md for the public shape.
+// tower_diff: read-only mission branch view.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { DiffInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool }} deps
+ */
+export function registerDiffTool(ctx, deps) {
+  const { define } = deps
+  define(ctx, {
+    name: 'tower_diff',
+    description:
+      'Read-only view of a mission branch for review: merge base, changed files, commits, and a capped patch against the recorded base. Safe for reviewers; it never modifies the repository.',
+    parameters: DiffInput,
+    aliases: {"missionId":["id"]},
+    requiresMissionId: true,
+    output: output(SCHEMAS.diff),
+    async execute(args) {
+      const tower = await Tower.open(args.repoRoot)
+      return tower.diff({ missionId: args.missionId, maxBytes: args.maxBytes })
+    },
+  })
+}

package/tools/doctor.js

@@ -0,0 +1,50 @@
+// tower_doctor: read-only health check.
+import { Tower } from '../app/tower.js'
+import { resolveRepo } from '../lib/git.js'
+import { runtimeConfig } from '../lib/config.js'
+import { runDoctor } from '../lib/doctor.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { DoctorInput } from '../domain/contracts/tool-inputs/index.js'
+import { DOCTOR_STATUS } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {import('../types/index.js').DefineTool} define
+ */
+export function registerDoctorTool(ctx, define) {
+  define(ctx, {
+    name: 'tower_doctor',
+    description:
+      'Read-only environment and repository health check: git, state schema, config, presets/subagents/HMR, workspace lock, roster staleness, worktree ownership, test discovery, leases. Returns checks with pass/warn/fail and an environment contract. Never writes state.',
+    parameters: DoctorInput,
+    output: output(SCHEMAS.doctor),
+    async execute(args, exec) {
+      let tower
+      let configError = null
+      try {
+        tower = await Tower.open(args.repoRoot)
+      } catch (error) {
+        const message = String(error?.message ?? error)
+        if (error?.code !== 'config-invalid' && error?.code !== 'config-unknown-key') throw error
+        configError = message
+        const repo = await resolveRepo(args.repoRoot)
+        tower = new Tower(repo, { ...runtimeConfig(), configPath: null, repoConfigPresent: true })
+      }
+      const report = await runDoctor(/** @type {any} */ ({ tower, ctx, agent: exec.agent }))
+      if (!configError) return report
+      return {
+        ...report,
+        ok: false,
+        checks: [
+          {
+            id: 'config',
+            status: DOCTOR_STATUS.fail,
+            detail: configError,
+            fix: 'repair <git-common-dir>/dsh-tower/config.json and re-run tower_doctor',
+          },
+          ...(report.checks ?? []),
+        ],
+      }
+    },
+  })
+}

package/tools/finding.js

@@ -0,0 +1,40 @@
+// tower_finding: file one structured finding.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { FindingInput } from '../domain/contracts/tool-inputs/index.js'
+import { ROLE } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireKnownActor: any }} deps
+ */
+export function registerFindingTool(ctx, deps) {
+  const { define, actorFor, requireKnownActor } = deps
+  define(ctx, {
+    name: 'tower_finding',
+    description:
+      'File a structured finding (bug / improve / vuln / idea) for the tower to route. Use this for anything notable OUTSIDE your mission scope instead of editing out-of-scope files. Severity is one of low|medium|high|critical. Use tower_findings to list, read, or close findings later.',
+    parameters: FindingInput,
+    aliases: {"missionId":["mission_id"]},
+    board: true,
+    output: output(SCHEMAS.finding),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireKnownActor(actor, 'tower_finding')
+      const view = await tower.rosterView()
+      const self = view.roster.find((entry) => entry.agentId === String(exec.agent.id))
+      return tower.addFinding({
+        type: args.type,
+        title: args.title,
+        severity: args.severity,
+        summary: args.summary,
+        location: args.location,
+        details: args.details,
+        suggested_fix: args.suggested_fix,
+        missionId: args.missionId,
+        reportedBy: self ? self.name : ROLE.tower,
+      })
+    },
+  })
+}

package/tools/findings.js

@@ -0,0 +1,39 @@
+// tower_findings: list, read, or update findings.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { FindingsInput } from '../domain/contracts/tool-inputs/index.js'
+import { ROLE } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireKnownActor: any }} deps
+ */
+export function registerFindingsTool(ctx, deps) {
+  const { define, actorFor, requireKnownActor } = deps
+  define(ctx, {
+    name: 'tower_findings',
+    description:
+      'List, read, or update findings for a repository. Without id it lists findings newest-first with counts by status (filters: status, type, severity, missionId, open, limit). With id it returns that finding; with id plus status and/or note it records a lifecycle transition. Statuses are open -> triaged -> fixed|wontfix, and fixed/wontfix can be reopened to open. Only the tower or a worker may change a finding; reviewers may only list and read. Read-only when no id is given.',
+    parameters: FindingsInput,
+    aliases: {"missionId":["mission_id"]},
+    output: output(SCHEMAS.findings),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireKnownActor(actor, 'tower_findings')
+      const view = await tower.rosterView()
+      const self = view.roster.find((entry) => entry.agentId === String(exec.agent.id))
+      return tower.findings({
+        id: args.id,
+        status: args.status,
+        note: args.note,
+        type: args.type,
+        severity: args.severity,
+        missionId: args.missionId,
+        open: args.open,
+        limit: args.limit,
+        actor: { name: self ? self.name : ROLE.tower, role: self ? self.role : ROLE.tower },
+      })
+    },
+  })
+}