docs: 区分 AgentRun source 与 trans target

.agents/skills/unidesk-code-queue/SKILL.md

@@ -31,10 +31,12 @@ AipodSpec/Artificer、task manifest 和 queue 渐进披露见 [references/resour
 
 - AgentRun 与调用方之间的契约版本、源码/镜像版本和 `commitId` 对齐只能产生非阻塞 warning；可安全归一化的请求继续 admission/dispatch，不得因版本或契约漂移阻止用户任务、session、run、command 或 runner。
 - 新写入口不要用 `codex submit/steer/resume`；这些 legacy mutation 已冻结。
-- Artificer task prompt 只引用 task 自身的 primary workspace：
-  - 默认写当前工作区 `.`，需要子目录时写相对路径；
-  - 禁止写入宿主 `/root/unidesk`、主代理 worktree 或其他 task 外部绝对路径；
-  - 路径不可见时先用 `agentrun events run/<runId> --detail-seq <seq>` 核对 durable workspace 物化事实，不让 Artificer 搜索或切换到旁路仓库。
+- Artificer 的 primary source workspace 与远端 tool target 必须分开判定：
+  - task prompt 引用待修改源码时，默认写 primary workspace `.`，需要子目录时写相对路径；
+  - 禁止把宿主 `/root/unidesk`、主代理 worktree 或其他 task 外部绝对路径当成 source workspace；
+  - 用户明确授权的 `trans <route> ...` 远端范围属于 `unidesk-ssh` tool target，不是旁路 source workspace；
+  - 访问远端 tool target 必须使用已投影的受控 `trans`，并继续遵守 route allowlist、SecretRef、脱敏和短连接边界；
+  - primary source 路径不可见时，先用 `agentrun events run/<runId> --detail-seq <seq>` 核对 durable workspace 物化事实，不让 Artificer 搜索或切换到旁路仓库。
 - 默认输出保持低噪声表格/摘要；机器消费显式 `-o json|yaml` 或 `--raw`。
 - 读取 task 的可重建输入：
   - 使用 `agentrun describe task/<taskId> --input -o json`；

docs/reference/agentrun.md

@@ -239,7 +239,19 @@ retry 保持 task identity 不变，服务端为每次执行保留不可变 atte
 
 AgentRun 公网 HTTPS 入口、FRP/Caddy edge、direct REST base URL 和鉴权来源都由 UniDesk `config/agentrun.yaml` 声明。YAML-only lane 不允许把这些部署选择写回 AgentRun source branch 的 `deploy/deploy.json`；AgentRun source repo 只保留应用代码、构建输入和 repo 内部实现文档。`bun scripts/cli.ts agentrun control-plane expose --confirm` 只负责按 UniDesk YAML 补 edge 侧 allow port 与 Caddy site，不在 AgentRun k3s 中创建 Ingress、NodePort、LoadBalancer、hostPort 或 HWLAB 转发层。
 
-AgentRun Queue 任务如果需要调用 UniDesk 维护桥，例如 `trans` / `unidesk-ssh`，长期契约以 UniDesk OA 的 [Runtime装配](../../project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md) 和 [YAML运维](../../project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md) 为准：调用方通过 `executionPolicy.secretScope.toolCredentials[].tool=unidesk-ssh` 请求 `UNIDESK_SSH_CLIENT_TOKEN` SecretRef；非敏感 endpoint 由 runner-job `transientEnv` 显式提供，或由 manager 受控默认值自动补齐。UniDesk bridge 提交 Queue payload 时不得在 prompt、payload 或 `transientEnv` 中携带 token，也不得使用 HWLAB runtime Web 入口冒充 UniDesk frontend。若 dispatcher 已正确请求 `unidesk-ssh` 但 trace 的 `runner-job-created.transientEnv.names` 没有 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL`，归为 AgentRun assembly 问题；若 endpoint env 已存在但 route denied/timeout，再按 UniDesk frontend/token scope 或 provider session 排查。
+AgentRun Queue 任务调用 UniDesk 维护桥时，长期契约以 UniDesk OA 的 [Runtime装配](../../project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md) 和 [YAML运维](../../project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md) 为准：
+
+- workspace 与 tool target 边界：
+  - 待修改源码只来自 task 的 primary workspace；
+  - 用户明确授权的 `trans <route> ...` 远端范围属于 `unidesk-ssh` tool target，不属于旁路 source workspace；
+  - runner 的 `tran` 必须委派 primary UniDesk workspace 中的共享 `scripts/tran`，不得在 AgentRun 维护第二套 Windows、host 或 k3s route parser。
+- credential 与 endpoint：
+  - 调用方通过 `executionPolicy.secretScope.toolCredentials[].tool=unidesk-ssh` 请求 `UNIDESK_SSH_CLIENT_TOKEN` SecretRef；
+  - 非敏感 endpoint 由 runner-job `transientEnv` 显式提供，或由 manager 受控默认值自动补齐；
+  - UniDesk bridge 提交 Queue payload 时不得在 prompt、payload 或 `transientEnv` 中携带 token，也不得使用 HWLAB runtime Web 入口冒充 UniDesk frontend。
+- 失败归因：
+  - dispatcher 已请求 `unidesk-ssh`，但 trace 的 `runner-job-created.transientEnv.names` 没有 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL`，归为 AgentRun assembly 问题；
+  - endpoint env 已存在但 route denied 或 timeout，再按 UniDesk frontend token scope、route allowlist 或 provider session 排查。
 
 旧 UniDesk Code Queue 只保留历史归档、只读排障和残留旧任务停止入口。`codex submit/enqueue`、`codex steer`、`codex resume`、`codex queue create/merge`、`codex move`、旧 Web 提交表单、旧队列管理和旧 workdir 管理都必须返回冻结状态或禁用；`codex task/tasks/output/read/unread/queues` 可继续读取历史，`codex interrupt|cancel` 只用于停止残留旧任务。旧 Code Queue history 不迁移到 AgentRun，也不提供 adapter、legacy mode、fallback 或双写路径。