@numa-tech/numa 1.13.2 → 1.13.4

package/dist/application-onboarding/commands.js

@@ -4,7 +4,7 @@ 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 { publicationScanSummary, scanProjectPublication } from "../publications/scanner.js";
+import { scanProjectPublication } from "../publications/scanner.js";
 import { OnboardingClient } from "./client.js";
 import { OnboardingError, sanitizeOnboardingOutput } from "./errors.js";
 import { OnboardingModeSchema, OnboardingEventOutputSchema, OnboardingFirstBuildActionRequestSchema, OnboardingJenkinsBindingActionRequestSchema, OnboardingObserverScopeActionRequestSchema, OnboardingPublicationPlanActionRequestSchema, OnboardingSessionStateSchema, OnboardingSpecSchema, ScmProviderSchema } from "./schemas.js";
@@ -189,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" : ""}`;
@@ -290,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)
@@ -315,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) => {
@@ -367,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,
@@ -375,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);
@@ -412,9 +614,18 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
 核心约束:
   所有客户端共享服务端 sessionNo、revision、planHash 和事件 sequence。
   --plan 只预检；--apply 才提交副作用，且服务端决定真实状态。
-  结果不明时用相同 idempotency-key 重试或 inspect/resume，禁止新建重复会话。
+  结果不明时先用 inspect/status/resolve 只读恢复；只有具体命令的服务端明确支持 replay 才可以原 key 重试，禁止新建重复会话。
 `);
     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 或名称搜索")
@@ -701,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",
@@ -719,6 +932,20 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
     ]);
     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 根目录")
@@ -729,12 +956,15 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         .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", 200);
+        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"),
@@ -745,19 +975,14 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
             commitMessage: options.commitMessage,
             files: source.requestFiles
         });
-        const result = await onboarding.attachPublicationPlan(sessionNo, input, key);
-        await output(command, {
-            ok: true,
-            session: result.session,
-            publicationPlan: result.publicationPlan,
-            replayed: result.replayed,
-            scan: publicationScanSummary(source),
-            idempotencyKey: key
-        }, `${result.publicationPlan.planNo}\t${result.publicationPlan.state}\t${result.publicationPlan.planHash}\treplayed:${result.replayed}`);
+        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；输出不含 sourceRoot、contentBase64 或 SCM credential。",
+        "只读取 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")
@@ -765,7 +990,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
     addExamples(jenkinsBindingAction.command("confirm <session-no>")
         .requiredOption("--binding-id <id>", "会话事件返回的候选 binding ID")
         .requiredOption("--expected-version <number>", "候选 binding 当前乐观锁版本")
-        .requiredOption("--idempotency-key <key>", "结果未知时复用同一 key")
+        .requiredOption("--idempotency-key <key>", "稳定 key；写响应未知时仅用于取证，不自动重发")
         .option("--yes", "确认该 Jenkins job 与应用/tier 的绑定关系")
         .action(async (sessionNo, options, command) => {
         requireConfirmation(options.yes, "Confirming a Jenkins binding");
@@ -774,7 +999,13 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
             bindingId: positiveInteger(options.bindingId, "binding-id"),
             expectedVersion: nonNegativeInteger(options.expectedVersion, "expected-version", 0)
         });
-        const result = await client().confirmJenkinsBinding(sessionNo, input, key);
+        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"
@@ -791,7 +1022,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         .requiredOption("--workload-kind <kind>", "最终 workload kind")
         .requiredOption("--workload-name <name>", "最终 workload name")
         .requiredOption("--expected-version <number>", "scope 当前版本；首次创建使用服务端事件给出的版本")
-        .requiredOption("--idempotency-key <key>", "结果未知时复用同一 key")
+        .requiredOption("--idempotency-key <key>", "稳定 key；写响应未知时仅用于取证，不自动重发")
         .option("--yes", "确认精确运行态坐标")
         .action(async (sessionNo, options, command) => {
         requireConfirmation(options.yes, "Configuring an observer scope");
@@ -807,7 +1038,13 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
             workloadName: stableActionText(options.workloadName, "workload-name"),
             expectedVersion: nonNegativeInteger(options.expectedVersion, "expected-version", 0)
         });
-        const result = await client().configureObserverScope(sessionNo, input, key);
+        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"
@@ -820,7 +1057,7 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
         .option("--parameter <KEY=VALUE>", "非敏感构建参数，可重复", collectParameter, [])
         .option("--approve-id <id>", "生产 TRIGGER 的审批记录 ID")
         .option("--production-reason <reason>", "生产 TRIGGER 的受审原因（至少10字符）")
-        .requiredOption("--idempotency-key <key>", "结果未知时复用同一 key")
+        .requiredOption("--idempotency-key <key>", "稳定 key；写响应未知时仅用于取证，不自动重发")
         .option("--yes", "确认记录决定；TRIGGER 会真正提交 Jenkins build")
         .action(async (sessionNo, options, command) => {
         requireConfirmation(options.yes, "Recording the first-build decision");
@@ -833,7 +1070,13 @@ export function registerApplicationOnboardingCommands(program, dependencies = {}
             productionReason: options.productionReason?.trim() || undefined
         });
         const key = idempotencyKey(options.idempotencyKey, "first-build decision");
-        const result = await client().decideFirstBuild(sessionNo, input, key);
+        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}`);
@@ -860,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 持续恢复")