dsh-tower 2.0.4 → 2.1.0

package/docs/zh/reference/doctor.md

@@ -11,21 +11,54 @@
     { "id": "git", "status": "pass", "detail": "git version 2.55.0" },
     { "id": "state", "status": "pass", "detail": ".../state.json revision 7" }
   ],
+  "archive": {
+    "missions": 3,
+    "archivedMissions": 12,
+    "stateBytes": 48211,
+    "archiveBytes": 190244,
+    "years": [2026],
+    "files": 2,
+    "unreadable": [],
+    "policy": { "enabled": true, "afterDays": 30, "maxMissions": 100 }
+  },
   "environmentContract": {
     "platform": "win32",
     "gitVersion": "git version 2.55.0",
     "repoRoot": "D:/repo",
     "commonDir": "D:/repo/.git",
-    "stateDir": "D:/repo/.git/dsh-tower"
+    "stateDir": "D:/repo/.git/dsh-tower",
+    "caseInsensitive": true,
+    "comparisonMode": "case-insensitive"
   }
 }
 ```
 
+`archive` 报告终态任务归档：活跃 `missions`、`archivedMissions` 与 `stateBytes`，归档目录的
+`archiveBytes`/`years`/`files`，每条 `unreadable` 诊断，以及配置的 `policy`（`enabled`、`afterDays`、
+`maxMissions`）。归档目录不存在是健康的空归档（`archive` 检查为 `pass`）；截断的 index/year 文件是
+`warn` 并附带诊断，且归档会暂停而不是覆盖它——归档不可读期间没有数据会丢失，符合条件的 mission 仍留在
+`state.json`。
+
 检查覆盖：git 可用性、仓库身份、state schema/加载、仓库配置是否存在、worker/reviewer preset 名称、
 subagents 与 HMR 服务、workspace 锁持有者/是否过期、实时 roster、worktree 是否存在/归属/是否脏、
-test-discovery 策略、旧版快照、batch 与租约。被 `tower_teardown` 正常清理的 mission worktree 会被
+test-discovery 策略、完成报告大小、归档健康度、旧版快照、batch 与租约。被 `tower_teardown` 正常清理的 mission worktree 会被
 跳过（检查中会注明已移除数量），不会被误报为 missing。`warn` 是提示；`fail` 表示仓库在 spawn/merge 前需要
+
+`caseInsensitive` 是 `tower_init` 在检出目录所在文件系统上一次性探测的结果；`null` 表示“尚未探测”，
+此时 `case-mode` 检查为 `warn`。`comparisonMode` 是 scope 匹配实际使用的比较方式：
+`case-insensitive` 会折叠双方大小写，`case-sensitive` 则保持逐字节精确。doctor 从不执行探测（探测会
+创建临时文件，只读调用不能写入）；在没有可用写权限的检出上运行 `tower_init` 会记录该模式，在此之前
+使用安全的 `case-sensitive` 默认值。
+
+检查覆盖：git 可用性、仓库身份、state schema/加载、已探测的大小写模式、仓库配置是否存在、
+worker/reviewer preset 名称、subagents 与 HMR 服务、workspace 锁持有者/是否过期、实时 roster、
+worktree 是否存在/归属/是否脏、test-discovery 策略、旧版快照、batch 与租约。被 `tower_teardown`
+正常清理的 mission worktree 会被跳过（检查中会注明已移除数量），不会被误报为 missing。`warn` 是提示；`fail` 表示仓库在 spawn/merge 前需要
 处理。state 加载失败会作为失败的检查报告而不是抛出，因此 doctor 在损坏的仓库上仍然有用。
 
+`reports` 检查会指出仓库中最大的完成报告（`<bytes> B on <mission>`，对照 `gates.maxReportBytes` 上限），
+同样的数据也以 `reports: { count, largest: { missionId, bytes } | null, capBytes }` 返回。上限生效前写入的
+报告只会产生 `warn`，doctor 绝不会重写它们。
+
 环境契约仅供参考；它不是身份或授权证明。`tower_init` 仍要求控制塔角色，`tower_spawn` 仍会检查
 实时子代理目录。

package/docs/zh/reference/errors.md

@@ -3,7 +3,7 @@
 [English](../../reference/errors.md) | **简体中文**
 
 工具失败是抛出的错误，不是 `{ok:false}` 结果（门禁结果是例外：见 [blockers.md](blockers.md)）。
-每个抛出的错误都以稳定 code 作为消息前缀。本版本定义 31 个工具错误码。
+每个抛出的错误都以稳定 code 作为消息前缀。本版本定义 35 个工具错误码。
 
 ```
 [tower:mission-not-found] unknown mission "M9"
@@ -20,15 +20,19 @@
 | `mission-not-found` | 不存在该 id 的 mission。 | 过期或拼错的 `M9` |
 | `finding-not-found` | 不存在该 id 的 finding。 | `tower_findings({id:"F99"})` |
 | `invalid-transition` | 请求的状态转换不被允许。 | 尝试 blocked→merged；finding 状态图之外的流转；reviewer 修改 finding；在还有未完成任务、blocker、无提交或未读消息时完成 mission。 |
+| `stale-base` | 操作准备期间仓库状态已变化，需要重试。 | two-phase mutation 重校验 |
 | `worktree-dirty` | mission worktree 有未提交改动，不能完成。 | `tower_complete` 前遗留 staged/modified/untracked 文件 |
 | `state-locked` | 另一个 Tower 写入者持有 state 锁。 | 锁超时后的并发写 |
-| `state-corrupt` | Tower state 文件不可读或无效。 | 手工编辑过的 `state.json` |
+| `state-corrupt` | Tower state 文件不可读或无效。 | 手工编辑过的 `state.json`；非法 JSON；没有可用的 `schemaVersion` |
+| `state-version-unsupported` | state 文件的 schema 版本高于本构建支持的版本，或无法迁移。 | 打开由更新插件写入的仓库；未知的旧版本；本构建拒绝降级 |
+| `state-migration-failed` | state 迁移抛出异常；原文件未被修改。 | 迁移步骤中的 bug；查看迁移前的 `state.json.v<N>.bak` |
 | `config-invalid` | Tower 配置无效。 | 格式错误的仓库 `config.json`、违反 schema 的值 |
 | `config-unknown-key` | Tower 配置存在未知顶层键。 | 例如把键拼成 `allowAgentToggle` |
 | `git-failed` | git 命令因未归入其他分类的原因失败。 | 被拒绝的合并命令、非法 ref |
 | `git-timeout` | git 命令超时或输出超出缓冲区。 | 慢 pre-merge 钩子、超大 diff |
 | `spawn-unavailable` | subagents 服务不可用。 | 没有 `subagents` 的 Host |
 | `provider-missing` | 没有注册的 subagent provider。 | provider 列表为空 |
+| `provider-cooldown` | 连续可重试的 provider 失败后，spawn 进入短暂冷却。 | 等待 `blockedUntil` 后重试 |
 | `preset-missing` | 配置的 agent preset 未注册。 | 缺少 `tower-worker`/`tower-reviewer` preset 行、DSH 未重启 |
 | `reviewer-prerequisite` | reviewer spawn 的前置条件未满足。 | mission 尚未 `completed` 或还没有 worktree 就 spawn reviewer |
 | `not-authorized` | 调用方 agent 角色无权执行该操作。 | worker 调用仅限控制塔的工具，或修改 mission 状态/scope；reviewer 修改 finding |

package/docs/zh/reference/tools.md

@@ -32,16 +32,16 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 | 工具 | 参数 | 用途 / 说明 |
 |---|---|---|
 | `tower_init` | `base?`、`autoGitInit?`、`snapshotDirty?`、`reanchor?` | 创建 `<git-common-dir>/dsh-tower/state.json`。`autoGitInit` 执行 `git init` 并创建空的初始提交；`snapshotDirty` 记录一个游离快照提交作为 mission 基线；`reanchor` 仅在没有非终态 mission 时修改基线。返回 `dirty`、`snapshotCommit`、`reanchored`。 |
-| `tower_plan` | `missions[]`（`title`、`scope[]`、`tasks[]?`、`deps[]?`、`kind?`、`context?`、`references[]?` ≤20、`reviewPolicy?`、`reviewExemptionReason?`） | 创建 mission `M1..`；重叠的 build scope 会自动加依赖；拒绝未知依赖与依赖循环。`reviewPolicy:"none"` 需要非空理由；审查门禁开启时，preflight 还要求 `gates.allowReviewExemption`。 |
+| `tower_plan` | `missions[]`（`title`——可打印 Unicode，NFC 规范化，≤120 字符、`scope[]`、`tasks[]?`、`deps[]?`、`kind?`、`context?`、`references[]?` ≤20、`reviewPolicy?`、`reviewExemptionReason?`） | 创建 mission `M1..`；重叠的 build scope 会自动加依赖；拒绝未知依赖与依赖循环。mission id 保持 ASCII（`M1`、`M2`）；不可见字符与超长标题会以 `invalid-argument` 拒绝。`reviewPolicy:"none"` 需要非空理由；审查门禁开启时，preflight 还要求 `gates.allowReviewExemption`。 |
 | `tower_mission` | `id`（别名 `missionId`）、`status?`、`task_done?`、`task_drop?`+`task_drop_reason?`、`blocker?`、`clear_blockers?`、`note?`、`scope?`、`pause_cause?`、`authorization?` | 更新单个 mission。worker 可安全使用的字段是 task/blocker/note；不能在这里设置 `merged`。暂停的 mission 记录 `pause_cause`（user/failure/resource/dependency）；恢复用户暂停的 mission 会遵循 `mode.requireResumeAuthorization`。 |
-| `tower_status` | `missionId?`、`offset?`、`limit?`、`includeGate?`、`format?` | 默认返回面板。`missionId` 返回完整详情（任务/备注/审查/finding/完成报告）。`offset`/`limit` 对 mission 分页（默认 20，最大 100），`includeGate` 附带门禁摘要，`format:"markdown"` 返回看板。 |
+| `tower_status` | `missionId?`、`offset?`、`limit?`、`includeGate?`、`format?` | 默认返回面板。分页 mission 只带 `reportBytes`；`missionId` 返回完整详情（任务/备注/审查/finding/完成报告正文）。`offset`/`limit` 对 mission 分页（默认 20，最大 100），`includeGate` 附带门禁摘要，`format:"markdown"` 返回看板。host 提供 mode hook 时还会包含 `mode.lastChange` 与最近 `history`。 |
 | `tower_spawn` | `missionId`（别名 `id`）、`role`（`worker`/`reviewer`）、`name?`、`instructions?`、`worktreeRoot?`、`wait?`、`waitMs?`、`takeover?`、`includeDirtyBase?` | 准备或复用 worktree 并启动子代理。worker 使用 `tower-worker`；reviewer 要求 mission 为 `completed`，并使用只读的 `tower-reviewer`。`takeover:true` 替换已不再运行的 worker 条目（ownerGeneration 递增）。每个 mission 只能有一个活跃 worker；`spawn.maxLiveWorkers` 限制整个仓库。 |
 | `tower_roster` | — | roster 及来自子代理目录的实时活动（`running`/`inactive`/`missing`/`unknown`）与 `stale` 标记。只读。 |
 | `tower_adopt` | `retireMissing?` | 把 roster 条目与持久子代理目录对账。可证明已消失的 agent 会被标记为 retired（默认），或标记为 `missing`（`retireMissing:false`）以便检查/接管。 |
 | `tower_diff` | `missionId`（别名 `id`）、`maxBytes?` | 只读 merge-base diff：文件、提交、有上限的 patch。供 reviewer 安全使用。 |
 | `tower_send` | `to`、`subject`、`body`、`scope?`、`interrupt?`、`consentRef?` | 向 roster 名称、`tower` 或 `all` 发送持久消息；对运行中的 agent 会即时投递。`interrupt:true` 先中断运行中的回合（Kimi 风格）再投递；`consentRef` 记录用于审计。受 `send.maxPerMinute` 限速。 |
 | `tower_inbox` | `limit?`、`include_read?` | 读取并确认发给调用者的消息；未读消息会阻止 `tower_complete`。 |
-| `tower_complete` | `missionId`（别名 `id`）、`report`、`checks?` | worker 报告完成（mission 变为 `completed`，可进入 preflight 与可选审查）。要求当前 owner、无未完成任务/blocker、≥1 个提交、无未读消息。`checks` 记录 `{name, command?, exitCode?, evidence?}` 证据；`gates.requireChecks` 可以强制要求。配置了测试发现时还会自动运行并添加 `tests` 检查；失败会抛出 `[tower:tests-failed]`。 |
+| `tower_complete` | `missionId`（别名 `id`）、`report`、`checks?` | worker 报告完成（mission 变为 `completed`，可进入 preflight 与可选审查）。要求当前 owner、无未完成任务/blocker、≥1 个提交、无未读消息。`report` 受 `gates.maxReportBytes`（默认 32768 UTF-8 字节）硬上限约束：超限会以 `invalid-argument` 拒绝并给出 `nextAction`（把全文写进 mission worktree 的文件），绝不截断；存储时会记录 `reportBytes`。`checks` 记录 `{name, command?, exitCode?, evidence?}` 证据；`gates.requireChecks` 可以强制要求。配置了测试发现时还会自动运行并添加 `tests` 检查；失败会抛出 `[tower:tests-failed]`。 |
 | `tower_interrupt` | `to?`（roster 名称）、`agentId?`、`reason?` | 通过 `subagents.interrupt` 中断一个运行中的 roster agent，并记录 `state:"interrupted"`。幂等（未运行 → `interrupted:false`）。 |
 | `tower_finding` | `type`、`title`、`summary`、`details`、`suggested_fix`、`severity?`、`missionId?`、`location?` | 记录 scope 之外的问题；reviewer 用它代替直接改文件。新 finding 初始为 `open`。 |
 | `tower_findings` | `id?`、`status?`、`note?`、过滤（`type?`、`severity?`、`missionId?`、`open?`、`limit?`） | 生命周期工具：列出/读取/流转。状态为 `open → triaged → fixed`/`wontfix`，允许重新打开。只有控制塔或 worker 能修改；reviewer 只能列出/读取。 |

package/domain/collab/batch.js

@@ -0,0 +1,112 @@
+// 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.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { summarize } from '../batch.js'
+
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'batch-invalid') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * Next free `B<n>` id.
+ * @param {any[]} batches
+ * @returns {string}
+ */
+export function nextBatchId(batches) {
+  const max = batches.reduce((value, batch) => {
+    const match = /^B(\d+)$/.exec(String(batch.id ?? ''))
+    return match ? Math.max(value, Number(match[1])) : value
+  }, 0)
+  return `B${max + 1}`
+}
+
+/**
+ * Project the persisted batch record from normalized create input.
+ * @param {string} id
+ * @param {any} normalized
+ * @param {string} actor
+ * @param {number} now
+ * @returns {any}
+ */
+export function createBatchRecord(id, normalized, actor, now) {
+  return {
+    id,
+    status: 'open',
+    ...normalized,
+    createdBy: actor,
+    createdAt: now,
+  }
+}
+
+/**
+ * Mark a validated open batch closed with its evidence snapshot.
+ * @param {any} batch
+ * @param {{ checks?: unknown, treeTip?: unknown, receiptHashes?: unknown }} options
+ * @param {string} actor
+ * @param {number} now
+ * @returns {any}
+ */
+export function closeBatchRecord(batch, options, actor, now) {
+  batch.status = 'closed'
+  batch.closedAt = now
+  batch.closedBy = actor
+  batch.close = {
+    checks: options.checks ?? [],
+    treeTip: options.treeTip ?? null,
+    receiptHashes: options.receiptHashes ?? {},
+    at: now,
+  }
+  return batch
+}
+
+/**
+ * A closed batch cannot be abandoned; an already-abandoned one is a no-op.
+ * @param {any} batch
+ * @param {string} batchId
+ * @returns {{ alreadyAbandoned: boolean }}
+ */
+export function abandonBatchCheck(batch, batchId) {
+  if (batch.status === 'closed') fail(`batch ${batchId} is already closed`)
+  return { alreadyAbandoned: batch.status === 'abandoned' }
+}
+
+/**
+ * Apply an abandonment to the draft batch.
+ * @param {{ batch: any, actor: string, reason?: unknown, now: number }} params
+ * @returns {any}
+ */
+export function applyBatchAbandon({ batch, actor, reason, now }) {
+  batch.status = 'abandoned'
+  batch.abandonedAt = now
+  batch.abandonedBy = actor
+  batch.abandonReason = typeof reason === 'string' && reason.trim() ? reason.trim() : null
+  return batch
+}
+
+/**
+ * Read-only `tower_batch status` payload.
+ * @param {TowerState} state
+ * @param {string | undefined} batchId
+ * @returns {any}
+ */
+export function batchStatusPayload(state, batchId) {
+  const batches = state.batches ?? []
+  const batch = batchId ? batches.find((entry) => entry.id === batchId) : null
+  if (batchId && !batch) fail(`unknown batch "${batchId}"`)
+  return {
+    batches: batches.map((entry) => summarize(state, entry)),
+    ...(batch ? { batch: summarize(state, batch) } : {}),
+  }
+}

package/domain/collab/messages.js

@@ -0,0 +1,127 @@
+// Pure message routing, read tracking, and inbox projections.
+//
+// app/messages.js owns the state lock, load, persistence, and activity log;
+// app/roster.js's unreadFor delegates to `unreadMessages` here.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('invalid-argument', message)
+}
+
+/**
+ * Validate the recipient against the roster plus the synthetic `tower` name.
+ * @param {{ roster?: RosterEntry[], to: string, from: string }} params
+ * @returns {void}
+ */
+export function assertMessageRecipient({ roster = [], to, from }) {
+  const names = new Set(roster.map((entry) => entry.name))
+  names.add('tower')
+  if (to !== 'all' && !names.has(to)) {
+    fail(`unknown message recipient "${to}" (known: ${[...names].join(', ')}, all)`)
+  }
+  if (to === from) fail('refusing to send a message to yourself')
+}
+
+/**
+ * Project the persisted message record.
+ * @param {any} input
+ * @param {number} seq
+ * @param {number} now
+ * @returns {any}
+ */
+export function createMessage(input, seq, now) {
+  return {
+    id: `msg-${seq}`,
+    seq,
+    from: input.from,
+    to: input.to,
+    subject: input.subject,
+    body: input.body,
+    scope: input.scope ?? null,
+    consentRef: input.consentRef ?? null,
+    at: now,
+    readBy: [],
+    delivery: [],
+  }
+}
+
+/**
+ * Append delivery results to a message, preserving earlier entries.
+ * @param {{ delivery?: unknown[] }} message
+ * @param {unknown[]} results
+ * @returns {unknown[]}
+ */
+export function addDelivery(message, results) {
+  message.delivery = [...(message.delivery ?? []), ...results]
+  return message.delivery
+}
+
+/**
+ * Inbox page plus read-marking mutation. Returns `changed` so the use case can
+ * decide whether the state file needs a write.
+ * @param {any[]} messages
+ * @param {{ reader: string, limit?: number, includeRead?: boolean }} input
+ * @param {number} now
+ * @returns {{ payload: any, changed: boolean }}
+ */
+export function inboxView(messages, input, now) {
+  const reader = input.reader
+  const limit = Math.max(1, Math.min(100, input.limit ?? 20))
+  const includeRead = input.includeRead === true
+  const visible = [...messages]
+    .reverse()
+    .filter((message) => (message.to === reader || message.to === 'all') && message.from !== reader)
+  const unread = visible.filter((message) => !(message.readBy ?? []).includes(reader))
+  const page = (includeRead ? visible : unread).slice(0, limit)
+
+  let changed = false
+  for (const message of page) {
+    if (!(message.readBy ?? []).includes(reader)) {
+      message.readBy = [...(message.readBy ?? []), reader]
+      message.readAt = { ...(message.readAt ?? {}), [reader]: now }
+      changed = true
+    }
+  }
+  const unreadRemaining = visible.filter((message) => !(message.readBy ?? []).includes(reader)).length
+  return {
+    payload: {
+      reader,
+      messages: page.map((message) => ({
+        id: message.id,
+        from: message.from,
+        to: message.to,
+        subject: message.subject,
+        body: message.body,
+        scope: message.scope ?? null,
+        at: message.at,
+        delivery: message.delivery ?? [],
+        ackAt: message.readAt?.[reader] ?? null,
+      })),
+      pageSize: page.length,
+      unreadRemaining,
+    },
+    changed,
+  }
+}
+
+/**
+ * Unread inbox rows for one recipient (messages from self never count).
+ * @param {TowerState} state
+ * @param {string} name
+ * @returns {any[]}
+ */
+export function unreadMessages(state, name) {
+  return (state.messages ?? []).filter((message) => {
+    if (message.from === name) return false
+    if (message.to !== name && message.to !== 'all') return false
+    return !(/** @type {any[]} */ (message.readBy ?? [])).includes(name)
+  })
+}

package/domain/collab/roster.js

@@ -0,0 +1,158 @@
+// Pure roster observation and stale/inactive policy.
+//
+// app/roster.js owns the state lock, load, persistence, and activity log; the
+// transitions below mutate only the in-memory roster rows they are given.
+// @ts-check
+import { ROSTER_INACTIVE } from '../roster.js'
+
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+
+/**
+ * @param {RosterEntry} entry
+ * @returns {void}
+ */
+export function clearStale(entry) {
+  delete entry.stale
+  delete entry.staleAt
+}
+
+/**
+ * Count repeated absence observations and list rows ready to adopt.
+ * @param {RosterEntry[]} roster
+ * @param {{ present?: unknown[], absent?: unknown[], confirmations?: unknown }} observations
+ * @param {number} now
+ * @returns {{ candidates: string[], changed: boolean }}
+ */
+export function recordRosterObservations(roster, { present = [], absent = [], confirmations = 2 }, now) {
+  const presentIds = new Set(present)
+  const absentIds = new Set(absent)
+  /** @type {string[]} */
+  const candidates = []
+  let changed = false
+  for (const entry of roster) {
+    if (presentIds.has(entry.agentId)) {
+      if (entry.absentObservations !== undefined) {
+        delete entry.absentObservations
+        delete entry.absentSince
+        changed = true
+      }
+      continue
+    }
+    if (!absentIds.has(entry.agentId)) continue
+    entry.absentObservations = (/** @type {number} */ (entry.absentObservations ?? 0)) + 1
+    entry.absentSince ??= now
+    changed = true
+    const observations = /** @type {number} */ (entry.absentObservations)
+    if (observations >= Math.max(2, Number(confirmations) || 2)) {
+      candidates.push(/** @type {string} */ (entry.agentId))
+    }
+  }
+  return { candidates, changed }
+}
+
+/**
+ * Release live slots whose catalog activity is explicitly inactive.
+ * @param {RosterEntry[]} roster
+ * @param {Record<string, string>} activity
+ * @param {number} now
+ * @returns {{ released: string[] }}
+ */
+export function reconcileObservedInactive(roster, activity = {}, now) {
+  /** @type {string[]} */
+  const released = []
+  for (const entry of roster) {
+    if (entry.state === 'reserved' || ROSTER_INACTIVE.has(entry.state)) continue
+    const agentId = /** @type {string} */ (entry.agentId)
+    if (activity[agentId] !== 'inactive') continue
+    entry.state = 'inactive'
+    entry.outcome = 'catalog reported inactive'
+    entry.outcomeAt = now
+    clearStale(entry)
+    released.push(entry.name)
+  }
+  return { released }
+}
+
+/**
+ * Retire entries by agent id, skipping rows already retired.
+ * @param {RosterEntry[]} roster
+ * @param {unknown[]} agentIds
+ * @param {number} now
+ * @returns {{ retired: string[] }}
+ */
+export function retireEntries(roster, agentIds, now) {
+  if (!Array.isArray(agentIds) || agentIds.length === 0) return { retired: [] }
+  /** @type {string[]} */
+  const retired = []
+  for (const entry of roster) {
+    if (entry.state !== 'retired' && agentIds.includes(entry.agentId)) {
+      entry.state = 'retired'
+      entry.retiredAt = now
+      clearStale(entry)
+      retired.push(/** @type {string} */ (entry.agentId))
+    }
+  }
+  return { retired }
+}
+
+/**
+ * Mark entries missing unless they are already inactive.
+ * @param {RosterEntry[]} roster
+ * @param {unknown[]} agentIds
+ * @param {number} now
+ * @returns {{ missing: string[] }}
+ */
+export function markMissingEntries(roster, agentIds, now) {
+  if (!Array.isArray(agentIds) || agentIds.length === 0) return { missing: [] }
+  /** @type {string[]} */
+  const missing = []
+  for (const entry of roster) {
+    if (!ROSTER_INACTIVE.has(entry.state) && agentIds.includes(entry.agentId)) {
+      entry.state = 'missing'
+      entry.missingSince = now
+      clearStale(entry)
+      missing.push(/** @type {string} */ (entry.agentId))
+    }
+  }
+  return { missing }
+}
+
+/**
+ * Watchdog sweep: catalog-inactive rows become inactive; rows absent from an
+ * authoritative catalog and older than `staleMs` become stale. Unknown catalog
+ * state is never treated as stopped.
+ * @param {RosterEntry[]} roster
+ * @param {{ activity?: Record<string, string>, staleMs?: unknown, authoritative?: unknown }} input
+ * @param {number} now
+ * @returns {{ marked: string[], idled: string[] }}
+ */
+export function sweepRosterState(roster, input = {}, now) {
+  const staleMs = Number(input.staleMs) || 0
+  if (staleMs <= 0 || input.authoritative !== true) return { marked: [], idled: [] }
+  const activity = input.activity ?? {}
+  /** @type {string[]} */
+  const marked = []
+  /** @type {string[]} */
+  const idled = []
+  for (const entry of roster) {
+    if (ROSTER_INACTIVE.has(entry.state)) continue
+    const observed = activity[/** @type {string} */ (entry.agentId)]
+    if (observed === 'inactive') {
+      entry.state = 'inactive'
+      entry.outcome = entry.outcome ?? 'idle (catalog)'
+      entry.outcomeAt = now
+      idled.push(entry.name)
+      continue
+    }
+    if (observed === 'running') continue
+    if (observed !== undefined) continue
+    const age = now - Number(entry.spawnedAt ?? now)
+    if (age > staleMs) {
+      entry.state = 'stale'
+      entry.stale = true
+      entry.staleAt = now
+      marked.push(entry.name)
+    }
+  }
+  return { marked, idled }
+}