dsh-tower 2.1.0 → 2.4.0

package/domain/config/schema.js

@@ -2,7 +2,7 @@
 //
 // This module is pure: it declares the Schemastery schema, validates raw config
 // objects, and materializes defaults. Profile and repository loading (fs and the
-// process-local profile snapshot) live in lib/config.js, which re-exports
+// process-local profile snapshot) live in host/config.js, which re-exports
 // `Config` and `resolveTowerConfig` for compatibility.
 //
 // Layers, lowest precedence first:
@@ -33,7 +33,10 @@ export const DEFAULT_DENY_TOOLS = [
 ]
 
 const LEGACY_KEYS = ['section', 'allowAgentControl']
-const GROUP_KEYS = ['init', 'mode', 'review', 'merge', 'git', 'worktrees', 'spawn', 'send', 'tests', 'gates', 'docs', 'archive', 'leases', 'dev', 'tools']
+// #121: the `tools` group is gone. Every capability that used to be a
+// `tools.expose*` boolean is now a component row in `cordis.patch.yml`, and a
+// component row is the switch. What remains here is genuine tuning policy.
+const GROUP_KEYS = ['init', 'mode', 'review', 'merge', 'git', 'worktrees', 'spawn', 'send', 'tests', 'gates', 'docs', 'archive', 'leases', 'dev']
 
 const SECTION_KEYS = {
   init: ['autoGitInit', 'snapshotDirty', 'autoExclude'],
@@ -75,9 +78,8 @@ const SECTION_KEYS = {
   gates: ['requireChecks', 'requireTests', 'allowReviewExemption', 'maxReportBytes'],
   docs: ['board', 'boardLocation'],
   archive: ['enabled', 'afterDays', 'maxMissions'],
-  tools: ['exposeOperational', 'exposeBatch', 'exposeImport', 'exposeLeases', 'exposeTests', 'exposeRecovery', 'exposeDoctor'],
   leases: ['ttlMs'],
-  dev: ['hotReload', 'reloadDelayMs', 'reloadRequiredIds'],
+  dev: ['reloadDelayMs', 'reloadRequiredIds'],
 }
 
 const MODEL_KEYS = ['provider', 'model', 'reasoningEffort', 'maxTokens']
@@ -261,43 +263,62 @@ export const Config = Schema.object({
   })
     .default({})
     .description('Terminal-mission archival policy. Archived missions are moved, never deleted.'),
-  tools: Schema.object({
-    exposeOperational: Schema.boolean()
-      .default(true)
-      .description('Master switch for batch/resource/import/legacy/recover/test/doctor tools.'),
-    exposeBatch: Schema.boolean().default(true).description('Register tower_batch.'),
-    exposeImport: Schema.boolean().default(true).description('Register tower_import_legacy/tower_legacy_map.'),
-    exposeLeases: Schema.boolean().default(true).description('Register tower_resource advisory leases.'),
-    exposeTests: Schema.boolean().default(true).description('Register tower_test; gates.requireTests requires it.'),
-    exposeRecovery: Schema.boolean().default(true).description('Register tower_recover (stale state-lock escape).'),
-    exposeDoctor: Schema.boolean().default(true).description('Register tower_doctor (read-only health contract).'),
-  })
-    .default({})
-    .description('Tool-surface policy.'),
   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-bundle', 'tower', 'tower-skills', 'preset-tower-worker', 'preset-tower-reviewer'])
-      .description('Loader entry ids passed to reconcileProfile as required.'),
+      .default(['tower', 'tower-host', 'preset-tower-worker'])
+      .description('Loader entry ids passed to reconcileProfile as required. Optional component rows are deliberately not required, so a row switched off is not a reload failure.'),
   })
     .default({})
     .description('Development and hot-reload behavior.'),
 }).description('DSH Tower configuration')
 
+/**
+ * The user-facing config surface (#84): every leaf key one level deep plus the
+ * names of the object sections. The generated config reference, `tower_doctor`
+ * and the surface baseline all count this same shape, so "how many concepts"
+ * is one number rather than three near-identical ones.
+ *
+ * @param {any} [config] the Schemastery root (defaults to the live `Config`)
+ * @returns {{ keys: string[], sections: string[], count: number }}
+ */
+export function configSurface(config = Config) {
+  const keys = []
+  const sections = []
+  for (const [key, schema] of Object.entries(config?.dict ?? {})) {
+    const dict = schema?.dict
+    if (dict && typeof dict === 'object') {
+      sections.push(key)
+      for (const child of Object.keys(dict)) keys.push(`${key}.${child}`)
+    } else {
+      keys.push(key)
+    }
+  }
+  return { keys, sections, count: keys.length }
+}
+
+/** @param {any} value */
 export function clone(value) {
   return value === undefined ? undefined : JSON.parse(JSON.stringify(value))
 }
 
+/**
+ * @param {any} value
+ * @returns {boolean}
+ */
 export function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
 
+/**
+ * @param {any} base
+ * @param {any} override
+ */
 export function deepMerge(base, override) {
   if (override === undefined) return clone(base) ?? {}
   if (!isPlainObject(base) || !isPlainObject(override)) return clone(override)
@@ -326,6 +347,10 @@ export function normalizeLegacy(raw = {}) {
   return out
 }
 
+/**
+ * @param {any} value
+ * @param {string} label
+ */
 function assertModelKeys(value, label) {
   const bad = Object.keys(value).filter((key) => !MODEL_KEYS.includes(key))
   if (bad.length > 0) {
@@ -333,12 +358,16 @@ function assertModelKeys(value, label) {
   }
 }
 
+/**
+ * @param {any} raw
+ * @param {string} label
+ */
 export 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 TowerToolError(
       'config-unknown-key',
-      `${label} has unknown key(s) ${unknown.join(', ')} — config is { section?, allowAgentControl?, init?, mode?, review?, merge?, git?, worktrees?, spawn?, send?, tests?, gates?, docs?, archive?, leases?, dev?, tools? }`,
+      `${label} has unknown key(s) ${unknown.join(', ')} — config is { section?, allowAgentControl?, init?, mode?, review?, merge?, git?, worktrees?, spawn?, send?, tests?, gates?, docs?, archive?, leases?, dev? }`,
     )
   }
   for (const [group, allowed] of Object.entries(SECTION_KEYS)) {
@@ -363,7 +392,11 @@ export function assertKnownKeys(raw, label) {
 
 const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
 
-/** Reject prototype-pollution style keys anywhere in a repository config. */
+/**
+ * Reject prototype-pollution style keys anywhere in a repository config.
+ * @param {any} value
+ * @param {string} label
+ */
 export function assertSafeKeys(value, label) {
   if (Array.isArray(value)) {
     for (const item of value) assertSafeKeys(item, label)
@@ -378,6 +411,7 @@ export function assertSafeKeys(value, label) {
   }
 }
 
+/** @param {any} [rawConfig] */
 export function resolveTowerConfig(rawConfig) {
   const raw = rawConfig ?? {}
   if (raw !== null && typeof raw !== 'object') throw new TowerToolError('config-invalid', 'Tower config must be an object')
@@ -389,11 +423,12 @@ export function resolveTowerConfig(rawConfig) {
     throw new TowerToolError('config-invalid', `Tower config is invalid: ${String(error?.message ?? error)}`)
   }
   const mode = clone(parsed.mode ?? {})
-  if (parsed.gates?.requireTests === true) {
-    const testsAvailable = parsed.tests?.enabled !== false && parsed.tools?.exposeOperational !== false && parsed.tools?.exposeTests !== false
-    if (!testsAvailable) {
-      throw new TowerToolError('config-invalid', 'Tower config is invalid: gates.requireTests is true but test discovery is disabled (tests.enabled/tools.exposeTests)')
-    }
+  if (parsed.gates?.requireTests === true && parsed.tests?.enabled === false) {
+    // #121: the tower-tests *component row* is the capability switch now; a
+    // repository that turns the row off cannot satisfy gates.requireTests. The
+    // component-level half of this invariant is enforced at plan/mode entry,
+    // where the mounted rows are known (host/presets.js).
+    throw new TowerToolError('config-invalid', 'Tower config is invalid: gates.requireTests is true but test discovery is disabled (tests.enabled:false)')
   }
   // Canonical keys win; the legacy top-level aliases only fill gaps.
   const rawMode = raw.mode ?? {}
@@ -420,7 +455,6 @@ export function resolveTowerConfig(rawConfig) {
     gates: clone(parsed.gates ?? {}),
     docs: clone(parsed.docs ?? {}),
     archive: clone(parsed.archive ?? {}),
-    tools: clone(parsed.tools ?? {}),
     leases: clone(parsed.leases ?? {}),
     dev: clone(parsed.dev ?? {}),
   }

package/domain/contracts/outputs.js

@@ -4,7 +4,12 @@ const S = {
   str: { type: 'string' },
   int: { type: 'integer' },
   bool: { type: 'boolean' },
+  /** @param {any} items */
   arr: (items) => ({ type: 'array', items }),
+  /**
+   * @param {Record<string, any>} [properties]
+   * @param {string[]} [required]
+   */
   obj: (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: true }),
   any: {},
 }
@@ -79,6 +84,7 @@ const SCHEMAS = {
       recentFindings: S.arr(S.obj()),
       missions: S.arr(S.obj()),
       activity: S.arr(S.obj()),
+      gitLock: S.obj({ held: S.bool, pid: S.any, phase: S.any, heldMs: S.any }),
       mode: S.any,
       spawn: S.any,
       towerAgentId: S.any,
@@ -169,7 +175,7 @@ const SCHEMAS = {
     ['counts', 'total'],
   ),
   review: S.obj(
-    { review: S.obj(), branchTip: S.str, missionStatus: S.str, round: S.int, reviewerRounds: S.int },
+    { review: S.obj(), branchTip: S.str, missionStatus: S.str, round: S.int, appended: S.bool, reviewerRounds: S.int },
     ['review', 'branchTip', 'missionStatus', 'round', 'reviewerRounds'],
   ),
   preflight: S.obj(
@@ -243,6 +249,8 @@ const SCHEMAS = {
     {
       ok: S.bool,
       checks: S.arr(S.obj()),
+      stateLock: S.any,
+      gitLock: S.any,
       stateSchema: S.obj({
         currentVersion: S.any,
         supportedVersion: S.int,
@@ -250,6 +258,7 @@ const SCHEMAS = {
         status: S.str,
       }),
       reports: S.any,
+      surface: S.any,
       archive: S.obj({
         missions: S.any,
         archivedMissions: S.int,
@@ -266,7 +275,7 @@ const SCHEMAS = {
     ['ok', 'checks'],
   ),
   recover: S.obj(
-    { ok: S.bool, action: S.str, stateLock: S.any, cleared: S.bool, backup: S.any, error: S.str },
+    { ok: S.bool, action: S.str, stateLock: S.any, cleared: S.bool, backup: S.any, forced: S.bool, error: S.str },
     ['ok', 'action'],
   ),
   test: S.obj(
@@ -294,10 +303,15 @@ const SCHEMAS = {
   legacyMap: S.obj({ ok: S.bool, map: S.obj(), maps: S.arr(S.obj()) }, ['ok']),
 }
 
+/**
+ * @param {any} _args
+ * @param {any} value
+ */
 function renderValue(_args, value) {
   return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
 }
 
+/** @param {any} schema */
 function output(schema) {
   return { schema, render: renderValue }
 }

package/domain/contracts/tool-inputs/ops.js

@@ -25,6 +25,7 @@ export const RecoverInput = Type.Object({
   repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
   action: enumOf(RECOVERY_ACTIONS, { description: 'Recovery action.' }),
   confirm: Type.Optional(Type.String({ description: 'Required literal CLEAR_STALE_LOCK for clear-stale-lock.' })),
+  force: Type.Optional(Type.Boolean({ description: 'clear-stale-lock: clear the lock even when its recorded PID is alive (a recycled PID); requires confirm and still moves the record to a .recovered-<ts> backup.' })),
 }, { additionalProperties: false })
 
 export const TestInput = Type.Object({

package/domain/errors.js

@@ -3,11 +3,33 @@
 // 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 also carries the recovery metadata the model can act on:
+//
+//   - `retryable`   — the same input may succeed later without a change;
+//   - `nextAction`  — the concrete recovery step, rendered once as a trailing
+//                     ` — next: …` segment (plus ` (retryable)` when retryable);
+//   - `trigger`     — the typical condition, documented in errors.md.
+//
+// Why the message suffix rather than a structured error payload: the DSH tool
+// contract declares output schemas for successful values only, and a thrown
+// error reaches the model as its rendered message. There is no separate
+// structured error channel to return `{ code, retryable, nextAction }` through,
+// so the suffix is the model-visible channel; the error object still carries
+// `code`, `retryable`, `nextAction` and `details` for programmatic callers.
+// Codes without a recovery step render byte-identically to the pre-#74 form.
+//
 // The catalog is documented in docs/reference/errors.md; scripts/check-docs.mjs
-// keeps the two in sync.
+// and scripts/generate-error-reference.mjs keep the two in sync.
+// @ts-check
 
 /** Neutral error type shared by the git adapter and the domain classifier. */
 export class GitError extends Error {
+  /**
+   * @param {string[]} args
+   * @param {string} detail
+   * @param {number | undefined} code the child-process errno, not a Tower code
+   * @param {{ timedOut?: boolean, bufferOverflow?: boolean, stdout?: string }} [meta]
+   */
   constructor(args, detail, code, meta = {}) {
     super(`git ${args.join(' ')} failed: ${detail}`)
     this.name = 'GitError'
@@ -18,74 +40,317 @@ export class GitError extends Error {
   }
 }
 
+/**
+ * @typedef {object} ErrorCodeEntry
+ * @property {string} description
+ * @property {string} trigger
+ * @property {boolean} retryable
+ * @property {string | null} nextAction
+ */
+
+/**
+ * One stable entry per failure family. `description` and `trigger` are the
+ * documented meaning; `retryable`/`nextAction` are the recovery contract the
+ * tool boundary renders.
+ * @type {Record<string, ErrorCodeEntry>}
+ */
 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.',
-  'stale-base': 'The repository state changed while the operation was being prepared; retry.',
-  'state-locked': 'Another Tower writer holds the state lock.',
-  'state-corrupt': 'The Tower state file is unreadable or invalid.',
-  'state-version-unsupported': 'The Tower state file uses a schema version this build cannot read or downgrade.',
-  'state-migration-failed': 'A Tower state migration failed; the original state file was not modified.',
-  '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.',
-  'worktree-dirty': 'The mission worktree has uncommitted changes and cannot complete.',
-  'spawn-unavailable': 'The subagents service is unavailable.',
-  'provider-missing': 'No subagent provider is registered.',
-  'provider-cooldown': 'The provider is throttled; spawn is in a short cooldown.',
-  '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.',
+  'invalid-argument': {
+    description: 'A tool argument is missing, malformed, or not allowed.',
+    trigger: '`missionId`/`id` omitted; unknown status; empty report; bad scope glob; `timeoutMs < 1000`; `status: "all"` on an update.',
+    retryable: false,
+    nextAction: null,
+  },
+  'repo-invalid': {
+    description: 'repoRoot is missing, relative, or not inside a Git repository.',
+    trigger: 'passing a path in a directory that is not a repo',
+    retryable: false,
+    nextAction: 'pass an absolute path to a directory inside a Git repository',
+  },
+  'not-initialized': {
+    description: 'Tower is not initialized for this repository; run tower_init.',
+    trigger: 'a read tool before `tower_init`',
+    retryable: false,
+    nextAction: 'run tower_init for this repository',
+  },
+  'mission-not-found': {
+    description: 'No mission with that id exists.',
+    trigger: 'a stale or mistyped `M9`',
+    retryable: false,
+    nextAction: 'list missions with tower_status',
+  },
+  'finding-not-found': {
+    description: 'No finding with that id exists.',
+    trigger: '`tower_findings({id:"F99"})`',
+    retryable: false,
+    nextAction: 'list findings with tower_findings',
+  },
+  'invalid-transition': {
+    description: 'The requested state transition is not allowed.',
+    trigger: 'a blocked→merged attempt; a finding transition not in the graph; a reviewer mutating findings; completing a mission with open tasks, blockers, no commits, or unread inbox messages.',
+    retryable: false,
+    nextAction: null,
+  },
+  'stale-base': {
+    description: 'The repository state changed while the operation was being prepared; retry.',
+    trigger: 'two-phase mutation revalidation',
+    retryable: true,
+    nextAction: 'retry the tool; if it keeps failing, run tower_preflight and inspect tower_status',
+  },
+  'state-locked': {
+    description: 'Another Tower writer holds the state lock.',
+    trigger: 'concurrent mutation after the lock timeout',
+    retryable: true,
+    nextAction: 'wait for the other Tower writer to finish, then retry',
+  },
+  'state-corrupt': {
+    description: 'The Tower state file is unreadable or invalid.',
+    trigger: 'hand-edited `state.json`; invalid JSON; no usable `schemaVersion`',
+    retryable: false,
+    nextAction: 'restore state.json from a backup, or re-initialize after filing the corruption',
+  },
+  'state-version-unsupported': {
+    description: 'The Tower state file uses a schema version this build cannot read or downgrade.',
+    trigger: 'opening a repository written by a newer plugin; an unknown older version; this build refuses to downgrade',
+    retryable: false,
+    nextAction: 'upgrade dsh-tower to a release that supports this state schemaVersion',
+  },
+  'state-migration-failed': {
+    description: 'A Tower state migration failed; the original state file was not modified.',
+    trigger: 'a bug in a migration step; see the pre-migration `state.json.v<N>.bak`',
+    retryable: false,
+    nextAction: 'restore the pre-migration backup state.json.v<N>.bak and report the migration bug',
+  },
+  'config-invalid': {
+    description: 'Tower configuration is invalid.',
+    trigger: 'malformed repo `config.json`, a value that violates the schema',
+    retryable: false,
+    nextAction: 'fix the repository config file, then retry',
+  },
+  'config-unknown-key': {
+    description: 'Tower configuration has an unknown top-level key.',
+    trigger: 'a typo such as `allowAgentToggle`',
+    retryable: false,
+    nextAction: 'remove the unknown key from the repository config file, then retry',
+  },
+  'git-failed': {
+    description: 'A git command failed.',
+    trigger: 'a rejected merge command, invalid ref',
+    retryable: false,
+    nextAction: null,
+  },
+  'git-timeout': {
+    description: 'A git command timed out or exceeded its output buffer.',
+    trigger: 'slow pre-merge hook, huge diff',
+    retryable: true,
+    nextAction: 'retry; if it persists, raise git.timeoutMs or merge.timeoutMs',
+  },
+  'worktree-dirty': {
+    description: 'The mission worktree has uncommitted changes and cannot complete.',
+    trigger: 'staged, modified, or untracked files left behind before `tower_complete`',
+    retryable: false,
+    nextAction: 'commit or remove the worktree changes, then retry tower_complete',
+  },
+  'spawn-unavailable': {
+    description: 'The subagents service is unavailable.',
+    trigger: 'a Host without `subagents`',
+    retryable: false,
+    nextAction: 'enable the DSH subagents service, then retry',
+  },
+  'provider-missing': {
+    description: 'No subagent provider is registered.',
+    trigger: 'an empty provider list',
+    retryable: false,
+    nextAction: 'register a subagent provider in the DSH profile, then retry',
+  },
+  'provider-cooldown': {
+    description: 'The provider is throttled; spawn is in a short cooldown.',
+    trigger: 'repeated retryable provider failures; wait for `blockedUntil`',
+    retryable: true,
+    nextAction: 'wait for the cooldown to expire, then retry',
+  },
+  'preset-missing': {
+    description: 'The configured agent preset is not registered.',
+    trigger: 'missing `tower-worker`/`tower-reviewer` preset rows, DSH not restarted',
+    retryable: false,
+    nextAction: 'install the tower-worker and tower-reviewer agent presets and restart DSH',
+  },
+  'reviewer-prerequisite': {
+    description: 'The reviewer spawn prerequisite is not met.',
+    trigger: 'reviewer spawned before the mission is `completed`, or before a worktree exists',
+    retryable: false,
+    nextAction: 'complete the mission first, then spawn the reviewer',
+  },
+  'not-authorized': {
+    description: 'The calling agent role may not perform this action.',
+    trigger: 'a worker calling a tower-only tool or changing mission status/scope; a reviewer mutating findings',
+    retryable: false,
+    nextAction: 'call the tool as the tower, or as the worker/reviewer it is assigned to',
+  },
+  'workspace-busy': {
+    description: 'Another Tower session owns this repository workspace lock.',
+    trigger: '`mode.workspaceLock:true` and a second session calls a repo-scoped tool',
+    retryable: true,
+    nextAction: 'run /tower off in the other session or wait for its lock to become stale',
+  },
+  'worker-limit': {
+    description: 'The repository reached spawn.maxLiveWorkers live workers.',
+    trigger: 'spawning a fifth worker with the default limit',
+    retryable: false,
+    nextAction: 'wait for a live worker to finish or raise spawn.maxLiveWorkers',
+  },
+  'rate-limited': {
+    description: 'The tower_send per-minute rate limit was reached.',
+    trigger: '`send.maxPerMinute` exceeded',
+    retryable: true,
+    nextAction: 'wait for the next per-minute window or raise send.maxPerMinute',
+  },
+  'takeover-refused': {
+    description: 'The mission already has a live worker that was not stopped first.',
+    trigger: '`tower_spawn({takeover:true})` before `tower_interrupt`',
+    retryable: false,
+    nextAction: 'run tower_interrupt for the live worker, then retry the takeover',
+  },
+  'reload-unavailable': {
+    description: 'The DSH HMR service is not available in this profile.',
+    trigger: '`tower_reload` / `/tower reload` on a profile without HMR',
+    retryable: false,
+    nextAction: 'restart DSH instead of reloading',
+  },
+  'reload-failed': {
+    description: 'The HMR reload failed; check the DSH log and restart if needed.',
+    trigger: '`reconcileProfile` threw',
+    retryable: false,
+    nextAction: 'check the DSH log and restart DSH',
+  },
+  'tests-failed': {
+    description: 'Declared test discovery failed or did not meet its admission requirements.',
+    trigger: 'nonzero command, malformed output, minCount/required shortfall',
+    retryable: false,
+    nextAction: 'fix the failing tests, then retry tower_complete',
+  },
+  'tests-timeout': {
+    description: 'Test discovery exceeded its time or output budget.',
+    trigger: '`tests.timeoutMs`, or stdout over `tests.maxBytes`',
+    retryable: false,
+    nextAction: 'raise tests.timeoutMs or tests.maxBytes (or speed up the suite), then retry',
+  },
+  'lease-busy': {
+    description: 'Another holder owns the requested advisory lease.',
+    trigger: '`tower_resource acquire` while `heavy-ci` is held',
+    retryable: false,
+    nextAction: 'release the lease or wait for it to expire, then retry',
+  },
+  'lease-token': {
+    description: 'The lease release token does not match the current holder.',
+    trigger: 'releasing with another session\'s token',
+    retryable: false,
+    nextAction: 'use the token returned when the lease was acquired',
+  },
+  'batch-invalid': {
+    description: 'The batch request or its close evidence is invalid.',
+    trigger: 'unknown member, duplicate id, unsafe receipt path, missing receipt hash',
+    retryable: false,
+    nextAction: 'fix the batch request or the receipt hashes, then retry',
+  },
+  'legacy-invalid': {
+    description: 'The legacy snapshot or mapping is invalid.',
+    trigger: 'unknown schema, source inside the Tower state dir, mapping rewrite',
+    retryable: false,
+    nextAction: 'check the legacy snapshot path, schema and mapping, then retry',
+  },
+  'tool-internal': {
+    description: 'An unexpected failure; read the message and the activity log.',
+    trigger: 'a bug; read the message and the activity log',
+    retryable: false,
+    nextAction: null,
+  },
 }
 
 export const ERROR_CODE_VALUES = Object.freeze(Object.keys(ERROR_CODES))
+
+/** @param {unknown} value */
 export function isErrorCode(value) {
   return typeof value === 'string' && Object.hasOwn(ERROR_CODES, value)
 }
 
-const RETRYABLE_CODES = new Set(['state-locked', 'rate-limited', 'provider-cooldown', 'git-timeout', 'workspace-busy', 'merge-intent-pending', 'stale-base'])
+/** @param {string} code */
+export function errorEntry(code) {
+  return isErrorCode(code) ? ERROR_CODES[code] : null
+}
+
+/** @param {string} code */
+export function errorDescription(code) {
+  return errorEntry(code)?.description ?? ''
+}
+
+/** @param {string} code */
+export function errorRetryable(code) {
+  return errorEntry(code)?.retryable === true
+}
+
+/** @param {string} code */
+export function errorNextAction(code) {
+  return errorEntry(code)?.nextAction ?? null
+}
+
+/**
+ * The model-visible message. Exactly one trailing ` — next: …` segment is
+ * appended when there is a recovery step; a retryable code marks the same
+ * segment with ` (retryable)`. A message that already carries the action is
+ * never suffixed twice.
+ * @param {string} code
+ * @param {string} message
+ * @param {{ nextAction?: string | null, retryable?: boolean }} [options]
+ * @returns {string}
+ */
+export function renderErrorMessage(code, message, options = {}) {
+  const text = String(message)
+  const base = `[tower:${code}] ${text}`
+  const nextAction = options.nextAction ?? errorNextAction(code)
+  if (nextAction === null || nextAction === undefined) return base
+  if (text.includes(nextAction) || text.includes('— next:')) return base
+  const retryable = options.retryable ?? errorRetryable(code)
+  return `${base} — next: ${nextAction}${retryable ? ' (retryable)' : ''}`
+}
 
 export class TowerToolError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {{ cause?: unknown, retryable?: boolean, nextAction?: string | null, details?: unknown }} [options]
+   */
   constructor(code, message, options = {}) {
-    super(`[tower:${code}] ${message}`, options.cause ? { cause: options.cause } : undefined)
+    const entry = errorEntry(code)
+    const retryable = options.retryable ?? entry?.retryable === true
+    const nextAction = options.nextAction ?? entry?.nextAction ?? null
+    super(renderErrorMessage(code, message, { nextAction, retryable }), options.cause ? { cause: options.cause } : undefined)
     this.name = 'TowerToolError'
     this.code = code
-    this.retryable = options.retryable ?? RETRYABLE_CODES.has(code)
-    this.nextAction = options.nextAction ?? null
+    this.retryable = retryable
+    this.nextAction = nextAction
     this.details = options.details ?? null
   }
 }
 
+/** @param {any} error */
 function originalMessage(error) {
   return String(error?.message ?? error)
 }
 
-/** Wrap any thrown value into a TowerToolError with a stable code. */
+/**
+ * Wrap any thrown value into a TowerToolError with a stable code.
+ * @param {any} error
+ */
 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,
-      retryable: error.retryable === true,
-      nextAction: error.nextAction ?? null,
+      // Let the catalog supply a default when the thrown object does not
+      // explicitly override the recovery metadata.
+      retryable: typeof error.retryable === 'boolean' ? error.retryable : undefined,
+      nextAction: error.nextAction ?? undefined,
       details: error.details ?? null,
     })
   }