fix(code-queue): add runner skills sync contract

scripts/code-queue-runner-skills-contract-test.ts

@@ -1,5 +1,7 @@
 import { readFileSync } from "node:fs";
-import { collectSkillAvailability } from "../src/components/microservices/code-queue/src/skill-availability";
+import { collectSkillAvailability, collectSkillSyncPreflight } from "../src/components/microservices/code-queue/src/skill-availability";
+import { codexPrPreflightQueryForTest } from "./src/code-queue";
+import { summarizeMicroserviceObservation } from "./src/microservices";
 
 type JsonRecord = Record<string, unknown>;
 
@@ -21,6 +23,9 @@ const devManifest = readFileSync("src/components/microservices/k3sctl-adapter/k3
 const runtimePreflight = readFileSync("src/components/microservices/code-queue/src/runtime-preflight.ts", "utf8");
 const indexSource = readFileSync("src/components/microservices/code-queue/src/index.ts", "utf8");
 const skillModule = readFileSync("src/components/microservices/code-queue/src/skill-availability.ts", "utf8");
+const codeQueueCli = readFileSync("scripts/src/code-queue.ts", "utf8");
+const microserviceCli = readFileSync("scripts/src/microservices.ts", "utf8");
+const helpSource = readFileSync("scripts/src/help.ts", "utf8");
 const promptSource = readFileSync("src/components/microservices/code-queue/src/prompts.ts", "utf8");
 const docsReference = readFileSync("docs/reference/code-queue-supervision.md", "utf8");
 const forbiddenPathLiteral = [".ag", "nets/skills"].join("");
@@ -69,17 +74,142 @@ assertCondition(missing.blocker === "skills-target-missing", "missing target sho
 assertCondition(missing.missingSkills.includes("docs-spec") && missing.missingSkills.includes("cli-spec"), "missing target should list required missing skills", missing);
 assertCondition(missing.valuesPrinted === false, "missing report must also declare valuesPrinted=false");
 
+const syncDryRun = collectSkillSyncPreflight({
+  source: "/home/ubuntu/.agents/skills",
+  target: "/path/that/does/not/exist/for-code-queue-skills-test",
+  requiredSkills: ["docs-spec", "cli-spec"],
+});
+assertCondition(syncDryRun.dryRun === true && syncDryRun.mutation === false, "skills sync contract must be dry-run and non-mutating", syncDryRun);
+assertCondition(syncDryRun.syncMode === "hostPath-read-only-projection", "skills sync must describe the hostPath projection lifecycle", syncDryRun);
+assertCondition(syncDryRun.source.path === "/home/ubuntu/.agents/skills", "skills sync must expose source", syncDryRun.source);
+assertCondition(syncDryRun.target.path === "/path/that/does/not/exist/for-code-queue-skills-test", "skills sync must expose target", syncDryRun.target);
+assertCondition(syncDryRun.expected.source === "/home/ubuntu/.agents/skills", "skills sync must expose stable expected source", syncDryRun.expected);
+assertCondition(syncDryRun.expected.target === "/root/.agents/skills", "skills sync must expose stable expected target", syncDryRun.expected);
+assertCondition(syncDryRun.expected.env === "UNIDESK_SKILLS_PATH" && syncDryRun.expected.envValue === "/root/.agents/skills", "skills sync must expose env contract", syncDryRun.expected);
+assertCondition(syncDryRun.counts.requiredSkills === 2, "skills sync must expose required skill count", syncDryRun.counts);
+assertCondition(syncDryRun.counts.targetSkills === 0 && syncDryRun.counts.missingTargetSkills === 2, "skills sync must expose target counts and missing count", syncDryRun.counts);
+assertCondition(syncDryRun.missing.targetSkills.includes("docs-spec") && syncDryRun.missing.targetSkills.includes("cli-spec"), "skills sync must expose missing target skills", syncDryRun.missing);
+assertCondition(syncDryRun.blocker === "unapproved-target", "arbitrary target paths must be blocked before silent copying", syncDryRun);
+assertCondition(syncDryRun.plannedActions.copy === false && syncDryRun.plannedActions.copyFromArbitraryPath === false, "skills sync dry-run must not plan arbitrary copy", syncDryRun.plannedActions);
+assertCondition(syncDryRun.plannedActions.restartRequired === false && syncDryRun.plannedActions.readsSecrets === false, "skills sync dry-run must not require restart or read secrets", syncDryRun.plannedActions);
+assertCondition(Array.isArray(syncDryRun.instructions) && syncDryRun.instructions.some((item) => item.includes("read-only hostPath projection")), "skills sync must include lifecycle instructions", syncDryRun.instructions);
+assertCondition(syncDryRun.valuesPrinted === false, "skills sync must declare valuesPrinted=false", syncDryRun);
+assertCondition(!JSON.stringify(syncDryRun).includes(forbiddenPathLiteral), "skills sync report must not propagate misspelled path literal");
+
+const missingTargetSync = collectSkillSyncPreflight({ target: "/path/that/does/not/exist/for-code-queue-skills-test" });
+assertCondition(missingTargetSync.blocker === "unapproved-target", "non-default target must be rejected as unapproved", missingTargetSync);
+
 assertCondition(runtimePreflight.includes("skills: SkillAvailabilityReport"), "runtime preflight type must include skills report");
+assertCondition(runtimePreflight.includes("skillsSync: SkillSyncPreflightReport"), "runtime preflight type must include skills sync report");
 assertCondition(runtimePreflight.includes("collectSkillAvailability"), "runtime preflight must collect skills availability");
-assertCondition(runtimePreflight.includes("skills.ok && ports.codex.ok"), "runtime preflight ok must depend on skills.ok");
+assertCondition(runtimePreflight.includes("collectSkillSyncPreflight"), "runtime preflight must collect skills sync preflight");
+assertCondition(runtimePreflight.includes("skills.ok && skillsSync.ok && ports.codex.ok"), "runtime preflight ok must depend on skills and skillsSync");
 assertCondition(indexSource.includes("const skillsReady = skills.ok === true"), "dev-ready must gate on structured skills ok");
+assertCondition(indexSource.includes("collectSkillsSyncPreflight"), "runtime index must expose skills sync preflight");
+assertCondition(indexSource.includes("/api/skills-sync"), "runtime must expose a dry-run skills sync endpoint");
+assertCondition(indexSource.includes("pass dryRun=1"), "skills sync endpoint must reject non-dry-run calls");
+assertCondition(codeQueueCli.includes("failureKind: \"dry-run-required\""), "codex skills-sync CLI must require --dry-run with structured output");
+assertCondition(codeQueueCli.includes("codex skills-sync is dry-run only; pass --dry-run"), "codex skills-sync CLI must explain the dry-run requirement");
+assertCondition(codeQueueCli.includes("Code Queue skills sync dry-run could not reach the control plane"), "codex skills-sync CLI must return structured control-plane failure output");
+assertCondition(codeQueueCli.includes("compact-skills-sync-control-plane-failure"), "codex skills-sync CLI must keep control-plane failure output compact");
+assertCondition(codeQueueCli.includes("compactSkillsSyncStatus"), "codex CLI must compact skills sync output");
+assertCondition(codeQueueCli.includes("runner-skills-blocker"), "codex preflight must classify skill lifecycle blockers");
+assertCondition(microserviceCli.includes("compactSkillSync"), "microservice health summary must compact skills sync output");
+assertCondition(helpSource.includes("codex skills-sync --dry-run"), "CLI help must document the skills sync dry-run command");
+assertCondition(docsReference.includes("codex skills-sync --dry-run"), "reference docs must document the skills sync dry-run command");
+
+const preflightSummary = asRecord(codexPrPreflightQueryForTest(["--remote"], {
+  config: null,
+  coreFetch: () => ({
+    ok: true,
+    status: 200,
+    body: {
+      runtimePreflight: {
+        ok: false,
+        checkedAt: "2026-05-23T00:00:00.000Z",
+        cwd: "/workspace/unidesk",
+        pid: 601,
+        skills: missing,
+        skillsSync: syncDryRun,
+        ports: {},
+        pullRequestDelivery: {
+          ok: true,
+          checkedAt: "2026-05-23T00:00:00.000Z",
+          tools: {},
+          unideskGhCli: { ok: true, path: "/workspace/unidesk/scripts/cli.ts", present: true },
+          authBroker: { ok: true, configured: true, source: "auth-broker" },
+          credentials: {
+            ghTokenPresent: false,
+            githubTokenPresent: false,
+            ghHostsConfigPresent: false,
+            gitCredentialsPresent: false,
+          },
+          git: {
+            insideWorktree: true,
+            branch: "code-queue/issue-68-runner-skills-lifecycle",
+            head: "abc1234",
+            originMaster: "def5678",
+            remoteOrigin: "git@github.com:pikasTech/unidesk.git",
+            home: "/root",
+            homeWritable: true,
+            knownHostsPresent: true,
+            privateKeyPresent: true,
+          },
+          githubContext: {
+            host: "github.com",
+            apiBaseUrl: "https://api.github.com",
+            repo: "pikasTech/unidesk",
+            issueProbeNumber: 68,
+          },
+          egress: { proxy: {} },
+          remote: null,
+          limitations: [],
+          risks: [],
+        },
+      },
+    },
+  }),
+}), "preflight summary");
+const preflight = asRecord(preflightSummary.preflight, "preflight");
+const preflightSkills = asRecord(preflight.skills, "preflight.skills");
+const preflightSkillsSync = asRecord(preflight.skillsSync, "preflight.skillsSync");
+assertCondition(preflightSummary.failureKind === "runner-skills-blocker", "compact preflight should classify missing skills as runner-skills-blocker", preflightSummary);
+assertCondition(preflightSummary.degradedReason === "unapproved-target", "compact preflight degraded reason should use the skills sync blocker first", preflightSummary);
+assertCondition(preflightSkills.target === "/path/that/does/not/exist/for-code-queue-skills-test", "compact preflight must show skills target", preflightSkills);
+assertCondition(preflightSkillsSync.dryRun === true && preflightSkillsSync.mutation === false, "compact preflight must show non-mutating skills sync dry-run", preflightSkillsSync);
+assertCondition(asRecord(preflightSkillsSync.counts, "preflight.skillsSync.counts").missingTargetSkills === 2, "compact preflight must show missing target count", preflightSkillsSync);
+assertCondition(asRecord(preflightSkillsSync.plannedActions, "preflight.skillsSync.plannedActions").copy === false, "compact preflight must show no copy action", preflightSkillsSync);
+assertCondition(preflightSkillsSync.valuesPrinted === false, "compact preflight skills sync must declare valuesPrinted=false", preflightSkillsSync);
+assertCondition(!JSON.stringify(preflightSkillsSync).includes(forbiddenPathLiteral), "compact preflight must not propagate misspelled path literal");
+
+const healthSummary = asRecord(summarizeMicroserviceObservation("health", "code-queue", {
+  ok: true,
+  status: 200,
+  body: {
+    ok: false,
+    service: "code-queue",
+    skills: missing,
+    skillsSync: syncDryRun,
+  },
+}, []), "microservice health summary");
+const microservice = asRecord(healthSummary.microservice, "microservice");
+const healthCompact = asRecord(microservice.summary, "microservice.summary");
+const healthSkills = asRecord(healthCompact.skills, "microservice.summary.skills");
+const healthSkillsSync = asRecord(healthCompact.skillsSync, "microservice.summary.skillsSync");
+assertCondition(healthSkills.target === "/path/that/does/not/exist/for-code-queue-skills-test", "compact health must show skills target", healthSkills);
+assertCondition(healthSkillsSync.dryRun === true && healthSkillsSync.mutation === false, "compact health must show dry-run skills sync", healthSkillsSync);
+assertCondition(asRecord(healthSkillsSync.counts, "microservice.summary.skillsSync.counts").missingTargetSkills === 2, "compact health must show missing target count", healthSkillsSync);
+assertCondition(asRecord(healthSkillsSync.plannedActions, "microservice.summary.skillsSync.plannedActions").copyFromArbitraryPath === false, "compact health must show arbitrary copy is blocked", healthSkillsSync);
+assertCondition(!JSON.stringify(healthSkillsSync).includes(forbiddenPathLiteral), "compact health must not propagate misspelled path literal");
 
 process.stdout.write(`${JSON.stringify({
   ok: true,
   checks: [
     "production Code Queue mounts /home/ubuntu/.agents/skills read-only at /root/.agents/skills",
     "skill availability report exposes source, target, requiredSkills, missingSkills, degraded/blocker and valuesPrinted=false",
-    "runtime-preflight and dev-ready use the same structured skill report",
+    "skills sync dry-run reports source, target, counts, missing skills, permission failures, instructions and no-copy actions",
+    "runtime-preflight, dev-ready, health and PR preflight use the same structured skill and sync reports",
+    "default health/preflight summaries expose bounded skills lifecycle evidence and --full expansion",
     "misspelled skills paths are only surfaced as a forbidden diagnostic risk",
   ],
   observedRunner: {
@@ -87,6 +217,8 @@ process.stdout.write(`${JSON.stringify({
     target: available.target,
     ok: available.ok,
     missingSkills: available.missingSkills,
+    syncDryRunOk: syncDryRun.ok,
+    syncDryRunBlocker: syncDryRun.blocker,
     valuesPrinted: available.valuesPrinted,
   },
 }, null, 2)}\n`);

scripts/src/code-queue.ts

@@ -305,7 +305,12 @@ interface CodexPrPreflightOptions {
   full: boolean;
 }
 
-type CodeQueuePrPreflightFailureKind = "auth-missing" | "proxy-gap" | "git-remote-gap" | "control-plane-missing" | "target-stack-not-running";
+interface CodexSkillsSyncOptions {
+  dryRun: boolean;
+  full: boolean;
+}
+
+type CodeQueuePrPreflightFailureKind = "auth-missing" | "runner-skills-blocker" | "proxy-gap" | "git-remote-gap" | "control-plane-missing" | "target-stack-not-running";
 type CodeQueueObservationGapKind = "runner-local-observation-gap" | "control-plane-observation-gap" | null;
 
 interface CodeQueuePrPreflightTransport {
@@ -1742,6 +1747,17 @@ function parsePrPreflightOptions(args: string[]): CodexPrPreflightOptions {
   };
 }
 
+function parseSkillsSyncOptions(args: string[]): CodexSkillsSyncOptions {
+  assertKnownOptions(args, {
+    flags: ["--dry-run", "--dryRun", "--full", "--raw"],
+  }, "codex skills-sync");
+  const dryRun = hasFlag(args, "--dry-run") || hasFlag(args, "--dryRun");
+  return {
+    dryRun,
+    full: hasFlag(args, "--full") || hasFlag(args, "--raw"),
+  };
+}
+
 function parseJudgeOptions(args: string[]): CodexJudgeOptions {
   assertKnownOptions(args, {
     flags: ["--dry-run", "--no-call", "--include-prompt"],
@@ -3072,6 +3088,56 @@ function compactSkillsStatus(value: unknown): Record<string, unknown> | null {
   };
 }
 
+function compactSkillPathReport(value: unknown): Record<string, unknown> | null {
+  const record = asRecord(value);
+  if (record === null) return null;
+  return {
+    path: record.path ?? null,
+    approved: record.approved ?? false,
+    exists: record.exists ?? false,
+    directory: record.directory ?? false,
+    readable: record.readable ?? false,
+    writable: record.writable ?? false,
+    readonly: record.readonly ?? false,
+    mountPoint: record.mountPoint ?? null,
+    skillCount: record.skillCount ?? 0,
+    requiredSkills: Array.isArray(record.requiredSkills) ? record.requiredSkills.map(String) : [],
+    missingSkills: Array.isArray(record.missingSkills) ? record.missingSkills.map(String) : [],
+    error: record.error ?? null,
+  };
+}
+
+function compactSkillsSyncStatus(value: unknown, full = false): Record<string, unknown> | null {
+  const record = asRecord(value);
+  if (record === null) return null;
+  const source = compactSkillPathReport(record.source);
+  const target = compactSkillPathReport(record.target);
+  const compact: Record<string, unknown> = {
+    ok: record.ok ?? false,
+    degraded: record.degraded ?? true,
+    blocker: record.blocker ?? null,
+    checkedAt: record.checkedAt ?? null,
+    mode: record.mode ?? "dry-run",
+    dryRun: record.dryRun ?? true,
+    mutation: record.mutation ?? false,
+    syncMode: record.syncMode ?? null,
+    source,
+    target,
+    expected: record.expected ?? null,
+    counts: record.counts ?? null,
+    missing: record.missing ?? null,
+    permissionFailures: Array.isArray(record.permissionFailures) ? record.permissionFailures.slice(0, full ? undefined : 4) : [],
+    permissionFailureCount: Array.isArray(record.permissionFailures) ? record.permissionFailures.length : 0,
+    pathSpelling: record.pathSpelling ?? null,
+    plannedActions: record.plannedActions ?? null,
+    instructions: Array.isArray(record.instructions) ? record.instructions.map(String).slice(0, full ? undefined : 4) : [],
+    commands: record.commands ?? null,
+    valuesPrinted: record.valuesPrinted ?? false,
+  };
+  if (full) compact.rawSkillsSync = record;
+  return compact;
+}
+
 function codeQueueDevReady(): unknown {
   const response = unwrapCodexResponse(coreInternalFetch(codeQueueProxyPath("/api/dev-ready")));
   const devReady = asRecord(response.body.devReady) ?? {};
@@ -3085,10 +3151,101 @@ function codeQueueDevReady(): unknown {
       codexConfig: devReady.codexConfig ?? null,
       ssh: devReady.ssh ?? null,
       skills: compactSkillsStatus(devReady.skills),
+      skillsSync: compactSkillsSyncStatus(devReady.skillsSync),
     },
     commands: {
       health: "bun scripts/cli.ts codex dev-ready",
       raw: "bun scripts/cli.ts microservice proxy code-queue /api/dev-ready --raw",
+      skillsSync: "bun scripts/cli.ts codex skills-sync --dry-run",
+    },
+  };
+}
+
+function codeQueueSkillsSync(args: string[]): unknown {
+  const options = parseSkillsSyncOptions(args);
+  if (!options.dryRun) {
+    return {
+      ok: false,
+      failureKind: "dry-run-required",
+      runnerDisposition: "business-failed",
+      message: "codex skills-sync is dry-run only; pass --dry-run",
+      mutation: false,
+      commands: {
+        dryRun: "bun scripts/cli.ts codex skills-sync --dry-run",
+        full: "bun scripts/cli.ts codex skills-sync --dry-run --full",
+      },
+    };
+  }
+  const rawResponse = coreInternalFetch(codeQueueProxyPath("/api/skills-sync?dryRun=1"));
+  const response = asRecord(rawResponse);
+  if (response?.ok !== true) {
+    const targetStack = asRecord(response?.targetStack);
+    const observed = asRecord(response?.observed);
+    const missingContainers = Array.isArray(targetStack?.missingContainers) ? targetStack.missingContainers.map(String) : [];
+    const relatedContainers = Array.isArray(targetStack?.relatedContainers) ? targetStack.relatedContainers : [];
+    return {
+      ok: false,
+      dryRun: true,
+      mutation: false,
+      runnerDisposition: response?.runnerDisposition ?? "infra-blocked",
+      failureKind: response?.failureKind ?? "control-plane-missing",
+      degradedReason: response?.degradedReason ?? "backend-core-proxy-unavailable",
+      message: response?.message ?? response?.stderrTail ?? response?.stdoutTail ?? "Code Queue skills sync dry-run could not reach the control plane",
+      controlPlane: {
+        mode: "local-backend-core",
+        localBackendCoreMissing: response?.failureKind === "target-stack-not-running",
+        schedulerStateChanged: false,
+        liveRunnerHostPathMutated: false,
+      },
+      targetStackSummary: targetStack === null ? null : {
+        missingContainers,
+        missingContainerCount: missingContainers.length,
+        relatedContainerCount: relatedContainers.length,
+        verifyOnlyObserved: targetStack.verifyOnlyObserved ?? false,
+      },
+      observed: observed === null ? null : {
+        commandExitCode: observed.commandExitCode ?? null,
+        stderrTail: typeof observed.stderrTail === "string" ? textView(observed.stderrTail, false, 600) : null,
+      },
+      outputPolicy: {
+        default: "compact-skills-sync-control-plane-failure",
+        unrelatedDiagnosticsOmitted: true,
+        full: "use microservice health/proxy commands only when control-plane diagnostics are needed",
+      },
+      commands: {
+        retry: "bun scripts/cli.ts codex skills-sync --dry-run",
+        full: "bun scripts/cli.ts codex skills-sync --dry-run --full",
+        health: "bun scripts/cli.ts microservice health code-queue",
+        rawProxy: "bun scripts/cli.ts microservice proxy code-queue /api/skills-sync?dryRun=1 --raw --full",
+      },
+    };
+  }
+  const body = asRecord(response.body);
+  if (body?.ok !== true) {
+    return {
+      ok: false,
+      dryRun: true,
+      mutation: false,
+      runnerDisposition: "infra-blocked",
+      failureKind: "runtime-skills-sync-missing",
+      degradedReason: "runtime-skills-sync-response-invalid",
+      message: "Code Queue skills sync dry-run response did not include a valid body",
+      upstream: { ok: response.ok, status: response.status ?? null },
+      bodyPreview: body,
+      commands: {
+        retry: "bun scripts/cli.ts codex skills-sync --dry-run",
+        rawProxy: "bun scripts/cli.ts microservice proxy code-queue /api/skills-sync?dryRun=1 --raw --full",
+      },
+    };
+  }
+  const skillsSync = asRecord(body.skillsSync);
+  return {
+    upstream: { ok: response.ok, status: response.status ?? null },
+    skillsSync: compactSkillsSyncStatus(skillsSync, options.full),
+    outputPolicy: {
+      default: "compact-skills-sync-dry-run",
+      full: "bun scripts/cli.ts codex skills-sync --dry-run --full",
+      mutation: false,
     },
   };
 }
@@ -3457,6 +3614,8 @@ function maybeFullPrPreflightObservations(options: CodexPrPreflightOptions, loca
 
 function compactPrRuntimePreflight(preflight: Record<string, unknown>, options: CodexPrPreflightOptions): Record<string, unknown> {
   const pull = asRecord(preflight.pullRequestDelivery) ?? {};
+  const skills = compactSkillsStatus(preflight.skills);
+  const skillsSync = compactSkillsSyncStatus(preflight.skillsSync, options.full);
   const tools = asRecord(pull.tools) ?? {};
   const unideskGhCli = compactUniDeskGhCliStatus(pull.unideskGhCli);
   const authBrokerRuntime = compactAuthBrokerRuntimeStatus(pull.authBroker);
@@ -3472,20 +3631,26 @@ 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 skillsBlocked = skills !== null && skills.ok !== true;
+  const skillsSyncBlocked = skillsSync !== null && skillsSync.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;
+    : skillsBlocked || skillsSyncBlocked
+      ? "runner-skills-blocker"
+      : 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"
     ? "auth-broker-needed"
-    : 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;
+    : failureKind === "runner-skills-blocker"
+      ? typeof skillsSync?.blocker === "string" ? skillsSync.blocker : typeof skills?.blocker === "string" ? skills.blocker : "runner-skills-degraded"
+      : 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";
@@ -3506,6 +3671,8 @@ function compactPrRuntimePreflight(preflight: Record<string, unknown>, options:
       cwd: preflight.cwd ?? null,
       pid: preflight.pid ?? null,
     },
+    skills,
+    skillsSync,
     tokenCoverage,
     authBroker: authBrokerNeededStatus(tokenCoverage, authBrokerRuntime, systemGhBinary, unideskGhCli),
     authScopeSummary,
@@ -4138,6 +4305,7 @@ export async function runCodeQueueCommand(config: UniDeskConfig, args: string[])
     assertKnownOptions(args.slice(1), {}, `codex ${action}`);
     return codeQueueDevReady();
   }
+  if (action === "skills-sync") return codeQueueSkillsSync(args.slice(1));
   if (action === "pr-preflight" || action === "runtime-preflight") return codeQueuePrPreflight(args.slice(1), { config });
   if (action === "output") {
     const taskId = requireTaskId(taskIdArg, "codex output");
@@ -4173,5 +4341,5 @@ export async function runCodeQueueCommand(config: UniDeskConfig, args: string[])
     const taskId = requireTaskId(taskIdArg, "codex steer");
     return codexSteerTask(taskId, args.slice(2));
   }
-  throw new Error("codex command must be one of: submit, enqueue, task, summary, show, tasks, overview, output, judge, read, mark-read, dev-ready, health, pr-preflight, runtime-preflight, queues, queue list, queue create, queue merge, move, steer, interrupt, cancel");
+  throw new Error("codex command must be one of: submit, enqueue, task, summary, show, tasks, overview, output, judge, read, mark-read, dev-ready, health, skills-sync, pr-preflight, runtime-preflight, queues, queue list, queue create, queue merge, move, steer, interrupt, cancel");
 }

scripts/src/help.ts

@@ -53,7 +53,8 @@ export function rootHelp(): unknown {
       { command: "schedule upsert-pgdata-backup [--time HH:MM] [--remote-base /SERVER_DATA/UNIDESK_PG_DATA]", description: "Create or update the daily PGDATA physical backup task that uploads monthly rotated archives to Baidu Netdisk." },
       { command: "codex deploy <commitId> [--provider-id D601] [--timeout-ms N]", description: "Disabled legacy Code Queue deploy path; use the dev-only artifact consumer instead." },
       { command: "codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue queueId] [--provider-id id] [--cwd path] [--model model] [--execution-mode mode] [--max-attempts N] [--reference-task-id id] [--dry-run]", description: "Submit a Code Queue task through backend-core -> code-queue proxy; --dry-run shows the structured request, while real success only confirms the write and task id." },
-      { command: "codex pr-preflight [--remote] [--push-dry-run --push-dry-run-ref refs/heads/probe/<name>] [--pr-create-dry-run --pr-create-dry-run-head <head>] [--issue N]", description: "Read-only PR admission check against the D601 scheduler/runner token, GitHub egress, repo visibility, optional push dry-run, and PR body/create dry-run guard." },
+      { command: "codex skills-sync --dry-run [--full]", description: "Inspect the controlled runner skills hostPath lifecycle contract without copying files, restarting services, reading secrets, or mutating live runner paths." },
+      { command: "codex pr-preflight [--remote] [--push-dry-run --push-dry-run-ref refs/heads/probe/<name>] [--pr-create-dry-run --pr-create-dry-run-head <head>] [--issue N]", description: "Read-only PR admission check against the D601 scheduler/runner token, GitHub egress, repo visibility, skills lifecycle health, optional push dry-run, and PR body/create dry-run guard." },
       { command: "codex task <taskId> [--detail] [--trace --tail|--from-start|--after-seq N|--before-seq N --limit N] [--full]", description: "Fetch the bounded review view by default; --detail is still capped, while --full/trace/output explicitly expand evidence." },
       { command: "codex tasks [--view supervisor|full] [--queue id] [--status status[,status]] [--unread|--unread-only] [--limit N] [--before-id id]", description: "Show the low-noise supervisor view by default: compact task rows, tiny local sections, diagnostics, and drill-down commands; use --view full for detailed rows." },
       { command: "codex output <taskId> [--tail|--from-start|--after-seq N|--before-seq N --limit N] [--full-text]", description: "Fetch paged raw Code Queue output records; default caps large limits/text previews, --full-text explicitly expands one seq window." },
@@ -244,7 +245,7 @@ function scheduleHelp(): unknown {
 
 function codexHelp(): unknown {
   return {
-    command: "codex deploy|submit|task|tasks|output|read|dev-ready|pr-preflight|judge|steer|interrupt|cancel|queues|queue|move",
+    command: "codex deploy|submit|task|tasks|output|read|dev-ready|skills-sync|pr-preflight|judge|steer|interrupt|cancel|queues|queue|move",
     output: "json",
     usage: [
       "bun scripts/cli.ts codex deploy <commitId> # disabled legacy deployment entry",
@@ -256,6 +257,7 @@ function codexHelp(): unknown {
       "bun scripts/cli.ts codex output <taskId> [--tail|--from-start|--after-seq N|--before-seq N --limit N] [--full-text]",
       "bun scripts/cli.ts codex read <taskId>",
       "bun scripts/cli.ts codex dev-ready",
+      "bun scripts/cli.ts codex skills-sync --dry-run [--full]",
       "bun scripts/cli.ts codex pr-preflight [--remote] [--push-dry-run --push-dry-run-ref refs/heads/probe/<name>] [--pr-create-dry-run --pr-create-dry-run-head <head>] [--issue N]",
       "bun scripts/cli.ts codex judge <taskId> --attempt N [--dry-run] [--include-prompt]",
       "bun scripts/cli.ts codex steer <taskId> [prompt|--prompt-file path|--prompt-stdin] [--dry-run] [--no-retry|--retry-attempts N]",
@@ -280,7 +282,7 @@ function codexHelp(): unknown {
     },
     disclosure: {
       defaultPolicy: "low-noise JSON by default; write commands confirm persistence, list/detail/output commands return bounded summaries with drill-down commands",
-      expand: ["codex task <taskId> --full", "codex task <taskId> --trace --limit N", "codex output <taskId> --after-seq N --limit N --full-text", "codex tasks --view full --limit N"],
+      expand: ["codex task <taskId> --full", "codex task <taskId> --trace --limit N", "codex output <taskId> --after-seq N --limit N --full-text", "codex tasks --view full --limit N", "codex skills-sync --dry-run --full"],
     },
     description: "Operate Code Queue through the stable backend-core private proxy path. Real submit/steer success is a low-noise write confirmation and does not echo prompt text.",
   };

scripts/src/microservices.ts

@@ -367,6 +367,86 @@ function compactQueueHealth(value: unknown): Record<string, unknown> | null {
   };
 }
 
+function compactSkillAvailability(value: unknown): Record<string, unknown> | null {
+  const skills = asRecord(value);
+  if (skills === null) return null;
+  return {
+    ok: skills.ok ?? false,
+    path: skills.path ?? null,
+    source: skills.source ?? null,
+    target: skills.target ?? null,
+    mountPoint: skills.mountPoint ?? null,
+    exists: skills.exists ?? false,
+    available: skills.available ?? false,
+    degraded: skills.degraded ?? true,
+    blocker: skills.blocker ?? null,
+    readonly: skills.readonly ?? false,
+    skillCount: skills.skillCount ?? 0,
+    requiredSkills: Array.isArray(skills.requiredSkills) ? skills.requiredSkills.map(String) : [],
+    missingSkills: Array.isArray(skills.missingSkills) ? skills.missingSkills.map(String) : [],
+    valuesPrinted: skills.valuesPrinted ?? false,
+    pathSpelling: compactRecordFields(asRecord(skills.pathSpelling), [
+      "expectedTarget",
+      "forbiddenPathChecked",
+      "forbiddenPathExists",
+      "forbiddenPathMustNotBeUsed",
+    ]),
+    repairHint: skills.repairHint ?? null,
+  };
+}
+
+function compactSkillSync(value: unknown): Record<string, unknown> | null {
+  const sync = asRecord(value);
+  if (sync === null) return null;
+  const source = compactRecordFields(asRecord(sync.source), [
+    "path",
+    "approved",
+    "exists",
+    "directory",
+    "readable",
+    "writable",
+    "readonly",
+    "mountPoint",
+    "skillCount",
+    "requiredSkills",
+    "missingSkills",
+    "error",
+  ]);
+  const target = compactRecordFields(asRecord(sync.target), [
+    "path",
+    "approved",
+    "exists",
+    "directory",
+    "readable",
+    "writable",
+    "readonly",
+    "mountPoint",
+    "skillCount",
+    "requiredSkills",
+    "missingSkills",
+    "error",
+  ]);
+  const permissionFailures = Array.isArray(sync.permissionFailures) ? sync.permissionFailures : [];
+  return {
+    ok: sync.ok ?? false,
+    degraded: sync.degraded ?? true,
+    blocker: sync.blocker ?? null,
+    mode: sync.mode ?? "dry-run",
+    dryRun: sync.dryRun ?? true,
+    mutation: sync.mutation ?? false,
+    syncMode: sync.syncMode ?? null,
+    source,
+    target,
+    counts: sync.counts ?? null,
+    missing: sync.missing ?? null,
+    permissionFailureCount: permissionFailures.length,
+    permissionFailures: permissionFailures.slice(0, 4),
+    plannedActions: sync.plannedActions ?? null,
+    commands: sync.commands ?? null,
+    valuesPrinted: sync.valuesPrinted ?? false,
+  };
+}
+
 function compactMicroserviceBody(body: unknown, serviceId: string): Record<string, unknown> | null {
   const record = asRecord(body);
   if (record === null) return null;
@@ -388,6 +468,8 @@ function compactMicroserviceBody(body: unknown, serviceId: string): Record<strin
     taskCount: record.taskCount ?? null,
     schemaReady: record.schemaReady ?? null,
     queue: compactQueueHealth(record.queue),
+    skills: compactSkillAvailability(record.skills),
+    skillsSync: compactSkillSync(record.skillsSync),
     resourceBudget: compactRecordFields(asRecord(record.resourceBudget), [
       "targetMemoryMb",
       "mgrPoolMax",
@@ -401,7 +483,8 @@ function compactMicroserviceBody(body: unknown, serviceId: string): Record<strin
     devReady: devReady === null ? null : {
       ok: devReady.ok ?? null,
       missingTools: compactStringList(devReady.missingTools, 8),
-      skills: devReady.skills ?? null,
+      skills: compactSkillAvailability(devReady.skills),
+      skillsSync: compactSkillSync(devReady.skillsSync),
     },
     executionDiagnostics: diagnostics === null ? null : {
       state: diagnostics.state ?? null,
@@ -416,7 +499,7 @@ function compactMicroserviceBody(body: unknown, serviceId: string): Record<strin
   };
 }
 
-function summarizeMicroserviceObservation(action: string, serviceId: string, response: unknown, args: string[]): unknown {
+export function summarizeMicroserviceObservation(action: string, serviceId: string, response: unknown, args: string[]): unknown {
   if (hasFlag(args, "--full") || hasFlag(args, "--raw")) return response;
   const record = asRecord(response);
   if (record === null) return response;