dsh-tower 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -4,6 +4,88 @@
 
 ## 未发布（Unreleased）
 
+## 2.7.0（2026-11-10）
+
+### 新增
+
+- **#148 检查任务（survey）成为独立的只读任务形状**：`tower_plan` 接受 `kind: "survey"`，
+  记录 `readCommit` 与 `readDirty`，不创建分支、工作树或提交；完成时要求 HEAD 与记录的提交一致、
+  受版本控制的文件状态不变，并接受可选的结构化结果 `{paths, symbols, notes, plan}`。
+  `tower-survey` 是独立的可选组件行，随包提供只读 preset 与可选的 detached sandbox preset；
+  survey 不占用执行代理并发预算，也不会被要求合并或 rebase。完成的 survey 现在是终态，可归档、
+  满足依赖、不再阻塞 `tower_init --reanchor`，也不再被规划为“未完成工作”。
+- **#148 可写的 detached survey sandbox**：`survey.sandbox: "detached"` 为需要写文件的检查任务
+  提供隔离工作树（无分支，HEAD 固定在 `readCommit`），完成后清理；只读检查仍使用共享检出。
+- **#148 依赖的新鲜度与结果传递**：`survey-stale` 警告在依赖读取落后于当前基准时出现；
+  `gates.requireFreshSurvey: true` 可将它提升为合并阻塞。依赖 briefing 会带上 survey 的
+  `readCommit` 与有界结果（路径/符号/计划/备注）。
+- **#149 形状注册表与维度审计机制**：`domain/shapes/{index,build,survey}.js` 成为任务生命周期的
+  唯一来源；生成式 `docs/reference/shapes.md` 列出 16 个状态维度的裁决、拥有模块与机械规则；
+  `scripts/shape-audit.mjs` 的 12 条规则随 `npm run check` 运行，阻止新的 kind/role 特例与
+  第二套状态词汇。
+- **#149 单一证据读取器**：`domain/evidence.js` 统一读取完成检查、测试发现回执与调用方检查，
+  并保留来源标签；`tower_complete` 不再复制合成 check，`tower_test` 只返回回执。
+- **#149 旧版导入的严格适配器**：`adapters/legacy.js` 声明一种载荷对应一种格式，拒绝混合
+  mission id 命名空间，把 `unresolved` / `dropped` / `remapped` 如实写入摘要与快照记录；导入
+  仍然只读，绝不激活或恢复任务。
+- **#149 形状拥有路径权限**：`shape.reach` 声明 `ownsPaths` 与唯一围栏，`domain/scope.js` 的
+  `scopeFenceBlocker` 成为所有门禁、规划与工作树检查的共同来源。
+- **#149 角色与形状正交**：`domain/roles.js` 的 `ROLE_CONTRACT` 统一解析 spawn、preset、roster、
+  briefing 与预算，不再出现“角色 ∧ 形状”条件；`reviewer` 仍只绑定完成的 build 任务。
+- **#149 审查、批次、租约与阻塞状态的契约化**：reviewer 在记录 commit 的 detached checkout 上
+  审查，裁决绑定该提交；batch 有显式的 `open → closed|abandoned` 生命周期；过期租约需要显式
+  `force` 才能被他人恢复；`blocked` 只由 blockers 派生，不能直接写入。
+
+### 变更
+
+- **状态 schema 从 v3 直接迁移到 v5**：`state.json` 在首次写入时自动执行 v3 → v4 → v5 迁移，
+  保留预迁移备份并只推进一次 `revision`。v4 为 survey 增加 `readCommit`/`readDirty` 字段、
+  移除 worktree/branch/baseCommit/merge 字段；v5 从 blockers 派生 `blocked` 并规范化 batch 状态。
+  只读加载仍在内存中迁移，不回写文件；计划但从未启动的旧 survey 会用 `state.base` 锚定。
+- **配置面 57 → 56 键**：移除 `tests.autoChecks`。旧配置会收到带迁移说明的
+  `config-unknown-key`，指向 `tower_test` 的 `mission.testRuns` 回执与 `domain/evidence.js`；
+  没有替代开关。可见组件仍为 12 个（内部 4 个），工具仍为 29 个，preset 增至 4 个。
+- **直接写 `blocked` 状态被拒绝**：`tower_mission` 不再接受 `status: "blocked"`；使用
+  `blocker` 报告阻塞，使用 `clear_blockers` 解除。`paused` 与 `blocked` 不再重叠。
+- **survey 的合并/变基/预检/差异动作被明确拒绝**：`tower_merge`、`tower_rebase`、
+  `tower_preflight` 与 `tower_diff` 对 survey 返回可操作的 `invalid-transition`，而不是
+  合成 `tip-moved`/`no-review` 等 build 语义。
+- **PR 模板新增形状/角色问题**，并要求说明是否新增了应属于 shape 的条件；生成的形状参考
+  与 ADR 0006 同步更新。
+
+- **#148/#149 形状注册表 W4：证据、旧版导入、scope 与角色的一次性契约。** `domain/evidence.js`
+  成为测试证据的唯一读取者：测试发现回执记录在 `mission.testRuns` 中并按分支 tip 绑定，
+  `tower_complete` 不再把同一证据复制成合成的 `tests` check，门禁、`tower_batch` 与 completion
+  校验都走同一个读取器。删除配置键 `tests.autoChecks`（写入旧键会收到带迁移说明的
+  `config-unknown-key`），配置键 57 → 56。`adapters/legacy.js` 改为严格适配器契约：声明格式与
+  状态重映射（Tower Codex `retired` → `abandoned`）、拒绝混合 mission id 命名空间、把
+  `unresolved` / `dropped` / `remapped` 如实写入摘要与快照记录，并只向消费方暴露规范的
+  `pausedMissionIds`。shape 以 `reach` 拥有路径权限，`domain/scope.js` 的 `scopeFenceBlocker`
+  是唯一围栏；角色与 shape 正交，`domain/roles.js` 的 `ROLE_CONTRACT` 让 spawn 预检、preset、
+  roster 与 gate 各自解析，不再出现"角色 ∧ shape"条件。`shape:audit` 新增四条规则
+  `evidence-single-read`、`legacy-vocabulary`、`scope-reach`、`role-shape-conflation`。
+- **#149 生成的形状参考改为维度清单。** `docs/reference/shapes.md` 现在按 16 个维度列出裁决
+  （shape-owned / correctly generic / redesigned）、拥有模块与机械规则；W1–W4 的裁决同时记录在
+  ADR 0006 的 W4 附录中。
+
+### 修复
+
+- **完成的 survey 不再死锁管理动作**：`tower_init --reanchor` 不再因一个完成的 survey 被拒绝；
+  survey 可归档并计入 `archive.maxMissions`；规划不再把它算作未完成工作。
+- **survey 完成可正常确认收件箱**：只读与 sandbox preset 现在包含 `tower_inbox`，避免存在未读
+  消息时完成被 `completion.js` 拒绝。
+- **旧版计划中的 survey 可迁移**：当 v2.6.0 的 survey 只有 `kind`、没有 baseCommit/worktree 时，
+  迁移用 `state.base` 与真实 tracked fingerprint 锚定，不再让每次加载都以
+  `state-migration-failed` 失败。
+- **detached sandbox 的 briefing 使用 sandbox 路径**：不再把 `workdir` 指向主检出，并把空 scope
+  说明改为“可写 sandbox”而非“只读检查”。
+- **归档 survey 的依赖证据不再丢失**：归档索引保留有界的 `readCommit` 与结果；依赖 briefing 与
+  `requireFreshSurvey` 在归档后仍能判断新鲜度，不会因缺少证据而失败开放。
+- **已记录的 sandbox 决定完成路径**：`mission.sandbox` 优先于当前配置，避免运行中把 detached 改回
+  `none` 时错误删除 sandbox 或切换完成规则。
+- **review checkout 的陈旧路径可恢复**，teardown 会清理残留的审查检出；survey 不占 build 执行
+  代理预算。
+
 ## 2.6.0（2026-11-01）
 
 ### 新增

package/COMPATIBILITY.md

@@ -5,6 +5,7 @@ is shipped in the npm package; doctor reads it locally and never contacts a regi
 
 | dsh version | tag / commit | verified on | what was run |
 |---|---|---|---|
+| 0.2.1-rc.2 | v2.7.0 | 2026-11-10 | mount smoke (28/28 default tools, 3 skills, 4 presets with distinct labels, 1 bundle row), `npm run test:property` (111), full static gate chain, focused shape/survey/evidence/scope/role/review/batch/leases tests, CI `test (22)`, `test (24)`, `test (22, windows)`, `mount`, `mount-fixtures` |
 | 0.2.1-rc.2 | v2.6.0 | 2026-11-01 | mount smoke (28/28 default tools, 3 skills, 2 presets with distinct labels, 1 bundle row), `npm test` (729), `npm run test:property` (111), `npm run check` (docs + generated + component + surface + pack 294 + types + architecture + domain), `npm run smoke:mount` |
 | 0.2.1-rc.2 | v2.5.0 | 2026-11-01 | mount smoke (28/28 default tools, 3 skills, 2 presets with distinct labels, 1 bundle row), `npm test` (696), `npm run test:property` (111), `npm run check` (docs + generated + component + surface + pack 293 + types + architecture + domain), `npm run release:check -- --mode tag --tag v2.5.0` |
 | 0.2.1-rc.2 | v2.4.2 | 2026-10-24 | mount smoke (28/28 default tools, 3 skills, 2 presets with distinct labels, 1 bundle row), `npm test` (631), docs + seven generated checks, types coverage 148/148, components + philosophy + surface gates |

package/CONTRIBUTING.md

@@ -126,7 +126,7 @@ the push gates; CI schedules it nightly.
 
 ## Pull request checklist
 
-1. `npm test` passes locally (729 tests today, including protocol end-to-end against a real temporary Git repository and mock spawn coverage), `npm run test:property` passes (111 generated property cases; also part of `npm run check`), and `npm run docs:check` passes.
+1. `npm test` passes locally (786 tests today, 785 run + 1 platform skip, including protocol end-to-end against a real temporary Git repository and mock spawn coverage), `npm run test:property` passes (111 generated property cases; also part of `npm run check`), and `npm run docs:check` passes.
 2. New behavior has a test. Bug fixes should add a test that fails before the fix.
 3. No secrets, tokens, personal paths, session logs, or generated artifacts are added. `.gitignore` covers local acceptance output; do not force-add it.
 4. Keep the public API and state-file formats compatible; if a change is breaking, call it out in `CHANGELOG.md` and bump the version.

package/README.en.md

@@ -16,6 +16,7 @@ The repository root **is** the DSH bundle: `package.json` declares `dsh.bundle.p
 
 - **Configurable Tower mode.** `/tower` toggles a session-level stance that narrows the tool surface and injects the Tower protocol. `/tower on|off <instruction>` also forwards your instruction to the model in the same step. By default the model may also enter/leave with `tower_control` and a concrete reason; set `mode.allowAgentControl:false` for human-only control.
 - **Missions with real isolation.** Every mission gets its own branch and Git worktree; workers never touch your checkout.
+- **Two mission shapes, one registry.** Every mission is a `build` or a `survey`, and the shape owns its statuses, completion evidence, provisioning, path reach and spawn contract instead of scattering `if (kind === …)` branches. Surveys are read-only: they pin a `readCommit` (by default in a detached sandbox) and complete without commits, a branch or a merge. `npm run shape:audit` fails a second vocabulary, a per-kind conditional outside `domain/shapes/`, an evidence read outside `domain/evidence.js`, and a role check combined with a shape check.
 - **Review-gated merges.** The review policy is one tri-state control on the plugin page: `off`, `optional` (the default) or `required` (`review.mode` in config). With `required`, a reviewer bound to the current branch tip must submit a `clean` / `merge` verdict before merge; the merge gate re-checks scope, staleness, task completion, review history, and worktree ownership before a `--no-ff` merge. Independent review is optional by default; use `reviewPolicy:"none"` + reason plus `gates.allowReviewExemption:true` for a single mission when the policy is required. Multi-route review is recorded per round: while a non-clean round keeps the mission `active`, a later reviewer may still submit its verdict for the same reviewed tip and it appends to that round. A completed `survey` dependency satisfies the dependency gate (a build dependency still must be merged). Upgrade note: the old boolean review toggle is a one-release alias; the mapping is in [install, upgrade and migration](docs/guide/install-upgrade-migration.md).
 - **Durable coordination.** Roster, inbox, findings, reviews, and mission state are persisted under `.git/dsh-tower/`, so a restart does not lose the plan.
 - **Bounded state growth.** Terminal missions whose worktree is gone move to `.git/dsh-tower/archive/` once `archive.afterDays`/`archive.maxMissions` says so, keeping their tasks, reviews, findings and completion report; mutations then rewrite only active work. `tower_status includeArchived` lists compact archived summaries, and `tower_doctor` reports archive size, count and policy.
@@ -196,7 +197,7 @@ The list above is the 22 core tools plus 5 of the component-owned optional tools
 - **Worktree ownership.** Dirty worktrees, a running worker, or a branch owned by a closed mission block teardown/merge.
 - **Goal isolation.** Entering Tower mode pauses the active goal and records it; leaving does not resume it. Use `/tower off` and resume the goal yourself.
 
-32 stable blocker/failure codes (including gate guards, `no-check-evidence`, `worker-stale`, test gates, and merge/rebase operation failures) — the complete list with triggers and fixes is in [docs/reference/blockers.md](docs/reference/blockers.md). Tool-level error codes are in [docs/reference/errors.md](docs/reference/errors.md); events are in [docs/reference/events.md](docs/reference/events.md).
+31 stable blocker/failure codes (including gate guards, `no-check-evidence`, `worker-stale`, test gates, and merge/rebase operation failures) — the complete list with triggers and fixes is in [docs/reference/blockers.md](docs/reference/blockers.md). Tool-level error codes are in [docs/reference/errors.md](docs/reference/errors.md); events are in [docs/reference/events.md](docs/reference/events.md).
 
 ## How it works
 

package/README.md

@@ -16,6 +16,11 @@ Tower 模式与 mission/审查工作流的灵感来自 Moonshot AI 的 **Kimi Co
 
 - **可配置的 Tower 模式。** `/tower` 切换会话级模式：收窄工具面并注入 Tower 协议；`/tower on|off <指令>` 还能把指令作为下一步用户消息转发给模型。默认也允许 Agent 通过 `tower_control` 带理由进出；设 `mode.allowAgentControl:false` 可改为仅人类控制。
 - **任务级隔离。** 每个 mission 使用独立分支和 Git worktree，worker 不会碰到你的主检出。
+- **两种 mission 形状，一个注册表。** 每个 mission 是 `build` 或 `survey`，其状态、完成证据、
+  供给方式、路径权限与 spawn 契约都由 shape 拥有，不再散落 `if (kind === …)` 分支。survey 只读：
+  固定一个 `readCommit`（默认在 detached sandbox 中）即可完成，不需要提交、分支或合并。
+  `npm run shape:audit` 会拒绝第二套词汇、`domain/shapes/` 之外的按 kind 条件、
+  `domain/evidence.js` 之外的证据读取，以及角色检查与 shape 检查混合的写法。
 - **审查门禁合并。** 审查策略是插件页上的一个三态控件：`off`、`optional`（默认）或 `required`（配置键 `review.mode`）。设为 `required` 时，审查者针对当前分支 tip 给出 `clean` / `merge` 结论；合并门禁重新校验 scope、分支新鲜度、任务完成度、审查记录与 worktree 归属，通过后才执行 `--no-ff` 合并。独立审查默认可选；策略为 `required` 时，单个 mission 可用 `reviewPolicy:"none"` + 理由并开启 `gates.allowReviewExemption:true` 做更窄豁免。升级提示：旧的布尔审查开关是保留一个版本的别名；映射关系见[安装、升级与迁移](docs/zh/guide/install-upgrade-migration.md)。
 - **可恢复的协作状态。** roster、inbox、findings、reviews 与 mission 状态持久化在 `.git/dsh-tower/` 下，重启不会丢计划。
 - **受控的状态增长。** worktree 已移除的终态任务在达到 `archive.afterDays`/`archive.maxMissions` 后移入 `.git/dsh-tower/archive/`，保留 tasks、reviews、findings 与完成报告；此后 mutation 只重写活跃工作。`tower_status includeArchived` 列出压缩后的归档摘要，`tower_doctor` 报告归档大小、数量与策略。
@@ -195,7 +200,7 @@ reviewer 行，策略为 `required` 时会以带解释的 `preset-missing` 锁
 - **worktree 归属。** 脏工作树、运行中的 worker、已关闭 mission 的分支都会阻止合并或 teardown。
 - **goal 隔离。** 进入 Tower 模式会暂停活跃 goal 并记录；退出不会自动恢复，需要你自行恢复。
 
-32 个稳定 blocker/failure code（含 gate 守卫、`no-check-evidence`、worker-stale、tests 门禁与 merge/rebase 操作失败码）——完整清单、触发条件与修复动作见 [docs/reference/blockers.md](docs/reference/blockers.md)。工具本身抛出的错误码见 [docs/reference/errors.md](docs/reference/errors.md)，事件见 [docs/reference/events.md](docs/reference/events.md)。
+31 个稳定 blocker/failure code（含 gate 守卫、`no-check-evidence`、worker-stale、tests 门禁与 merge/rebase 操作失败码）——完整清单、触发条件与修复动作见 [docs/reference/blockers.md](docs/reference/blockers.md)。工具本身抛出的错误码见 [docs/reference/errors.md](docs/reference/errors.md)，事件见 [docs/reference/events.md](docs/reference/events.md)。
 
 ## 工作原理
 

package/adapters/leases.js

@@ -247,7 +247,7 @@ export async function acquireLease(commonDir, options = {}) {
           'lease-busy',
           `lease "${name}" is held by ${existing.holder} (pid ${existing.pid}) until ${expiresAt}` +
             (expired
-              ? `; the lease expired at ${expiresAt} but is not taken over automatically — its holder must release it explicitly (force: true)`
+              ? `; the lease expired at ${expiresAt} but is not taken over automatically — an explicit tower_resource release with force: true recovers it`
               : ''),
         )
       }
@@ -269,9 +269,12 @@ export async function acquireLease(commonDir, options = {}) {
 }
 
 /**
- * Release a lease. The token must match its holder; an expired lease can only
- * be released with an explicit `force: true`. Returns `true` when removed and
- * `false` when no such lease exists.
+ * Release a lease. A live lease can only be released by the holder that owns
+ * its token. An expired lease is recoverable: the holder may still release it
+ * with the original token, and `force: true` lets the tower take over an
+ * EXPIRED lease whose holder crashed — that is explicit recovery, never silent
+ * takeover, and a live lease always refuses a foreign token. Returns `true` when
+ * removed and `false` when no such lease exists.
  */
 export async function releaseLease(commonDir, options = {}) {
   const name = options?.name
@@ -295,10 +298,21 @@ export async function releaseLease(commonDir, options = {}) {
     const { doc } = await readLeaseDocument(commonDir)
     const existing = doc.leases[name]
     if (!existing) return false
+    const expired = now >= existing.expiresAt
     if (existing.token !== token) {
-      fail('lease-token', `lease "${name}" token does not match its holder; refusing release`)
+      if (expired && force) {
+        // Explicit recovery of a crashed holder: only an expired lease and only
+        // with `force`. Live leases below still refuse a foreign token.
+      } else {
+        fail(
+          'lease-token',
+          expired
+            ? `lease "${name}" is held by ${existing.holder} (pid ${existing.pid}) and expired at ${new Date(existing.expiresAt).toISOString()}; the token does not match — pass force: true to take over the expired lease`
+            : `lease "${name}" is held by ${existing.holder} (pid ${existing.pid}) until ${new Date(existing.expiresAt).toISOString()}; a live lease can only be released by its holder`,
+        )
+      }
     }
-    if (!force && now >= existing.expiresAt) {
+    if (!force && expired) {
       fail(
         'lease-busy',
         `lease "${name}" expired at ${new Date(existing.expiresAt).toISOString()}; release it explicitly with force: true`,

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 } : {}),
   }
 }