gsd-pi 2.31.2 → 2.32.0-dev.3d7932c

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

@@ -64,6 +64,7 @@ import { pauseAutoForProviderError, classifyProviderError } from "./provider-err
 import { toPosixPath } from "../shared/mod.js";
 import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
+import { getErrorMessage } from "./error-utils.js";
 
 /**
  * Ensure the GSD database is available, auto-initializing if needed.
@@ -374,7 +375,7 @@ export default function (pi: ExtensionAPI) {
           details: { operation: "save_decision", id },
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = getErrorMessage(err);
         process.stderr.write(`gsd-db: gsd_save_decision tool failed: ${msg}\n`);
         return {
           content: [{ type: "text" as const, text: `Error saving decision: ${msg}` }],
@@ -445,7 +446,7 @@ export default function (pi: ExtensionAPI) {
           details: { operation: "update_requirement", id: params.id },
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = getErrorMessage(err);
         process.stderr.write(`gsd-db: gsd_update_requirement tool failed: ${msg}\n`);
         return {
           content: [{ type: "text" as const, text: `Error updating requirement: ${msg}` }],
@@ -525,7 +526,7 @@ export default function (pi: ExtensionAPI) {
           details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type },
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = getErrorMessage(err);
         process.stderr.write(`gsd-db: gsd_save_summary tool failed: ${msg}\n`);
         return {
           content: [{ type: "text" as const, text: `Error saving artifact: ${msg}` }],
@@ -574,7 +575,7 @@ export default function (pi: ExtensionAPI) {
           details: { operation: "generate_milestone_id", id: newId, existingCount: existingIds.length, reservedCount: reservedMilestoneIds.size, uniqueEnabled },
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = getErrorMessage(err);
         return {
           content: [{ type: "text" as const, text: `Error generating milestone ID: ${msg}` }],
           isError: true,
@@ -607,6 +608,12 @@ export default function (pi: ExtensionAPI) {
     // Load tool API keys from auth.json into environment
     loadToolApiKeys();
 
+    // Always-on health widget — ambient system health signal below the editor
+    try {
+      const { initHealthWidget } = await import("./health-widget.js");
+      initHealthWidget(ctx);
+    } catch { /* non-fatal — widget is best-effort */ }
+
     // Notify remote questions status if configured
     try {
       const [{ getRemoteConfigStatus }, { getLatestPromptSummary }] = await Promise.all([
@@ -789,6 +796,12 @@ export default function (pi: ExtensionAPI) {
 
   // ── agent_end: auto-mode advancement or auto-start after discuss ───────────
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
+    // Clean up quick-task branch if one just completed (#1269)
+    try {
+      const { cleanupQuickBranch } = await import("./quick.js");
+      cleanupQuickBranch();
+    } catch { /* non-fatal */ }
+
     // If discuss phase just finished, start auto-mode
     if (checkAutoStartAfterDiscuss()) {
       depthVerifiedMilestones.clear();
@@ -981,7 +994,7 @@ export default function (pi: ExtensionAPI) {
     } catch (err) {
       // Safety net: if handleAgentEnd throws despite its internal try-catch,
       // ensure auto-mode stops gracefully instead of silently stalling (#381).
-      const message = err instanceof Error ? err.message : String(err);
+      const message = getErrorMessage(err);
       ctx.ui.notify(
         `Auto-mode error in agent_end handler: ${message}. Stopping auto-mode.`,
         "error",

package/dist/resources/extensions/gsd/key-manager.ts

@@ -16,6 +16,7 @@ import { getEnvApiKey } from "@gsd/pi-ai";
 import { existsSync, statSync, chmodSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { mkdirSync } from "node:fs";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Provider Registry ─────────────────────────────────────────────────────────
 
@@ -552,7 +553,7 @@ export async function testProviderKey(
     return { provider, status: "error", message: `HTTP ${res.status}`, latencyMs };
   } catch (err) {
     const latencyMs = Date.now() - start;
-    const msg = err instanceof Error ? err.message : String(err);
+    const msg = getErrorMessage(err);
     if (msg.includes("timeout") || msg.includes("AbortError")) {
       return { provider, status: "error", message: "timeout (15s)", latencyMs };
     }

package/dist/resources/extensions/gsd/marketplace-discovery.ts

@@ -16,6 +16,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { getErrorMessage } from "./error-utils.js";
 
 // ============================================================================
 // Type Definitions
@@ -194,7 +195,7 @@ export function parseMarketplaceJson(repoRoot: string):
   } catch (err) {
     return {
       success: false,
-      error: `Failed to read marketplace.json: ${err instanceof Error ? err.message : String(err)}`
+      error: `Failed to read marketplace.json: ${getErrorMessage(err)}`
     };
   }
   
@@ -204,7 +205,7 @@ export function parseMarketplaceJson(repoRoot: string):
   } catch (err) {
     return {
       success: false,
-      error: `Failed to parse marketplace.json: ${err instanceof Error ? err.message : String(err)}`
+      error: `Failed to parse marketplace.json: ${getErrorMessage(err)}`
     };
   }
   
@@ -293,7 +294,7 @@ export function inspectPlugin(
       }
     } catch (err) {
       // Fall back to marketplace inline or derived
-      result.error = `Failed to parse plugin.json: ${err instanceof Error ? err.message : String(err)}`;
+      result.error = `Failed to parse plugin.json: ${getErrorMessage(err)}`;
     }
   }
   

package/dist/resources/extensions/gsd/metrics.ts

@@ -18,6 +18,7 @@ import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import { gsdRoot } from "./paths.js";
 import { getAndClearSkills } from "./skill-telemetry.js";
 import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { parseUnitId } from "./unit-id.js";
 
 // Re-export from shared — canonical implementation lives in format-utils.
 export { formatTokenCount } from "../shared/mod.js";
@@ -290,9 +291,8 @@ export function aggregateByPhase(units: UnitMetrics[]): PhaseAggregate[] {
 export function aggregateBySlice(units: UnitMetrics[]): SliceAggregate[] {
   const map = new Map<string, SliceAggregate>();
   for (const u of units) {
-    const parts = u.id.split("/");
-    // Slice ID is parts[0]/parts[1] if it exists, else parts[0]
-    const sliceId = parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+    const { milestone, slice } = parseUnitId(u.id);
+    const sliceId = slice ? `${milestone}/${slice}` : milestone;
     let agg = map.get(sliceId);
     if (!agg) {
       agg = { sliceId, units: 0, tokens: emptyTokens(), cost: 0, duration: 0 };

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

@@ -9,6 +9,7 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { externalGsdRoot } from "./repo-identity.js";
+import { getErrorMessage } from "./error-utils.js";
 
 export interface MigrationResult {
   migrated: boolean;
@@ -47,7 +48,7 @@ export function migrateToExternalState(basePath: string): MigrationResult {
       return { migrated: false, error: ".gsd exists but is not a directory or symlink" };
     }
   } catch (err) {
-    return { migrated: false, error: `Cannot stat .gsd: ${err instanceof Error ? err.message : String(err)}` };
+    return { migrated: false, error: `Cannot stat .gsd: ${getErrorMessage(err)}` };
   }
 
   const externalPath = externalGsdRoot(basePath);
@@ -57,8 +58,24 @@ export function migrateToExternalState(basePath: string): MigrationResult {
     // mkdir -p the external dir
     mkdirSync(externalPath, { recursive: true });
 
-    // Rename .gsd -> .gsd.migrating (atomic lock)
-    renameSync(localGsd, migratingPath);
+    // Rename .gsd -> .gsd.migrating (atomic lock).
+    // On Windows, NTFS may reject rename with EPERM if file descriptors are
+    // open (VS Code watchers, antivirus on-access scan). Fall back to
+    // copy+delete (#1292).
+    try {
+      renameSync(localGsd, migratingPath);
+    } catch (renameErr: any) {
+      if (renameErr?.code === "EPERM" || renameErr?.code === "EBUSY") {
+        try {
+          cpSync(localGsd, migratingPath, { recursive: true, force: true });
+          rmSync(localGsd, { recursive: true, force: true });
+        } catch (copyErr) {
+          return { migrated: false, error: `Migration rename/copy failed: ${copyErr instanceof Error ? copyErr.message : String(copyErr)}` };
+        }
+      } else {
+        throw renameErr;
+      }
+    }
 
     // Copy contents to external dir, skipping worktrees/
     const entries = readdirSync(migratingPath, { withFileTypes: true });
@@ -98,7 +115,7 @@ export function migrateToExternalState(basePath: string): MigrationResult {
 
     return {
       migrated: false,
-      error: `Migration failed: ${err instanceof Error ? err.message : String(err)}`,
+      error: `Migration failed: ${getErrorMessage(err)}`,
     };
   }
 }

package/dist/resources/extensions/gsd/milestone-ids.ts

@@ -9,6 +9,7 @@ import { randomInt } from "node:crypto";
 import { readdirSync, existsSync } from "node:fs";
 import { milestonesDir } from "./paths.js";
 import { loadQueueOrder, sortByQueueOrder } from "./queue-order.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Regex ──────────────────────────────────────────────────────────────────
 
@@ -88,7 +89,7 @@ export function findMilestoneIds(basePath: string): string[] {
   } catch (err) {
     // Log why milestone scanning failed — silent [] here causes infinite loops (#456)
     if (existsSync(dir)) {
-      console.error(`[gsd] findMilestoneIds: .gsd/milestones/ exists but readdirSync failed — ${err instanceof Error ? err.message : String(err)}`);
+      console.error(`[gsd] findMilestoneIds: .gsd/milestones/ exists but readdirSync failed — ${getErrorMessage(err)}`);
     }
     return [];
   }

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

@@ -10,6 +10,7 @@ import { existsSync, readFileSync, unlinkSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { GSDError, GSD_GIT_ERROR } from "./errors.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // Issue #453: keep auto-mode bookkeeping on the stable git CLI path unless a
 // caller explicitly opts into the native helper.
@@ -716,7 +717,7 @@ export function nativeCommit(
     try {
       return native.gitCommit(basePath, message, options?.allowEmpty);
     } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
+      const msg = getErrorMessage(e);
       if (msg.includes("nothing to commit")) return null;
       throw e;
     }

package/dist/resources/extensions/gsd/parallel-merge.ts

@@ -11,6 +11,7 @@ import { mergeMilestoneToMain } from "./auto-worktree.js";
 import { MergeConflictError } from "./git-service.js";
 import { removeSessionStatus } from "./session-status-io.js";
 import type { WorkerInfo } from "./parallel-orchestrator.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -99,7 +100,7 @@ export async function mergeCompletedMilestone(
     return {
       milestoneId,
       success: false,
-      error: err instanceof Error ? err.message : String(err),
+      error: getErrorMessage(err),
     };
   }
 }

package/dist/resources/extensions/gsd/parallel-orchestrator.ts

@@ -38,6 +38,7 @@ import {
   analyzeParallelEligibility,
   type ParallelCandidates,
 } from "./parallel-eligibility.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -363,7 +364,7 @@ export async function startParallel(
 
       started.push(mid);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      const message = getErrorMessage(err);
       errors.push({ mid, error: message });
     }
   }

package/dist/resources/extensions/gsd/post-unit-hooks.ts

@@ -15,6 +15,7 @@ import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js"
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
+import { parseUnitId } from "./unit-id.js";
 
 // ─── Hook Queue State ──────────────────────────────────────────────────────
 
@@ -149,7 +150,7 @@ function dequeueNextHook(basePath: string): HookDispatchResult | null {
     };
 
     // Build the prompt with variable substitution
-    const [mid, sid, tid] = triggerUnitId.split("/");
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(triggerUnitId);
     const prompt = config.prompt
       .replace(/\{milestoneId\}/g, mid ?? "")
       .replace(/\{sliceId\}/g, sid ?? "")
@@ -208,16 +209,14 @@ function handleHookCompletion(basePath: string): HookDispatchResult | null {
  *   - Milestone-level (M001):    .gsd/M001/{artifact}
  */
 export function resolveHookArtifactPath(basePath: string, unitId: string, artifactName: string): string {
-  const parts = unitId.split("/");
-  if (parts.length === 3) {
-    const [mid, sid, tid] = parts;
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
+  if (mid && sid && tid) {
     return join(gsdRoot(basePath), mid, "slices", sid, "tasks", `${tid}-${artifactName}`);
   }
-  if (parts.length === 2) {
-    const [mid, sid] = parts;
+  if (mid && sid) {
     return join(gsdRoot(basePath), mid, "slices", sid, artifactName);
   }
-  return join(gsdRoot(basePath), parts[0], artifactName);
+  return join(gsdRoot(basePath), mid, artifactName);
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -253,7 +252,7 @@ export function runPreDispatchHooks(
     return { action: "proceed", prompt, firedHooks: [] };
   }
 
-  const [mid, sid, tid] = unitId.split("/");
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   const substitute = (text: string): string =>
     text
       .replace(/\{milestoneId\}/g, mid ?? "")
@@ -466,7 +465,7 @@ export function triggerHookManually(
   activeHook.cycle = currentCycle;
 
   // Build the prompt with variable substitution
-  const [mid, sid, tid] = unitId.split("/");
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   const prompt = hook.prompt
     .replace(/\{milestoneId\}/g, mid ?? "")
     .replace(/\{sliceId\}/g, sid ?? "")

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

@@ -86,6 +86,14 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "context_selection",
 ]);
 
+/** Canonical list of all dispatch unit types. */
+export const KNOWN_UNIT_TYPES = [
+  "research-milestone", "plan-milestone", "research-slice", "plan-slice",
+  "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
+  "run-uat", "complete-milestone",
+] as const;
+export type UnitType = (typeof KNOWN_UNIT_TYPES)[number];
+
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
 
 export interface GSDSkillRule {

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

@@ -14,6 +14,7 @@ import { normalizeStringArray } from "../shared/mod.js";
 
 import {
   KNOWN_PREFERENCE_KEYS,
+  KNOWN_UNIT_TYPES,
   SKILL_ACTIONS,
   type WorkflowMode,
   type GSDPreferences,
@@ -239,11 +240,7 @@ export function validatePreferences(preferences: GSDPreferences): {
   if (preferences.post_unit_hooks && Array.isArray(preferences.post_unit_hooks)) {
     const validHooks: PostUnitHookConfig[] = [];
     const seenNames = new Set<string>();
-    const knownUnitTypes = new Set([
-      "research-milestone", "plan-milestone", "research-slice", "plan-slice",
-      "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
-      "run-uat", "complete-milestone",
-    ]);
+    const knownUnitTypes = new Set<string>(KNOWN_UNIT_TYPES);
     for (const hook of preferences.post_unit_hooks) {
       if (!hook || typeof hook !== "object") {
         errors.push("post_unit_hooks entry must be an object");
@@ -305,11 +302,7 @@ export function validatePreferences(preferences: GSDPreferences): {
   if (preferences.pre_dispatch_hooks && Array.isArray(preferences.pre_dispatch_hooks)) {
     const validPreHooks: PreDispatchHookConfig[] = [];
     const seenPreNames = new Set<string>();
-    const knownUnitTypes = new Set([
-      "research-milestone", "plan-milestone", "research-slice", "plan-slice",
-      "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
-      "run-uat", "complete-milestone",
-    ]);
+    const knownUnitTypes = new Set<string>(KNOWN_UNIT_TYPES);
     const validActions = new Set(["modify", "skip", "replace"]);
     for (const hook of preferences.pre_dispatch_hooks) {
       if (!hook || typeof hook !== "object") {

package/dist/resources/extensions/gsd/progress-score.ts

@@ -0,0 +1,273 @@
+/**
+ * GSD Progress Score — Traffic Light Status Indicator (#1221)
+ *
+ * Combines existing health signals into a single at-a-glance status:
+ *   - Green: progressing well
+ *   - Yellow: struggling (retries, warnings)
+ *   - Red: stuck (loops, persistent errors, no activity)
+ *
+ * Purely derived — no stored state. Reads from doctor-proactive health
+ * tracking, stuck detection counters, and working-tree activity.
+ */
+
+import {
+  getHealthTrend,
+  getConsecutiveErrorUnits,
+  getHealthHistory,
+  type HealthSnapshot,
+} from "./doctor-proactive.js";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type ProgressLevel = "green" | "yellow" | "red";
+
+export interface ProgressScore {
+  level: ProgressLevel;
+  summary: string;
+  signals: ProgressSignal[];
+}
+
+export interface ProgressSignal {
+  name: string;
+  level: ProgressLevel;
+  detail: string;
+}
+
+// ── Signal Evaluators ──────────────────────────────────────────────────────
+
+function evaluateHealthTrend(): ProgressSignal {
+  const trend = getHealthTrend();
+
+  switch (trend) {
+    case "improving":
+      return { name: "health_trend", level: "green", detail: "Health improving" };
+    case "stable":
+      return { name: "health_trend", level: "green", detail: "Health stable" };
+    case "degrading":
+      return { name: "health_trend", level: "red", detail: "Health degrading" };
+    case "unknown":
+      return { name: "health_trend", level: "green", detail: "Insufficient data" };
+  }
+}
+
+function evaluateErrorStreak(): ProgressSignal {
+  const streak = getConsecutiveErrorUnits();
+
+  if (streak === 0) {
+    return { name: "error_streak", level: "green", detail: "No consecutive errors" };
+  }
+  if (streak <= 2) {
+    return { name: "error_streak", level: "yellow", detail: `${streak} consecutive error unit(s)` };
+  }
+  return { name: "error_streak", level: "red", detail: `${streak} consecutive error units` };
+}
+
+function evaluateRecentErrors(): ProgressSignal {
+  const history = getHealthHistory();
+  if (history.length === 0) {
+    return { name: "recent_errors", level: "green", detail: "No health data yet" };
+  }
+
+  const latest = history[history.length - 1]!;
+
+  if (latest.errors === 0 && latest.warnings <= 1) {
+    return { name: "recent_errors", level: "green", detail: `${latest.errors}E/${latest.warnings}W` };
+  }
+  if (latest.errors === 0) {
+    return { name: "recent_errors", level: "yellow", detail: `${latest.warnings} warning(s)` };
+  }
+  if (latest.errors <= 2) {
+    return { name: "recent_errors", level: "yellow", detail: `${latest.errors} error(s), ${latest.warnings} warning(s)` };
+  }
+  return { name: "recent_errors", level: "red", detail: `${latest.errors} error(s), ${latest.warnings} warning(s)` };
+}
+
+function evaluateArtifactProduction(): ProgressSignal {
+  const history = getHealthHistory();
+  if (history.length < 2) {
+    return { name: "artifact_production", level: "green", detail: "Insufficient data" };
+  }
+
+  const totalFixes = history.reduce((sum, s) => sum + s.fixesApplied, 0);
+  const recent = history.slice(-3);
+  const recentFixes = recent.reduce((sum, s) => sum + s.fixesApplied, 0);
+
+  // If recent units are all producing fixes but errors aren't decreasing,
+  // doctor is fighting fires but not making headway
+  if (recentFixes > 3 && recent.every(s => s.errors > 0)) {
+    return { name: "artifact_production", level: "yellow", detail: "Doctor applying fixes but errors persist" };
+  }
+
+  return { name: "artifact_production", level: "green", detail: `${totalFixes} total fixes applied` };
+}
+
+function evaluateDispatchVelocity(): ProgressSignal {
+  const history = getHealthHistory();
+  if (history.length < 3) {
+    return { name: "dispatch_velocity", level: "green", detail: "Insufficient data" };
+  }
+
+  // Check time between recent snapshots — are units completing at a reasonable rate?
+  const recent = history.slice(-5);
+  if (recent.length < 2) {
+    return { name: "dispatch_velocity", level: "green", detail: "Insufficient data" };
+  }
+
+  const timeDiffs: number[] = [];
+  for (let i = 1; i < recent.length; i++) {
+    timeDiffs.push(recent[i]!.timestamp - recent[i - 1]!.timestamp);
+  }
+
+  const avgTimeMs = timeDiffs.reduce((a, b) => a + b, 0) / timeDiffs.length;
+  const avgTimeMins = Math.round(avgTimeMs / 60_000);
+
+  // If average unit time is > 15 minutes, something might be wrong
+  if (avgTimeMins > 15) {
+    return { name: "dispatch_velocity", level: "yellow", detail: `Units averaging ${avgTimeMins}min each` };
+  }
+
+  return { name: "dispatch_velocity", level: "green", detail: `Units averaging ${avgTimeMins || "<1"}min each` };
+}
+
+// ── Main API ───────────────────────────────────────────────────────────────
+
+/**
+ * Compute the current progress score by evaluating all available signals.
+ * Returns a composite score with individual signal details.
+ */
+export function computeProgressScore(): ProgressScore {
+  const signals: ProgressSignal[] = [
+    evaluateHealthTrend(),
+    evaluateErrorStreak(),
+    evaluateRecentErrors(),
+    evaluateArtifactProduction(),
+    evaluateDispatchVelocity(),
+  ];
+
+  // Overall level: worst of all signals
+  const level = signals.some(s => s.level === "red")
+    ? "red"
+    : signals.some(s => s.level === "yellow")
+      ? "yellow"
+      : "green";
+
+  // Build summary from the most important signals
+  const summary = buildSummary(level, signals);
+
+  return { level, summary, signals };
+}
+
+/**
+ * Compute progress score with additional context from the current unit.
+ */
+export function computeProgressScoreWithContext(context: {
+  currentUnitType?: string;
+  currentUnitId?: string;
+  completedUnits?: number;
+  totalUnits?: number;
+  retryCount?: number;
+  maxRetries?: number;
+}): ProgressScore {
+  const base = computeProgressScore();
+
+  // Add retry signal if available
+  if (context.retryCount !== undefined && context.maxRetries !== undefined) {
+    const retrySignal: ProgressSignal = context.retryCount === 0
+      ? { name: "retry_count", level: "green", detail: "No retries" }
+      : context.retryCount <= 2
+        ? { name: "retry_count", level: "yellow", detail: `Retry ${context.retryCount}/${context.maxRetries}` }
+        : { name: "retry_count", level: "red", detail: `Retry ${context.retryCount}/${context.maxRetries} — looping` };
+
+    base.signals.push(retrySignal);
+
+    // Re-evaluate level
+    if (retrySignal.level === "red") base.level = "red";
+    else if (retrySignal.level === "yellow" && base.level === "green") base.level = "yellow";
+  }
+
+  // Build richer summary with context
+  base.summary = buildSummaryWithContext(base.level, base.signals, context);
+
+  return base;
+}
+
+// ── Formatting ─────────────────────────────────────────────────────────────
+
+function buildSummary(level: ProgressLevel, signals: ProgressSignal[]): string {
+  switch (level) {
+    case "green":
+      return "Progressing well";
+    case "yellow": {
+      const issues = signals.filter(s => s.level === "yellow").map(s => s.detail);
+      return `Struggling — ${issues[0] ?? "minor issues detected"}`;
+    }
+    case "red": {
+      const issues = signals.filter(s => s.level === "red").map(s => s.detail);
+      return `Stuck — ${issues[0] ?? "critical issues detected"}`;
+    }
+  }
+}
+
+function buildSummaryWithContext(
+  level: ProgressLevel,
+  signals: ProgressSignal[],
+  context: {
+    currentUnitType?: string;
+    currentUnitId?: string;
+    completedUnits?: number;
+    totalUnits?: number;
+    retryCount?: number;
+    maxRetries?: number;
+  },
+): string {
+  const unitLabel = context.currentUnitId
+    ? ` ${context.currentUnitId}`
+    : "";
+  const progressLabel = context.completedUnits !== undefined && context.totalUnits !== undefined
+    ? ` (${context.completedUnits} of ${context.totalUnits} done)`
+    : "";
+
+  switch (level) {
+    case "green":
+      return `Progressing well —${unitLabel}${progressLabel}`;
+    case "yellow": {
+      const issues = signals.filter(s => s.level === "yellow").map(s => s.detail);
+      const retryInfo = context.retryCount ? `, attempt ${context.retryCount}/${context.maxRetries}` : "";
+      return `Struggling —${unitLabel}${retryInfo}${progressLabel ? ` ${progressLabel}` : ""}, ${issues[0] ?? "issues detected"}`;
+    }
+    case "red": {
+      const issues = signals.filter(s => s.level === "red").map(s => s.detail);
+      return `Stuck —${unitLabel}${progressLabel ? ` ${progressLabel}` : ""}, ${issues[0] ?? "critical issues"}`;
+    }
+  }
+}
+
+/**
+ * Format progress score as a single-line traffic light for TUI display.
+ */
+export function formatProgressLine(score: ProgressScore): string {
+  const icon = score.level === "green" ? "\uD83D\uDFE2"
+    : score.level === "yellow" ? "\uD83D\uDFE1"
+      : "\uD83D\uDD34";
+  return `${icon} ${score.summary}`;
+}
+
+/**
+ * Format a detailed progress report showing all signals.
+ */
+export function formatProgressReport(score: ProgressScore): string {
+  const lines: string[] = [];
+
+  lines.push(formatProgressLine(score));
+  lines.push("");
+  lines.push("Signals:");
+
+  for (const signal of score.signals) {
+    const icon = signal.level === "green" ? "\u2705"
+      : signal.level === "yellow" ? "\u26A0\uFE0F"
+        : "\uD83D\uDED1";
+    lines.push(`  ${icon} ${signal.name}: ${signal.detail}`);
+  }
+
+  return lines.join("\n");
+}