fix: tighten code queue pr preflight contract

scripts/src/code-queue.ts

@@ -222,7 +222,7 @@ interface CodexPrPreflightOptions {
   full: boolean;
 }
 
-type CodeQueuePrPreflightFailureKind = "auth-missing" | "proxy-gap" | "git-remote-gap" | "target-stack-not-running";
+type CodeQueuePrPreflightFailureKind = "auth-missing" | "proxy-gap" | "git-remote-gap" | "control-plane-missing" | "target-stack-not-running";
 
 interface CodeQueuePrPreflightTransport {
   config?: UniDeskConfig | null;
@@ -2400,13 +2400,21 @@ function compactToolStatus(value: unknown): Record<string, unknown> {
 }
 
 function compactUniDeskGhCliStatus(value: unknown): Record<string, unknown> {
-  const cli = asRecord(value) ?? {};
+  const cli = asRecord(value);
+  const observed = cli !== null;
+  const ok = observed ? cli.ok === true : null;
   return {
-    ok: cli.ok ?? false,
-    path: cli.path ?? null,
-    present: cli.present ?? false,
+    ok,
+    observed,
+    path: observed ? cli.path ?? null : null,
+    present: observed ? cli.present ?? false : null,
     role: "repo-native REST GitHub CLI used by bun scripts/cli.ts gh",
     requiresSystemGhBinary: false,
+    unavailableReason: ok === true
+      ? null
+      : observed
+        ? "scripts-cli-missing"
+        : "runtime-preflight-did-not-report-unidesk-gh-cli",
   };
 }
 
@@ -2440,10 +2448,45 @@ function tokenCoverageStatus(credentials: Record<string, unknown>): Record<strin
   };
 }
 
+function authBrokerNeededStatus(tokenCoverage: Record<string, unknown>, systemGhBinary: Record<string, unknown>, unideskGhCli: Record<string, unknown>): Record<string, unknown> {
+  const missing = Array.isArray(tokenCoverage.missing) ? tokenCoverage.missing.map(String) : [];
+  const needed = tokenCoverage.ok !== true;
+  return {
+    ok: !needed,
+    source: needed ? "broker/auth-broker-needed" : tokenCoverage.source ?? "runner-env-token",
+    needed,
+    configured: false,
+    runnerDisposition: needed ? "infra-blocked" : "ready",
+    failureKind: needed ? "auth-missing" : null,
+    degradedReason: needed ? "auth-broker-needed" : null,
+    runnerEnvTokenRequiredWithoutBroker: true,
+    brokerCredentialSource: null,
+    valuesPrinted: false,
+    evidence: {
+      envTokenMissing: needed,
+      missing,
+      systemGhBinaryOk: systemGhBinary.ok === true,
+      systemGhBinaryRequiredForWrites: false,
+      unideskGhCliObserved: unideskGhCli.observed ?? false,
+      unideskGhCliOk: unideskGhCli.ok ?? null,
+      unideskGhCliRequiresSystemGhBinary: false,
+      systemGhMissingMisclassifiedAsUniDeskCliMissing: false,
+    },
+    next: needed
+      ? [
+        "inject GH_TOKEN or GITHUB_TOKEN into the Code Queue scheduler runtime secret",
+        "or configure the planned auth-broker so PR preflight can use a broker-held GitHub credential without exposing runner env tokens",
+      ]
+      : [],
+    reference: "docs/reference/auth-broker.md#post-v1githubpr-preflight",
+  };
+}
+
 function compactPrRuntimePreflight(preflight: Record<string, unknown>, options: CodexPrPreflightOptions): Record<string, unknown> {
   const pull = asRecord(preflight.pullRequestDelivery) ?? {};
   const tools = asRecord(pull.tools) ?? {};
   const unideskGhCli = compactUniDeskGhCliStatus(pull.unideskGhCli);
+  const systemGhBinary = compactToolStatus(tools.gh);
   const credentials = asRecord(pull.credentials) ?? {};
   const git = asRecord(pull.git) ?? {};
   const githubContext = asRecord(pull.githubContext) ?? {};
@@ -2455,12 +2498,28 @@ function compactPrRuntimePreflight(preflight: Record<string, unknown>, options:
   const limitations = Array.isArray(pull.limitations) ? pull.limitations.map(String) : [];
   const risks = Array.isArray(pull.risks) ? pull.risks.map(String) : [];
   const ok = preflight.ok === true && tokenCoverage.ok === true;
+  const failureKind = !tokenCoverage.ok
+    ? "auth-missing"
+    : limitations.some((item) => item.includes("git ls-remote") || item.includes("git push --dry-run failed"))
+      ? "git-remote-gap"
+      : !preflight.ok
+        ? "proxy-gap"
+        : null;
+  const degradedReason = failureKind === "auth-missing"
+    ? "GH_TOKEN/GITHUB_TOKEN missing"
+    : failureKind === "git-remote-gap"
+      ? "git remote probe failed"
+      : failureKind === "proxy-gap"
+        ? limitations.find((item) => item.includes("proxy") || item.includes("auth") || item.includes("egress") || item.includes("reachable")) ?? null
+        : null;
   const defaultPushDryRunRef = "refs/heads/probe/code-queue-pr-capability-dryrun";
   const pushDryRunRef = options.pushDryRunRef ?? defaultPushDryRunRef;
   const targetBranch = "master";
   const expectedHeadBranch = options.prCreateDryRunHead ?? (typeof git.branch === "string" && git.branch.length > 0 ? git.branch : "<head-branch>");
   const result: Record<string, unknown> = {
     ok,
+    failureKind,
+    degradedReason,
     checkedAt: preflight.checkedAt ?? pull.checkedAt ?? null,
     runner: {
       serviceId: "code-queue",
@@ -2470,6 +2529,7 @@ function compactPrRuntimePreflight(preflight: Record<string, unknown>, options:
       pid: preflight.pid ?? null,
     },
     tokenCoverage,
+    authBroker: authBrokerNeededStatus(tokenCoverage, systemGhBinary, unideskGhCli),
     prCapabilityContract: {
       targetBranch,
       tokenSource: tokenCoverage.source,
@@ -2510,8 +2570,8 @@ function compactPrRuntimePreflight(preflight: Record<string, unknown>, options:
     },
     tools: {
       git: compactToolStatus(tools.git),
-      gh: compactToolStatus(tools.gh),
-      systemGhBinary: compactToolStatus(tools.gh),
+      gh: systemGhBinary,
+      systemGhBinary,
       hub: compactToolStatus(tools.hub),
       jq: compactToolStatus(tools.jq),
       ssh: compactToolStatus(tools.ssh),
@@ -2595,7 +2655,7 @@ function queryRemoteMainServerPrPreflight(optionArgs: string[], config: UniDeskC
       return {
         ok: false,
         runnerDisposition: "infra-blocked",
-        failureKind: "proxy-gap",
+        failureKind: "control-plane-missing",
         degradedReason: "remote-control-plane-unreachable",
         message,
         controlPlane: {
@@ -2620,7 +2680,7 @@ function queryRemoteMainServerPrPreflight(optionArgs: string[], config: UniDeskC
   return {
     ok: false,
     runnerDisposition: "infra-blocked",
-    failureKind: "proxy-gap",
+    failureKind: "control-plane-missing",
     degradedReason: "remote-control-plane-unreachable",
     message,
     controlPlane: {
@@ -2696,7 +2756,7 @@ function codeQueuePrPreflight(optionArgs: string[] = [], transport: CodeQueuePrP
   }
   if (localRecord?.ok !== true) {
     if (options.remote && localTargetStackMissing) {
-      const failureKind: CodeQueuePrPreflightFailureKind = "proxy-gap";
+      const failureKind: CodeQueuePrPreflightFailureKind = "control-plane-missing";
       const degradedReason = "remote-control-plane-unreachable";
       return {
         ...(localRecord ?? {}),