dsh-tower 2.0.3 → 2.1.0-beta.1

package/lib/persistence.js

@@ -0,0 +1,349 @@
+// Shared durable-persistence contract (#56 P2b).
+//
+// state.json (lib/store.js) and modes.json (lib/modeStore.js) both persist a
+// whole JSON document behind a token-owned writer lock. They must agree on:
+//
+//   - atomic replacement: serialise completely, write a temp file, rename;
+//   - dead-PID reclamation: a provably dead owner is moved to a quarantine
+//     name, verified, and only then removed; a live/foreign lock is never
+//     stolen or deleted;
+//   - bounded waiting: a held lock is reported after a timeout, not stolen.
+//
+// Keeping the primitives here means a protocol fix applies to both contracts
+// at once. This module is the only lib/ file besides store.js that talks to
+// the fs adapter; it never imports node:fs directly (#50).
+import { fs, fsp } from '../adapters/store-fs.js'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { TowerToolError } from '../domain/errors.js'
+
+export const DEFAULT_LOCK_TIMEOUT_MS = 5000
+export const DEFAULT_LOCK_POLL_MS = 25
+
+const RENAME_ATTEMPTS = 12
+const TRANSIENT_RENAME_ERRORS = new Set(['EPERM', 'EBUSY', 'EACCES'])
+const PROCESS_STARTED_AT = Date.now() - Math.round(process.uptime() * 1000)
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+  } catch {
+    // best effort; a busy loop would be worse
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON document I/O
+// ---------------------------------------------------------------------------
+
+function parseJson(file, text) {
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new TowerToolError('state-corrupt', `corrupt tower state at ${file}: ${error.message}`)
+  }
+}
+
+export async function readJson(file) {
+  return parseJson(file, await fsp.readFile(file, 'utf8'))
+}
+
+/** Synchronous counterpart for the mode store's short critical section. */
+export function readJsonSync(file) {
+  return parseJson(file, fs.readFileSync(file, 'utf8'))
+}
+
+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.
+ */
+export async function renameWithRetry(tmp, file) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await fsp.rename(tmp, file)
+      return
+    } catch (error) {
+      if (!TRANSIENT_RENAME_ERRORS.has(error?.code) || attempt >= RENAME_ATTEMPTS) {
+        await fsp.unlink(tmp).catch(() => {})
+        throw error
+      }
+      await sleep(10 + attempt * 15)
+    }
+  }
+}
+
+/** Synchronous counterpart used by the mode store's short critical section. */
+export function writeJsonAtomicSync(file, value) {
+  const dir = path.dirname(file)
+  const tmp = path.join(dir, `.${path.basename(file)}.tmp-${process.pid}-${crypto.randomUUID()}`)
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2), 'utf8')
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      fs.renameSync(tmp, file)
+      return
+    } catch (error) {
+      if (!TRANSIENT_RENAME_ERRORS.has(error?.code) || attempt >= RENAME_ATTEMPTS) {
+        try {
+          fs.unlinkSync(tmp)
+        } catch {
+          // best effort
+        }
+        throw error
+      }
+      sleepSync(10 + attempt * 15)
+    }
+  }
+}
+
+export async function appendJsonl(file, value) {
+  await fsp.appendFile(file, `${JSON.stringify(value)}\n`, 'utf8')
+}
+
+// ---------------------------------------------------------------------------
+// Lock records
+// ---------------------------------------------------------------------------
+
+/**
+ * true = process exists, false = provably gone, null = the record carries no
+ * usable PID. The tri-state matters: a malformed state lock must be reported,
+ * not silently reclaimed as if its owner were dead.
+ */
+export function processAlive(pid) {
+  const value = Number(pid)
+  if (!Number.isInteger(value) || value <= 0) return null
+  try {
+    process.kill(value, 0)
+    return true
+  } catch (error) {
+    if (error?.code === 'ESRCH') return false
+    // EPERM means the process exists but belongs to another user.
+    return true
+  }
+}
+
+export function lockRecord(token, extra = {}) {
+  return { token, pid: process.pid, ...extra, at: Date.now() }
+}
+
+function isDeadLock(record, options) {
+  const alive = processAlive(record?.pid)
+  if (alive === false) return true
+  // The mode store historically treated a lock without a usable PID as dead;
+  // preserve that where callers opt in, while the state lock stays defensive.
+  return alive === null && options.invalidPidIsDead === true
+}
+
+// ---------------------------------------------------------------------------
+// Lock inspection / reclamation
+// ---------------------------------------------------------------------------
+
+export async function readLock(lockPath) {
+  try {
+    const raw = await fsp.readFile(lockPath, 'utf8')
+    const record = JSON.parse(raw)
+    return { path: lockPath, record, alive: processAlive(record?.pid), raw }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { path: lockPath, record: null, alive: null, raw: null }
+    return { path: lockPath, record: null, alive: null, raw: null, error: String(error?.message ?? error) }
+  }
+}
+
+export function readLockSync(lockPath) {
+  try {
+    const raw = fs.readFileSync(lockPath, 'utf8')
+    const record = JSON.parse(raw)
+    return { path: lockPath, record, alive: processAlive(record?.pid), raw }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { path: lockPath, record: null, alive: null, raw: null }
+    return { path: lockPath, record: null, alive: null, raw: null, error: String(error?.message ?? error) }
+  }
+}
+
+export async function reclaimDeadLock(lockPath, options = {}) {
+  let original
+  try {
+    original = await fsp.readFile(lockPath, 'utf8')
+  } catch {
+    return false
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(original)
+  } catch {
+    return false
+  }
+  if (!isDeadLock(parsed, options)) return false
+  // Move, never delete: a concurrent writer may have replaced the record
+  // between the read and the rename, so verify the quarantined bytes first.
+  const quarantine = `${lockPath}.stale-${process.pid}-${crypto.randomUUID()}`
+  try {
+    await fsp.rename(lockPath, quarantine)
+  } catch {
+    return false
+  }
+  const moved = await fsp.readFile(quarantine, 'utf8').catch(() => null)
+  if (moved === null || moved !== original) {
+    if (moved !== null) await fsp.rename(quarantine, lockPath).catch(() => {})
+    return false
+  }
+  await fsp.unlink(quarantine).catch(() => {})
+  return true
+}
+
+export function reclaimDeadLockSync(lockPath, options = {}) {
+  let original
+  try {
+    original = fs.readFileSync(lockPath, 'utf8')
+  } catch {
+    return false
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(original)
+  } catch {
+    return false
+  }
+  if (!isDeadLock(parsed, options)) return false
+  const quarantine = `${lockPath}.stale-${process.pid}-${crypto.randomUUID()}`
+  try {
+    fs.renameSync(lockPath, quarantine)
+  } catch {
+    return false
+  }
+  let moved = null
+  try {
+    moved = fs.readFileSync(quarantine, 'utf8')
+  } catch {
+    moved = null
+  }
+  if (moved === null || moved !== original) {
+    if (moved !== null) {
+      try {
+        fs.renameSync(quarantine, lockPath)
+      } catch {
+        // the newer record could not be restored; never delete it silently
+      }
+    }
+    return false
+  }
+  try {
+    fs.unlinkSync(quarantine)
+  } catch {
+    // the lock is already reclaimed; a leftover quarantine is inert
+  }
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// Lock acquire / token-checked release
+// ---------------------------------------------------------------------------
+
+function handleFor(lockPath, token, record) {
+  return {
+    path: lockPath,
+    token,
+    record,
+    async release() {
+      return releaseLock(lockPath, token)
+    },
+  }
+}
+
+function syncHandleFor(lockPath, token, record) {
+  return {
+    path: lockPath,
+    token,
+    record,
+    release() {
+      return releaseLockSync(lockPath, token)
+    },
+  }
+}
+
+/**
+ * Acquire a token-owned lock with a bounded wait. Returns null when another
+ * writer still holds a live lock at the deadline; callers translate that into
+ * their own [tower:state-locked] message (or a false return for modes).
+ */
+export async function acquireLock(lockPath, options = {}) {
+  const token = options.token ?? crypto.randomUUID()
+  const record = options.record ?? lockRecord(token)
+  const timeoutMs = Number(options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS)
+  const pollMs = Number(options.pollMs ?? DEFAULT_LOCK_POLL_MS)
+  const deadline = Date.now() + Math.max(0, timeoutMs)
+  for (;;) {
+    try {
+      await fsp.writeFile(lockPath, JSON.stringify(record), { flag: 'wx' })
+      return handleFor(lockPath, token, record)
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      if (await reclaimDeadLock(lockPath, options)) continue
+      if (Date.now() > deadline) return null
+      await sleep(pollMs)
+    }
+  }
+}
+
+export function acquireLockSync(lockPath, options = {}) {
+  const token = options.token ?? crypto.randomUUID()
+  const record = options.record ?? lockRecord(token)
+  const timeoutMs = Number(options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS)
+  const pollMs = Number(options.pollMs ?? DEFAULT_LOCK_POLL_MS)
+  const deadline = Date.now() + Math.max(0, timeoutMs)
+  for (;;) {
+    try {
+      fs.writeFileSync(lockPath, JSON.stringify(record), { flag: 'wx' })
+      return syncHandleFor(lockPath, token, record)
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      if (reclaimDeadLockSync(lockPath, options)) continue
+      if (Date.now() > deadline) return null
+      sleepSync(pollMs)
+    }
+  }
+}
+
+export async function releaseLock(lockPath, token) {
+  try {
+    const current = await fsp.readFile(lockPath, 'utf8').catch(() => null)
+    if (current === null) return false
+    const parsed = JSON.parse(current)
+    if (!parsed || parsed.token !== token) return false
+    await fsp.unlink(lockPath)
+    return true
+  } catch {
+    // a foreign or unreadable lock is not ours to remove
+    return false
+  }
+}
+
+export function releaseLockSync(lockPath, token) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf8'))
+    if (!parsed || parsed.token !== token) return false
+    fs.unlinkSync(lockPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export { PROCESS_STARTED_AT }

package/lib/presets.js

@@ -0,0 +1,35 @@
+// Cross-field preset validation (#64): fail before work starts, not at spawn.
+import { TowerToolError } from '../domain/errors.js'
+
+export function presetIds(config = {}) {
+  return {
+    worker: String(config.spawn?.workerPreset ?? 'tower-worker'),
+    reviewer: String(config.spawn?.reviewerPreset ?? 'tower-reviewer'),
+  }
+}
+
+function rowId(preset) {
+  return preset === 'tower-worker' ? 'preset-tower-worker' : preset === 'tower-reviewer' ? 'preset-tower-reviewer' : preset
+}
+
+/**
+ * Resolve both presets against the profile's agentPresets service. Fail closed
+ * with preset-missing before mode entry/planning when a required preset is not
+ * registered. If the service is unavailable, doctor reports that separately and
+ * this check cannot make a claim either way.
+ */
+export async function assertPresetsAvailable(ctx, config = {}) {
+  const service = ctx?.get?.('agentPresets')
+  if (!service || typeof service.list !== 'function') return { checked: false, missing: [] }
+  const presets = presetIds(config)
+  const available = new Set((await service.list()).map((entry) => String(entry.id)))
+  const missing = [presets.worker, presets.reviewer].filter((id) => !available.has(id))
+  if (missing.length > 0) {
+    const rows = [...new Set(missing.map(rowId))]
+    throw new TowerToolError(
+      'preset-missing',
+      `required Tower agent preset(s) missing: ${missing.join(', ')}; re-enable ${rows.join(', ')} in the plugin page, then restart DSH`,
+    )
+  }
+  return { checked: true, missing: [] }
+}

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