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

package/src/reward.mjs

@@ -3,25 +3,42 @@ 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';
+import {campaignEnded, trackingConfigInForce} from './tracking-config.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})),
 ];
-// 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));
+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. The = targets are the table's too; no
+// setting of the user's changes either (the --reward-equals setting, which gated nothing, was removed on 2026-09-24). Since
+// 2026-10-23 these are the bundled table's, the last of the three fallbacks: the summary's requiredSeconds and requiredEquals are
+// the last milestone's in force (milestonesOf, below), which the server's tracking config may set (tracking-config.mjs).
+const LAST_MILESTONE = REWARD_MILESTONES[REWARD_MILESTONES.length - 1];
+export const REWARD_SECONDS = LAST_MILESTONE.requiredSeconds;
 
 const VALID_TIER_PERCENTS = new Set(REWARD_TIERS.map((tier) => tier.percent));
 
+// The milestones, with the targets of `config`, a tracking config (tracking-config.mjs): by default the one in force, the
+// document the tracker took from the server, its last good copy, or the table this KitCode bundles, the REWARD_MILESTONES above.
+// Since 2026-10-23 (tracking/2-cli; docs/plans/2026-10-22-server-tracking-config.md) every milestone is decided against the
+// targets in force at the moment it is decided: a milestone reached stays reached, whatever the targets do after (the record says
+// so); the one in progress keeps what it earned since it began, and is reached once that meets the targets now in force, so a
+// target lowered under what it earned reaches it at the next write, and one raised only lowers its percent. The percents are the
+// contract's, 30, 50 and 100, and 30 % the one tier, as before.
+export function milestonesOf(config = trackingConfigInForce()) {
+  return config.milestones.map(({percent, focusSeconds, equals}) => ({percent, requiredSeconds: focusSeconds, requiredEquals: equals, rewardBacked: VALID_TIER_PERCENTS.has(percent)}));
+}
+
 function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -40,6 +57,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 +87,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 +113,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 +126,7 @@ export function normalizeEarnedTiers(entries) {
         ...(existing?.announced_at ?? {}),
         ...record.announced_at,
       },
+      ...(Object.keys(byCycle).length > 0 ? {announced_in_cycles: byCycle} : {}),
     });
   }
 
@@ -125,72 +171,199 @@ 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));
+}
+
+// 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.
+//
+// Since 2026-10-23 `milestones` gives the targets, milestonesOf's: by default those in force (tracking-config.mjs). What was reached
+// before the record began, and a record not what KitCode writes, are read as the milestones stacked by the table this KitCode bundles,
+// as before, never by the targets in force: they were reached under a KitCode's own table, and the server's raise must not take away
+// what the record's first write would keep (a ruling of tracking/2-cli, docs/reward-rules.md §2).
+export function decideMilestones({totals, record, redeemed = new Set(), milestones = milestonesOf()}) {
+  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 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 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;
+// 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.
+//
+// Since 2026-10-23 (tracking/2-cli; docs/plans/2026-10-22-server-tracking-config.md) its targets are those of `config`, a tracking
+// config (tracking-config.mjs), by default the one in force, and the summary says which: `targets`, {source, issuedAt}, `source`
+// 'server', 'saved' or 'bundled', `issuedAt` the document's, null for the bundled table; and `campaign`, {endsAt, ended}, the end
+// the config gives, an instant or null, and whether it has passed by `now`, the user's clock. Once it has, `nextBreak` is null:
+// the campaign names no next milestone, though counting goes on, and a milestone reached is reached as before.
+export function buildRewardSummary({earnedSeconds, totalEquals, ledger, record, config = trackingConfigInForce(), now = Date.now()}) {
+  const targets = milestonesOf(config);
   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, milestones: targets});
+  const laterCycle = !decided.stacked && decided.cycle.number > 1;
+  const milestones = targets.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 last = targets[targets.length - 1];
+  const ended = campaignEnded(config, now);
   const summary = {
-    requiredSeconds,
-    requiredEquals: FINAL_EQUALS,
+    requiredSeconds: last.requiredSeconds,
+    requiredEquals: last.requiredEquals,
     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,
+    targets: {source: config.source ?? 'bundled', issuedAt: config.issuedAt ?? null},
+    campaign: {endsAt: config.campaignEndsAt ?? null, ended},
     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
   // §10). `progress` is the same number as a fraction; until 2026-09-24 it was time alone.
   summary.progressPercent = breakProgressPercent(summary);
   summary.progress = summary.progressPercent / 100;
-  summary.nextBreak = nextBreakReminder(summary);
+  summary.nextBreak = ended ? null : nextBreakReminder(summary);
   return summary;
 }
 
@@ -203,6 +376,7 @@ function rewardSummaryFrom(state) {
     earnedSeconds,
     totalEquals: ledger.total_equals,
     ledger,
+    record: state.milestonesReached,
   });
 }
 
@@ -227,6 +401,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 +420,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 +444,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 {