dsh-tower 2.6.0 → 2.7.0

package/domain/collab/batch.js

@@ -1,12 +1,14 @@
 // Pure batch lifecycle decisions and status projection.
 //
-// `domain/batch.js` owns the admission/close evidence validation; this module
-// owns the id assignment, close/abandon record transitions, and status payload
-// that app/batch.js used to keep inline. Receipt file reads stay in the tool
-// layer.
+// `domain/batch.js` owns the lifecycle vocabulary, admission/close evidence
+// validation and normalization; this module owns the id assignment, close/abandon
+// record transitions, and status payload that app/batch.js used to keep inline.
+// Receipt file reads stay in the tool layer. Every status move goes through the
+// lifecycle module's `canTransitionBatch`, so this file never names a status
+// literal of its own (#149 W3).
 // @ts-check
 import { TowerToolError } from '../errors.js'
-import { summarize } from '../batch.js'
+import { BATCH_STATUS, canTransitionBatch, isBatchTerminal, normalizeBatchStatus, summarize } from '../batch.js'
 
 /** @typedef {import('../../types/index.js').TowerState} TowerState */
 
@@ -19,6 +21,21 @@ function fail(message, code = 'batch-invalid') {
   throw new TowerToolError(code, message)
 }
 
+/**
+ * Move a draft batch to `to`, refusing a transition the lifecycle does not
+ * allow. A no-op (already at the target) is handled by the callers, not here.
+ * @param {any} batch
+ * @param {string} to
+ * @param {string} batchId
+ * @returns {void}
+ */
+function assertBatchMove(batch, to, batchId) {
+  const from = normalizeBatchStatus(batch.status)
+  if (!canTransitionBatch(from, to)) {
+    fail(`batch ${batchId} is ${from}; it cannot move to ${to}${isBatchTerminal(from) ? ' (a batch is closed or abandoned exactly once)' : ''}`)
+  }
+}
+
 /**
  * Next free `B<n>` id.
  * @param {any[]} batches
@@ -43,7 +60,7 @@ export function nextBatchId(batches) {
 export function createBatchRecord(id, normalized, actor, now) {
   return {
     id,
-    status: 'open',
+    status: BATCH_STATUS.OPEN,
     ...normalized,
     createdBy: actor,
     createdAt: now,
@@ -59,7 +76,8 @@ export function createBatchRecord(id, normalized, actor, now) {
  * @returns {any}
  */
 export function closeBatchRecord(batch, options, actor, now) {
-  batch.status = 'closed'
+  assertBatchMove(batch, BATCH_STATUS.CLOSED, String(batch.id ?? ''))
+  batch.status = BATCH_STATUS.CLOSED
   batch.closedAt = now
   batch.closedBy = actor
   batch.close = {
@@ -78,8 +96,9 @@ export function closeBatchRecord(batch, options, actor, now) {
  * @returns {{ alreadyAbandoned: boolean }}
  */
 export function abandonBatchCheck(batch, batchId) {
-  if (batch.status === 'closed') fail(`batch ${batchId} is already closed`)
-  return { alreadyAbandoned: batch.status === 'abandoned' }
+  const status = normalizeBatchStatus(batch.status)
+  if (status === BATCH_STATUS.CLOSED) fail(`batch ${batchId} is already closed`)
+  return { alreadyAbandoned: status === BATCH_STATUS.ABANDONED }
 }
 
 /**
@@ -88,7 +107,8 @@ export function abandonBatchCheck(batch, batchId) {
  * @returns {any}
  */
 export function applyBatchAbandon({ batch, actor, reason, now }) {
-  batch.status = 'abandoned'
+  assertBatchMove(batch, BATCH_STATUS.ABANDONED, String(batch.id ?? ''))
+  batch.status = BATCH_STATUS.ABANDONED
   batch.abandonedAt = now
   batch.abandonedBy = actor
   batch.abandonReason = typeof reason === 'string' && reason.trim() ? reason.trim() : null

package/domain/collab/spawn.js

@@ -7,6 +7,8 @@
 // @ts-check
 import { TowerToolError } from '../errors.js'
 import { ROSTER_INACTIVE, countLiveWorkers, workerEntries } from '../roster.js'
+import { isReviewerRole, isWorkerRole } from '../roles.js'
+import { shapeFor } from '../shapes/index.js'
 import { clearStale } from './roster.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
@@ -14,19 +16,14 @@ import { clearStale } from './roster.js'
 
 /**
  * @param {string} message
+ * @param {string} [code]
  * @returns {never}
  */
-function fail(message) {
-  throw new TowerToolError('invalid-argument', message)
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
 }
 
-/**
- * @param {unknown} role
- * @returns {boolean}
- */
-export function isWorkerRole(role) {
-  return role === 'worker'
-}
+export { isWorkerRole } from '../roles.js'
 
 /**
  * The configured live-worker ceiling, defaulting to four.
@@ -67,6 +64,26 @@ export function applyInterrupt(entry, input, now) {
   return entry
 }
 
+/**
+ * A reviewer's evidence is the commit recorded here, never a live branch tip
+ * read later (#149 W3). The checkout is the disposable detached worktree the
+ * reviewer reads in; it is cleared when the verdict is recorded.
+ * @param {any} input
+ * @param {{ requireReviewCommit?: boolean }} [options]
+ * @returns {{ reviewCommit: string | null, reviewCheckout: string | null }}
+ */
+function reviewEvidence(input, options = {}) {
+  const reviewCommit = typeof input.reviewCommit === 'string' && input.reviewCommit.length > 0 ? input.reviewCommit : null
+  const reviewCheckout = typeof input.reviewCheckout === 'string' && input.reviewCheckout.length > 0 ? input.reviewCheckout : null
+  if (options.requireReviewCommit && isReviewerRole(input.role) && !reviewCommit) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `reviewer ${input.name} has no recorded review commit; spawn reviewers through tower_spawn (a review verdict is stamped with a commit, not a live branch tip)`,
+    )
+  }
+  return { reviewCommit, reviewCheckout }
+}
+
 /**
  * A reserved roster row: the name is claimed before activation so a failed
  * spawn remains recoverable.
@@ -75,6 +92,7 @@ export function applyInterrupt(entry, input, now) {
  * @returns {RosterEntry}
  */
 export function reservedRosterEntry(input, now) {
+  const evidence = reviewEvidence(input, { requireReviewCommit: true })
   return {
     name: input.name,
     role: input.role,
@@ -84,6 +102,8 @@ export function reservedRosterEntry(input, now) {
     missionId: input.missionId,
     cwd: input.cwd ?? null,
     branch: input.branch ?? null,
+    ...(evidence.reviewCommit ? { reviewCommit: evidence.reviewCommit } : {}),
+    ...(evidence.reviewCheckout ? { reviewCheckout: evidence.reviewCheckout } : {}),
     spawnTip: null,
     state: 'reserved',
     reservedAt: now,
@@ -104,10 +124,15 @@ export function reserveRosterEntry({ roster, input, now }) {
 /**
  * Validate and apply a spawn record. Mutates the roster (retiring prior worker
  * rows and inserting/reusing the entry) and the mission owner/status/gen.
- * @param {{ roster: RosterEntry[], mission: Mission, input: any, spawnTip: string | null, maxLiveWorkers: unknown, now: number }} params
+ *
+ * `missions` is the state's mission list, not just the spawned mission: the live
+ * worker count resolves every roster row's kind through the shape registry, so a
+ * survey row must not be counted as a build worker (#148). Callers that omit it
+ * (direct domain tests) keep the historical roster-only treatment.
+ * @param {{ roster: RosterEntry[], missions?: Mission[], mission: Mission, input: any, spawnTip: string | null, maxLiveWorkers: unknown, now: number }} params
  * @returns {RosterEntry}
  */
-export function recordSpawnEntry({ roster, mission, input, spawnTip, maxLiveWorkers, now }) {
+export function recordSpawnEntry({ roster, missions = [], mission, input, spawnTip, maxLiveWorkers, now }) {
   const reserved = roster.find((entry) => entry.name === input.name && entry.state === 'reserved' && !entry.agentId)
   if (!reserved && roster.some((entry) => entry.name === input.name)) {
     fail(`roster name already used: ${input.name}`)
@@ -115,7 +140,9 @@ export function recordSpawnEntry({ roster, mission, input, spawnTip, maxLiveWork
   if (roster.some((entry) => entry.agentId && entry.agentId === input.agentId)) {
     fail(`agent ${input.agentId} is already in the roster`)
   }
-  /** @type {RosterEntry} */
+  /** @type {{ reviewCommit?: string | null, reviewCheckout?: string | null }} */
+  const evidence = reviewEvidence(input, { requireReviewCommit: true })
+  /** @type {RosterEntry & { generation?: number }} */
   const entry = {
     name: input.name,
     role: input.role,
@@ -125,12 +152,14 @@ export function recordSpawnEntry({ roster, mission, input, spawnTip, maxLiveWork
     missionId: input.missionId,
     cwd: input.cwd ?? null,
     branch: input.branch ?? null,
+    ...(evidence.reviewCommit ? { reviewCommit: evidence.reviewCommit } : {}),
+    ...(evidence.reviewCheckout ? { reviewCheckout: evidence.reviewCheckout } : {}),
     spawnTip,
     state: 'active',
     spawnedAt: now,
   }
   if (isWorkerRole(input.role)) {
-    const snapshot = /** @type {any} */ ({ roster })
+    const snapshot = /** @type {any} */ ({ roster, missions })
     const previous = workerEntries(snapshot, mission.id)
     const live = previous.find((row) => !ROSTER_INACTIVE.has(row.state) && row.state !== 'reserved')
     if (live && !input.takeover) {
@@ -148,9 +177,17 @@ export function recordSpawnEntry({ roster, mission, input, spawnTip, maxLiveWork
       old.outcomeAt = now
       clearStale(old)
     }
-    const max = liveWorkerLimit(maxLiveWorkers)
-    if (countLiveWorkers(snapshot) >= max) {
-      fail(`live worker limit reached (${max}); stop a worker or raise spawn.maxLiveWorkers`)
+    // A shape that does not count toward the live-worker budget (the read-only
+    // survey) must pass even when every build slot is busy; otherwise the
+    // precheck and the record-level check disagree (#148).
+    if (shapeFor(mission.kind).spawn.countsTowardWorkerBudget !== false) {
+      const max = liveWorkerLimit(maxLiveWorkers)
+      if (countLiveWorkers(snapshot) >= max) {
+        fail(
+          `live worker limit reached (${max}); stop a worker or raise spawn.maxLiveWorkers`,
+          'worker-limit',
+        )
+      }
     }
     const generation = (mission.ownerGeneration ?? 0) + 1
     entry.generation = generation

package/domain/config/schema.js

@@ -37,7 +37,7 @@ const LEGACY_KEYS = ['section', 'allowAgentControl']
 // #121: the `tools` group is gone. Every capability that used to be a
 // `tools.expose*` boolean is now a component row in `cordis.patch.yml`, and a
 // component row is the switch. What remains here is genuine tuning policy.
-const GROUP_KEYS = ['init', 'mode', 'review', 'merge', 'git', 'worktrees', 'spawn', 'send', 'tests', 'gates', 'docs', 'archive', 'leases', 'dev']
+const GROUP_KEYS = ['init', 'mode', 'review', 'merge', 'git', 'worktrees', 'spawn', 'send', 'survey', 'tests', 'gates', 'docs', 'archive', 'leases', 'dev']
 
 const SECTION_KEYS = {
   init: ['autoGitInit', 'snapshotDirty', 'autoExclude'],
@@ -69,40 +69,54 @@ const SECTION_KEYS = {
     'provider',
     'workerModel',
     'reviewerModel',
+    'surveyModel',
     'maxLiveWorkers',
     'staleMs',
     'maxWaitMs',
     'requireLease',
   ],
   send: ['maxPerMinute', 'interruptDefault'],
-  tests: ['admission', 'timeoutMs', 'maxBytes', 'autoChecks', 'allowPackageDiscovery'],
-  gates: ['requireChecks', 'requireTests', 'allowReviewExemption', 'maxReportBytes'],
+  // #148 W2: where a survey reads. This is tuning, not a component: the
+  // tower-survey row is the switch; the placement decides whether write/shell
+  // side effects are rejected (shared) or absorbed by a disposable checkout.
+  survey: ['sandbox'],
+  tests: ['admission', 'timeoutMs', 'maxBytes', 'allowPackageDiscovery'],
+  gates: ['requireChecks', 'requireTests', 'allowReviewExemption', 'requireFreshSurvey', 'maxReportBytes'],
   docs: ['boardLocation'],
   archive: ['afterDays', 'maxMissions'],
   leases: ['ttlMs'],
   dev: ['reloadDelayMs', 'reloadRequiredIds'],
 }
 
-// #133/#135: `docs.board` and `archive.enabled` were component-shaped switches
-// hiding in the config form. They are component rows now, so a legacy config
-// keeps failing as an unknown key — with an upgrade note naming the row that
-// replaced it.
-/** @type {Record<string, string>} */
+// #133/#135/#149: a removed key keeps failing as an unknown key — with an
+// upgrade note naming what replaced it. `docs.board` and `archive.enabled`
+// were component-shaped switches hiding in the config form, so their note
+// names the component row. `tests.autoChecks` existed only to copy a discovery
+// projection into the completion report; its replacement is the `testRuns`
+// receipt (whose concrete record path belongs to domain/evidence.js), so the
+// note names the receipt and the one reader instead of a row.
+/** @type {Record<string, { component?: string, note?: string }>} */
 const REMOVED_KEYS = {
-  'docs.board': 'tower-board',
-  'archive.enabled': 'tower-archive',
+  'docs.board': { component: 'tower-board' },
+  'archive.enabled': { component: 'tower-archive' },
+  'tests.autoChecks': {
+    note: 'tests.autoChecks was removed: test evidence is the testRuns receipt read by domain/evidence.js (see docs/adr/0006-mission-shapes.md)',
+  },
 }
 
 /**
- * Upgrade note for a removed component switch, appended to the unknown-key error.
+ * Upgrade note for a removed key, appended to the unknown-key error.
  * @param {string} group
  * @param {string} key
  * @returns {string}
  */
 function removedKeyNote(group, key) {
-  const component = REMOVED_KEYS[`${group}.${key}`]
-  if (!component) return ''
-  return ` — ${group}.${key} was removed: the ${component} component row in cordis.patch.yml is the switch (see docs/adr/0005-component-surface.md)`
+  const entry = REMOVED_KEYS[`${group}.${key}`]
+  if (!entry) return ''
+  if (entry.component) {
+    return ` — ${group}.${key} was removed: the ${entry.component} component row in cordis.patch.yml is the switch (see docs/adr/0005-component-surface.md)`
+  }
+  return ` — ${entry.note}`
 }
 
 const MODEL_KEYS = ['provider', 'model', 'reasoningEffort', 'maxTokens']
@@ -216,12 +230,13 @@ export const Config = Schema.object({
     .default({})
     .description('Worktree placement.'),
   spawn: Schema.object({
-    workerPreset: Schema.string().default('tower-worker').description('Agent preset for worker missions.'),
+    workerPreset: Schema.string().default('tower-worker').description('Agent preset for build workers.'),
     reviewerPreset: Schema.string().default('tower-reviewer').description('Agent preset for reviewers.'),
     maxDepth: Schema.natural().min(1).default(1).description('Subagent depth requested when spawning tower agents.'),
     provider: Schema.string().description('Subagent provider id; empty picks spawn, then the first registered provider.'),
     workerModel: ModelSchema().description('Model route for workers; omitted inherits the parent session.'),
     reviewerModel: ModelSchema().description('Model route for reviewers; omitted inherits the parent session (recommended).'),
+    surveyModel: ModelSchema().description('Model route for survey workers; omitted inherits the parent session.'),
     maxLiveWorkers: Schema.natural()
       .min(1)
       .max(64)
@@ -251,6 +266,15 @@ export const Config = Schema.object({
   })
     .default({})
     .description('Message delivery policy.'),
+  survey: Schema.object({
+    sandbox: Schema.union(['none', 'detached'])
+      .default('none')
+      .description(
+        'Where a survey reads. none = the shared checkout with a read-only preset (writes and shell commands are impossible); detached = a disposable detached git worktree created at the recorded commit, with a sandbox preset that may write and run commands inside it. A detached sandbox is removed when the survey completes or is abandoned; it has no branch, never participates in merge/stale-base, and cannot commit its evidence.',
+      ),
+  })
+    .default({})
+    .description('Survey placement. Tuning only: the tower-survey component row is the capability switch.'),
   tests: Schema.object({
     // #136: no `enabled` switch. The `tower-tests` component row *is* the
     // switch; a second boolean could only disagree with it, and a row-off
@@ -260,7 +284,6 @@ export const Config = Schema.object({
       .description('Run discovery before spawning a worker, when completing, or only on explicit tower_test (default off: repository code runs only on an explicit tower_test).'),
     timeoutMs: Schema.natural().min(1000).max(1800000).default(60000).description('Per discovery command timeout.'),
     maxBytes: Schema.natural().min(1024).max(16 * 1024 * 1024).default(16 * 1024 * 1024).description('Maximum captured stdout bytes per command.'),
-    autoChecks: Schema.boolean().default(true).description('Attach a tests check to the completion report when discovery runs.'),
     allowPackageDiscovery: Schema.boolean()
       .default(true)
       .description('Allow package.json tower.testDiscovery commands from the mission worktree (executes repository code; see security docs).'),
@@ -270,13 +293,16 @@ export const Config = Schema.object({
   gates: Schema.object({
     requireChecks: Schema.boolean()
       .default(false)
-      .description('Require at least one completion check (tower_complete.checks) before a mission can merge.'),
+      .description('Require at least one recorded check (tower_complete.checks) or test-discovery receipt before a mission can merge.'),
     requireTests: Schema.boolean()
       .default(false)
       .description('Require a passing test-discovery receipt for the reviewed worktree tip before merge.'),
     allowReviewExemption: Schema.boolean()
       .default(false)
       .description('Allow reviewPolicy:none missions with a non-empty reviewExemptionReason to skip review blockers.'),
+    requireFreshSurvey: Schema.boolean()
+      .default(false)
+      .description('Promote the advisory survey-stale dependency warning to a merge blocker: a build may only merge when every survey dependency read a commit that is an ancestor-or-equal of the build base. Default false (warning only).'),
     maxReportBytes: Schema.natural()
       .min(1024)
       .max(16 * 1024 * 1024)
@@ -429,6 +455,9 @@ export function assertKnownKeys(raw, label) {
     if ((group === 'spawn') && value.reviewerModel && typeof value.reviewerModel === 'object') {
       assertModelKeys(value.reviewerModel, `${label} spawn.reviewerModel`)
     }
+    if ((group === 'spawn') && value.surveyModel && typeof value.surveyModel === 'object') {
+      assertModelKeys(value.surveyModel, `${label} spawn.surveyModel`)
+    }
   }
 }
 
@@ -509,6 +538,7 @@ export function resolveTowerConfig(rawConfig) {
     worktrees: clone(parsed.worktrees ?? {}),
     spawn: clone(parsed.spawn ?? {}),
     send: clone(parsed.send ?? {}),
+    survey: clone(parsed.survey ?? {}),
     tests: clone(parsed.tests ?? {}),
     gates: clone(parsed.gates ?? {}),
     docs: clone(parsed.docs ?? {}),

package/domain/contracts/outputs.js

@@ -289,7 +289,6 @@ const SCHEMAS = {
       commands: S.arr(S.obj()),
       error: S.str,
       receipt: S.obj(),
-      checks: S.arr(S.obj()),
     },
     ['ok', 'configured'],
   ),

package/domain/contracts/tool-inputs/missions.js

@@ -17,7 +17,7 @@ export const PlanInput = Type.Object({
       title: Type.String({ description: 'Printable Unicode mission title, NFC-normalized, at most 120 characters; used as the mission label.' }),
       scope: Type.Optional(Type.Array(Type.String(), { description: 'Relative file globs this mission may touch; empty only for survey.' })),
       tasks: Type.Optional(Type.Array(Type.String(), { description: 'Verifiable task items the worker ticks off.' })),
-      deps: Type.Optional(Type.Array(Type.String(), { description: 'Mission ids that must merge before this one.' })),
+      deps: Type.Optional(Type.Array(Type.String(), { description: 'Mission ids that must be satisfied before this one: merged for a build, completed for a survey.' })),
       kind: Type.Optional(enumOf(MISSION_KINDS, { description: 'survey = read-only investigation that reserves no scope.' })),
       context: Type.Optional(Type.String({ description: "The user's own key sentences, verbatim (max 4096 chars)." })),
       references: Type.Optional(Type.Array(Type.String(), { maxItems: 20, description: 'Read-only pointers/files the worker should read (max 20); copied into the briefing.' })),
@@ -63,6 +63,14 @@ export const CompleteInput = Type.Object({
   missionId: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: id).' })),
   id: Type.Optional(Type.String({ description: 'Alias for missionId; both are accepted.' })),
   report: Type.String({ description: 'Full completion report for the tower and the next review round.' }),
+  result: Type.Optional(
+    Type.Object({
+      paths: Type.Optional(Type.Array(Type.String(), { maxItems: 200, description: 'Survey only: paths the read touched or found relevant.' })),
+      symbols: Type.Optional(Type.Array(Type.String(), { maxItems: 200, description: 'Survey only: symbols the read identified.' })),
+      plan: Type.Optional(Type.Array(Type.String(), { maxItems: 200, description: 'Survey only: the ordered plan or next steps the read recommends.' })),
+      notes: Type.Optional(Type.String({ description: 'Survey only: short free-form evidence (max 4000 chars).' })),
+    }, { additionalProperties: false, description: 'Survey evidence; a build completion may not carry one.' }),
+  ),
   checks: Type.Optional(
     Type.Array(
       Type.Object({