dsh-tower 2.5.0 → 2.7.0

package/scripts/shape-audit.mjs

@@ -0,0 +1,361 @@
+// Shape audit (#149): one shape registry means generic layers must not branch on
+// a kind or a role, and the old global status vocabulary must not come back.
+//
+// The audit is the ongoing mechanism, not a one-off cleanup: it fails on
+//   - a comparison against a kind literal ('build' | 'survey'),
+//   - a comparison against a role literal ('worker' | 'reviewer' | 'tower'),
+//   - the global TERMINAL_STATUSES / TRANSITIONS identifiers,
+//   - a one-argument isTerminal(...) or one-argument canTransition(...) call,
+//   - reading a review tip from a live worktree HEAD (review evidence is a commit),
+//   - comparing a batch status against a literal outside the batch owner module,
+//   - naming the lease ledger outside the lease adapter,
+//   - reading completion checks / test receipts outside domain/evidence.js,
+//   - the legacy format/status vocabulary outside adapters/legacy.js,
+//   - owning or re-implementing path permission instead of shape.reach + domain/scope.js,
+//   - combining a role decision with a shape decision outside domain/roles.js.
+//
+// Exemptions live in scripts/architecture-waivers.json under `shapeWaivers` and
+// require a reason plus an owner or a ref, exactly like the architecture gate.
+// A waiver with no reason is a contract failure, and a waiver for a path that no
+// longer violates anything is reported as stale.
+//
+// Usage: node scripts/shape-audit.mjs [--root <path>] [--json]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+export const WAIVER_FILE = 'scripts/architecture-waivers.json'
+export const WAIVER_KEY = 'shapeWaivers'
+export const SCAN_DIRS = ['domain', 'app', 'tools', 'host', 'adapters', 'ports']
+export const SHAPE_DIR = 'domain/shapes'
+/**
+ * The fitness rules this audit enforces. `docs/reference/shapes.md` is generated
+ * from this list, so a verdict cannot name a rule the audit does not run.
+ */
+export const RULES = [
+  {
+    id: 'kind-literal',
+    rule: 'Generic layers never compare mission.kind with a literal.',
+    owner: 'domain/shapes/<kind>.js',
+  },
+  {
+    id: 'role-literal',
+    rule: 'Generic layers use the vocabulary role predicates, never a role literal.',
+    owner: 'domain/roles.js',
+  },
+  {
+    id: 'global-status-vocabulary',
+    rule: 'No module reaches for the global TERMINAL_STATUSES/TRANSITIONS tables.',
+    owner: 'domain/shapes/<kind>.js',
+  },
+  {
+    id: 'shape-entry-point',
+    rule: 'isTerminal(kind, status) and canTransition(kind, from, to) are the only entry points.',
+    owner: 'domain/shapes/index.js',
+  },
+  {
+    id: 'review-tip-read',
+    rule: 'A review never reads a live worktree HEAD; verdicts are stamped with a recorded commit.',
+    owner: 'app/reviewCheckout.js',
+  },
+  {
+    id: 'batch-status-literal',
+    rule: 'Batch status literals live in domain/batch.js; every other layer uses its constants.',
+    owner: 'domain/batch.js',
+  },
+  {
+    id: 'lease-ledger',
+    rule: 'Only adapters/leases.js reads or writes the lease ledger.',
+    owner: 'adapters/leases.js',
+  },
+  {
+    id: 'blocked-status-write',
+    rule: 'blocked is derived from open blockers; only domain/missions/lifecycle.js writes it.',
+    owner: 'domain/missions/lifecycle.js',
+  },
+  {
+    id: 'evidence-single-read',
+    rule: 'Completion checks and test receipts have one reader: domain/evidence.js.',
+    owner: 'domain/evidence.js',
+  },
+  {
+    id: 'legacy-vocabulary',
+    rule: 'One live vocabulary: legacy formats/statuses are read only by adapters/legacy.js.',
+    owner: 'adapters/legacy.js',
+  },
+  {
+    id: 'scope-reach',
+    rule: 'Path permission derives from shape.reach through domain/scope.js; no module owns or re-implements it.',
+    owner: 'domain/scope.js',
+  },
+  {
+    id: 'role-shape-conflation',
+    rule: 'A role decision never combines with a shape decision; role facts live in domain/roles.js.',
+    owner: 'domain/roles.js',
+  },
+]
+/** Rules whose implementation module necessarily names the vocabulary it owns. */
+export const RULE_EXEMPT_PATHS = {
+  'batch-status-literal': ['domain/batch.js'],
+  'lease-ledger': ['adapters/leases.js'],
+  'blocked-status-write': ['domain/missions/lifecycle.js'],
+  'evidence-single-read': ['domain/evidence.js', 'app/recording.js', 'domain/summary.js', 'domain/state/schema.js'],
+  'legacy-vocabulary': ['adapters/legacy.js'],
+  'scope-reach': ['domain/scope.js'],
+  'role-shape-conflation': ['domain/roles.js'],
+}
+
+const KIND_PATTERN = /(?:\bkind\b\s*[!=]==?\s*['"](?:build|survey)['"])|(?:['"](?:build|survey)['"]\s*[!=]==?\s*\bkind\b)/
+const ROLE_PATTERN = /(?:\brole\b\s*[!=]==?\s*['"](?:worker|reviewer|tower)['"])|(?:['"](?:worker|reviewer|tower)['"]\s*[!=]==?\s*\brole\b)/
+const GLOBAL_VOCAB_PATTERN = /\b(?:TERMINAL_STATUSES|TRANSITIONS)\b/
+const CALL_PATTERN = /(?<!\.)\b(isTerminal|canTransition)\s*\(([^()]*)\)/g
+const REVIEW_TIP_PATTERN = /\brevParse\s*\(\s*[^)]*worktree\.path\s*,\s*['"]HEAD['"]\s*\)/
+const BATCH_STATUS_PATTERN =
+  /(?:\bbatch\.status\s*[!=]==?\s*['"](?:open|closed|abandoned|created|active|pending)['"])|(?:['"](?:open|closed|abandoned|created|active|pending)['"]\s*[!=]==?\s*\bbatch\.status\b)/
+const LEASE_LEDGER_PATTERN = /['"](?:leases\.json|leases\.json\.lock|leases\.lock)['"]/
+const BLOCKED_WRITE_PATTERN = /(?:\bstatus\s*=\s*['"]blocked['"])|(?:['"]status['"]\s*:\s*['"]blocked['"])/
+const EVIDENCE_READ_PATTERN = /\bmission\.testRuns\b|\btestRuns\s*[.[]|completionReport\?\.checks|completionReport\.checks/
+const LEGACY_VOCABULARY_PATTERN = /\btower-codex\b|\bpausedIds\b|\bCODEX_(?:STATUSES|ID_RE)\b/
+const SCOPE_FENCE_PATTERN = /\bownsScope\b|\bfileInScope\s*\(/
+const ROLE_SHAPE_PATTERN = /\b(?:isWorkerRole|isReviewerRole|isTowerRole)\s*\(|\bROLE\.(?:worker|reviewer|tower)\b/
+const SHAPE_DECISION_PATTERN = /\bshapeFor\s*\(|\bshape\s*[.[]/
+
+/**
+ * Count top-level arguments in a call's argument text.
+ * @param {string} args
+ * @returns {number}
+ */
+function argumentCount(args) {
+  const trimmed = args.trim()
+  if (trimmed.length === 0) return 0
+  let depth = 0
+  let count = 1
+  for (const char of trimmed) {
+    if (char === '(' || char === '[' || char === '{') depth += 1
+    else if (char === ')' || char === ']' || char === '}') depth -= 1
+    else if (char === ',' && depth === 0) count += 1
+  }
+  return count
+}
+
+/**
+ * @param {string} source
+ * @returns {Array<{ rule: string, detail: string }>}
+ */
+export function inspectSource(source) {
+  const violations = []
+  const lines = source.split('\n')
+  lines.forEach((line, index) => {
+    const at = `line ${index + 1}`
+    const trimmed = line.trim()
+    // Documentation may quote the vocabulary it forbids; only code counts.
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) return
+    if (KIND_PATTERN.test(line)) {
+      violations.push({ rule: 'kind-literal', detail: `${at}: ${line.trim()} — resolve shapeFor(mission.kind) instead` })
+    }
+    if (ROLE_PATTERN.test(line)) {
+      violations.push({ rule: 'role-literal', detail: `${at}: ${line.trim()} — use the vocabulary role predicates instead` })
+    }
+    if (GLOBAL_VOCAB_PATTERN.test(line)) {
+      violations.push({ rule: 'global-status-vocabulary', detail: `${at}: ${line.trim()} — use shape.isTerminal(status) / shape.transitions` })
+    }
+    if (REVIEW_TIP_PATTERN.test(line)) {
+      violations.push({
+        rule: 'review-tip-read',
+        detail: `${at}: ${line.trim()} — stamp reviews with a recorded commit (tower.branchTip(mission)) instead of a live worktree HEAD`,
+      })
+    }
+    if (BATCH_STATUS_PATTERN.test(line)) {
+      violations.push({
+        rule: 'batch-status-literal',
+        detail: `${at}: ${line.trim()} — use BATCH_STATUS / canTransitionBatch from domain/batch.js`,
+      })
+    }
+    if (LEASE_LEDGER_PATTERN.test(line)) {
+      violations.push({
+        rule: 'lease-ledger',
+        detail: `${at}: ${line.trim()} — the lease ledger is owned by adapters/leases.js`,
+      })
+    }
+    if (BLOCKED_WRITE_PATTERN.test(line)) {
+      violations.push({
+        rule: 'blocked-status-write',
+        detail: `${at}: ${line.trim()} — blocked is derived from open blockers: use markBlocked(mission, text)`,
+      })
+    }
+    if (EVIDENCE_READ_PATTERN.test(line)) {
+      violations.push({
+        rule: 'evidence-single-read',
+        detail: `${at}: ${line.trim()} — read evidence through domain/evidence.js (findEvidence/passingDiscovery/hasCheckEvidence)`,
+      })
+    }
+    if (LEGACY_VOCABULARY_PATTERN.test(line)) {
+      violations.push({
+        rule: 'legacy-vocabulary',
+        detail: `${at}: ${line.trim()} — legacy formats/statuses are normalised by adapters/legacy.js; do not introduce a second vocabulary`,
+      })
+    }
+    if (SCOPE_FENCE_PATTERN.test(line)) {
+      violations.push({
+        rule: 'scope-reach',
+        detail: `${at}: ${line.trim()} — path permission is shape.reach through scopeFenceBlocker(); no ownsScope flag or direct matcher`,
+      })
+    }
+    if (ROLE_SHAPE_PATTERN.test(line) && SHAPE_DECISION_PATTERN.test(line)) {
+      violations.push({
+        rule: 'role-shape-conflation',
+        detail: `${at}: ${line.trim()} — resolve the role through domain/roles.js; the shape supplies facts, not role branches`,
+      })
+    }
+    for (const match of line.matchAll(CALL_PATTERN)) {
+      const expected = match[1] === 'isTerminal' ? 2 : 3
+      if (argumentCount(match[2]) < expected) {
+        violations.push({
+          rule: 'shape-entry-point',
+          detail: `${at}: ${match[0]} — the only entry points are isTerminal(kind, status) and canTransition(kind, from, to)`,
+        })
+      }
+    }
+  })
+  return violations
+}
+
+/**
+ * @param {string} start
+ * @returns {string[]}
+ */
+function walk(start) {
+  const files = []
+  if (!fs.existsSync(start)) return files
+  for (const entry of fs.readdirSync(start, { withFileTypes: true })) {
+    const full = path.join(start, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+      files.push(...walk(full))
+    } else if (entry.name.endsWith('.js') || entry.name.endsWith('.mjs')) {
+      files.push(full)
+    }
+  }
+  return files
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {{ path: string, rule: string, detail: string }[]}
+ */
+export function scan(repoRoot) {
+  const results = []
+  for (const dir of SCAN_DIRS) {
+    for (const file of walk(path.join(repoRoot, dir))) {
+      const relative = path.relative(repoRoot, file).split(path.sep).join('/')
+      if (relative.startsWith(`${SHAPE_DIR}/`)) continue
+      const source = fs.readFileSync(file, 'utf8')
+      for (const violation of inspectSource(source)) {
+        const exempt = RULE_EXEMPT_PATHS[violation.rule] ?? []
+        if (exempt.includes(relative)) continue
+        results.push({ path: relative, ...violation })
+      }
+    }
+  }
+  return results
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {{ waivers: Array<{ rule?: string, path?: string, reason?: string, owner?: string, ref?: string, match?: string }>, errors: string[] }}
+ */
+export function loadShapeWaivers(repoRoot) {
+  const file = path.join(repoRoot, WAIVER_FILE)
+  if (!fs.existsSync(file)) return { waivers: [], errors: [`${WAIVER_FILE}: missing`] }
+  let document
+  try {
+    document = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    return { waivers: [], errors: [`${WAIVER_FILE}: not valid JSON (${String(error?.message ?? error)})`] }
+  }
+  const entries = document?.[WAIVER_KEY] ?? []
+  if (!Array.isArray(entries)) return { waivers: [], errors: [`${WAIVER_FILE}: ${WAIVER_KEY} must be an array`] }
+  const errors = []
+  for (const [index, entry] of entries.entries()) {
+    const where = `${WAIVER_FILE} ${WAIVER_KEY}[${index}]`
+    if (!entry || typeof entry !== 'object') {
+      errors.push(`${where}: must be an object`)
+      continue
+    }
+    if (typeof entry.rule !== 'string' || entry.rule.length === 0) errors.push(`${where}: rule is required`)
+    if (typeof entry.path !== 'string' || entry.path.length === 0) errors.push(`${where}: path is required`)
+    if (typeof entry.reason !== 'string' || entry.reason.length === 0) errors.push(`${where}: reason is required`)
+    if (!entry.owner && !entry.ref) errors.push(`${where}: owner or ref is required`)
+  }
+  return { waivers: errors.length === 0 ? entries : [], errors }
+}
+
+/**
+ * @param {{ path: string, rule: string, detail: string }[]} violations
+ * @param {Array<{ rule?: string, path?: string, match?: string }>} waivers
+ * @returns {{ violations: typeof violations, waived: typeof violations, unused: Array<{ rule?: string, path?: string }> }}
+ */
+export function applyWaivers(violations, waivers) {
+  const waived = []
+  const used = new Set()
+  const remaining = []
+  for (const violation of violations) {
+    const index = waivers.findIndex((waiver) => {
+      if (waiver.path !== violation.path) return false
+      if (waiver.rule !== violation.rule) return false
+      if (waiver.match && !violation.detail.includes(waiver.match)) return false
+      return true
+    })
+    if (index >= 0) {
+      used.add(index)
+      waived.push(violation)
+    } else {
+      remaining.push(violation)
+    }
+  }
+  const unused = waivers.filter((_, index) => !used.has(index))
+  return { violations: remaining, waived, unused }
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {{ ok: boolean, violations: any[], waived: any[], errors: string[], unused: any[] }}
+ */
+export function evaluator(repoRoot = root) {
+  const reported = []
+  const waivers = loadShapeWaivers(repoRoot)
+  if (waivers.errors.length > 0) return { ok: false, violations: [], waived: [], errors: waivers.errors, unused: [] }
+  const applied = applyWaivers(scan(repoRoot), waivers.waivers)
+  for (const violation of applied.violations) {
+    reported.push(`shape-audit error: [${violation.rule}] ${violation.path} ${violation.detail}`)
+  }
+  if (applied.unused.length > 0) {
+    for (const waiver of applied.unused) {
+      reported.push(`shape-audit error: [stale-waiver] ${waiver.path} ${waiver.rule} no longer matches a violation; remove it`)
+    }
+  }
+  return {
+    ok: reported.length === 0,
+    violations: applied.violations,
+    waived: applied.waived,
+    errors: reported,
+    unused: applied.unused,
+  }
+}
+
+function main(argv) {
+  const rootIndex = argv.indexOf('--root')
+  const repoRoot = rootIndex >= 0 ? path.resolve(argv[rootIndex + 1]) : root
+  const result = evaluator(repoRoot)
+  if (argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+  } else if (result.ok) {
+    process.stdout.write(`shape-audit: ok (waived: ${result.waived.length})\n`)
+  } else {
+    for (const line of result.errors) process.stderr.write(`${line}\n`)
+  }
+  process.exitCode = result.ok ? 0 : 1
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2))

package/scripts/surface-baseline.json

@@ -4,7 +4,7 @@
   "surfaces": {
     "configKeys": {
       "seed": 64,
-      "value": 53,
+      "value": 56,
       "decisions": [
         {
           "from": 64,
@@ -12,13 +12,77 @@
           "date": "2026-11-03",
           "adr": "docs/adr/0005-component-surface.md",
           "note": "Recorded contraction, not a free ratchet (#138). #121 removed the seven tools.expose* keys plus dev.hotReload, #136 replaced tests.enabled with the tower-tests row, and #133/#135 replaced docs.board/archive.enabled with the tower-board/tower-archive rows. The chain now continues here: the config-key surface is two-way like components, so any later increase or decrease needs its own dated decision."
+        },
+        {
+          "from": 53,
+          "to": 54,
+          "date": "2026-11-03",
+          "adr": "docs/adr/0005-component-surface.md",
+          "note": "#M39: one new key, review.mode (off/optional/required), replaces the deprecated review.requireReview boolean as the review policy. It is not a fifth component row: the reviewer preset row stays a capability, and the mode decides whether it is required (required) or unused (off). review.requireReview remains accepted for one release as a normalized alias, so it is a deprecated key rather than a removed one and the surface grows by exactly one."
+        },
+        {
+          "from": 54,
+          "to": 57,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148/#149: the shape redesign adds the survey routing keys spawn.surveyPreset (core) and spawn.surveyModel (tuning), plus survey.sandbox (tuning) in the new survey section. tower-survey is the capability row; the preset/model names only route the read-only agent."
+        },
+        {
+          "from": 57,
+          "to": 55,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "Review round 2 contracts the shape surface before release: spawn.surveyPreset could never be read (a survey's preset is shape-owned, so the key could only disagree with the registry) and survey.sandbox advertised a placement W1 does not implement. Only spawn.surveyModel remains as the optional model route; both removals are recorded here rather than silently shrinking the two-way surface."
+        },
+        {
+          "from": 55,
+          "to": 56,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148 W2 implements the detached survey sandbox, so survey.sandbox returns as one tuning key: none (read-only shared checkout, the default and unchanged W1 behavior) or detached (a disposable detached worktree with a write/shell-capable preset). It is placement tuning, not a capability row or a second routing key; spawn.surveyPreset stays removed because the shape resolves the preset."
+        },
+        {
+          "from": 56,
+          "to": 57,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148 W2 D5 adds gates.requireFreshSurvey (default false): the survey-stale dependency warning is advisory by default and becomes a merge blocker only when this gate is true. It is a merge-gate strictness key like the other gates.* entries, not a component."
+        },
+        {
+          "from": 57,
+          "to": 56,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#149 W4 contracts the surface by one: `tests.autoChecks` existed only to copy a discovery projection into the completion report, which made a second evidence shape. The receipt in mission.testRuns is now the one evidence shape read by domain/evidence.js, so the key has no remaining meaning and is removed rather than kept as a dead tuning switch."
         }
       ]
     },
     "sections": {
       "seed": 15,
-      "value": 14,
-      "decisions": []
+      "value": 15,
+      "decisions": [
+        {
+          "from": 15,
+          "to": 15,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148/#149 restore the section count to its seed: survey.sandbox needs a home, so the survey section returns the 15 sections that #121 shrank to 14. Net zero against the seed; no other section changed."
+        },
+        {
+          "from": 15,
+          "to": 14,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "Review round 2 removes the survey section with its only key: survey.sandbox advertised a detached read-only checkout W1 does not implement. The section existed only to hold that key, so the count returns to 14."
+        },
+        {
+          "from": 14,
+          "to": 15,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148 W2 restores the survey section for its one tuning key, survey.sandbox (placement: none|detached). The section count returns to the 15 of the earlier shape cut; no other section changed and no component row was added (the sandbox preset is an internal child of the existing tower-survey group)."
+        }
+      ]
     },
     "tools": {
       "seed": 27,
@@ -38,7 +102,7 @@
     },
     "components": {
       "seed": 4,
-      "value": 11,
+      "value": 12,
       "decisions": [
         {
           "from": 4,
@@ -74,6 +138,13 @@
           "date": "2026-11-02",
           "adr": "docs/adr/0005-component-surface.md",
           "note": "#134: the gate reads every shipped cordis.patch.yml, so the tower-ui row in ui-bundle/cordis.patch.yml joins the counted surface. The row was always shipped and unclassified; counting it is not new surface, it is the existing surface becoming visible to the policy."
+        },
+        {
+          "from": 11,
+          "to": 12,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148/#149: tower-survey is a visible optional row: off means surveys cannot be planned and no survey agent is dispatched; build missions are unaffected."
         }
       ]
     }

package/scripts/types-coverage.mjs

@@ -14,6 +14,9 @@
 // changing the tsconfig is enough and this gate follows.
 //
 // Excluded tiers are data with a reason, not silent gaps:
+//   - `client.js` is the core Web Client half (#M40): a browser artifact checked
+//     by tests/plugin-config-client.test.mjs and the client rules, not by the
+//     Node tsc program;
 //   - `ui-bundle/**` is the optional Web client: a browser artifact with DOM
 //     types and no Node runtime, checked by tests/ui-bundle.test.mjs and the
 //     architecture client rules instead of the Node tsc program;
@@ -30,6 +33,10 @@ const WALK_SKIP = new Set(['node_modules', '.git', '.dsh-tower-worktrees', 'cove
 
 /** Shipped `.js` tiers that are deliberately outside the Node tsc program. */
 export const NOT_CHECKED_TIERS = [
+  {
+    pattern: 'client.js',
+    reason: 'core Web client: browser artifact, checked by tests/plugin-config-client.test.mjs',
+  },
   {
     pattern: 'ui-bundle/**',
     reason: 'optional Web client: browser artifact, checked by tests/ui-bundle.test.mjs and the client architecture rules',

package/survey-sandbox.js

@@ -0,0 +1,48 @@
+// tower-survey-sandbox preset policy (#148 W2): a survey that reads in a
+// disposable detached sandbox may write and run commands *inside that sandbox*,
+// but it still owns no branch, never commits, and may not merge, rebase, review
+// or spawn. The allow-list is the structural guarantee: the denied tools do not
+// exist in the session, so a prompt cannot talk the agent into using them.
+//
+// The shared-checkout survey preset (`dsh-tower/survey`) stays strictly
+// read-only; this module is mounted only for a detached sandbox.
+export const name = 'dsh-tower/survey-sandbox'
+export const inject = ['tools', 'systemPrompt']
+
+const ALLOW = [
+  'read',
+  'write',
+  'edit',
+  'glob',
+  'grep',
+  'pwsh',
+  'tower_mission',
+  'tower_status',
+  'tower_finding',
+  'tower_findings',
+  'tower_inbox',
+  'tower_complete',
+  'skill',
+]
+
+const PROTOCOL = [
+  'You are a Tower survey worker reading one recorded commit in a disposable detached sandbox.',
+  'Work only inside the sandbox path named in your briefing; never modify the main checkout.',
+  'You may write files and run shell commands inside the sandbox, but do not commit: completion requires',
+  'the sandbox HEAD to still be the recorded commit and zero new commits. The sandbox is removed when the mission completes.',
+  'You cannot spawn, merge, rebase, review or diff. Acknowledge inbox mail with tower_inbox; unread messages block completion.',
+  'Finish with tower_complete (report + checks evidence, optionally result:{paths,symbols,plan,notes}); the result is survey evidence only.',
+].join(' ')
+
+export function apply(ctx) {
+  try {
+    ctx.tools.restrict({ allow: ALLOW })
+  } catch {
+    // a composition without the tool registry still gets the protocol text
+  }
+  try {
+    ctx.systemPrompt.section({ name: 'tower:survey-sandbox-protocol', order: 12000, text: PROTOCOL })
+  } catch {
+    // prompt assembly remains valid without the section
+  }
+}

package/survey.js

@@ -0,0 +1,40 @@
+// tower-survey preset policy: a read-only inspection surface. The allow-list is
+// the structural read-only guarantee (#148): a survey cannot write, edit, run a
+// shell, commit, or merge because the tools do not exist in its session.
+export const name = 'dsh-tower/survey'
+export const inject = ['tools', 'systemPrompt']
+
+const ALLOW = [
+  'read',
+  'glob',
+  'grep',
+  'tower_mission',
+  'tower_status',
+  'tower_finding',
+  'tower_findings',
+  'tower_inbox',
+  'tower_complete',
+  'skill',
+]
+
+const PROTOCOL = [
+  'You are a Tower survey worker in a DeepSeek Harness Tower workspace.',
+  'You read one recorded commit in the shared checkout and never modify it: do not write, edit, run a shell,',
+  'commit, rebase, or merge. Your tools are read, glob, grep, skill, and the Tower mission/status/finding/inbox/complete tools.',
+  'Acknowledge inbox mail with tower_inbox (it records Tower state, not a repository write): unread messages block completion.',
+  'Finish with tower_complete (report + checks evidence, optionally result:{paths,symbols,notes}); completion requires',
+  'HEAD to still be the recorded commit, the tracked-file status set to be unchanged, and zero commits.',
+].join(' ')
+
+export function apply(ctx) {
+  try {
+    ctx.tools.restrict({ allow: ALLOW })
+  } catch {
+    // a composition without the tool registry still gets the protocol text
+  }
+  try {
+    ctx.systemPrompt.section({ name: 'tower:survey-protocol', order: 12000, text: PROTOCOL })
+  } catch {
+    // prompt assembly remains valid without the section
+  }
+}

package/tools/complete.js

@@ -13,7 +13,7 @@ export function registerCompleteTool(ctx, deps) {
   define(ctx, {
     name: 'tower_complete',
     description:
-      'Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base, and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. Stores the full report, capped at gates.maxReportBytes (default 32768 UTF-8 bytes); a larger report is rejected with invalid-argument and an actionable nextAction, never truncated. Persists reportBytes on the stored report. completion means ready for preflight and optional review, not merged.',
+      'Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base (zero commits plus HEAD pinned to readCommit for a survey; zero commits in its detached sandbox with HEAD pinned for a sandboxed survey), and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. result is survey-only evidence ({paths?,symbols?,plan?,notes?}); a build completion that carries one is refused. Stores the full report, capped at gates.maxReportBytes (default 32768 UTF-8 bytes); a larger report is rejected with invalid-argument and an actionable nextAction, never truncated. Persists reportBytes on the stored report. completion means ready for preflight and optional review, not merged.',
     parameters: CompleteInput,
     aliases: {"missionId":["id"]},
     requiresMissionId: true,
@@ -38,15 +38,15 @@ export function registerCompleteTool(ctx, deps) {
         if (discovery.configured && discovery.receipt.ok !== true) {
           throw new TowerToolError('tests-failed', `test discovery failed for ${args.missionId}: ${discovery.receipt.error}`)
         }
-        if (discovery.configured && testsConfig.autoChecks !== false && discovery.check) {
-          if (checks.length >= 20) checks[19] = discovery.check
-          else checks.push(discovery.check)
-        }
       }
+      // #149 W4: the receipt already lives in mission.testRuns and is read by
+      // domain/evidence.js. Copying a `tests` projection into the completion
+      // report would be a second evidence shape, so it is not done here.
       return tower.complete({
         missionId: args.missionId,
         agentId: String(exec.agent.id),
         report: args.report,
+        result: args.result,
         checks,
       })
     },

package/tools/diff.js

@@ -18,7 +18,7 @@ import { DiffInput } from '../domain/contracts/tool-inputs/index.js'
 
 /**
  * @param {any} ctx
- * @param {{ define: import('../types/index.js').DefineTool, openTower: any }} deps
+ * @param {{ define: import('../types/index.js').DefineTool, openTower: any, actorFor: any }} deps
  */
 export function registerDiffTool(ctx, deps) {
   // openTower is injected by the composition root (#69).
@@ -31,9 +31,11 @@ export function registerDiffTool(ctx, deps) {
     aliases: {"missionId":["id"]},
     requiresMissionId: true,
     output: output(SCHEMAS.diff),
-    async execute(args) {
+    async execute(args, exec) {
       const tower = await deps.openTower(args.repoRoot)
-      return tower.diff({ missionId: args.missionId, maxBytes: args.maxBytes })
+      // A reviewer's diff is bound to its recorded review commit (#149 W3).
+      const actor = await deps.actorFor(tower, exec)
+      return tower.diff({ missionId: args.missionId, maxBytes: args.maxBytes, actor })
     },
   })
 }

package/tools/plan.js

@@ -25,7 +25,7 @@ export function registerPlanTool(ctx, deps) {
   define(ctx, {
     name: 'tower_plan',
     description:
-      'Plan one or more missions in an initialized repository. Each mission has a printable-Unicode title (NFC-normalized, at most 120 characters), 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.',
+      'Plan one or more missions in an initialized repository. Each mission has a printable-Unicode title (NFC-normalized, at most 120 characters), 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. Returns survey-stale warnings for a build that depends on a survey whose recorded readCommit is not an ancestor of the base; those warnings are advisory and gates.requireFreshSurvey promotes them to merge blockers.',
     parameters: PlanInput,
     board: true,
     output: output(SCHEMAS.plan),