gsd-pi 2.50.0 → 2.51.0-dev.7d435fe

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

@@ -70,6 +70,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "service_tier",
     "forensics_dedup",
     "show_token_cost",
+    "experimental",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [

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

@@ -823,5 +823,30 @@ export function validatePreferences(preferences) {
             errors.push("show_token_cost must be a boolean");
         }
     }
+    // ─── Experimental Features ────────────────────────────────────────
+    if (preferences.experimental !== undefined) {
+        if (typeof preferences.experimental === "object" && preferences.experimental !== null) {
+            const exp = preferences.experimental;
+            const validExp = {};
+            if (exp.rtk !== undefined) {
+                if (typeof exp.rtk === "boolean")
+                    validExp.rtk = exp.rtk;
+                else
+                    errors.push("experimental.rtk must be a boolean");
+            }
+            const knownExpKeys = new Set(["rtk"]);
+            for (const key of Object.keys(exp)) {
+                if (!knownExpKeys.has(key)) {
+                    warnings.push(`unknown experimental key "${key}" — ignored`);
+                }
+            }
+            if (Object.keys(validExp).length > 0) {
+                validated.experimental = validExp;
+            }
+        }
+        else {
+            errors.push("experimental must be an object");
+        }
+    }
     return { preferences: validated, errors, warnings };
 }

package/dist/resources/extensions/gsd/preferences.js

@@ -24,27 +24,27 @@ export { validatePreferences } from "./preferences-validation.js";
 // ─── Re-exports: skills ─────────────────────────────────────────────────────
 export { resolveAllSkillReferences, resolveSkillDiscoveryMode, resolveSkillStalenessDays, } from "./preferences-skills.js";
 // ─── Re-exports: models ─────────────────────────────────────────────────────
-export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, isTransientNetworkError, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, resolveEffectiveProfile, resolveInlineLevel, resolveContextSelection, resolveSearchProviderFromPreferences, } from "./preferences-models.js";
+export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, resolveEffectiveProfile, resolveInlineLevel, resolveContextSelection, resolveSearchProviderFromPreferences, } from "./preferences-models.js";
 // ─── Path Constants & Getters ───────────────────────────────────────────────
 function gsdHome() {
     return process.env.GSD_HOME || join(homedir(), ".gsd");
 }
 function globalPreferencesPath() {
-    return join(gsdHome(), "preferences.md");
+    return join(gsdHome(), "PREFERENCES.md");
 }
 function legacyGlobalPreferencesPath() {
     return join(homedir(), ".pi", "agent", "gsd-preferences.md");
 }
 function projectPreferencesPath() {
-    return join(gsdRoot(process.cwd()), "preferences.md");
+    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
 }
-// Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake.
-// Check uppercase as a fallback so those files aren't silently ignored.
-function globalPreferencesPathUppercase() {
-    return join(gsdHome(), "PREFERENCES.md");
+// Legacy: older versions used lowercase preferences.md.
+// Check lowercase as a fallback so those files aren't silently ignored.
+function globalPreferencesPathLegacy() {
+    return join(gsdHome(), "preferences.md");
 }
-function projectPreferencesPathUppercase() {
-    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+function projectPreferencesPathLegacy() {
+    return join(gsdRoot(process.cwd()), "preferences.md");
 }
 export function getGlobalGSDPreferencesPath() {
     return globalPreferencesPath();
@@ -58,12 +58,12 @@ export function getProjectGSDPreferencesPath() {
 // ─── Loading ────────────────────────────────────────────────────────────────
 export function loadGlobalGSDPreferences() {
     return loadPreferencesFile(globalPreferencesPath(), "global")
-        ?? loadPreferencesFile(globalPreferencesPathUppercase(), "global")
+        ?? loadPreferencesFile(globalPreferencesPathLegacy(), "global")
         ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
 export function loadProjectGSDPreferences() {
     return loadPreferencesFile(projectPreferencesPath(), "project")
-        ?? loadPreferencesFile(projectPreferencesPathUppercase(), "project");
+        ?? loadPreferencesFile(projectPreferencesPathLegacy(), "project");
 }
 export function loadEffectiveGSDPreferences() {
     const globalPreferences = loadGlobalGSDPreferences();
@@ -149,7 +149,7 @@ export function parsePreferencesMarkdown(content) {
     }
     if (!_warnedUnrecognizedFormat) {
         _warnedUnrecognizedFormat = true;
-        console.warn("[parsePreferencesMarkdown] preferences.md exists but uses an unrecognized format — skipping.");
+        console.warn("[parsePreferencesMarkdown] PREFERENCES.md exists but uses an unrecognized format — skipping.");
     }
     return null;
 }
@@ -275,6 +275,9 @@ function mergePreferences(base, override) {
         service_tier: override.service_tier ?? base.service_tier,
         forensics_dedup: override.forensics_dedup ?? base.forensics_dedup,
         show_token_cost: override.show_token_cost ?? base.show_token_cost,
+        experimental: (base.experimental || override.experimental)
+            ? { ...(base.experimental ?? {}), ...(override.experimental ?? {}) }
+            : undefined,
     };
 }
 function mergeStringLists(base, override) {
@@ -395,7 +398,7 @@ export function resolvePreDispatchHooks() {
  * Resolve the effective git isolation mode from preferences.
  * Returns "none" (default), "worktree", or "branch".
  *
- * Default is "none" so GSD works out of the box without preferences.md.
+ * Default is "none" so GSD works out of the box without PREFERENCES.md.
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */

package/dist/resources/extensions/gsd/prompts/forensics.md

@@ -142,11 +142,10 @@ Then **offer GitHub issue creation**: "Would you like me to create a GitHub issu
 If yes, create using the `bash` tool:
 
 ```bash
-# Step 1: Create issue (use labels for metadata, NOT for classification — type is set via GraphQL)
-ISSUE_URL=$(gh issue create --repo gsd-build/gsd-2 \
-  --title "..." \
-  --label "auto-generated" \
-  --body "$(cat <<'EOF'
+# Step 1: Write issue body to a temp file to avoid escaping/truncation issues.
+# Using --body-file bypasses shell quoting entirely — backticks, quotes, and
+# content containing "EOF" all render correctly. (#2465)
+cat > /tmp/gsd-forensic-issue.md << 'GSD_ISSUE_BODY'
 ## Problem
 [1-2 sentence summary]
 
@@ -169,8 +168,13 @@ ISSUE_URL=$(gh issue create --repo gsd-build/gsd-2 \
 
 ---
 *Auto-generated by `/gsd forensics`*
-EOF
-)")
+GSD_ISSUE_BODY
+
+ISSUE_URL=$(gh issue create --repo gsd-build/gsd-2 \
+  --title "..." \
+  --label "auto-generated" \
+  --body-file /tmp/gsd-forensic-issue.md)
+rm -f /tmp/gsd-forensic-issue.md
 
 # Step 2: Set issue type via GraphQL (gh issue create has no --type flag)
 ISSUE_NUM=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')

package/dist/resources/extensions/gsd/prompts/system.md

@@ -92,7 +92,7 @@ Titles live inside file content (headings, frontmatter), not in file or director
 
 ### Isolation Model
 
-Auto-mode supports three isolation modes (configured in `.gsd/preferences.md` under `taskIsolation.mode`):
+Auto-mode supports three isolation modes (configured in `.gsd/PREFERENCES.md` under `taskIsolation.mode`):
 
 - **worktree** (default): Work happens in `.gsd/worktrees/<MID>/`, a full git worktree on the `milestone/<MID>` branch. Each worktree has its own working copy and `.gsd/` directory. Squash-merged back to the integration branch on milestone completion.
 - **branch**: Work happens in the project root on a `milestone/<MID>` branch. No worktree directory — files are checked out in-place.

package/dist/resources/extensions/gsd/prompts/validate-milestone.md

@@ -24,7 +24,12 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 2. For each **slice** in the roadmap, verify its demo/deliverable claim against its summary. Flag any slice whose summary does not substantiate its claimed output.
 3. Check **cross-slice integration points** — do boundary map entries (produces/consumes) align with what was actually built?
 4. Check **requirement coverage** — are all active requirements addressed by at least one slice?
-5. Determine a verdict:
+5. If **Verification Classes** are provided in the inlined context above, check each non-empty class:
+   - For each verification class (Contract, Integration, Operational, UAT), determine whether slice summaries, UAT results, or observable behavior provide evidence that this verification tier was addressed.
+   - Document the compliance status of each class in your verdict rationale.
+   - If `Operational` verification is non-empty and no evidence of operational verification exists, flag this explicitly — it means planned operational checks (migrations, deployments, runtime verification) were not proven.
+   - A milestone with unaddressed verification classes may still pass if the gaps are minor, but the gaps MUST be documented in the Deferred Work Inventory.
+6. Determine a verdict:
    - `pass` — all criteria met, all slices delivered, no gaps
    - `needs-attention` — minor gaps that do not block completion (document them)
    - `needs-remediation` — material gaps found; remediation slices must be added to the roadmap

package/dist/resources/extensions/gsd/provider-error-pause.js

@@ -1,39 +1,3 @@
-/**
- * Classify a provider error as transient (auto-resume) or permanent (manual resume).
- *
- * Transient: rate limits, server errors (500/502/503), overloaded, internal errors.
- * These are expected to self-resolve and should auto-resume after a delay.
- *
- * Permanent: auth errors, invalid API key, billing issues.
- * These require user intervention and should pause indefinitely.
- */
-export function classifyProviderError(errorMsg) {
-    const isRateLimit = /rate.?limit|too many requests|429/i.test(errorMsg);
-    const isServerError = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i.test(errorMsg);
-    // Connection/process errors — transient, auto-resume after brief backoff (#2309).
-    // These indicate the process was killed, the connection was reset, or a network
-    // blip occurred. They are NOT permanent failures.
-    const isConnectionError = /terminated|connection.?reset|connection.?refused|other side closed|fetch failed|network.?(?:is\s+)?unavailable|ECONNREFUSED|ECONNRESET|EPIPE/i.test(errorMsg);
-    // Permanent errors — never auto-resume
-    const isPermanent = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i.test(errorMsg);
-    if (isPermanent && !isRateLimit) {
-        return { isTransient: false, isRateLimit: false, suggestedDelayMs: 0 };
-    }
-    if (isRateLimit) {
-        // Try to extract retry-after from the message
-        const resetMatch = errorMsg.match(/reset in (\d+)s/i);
-        const delayMs = resetMatch ? Number(resetMatch[1]) * 1000 : 60_000; // default 60s for rate limits
-        return { isTransient: true, isRateLimit: true, suggestedDelayMs: delayMs };
-    }
-    if (isServerError) {
-        return { isTransient: true, isRateLimit: false, suggestedDelayMs: 30_000 }; // 30s for server errors
-    }
-    if (isConnectionError) {
-        return { isTransient: true, isRateLimit: false, suggestedDelayMs: 15_000 }; // 15s for connection errors
-    }
-    // Unknown error — treat as permanent (user reviews)
-    return { isTransient: false, isRateLimit: false, suggestedDelayMs: 0 };
-}
 /**
  * Pause auto-mode due to a provider error.
  *

package/dist/resources/extensions/gsd/roadmap-mutations.js

@@ -0,0 +1,110 @@
+/**
+ * Roadmap Mutations — shared utilities for modifying roadmap checkbox state.
+ *
+ * Extracts the duplicated "flip slice checkbox" pattern that existed in
+ * doctor.ts, mechanical-completion.ts, and auto-recovery.ts.
+ */
+import { readFileSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { clearParseCache } from "./files.js";
+/**
+ * Mark a slice as done ([x]) in the milestone roadmap.
+ * Idempotent — no-op if already checked or if the slice isn't found.
+ *
+ * @returns true if the roadmap was modified, false if no change was needed
+ */
+export function markSliceDoneInRoadmap(basePath, mid, sid) {
+    const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+    if (!roadmapFile)
+        return false;
+    let content;
+    try {
+        content = readFileSync(roadmapFile, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    // Try checkbox format first: "- [ ] **S01: Title**"
+    let updated = content.replace(new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${sid}:`, "m"), `$1[x] **${sid}:`);
+    // If checkbox format didn't match, try prose format: "## S01: Title" -> "## S01: \u2713 Title"
+    if (updated === content) {
+        updated = content.replace(new RegExp(`^(#{1,4}\\s+(?:\\*{0,2})(?:Slice\\s+)?${sid}\\*{0,2}[:\\s.\\u2014\\u2013-]+\\s*)(.+)`, "m"), (match, prefix, title) => {
+            // Already marked done — no-op
+            if (/^\u2713/.test(title) || /\(Complete\)\s*$/i.test(title))
+                return match;
+            return `${prefix}\u2713 ${title}`;
+        });
+    }
+    if (updated === content)
+        return false;
+    atomicWriteSync(roadmapFile, updated);
+    clearParseCache();
+    return true;
+}
+/**
+ * Mark a slice as not done ([ ]) in the milestone roadmap.
+ * Idempotent — no-op if already unchecked or if the slice isn't found.
+ *
+ * @returns true if the roadmap was modified, false if no change was needed
+ */
+export function markSliceUndoneInRoadmap(basePath, mid, sid) {
+    const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+    if (!roadmapFile)
+        return false;
+    let content;
+    try {
+        content = readFileSync(roadmapFile, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const updated = content.replace(new RegExp(`^(\\s*-\\s+)\\[x\\]\\s+\\*\\*${sid}:`, "m"), `$1[ ] **${sid}:`);
+    if (updated === content)
+        return false;
+    atomicWriteSync(roadmapFile, updated);
+    clearParseCache();
+    return true;
+}
+/**
+ * Mark a task as done ([x]) in the slice plan.
+ * Idempotent — no-op if already checked or if the task isn't found.
+ *
+ * @returns true if the plan was modified, false if no change was needed
+ */
+export function markTaskDoneInPlan(basePath, planPath, tid) {
+    let content;
+    try {
+        content = readFileSync(planPath, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const updated = content.replace(new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"), `$1[x] **${tid}:`);
+    if (updated === content)
+        return false;
+    atomicWriteSync(planPath, updated);
+    clearParseCache();
+    return true;
+}
+/**
+ * Mark a task as not done ([ ]) in the slice plan.
+ * Idempotent — no-op if already unchecked or if the task isn't found.
+ *
+ * @returns true if the plan was modified, false if no change was needed
+ */
+export function markTaskUndoneInPlan(basePath, planPath, tid) {
+    let content;
+    try {
+        content = readFileSync(planPath, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const updated = content.replace(new RegExp(`^(\\s*-\\s+)\\[x\\]\\s+\\*\\*${tid}:`, "mi"), `$1[ ] **${tid}:`);
+    if (updated === content)
+        return false;
+    atomicWriteSync(planPath, updated);
+    clearParseCache();
+    return true;
+}

package/dist/resources/extensions/gsd/rtk-status.js

@@ -0,0 +1,43 @@
+import { ensureRtkSessionBaseline, formatRtkSavingsLabel, getRtkSessionSavings, } from "../shared/rtk-session-stats.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+const STATUS_KEY = "gsd-rtk";
+const REFRESH_INTERVAL_MS = 30_000;
+let refreshTimer = null;
+function clearTimer() {
+    if (refreshTimer) {
+        clearInterval(refreshTimer);
+        refreshTimer = null;
+    }
+}
+function isRtkEnabledInPrefs() {
+    return loadEffectiveGSDPreferences()?.preferences.experimental?.rtk === true;
+}
+function updateStatus(ctx) {
+    if (!ctx.hasUI)
+        return;
+    if (!isRtkEnabledInPrefs())
+        return;
+    const basePath = ctx.cwd;
+    const sessionId = ctx.sessionManager.getSessionId();
+    ensureRtkSessionBaseline(basePath, sessionId);
+    const savings = getRtkSessionSavings(basePath, sessionId);
+    ctx.ui.setStatus(STATUS_KEY, formatRtkSavingsLabel(savings) ?? undefined);
+}
+export function startRtkStatusUpdates(ctx) {
+    clearTimer();
+    if (!isRtkEnabledInPrefs()) {
+        // Ensure any previously set status is cleared (e.g. preference was toggled off)
+        ctx.ui.setStatus(STATUS_KEY, undefined);
+        return;
+    }
+    updateStatus(ctx);
+    if (!ctx.hasUI)
+        return;
+    refreshTimer = setInterval(() => {
+        updateStatus(ctx);
+    }, REFRESH_INTERVAL_MS);
+}
+export function stopRtkStatusUpdates(ctx) {
+    clearTimer();
+    ctx?.ui.setStatus(STATUS_KEY, undefined);
+}

package/dist/resources/extensions/gsd/rule-registry.js

@@ -8,18 +8,17 @@
 import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { parseUnitId } from "./unit-id.js";
 // ─── Artifact Path Resolution ──────────────────────────────────────────────
 export function resolveHookArtifactPath(basePath, unitId, artifactName) {
-    const parts = unitId.split("/");
-    if (parts.length === 3) {
-        const [mid, sid, tid] = parts;
-        return join(basePath, ".gsd", "milestones", mid, "slices", sid, "tasks", `${tid}-${artifactName}`);
+    const { milestone, slice, task } = parseUnitId(unitId);
+    if (task !== undefined && slice !== undefined) {
+        return join(basePath, ".gsd", "milestones", milestone, "slices", slice, "tasks", `${task}-${artifactName}`);
     }
-    if (parts.length === 2) {
-        const [mid, sid] = parts;
-        return join(basePath, ".gsd", "milestones", mid, "slices", sid, artifactName);
+    if (slice !== undefined) {
+        return join(basePath, ".gsd", "milestones", milestone, "slices", slice, artifactName);
     }
-    return join(basePath, ".gsd", "milestones", parts[0], artifactName);
+    return join(basePath, ".gsd", "milestones", milestone, artifactName);
 }
 // ─── Dispatch Rule Conversion ──────────────────────────────────────────────
 /**
@@ -163,7 +162,7 @@ export class RuleRegistry {
                 pendingRetry: false,
             };
             // Build prompt with variable substitution
-            const [mid, sid, tid] = triggerUnitId.split("/");
+            const { milestone: mid, slice: sid, task: tid } = parseUnitId(triggerUnitId);
             let prompt = config.prompt
                 .replace(/\{milestoneId\}/g, mid ?? "")
                 .replace(/\{sliceId\}/g, sid ?? "")
@@ -224,7 +223,7 @@ export class RuleRegistry {
         if (hooks.length === 0) {
             return { action: "proceed", prompt, firedHooks: [] };
         }
-        const [mid, sid, tid] = unitId.split("/");
+        const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
         const substitute = (text) => text
             .replace(/\{milestoneId\}/g, mid ?? "")
             .replace(/\{sliceId\}/g, sid ?? "")
@@ -410,7 +409,7 @@ export class RuleRegistry {
         const currentCycle = (this.cycleCounts.get(cycleKey) ?? 0) + 1;
         this.cycleCounts.set(cycleKey, currentCycle);
         this.activeHook.cycle = currentCycle;
-        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 ?? "")
@@ -427,7 +426,7 @@ export class RuleRegistry {
     formatHookStatus() {
         const entries = this.getHookStatus();
         if (entries.length === 0) {
-            return "No hooks configured. Add post_unit_hooks or pre_dispatch_hooks to .gsd/preferences.md";
+            return "No hooks configured. Add post_unit_hooks or pre_dispatch_hooks to .gsd/PREFERENCES.md";
         }
         const lines = ["Configured Hooks:", ""];
         const postHooks = entries.filter(e => e.type === "post");

package/dist/resources/extensions/gsd/service-tier.js

@@ -13,16 +13,27 @@ import { getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences, loadGlobalGSD
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
 const SERVICE_TIER_SCOPE_NOTE = "Only affects gpt-5.4 models, regardless of provider.";
 // ─── Gating ──────────────────────────────────────────────────────────────────
+/**
+ * Model ID prefixes (bare, without provider) that support OpenAI service tiers.
+ *
+ * This list is the fallback for callers that only have a model ID string.
+ * The authoritative source of truth is `model.capabilities.supportsServiceTier`
+ * (set via CAPABILITY_PATCHES in packages/pi-ai/src/models.ts). When callers
+ * have access to the full Model object, prefer reading capabilities directly.
+ *
+ * See: https://github.com/gsd-build/gsd-2/issues/2546
+ */
+const SERVICE_TIER_MODEL_PREFIXES = ["gpt-5.4"];
 /**
  * Returns true when the given model ID supports OpenAI service tiers.
- * Currently only gpt-5.4 variants qualify.
+ * Reads from SERVICE_TIER_MODEL_PREFIXES — update that list, not this function.
  */
 export function supportsServiceTier(modelId) {
     if (!modelId)
         return false;
     // Strip provider prefix if present (e.g. "openai/gpt-5.4" → "gpt-5.4")
     const bare = modelId.includes("/") ? modelId.split("/").pop() : modelId;
-    return bare.startsWith("gpt-5.4");
+    return SERVICE_TIER_MODEL_PREFIXES.some((prefix) => bare.startsWith(prefix));
 }
 // ─── Status Formatting ───────────────────────────────────────────────────────
 /**

package/dist/resources/extensions/gsd/session-forensics.js

@@ -363,9 +363,13 @@ function formatTraceSummary(trace) {
     if (trace.errors.length > 0) {
         parts.push(`Errors: ${trace.errors.slice(-3).join("; ")}`);
     }
-    if (trace.lastReasoning) {
-        parts.push(`Last reasoning: "${trace.lastReasoning}"`);
-    }
+    // NOTE: lastReasoning is intentionally excluded from the retry diagnostic.
+    // This summary is injected into retry prompts via getDeepDiagnostic() →
+    // phases.ts. Including prior assistant free-text causes hallucination loops
+    // when the previous turn was truncated or malformed. Crash recovery has its
+    // own path (formatCrashRecoveryBriefing) that handles lastReasoning safely
+    // with explicit "Last Agent Reasoning Before Interruption" framing.
+    // See: https://github.com/gsd-build/gsd-2/issues/2195
     return parts.join("\n");
 }
 // ─── Helpers ──────────────────────────────────────────────────────────────────