dsh-tower 2.6.0 → 2.7.0

package/domain/state/migrations.js

@@ -12,8 +12,12 @@
 // @ts-check
 import { TowerToolError } from '../errors.js'
 import { SCHEMA_VERSION } from '../mission.js'
+import { SHAPE_KINDS, shapeFor } from '../shapes/index.js'
+import { normalizeBatchStatus } from '../batch.js'
 
-/** @typedef {{ from: number, to: number, migrate: (state: Record<string, any>) => Record<string, any> }} StateMigration */
+/** @typedef {{ readCommit: string, readDirty: string[] }} LegacySurveyRead */
+/** @typedef {{ legacySurveyRead?: LegacySurveyRead | null }} MigrationContext */
+/** @typedef {{ from: number, to: number, migrate: (state: Record<string, any>, context?: MigrationContext) => Record<string, any> }} StateMigration */
 
 /**
  * @param {unknown} value
@@ -57,10 +61,109 @@ export function migrateV2ToV3(state) {
   return { ...state, caseInsensitive: null }
 }
 
+/**
+ * v3 -> v4. Mission state becomes per-shape (#149). Every mission is stamped with
+ * its kind; a legacy branch-shaped survey keeps the commit it read (the
+ * worktree's base commit) and drops the worktree/branch/merge fields it no
+ * longer owns. Build missions keep their document unchanged.
+ *
+ * The step is pure and one-way. Re-running it on a v4 document is a fixed point:
+ * every mission already has a kind, so the same shape migration rewrites it to
+ * the same values.
+ *
+ * A legacy survey planned but never provisioned records no base commit at all
+ * (2.6.0 wrote neither `baseCommit` nor a worktree at plan time). The loader
+ * resolves the state base once and passes it as `context.legacySurveyRead`; the
+ * survey shape consumes it only when it has no recorded base of its own.
+ * @param {Record<string, any>} state
+ * @param {MigrationContext} [context]
+ * @returns {Record<string, any>}
+ */
+export function migrateV3ToV4(state, context = {}) {
+  const next = { ...state }
+  next.missions = (Array.isArray(next.missions) ? next.missions : []).map((mission) => {
+    if (!isPlainObject(mission)) return mission
+    const shape = SHAPE_KINDS.map((kind) => shapeFor(kind)).find((candidate) => candidate.isLegacy(mission))
+    return shape ? shape.migrateLegacy(mission, context) : mission
+  })
+  return next
+}
+
+/**
+ * v4 -> v5. Two contracts that used to overlap are made exact (#149 W3):
+ *
+ * - `blocked` is derived from open blockers, not an independent stop state. A
+ *   non-terminal mission that says `blocked` without a blocker gets one explicit
+ *   legacy blocker (it stays blocked; `clear_blockers` resumes it); a
+ *   non-terminal mission that carries blockers under any other status becomes
+ *   `blocked` because a blocker wins over a pause or a fresh status. Terminal
+ *   missions keep their blockers as history and are never reopened.
+ * - A batch's status vocabulary is normalized to `open|closed|abandoned`;
+ *   pre-v5 documents used `created|active|pending` as synonyms for `open`.
+ *
+ * The step is pure and one-way. Re-running it on a v5 document is a fixed point.
+ * @param {Record<string, any>} state
+ * @returns {Record<string, any>}
+ */
+export function migrateV4ToV5(state) {
+  const next = { ...state }
+  next.missions = (Array.isArray(next.missions) ? next.missions : []).map((mission) => {
+    if (!isPlainObject(mission)) return mission
+    const shape = shapeFor(mission.kind)
+    const blockers = Array.isArray(mission.blockers) ? [...mission.blockers] : []
+    if (shape.isTerminal(mission.status)) return { ...mission, blockers }
+    if (mission.status === 'blocked' && blockers.length === 0) {
+      return {
+        ...mission,
+        blockers: ['(legacy blocked state: no blocker was recorded; clear_blockers resumes the mission)'],
+      }
+    }
+    if (mission.status !== 'blocked' && blockers.length > 0) {
+      const migrated = { ...mission, status: 'blocked', blockers }
+      // A blocker supersedes a pause: the pause cause no longer describes why
+      // the mission is stopped.
+      delete migrated.pauseCause
+      return migrated
+    }
+    return mission
+  })
+  if (Array.isArray(next.batches)) {
+    next.batches = next.batches.map((batch) => {
+      if (!isPlainObject(batch)) return batch
+      const status = normalizeBatchStatus(batch.status)
+      return status === batch.status ? batch : { ...batch, status }
+    })
+  }
+  return next
+}
+
+/**
+ * True when a pre-v4 document contains at least one legacy mission whose shape
+ * cannot anchor its read from the document alone (a survey planned but never
+ * provisioned). The load path must resolve the repository base before migration
+ * runs; a document that recorded its own commit needs no resolver, and a
+ * current-version document is never re-migrated.
+ * @param {unknown} state
+ * @returns {boolean}
+ */export function legacySurveyNeedsRead(state) {
+  if (!isPlainObject(state)) return false
+  const document = /** @type {Record<string, any>} */ (state)
+  const version = document.schemaVersion
+  if (!Number.isInteger(version) || version < 1 || version >= SCHEMA_VERSION) return false
+  const missions = Array.isArray(document.missions) ? document.missions : []
+  return missions.some((mission) => {
+    if (!isPlainObject(mission)) return false
+    const shape = SHAPE_KINDS.map((kind) => shapeFor(kind)).find((candidate) => candidate.isLegacy(mission))
+    return typeof shape?.needsLegacyRead === 'function' && shape.needsLegacyRead(mission)
+  })
+}
+
 /** Ordered registry: entry 0 moves 1 -> 2, entry 1 moves 2 -> 3, and so on. */
 export const STATE_MIGRATIONS = Object.freeze([
   Object.freeze({ from: 1, to: 2, migrate: migrateV1ToV2 }),
   Object.freeze({ from: 2, to: 3, migrate: migrateV2ToV3 }),
+  Object.freeze({ from: 3, to: 4, migrate: migrateV3ToV4 }),
+  Object.freeze({ from: 4, to: 5, migrate: migrateV4ToV5 }),
 ])
 
 /**
@@ -91,16 +194,20 @@ export function migrationChain(from, to = SCHEMA_VERSION, migrations = STATE_MIG
 
 /**
  * Apply the registry to a parsed document. Pure: the input object is never
- * touched and the returned document has the target `schemaVersion`.
+ * touched and the returned document has the target `schemaVersion`. The same
+ * `MigrationContext` object reaches every step, so a step may consume a value
+ * the loader resolved once (the legacy survey read).
  *
  * @param {Record<string, any>} state
- * @param {{ statePath?: string, to?: number, migrations?: readonly StateMigration[] }} [options]
+ * @param {{ statePath?: string, to?: number, migrations?: readonly StateMigration[] } & MigrationContext} [options]
  * @returns {{ state: Record<string, any>, from: number, to: number, steps: Array<{ from: number, to: number }> }}
  */
 export function migrateState(state, options = {}) {
   const where = options.statePath ? ` at ${options.statePath}` : ''
   const to = options.to ?? SCHEMA_VERSION
   const migrations = options.migrations ?? STATE_MIGRATIONS
+  /** @type {MigrationContext} */
+  const context = { legacySurveyRead: options.legacySurveyRead }
   const from = state?.schemaVersion
   const chain = migrationChain(from, to, migrations)
   if (!chain || chain.length === 0) {
@@ -120,7 +227,7 @@ export function migrateState(state, options = {}) {
     /** @type {Record<string, any>} */
     let next
     try {
-      next = step.migrate(current)
+      next = step.migrate(current, context)
     } catch (error) {
       throw new TowerToolError(
         'state-migration-failed',

package/domain/state/schema.js

@@ -1,15 +1,21 @@
-// Declarative state-file schema (#56 P4).
+// Declarative state-file schema (#56 P4, #149).
 //
 // `StateSchema` describes the structural contract of
-// `<git-common-dir>/dsh-tower/state.json`. Object schemas allow additional
-// properties on purpose: state files are forward/backward compatible and legacy
-// rows carry extra fields. Semantic policy (uniqueness, status/verdict
-// vocabularies, review exemption, worktree records and the revision counter)
-// lives in `./semantics.js`, so this module remains a pure declaration.
+// `<git-common-dir>/dsh-tower/state.json`. Schema v4 splits a mission into a
+// per-shape union: a build mission owns a branch/worktree/merge projection, a
+// survey owns `readCommit`/`readDirty` and may *not* carry the branch-shaped
+// fields. Object schemas allow additional properties on purpose: state files
+// are forward/backward compatible and legacy rows carry extra fields, while the
+// union's forbidden keys are declared `Type.Never()` so a survey carrying a
+// worktree record fails the shape check. Semantic policy (uniqueness,
+// status/verdict vocabularies, review exemption, worktree records and the
+// revision counter) lives in `./semantics.js`, so this module remains a pure
+// declaration.
 // @ts-check
 import { Type } from '@sinclair/typebox'
 import { Value } from '@sinclair/typebox/value'
 import { SCHEMA_VERSION } from '../mission.js'
+import { isShapeKind, shapeFor } from '../shapes/index.js'
 
 const optional = { additionalProperties: true }
 
@@ -17,9 +23,10 @@ const NonNegativeInteger = Type.Integer({ minimum: 0 })
 
 const WorktreeSchema = Type.Object({}, optional)
 
-const MissionSchema = Type.Object(
+const BuildMissionSchema = Type.Object(
   {
     id: Type.String(),
+    kind: Type.Literal('build'),
     status: Type.Optional(Type.String()),
     tasks: Type.Array(Type.Unknown()),
     deps: Type.Array(Type.Unknown()),
@@ -27,10 +34,41 @@ const MissionSchema = Type.Object(
     reviewPolicy: Type.Optional(Type.String()),
     testRuns: Type.Optional(Type.Array(Type.Unknown())),
     worktree: Type.Optional(Type.Union([WorktreeSchema, Type.Null()])),
+    // A build mission reads a base and writes a branch; it never carries the
+    // survey fingerprint or a detached survey sandbox.
+    readCommit: Type.Optional(Type.Never()),
+    readDirty: Type.Optional(Type.Never()),
+    sandbox: Type.Optional(Type.Never()),
   },
   optional,
 )
 
+const SurveyMissionSchema = Type.Object(
+  {
+    id: Type.String(),
+    kind: Type.Literal('survey'),
+    status: Type.Optional(Type.String()),
+    tasks: Type.Array(Type.Unknown()),
+    deps: Type.Array(Type.Unknown()),
+    references: Type.Optional(Type.Array(Type.Unknown())),
+    reviewPolicy: Type.Optional(Type.String()),
+    readCommit: Type.String(),
+    readDirty: Type.Optional(Type.Array(Type.String())),
+    // #148 W2: an optional path to the disposable detached sandbox. Absent for
+    // a shared-checkout survey and for every build.
+    sandbox: Type.Optional(Type.String()),
+    // A survey reads one commit in the shared checkout: no branch shape.
+    worktree: Type.Optional(Type.Never()),
+    branch: Type.Optional(Type.Never()),
+    baseCommit: Type.Optional(Type.Never()),
+    mergedCommit: Type.Optional(Type.Never()),
+    mergedAt: Type.Optional(Type.Never()),
+  },
+  optional,
+)
+
+const MissionSchema = Type.Union([BuildMissionSchema, SurveyMissionSchema])
+
 const RosterEntrySchema = Type.Object(
   {
     name: Type.String(),
@@ -131,6 +169,9 @@ function firstShapeMessage(state, where) {
   for (const mission of state.missions) {
     if (!isPlainObject(mission) || typeof mission.id !== 'string') return `mission entry without id${where}`
     const id = mission.id
+    if (!isShapeKind(mission.kind)) {
+      return `mission ${id} has unknown kind ${String(mission.kind)}${where}`
+    }
     if (!Array.isArray(mission.tasks)) return `mission ${id} has no tasks array${where}`
     if (!Array.isArray(mission.deps)) return `mission ${id} has no deps array${where}`
     if (mission.references !== undefined && !Array.isArray(mission.references)) {
@@ -142,6 +183,27 @@ function firstShapeMessage(state, where) {
     if (mission.testRuns !== undefined && !Array.isArray(mission.testRuns)) {
       return `mission ${id} has no testRuns array${where}`
     }
+    if (isShapeKind(mission.kind)) {
+      const shape = shapeFor(mission.kind)
+      if (shape.fields.readCommit) {
+        if (typeof mission.readCommit !== 'string' || mission.readCommit.length === 0) {
+          return `mission ${id} is a survey and needs a readCommit${where}`
+        }
+        if (mission.readDirty !== undefined && !Array.isArray(mission.readDirty)) {
+          return `mission ${id} has an invalid readDirty fingerprint${where}`
+        }
+        if (mission.sandbox !== undefined && (typeof mission.sandbox !== 'string' || mission.sandbox.length === 0)) {
+          return `mission ${id} has an invalid sandbox path${where}`
+        }
+        if (mission.worktree !== undefined && mission.worktree !== null) {
+          return `mission ${id} is a survey and may not have a worktree record${where}`
+        }
+      } else if (mission.readCommit !== undefined || mission.readDirty !== undefined) {
+        return `mission ${id} is a build and may not have readCommit/readDirty${where}`
+      } else if (mission.sandbox !== undefined) {
+        return `mission ${id} is a build and may not have a sandbox${where}`
+      }
+    }
     if (mission.worktree !== undefined && mission.worktree !== null && !isPlainObject(mission.worktree)) {
       return `mission ${id} has an invalid worktree record${where}`
     }

package/domain/state/semantics.js

@@ -1,12 +1,10 @@
-// Semantic state-file checks (#56 P4).
-//
-// `stateShapeError` proves the structural contract; this module owns the policy
-// the shape cannot express: unique ids, status/verdict vocabularies, the review
-// exemption, roster/agent uniqueness, worktree records and the revision
-// counter. Messages keep the historical `[tower:state-corrupt]` wording.
+// State semantics that a structural schema cannot express: uniqueness,
+// status vocabularies, review exemption and per-kind mission fields (#149).
 // @ts-check
+import { FINDING_STATUSES, MERGE_VERDICTS, REVIEW_STATUS_RE } from '../mission.js'
+import { BATCH_STATUSES } from '../batch.js'
 import { TowerToolError } from '../errors.js'
-import { FINDING_STATUSES, MERGE_VERDICTS, MISSION_STATUSES, REVIEW_STATUS_RE } from '../mission.js'
+import { isShapeKind, shapeFor } from '../shapes/index.js'
 
 /** @typedef {import('../../types/index.js').TowerState} TowerState */
 
@@ -19,11 +17,52 @@ function fail(message) {
 }
 
 /**
- * @param {unknown} value
- * @returns {boolean}
+ * A build mission may carry a worktree/branch/merge projection; a survey may
+ * not, and carries the read fingerprint instead. The shape declares which
+ * dimensions its document owns, so this module never compares kinds.
+ * @param {Record<string, any>} mission
+ * @param {string} where
+ * @returns {void}
  */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
+function assertMissionShapeFields(mission, where) {
+  if (!isShapeKind(mission.kind)) {
+    fail(`mission ${mission.id} has unknown kind ${String(mission.kind)}${where}`)
+  }
+  const shape = shapeFor(mission.kind)
+  if (!shape.fields.worktree) {
+    if (mission.worktree !== undefined && mission.worktree !== null) {
+      fail(`mission ${mission.id} is a ${shape.kind} and may not have a worktree record${where}`)
+    }
+    for (const key of ['branch', 'baseCommit', 'mergedCommit', 'mergedAt']) {
+      if (mission[key] !== undefined && mission[key] !== null) {
+        fail(`mission ${mission.id} is a ${shape.kind} and may not have ${key}${where}`)
+      }
+    }
+  }
+  if (shape.fields.worktree) {
+    if (mission.sandbox !== undefined) {
+      fail(`mission ${mission.id} is a ${shape.kind} and may not have a sandbox${where}`)
+    }
+  } else if (shape.fields.sandbox) {
+    // A detached survey sandbox is a recorded path, never a worktree record: it
+    // has no branch, base commit or merge projection.
+    if (mission.sandbox !== undefined && (typeof mission.sandbox !== 'string' || mission.sandbox.length === 0)) {
+      fail(`mission ${mission.id} has an invalid sandbox path${where}`)
+    }
+  } else if (mission.sandbox !== undefined) {
+    fail(`mission ${mission.id} is a ${shape.kind} and may not have a sandbox${where}`)
+  }
+  if (shape.fields.readCommit) {
+    if (typeof mission.readCommit !== 'string' || mission.readCommit.length === 0) {
+      fail(`mission ${mission.id} is a ${shape.kind} and needs a readCommit${where}`)
+    }
+    if (mission.readDirty === undefined) return
+    if (!Array.isArray(mission.readDirty) || mission.readDirty.some((entry) => typeof entry !== 'string')) {
+      fail(`mission ${mission.id} has an invalid readDirty fingerprint${where}`)
+    }
+  } else if (mission.readCommit !== undefined || mission.readDirty !== undefined) {
+    fail(`mission ${mission.id} is a ${shape.kind} and may not have readCommit/readDirty${where}`)
+  }
 }
 
 /**
@@ -42,6 +81,14 @@ function assertWorktreeRecord(mission, where) {
   if (invalid) fail(`mission ${mission.id} has an invalid worktree record${where}`)
 }
 
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
 /**
  * @param {unknown} state
  * @param {string} where
@@ -56,8 +103,9 @@ export function assertStateSemantics(state, where) {
   for (const mission of record.missions) {
     if (missionIds.has(mission.id)) fail(`duplicate mission id ${mission.id}${where}`)
     missionIds.add(mission.id)
-    if (!MISSION_STATUSES.includes(mission.status)) {
-      fail(`mission ${mission.id} has unknown status ${mission.status}${where}`)
+    const shape = shapeFor(mission.kind)
+    if (!shape.statuses.includes(mission.status)) {
+      fail(`mission ${mission.id} has unknown status ${mission.status} for a ${shape.kind} mission${where}`)
     }
     if (mission.reviewPolicy !== undefined && !['required-clean', 'none'].includes(mission.reviewPolicy)) {
       fail(`mission ${mission.id} has unknown reviewPolicy ${mission.reviewPolicy}${where}`)
@@ -65,7 +113,24 @@ export function assertStateSemantics(state, where) {
     if (mission.reviewPolicy === 'none' && !String(mission.reviewExemptionReason ?? '').trim()) {
       fail(`mission ${mission.id} has reviewPolicy none without a reason${where}`)
     }
+    assertMissionShapeFields(mission, where)
     assertWorktreeRecord(mission, where)
+    // W3: `blocked` is derived from open blockers, never an independent stop
+    // state. A non-terminal mission is blocked exactly when it records a
+    // blocker, so the two can never disagree (a paused mission has no blockers;
+    // a blocker supersedes a pause). Terminal missions keep blockers as history.
+    const blockers = mission.blockers ?? []
+    if (!Array.isArray(blockers) || blockers.some((entry) => typeof entry !== 'string')) {
+      fail(`mission ${mission.id} has invalid blockers${where}`)
+    }
+    if (!shape.isTerminal(mission.status)) {
+      if (mission.status === 'blocked' && blockers.length === 0) {
+        fail(`mission ${mission.id} is blocked but records no blocker; blocked is derived from open blockers${where}`)
+      }
+      if (mission.status !== 'blocked' && blockers.length > 0) {
+        fail(`mission ${mission.id} has open blockers but is ${mission.status}; blocked is derived from open blockers${where}`)
+      }
+    }
   }
   if (record.roster !== undefined) {
     const names = new Set()
@@ -113,5 +178,20 @@ export function assertStateSemantics(state, where) {
       }
     }
   }
+  // Batches have their own generic lifecycle (#149 W3), not a mission shape. The
+  // ledger may only carry canonical statuses; legacy synonyms are normalized by
+  // the v5 state migration, never accepted at rest.
+  if (record.batches !== undefined) {
+    const ids = new Set()
+    for (const batch of record.batches) {
+      if (!isPlainObject(batch)) fail(`invalid batch record${where}`)
+      if (ids.has(batch.id)) fail(`duplicate batch id ${batch.id}${where}`)
+      ids.add(batch.id)
+      const status = typeof batch.status === 'string' ? batch.status : ''
+      if (!BATCH_STATUSES.includes(status)) {
+        fail(`batch ${batch.id} has unknown status ${batch.status}${where}`)
+      }
+    }
+  }
   return /** @type {TowerState} */ (record)
 }

package/domain/state.js

@@ -150,7 +150,10 @@ export function validateState(state, statePath) {
  *
  * @param {unknown} state
  * @param {string} [statePath]
- * @param {{ migrations?: readonly StateMigration[] }} [options]
+ * @param {{
+ *   migrations?: readonly StateMigration[],
+ *   legacySurveyRead?: import('./state/migrations.js').LegacySurveyRead | null,
+ * }} [options]
  * @returns {{ state: TowerState, from: number, to: number, migrated: MigrationStep[], changed: boolean }}
  */
 export function prepareState(state, statePath, options = {}) {
@@ -169,6 +172,7 @@ export function prepareState(state, statePath, options = {}) {
     statePath,
     to: info.supportedVersion,
     migrations: options.migrations,
+    legacySurveyRead: options.legacySurveyRead ?? null,
   })
   // Validation runs on the *target* document: a shape that was invalid under
   // the old schema (a missing `tasks` array, say) may be valid after a backfill,

package/domain/summary.js

@@ -2,6 +2,7 @@
 // @ts-check
 import { FINDING_STATUSES } from './mission.js'
 import { completionReportBytes } from './missions/completion.js'
+import { shapeFor } from './shapes/index.js'
 
 /** @typedef {import('../types/index.js').Finding} Finding */
 /** @typedef {import('../types/index.js').FindingSummary} FindingSummary */
@@ -31,7 +32,8 @@ function taskCounts(tasks) {
  * @returns {MissionSummary}
  */
 export function missionSummary(mission) {
-  return {
+  const shape = shapeFor(mission.kind)
+  return /** @type {MissionSummary} */ ({
     id: mission.id,
     title: mission.title,
     kind: mission.kind,
@@ -39,24 +41,16 @@ export function missionSummary(mission) {
     scope: mission.scope,
     deps: mission.deps,
     owner: mission.owner ?? null,
-    worktree: mission.worktree
-      ? {
-          path: mission.worktree.path,
-          branch: mission.worktree.branch,
-          baseCommit: mission.worktree.baseCommit,
-        }
-      : null,
+    ...shape.summary(mission),
     blockers: mission.blockers ?? [],
     tasks: taskCounts(mission.tasks ?? []),
     scopeGeneration: mission.scopeGeneration ?? 1,
     ownerGeneration: mission.ownerGeneration ?? 0,
     pauseCause: mission.pauseCause ?? null,
     reviewPolicy: mission.reviewPolicy ?? 'required-clean',
-    mergedCommit: mission.mergedCommit ?? null,
-    mergedAt: mission.mergedAt ?? null,
     reportBytes: completionReportBytes(mission.completionReport),
     updatedAt: mission.updatedAt,
-  }
+  })
 }
 
 /**

package/domain/vocabulary.js

@@ -13,6 +13,7 @@ import {
   PAUSE_CAUSES,
 } from './mission.js'
 import { ROSTER_INACTIVE_STATES } from './roster.js'
+import { SHAPE_KINDS } from './shapes/index.js'
 
 export {
   FINDING_SEVERITIES,
@@ -24,44 +25,25 @@ export {
   ROSTER_INACTIVE_STATES,
 }
 
-// Mission inputs accepted by tower_plan.
+// Mission inputs accepted by tower_plan: the registry's kinds, in order.
 /** @type {readonly string[]} */
-export const MISSION_KINDS = ['build', 'survey']
+export const MISSION_KINDS = SHAPE_KINDS
 /** @type {readonly string[]} */
 export const REVIEW_POLICIES = ['required-clean', 'none']
 
 // Roster actors (the caller resolved by actorFor) and createable agent roles.
-export const ROLE = Object.freeze({
-  tower: 'tower',
-  worker: 'worker',
-  reviewer: 'reviewer',
-  unknown: 'unknown',
-})
-/** @type {readonly string[]} */
-export const ROLES = Object.freeze([ROLE.worker, ROLE.reviewer])
-/** @type {readonly string[]} */
-export const ACTOR_ROLES = Object.freeze([ROLE.tower, ROLE.worker, ROLE.reviewer, ROLE.unknown])
-export const DEFAULT_ROLE = ROLE.worker
-
-/** @param {string | null | undefined} role */
-export function isTowerRole(role) {
-  return role === ROLE.tower
-}
-
-/** @param {string | null | undefined} role */
-export function isWorkerRole(role) {
-  return role === ROLE.worker
-}
-
-/** @param {string | null | undefined} role */
-export function isReviewerRole(role) {
-  return role === ROLE.reviewer
-}
-
-/** @param {string | null | undefined} role */
-export function isUnknownRole(role) {
-  return role === ROLE.unknown
-}
+// One definition lives in domain/roles.js so roster/vocabulary have no cycle.
+import { ROLE } from './roles.js'
+export {
+  ACTOR_ROLES,
+  DEFAULT_ROLE,
+  ROLE,
+  ROLES,
+  isReviewerRole,
+  isTowerRole,
+  isUnknownRole,
+  isWorkerRole,
+} from './roles.js'
 
 // Inbox recipients: a roster name, the tower, or a broadcast.
 export const RECIPIENT = Object.freeze({ tower: ROLE.tower, all: 'all' })

package/host/capability-registry.js

@@ -25,6 +25,7 @@ export const TOWER_COMPONENT_IDS = Object.freeze([
   'tower-archive',
   'tower-hmr',
   'preset-tower-reviewer',
+  'tower-survey',
 ])
 
 /** Tool ids each code component owns; the preset row owns no tool. */
@@ -38,6 +39,7 @@ export const COMPONENT_TOOLS = Object.freeze({
   'tower-archive': Object.freeze([]),
   'tower-hmr': Object.freeze(['tower_reload']),
   'preset-tower-reviewer': Object.freeze([]),
+  'tower-survey': Object.freeze([]),
 })
 
 /** id -> number of live registrations (redelivery/HMR can overlap briefly). */
@@ -86,23 +88,37 @@ export function disabledReason(id) {
   return `disabled by component ${id}`
 }
 
-/** Reviewer-preset availability from the optional agent-presets service. */
-async function reviewerPresetAvailable(ctx) {
+/**
+ * Availability of one declarative preset row from the optional agent-presets
+ * service. Preset rows (`preset-tower-reviewer`, `tower-survey`) mount an agent
+ * preset instead of a code entry point, so the process-local component registry
+ * cannot see them.
+ * @param {any} ctx
+ * @param {string} presetId the agent-preset id the row registers
+ * @returns {Promise<boolean | null>} null when the service cannot answer
+ */
+export async function presetAvailable(ctx, presetId) {
   const service = ctx?.get?.('agentPresets')
   if (!service || typeof service.list !== 'function') return null
   try {
     const presets = await service.list()
-    return Array.isArray(presets) && presets.some((entry) => String(entry?.id) === 'tower-reviewer')
+    return Array.isArray(presets) && presets.some((entry) => String(entry?.id) === presetId)
   } catch {
     return null
   }
 }
 
+/** Component rows whose switch is a declarative agent-preset registration. */
+export const PRESET_ROW_COMPONENTS = Object.freeze({
+  'preset-tower-reviewer': 'tower-reviewer',
+  'tower-survey': 'tower-survey',
+})
+
 /**
- * Report every optional component as enabled or disabled. The reviewer preset
- * is not a code entry point: its row mounts an agent preset, so availability is
- * read from `agentPresets` and reported as unknown (omitted) when that service
- * is absent, exactly as the doctor's preset check does.
+ * Report every optional component as enabled or disabled. A preset row is not a
+ * code entry point: its availability is read from `agentPresets` and reported as
+ * unknown (omitted) when that service is absent, exactly as the doctor's preset
+ * check does.
  *
  * @param {any} ctx
  * @returns {Promise<{ enabled: string[], disabled: Array<{ id: string, reason: string }> }>}
@@ -111,8 +127,8 @@ export async function componentReport(ctx) {
   const enabled = []
   const disabled = []
   for (const id of TOWER_COMPONENT_IDS) {
-    if (id === 'preset-tower-reviewer') {
-      const available = await reviewerPresetAvailable(ctx)
+    if (PRESET_ROW_COMPONENTS[id]) {
+      const available = await presetAvailable(ctx, PRESET_ROW_COMPONENTS[id])
       if (available === false) disabled.push({ id, reason: disabledReason(id) })
       else if (available === true) enabled.push(id)
       continue

package/host/doctor.js

@@ -12,6 +12,7 @@ import { inspectStateVersion } from '../domain/state.js'
 import { SCHEMA_VERSION } from '../domain/mission.js'
 import { DEFAULT_MAX_REPORT_BYTES, completionReportBytes } from '../domain/missions/completion.js'
 import { comparisonMode } from '../domain/scope.js'
+import { hasTestReceipts } from '../domain/evidence.js'
 import { configSurface } from '../domain/config/schema.js'
 import { reviewPolicyView, reviewRequired } from '../domain/integration/review.js'
 import { parseBaseline, surfaceLine, SURFACE_BASELINE_FILE } from '../domain/surface.js'
@@ -454,7 +455,7 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
           : check('worktrees', 'pass', `all registered worktrees are valid${removedNote}`),
     )
 
-    const testConfigured = state.missions?.some((mission) => mission.testRuns !== undefined)
+    const testConfigured = state.missions?.some((mission) => hasTestReceipts(mission))
     // #136: the `tower-tests` component row is the only switch (there is no
     // tests.enabled), so this check reads the registry and nothing else.
     const testsDisabled = components.disabled.some((entry) => entry.id === 'tower-tests')

package/host/preset-survey-sandbox.js

@@ -0,0 +1,19 @@
+// Tower detached-survey preset declaration (#148 W2): the sandbox preset's own
+// Plugins-page label. This is the writable twin of `host/preset-survey.js`: the
+// row config stays in `cordis.patch.yml` and this module forwards it to the
+// injected `agentPresets` service, which owns mount/unmount. A Tower-owned
+// specifier gives the row a distinct locale
+// (`dsh-tower/preset-survey-sandbox/locale/<lang>.json`).
+export const name = 'dsh-tower/preset-survey-sandbox'
+
+export const inject = ['agentPresets']
+
+/**
+ * Register the detached-survey preset with the profile's preset registry.
+ * @param {{ agentPresets: { register: (config: any) => Promise<() => Promise<void> | void> } }} ctx
+ * @param {any} config the `cordis.patch.yml` row config (id/name/description/order/plugins)
+ * @returns {Promise<() => Promise<void> | void>} the registry's unregister disposer
+ */
+export async function apply(ctx, config) {
+  return ctx.agentPresets.register(config)
+}