dsh-tower 2.5.0 → 2.7.0

package/tools/preflight.js

@@ -12,7 +12,7 @@ export function registerPreflightTool(ctx, 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.',
+      'Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards) and warnings (survey-stale). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.mode is required; review.mode off and optional skip them. survey-stale reports a build dependency on a survey whose readCommit is not an ancestor-or-equal of the build base; it is a warning by default and a blocker only when gates.requireFreshSurvey is true. A survey has no merge gate: it is refused with invalid-transition (tower_complete checks HEAD/readCommit and zero commits). Never changes anything.',
     parameters: PreflightInput,
     aliases: {"missionId":["id"]},
     requiresMissionId: true,
@@ -20,10 +20,11 @@ export function registerPreflightTool(ctx, deps) {
     async execute(args) {
       const tower = await deps.openTower(args.repoRoot)
       const { activity, parentStatus } = await observeActivity(ctx, tower)
-      const gate = await tower.evaluateGate({ missionId: args.missionId, activity, parentStatus })
+      const gate = await tower.evaluateGate({ missionId: args.missionId, activity, parentStatus, action: 'preflight' })
       return {
         ok: gate.ok,
         blockers: gate.blockers,
+        warnings: gate.warnings ?? [],
         missionId: args.missionId,
         branchTip: gate.branchTip ?? null,
         baseTip: gate.baseTip ?? null,

package/tools/review.js

@@ -13,7 +13,7 @@ export function registerReviewTool(ctx, deps) {
   define(ctx, {
     name: 'tower_review',
     description:
-      'Submit an independent review verdict bound to the current branch tip: a completed mission starts a review round, and while the mission is active a later route may still record a verdict for that same reviewed tip, appending to the same round without changing the status (a moved tip is rejected with an explanation). status is "clean", "p1-Nitems", or "p2-Nitems"; merge is "merge", "fix-then-merge", or "hold" (only clean + merge is later approval). Non-clean returns the mission to active. Reviewers are capped at 5 rounds per branch; a tower-submitted review is break-glass and requires breakGlassReason.',
+      'Submit an independent review verdict bound to the current branch tip: a completed mission starts a review round, and while the mission is active a later route may still record a verdict for that same reviewed tip, appending to the same round without changing the status (a moved tip is rejected with an explanation). status is "clean", "p1-Nitems", or "p2-Nitems"; merge is "merge", "fix-then-merge", or "hold" (only clean + merge is later approval). Non-clean returns the mission to active. Reviewers are capped at 5 rounds per branch; a tower-submitted review is break-glass and requires breakGlassReason. The tool is not registered when review.mode is off.',
     parameters: ReviewInput,
     aliases: {"missionId":["id"]},
     requiresMissionId: true,

package/tools/spawn.js

@@ -2,47 +2,27 @@
 import { SCHEMAS, output } from '../domain/contracts/outputs.js'
 import { TowerToolError, classifyError } from '../domain/errors.js'
 import { SpawnInput } from '../domain/contracts/tool-inputs/index.js'
-import { DEFAULT_ROLE, ROLES as ROLE_ENUM, SPAWN_OUTCOME, isCompletedStopReason, isReviewerRole, isSpawnAdmission, isWorkerRole } from '../domain/vocabulary.js'
+import { defaultPresetFor, shapeFor } from '../domain/shapes/index.js'
+import { DEFAULT_ROLE, ROLES as ROLE_ENUM, SPAWN_OUTCOME, isCompletedStopReason, isSpawnAdmission } from '../domain/vocabulary.js'
+import { resolveRoleSpawn, roleSpawnDiscovery } from '../domain/roles.js'
 import {
   assertSpawnableMission,
   precheckSpawnServices,
   precheckWorkerOwnership,
   resolveRosterName,
 } from '../app/spawn-prechecks.js'
-import { buildAgentOptions, buildSpawnBriefing, waitForSpawnResult } from '../app/spawn-support.js'
-
-/**
- * @param {any} ctx
- * @param {{
- *   define: import('../types/index.js').DefineTool,
- *   openTower: any,
- *   actorFor: any,
- *   requireTowerActor: any,
- *   enqueueSpawn: any,
- *   observeActivity: any,
- *   spawnBackoffState: any,
- *   recordSpawnThrottle: any,
- *   recordSpawnSuccess: any,
- *   runMissionDiscovery: any,
- *   textOf: any, inspectLeases: any,
- *   leaseComponent?: () => { enabled: boolean, reason: string },
- * }} deps
- */
+import { buildAgentOptions, provisionSpawnPlacement, waitForSpawnResult } from '../app/spawn-support.js'
+import { cleanupReviewCheckout } from '../app/reviewCheckout.js'
+/** @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, [key: string]: any }} deps */
 export function registerSpawnTool(ctx, deps) {
-  const {
-    define, actorFor, requireTowerActor, enqueueSpawn, observeActivity,
-    spawnBackoffState, recordSpawnThrottle, recordSpawnSuccess,
-    runMissionDiscovery, textOf,
-  } = deps
+  const { define, actorFor, requireTowerActor, enqueueSpawn, observeActivity, spawnBackoffState, recordSpawnThrottle, recordSpawnSuccess, runMissionDiscovery, textOf } = deps
   define(ctx, {
     name: 'tower_spawn',
     description:
-      'Spawn a worker or reviewer for a mission. Workers use the tower-worker preset; reviewers require a completed mission and use the read-only tower-reviewer preset. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing, and starts a background subagent in that worktree. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns record the branch tip so a reviewer that modifies the branch cannot submit a review. Returns immediately unless wait=true.',
-    parameters: SpawnInput,
+      'Spawn a worker or reviewer for a mission. Workers use the mission shape\'s preset (tower-worker for a build, tower-survey for a read-only shared survey, tower-survey-sandbox for a detached survey with survey.sandbox=detached); reviewers require a completed build mission and use the read-only tower-reviewer preset, and the reviewer role is refused when review.mode is off. A build provisions (or reuses) the mission git worktree and branch; a shared survey runs in the shared checkout because it reads one commit; a detached survey provisions (or reuses) a disposable detached worktree at its readCommit with no branch. Generates a self-contained briefing (including dependency survey result evidence) and starts a background subagent. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns get a disposable detached checkout at the recorded branch tip, and the verdict is stamped with that commit (never a live worktree HEAD). Returns immediately unless wait=true.', parameters: SpawnInput,
     aliases: {"missionId":["id"],"waitMs":["wait_ms"]},
-    requiresMissionId: true,
-    board: true,
-    output: output(SCHEMAS.spawn),
+    requiresMissionId: true, board: true, output: output(SCHEMAS.spawn),
     async execute(args, exec) {
       const tower = await deps.openTower(args.repoRoot)
       const actor = await actorFor(tower, exec)
@@ -51,10 +31,18 @@ export function registerSpawnTool(ctx, deps) {
       if (!ROLE_ENUM.includes(role)) throw new TowerToolError('invalid-argument', `role must be one of ${ROLE_ENUM.join('|')}`)
       // Repository config (if any) already overrides the profile config here.
       const config = tower.config
-      const preset = isReviewerRole(role) ? config.spawn.reviewerPreset : config.spawn.workerPreset
-      const model = isReviewerRole(role) ? config.spawn.reviewerModel : config.spawn.workerModel
       const context = await tower.missionContext(args.missionId)
-      assertSpawnableMission({ role, context })
+      assertSpawnableMission({ role, context, config })
+      const shape = shapeFor(context.mission.kind)
+      // #148 W2: the shape resolves its preset from tuning config, so a detached
+      // survey gets the sandbox preset and a shared survey stays read-only.
+      // #149 W4: role resolution (preset row, model route, placement, briefing)
+      // is one contract, orthogonal to the shape that supplies the facts.
+      const shapePreset = defaultPresetFor(context.mission.kind, config, context.mission)
+      const roleSpawn = resolveRoleSpawn(role, { config, shape, shapePreset })
+      if (!roleSpawn) throw new TowerToolError('invalid-argument', `role must be one of ${ROLE_ENUM.join('|')}`)
+      const preset = roleSpawn.preset
+      const model = roleSpawn.model
       const spawned = await enqueueSpawn(tower.root, async () => {
         const observed = await observeActivity(ctx, tower)
         await tower.reconcileObservedInactive(observed.activity)
@@ -65,26 +53,25 @@ export function registerSpawnTool(ctx, deps) {
         }
         const view = await tower.rosterView()
         const name = resolveRosterName({ role, missionId: args.missionId, requested: args.name, roster: view.roster })
-        const takeover = await precheckWorkerOwnership({
-          role, tower, ctx, view, missionId: args.missionId, takeover: args.takeover,
-          maxLiveWorkers: config.spawn.maxLiveWorkers, budget: backoff.budget, observeActivity,
-        })
+        const takeover = await precheckWorkerOwnership({ role, tower, ctx, view, missionId: args.missionId, takeover: args.takeover, maxLiveWorkers: config.spawn.maxLiveWorkers, budget: backoff.budget, observeActivity })
         const { subagents, provider } = await precheckSpawnServices({
           tower, ctx, config, preset, actor, exec, inspectLeases: deps.inspectLeases,
           // #131: the app layer only needs the row fact; the root owns the registry.
           leaseComponent: deps.leaseComponent,
         })
 
-        const provisioned = await tower.provision({
-          missionId: args.missionId,
+        const { mission, worktree, cwd, branch, review, briefing, provisioning, created, sandbox } = await provisionSpawnPlacement(tower, {
+          role,
+          context,
+          missionId: /** @type {string} */ (args.missionId),
+          name,
           worktreeRoot: args.worktreeRoot,
-          includeDirtyBase: args.includeDirtyBase !== false,
+          includeDirtyBase: args.includeDirtyBase,
+          instructions: args.instructions,
         })
-        const { mission, worktree } = provisioned
-        const briefing = buildSpawnBriefing({ role, towerRoot: tower.root, context, worktree, instructions: args.instructions })
         const agentOptions = buildAgentOptions(model)
 
-        if (isWorkerRole(role) && isSpawnAdmission(tower.config.tests?.admission)) {
+        if (roleSpawnDiscovery(role, shape) && isSpawnAdmission(tower.config.tests?.admission)) {
           const discovery = await runMissionDiscovery(tower, mission)
           if (discovery.configured && discovery.receipt.ok !== true) {
             throw new TowerToolError(
@@ -102,15 +89,17 @@ export function registerSpawnTool(ctx, deps) {
           name,
           role,
           parentSessionId: String(exec.agent.id),
-          cwd: worktree.path,
-          branch: worktree.branch,
+          cwd,
+          branch,
+          reviewCommit: review?.commit,
+          reviewCheckout: review?.path,
         })
         try {
           activation = await subagents.startActivation({
             provider,
             label: name,
             request: {
-              cwd: worktree.path,
+              cwd,
               agentPreset: preset,
               prompt: [{ type: 'text', text: briefing }],
               parent: exec.agent,
@@ -127,8 +116,10 @@ export function registerSpawnTool(ctx, deps) {
             role,
             agentId,
             parentSessionId: String(exec.agent.id),
-            cwd: worktree.path,
-            branch: worktree.branch,
+            cwd,
+            branch,
+            reviewCommit: review?.commit,
+            reviewCheckout: review?.path,
             takeover,
           })
           recordSpawnSuccess(tower.root, config.spawn.maxLiveWorkers)
@@ -152,6 +143,10 @@ export function registerSpawnTool(ctx, deps) {
               detail: `spawn failed${agentId ? ` after activation ${agentId}` : ' before activation'}: ${String(error?.message ?? error).slice(0, 300)}`,
             })
             .catch(() => {})
+          // A failed review spawn must not leak its detached evidence checkout.
+          if (review) {
+            await cleanupReviewCheckout(tower, { name, missionId: mission.id }).catch(() => {})
+          }
           throw error
         }
 
@@ -167,8 +162,11 @@ export function registerSpawnTool(ctx, deps) {
           provider,
           maxDepth: config.spawn.maxDepth ?? 1,
           ...(Object.keys(agentOptions).length > 0 ? { agentOptions } : {}),
-          worktree: { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit },
-          created: provisioned.created,
+          worktree: worktree ? { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit } : null,
+          sandbox,
+          review: review ? { commit: review.commit, checkout: review.path } : null,
+          provisioning,
+          created,
           briefingChars: briefing.length,
           takeover,
           rosterEntry: entry,

package/tools/status.js

@@ -4,6 +4,7 @@ import { classifyError } from '../domain/errors.js'
 import { StatusInput } from '../domain/contracts/tool-inputs/index.js'
 import { ROSTER_INACTIVE_STATES, isMarkdownFormat, isReservedState, isWorkerRole } from '../domain/vocabulary.js'
 import { archiveView } from '../app/archive.js'
+import { reviewPolicyView } from '../domain/integration/review.js'
 
 /**
  * @param {any} ctx
@@ -21,7 +22,7 @@ export function registerStatusTool(ctx, deps) {
   define(ctx, {
     name: 'tower_status',
     description:
-      'Read the Tower dashboard for a repository: state path, base branch, revision, mission status counts, paged mission summaries (scope/deps/tasks/worktree/owner), roster size, findings, archive count, config path and the activity tail. Also reports the repo-scoped git lock holder (`gitLock: {held,pid,phase,heldMs}`) so a merge holding the mutex is visible. Pass missionId for one full mission (tasks, notes, reviews, findings, completion report; archived missions are loaded from their year file); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; includeArchived appends compact archived summaries after the active page; format:"markdown" returns the human-readable mission board (active missions plus an archived count). Read-only.',
+      'Read the Tower dashboard for a repository: state path, base branch, revision, mission status counts, paged mission summaries (scope/deps/tasks/worktree/owner), roster size, findings, archive count, config path and the activity tail. Also reports the repo-scoped git lock holder (`gitLock: {held,pid,phase,heldMs}`) so a merge holding the mutex is visible, and the resolved review policy (`review: {mode, available, required, detail}`; mode off means review is intentionally unavailable). Pass missionId for one full mission (tasks, notes, reviews, findings, completion report; archived missions are loaded from their year file); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; includeArchived appends compact archived summaries after the active page; format:"markdown" returns the human-readable mission board (active missions plus an archived count). Read-only.',
     parameters: StatusInput,
     aliases: { mission_id: ['missionId'], include_gate: ['includeGate'], include_archived: ['includeArchived'] },
     output: output(SCHEMAS.status),
@@ -38,6 +39,10 @@ export function registerStatusTool(ctx, deps) {
         (entry) => isWorkerRole(entry.role) && !ROSTER_INACTIVE_STATES.includes(entry.state) && !isReservedState(entry.state),
       ).length
       const spawn = spawnBackoffView(tower.root, tower.config.spawn?.maxLiveWorkers, inflight)
+      // #M39: the resolved review policy (`{mode, available, required, detail}`)
+      // is a first-class dashboard fact. In `off` the detail says review is
+      // intentionally unavailable rather than leaving it as a silent absence.
+      const review = reviewPolicyView(tower.config)
       if (args.missionId) {
         const [status, detail] = await Promise.all([
           tower.status({ missionIds: [args.missionId] }),
@@ -51,6 +56,7 @@ export function registerStatusTool(ctx, deps) {
           boardPath,
           mode,
           spawn,
+          review,
           components,
         }
       }
@@ -96,6 +102,7 @@ export function registerStatusTool(ctx, deps) {
         boardPath,
         mode,
         spawn,
+        review,
         components,
       }
       if (isMarkdownFormat(args.format)) {

package/tools/test.js

@@ -46,6 +46,8 @@ export function registerTestTool(ctx, deps) {
         return { ok: false, configured: false, error, tests: [], commands: [] }
       }
       const receipt = discovery.receipt
+      // #149 W4: the receipt is returned as recorded; there is no derived
+      // `checks` copy. Completion/batch read it through domain/evidence.js.
       return {
         ok: receipt.ok === true,
         configured: true,
@@ -54,7 +56,6 @@ export function registerTestTool(ctx, deps) {
         commands: receipt.commands ?? [],
         error: receipt.error ?? undefined,
         receipt,
-        checks: discovery.check ? [discovery.check] : [],
       }
     },
   })

package/types/index.d.ts

@@ -57,6 +57,7 @@ export type ErrorCode =
   | 'provider-cooldown'
   | 'preset-missing'
   | 'reviewer-prerequisite'
+  | 'review-disabled'
   | 'not-authorized'
   | 'workspace-busy'
   | 'worker-limit'
@@ -73,6 +74,15 @@ export type ErrorCode =
   | 'tool-internal'
 // generated:vocabulary:end
 
+/**
+ * Review policy mode (#M39): `off` (review intentionally unavailable),
+ * `optional` (available, never required; default) or `required` (a clean review
+ * bound to the branch tip is a merge blocker). The deprecated
+ * `review.requireReview` boolean normalizes to this: true -> required,
+ * false -> optional.
+ */
+export type ReviewMode = 'off' | 'optional' | 'required'
+
 /** One machine-readable gate/completion blocker: a stable code plus a detail. */
 export interface Blocker {
   code: string
@@ -139,11 +149,25 @@ export interface RebaseRecord {
   baseTip?: string
 }
 
-export interface Mission {
+/** Evidence a survey may record when it completes (optional). */
+export interface SurveyResult {
+  paths?: string[]
+  symbols?: string[]
+  /** Ordered plan / next steps the read recommends (bounded array of strings). */
+  plan?: string[]
+  notes?: string
+  [key: string]: unknown
+}
+
+/**
+ * Fields every mission carries regardless of shape. The per-shape arms below
+ * declare which document dimensions a kind owns; the state schema v4 union and
+ * `domain/state/semantics.js` enforce the same split at runtime.
+ */
+export interface MissionBase {
   id: string
   title: string
   status: MissionStatus
-  kind: MissionKind
   scope: string[]
   deps: string[]
   /**
@@ -155,22 +179,59 @@ export interface Mission {
   blockers?: string[]
   reviewPolicy?: ReviewPolicy
   reviewExemptionReason?: string | null
-  worktree?: MissionWorktree | null
   owner?: string | null
   notes?: string[]
   completionReport?: CompletionReport | null
   testRuns?: TestRun[]
   rebase?: RebaseRecord | null
-  mergedCommit?: string | null
-  mergedAt?: number | null
   scopeGeneration?: number
   ownerGeneration?: number
   pauseCause?: string | null
   updatedAt?: number
   references?: string[]
   authorizationRef?: string | null
+  /**
+   * Survey evidence; the completion transition refuses a result on a shape that
+   * does not accept one, so the type stays permissive for the shared draft.
+   */
+  result?: SurveyResult | null
+}
+
+/** A build mission owns a private branch/worktree and lands by merging. */
+export interface BuildMission extends MissionBase {
+  kind: 'build'
+  worktree?: MissionWorktree | null
+  mergedCommit?: string | null
+  mergedAt?: number | null
+  readCommit?: never
+  readDirty?: never
+  sandbox?: never
+}
+
+/** A survey reads one commit in the shared checkout; it never merges. */
+export interface SurveyMission extends MissionBase {
+  kind: 'survey'
+  readCommit: string
+  readDirty?: string[]
+  result?: SurveyResult | null
+  /**
+   * #148 W2: the disposable detached sandbox path when `survey.sandbox` is
+   * `detached`. It has no branch and is removed on completion/abandon; a
+   * cleanup failure keeps the path plus `sandboxCleanupError` so the record and
+   * the filesystem do not silently disagree.
+   */
+  sandbox?: string
+  sandboxCleanupError?: string
+  sandboxRemovedAt?: number
+  worktree?: never
+  branch?: never
+  baseCommit?: never
+  mergedCommit?: never
+  mergedAt?: never
 }
 
+export type Mission = BuildMission | SurveyMission
+
 /**
  * Compact archived-mission entry (`archive/index.json`). It keeps enough of the
  * mission for ordering, dependency lookups and id allocation without loading the
@@ -245,6 +306,10 @@ export interface RosterEntry {
   missionId?: string | null
   parentSessionId?: string | null
   spawnTip?: string | null
+  /** The commit a reviewer's verdict is stamped with (#149 W3). */
+  reviewCommit?: string | null
+  /** The disposable detached checkout the reviewer reads, when recorded. */
+  reviewCheckout?: string | null
   stale?: boolean
   [key: string]: unknown
 }
@@ -316,6 +381,12 @@ export interface MissionSummary {
   reviewPolicy: ReviewPolicy
   mergedCommit: string | null
   mergedAt: number | null
+  /** Survey projection: the commit the survey read (null for a build). */
+  readCommit?: string | null
+  /** Survey projection: the tracked-status fingerprint captured at plan time. */
+  readDirty?: string[]
+  /** Survey projection: the disposable detached sandbox path (null otherwise). */
+  sandbox?: string | null
   /** Size of the completion report without loading its body; null when absent. */
   reportBytes: number | null
   updatedAt?: number