gsd-pi 2.38.0-dev.96dc7fb → 2.38.0-dev.98b44dc

package/src/resources/extensions/gsd/health-widget-core.ts

@@ -5,10 +5,9 @@
  * runtime integrations so the regressions can be tested directly.
  */
 
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { detectProjectState } from "./detection.js";
 import { gsdRoot } from "./paths.js";
-import { join } from "node:path";
-import type { GSDState, Phase } from "./types.js";
 
 export type HealthWidgetProjectState = "none" | "initialized" | "active";
 
@@ -20,75 +19,19 @@ export interface HealthWidgetData {
   environmentErrorCount: number;
   environmentWarningCount: number;
   lastRefreshed: number;
-  executionPhase?: Phase;
-  executionStatus?: string;
-  executionTarget?: string;
-  nextAction?: string;
-  blocker?: string | null;
-  activeMilestoneId?: string;
-  activeSliceId?: string;
-  activeTaskId?: string;
-  progress?: GSDState["progress"];
-  eta?: string | null;
 }
 
 export function detectHealthWidgetProjectState(basePath: string): HealthWidgetProjectState {
-  const root = gsdRoot(basePath);
-  if (!existsSync(root)) return "none";
+  if (!existsSync(gsdRoot(basePath))) return "none";
 
-  // Lightweight milestone count — avoids the full detectProjectState() scan
-  // (CI markers, Makefile targets, etc.) that is unnecessary on the 60s refresh.
-  try {
-    const milestonesDir = join(root, "milestones");
-    if (existsSync(milestonesDir)) {
-      const entries = readdirSync(milestonesDir, { withFileTypes: true });
-      if (entries.some(e => e.isDirectory())) return "active";
-    }
-  } catch { /* non-fatal */ }
-
-  return "initialized";
+  const { state } = detectProjectState(basePath);
+  return state === "v2-gsd" ? "active" : "initialized";
 }
 
 function formatCost(n: number): string {
   return n >= 1 ? `$${n.toFixed(2)}` : `${(n * 100).toFixed(1)}¢`;
 }
 
-function formatProgress(progress?: GSDState["progress"]): string | null {
-  if (!progress) return null;
-
-  const parts: string[] = [];
-  parts.push(`M ${progress.milestones.done}/${progress.milestones.total}`);
-  if (progress.slices) parts.push(`S ${progress.slices.done}/${progress.slices.total}`);
-  if (progress.tasks) parts.push(`T ${progress.tasks.done}/${progress.tasks.total}`);
-  return parts.length > 0 ? `Progress: ${parts.join(" · ")}` : null;
-}
-
-function formatEnvironmentSummary(errorCount: number, warningCount: number): string | null {
-  if (errorCount <= 0 && warningCount <= 0) return null;
-
-  const parts: string[] = [];
-  if (errorCount > 0) parts.push(`${errorCount} error${errorCount > 1 ? "s" : ""}`);
-  if (warningCount > 0) parts.push(`${warningCount} warning${warningCount > 1 ? "s" : ""}`);
-  return `Env: ${parts.join(", ")}`;
-}
-
-function formatBudgetSummary(data: HealthWidgetData): string | null {
-  if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
-    const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
-    return `Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`;
-  }
-  if (data.budgetSpent > 0) {
-    return `Spent: ${formatCost(data.budgetSpent)}`;
-  }
-  return null;
-}
-
-function buildExecutionHeadline(data: HealthWidgetData): string {
-  const status = data.executionStatus ?? "Active project";
-  const target = data.executionTarget ?? data.blocker ?? "loading status…";
-  return `  GSD  ${status}${target ? ` - ${target}` : ""}`;
-}
-
 /**
  * Build compact health lines for the widget.
  * Returns a string array suitable for setWidget().
@@ -102,28 +45,33 @@ export function buildHealthLines(data: HealthWidgetData): string[] {
     return ["  GSD  Project initialized — run /gsd to continue setup"];
   }
 
-  const lines = [buildExecutionHeadline(data)];
-  const details: string[] = [];
-
-  const progress = formatProgress(data.progress);
-  if (progress) details.push(progress);
-
-  if (data.providerIssue) details.push(data.providerIssue);
+  const parts: string[] = [];
 
-  const environment = formatEnvironmentSummary(
-    data.environmentErrorCount,
-    data.environmentWarningCount,
-  );
-  if (environment) details.push(environment);
+  const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);
+  if (totalIssues === 0) {
+    parts.push("● System OK");
+  } else if (data.environmentErrorCount > 0 || data.providerIssue?.includes("✗")) {
+    parts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
+  } else {
+    parts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
+  }
 
-  const budget = formatBudgetSummary(data);
-  if (budget) details.push(budget);
+  if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
+    const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
+    parts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
+  } else if (data.budgetSpent > 0) {
+    parts.push(`Spent: ${formatCost(data.budgetSpent)}`);
+  }
 
-  if (data.eta) details.push(data.eta);
+  if (data.providerIssue) {
+    parts.push(data.providerIssue);
+  }
 
-  if (details.length > 0) {
-    lines.push(`  ${details.join("  │  ")}`);
+  if (data.environmentErrorCount > 0) {
+    parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
+  } else if (data.environmentWarningCount > 0) {
+    parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
   }
 
-  return lines;
+  return [`  ${parts.join("  │  ")}`];
 }

package/src/resources/extensions/gsd/health-widget.ts

@@ -16,7 +16,6 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
 import { describeNextUnit, estimateTimeRemaining, updateSliceProgressCache } from "./auto-dashboard.js";
 import { projectRoot } from "./commands.js";
-import { deriveState, invalidateStateCache } from "./state.js";
 import {
   buildHealthLines,
   detectHealthWidgetProjectState,
@@ -25,7 +24,7 @@ import {
 
 // ── Data loader ────────────────────────────────────────────────────────────────
 
-function loadBaseHealthWidgetData(basePath: string): HealthWidgetData {
+function loadHealthWidgetData(basePath: string): HealthWidgetData {
   let budgetCeiling: number | undefined;
   let budgetSpent = 0;
   let providerIssue: string | null = null;
@@ -69,90 +68,6 @@ function loadBaseHealthWidgetData(basePath: string): HealthWidgetData {
   };
 }
 
-function compactText(text: string, max = 64): string {
-  const trimmed = text.replace(/\s+/g, " ").trim();
-  if (trimmed.length <= max) return trimmed;
-  return `${trimmed.slice(0, max - 1).trimEnd()}…`;
-}
-
-function summarizeExecutionStatus(state: GSDState): string {
-  switch (state.phase) {
-    case "blocked": return "Blocked";
-    case "paused": return "Paused";
-    case "complete": return "Complete";
-    case "executing": return "Executing";
-    case "planning": return "Planning";
-    case "pre-planning": return "Pre-planning";
-    case "summarizing": return "Summarizing";
-    case "validating-milestone": return "Validating";
-    case "completing-milestone": return "Completing";
-    case "needs-discussion": return "Needs discussion";
-    case "replanning-slice": return "Replanning";
-    default: return "Active";
-  }
-}
-
-function summarizeExecutionTarget(state: GSDState): string {
-  switch (state.phase) {
-    case "needs-discussion":
-      return state.activeMilestone ? `Discuss ${state.activeMilestone.id}` : "Discuss milestone draft";
-    case "pre-planning":
-      return state.activeMilestone ? `Plan ${state.activeMilestone.id}` : "Research & plan milestone";
-    case "planning":
-      return state.activeSlice ? `Plan ${state.activeSlice.id}` : "Plan next slice";
-    case "executing":
-      return state.activeTask ? `Execute ${state.activeTask.id}` : "Execute next task";
-    case "summarizing":
-      return state.activeSlice ? `Complete ${state.activeSlice.id}` : "Complete current slice";
-    case "validating-milestone":
-      return state.activeMilestone ? `Validate ${state.activeMilestone.id}` : "Validate milestone";
-    case "completing-milestone":
-      return state.activeMilestone ? `Complete ${state.activeMilestone.id}` : "Complete milestone";
-    case "replanning-slice":
-      return state.activeSlice ? `Replan ${state.activeSlice.id}` : "Replan current slice";
-    case "blocked":
-      return `waiting on ${compactText(state.blockers[0] ?? state.nextAction, 56)}`;
-    case "paused":
-      return compactText(state.nextAction || "waiting to resume", 56);
-    case "complete":
-      return "All milestones complete";
-    default:
-      return compactText(describeNextUnit(state).label, 56);
-  }
-}
-
-async function enrichHealthWidgetData(basePath: string, baseData: HealthWidgetData): Promise<HealthWidgetData> {
-  if (baseData.projectState !== "active") return baseData;
-
-  try {
-    invalidateStateCache();
-    const state = await deriveState(basePath);
-
-    if (state.activeMilestone) {
-      // Warm the slice-progress cache so estimateTimeRemaining() has data
-      updateSliceProgressCache(basePath, state.activeMilestone.id, state.activeSlice?.id);
-    }
-
-    return {
-      ...baseData,
-      executionPhase: state.phase,
-      executionStatus: summarizeExecutionStatus(state),
-      executionTarget: summarizeExecutionTarget(state),
-      nextAction: state.nextAction,
-      blocker: state.blockers[0] ?? null,
-      activeMilestoneId: state.activeMilestone?.id,
-      activeSliceId: state.activeSlice?.id,
-      activeTaskId: state.activeTask?.id,
-      progress: state.progress,
-      eta: state.phase === "blocked" || state.phase === "paused" || state.phase === "complete"
-        ? null
-        : estimateTimeRemaining(),
-    };
-  } catch {
-    return baseData;
-  }
-}
-
 // ── Widget init ────────────────────────────────────────────────────────────────
 
 const REFRESH_INTERVAL_MS = 60_000;
@@ -167,7 +82,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
   const basePath = projectRoot();
 
   // String-array fallback — used in RPC mode (factory is a no-op there)
-  const initialData = loadBaseHealthWidgetData(basePath);
+  const initialData = loadHealthWidgetData(basePath);
   ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
 
   // Factory-based widget for TUI mode — replaces the string-array above
@@ -180,8 +95,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       if (refreshInFlight) return;
       refreshInFlight = true;
       try {
-        const baseData = loadBaseHealthWidgetData(basePath);
-        data = await enrichHealthWidgetData(basePath, baseData);
+        data = loadHealthWidgetData(basePath);
         cachedLines = undefined;
         _tui.requestRender();
       } catch { /* non-fatal */ } finally {

package/src/resources/extensions/gsd/index.ts

@@ -60,6 +60,8 @@ import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { shortcutDesc } from "../shared/mod.js";
+
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 import { Text } from "@gsd/pi-tui";
 import { pauseAutoForProviderError, classifyProviderError } from "./provider-error-pause.js";
 import { toPosixPath } from "../shared/mod.js";
@@ -73,7 +75,7 @@ import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../cmux/index.js"
 
 function warnDeprecatedAgentInstructions(): void {
   const paths = [
-    join(homedir(), ".gsd", "agent-instructions.md"),
+    join(gsdHome, "agent-instructions.md"),
     join(process.cwd(), ".gsd", "agent-instructions.md"),
   ];
   for (const p of paths) {
@@ -90,6 +92,23 @@ function warnDeprecatedAgentInstructions(): void {
 // ── Depth verification state ──────────────────────────────────────────────
 let depthVerificationDone = false;
 
+// ── DB lazy-open helper ───────────────────────────────────────────────────
+// In manual sessions (no auto-mode), the DB is never opened by bootstrapAutoSession.
+// This helper ensures the DB is lazily opened on first tool call that needs it.
+async function ensureDbOpen(): Promise<boolean> {
+  try {
+    const db = await import("./gsd-db.js");
+    if (db.isDbAvailable()) return true;
+    const dbPath = join(process.cwd(), ".gsd", "gsd.db");
+    if (existsSync(dbPath)) {
+      return db.openDatabase(dbPath);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 // ── Queue phase tracking ──────────────────────────────────────────────────
 // When true, the LLM is in a queue flow writing CONTEXT.md files.
 // The write-gate applies during queue flows just like discussion flows.
@@ -298,12 +317,8 @@ export default function (pi: ExtensionAPI) {
       when_context: Type.Optional(Type.String({ description: "When/context for the decision (e.g. milestone ID)" })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      // Check DB availability
-      let dbAvailable = false;
-      try {
-        const db = await import("./gsd-db.js");
-        dbAvailable = db.isDbAvailable();
-      } catch { /* dynamic import failed */ }
+      // Ensure DB is open (lazy-open on first tool call in manual sessions)
+      const dbAvailable = await ensureDbOpen();
 
       if (!dbAvailable) {
         return {
@@ -365,11 +380,7 @@ export default function (pi: ExtensionAPI) {
       supporting_slices: Type.Optional(Type.String({ description: "Supporting slices" })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      let dbAvailable = false;
-      try {
-        const db = await import("./gsd-db.js");
-        dbAvailable = db.isDbAvailable();
-      } catch { /* dynamic import failed */ }
+      const dbAvailable = await ensureDbOpen();
 
       if (!dbAvailable) {
         return {
@@ -439,11 +450,7 @@ export default function (pi: ExtensionAPI) {
       content: Type.String({ description: "The full markdown content of the artifact" }),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      let dbAvailable = false;
-      try {
-        const db = await import("./gsd-db.js");
-        dbAvailable = db.isDbAvailable();
-      } catch { /* dynamic import failed */ }
+      const dbAvailable = await ensureDbOpen();
 
       if (!dbAvailable) {
         return {

package/src/resources/extensions/gsd/migrate/parsers.ts

@@ -3,7 +3,7 @@
 // Zero Pi dependencies — uses only exported helpers from files.ts.
 
 import { splitFrontmatter, parseFrontmatterMap, extractBoldField } from '../files.js';
-import { normalizeStringArray } from '../../shared/mod.js';
+import { normalizeStringArray } from '../../shared/format-utils.js';
 
 import type {
   PlanningRoadmap,

package/src/resources/extensions/gsd/migrate-external.ts

@@ -6,11 +6,13 @@
  * symlink replaces the original directory so all paths remain valid.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { externalGsdRoot } from "./repo-identity.js";
 import { getErrorMessage } from "./error-utils.js";
 import { hasGitTrackedGsdFiles } from "./gitignore.js";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 
 export interface MigrationResult {
   migrated: boolean;
@@ -144,7 +146,22 @@ export function migrateToExternalState(basePath: string): MigrationResult {
       return { migrated: false, error: `Migration verification failed: ${getErrorMessage(verifyErr)}` };
     }
 
-    // Remove .gsd.migrating only after symlink is verified
+    // Clean the git index — any .gsd/* files tracked before migration now
+    // sit behind the symlink and git can't follow it, causing them to show
+    // as deleted. Remove them from the index so the working tree stays clean.
+    // --ignore-unmatch makes this a no-op on fresh projects with no tracked .gsd/.
+    try {
+      execFileSync("git", ["rm", "-r", "--cached", "--ignore-unmatch", ".gsd"], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "ignore"],
+        env: GIT_NO_PROMPT_ENV,
+        timeout: 10_000,
+      });
+    } catch {
+      // Non-fatal — git may be unavailable or nothing was tracked
+    }
+
+    // Remove .gsd.migrating only after symlink is verified and index is clean
     rmSync(migratingPath, { recursive: true, force: true });
 
     return { migrated: true };

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -671,6 +671,43 @@ export function nativeAddAll(basePath: string): void {
   gitFileExec(basePath, ["add", "-A"]);
 }
 
+/**
+ * Stage all files with pathspec exclusions (git add -A -- ':!pattern' ...).
+ * Excluded paths are never hashed by git, preventing hangs on large
+ * untracked artifact trees (57GB+, 11K+ files). See #1605.
+ *
+ * Falls back to plain `git add -A` when no exclusions are provided.
+ * Always uses the CLI path (not libgit2) because libgit2's add_all
+ * does not support pathspec exclusion syntax.
+ *
+ * When excluded paths are already covered by .gitignore, git may exit
+ * with code 1 and an "ignored by .gitignore" warning. This is harmless
+ * (the staging succeeds for all non-ignored files) and is suppressed.
+ */
+export function nativeAddAllWithExclusions(basePath: string, exclusions: readonly string[]): void {
+  if (exclusions.length === 0) {
+    nativeAddAll(basePath);
+    return;
+  }
+  const pathspecs = exclusions.map(e => `:!${e}`);
+  try {
+    execFileSync("git", ["add", "-A", "--", ...pathspecs], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    });
+  } catch (err: unknown) {
+    // git exits 1 when pathspec exclusions reference paths already covered
+    // by .gitignore. The staging itself succeeds — only suppress that case.
+    const stderr = (err as { stderr?: string })?.stderr ?? "";
+    if (stderr.includes("ignored by one of your .gitignore files")) {
+      return;
+    }
+    throw new GSDError(GSD_GIT_ERROR, `git add -A with exclusions failed in ${basePath}: ${getErrorMessage(err)}`);
+  }
+}
+
 /**
  * Stage specific files.
  * Native: libgit2 index add.

package/src/resources/extensions/gsd/paths.ts

@@ -356,6 +356,10 @@ export function milestonesDir(basePath: string): string {
   return join(gsdRoot(basePath), "milestones");
 }
 
+export function resolveRuntimeFile(basePath: string): string {
+  return join(gsdRoot(basePath), "RUNTIME.md");
+}
+
 export function resolveGsdRootFile(basePath: string, key: GSDRootFileKey): string {
   const root = gsdRoot(basePath);
   const canonical = join(root, GSD_ROOT_FILES[key]);

package/src/resources/extensions/gsd/preferences-models.ts

@@ -295,18 +295,6 @@ export function resolveInlineLevel(): InlineLevel {
   }
 }
 
-/**
- * Resolve the compression strategy from the active token profile.
- * budget/balanced -> "compress", quality -> "truncate".
- * Explicit preference always wins.
- */
-export function resolveCompressionStrategy(): import("./types.js").CompressionStrategy {
-  const prefs = loadEffectiveGSDPreferences();
-  if (prefs?.preferences.compression_strategy) return prefs.preferences.compression_strategy;
-  const profile = resolveEffectiveProfile();
-  return profile === "quality" ? "truncate" : "compress";
-}
-
 /**
  * Resolve the context selection mode from the active token profile.
  * budget -> "smart", balanced/quality -> "full".

package/src/resources/extensions/gsd/preferences-types.ts

@@ -16,11 +16,11 @@ import type {
   InlineLevel,
   PhaseSkipPreferences,
   ParallelConfig,
-  CompressionStrategy,
   ContextSelectionMode,
   ReactiveExecutionConfig,
 } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
+import type { GitHubSyncConfig } from "../github-sync/types.js";
 
 // ─── Workflow Modes ──────────────────────────────────────────────────────────
 
@@ -84,10 +84,10 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "verification_auto_fix",
   "verification_max_retries",
   "search_provider",
-  "compression_strategy",
   "context_selection",
   "widget_mode",
   "reactive_execution",
+  "github",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -211,14 +211,14 @@ export interface GSDPreferences {
   verification_max_retries?: number;
   /** Search provider preference. "brave"/"tavily"/"ollama" force that backend and disable native Anthropic search. "native" forces native only. "auto" = current default behavior. */
   search_provider?: "brave" | "tavily" | "ollama" | "native" | "auto";
-  /** Compression strategy for context that exceeds budget. "truncate" (default) drops sections, "compress" applies heuristic compression first. */
-  compression_strategy?: CompressionStrategy;
   /** Context selection mode for file inlining. "full" inlines entire files, "smart" uses semantic chunking. Default derived from token profile. */
   context_selection?: ContextSelectionMode;
   /** Default widget display mode for auto-mode dashboard. "full" | "small" | "min" | "off". Default: "full". */
   widget_mode?: "full" | "small" | "min" | "off";
   /** Reactive (graph-derived parallel) task execution within slices. Disabled by default. */
   reactive_execution?: ReactiveExecutionConfig;
+  /** GitHub sync configuration. Opt-in: syncs GSD events to GitHub Issues, Milestones, and PRs. */
+  github?: GitHubSyncConfig;
 }
 
 export interface LoadedGSDPreferences {

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -10,7 +10,7 @@ import type { GitPreferences } from "./git-service.js";
 import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile, PhaseSkipPreferences } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { VALID_BRANCH_NAME } from "./git-service.js";
-import { normalizeStringArray } from "../shared/mod.js";
+import { normalizeStringArray } from "../shared/format-utils.js";
 
 import {
   KNOWN_PREFERENCE_KEYS,
@@ -686,16 +686,6 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
-  // ─── Compression Strategy ───────────────────────────────────────────
-  if (preferences.compression_strategy !== undefined) {
-    const validStrategies = new Set(["truncate", "compress"]);
-    if (typeof preferences.compression_strategy === "string" && validStrategies.has(preferences.compression_strategy)) {
-      validated.compression_strategy = preferences.compression_strategy as GSDPreferences["compression_strategy"];
-    } else {
-      errors.push(`compression_strategy must be one of: truncate, compress`);
-    }
-  }
-
   // ─── Context Selection ──────────────────────────────────────────────
   if (preferences.context_selection !== undefined) {
     const validModes = new Set(["full", "smart"]);
@@ -706,5 +696,55 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── GitHub Sync ────────────────────────────────────────────────────────
+  if (preferences.github !== undefined) {
+    if (typeof preferences.github === "object" && preferences.github !== null) {
+      const gh = preferences.github as unknown as Record<string, unknown>;
+      const validGh: Record<string, unknown> = {};
+
+      if (gh.enabled !== undefined) {
+        if (typeof gh.enabled === "boolean") validGh.enabled = gh.enabled;
+        else errors.push("github.enabled must be a boolean");
+      }
+      if (gh.repo !== undefined) {
+        if (typeof gh.repo === "string" && gh.repo.includes("/")) validGh.repo = gh.repo;
+        else errors.push('github.repo must be a string in "owner/repo" format');
+      }
+      if (gh.project !== undefined) {
+        const p = typeof gh.project === "number" ? gh.project : Number(gh.project);
+        if (Number.isFinite(p) && p > 0) validGh.project = Math.floor(p);
+        else errors.push("github.project must be a positive number");
+      }
+      if (gh.labels !== undefined) {
+        if (Array.isArray(gh.labels) && gh.labels.every((l: unknown) => typeof l === "string")) {
+          validGh.labels = gh.labels;
+        } else {
+          errors.push("github.labels must be an array of strings");
+        }
+      }
+      if (gh.auto_link_commits !== undefined) {
+        if (typeof gh.auto_link_commits === "boolean") validGh.auto_link_commits = gh.auto_link_commits;
+        else errors.push("github.auto_link_commits must be a boolean");
+      }
+      if (gh.slice_prs !== undefined) {
+        if (typeof gh.slice_prs === "boolean") validGh.slice_prs = gh.slice_prs;
+        else errors.push("github.slice_prs must be a boolean");
+      }
+
+      const knownGhKeys = new Set(["enabled", "repo", "project", "labels", "auto_link_commits", "slice_prs"]);
+      for (const key of Object.keys(gh)) {
+        if (!knownGhKeys.has(key)) {
+          warnings.push(`unknown github key "${key}" — ignored`);
+        }
+      }
+
+      if (Object.keys(validGh).length > 0) {
+        validated.github = validGh as unknown as import("../github-sync/types.js").GitHubSyncConfig;
+      }
+    } else {
+      errors.push("github must be an object");
+    }
+  }
+
   return { preferences: validated, errors, warnings };
 }