agentboss 0.1.1 → 0.1.3

package/server/analysis/dimensions/output-quality.js

@@ -1,167 +1,167 @@
-/**
- * O1 — AI Output Quality.
- *
- * Sub-indicators:
- *   • first_take    — fraction of assistant turns NOT followed by an
- *                     immediate user correction
- *   • code_style    — LLM-judged (rule fallback returns 0.7 neutral)
- *   • completeness  — assistant text mentions edge/error/test concepts
- *                     (LLM judge is more accurate; rules give a proxy)
- *
- * See spec §4.6.
- *
- * @author Felix
- */
-
-'use strict';
-
-const {
-  fetchMessages,
-  matchesAny,
-} = require('../text-signals');
-const { explainIndicator, rollupDimension, scoreToLevel, O1 } = require('../thresholds-v2');
-const { mergeIndicator, dimensionSource } = require('./llm-merge');
-const { makeEvidence } = require('../evidence-builder');
-
-const CORRECTION_PATTERNS = [
-  /改一下/, /不对/, /(再|重新)(写|来|改|做)/, /(错|有问题|有bug)/, /漏了/, /换/,
-  /fix that/i, /that'?s wrong/i, /redo/i, /try again/i, /not quite/i,
-];
-
-const COMPLETENESS_PATTERNS = [
-  /边界/, /异常/, /错误处理/, /测试/, /单元测试/, /回退/, /兜底/,
-  /edge case/i, /error handling/i, /test/i, /fallback/i, /exception/i,
-];
-
-function analyzeRules(db, session, difficulty = 2) {
-  const messages = fetchMessages(db, session.id);
-  const haveText = messages.some((m) => m.text && m.text.length > 0);
-
-  let first_take = null;
-  let assistantTurns = 0;
-  let correctionsAfter = 0;
-
-  for (let i = 0; i < messages.length; i++) {
-    const m = messages[i];
-    if (m.role !== 'assistant') continue;
-    assistantTurns++;
-    const next = i + 1 < messages.length ? messages[i + 1] : null;
-    if (!next || next.role !== 'user' || !next.text) continue;
-    if (matchesAny(next.text, CORRECTION_PATTERNS)) correctionsAfter++;
-  }
-  if (assistantTurns > 0) {
-    first_take = 1 - correctionsAfter / assistantTurns;
-  }
-
-  const code_style = haveText ? 0.7 : null;
-
-  let completeness = null;
-  let completenessHits = 0;
-  let assistantMsgsWithText = 0;
-  if (haveText) {
-    const assistantMsgs = messages.filter((m) => m.role === 'assistant' && m.text);
-    assistantMsgsWithText = assistantMsgs.length;
-    if (assistantMsgs.length > 0) {
-      completenessHits = assistantMsgs.filter((m) => matchesAny(m.text, COMPLETENESS_PATTERNS)).length;
-      completeness = completenessHits / assistantMsgs.length;
-    }
-  }
-
-  const ftE = explainIndicator(O1.first_take,   first_take,   difficulty);
-  const csE = explainIndicator(O1.code_style,   code_style,   difficulty);
-  const cpE = explainIndicator(O1.completeness, completeness, difficulty);
-
-  const subScores = {
-    first_take:   ftE.score,
-    code_style:   csE.score,
-    completeness: cpE.score,
-  };
-  const subLevels = {
-    first_take:   ftE.level,
-    code_style:   csE.level,
-    completeness: cpE.level,
-  };
-
-  const subEvidence = buildSubEvidence(
-    { ft: ftE, cs: csE, cp: cpE },
-    {
-      mode: 'rules', haveText, assistantTurns, correctionsAfter,
-      assistantMsgsWithText, completenessHits,
-    },
-    difficulty
-  );
-
-  const score = rollupDimension('O1', subScores);
-  const level = scoreToLevel(score);
-
-  return {
-    subScores,
-    subLevels,
-    subEvidence,
-    raw: { first_take, code_style, completeness, assistantTurns, correctionsAfter, completenessHits, assistantMsgsWithText },
-    score,
-    level,
-    judgeSource: 'rules',
-    llmJudge: null,
-  };
-}
-
-/** Public entry — synchronous.  `llmCell` is llmJudge.O1 (or null). */
-function analyze(db, session, difficulty = 2, llmCell = null) {
-  const ruleResult = analyzeRules(db, session, difficulty);
-  if (!llmCell) return ruleResult;
-
-  const cell = llmCell;
-  const m = {
-    first_take:   mergeIndicator(cell.first_take,   ruleResult.subScores.first_take,   ruleResult.subLevels.first_take),
-    code_style:   mergeIndicator(cell.code_style,   ruleResult.subScores.code_style,   ruleResult.subLevels.code_style),
-    completeness: mergeIndicator(cell.completeness, ruleResult.subScores.completeness, ruleResult.subLevels.completeness),
-  };
-
-  const subScores = { first_take: m.first_take.score, code_style: m.code_style.score, completeness: m.completeness.score };
-  const subLevels = { first_take: m.first_take.level, code_style: m.code_style.level, completeness: m.completeness.level };
-
-  const subEvidence = {
-    first_take:   { ...ruleResult.subEvidence.first_take,   what: m.first_take.evidence   || ruleResult.subEvidence.first_take.what,   level: subLevels.first_take,   score: subScores.first_take },
-    code_style:   { ...ruleResult.subEvidence.code_style,   what: m.code_style.evidence   || ruleResult.subEvidence.code_style.what,   level: subLevels.code_style,   score: subScores.code_style },
-    completeness: { ...ruleResult.subEvidence.completeness, what: m.completeness.evidence || ruleResult.subEvidence.completeness.what, level: subLevels.completeness, score: subScores.completeness },
-  };
-
-  const score = rollupDimension('O1', subScores);
-  const level = scoreToLevel(score);
-  const judgeSource = dimensionSource([m.first_take.source, m.code_style.source, m.completeness.source]);
-
-  return { subScores, subLevels, subEvidence, raw: { llmCell: cell, ruleRaw: ruleResult.raw }, score, level, judgeSource, llmJudge: null };
-}
-
-function buildSubEvidence(expls, ctx, difficulty) {
-  const { ft, cs, cp } = expls;
-
-  // rules
-  const { haveText, assistantTurns, correctionsAfter, assistantMsgsWithText, completenessHits } = ctx;
-  return {
-    first_take: makeEvidence({
-      key: 'first_take', label: '一次采纳率',
-      what: assistantTurns > 0
-        ? `规则版：1 - (AI 回合后用户立即纠错的比例) = 1 - ${correctionsAfter} / ${assistantTurns} 个 AI 回合。`
-        : '规则版：无 AI 回合可评估。',
-      expl: ft, unit: '%', difficulty,
-    }),
-    code_style: makeEvidence({
-      key: 'code_style', label: '代码规范性',
-      what: haveText
-        ? '规则版无法评估代码规范，默认给中性 0.7 分。开启 LLM judge 可获得真实评估。'
-        : '消息文本缺失，无法评估。',
-      expl: cs, unit: '%', difficulty,
-    }),
-    completeness: makeEvidence({
-      key: 'completeness', label: '方案完备性',
-      what: assistantMsgsWithText > 0
-        ? `规则版：AI 消息中含完备性关键词（"边界"、"异常"、"测试"等）的比例：${completenessHits} / ${assistantMsgsWithText}。`
-        : '规则版：无 AI 文本，无法评估。',
-      expl: cp, unit: '%', difficulty,
-    }),
-  };
-}
-
-module.exports = { analyze, analyzeRules };
+/**
+ * O1 — AI Output Quality.
+ *
+ * Sub-indicators:
+ *   • first_take    — fraction of assistant turns NOT followed by an
+ *                     immediate user correction
+ *   • code_style    — LLM-judged (rule fallback returns 0.7 neutral)
+ *   • completeness  — assistant text mentions edge/error/test concepts
+ *                     (LLM judge is more accurate; rules give a proxy)
+ *
+ * See spec §4.6.
+ *
+ * @author Felix
+ */
+
+'use strict';
+
+const {
+  fetchMessages,
+  matchesAny,
+} = require('../text-signals');
+const { explainIndicator, rollupDimension, scoreToLevel, O1 } = require('../thresholds-v2');
+const { mergeIndicator, dimensionSource } = require('./llm-merge');
+const { makeEvidence } = require('../evidence-builder');
+
+const CORRECTION_PATTERNS = [
+  /改一下/, /不对/, /(再|重新)(写|来|改|做)/, /(错|有问题|有bug)/, /漏了/, /换/,
+  /fix that/i, /that'?s wrong/i, /redo/i, /try again/i, /not quite/i,
+];
+
+const COMPLETENESS_PATTERNS = [
+  /边界/, /异常/, /错误处理/, /测试/, /单元测试/, /回退/, /兜底/,
+  /edge case/i, /error handling/i, /test/i, /fallback/i, /exception/i,
+];
+
+function analyzeRules(db, session, difficulty = 2) {
+  const messages = fetchMessages(db, session.id);
+  const haveText = messages.some((m) => m.text && m.text.length > 0);
+
+  let first_take = null;
+  let assistantTurns = 0;
+  let correctionsAfter = 0;
+
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (m.role !== 'assistant') continue;
+    assistantTurns++;
+    const next = i + 1 < messages.length ? messages[i + 1] : null;
+    if (!next || next.role !== 'user' || !next.text) continue;
+    if (matchesAny(next.text, CORRECTION_PATTERNS)) correctionsAfter++;
+  }
+  if (assistantTurns > 0) {
+    first_take = 1 - correctionsAfter / assistantTurns;
+  }
+
+  const code_style = haveText ? 0.7 : null;
+
+  let completeness = null;
+  let completenessHits = 0;
+  let assistantMsgsWithText = 0;
+  if (haveText) {
+    const assistantMsgs = messages.filter((m) => m.role === 'assistant' && m.text);
+    assistantMsgsWithText = assistantMsgs.length;
+    if (assistantMsgs.length > 0) {
+      completenessHits = assistantMsgs.filter((m) => matchesAny(m.text, COMPLETENESS_PATTERNS)).length;
+      completeness = completenessHits / assistantMsgs.length;
+    }
+  }
+
+  const ftE = explainIndicator(O1.first_take,   first_take,   difficulty);
+  const csE = explainIndicator(O1.code_style,   code_style,   difficulty);
+  const cpE = explainIndicator(O1.completeness, completeness, difficulty);
+
+  const subScores = {
+    first_take:   ftE.score,
+    code_style:   csE.score,
+    completeness: cpE.score,
+  };
+  const subLevels = {
+    first_take:   ftE.level,
+    code_style:   csE.level,
+    completeness: cpE.level,
+  };
+
+  const subEvidence = buildSubEvidence(
+    { ft: ftE, cs: csE, cp: cpE },
+    {
+      mode: 'rules', haveText, assistantTurns, correctionsAfter,
+      assistantMsgsWithText, completenessHits,
+    },
+    difficulty
+  );
+
+  const score = rollupDimension('O1', subScores);
+  const level = scoreToLevel(score);
+
+  return {
+    subScores,
+    subLevels,
+    subEvidence,
+    raw: { first_take, code_style, completeness, assistantTurns, correctionsAfter, completenessHits, assistantMsgsWithText },
+    score,
+    level,
+    judgeSource: 'rules',
+    llmJudge: null,
+  };
+}
+
+/** Public entry — synchronous.  `llmCell` is llmJudge.O1 (or null). */
+function analyze(db, session, difficulty = 2, llmCell = null) {
+  const ruleResult = analyzeRules(db, session, difficulty);
+  if (!llmCell) return ruleResult;
+
+  const cell = llmCell;
+  const m = {
+    first_take:   mergeIndicator(cell.first_take,   ruleResult.subScores.first_take,   ruleResult.subLevels.first_take),
+    code_style:   mergeIndicator(cell.code_style,   ruleResult.subScores.code_style,   ruleResult.subLevels.code_style),
+    completeness: mergeIndicator(cell.completeness, ruleResult.subScores.completeness, ruleResult.subLevels.completeness),
+  };
+
+  const subScores = { first_take: m.first_take.score, code_style: m.code_style.score, completeness: m.completeness.score };
+  const subLevels = { first_take: m.first_take.level, code_style: m.code_style.level, completeness: m.completeness.level };
+
+  const subEvidence = {
+    first_take:   { ...ruleResult.subEvidence.first_take,   what: m.first_take.evidence   || ruleResult.subEvidence.first_take.what,   level: subLevels.first_take,   score: subScores.first_take,   source: m.first_take.source },
+    code_style:   { ...ruleResult.subEvidence.code_style,   what: m.code_style.evidence   || ruleResult.subEvidence.code_style.what,   level: subLevels.code_style,   score: subScores.code_style,   source: m.code_style.source },
+    completeness: { ...ruleResult.subEvidence.completeness, what: m.completeness.evidence || ruleResult.subEvidence.completeness.what, level: subLevels.completeness, score: subScores.completeness, source: m.completeness.source },
+  };
+
+  const score = rollupDimension('O1', subScores);
+  const level = scoreToLevel(score);
+  const judgeSource = dimensionSource([m.first_take.source, m.code_style.source, m.completeness.source]);
+
+  return { subScores, subLevels, subEvidence, raw: { llmCell: cell, ruleRaw: ruleResult.raw }, score, level, judgeSource, llmJudge: null };
+}
+
+function buildSubEvidence(expls, ctx, difficulty) {
+  const { ft, cs, cp } = expls;
+
+  // rules
+  const { haveText, assistantTurns, correctionsAfter, assistantMsgsWithText, completenessHits } = ctx;
+  return {
+    first_take: makeEvidence({
+      key: 'first_take', label: '一次采纳率',
+      what: assistantTurns > 0
+        ? `规则版：1 - (AI 回合后用户立即纠错的比例) = 1 - ${correctionsAfter} / ${assistantTurns} 个 AI 回合。`
+        : '规则版：无 AI 回合可评估。',
+      expl: ft, unit: '%', difficulty,
+    }),
+    code_style: makeEvidence({
+      key: 'code_style', label: '代码规范性',
+      what: haveText
+        ? '规则版无法评估代码规范，默认给中性 0.7 分。开启 LLM judge 可获得真实评估。'
+        : '消息文本缺失，无法评估。',
+      expl: cs, unit: '%', difficulty,
+    }),
+    completeness: makeEvidence({
+      key: 'completeness', label: '方案完备性',
+      what: assistantMsgsWithText > 0
+        ? `规则版：AI 消息中含完备性关键词（"边界"、"异常"、"测试"等）的比例：${completenessHits} / ${assistantMsgsWithText}。`
+        : '规则版：无 AI 文本，无法评估。',
+      expl: cp, unit: '%', difficulty,
+    }),
+  };
+}
+
+module.exports = { analyze, analyzeRules };

package/server/analysis/dimensions/problem-definition.js

@@ -1,104 +1,109 @@
-/**
- * H1 — Problem Definition.
- *
- * Captures the human ability to turn a vague need into a precise,
- * AI-executable problem.  Three sub-indicators:
- *   • clarity   — AI proactive-question count in the first 30%
- *   • converge  — number of user-message rounds to convergence
- *   • drift     — direction-change events
- *
- * See docs/superpowers/specs/2026-06-13-capability-model-v2.md §4.1.
- *
- * @author Felix
- */
-
-'use strict';
-
-const { queryAll } = require('../../db/queries');
-const {
-  fetchMessages,
-  userMessages,
-  matchesAny,
-  DRIFT_PATTERNS,
-} = require('../text-signals');
-const { explainIndicator, rollupDimension, scoreToLevel, H1 } = require('../thresholds-v2');
-const { makeEvidence } = require('../evidence-builder');
-const { mergeIndicator, dimensionSource } = require('./llm-merge');
-
-function analyze(db, session, difficulty = 2, llmCell = null) {
-  const messages = fetchMessages(db, session.id);
-  const users = userMessages(messages);
-
-  // ---- clarity: count of `question` tool calls in first 30% ----------
-  const toolCalls = queryAll(
-    db,
-    `SELECT tool_name, timestamp
-       FROM unified_tool_call
-      WHERE session_id = ?
-      ORDER BY timestamp ASC`,
-    [session.id]
-  );
-  let clarity = 0;
-  let clarityCutoff = 0;
-  if (toolCalls.length > 0) {
-    clarityCutoff = Math.max(1, Math.floor(toolCalls.length * 0.3));
-    clarity = toolCalls.slice(0, clarityCutoff).filter((t) => t.tool_name === 'question').length;
-  }
-
-  // ---- converge: number of user messages -----------------------------
-  const converge = users.length;
-
-  // ---- drift: keyword spotting on user text -------------------------
-  const haveText = users.some((m) => m.text && m.text.length > 0);
-
-  let drift = null;
-  if (haveText) {
-    drift = users.filter((m) => matchesAny(m.text, DRIFT_PATTERNS)).length;
-  }
-
-  // ---- eval each ----------------------------------------------------
-  const clarityE  = explainIndicator(H1.clarity,  clarity,  difficulty);
-  const convergeE = explainIndicator(H1.converge, converge, difficulty);
-  const driftE    = explainIndicator(H1.drift,    drift,    difficulty);
-
-  // Rule baseline per indicator (level + centred score).
-  const rule = {
-    clarity:  { score: clarityE.score,  level: clarityE.level },
-    converge: { score: convergeE.score, level: convergeE.level },
-    drift:    { score: driftE.score,    level: driftE.level },
-  };
-
-  // Merge LLM cell (if any) over the rule baseline.
-  const cell = llmCell || {};
-  const m = {
-    clarity:  mergeIndicator(cell.clarity,  rule.clarity.score,  rule.clarity.level),
-    converge: mergeIndicator(cell.converge, rule.converge.score, rule.converge.level),
-    drift:    mergeIndicator(cell.drift,    rule.drift.score,    rule.drift.level),
-  };
-
-  const subScores = { clarity: m.clarity.score, converge: m.converge.score, drift: m.drift.score };
-  const subLevels = { clarity: m.clarity.level, converge: m.converge.level, drift: m.drift.level };
-
-  // Evidence: prefer the LLM's cited rationale when that indicator used the LLM.
-  const subEvidence = {
-    clarity:  makeEvidence({ key: 'clarity',  label: '初始指令清晰度', what: m.clarity.evidence  || `规则版：前 30% 工具调用中 question 次数 ${clarity}（共 ${toolCalls.length} 次调用）。`, expl: clarityE,  unit: '次', difficulty }),
-    converge: makeEvidence({ key: 'converge', label: '任务收敛轮次',   what: m.converge.evidence || `规则版：用户消息 ${converge} 条。`, expl: convergeE, unit: '轮', difficulty }),
-    drift:    makeEvidence({ key: 'drift',    label: '方向变更次数',   what: m.drift.evidence    || (haveText ? `规则版：方向变更关键词命中 ${drift} 条。` : '用户消息无文本，无法识别。'), expl: driftE, unit: '次', difficulty }),
-  };
-
-  const score = rollupDimension('H1', subScores);
-  const level = scoreToLevel(score);
-  const judgeSource = dimensionSource([m.clarity.source, m.converge.source, m.drift.source]);
-
-  return {
-    subScores,
-    subLevels,
-    subEvidence,
-    raw: { clarity, converge, drift, difficulty, haveText, toolCallCount: toolCalls.length, clarityCutoff },
-    score,
-    level,
-    judgeSource,
-  };
-}
-
-module.exports = { analyze };
+/**
+ * H1 — Problem Definition.
+ *
+ * Captures the human ability to turn a vague need into a precise,
+ * AI-executable problem.  Three sub-indicators:
+ *   • clarity   — AI proactive-question count in the first 30%
+ *   • converge  — number of user-message rounds to convergence
+ *   • drift     — direction-change events
+ *
+ * See docs/superpowers/specs/2026-06-13-capability-model-v2.md §4.1.
+ *
+ * @author Felix
+ */
+
+'use strict';
+
+const { queryAll } = require('../../db/queries');
+const {
+  fetchMessages,
+  userMessages,
+  matchesAny,
+  DRIFT_PATTERNS,
+} = require('../text-signals');
+const { explainIndicator, rollupDimension, scoreToLevel, H1 } = require('../thresholds-v2');
+const { makeEvidence } = require('../evidence-builder');
+const { mergeIndicator, dimensionSource } = require('./llm-merge');
+
+function analyze(db, session, difficulty = 2, llmCell = null) {
+  const messages = fetchMessages(db, session.id);
+  const users = userMessages(messages);
+
+  // ---- clarity: count of `question` tool calls in first 30% ----------
+  const toolCalls = queryAll(
+    db,
+    `SELECT tool_name, timestamp
+       FROM unified_tool_call
+      WHERE session_id = ?
+      ORDER BY timestamp ASC`,
+    [session.id]
+  );
+  let clarity = 0;
+  let clarityCutoff = 0;
+  if (toolCalls.length > 0) {
+    clarityCutoff = Math.max(1, Math.floor(toolCalls.length * 0.3));
+    clarity = toolCalls.slice(0, clarityCutoff).filter((t) => t.tool_name === 'question').length;
+  }
+
+  // ---- converge: number of user messages -----------------------------
+  const converge = users.length;
+
+  // ---- drift: keyword spotting on user text -------------------------
+  const haveText = users.some((m) => m.text && m.text.length > 0);
+
+  let drift = null;
+  if (haveText) {
+    drift = users.filter((m) => matchesAny(m.text, DRIFT_PATTERNS)).length;
+  }
+
+  // ---- eval each ----------------------------------------------------
+  const clarityE  = explainIndicator(H1.clarity,  clarity,  difficulty);
+  const convergeE = explainIndicator(H1.converge, converge, difficulty);
+  const driftE    = explainIndicator(H1.drift,    drift,    difficulty);
+
+  // Rule baseline per indicator (level + centred score).
+  const rule = {
+    clarity:  { score: clarityE.score,  level: clarityE.level },
+    converge: { score: convergeE.score, level: convergeE.level },
+    drift:    { score: driftE.score,    level: driftE.level },
+  };
+
+  // Merge LLM cell (if any) over the rule baseline.
+  const cell = llmCell || {};
+  const m = {
+    clarity:  mergeIndicator(cell.clarity,  rule.clarity.score,  rule.clarity.level),
+    converge: mergeIndicator(cell.converge, rule.converge.score, rule.converge.level),
+    drift:    mergeIndicator(cell.drift,    rule.drift.score,    rule.drift.level),
+  };
+
+  const subScores = { clarity: m.clarity.score, converge: m.converge.score, drift: m.drift.score };
+  const subLevels = { clarity: m.clarity.level, converge: m.converge.level, drift: m.drift.level };
+
+  // Evidence: prefer the LLM's cited rationale when that indicator used the LLM.
+  const subEvidence = {
+    clarity:  makeEvidence({ key: 'clarity',  label: '初始指令清晰度', what: m.clarity.evidence  || `规则版：前 30% 工具调用中 question 次数 ${clarity}（共 ${toolCalls.length} 次调用）。`, expl: clarityE,  unit: '次', difficulty }),
+    converge: makeEvidence({ key: 'converge', label: '任务收敛轮次',   what: m.converge.evidence || `规则版：用户消息 ${converge} 条。`, expl: convergeE, unit: '轮', difficulty }),
+    drift:    makeEvidence({ key: 'drift',    label: '方向变更次数',   what: m.drift.evidence    || (haveText ? `规则版：方向变更关键词命中 ${drift} 条。` : '用户消息无文本，无法识别。'), expl: driftE, unit: '次', difficulty }),
+  };
+
+  // Tag each sub-indicator with its source (llm / rules) for the UI badge.
+  subEvidence.clarity.source  = m.clarity.source;
+  subEvidence.converge.source = m.converge.source;
+  subEvidence.drift.source    = m.drift.source;
+
+  const score = rollupDimension('H1', subScores);
+  const level = scoreToLevel(score);
+  const judgeSource = dimensionSource([m.clarity.source, m.converge.source, m.drift.source]);
+
+  return {
+    subScores,
+    subLevels,
+    subEvidence,
+    raw: { clarity, converge, drift, difficulty, haveText, toolCallCount: toolCalls.length, clarityCutoff },
+    score,
+    level,
+    judgeSource,
+  };
+}
+
+module.exports = { analyze };

package/server/analysis/job.js

@@ -27,17 +27,25 @@ const { aggregateDailySummary } = require('./daily-aggregator');
 /**
  * Build a list of YYYY-MM-DD strings starting from today going back
  * `days` days, ordered most-recent first.  Today is included so the
- * current day's sessions get scored too; sessions that keep growing
- * after being scored are re-picked by getUnanalyzedSessions (ended_at
- * newer than analyzed_at).
+ * Today is EXCLUDED — sessions on the current calendar day are still
+ * actively being held (judge / advice analysing them would race against
+ * the user typing more messages, churn the cache, and waste LLM calls).
+ * Yesterday + N earlier days only.  Callers who really want to (re)
+ * analyze today must pass `dates: ['YYYY-MM-DD']` explicitly to
+ * runAnalysisJob, or use the per-session reanalyze endpoint
+ * (`POST /api/analysis/session/:id`) which bypasses this path.
  *
- * @param {number} days
+ * Default `days = 7` therefore produces 7 dates (yesterday through 7
+ * days ago), not 8.
+ *
+ * @param {number} days  number of past days to include (yesterday-anchored)
  * @returns {string[]}
  */
 function buildDateList(days) {
   const dates = [];
   const now = new Date();
-  for (let i = 0; i <= days; i++) {
+  // Start at i=1 → yesterday; end at i=days inclusive → `days` total dates.
+  for (let i = 1; i <= days; i++) {
     const d = new Date(now);
     d.setDate(d.getDate() - i);
     dates.push(formatDate(d));
@@ -63,6 +71,11 @@ function formatDate(d) {
  * We skip this session in the job so we don't analyze a still-growing
  * conversation; the next job pass will pick it up once it settles.
  *
+ * Note: the default invocation of runAnalysisJob no longer includes
+ * today at all (see buildDateList).  This function only fires when a
+ * caller explicitly passes `dates` that includes today — in which case
+ * we still shield the actively-typed-in session.
+ *
  * @param {object} db
  * @param {string} date  YYYY-MM-DD
  * @param {object[]} sessions  candidate session rows for that date
@@ -156,7 +169,24 @@ async function analyzeAndStoreSession(db, session, opts = {}) {
 
 /**
  * Run analysis job: analyze unanalyzed sessions in reverse chronological order.
- * Default: last 7 days. Processes one date at a time, most recent first.
+ *
+ * # Today policy
+ *
+ * Default invocation ({days}) skips TODAY entirely — sessions on the
+ * current calendar day are likely still being held, and analysing
+ * them now means churning the LLM cache for results that will be stale
+ * within minutes.  The boot path (bin/aboss.js) uses this default, so
+ * "open aboss → background scan" never touches today.
+ *
+ * Two escape hatches keep today analysable when the user really asks:
+ *   - `dates: ['YYYY-MM-DD']` explicit list → not filtered.  Used by
+ *     manual triggers that pass a specific date set.
+ *   - `POST /api/analysis/session/:id` → goes straight through
+ *     `analyzeAndStoreSession`, doesn't use this job loop, so today's
+ *     "Re-analyze" button in the UI keeps working.
+ *
+ * Default: last 7 days (yesterday → 7 days ago).  Processes one date at
+ * a time, most recent first.
  *
  * @param {object} db - sql.js boss.db instance
  * @param {object} options - {
@@ -164,6 +194,7 @@ async function analyzeAndStoreSession(db, session, opts = {}) {
  *   onProgress: fn,
  *   forceReanalyze: false,
  *   dates: string[]  // optional explicit YYYY-MM-DD list; overrides `days`
+ *                    // AND bypasses the "skip today" rule
  * }
  * @returns {Promise<{analyzed: number, errors: number, skipped: number}>}
  */