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

package/src/reward.mjs

@@ -3,22 +3,27 @@ import {equalsLedgerFrom, storedEqualsLedger} from './equals-ledger.mjs';
 import {focusTimeFrom} from './focus-clock.mjs';
 import {nextBreakReminder} from './next-break-reminder.mjs';
 import {KITCODE_DISPLAY_MILESTONES, KITCODE_REWARD_TIERS} from './integration-spec.mjs';
+import {readMilestoneRecord} from './milestone-record.mjs';
 import {loadState, updateState} from './store.mjs';
 
-// The focus time the 100 % milestone needs, fixed (operator decision Q5, 2026-09-25; docs/reward-rules.md
-// §3). Until then it was a setting, down to 1 s: --reward-seconds, KITCODE_REWARD_SECONDS, and
-// rewardSettings.requiredSeconds in state.json. A requiredSeconds an older KitCode stored stays in the
-// file, unread, as the removed requiredEquals does.
-export const REWARD_SECONDS = 3600;
 export const REWARD_TIERS = KITCODE_REWARD_TIERS;
 export const CAMPAIGN_MILESTONES = KITCODE_DISPLAY_MILESTONES;
 export const REWARD_MILESTONES = [
   ...REWARD_TIERS.map((tier) => ({...tier, rewardBacked: true})),
   ...CAMPAIGN_MILESTONES.map((milestone) => ({...milestone, rewardBacked: false})),
 ];
+export const MILESTONE_PERCENTS = REWARD_MILESTONES.map((milestone) => milestone.percent);
+// The focus time the 100 % milestone needs, fixed (operator decision Q5, 2026-09-25; docs/reward-rules.md
+// §3). Until then it was a setting, down to 1 s: --reward-seconds, KITCODE_REWARD_SECONDS, and
+// rewardSettings.requiredSeconds in state.json. A requiredSeconds an older KitCode stored stays in the
+// file, unread, as the removed requiredEquals does. Since 2026-10-20 each milestone names its own time in the table
+// (integration-spec.mjs), where it was this × its percent: the same numbers in the tester table, which held the operator's
+// from 2026-10-21 to 2026-10-22, 100 %'s 8 h, and since then its own again, 100 %'s 3600 s.
+const LAST_MILESTONE = REWARD_MILESTONES[REWARD_MILESTONES.length - 1];
+export const REWARD_SECONDS = LAST_MILESTONE.requiredSeconds;
 // The = the last milestone needs. The = targets are the table's; no setting changes them (the
 // --reward-equals setting, which gated nothing, was removed on 2026-09-24).
-const FINAL_EQUALS = Math.max(...REWARD_MILESTONES.map((milestone) => milestone.requiredEquals));
+const FINAL_EQUALS = LAST_MILESTONE.requiredEquals;
 
 const VALID_TIER_PERCENTS = new Set(REWARD_TIERS.map((tier) => tier.percent));
 
@@ -40,6 +45,27 @@ export function normalizeTierPercent(value) {
   return percent;
 }
 
+function announcementsOf(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value).filter(([source, at]) => normalizeSource(source) && typeof at === 'string'))
+    : {};
+}
+
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2) a tier is announced once per agent in each cycle: cycle 1's
+// announcements are `announced_at`, as they always were, and a later cycle's are kept by its number, `announced_in_cycles`,
+// {"2": {"claude": "2026-…"}}, a field written only once a later cycle has one, so that a file with none is byte for byte
+// what it was, and a KitCode from before reads cycle 1's as ever.
+function cycleAnnouncementsOf(value) {
+  if (!isObject(value)) {
+    return {};
+  }
+
+  return Object.fromEntries(Object.entries(value)
+    .filter(([cycle]) => /^[1-9][0-9]*$/u.test(cycle) && Number(cycle) >= 2)
+    .map(([cycle, announced]) => [cycle, announcementsOf(announced)])
+    .filter(([, announced]) => Object.keys(announced).length > 0));
+}
+
 function normalizeTierRecord(entry) {
   const percent = normalizeTierPercent(
     typeof entry === 'object' && entry !== null ? entry.percent : entry,
@@ -49,20 +75,21 @@ function normalizeTierRecord(entry) {
     return null;
   }
 
-  const announcedAt = entry?.announced_at && typeof entry.announced_at === 'object'
-    ? Object.fromEntries(
-      Object.entries(entry.announced_at)
-        .filter(([source, value]) => normalizeSource(source) && typeof value === 'string'),
-    )
-    : {};
+  const byCycle = cycleAnnouncementsOf(entry?.announced_in_cycles);
 
   return {
     percent,
     redeemed_at: typeof entry?.redeemed_at === 'string' ? entry.redeemed_at : null,
-    announced_at: announcedAt,
+    announced_at: announcementsOf(entry?.announced_at),
+    ...(Object.keys(byCycle).length > 0 ? {announced_in_cycles: byCycle} : {}),
   };
 }
 
+// Whether `record`, a tier's record, normalized, holds its announcement to `source` in `cycle`.
+function announcedIn(record, source, cycle) {
+  return cycle > 1 ? Boolean(record?.announced_in_cycles?.[String(cycle)]?.[source]) : Boolean(record?.announced_at?.[source]);
+}
+
 export function normalizeEarnedTiers(entries) {
   const records = new Map();
 
@@ -74,6 +101,12 @@ export function normalizeEarnedTiers(entries) {
     }
 
     const existing = records.get(record.percent);
+    const byCycle = {...(existing?.announced_in_cycles ?? {})};
+
+    for (const [cycle, announced] of Object.entries(record.announced_in_cycles ?? {})) {
+      byCycle[cycle] = {...(byCycle[cycle] ?? {}), ...announced};
+    }
+
     records.set(record.percent, {
       percent: record.percent,
       redeemed_at: existing?.redeemed_at ?? record.redeemed_at,
@@ -81,6 +114,7 @@ export function normalizeEarnedTiers(entries) {
         ...(existing?.announced_at ?? {}),
         ...record.announced_at,
       },
+      ...(Object.keys(byCycle).length > 0 ? {announced_in_cycles: byCycle} : {}),
     });
   }
 
@@ -125,65 +159,176 @@ function updateTierRecord(ledger, percent, change) {
   });
 }
 
-function milestoneTimeTarget(requiredSeconds, percent) {
-  return Math.ceil(requiredSeconds * (percent / 100));
+function reachesTargets(earned, milestone) {
+  return earned.seconds >= milestone.requiredSeconds && earned.equals >= milestone.requiredEquals;
+}
+
+// The milestones as they stacked until 2026-10-20 (docs/reward-rules.md §2): each reached when the totals since install
+// meet its own targets, with every milestone below the highest one reached, or whose code an earlier KitCode recorded as
+// shown (E8). A record that is not what KitCode writes is read so, and nothing is written over it (decideMilestones).
+function stackedReached(totals, redeemed) {
+  const highest = Math.max(0, ...REWARD_MILESTONES
+    .filter((milestone) => reachesTargets(totals, milestone) || redeemed.has(milestone.percent))
+    .map((milestone) => milestone.percent));
+
+  return new Set(MILESTONE_PERCENTS.filter((percent) => percent <= highest));
 }
 
-// The reward summary for `earnedSeconds` of focus time and `totalEquals` counted, against the fixed time
-// target and the tier table's = targets. It takes no target: a `settings` a caller still passes, as
-// older code and tests do, is not read.
-export function buildRewardSummary({earnedSeconds, totalEquals, ledger}) {
-  const requiredSeconds = REWARD_SECONDS;
+// Which milestones are reached, and where each counts from (docs/reward-rules.md §2; the plan of 2026-10-20, decisions 1
+// to 3). Each counts its own focus time and = from the moment the milestone before it was reached, the first from install,
+// and is reached when what was earned since meets both its targets: nothing earned before that moment counts toward it,
+// neither the time earned while waiting for = nor the = while waiting for time. So at most one is reached at a time.
+//
+// `totals` are the focus seconds, floored, and the = counted since install; `record` the milestone record as state.json
+// holds it; `redeemed` the tiers an earlier KitCode recorded a code shown for. A milestone the record holds is reached,
+// whatever the totals say now, and so is every one below it: a reached milestone stays reached. One that is not held
+// is reached once the totals since its start meet its targets, its moment the moment this is found: the record's next
+// write records it, with these totals.
+//
+// Decision 2, people who reached milestones before this rule: a milestone reached with no totals known, an earlier
+// KitCode's entry or one reached before the record began, keeps its place, and the one after it counts from the record's
+// freshSince, the totals when this KitCode first wrote such a record; until that write, from the totals now. A file with
+// no record yet is read as the first write will record it: the milestones its totals reached as they stacked, reached
+// before the record began, and the next counting from now.
+//
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2; the plan of 2026-10-21, decision 1) the milestones count in the cycle
+// the record is in (milestone-record.mjs): cycle 1, as above, until the tracker takes a receipt the claim backend signed for
+// a voucher; then the next, whose milestones all count fresh from the totals at that moment, the first from there where cycle
+// 1's counts from install. Nothing of an earlier cycle counts toward a later one, and nothing an earlier KitCode recorded as a
+// code shown (`redeemed`) does either: that is cycle 1's.
+//
+// Returns {stacked, entries, cycle}: `stacked` true for a record that is not what KitCode writes, read as the milestones
+// stacked; otherwise each entry {percent, reached, recorded, countedFrom, end}, `countedFrom` the totals the milestone counts
+// from, or null for one that has not begun, or whose start is not known; `end` the totals it was reached at, null when not
+// known; and `cycle` {number, startedAt, start}, the cycle counted in, when it began (null for cycle 1) and its start totals.
+export function decideMilestones({totals, record, redeemed = new Set()}) {
+  const read = readMilestoneRecord(record, MILESTONE_PERCENTS);
+
+  if (read.state === 'damaged') {
+    return {stacked: true, reached: stackedReached(totals, redeemed)};
+  }
+
+  const current = read.state === 'none' ? null : read.current;
+  const later = current !== null && current.cycle > 1;
+  const before = read.state === 'none'
+    ? new Map([...stackedReached(totals, redeemed)].map((percent) => [percent, {kind: 'before-recording', end: null}]))
+    : current.entries;
+  const freshSince = read.state === 'none' ? null : current.freshSince;
+  const shown = later ? [] : [...redeemed].filter((percent) => MILESTONE_PERCENTS.includes(percent));
+  const highest = Math.max(0, ...before.keys(), ...shown);
+  const entries = [];
+  // Where the next milestone counts from: install for the first of cycle 1, a later cycle's start for its first; null once one
+  // has not been reached.
+  let start = later ? {...current.start} : {seconds: 0, equals: 0};
+  let startKnown = true;
+
+  for (const milestone of REWARD_MILESTONES) {
+    const entry = before.get(milestone.percent);
+
+    if (start === null) {
+      entries.push({percent: milestone.percent, reached: false, recorded: false, countedFrom: null, end: null});
+      continue;
+    }
+
+    if (milestone.percent <= highest) {
+      const end = entry?.end ?? null;
+      entries.push({percent: milestone.percent, reached: true, recorded: entry !== undefined, countedFrom: startKnown ? start : null, end});
+      start = end ?? (freshSince ? {seconds: freshSince.seconds, equals: freshSince.equals} : {...totals});
+      startKnown = end !== null || freshSince !== null;
+      continue;
+    }
+
+    const earned = {seconds: Math.max(0, totals.seconds - start.seconds), equals: Math.max(0, totals.equals - start.equals)};
+
+    if (reachesTargets(earned, milestone)) {
+      entries.push({percent: milestone.percent, reached: true, recorded: false, countedFrom: start, end: {...totals}});
+      start = {...totals};
+      startKnown = true;
+      continue;
+    }
+
+    entries.push({percent: milestone.percent, reached: false, recorded: false, countedFrom: start, end: null});
+    start = null;
+  }
+
+  return {
+    stacked: false,
+    entries,
+    cycle: later ? {number: current.cycle, startedAt: current.startedAt, start: {...current.start}} : {number: 1, startedAt: null, start: {seconds: 0, equals: 0}},
+  };
+}
+
+// The focus time still needed to reach 100 %, each milestone not reached counted fresh, the current one from its start.
+function timeLeft(totals, milestones) {
+  return milestones.reduce((sum, milestone) => {
+    if (milestone.unlocked) {
+      return sum;
+    }
+
+    const from = milestone.countedFrom?.seconds;
+    return sum + Math.max(0, milestone.requiredSeconds - (from === undefined || from === null ? 0 : Math.max(0, totals.seconds - from)));
+  }, 0);
+}
+
+// The reward summary for `earnedSeconds` of focus time and `totalEquals` counted, against the milestone table
+// (integration-spec.mjs), and the milestone record (`record`, state.json's milestonesReached; decideMilestones). It takes
+// no target: a `settings` a caller still passes, as older code and tests do, is not read.
+//
+// Since 2026-10-20 each milestone of the summary also says where it counts from, `countedFrom`, {seconds, equals}, or null
+// for one that has not begun: what counts toward it is what was earned since (break-progress.mjs). A record that is not
+// what KitCode writes gives the summary as it was before: no `countedFrom`, every milestone counted from install.
+//
+// Since 2026-10-22 the summary says the cycle its milestones count in, `cycle`, 1 until the tracker takes a receipt for a
+// voucher (decideMilestones), and `cycleStartedAt`, when a later one began, null for cycle 1; both null for a record that is
+// not what KitCode writes. Its milestones and tiers are that cycle's: in a later one, none is `redeemed`, a code an earlier
+// KitCode recorded as shown being cycle 1's.
+export function buildRewardSummary({earnedSeconds, totalEquals, ledger, record}) {
   const records = tierRecordMap(ledger);
   const normalizedEarnedSeconds = Math.floor(Math.max(0, Number(earnedSeconds) || 0));
   const normalizedTotalEquals = Math.max(0, Number(totalEquals) || 0);
-  const tiers = REWARD_TIERS.map((tier) => {
-    const record = records.get(tier.percent);
-    const requiredTimeSeconds = milestoneTimeTarget(requiredSeconds, tier.percent);
-    const unlocked = (
-      normalizedEarnedSeconds >= requiredTimeSeconds &&
-      normalizedTotalEquals >= tier.requiredEquals
-    );
-    const redeemed = Boolean(record?.redeemed_at);
+  const totals = {seconds: normalizedEarnedSeconds, equals: normalizedTotalEquals};
+  const redeemed = new Set(REWARD_TIERS.filter((tier) => records.get(tier.percent)?.redeemed_at).map((tier) => tier.percent));
+  const decided = decideMilestones({totals, record, redeemed});
+  const laterCycle = !decided.stacked && decided.cycle.number > 1;
+  const milestones = REWARD_MILESTONES.map((milestone, index) => {
+    const record = records.get(milestone.percent);
+    const isRedeemed = milestone.rewardBacked && Boolean(record?.redeemed_at) && !laterCycle;
+    const unlocked = decided.stacked ? decided.reached.has(milestone.percent) : decided.entries[index].reached;
 
     return {
-      percent: tier.percent,
-      requiredEquals: tier.requiredEquals,
-      requiredSeconds: requiredTimeSeconds,
+      percent: milestone.percent,
+      requiredEquals: milestone.requiredEquals,
+      requiredSeconds: milestone.requiredSeconds,
+      rewardBacked: milestone.rewardBacked,
+      displayOnly: !milestone.rewardBacked,
       unlocked,
-      redeemed,
-      redeemedAt: record?.redeemed_at ?? null,
-      status: redeemed ? 'redeemed' : unlocked ? 'ready' : 'locked',
+      redeemed: isRedeemed,
+      redeemedAt: isRedeemed ? record.redeemed_at : null,
+      status: isRedeemed ? 'redeemed' : unlocked ? 'ready' : 'locked',
+      ...(decided.stacked ? {} : {countedFrom: decided.entries[index].countedFrom}),
     };
   });
-  const tierMap = new Map(tiers.map((tier) => [tier.percent, tier]));
+  const tierPercents = new Set(REWARD_TIERS.map((tier) => tier.percent));
+  const tiers = milestones.filter((milestone) => tierPercents.has(milestone.percent)).map((milestone) => ({
+    percent: milestone.percent,
+    requiredEquals: milestone.requiredEquals,
+    requiredSeconds: milestone.requiredSeconds,
+    unlocked: milestone.unlocked,
+    redeemed: milestone.redeemed,
+    redeemedAt: milestone.redeemedAt,
+    status: milestone.status,
+  }));
 
   const summary = {
-    requiredSeconds,
+    requiredSeconds: REWARD_SECONDS,
     requiredEquals: FINAL_EQUALS,
     earnedSeconds: normalizedEarnedSeconds,
     totalEquals: normalizedTotalEquals,
-    timeLeftSeconds: Math.max(0, Math.floor(requiredSeconds - normalizedEarnedSeconds)),
+    timeLeftSeconds: timeLeft(totals, milestones),
+    cycle: decided.stacked ? null : decided.cycle.number,
+    cycleStartedAt: decided.stacked ? null : decided.cycle.startedAt,
     tiers,
-    milestones: REWARD_MILESTONES.map((milestone) => {
-      const tier = tierMap.get(milestone.percent);
-      const requiredTimeSeconds = tier?.requiredSeconds ?? milestoneTimeTarget(requiredSeconds, milestone.percent);
-      const timeReached = normalizedEarnedSeconds >= requiredTimeSeconds;
-      const equalsReached = normalizedTotalEquals >= milestone.requiredEquals;
-      const unlocked = timeReached && equalsReached;
-
-      return {
-        percent: milestone.percent,
-        requiredEquals: milestone.requiredEquals,
-        requiredSeconds: requiredTimeSeconds,
-        rewardBacked: milestone.rewardBacked,
-        displayOnly: !milestone.rewardBacked,
-        unlocked,
-        redeemed: tier?.redeemed ?? false,
-        redeemedAt: tier?.redeemedAt ?? null,
-        status: tier?.status ?? (unlocked ? 'ready' : 'locked'),
-      };
-    }),
+    milestones,
   };
 
   // The one progress number the CLI, the Mini and the dashboard all show (docs/reward-rules.md
@@ -203,6 +348,7 @@ function rewardSummaryFrom(state) {
     earnedSeconds,
     totalEquals: ledger.total_equals,
     ledger,
+    record: state.milestonesReached,
   });
 }
 
@@ -227,6 +373,7 @@ function saveTierRecords(changes) {
 // code an earlier version recorded as shown keeps its redeemed_at, and so its status, `redeemed`: it was reached, and
 // the record says so (docs/reward-rules.md §7).
 
+// Each tier given is announced to `source` in its cycle, `tier.cycle`, 1 when it names none (getReadyUnannouncedTiers).
 export function markTiersAnnounced(source, tiers) {
   const normalizedSource = normalizeSource(source);
 
@@ -245,8 +392,12 @@ export function markTiersAnnounced(source, tiers) {
       continue;
     }
 
-    changes.push([percent, (record) => ({...record, announced_at: {...record.announced_at, [normalizedSource]: now}})]);
-    announced.push({...tier, announcedAt: now});
+    const cycle = Number.isSafeInteger(tier.cycle) && tier.cycle > 1 ? tier.cycle : 1;
+
+    changes.push([percent, (record) => (cycle === 1
+      ? {...record, announced_at: {...record.announced_at, [normalizedSource]: now}}
+      : {...record, announced_in_cycles: {...record.announced_in_cycles, [cycle]: {...record.announced_in_cycles?.[cycle], [normalizedSource]: now}}})]);
+    announced.push({...tier, cycle, announcedAt: now});
   }
 
   if (changes.length > 0) {
@@ -265,10 +416,10 @@ export function getReadyUnannouncedTiers(source) {
 
   const state = loadState();
   const records = tierRecordMap(equalsLedgerFrom(state));
+  const summary = rewardSummaryFrom(state);
+  const cycle = summary.cycle ?? 1;
 
-  return rewardSummaryFrom(state).tiers.filter((tier) => {
-    const record = records.get(tier.percent);
-
-    return tier.status === 'ready' && !record?.announced_at?.[normalizedSource];
-  });
+  return summary.tiers
+    .filter((tier) => tier.status === 'ready' && !announcedIn(records.get(tier.percent), normalizedSource, cycle))
+    .map((tier) => ({...tier, cycle}));
 }

package/src/runtime.mjs

@@ -43,7 +43,7 @@ import {
   startedFocusTime,
   storedFocusTime,
 } from './focus-clock.mjs';
-import {noteMilestonesReached} from './milestones-reached.mjs';
+import {beginNextCycle, noteMilestonesReached} from './milestones-reached.mjs';
 import {buildRewardSummary} from './reward.mjs';
 import {createScanner} from './scanner.mjs';
 
@@ -452,7 +452,10 @@ export function prepareState({rules = RULES, to = RULES_VERSION} = {}) {
 // earns nothing (§5.2, §5.7); a read that is a baseline, because code can have arrived through git,
 // earns nothing at all (§5.8). Returns null when the project is not in state.json, or when a partial
 // read cannot make its first snapshot.
-function foldScan(project, read, base, {lockTimeoutMs} = {}) {
+//
+// `focusSeconds` is the tracker's own clock, when it folds: ahead of the file's by up to one save, and the moment a milestone
+// these = reach is recorded at with it (milestones-reached.mjs).
+function foldScan(project, read, base, {lockTimeoutMs, focusSeconds} = {}) {
   return withStateLock(() => {
     // An older file is converted first, in this same update: after an upgrade, the first scan does it.
     migrateState();
@@ -492,7 +495,7 @@ function foldScan(project, read, base, {lockTimeoutMs} = {}) {
           stored.projects[project.id].changeBatchCount = (Number(current.changeBatchCount) || 0) + 1;
           addSourceEqualsOnce(project, crypto.randomUUID(), result.equalsAdded);
           // = credited can make a milestone ready: recorded in this same update (docs/reward-rules.md §6.1).
-          noteMilestonesReached(stored);
+          noteMilestonesReached(stored, undefined, {focusSeconds});
         }
       });
     }
@@ -504,6 +507,7 @@ function foldScan(project, read, base, {lockTimeoutMs} = {}) {
       ...result,
       changeBatchCount: Number(after.projects[project.id].changeBatchCount) || 0,
       ledger: equalsLedgerFrom(after),
+      record: after.milestonesReached,
     };
   }, {lockTimeoutMs});
 }
@@ -541,6 +545,8 @@ export function createRuntime(options) {
     options,
     state: normalizeState(stored),
     ledger: equalsLedgerFrom(stored),
+    // The milestone record, which decides the milestones since 2026-10-20 (reward.mjs decideMilestones).
+    record: stored.milestonesReached,
     focus: focusClockFrom(stored),
     stateIdentity,
     projectRuns: new Map(),
@@ -890,7 +896,7 @@ function applyRead(runtime, projectId, run, read, base, activityAt) {
   let result;
 
   try {
-    result = foldScan(project, read, base, {lockTimeoutMs: SCAN_LOCK_TIMEOUT_MS});
+    result = foldScan(project, read, base, {lockTimeoutMs: SCAN_LOCK_TIMEOUT_MS, focusSeconds: runtime.focus?.activeSeconds});
   } catch (error) {
     if (!(error instanceof StateLockError)) {
       throw error;
@@ -908,6 +914,7 @@ function applyRead(runtime, projectId, run, read, base, activityAt) {
     project.sourceSnapshot = result.snapshot;
     project.changeBatchCount = result.changeBatchCount;
     runtime.ledger = result.ledger;
+    runtime.record = result.record;
     clearProblem(runtime, 'scan-failed', projectId);
     clearProblem(runtime, 'project-missing', projectId);
     const at = activityAt(result);
@@ -1150,6 +1157,7 @@ function reconcileProjects(runtime) {
     const diskState = normalizeState(stored);
     runtime.stateIdentity = identity;
     runtime.ledger = equalsLedgerFrom(stored);
+    runtime.record = stored.milestonesReached;
 
     for (const [projectId, project] of Object.entries(runtime.state.projects)) {
       if (!diskState.projects[projectId]) {
@@ -1184,6 +1192,8 @@ function reconcileProjects(runtime) {
 // the file is left as it is. Since 2026-09-25 it also records a milestone its time has made ready
 // (docs/reward-rules.md §6.1), within one save, 10 s, of it becoming ready.
 export function persistRuntimeState(runtime, options) {
+  let saved = null;
+
   updateState((stored) => {
     if (!isObject(stored.projects)) {
       return;
@@ -1215,7 +1225,40 @@ export function persistRuntimeState(runtime, options) {
 
     stored.version = 4;
     noteMilestonesReached(stored);
+    saved = {record: stored.milestonesReached === undefined ? undefined : structuredClone(stored.milestonesReached)};
   }, options);
+
+  // What the save recorded, for the tracker's own summary until its next read of the file. A copy: the file's object is
+  // the store's.
+  if (saved) {
+    runtime.record = saved.record;
+  }
+}
+
+// Begins the next cycle on `receipt`, one the tracker has read and checked (api.mjs, POST /api/claim/receipt; the plan of
+// 2026-10-21, decision 1), in one locked write with the tracker's own save: its counters first, as every save writes them,
+// so that the cycle starts at the totals the tracker shows, the focus time on its own clock among them; then the record
+// (milestones-reached.mjs, beginNextCycle), which says whether this receipt may begin one, and adds the cycle if it may.
+// Nothing else in the file changes, and the totals are never reduced. Returns beginNextCycle's outcome; throws the store's
+// StateLockError when the file stays locked, and its StateFileError when it cannot be read, as a save does, having written
+// nothing.
+export function startNextCycle(runtime, receipt, {lockTimeoutMs = PERIODIC_SAVE_LOCK_TIMEOUT_MS} = {}) {
+  let outcome = null;
+  let saved;
+
+  withStateLock(() => {
+    tickActiveProjects(runtime);
+    persistRuntimeState(runtime);
+    outcome = updateState((stored) => {
+      const result = beginNextCycle(stored, receipt, new Date(Date.now()));
+      saved = stored.milestonesReached === undefined ? undefined : structuredClone(stored.milestonesReached);
+      return result;
+    });
+  }, {lockTimeoutMs});
+
+  // What the write recorded, for the tracker's own summary at once: the new cycle's milestones count from now.
+  runtime.record = saved;
+  return outcome;
 }
 
 // Runs one of the tracker's periodic jobs. A busy lock skips it until the next tick. A state file
@@ -1253,6 +1296,7 @@ export function buildSummary(runtime) {
     earnedSeconds: focus.activeSeconds,
     totalEquals,
     ledger,
+    record: 'record' in runtime ? runtime.record : loadState().milestonesReached,
   });
 
   return {

package/src/welcome-words.mjs

@@ -0,0 +1,115 @@
+// Every word Welcome shows, in one place: the client's Vietnamese, word for word as the deck has it, and the operator's
+// approved drafts where the deck does not reach (docs/plans/2026-10-22-vietnamese-setup-and-welcome-strings.md; each line
+// names its row there, a number for the deck's, an id for a draft's). "just make sure the translation stay truthful to the
+// deck": the deck's own spelling stays, "Kitcode" in row 56 included. A "\n" is the deck's line break; "{N}" is a count and
+// "{name}" a folder's name, which the page fills in. Everything here is NFC, and every character is in the fonts Welcome
+// embeds (test/welcome-words.test.mjs). Nothing here may say a reward was claimed, saved or confirmed (hard rule 8): "Đã lưu
+// project" is about projects.
+//
+// The page shows some of these in capitals, as the English was: the rail, the + THÊM PROJECT button (typed so by
+// onboarding-window.mjs), and the section titles and the hint (by its stylesheet).
+
+export const WELCOME_WORDS = {
+  // The page's own name, which the OS lists the window by (X8a), and the native window's, before the page loads (X8b).
+  title: 'Thiết lập KitCode',
+  windowTitle: 'Chào mừng bạn đến với KitCode',
+
+  // The title bar (src/onboarding-platform.mjs): its tooltip (X7e), and the close dot's tooltip and name (X7g, X7f).
+  chrome: {
+    drag: 'Kéo để di chuyển cửa sổ',
+    close: 'Đóng',
+    closeName: 'Đóng cửa sổ thiết lập',
+  },
+
+  // The rail's steps 01 and 02 (rows 54, 55).
+  rail: {
+    tracking: 'Thiết lập',
+    projects: 'Chọn project',
+  },
+
+  // Step 01: the question (row 56), its radio group's name (X7c, row 56 again), and the answers (rows 57, 58), between "[ ]".
+  tracking: {
+    question: 'Bắt đầu tracking sau khi thiết lập Kitcode',
+    groupName: 'Bắt đầu tracking sau khi thiết lập Kitcode',
+    yes: 'CÓ',
+    no: 'KHÔNG',
+  },
+
+  // Step 02: the heading (row 59), the list's name (X7d), the button after "+ " (row 60), the hint beside it (row 61), the
+  // empty list (X4), and each project's remove button, its tooltip (X7a) and its name (X7b).
+  projects: {
+    heading: 'Chọn một hoặc nhiều folder local',
+    listName: 'Danh sách project của KitCode',
+    add: 'Thêm project',
+    hint: 'Các tệp hiện có sẽ được lấy làm mốc để theo dõi thay đổi.\nMã nguồn và mọi thay đổi đều chỉ được lưu trên máy bạn.',
+    empty: 'Chưa thêm project nào',
+    removeTitle: 'Gỡ project',
+    removeName: 'Gỡ {name}',
+  },
+
+  // The main button: between "+ " and " ->" (row 62); while saving (N18); saved (row 72); after a failed save (X5a).
+  buttons: {
+    save: 'ĐÃ XONG, MỞ KITCODE ĐỂ TÍNH CÔNG',
+    saving: 'Đang lưu…',
+    saved: 'Thiết lập hoàn tất.',
+    retry: 'Thử lưu lại',
+  },
+
+  // The message line, after "/* ".
+  messages: {
+    ready: 'Chọn một hay nhiều project để tiếp tục', // row 77
+    suggested: 'Đã thêm {N} folder project. Kiểm tra và lưu để tiếp tục.', // row 64
+    loaded: 'Đã chọn {N} project', // row 70
+    stateFailed: 'Không thể tải trạng thái thiết lập trên máy. Hãy khởi động lại quá trình thiết lập và thử lại nhé!', // row 76
+    noBridge: 'Không thể kết nối với KitCode setup. Vui lòng đóng cửa sổ này và thử lại.', // row 73
+    picking: 'Đang mở trình chọn folder…', // N14
+    pickCanceled: 'Đã hủy chọn project', // row 65
+    readyToAdd: '{N} project đã sẵn sàng', // row 69
+    alreadyAdded: 'Project đã được thêm', // row 63
+    pickerFailed: 'Không thể mở trình chọn folder.\nHãy khởi động lại phần thiết lập và thử lại nhé!', // row 66
+    removed: 'Đã gỡ project', // row 67
+    removedFromSetup: 'Đã gỡ project khỏi phần thiết lập này.', // N15
+    removeFailed: 'Không thể gỡ project.', // N16a
+    removeFailedRetry: 'Không thể gỡ project. Hãy thử lại nhé!', // N16b
+    noProjects: 'Hãy chọn ít nhất một project', // row 68
+    saving: 'Đang lưu project và tùy chỉnh…', // row 75
+    saveFailed: 'Không thể lưu thiết lập.', // N17
+    requestFailed: 'Không thể gửi yêu cầu thiết lập. Yên tâm, lựa chọn của bạn vẫn còn đây.', // X5b
+    saved: 'Vậy là xong. KitCode sắp lên sóng!', // row 71
+  },
+};
+
+// A tester build's alone (src/diagnostics.mjs): the rail's step 03 (N19), the step's heading (row 78), what the build sends
+// and never holds (row 79, two paragraphs), and the invited email's label (row 80). Any other build's page holds none of it.
+export const WELCOME_TESTER_WORDS = {
+  rail: 'Tìm sự cố',
+  heading: 'TÌM SỰ CỐ ĐỂ KHÔNG SAI SỐ',
+  text: 'KitCode gửi diagnostic log đến máy chủ, ghi lại các hoạt động và lỗi của KitCode (như lỗi khởi động tracker hoặc lỗi hook). Nhờ vậy, đội ngũ phát triển có thể truy vết sự cố mà không cần hỏi thêm bạn.\n\nDiagnostic log không chứa mã nguồn, tệp, prompt hay tên project của bạn.',
+  emailLabel: 'Email nhận lời mời (không bắt buộc): Giúp đội ngũ hỗ trợ tìm đúng diagnostic log của bạn nhanh hơn.',
+};
+
+// What the main process answers (src/onboarding-electron.mjs), which the page shows on its message line as it is.
+export const WELCOME_ERRORS = {
+  invalidRequest: 'Yêu cầu thiết lập không hợp lệ.', // X6a, answered only to a sender other than Welcome's page
+  noProjects: 'Hãy chọn ít nhất một project', // X6c, row 68's
+  registerFailed: 'KitCode không thể thêm một trong các folder bạn vừa chọn.', // X6d
+  trackerFailed: 'Đã lưu project, nhưng tracker không khởi động được', // row 74
+  projectNotFound: 'Không tìm thấy project.', // X6e
+  removeFailed: 'KitCode không thể gỡ project này.', // X6f
+};
+
+// A tester build's alone: an invited email that is not an address (X6b).
+export const WELCOME_TESTER_ERRORS = {
+  invalidEmail: 'Email này có vẻ chưa đúng. Kiểm tra lại hoặc để trống nhé.',
+};
+
+// What the deck keeps English ("ko cần dịch", rows 81-83), and what is never shown (N13): marked lang="en" in the page.
+// The status bar's codes (setup:ready, projects:removed…) are codes, and stay where the script sets them (K7).
+export const WELCOME_ENGLISH = {
+  topTag: 'local-first setup', // row 81
+  mode: 'NORMAL', // row 82
+  shortcuts: '↑↓ move # space select # enter continue', // row 82
+  pending: 'PENDING', // row 83
+  tracked: 'TRACKED', // row 83
+  added: '{N} ADDED', // N13, display: none
+};

package/src/window-page.mjs

@@ -7,12 +7,26 @@ import fs from 'node:fs';
 // 5.3.0, under the SIL Open Font License 1.1 (fonts/<family>/OFL.txt, from github.com/google/fonts).
 // Embedded as data: URLs, so a page asks no server for them, whether it is a file, a data: URL or
 // served by the tracker. A character outside the subset falls back to the next font in the stack.
+// Since 2026-10-22 also JetBrains Mono, Welcome's alone, which speaks Vietnamese: its latin and vietnamese subsets, from
+// @fontsource/jetbrains-mono 5.3.0, each with the unicode-range Google Fonts gives it, so that the two read as one font.
+// Fira Code has no Vietnamese subset (docs/plans/2026-10-22-vietnamese-setup-and-welcome.md, "Fonts"); the Mini keeps it.
+const JETBRAINS_MONO_RANGES = {
+  latin: 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD',
+  vietnamese: 'U+0102-0103,U+0110-0111,U+0128-0129,U+0168-0169,U+01A0-01A1,U+01AF-01B0,U+0300-0301,U+0303-0304,U+0308-0309,U+0323,U+0329,U+1EA0-1EF9,U+20AB',
+};
+
 const FONTS = {
   'vt323': {family: 'VT323', faces: [{weight: 400, file: 'vt323/vt323-latin-400-normal.woff2'}]},
   'fira-code': {
     family: 'Fira Code',
     faces: [400, 500, 700].map((weight) => ({weight, file: `fira-code/fira-code-latin-${weight}-normal.woff2`})),
   },
+  'jetbrains-mono': {
+    family: 'JetBrains Mono',
+    faces: [400, 500, 700].flatMap((weight) => ['vietnamese', 'latin'].map((subset) => (
+      {weight, file: `jetbrains-mono/jetbrains-mono-${subset}-${weight}-normal.woff2`, range: JETBRAINS_MONO_RANGES[subset]}
+    ))),
+  },
 };
 
 const fontFaceCache = new Map();
@@ -21,9 +35,9 @@ export function fontFaces(names) {
   const key = names.join(',');
 
   if (!fontFaceCache.has(key)) {
-    fontFaceCache.set(key, names.flatMap((name) => FONTS[name].faces.map(({weight, file}) => {
+    fontFaceCache.set(key, names.flatMap((name) => FONTS[name].faces.map(({weight, file, range}) => {
       const data = fs.readFileSync(new URL(`./fonts/${file}`, import.meta.url)).toString('base64');
-      return `@font-face{font-family:'${FONTS[name].family}';font-style:normal;font-weight:${weight};font-display:swap;src:url(data:font/woff2;base64,${data}) format('woff2')}`;
+      return `@font-face{font-family:'${FONTS[name].family}';font-style:normal;font-weight:${weight};font-display:swap;src:url(data:font/woff2;base64,${data}) format('woff2')${range ? `;unicode-range:${range}` : ''}}`;
     })).join('\n'));
   }