dsh-tower 1.3.0 → 2.0.1

package/lib/config.js

@@ -1,9 +1,18 @@
 // Tower configuration: one declared schema, resolved defaults, and the
 // process-local effective snapshot consumed by the domain modules.
 //
+// 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)
+//
 // 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'
+import path from 'node:path'
 import Schema from '@deepseek-ai/schemastery'
+import { TowerToolError } from './errors.js'
 
 export const DEFAULT_DENY_TOOLS = [
   'create_goal',
@@ -11,11 +20,17 @@ export const DEFAULT_DENY_TOOLS = [
   '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 = ['mode', 'review', 'merge', 'worktrees', 'spawn']
+const GROUP_KEYS = ['init', 'mode', 'review', 'merge', 'worktrees', 'spawn', 'send', 'tests', 'gates', 'docs', 'leases', 'dev']
 
 const ModelSchema = () =>
   Schema.object({
@@ -32,11 +47,38 @@ export const Config = Schema.object({
   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().default(false).description('Register tower_control so the model may enter/leave the mode with a reason.'),
+    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.'),
@@ -68,26 +110,161 @@ export const Config = Schema.object({
     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')
 
 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))
 }
 
-export function resolveTowerConfig(rawConfig) {
-  const raw = rawConfig ?? {}
-  if (raw !== null && typeof raw !== 'object') throw new Error('Tower config must be an object')
+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 Error(
-      `Tower config has unknown key(s) ${unknown.join(', ')} — config is { section?, allowAgentControl?, mode?, review?, merge?, worktrees?, spawn? }`,
+    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)
@@ -95,20 +272,36 @@ export function resolveTowerConfig(rawConfig) {
     throw new Error(`Tower config is invalid: ${String(error?.message ?? error)}`)
   }
   const mode = clone(parsed.mode ?? {})
-  if (raw.section !== undefined) mode.promptSection = raw.section
-  if (raw.allowAgentControl !== undefined) mode.allowAgentControl = raw.allowAgentControl
+  // 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
 }
@@ -117,3 +310,76 @@ export function runtimeConfig() {
   if (!effective) effective = resolveTowerConfig({})
   return effective
 }
+
+export function repoConfigPath(commonDir) {
+  return path.join(commonDir, 'dsh-tower', 'config.json')
+}
+
+/**
+ * Read and validate <git-common-dir>/dsh-tower/config.json.
+ * Returns the raw (legacy-normalized) object plus its path; missing is not an error.
+ */
+export async function readRepoConfig(commonDir) {
+  const file = repoConfigPath(commonDir)
+  let stat
+  try {
+    stat = await fsp.stat(file)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { config: {}, path: file, present: false }
+    throw new TowerToolError('config-invalid', `repo config at ${file} could not be read: ${String(error?.message ?? error)}`)
+  }
+  if (stat.size > REPO_CONFIG_MAX_BYTES) {
+    throw new TowerToolError(
+      'config-invalid',
+      `repo config at ${file} is too large (${stat.size} bytes; limit ${REPO_CONFIG_MAX_BYTES})`,
+    )
+  }
+  let text
+  try {
+    text = await fsp.readFile(file, 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { config: {}, path: file, present: false }
+    throw new TowerToolError('config-invalid', `repo config at ${file} could not be read: ${String(error?.message ?? error)}`)
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw new TowerToolError('config-invalid', `repo config at ${file} is not valid JSON: ${String(error?.message ?? error)}`)
+  }
+  if (!isPlainObject(parsed)) {
+    throw new TowerToolError('config-invalid', `repo config at ${file} must be a JSON object`)
+  }
+  assertSafeKeys(parsed, `repo config at ${file}`)
+  assertKnownKeys(parsed, `repo config at ${file}`)
+  try {
+    // Validate value types without letting the schema's defaults win over the
+    // profile layer: merge into an empty raw object and discard the result.
+    Config(parsed)
+  } catch (error) {
+    throw new TowerToolError('config-invalid', `repo config at ${file} is invalid: ${String(error?.message ?? error)}`)
+  }
+  return { config: normalizeLegacy(parsed), path: file, present: true }
+}
+
+/**
+ * Effective config for one repository: profile config (already resolved with
+ * code defaults) overridden by the repository config file. Tool arguments are
+ * applied by the tool layer on top of this snapshot.
+ */
+export async function resolveRepoConfig(repo) {
+  const base = runtimeConfig()
+  const layer = await readRepoConfig(repo.commonDir)
+  const merged = deepMerge(base, layer.config)
+  if (!Array.isArray(merged.mode?.denyTools) || merged.mode.denyTools.length === 0) {
+    merged.mode = { ...(merged.mode ?? {}), denyTools: [...DEFAULT_DENY_TOOLS] }
+  }
+  merged.section = merged.mode?.promptSection ?? merged.section ?? ''
+  return {
+    ...merged,
+    configPath: layer.path,
+    repoConfigPresent: layer.present,
+    profileConfigured: Object.keys(profileRaw).length > 0,
+  }
+}
+

package/lib/doctor.js

@@ -0,0 +1,171 @@
+// Read-only environment contract and health checks for a Tower repository.
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import path from 'node:path'
+import fsp from 'node:fs/promises'
+import { git } from './git.js'
+import { inspectWorkspaceLock } from './workspaceLock.js'
+
+const execFileAsync = promisify(execFile)
+
+async function exists(target) {
+  try {
+    await fsp.stat(target)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function gitVersion() {
+  try {
+    const { stdout } = await execFileAsync('git', ['--version'], { windowsHide: true })
+    return String(stdout).trim()
+  } catch {
+    return null
+  }
+}
+
+function check(id, status, detail, action) {
+  return { id, status, detail, ...(action ? { action } : {}) }
+}
+
+/** Run every read-only diagnostic; never writes state or takes the state lock. */
+export async function runDoctor({ tower, ctx, agent }) {
+  const checks = []
+  const version = await gitVersion()
+  checks.push(version ? check('git', 'pass', version) : check('git', 'fail', 'git is not available', 'install Git and retry'))
+
+  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}`))
+  } catch (error) {
+    checks.push(check('state', 'fail', String(error?.message ?? error), 'run tower_init or restore the state file'))
+  }
+
+  const config = tower.config ?? {}
+  checks.push(
+    check(
+      'config',
+      config.configPath && config.repoConfigPresent ? 'pass' : 'warn',
+      config.repoConfigPresent ? `repo config ${config.configPath}` : `repo config not present (${config.configPath ?? 'unknown'})`,
+      'optional: add <git-common-dir>/dsh-tower/config.json',
+    ),
+  )
+  const presets = ctx.get?.('agentPresets')
+  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'),
+      )
+    } catch (error) {
+      checks.push(check('presets', 'warn', `preset registry unavailable: ${String(error?.message ?? error)}`))
+    }
+  } else {
+    checks.push(check('presets', 'warn', 'agentPresets service is unavailable'))
+  }
+
+  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')
+  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')
+    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'),
+    )
+    const lockDir = path.join(tower.commonDir, 'dsh-tower', 'tower.lock')
+    try {
+      const lock = await inspectWorkspaceLock(tower.commonDir, {
+        staleMs: Number(config.mode?.workspaceStaleMs) || 300000,
+      })
+      checks.push(lock.held ? check('workspace-lock', lock.stale ? 'warn' : 'pass', `held by ${lock.holder?.sessionId ?? 'unknown'}`) : check('workspace-lock', 'pass', 'free'))
+    } catch {
+      checks.push(check('workspace-lock', 'warn', `lock file ${lockDir} could not be inspected`))
+    }
+
+    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'))
+
+    let missingWorktrees = 0
+    let dirtyWorktrees = 0
+    let removedWorktrees = 0
+    for (const mission of state.missions ?? []) {
+      if (!mission.worktree) continue
+      if (mission.worktreeRemovedAt) {
+        removedWorktrees += 1
+        continue
+      }
+      try {
+        await tower.assertWorktree(mission.worktree)
+        if (await exists(mission.worktree.path)) {
+          const dirty = (await git(mission.worktree.path, ['status', '--porcelain'])).trim()
+          if (dirty) dirtyWorktrees += 1
+        } else {
+          missingWorktrees += 1
+        }
+      } catch {
+        missingWorktrees += 1
+      }
+    }
+    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')
+        : dirtyWorktrees > 0
+          ? check('worktrees', 'warn', `${dirtyWorktrees} worktree(s) have uncommitted changes${removedNote}`)
+          : check('worktrees', 'pass', `all registered worktrees are valid${removedNote}`),
+    )
+
+    const testConfigured = state.missions?.some((mission) => mission.testRuns !== undefined)
+    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' : ''}`,
+      ),
+    )
+    checks.push(check('legacy', 'pass', `${state.legacySnapshots?.length ?? 0} legacy snapshot(s)`))
+    checks.push(check('batches', 'pass', `${state.batches?.length ?? 0} batch(es)`))
+  }
+
+  try {
+    const { inspectLeases } = await import('./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) {
+    const corrupt = error?.code === 'state-corrupt'
+    checks.push(
+      check(
+        'leases',
+        corrupt ? 'fail' : 'warn',
+        corrupt ? `lease ledger is corrupt: ${String(error?.message ?? error)}` : 'lease module unavailable',
+        corrupt ? 'inspect <git-common-dir>/dsh-tower/leases.json and repair or remove it' : undefined,
+      ),
+    )
+  }
+
+  const failed = checks.filter((item) => item.status === 'fail').length
+  return {
+    ok: failed === 0,
+    checks,
+    environmentContract: {
+      platform: process.platform,
+      gitVersion: version,
+      repoRoot: tower.root,
+      commonDir: tower.commonDir,
+      stateDir: tower.paths.dir,
+    },
+    mode: agent ? 'ready' : 'unknown',
+  }
+}

package/lib/errors.js

@@ -0,0 +1,111 @@
+// Stable tool error codes.
+//
+// Everything a Tower tool throws reaches the model as
+//   [tower:<code>] <original message>
+// so callers (and tests) can branch on the code instead of matching prose.
+// The catalog is documented in docs/reference/errors.md; scripts/check-docs.mjs
+// keeps the two in sync.
+import { GitError } from './git.js'
+
+export const ERROR_CODES = {
+  'invalid-argument': 'A tool argument is missing, malformed, or not allowed.',
+  'repo-invalid': 'repoRoot is missing, relative, or not inside a Git repository.',
+  'not-initialized': 'Tower is not initialized for this repository; run tower_init.',
+  'mission-not-found': 'No mission with that id exists.',
+  'finding-not-found': 'No finding with that id exists.',
+  'invalid-transition': 'The requested state transition is not allowed.',
+  'state-locked': 'Another Tower writer holds the state lock.',
+  'state-corrupt': 'The Tower state file is unreadable or invalid.',
+  'config-invalid': 'Tower configuration is invalid.',
+  'config-unknown-key': 'Tower configuration has an unknown top-level key.',
+  'git-failed': 'A git command failed.',
+  'git-timeout': 'A git command timed out or exceeded its output buffer.',
+  'spawn-unavailable': 'The subagents service is unavailable.',
+  'provider-missing': 'No subagent provider is registered.',
+  'preset-missing': 'The configured agent preset is not registered.',
+  'reviewer-prerequisite': 'The reviewer spawn prerequisite is not met.',
+  'not-authorized': 'The calling agent role may not perform this action.',
+  'workspace-busy': 'Another Tower session owns this repository workspace lock.',
+  'worker-limit': 'The repository reached spawn.maxLiveWorkers live workers.',
+  'rate-limited': 'The tower_send per-minute rate limit was reached.',
+  'takeover-refused': 'The mission already has a live worker that was not stopped first.',
+  'reload-unavailable': 'The DSH HMR service is not available in this profile.',
+  'reload-failed': 'The HMR reload failed; check the DSH log and restart if needed.',
+  'tests-failed': 'Declared test discovery failed or did not meet its admission requirements.',
+  'tests-timeout': 'Test discovery exceeded its time or output budget.',
+  'lease-busy': 'Another holder owns the requested advisory lease.',
+  'lease-token': 'The lease release token does not match the current holder.',
+  'batch-invalid': 'The batch request or its close evidence is invalid.',
+  'legacy-invalid': 'The legacy snapshot or mapping is invalid.',
+  'tool-internal': 'An unexpected failure; read the message and the activity log.',
+}
+
+export class TowerToolError extends Error {
+  constructor(code, message, options = {}) {
+    super(`[tower:${code}] ${message}`, options.cause ? { cause: options.cause } : undefined)
+    this.name = 'TowerToolError'
+    this.code = code
+  }
+}
+
+// Ordered rules; the first match wins. Keep the specific patterns above the
+// generic argument fallback so `no open task matching` never becomes internal.
+const RULES = [
+  ['not-initialized', /tower is not initialized/i],
+  ['mission-not-found', /^unknown mission "/i],
+  ['finding-not-found', /^unknown finding "/i],
+  ['state-locked', /locked by another writer/i],
+  [
+    'state-corrupt',
+    /corrupt tower state|^tower state |^unsupported tower state|^invalid (?:mission|roster|message|finding|review) entry|^mission entry without id|^duplicate (?:mission|roster|message|finding|review)|^mission .* (?:has unknown status|has no tasks array|has no deps array)|^message .* has no readBy array|^finding .* has unknown status|^review .* has unknown (?:status|merge verdict)/i,
+  ],
+  ['config-unknown-key', /unknown key|unknown top-level key/i],
+  ['config-invalid', /config (?:is invalid|must be an object)|repo config/i],
+  ['lease-busy', /lease .* (?:held|owned)|another holder owns/i],
+  ['lease-token', /lease .*token|token does not match/i],
+  ['tests-timeout', /test discovery .*(?:timed out|exceeded|too large)/i],
+  ['tests-failed', /test discovery (?:failed|did not)|tests? (?:failed|missing|did not pass)/i],
+  ['batch-invalid', /batch (?:is invalid|close|member|receipt)/i],
+  ['legacy-invalid', /legacy (?:snapshot|map|source)|unsupported legacy/i],
+  ['spawn-unavailable', /subagents service is unavailable/i],
+  ['provider-missing', /no subagent provider/i],
+  ['preset-missing', /agent preset .*is not registered/i],
+  ['reviewer-prerequisite', /reviewer needs an existing|reviewer requires a completed/i],
+  ['repo-invalid', /repoRoot is required|repoRoot must be an absolute path/i],
+  ['workspace-busy', /workspace .*lock|another tower session owns/i],
+  ['worker-limit', /live worker limit|too many live workers|worker limit reached/i],
+  ['rate-limited', /rate limit|too many tower messages/i],
+  ['takeover-refused', /takeover refused|cannot take over/i],
+  ['not-authorized', /only the tower|only an assigned reviewer|only the tower or a worker|does not own mission|not authorized|may not perform this action/i],
+  [
+    'invalid-transition',
+    /cannot move from|cannot be completed from that state|is already completed|merged is recorded only|can only be widened|only a completed mission|reviewers may list and read|still has \d+ open task|has unresolved blockers|has no worktree|has no commits since|cannot complete with \d+ unread inbox|not assigned to mission|is a [a-z]+, not a worker|cannot reanchor base|worktree is missing|worktree .* is not a Git worktree|belongs to a different repository|is on .* expected|has \d+ live worker|already has a live worker|cannot reopen a terminal mission|stopped worker cannot report completion|can only be spawned|violates? (?:the )?mission (?:state|transition)/i,
+  ],
+  [
+    'invalid-argument',
+    /requires |is required|must be (?:a|an|one|an integer|non-empty|printable)|must not be|must be one of|no open task matching|unknown mission status|unknown finding severity|unknown finding type|not an array|is not an array|scope must|title must|checks must|role must|timeoutMs must|repoRoot is required|only a list filter|snapshotDirty was requested|refusing to send a message to yourself|mission has \d+ live worker|roster name already used|is already in the roster|depends on unknown mission/i,
+  ],
+]
+
+function originalMessage(error) {
+  return String(error?.message ?? error)
+}
+
+/** Wrap any thrown value into a TowerToolError with a stable code. */
+export function classifyError(error) {
+  if (error instanceof TowerToolError) return error
+  if (error && typeof error.code === 'string' && ERROR_CODES[error.code]) {
+    return new TowerToolError(error.code, originalMessage(error), { cause: error })
+  }
+  if (error instanceof GitError || error?.name === 'GitError') {
+    const message = originalMessage(error)
+    if (/not a git repository/i.test(message)) return new TowerToolError('repo-invalid', message, { cause: error })
+    const code = error?.timedOut === true || error?.bufferOverflow === true ? 'git-timeout' : 'git-failed'
+    return new TowerToolError(code, message, { cause: error })
+  }
+  const message = originalMessage(error)
+  for (const [code, pattern] of RULES) {
+    if (pattern.test(message)) return new TowerToolError(code, message, { cause: error })
+  }
+  return new TowerToolError('tool-internal', message, { cause: error })
+}