@menghuan1918/dsh-apollo 0.5.1 → 0.5.3

package/README.md

@@ -86,13 +86,13 @@ flowchart TB
 
 ```sh
 # npm 安装（发布后）
-dsh plugin --profile <profile> add @menghuan1918/dsh-apollo@0.5.1
+dsh plugin --profile <profile> add @menghuan1918/dsh-apollo@0.5.2
 
 # 或从 GitHub main 源码安装（备选）
 dsh plugin --profile <profile> add github:Menghuan1918/dsh-apollo
 ```
 
-> **发布状态（诚实说明）**：Apollo `0.5.0` 已发布，`dsh-better-subagent@0.1.0` / `dsh-better-compact@0.1.0` 作为其精确依赖已可从 npm 取得。当前版本 `0.5.1` 是旧 profile `name` guard 的迁移修复版；本仓库 0.5.1 的验证使用本地 tarball `npm install --no-save`，提交的 manifest 中**没有** `file:` / `link:` / Git 说明符。
+> **发布状态（诚实说明）**：Apollo `0.5.0` 已发布，`dsh-better-subagent@0.1.0` / `dsh-better-compact@0.1.1` 作为其精确依赖已可从 npm 取得。当前版本 `0.5.2` 是 compact 0.1.1 的设置表单 schema 修复版；本仓库 0.5.1 的验证使用本地 tarball `npm install --no-save`，提交的 manifest 中**没有** `file:` / `link:` / Git 说明符。
 
 安装、升级或换包都会改变运行的代码，必须重启对应 profile 的 DSH 进程；只刷新网页不够。目标行、子代理行与压缩行由 Apollo 的 bundle patch 插入，不需要再单独 `add` 三个子包。
 
@@ -102,14 +102,14 @@ dsh plugin --profile <profile> add github:Menghuan1918/dsh-apollo
 
 ```sh
 dsh plugin --profile <profile> remove dsh-apollo
-dsh plugin --profile <profile> add @menghuan1918/dsh-apollo@0.5.1
+dsh plugin --profile <profile> add @menghuan1918/dsh-apollo@0.5.2
 ```
 
 > `dsh-apollo` 只是旧入口名；unscoped 的 `dsh-apollo` 已被其他项目占用，不要从 npm 安装它。
 
 ## 从 0.4.x 升级
 
-0.5.0 把子代理与压缩能力移出 Apollo，0.5.1 修复旧 profile 行的 `name` guard 迁移缺口。旧 profile 不需要手工重填配置：Apollo 启动后在 settings/loader 可用时运行一次**幂等迁移**（[src/migrate.js](src/migrate.js)）。
+0.5.0 把子代理与压缩能力移出 Apollo，0.5.1 修复旧 profile 行的 `name` guard 迁移缺口；0.5.2 依赖 compact 0.1.1，修复 Web 设置表单的 schema rehydrate。旧 profile 不需要手工重填配置：Apollo 启动后在 settings/loader 可用时运行一次**幂等迁移**（[src/migrate.js](src/migrate.js)）。
 
 > **0.5.1 迁移修复**：如果旧 profile patch 的 `apollo-skills` 覆盖还带历史名称 `name: dsh-apollo`，DSH 会把 `name` 当 guard 并跳过该覆盖，导致有效配置看起来仍是默认值。0.5.1 从 `configEditor.configuration().override` 恢复这些显式值（含 `false` / `0` / `""` / `[]`），再合并到迁移来源；被跳过的旧预设覆盖（`preset-eng` / `preset-eng-ptc`）同样处理。无需手工修改旧行；升级后重启 profile 即可。
 
@@ -171,7 +171,7 @@ flowchart LR
 dsh plugin --profile <profile> add @menghuan1918/dsh-better-subagent@0.1.0
 
 # 只装压缩
-dsh plugin --profile <profile> add dsh-better-compact@0.1.0
+dsh plugin --profile <profile> add dsh-better-compact@0.1.1
 ```
 
 独立安装时的行、页面和提示词与 Apollo 集成完全相同；行 id/name 也是同一组稳定值。区别只在**由谁插入这些行**：Apollo 的 bundle patch 自己携带同样的行，因为 DSH 不会自动应用传递依赖的 bundle patch。
@@ -226,7 +226,7 @@ dsh plugin --profile <profile> remove dsh-better-compact
 - `package.json` 的 `files` 只列入 `docs/DEVELOPMENT.md`，并额外用 [.npmignore](.npmignore) 排除 `docs/specs/`；
 - `tests/packaging.test.mjs` 直接运行 `npm pack --dry-run --json`，断言发布清单没有 Specs、测试、脚本、快照或 tarball。
 
-发布顺序：**先发布并验证两个独立包（`@menghuan1918/dsh-better-subagent@0.1.0`、`dsh-better-compact@0.1.0`），再发布 Apollo 0.5.1**。两个 0.1.0 已随 0.5.0 发布；0.5.1 可只发布本包。Apollo 的精确依赖指向尚不存在的版本时，`npm install` 会失败；不要用开发 `file:`/`link:` 依赖发布。两个子仓各自有 trusted publishing workflow；Apollo 的 [release workflow](.github/workflows/release.yml) 只发布本包。
+发布顺序：**先发布并验证两个独立包（`@menghuan1918/dsh-better-subagent@0.1.0`、`dsh-better-compact@0.1.1`），再发布 Apollo 0.5.2**。两个 0.1.0 已随 0.5.0 发布；0.5.1 可只发布本包。Apollo 的精确依赖指向尚不存在的版本时，`npm install` 会失败；不要用开发 `file:`/`link:` 依赖发布。两个子仓各自有 trusted publishing workflow；Apollo 的 [release workflow](.github/workflows/release.yml) 只发布本包。
 
 ## 验证状态（诚实记录）
 
@@ -239,7 +239,7 @@ dsh plugin --profile <profile> remove dsh-better-compact
 
 **未验证 / 明确限制**：
 
-- 两个子包的 `0.1.0` 尚未发布；本轮只用本地 tarball 验证，未验证 npm registry 安装路径。
+- 子包 `@menghuan1918/dsh-better-subagent@0.1.0` 与 `dsh-better-compact@0.1.1` 已可从 npm 取得。
 - 未修改或重启用户当前运行的 profile，未验证当前 GUI（`http://127.0.0.1:3384`）的设置页/卡片；S3 视觉设置页的 GUI 验收归 S3/最终宿主验收。
 - 未运行真实 Codex/Claude CLI 的真实模型回合（那属于两个子包自己的验证；Apollo 侧本轮只用脚本化适配器）。
 - 真实模型摘要保真、缓存命中率与跨版本预设漂移仍需按实际环境复验。

package/docs/DEVELOPMENT.md

@@ -2,7 +2,7 @@
 
 面向维护者、集成者和需要排查装配问题的用户。用户安装与配置请看 [README](../README.md)；本文保留 DSH 插件的实现细节、旧配置迁移、组合安装边界与验证方法。
 
-当前实现版本：`0.5.1`；npm 包名是 `@menghuan1918/dsh-apollo`。纯 ESM，无构建步骤；宿主浏览器半边是直接加载的闭包工厂。
+当前实现版本：`0.5.3`；npm 包名是 `@menghuan1918/dsh-apollo`。纯 ESM，无构建步骤；宿主浏览器半边是直接加载的闭包工厂。
 
 ## 目录
 
@@ -34,16 +34,15 @@
 | 依赖 | 版本 | 所有权 |
 |---|---|---|
 | `dsh-better-goal` | `0.2.0` | 目标域 |
-| `@menghuan1918/dsh-better-subagent` | `0.1.0` | 子代理 CLI/等待/child guard/分档/设置页 |
-| `dsh-better-compact` | `0.1.0` | 压缩 companion + engine + 设置页/诊断 |
+| `@menghuan1918/dsh-better-subagent` | `0.1.1` | 子代理 CLI/等待/child guard/分档/设置页 |
+| `dsh-better-compact` | `0.1.2` | 压缩 companion + engine + 设置页/诊断 |
 | `@deepseek-ai/schemastery` | `~3.18.4` | Apollo 行 Config |
 | `react` | peer | 宿主提供 |
 
-两个 0.1.0 版本在实现完成时尚未发布到 npm；验证使用本地 tarball：
+正式安装从 npm registry 获取上述精确版本，不需要本地 tarball 或 link：
 
 ```sh
 npm install
-npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/to/dsh-better-compact-0.1.0.tgz
 ```
 
 发布顺序必须是先两个子包、后 Apollo（见[发布](#实现入口打包与发布)）。
@@ -192,7 +191,7 @@ npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/
 1. 有 Loader 时等待装配完成（`loader.await()`，有界）；
 2. 等待 `legacyImport`（旧 eng.json）完成；
 3. 有界轮询 `settings.describe()`，直到 `dsh-better-subagent` 与 `dsh-better-compact` 两个命名空间都出现（默认 5s，50ms 间隔）；
-4. 子代理迁移 → 压缩迁移，各自写入后重读验证；
+4. 子代理迁移 → 恢复 Apollo job 开关 → 压缩迁移，各自写入后重读验证；
 5. 返回状态并记录日志（complete / pending / blocked / error）。
 
 若目标命名空间一直不可读/不可写（例如双显式 bundle 导致写入被拒），日志明确要求重载 profile，迁移保持幂等，下次启动会再试；不宣告成功。迁移不删除旧值，也不创建迁移 sidecar。
@@ -205,6 +204,8 @@ npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/
 
 **0.5.1 修复**：DSH 把 profile 覆盖行的 `name` 当 guard。旧 profile 若保留历史 `name: dsh-apollo`，Loader 会跳过该覆盖，`describe().value` 只剩默认值（例如用户显式 `subagents.eng: false` 会被看成默认 `true`）。迁移现在额外读取 `configEditor.configuration()` 中该行的 `override`，递归合并到有效配置之上：普通对象逐键合并，数组与所有标量（含 `false`/`0`/`""`/`[]`）整体覆盖。这样被跳过的显式值仍会迁移。`preset-eng` / `preset-eng-ptc` 的预设覆盖也按同样方式合并（`plugins` 数组整体替换），再读取原生 `compaction-basic`。
 
+历史 name guard 同样会让仍活跃的 Apollo job `exitGuard` 静默回退到默认 false。现在迁移还会只把这个开关经 `settings.update` 恢复到 Apollo，并重读验证；不会激活其他已弃用字段。宿主 `describe().user` 会投影被跳过的旧覆盖，因此优先检查活动 Apollo entry 的 raw config：它已声明 `exitGuard` 时（尤其当前 scoped 行显式 false），不覆盖。child 目标仍按自己的 `user.childExitGuard` 存在性判断，不让两个开关互相覆盖。旧 unscoped 行保留，重复执行不重写。仅在子代理迁移完成/无需写入后恢复 job 开关，避免新 scoped 行遮蔽尚未导入的旧来源；写入拒绝为 pending，重读不一致为 error，均纳入顶层状态。
+
 目标：`dsh-better-subagent` 的 `settings.describe()`：
 
 - `target.user` 的存在性表示显式值（含 false/0/""/[]）；
@@ -218,7 +219,7 @@ npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/
 | `tiers.fast` / `tiers.quality` | 同名 | 目标该档已有任一显式字段 → 整档不混写；否则来源档与目标默认不同才写 |
 | `subagents.eng` / `global` | 同名 | 目标缺字段且值不同才写；显式 false 是值 |
 | `subagents.codex/claude.*` | 同名 | 逐叶补齐：enabled、executable、profile（仅 codex）、permissionMode、defaultModel、models（含顺序/effort 元数据） |
-| `exitGuard` | `childExitGuard` | 只补目标缺失字段；Apollo 自己的 `exitGuard` 保留给 job 守卫 |
+| `exitGuard` | Apollo `exitGuard` + `childExitGuard` | 两份相同初值，随后独立配置；当前目标显式值（含 false）各自优先 |
 | `trustedHosts` | `trustedHosts` | 非 volatile；目标 raw config 未声明且来源非空时用 `configEditor.edit` 写 |
 
 写入：volatile 用 `settings.update(ns, patch, revision)`；非 volatile 用 target entry 的 `configEditor.edit`。`settings.update` 会触发 reconcile，可能替换目标 entry 对象，因此写 `trustedHosts` 前重新从 `entries()` 取目标 entry。写后重新 `describe()`/读 raw config 校验，任何字段不一致按 `error` 报告。
@@ -240,6 +241,10 @@ npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/
 
 原生默认值不会变成目标显式值：只有来源行里显式存在的键才会被携带。压缩配置是 volatile 保存、引擎载入时冻结快照；迁移后的设置需要重载 profile 才会被运行中引擎采用（inspect 的 `requiresReload` 可观察）。
 
+Apollo 在迁移挂载时先登记启动门禁：验证完成前，`agent/pre-step` 阻止任务步骤，`llm/stream` 同时阻止不经过 pre-step 的手动摘要调用。迁移 pending/blocked/error 不得按默认配置继续执行；应检查日志后修复来源或目标并重载。若本次迁移改变 compact 的载入快照，持久化验证完成后仍要求重载，重载后确认无差异才放行。普通后续设置保存不关闭已通过的启动门禁，仍按原有“当前快照继续、重载后应用新值”语义处理。
+
+宿主行明确 `disabled: true` 时，跳过该增强的迁移，不将其缺少 settings namespace 误判为全宿主故障；活动行缺失 namespace 仍报 pending。子代理增强被禁用时保留尚未迁出的旧来源，并暂缓会遮蔽该来源的旧 job 开关恢复，待重新启用后再迁移；已生效的 Apollo job 配置不变。停用 compact 增强时仍需按卸载说明启用原生 `compaction-basic`，以恢复 `/compact`；启动门禁不替用户改写禁用选择。
+
 ### 迁移测试
 
 - [tests/migrate.test.mjs](../tests/migrate.test.mjs)：纯函数与 fake host 编排。覆盖显式 false/空值、目标优先（分档整档、models 空列表、保留方式二选一）、缺失来源、ambiguity、trustedHosts、写入拒绝、幂等、重读验证、有界等待。
@@ -308,10 +313,10 @@ DSH_PACKAGE_ROOT="/…/node_modules/@deepseek-ai/dsh" npm run prompts
 ### npm 安装
 
 ```sh
-dsh plugin --profile <profile> add @menghuan1918/dsh-apollo@0.5.1
+dsh plugin --profile <profile> add @menghuan1918/dsh-apollo@0.5.2
 ```
 
-包发布后即可用此命令安装，并带入三个精确依赖、应用三份 bundle patch。安装后需要重启对应 profile 的 DSH 进程。0.5.0 已发布；0.5.1 是迁移修复版本，可只发布本包。
+包发布后即可用此命令安装，并带入三个精确依赖、应用三份 bundle patch。安装后需要重启对应 profile 的 DSH 进程。0.5.0 已发布；0.5.1 是迁移修复版本；0.5.2 依赖 compact 0.1.1，修复 Web 设置表单的 schema rehydrate。
 
 ### GitHub 源码安装
 
@@ -319,7 +324,7 @@ dsh plugin --profile <profile> add @menghuan1918/dsh-apollo@0.5.1
 dsh plugin --profile <profile> add github:Menghuan1918/dsh-apollo
 ```
 
-GitHub main 仍是源码安装选项。它同样按 `package.json` 解析精确依赖；两个子包 0.1.0 在 registry 可取得前，源码安装会因依赖 404 失败。
+GitHub main 仍是源码安装选项。它同样按 `package.json` 解析精确依赖；子包 0.1.0/0.1.1 在 registry 可取得前，源码安装会因依赖 404 失败。
 
 ### 本地 link 安装
 
@@ -363,9 +368,9 @@ dsh plugin --profile <profile> remove @menghuan1918/dsh-apollo
 
 两个子仓和 Apollo 都用 GitHub Release 触发 `.github/workflows/release.yml`，通过 npm trusted publishing（OIDC）发布，仓库里不存 npm token。tag 必须是 `v<package.json 的 version>`，CI 会先校验再跑测试和 `npm publish --provenance`。
 
-1. 先发布 `@menghuan1918/dsh-better-subagent@0.1.0` 与 `dsh-better-compact@0.1.0`（各自仓库的 Release）；
+1. 先发布 `@menghuan1918/dsh-better-subagent@0.1.0` 与 `dsh-better-compact@0.1.1`（各自仓库的 Release）；
 2. 在官方 registry（`https://registry.npmjs.org/`）确认两个版本可取得、可安装；
-3. 再把 Apollo 的精确依赖指向已发布版本，推 main 并发布 Apollo Release（0.5.0 已发布；本轮为 `v0.5.1`）；
+3. 再把 Apollo 的精确依赖指向已发布版本，推 main 并发布 Apollo Release（0.5.0 已发布；本轮为 `v0.5.2`）；
 4. 子包版本可取得前，不要把指向它们的精确依赖推到 Apollo main，否则 `npm install` / GitHub 源码安装会 404。
 
 ## 测试与冒烟
@@ -424,7 +429,7 @@ DSH_PACKAGE_ROOT=/path/to/node_modules/@deepseek-ai/dsh node scripts/runtime-smo
 - 本仓库不运行真实 Codex/Claude CLI；两个子包各自的 `cli-smoke` / runtime smoke 负责真实 CLI 生命周期。
 - 真实模型摘要保真、缓存命中率、S3 可视化页面的 GUI 验收不在 Apollo 侧冒烟内。
 - 未修改用户当前运行的 profile，未验证当前 GUI；当前 URL 以执行时 runtime context 为准。
-- 单元测试通过不等于 registry 发布/安装路径通过；两个 0.1.0 未发布前，`npm install` 的正式路径仍未验证。
+- 单元测试通过不等于 registry 发布/安装路径通过；子包 0.1.0/0.1.1 已发布；registry 安装路径已用 fresh cache 验证。
 
 ## 历史兼容
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@menghuan1918/dsh-apollo",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "DSH plugin bundle: workflow skills, engineering presets, independent better-goal / better-subagent / better-compact integration, and a minimal job exit guard. Pure ESM, no build step.",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -54,8 +54,8 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "~3.18.4",
-    "@menghuan1918/dsh-better-subagent": "0.1.0",
-    "dsh-better-compact": "0.1.0",
+    "@menghuan1918/dsh-better-subagent": "0.1.1",
+    "dsh-better-compact": "0.1.2",
     "dsh-better-goal": "0.2.0"
   },
   "peerDependencies": {

package/src/admission.js

@@ -0,0 +1,36 @@
+import { isDeepStrictEqual } from 'node:util'
+
+/** Do not run a turn or manual summary using pre-migration defaults. */
+export function mountMigrationAdmission(ctx) {
+  let report = { status: 'pending' }
+  let requiresReload = false
+  const assertReady = () => {
+    if (report.status !== 'complete') {
+      const detail = report.error ?? report.compact?.error ?? report.compact?.reason ?? report.subagent?.error
+      const error = new Error('Apollo 配置迁移尚未完成（' + report.status + '）。请检查迁移诊断，修复配置后重载 profile。' + (detail ? ' ' + detail : ''))
+      error.code = 'APOLLO_MIGRATION_PENDING'
+      throw error
+    }
+    if (requiresReload) {
+      const error = new Error('Apollo 已迁移压缩配置，但当前引擎仍使用旧快照。请重载 profile 后继续；刷新网页不会应用压缩配置。')
+      error.code = 'APOLLO_MIGRATION_RELOAD_REQUIRED'
+      throw error
+    }
+  }
+  ctx.on('agent/pre-step', (_payload, next) => {
+    assertReady()
+    return next()
+  }, { prepend: true })
+  // Manual /compact does not enter pre-step. Guard its provider boundary too,
+  // without replacing the compaction service or changing any request messages.
+  ctx.on('llm/stream', async function* (_options, next) {
+    assertReady()
+    yield* next()
+  }, { prepend: true })
+  return (result) => {
+    report = result
+    const compact = ctx.get?.('betterCompactConfig')
+    requiresReload = result.status === 'complete' && result.compact?.fields?.length > 0
+      && compact !== undefined && !isDeepStrictEqual(compact.snapshot(), compact.current())
+  }
+}

package/src/index.js

@@ -14,6 +14,7 @@ import { readFile, readdir } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { mountMigration } from './migrate.js'
+import { mountMigrationAdmission } from './admission.js'
 import { mountSettings } from './settings.js'
 export { Config } from './config.js'
 
@@ -33,8 +34,9 @@ export const inject = ['skills']
 export function apply(ctx, config) {
   ctx.skills.registerProvider(() => createProvider(ctx))
   if (typeof ctx.inject === 'function') {
+    const onResult = typeof ctx.on === 'function' ? mountMigrationAdmission(ctx) : undefined
     const settings = mountSettings(ctx, config)
-    mountMigration(ctx, config, { legacyImport: settings.legacyImport })
+    mountMigration(ctx, config, { legacyImport: settings.legacyImport, onResult })
   }
 }
 

package/src/migrate.js

@@ -7,8 +7,8 @@
  *
  *   - `apollo-skills` 的 `tiers.fast/quality`、`subagents.{eng,global}`、
  *     `subagents.{codex,claude}.*`、`trustedHosts` → `dsh-better-subagent`
- *     相同路径；`exitGuard` → `childExitGuard`。旧 `exitGuard` 仍留在 Apollo
- *     作为 job/通用守卫开关，不被删除。
+ *     相同路径；`exitGuard` → `childExitGuard`。旧 `exitGuard` 同时保留/恢复到
+ *     Apollo 作为 job 守卫开关；两边目标显式配置（含 false）各自优先。
  *   - 旧 `eng` / `eng-ptc` 预设里原生 `compaction-basic` 的显式配置 →
  *     `dsh-better-compact` 同名原生键；目标缺失的 `mode` 采用默认 `goal`。
  *
@@ -524,6 +524,28 @@ export async function migrateSubagent({ settings, configEditor, descriptors, sou
   return { status: 'complete', fields }
 }
 
+/** Restore only the job switch lost to a historical Apollo name guard. */
+async function migrateJobExitGuard({ settings, descriptors, source, rawSource }) {
+  const target = descriptors.find((row) => row?.ns === APOLLO_NS)
+  // user also projects skipped overrides, so the active raw config is the
+  // authority for an already configured job switch (including explicit false).
+  if (hasOwn(rawSource, 'exitGuard')
+    || (hasOwn(target?.user, 'exitGuard') && target.user.exitGuard !== source.exitGuard)
+    || target?.value?.exitGuard === source.exitGuard) {
+    return { status: 'no-change' }
+  }
+  if (target === undefined) return { status: 'pending', error: 'Apollo namespace is not readable' }
+  try {
+    await settings.update(APOLLO_NS, { exitGuard: source.exitGuard }, target.revision)
+  } catch (error) {
+    return { status: 'pending', error: errorMessage(error) }
+  }
+  const after = (await settings.describe()).find((row) => row?.ns === APOLLO_NS)
+  return after?.value?.exitGuard === source.exitGuard
+    ? { status: 'complete' }
+    : { status: 'error', error: 'unverified: exitGuard' }
+}
+
 /**
  * Apply the compaction migration.
  *
@@ -570,7 +592,8 @@ function errorMessage(error) {
  * Run the one-time (idempotent) migration.
  *
  * Order: Loader settlement → legacy `eng.json` import → bounded wait for both
- * target namespaces → subagent plan/write/verify → compact plan/write/verify.
+ * target namespaces → subagent plan/write/verify → job switch recovery →
+ * compact plan/write/verify.
  * A missing target namespace yields `pending`; errors are reported, never
  * silently claimed as success, and no source value is deleted.
  *
@@ -588,7 +611,12 @@ export async function runMigration(ctx, options = {}) {
   const loader = loaderOf(ctx)
   if (loader !== undefined) await bounded(Promise.resolve(loader.await()).catch(() => undefined), timeoutMs)
   if (options.legacyImport !== undefined) await bounded(options.legacyImport, timeoutMs)
-  const descriptors = await waitForDescriptors(settings, [SUBAGENT_NS, COMPACT_NS], {
+  const configEditor = options.configEditor ?? serviceOf(ctx, 'configEditor')
+  // A deliberately disabled row is not an unloaded/failed active plugin. Keep
+  // its legacy source intact for a later re-enable instead of blocking native work.
+  const disabled = new Set([SUBAGENT_NS, COMPACT_NS].filter((ns) => targetEntryOf(configEditor, ns)?.options?.disabled === true))
+  const targets = [SUBAGENT_NS, COMPACT_NS].filter((ns) => !disabled.has(ns))
+  const descriptors = await waitForDescriptors(settings, targets, {
     timeoutMs,
     intervalMs: options.intervalMs,
   })
@@ -599,7 +627,6 @@ export async function runMigration(ctx, options = {}) {
     return { status: 'pending', error: message }
   }
   const sourceDescriptor = descriptors.find((row) => row?.ns === APOLLO_NS)
-  const configEditor = options.configEditor ?? serviceOf(ctx, 'configEditor')
   const agentPresets = options.agentPresets ?? serviceOf(ctx, 'agentPresets')
   // describe().value only projects the *volatile* form, so read the Apollo
   // row's raw config for non-volatile fields (trustedHosts) and overlay the
@@ -617,23 +644,34 @@ export async function runMigration(ctx, options = {}) {
     effectiveSource,
     configurationOverrideOf(configEditor, APOLLO_NS),
   ))
-  const subagent = await migrateSubagent({ settings, configEditor, descriptors, source, log })
-  const compact = await migrateCompact({ settings, configEditor, descriptors, agentPresets, log })
-  const status = [subagent.status, compact.status].some((value) => value === 'error')
+  const subagent = disabled.has(SUBAGENT_NS)
+    ? { status: 'disabled', fields: [] }
+    : await migrateSubagent({ settings, configEditor, descriptors, source, log })
+  // A scoped job write would become the last override and hide the skipped
+  // source from configuration().override. Wait until its child fields are safe.
+  const job = subagent.status === 'disabled'
+    ? { status: 'deferred', reason: 'subagent is disabled; preserve the legacy source until it is re-enabled' }
+    : ['complete', 'no-change'].includes(subagent.status)
+      ? await migrateJobExitGuard({ settings, descriptors, source, rawSource })
+      : { status: 'pending', error: 'waiting for the subagent migration before restoring the job switch' }
+  const compact = disabled.has(COMPACT_NS)
+    ? { status: 'disabled', fields: [] }
+    : await migrateCompact({ settings, configEditor, descriptors, agentPresets, log })
+  const status = [job.status, subagent.status, compact.status].some((value) => value === 'error')
     ? 'error'
-    : [subagent.status, compact.status].some((value) => value === 'pending')
+    : [job.status, subagent.status, compact.status].some((value) => value === 'pending')
       ? 'pending'
       : ['ambiguous', 'invalid', 'source-missing'].includes(compact.status) ? 'blocked'
         : 'complete'
-  for (const [name, section] of [['subagent', subagent], ['compact', compact]]) {
+  for (const [name, section] of [['job', job], ['subagent', subagent], ['compact', compact]]) {
     if (section.error !== undefined) {
       log?.warn?.(`apollo-migration: ${name} is ${section.status}: ${section.error}`)
     }
   }
   log?.[status === 'complete' ? 'info' : 'warn']?.(
-    `apollo-migration: ${status} (subagent=${subagent.status}, compact=${compact.status})`,
+    `apollo-migration: ${status} (job=${job.status}, subagent=${subagent.status}, compact=${compact.status})`,
   )
-  return { status, source: sourceDescriptor === undefined ? 'apply-config' : 'settings', subagent, compact }
+  return { status, source: sourceDescriptor === undefined ? 'apply-config' : 'settings', job, subagent, compact }
 }
 
 /**
@@ -641,7 +679,8 @@ export async function runMigration(ctx, options = {}) {
  *
  * @param ctx - plugin context.
  * @param config - Apollo row config (fallback source when describe() is not ready).
- * @param options - `{ legacyImport, env, timeoutMs, intervalMs }`.
+ * @param options - `{ legacyImport, env, timeoutMs, intervalMs, onResult }`.
+ *   `onResult` receives the settled report without blocking the Loader callback.
  */
 export function mountMigration(ctx, config, options = {}) {
   let started = false
@@ -656,7 +695,8 @@ export function mountMigration(ctx, config, options = {}) {
       log: settingsCtx.logger ?? ctx.logger,
     }).catch((error) => {
       settingsCtx.logger?.warn?.(`apollo-migration: skipped: ${errorMessage(error)}`)
-    })
+      return { status: 'error', error: errorMessage(error) }
+    }).then((result) => options.onResult?.(result))
   }
   ctx.inject(['settings'], start)
 }