@kitkat-vn/kitcode 0.2.0-staging.8 → 0.3.0-staging.15

package/src/milestone-record.mjs

@@ -0,0 +1,214 @@
+// The milestone record in state.json, `milestonesReached`, read (docs/reward-rules.md §6.1): what each milestone's entry
+// says, checked as KitCode writes it. Pure, with no imports: reward.mjs reads it to decide the milestones, and
+// milestones-reached.mjs to write the record and to report it in the claim bundle.
+//
+//   {"recordingSince": "2026-09-25T09:15:00.004Z",
+//    "milestones": {"30": {"reachedBeforeRecording": true},
+//                   "50": {"reachedAt": "2026-10-20T11:03:27.918Z", "focusSeconds": 3600, "equals": 15}},
+//    "freshSince": {"at": "2026-10-20T10:00:00.000Z", "focusSeconds": 2400, "equals": 11}}
+//
+// Since 2026-10-20 (rewards/2-no-stack) an entry the CLI writes also holds the totals at the moment the milestone was
+// reached, its focus seconds and its =, and `freshSince` the totals at the moment this KitCode first wrote a record that
+// holds a milestone reached without them: by an earlier KitCode, or before the record began. The milestone after such a
+// one counts from `freshSince` (the plan's decision 2). An entry an earlier KitCode wrote, `reachedAt` alone, stays as it
+// is, and so does every field this version does not know.
+//
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2) the record counts in cycles (the plan of 2026-10-21, decision 1: after a
+// claim, all progress resets). Cycle 1 is the record as it was, its entries in `milestones`; each later cycle is one entry of
+// `cycles`, added when the tracker takes a receipt the claim backend signed for the voucher of the cycle before
+// (milestones-reached.mjs, beginNextCycle), and never changed after but for its own milestones, added once each. Since 2026-10-22's
+// phase 3 a cycle is numbered as the claim backend counts, the one after its receipt's, so the numbers can skip: a KitCode installed
+// afresh in cycle 1 that takes the receipt of cycle 2 begins cycle 3.
+//
+//    "cycles": [{"cycle": 2, "startedAt": "2026-10-22T08:00:00.000Z", "focusSeconds": 57900, "equals": 1810,
+//                "receipt": {"claimId": "…", "issuedAt": "2026-10-22T07:58:00.000Z"},
+//                "milestones": {"30": {"reachedAt": "…", "focusSeconds": 68722, "equals": 2110}}}]
+//
+// A cycle's start is the totals since install at the moment it began, which its first milestone counts from; the totals keep
+// counting across cycles. Nothing of cycle 1 changes when cycle 2 begins: the record is additive only (hard rule 4).
+
+// A time as toISOString writes it, and a real one: 2026-02-30 is not.
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isInstant(value) {
+  if (typeof value !== 'string' || !INSTANT.test(value)) {
+    return false;
+  }
+
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value;
+}
+
+function isCount(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+const CLAIM_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+
+// A record as KitCode writes it: when it began, and its entries.
+export function isRecord(record) {
+  return isObject(record) && isInstant(record.recordingSince) && isObject(record.milestones);
+}
+
+// The totals an entry, or freshSince, holds: both, whole and not below 0, or neither (null). Anything else is undefined:
+// not what KitCode writes.
+function totalsOf(value) {
+  const hasSeconds = Object.hasOwn(value, 'focusSeconds');
+  const hasEquals = Object.hasOwn(value, 'equals');
+
+  if (!hasSeconds && !hasEquals) {
+    return null;
+  }
+
+  return hasSeconds && hasEquals && isCount(value.focusSeconds) && isCount(value.equals)
+    ? {seconds: value.focusSeconds, equals: value.equals}
+    : undefined;
+}
+
+// One milestone's entry: {kind: 'before-recording'} or {kind: 'reached', reachedAt, end}, `end` the totals it was reached
+// at, or null when the entry holds none; undefined when it is not an entry KitCode writes.
+function entryOf(entry) {
+  if (!isObject(entry)) {
+    return undefined;
+  }
+
+  if (entry.reachedBeforeRecording === true && entry.reachedAt === undefined) {
+    return totalsOf(entry) === null ? {kind: 'before-recording', reachedAt: null, end: null} : undefined;
+  }
+
+  if (isInstant(entry.reachedAt) && entry.reachedBeforeRecording === undefined) {
+    const end = totalsOf(entry);
+    return end === undefined ? undefined : {kind: 'reached', reachedAt: entry.reachedAt, end};
+  }
+
+  return undefined;
+}
+
+// A later cycle's entry, read for `percents`, `after` the number of the cycle before it: {cycle, startedAt, start, receipt,
+// entries}, or a problem's words, a string, when it is not what KitCode writes. Each of its milestones was reached with its
+// totals: a later cycle counts from a start it knows. Its number is past the one before it, by one when the tracker took the
+// receipt of the cycle it was in, and by more since 2026-10-22's phase 3, when it took one of a cycle ahead, as the claim
+// backend counts them (milestones-reached.mjs, beginNextCycle).
+function cycleOf(value, after, percents) {
+  if (!isObject(value) || !Number.isSafeInteger(value.cycle) || value.cycle <= after || !isInstant(value.startedAt) || !isCount(value.focusSeconds) || !isCount(value.equals)
+    || !isObject(value.receipt) || typeof value.receipt.claimId !== 'string' || !CLAIM_ID.test(value.receipt.claimId) || !isInstant(value.receipt.issuedAt)
+    || !isObject(value.milestones)) {
+    return `holds a cycle after cycle ${after} that KitCode does not write`;
+  }
+
+  const cycle = value.cycle;
+  const entries = new Map();
+
+  for (const percent of percents) {
+    if (!Object.hasOwn(value.milestones, String(percent))) {
+      continue;
+    }
+
+    const entry = entryOf(value.milestones[String(percent)]);
+
+    if (entry?.kind !== 'reached' || entry.end === null) {
+      return `holds an entry for ${percent} % in cycle ${cycle} that KitCode does not write`;
+    }
+
+    entries.set(percent, entry);
+  }
+
+  return {
+    cycle,
+    startedAt: value.startedAt,
+    start: {seconds: value.focusSeconds, equals: value.equals},
+    receipt: {claimId: value.receipt.claimId, issuedAt: value.receipt.issuedAt},
+    entries,
+  };
+}
+
+// The record, read for `percents`, the milestones in order (the retired 10 and 20 % are never among them, whatever their
+// entries hold):
+//
+//   {state: 'none'}: no record yet, a file from before it, or one 0.1.39 rewrote;
+//   {state: 'damaged', problem}: not what KitCode writes, which is left as it is, never repaired or written over;
+//   {state: 'kept', recordingSince, freshSince, entries, cycles, current}: `entries` maps each percent recorded in cycle 1 to
+//   its entry, and `freshSince` is cycle 1's {at, seconds, equals} or null; since 2026-10-22 `cycles` lists the later cycles,
+//   oldest first, each {cycle, startedAt, start, receipt, entries}, and `current` is the cycle the milestones count in now:
+//   {cycle: 1, startedAt: null, start: {seconds: 0, equals: 0}, receipt: null, entries, freshSince} with no later one, else
+//   the last, its freshSince null.
+//
+// A milestone with its totals, after one whose totals are not known, counts from freshSince: without it, the record is
+// not one KitCode writes.
+export function readMilestoneRecord(record, percents) {
+  if (record === undefined) {
+    return {state: 'none'};
+  }
+
+  if (!isRecord(record)) {
+    return {state: 'damaged', problem: 'is not the record KitCode writes'};
+  }
+
+  let freshSince = null;
+
+  if (record.freshSince !== undefined) {
+    const totals = isObject(record.freshSince) && isInstant(record.freshSince.at) ? totalsOf(record.freshSince) : undefined;
+
+    if (!totals) {
+      return {state: 'damaged', problem: 'holds a start of fresh counting (freshSince) that KitCode does not write'};
+    }
+
+    freshSince = {at: record.freshSince.at, ...totals};
+  }
+
+  const entries = new Map();
+
+  for (const percent of percents) {
+    if (!Object.hasOwn(record.milestones, String(percent))) {
+      continue;
+    }
+
+    const entry = entryOf(record.milestones[String(percent)]);
+
+    if (entry === undefined) {
+      return {state: 'damaged', problem: `holds an entry for ${percent} % that KitCode does not write`};
+    }
+
+    entries.set(percent, entry);
+  }
+
+  // Each milestone's start, in order: install for the first; for another, the totals the one before it was reached at,
+  // when its entry holds them, and otherwise freshSince.
+  let previousEnd = {seconds: 0, equals: 0};
+
+  for (const percent of percents) {
+    const entry = entries.get(percent);
+
+    if (entry?.end && previousEnd === null && freshSince === null) {
+      return {state: 'damaged', problem: `holds the totals ${percent} % was reached at, with no start for them to count from`};
+    }
+
+    previousEnd = entry?.end ?? null;
+  }
+
+  // Since 2026-10-22: the later cycles, oldest first, each past the one before it, the first past cycle 1.
+  const cycles = [];
+
+  if (record.cycles !== undefined) {
+    if (!Array.isArray(record.cycles)) {
+      return {state: 'damaged', problem: 'holds cycles that KitCode does not write'};
+    }
+
+    for (const value of record.cycles) {
+      const cycle = cycleOf(value, cycles.at(-1)?.cycle ?? 1, percents);
+
+      if (typeof cycle === 'string') {
+        return {state: 'damaged', problem: cycle};
+      }
+
+      cycles.push(cycle);
+    }
+  }
+
+  const current = cycles.at(-1) ?? {cycle: 1, startedAt: null, start: {seconds: 0, equals: 0}, receipt: null, entries, freshSince};
+  return {state: 'kept', recordingSince: record.recordingSince, freshSince, entries, cycles, current: {freshSince: null, ...current}};
+}

package/src/milestones-reached.mjs

@@ -1,6 +1,7 @@
 import {equalsLedgerFrom} from './equals-ledger.mjs';
 import {focusTimeFrom} from './focus-clock.mjs';
-import {buildRewardSummary, REWARD_MILESTONES} from './reward.mjs';
+import {readMilestoneRecord} from './milestone-record.mjs';
+import {decideMilestones, MILESTONE_PERCENTS, REWARD_TIERS} from './reward.mjs';
 
 // When each milestone first became ready (docs/reward-rules.md §6.1), for the claim bundle. Kept in
 // state.json, where the tracker writes the progress it belongs to, as `milestonesReached`:
@@ -17,40 +18,38 @@ import {buildRewardSummary, REWARD_MILESTONES} from './reward.mjs';
 // 0.1.39 drops it when it rewrites the file (install-id.mjs says how). The next write of this version then
 // begins a new record, and a milestone reached by then is recorded as reached before recording began:
 // the time it was reached is lost, and none is made up.
-
-export const MILESTONE_PERCENTS = REWARD_MILESTONES.map((milestone) => milestone.percent);
-
-// A time as toISOString writes it, and a real one: 2026-02-30 is not.
-const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
-
-function isObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function isInstant(value) {
-  if (typeof value !== 'string' || !INSTANT.test(value)) {
-    return false;
-  }
-
-  const time = Date.parse(value);
-  return Number.isFinite(time) && new Date(time).toISOString() === value;
-}
-
-// A record as KitCode writes it: when it began, and its entries.
-function isRecord(record) {
-  return isObject(record) && isInstant(record.recordingSince) && isObject(record.milestones);
+//
+// Since 2026-10-08 the milestones are 30, 50 and 100 % (integration-spec.mjs): the entries an earlier version wrote for 10
+// and 20 % stay in the record, never changed or removed, as every entry does, and nothing reads them now.
+//
+// Since 2026-10-20 (rewards/2-no-stack) the record decides the milestones: each counts from the moment the one before it
+// was reached (reward.mjs decideMilestones), so an entry also holds the totals at that moment, written with it, once:
+//
+//   "50": {"reachedAt": "2026-10-20T11:03:27.918Z", "focusSeconds": 4200, "equals": 21}
+//
+// and, the first time this KitCode writes a record that holds a milestone reached without them, by an earlier KitCode or
+// before the record began, `freshSince` records the totals then: the milestone after it counts from there (the plan's
+// decision 2). An earlier entry is never given totals it did not hold, and none is made up (milestone-record.mjs).
+//
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2) the record counts in cycles (milestone-record.mjs): a milestone newly
+// reached is recorded in the cycle it is in, and a new cycle begins only by beginNextCycle, on a receipt the claim backend
+// signed for the voucher of the cycle before, which the tracker has checked (api.mjs). Nothing else begins one: no read, no
+// failure and no prompt resets anyone's progress.
+
+export {MILESTONE_PERCENTS};
+
+function totalsIn(stored, focusSeconds) {
+  return {
+    seconds: Math.floor(Math.max(0, Number(focusSeconds ?? focusTimeFrom(stored).activeSeconds) || 0)),
+    equals: Math.max(0, Number(equalsLedgerFrom(stored).total_equals) || 0),
+  };
 }
 
-// The milestones reached by `state` now: every milestone up to the highest one that is ready or
-// redeemed. A milestone's targets are never below a lower one's, so a higher milestone ready means every
-// lower one was ready then too, even one that reads locked now: a redeemed tier keeps its status when
-// its = go down (docs/reward-rules.md §6, E8).
-function reachedNow(state) {
-  const ledger = equalsLedgerFrom(state);
-  const reward = buildRewardSummary({earnedSeconds: focusTimeFrom(state).activeSeconds, totalEquals: ledger.total_equals, ledger});
-  const highest = Math.max(0, ...reward.milestones.filter((milestone) => milestone.status !== 'locked').map((milestone) => milestone.percent));
-
-  return MILESTONE_PERCENTS.filter((percent) => percent <= highest);
+function redeemedIn(stored) {
+  const tiers = new Set(REWARD_TIERS.map((tier) => tier.percent));
+  return new Set(equalsLedgerFrom(stored).earned_tiers
+    .filter((entry) => entry !== null && typeof entry === 'object' && tiers.has(Number(entry.percent)) && typeof entry.redeemed_at === 'string')
+    .map((entry) => Number(entry.percent)));
 }
 
 // Records, in `stored`, each milestone first found reached: `stored` is the file's own object, inside
@@ -59,72 +58,172 @@ function reachedNow(state) {
 // before recording began, with no time, since none is known. From then on, a milestone newly reached is
 // recorded at `now`. A record, or an entry, that is not what KitCode writes is left exactly as it is:
 // never repaired, never written over. `now` is the tracker's clock, which a test can move.
-export function noteMilestonesReached(stored, now = new Date(Date.now())) {
+//
+// Since 2026-10-20 a milestone newly reached is recorded with the totals at `now`, its focus seconds, floored, and its =;
+// `focusSeconds` is the tracker's own clock, when it folds a scan between two saves, ahead of the file's by up to one
+// save. One write reaches one milestone at most: the next counts from that write's totals, so nothing it credited counts
+// toward the next. A milestone reached with no totals known, and freshSince not yet written, has it written now.
+export function noteMilestonesReached(stored, now = new Date(Date.now()), {focusSeconds} = {}) {
   const record = stored.milestonesReached;
+  const read = readMilestoneRecord(record, MILESTONE_PERCENTS);
 
-  if (record !== undefined && !isRecord(record)) {
+  if (read.state === 'damaged') {
     return;
   }
 
-  const reached = reachedNow(stored);
+  const totals = totalsIn(stored, focusSeconds);
+  const decided = decideMilestones({totals, record, redeemed: redeemedIn(stored)});
   const at = now.toISOString();
+  const atTotals = {at, focusSeconds: totals.seconds, equals: totals.equals};
 
-  if (record === undefined) {
+  if (read.state === 'none') {
+    const before = decided.entries.filter((entry) => entry.reached);
     stored.milestonesReached = {
       recordingSince: at,
-      milestones: Object.fromEntries(reached.map((percent) => [String(percent), {reachedBeforeRecording: true}])),
+      milestones: Object.fromEntries(before.map((entry) => [String(entry.percent), {reachedBeforeRecording: true}])),
+      ...(before.length > 0 ? {freshSince: atTotals} : {}),
     };
     return;
   }
 
-  for (const percent of reached) {
-    if (!Object.hasOwn(record.milestones, String(percent))) {
-      record.milestones[String(percent)] = {reachedAt: at};
+  // The milestones of the cycle counted in: cycle 1's are the record's own; a later cycle's, its entry's, the last of `cycles`
+  // (milestone-record.mjs), whose numbers can skip since 2026-10-22's phase 3.
+  const cycle = read.current.cycle > 1 ? record.cycles[record.cycles.length - 1] : null;
+  const milestones = cycle === null ? record.milestones : cycle.milestones;
+
+  for (const entry of decided.entries) {
+    if (!entry.reached || entry.recorded || Object.hasOwn(milestones, String(entry.percent))) {
+      continue;
     }
+
+    // Found reached now, at the frontier, with the totals of this write; or below one that is, its totals not known, which a
+    // later cycle never has: it counts from a start it knows.
+    milestones[String(entry.percent)] = entry.end === null
+      ? {reachedAt: at}
+      : {reachedAt: at, focusSeconds: entry.end.seconds, equals: entry.end.equals};
   }
-}
 
-// A milestone record that is not what KitCode writes. The claim bundle does not guess at it.
-export class MilestoneRecordError extends Error {
-  constructor(problem) {
-    super(`The record of when each milestone was reached, in state.json, ${problem}. KitCode has left it as it is.`);
-    this.name = 'MilestoneRecordError';
+  const unknown = MILESTONE_PERCENTS.some((percent) => {
+    const entry = record.milestones[String(percent)];
+    return entry !== undefined && (entry.reachedBeforeRecording === true || entry.focusSeconds === undefined);
+  });
+
+  if (unknown && record.freshSince === undefined) {
+    record.freshSince = atTotals;
   }
 }
 
-function entryFor(percent, record) {
-  const key = String(percent);
+// Begins the next cycle, in `stored`, the file's own object inside updateState, on `receipt`, a receipt the tracker read and
+// found signed with the claim backend's key and for this install (cycle-receipt.mjs, api.mjs): {installId, cycle, claimId,
+// issuedAt}. The plan of 2026-10-21's decision 1: after a claim, all progress resets. The receipt of the cycle the record is in
+// begins the next, once: the record holds which receipt began each cycle, so the same receipt again, or one of a cycle past,
+// changes nothing. Since 2026-10-22's phase 3 (the coordinator's ruling: the server is the authority on cycles) one of a cycle
+// ahead, as a KitCode installed afresh after its person's earlier vouchers is given, begins the cycle after the receipt's, as the
+// claim backend counts them; until then it changed nothing, and such an install stayed in its cycle for good. Either way a
+// receipt only ever resets progress, and never adds any. The new cycle starts at the totals at `now`, `focusSeconds` the
+// tracker's own clock as a save writes it (noteMilestonesReached); the totals themselves go on counting, and nothing earlier is
+// changed or removed: the record is additive only (hard rule 4). First, as any write that makes progress does, it records what
+// is reached by now in the cycle it closes, beginning the record if none was.
+//
+// Returns {outcome: 'started', cycle, startedAt, start}; {outcome: 'used', cycle, startedAt}, the cycle this receipt began
+// already; {outcome: 'cycle', current}, the receipt of a cycle before the record's, `current`; or {outcome: 'damaged', problem},
+// a record not what KitCode writes, left as it is.
+export function beginNextCycle(stored, receipt, now = new Date(Date.now()), {focusSeconds} = {}) {
+  noteMilestonesReached(stored, now, {focusSeconds});
+  const read = readMilestoneRecord(stored.milestonesReached, MILESTONE_PERCENTS);
+
+  if (read.state === 'damaged') {
+    return {outcome: 'damaged', problem: read.problem};
+  }
+
+  const used = read.cycles.find((cycle) => cycle.receipt.claimId === receipt.claimId);
 
-  if (!Object.hasOwn(record.milestones, key)) {
-    return {percent, status: 'not-reached', reachedAt: null};
+  if (used !== undefined) {
+    return {outcome: 'used', cycle: used.cycle, startedAt: used.startedAt};
   }
 
-  const entry = record.milestones[key];
+  if (receipt.cycle < read.current.cycle) {
+    return {outcome: 'cycle', current: read.current.cycle};
+  }
 
-  if (isObject(entry) && entry.reachedBeforeRecording === true && entry.reachedAt === undefined) {
-    return {percent, status: 'reached-before-recording', reachedAt: null};
+  const totals = totalsIn(stored, focusSeconds);
+  const startedAt = now.toISOString();
+  const record = stored.milestonesReached;
+  const next = {
+    cycle: receipt.cycle + 1,
+    startedAt,
+    focusSeconds: totals.seconds,
+    equals: totals.equals,
+    receipt: {claimId: receipt.claimId, issuedAt: receipt.issuedAt},
+    milestones: {},
+  };
+
+  if (Array.isArray(record.cycles)) {
+    record.cycles.push(next);
+  } else {
+    record.cycles = [next];
   }
 
-  if (isObject(entry) && isInstant(entry.reachedAt) && entry.reachedBeforeRecording === undefined) {
-    return {percent, status: 'reached', reachedAt: entry.reachedAt};
+  return {outcome: 'started', cycle: next.cycle, startedAt, start: {focusSeconds: totals.seconds, equals: totals.equals}};
+}
+
+// A milestone record that is not what KitCode writes. The claim bundle does not guess at it.
+export class MilestoneRecordError extends Error {
+  constructor(problem) {
+    super(`The record of when each milestone was reached, in state.json, ${problem}. KitCode has left it as it is.`);
+    this.name = 'MilestoneRecordError';
   }
+}
 
-  throw new MilestoneRecordError(`holds an entry for ${percent} % that KitCode does not write`);
+function totalsField(totals) {
+  return {focusSeconds: totals.seconds, equals: totals.equals};
 }
 
 // The record as the claim bundle reports it: when it began, or null when it has not, and each
-// milestone's status and time, from 10 to 100 %. Reads only; a damaged record throws a
+// milestone's status and time, from 30 to 100 %. Reads only; a damaged record throws a
 // MilestoneRecordError.
+//
+// Since 2026-10-20 each milestone also carries `start` and `end`, the totals it counted from and those it was reached at,
+// {focusSeconds, equals}, when its entry holds them; null otherwise: not reached, or reached with no totals known.
+//
+// Since 2026-10-22 the record reported is that of the cycle counted in, `cycle`, and `cycleStart` says where it began:
+// {at: null, focusSeconds: 0, equals: 0} for cycle 1, install; the moment a later one began, and the totals then, which its
+// 30 % counts from.
+const FIRST_CYCLE_START = Object.freeze({at: null, focusSeconds: 0, equals: 0});
+
 export function milestonesReachedFrom(state) {
-  const record = state.milestonesReached;
+  const read = readMilestoneRecord(state.milestonesReached, MILESTONE_PERCENTS);
 
-  if (record === undefined) {
-    return {recordingSince: null, milestones: MILESTONE_PERCENTS.map((percent) => ({percent, status: 'not-reached', reachedAt: null}))};
+  if (read.state === 'none') {
+    return {recordingSince: null, cycle: 1, cycleStart: {...FIRST_CYCLE_START}, milestones: MILESTONE_PERCENTS.map((percent) => ({percent, status: 'not-reached', reachedAt: null, start: null, end: null}))};
   }
 
-  if (!isRecord(record)) {
-    throw new MilestoneRecordError('is not the record KitCode writes');
+  if (read.state === 'damaged') {
+    throw new MilestoneRecordError(read.problem);
   }
 
-  return {recordingSince: record.recordingSince, milestones: MILESTONE_PERCENTS.map((percent) => entryFor(percent, record))};
+  const {current} = read;
+  let previousEnd = {...current.start};
+
+  const milestones = MILESTONE_PERCENTS.map((percent) => {
+    const entry = current.entries.get(percent);
+    const start = previousEnd ?? current.freshSince;
+    previousEnd = entry?.end ?? null;
+
+    if (entry === undefined) {
+      return {percent, status: 'not-reached', reachedAt: null, start: null, end: null};
+    }
+
+    const segment = entry.end === null ? {start: null, end: null} : {start: totalsField(start), end: totalsField(entry.end)};
+    return entry.kind === 'before-recording'
+      ? {percent, status: 'reached-before-recording', reachedAt: null, ...segment}
+      : {percent, status: 'reached', reachedAt: entry.reachedAt, ...segment};
+  });
+
+  return {
+    recordingSince: read.recordingSince,
+    cycle: current.cycle,
+    cycleStart: current.cycle > 1 ? {at: current.startedAt, focusSeconds: current.start.seconds, equals: current.start.equals} : {...FIRST_CYCLE_START},
+    milestones,
+  };
 }

package/src/next-break-reminder.mjs

@@ -1,4 +1,4 @@
-import {milestoneProgressPercent} from './break-progress.mjs';
+import {earnedToward, milestoneProgressPercent} from './break-progress.mjs';
 
 export function formatBreakDuration(seconds) {
   const totalSeconds = Math.max(0, Math.floor(Number(seconds) || 0));
@@ -48,8 +48,9 @@ export function nextBreakReminder(reward) {
     return null;
   }
 
-  const earnedSeconds = Math.max(0, Number(reward.earnedSeconds) || 0);
-  const totalEquals = Math.max(0, Number(reward.totalEquals) || 0);
+  // What counts toward it: since 2026-10-20 what was earned since it began, the moment the milestone before it was
+  // reached (break-progress.mjs earnedToward); from a tracker before then, the totals.
+  const {seconds: earnedSeconds, equals: totalEquals} = earnedToward(reward, milestone);
   const requiredSeconds = Math.max(0, Number(milestone.requiredSeconds) || 0);
   const requiredEquals = Math.max(0, Number(milestone.requiredEquals) || 0);
   // Floored, so it reads 100 only once the milestone is unlocked (docs/reward-rules.md §10).

package/src/onboarding-electron.mjs

@@ -10,6 +10,7 @@ import {DASHBOARD_URL} from './integration-spec.mjs';
 import {onboardingPreferences, saveOnboardingPreferences, STORE_DIR} from './store.mjs';
 import {resolveSetupPlatform} from './onboarding-platform.mjs';
 import {renderOnboardingWindow} from './onboarding-window.mjs';
+import {WELCOME_ERRORS, WELCOME_TESTER_ERRORS, WELCOME_WORDS} from './welcome-words.mjs';
 import {keepWindowOnItsPage} from './window-guards.mjs';
 
 const sourceDirectory = path.dirname(fileURLToPath(import.meta.url));
@@ -132,7 +133,7 @@ function setupWindowOptions(platform) {
     transparent: true,
     hasShadow: false,
     backgroundColor: '#00000000',
-    title: 'Welcome to KitCode',
+    title: WELCOME_WORDS.windowTitle,
     webPreferences: {preload: preloadPath, contextIsolation: true, nodeIntegration: false, sandbox: true},
   };
 }
@@ -154,7 +155,7 @@ app.whenReady().then(() => {
   keepWindowOnItsPage(window);
   // Project records carry absolute paths: only Welcome's own page gets them.
   ipcMain.handle('kitcode:onboarding-initial-state', (event) => {
-    if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.', projects: [], suggestedProjects: []};
+    if (event.sender !== window.webContents) return {ok: false, error: WELCOME_ERRORS.invalidRequest, projects: [], suggestedProjects: []};
     return {
       ...onboardingPreferences(),
       projects: listProjectRecords(),
@@ -170,21 +171,21 @@ app.whenReady().then(() => {
     return {canceled: result.canceled, paths, projects: describeProjects(paths)};
   });
   ipcMain.handle('kitcode:onboarding-submit', async (event, input) => {
-    if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.'};
+    if (event.sender !== window.webContents) return {ok: false, error: WELCOME_ERRORS.invalidRequest};
     // A tester build's invited email, kept outside state.json, before anything else is saved; one that is not an address is
     // asked for again, and nothing is saved.
     if (diagnosticsEnabled() && typeof input?.invitedEmail === 'string' && !setInvitedEmail(input.invitedEmail).ok) {
-      return {ok: false, error: 'That email address does not look right: check it, or leave it empty.'};
+      return {ok: false, error: WELCOME_TESTER_ERRORS.invalidEmail};
     }
     const folders = validFolders(input?.folders);
-    if (!folders.length && !listProjectRecords().length) return {ok: false, error: 'Add at least one readable project folder.'};
-    try { registerNewProjects(folders); } catch { return {ok: false, error: 'KitCode could not register one of those folders.'}; }
+    if (!folders.length && !listProjectRecords().length) return {ok: false, error: WELCOME_ERRORS.noProjects};
+    try { registerNewProjects(folders); } catch { return {ok: false, error: WELCOME_ERRORS.registerFailed}; }
     const selection = {autoTrack: input?.autoTrack === true, companionView: 'mini'};
     if (selection.autoTrack && !(await runCli(['track', '--host', host, '--port', port]))) {
       saveOnboardingPreferences({...selection, completed: false});
       return {
         ok: false,
-        error: 'Projects were saved, but the tracker could not start. Free the local port and retry.',
+        error: WELCOME_ERRORS.trackerFailed,
         projects: listProjectRecords(),
       };
     }
@@ -197,14 +198,14 @@ app.whenReady().then(() => {
     return {ok: true, projects};
   });
   ipcMain.handle('kitcode:onboarding-remove-project', async (event, projectId) => {
-    if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.'};
-    if (!projectId) return {ok: false, error: 'Project not found.'};
+    if (event.sender !== window.webContents) return {ok: false, error: WELCOME_ERRORS.invalidRequest};
+    if (!projectId) return {ok: false, error: WELCOME_ERRORS.projectNotFound};
     try {
       const removed = removeProject(projectId);
-      if (!removed) return {ok: false, error: 'Project not found.'};
+      if (!removed) return {ok: false, error: WELCOME_ERRORS.projectNotFound};
       return {ok: true, projects: listProjectRecords()};
     } catch {
-      return {ok: false, error: 'KitCode could not remove that project.'};
+      return {ok: false, error: WELCOME_ERRORS.removeFailed};
     }
   });
   ipcMain.handle('kitcode:onboarding-close', (event) => {

package/src/onboarding-platform.mjs

@@ -1,3 +1,5 @@
+import {WELCOME_WORDS} from './welcome-words.mjs';
+
 const PLATFORM_CHROME = {
   darwin: {
     id: 'darwin',
@@ -41,9 +43,10 @@ export function setupPlatformTheme(platform) {
   return PLATFORM_CHROME[resolveSetupPlatform(platform)];
 }
 
+// Welcome's title bar, in Welcome's words (src/welcome-words.mjs); the Mini has its own (src/companion-controls.mjs).
 export function renderPlatformChrome(theme = setupPlatformTheme()) {
-  return `<div class="${theme.chromeClass}" title="Drag window">
-    <button class="dot filled dot-close" id="closeButton" type="button" aria-label="Close setup" title="Close"></button>
+  return `<div class="${theme.chromeClass}" title="${WELCOME_WORDS.chrome.drag}">
+    <button class="dot filled dot-close" id="closeButton" type="button" aria-label="${WELCOME_WORDS.chrome.closeName}" title="${WELCOME_WORDS.chrome.close}"></button>
     <span class="dot" aria-hidden="true"></span>
     <span class="dot" aria-hidden="true"></span>
   </div>`;