@numa-tech/numa 1.13.4 → 1.14.0

package/README.md

@@ -194,8 +194,9 @@ numa config \
 | `numa registry approvals/router/audit` | 需登录 | 两人制发布、Router 健康/对账和追加式审计 |
 | `numa registry tui` | 需登录 | 打开 namespace、Skills、MCP、审批、Router、审计全屏工作台 |
 | `numa app capabilities/begin/onboard/publication/jenkins-binding/observer-scope/first-build/...` | 需登录 | 自述运行时能力，创建、接入并按独立 child gate Promote 应用 |
-| `numa publication scan/plan/apply/status/events/...` | 公开扫描/需登录写入 | 把 clean Git HEAD 通过受控 bundle 发布到受管仓库 |
+| `numa publication scan/plan/apply/status/events/...` | 公开扫描/需登录写入 | 把 clean Git HEAD 通过受控 bundle 发布到受管仓库；plan 可按原 request ID 只读恢复 |
 | `numa jenkins job plan/apply/status/events/...` | 需登录 | 创建/校验 Jenkins Multibranch Job，默认不扫描、不构建 |
+| `numa pipeline platform-build trigger/resolve/status/log/stop` | 需登录 | 新应用 v2 immutable snapshot 构建；无任意参数，GitOps 写由平台 SCM CAS 完成 |
 | `numa app options` | 需登录 | 查询应用归属所需的团队、系统、业务域和环境 ID |
 | `numa app candidate list/inspect/preview/review/adopt` | 需登录 | 审查应用发现候选并确认收录，服务端执行最终管理员授权和审计 |
 | `numa media capabilities` | 需登录 | 查询媒体 API、Provider 和版本能力 |
@@ -535,6 +536,29 @@ numa app first-build decide <session-no> --decision defer \
   --idempotency-key defer-code-index-first-build --yes --json
 ```
 
+onboarding v3 在 GitOps structural apply 完成后会于同一 session/task 内自动执行
+server-internal `gitops-platform-writer-bootstrap/v2`，在 Observer 和 first-build 之前锁定并只读写
+base release、exact overlay values、overlay kustomization 三个服务文件。这不是新 CLI
+或独立 child plan；CLI 只通过原有 `app inspect <session-no> [--watch] [--after-sequence]`
+读取 `GITOPS_V2_WRITER_BOOTSTRAP` 事件。只有 exact contract/identity/revision/digest 匹配的
+成功事件才能继续；`PENDING` 只继续等待原 session，`UNKNOWN` 或 drift 均 fail closed。
+该阶段不调用 v1 `legacy-image-migration`，不枚举、读取或改写 Secret，也不新建
+Application、session、binding 或 target。
+
+若事件进入 `UNKNOWN`，先只读检查原 session；普通 status/inspect 和 first-build 的未知结果恢复
+都不会重启 bootstrap。只有服务端把同一内部步骤标记为可重入失败时，用户才显式调用既有的
+通用会话恢复命令；服务端据此恢复原 run/key，不创建新的 bootstrap 请求或业务身份：
+
+```bash
+numa app inspect <session-no> --after-sequence <last-sequence> --json
+numa app retry <session-no> --json
+numa app inspect <session-no> --watch --after-sequence <last-sequence> --json
+```
+
+`app retry` 不接受 bootstrap、SCM、path、Secret、binding、target 或 first-build 参数；调用后仍须等到
+同一 `GITOPS_V2_WRITER_BOOTSTRAP` 的 exact 成功证据。若状态仍为 `UNKNOWN` 或出现 drift，继续阻断
+Observer/first-build，禁止重放 first-build POST、手工修改 SCM 或改用新 session/identity。
+
 `app publication attach --json` 只返回 session/plan 标识、manifest 计数和 tree digest 摘要，不返回
 完整 session draft/plan、manifest path、本地绝对路径或文件内容。若写响应在网关处变成结果未知，
 CLI 会以原 `sessionNo/clientRequestId` 有界轮询固定的 `GET publication-plan/resolve`；只有 200
@@ -543,6 +567,19 @@ CLI 会以原 `sessionNo/clientRequestId` 有界轮询固定的 `GET publication
 `app publication resolve` 重查；仍无确定结果时返回 `onboarding_publication_result_unknown`，不自动
 重放 attach。
 
+独立 `STANDALONE` Publication（不属于 onboarding parent）在 plan POST 的 500/504、连接中断或无效
+2xx 后会自动用原 `clientRequestId` 有界调用同一只读 resolve API；POST 始终只发一次。恢复结果必须仍是
+`STANDALONE` 且 `repositoryKey` 与请求一致，否则 fail closed：
+
+```bash
+numa publication plan create --source ./project --repository-key <repository-key> \
+  --commit-message 'feat: publish source' --client-request-id <stable-id> \
+  --idempotency-key <stable-id> --json
+numa publication plan resolve --client-request-id <stable-id> --json
+```
+
+`PUBLICATION_PLAN_NOT_RESOLVED` 的 retryable 404 只表示可稍后继续 GET；不得重放 plan create。
+
 v3 structural spec 只允许 MCI_FLUX_V1 结构字段，拒绝 image、仓库/分支/namespace/path、raw
 Kubernetes Secret 和明文敏感环境变量。Job Control Plane 默认 `scanMode=NONE`；`INDEX_ONLY`
 也必须通过服务端 NoTrigger 配置验证，不能等同于 build。
@@ -580,14 +617,20 @@ Application Onboarding 契约定义。
 SCM 目录和连接诊断使用同一身份。仓库查询支持服务端 search/cursor 分页，返回稳定的
 `externalId`、`defaultBranch`、`headRevision`；向导选中仓库后会把 `headRevision` 固定为
 `expectedHead`。HTTP 429 会保留服务端 `Retry-After` 诊断，Provider 未安装（501）时 TUI
-明确退回手工填写稳定标识。Codeup 安全摘要会额外显示 HTTPS clone credential readiness；
-含 `100755` 文件时只有 `codeup_clone_credential_configured=true` 才能继续 Publication：
+明确退回手工填写稳定标识。Codeup 安全摘要分别显示 OpenAPI Personal AT readiness
+`codeup_access_token_configured` 与 HTTPS clone credential readiness
+`codeup_clone_credential_configured`，但只有
+`codeup_credential_readiness_available=true` 时才解释这两个布尔值。availability 为 `false` 或字段
+缺失时，即使旧响应显式返回 configured=`false`，也保持 `unknown`；只有 availability=`true` 且
+configured=`false` 才是 `missing`。不能把 `capabilities.executable_mode` 当作 credential 证据。
+含 `100755` 文件时只有 availability 与 clone configured 同时为 `true` 才能继续 Publication：
 
 ```bash
 numa app scm list --provider codeup --json
 numa app scm inspect codeup-main --repositories --search order --limit 50 --json
 numa app scm inspect codeup-main --repositories --cursor '<next-cursor>' --limit 50 --json
 numa app scm probe codeup-main --json
+numa repository connection list --json
 ```
 
 仓库生命周期也可以脱离应用入驻流程单独使用。先查询 Provider 返回的稳定 namespace
@@ -644,9 +687,9 @@ numa gitops service plan \
   --spec gitops-service.json \
   --json
 
-# 只用受管引用规划 legacy Jenkins image writer 迁移；不接受 YAML/path/image/secret
+# 仅旧 v1 应用使用：只用受管引用规划 legacy Jenkins image writer 迁移；不接受 YAML/path/image/secret
 numa gitops service legacy-image-migration plan \
-  --application code-index \
+  --application legacy-order-service \
   --target prd \
   --profile MCI_FLUX_V1 \
   --json
@@ -654,7 +697,7 @@ numa gitops service legacy-image-migration plan \
 # 使用 plan 原样返回的 number/hash；结果不明时必须复用同一 Idempotency-Key
 numa gitops service apply gplan_01 \
   --plan-hash <64-hex> \
-  --idempotency-key code-index-prd-image-migration-apply-1 \
+  --idempotency-key legacy-order-prd-image-migration-apply-1 \
   --yes --json
 
 # status/events 同时接受 stable runNo 和数字 ID
@@ -680,7 +723,12 @@ spec 不得包含整个 `image`，也不得包含应用、环境、namespace、r
 `GITOPS_IMAGE_REPOSITORY_UNRESOLVED` 阻断，不会猜测镜像地址。返回的 `canonicalSpecHash`、
 `planHash`、`baseRevision` 和 `sideEffects` 是后续审阅的锁定证据。
 
-`legacy-image-migration plan` 严格只提交 `applicationCode/targetKey/profileCode/profileVersion/serviceId`。
+`legacy-image-migration plan` 只适用于明确保留 legacy/v1 writer 的旧应用，严格只提交
+`applicationCode/targetKey/profileCode/profileVersion/serviceId`。新应用 v2 不调用该接口；它在
+onboarding v3 GitOps structural apply 之后由服务端内部自动执行
+`gitops-platform-writer-bootstrap/v2`，且只读写该服务的 base release、exact overlay values 和
+overlay kustomization 三个受管文件。CLI 无 bootstrap 命令，只从原 session events 读取
+`GITOPS_V2_WRITER_BOOTSTRAP`；不枚举或修改同一 overlay 的 sibling Secret。
 路径、image pointers 和文件变更由服务端派生；CLI 只输出 `READY/BLOCKED`、plan number/hash、
 changed file count、blocker/recovery、warnings 和 side effects，不输出 path/diff/pointer。`READY` 后复用
 `gitops service apply`。该 plan API 没有 Idempotency-Key 或 resolve-by-key，因此响应不明时必须
@@ -691,49 +739,115 @@ fail closed，不自动重放；只有获得 plan number 后才可用 status/eve
 `REVIEWED_CHANGE` 会进入 `WAITING_REVIEW` 并返回审查地址。apply 请求只包含 `planNumber`、
 `planHash` 和 `Idempotency-Key`，不接受任意 repository/path/image 输入。
 
-## Jenkins GitOps image writer rollout
+## Jenkins GitOps image writer rollout v1
 
-Jenkins rollout 管理位于 `numa jenkins gitops-rollout`。读取需 Jenkins reader；plan/apply/readiness
-只允许 `mci-devops-platform-ops-admin`。所有写入都要求稳定 `Idempotency-Key` 和 `--yes`，
-且使用 backend `jenkins-gitops-rollout/v1` 的 strict DTO。
+旧 Jenkins rollout 管理位于 `numa jenkins gitops-rollout`。读取需 Jenkins reader；
+plan/apply/readiness 只允许 `mci-devops-platform-ops-admin`。所有写入都要求稳定
+`Idempotency-Key` 和 `--yes`，且保持 backend `jenkins-gitops-rollout/v1` 的 strict DTO 和行为。
+该命令族不包含 automatic configure；新应用不应通过它隐式升级。
 
 ```bash
-# 规划单应用启用 platform writer；contract 固定为 gitops-image-delivery/v1
+# 旧 v1 contract 固定为 gitops-image-delivery/v1
 numa jenkins gitops-rollout plan enable-platform \
-  --application code-index --instance numa \
+  --application legacy-order-service --instance numa \
   --shared-library-revision 230e0f00444dfd1874e1ab3e624381341a0c31c5 \
-  --idempotency-key code-index-rollout-plan-1 --yes --json
+  --idempotency-key legacy-order-v1-rollout-plan-1 --yes --json
 
 numa jenkins gitops-rollout plan get <plan-no> --json
 
 # apply 只持久化 fail-closed rollout gate，不写 Jenkins 或触发 build
 numa jenkins gitops-rollout apply \
   --plan-no <plan-no> --plan-hash <64hex> \
-  --idempotency-key code-index-rollout-apply-1 --yes --json
+  --idempotency-key legacy-order-v1-rollout-apply-1 --yes --json
 
-numa jenkins gitops-rollout list --application code-index --instance numa --json
+numa jenkins gitops-rollout list --application legacy-order-service --instance numa --json
 numa jenkins gitops-rollout get <rollout-no> --json
 
-# 先在 Jenkins trusted 管理面完成返回的 exact operator actions，再做人工证明
-numa jenkins gitops-rollout readiness <rollout-no> \
-  --desired-mode platform --expected-version <version> \
+# 旧 v1 readiness 是人工证明，不是 live-read
+numa jenkins gitops-rollout readiness <legacy-rollout-no> \
+  --desired-mode legacy --expected-version <version> \
   --operator-action-reference CHG-20260824-001 \
-  --idempotency-key code-index-readiness-1 --yes --json
+  --idempotency-key legacy-order-readiness-1 --yes --json
 ```
 
-`readiness` 固定是 `MANUAL_OPERATOR_ATTESTED`，不是 Jenkins live-read。CLI 从当前 rollout 回传
-exact public tuple 和固定 credential reference names，不接受 secret value、raw XML、env map 或
-credential value。响应不明时，apply 只有在 list 中发现 exact application/instance/plan mode
-且 durable version 增长才恢复；readiness 只有 GET 同 rollout 显示 exact reference/mode/status/identity
+`readiness` 固定是 `MANUAL_OPERATOR_ATTESTED`，不是 Jenkins live-read。CLI 从当前
+rollout 回传 exact public tuple 和固定 credential reference names，不接受 secret value、raw XML、env map
+或 credential value。响应不明时，apply 只有在 list 中发现 exact application/instance/plan mode 且 durable
+version 增长才恢复；readiness 只有 GET 同 rollout 显示 exact reference/mode/status/identity
 且 version 增长才恢复。其余情况均返回 result unknown，不自动重放。
 
+## Platform build rollout v2
+
+新应用的 Jenkins 配置门禁位于独立 `numa jenkins platform-build-rollout`，与 v1
+`gitops-rollout` 的 API、DTO、表和状态机分离。v2 只支持 `ENABLE_PLATFORM`/
+`DISABLE_PLATFORM`，没有 manual readiness，不要求 Jenkins 持有 Flux Git credential。
+
+```bash
+numa jenkins platform-build-rollout plan enable-platform \
+  --application code-index --instance numa \
+  --shared-library-revision <approved-v2-shared-library-revision> \
+  --idempotency-key code-index-v2-rollout-plan-1 --yes --json
+
+numa jenkins platform-build-rollout plan get <plan-no> --json
+numa jenkins platform-build-rollout apply \
+  --plan-no <plan-no> --plan-hash <64hex> \
+  --idempotency-key code-index-v2-rollout-apply-1 --yes --json
+numa jenkins platform-build-rollout list --application code-index --instance numa --json
+numa jenkins platform-build-rollout get <rollout-no> --json
+numa jenkins platform-build-rollout configure <rollout-no> \
+  --expected-version <version> \
+  --idempotency-key code-index-v2-auto-configure-1 --yes --json
+```
+
+`configure` 的 strict body 只有 `expectedVersion`，不接收 public tuple、env、XML、Groovy、
+token、credential ID/value 或 operator attestation。服务端只有在返回 exact
+`READY/JENKINS_API_VERIFIED/VERIFIED`、writer credential readiness、observed shared-library/source
+revision 以及 Jenkinsfile/profile/configuration digest 时才放行。响应不明时 CLI 只 GET
+同一 rollout，不重放 POST。
+
+automatic configure 之前，Project Publication CAS 必须发布 exact
+`@Library('mciShareLib@<approvedSharedLibraryRevision>') _`、唯一 `platformBuildEntry()` 和 strict
+`.mci/platform-build.yaml`。生产 snapshot 执行服务端固定 wrapper，不加载应用 Jenkinsfile；
+Jenkins 只 checkout 锁定源码并构建/push 镜像，Flux SCM CAS 由 DevOps 服务端执行。
+
+## Platform build v2
+
+新应用使用独立 `pipeline platform-build` 表面；旧 `pipeline build/builds/status/log/stop/retry` 的 v1
+请求和响应保持不变。v2 不接受任意 Jenkins 参数，生产审批依据只保留在平台审计中。镜像构建完成后，
+Jenkins 只提交一次 image intent；DevOps 服务端持有 Flux writer credential，并按锁定 contract/HEAD
+执行 SCM CAS。运行态完成证据仍来自独立 Observer。
+
+```bash
+numa pipeline platform-build trigger code-index \
+  --tier production --branch master \
+  --idempotency-key code-index-prd-first-v2 \
+  --production-reason '新运维系统上线前首次生产构建与部署' \
+  --yes --wait --json
+
+# trigger 响应未知时只读恢复，绝不重放 POST
+numa pipeline platform-build resolve \
+  --client-request-id code-index-prd-first-v2 --json
+numa pipeline platform-build status <request-id> --watch --json
+numa pipeline platform-build log <request-id> --start 0 --json
+
+# stop 同样只发送一次；未知后只读同一个 request
+numa pipeline platform-build stop <request-id> \
+  --idempotency-key code-index-prd-stop-v2 \
+  --production-reason '停止异常的首次生产构建' \
+  --yes --json
+```
+
+首次 v2 build 的正式入口仍由原 onboarding session 的 first-build action 创建，独立命令用于恢复与
+运维；不得新建第二 Application、Repository、session、binding 或 target。任何 result unknown 都必须
+使用原 key/request 只读 resolve/status，不能换 key 重放。
+
 SCM 管理接口位于 `/api/v1/admin/scm-connections`，最终权限始终由网关和后端按 canonical
 Client Role 校验。metadata JSON 只允许 provider、URL、组织、auth type 以及服务端托管的
 `aliyunAccountId`/`aliyunAssumeRoleId` 引用；Numa 不接收云 AK。CODEUP 必须引用
 `aliyunAccountId`，没有 access token 时直接使用服务端 Aliyun identity，不写入空 credential。
 Codeup Personal AT 只用于 OpenAPI，不能当作 HTTPS Git 密码；包含 `100755` 文件的 Publication
 另需 Codeup 的 HTTPS clone username/password。GitHub App/PAT 和这三项 Codeup credential 均为
-WRITE_ONLY，只能从 owner-only 文件或重定向 stdin 读取，禁止放在 argv、环境变量和 metadata
+WRITE_ONLY，只能从隐藏终端提示、owner-only 文件或重定向 stdin 读取，禁止放在 argv、环境变量和 metadata
 JSON 中，且不会出现在输出或错误中。安全响应只返回 credential readiness boolean：
 
 ```bash
@@ -741,7 +855,7 @@ numa app scm create --input codeup.json --json
 chmod 600 github-app.private.json
 numa app scm create --input github.json --credential-file github-app.private.json --json
 numa app scm rotate github-main --revision 4 --credential-stdin --yes --json < github-pat.private.json
-numa app scm rotate codeup-main --revision 5 --credential-file codeup.private.json --yes --json
+numa app scm rotate codeup-main --revision 5 --credential-prompt --yes --json
 numa app scm disable old-codeup --revision 7 --yes --json
 ```
 

package/dist/application-onboarding/client.d.ts

@@ -155,6 +155,7 @@ export declare class OnboardingClient implements OnboardingApi {
             health: string;
             capabilities: Record<string, boolean>;
             credentialConfigured?: boolean | undefined;
+            codeupCredentialReadinessAvailable?: boolean | undefined;
             codeupAccessTokenConfigured?: boolean | undefined;
             codeupCloneCredentialConfigured?: boolean | undefined;
             lastCheckedAt?: string | null | undefined;

package/dist/application-onboarding/commands.d.ts

@@ -48,6 +48,7 @@ export interface PublicationAttachmentRecoveryOptions {
     delaysMs?: number[];
     sleep?: (milliseconds: number) => Promise<void>;
 }
+export declare function canAttachPublicationPlan(inspection: OnboardingInspection): boolean;
 export type OnboardingRecoveryAction = "cancel" | "retry" | "resume" | "reassess";
 export type ApplicationCatalogOptionType = "team" | "system" | "business-domain" | "environment";
 export declare function publicOnboardingEvent(event: OnboardingEvent): OnboardingEvent;
@@ -56,6 +57,7 @@ export declare function parseOnboardingMode(value: string): OnboardingMode;
 export declare function parseApplicationCatalogOptionType(value: string): ApplicationCatalogOptionType;
 export declare function resolveScmConnection(client: Pick<OnboardingApi, "listScmConnections">, code: string): Promise<ScmConnection>;
 export declare function scmCredentialUpdate(version: number, authType: ScmAuthType, credential: ScmCredentialBundle): ScmCredentialUpdate;
+export declare function scmConnectionLine(connection: ScmConnection): string;
 export declare function readOnboardingSpec(path: string): Promise<OnboardingSpec>;
 export declare function executeOnboardingSpec(client: OnboardingApi, spec: OnboardingSpec, options?: {
     mode?: OnboardingMode;

package/dist/application-onboarding/commands.js

@@ -24,6 +24,20 @@ const STATE_SUMMARIES = {
     FAILED: "服务端执行失败；请依据事件中的 errorCode 和 recoveryAction 恢复",
     CANCELLED: "服务端已取消尚未开始的步骤；既有外部资源未回滚"
 };
+export function canAttachPublicationPlan(inspection) {
+    const { session } = inspection;
+    if (session.state !== "WAITING_EXTERNAL" || !session.planHash)
+        return false;
+    if (session.currentStep === "ATTACH_PUBLICATION_PLAN")
+        return true;
+    if (session.currentStep !== "EXECUTION")
+        return false;
+    const latest = inspection.events.at(-1);
+    return latest?.eventType === "WAITING_EXTERNAL"
+        && latest.stepCode === "ATTACH_PUBLICATION_PLAN"
+        && latest.stepState === "WAITING"
+        && latest.output?.planHash === session.planHash;
+}
 function addExamples(command, examples, notes = []) {
     const noteSection = notes.length
         ? `\n说明:\n${notes.map((item) => `  - ${item}`).join("\n")}\n`
@@ -187,14 +201,17 @@ export function scmCredentialUpdate(version, authType, credential) {
         return { version, githubPat: credential };
     return { version, codeup: credential };
 }
-function scmConnectionLine(connection) {
+function readiness(value, available) {
+    if (available !== true || value == null)
+        return "unknown";
+    return value ? "ready" : "missing";
+}
+export function scmConnectionLine(connection) {
     const enabled = Object.entries(connection.capabilities).filter(([, value]) => value).map(([key]) => key);
-    const codeupCloneReadiness = connection.provider === "CODEUP"
-        ? `\tcodeup-clone:${connection.codeupCloneCredentialConfigured == null
-            ? "unknown"
-            : connection.codeupCloneCredentialConfigured ? "ready" : "missing"}`
+    const codeupReadiness = connection.provider === "CODEUP"
+        ? `\tcodeup-at:${readiness(connection.codeupAccessTokenConfigured, connection.codeupCredentialReadinessAvailable)}\tcodeup-clone:${readiness(connection.codeupCloneCredentialConfigured, connection.codeupCredentialReadinessAvailable)}`
         : "";
-    return `${connection.code}\t${connection.provider}\t${connection.health}\t${connection.organizationKey}\t${enabled.join(",") || "no-capabilities"}${codeupCloneReadiness}`;
+    return `${connection.code}\t${connection.provider}\t${connection.health}\t${connection.organizationKey}\t${enabled.join(",") || "no-capabilities"}${codeupReadiness}`;
 }
 function repositoryLine(repository) {
     return `${repository.externalId}\t${repository.fullName ?? repository.name}\t${repository.defaultBranch ?? "-"}\t${repository.headRevision ?? "-"}${repository.archived ? "\tARCHIVED" : ""}`;
@@ -649,10 +666,10 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
 安全边界:
   普通诊断只显示 code、provider、organization、health 和 capability。
   live probe 与连接变更由服务端校验平台管理员权限和乐观锁 version。
-  provider credential 只能来自权限受限文件或重定向 stdin；禁止通过 argv、环境变量或普通 JSON 输出传递。
+  provider credential 只能来自隐藏终端提示、权限受限文件或重定向 stdin；禁止通过 argv、环境变量或普通 JSON 输出传递。
   Codeup 云 AK/Role 只能引用已有 aliyunAccountId/aliyunAssumeRoleId，Numa 不读取或保存云 AK。
   Codeup accessToken 只用于 OpenAPI；含 100755 文件的 Publication 另需 HTTPS cloneUsername/clonePassword。
-  三者只从 chmod 600 文件或重定向 stdin 写入；未提供时使用服务端 Aliyun identity，不提交空 credential bundle。
+  三者只从隐藏终端提示、chmod 600 文件或重定向 stdin 写入；未提供时使用服务端 Aliyun identity，不提交空 credential bundle。
 `);
     addExamples(scm.command("list")
         .description("列出当前用户可见的安全 SCM 连接摘要")
@@ -793,6 +810,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         .requiredOption("--input <file>", "无 secret 的连接 metadata JSON")
         .option("--credential-file <file>", "仅 owner 可读（chmod 600）的 provider credential JSON")
         .option("--credential-stdin", "从重定向 stdin 读取 provider credential JSON")
+        .option("--credential-prompt", "在交互终端隐藏输入 provider credential")
         .action(async (options, command) => {
         const onboarding = client();
         const input = await readScmAdminConnectionInput(options.input);
@@ -808,7 +826,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         await output(command, { ok: true, connection }, `${connection.code}\t${connection.status}\tversion:${connection.version}\tcredential:${connection.credentialConfigured ? "configured" : "missing"}\tcodeup-at:${connection.codeupAccessTokenConfigured ? "ready" : "missing"}\tcodeup-clone:${connection.codeupCloneCredentialConfigured ? "ready" : "missing"}`);
     }), [
         "numa app scm create --input github.json --credential-file github-app.private.json --json",
-        "numa app scm create --input codeup.json --json"
+        "numa app scm create --input codeup.json --credential-prompt --json"
     ]);
     addExamples(scm.command("update <code>")
         .description("平台管理员按 version 更新连接 metadata；身份字段变更可能使已有 plan 失效")
@@ -833,11 +851,12 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         .requiredOption("--revision <number>", "当前乐观锁 version")
         .option("--credential-file <file>", "仅 owner 可读（chmod 600）的 provider credential JSON")
         .option("--credential-stdin", "从重定向 stdin 读取 provider credential JSON")
+        .option("--credential-prompt", "在交互终端隐藏输入 provider credential")
         .option("--yes", "确认凭据轮换并使旧 plan 失效")
         .action(async (code, options, command) => {
         requireConfirmation(options.yes, "SCM credential rotation");
-        if (!options.credentialFile && !options.credentialStdin) {
-            throw new OnboardingError("SCM credential rotation requires --credential-file or --credential-stdin.", "onboarding_scm_credential_source_invalid");
+        if (!options.credentialFile && !options.credentialStdin && !options.credentialPrompt) {
+            throw new OnboardingError("SCM credential rotation requires --credential-prompt, --credential-file, or --credential-stdin.", "onboarding_scm_credential_source_invalid");
         }
         const onboarding = client();
         const version = revision(options.revision);
@@ -851,7 +870,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         await output(command, { ok: true, connection }, `${connection.code}\tcredential:configured\tversion:${connection.version}`);
     }), [
         "numa app scm rotate github-main --revision 4 --credential-file github-app.private.json --yes --json",
-        "numa app scm rotate codeup-main --revision 2 --credential-stdin --yes --json < codeup.private.json"
+        "numa app scm rotate codeup-main --revision 2 --credential-prompt --yes --json"
     ]);
     addExamples(scm.command("disable <code>")
         .description("平台管理员软禁用连接；服务端会阻止仍被非终态会话使用的连接")
@@ -961,9 +980,15 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
             throw new OnboardingError("idempotency-key must exactly match client-request-id for publication attachment.", "onboarding_input_invalid");
         }
         const onboarding = client();
-        const session = await onboarding.getSession(sessionNo);
-        if (session.state !== "WAITING_EXTERNAL" || session.currentStep !== "ATTACH_PUBLICATION_PLAN") {
-            throw new OnboardingError("Publication attachment requires the same parent session to be WAITING_EXTERNAL at ATTACH_PUBLICATION_PLAN.", "onboarding_publication_session_invalid", undefined, undefined, false, { sessionNo: session.sessionNo, state: session.state, currentStep: session.currentStep ?? null });
+        const inspection = await inspectOnboardingSession(onboarding, sessionNo);
+        const session = inspection.session;
+        if (!canAttachPublicationPlan(inspection)) {
+            throw new OnboardingError("Publication attachment requires the same parent session to have durable WAITING_EXTERNAL evidence for ATTACH_PUBLICATION_PLAN.", "onboarding_publication_session_invalid", undefined, undefined, false, {
+                sessionNo: session.sessionNo,
+                state: session.state,
+                currentStep: session.currentStep ?? null,
+                lastSequence: inspection.lastSequence
+            });
         }
         const source = await scanPublication(options.source);
         const input = parsedActionInput(OnboardingPublicationPlanActionRequestSchema, {
@@ -1180,7 +1205,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         "numa app tui --session 8d15ee89-43f0-4378-a7aa-51f09c5b42fc"
     ]);
     addExamples(app.command("retry <session-no>")
-        .description("让服务端重试可重入的失败步骤")
+        .description("显式请求服务端恢复同一会话中可重入的失败步骤")
         .action(async (sessionNo, _options, command) => {
         const inspection = await executeOnboardingAction(client(), sessionNo, "retry");
         await output(command, { ok: true, ...inspection }, executionText(inspection.session, inspection.events));