dsh-tower 2.0.3 → 2.1.0-beta.1

package/tools/findings.js

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

package/tools/import-legacy.js

@@ -0,0 +1,42 @@
+// tower_import_legacy — import a legacy snapshot read-only.
+// 
+// Input: ImportLegacyInput (sourcePath) from contracts.
+// Output: snapshot summary; state is never activated or adopted.
+// Authorization: tower only.
+// Side effects: writes a content-addressed legacy snapshot only.
+// Failure modes: invalid legacy payload, path inside tower state.
+// Pure legacy validation lives in domain and never runs fs.
+// See docs/reference/tools.generated.md for the public shape.
+// tower_import_legacy: read-only legacy snapshot import.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { importLegacySnapshot } from '../lib/legacy.js'
+import { ImportLegacyInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any }} deps
+ */
+export function registerImportLegacyTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor } = deps
+  define(ctx, {
+    name: 'tower_import_legacy',
+    description:
+      'Read-only import of a Tower Codex (schemaVersion 1) or DSH legacy state file. Stores the full payload under <common>/dsh-tower/legacy/<sha256>.json and records only a summary in state.legacySnapshots; never activates, adopts, or resumes paused missions.',
+    parameters: ImportLegacyInput,
+    board: true,
+    output: output(SCHEMAS.importLegacy),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'import a legacy snapshot')
+      const imported = await importLegacySnapshot({
+        repoRoot: tower.root,
+        commonDir: tower.commonDir,
+        sourcePath: args.sourcePath,
+      })
+      const recorded = await tower.recordLegacySnapshot(imported.snapshot)
+      return { ok: true, summary: imported.summary, snapshot: recorded.snapshot }
+    },
+  })
+}

package/tools/inbox.js

@@ -0,0 +1,39 @@
+// Acknowledged messages are filtered from later unread counts.
+// Delivery results are persisted by the registry.
+// tower_inbox — read and acknowledge mission messages.
+// 
+// Input: InboxInput (name, limit) from domain contracts.
+// Output: unread messages plus acknowledgement metadata.
+// Authorization: the addressed roster agent or the tower.
+// Side effects: marks delivered messages as read and persists state.
+// Failure modes: unknown recipient, invalid limit.
+// The unread calculation is a pure domain/collab projection.
+// See docs/reference/tools.generated.md for the public shape.
+// tower_inbox: read and acknowledge inbound messages.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { InboxInput } from '../domain/contracts/tool-inputs/index.js'
+import { ROLE } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool }} deps
+ */
+export function registerInboxTool(ctx, deps) {
+  const { define } = deps
+  define(ctx, {
+    name: 'tower_inbox',
+    description:
+      'Read your tower inbox: messages addressed to you plus broadcasts, newest first. Only returned messages are acknowledged; the result reports unreadRemaining, so keep reading until it reaches 0. Set include_read for history. Unread messages block tower_complete.',
+    parameters: InboxInput,
+    aliases: {"include_read":["includeRead"]},
+    output: output(SCHEMAS.inbox),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const view = await tower.rosterView()
+      const self = view.roster.find((entry) => entry.agentId === String(exec.agent.id))
+      const reader = self ? self.name : ROLE.tower
+      return tower.inbox({ reader, limit: args.limit, includeRead: args.include_read === true })
+    },
+  })
+}

package/tools/index.js

@@ -0,0 +1,39 @@
+// Public tool wiring for the DSH Host plugin.
+// 
+// Registration contract:
+// - define(ctx, definition) accepts a TypeBox parameters schema;
+// - execute(args) is typed from that schema by Static<>;
+// - aliases and requiresMissionId are honored by the registry;
+// - operational switches decide whether a tool is registered;
+// - errors are classified to stable [tower:code] values;
+// - tools must not import node:fs or node:child_process directly.
+// 
+// Tests import this module for the public surface; they may also
+// import lib/tool-registry.js for low-level test hooks.
+// 
+// Packaging: package.json ships tools/*.js and lib/tool-registry.js.
+// The file intentionally stays tiny so handler modules remain the
+// only place where a tool is defined.
+// Keep this comment and the re-export list in sync when adding tools.
+// See docs/reference/tools.generated.md for the generated list.
+// Tower tool surface — thin public wiring (#56).
+// 
+// The registration aggregator, guards, rate limits, spawn backoff,
+// repository preparation, discovery helpers, and verb helpers live in
+// lib/tool-registry.js. This module only re-exports the public entry
+// points consumed by the Host plugin, tests, and docs generators.
+// 
+// Design rules:
+// - one handler module per tool under tools/;
+// - tool schemas live in domain/contracts/tool-inputs;
+// - vocabulary lives in domain/vocabulary.js;
+// - no business logic in this file;
+// - keep the surface stable for index.js and tests.
+// 
+// See docs/architecture/overview.md and lib/tool-registry.js.
+// Tower tool surface: thin public wiring (#56 P5).
+// Registration and shared machinery live in lib/tool-registry.js; one handler
+// module per tool lives under tools/. This file only exposes the public entry
+// points consumed by the Host plugin, tests, and documentation generators.
+export { registerTowerTools, __testSpawnBackoff } from '../lib/tool-registry.js'
+export { workerBriefing, reviewerBriefing } from '../lib/briefing.js'

package/tools/init.js

@@ -0,0 +1,63 @@
+// tower_init: repository initialization.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { resolveRepo } from '../lib/git.js'
+import { runtimeConfig } from '../lib/config.js'
+import { InitInput } from '../domain/contracts/tool-inputs/index.js'
+import { isTowerRole, isUnknownRole } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any, workspaceHook: any, ensureRepository: any }} deps
+ */
+export function registerInitTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor, workspaceHook, ensureRepository } = deps
+  define(ctx, {
+    name: 'tower_init',
+    description:
+      'Initialize Tower mission state for a repository (absolute repoRoot). Creates <git-common-dir>/dsh-tower/state.json and an activity log; idempotent on an existing workspace. Options: autoGitInit (git init + empty initial commit when the directory is not a repository), snapshotDirty (snapshot uncommitted work into a dangling commit used as the mission baseline), reanchor (change base when every mission is merged/abandoned). Only the tower may initialize.',
+    parameters: InitInput,
+    aliases: { auto_git_init: ['autoGitInit'], snapshot_dirty: ['snapshotDirty'] },
+    board: true,
+    output: output(SCHEMAS.init),
+    async execute(args, exec) {
+      const profileInit = runtimeConfig().init ?? {}
+      let repo = null
+      try {
+        repo = await resolveRepo(args.repoRoot)
+      } catch (error) {
+        const autoGitInit =
+          args.autoGitInit === true || (args.autoGitInit === undefined && profileInit.autoGitInit === true)
+        repo = await ensureRepository(args.repoRoot, autoGitInit)
+      }
+      const tower = await Tower.open(repo.root)
+      const initConfig = tower.config.init ?? {}
+      const snapshotDirty =
+        args.snapshotDirty === true || (args.snapshotDirty === undefined && initConfig.snapshotDirty === true)
+      const agentId = exec?.agent?.id !== undefined ? String(exec.agent.id) : null
+      if (!agentId) {
+        throw new TowerToolError('not-authorized', 'tower_init requires a caller agent id; refusing to treat an unidentified caller as the tower')
+      }
+      let state = null
+      try {
+        state = await tower.load()
+      } catch {
+        state = null
+      }
+      if (state?.towerAgentId) {
+        const actor = await actorFor(tower, exec)
+        requireTowerActor(actor, 'initialize Tower state')
+      } else if (state) {
+        // Legacy state predating owner binding: an explicit tower_init may
+        // claim ownership once. Other tools remain fail-closed until then.
+        const actor = await actorFor(tower, exec)
+        if (!isTowerRole(actor.role) && !isUnknownRole(actor.role)) {
+          requireTowerActor(actor, 'claim Tower ownership')
+        }
+      }
+      const base = args.base ?? workspaceHook?.basePreference?.(exec) ?? undefined
+      return tower.init({ base, snapshotDirty, reanchor: args.reanchor, towerAgentId: agentId })
+    },
+  })
+}

package/tools/interrupt.js

@@ -0,0 +1,42 @@
+// tower_interrupt — stop one running roster agent.
+// 
+// Input: InterruptInput (name/agentId/id) from domain contracts.
+// Output: interrupted agent and updated roster observation.
+// Authorization: tower or the worker parent for its own child.
+// Side effects: interrupts the subagent and persists state.
+// Failure modes: unknown agent, not running, not authorized.
+// Roster state policy is pure and lives in domain/collab.
+// See docs/reference/tools.generated.md for the public shape.
+// tower_interrupt: interrupt one running roster agent.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { InterruptInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any, interruptRosterAgent: any }} deps
+ */
+export function registerInterruptTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor, interruptRosterAgent } = deps
+  define(ctx, {
+    name: 'tower_interrupt',
+    description:
+      'Interrupt one running tower roster agent (worker or reviewer) and record it as interrupted in the roster. Only the tower may interrupt. Idempotent: an agent that is not running returns interrupted:false. Use it before takeover after a runaway worker, or to stop work that is no longer wanted.',
+    parameters: InterruptInput,
+    aliases: { agentId: ['agent_id'] },
+    output: output(SCHEMAS.interrupt),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'interrupt tower agents')
+      if (!args.to && !args.agentId) throw new TowerToolError('invalid-argument', 'tower_interrupt requires to (roster name) or agentId')
+      const result = await interruptRosterAgent(ctx, tower, exec, {
+        to: args.to,
+        agentId: args.agentId,
+        reason: args.reason,
+      })
+      return { ok: true, ...result }
+    },
+  })
+}

package/tools/legacy-map.js

@@ -0,0 +1,44 @@
+// tower_legacy_map — map a legacy snapshot to a mission.
+// 
+// Input: LegacyMapInput (action, sourceHash, oldId) from contracts.
+// Output: mapping record or mapping status.
+// Authorization: tower only.
+// Side effects: appends audit mapping to state; no adoption.
+// Failure modes: unknown snapshot, duplicate mapping, invalid id.
+// Pure mapping validation lives in the domain legacy layer.
+// See docs/reference/tools.generated.md for the public shape.
+// tower_legacy_map: audit-only legacy snapshot mapping.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { validateLegacyMap } from '../lib/legacy.js'
+import { LegacyMapInput } from '../domain/contracts/tool-inputs/index.js'
+import { LEGACY_MAP_ACTION } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any }} deps
+ */
+export function registerLegacyMapTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor } = deps
+  define(ctx, {
+    name: 'tower_legacy_map',
+    description:
+      'Audit-only mapping between a legacy snapshot id and a current mission. map records sourceHash/oldId/newMissionId; status lists mappings. Mapping never adopts or resumes a legacy mission.',
+    parameters: LegacyMapInput,
+    output: output(SCHEMAS.legacyMap),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      const state = await tower.load()
+      if (args.action === LEGACY_MAP_ACTION.status) {
+        return { ok: true, maps: state.legacyMaps ?? [] }
+      }
+      requireTowerActor(actor, 'map a legacy mission')
+      const validation = validateLegacyMap(state, args)
+      const map = { ...validation.map, by: actor.name, at: Date.now() }
+      const recorded = await tower.recordLegacyMap(map)
+      return { ok: true, map: recorded.map, maps: [...(state.legacyMaps ?? []), recorded.map] }
+    },
+  })
+}

package/tools/merge.js

@@ -0,0 +1,39 @@
+// The merge command uses the exact reviewed commit, never a mutable branch name.
+// tower_merge — integrate a reviewed mission branch.
+// 
+// Input: MergeInput (missionId/id, timeoutMs) from domain contracts.
+// Output: merged commit, parents, review evidence, blockers.
+// Authorization: tower only; the gate is re-evaluated.
+// Side effects: git merge, state/activity writes, cleanup on failure.
+// Failure modes: merge-conflict, merge-hook-failed, merge-shape.
+// The pure intent/shape decisions live in domain/integration.
+// See docs/reference/tools.generated.md for the public shape.
+// tower_merge: merge a mission branch into the recorded base.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { MergeInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any, observeActivity: any }} deps
+ */
+export function registerMergeTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor, observeActivity } = deps
+  define(ctx, {
+    name: 'tower_merge',
+    description:
+      'Merge a mission branch into the recorded base branch with --no-ff, after the hard gate passes. Verifies the two merge parents and records the mission as merged. If the merge commit already landed (manual merge, crashed or slow pre-merge hook), it detects the merge commit and records it as reconciled instead of merging again. A failed gate returns stable blocker codes without merging; a hook failure aborts cleanly and returns "merge-hook-failed" while a real content conflict returns "merge-conflict".',
+    parameters: MergeInput,
+    aliases: {"missionId":["id"],"timeoutMs":["timeout_ms"]},
+    requiresMissionId: true,
+    board: true,
+    output: output(SCHEMAS.merge),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'merge missions')
+      const { activity, parentStatus } = await observeActivity(ctx, tower)
+      return tower.merge({ missionId: args.missionId, activity, parentStatus, timeoutMs: args.timeoutMs })
+    },
+  })
+}

package/tools/mission.js

@@ -0,0 +1,41 @@
+// tower_mission: mission lifecycle updates.
+import { Tower } from '../app/tower.js'
+import { TowerToolError } from '../domain/errors.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { MissionInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireKnownActor: any }} deps
+ */
+export function registerMissionTool(ctx, deps) {
+  const { define, actorFor, requireKnownActor } = deps
+  define(ctx, {
+    name: 'tower_mission',
+    description:
+      'Update one mission: lifecycle status, decision note, blocker, clear blockers, mark a task done, drop a task with a reason, or widen the scope (tower only). "merged" is never set here; only a future tower_merge records it. Merged and abandoned are terminal.',
+    parameters: MissionInput,
+    aliases: {"id":["missionId"],"task_done":["taskDone"],"task_drop":["taskDrop"],"task_drop_reason":["taskDropReason"],"clear_blockers":["clearBlockers"]},
+    board: true,
+    output: output(SCHEMAS.mission),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireKnownActor(actor, 'tower_mission')
+      return tower.mission({
+        actor,
+        id: args.id,
+        status: args.status,
+        note: args.note,
+        blocker: args.blocker,
+        clear_blockers: args.clear_blockers,
+        task_done: args.task_done,
+        task_drop: args.task_drop,
+        task_drop_reason: args.task_drop_reason,
+        scope: args.scope,
+        pause_cause: args.pause_cause,
+        authorization: args.authorization,
+      })
+    },
+  })
+}

package/tools/plan.js

@@ -0,0 +1,39 @@
+// Mission ids are assigned monotonically by the domain planner.
+// tower_plan — create missions and assign M1.. ids.
+// 
+// Input: PlanInput from domain contracts (missions, scope, deps).
+// Output: created mission summaries and board state.
+// Authorization: tower only; presets are validated first.
+// Side effects: persists state and optional board file.
+// It never creates worktrees; spawn/provision do that later.
+// Failure modes: invalid scope, cyclic deps, preset missing.
+// Pure normalization and DAG policy live in domain/missions.
+// See docs/reference/tools.generated.md for the public shape.
+// tower_plan: create missions.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { assertPresetsAvailable } from '../lib/presets.js'
+import { PlanInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any }} deps
+ */
+export function registerPlanTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor } = deps
+  define(ctx, {
+    name: 'tower_plan',
+    description:
+      'Plan one or more missions in an initialized repository. Each mission has a printable-ASCII title, relative scope globs, optional task checklist, optional mission-id dependencies, and kind build|survey. Assigns M1.. ids and auto-adds a dependency when build scopes overlap (serializes merges); rejects dependency cycles.',
+    parameters: PlanInput,
+    board: true,
+    output: output(SCHEMAS.plan),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'plan missions')
+      await assertPresetsAvailable(ctx, tower.config)
+      return tower.plan({ missions: args.missions })
+    },
+  })
+}

package/tools/preflight.js

@@ -0,0 +1,44 @@
+// tower_preflight: read-only merge gate digest.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { classifyError } from '../domain/errors.js'
+import { PreflightInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, observeActivity: any }} deps
+ */
+export function registerPreflightTool(ctx, deps) {
+  const { define, observeActivity } = deps
+  define(ctx, {
+    name: 'tower_preflight',
+    description:
+      'Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, read-only-survey, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.requireReview is on. Never changes anything.',
+    parameters: PreflightInput,
+    aliases: {"missionId":["id"]},
+    requiresMissionId: true,
+    output: output(SCHEMAS.preflight),
+    async execute(args) {
+      const tower = await Tower.open(args.repoRoot)
+      const { activity, parentStatus } = await observeActivity(ctx, tower)
+      const gate = await tower.evaluateGate({ missionId: args.missionId, activity, parentStatus })
+      return {
+        ok: gate.ok,
+        blockers: gate.blockers,
+        missionId: args.missionId,
+        branchTip: gate.branchTip ?? null,
+        baseTip: gate.baseTip ?? null,
+        changedFiles: gate.changedFiles ?? [],
+        review: gate.review
+          ? {
+              round: gate.review.round,
+              status: gate.review.status,
+              mergeVerdict: gate.review.mergeVerdict,
+              reviewer: gate.review.reviewer,
+              reviewedCommit: gate.review.reviewedCommit,
+            }
+          : null,
+      }
+    },
+  })
+}

package/tools/rebase.js

@@ -0,0 +1,39 @@
+// A clean rebase may waive re-review by binding the old reviewed tip.
+// tower_rebase — rebase a mission branch onto the base.
+// 
+// Input: RebaseInput (missionId/id) from domain contracts.
+// Output: old/new tips, base tip, review-waiver decision.
+// Authorization: tower only; ownership and cleanliness are checked.
+// Side effects: git rebase, abort/cleanup, state/activity writes.
+// Failure modes: conflict, stale-base, tip-moved, dirty worktree.
+// Pure intent/waiver decisions live in domain/integration.
+// See docs/reference/tools.generated.md for the public shape.
+// tower_rebase: rebase a mission branch inside its worktree.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { RebaseInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any, observeActivity: any }} deps
+ */
+export function registerRebaseTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor, observeActivity } = deps
+  define(ctx, {
+    name: 'tower_rebase',
+    description:
+      'Rebase a mission branch onto the current base tip inside its own worktree. Refuses while its worker is running or the worktree is dirty. A clean conflict-free rebase waives re-review for the old review; a conflict is aborted and the mission is marked blocked. If the branch is already contained in the base, it returns alreadyMerged and leaves the branch untouched so tower_merge can record the landed merge.',
+    parameters: RebaseInput,
+    aliases: {"missionId":["id"]},
+    requiresMissionId: true,
+    board: true,
+    output: output(SCHEMAS.rebase),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'rebase missions')
+      const { activity } = await observeActivity(ctx, tower)
+      return tower.rebase({ missionId: args.missionId, activity })
+    },
+  })
+}

package/tools/recover.js

@@ -0,0 +1,45 @@
+// tower_recover: explicit stale state-lock diagnostics/repair.
+import { Tower } from '../app/tower.js'
+import { readStateLock } from '../lib/store.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { fsp } from '../adapters/store-fs.js'
+import { RecoverInput } from '../domain/contracts/tool-inputs/index.js'
+import { RECOVERY_ACTION, RECOVERY_CONFIRM, ROLE } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any }} deps
+ */
+export function registerRecoverTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor } = deps
+  define(ctx, {
+    name: 'tower_recover',
+    description:
+      'Read-only recovery diagnostics and an explicit stale-state-lock repair. status reports the state lock owner; clear-stale-lock requires confirm:"CLEAR_STALE_LOCK" and only moves a lock whose PID is provably dead to a backup file. It never resets Tower state or worktrees.',
+    parameters: RecoverInput,
+    output: output(SCHEMAS.recover),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'recover Tower state')
+      const lock = await readStateLock(tower.paths)
+      const publicLock = lock.record
+        ? { pid: lock.record.pid ?? null, startedAt: lock.record.startedAt ?? null, at: lock.record.at ?? null, alive: lock.alive }
+        : null
+      if (args.action === RECOVERY_ACTION.status) {
+        return { ok: true, action: RECOVERY_ACTION.status, stateLock: publicLock, cleared: false }
+      }
+      if (args.confirm !== RECOVERY_CONFIRM) {
+        throw new TowerToolError('invalid-argument', 'clear-stale-lock requires confirm:"CLEAR_STALE_LOCK"')
+      }
+      if (!lock.record) return { ok: true, action: RECOVERY_ACTION.clearStaleLock, stateLock: null, cleared: false }
+      if (lock.alive !== false) {
+        throw new TowerToolError('state-locked', `state lock pid ${lock.record.pid ?? ROLE.unknown} is still alive; refusing to clear it`)
+      }
+      const backup = `${tower.paths.lock}.recovered-${Date.now()}`
+      await fsp.rename(tower.paths.lock, backup)
+      return { ok: true, action: RECOVERY_ACTION.clearStaleLock, stateLock: publicLock, cleared: true, backup }
+    },
+  })
+}

package/tools/reload.js

@@ -0,0 +1,52 @@
+// tower_reload: dev-only HMR reload request.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { runtimeConfig } from '../lib/config.js'
+import { createHmrBridge } from '../lib/hmr.js'
+import { ReloadInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any, sharedHmrBridge: any }} deps
+ */
+export function registerReloadTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor, sharedHmrBridge } = deps
+  // Dev-only hot reload. The tool is registered whenever dev.hotReload is on;
+  // it reports reload-unavailable when the profile has no HMR service. When the
+  // Host passed a shared bridge, its status() reflects the command's reloads too.
+  const dev = runtimeConfig().dev ?? {}
+  if (dev.hotReload !== false) {
+    const bridge =
+      sharedHmrBridge ??
+      createHmrBridge(ctx, {
+        requiredIds: dev.reloadRequiredIds,
+        delayMs: dev.reloadDelayMs,
+        logger: ctx.logger ?? console,
+      })
+    define(ctx, {
+      name: 'tower_reload',
+      description:
+        'Dev-only: ask DSH HMR to reconcile this profile and reload the Tower Host plugin from disk. The reload is scheduled a few milliseconds after this call returns (so the result reaches the model first). Use after editing the plugin source in a linked profile; plugin_manager install/update already triggers reconciliation by itself. Registered while dev.hotReload is on; fails with reload-unavailable when the HMR service is absent.',
+      parameters: ReloadInput,
+      output: output(SCHEMAS.reload),
+      async execute(args, exec) {
+        if (typeof args.repoRoot === 'string') {
+          const tower = await Tower.open(args.repoRoot)
+          const actor = await actorFor(tower, exec)
+          requireTowerActor(actor, 'reload the Tower plugin')
+        }
+        if (!bridge.available) {
+          throw new TowerToolError('reload-unavailable', 'this DSH profile has no HMR service; restart DSH instead')
+        }
+        const outcome = bridge.schedule()
+        return {
+          ok: true,
+          ...outcome,
+          ...(outcome.lastError ? { error: outcome.lastError } : {}),
+          restartHint: 'If the new code does not appear, restart DSH or check the profile hmr entry.',
+        }
+      },
+    })
+  }
+}