dsh-tower 2.6.0 → 2.7.0

package/app/spawn-support.js

@@ -1,7 +1,55 @@
 // 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 { shapeFor } from '../domain/shapes/index.js'
+import { roleBriefingKind, rolePlacement } from '../domain/roles.js'
 import { workerBriefing, reviewerBriefing } from './briefing.js'
 
+/**
+ * Resolve where a spawn runs (#149 W3). A worker gets the shape's provisioning
+ * (branch worktree, shared checkout, or detached survey sandbox); a reviewer
+ * gets a disposable detached checkout at the recorded branch tip, so the
+ * verdict is stamped with a commit instead of a live worktree HEAD.
+ * @param {any} tower
+ * @param {{ role: string, context: any, missionId: string, name: string, worktreeRoot?: string, includeDirtyBase?: boolean, instructions?: string }} input
+ */
+export async function provisionSpawnPlacement(tower, { role, context, missionId, name, worktreeRoot, includeDirtyBase, instructions }) {
+  // #149 W4: the role contract decides the placement; the shape supplies the
+  // mission provisioning facts it does not own.
+  const reviewCheckout = rolePlacement(role) === 'review-checkout'
+  const shape = shapeFor(context.mission.kind)
+  const provisioned = reviewCheckout
+    ? null
+    : await tower.provision({ missionId, worktreeRoot, includeDirtyBase: includeDirtyBase !== false })
+  const review = reviewCheckout
+    ? await tower.provisionReviewCheckout({ missionId, name, worktreeRoot })
+    : null
+  const mission = review ? review.mission : provisioned.mission
+  const worktree = review ? mission.worktree : provisioned.worktree
+  const cwd = review ? review.path : (provisioned.cwd ?? worktree.path)
+  const branch = worktree?.branch ?? null
+  // The briefing must describe the checkout that actually exists: a detached
+  // sandbox is recorded only after provision, so use the provisioned mission.
+  const briefing = buildSpawnBriefing({
+    role,
+    towerRoot: tower.root,
+    context: /** @type {any} */ ({ ...context, mission }),
+    worktree,
+    review,
+    instructions,
+  })
+  return {
+    mission,
+    worktree,
+    cwd,
+    branch,
+    review,
+    briefing,
+    provisioning: review ? 'review-checkout' : (provisioned.provisioning ?? shape.provisioning),
+    created: review ? true : provisioned.created,
+    sandbox: provisioned?.sandbox ?? null,
+  }
+}
+
 /**
  * @param {any} model
  */
@@ -14,25 +62,28 @@ export function buildAgentOptions(model) {
 }
 
 /**
- * @param {{ role: string, towerRoot: string, context: any, worktree: any, instructions: string | undefined }} input
+ * @param {{ role: string, towerRoot: string, context: any, worktree: any, review?: 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 },
-  }
+export function buildSpawnBriefing({ role, towerRoot, context, worktree, review = null, instructions }) {
+  // Only a shape that owns a worktree gets the git checkout projection; a survey
+  // reads the shared checkout and must not see a worktree record it does not own.
+  const shape = shapeFor(context.mission.kind)
+  const mission = shape.fields.worktree
+    ? { ...context.mission, worktree: { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit } }
+    : { ...context.mission }
   const briefing = {
     repoRoot: towerRoot,
     base: context.base,
     mission,
     deps: context.deps,
-    worktree,
+    worktree: worktree ?? null,
+    review,
     instructions,
     reviews: context.reviews,
     findings: context.findings,
     completionReport: context.completionReport,
   }
-  return role === 'worker' ? workerBriefing(briefing) : reviewerBriefing(briefing)
+  return roleBriefingKind(role) === 'reviewer' ? reviewerBriefing(briefing) : workerBriefing(briefing)
 }
 
 /**

package/app/spawn.js

@@ -96,6 +96,9 @@ export async function recordSpawn(tower, input) {
     const now = Date.now()
     const entry = recordSpawnEntry({
       roster: state.roster,
+      // The live-worker count resolves each roster row's kind, so the whole
+      // mission list is required: a survey row is not a build worker (#148).
+      missions: state.missions,
       mission,
       input,
       spawnTip,

package/app/teardown.js

@@ -21,6 +21,106 @@ import {
   teardownRemovedDecision,
 } from '../domain/integration/teardown.js'
 import { sweepArchive } from './archive.js'
+import { cleanupSandbox } from './sandbox.js'
+import { cleanupReviewCheckout } from './reviewCheckout.js'
+
+/**
+ * Disposable review checkouts (#149 W3). A reviewer works in a detached checkout
+ * at its recorded review commit and the checkout is removed when the verdict is
+ * recorded; a failed spawn or an interrupted reviewer leaves it behind, so
+ * teardown retries the bounded removal and clears the recorded path. A checkout
+ * whose reviewer is still active is kept. This runs before the worktree phase so
+ * its state revisions never invalidate the worktree claims.
+ * @param {any} tower
+ * @param {any} input
+ * @returns {Promise<{ decisions: any[], removed: string[] }>}
+ */
+async function teardownReviewCheckouts(tower, input) {
+  const state = await tower.load()
+  const exclude = new Set(input.exclude ?? [])
+  const decisions = []
+  const removed = []
+  for (const entry of state.roster ?? []) {
+    const checkout = typeof entry.reviewCheckout === 'string' ? entry.reviewCheckout : null
+    if (!checkout) continue
+    const row = { name: entry.name, missionId: entry.missionId ?? null, checkout }
+    if (exclude.has(entry.missionId)) {
+      decisions.push({ ...row, action: 'keep', reason: 'excluded' })
+      continue
+    }
+    if (entry.state === 'active') {
+      decisions.push({ ...row, action: 'keep', reason: 'reviewer is active' })
+      continue
+    }
+    if (input.dryRun === true) {
+      decisions.push({ ...row, action: 'remove', reason: 'eligible' })
+      continue
+    }
+    const outcome = await cleanupReviewCheckout(tower, { name: entry.name, missionId: entry.missionId })
+    if (!outcome || outcome.removal.ok) {
+      decisions.push({ ...row, action: 'removed', reason: outcome ? 'checkout was already gone' : 'checkout and record were already gone' })
+      removed.push(entry.name)
+      continue
+    }
+    decisions.push({
+      ...row,
+      action: 'keep',
+      reason: `checkout cleanup failed after ${outcome.removal.attempts} attempt(s): ${outcome.removal.error}`,
+    })
+  }
+  return { decisions, removed }
+}
+
+/**
+ * Disposable detached survey sandboxes (#148 W2). A terminal survey may still
+ * carry a sandbox after a failed cleanup; teardown retries with the same bounded
+ * removal as completion. Run before the worktree phase so its state revisions
+ * never invalidate the worktree claims.
+ * @param {any} tower
+ * @param {any} input
+ * @returns {Promise<{ decisions: any[], removed: string[] }>}
+ */
+async function teardownSandboxes(tower, input) {
+  const state = await tower.load()
+  const activity = input.activity ?? {}
+  const exclude = new Set(input.exclude ?? [])
+  const decisions = []
+  const removed = []
+  for (const mission of state.missions) {
+    const sandbox = typeof /** @type {any} */ (mission).sandbox === 'string' ? /** @type {any} */ (mission).sandbox : null
+    if (!sandbox) continue
+    if (exclude.has(mission.id)) {
+      decisions.push({ missionId: mission.id, action: 'keep', sandbox, reason: 'excluded' })
+      continue
+    }
+    if (hasLiveAgent(state, mission.id, activity)) {
+      decisions.push({ missionId: mission.id, action: 'keep', sandbox, reason: 'live agent' })
+      continue
+    }
+    if (!['completed', 'abandoned'].includes(mission.status)) {
+      decisions.push({ missionId: mission.id, action: 'keep', sandbox, reason: `mission is ${mission.status}` })
+      continue
+    }
+    if (input.dryRun === true) {
+      decisions.push({ missionId: mission.id, action: 'remove', sandbox, reason: 'eligible' })
+      continue
+    }
+    const outcome = await cleanupSandbox(tower, mission.id)
+    if (!outcome) {
+      decisions.push({ missionId: mission.id, action: 'removed', sandbox, reason: 'sandbox was already gone' })
+      removed.push(mission.id)
+      continue
+    }
+    if (outcome.ok) removed.push(mission.id)
+    decisions.push({
+      missionId: mission.id,
+      action: outcome.ok ? 'removed' : 'keep',
+      sandbox,
+      ...(outcome.ok ? {} : { reason: `sandbox cleanup failed after ${outcome.attempts} attempt(s): ${outcome.error}` }),
+    })
+  }
+  return { decisions, removed }
+}
 
 /**
  * Phase 1 (#51): decide every keep/remove outcome without holding the state
@@ -87,8 +187,23 @@ async function claimRemoval(tower, candidate, expectedRevision, input) {
 }
 
 export async function teardown(tower, input) {
+  // Sandbox cleanup runs first: it owns its own short locks and revisions, so
+  // the worktree prepare/act/commit phases below see a stable revision.
+  // Review checkout cleanup first: it owns its own short locks and revisions, so
+  // the worktree prepare/act/commit phases below see a stable revision.
+  const reviews = await teardownReviewCheckouts(tower, input)
+  const sandboxes = await teardownSandboxes(tower, input)
   const prepared = await prepareTeardown(tower, input)
-  if (prepared.dryRun) return { ok: true, dryRun: true, removed: [], decisions: prepared.decisions }
+  if (prepared.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      removed: [],
+      decisions: [...reviews.decisions, ...sandboxes.decisions, ...prepared.decisions],
+      reviewCheckoutsRemoved: [],
+      sandboxesRemoved: [],
+    }
+  }
 
   const removed = []
   let expectedRevision = prepared.stateRevision
@@ -197,7 +312,9 @@ export async function teardown(tower, input) {
     ok: true,
     dryRun: false,
     removed,
-    decisions: prepared.decisions,
+    decisions: [...reviews.decisions, ...sandboxes.decisions, ...prepared.decisions],
+    reviewCheckoutsRemoved: reviews.removed,
+    sandboxesRemoved: sandboxes.removed,
     archived: archive.archived,
     ...(archive.error ? { archiveError: archive.error } : {}),
   }

package/app/tower.js

@@ -28,6 +28,7 @@ import { writeBoard, boardFile } from './board.js'
 import { archiveIndex, archivedMission } from './archive.js'
 import { recordSpawnOutcome, recordInterrupt, reserveRoster, recordSpawn, rosterView } from './spawn.js'
 import { recordTestRun, recordLegacySnapshot, recordLegacyMap } from './recording.js'
+import { resolveLegacySurveyRead } from './sharedCheckout.js'
 
 export const ROLES = ['worker', 'reviewer']
 const MAX_REVIEW_ROUNDS = 5
@@ -99,6 +100,7 @@ import { rebase } from './rebase.js'
 import { merge } from './merge.js'
 import { init } from './init.js'
 import { provision } from './provision.js'
+import { provisionReviewCheckout } from './reviewCheckout.js'
 import { addFinding, readFindings, findings } from './findings.js'
 import { recordMessage, recordDelivery, inbox } from './messages.js'
 import { createBatch, closeBatch, abandonBatch, batchStatus } from './batch.js'
@@ -170,6 +172,20 @@ export class Tower {
     return (await this.git(cwd, ['rev-parse', ref])).trim()
   }
 
+  /**
+   * The commit a mission branch points at, resolved from the branch ref. Never
+   * reads a live worktree checkout: a checkout is a view, the ref is the fact
+   * (#149 W3 review evidence and every tip comparison use this).
+   * @param {{ id?: string, worktree?: { branch?: string } | null }} mission
+   */
+  async branchTip(mission) {
+    const branch = mission?.worktree?.branch
+    if (typeof branch !== 'string' || branch.length === 0) {
+      fail(`mission ${mission?.id ?? ''} has no branch to resolve`.replace('  ', ' '), 'invalid-argument')
+    }
+    return this.revParse(this.root, `refs/heads/${branch}`)
+  }
+
   async isClean(cwd) {
     return (await this.git(cwd, ['status', '--porcelain'])).trim().length === 0
   }
@@ -193,6 +209,9 @@ export class Tower {
       paths: this.paths,
       now: this.deps.clock?.now ? this.deps.clock.now() : Date.now(),
       persist: options.persist,
+      // A legacy survey planned but never provisioned recorded no base; the
+      // loader resolves it once, from this checkout, before the pure migration.
+      resolveLegacySurvey: (rawState) => resolveLegacySurveyRead(this, rawState),
     })
     this.stateLoad = { ...loaded.version, migration: loaded.migration }
     return loaded.state
@@ -279,6 +298,15 @@ export class Tower {
     return provision(this, input)
   }
 
+  /**
+   * Provision the disposable detached review checkout for a reviewer (#149 W3).
+   * The commit it returns is the reviewer's evidence for every later read and
+   * the verdict stamp.
+   */
+  async provisionReviewCheckout(input = {}) {
+    return provisionReviewCheckout(this, input)
+  }
+
   async missionContext(missionId) {
     return missionContext(this, missionId)
   }
@@ -521,7 +549,7 @@ export class Tower {
     let branchTip
     try {
       baseTip = await this.revParse(this.root, state.base)
-      branchTip = await this.revParse(mission.worktree.path, 'HEAD')
+      branchTip = await this.branchTip(mission)
     } catch {
       return null
     }

package/cordis.patch.yml

@@ -110,3 +110,53 @@
             name: '@deepseek-ai/dsh-tool-fs-search'
             config:
               sampleOverCapGlobResults: false
+    # #148 D7/W2: one visible survey capability row. The group is the switch:
+    # both the read-only preset and the detached-sandbox preset are nested
+    # dependencies of it, so the sandbox placement is tuning and adds no second
+    # visible component. Off means a survey cannot be planned (tower_plan refuses
+    # with an actionable code) and no survey agent can be dispatched; build
+    # missions are unaffected. Read-only remains structural for the shared
+    # placement (the preset allow-list has no write, edit, or shell tool); the
+    # sandbox preset exists only for `survey.sandbox: 'detached'`.
+    - id: tower-survey
+      name: cordis:group
+      group: true
+      config:
+        - id: preset-tower-survey
+          name: 'dsh-tower/preset-survey'
+          config:
+            id: tower-survey
+            name: Tower Survey
+            description: Read-only inspection of one recorded commit in the shared checkout.
+            order: 62
+            plugins:
+              - id: tower-survey-policy
+                name: 'dsh-tower/survey'
+              - id: tower-survey-fs
+                name: '@deepseek-ai/dsh-tool-fs'
+                config:
+                  write: false
+                  edit: false
+                  readImage: false
+              - id: tower-survey-fs-search
+                name: '@deepseek-ai/dsh-tool-fs-search'
+                config:
+                  sampleOverCapGlobResults: false
+        - id: preset-tower-survey-sandbox
+          name: 'dsh-tower/preset-survey-sandbox'
+          config:
+            id: tower-survey-sandbox
+            name: Tower Survey Sandbox
+            description: Disposable detached checkout for a survey that may write or run commands while reading one recorded commit.
+            order: 63
+            plugins:
+              - id: tower-survey-sandbox-policy
+                name: 'dsh-tower/survey-sandbox'
+              - id: tower-survey-sandbox-fs
+                name: '@deepseek-ai/dsh-tool-fs'
+              - id: tower-survey-sandbox-fs-search
+                name: '@deepseek-ai/dsh-tool-fs-search'
+                config:
+                  sampleOverCapGlobResults: false
+              - id: tower-survey-sandbox-pwsh
+                name: '@deepseek-ai/dsh-tool-pwsh'