@goodandready/dsh-goal 0.2.30 → 0.2.32

package/lib/client.js

@@ -1808,9 +1808,200 @@ window.__ModuleLoader__.load({
         background: var(--dsw-alias-bg-layer-2);
         font-family: monospace;
       }
-
+      .dsh-goal-tabs {
+        display: flex;
+        gap: 8px;
+        border-bottom: 1px solid var(--dsw-alias-border-l1);
+        margin: 10px 0 14px 0;
+        padding-bottom: 6px;
+      }
+      .dsh-goal-tab-btn {
+        background: transparent;
+        border: none;
+        font-size: 13px;
+        font-weight: 500;
+        color: var(--dsw-alias-label-secondary);
+        cursor: pointer;
+        padding: 6px 12px;
+        border-radius: 6px;
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        transition: all 0.15s ease;
+      }
+      .dsh-goal-tab-btn:hover {
+        color: var(--dsw-alias-label-primary);
+        background: var(--dsw-alias-bg-layer-2);
+      }
+      .dsh-goal-tab-btn.active {
+        color: var(--dsw-alias-brand-primary);
+        background: var(--dsw-alias-bg-layer-2);
+        font-weight: 600;
+      }
+      .dsh-goal-diff-box {
+        display: flex;
+        flex-direction: column;
+        gap: 10px;
+      }
+      .dsh-goal-diff-summary {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        background: var(--dsw-alias-bg-sunken);
+        border: 1px solid var(--dsw-alias-border-l1);
+        border-radius: 6px;
+        padding: 8px 12px;
+        font-size: 12px;
+      }
+      .dsh-goal-diff-stat-pill {
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        font-weight: 600;
+      }
+      .dsh-goal-diff-ins {
+        color: var(--dsw-alias-state-success-primary);
+      }
+      .dsh-goal-diff-del {
+        color: var(--dsw-alias-state-danger-primary);
+      }
+      .dsh-goal-diff-files-list {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 6px;
+        max-height: 100px;
+        overflow-y: auto;
+      }
+      .dsh-goal-diff-file-chip {
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        background: var(--dsw-alias-bg-layer-2);
+        border: 1px solid var(--dsw-alias-border-l1);
+        border-radius: 4px;
+        padding: 3px 8px;
+        font-size: 11px;
+        font-family: monospace;
+        cursor: pointer;
+        color: var(--dsw-alias-label-secondary);
+      }
+      .dsh-goal-diff-file-chip:hover,
+      .dsh-goal-diff-file-chip.active {
+        border-color: var(--dsw-alias-brand-primary);
+        color: var(--dsw-alias-label-primary);
+      }
+      .dsh-goal-diff-viewer {
+        background: var(--dsw-alias-bg-sunken);
+        border: 1px solid var(--dsw-alias-border-l1);
+        border-radius: 6px;
+        padding: 10px;
+        font-family: monospace;
+        font-size: 12px;
+        line-height: 1.45;
+        max-height: 380px;
+        overflow: auto;
+        white-space: pre-wrap;
+        word-break: break-all;
+      }
+      .dsh-goal-diff-line {
+        display: block;
+        padding: 1px 4px;
+        border-radius: 2px;
+      }
+      .dsh-goal-diff-line-add {
+        background: var(--dsw-alias-state-success-bg, var(--dsw-alias-bg-hover));
+        color: var(--dsw-alias-state-success-primary);
+      }
+      .dsh-goal-diff-line-del {
+        background: var(--dsw-alias-state-error-bg, var(--dsw-alias-bg-hover));
+        color: var(--dsw-alias-state-danger-primary);
+      }
+      .dsh-goal-diff-line-hunk {
+        background: var(--dsw-alias-bg-layer-2);
+        color: var(--dsw-alias-state-info-primary);
+      }
+      .dsh-goal-diff-line-header {
+        color: var(--dsw-alias-label-tertiary);
+        font-weight: 600;
+      }
+      .dsh-goal-diff-empty {
+        padding: 24px;
+        text-align: center;
+        color: var(--dsw-alias-label-secondary);
+        font-size: 13px;
+      }
+      /* Sub-goals and Compaction (Issue 167 and Issue 170) */
+      .dsh-goal-badge-subgoal {
+        background: var(--dsw-alias-brand-bg, var(--dsw-alias-bg-hover));
+        color: var(--dsw-alias-brand-primary, var(--dsw-alias-text-primary));
+        border: 1px solid var(--dsw-alias-brand-border, var(--dsw-alias-border));
+      }
+      .dsh-goal-breadcrumbs {
+        display: inline-flex;
+        align-items: center;
+        gap: 4px;
+        font-size: 13px;
+        color: var(--dsw-alias-label-secondary);
+      }
+      .dsh-goal-breadcrumb-item {
+        color: var(--dsw-alias-label-secondary);
+      }
+      .dsh-goal-breadcrumb-item.active {
+        color: var(--dsw-alias-text-primary);
+        font-weight: 600;
+      }
+      .dsh-goal-crumb-sep {
+        color: var(--dsw-alias-label-tertiary);
+        margin: 0 2px;
+      }
+      .dsh-goal-subgoals-box {
+        display: flex;
+        flex-direction: column;
+        gap: 10px;
+        padding: 4px 0;
+      }
+      .dsh-goal-subgoals-list {
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+      }
+      .dsh-goal-subgoal-card {
+        background: var(--dsw-alias-bg-layer-2, var(--dsw-alias-bg-hover));
+        border: 1px solid var(--dsw-alias-border);
+        border-radius: 6px;
+        padding: 10px 12px;
+        display: flex;
+        flex-direction: column;
+        gap: 4px;
+      }
+      .dsh-goal-subgoal-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 8px;
+      }
+      .dsh-goal-subgoal-title {
+        font-weight: 600;
+        font-size: 13px;
+        color: var(--dsw-alias-text-primary);
+      }
+      .dsh-goal-subgoal-summary {
+        font-size: 12px;
+        color: var(--dsw-alias-label-secondary);
+      }
+      .dsh-goal-compacted-pill {
+        display: inline-flex;
+        align-items: center;
+        gap: 3px;
+        font-size: 10px;
+        padding: 1px 5px;
+        border-radius: 3px;
+        background: var(--dsw-alias-bg-layer-2, var(--dsw-alias-bg-hover));
+        color: var(--dsw-alias-state-success-primary, var(--dsw-alias-text-secondary));
+        border: 1px solid var(--dsw-alias-border);
+        margin-left: 6px;
+      }
     `;
-
     function injectStylesOnce() {
 
       if (typeof document === 'undefined') return;
@@ -2103,6 +2294,193 @@ window.__ModuleLoader__.load({
       const [interveneText, setInterveneText] = useState('');
 
       const [interveneSent, setInterveneSent] = useState(false);
+      const [activeTab, setActiveTab] = useState("overview");
+      const [diffData, setDiffData] = useState(null);
+      const [diffLoading, setDiffLoading] = useState(false);
+      const [diffError, setDiffError] = useState(null);
+      const [selectedFile, setSelectedFile] = useState(null);
+
+      const fetchDiff = useCallback(() => {
+        setDiffLoading(true);
+        setDiffError(null);
+        const sid = state.sessionId || "default";
+        const url = "/dsh-goal/diff?sessionId=" + encodeURIComponent(sid);
+        if (typeof fetch === "function") {
+          fetch(url)
+            .then((res) => {
+              if (!res.ok) throw new Error("HTTP " + res.status);
+              return res.json();
+            })
+            .then((data) => {
+              if (data && data.ok) {
+                setDiffData(data);
+              } else {
+                setDiffError((data && data.error) || "Failed to load diff");
+              }
+            })
+            .catch((err) => {
+              setDiffError(err.message || "Network error");
+            })
+            .finally(() => {
+              setDiffLoading(false);
+            });
+        } else {
+          setDiffLoading(false);
+        }
+      }, [state.sessionId]);
+
+      useEffect(() => {
+        if (activeTab === "diff") {
+          fetchDiff();
+        }
+      }, [activeTab, fetchDiff]);
+
+      const renderDiffBox = () => {
+        return React.createElement(
+          "div",
+          { className: "dsh-goal-diff-box" },
+          React.createElement(
+            "div",
+            { className: "dsh-goal-diff-summary" },
+            React.createElement(
+              "div",
+              { style: { display: "flex", alignItems: "center", gap: 8 } },
+              React.createElement("span", null, (t("diffBaseCommit") || "Base:") + " ", React.createElement("code", null, (diffData && diffData.base ? diffData.base : (state.gitStartCommit || "main")).slice(0, 7))),
+              React.createElement("span", null, "→"),
+              React.createElement("span", null, (t("diffTargetBranch") || "Target:") + " ", React.createElement("code", null, (diffData && diffData.target) || state.gitBranch || state.branchName || "HEAD"))
+            ),
+            React.createElement(
+              "div",
+              { style: { display: "flex", alignItems: "center", gap: 8 } },
+              diffData && diffData.stats ? React.createElement(
+                "span",
+                { className: "dsh-goal-diff-stat-pill" },
+                React.createElement("span", { className: "dsh-goal-diff-ins" }, "+" + diffData.stats.insertions),
+                React.createElement("span", { className: "dsh-goal-diff-del" }, "-" + diffData.stats.deletions)
+              ) : null,
+              React.createElement(
+                "button",
+                {
+                  type: "button",
+                  className: "dsh-goal-btn icon-only",
+                  style: { padding: "2px 8px", fontSize: 11 },
+                  onClick: fetchDiff,
+                  title: t("diffRefresh") || "Refresh Diff",
+                },
+                "🔄"
+              )
+            )
+          ),
+          diffData && diffData.files && diffData.files.length > 0 ? React.createElement(
+            "div",
+            { className: "dsh-goal-diff-files-list" },
+            React.createElement(
+              "span",
+              {
+                className: `dsh-goal-diff-file-chip${selectedFile === null ? " active" : ""}`,
+                onClick: () => setSelectedFile(null),
+              },
+              (t("allFiles") || "All Files") + ` (${diffData.files.length})`
+            ),
+            diffData.files.map((f) => React.createElement(
+              "span",
+              {
+                key: f.path,
+                className: `dsh-goal-diff-file-chip${selectedFile === f.path ? " active" : ""}`,
+                onClick: () => setSelectedFile(selectedFile === f.path ? null : f.path),
+                title: `${f.path} (+${f.insertions} / -${f.deletions})`,
+              },
+              `${f.path.split("/").pop()} `,
+              React.createElement("span", { className: "dsh-goal-diff-ins" }, "+" + f.insertions),
+              "/",
+              React.createElement("span", { className: "dsh-goal-diff-del" }, "-" + f.deletions)
+            ))
+          ) : null,
+          diffLoading ? React.createElement("div", { className: "dsh-goal-diff-empty" }, t("diffLoading") || "Loading diff...")
+            : diffError ? React.createElement("div", { className: "dsh-goal-diff-empty dsh-goal-gate-error" }, "Error: " + diffError)
+            : !diffData || !diffData.diff || diffData.diff.trim().length === 0 ? React.createElement("div", { className: "dsh-goal-diff-empty" }, t("diffNoChanges") || "No git changes detected relative to base commit.")
+            : React.createElement(
+                "div",
+                { className: "dsh-goal-diff-viewer" },
+                (() => {
+                  const allLines = diffData.diff.split("\n");
+                  let linesToShow = allLines;
+                  if (selectedFile) {
+                    const fileChunks = [];
+                    let collecting = false;
+                    for (const l of allLines) {
+                      if (l.startsWith("diff --git ")) {
+                        const bPart = l.split(" b/")[1] || "";
+                        collecting = bPart === selectedFile;
+                      }
+                      if (collecting) fileChunks.push(l);
+                    }
+                    if (fileChunks.length > 0) linesToShow = fileChunks;
+                  }
+                  return linesToShow.map((line, idx) => {
+                    let lineClass = "dsh-goal-diff-line";
+                    if (line.startsWith("+") && !line.startsWith("+++")) {
+                      lineClass += " dsh-goal-diff-line-add";
+                    } else if (line.startsWith("-") && !line.startsWith("---")) {
+                      lineClass += " dsh-goal-diff-line-del";
+                    } else if (line.startsWith("@@")) {
+                      lineClass += " dsh-goal-diff-line-hunk";
+                    } else if (line.startsWith("diff --git") || line.startsWith("index ") || line.startsWith("---") || line.startsWith("+++")) {
+                      lineClass += " dsh-goal-diff-line-header";
+                    }
+                    return React.createElement("span", { key: idx, className: lineClass }, line || " ");
+                  });
+                })()
+              )
+        );
+      };
+
+      const renderSubGoalsBox = () => {
+        const subList = Array.isArray(state.subGoals) ? state.subGoals : [];
+        return React.createElement(
+          'div',
+          { className: 'dsh-goal-subgoals-box' },
+          state.isSubGoal
+            ? React.createElement(
+                'div',
+                { className: 'dsh-goal-subgoal-card', style: { borderStyle: 'dashed' } },
+                React.createElement('div', { style: { fontSize: 11, color: 'var(--dsw-alias-brand-primary)', fontWeight: 600 } }, '🌱 ' + (t('parentGoalBanner') || 'Child Sub-goal of:')),
+                React.createElement('div', { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } }, state.parentGoalId || 'Parent Goal')
+              )
+            : null,
+          subList.length === 0
+            ? React.createElement('div', { className: 'dsh-goal-diff-empty' }, t('noSubGoals') || 'No sub-goals spawned yet.')
+            : React.createElement(
+                'div',
+                { className: 'dsh-goal-subgoals-list' },
+                subList.map((sub, idx) =>
+                  React.createElement(
+                    'div',
+                    { key: sub.id || sub.subGoalId || idx, className: 'dsh-goal-subgoal-card' },
+                    React.createElement(
+                      'div',
+                      { className: 'dsh-goal-subgoal-header' },
+                      React.createElement('span', { className: 'dsh-goal-subgoal-title' }, sub.title),
+                      React.createElement(
+                        'span',
+                        {
+                          className: 'dsh-goal-badge ' + (sub.state === 'COMPLETED' ? 'dsh-goal-badge-ok' : sub.state === 'RUNNING' ? 'dsh-goal-badge-plan' : ''),
+                        },
+                        sub.state || 'PENDING'
+                      )
+                    ),
+                    sub.resultSummary
+                      ? React.createElement(
+                          'div',
+                          { className: 'dsh-goal-subgoal-summary' },
+                          sub.resultSummary
+                        )
+                      : null
+                  )
+                )
+              )
+        );
+      };
 
       const totalTokens = state.tokensUsage?.totalTokens || 0;
 
@@ -2222,7 +2600,46 @@ window.__ModuleLoader__.load({
 
             ),
 
-            isPlanMode && !isCompleted
+            React.createElement(
+              'div',
+              { className: 'dsh-goal-tabs' },
+              React.createElement(
+                'button',
+                {
+                  type: 'button',
+                  className: `dsh-goal-tab-btn${activeTab === "overview" ? " active" : ""}`,
+                  onClick: () => setActiveTab("overview"),
+                },
+                "📋 " + (t("tabOverview") || "Plan & Overview")
+              ),
+              React.createElement(
+                'button',
+                {
+                  type: 'button',
+                  className: `dsh-goal-tab-btn${activeTab === "diff" ? " active" : ""}`,
+                  onClick: () => setActiveTab("diff"),
+                },
+                "🔍 " + (t("tabDiff") || "Changes / Diff") + (diffData && diffData.stats && diffData.stats.filesChanged ? ` (${diffData.stats.filesChanged})` : "")
+              ),
+              React.createElement(
+                'button',
+                {
+                  type: 'button',
+                  className: `dsh-goal-tab-btn${activeTab === "subgoals" ? " active" : ""}`,
+                  onClick: () => setActiveTab("subgoals"),
+                },
+                "🌳 " + (t("tabSubGoals") || "Sub-goals") + (state.subGoals && state.subGoals.length > 0 ? ` (${state.subGoals.length})` : "")
+              )
+            ),
+
+            activeTab === 'diff'
+              ? renderDiffBox()
+              : activeTab === 'subgoals'
+              ? renderSubGoalsBox()
+              : React.createElement(
+                  React.Fragment,
+                  null,
+                  isPlanMode && !isCompleted
               ? React.createElement(
                   'div',
                   { className: 'dsh-goal-plan-banner' },
@@ -2547,6 +2964,13 @@ window.__ModuleLoader__.load({
                           },
 
                           `${i + 1}. ${m.title}`,
+                          m.compactionSummary
+                            ? React.createElement(
+                                'span',
+                                { className: 'dsh-goal-compacted-pill', title: m.compactionSummary },
+                                '⚡ ' + (t('compactedBadge') || 'Compacted')
+                              )
+                            : null,
                           m.verificationCommand
                             ? React.createElement(
                                 'span',
@@ -2716,7 +3140,8 @@ window.__ModuleLoader__.load({
                     )
                   )
                 )
-              : null,
+              : null
+                ),
 
           ),
 
@@ -4068,7 +4493,28 @@ window.__ModuleLoader__.load({
 
               ),
 
-              React.createElement('span', { className: 'dsh-goal-title', title: state.title }, state.title),
+              state.isSubGoal
+                ? React.createElement(
+                    'span',
+                    { className: 'dsh-goal-badge dsh-goal-badge-subgoal', title: t('subGoalBadge') || 'Sub-goal' },
+                    '🌱 ' + (t('subGoalBadge') || 'Sub-goal')
+                  )
+                : null,
+
+              state.breadcrumbs && state.breadcrumbs.length > 1
+                ? React.createElement(
+                    'span',
+                    { className: 'dsh-goal-breadcrumbs', title: state.title },
+                    state.breadcrumbs.map((crumb, idx) =>
+                      React.createElement(
+                        'span',
+                        { key: crumb.sessionId || idx, className: 'dsh-goal-breadcrumb-item' + (crumb.isCurrent ? ' active' : '') },
+                        idx > 0 && React.createElement('span', { className: 'dsh-goal-crumb-sep' }, ' / '),
+                        crumb.title
+                      )
+                    )
+                  )
+                : React.createElement('span', { className: 'dsh-goal-title', title: state.title }, state.title),
 
             ),
 
@@ -4078,6 +4524,19 @@ window.__ModuleLoader__.load({
 
               { className: 'dsh-goal-right' },
 
+              state.subGoals && state.subGoals.length > 0
+                ? React.createElement(
+                    'span',
+                    {
+                      className: 'dsh-goal-stat-pill',
+                      style: { cursor: 'pointer' },
+                      title: t('subGoalsTitle') || 'Sub-goals',
+                      onClick: () => setIsModalOpen(true),
+                    },
+                    '🌿 ' + state.subGoals.filter((s) => s.state === 'COMPLETED').length + '/' + state.subGoals.length + ' ' + (t('subGoalsPill') || 'sub-goals')
+                  )
+                : null,
+
               React.createElement(
 
                 'span',
@@ -5533,8 +5992,27 @@ window.__ModuleLoader__.load({
         planningPhase: 'Planning Phase (Read-Only)',
         planPhaseNotice: 'Agent is formulating the plan. File modifications are guarded until operator approval.',
         launchModeLabel: 'Launch Mode:',
+        tabOverview: 'Plan & Overview',
+        tabDiff: 'Changes / Diff',
+        diffLoading: 'Loading diff...',
+        diffNoChanges: 'No git changes detected relative to base commit.',
+        diffFilesChanged: 'Files changed:',
+        diffInsertions: 'insertions',
+        diffDeletions: 'deletions',
+        diffBaseCommit: 'Base:',
+        diffTargetBranch: 'Target:',
+        diffRefresh: 'Refresh Diff',
+        allFiles: 'All Files',
         planModeDesc: 'Plan first, review milestones, then execute',
         actModeDesc: 'Direct execution right away',
+        tabSubGoals: 'Sub-goals',
+        subGoalsTitle: 'Hierarchical Sub-goals',
+        subGoalBadge: 'Sub-goal',
+        subGoalsPill: 'sub-goals',
+        noSubGoals: 'No sub-goals spawned yet. Model can spawn sub-goals via goal_spawn_subgoal tool.',
+        parentGoalBanner: 'Child Sub-goal of:',
+        compactedBadge: 'Compacted',
+        compactionTooltip: 'History compacted to reduce context footprint',
 
       },
 
@@ -5684,8 +6162,27 @@ window.__ModuleLoader__.load({
         planningPhase: '规划阶段（只读）',
         planPhaseNotice: '智能体正在制定方案与里程碑。在操作者批准前，禁止修改文件。',
         launchModeLabel: '启动模式：',
+        tabOverview: '方案与概览',
+        tabDiff: '代码变更 / Diff',
+        diffLoading: '正在加载差异...',
+        diffNoChanges: '未检测到相对于基线提交的代码变更。',
+        diffFilesChanged: '变更文件数：',
+        diffInsertions: '行新增',
+        diffDeletions: '行删除',
+        diffBaseCommit: '基线：',
+        diffTargetBranch: '目标：',
+        diffRefresh: '刷新 Diff',
+        allFiles: '所有文件',
         planModeDesc: '先制定里程碑方案，人工确认后再执行',
         actModeDesc: '立即开始编码与任务执行',
+        tabSubGoals: '子目标',
+        subGoalsTitle: '分层子目标管理',
+        subGoalBadge: '子目标',
+        subGoalsPill: '个子目标',
+        noSubGoals: '当前任务暂无衍生子目标。模型可通过 goal_spawn_subgoal 工具动态创建独立子目标。',
+        parentGoalBanner: '衍生自主目标:',
+        compactedBadge: '已压缩',
+        compactionTooltip: '阶段历史已自动精简压缩以优化上下文窗口',
 
       },
 

package/lib/engine-compaction.js

@@ -0,0 +1,126 @@
+/**
+ * Milestone Context Compaction for DSH Goal Engine (Issue #167).
+ * Compresses verbose raw logs and full checklist traces of completed milestones
+ * into high-density summaries, cutting context token footprint by > 40%.
+ */
+
+/**
+ * Compact a single milestone upon completion into a structured summary
+ * @param {object} milestone
+ * @param {object} [options]
+ * @returns {object}
+ */
+export function compactMilestone(milestone, options = {}) {
+  if (!milestone) return null;
+
+  const id = milestone.id ? String(milestone.id).toUpperCase() : 'M';
+  const title = milestone.title || 'Milestone';
+  const notes = milestone.notes ? String(milestone.notes).trim() : '';
+
+  let checklistPart = '';
+  if (Array.isArray(milestone.checklist) && milestone.checklist.length > 0) {
+    const doneCount = milestone.checklist.filter((item) => item && item.done).length;
+    checklistPart = ` [${doneCount}/${milestone.checklist.length} subtasks]`;
+  }
+
+  let gatePart = '';
+  if (milestone.verificationCommand) {
+    gatePart = milestone.verificationPassed ? ' [Gate: verified]' : ' [Gate: passed]';
+  }
+
+  const outcomePart = notes ? ` (Outcome: ${notes})` : '';
+  const summaryLine = `[${id} COMPLETED] ${title}${outcomePart}${checklistPart}${gatePart}`;
+
+  milestone.compactionSummary = summaryLine;
+  milestone.compactedAt = milestone.completedAt || Date.now();
+
+  return {
+    id: milestone.id,
+    title,
+    notes,
+    summary: summaryLine,
+    completedAt: milestone.compactedAt,
+  };
+}
+
+/**
+ * Build compacted milestones history block for active prompt injection
+ * @param {Array<object>} milestones
+ * @param {string} [lang='en']
+ * @returns {string}
+ */
+export function buildCompactedMilestonesHistory(milestones = [], lang = 'en') {
+  if (!Array.isArray(milestones) || milestones.length === 0) return '';
+
+  const completed = milestones.filter((m) => m && m.status === 'completed');
+  if (completed.length === 0) return '';
+
+  const header = lang === 'zh'
+    ? '[已完成里程碑历史简报 / COMPACTED MILESTONES HISTORY]'
+    : '[COMPACTED MILESTONES HISTORY]';
+
+  const lines = completed.map((m) => {
+    if (m.compactionSummary) return `- ${m.compactionSummary}`;
+    const id = m.id ? String(m.id).toUpperCase() : 'M';
+    const outcome = m.notes ? ` (Outcome: ${m.notes})` : '';
+    return `- [${id} COMPLETED] ${m.title}${outcome}`;
+  });
+
+  return `${header}\n${lines.join('\n')}`;
+}
+
+/**
+ * Format milestone into raw uncompacted text (for baseline comparison & active milestones)
+ * @param {object} m
+ * @param {number} idx
+ * @returns {string}
+ */
+export function formatRawMilestoneTrace(m, idx = 0) {
+  if (!m) return '';
+  const statusStr = (m.status || 'pending').toUpperCase();
+  let line = `  ${idx + 1}. [${statusStr}] ${m.title || ''}${m.notes ? ` (${m.notes})` : ''}`;
+  if (m.verificationCommand) {
+    line += `\n      [verification_command: ${m.verificationCommand}]`;
+  }
+  if (Array.isArray(m.checklist) && m.checklist.length > 0) {
+    const checkLines = m.checklist
+      .map((item) => `      [${item && item.done ? 'x' : ' '}] ${item && item.text ? item.text : ''}`)
+      .join('\n');
+    line += `\n${checkLines}`;
+  }
+  return line;
+}
+
+/**
+ * Estimate context savings achieved by compaction on completed milestones
+ * @param {Array<object>} milestones
+ * @param {string} [lang='en']
+ * @returns {{ completedCount: number, uncompactedChars: number, compactedChars: number, savedChars: number, savingsRatio: number, savingsPercent: string }}
+ */
+export function estimateCompactionSavings(milestones = [], lang = 'en') {
+  if (!Array.isArray(milestones) || milestones.length === 0) {
+    return { completedCount: 0, uncompactedChars: 0, compactedChars: 0, savedChars: 0, savingsRatio: 0, savingsPercent: '0%' };
+  }
+
+  const completed = milestones.filter((m) => m && m.status === 'completed');
+  if (completed.length === 0) {
+    return { completedCount: 0, uncompactedChars: 0, compactedChars: 0, savedChars: 0, savingsRatio: 0, savingsPercent: '0%' };
+  }
+
+  const uncompacted = completed.map((m, i) => formatRawMilestoneTrace(m, i)).join('\n');
+  const compacted = completed.map((m) => m.compactionSummary || `[${m.id ? String(m.id).toUpperCase() : 'M'} COMPLETED] ${m.title}`).join('\n');
+
+  const uncompactedChars = uncompacted.length;
+  const compactedChars = compacted.length;
+  const savedChars = Math.max(0, uncompactedChars - compactedChars);
+  const savingsRatio = uncompactedChars > 0 ? (savedChars / uncompactedChars) : 0;
+
+  return {
+    completedCount: completed.length,
+    uncompactedChars,
+    compactedChars,
+    savedChars,
+    savingsRatio,
+    savingsPercent: `${Math.round(savingsRatio * 100)}%`,
+  };
+}