gsd-pi 2.35.0-dev.640d5c7 → 2.35.0-dev.67d0e02

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -8,6 +8,8 @@
  */
 
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
+import { parseUnitId } from "./unit-id.js";
+import { atomicWriteSync } from "./atomic-write.js";
 import { clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { clearParseCache, parseRoadmap, parsePlan } from "./files.js";
 import { isValidationTerminal } from "./state.js";
@@ -35,6 +37,7 @@ import {
   clearPathCache,
   resolveGsdRootFile,
 } from "./paths.js";
+import { markSliceDoneInRoadmap } from "./roadmap-mutations.js";
 import {
   existsSync,
   mkdirSync,
@@ -499,6 +502,42 @@ export async function selfHealRuntimeRecords(
     for (const record of records) {
       const { unitType, unitId } = record;
 
+      // Case 0: complete-slice with SUMMARY + UAT but unchecked roadmap (#1350).
+      // If a complete-slice was interrupted after writing artifacts but before
+      // flipping the roadmap checkbox, the verification fails and the dispatch
+      // loop relaunches the same unit forever. Auto-fix the checkbox.
+      if (unitType === "complete-slice") {
+        const { milestone: mid, slice: sid } = parseUnitId(unitId);
+        if (mid && sid) {
+          const dir = resolveSlicePath(base, mid, sid);
+          if (dir) {
+            const summaryPath = join(dir, buildSliceFileName(sid, "SUMMARY"));
+            const uatPath = join(dir, buildSliceFileName(sid, "UAT"));
+            if (existsSync(summaryPath) && existsSync(uatPath)) {
+              const roadmapFile = resolveMilestoneFile(base, mid, "ROADMAP");
+              if (roadmapFile && existsSync(roadmapFile)) {
+                try {
+                  const roadmapContent = readFileSync(roadmapFile, "utf-8");
+                  const roadmap = parseRoadmap(roadmapContent);
+                  const slice = (roadmap.slices ?? []).find(s => s.id === sid);
+                  if (slice && !slice.done) {
+                    // Auto-fix: flip the checkbox using shared utility
+                    if (markSliceDoneInRoadmap(base, mid, sid)) {
+                      ctx.ui.notify(
+                        `Self-heal: marked ${sid} done in roadmap (SUMMARY + UAT exist but checkbox was stale).`,
+                        "info",
+                      );
+                    }
+                  }
+                } catch {
+                  // Roadmap parse failure — don't block self-heal
+                }
+              }
+            }
+          }
+        }
+      }
+
       // Clear stale dispatched records (dispatched > 1h ago, process crashed)
       const age = now - (record.startedAt ?? 0);
       if (record.phase === "dispatched" && age > STALE_THRESHOLD_MS) {

package/src/resources/extensions/gsd/auto-start.ts

@@ -20,6 +20,8 @@ import {
   resolveSkillDiscoveryMode,
   getIsolationMode,
 } from "./preferences.js";
+import { ensureGsdSymlink } from "./repo-identity.js";
+import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { gsdRoot, resolveMilestoneFile, milestonesDir } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
@@ -92,6 +94,13 @@ export interface BootstrapDeps {
  * Returns false if the bootstrap aborted (e.g., guided flow returned,
  * concurrent session detected). Returns true when ready to dispatch.
  */
+
+/** Guard: tracks consecutive bootstrap attempts that found phase === "complete".
+ *  Prevents the recursive dialog loop described in #1348 where
+ *  bootstrapAutoSession → showSmartEntry → checkAutoStartAfterDiscuss → startAuto
+ *  cycles indefinitely when the discuss workflow doesn't produce a milestone. */
+let _consecutiveCompleteBootstraps = 0;
+const MAX_CONSECUTIVE_COMPLETE_BOOTSTRAPS = 2;
 export async function bootstrapAutoSession(
   s: AutoSession,
   ctx: ExtensionCommandContext,
@@ -128,7 +137,20 @@ export async function bootstrapAutoSession(
       nativeInit(base, mainBranch);
     }
 
-    // Ensure .gitignore has baseline patterns
+    // Migrate legacy in-project .gsd/ to external state directory.
+    // Migration MUST run before ensureGitignore to avoid adding ".gsd" to
+    // .gitignore when .gsd/ is git-tracked (data-loss bug #1364).
+    recoverFailedMigration(base);
+    const migration = migrateToExternalState(base);
+    if (migration.error) {
+      ctx.ui.notify(`External state migration warning: ${migration.error}`, "warning");
+    }
+    // Ensure symlink exists (handles fresh projects and post-migration)
+    ensureGsdSymlink(base);
+
+    // Ensure .gitignore has baseline patterns.
+    // ensureGitignore checks for git-tracked .gsd/ files and skips the
+    // ".gsd" pattern if the project intentionally tracks .gsd/ in git.
     const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
     const commitDocs = gitPrefs?.commit_docs;
     const manageGitignore = gitPrefs?.manage_gitignore;
@@ -286,6 +308,20 @@ export async function bootstrapAutoSession(
     if (!hasSurvivorBranch) {
       // No active work — start a new milestone via discuss flow
       if (!state.activeMilestone || state.phase === "complete") {
+        // Guard against recursive dialog loop (#1348):
+        // If we've entered this branch multiple times in quick succession,
+        // the discuss workflow isn't producing a milestone. Break the cycle.
+        _consecutiveCompleteBootstraps++;
+        if (_consecutiveCompleteBootstraps > MAX_CONSECUTIVE_COMPLETE_BOOTSTRAPS) {
+          _consecutiveCompleteBootstraps = 0;
+          ctx.ui.notify(
+            "All milestones are complete and the discussion didn't produce a new one. " +
+            "Run /gsd to start a new milestone manually.",
+            "warning",
+          );
+          return releaseLockAndReturn();
+        }
+
         const { showSmartEntry } = await import("./guided-flow.js");
         await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
 
@@ -296,6 +332,7 @@ export async function bootstrapAutoSession(
           postState.phase !== "complete" &&
           postState.phase !== "pre-planning"
         ) {
+          _consecutiveCompleteBootstraps = 0; // Successfully advanced past "complete"
           state = postState;
         } else if (
           postState.activeMilestone &&
@@ -352,6 +389,9 @@ export async function bootstrapAutoSession(
       return releaseLockAndReturn();
     }
 
+    // Successfully resolved an active milestone — reset the re-entry guard
+    _consecutiveCompleteBootstraps = 0;
+
     // ── Initialize session state ──
     s.active = true;
     s.stepMode = requestedStepMode;
@@ -484,7 +524,7 @@ export async function bootstrapAutoSession(
     // Secrets collection gate
     const mid = state.activeMilestone!.id;
     try {
-      const manifestStatus = await getManifestStatus(base, mid);
+      const manifestStatus = await getManifestStatus(base, mid, s.originalBasePath || base);
       if (manifestStatus && manifestStatus.pending.length > 0) {
         const result = await collectSecretsFromManifest(base, mid, ctx);
         if (

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

@@ -127,7 +127,7 @@ import {
   formatTokenCount,
 } from "./metrics.js";
 import { join } from "node:path";
-import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import {
   autoCommitCurrentBranch,
@@ -554,6 +554,13 @@ export async function stopAuto(
   resetRoutingHistory();
   resetHookState();
   if (s.basePath) clearPersistedHookState(s.basePath);
+
+  // Remove paused-session metadata if present (#1383)
+  try {
+    const pausedPath = join(gsdRoot(s.originalBasePath || s.basePath), "runtime", "paused-session.json");
+    if (existsSync(pausedPath)) unlinkSync(pausedPath);
+  } catch { /* non-fatal */ }
+
   s.active = false;
   s.paused = false;
   s.stepMode = false;
@@ -607,8 +614,32 @@ export async function pauseAuto(
 
   s.pausedSessionFile = ctx?.sessionManager?.getSessionFile() ?? null;
 
-  if (lockBase()) clearLock(lockBase());
-  if (lockBase()) releaseSessionLock(lockBase());
+  // Persist paused-session metadata so resume survives /exit (#1383).
+  // The fresh-start bootstrap checks for this file and restores worktree context.
+  try {
+    const pausedMeta = {
+      milestoneId: s.currentMilestoneId,
+      worktreePath: isInAutoWorktree(s.basePath) ? s.basePath : null,
+      originalBasePath: s.originalBasePath,
+      stepMode: s.stepMode,
+      pausedAt: new Date().toISOString(),
+      sessionFile: s.pausedSessionFile,
+    };
+    const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
+    mkdirSync(runtimeDir, { recursive: true });
+    writeFileSync(
+      join(runtimeDir, "paused-session.json"),
+      JSON.stringify(pausedMeta, null, 2),
+      "utf-8",
+    );
+  } catch {
+    // Non-fatal — resume will still work via full bootstrap, just without worktree context
+  }
+
+  if (lockBase()) {
+    releaseSessionLock(lockBase());
+    clearLock(lockBase());
+  }
 
   deregisterSigtermHandler();
 
@@ -792,6 +823,30 @@ export async function startAuto(
   base = escapeStaleWorktree(base);
 
   // If resuming from paused state, just re-activate and dispatch next unit.
+  // Check persisted paused-session first (#1383) — survives /exit.
+  if (!s.paused) {
+    try {
+      const pausedPath = join(gsdRoot(base), "runtime", "paused-session.json");
+      if (existsSync(pausedPath)) {
+        const meta = JSON.parse(readFileSync(pausedPath, "utf-8"));
+        if (meta.milestoneId) {
+          s.currentMilestoneId = meta.milestoneId;
+          s.originalBasePath = meta.originalBasePath || base;
+          s.stepMode = meta.stepMode ?? requestedStepMode;
+          s.paused = true;
+          // Clean up the persisted file — we're consuming it
+          try { unlinkSync(pausedPath); } catch { /* non-fatal */ }
+          ctx.ui.notify(
+            `Resuming paused session for ${meta.milestoneId}${meta.worktreePath ? ` (worktree)` : ""}.`,
+            "info",
+          );
+        }
+      }
+    } catch {
+      // Malformed or missing — proceed with fresh bootstrap
+    }
+  }
+
   if (s.paused) {
     const resumeLock = acquireSessionLock(base);
     if (!resumeLock.acquired) {
@@ -1145,6 +1200,9 @@ export async function dispatchHookUnit(
   ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
   ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info");
 
+  // Ensure cwd matches basePath before hook dispatch (#1389)
+  try { if (process.cwd() !== s.basePath) process.chdir(s.basePath); } catch {}
+
   debugLog("dispatchHookUnit", {
     phase: "send-message",
     promptLength: hookPrompt.length,

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -24,7 +24,7 @@ import { projectRoot } from "./commands.js";
 import { loadPrompt } from "./prompt-loader.js";
 
 export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
   const prompt = loadPrompt("doctor-heal", {
     doctorSummary: reportText,
@@ -187,7 +187,7 @@ export async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAP
     roadmapContext: roadmapContext || "(no active roadmap)",
   });
 
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
 
   pi.sendMessage(

package/src/resources/extensions/gsd/doctor-environment.ts

@@ -180,26 +180,36 @@ function checkPortConflicts(basePath: string): EnvironmentCheckResult[] {
   const portsToCheck = new Set<number>();
   const pkgPath = join(basePath, "package.json");
 
-  if (existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-      const scripts = pkg.scripts ?? {};
-      const scriptText = Object.values(scripts).join(" ");
-
-      // Look for --port NNNN, -p NNNN, PORT=NNNN, :NNNN patterns
-      const portMatches = scriptText.matchAll(/(?:--port\s+|(?:^|[^a-z])PORT[=:]\s*|-p\s+|:)(\d{4,5})\b/gi);
-      for (const m of portMatches) {
-        const port = parseInt(m[1], 10);
-        if (port >= 1024 && port <= 65535) portsToCheck.add(port);
-      }
-    } catch {
-      // parse failed — use defaults
+  if (!existsSync(pkgPath)) {
+    // No package.json — this isn't a Node.js project. Skip port checks
+    // entirely to avoid false positives from system services (e.g., macOS
+    // AirPlay Receiver on port 5000). (#1381)
+    return [];
+  }
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const scripts = pkg.scripts ?? {};
+    const scriptText = Object.values(scripts).join(" ");
+
+    // Look for --port NNNN, -p NNNN, PORT=NNNN, :NNNN patterns
+    const portMatches = scriptText.matchAll(/(?:--port\s+|(?:^|[^a-z])PORT[=:]\s*|-p\s+|:)(\d{4,5})\b/gi);
+    for (const m of portMatches) {
+      const port = parseInt(m[1], 10);
+      if (port >= 1024 && port <= 65535) portsToCheck.add(port);
     }
+  } catch {
+    // parse failed — skip port checks rather than using defaults
+    return [];
   }
 
-  // If no ports found in scripts, check common defaults
+  // If no ports found in scripts, check common defaults.
+  // Filter out port 5000 on macOS — AirPlay Receiver uses it by default (#1381).
   if (portsToCheck.size === 0) {
-    for (const p of DEFAULT_DEV_PORTS) portsToCheck.add(p);
+    for (const p of DEFAULT_DEV_PORTS) {
+      if (p === 5000 && process.platform === "darwin") continue;
+      portsToCheck.add(p);
+    }
   }
 
   for (const port of portsToCheck) {

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

@@ -805,7 +805,7 @@ export async function inlinePriorMilestoneSummary(mid: string, base: string): Pr
  * file not on disk) - callers can distinguish "no manifest" from "empty manifest".
  */
 export async function getManifestStatus(
-  base: string, milestoneId: string,
+  base: string, milestoneId: string, projectRoot?: string,
 ): Promise<ManifestStatus | null> {
   const resolvedPath = resolveMilestoneFile(base, milestoneId, 'SECRETS');
   if (!resolvedPath) return null;
@@ -815,9 +815,18 @@ export async function getManifestStatus(
 
   const manifest = parseSecretsManifest(content);
   const keys = manifest.entries.map(e => e.key);
+
+  // Check both the base path .env AND the project root .env (#1387).
+  // In worktree mode, base is the worktree path which may not have .env.
+  // The project root's .env is where the user actually defined their keys.
   const existingKeys = await checkExistingEnvKeys(keys, resolve(base, '.env'));
   const existingSet = new Set(existingKeys);
 
+  if (projectRoot && projectRoot !== base) {
+    const rootKeys = await checkExistingEnvKeys(keys, resolve(projectRoot, '.env'));
+    for (const k of rootKeys) existingSet.add(k);
+  }
+
   const result: ManifestStatus = {
     pending: [],
     collected: [],

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

@@ -7,8 +7,8 @@
  */
 
 import { join } from "node:path";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { nativeRmCached } from "./native-git-bridge.js";
+import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
+import { nativeRmCached, nativeLsFiles } from "./native-git-bridge.js";
 import { gsdRoot } from "./paths.js";
 
 /**
@@ -79,12 +79,47 @@ const BASELINE_PATTERNS = [
 ];
 
 /**
- * Ensure basePath/.gitignore contains a blanket `.gsd/` ignore.
- * Creates the file if missing; appends `.gsd/` if not present.
+ * Check whether `.gsd/` contains files tracked by git.
+ * If so, the project intentionally keeps `.gsd/` in version control
+ * and we must NOT add `.gsd` to `.gitignore` or attempt migration.
+ *
+ * Returns true if git tracks at least one file under `.gsd/`.
+ * Returns false (safe to ignore) if:
+ *   - Not a git repo
+ *   - `.gsd/` is a symlink (external state, should be ignored)
+ *   - `.gsd/` doesn't exist
+ *   - No tracked files found under `.gsd/`
+ */
+export function hasGitTrackedGsdFiles(basePath: string): boolean {
+  const localGsd = join(basePath, ".gsd");
+
+  // If .gsd doesn't exist or is already a symlink, no tracked files concern
+  if (!existsSync(localGsd)) return false;
+  try {
+    if (lstatSync(localGsd).isSymbolicLink()) return false;
+  } catch {
+    return false;
+  }
+
+  // Check if git tracks any files under .gsd/
+  try {
+    const tracked = nativeLsFiles(basePath, ".gsd");
+    return tracked.length > 0;
+  } catch {
+    // Not a git repo or git not available — safe to proceed
+    return false;
+  }
+}
+
+/**
+ * Ensure basePath/.gitignore contains baseline ignore patterns.
+ * Creates the file if missing; appends missing patterns.
  * Returns true if the file was created or modified, false if already complete.
  *
- * `.gsd/` state is managed externally (symlinked to `~/.gsd/projects/<hash>/`),
- * so the entire directory is always gitignored.
+ * **Safety check:** If `.gsd/` contains git-tracked files (i.e., the project
+ * intentionally keeps `.gsd/` in version control), the `.gsd` ignore pattern
+ * is excluded to prevent data loss. Only the `.gsd` pattern is affected —
+ * all other baseline patterns are still applied normally.
  */
 export function ensureGitignore(
   basePath: string,
@@ -108,8 +143,15 @@ export function ensureGitignore(
       .filter((l) => l && !l.startsWith("#")),
   );
 
+  // Determine which patterns to apply. If .gsd/ has tracked files,
+  // exclude the ".gsd" pattern to prevent deleting tracked state.
+  const gsdIsTracked = hasGitTrackedGsdFiles(basePath);
+  const patternsToApply = gsdIsTracked
+    ? BASELINE_PATTERNS.filter((p) => p !== ".gsd")
+    : BASELINE_PATTERNS;
+
   // Find patterns not yet present
-  const missing = BASELINE_PATTERNS.filter((p) => !existingLines.has(p));
+  const missing = patternsToApply.filter((p) => !existingLines.has(p));
 
   if (missing.length === 0) return false;
 
@@ -135,6 +177,11 @@ export function ensureGitignore(
  * already in the index even after .gitignore is updated.
  *
  * Only removes from the index (`--cached`), never from disk. Idempotent.
+ *
+ * Note: These are strictly runtime/ephemeral paths (activity logs, lock files,
+ * metrics, STATE.md). They are always safe to untrack, even when the project
+ * intentionally keeps other `.gsd/` files (like PROJECT.md, milestones/) in
+ * version control.
  */
 export function untrackRuntimeFiles(basePath: string): void {
   const runtimePaths = GSD_RUNTIME_PATTERNS;

package/src/resources/extensions/gsd/guided-flow.ts

@@ -191,7 +191,7 @@ type UIContext = ExtensionContext;
  * This is the only way the wizard triggers work — everything else is the LLM's job.
  */
 function dispatchWorkflow(pi: ExtensionAPI, note: string, customType = "gsd-run"): void {
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
 
   pi.sendMessage(

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

@@ -0,0 +1,129 @@
+/**
+ * Pure GSD health widget logic.
+ *
+ * Separates project-state detection and line rendering from the widget's
+ * runtime integrations so the regressions can be tested directly.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { gsdRoot } from "./paths.js";
+import { join } from "node:path";
+import type { GSDState, Phase } from "./types.js";
+
+export type HealthWidgetProjectState = "none" | "initialized" | "active";
+
+export interface HealthWidgetData {
+  projectState: HealthWidgetProjectState;
+  budgetCeiling: number | undefined;
+  budgetSpent: number;
+  providerIssue: string | null;
+  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";
+
+  // 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";
+}
+
+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().
+ */
+export function buildHealthLines(data: HealthWidgetData): string[] {
+  if (data.projectState === "none") {
+    return ["  GSD  No project loaded — run /gsd to start"];
+  }
+
+  if (data.projectState === "initialized") {
+    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 environment = formatEnvironmentSummary(
+    data.environmentErrorCount,
+    data.environmentWarningCount,
+  );
+  if (environment) details.push(environment);
+
+  const budget = formatBudgetSummary(data);
+  if (budget) details.push(budget);
+
+  if (data.eta) details.push(data.eta);
+
+  if (details.length > 0) {
+    lines.push(`  ${details.join("  │  ")}`);
+  }
+
+  return lines;
+}