协议与拒绝码

七段执行流程、退出码阶梯、六种拒绝码的含义与处置。

七段执行流程

一次调用会依次经过七个阶段，任何一段失败就停下：

阶段	标识	职责	阻断时的退出码	错误码
1	`ingress_validation`	校验入参，设定超时与工作路径	128	`ERR_PROTOCOL_VIOLATION`
2	`intent_routing`	解析意图，给出得分占比与命中依据	127	`ERR_ROUTE_FAILED`
3	`envfeel_prerequisites`	探测依赖是否存在、版本是否满足、实测能否拉起	126	`ERR_PREREQUISITE_MISSING`
4	`tier_authorization`	读取当前挡位，拦只读下的写操作与越权	126	`ERR_PERMISSION_DENIED`
5	`catalog_containment`	校验解析出的目标是否落在受信根目录内	125	`ERR_TARGET_OUTSIDE_SANDBOX`
6	`sandbox_execution`	在剥除敏感凭证的最小环境里派生进程	124 或子进程退出码	`ERR_EXECUTION_TIMEOUT` / 非零
7	`egress_packaging`	封装返回包，生成并保存执行凭据	0	正常交付

错误码	退出码	发生阶段	触发原因	怎么办
`ERR_PREREQUISITE_MISSING`	126	3	工具声明的运行环境没找到，或实测探针拉不起来	按返回里的修复建议在宿主安装该工具链
`ERR_PERMISSION_DENIED`	126	4	当前是 `read-only`，而请求的工具带写操作	由用户在宿主界面切换挡位，AI 不能代劳
`ERR_TARGET_OUTSIDE_SANDBOX`	125	5	解析出的启动目标落在受信目录之外	检查索引映射配置，不要用相对路径逃逸沙箱
`ERR_EXECUTION_TIMEOUT`	124	6	外部进程超过设定阈值（默认 180 秒）	查目标进程是否死锁或网络假死；必要时调大 `timeout`
`ERR_LAUNCHER_NOT_FOUND`	127	2 / 3	启动器脚本在磁盘上丢了	重跑安装器修复环境
`ERR_SUBPROCESS_EXIT_NONZERO`	1–255	6	操作系统进程自己报错返回非零	看 `stderr`，再用 `retrace` 取现场

退出码阶梯只区分层级，不区分"是谁的错"。

124 超时 / 125 越界 / 126 前置或越权 / 127 路由或启动器 / 128 协议违规。看到哪个数字，就知道在哪一层被拦下的。

注意 ERR_SUBPROCESS_EXIT_NONZERO 的范围是 1–255，和上面几个数字重叠。所以判断时要结合阶段号一起看，别只看退出码。

每次执行都会生成一个 trace_id 和执行凭据。失败时顺着接口往回查：

dsha retrace <trace_id>

输出会把七个阶段从后往前列一遍，标出哪一段 FAIL、哪几段因为上游熔断而 SKIP，并给出根因、复现命令和回滚方式。