fix: improve egress and job diagnostics (#969)

Co-authored-by: Codex <codex@noreply.local>

scripts/src/docker.ts

@@ -1,3 +1,5 @@
+// SPEC: PJ2026-01060509 出站诊断 draft-2026-06-26-p8-egress-job-friction.
+// Main-server Docker lifecycle helpers with bounded status probes and job summaries.
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { commandOk, runCommand, tailFile } from "./command";
@@ -608,7 +610,7 @@ export function dockerContainers(config: UniDeskConfig): ContainerStatus[] {
     "label=com.docker.compose.oneoff=False",
     "--format",
     "{{json .}}",
-  ], repoRoot);
+  ], repoRoot, { timeoutMs: 5000 });
   if (result.exitCode !== 0 || result.stdout.trim().length === 0) return [];
   return result.stdout
     .split("\n")
@@ -643,9 +645,9 @@ function dockerExecJson(container: string, path: string): unknown {
     "export url",
     "bun -e 'const url=process.env.url; fetch(url).then(async r=>{const text=await r.text(); console.log(JSON.stringify({ok:r.ok,status:r.status,body:text?JSON.parse(text):null})); process.exit(r.ok?0:1);}).catch(e=>{console.error(e); process.exit(1)})'",
   ].join("\n");
-  const result = runCommand(["docker", "exec", container, "sh", "-lc", script], repoRoot);
+  const result = runCommand(["docker", "exec", container, "sh", "-lc", script], repoRoot, { timeoutMs: 5000 });
   if (result.exitCode !== 0) {
-    return { ok: false, exitCode: result.exitCode, stdout: result.stdout.slice(-1200), stderr: result.stderr.slice(-1200) };
+    return { ok: false, exitCode: result.exitCode, timedOut: result.timedOut, signal: result.signal, stdout: result.stdout.slice(-1200), stderr: result.stderr.slice(-1200) };
   }
   try {
     return JSON.parse(result.stdout.trim()) as unknown;
@@ -655,8 +657,8 @@ function dockerExecJson(container: string, path: string): unknown {
 }
 
 function dockerExec(config: UniDeskConfig, container: string, command: string[]): unknown {
-  const result = runCommand(["docker", "exec", container, ...command], repoRoot);
-  return { ok: result.exitCode === 0, exitCode: result.exitCode, stdout: result.stdout.slice(-1200), stderr: result.stderr.slice(-1200) };
+  const result = runCommand(["docker", "exec", container, ...command], repoRoot, { timeoutMs: 5000 });
+  return { ok: result.exitCode === 0, exitCode: result.exitCode, timedOut: result.timedOut, signal: result.signal, stdout: result.stdout.slice(-1200), stderr: result.stderr.slice(-1200) };
 }
 
 export async function stackStatus(config: UniDeskConfig): Promise<unknown> {

scripts/src/help.ts

@@ -1,3 +1,5 @@
+// SPEC: PJ2026-01060509 出站诊断 draft-2026-06-26-p8-egress-job-friction.
+// Static CLI help for job aliases and server lifecycle progressive disclosure.
 import { ghHelp, ghScopedHelp } from "./gh";
 import { authBrokerHelp } from "./auth-broker";
 import { platformDbHelp } from "./platform-db";
@@ -86,8 +88,8 @@ export function rootHelp(): unknown {
       { command: "codex steer-confirm <taskId> --steer-id <id> [--raw]", description: "Read-only lookup for a steerId in task trace so deliveryUnconfirmed can be resolved without resending the corrective prompt." },
       { command: "codex interrupt|cancel <taskId>", description: "Request interrupt for a running Code Queue task, or cancel a queued/retry_wait task, through the same private proxy." },
       { command: "codex queues [--full|--all] [--limit N] [--page N|--offset N]", description: "Read legacy Code Queue archive summaries. Legacy queue create/merge and move are frozen; use agentrun create/apply/get/cancel for new work." },
-      { command: "job list [--limit N] [--include-command]", description: "List async jobs from .state/jobs with a bounded default page and progress summaries." },
-      { command: "job status <jobId|latest> [--tail-bytes N]", description: "Show job state with a structured progress summary and bounded stdout/stderr tails." },
+      { command: "job|jobs list [--limit N] [--include-command]", description: "List async jobs from .state/jobs with a bounded default page and progress summaries." },
+      { command: "job status|get|read <jobId|latest> [--tail-bytes N]", description: "Show job state with a structured progress summary and bounded stdout/stderr tails." },
       { command: "job cancel <jobId>", description: "Cancel a queued/running async job through the .state/jobs control entry and keep a terminal canceled record." },
       { command: "debug health", description: "Probe internal core, nodes, system/Docker status, frontend, provider ingress, and public boundary." },
       { command: "debug ssh-pool <providerId>", description: "Show bounded host.ssh.tcp-pool labels for one provider, including ready/claimed/desired/lastError." },
@@ -503,14 +505,15 @@ function codexHelp(): unknown {
 
 function jobHelp(): unknown {
   return {
-    command: "job list|status|cancel",
+    command: "job|jobs list|status|get|read|cancel",
     output: "json",
     usage: [
       "bun scripts/cli.ts job list [--limit N] [--include-command]",
       "bun scripts/cli.ts job status <jobId|latest> [--tail-bytes N]",
+      "bun scripts/cli.ts jobs get <jobId|latest> [--tail-bytes N]",
       "bun scripts/cli.ts job cancel <jobId>",
     ],
-    description: "Inspect or cancel fire-and-forget job state from .state/jobs with structured progress summaries and bounded log tails.",
+    description: "Inspect or cancel fire-and-forget job state from .state/jobs with structured progress summaries and bounded log tails. `jobs get/read` are compatibility aliases for `job status`; server lifecycle commands return this drill-down by default and reserve full JSON for --full/--raw.",
   };
 }
 

scripts/src/jobs.ts

@@ -1,3 +1,5 @@
+// SPEC: PJ2026-01060509 出站诊断 draft-2026-06-26-p8-egress-job-friction.
+// Async job state, summaries, and lifecycle drill-down rendering for UniDesk CLI.
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -270,6 +272,50 @@ export function renderJobStatusSummary(job: ReturnType<typeof jobWithTail>): Ren
   };
 }
 
+export function renderJobLaunchSummary(command: string, result: unknown): RenderedCliResult | null {
+  if (typeof result !== "object" || result === null || !("job" in result)) return null;
+  const record = result as Record<string, unknown>;
+  const job = record.job as Partial<JobRecord> | undefined;
+  if (typeof job !== "object" || job === null || typeof job.id !== "string") return null;
+  const service = typeof record.service === "string" ? record.service : "-";
+  const runtimeEnv = typeof record.runtimeEnv === "object" && record.runtimeEnv !== null ? record.runtimeEnv as Record<string, unknown> : {};
+  const stdoutFile = typeof job.stdoutFile === "string" ? job.stdoutFile : "-";
+  const stderrFile = typeof job.stderrFile === "string" ? job.stderrFile : "-";
+  const statusCommand = `bun scripts/cli.ts job status ${job.id} --tail-bytes 12000`;
+  const fullCommand = command.includes("--full") || command.includes("--raw") ? null : `bun scripts/cli.ts ${command} --full`;
+  const lines = [
+    "ASYNC_JOB",
+    jobStatusTable(
+      ["JOB", "NAME", "STATUS", "SERVICE", "RUNNER", "CREATED"],
+      [[job.id, job.name ?? "-", job.status ?? "-", service, job.runner ?? "-", job.createdAt ?? "-"]],
+    ),
+    "",
+    jobStatusTable(
+      ["STREAM", "PATH"],
+      [
+        ["stdout", stdoutFile],
+        ["stderr", stderrFile],
+        ["runtimeEnv", typeof runtimeEnv.envFile === "string" ? runtimeEnv.envFile : "-"],
+        ["logDir", typeof runtimeEnv.logDir === "string" ? runtimeEnv.logDir : "-"],
+      ],
+    ),
+    "",
+    "NEXT",
+    `  status: ${statusCommand}`,
+    "  latest: bun scripts/cli.ts job status latest --tail-bytes 12000",
+    "  list: bun scripts/cli.ts job list --limit 20",
+    "  logs: bun scripts/cli.ts server logs --tail-bytes 3000",
+    "  server: bun scripts/cli.ts server status",
+    fullCommand === null ? null : `  full: ${fullCommand}`,
+  ].filter((line): line is string => line !== null);
+  return {
+    ok: job.status !== "failed",
+    command,
+    contentType: "text/plain",
+    renderedText: `${lines.join("\n")}\n`,
+  };
+}
+
 function summarizeJobProgress(job: JobRecord, maxBytes = 96_000, tails?: { stdoutTail: string; stderrTail: string }): JobProgressSummary {
   const nowMs = Date.now();
   const knownWorkflow = job.name === "hwlab_g14_v02_trigger_current";