dsh-tower 2.5.0 → 2.7.0

package/adapters/legacy.js

@@ -12,16 +12,48 @@
 import { fsp } from './store-fs.js'
 import path from 'node:path'
 import crypto from 'node:crypto'
+import { isShapeKind } from '../domain/shapes/index.js'
 
 const SCHEMA_VERSION = 1
 const MAX_SNAPSHOT_BYTES = 16 * 1024 * 1024
 const DSH_STATUSES = ['planned', 'active', 'completed', 'blocked', 'paused', 'merged', 'abandoned']
-// Tower Codex also retires missions; retired is read-only history here.
+// Tower Codex also retires missions; `retired` is accepted input vocabulary and
+// is remapped below. It is never a DSH mission status.
 const CODEX_STATUSES = [...DSH_STATUSES, 'retired']
 const DSH_ID_RE = /^M\d+$/
 const CODEX_ID_RE = /^T\d{4,}$/
 const SHA256_RE = /^[a-f0-9]{64}$/
 
+// The strict adapter contract (#149 W4). One payload is exactly one legacy
+// format; every status and field alias this module accepts is declared here.
+// Missions are normalised to the shape registry's DSH vocabulary: a status
+// remap is applied and reported in `remapped`, never silently invented, and a
+// value the adapter cannot carry is reported in `unresolved`/`dropped`.
+export const LEGACY_FORMATS = Object.freeze({
+  'tower-codex': Object.freeze({
+    idPattern: CODEX_ID_RE,
+    idHint: 'T####',
+    statuses: CODEX_STATUSES,
+    statusRemap: Object.freeze({ retired: 'abandoned' }),
+    baseBranchField: 'baseBranch',
+    requiresBaseBranch: true,
+  }),
+  dsh: Object.freeze({
+    idPattern: DSH_ID_RE,
+    idHint: 'M#',
+    statuses: DSH_STATUSES,
+    statusRemap: Object.freeze({}),
+    baseBranchField: 'base',
+    requiresBaseBranch: false,
+  }),
+})
+
+// Only these fields cross the adapter boundary. Everything else a legacy
+// mission carries is validated for safety, then reported as dropped: the
+// adapter deliberately does not invent DSH semantics for it.
+const CARRIED_MISSION_FIELDS = Object.freeze(['id', 'status', 'kind'])
+const DROPPED_REASON = 'validated for safety but not carried into the summary; the exact payload bytes remain in the stored snapshot'
+
 function fail(code, message) {
   /** @type {Error & {code?: string}} */
   const error = new Error(message)
@@ -86,6 +118,9 @@ function invalidResult(error, format = null) {
     missionIds: [],
     missionCount: 0,
     paused: [],
+    unresolved: [],
+    dropped: [],
+    remapped: [],
     events: null,
     legacySnapshots: null,
     repoRoot: null,
@@ -140,31 +175,89 @@ function validateReviews(reviews, id) {
   return null
 }
 
+/**
+ * Detect one legacy format per payload. A declared `format` is authoritative;
+ * otherwise every mission id must belong to exactly one namespace. Empty
+ * mission lists use the top-level shape (a Tower Codex snapshot has a
+ * baseBranch; DSH state uses `base`).
+ * @param {any} payload
+ * @returns {{ format: 'tower-codex'|'dsh'|null, error: string|null }}
+ */
+function detectFormat(payload) {
+  if (payload.format !== undefined) {
+    if (typeof payload.format !== 'string' || !Object.prototype.hasOwnProperty.call(LEGACY_FORMATS, payload.format)) {
+      return { format: null, error: `unsupported legacy format ${JSON.stringify(payload.format)} (expected tower-codex or dsh)` }
+    }
+    return { format: payload.format, error: null }
+  }
+  if (payload.missions.length === 0) {
+    return { format: isNonEmptyString(payload.baseBranch) ? 'tower-codex' : 'dsh', error: null }
+  }
+  let codex = 0
+  let dsh = 0
+  for (const mission of payload.missions) {
+    const id = mission?.id
+    if (typeof id === 'string' && CODEX_ID_RE.test(id)) codex += 1
+    else if (typeof id === 'string' && DSH_ID_RE.test(id)) dsh += 1
+  }
+  if (codex === payload.missions.length) return { format: 'tower-codex', error: null }
+  if (dsh === payload.missions.length) return { format: 'dsh', error: null }
+  for (const mission of payload.missions) {
+    const id = mission?.id
+    if (typeof id !== 'string' || (!CODEX_ID_RE.test(id) && !DSH_ID_RE.test(id))) {
+      return {
+        format: null,
+        error: `unsupported legacy mission id ${JSON.stringify(id)} (expected T#### for Tower Codex or M# for DSH)`,
+      }
+    }
+  }
+  return { format: null, error: 'legacy snapshot mixes mission id namespaces (T#### and M#); one snapshot is one format' }
+}
+
 /**
  * @param {any} payload
  * @param {'tower-codex'|'dsh'} format
- * @returns {{error:string|null, missions:Array<{id:string,status:string,kind:string}>, missionIds:string[], paused:string[]}}
+ * @param {{ idPattern: RegExp, idHint: string, statuses: string[], statusRemap: Record<string, string>, baseBranchField: string, requiresBaseBranch: boolean }} spec
+ * @returns {{error:string|null, missions:Array<{id:string,status:string,kind:string}>, missionIds:string[], paused:string[],
+ *   unresolved:Array<{missionId:string, field:string, reason:string}>,
+ *   dropped:Array<{field:string, reason:string}>,
+ *   remapped:Array<{missionId:string, field:string, from:string, to:string}>}}
  */
-function validateMissions(payload, format) {
-  const statuses = format === 'tower-codex' ? CODEX_STATUSES : DSH_STATUSES
-  const idRe = format === 'tower-codex' ? CODEX_ID_RE : DSH_ID_RE
+function validateMissions(payload, format, spec) {
   const missions = []
   const missionIds = []
   const paused = []
+  const unresolved = []
+  const remapped = []
+  const droppedFields = new Set()
   const seen = new Set()
   for (let index = 0; index < payload.missions.length; index += 1) {
     const mission = payload.missions[index]
-    if (!isPlainObject(mission)) return { error: `missions[${index}] must be an object`, missions: [], missionIds: [], paused: [] }
-    if (typeof mission.id !== 'string' || !idRe.test(mission.id)) {
-      return { error: `missions[${index}] has unsupported id ${JSON.stringify(mission.id)} (expected ${format === 'tower-codex' ? 'T####' : 'M#'})`, missions: [], missionIds: [], paused: [] }
+    if (!isPlainObject(mission)) return { error: `missions[${index}] must be an object`, missions: [], missionIds: [], paused: [], unresolved: [], dropped: [], remapped: [] }
+    if (typeof mission.id !== 'string' || !spec.idPattern.test(mission.id)) {
+      return { error: `missions[${index}] has unsupported id ${JSON.stringify(mission.id)} (expected ${spec.idHint})`, missions: [], missionIds: [], paused: [], unresolved: [], dropped: [], remapped: [] }
     }
-    if (seen.has(mission.id)) return { error: `duplicate legacy mission id ${mission.id}`, missions: [], missionIds: [], paused: [] }
+    if (seen.has(mission.id)) return { error: `duplicate legacy mission id ${mission.id}`, missions: [], missionIds: [], paused: [], unresolved: [], dropped: [], remapped: [] }
     seen.add(mission.id)
-    if (typeof mission.status !== 'string' || !statuses.includes(mission.status)) {
-      return { error: `mission ${mission.id} has unknown status ${JSON.stringify(mission.status)}`, missions: [], missionIds: [], paused: [] }
+    if (typeof mission.status !== 'string' || !spec.statuses.includes(mission.status)) {
+      return { error: `mission ${mission.id} has unknown status ${JSON.stringify(mission.status)}`, missions: [], missionIds: [], paused: [], unresolved: [], dropped: [], remapped: [] }
+    }
+    const mappedStatus = spec.statusRemap[mission.status]
+    if (mappedStatus !== undefined) {
+      remapped.push({ missionId: mission.id, field: 'status', from: mission.status, to: mappedStatus })
+    }
+    const status = mappedStatus ?? mission.status
+    if (!DSH_STATUSES.includes(status)) {
+      return { error: `legacy status ${JSON.stringify(mission.status)} has no declared DSH mapping`, missions: [], missionIds: [], paused: [], unresolved: [], dropped: [], remapped: [] }
     }
-    if (mission.kind !== undefined && mission.kind !== 'build' && mission.kind !== 'survey') {
-      return { error: `mission ${mission.id} has unknown kind ${JSON.stringify(mission.kind)}`, missions: [], missionIds: [], paused: [] }
+    let kind = 'build'
+    if (mission.kind !== undefined) {
+      if (!isShapeKind(mission.kind)) {
+        return { error: `mission ${mission.id} has unknown kind ${JSON.stringify(mission.kind)}`, missions: [], missionIds: [], paused: [], unresolved: [], dropped: [], remapped: [] }
+      }
+      kind = mission.kind
+    } else {
+      unresolved.push({ missionId: mission.id, field: 'kind', reason: 'legacy mission has no kind; assumed build' })
     }
     for (const problem of [
       validateScope(mission.scope, mission.id),
@@ -172,13 +265,24 @@ function validateMissions(payload, format) {
       validateDeps(mission.deps, mission.id),
       validateReviews(mission.reviews, mission.id),
     ]) {
-      if (problem) return { error: problem, missions: [], missionIds: [], paused: [] }
+      if (problem) return { error: problem, missions: [], missionIds: [], paused: [], unresolved: [], dropped: [], remapped: [] }
     }
-    missions.push({ id: mission.id, status: mission.status, kind: mission.kind ?? 'build' })
+    for (const key of Object.keys(mission)) {
+      if (!CARRIED_MISSION_FIELDS.includes(key)) droppedFields.add(key)
+    }
+    missions.push({ id: mission.id, status, kind })
     missionIds.push(mission.id)
-    if (mission.status === 'paused') paused.push(mission.id)
+    if (status === 'paused') paused.push(mission.id)
+  }
+  return {
+    missions,
+    missionIds,
+    paused,
+    unresolved,
+    dropped: [...droppedFields].sort().map((field) => ({ field, reason: DROPPED_REASON })),
+    remapped,
+    error: null,
   }
-  return { missions, missionIds, paused, error: null }
 }
 
 /**
@@ -189,9 +293,12 @@ function validateMissions(payload, format) {
  *
  * @returns {{ok:boolean, format:'tower-codex'|'dsh'|null, schemaVersion:number|null,
  *   missions:Array<{id:string,status:string,kind:string}>, missionIds:string[],
- *   missionCount:number, paused:string[], events:number|null,
- *   legacySnapshots:number|null, repoRoot:string|null, baseBranch:string|null,
- *   error:string|null}}
+ *   missionCount:number, paused:string[],
+ *   unresolved:Array<{missionId:string, field:string, reason:string}>,
+ *   dropped:Array<{field:string, reason:string}>,
+ *   remapped:Array<{missionId:string, field:string, from:string, to:string}>,
+ *   events:number|null, legacySnapshots:number|null, repoRoot:string|null,
+ *   baseBranch:string|null, error:string|null}}
  */
 export function validateLegacySnapshot(payload) {
   if (!isPlainObject(payload)) return invalidResult('legacy snapshot must be a JSON object')
@@ -204,30 +311,26 @@ export function validateLegacySnapshot(payload) {
   }
   if (!Array.isArray(payload.missions)) return invalidResult('legacy snapshot has no missions array')
 
-  /** @type {'tower-codex'|'dsh'} */
-  let format = 'dsh'
-  if (payload.missions.length === 0) {
-    format = isNonEmptyString(payload.baseBranch) ? 'tower-codex' : 'dsh'
-  } else {
-    const firstId = payload.missions[0]?.id
-    if (typeof firstId === 'string' && CODEX_ID_RE.test(firstId)) format = 'tower-codex'
-    else if (typeof firstId === 'string' && DSH_ID_RE.test(firstId)) format = 'dsh'
-    else {
-      return invalidResult(
-        `unsupported legacy mission id ${JSON.stringify(firstId)} (expected T#### for Tower Codex or M# for DSH)`,
-      )
-    }
+  const detected = detectFormat(payload)
+  if (detected.error || !detected.format) {
+    return invalidResult(detected.error ?? 'legacy snapshot format could not be determined')
   }
+  const format = detected.format
+  const spec = LEGACY_FORMATS[format]
 
   const rejected = (error) => invalidResult(error, format)
-  const validated = validateMissions(payload, format)
+  const validated = validateMissions(payload, format, spec)
   if (validated.error) return rejected(validated.error)
 
   if (isNonEmptyString(payload.repoRoot) === false) {
     return rejected(`legacy ${format} snapshot has no repoRoot string`)
   }
-  if (format === 'tower-codex' && isNonEmptyString(payload.baseBranch) === false) {
-    return rejected('legacy tower-codex snapshot has no baseBranch string')
+  if (spec.requiresBaseBranch && isNonEmptyString(payload[spec.baseBranchField]) === false) {
+    return rejected(`legacy ${format} snapshot has no baseBranch string`)
+  }
+  const baseBranchValue = payload[spec.baseBranchField]
+  if (baseBranchValue !== undefined && baseBranchValue !== null && !isNonEmptyString(baseBranchValue)) {
+    return rejected(`legacy ${format} snapshot has no baseBranch string`)
   }
   if (payload.events !== undefined && !Array.isArray(payload.events)) {
     return rejected('legacy snapshot events must be an array')
@@ -247,10 +350,13 @@ export function validateLegacySnapshot(payload) {
     missionIds: validated.missionIds,
     missionCount: validated.missionIds.length,
     paused: validated.paused,
+    unresolved: validated.unresolved,
+    dropped: validated.dropped,
+    remapped: validated.remapped,
     events: Array.isArray(payload.events) ? payload.events.length : null,
     legacySnapshots: Array.isArray(payload.legacySnapshots) ? payload.legacySnapshots.length : null,
     repoRoot: payload.repoRoot.trim(),
-    baseBranch: format === 'tower-codex' ? payload.baseBranch.trim() : (isNonEmptyString(payload.base) ? payload.base.trim() : null),
+    baseBranch: isNonEmptyString(baseBranchValue) ? baseBranchValue.trim() : null,
     error: null,
   }
 }
@@ -342,6 +448,9 @@ export async function importLegacySnapshot(input = {}) {
     missionIds: validation.missionIds,
     paused: validation.paused,
     pausedCount: validation.paused.length,
+    unresolved: validation.unresolved,
+    dropped: validation.dropped,
+    remapped: validation.remapped,
     events: validation.events,
     legacySnapshots: validation.legacySnapshots,
     sourcePath: resolvedSource,
@@ -362,6 +471,9 @@ export async function importLegacySnapshot(input = {}) {
     missionIds: validation.missionIds,
     missionCount: validation.missionCount,
     pausedMissionIds: validation.paused,
+    unresolved: validation.unresolved,
+    droppedFields: validation.dropped.map((entry) => entry.field),
+    remapped: validation.remapped,
     bytes: buffer.length,
     importedAt,
   }

package/adapters/stateFile.js

@@ -15,6 +15,7 @@
 //      `state.migrated {from,to}` to the activity log.
 // A migration that throws therefore leaves state.json byte-identical.
 import { inspectStateVersion, prepareState } from '../domain/state.js'
+import { legacySurveyNeedsRead } from '../domain/state/migrations.js'
 import { isStateLockHeld } from './store.js'
 
 /**
@@ -37,6 +38,7 @@ import { isStateLockHeld } from './store.js'
  *   now?: number,
  *   persist?: boolean,
  *   migrations?: readonly import('../domain/state/migrations.js').StateMigration[],
+ *   resolveLegacySurvey?: (rawState: Record<string, any>) => Promise<import('../domain/state/migrations.js').LegacySurveyRead | null>,
  * }} input
  * @returns {Promise<StateLoadResult>}
  */
@@ -54,7 +56,15 @@ export async function loadStateFile(input) {
     await store.writeJsonAtomic(backupPath, raw)
   }
 
-  const prepared = prepareState(raw, paths.state, { migrations })
+  // A legacy survey planned but never provisioned recorded no base at all, so
+  // the document alone cannot anchor it. Resolve the repository base exactly
+  // once, in the same moment as the migration, and hand it to the pure step.
+  const legacySurveyRead =
+    version.status === 'migratable' && legacySurveyNeedsRead(raw) && typeof input.resolveLegacySurvey === 'function'
+      ? await input.resolveLegacySurvey(raw)
+      : null
+
+  const prepared = prepareState(raw, paths.state, { migrations, legacySurveyRead })
   if (!prepared.changed) {
     return { state: prepared.state, version, migration: null }
   }

package/app/archive.js

@@ -144,10 +144,34 @@ export async function sweepArchive(tower, state, options = {}) {
     force: options.force === true,
     protectedIds,
   })
-  if (selected.length === 0) return { archived: [], written: false, error: null }
+  // #148 W2: never archive a mission whose disposable sandbox is still on disk.
+  // Archiving would move the only record of the path out of hot state while the
+  // checkout leaks; the mission stays hot (protected) until cleanup succeeds on
+  // a later mutate or tower_teardown, and this sweep names the caused path.
+  const sandboxPending = selected
+    .filter((mission) => typeof /** @type {any} */ (mission).sandbox === 'string' && /** @type {any} */ (mission).sandbox.length > 0)
+    .map((mission) => ({ missionId: mission.id, sandbox: /** @type {any} */ (mission).sandbox }))
+  const pendingIds = new Set(sandboxPending.map((entry) => entry.missionId))
+  const archivable = selected.filter((mission) => !pendingIds.has(mission.id))
+  for (const entry of sandboxPending) {
+    await tower.deps.store.appendJsonl(tower.paths.activity, {
+      at: now,
+      type: 'archive',
+      missionId: entry.missionId,
+      text: `deferred: detached sandbox at ${entry.sandbox} is still present; cleanup retries on tower_teardown`,
+    }).catch(() => {})
+  }
+  if (archivable.length === 0) {
+    return {
+      archived: [],
+      written: false,
+      error: null,
+      ...(sandboxPending.length > 0 ? { sandboxPending } : {}),
+    }
+  }
 
   const archivedYear = archiveYearFor(now)
-  const entries = selected.map((mission) =>
+  const entries = archivable.map((mission) =>
     archivedEntry(mission, {
       archivedAt: now,
       archivedYear,
@@ -165,9 +189,9 @@ export async function sweepArchive(tower, state, options = {}) {
   if (!written.ok) return { archived: [], written: false, error: written.error ?? 'archive write failed' }
 
   // The archive now holds the full record: compact state.json in the same lock.
-  const ids = new Set(selected.map((mission) => mission.id))
+  const ids = new Set(archivable.map((mission) => mission.id))
   const branches = new Set(
-    selected
+    archivable
       .map((mission) => mission.worktree?.branch)
       .filter((branch) => typeof branch === 'string'),
   )
@@ -184,7 +208,7 @@ export async function sweepArchive(tower, state, options = {}) {
   state.revision += 1
   state.updatedAt = now
 
-  for (const mission of selected) {
+  for (const mission of archivable) {
     await tower.deps.store.appendJsonl(tower.paths.activity, {
       at: now,
       type: 'archive',
@@ -199,5 +223,6 @@ export async function sweepArchive(tower, state, options = {}) {
     files: written.files,
     error: null,
     year: archivedYear,
+    ...(sandboxPending.length > 0 ? { sandboxPending } : {}),
   }
 }

package/app/briefing.js

@@ -1,10 +1,34 @@
 // Mission briefings: pure text builders for worker/reviewer prompts.
+import { shapeFor } from '../domain/shapes/index.js'
 
 function clip(text, max = 2000) {
   const value = String(text ?? '')
   return value.length > max ? `${value.slice(0, max)}\n… truncated` : value
 }
 
+/**
+ * Dependency lines shared by the worker and reviewer briefings. A survey
+ * dependency carries its recorded result (#148 D6) alongside its status, with
+ * bounded formatting so a large evidence set cannot crowd out the mission.
+ * @param {any[]} deps
+ * @returns {string[]}
+ */
+function dependencyLines(deps) {
+  const lines = []
+  for (const dep of deps) {
+    lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status}${dep.kind ? `, ${dep.kind}` : ''})`)
+    const result = dep.result
+    if (!result || typeof result !== 'object') continue
+    const evidence = []
+    if (Array.isArray(result.paths) && result.paths.length > 0) evidence.push(`paths: ${result.paths.slice(0, 20).join(', ')}`)
+    if (Array.isArray(result.symbols) && result.symbols.length > 0) evidence.push(`symbols: ${result.symbols.slice(0, 20).join(', ')}`)
+    if (Array.isArray(result.plan) && result.plan.length > 0) evidence.push(`plan: ${clip(result.plan.slice(0, 20).join('; '), 1200)}`)
+    if (typeof result.notes === 'string' && result.notes.trim()) evidence.push(`notes: ${clip(result.notes.trim(), 1200)}`)
+    if (evidence.length > 0) lines.push(`  evidence: ${evidence.join(' | ')}`)
+  }
+  return lines
+}
+
 export function workerBriefing({
   repoRoot,
   base,
@@ -17,25 +41,44 @@ export function workerBriefing({
   completionReport = null,
 }) {
   const completion = /** @type {import('../types/index.js').CompletionReport | null} */ (completionReport)
+  const shape = shapeFor(mission.kind)
+  // The checkout the worker actually runs in: a recorded detached sandbox wins
+  // over the (absent) worktree, then a build worktree, then the shared main
+  // checkout. The spawn cwd uses the same precedence, so the prompt matches the
+  // process the agent is started in.
+  const cwd = mission.sandbox ?? worktree?.path ?? repoRoot
   const lines = []
   lines.push(`# Tower mission ${mission.id} — ${mission.title}`)
   lines.push('')
   lines.push(`You are the tower worker for mission ${mission.id} in repository ${repoRoot}.`)
   lines.push('')
-  lines.push(`Work ONLY in this git worktree: ${worktree.path}`)
-  lines.push(`Branch: ${worktree.branch} (based on ${base} @ ${String(worktree.baseCommit).slice(0, 12)})`)
-  lines.push('')
-  lines.push(`Kind: ${mission.kind}`)
   lines.push(
-    `Scope (only files you may touch): ${mission.scope.length > 0 ? mission.scope.join(', ') : '(none — survey is read-only)'}`,
+    ...shape.briefing(mission, {
+      repoRoot,
+      base,
+      worktree,
+      readCommit: /** @type {string | undefined} */ (mission.readCommit),
+      readDirty: mission.readDirty,
+    }),
   )
+  lines.push('')
+  lines.push(`Kind: ${mission.kind}`)
+  // The empty scope means different things by shape: a build still owns its
+  // worktree, a detached survey owns a disposable writable sandbox, and only a
+  // shared survey is strictly read-only.
+  const emptyScope = shape.fields.worktree
+    ? '(none declared — stay inside your worktree)'
+    : shape.fields.sandbox && mission.sandbox
+      ? '(none declared — the detached survey sandbox is disposable: write and run commands inside it, but never commit or leave it)'
+      : '(none — survey is read-only)'
+  lines.push(`Scope (only files you may touch): ${mission.scope.length > 0 ? mission.scope.join(', ') : emptyScope}`)
   if (mission.tasks.length > 0) {
     lines.push('Tasks:')
     for (const task of mission.tasks) lines.push(`- [${task.status}] ${task.text}`)
   }
   if (deps.length > 0) {
     lines.push('Dependencies:')
-    for (const dep of deps) lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status})`)
+    lines.push(...dependencyLines(deps))
   }
   if (mission.context) {
     lines.push('Context (verbatim from the user):')
@@ -57,6 +100,11 @@ export function workerBriefing({
       for (const check of completion.checks ?? []) lines.push(`- ${check.name}${check.exitCode !== undefined ? ` (exit ${check.exitCode})` : ''}`)
     }
   }
+  if (mission.result) {
+    lines.push('')
+    lines.push('Recorded evidence (from a previous completion):')
+    lines.push(`- ${JSON.stringify(mission.result)}`)
+  }
   if (reviews.length > 0) {
     lines.push('')
     lines.push('Previous review rounds for this branch (newest first) — address every finding:')
@@ -73,16 +121,34 @@ export function workerBriefing({
   }
   lines.push('')
   lines.push('Rules:')
-  lines.push(`- Pass workdir="${worktree.path}" on every shell command; never edit the main checkout.`)
-  lines.push('- Stay inside the declared scope; out-of-scope changes are rejected later.')
-  lines.push('- Commit your work on the mission branch. Do not merge, push, or spawn other agents.')
+  if (shape.fields.worktree) {
+    lines.push(`- Pass workdir="${cwd}" on every shell command; never edit the main checkout.`)
+    lines.push('- Stay inside the declared scope; out-of-scope changes are rejected later.')
+    lines.push('- Commit your work on the mission branch. Do not merge, push, or spawn other agents.')
+  } else if (shape.fields.sandbox && mission.sandbox) {
+    lines.push(`- Pass workdir="${mission.sandbox}" on every shell command; that checkout is a disposable detached sandbox, not the main checkout.`)
+    lines.push('- You may write files and run commands inside the sandbox, but never commit: completion requires the sandbox HEAD to still equal the recorded commit and zero new commits.')
+    lines.push(`- Stay inside the sandbox; never edit the main checkout ${repoRoot}. Do not merge, push, or spawn other agents.`)
+  } else {
+    lines.push(`- Read the shared checkout at ${cwd}; it is the main checkout, not your own worktree.`)
+    lines.push(
+      '- Make no commits: this mission reads one fixed commit. Do not write, edit, merge, push, rebase, or spawn other agents.',
+    )
+  }
   lines.push(
     `- Update progress: tower_mission({repoRoot:"${repoRoot}",id:"${mission.id}",task_done:"..."}) or blocker:"...".`,
   )
+  const resultHint = shape.acceptsResult
+    ? ' Optionally record evidence as result:{paths?:string[],symbols?:string[],plan?:string[],notes?:string}.'
+    : ''
+  lines.push(
+    `- When the work is finished and every task is closed, call tower_complete({repoRoot:"${repoRoot}",missionId:"${mission.id}",report:"<full handoff>",checks:[{name,command,exitCode,evidence}]}).${resultHint} Unread inbox messages block completion, so read them with tower_inbox first.`,
+  )
   lines.push(
-    `- When the work is finished and every task is closed, call tower_complete({repoRoot:"${repoRoot}",missionId:"${mission.id}",report:"<full handoff>",checks:[{name,command,exitCode,evidence}]}). Unread inbox messages block completion, so read them with tower_inbox first.`,
+    shape.fields.worktree
+      ? '- Your final message is the full handoff: files changed, how you verified, what remains.'
+      : '- Your final message is the full handoff: what you inspected, how you verified it, what remains.',
   )
-  lines.push('- Your final message is the full handoff: files changed, how you verified, what remains.')
   if (instructions) {
     lines.push('')
     lines.push('Extra tower instructions:')
@@ -91,12 +157,19 @@ export function workerBriefing({
   return lines.join('\n')
 }
 
+/**
+ * @param {{ repoRoot: string, base: string, mission: any, deps: any[],
+ *   worktree: any, review?: { commit: string, path: string } | null,
+ *   instructions?: string, reviews?: any[], findings?: any[],
+ *   completionReport?: any }} input
+ */
 export function reviewerBriefing({
   repoRoot,
   base,
   mission,
   deps,
   worktree,
+  review = null,
   instructions,
   reviews = [],
   findings = [],
@@ -111,6 +184,12 @@ export function reviewerBriefing({
   lines.push(`Review branch: ${worktree.branch}`)
   lines.push(`Worktree: ${worktree.path}`)
   lines.push(`Reviewed base: ${base} @ ${String(worktree.baseCommit).slice(0, 12)}`)
+  if (review) {
+    lines.push(`Review commit: ${String(review.commit).slice(0, 12)} (the evidence your verdict is stamped with)`)
+    lines.push(`Checkout: ${review.path}`)
+    lines.push('')
+    lines.push(`Read and inspect the review commit in ${review.path}; that checkout is removed after your verdict.`)
+  }
   lines.push('')
   lines.push(`Kind: ${mission.kind}`)
   if (mission.tasks.length > 0) {
@@ -119,7 +198,7 @@ export function reviewerBriefing({
   }
   if (deps.length > 0) {
     lines.push('Dependencies:')
-    for (const dep of deps) lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status})`)
+    lines.push(...dependencyLines(deps))
   }
   if (mission.context) {
     lines.push('Context (verbatim from the user):')
@@ -158,6 +237,10 @@ export function reviewerBriefing({
   lines.push('')
   lines.push('Rules:')
   lines.push('- Read-only: do not modify files, commit, or merge.')
+  if (review) {
+    lines.push(`- Pass workdir="${review.path}" on every command: the checkout is a detached read of commit ${String(review.commit).slice(0, 12)}, not the mutable mission worktree.`)
+    lines.push('- tower_diff shows the recorded commit your verdict will stamp; do not review anything newer.')
+  }
   lines.push('- Inspect the diff from the reviewed base to the branch tip and map every task to the diff.')
   lines.push('- Check scope, correctness, tests, and security. Report severity and concrete evidence.')
   lines.push(