@numa-tech/numa 1.13.1 → 1.13.3

package/dist/application-onboarding/commands.js

@@ -4,9 +4,10 @@ import { loadAppConfig } from "../app-config.js";
 import { loadConfig } from "../config.js";
 import { registerApplicationCandidateCommands } from "../application-candidates/commands.js";
 import { SourceRepositoryClient } from "../repositories/client.js";
+import { scanProjectPublication } from "../publications/scanner.js";
 import { OnboardingClient } from "./client.js";
 import { OnboardingError, sanitizeOnboardingOutput } from "./errors.js";
-import { OnboardingModeSchema, OnboardingEventOutputSchema, OnboardingSessionStateSchema, OnboardingSpecSchema, ScmProviderSchema } from "./schemas.js";
+import { OnboardingModeSchema, OnboardingEventOutputSchema, OnboardingFirstBuildActionRequestSchema, OnboardingJenkinsBindingActionRequestSchema, OnboardingObserverScopeActionRequestSchema, OnboardingPublicationPlanActionRequestSchema, OnboardingSessionStateSchema, OnboardingSpecSchema, ScmProviderSchema } from "./schemas.js";
 import { readScmAdminConnectionInput, readScmCredentialBundle } from "./scm-credentials.js";
 import { runOnboardingTui } from "./tui.js";
 const TERMINAL_STATES = new Set(["COMPLETED", "FAILED", "CANCELLED"]);
@@ -188,7 +189,12 @@ export function scmCredentialUpdate(version, authType, credential) {
 }
 function scmConnectionLine(connection) {
     const enabled = Object.entries(connection.capabilities).filter(([, value]) => value).map(([key]) => key);
-    return `${connection.code}\t${connection.provider}\t${connection.health}\t${connection.organizationKey}\t${enabled.join(",") || "no-capabilities"}`;
+    const codeupCloneReadiness = connection.provider === "CODEUP"
+        ? `\tcodeup-clone:${connection.codeupCloneCredentialConfigured == null
+            ? "unknown"
+            : connection.codeupCloneCredentialConfigured ? "ready" : "missing"}`
+        : "";
+    return `${connection.code}\t${connection.provider}\t${connection.health}\t${connection.organizationKey}\t${enabled.join(",") || "no-capabilities"}${codeupCloneReadiness}`;
 }
 function repositoryLine(repository) {
     return `${repository.externalId}\t${repository.fullName ?? repository.name}\t${repository.defaultBranch ?? "-"}\t${repository.headRevision ?? "-"}${repository.archived ? "\tARCHIVED" : ""}`;
@@ -211,6 +217,56 @@ function idempotencyKey(value, operation = "--apply") {
     }
     return candidate;
 }
+function stableActionText(value, label, maximum = 253) {
+    const candidate = value?.trim() ?? "";
+    if (!candidate || candidate.length > maximum || /[\u0000-\u001f\u007f]/u.test(candidate)) {
+        throw new OnboardingError(`${label} must be 1-${maximum} printable characters.`, "onboarding_input_invalid");
+    }
+    return candidate;
+}
+function sha256(value, label) {
+    const candidate = value?.trim() ?? "";
+    if (!/^[0-9a-f]{64}$/u.test(candidate)) {
+        throw new OnboardingError(`${label} must be the exact lower-case SHA-256 locked by the server.`, "onboarding_input_invalid");
+    }
+    return candidate;
+}
+function collectParameter(value, previous) {
+    return [...previous, value];
+}
+function buildParameters(values) {
+    if (!values?.length)
+        return undefined;
+    if (values.length > 100)
+        throw new OnboardingError("At most 100 first-build parameters are allowed.", "onboarding_input_invalid");
+    const result = {};
+    for (const value of values) {
+        const separator = value.indexOf("=");
+        const key = separator > 0 ? value.slice(0, separator).trim() : "";
+        const parameterValue = separator > 0 ? value.slice(separator + 1) : "";
+        if (!/^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/u.test(key) || parameterValue.length > 2_000
+            || /[\u0000-\u001f\u007f]/u.test(parameterValue)) {
+            throw new OnboardingError("Each --parameter must be printable KEY=VALUE with a stable key.", "onboarding_input_invalid");
+        }
+        const normalizedKey = key.replace(/[^A-Za-z0-9]/gu, "").toLowerCase();
+        if (["secret", "password", "passwd", "credential", "token", "privatekey", "apikey", "accesskey"].some((part) => normalizedKey.includes(part))
+            || /\b(?:Bearer|Basic)\s+\S+/iu.test(parameterValue)
+            || /\b(?:gh[pousr]_[A-Za-z0-9_]{20,}|LTAI[A-Za-z0-9]{12,})\b/u.test(parameterValue)
+            || /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/u.test(parameterValue)) {
+            throw new OnboardingError("First-build parameters cannot contain credential-like keys or values.", "onboarding_secret_not_allowed");
+        }
+        if (Object.hasOwn(result, key))
+            throw new OnboardingError(`Duplicate first-build parameter: ${key}`, "onboarding_input_invalid");
+        result[key] = parameterValue;
+    }
+    return result;
+}
+function parsedActionInput(schema, value) {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success)
+        throw new OnboardingError(`Invalid onboarding action input: ${parsed.error.message}`, "onboarding_input_invalid");
+    return parsed.data;
+}
 export async function readOnboardingSpec(path) {
     try {
         const info = await stat(path);
@@ -239,6 +295,9 @@ export async function executeOnboardingSpec(client, spec, options = {}) {
     if (!options.apply && options.idempotencyKey) {
         throw new OnboardingError("--idempotency-key is only valid with --apply.", "onboarding_input_invalid");
     }
+    if (spec.schemaVersion === 3 && spec.projectStrategy === "PUBLISH_PROJECT" && !options.sessionNo) {
+        throw new OnboardingError("schemaVersion=3 PUBLISH_PROJECT must reuse the session created by `numa app begin`; provide --session <session-no>.", "onboarding_session_required");
+    }
     const key = options.apply ? idempotencyKey(options.idempotencyKey) : undefined;
     const draftSession = options.sessionNo
         ? await client.getSession(options.sessionNo)
@@ -264,9 +323,17 @@ export async function executeOnboardingSpec(client, spec, options = {}) {
     if (!planHash) {
         throw new OnboardingError("The server did not return a plan hash; apply was not submitted.", "onboarding_plan_missing");
     }
-    const task = await client.apply(session.sessionNo, { planHash, idempotencyKey: key });
+    const attempt = await executeOnboardingSessionMutation(client, session.sessionNo, () => client.apply(session.sessionNo, { planHash, idempotencyKey: key }), (event) => hasOnboardingApplyRecoveryEvidence(event, planHash));
+    if (!attempt.result) {
+        return {
+            session: attempt.inspection.session,
+            preflight,
+            idempotencyKey: key,
+            recoveredFromStatus: true
+        };
+    }
     session = await client.getSession(session.sessionNo);
-    return { session, preflight, task, idempotencyKey: key };
+    return { session, preflight, task: attempt.result, idempotencyKey: key, recoveredFromStatus: false };
 }
 function defaultSleep(milliseconds, signal) {
     return new Promise((resolve, reject) => {
@@ -316,7 +383,7 @@ export async function inspectOnboardingSession(client, sessionNo, afterSequence
         .filter((event) => event.sequenceNo > afterSequence)
         .map(publicOnboardingEvent)
         .sort((left, right) => left.sequenceNo - right.sequenceNo);
-    const lastSequence = events.reduce((maximum, event) => Math.max(maximum, event.sequenceNo), afterSequence);
+    const lastSequence = events.reduce((maximum, event) => Math.max(maximum, event.sequenceNo), Math.max(afterSequence, eventPage.nextSequence ?? afterSequence));
     return {
         session,
         events,
@@ -324,6 +391,192 @@ export async function inspectOnboardingSession(client, sessionNo, afterSequence
         execution: { ...onboardingExecutionView(session, events), lastSequence }
     };
 }
+function mutationResultMayBeUnknown(error) {
+    if (error instanceof OnboardingError) {
+        return error.retryable
+            || (error.status != null && error.status >= 500)
+            || (error.code === "onboarding_invalid_response" && error.status != null
+                && error.status >= 200 && error.status < 300);
+    }
+    return error instanceof TypeError;
+}
+export function hasOnboardingApplyRecoveryEvidence(event, planHash) {
+    return event.output?.taskNo != null && event.output.planHash === planHash;
+}
+export function hasJenkinsBindingRecoveryEvidence(_event, _bindingId) {
+    // jenkinsBindingId alone does not prove CONFIRMED status or the requested
+    // optimistic-lock version; unknown confirmations therefore fail closed.
+    return false;
+}
+export function hasObserverScopeRecoveryEvidence(_event) {
+    // The reviewed event projection currently lacks serviceBindingId and exact
+    // observer coordinates, so no event can prove this request's full intent.
+    return false;
+}
+export function hasFirstBuildRecoveryEvidence(_event, _input) {
+    // Aggregated task output can repeat an older decision on an unrelated new
+    // event and does not carry the action idempotency key or full build intent.
+    return false;
+}
+export async function executeOnboardingSessionMutation(client, sessionNo, mutate, hasNewEvidence) {
+    // A pre-write cursor is required: without it, a matching field or broad
+    // session state that predates this request could be misreported as recovery.
+    const baseline = await inspectOnboardingSession(client, sessionNo);
+    try {
+        return { result: await mutate(), recoveredFromStatus: false };
+    }
+    catch (error) {
+        if (!mutationResultMayBeUnknown(error))
+            throw error;
+        let inspection;
+        try {
+            inspection = await inspectOnboardingSession(client, sessionNo, baseline.lastSequence);
+        }
+        catch {
+            // Preserve the mutation error below; a failed read must never trigger a write replay.
+        }
+        if (inspection && inspection.events.some((event) => event.sequenceNo > baseline.lastSequence && hasNewEvidence(event, baseline, inspection))) {
+            return { inspection, recoveredFromStatus: true };
+        }
+        const original = error instanceof OnboardingError ? error : undefined;
+        throw new OnboardingError("The mutation result is unknown. Status recovery was attempted; inspect the same session before reusing the original idempotency key.", "onboarding_result_unknown", original?.status, original?.requestId, true, {
+            sessionNo,
+            recoveryCommand: `numa app inspect ${sessionNo} --json`,
+            originalCode: original?.code ?? "network_error"
+        }, original?.retryAfterSeconds);
+    }
+}
+function assertPublicationSessionBinding(result, sessionNo, resolved) {
+    if (result.session.sessionNo !== sessionNo
+        || result.publicationPlan.consumerType !== "APPLICATION_ONBOARDING"
+        || result.publicationPlan.consumerRef !== sessionNo
+        || (resolved && !result.replayed)) {
+        throw new OnboardingError("The publication response is not a replay bound to the same APPLICATION_ONBOARDING session.", "onboarding_invalid_response", 200);
+    }
+}
+function publicationResolutionPending(error) {
+    return error instanceof OnboardingError
+        && error.status === 404
+        && error.code === "ONBOARDING_PUBLICATION_PLAN_NOT_RESOLVED"
+        && error.retryable;
+}
+export async function executePublicationAttachmentWithRecovery(client, sessionNo, clientRequestId, mutate, options = {}) {
+    try {
+        const result = await mutate();
+        assertPublicationSessionBinding(result, sessionNo, false);
+        return { result, recoveredFromStatus: false };
+    }
+    catch (error) {
+        if (!mutationResultMayBeUnknown(error))
+            throw error;
+        const delaysMs = options.delaysMs ?? [0, 200, 500, 1_000];
+        const sleep = options.sleep ?? ((milliseconds) => defaultSleep(milliseconds));
+        let resolutionCode;
+        for (const delayMs of delaysMs) {
+            if (delayMs > 0)
+                await sleep(delayMs);
+            try {
+                const result = await client.resolvePublicationPlan(sessionNo, clientRequestId);
+                assertPublicationSessionBinding(result, sessionNo, true);
+                return { result, recoveredFromStatus: true };
+            }
+            catch (resolutionError) {
+                resolutionCode = resolutionError instanceof OnboardingError ? resolutionError.code : "network_error";
+                if (publicationResolutionPending(resolutionError) || mutationResultMayBeUnknown(resolutionError))
+                    continue;
+                break;
+            }
+        }
+        const original = error instanceof OnboardingError ? error : undefined;
+        throw new OnboardingError("The publication attachment result is unknown. Continue read-only resolution with the original session and client-request-id; do not replay the write based on this error.", "onboarding_publication_result_unknown", original?.status, original?.requestId, true, {
+            sessionNo,
+            clientRequestId,
+            recoveryCommand: `numa app publication resolve ${sessionNo} --client-request-id ${clientRequestId} --json`,
+            originalCode: original?.code ?? "network_error",
+            resolutionCode
+        }, original?.retryAfterSeconds);
+    }
+}
+function sessionSummary(session) {
+    return {
+        sessionNo: session.sessionNo,
+        mode: session.mode,
+        state: session.state,
+        currentStep: session.currentStep,
+        revision: session.revision,
+        planHash: session.planHash
+    };
+}
+function recoveredMutationPayload(inspection, idempotencyKeyValue) {
+    return {
+        ok: true,
+        session: sessionSummary(inspection.session),
+        execution: inspection.execution,
+        recoveredFromStatus: true,
+        mutationResponseReceived: false,
+        idempotencyKey: idempotencyKeyValue,
+        recovery: { inspectCommand: `numa app inspect ${inspection.session.sessionNo} --json` }
+    };
+}
+export function onboardingPublicationAttachmentView(result, source, idempotencyKeyValue, recoveredFromStatus = false) {
+    const plan = result.publicationPlan;
+    return {
+        ok: true,
+        session: sessionSummary(result.session),
+        publicationPlan: {
+            planNo: plan.planNo,
+            state: plan.state,
+            planHash: plan.planHash,
+            repositoryKey: plan.repositoryKey,
+            consumerType: plan.consumerType,
+            consumerRef: plan.consumerRef,
+            publicationMode: plan.publicationMode,
+            branch: plan.branch,
+            expectedHead: plan.expectedHead,
+            fileCount: plan.manifest.length,
+            warningCount: plan.warnings.length,
+            blockerCount: plan.blockers.length,
+            expiresAt: plan.expiresAt
+        },
+        scan: {
+            schemaVersion: source.schemaVersion,
+            sourceRevision: source.sourceRevision,
+            sourceTreeDigest: source.sourceTreeDigest,
+            clean: source.clean,
+            fileCount: source.fileCount,
+            totalBytes: source.totalBytes,
+            executableFileCount: source.executableFileCount
+        },
+        replayed: result.replayed,
+        recoveredFromStatus,
+        idempotencyKey: idempotencyKeyValue
+    };
+}
+export function onboardingPublicationResolutionView(result, clientRequestId) {
+    const plan = result.publicationPlan;
+    return {
+        ok: true,
+        session: sessionSummary(result.session),
+        publicationPlan: {
+            planNo: plan.planNo,
+            state: plan.state,
+            planHash: plan.planHash,
+            repositoryKey: plan.repositoryKey,
+            consumerType: plan.consumerType,
+            consumerRef: plan.consumerRef,
+            publicationMode: plan.publicationMode,
+            branch: plan.branch,
+            expectedHead: plan.expectedHead,
+            fileCount: plan.manifest.length,
+            warningCount: plan.warnings.length,
+            blockerCount: plan.blockers.length,
+            expiresAt: plan.expiresAt
+        },
+        replayed: result.replayed,
+        recoveredFromStatus: true,
+        clientRequestId
+    };
+}
 export async function executeOnboardingAction(client, sessionNo, action) {
     await client[action](sessionNo);
     return inspectOnboardingSession(client, sessionNo);
@@ -353,6 +606,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
     const client = () => dependencies.clientFactory?.() ?? new OnboardingClient(loadConfig("platform"));
     const isInteractive = dependencies.interactive ?? (() => Boolean(process.stdin.isTTY && process.stdout.isTTY));
     const tui = dependencies.runTui ?? runOnboardingTui;
+    const scanPublication = dependencies.scanPublication ?? scanProjectPublication;
     const sleep = dependencies.sleep ?? defaultSleep;
     const app = program.command("app")
         .description("创建新应用或把存量代码库接入 DevOps 平台")
@@ -363,6 +617,15 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
   结果不明时用相同 idempotency-key 重试或 inspect/resume，禁止新建重复会话。
 `);
     registerApplicationCandidateCommands(app);
+    addExamples(app.command("capabilities")
+        .description("读取服务端 Application Onboarding 能力自述；命令存在不代表端到端能力可用")
+        .action(async (_options, command) => {
+        const capabilities = await client().getCapabilities();
+        await output(command, { ok: true, capabilities }, JSON.stringify(stableOutput(capabilities), null, 2));
+    }), ["numa app capabilities --json"], [
+        "与 `numa commands --json`、Repository capability 及各 child control plane 的只读能力共同形成运行时能力矩阵。",
+        "HTTP 501 表示服务端能力未发布；不得因为本地命令存在就声称可执行。"
+    ]);
     addExamples(app.command("options <type>")
         .description("按名称查询应用所需的团队、系统、业务域或环境 ID")
         .option("--search <text>", "按 code 或名称搜索")
@@ -388,7 +651,8 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
   live probe 与连接变更由服务端校验平台管理员权限和乐观锁 version。
   provider credential 只能来自权限受限文件或重定向 stdin；禁止通过 argv、环境变量或普通 JSON 输出传递。
   Codeup 云 AK/Role 只能引用已有 aliyunAccountId/aliyunAssumeRoleId，Numa 不读取或保存云 AK。
-  未提供 Codeup accessToken 时使用服务端 Aliyun identity，不提交空 credential bundle。
+  Codeup accessToken 只用于 OpenAPI；含 100755 文件的 Publication 另需 HTTPS cloneUsername/clonePassword。
+  三者只从 chmod 600 文件或重定向 stdin 写入；未提供时使用服务端 Aliyun identity，不提交空 credential bundle。
 `);
     addExamples(scm.command("list")
         .description("列出当前用户可见的安全 SCM 连接摘要")
@@ -541,7 +805,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         if (credential) {
             connection = await onboarding.rotateAdminScmCredential(connection.code, scmCredentialUpdate(connection.version, connection.authType, credential));
         }
-        await output(command, { ok: true, connection }, `${connection.code}\t${connection.status}\tversion:${connection.version}\tcredential:${connection.credentialConfigured ? "configured" : "missing"}`);
+        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"
@@ -565,7 +829,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         await output(command, { ok: true, connection }, `${connection.code}\t${connection.status}\tversion:${connection.version}`);
     }), ["numa app scm update github-main --input github.json --revision 4 --yes --json"]);
     addExamples(scm.command("rotate <code>")
-        .description("平台管理员写入新 GitHub 或 Codeup access token；不会回显 credential")
+        .description("平台管理员轮换 GitHub 凭据或 Codeup OpenAPI/HTTPS clone 凭据；不会回显 credential")
         .requiredOption("--revision <number>", "当前乐观锁 version")
         .option("--credential-file <file>", "仅 owner 可读（chmod 600）的 provider credential JSON")
         .option("--credential-stdin", "从重定向 stdin 读取 provider credential JSON")
@@ -587,7 +851,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-token.private.json"
+        "numa app scm rotate codeup-main --revision 2 --credential-stdin --yes --json < codeup.private.json"
     ]);
     addExamples(scm.command("disable <code>")
         .description("平台管理员软禁用连接；服务端会阻止仍被非终态会话使用的连接")
@@ -603,11 +867,27 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         await onboarding.disableAdminScmConnection(code, version);
         await output(command, { ok: true, code, disabled: true, previousVersion: version }, `${code}\tDISABLED`);
     }), ["numa app scm disable github-main --revision 5 --yes --json"]);
+    addExamples(app.command("begin")
+        .description("幂等创建空 onboarding session，为 consumer-bound Repository plan 获取 sessionNo")
+        .requiredOption("--mode <mode>", "new|existing")
+        .requiredOption("--idempotency-key <key>", "同一 actor/mode 结果未知时复用")
+        .option("--yes", "确认创建服务端草稿会话")
+        .action(async (options, command) => {
+        requireConfirmation(options.yes, "Beginning an onboarding session");
+        const key = idempotencyKey(options.idempotencyKey, "onboarding begin");
+        const session = await client().createSession(parseOnboardingMode(options.mode), key);
+        await output(command, { ok: true, session, idempotencyKey: key }, sessionLine(session));
+    }), [
+        "numa app begin --mode new --idempotency-key begin-code-index-onboarding --yes --json"
+    ], [
+        "先取得 sessionNo，再创建 consumer=APPLICATION_ONBOARDING、consumerRef=sessionNo 的 Repository plan。",
+        "相同 actor/key/mode 安全返回原 session；不同 mode 冲突，不会创建第二个会话。"
+    ]);
     addExamples(app.command("onboard")
         .description("启动入驻向导，或按 JSON spec 创建、预检和执行")
         .option("--mode <mode>", "new|existing；如有 --spec 必须与文件一致")
         .option("--session <session-no>", "更新已有草稿并跨 Web/CLI 恢复；不创建新会话")
-        .option("--spec <file>", "schemaVersion=1（兼容）或 2（Repository Control Plane）的 onboarding JSON 文件")
+        .option("--spec <file>", "schemaVersion=1（兼容）、2（Repository CP）或 3（Promote 全链路）的 onboarding JSON 文件")
         .option("--plan", "保存草稿并执行服务端预检，不产生外部副作用")
         .option("--apply", "保存草稿、预检并提交服务端异步执行")
         .option("--idempotency-key <key>", "apply 幂等键；结果不明时必须复用")
@@ -632,11 +912,13 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
             idempotencyKey: options.idempotencyKey
         });
         const execution = onboardingExecutionView(result.session);
-        const text = result.task
-            ? `入驻执行已提交:\n${executionText(result.session)}\nidempotency-key: ${result.idempotencyKey}`
-            : result.preflight
-                ? `预检完成: ${sessionLine(result.session)}\nplan: ${result.preflight.planHash ?? "-"}\nblocking: ${result.preflight.blockingErrors.length}`
-                : `草稿已保存: ${sessionLine(result.session)}`;
+        const text = result.recoveredFromStatus
+            ? `写响应未知，已从同一会话状态恢复:\n${executionText(result.session)}\nidempotency-key: ${result.idempotencyKey}`
+            : result.task
+                ? `入驻执行已提交:\n${executionText(result.session)}\nidempotency-key: ${result.idempotencyKey}`
+                : result.preflight
+                    ? `预检完成: ${sessionLine(result.session)}\nplan: ${result.preflight.planHash ?? "-"}\nblocking: ${result.preflight.blockingErrors.length}`
+                    : `草稿已保存: ${sessionLine(result.session)}`;
         await output(command, { ok: true, ...result, execution }, text);
     }), [
         "numa app onboard",
@@ -648,6 +930,163 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         "未指定 --plan/--apply 时只保存服务端草稿。",
         "完整 spec 保存的 currentStep 为稳定字符串 REVIEW。"
     ]);
+    const publicationAction = app.command("publication")
+        .description("为 schemaVersion=3 会话附加受控本地源码 Publication 计划");
+    addExamples(publicationAction.command("resolve <session-no>")
+        .description("按原 clientRequestId 只读恢复 publication attach 的确定结果")
+        .requiredOption("--client-request-id <id>", "原 attach 使用的稳定 child request ID")
+        .action(async (sessionNo, options, command) => {
+        const clientRequestId = stableActionText(options.clientRequestId, "client-request-id", 160);
+        const result = await client().resolvePublicationPlan(sessionNo, clientRequestId);
+        assertPublicationSessionBinding(result, sessionNo, true);
+        await output(command, onboardingPublicationResolutionView(result, clientRequestId), `${result.publicationPlan.planNo}\t${result.publicationPlan.state}\t${result.publicationPlan.planHash}\trecovered-from-status`);
+    }), [
+        "numa app publication resolve <session-no> --client-request-id onboarding-code-index-publication --json"
+    ], [
+        "固定 GET resolve，不上传 bundle、不重放 attach；404 ONBOARDING_PUBLICATION_PLAN_NOT_RESOLVED 可安全稍后重查。",
+        "compact 输出不含 manifest path、文件内容、完整 session draft/plan 或 SCM credential。"
+    ]);
+    addExamples(publicationAction.command("attach <session-no>")
+        .description("扫描 clean Git HEAD 并创建绑定当前 onboarding planHash 的 child plan；不写远端 Git")
+        .requiredOption("--source <directory>", "本地 Git worktree 根目录")
+        .requiredOption("--commit-message <message>", "受审提交消息，1-500字符")
+        .requiredOption("--client-request-id <id>", "稳定 child request ID")
+        .requiredOption("--idempotency-key <key>", "结果未知时必须复用；须与 client-request-id 相同")
+        .option("--yes", "确认上传受限源码 bundle 并附加 child plan")
+        .action(async (sessionNo, options, command) => {
+        requireConfirmation(options.yes, "Attaching a project publication plan");
+        const key = idempotencyKey(options.idempotencyKey, "publication attach");
+        const clientRequestId = stableActionText(options.clientRequestId, "client-request-id", 160);
+        if (key !== clientRequestId) {
+            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 source = await scanPublication(options.source);
+        const input = parsedActionInput(OnboardingPublicationPlanActionRequestSchema, {
+            parentPlanHash: sha256(session.planHash, "session planHash"),
+            clientRequestId,
+            sourceRevision: source.sourceRevision,
+            sourceTreeDigest: source.sourceTreeDigest,
+            clean: true,
+            commitMessage: options.commitMessage,
+            files: source.requestFiles
+        });
+        const attempt = await executePublicationAttachmentWithRecovery(onboarding, session.sessionNo, clientRequestId, () => onboarding.attachPublicationPlan(session.sessionNo, input, key));
+        const result = attempt.result;
+        await output(command, onboardingPublicationAttachmentView(result, source, key, attempt.recoveredFromStatus), `${result.publicationPlan.planNo}\t${result.publicationPlan.state}\t${result.publicationPlan.planHash}\t${attempt.recoveredFromStatus ? "recovered-from-status" : `replayed:${result.replayed}`}`);
+    }), [
+        "numa app publication attach <session-no> --source ./code-index --commit-message 'feat: publish code-index source' --client-request-id onboarding-code-index-publication --idempotency-key onboarding-code-index-publication --yes --json"
+    ], [
+        "只读取 clean Git HEAD；compact 输出不含 sourceRoot、manifest path、contentBase64、完整 session draft/plan 或 SCM credential。",
+        "POST 500/504、连接中断或成功响应无法解析时，CLI 以原 sessionNo/clientRequestId 轮询 GET resolve；绝不自动重放 attach。",
+        "该动作只创建 child plan；onboarding worker 仍会等待显式执行和验证。"
+    ]);
+    const jenkinsBindingAction = app.command("jenkins-binding")
+        .description("确认 Job Control Plane 产生的候选 Jenkins binding");
+    addExamples(jenkinsBindingAction.command("confirm <session-no>")
+        .requiredOption("--binding-id <id>", "会话事件返回的候选 binding ID")
+        .requiredOption("--expected-version <number>", "候选 binding 当前乐观锁版本")
+        .requiredOption("--idempotency-key <key>", "稳定 key；写响应未知时仅用于取证，不自动重发")
+        .option("--yes", "确认该 Jenkins job 与应用/tier 的绑定关系")
+        .action(async (sessionNo, options, command) => {
+        requireConfirmation(options.yes, "Confirming a Jenkins binding");
+        const key = idempotencyKey(options.idempotencyKey, "jenkins binding confirmation");
+        const input = parsedActionInput(OnboardingJenkinsBindingActionRequestSchema, {
+            bindingId: positiveInteger(options.bindingId, "binding-id"),
+            expectedVersion: nonNegativeInteger(options.expectedVersion, "expected-version", 0)
+        });
+        const onboarding = client();
+        const attempt = await executeOnboardingSessionMutation(onboarding, sessionNo, () => onboarding.confirmJenkinsBinding(sessionNo, input, key), (event) => hasJenkinsBindingRecoveryEvidence(event, input.bindingId));
+        if (!attempt.result) {
+            await output(command, recoveredMutationPayload(attempt.inspection, key), `${input.bindingId}\trecovered-from-status\t${attempt.inspection.session.state}`);
+            return;
+        }
+        const result = attempt.result;
+        await output(command, { ok: true, ...result, idempotencyKey: key }, `${result.binding.id}\t${result.binding.confirmationStatus}\tv${result.binding.version}\treplayed:${result.replayed}`);
+    }), [
+        "numa app jenkins-binding confirm <session-no> --binding-id 42 --expected-version 0 --idempotency-key confirm-code-index-binding --yes --json"
+    ], ["确认不会触发 scan 或 build；Job Control Plane 已独立验证配置和 inventory generation。"]);
+    const observerScopeAction = app.command("observer-scope")
+        .description("把服务绑定关联到 observer 可验证的精确 Flux/Kubernetes 坐标");
+    addExamples(observerScopeAction.command("configure <session-no>")
+        .requiredOption("--service-binding-id <id>", "会话锁定的 GitOps service binding ID")
+        .requiredOption("--kustomization-namespace <name>", "Flux Kustomization namespace")
+        .requiredOption("--kustomization-name <name>", "Flux Kustomization name")
+        .requiredOption("--helm-release-namespace <name>", "HelmRelease namespace")
+        .requiredOption("--helm-release-name <name>", "HelmRelease name")
+        .requiredOption("--workload-namespace <name>", "最终 workload namespace")
+        .requiredOption("--workload-kind <kind>", "最终 workload kind")
+        .requiredOption("--workload-name <name>", "最终 workload name")
+        .requiredOption("--expected-version <number>", "scope 当前版本；首次创建使用服务端事件给出的版本")
+        .requiredOption("--idempotency-key <key>", "稳定 key；写响应未知时仅用于取证，不自动重发")
+        .option("--yes", "确认精确运行态坐标")
+        .action(async (sessionNo, options, command) => {
+        requireConfirmation(options.yes, "Configuring an observer scope");
+        const key = idempotencyKey(options.idempotencyKey, "observer scope configuration");
+        const input = parsedActionInput(OnboardingObserverScopeActionRequestSchema, {
+            serviceBindingId: positiveInteger(options.serviceBindingId, "service-binding-id"),
+            kustomizationNamespace: stableActionText(options.kustomizationNamespace, "kustomization-namespace"),
+            kustomizationName: stableActionText(options.kustomizationName, "kustomization-name"),
+            helmReleaseNamespace: stableActionText(options.helmReleaseNamespace, "helm-release-namespace"),
+            helmReleaseName: stableActionText(options.helmReleaseName, "helm-release-name"),
+            workloadNamespace: stableActionText(options.workloadNamespace, "workload-namespace"),
+            workloadKind: stableActionText(options.workloadKind, "workload-kind", 160),
+            workloadName: stableActionText(options.workloadName, "workload-name"),
+            expectedVersion: nonNegativeInteger(options.expectedVersion, "expected-version", 0)
+        });
+        const onboarding = client();
+        const attempt = await executeOnboardingSessionMutation(onboarding, sessionNo, () => onboarding.configureObserverScope(sessionNo, input, key), hasObserverScopeRecoveryEvidence);
+        if (!attempt.result) {
+            await output(command, recoveredMutationPayload(attempt.inspection, key), `${String(attempt.inspection.execution.eventOutput.observerScopeNo)}\trecovered-from-status\t${attempt.inspection.session.state}`);
+            return;
+        }
+        const result = attempt.result;
+        await output(command, { ok: true, ...result, idempotencyKey: key }, `${result.scope.scopeNo}\t${result.scope.status}\t${result.scope.evidenceFreshness}\t${result.scope.lastDriftState ?? "-"}`);
+    }), [
+        "numa app observer-scope configure <session-no> --service-binding-id 17 --kustomization-namespace flux-system --kustomization-name prd --helm-release-namespace prd --helm-release-name code-index --workload-namespace prd --workload-kind Deployment --workload-name code-index --expected-version 0 --idempotency-key scope-code-index-prd --yes --json"
+    ], ["服务端强制 serviceBindingId 属于该会话；CLI 不允许任意 cluster/path/YAML。"]);
+    const firstBuildAction = app.command("first-build")
+        .description("在全部结构与运行证据就绪后，独立决定首次 Jenkins build");
+    addExamples(firstBuildAction.command("decide <session-no>")
+        .requiredOption("--decision <decision>", "trigger|defer")
+        .option("--branch <branch>", "TRIGGER 的分支；缺省由服务端锁定配置决定")
+        .option("--parameter <KEY=VALUE>", "非敏感构建参数，可重复", collectParameter, [])
+        .option("--approve-id <id>", "生产 TRIGGER 的审批记录 ID")
+        .option("--production-reason <reason>", "生产 TRIGGER 的受审原因（至少10字符）")
+        .requiredOption("--idempotency-key <key>", "稳定 key；写响应未知时仅用于取证，不自动重发")
+        .option("--yes", "确认记录决定；TRIGGER 会真正提交 Jenkins build")
+        .action(async (sessionNo, options, command) => {
+        requireConfirmation(options.yes, "Recording the first-build decision");
+        const decision = options.decision.trim().toUpperCase();
+        const input = parsedActionInput(OnboardingFirstBuildActionRequestSchema, {
+            decision,
+            branch: options.branch?.trim() || undefined,
+            parameters: buildParameters(options.parameter),
+            approveId: options.approveId?.trim() || undefined,
+            productionReason: options.productionReason?.trim() || undefined
+        });
+        const key = idempotencyKey(options.idempotencyKey, "first-build decision");
+        const onboarding = client();
+        const attempt = await executeOnboardingSessionMutation(onboarding, sessionNo, () => onboarding.decideFirstBuild(sessionNo, input, key), (event) => hasFirstBuildRecoveryEvidence(event, input));
+        if (!attempt.result) {
+            await output(command, recoveredMutationPayload(attempt.inspection, key), `${decision}\trecovered-from-status\t${attempt.inspection.session.state}`);
+            return;
+        }
+        const result = attempt.result;
+        await output(command, { ok: true, ...result, idempotencyKey: key }, result.build
+            ? `${result.decision}\t${result.build.requestId}\t${result.build.state}\treplayed:${result.replayed}`
+            : `${result.decision}\tno-build\treplayed:${result.replayed}`);
+    }), [
+        "numa app first-build decide <session-no> --decision defer --idempotency-key defer-code-index-first-build --yes --json",
+        "numa app first-build decide <session-no> --decision trigger --branch main --idempotency-key trigger-code-index-first-build --yes --json"
+    ], [
+        "DEFER 永不触发 build，且会话保持 WAITING_EXTERNAL。",
+        "生产 TRIGGER 仍由服务端强制 ops-admin 与受审生产依据；参数禁止凭据式 key/value。"
+    ]);
     addExamples(app.command("resume <session-no>")
         .description("让服务端重新检查外部等待条件，不在客户端推进状态")
         .action(async (sessionNo, _options, command) => {
@@ -664,11 +1103,16 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
             throw new OnboardingError("Session has no server plan hash; run onboarding preflight first.", "onboarding_plan_missing");
         }
         const key = idempotencyKey(options.idempotencyKey);
-        const task = await onboarding.apply(sessionNo, { planHash: before.planHash, idempotencyKey: key });
+        const attempt = await executeOnboardingSessionMutation(onboarding, sessionNo, () => onboarding.apply(sessionNo, { planHash: before.planHash, idempotencyKey: key }), (event) => hasOnboardingApplyRecoveryEvidence(event, before.planHash));
+        if (!attempt.result) {
+            await output(command, recoveredMutationPayload(attempt.inspection, key), `写响应未知，已从同一会话状态恢复:\n${executionText(attempt.inspection.session, attempt.inspection.events)}\nidempotency-key: ${key}`);
+            return;
+        }
+        const task = attempt.result;
         const session = await onboarding.getSession(sessionNo);
         await output(command, { ok: true, session, task, idempotencyKey: key, execution: onboardingExecutionView(session) }, `入驻执行已提交:\n${executionText(session)}\nidempotency-key: ${key}`);
     }), ["numa app apply 8d15ee89-43f0-4378-a7aa-51f09c5b42fc --idempotency-key app-order-20260819 --json"], [
-        "用于先 --plan 后 apply 的安全自动化，也用于响应不明时以同一 key 重放。"
+        "用于先 --plan 后的首次显式 apply；响应不明时只读 inspect/status，证据不足返回 onboarding_result_unknown，不要重发 apply。"
     ]);
     addExamples(app.command("inspect <session-no>")
         .description("查询会话；watch 从最后 event sequence 持续恢复")