dsh-tower 2.0.4 → 2.1.0

package/lib/spawn-prechecks.js

@@ -0,0 +1,168 @@
+// tower_spawn prechecks (#56 P3c): roster naming, mission preconditions, and
+// service/provider/lease validation. Split out of tools/spawn.js; no I/O.
+import { TowerToolError } from '../domain/errors.js'
+import { ROSTER_INACTIVE_STATES } from '../domain/roster.js'
+import { inspectLeases } from './leases.js'
+
+/**
+ * Pick a unique roster name before any activation.
+ * @param {{ role: string, missionId: string | undefined, requested: string | undefined, roster: any[] }} input
+ */
+export function resolveRosterName({ role, missionId, requested, roster }) {
+  if (typeof requested === 'string' && requested.trim()) {
+    const name = requested.trim()
+    if (roster.some((entry) => entry.name === name)) {
+      throw new TowerToolError('invalid-argument', 'roster name already used: ' + name)
+    }
+    return name
+  }
+  const base = role + '-' + String(missionId).toLowerCase()
+  let candidate = base
+  let suffix = 2
+  while (roster.some((entry) => entry.name === candidate)) {
+    candidate = base + '-' + suffix
+    suffix += 1
+  }
+  return candidate
+}
+
+/**
+ * Role/mission preconditions checked before any provisioning.
+ * @param {{ role: string, context: any }} input
+ */
+export function assertSpawnableMission({ role, context }) {
+  if (role === 'reviewer') {
+    if (!context.mission.worktree) {
+      throw new TowerToolError('reviewer-prerequisite', 'reviewer needs an existing mission worktree; spawn a worker first')
+    }
+    if (context.mission.status !== 'completed') {
+      throw new TowerToolError('reviewer-prerequisite', `reviewer requires a completed mission; ${context.mission.id} is ${context.mission.status}`)
+    }
+  }
+  if (role === 'worker' && ['merged', 'abandoned'].includes(context.mission.status)) {
+    throw new TowerToolError(
+      'invalid-transition',
+      `mission ${context.mission.id} is ${context.mission.status}; a worker can only be spawned for a planned or active mission`,
+    )
+  }
+}
+
+/**
+ * Single-owner and live-worker rules, checked before provisioning or starting
+ * a child so a rejection cannot leak an activation or worktree.
+ * @param {{
+ *   role: string,
+ *   tower: any,
+ *   ctx: any,
+ *   view: any,
+ *   missionId: string | undefined,
+ *   takeover: boolean | undefined,
+ *   maxLiveWorkers: number | undefined,
+ *   budget: number,
+ *   observeActivity: any,
+ * }} input
+ */
+export async function precheckWorkerOwnership({
+  role,
+  tower,
+  ctx,
+  view,
+  missionId,
+  takeover,
+  maxLiveWorkers,
+  budget,
+  observeActivity,
+}) {
+  let effectiveTakeover = takeover === true
+  if (role !== 'worker') return effectiveTakeover
+  const liveWorkers = view.roster.filter(
+    (entry) => entry.role === 'worker' && !ROSTER_INACTIVE_STATES.includes(entry.state),
+  )
+  const sameMission = liveWorkers.filter((entry) => entry.missionId === missionId)
+  if (sameMission.length > 1) {
+    throw new TowerToolError(
+      'invalid-transition',
+      'mission ' + missionId + ' has ' + sameMission.length + ' live worker entries; inspect tower_roster before spawning',
+    )
+  }
+  if (sameMission.length === 1 && !effectiveTakeover) {
+    throw new TowerToolError(
+      'invalid-transition',
+      'mission ' + missionId + ' already has a live worker "' + sameMission[0].name + '"; stop it with tower_interrupt, or pass takeover:true after it is no longer running',
+    )
+  }
+  if (effectiveTakeover) {
+    if (sameMission.length === 1) {
+      const worker = sameMission[0]
+      const observed = await observeActivity(ctx, tower)
+      if (observed.parentStatus[worker.parentSessionId] !== 'ok') {
+        throw new TowerToolError(
+          'takeover-refused',
+          'cannot verify that worker ' + worker.name + ' stopped: its parent catalog is unavailable',
+        )
+      }
+      const activity = observed.activity[worker.agentId]
+      if (activity === 'running') {
+        throw new TowerToolError(
+          'takeover-refused',
+          'worker ' + worker.name + ' is still running; call tower_interrupt (or wait) before takeover',
+        )
+      }
+      if (activity === undefined) {
+        throw new TowerToolError(
+          'takeover-refused',
+          'worker ' + worker.name + ' is not in the live catalog; run tower_adopt before takeover',
+        )
+      }
+    } else {
+      effectiveTakeover = false
+    }
+  }
+  const replacing = effectiveTakeover ? sameMission : []
+  const remaining = liveWorkers.filter((entry) => !replacing.includes(entry))
+  const max = Math.min(Number(maxLiveWorkers) || 4, budget)
+  if (remaining.length >= max) {
+    throw new TowerToolError(
+      'worker-limit',
+      'live worker limit reached (' + max + '); stop a worker with tower_interrupt or raise spawn.maxLiveWorkers',
+    )
+  }
+  return effectiveTakeover
+}
+
+/**
+ * Service/provider/preset/lease checks, run before provisioning.
+ * @param {{ tower: any, ctx: any, config: any, preset: string, actor: any, exec: any }} input
+ */
+export async function precheckSpawnServices({ tower, ctx, config, preset, actor, exec }) {
+  const subagents = ctx.get('subagents')
+  if (!subagents) throw new TowerToolError('spawn-unavailable', 'subagents service is unavailable; cannot spawn')
+  const providers = subagents.list()
+  const provider = config.spawn.provider || (providers.includes('spawn') ? 'spawn' : providers[0])
+  if (!provider) throw new TowerToolError('provider-missing', 'no subagent provider is registered')
+  const presets = ctx.get('agentPresets')
+  if (presets && typeof presets.list === 'function') {
+    const available = await presets.list()
+    if (!available.some((entry) => String(entry.id) === preset)) {
+      throw new TowerToolError('preset-missing', 'agent preset "' + preset + '" is not registered; check the Tower bundle preset rows and restart DSH')
+    }
+  }
+  if (typeof config.spawn.requireLease === 'string' && config.spawn.requireLease.trim()) {
+    const requiredLease = config.spawn.requireLease.trim()
+    const info = await inspectLeases(tower.commonDir)
+    const lease = info.leases.find((entry) => entry.name === requiredLease && entry.expired !== true)
+    if (!lease) {
+      throw new TowerToolError(
+        'lease-busy',
+        `spawn.requireLease="${requiredLease}" is not held; acquire it with tower_resource before spawning`,
+      )
+    }
+    if (lease.holder !== actor.name && lease.holder !== String(exec.agent.id)) {
+      throw new TowerToolError(
+        'lease-busy',
+        `spawn.requireLease="${requiredLease}" is held by "${lease.holder}", not by this tower`,
+      )
+    }
+  }
+  return { subagents, provider }
+}

package/lib/spawn-support.js

@@ -0,0 +1,79 @@
+// tower_spawn support (#56 P3c): briefing assembly, agent options, and the
+// wait/result settling path. Split out of tools/spawn.js; no I/O of its own.
+import { workerBriefing, reviewerBriefing } from './briefing.js'
+
+/**
+ * @param {any} model
+ */
+export function buildAgentOptions(model) {
+  const agentOptions = {}
+  for (const key of ['provider', 'model', 'reasoningEffort', 'maxTokens']) {
+    if (model && model[key] !== undefined && model[key] !== null && model[key] !== '') agentOptions[key] = model[key]
+  }
+  return agentOptions
+}
+
+/**
+ * @param {{ role: string, towerRoot: string, context: any, worktree: any, instructions: string | undefined }} input
+ */
+export function buildSpawnBriefing({ role, towerRoot, context, worktree, instructions }) {
+  const mission = {
+    ...context.mission,
+    worktree: { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit },
+  }
+  const briefing = {
+    repoRoot: towerRoot,
+    base: context.base,
+    mission,
+    deps: context.deps,
+    worktree,
+    instructions,
+    reviews: context.reviews,
+    findings: context.findings,
+    completionReport: context.completionReport,
+  }
+  return role === 'worker' ? workerBriefing(briefing) : reviewerBriefing(briefing)
+}
+
+/**
+ * Wait for the activation result when wait=true, or forward the eventual
+ * outcome when wait=false.
+ * @param {{
+ *   activation: any,
+ *   report: any,
+ *   recordOutcome: (state: string, detail: any) => Promise<any>,
+ *   maxWaitMs: number | undefined,
+ *   requestedWaitMs: number | undefined,
+ *   textOf: any,
+ * }} input
+ */
+export async function waitForSpawnResult({ activation, report, recordOutcome, maxWaitMs, requestedWaitMs, textOf }) {
+  const waitMs = Math.max(1000, Math.min(maxWaitMs ?? 90000, requestedWaitMs ?? 180000))
+  let timer
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve({ __timeout: true }), waitMs)
+  })
+  let result
+  try {
+    result = await Promise.race([activation.result, timeout])
+  } catch (error) {
+    report.stopReason = 'failed'
+    report.diagnostic = String(error?.message ?? error)
+    await recordOutcome('failed', report.diagnostic)
+    throw error
+  } finally {
+    clearTimeout(timer)
+  }
+  if (result && result.__timeout) {
+    report.timedOut = true
+    recordOutcome('unknown', 'spawn wait timed out; check tower_roster')
+  } else {
+    report.stopReason = result?.stopReason ?? null
+    report.output = textOf(result?.output)
+    report.diagnostic = result?.diagnostic ?? null
+    const state = report.stopReason === 'completed' ? 'inactive' : 'failed'
+    if (state === 'failed') report.diagnostic = report.diagnostic ?? report.stopReason
+    await recordOutcome(state, report.diagnostic ?? null)
+  }
+  return report
+}

package/lib/stateFile.js

@@ -0,0 +1,99 @@
+// State-file load path: schema-version inspection, migration, and the one
+// persisted migration result (#72).
+//
+// The domain stays pure: `prepareState` classifies, transforms and validates the
+// document. This module owns the disk effects, and it persists them only while
+// the caller holds the state lock, so a reader can never rewrite a document a
+// concurrent writer is about to change. A read-only load still migrates in
+// memory; the next locked write persists that migration once.
+//
+// Ordering mirrors the protocol contract:
+//   1. classify the version (a newer document is refused before any write);
+//   2. write the pre-migration backup;
+//   3. migrate in memory and validate the target schema;
+//   4. atomically replace state.json, bump `revision` once, append
+//      `state.migrated {from,to}` to the activity log.
+// A migration that throws therefore leaves state.json byte-identical.
+import { inspectStateVersion, prepareState } from '../domain/state.js'
+import { isStateLockHeld } from './store.js'
+
+/**
+ * @typedef {object} StateLoadResult
+ * @property {import('../types/index.js').TowerState} state
+ * @property {ReturnType<typeof inspectStateVersion>} version
+ * @property {null | {
+ *   from: number, to: number, steps: Array<{ from: number, to: number }>,
+ *   persisted: boolean, backupPath: string|null,
+ * }} migration
+ */
+
+/**
+ * Read `paths.state`, migrate it when it is older than this build, and (only
+ * while the state lock is held) persist that migration.
+ *
+ * @param {{
+ *   store: any,
+ *   paths: any,
+ *   now?: number,
+ *   persist?: boolean,
+ *   migrations?: readonly import('../domain/state/migrations.js').StateMigration[],
+ * }} input
+ * @returns {Promise<StateLoadResult>}
+ */
+export async function loadStateFile(input) {
+  const { store, paths, migrations } = input
+  const now = input.now ?? Date.now()
+  const raw = await store.readJson(paths.state)
+  const version = inspectStateVersion(raw, paths.state, migrations)
+  const persist = input.persist ?? isStateLockHeld(paths)
+  const backupPath = `${paths.state}.v${String(version.currentVersion ?? 'unknown')}.bak`
+
+  // Backup before the original can change. `prepareState` is pure, so a
+  // throwing migration cannot touch state.json whether or not this ran.
+  if (persist && version.status === 'migratable') {
+    await store.writeJsonAtomic(backupPath, raw)
+  }
+
+  const prepared = prepareState(raw, paths.state, { migrations })
+  if (!prepared.changed) {
+    return { state: prepared.state, version, migration: null }
+  }
+
+  if (!persist) {
+    return {
+      state: prepared.state,
+      version,
+      migration: {
+        from: prepared.from,
+        to: prepared.to,
+        steps: prepared.migrated,
+        persisted: false,
+        backupPath: null,
+      },
+    }
+  }
+
+  const baseRevision =
+    Number.isInteger(prepared.state.revision) && prepared.state.revision >= 0 ? prepared.state.revision : 0
+  const migrated = { ...prepared.state, revision: baseRevision + 1, updatedAt: now }
+  await store.writeJsonAtomic(paths.state, migrated)
+  await store.appendJsonl(paths.activity, {
+    at: now,
+    type: 'state.migrated',
+    from: prepared.from,
+    to: prepared.to,
+    revision: migrated.revision,
+    text: `schema v${prepared.from} -> v${prepared.to}`,
+  })
+  return {
+    state: migrated,
+    version,
+    migration: {
+      from: prepared.from,
+      to: prepared.to,
+      steps: prepared.migrated,
+      persisted: true,
+      backupPath,
+    },
+  }
+}

package/lib/store.js

@@ -1,14 +1,31 @@
+import { TowerToolError } from '../domain/errors.js'
 // Durable repo-scoped store: exclusive lock + atomic JSON + append-only activity.
-import fsp from 'node:fs/promises'
+// The atomic/lock/JSON primitives are shared with the mode store (#56 P2b).
+import { fsp } from '../adapters/store-fs.js'
+import {
+  PROCESS_STARTED_AT,
+  acquireLock,
+  lockRecord,
+  readLock,
+} from './persistence.js'
 import path from 'node:path'
 import crypto from 'node:crypto'
 
+export {
+  readJson,
+  writeJsonAtomic,
+  writeJsonAtomicSync,
+  renameWithRetry,
+  appendJsonl,
+} from './persistence.js'
+
 export function pathsFor(commonDir) {
   const dir = path.join(commonDir, 'dsh-tower')
   return {
     dir,
     state: path.join(dir, 'state.json'),
     lock: path.join(dir, 'state.lock'),
+    gitLock: path.join(dir, 'git.lock'),
     activity: path.join(dir, 'activity.jsonl'),
   }
 }
@@ -26,55 +43,6 @@ export async function ensureDir(dir) {
   await fsp.mkdir(dir, { recursive: true })
 }
 
-export async function readJson(file) {
-  const text = await fsp.readFile(file, 'utf8')
-  try {
-    return JSON.parse(text)
-  } catch (error) {
-    throw new Error(`corrupt tower state at ${file}: ${error.message}`)
-  }
-}
-
-export async function writeJsonAtomic(file, value) {
-  const dir = path.dirname(file)
-  const tmp = path.join(dir, `.${path.basename(file)}.tmp-${process.pid}-${crypto.randomUUID()}`)
-  const handle = await fsp.open(tmp, 'w')
-  try {
-    await handle.writeFile(JSON.stringify(value, null, 2), 'utf8')
-    await handle.sync()
-  } finally {
-    await handle.close()
-  }
-  await renameWithRetry(tmp, file)
-}
-
-/**
- * Windows can reject a rename while an indexer, antivirus, or a concurrent
- * reader still holds the destination; retry briefly instead of failing a
- * successful mutation. The temp file is removed when the rename never lands.
- */
-async function renameWithRetry(tmp, file) {
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      await fsp.rename(tmp, file)
-      return
-    } catch (error) {
-      const transient = error?.code === 'EPERM' || error?.code === 'EBUSY' || error?.code === 'EACCES'
-      if (!transient || attempt >= 12) {
-        await fsp.unlink(tmp).catch(() => {})
-        throw error
-      }
-      await sleep(10 + attempt * 15)
-    }
-  }
-}
-
-export { renameWithRetry }
-
-export async function appendJsonl(file, value) {
-  await fsp.appendFile(file, `${JSON.stringify(value)}\n`, 'utf8')
-}
-
 export function shortHash(text) {
   return crypto.createHash('sha256').update(String(text)).digest('hex').slice(0, 12)
 }
@@ -94,66 +62,21 @@ export async function readActivityTail(file, limit = 12) {
   return out
 }
 
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
-const PROCESS_STARTED_AT = Date.now() - Math.round(process.uptime() * 1000)
-
-function processAlive(pid) {
-  if (!Number.isInteger(Number(pid)) || Number(pid) <= 0) return null
-  try {
-    process.kill(Number(pid), 0)
-    return true
-  } catch (error) {
-    if (error?.code === 'ESRCH') return false
-    // EPERM means the process exists but belongs to another user.
-    return true
-  }
-}
-
-/** Read the current lock record without acquiring the lock. */
 export async function readStateLock(paths) {
-  try {
-    const text = await fsp.readFile(paths.lock, 'utf8')
-    const record = JSON.parse(text)
-    const alive = processAlive(record?.pid)
-    return { path: paths.lock, record, alive, raw: text }
-  } catch (error) {
-    if (error?.code === 'ENOENT') return { path: paths.lock, record: null, alive: null, raw: null }
-    return { path: paths.lock, record: null, alive: null, raw: null, error: String(error?.message ?? error) }
-  }
+  return readLock(paths.lock)
 }
 
-async function reclaimDeadLock(paths) {
-  let original
-  try {
-    original = await fsp.readFile(paths.lock, 'utf8')
-  } catch {
-    return false
-  }
-  let parsed
-  try {
-    parsed = JSON.parse(original)
-  } catch {
-    return false
-  }
-  if (processAlive(parsed?.pid) !== false) return false
-  const quarantine = `${paths.lock}.stale-${process.pid}-${crypto.randomUUID()}`
-  try {
-    await fsp.rename(paths.lock, quarantine)
-  } catch {
-    return false
-  }
-  const moved = await fsp.readFile(quarantine, 'utf8').catch(() => null)
-  if (moved === null || moved !== original) {
-    // A concurrent writer replaced the lock between read and rename. Put the
-    // newer record back rather than deleting it.
-    if (moved !== null) await fsp.rename(quarantine, paths.lock).catch(() => {})
-    return false
-  }
-  await fsp.unlink(quarantine).catch(() => {})
-  return true
+/**
+ * Paths objects whose state lock this process currently holds. A state
+ * migration may be persisted only inside `withLock`: the loader reads this to
+ * tell a locked mutation (which may write) from a read-only load (which must
+ * migrate in memory and leave the file alone).
+ */
+const HELD_STATE_LOCKS = new WeakSet()
+
+/** @param {object} [paths] @returns {boolean} */
+export function isStateLockHeld(paths) {
+  return Boolean(paths) && HELD_STATE_LOCKS.has(paths)
 }
 
 /**
@@ -164,38 +87,47 @@ export async function withLock(paths, fn, options = {}) {
   const timeoutMs = options.timeoutMs ?? 5000
   const pollMs = options.pollMs ?? 25
   const token = crypto.randomUUID()
-  const record = JSON.stringify({ token, pid: process.pid, startedAt: PROCESS_STARTED_AT, at: Date.now() })
-  const deadline = Date.now() + timeoutMs
-
-  for (;;) {
-    try {
-      await fsp.writeFile(paths.lock, record, { flag: 'wx' })
-      break
-    } catch (error) {
-      if (error.code !== 'EEXIST') throw error
-      if (await reclaimDeadLock(paths)) continue
-      if (Date.now() > deadline) {
-        const owner = await readStateLock(paths)
-        const payload = owner.raw ?? (owner.record ? JSON.stringify(owner.record) : null)
-        throw new Error(
-          `tower state is locked by another writer${payload ? ` (${payload})` : ''}; retry after it finishes`,
-        )
-      }
-      await sleep(pollMs)
-    }
+  const record = lockRecord(token, { startedAt: PROCESS_STARTED_AT })
+  const held = await acquireLock(paths.lock, { token, record, timeoutMs, pollMs })
+  if (!held) {
+    const owner = await readStateLock(paths)
+    const ownerRecord = owner.record
+    const payload = owner.raw ?? (ownerRecord ? JSON.stringify(ownerRecord) : null)
+    throw new TowerToolError(
+      'state-locked',
+      `tower state is locked by another writer${payload ? ` (${payload})` : ''}; retry after it finishes`,
+    )
+  }
+  const startedAt = Date.now()
+  HELD_STATE_LOCKS.add(paths)
+  try {
+    return await fn(paths)
+  } finally {
+    HELD_STATE_LOCKS.delete(paths)
+    await held.release()
+    await fsp
+      .appendFile(path.join(paths.dir, 'lock-holds.jsonl'), `${JSON.stringify({ at: Date.now(), ms: Date.now() - startedAt, pid: process.pid })}\n`, 'utf8')
+      .catch(() => {})
   }
+}
 
+/** Serialize git mutations without holding the state lock. */
+export async function withGitLock(paths, fn, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 60000
+  const pollMs = options.pollMs ?? 25
+  const lock = paths.gitLock
+  const token = crypto.randomUUID()
+  const startedAt = Date.now()
+  const held = await acquireLock(lock, { token, record: lockRecord(token, { kind: 'git' }), timeoutMs, pollMs })
+  if (!held) {
+    throw new TowerToolError('state-locked', 'another git mutation is in progress for this repository; retry after it finishes')
+  }
   try {
     return await fn(paths)
   } finally {
-    try {
-      const current = await fsp.readFile(paths.lock, 'utf8').catch(() => null)
-      if (current) {
-        const parsed = JSON.parse(current)
-        if (parsed && parsed.token === token) await fsp.unlink(paths.lock)
-      }
-    } catch {
-      // a lock left behind by a crash is reported by the next writer, not fixed here
-    }
+    await held.release()
+    await fsp
+      .appendFile(path.join(paths.dir, 'lock-holds.jsonl'), `${JSON.stringify({ at: Date.now(), ms: Date.now() - startedAt, pid: process.pid, phase: 'git' })}\n`, 'utf8')
+      .catch(() => {})
   }
 }

package/lib/tests.js

@@ -1,3 +1,4 @@
+import { TowerToolError } from '../domain/errors.js'
 // Tower test discovery (2.1): fail-closed admission evidence from the
 // repository's own `package.json` `tower.testDiscovery` block.
 //
@@ -18,10 +19,10 @@
 //   minCount/required shortfall) returns `ok: false` in the receipt;
 // - an invalid discovery configuration (or invalid call arguments) throws a
 //   plain `Error`, which the tool layer wraps as `tower:invalid-argument`.
-import { spawn } from 'node:child_process'
-import { createWriteStream } from 'node:fs'
+import { spawn } from '../adapters/vcs-git.js'
+import { createWriteStream } from '../adapters/store-fs.js'
 import crypto from 'node:crypto'
-import fsp from 'node:fs/promises'
+import { fsp } from '../adapters/store-fs.js'
 import path from 'node:path'
 
 import { tryGit } from './git.js'
@@ -45,7 +46,7 @@ function nonEmptyString(value) {
 }
 
 function normalizePositiveInteger(value, name) {
-  if (!Number.isInteger(value) || value <= 0) throw new Error(`${name} must be an integer > 0`)
+  if (!Number.isInteger(value) || value <= 0) throw new TowerToolError('invalid-argument', `${name} must be an integer > 0`)
   return value
 }
 
@@ -287,8 +288,12 @@ export function testProcessEnv(source = process.env) {
   return env
 }
 
-/** Platform shell for discovery commands (PowerShell 7 on Windows, bash on POSIX). */
-function shellSpec(platform = process.platform) {
+/**
+ * Platform shell for discovery commands (PowerShell 7 on Windows with a
+ * `powershell` fallback, bash on POSIX). Exported so both branches are asserted
+ * on every OS instead of only on the platform that happens to run CI (#86).
+ */
+export function shellSpec(platform = process.platform) {
   if (platform === 'win32') {
     const args = (command) => ['-NoProfile', '-NonInteractive', '-Command', command]
     return {
@@ -480,7 +485,7 @@ async function resolveDiagnosticsDir({ worktreePath, diagnosticsDir, missionId }
 
 function normalizeDiscoveryInput(config) {
   if (isPlainObject(config) && Object.prototype.hasOwnProperty.call(config, 'configured')) {
-    if (config.error) throw new Error(`test discovery configuration is invalid: ${config.error}`)
+    if (config.error) throw new TowerToolError('invalid-argument', `test discovery configuration is invalid: ${config.error}`)
     if (config.configured === false) return { configured: false, config: null, error: null }
     return { configured: true, config: config.config, error: null }
   }
@@ -527,16 +532,16 @@ export async function runDiscovery(options = {}) {
   } = options
   const startedAt = new Date().toISOString()
 
-  if (!nonEmptyString(worktreePath)) throw new Error('worktreePath is required')
-  if (!path.isAbsolute(worktreePath)) throw new Error(`worktreePath must be an absolute path: ${worktreePath}`)
+  if (!nonEmptyString(worktreePath)) throw new TowerToolError('invalid-argument', 'worktreePath is required')
+  if (!path.isAbsolute(worktreePath)) throw new TowerToolError('invalid-argument', `worktreePath must be an absolute path: ${worktreePath}`)
   const effectiveTimeout = normalizePositiveInteger(timeoutMs, 'timeoutMs')
   const effectiveMaxBytes = normalizePositiveInteger(maxBytes, 'maxBytes')
   if (runner !== undefined && runner !== null && typeof runner !== 'function') {
-    throw new Error('runner must be a function')
+    throw new TowerToolError('invalid-argument', 'runner must be a function')
   }
   if (diagnosticsDir !== undefined && diagnosticsDir !== null) {
     if (!nonEmptyString(diagnosticsDir) || !path.isAbsolute(diagnosticsDir)) {
-      throw new Error(`diagnosticsDir must be an absolute path: ${diagnosticsDir}`)
+      throw new TowerToolError('invalid-argument', `diagnosticsDir must be an absolute path: ${diagnosticsDir}`)
     }
   }
 
@@ -558,7 +563,7 @@ export async function runDiscovery(options = {}) {
 
   if (!discovery.configured) return finishUnconfigured(discovery.error)
   const normalized = normalizeDiscovery(discovery.config)
-  if (!normalized.ok) throw new Error(`invalid tower.testDiscovery config: ${normalized.error}`)
+  if (!normalized.ok) throw new TowerToolError('invalid-argument', `invalid tower.testDiscovery config: ${normalized.error}`)
 
   const dir = await resolveDiagnosticsDir({ worktreePath, diagnosticsDir, missionId })
   const commands = []