secondmate-provisioning

secondmate-provisioning

在创建、播种、验证、启动、移交待办事项、恢复、将继承的本地材料推送到持久化 secondmate，或退役持久化 secondmate 之前，以及编辑 data/secondmates.md 之前，请先参阅本文档。

始终以内联方式提供的路由规则以 AGENTS.md 为准：按自然语言 scope: 路由，本地专属项目由主 firstmate 负责，secondmate 默认处于空闲状态。

路由表

data/secondmates.md 中，每个持久化 secondmate 占一行，并与解析器兼容。 本地路由使用：

- <id> - <one-sentence charter summary> (home: <absolute-home-path>; scope: <natural-language responsibility>; projects: <project-a>, <project-b>; added <date>)

整个主目录的远程路由使用：

- <id> - <one-sentence charter summary> (host: <ssh-alias>; root: <absolute-remote-code-root>; home: <absolute-remote-home>; scope: <natural-language responsibility>; projects: <project-a>, <project-b>; added <date>)

每个注册表条目都应简洁且仅占一行：摘要用一个句子说明长期职责，scope: 是自然语言描述的受理职责，projects: 是非排他性的克隆列表；任何额外文字都仅限于确实会改变该 secondmate 路由或安全规则的领域专属硬性规定。 自然语言摘要和 scope: 文本可以包含括号和分号；请保留生成的 (home: ...; scope: ...; projects: ...; added ...) 后缀原样不动，以便运维工具解析其中明确标记的字段。 home: 路径指向包含 data/charter.md 的已播种主目录；无需添加额外的注册表指针字段。 对于远程路由，host: 是 OpenSSH 配置别名，root: 是该主机上单独跟踪的 Firstmate 代码根目录。 远程 secondmate Agent 始终运行在 Herdr 后端；每次播种、启动和存活检查重启之前，都会先通过 bin/fm-remote-doctor.sh 检查主机是否就绪。因此，主机未就绪时会拒绝操作，并显示该检查程序提供的具体缺项信息，而不会半途创建路由；由该 secondmate 监管的 worker 仍使用主目录的常规后端选择。 此版本将整个 secondmate 主目录放在远程端，不会将单个 worker 放在远程端。 docs/remote-secondmates.md 负责说明当前的运维设置和传输行为。 已在主目录中播种的 data/charter.md 是默认空闲行为、常规委派生命周期和标准升级处理约定的唯一权威来源，因此应在注册表条目中指向该章程，而不要重述这些约定。 scope: 字段用于受理时的路由。 projects: 字段是非排他性的克隆列表，不代表所有权。

章程与播种

使用以下命令搭建 secondmate 章程：

bin/fm-brief.sh <id> --secondmate {<project>...|--no-projects}

搭建命令会生成章程简介，而不是任务简介。 设置 FM_SECONDMATE_CHARTER='<charter>' 可填入章程文本；如果路由范围不同，还可设置 FM_SECONDMATE_SCOPE='<scope>'。 如果搭建时未设置 FM_SECONDMATE_CHARTER，请在播种前替换 {TASK} 占位符。 对于主题是 firstmate 仓库本身、主目录是 firstmate 工作树且团队使用同一仓库的共享工作树的领域，请传入 --no-projects 而不是项目列表，以搭建不关联项目的章程。 --no-projects 不能与项目列表同时使用；如果两者都省略，命令仍会明确报错，因此不会将意外遗漏误认为是有意创建不关联项目的播种。 如果已填充的主目录中包含项目克隆或 data/projects.md 条目，则会以非破坏性方式拒绝将其重新播种为不关联项目。 请先退役或清理该主目录，然后使用 --no-projects 重新搭建过时的、包含项目的章程，再进行播种。 自定义章程文本应聚焦于长期职责、可用项目克隆，以及确实属于领域专属的硬性规定。 搭建生成的章程之后会复制到 data/charter.md，并由其负责标准生命周期和升级处理措辞。 除非领域确实需要硬性规定，否则请保留生成的章程章节。

填妥章程后，配置本地持久化主目录和注册表条目：

bin/fm-home-seed.sh <id> <home|-> {<project>...|--no-projects}

使用以下命令，通过已配置的 SSH 主机配置整个远程主目录：

bin/fm-remote-home-seed.sh <id> <ssh-alias> <remote-root> <remote-home> {<project>[=<origin-url>]...|--no-projects}

你需要自行解析每个项目的来源——可以从 captain、项目注册表、其他位置已有的克隆、gh-axi 或明确粘贴的来源中获取，并将其命名为 <project>=<origin-url>；seed 会验证并传输你提供的内容。 因此，远程 seed 除了路由、章程概要以及启动后生成的启动记录外，不会在此主目录中创建任何内容：绝不要将项目克隆到 projects/，不要在此处初始化 no-mistakes，也不要只为 seed 一个远程 secondmate 就运行 fleet sync。 单独的 <project> 是一种便捷写法，仅适用于此主目录中已克隆的项目，此时会读取其已配置的来源。 其余操作约定见 docs/remote-secondmates.md，接受的来源格式见 bin/fm-project-origin-lib.sh。 在项目参数位置传入 --no-projects，即可 seed 上述不含项目的主目录；同样适用互斥规则和缺少参数时明确报错的规则。 此操作只能用于没有项目克隆或项目注册表条目的主目录；若主目录中已有项目，则会拒绝转换且不会对其进行更改。 - 会在 secondmate ID 下通过 treehouse get --lease 持久租用一个全新的 firstmate 工作树。 即使没有运行中的进程，该租用也会持续存在，后续的 treehouse get 或 prune 绝不会将其回收。 该槽位会一直保留，直到租用被释放，即使期间发生重启也不例外。 只有显式退役或 seed 回滚时才会释放租用，常规重启或恢复不会释放。

bin/fm-home-seed.sh 会将章程复制到 secondmate 主目录中的 data/charter.md。 它还会在必需的 .fm-secondmate-home 身份标记之前写入受 git 忽略的 .fm-secondmate-parent 持久绑定；记录格式约定见 bin/fm-secondmate-parent-lib.sh 中的解析器头部，且这两个文件都必须保留。 主目录中 secondmate 的运行时固定版本、各 mate 的覆盖设置、启动优先级、兼容性以及格式错误文件的拒绝处理，见 docs/configuration.md。 解析固定版本时，请选择已注册 mate 的 ID；解析器命令见 bin/fm-harness.sh 的头部。 本节是 secondmate 同步和继承的本地资料传播约定的唯一权威来源；AGENTS.md 第 3 和第 4 节指向这里。 在本地启动前，如果安全，fm-spawn.sh --secondmate 会在本地将 home 快进到主 firstmate 检出当前默认分支的提交；或者使用 reset --keep 协调干净的分叉，前提是其完整本地结果已存在于主 firstmate 中（例如 squash merge 之后）。有未提交更改、独有分叉或正在进行的操作时，home 保持不变并发出警告；真正的分叉会获得与 bin/fm-ff-lib.sh 为 /updatefirstmate 写入的相同持久协调记录。 加锁的会话启动延后网络阶段会对每个仍在运行的本地 secondmate home 执行相同的引导扫描；这些 home 从 state/<id>.meta 记录中发现，条件是 kind=secondmate（data/secondmates.md 仅为较旧记录回填 home=）。 这条不获取路径只会对已跟踪文件执行纯本地快进或冗余分叉协调，绝不从 origin 获取内容，也绝不触碰被 git 忽略的运行目录，因此不会干扰 secondmate 的待办、项目和进行中的工作；关联工作树会立即前进，而缺少目标提交的独立克隆则通过 /updatefirstmate 的 origin 刷新接收 firstmate 更新。 远程启动和延后的引导扫描会将主仓库自身的默认分支提交交给配置的主机，并要求该主机在与本地 home 相同的干净状态、祖先关系和分支保护条件下，将持久 home 快进或协调冗余分叉，使其恰好指向该提交。 远程 home 是另一台机器上的独立克隆，因此该主机会导入收到的那个提交：如果本地已有则直接使用，否则从该主机自己的 Firstmate 副本导入但不移动该副本，再不然从 home 的 origin 导入；如果这些位置都没有该提交，就会跳过并说明可采取的操作，这正是未推送的主仓库提交在那台机器上的表现。 这两条路径都不会移动主机上的 Firstmate 副本，而且在父进程已经同步 home 后，主机上的本地启动绝不会重新定位该副本。 /updatefirstmate 是唯一仍会跟随该副本的路径：它先从自身 origin 更新远程代码根目录，再将 home 同步到刷新后的代码根目录提交。 SSH 退出码 255 会保留路由并报告完成状态未知；绝不会触发本地重新启动或故障转移。 相同的、按放置位置区分的启动和延后引导扫描还会传播主仓库声明的继承本地资料，具体由 fm_config_inherit_items 声明，其所有者也定义哪些项目属于会话级。 由于这些路径被 git 忽略，该传播是独立于已跟踪文件快进的、由主仓库控制的复制操作：无论已跟踪文件是否前进，它都会重新收敛每个仍在运行的 home，且只触碰已声明的项目。 传播失败会发出警告，但不会阻止本地 secondmate 启动或会话启动继续；远程启动前传输失败则会拒绝启动。 目标端会保留助手留下的、经过安全验证的状态。 对于继承的配置文件，本地传播和远程发送方在源检查出错时会保留目标项目，并且只有确认源文件不存在时才会镜像删除；此边界由 fm-config-inherit-lib.sh 负责。 继承会复制字面意义上的 config/crew-harness 文件，因此，只有当它指定了 codex 这样的具体适配器时，secondmate 自己的 crewmate 才会使用主仓库的 crewmate harness；未设置或设为 default 时，没有具体值可供继承，secondmate 自己的 crewmate 会改用 secondmate 自己的 harness 或检测到的 harness。 继承的 config/backend 仅会成为该 secondmate home 的本地运行时后端默认值，适用于后续启动；它绝不会重新定位、改写、迁移、停止或重启已经运行的 worker 端点。 只要主仓库存在 config/backend 值，该值就会按字节精确地收敛到经过验证的 secondmate home；主仓库没有此文件时，则会移除这些 home 中的该后端设置，使其继续自动检测运行时后端。 显式的每次启动参数 --backend 和 FM_BACKEND 始终优先于任何 home 本地的 config/backend，包括继承的默认值。 已声明的 config/supervision-host-off 退出选项也采用同样的主仓库权威传播方式：只要该文件存在，secondmate home 就会退出监督，即使它们有自己的引擎设置；收敛时若主仓库中不存在该文件，则会移除 secondmate home 中的副本。 config/supervision-host 本身不继承；每个 home 自行选择其引擎。 config/secondmate-harness 不继承，因为它只是主仓库用于启动 secondmate Agent 的设置项。 config/firstmate-role 会依据额外的解析后角色和收据策略继承，而不是原样复制主仓库文件。 账户固定配置不继承。 Worker account pin负责 config/claude-account 和 config/pi-account 的继承及后端限制；T3 provider instances负责 T3 账户选择。 docs/configuration.md "Per-secondmate account pins"负责显式的 config/secondmate-accounts/<id>/ 覆盖项，以及每个 mate 的 home 内独立的 worker 固定配置。 在主 home 中，data/captain-shared.md 以主仓库为权威来源；在 secondmate home 中，该文件只读。 其主文件头必须说明：该文件以主仓库为权威来源，在 secondmate home 中只读，不得在此编辑，并且新发现的 captain 偏好应通过带标记的状态信息或文档指针转交给主 firstmate。 每个传播点都会让 secondmate 副本收敛到主仓库的字节内容；当主仓库中不存在该文件时，任何现存的 secondmate 副本都会被隔离并删除，使文件缺失状态也能收敛。 本地助手和远程接收方都会将目标文件与上次在此发布的版本进行比较，因此，未经改动的继承副本会被静默替换，而不会报告为漂移。 如果目标文件既不匹配主仓库字节内容，也不匹配记录的版本，则会在替换前将其隔离到名称可避免冲突的私有日期后缀文件中；本地路径还会发出 SECONDMATE_SYNC: 诊断信息，指出 home 和隔离文件，以便为真实的本地编辑和中断的发布保留恢复副本。 助手会拒绝不安全目录、符号链接或非普通源文件及目标文件，以及硬链接目标文件。 在传播运行之间，secondmate 副本在文件系统中为只读；助手可能仅在受保护的更新期间让其管理的目标文件可写，并会在成功、字节内容未变化以及可恢复的失败路径中恢复只读模式。 绝不要将任何 secondmate 的 data/captain-shared.md 复制回主仓库。 每个 home 的 data/captain.md 都应保持领域本地化。 首次向现有 home 传播后，手动精简该 home 的本地 data/captain.md，仅保留领域专属内容和指向 data/captain-shared.md 的指针；不要自动执行此操作，也不要静默删除私有内容。 根据 captain 的决定，让每个 data/learnings.md 都完全保持本地；将适用于整个集群的机制事实通过常规的 firstmate 仓库路径写入已跟踪文档，而不是另行创建共享学习内容传播机制。 启动或重新启动时无需提示重新读取 AGENTS.md，因为 Agent 每次启动时都会重新读取指令；只有引导扫描推进运行中 home 的指令界面时，才需要重新读取 AGENTS.md。 引导扫描会将成功发送的 AGENTS.md 重读指令报告为 BOOTSTRAP_INFO:，且仅当发送失败、需要重试时才发出 NUDGE_SECONDMATES:。 只要继承的 config/* 资料发生变化，运行中的 secondmate 就必须另外重新读取配置的字面内容。 对于本地 home，每次成功写入允许列表中的配置文件后，加锁的引导收敛路径和会话中运行的 bin/fm-config-push.sh 都会使用共享传播报告，为每个 home 生成一份私有指令文件。该文件按代次区分，内容取自经过验证的目标文件写入后字节，只包含已声明且对该 home 确实发生变化的配置项，并遵循声明顺序。 每个发生变化的路径都会打印清晰的开始和结束分隔符，并原样输出目标文件完整、未经解析的新字节；如果传播移除了目标副本，则打印明确标记 ABSENT。 指令只使用最简说明，指出这些是默认值或规则，不会取代判断；绝不包含 SHA 值、所选配置档、解析后的摘要或任何其他生成的解读。 data/captain-shared.md 不是配置文件，绝不会内联到此指令文件或消息中。 如果某个 home 所有允许列表中的配置文件都未变化，且没有待重试事项，则不会向其发送配置重读消息。 不同 home 根据推送前的目标文件字节内容，可能会获得不同的变更文件集合。 交付会使用现有的路由 secondmate 路径（fm-send），且只发送单行指针 CONFIG_REREAD: <absolute generation-specific instruction path>；如果指令发布失败，只要可行，就会将生成的精确字节保留在有界的私有重试队列中；旧版重试报告仍可恢复；发布或重试标记写入失败时，会保留该代次，直至能够交付；发送失败时，会在可行的情况下记录该代次的持久重试标记；所有失败都会显示具体的 CONFIG_REREAD: 诊断信息，但不会声称运行中的 Agent 已重新读取这些值。 传播、代次发布和指针交付的整个过程都会持有单个 home 的继承锁，因此，并发的会话中推送不会在更新的代次之后交付较旧代次。 新启动或重新启动的 secondmate 已在启动时读取其文件，因此，待处理的配置重读代次会在清理后丢弃或隔离；除非传播在启动后更改了文件，否则无需向运行中的 Agent 发送多余的配置提示。 重新启动前被隔离的代次会保留在有界私有历史记录中；清理时不会创建空的隔离代次。 成功交付的代次只会在每个 home 的有界状态历史中保留；待处理代次会一直保留，直至成功交付或被后续启动取代。 远程 home 会通过 fm-remote-inherit.sh 接收相同的允许列表字节；如果传输或已跟踪指令界面的变更要求重读，或者先前的重读仍未完成，则在成功收敛后会收到一条带标记的重读指令。 未变化的传输，或 AGENTS.md、bin/ 和 .agents/skills/ 之外的已跟踪内容更新，都不会产生新的重读义务。 父进程会在交付前记录该提示；如果发送失败、部分应用、完成状态未知，或尝试在报告前被终止，则会保留该提示，并在加锁的引导收敛期间重试完全相同的路由。 fm-secondmate-nudge-lib.sh负责持久义务记录和兼容性行为。 不会向远程 home 发送指向主仓库本地代次路径的指针，因为该路径在远程主机上不存在。 继承的 harness 和运行时后端默认值不得使 fm-spawn 收紧限制，从而拒绝与这些默认值不同的有意运行时选择。 worker 启动环境约定另行规定显式环境变量授权。 对于已经运行的 secondmate，如需在会话中推送继承的本地资料变更，而不运行已跟踪文件快进，请使用 bin/fm-config-push.sh。 它使用与引导扫描相同的运行中 home 发现机制和传播助手，将每个项目报告为 pushed、unchanged、skipped 或 error，并遵循上述配置重读约定处理发生变化或仍待处理的代次。 bin/fm-home-seed.sh会拒绝复制缺失或仅为占位符的章程。 在没有既有简报的情况下直接播种需要 FM_SECONDMATE_CHARTER。 在检查注册表完整性时运行 bin/fm-home-seed.sh validate；其文件头包含完整的验证与拒绝机制。

播种是事务性的。 如果验证、克隆、no-mistakes 初始化或注册表更新失败，生成的简报、新 home、新项目克隆以及注册表编辑都会被回滚。

Secondmate 项目列表只能包含 no-mistakes 和 direct-PR 项目。 local-only 项目保留在主 firstmate 处。 对于 no-mistakes 项目，播种只会初始化新克隆到 secondmate home 中的项目，并拒绝修改尚未初始化的既有克隆。

为既有或继承的领域做记录接收

在播种前先对该领域分类，因为此步骤仅适用于两种情况中的一种。 全新领域尚无已交付的领域工作：其项目中没有任何已交付内容，没有线上部署，也没有可导入的前任记录。 正常播种全新领域即可；没有什么需要核对，本节不会给它增加任何工作。 既有或继承的领域是指其产品已处于开发中的任何领域，以及新 mate 接手的任何前任领域，包括退休后的整合。 这两种情况都要求在新 mate 对任何继承的计划采取行动之前先做记录接收。

对于既有或继承的领域，创建 Agent 必须：

1. 将每一份继承的计划与该领域权威的已交付状态进行核对，后者是每个相关项目的 origin/main 加上线上部署。 已获取的相关项目克隆是该核对的前提条件，因此要在核对之前就把 home 与其项目接好，而不是等到第一个任务时才接。 导入的待办事项、前任自己的笔记、指令界面中的文字描述，以及缺失或未获取的本地视图，都不可作为已交付状态的证据。
2. 只用真正未完成的工作加上该领域持久的知识来播种新 home，即仍然有效的经验、决策和交付姿态。
3. 绝不盲目继承计划待办事项。 工作已交付的计划行会被丢弃，或连同确定其状态的已合并证据一并记为已完成，绝不作为未完成项向前结转。

实时待办事项在设计中只保留配置的近期 Done 条目，因此继承的队列在结构上会过度呈现计划而低估交付。 把继承队列中带有计划却没有对应交付记录的条目视为未核对，而不是未完成的工作，并将所有无法核对的内容作为明确的残余不确定性清单记录在新 home 中，而不是让这一缺口无声无息地存在。

Backlog 交接

创建或交接前，先遵循 AGENTS.md 第 10 节中仅处理工作项的 backlog 约定。 为某个领域创建 secondmate 后，现有主 backlog 中属于其范围的项目应转为由它处理，而不是继续留在主 backlog 中。 范围匹配由 firstmate 根据 secondmate 的自然语言范围进行判断，而不是按关键词规则判断。 读取 data/backlog.md，挑选符合新范围的排队项目，并使用以下命令将其移出：

bin/fm-backlog-handoff.sh <secondmate-id> <item-key>...

完成初始填充后，对新 secondmate 范围内排队的项目执行此交接。 对于现有领域或继承的领域，先完成记录接收，确保没有已交付的计划行被作为未完成工作移交。 对于本地路由，辅助脚本会根据 data/secondmates.md 解析并验证 secondmate 的主目录，然后将项目移动委托给 tasks-axi mv（backlog 格式的唯一所有者）；该命令会将每个指定项目及其整个关联集合（阻塞项及其依赖项）原子地从主 data/backlog.md 移至 secondmate 主目录的 data/backlog.md。 对于远程路由，同一个辅助脚本会先将依赖闭合的项目集合原子地从主 backlog 移至 data/handoff/<id>.outbox.md，然后通过 fm-on.sh 传输该 backlog 格式的 outbox，并由远程主目录的 fm-backlog-receive.sh 在目标锁内移入所有尚未存在的键。 新的本地存放位置或远程 outbox 接收持久化后，辅助脚本会尝试通过接收方 secondmate 已记录的端点发送一条带标记的路由工作指令。 bin/fm-backlog-handoff.sh 负责特定路由的唤醒结果、持久接收后远程 outbox 的释放，以及稳定的唤醒关联重试行为。 这里没有两阶段交接日志，也没有超出已要求的原子 mv 能力的 tasks-axi release。 在授权修改时，Bootstrap 会重试待处理的 outbox 和唤醒，并对所有仍未处理的 outbox 输出 SECONDMATE_HANDOFF:。 即使 config/backlog-backend=manual，仍必须使用此委托路由；该设置仅控制 firstmate 对 backlog 的常规编辑。 它会按字节原样移动每个排队项目的整个区块——包括 - [ ] <id> ... 标题、其后所有缩进两个或更多空格的正文行和空行分隔符，直至下一个项目或位于第 0 列的节标题——并保留在同一节中；缩进的 ## ... 行会被视为正文，而不是节边界，因此标题及其正文都不会重复或被遗留。 如果选定项目包含仅缩进一个空格或以制表符缩进的后续行，则会拒绝移动，以免主 backlog 中遗留内容。 它只接受范围内 ## Queued 下的条目，并拒绝 ## In flight 和历史 ## Done 条目。 已完成记录保留在所属主目录中，以便清理或归档。 此操作具有幂等性；secondmate backlog 中已存在的项目会跳过。 成功移动后，如果有任何已移动的键仍需发送绑定到 main/<key> 的公开 Relay 回复，脚本会发出警告，因为该绑定已不再指向负责该工作的主目录；请按照 fmx-respond 的 promised-final 流程，将该承诺重新绑定到 secondmate:<id>，相关命令由该流程负责。 同一规则也适用于一般路由：如果 Relay 关联请求的工作被分配给 secondmate，就不能使用主目录本地的提及链接，必须将 promised-final 承诺绑定到该 secondmate 的主目录。 如果目标不是一个真正完成初始设置的 firstmate 主目录，或缺少安全的运行目录及匹配的 .fm-secondmate-home 标记，则会拒绝该目标，确保项目绝不会被移入其他项目中。 不要移交 local-only 项目。

恢复

对于没有窗口的本地 kind=secondmate 元数据，应将 secondmate 视为已停止的持久直接下属，并重新启动：

bin/fm-spawn.sh <id> --secondmate

使用元数据中记录的 home=。 如果元数据缺失，但 data/secondmates.md 仍登记了该 secondmate，则根据登记项及其持久 home 重新启动。 对于远程路由，同一命令只会探测配置的主机，并仅在该主机上重新启动。 SSH 传输失败或远程端点不可读时，状态仍属未知，必须在该主机上核实；切勿启动本地替代项。 stuck-crewmate-recovery 中关于远程 secondmate 的说明解释了为何看似足以支持这些判断的端点已死和发送失败判定本身并不可靠。 重新启动时会根据当前配置重新解析 secondmate harness，使用相同的启动前防护式同步，并重新传播继承的本地材料；因此，只要其 home 有效，恢复后的 secondmate 就会统一继承的配置项和共享 captain 偏好；受跟踪文件的同步仍单独受到防护。 如果 secondmate 已在运行，只是继承的本地材料发生变化，应优先使用 bin/fm-config-push.sh，而不是重新启动。 将正在运行的本地 secondmate 切换到新固定的 harness、模型或 effort 前，请查看 docs/agent-control.md 中的替换支持情况。 在支持的后端上，设置 config/secondmate-harness，然后使用 bin/fm-control.sh <id> relaunch 重新启动；该命令会重新解析固定项、停止 Agent，并在同一 home 中启动替代项。 相同的重新启动和恢复路径也遵循持久化的每个 secondmate 账户固定项。 该控制层会按名称拒绝远程放置的 secondmate，因为它的 Agent 在另一台主机上运行，无法读取该控制层的任何后置条件。 使用 bin/fm-remote-secondmate-relaunch.sh <id> <harness> <model|default|-> <effort|default|-> 移动远程 secondmate；此命令会在其主机上执行相同的控制层重新启动，然后根据该主机确认的身份重新发布此主机自己的路由元数据。请显式传入配置，并在没有固定项时使用 default，因为 config/secondmate-harness 不会继承，且该主机上的副本属于另一个 home（docs/remote-secondmates.md）。 切勿直接通过 fm-on.sh 调用 fm-remote-secondmate-control.sh relaunch 来执行此操作：这样会使此主机自己的记录仍指向 mate 之前运行时使用的配置。 成功更新后，会自动重启两个放置位置上所有正在运行的 mate，包括已处于目标提交版本的 mate；/updatefirstmate 技能负责此流程，而 bin/fm-secondmate-restart.sh 负责其持久化门控和失败分类。

不要从主 home 重建 secondmate 的整个目录树。 主 firstmate 只核实直接下属。 每个 secondmate 都是其自身 home 中的 firstmate，因此会在启动时运行恢复，并核实自己的 crewmate。 secondmate 的恢复只核实已经属于它的工作，然后进入空闲状态。 它在恢复期间绝不会发起调查或审计。

退役和拆除

secondmate 默认是持久运行的。 队列为空属于正常状态，不会触发拆除。 只有 captain 或主 firstmate 明确决定让该持久 second mate 退役时，才对 kind=secondmate 运行 bin/fm-teardown.sh <id>。

安全检查以 secondmate 自身的主目录为准。 只要其 state/*.meta 中仍有进行中的工作，拆除就会拒绝执行。 只要该 id 的任一父级待回复仍未解决，非强制退役也会拒绝执行。 远程路由会将进行中工作检查委托给其配置的主机，并且在主实例存在待处理的交接发件箱时也会拒绝执行。 SSH 退出码 255 表示远程操作是否完成尚不明确，因此会保留路由和本地记录。 退役继续执行时，拆除会终止直接端点，移除该 id 的所有父级待回复记录（包括已解决但残留的记录）及其交付确认，移除 data/secondmates.md 路由，清除主目录元数据，并移除已退役 secondmate 的主目录。 如果无法关闭端点，退役会在移除任何指向该端点的记录之前停止，这样清理就不会在磁盘上已无任何记录指向某个可能仍在运行的 Agent 时，报告操作成功。 bin/fm-teardown.sh 的 endpoint_close_refusal 契约负责规定特定后端的 --force 限制；端点关闭验证记录了各后端能够确认的内容。 移除已租用的主目录时，会通过 treehouse return 释放其持久的 treehouse 租约，从而释放池槽位以供复用，而不是让它永远处于已租用状态。 没有池槽位的普通克隆主目录会直接移除。 如果已租用主目录的 treehouse return 失败，拆除会在状态保持不变的情况下停止，而不是直接删除目录并掩盖仍被占用的租约。 无论是归还还是直接移除，拆除都会先请求目标主目录的进程事件运行器，通过安全的、绑定代次的路径退役其注册项和实际归其所有的整机级声明。 如果该清理状态不确定或不可用，拆除会拒绝退役，并保留主目录和退役记录，以便稍后重试。 不支持直接删除，因为阻塞中的进程事件子进程可能在其主目录被移除后仍继续运行。

使用 --force 时，拆除会执行显式丢弃操作。 bin/fm-teardown.sh 中的工作树槽位所有权契约仍然适用：--force 绝不授权归还其他任务可能拥有的后代池槽位。 它会终止子窗口，丢弃 secondmate 主目录中的子任务工作和状态，移除路由，释放租约，并移除已退役 secondmate 的主目录。 如果强制拆除与任何受影响主目录中的新任务发布发生竞争，单条命令会拒绝执行，且不会发布或移除任务状态；应将此拒绝视为最终结果，并在重试前检查另一项操作。 fm-spawn.sh --relaunch 和非强制拆除不受该任务集序列化机制约束；自动恢复序列化由 fm-secondmate-liveness-lib.sh 的文件头负责。 除非 captain 明确要求丢弃工作，否则绝不要使用 --force。