DevCodex

状态与错误码

先运行 devcodex status 看摘要，再用 devcodex doctor --json 获取 typed issue、证据和下一步。诊断应从真实项目或 workspace 根执行。

若问题是 .devcodex 磁盘增长，使用专用运行态命令，不要先删除文件：

devcodex runtime status --json
devcodex runtime doctor --json
devcodex runtime maintenance --dry-run --json

runtime status 将 V5、项目内 legacy lifecycle 文件与用户级安装 runtime generation 分栏，并显示物理磁盘、reserve、hot/cold/terminal/ephemeral、top task 与配置来源。runtime doctor 检查 A/B、reserve 大小和尾标、容量/headroom、配置、legacy 最近写入及 generation retention 证据。runtime maintenance 默认 preview；即使显式普通 --apply，legacy 的 deletedFiles 仍必须为 0，安装 generation 也只有匹配 --generation-plan 才会处理。

治理台账清单、索引与分片

普通非 dry-run 的 devcodex init / devcodex update 会以零搬迁方式初始化 GovernanceLedgerManifestV1 并重建派生索引；既有 Markdown 台账字节不应改变。也可以显式检查：

devcodex governance ledger init --json
devcodex governance ledger init --apply --json
devcodex governance ledger index --json
devcodex governance ledger index --apply --json
devcodex governance ledger plan --kind GR --json

plan 始终只读。GR 试点只迁移具有明确日期、终态且自包含的记录；真正执行必须把预览返回的 64 位 planDigest 原样传给 devcodex governance ledger apply --kind GR --plan <sha256> --json。source 或 manifest 在预览后漂移会返回 GOVERNANCE_LEDGER_MIGRATION_PLAN_STALE；缺失/篡改 shard、重复主 ID、非法 reopened overlay 或事务残留会失败关闭。回滚使用 devcodex governance ledger rollback --kind GR --plan <sha256> --json，immutable shard 保留为未引用审计证据，不会被普通回滚删除。

manifest 是活动文件、archive shard、reopened overlay 与 nextSequence 的唯一真相源；.memory/indexes/governance-ledgers.json 只是可重建索引。所有普通写入仍落到活动台账，不得直接修改 archive，也不得通过扫描“当前最大编号 + 1”分配新 ID。

status 与 doctor 的 worktrees 字段是只读 WorktreeDiagnosticsV1。WARN 通常表示当前工作树有改动、存在 prunable 元数据，或某个外部 worktree 的 owner/dirty 状态未核实；它不表示 DevCodex 已清理或可以清理。诊断受单命令和总时间预算约束，且绝不执行 prune、remove、unlock、branch 操作或 safe.directory 修改。

若“提交后怎么多了一个分支”，先区分事实与历史原因：过去发生过代理误用通用多人协作分支惯例、又未在创建前告知的情况；这不是 DevCodex 内置的自动建分支行为。先用 git status --short --branch 核实当前分支，再运行 devcodex status 和 devcodex doctor --json 检查 worktree 归属。不要仅因看到未知分支或 prunable 元数据就删除它；任何 branch create/switch/cleanup 都需要独立授权。

readiness 决策树

workspace 能否解析？
├─ 否 → 回到真实根目录，检查 .devcodex 与 Profile
└─ 是 → adapter configured？
   ├─ 否 → global-adapters apply，然后重开宿主
   └─ 是 → contract passed？
      ├─ 否 → 按首个 typed issue 修复并重新 apply
      └─ 是 → native/direct evidence 是否需要且存在？
         ├─ 否 → 保持 UNVERIFIED，不冒充 ready
         └─ 是 → 用全新会话验证用户路径

状态词

状态含义不能推出什么
PASS当前检查与证据通过不自动覆盖其他宿主、版本或发布面
WARN可以继续，但有明确风险或缺口不等于完成
BLOCK当前动作必须停止并恢复不等于整个安装不可用
UNVERIFIED缺少足够的新鲜直接证据既不是 PASS，也不是失败
N/A对当前目标不适用不能计入通过分母

常见错误码

错误码或诊断含义最短恢复
CONTEXT_PLAN_INVALID + Profile README 缺失active target 没有可用 Profile确认项目绑定；用 devcodex profile plan 预览，再初始化 Profile
CLI_COMMAND_UNKNOWN命令不在当前 registrydevcodex help，检查版本与拼写
CLI_HOST_CONFIG_GLOBAL_ONLY尝试从 workspace 命令写宿主 adapter使用 devcodex global-adapters apply
GLOBAL_HOST_RECEIPT_STALE已安装 receipt 与当前包不一致从预期包根重新 apply，重开宿主
GLOBAL_HOST_ENTRYPOINT_MISSING稳定 runtime 的入口文件缺失重新全局安装或 apply
GLOBAL_HOST_MANAGED_CONFIG_DRIFT受管配置与 receipt 不一致保存 doctor 证据并重新 apply
HOST_ADAPTER_ENTRY_MISSINGadapter contract 找不到 runtime 入口恢复用户级 runtime，再跑 doctor
*_MCP_CONTRACT_FAILED某宿主的 memory/profile MCP 指向错误或缺失刷新该宿主 plugin 与稳定 runtime
GLOBAL_HOST_TARGET_UNVERIFIED / sandbox-read-denied当前沙箱不能读取精确用户目录只批准必要目录后重试；兄弟宿主独立判断
node runtime BLOCK / sandbox-exec-deniedNode launcher 在启动前被宿主拒绝核对 Node provider 与精确 launcher 权限
TASK_RECOVERY_CONFIG_INVALIDhardLimitMiB 或 taskRecovery key 非法修正为 safe integer >=512，再运行 runtime doctor --json
TASK_RECOVERY_DISK_HEADROOM_REQUIREDatomic write、reserve 修复与 8 MiB safety headroom 不足先释放项目所在卷空间；不要删除未知 Hook 文件
LIFECYCLE_EPHEMERAL_ENTRY_EXCEEDED临时恢复状态无法压缩到 8 KiB保存 doctor 输出；完整 plan 应从固定 store 重建，不要提高上限
LEGACY_WRITER_RESTART_REQUIRED安装新版本后仍观察到旧 generation writer 写入完全退出相关 AI Coding 宿主并新建任务，再复查最近写入
RUNTIME_GENERATION_RETENTION_NOT_INITIALIZED用户级安装 runtime 还没有 retention state从当前安装包执行 devcodex global-adapters apply --json，重开宿主
generation-adoption-evidence-missinggeneration 没有可验证的本机首次采用记录保留该代次；运行当前包的 global-adapters apply 安装/修复 adoption state，再等待宽限期
RUNTIME_GENERATION_GC_PLAN_STALEgeneration、回执、manifest、树或 lease 在预览后变化重新运行 dry-run；不要复用旧摘要
RUNTIME_GENERATION_GC_CLAIM_RECHECK_FAILED建立独占 claim 后证据不再与预览一致保留所有目标，检查活动 MCP/权限后重新预览
RUNTIME_GENERATION_ACTIVATION_LEASE_REQUIRED安装/回滚目标正被 GC claim 占用，或 activation lease 无法建立当前宿主事务在 mutation 前停止；等待 maintenance 结束后重新执行 apply

证据层不要混用

  • 配置文件存在只证明 configured。
  • adapter contract 通过证明受管入口可解析。
  • 原生 CLI probe 证明该命令身份与基本可达。
  • 真实模型回放才证明对应用户路径。
  • 一个宿主或 variant 的 PASS 不覆盖另一个。

如果 typed issue 不在本页，保存错误码、nextStep、版本、宿主和最小复现；不要先手动删除 .devcodex 或用户级宿主目录。