@kitkat-vn/kitcode 0.3.0-staging.15 → 0.3.0-staging.16

package/README.md

@@ -252,6 +252,7 @@ KITCODE_HOOKS_OFF=1
 ~/.kitcode/state.json     Projects and their snapshots, onboarding prefs, focus time, equals ledger
 ~/.kitcode/seen-lines     Every line KitCode has seen, as hashes: a line earns once
 ~/.kitcode/install-id     A random id the claim bundle carries, made by the tracker
+~/.kitcode/tracking-config.json  The campaign's targets and end, as the tracker last took them from the server
 ~/.kitcode/tracker.json   Background tracker PID/host/port metadata
 ~/.kitcode/tracker.log    The background tracker's log
 ~/.kitcode/hook.log       Hook errors, when logging succeeds
@@ -271,6 +272,10 @@ By default KitCode does not send:
 
 The local API returns totals only: active/idle time, project count, commit count, change batches, counted `=`, and reward progress, with the tracker's health. The claim bundle, which it gives an allowed origin alone, adds when each milestone was reached, the CLI's and the counting rules' versions, and the install id, which names no person, machine or project.
 
+KitCode connects to kitcode.vn about once an hour to download the campaign's current targets and end date. It sends nothing about you, your computer or your code, and the server does not record the address of this request.
+
+Only the background tracker connects, about an hour apart and once when your computer wakes: one request to the dashboard's address plus `/v1/tracking-config`, with no cookie, install id or version. It takes the answer only if KitCode's claim server signed it, and otherwise keeps the targets it had; the hook and the commands never connect. The staging package connects to its staging site instead, and a copy of KitCode run from its repository connects to nothing. If the campaign has ended, by your computer's clock, the hook adds nothing to your prompts and `kitcode summary` says so; your totals are kept.
+
 ## API
 
 ```txt

package/bin/kitcode.mjs

@@ -53,6 +53,7 @@ import {
   updateTrackerRecord,
 } from '../src/tracker-instance.mjs';
 import {askTrackerToStop, watchForStopRequest} from '../src/tracker-stop.mjs';
+import {startTrackingConfigLoop, TRACKING_CONFIG_DISPLAY_PATH, trackingConfigUrl} from '../src/tracking-config.mjs';
 import {normalizeSetupPlatform} from '../src/onboarding-platform.mjs';
 import {uninstallKitCode} from '../src/uninstall.mjs';
 
@@ -288,8 +289,11 @@ function formatDuration(seconds) {
 // showing a 10–30 % code was what cleared one; with the codes gone nothing does (docs/reward-rules.md §7). Since 2026-10-22
 // the milestones are those of the cycle counted in, which it names from cycle 2 on, when it began (docs/reward-rules.md §2,
 // "Cycles"); cycle 1 reads as it always has.
-function printRewardSummary() {
-  const reward = getDiskRewardSummary();
+//
+// Since 2026-10-23 (tracking/2-cli; the plan's D4) a campaign that has ended, by this computer's clock and the end the targets in force
+// give (src/tracking-config.mjs), is said so in the plan's words, and no next milestone is named: the summary has none. Counting, and
+// what was reached, are as before.
+function printRewardSummary(reward = getDiskRewardSummary()) {
   const next = reward.nextBreak;
   const ready = reward.milestones.filter((milestone) => milestone.status === 'ready' && !milestone.redeemed);
 
@@ -298,6 +302,10 @@ function printRewardSummary() {
   console.log(`  active time: ${formatDuration(reward.earnedSeconds)}`);
   console.log(`  campaign progress: ${reward.progressPercent}%`);
 
+  if (reward.campaign?.ended) {
+    console.log(`  ${campaignEndedWords(reward.campaign)}`);
+  }
+
   if (Number.isSafeInteger(reward.cycle) && reward.cycle > 1) {
     console.log(`  cycle: ${reward.cycle}, its milestones counted from ${reward.cycleStartedAt}`);
   }
@@ -323,6 +331,41 @@ function printAwards() {
     const status = milestone.status === 'redeemed' ? 'ready' : milestone.status;
     console.log(`  ${milestone.percent}% milestone: ${status} (${milestoneProgressPercent(reward, milestone)}%)`);
   }
+
+  if (reward.campaign?.ended) {
+    console.log(`  ${campaignEndedWords(reward.campaign)}`);
+  }
+}
+
+// An instant in Vietnam time, UTC+7 all year, as "YYYY-MM-DD HH:MM": the campaign's end is set so (docs/backend.md,
+// VOUCHER_CAMPAIGN_END), and the plan's words name its date there.
+function vietnamTime(instant) {
+  return new Date(Date.parse(instant) + 7 * 60 * 60 * 1000).toISOString().slice(0, 16).replace('T', ' ');
+}
+
+// The plan's words for a campaign that has ended (D4 of docs/plans/2026-10-22-server-tracking-config.md).
+function campaignEndedWords(campaign) {
+  return `KitCode's campaign ended on ${vietnamTime(campaign.endsAt).slice(0, 10)} (Vietnam time). Your totals are kept; no more vouchers can be claimed.`;
+}
+
+// Which targets KitCode counts by, and where they came from (src/tracking-config.mjs), so that a fallback never reads as the healthy
+// path; and the campaign's end. From the summary this command builds: the last good copy on disk, as the prompt hook reads it.
+function targetsLine(targets) {
+  if (targets.source === 'bundled') {
+    return trackingConfigUrl() === null
+      ? 'the ones this KitCode bundles; this build never asks a server for them'
+      : `the ones this KitCode bundles, since ${TRACKING_CONFIG_DISPLAY_PATH} holds no good copy of the server's yet`;
+  }
+
+  return `the server's, issued ${targets.issuedAt}${targets.source === 'saved' ? `, from the copy in ${TRACKING_CONFIG_DISPLAY_PATH}` : ''}`;
+}
+
+function campaignLine(campaign) {
+  if (campaign.endsAt === null) {
+    return 'no end set';
+  }
+
+  return campaign.ended ? `ended on ${vietnamTime(campaign.endsAt).slice(0, 10)} (Vietnam time)` : `ends ${vietnamTime(campaign.endsAt)} (Vietnam time)`;
 }
 
 async function printStatus(options) {
@@ -343,7 +386,10 @@ async function printStatus(options) {
     }).join(', ')}; see ${TRACKER_LOG_PATH}`);
   }
   console.log(`  added projects: ${totals.trackingProjects}`);
-  printRewardSummary();
+  const reward = getDiskRewardSummary();
+  console.log(`  targets: ${targetsLine(reward.targets)}`);
+  console.log(`  campaign: ${campaignLine(reward.campaign)}`);
+  printRewardSummary(reward);
 }
 
 
@@ -934,6 +980,10 @@ async function runDaemon(options, status = createStatusReporter()) {
       return {projects: Object.values(runtime.state.projects).filter((project) => project.active).length, tracking: current.tracking, problems: current.problems.map((problem) => problem.code)};
     },
   });
+  // The campaign's targets and end, from the server, in a build that carries the claim backend's key (src/tracking-config.mjs):
+  // a random 5 to 120 s from now, then whenever the last try is over an hour old, and at once after a sleep. The tracker alone
+  // fetches; whatever happens to a fetch stays in tracker.log, and the tracker counts by the targets it had.
+  const trackingConfig = startTrackingConfigLoop({log});
   const app = createServer(runtime, VERSION, {diagnostics});
   let cleanup = async () => {};
   let server = null;
@@ -973,7 +1023,7 @@ async function runDaemon(options, status = createStatusReporter()) {
       report('error', `Stopped: ${error.message}`);
       cleanup({persist: false});
       recordEvent('tracker-stopped', {reason: 'state-unreadable', uptimeSeconds: uptimeSeconds()}, {source: 'tracker'});
-      diagnostics.stop().finally(() => exit(1));
+      Promise.allSettled([trackingConfig.stop(), diagnostics.stop()]).finally(() => exit(1));
     },
   });
 
@@ -990,6 +1040,7 @@ async function runDaemon(options, status = createStatusReporter()) {
 
     log.info(`stopped (${signal})`);
     recordEvent('tracker-stopped', {reason: signal === 'stop request' ? 'stop-request' : 'signal', uptimeSeconds: uptimeSeconds()}, {source: 'tracker'});
+    await trackingConfig.stop();
     await diagnostics.stop();
     exit(0);
   };
@@ -1005,6 +1056,7 @@ async function runDaemon(options, status = createStatusReporter()) {
     await cleanup().catch(() => {});
     releaseTracker(process.pid);
     recordTrackerNotStarted('tracker', error.code === 'EADDRINUSE' ? 'port-in-use' : 'start-failed', error);
+    await trackingConfig.stop();
     await diagnostics.stop({finalSend: false});
 
     if (error.code === 'EADDRINUSE') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitkat-vn/kitcode",
-  "version": "0.3.0-staging.15",
+  "version": "0.3.0-staging.16",
   "description": "Local aggregate activity server for KitCode.",
   "license": "MIT",
   "repository": {
@@ -37,5 +37,5 @@
   "optionalDependencies": {
     "electron": "^43.0.0"
   },
-  "gitHead": "e1f3a6b5e2c101cd4d3a24c611b85eb66066762e"
+  "gitHead": "1e310fb2aaf244ede82956f5f6046ea9f52a7eb1"
 }

package/src/companion-window.mjs

@@ -35,7 +35,7 @@ ${COMPANION_HIDE_CSS}
 const API_BASE=${JSON.stringify(apiBase)};const brandLabel=document.getElementById('brandLabel'),brandSecond=document.getElementById('brandSecond'),percent=document.getElementById('percent'),countValue=document.getElementById('countValue'),workedValue=document.getElementById('workedValue'),idleValue=document.getElementById('idleValue'),progressFill=document.getElementById('progressFill'),main=document.getElementById('main'),dashboardButton=document.getElementById('dashboardButton');
 function formatDuration(seconds){const totalSeconds=Math.max(0,Math.floor(Number(seconds)||0));if(totalSeconds<60)return totalSeconds+'s';const hours=Math.floor(totalSeconds/3600),minutes=Math.floor((totalSeconds%3600)/60);if(hours>0)return minutes>0?hours+'h '+minutes+'m':hours+'h';return minutes+'m'}
 function updateProgress(value){progressFill.style.width=Math.max(0,Math.min(100,Number(value)||0))+'%'}
-function render(summary){const reward=summary?.reward||{},global=summary?.global||{},value=Math.max(0,Math.min(100,Math.floor(Number(reward.progressPercent)||0))),cycle=Number.isSafeInteger(reward.cycle)&&reward.cycle>1?reward.cycle:null;brandSecond.textContent=cycle===null?'COUNTER':'CYCLE '+cycle;brandLabel.setAttribute('aria-label',cycle===null?'KitCode Counter':'KitCode cycle '+cycle);percent.textContent=value+'%';countValue.textContent=String(Math.max(0,Math.floor(Number(reward.totalEquals)||0)));workedValue.textContent=formatDuration(global.totalActiveSeconds);idleValue.textContent=formatDuration(global.totalIdleSeconds);updateProgress(value);main.classList.remove('offline')}
+function render(summary){const reward=summary?.reward||{},global=summary?.global||{},value=Math.max(0,Math.min(100,Math.floor(Number(reward.progressPercent)||0))),cycle=Number.isSafeInteger(reward.cycle)&&reward.cycle>1?reward.cycle:null,ended=reward.campaign?.ended===true;brandSecond.textContent=ended?'ENDED':cycle===null?'COUNTER':'CYCLE '+cycle;brandLabel.setAttribute('aria-label',ended?'KitCode campaign ended':cycle===null?'KitCode Counter':'KitCode cycle '+cycle);percent.textContent=value+'%';countValue.textContent=String(Math.max(0,Math.floor(Number(reward.totalEquals)||0)));workedValue.textContent=formatDuration(global.totalActiveSeconds);idleValue.textContent=formatDuration(global.totalIdleSeconds);updateProgress(value);main.classList.remove('offline')}
 function offline(){percent.textContent='--';countValue.textContent='--';workedValue.textContent='--';idleValue.textContent='--';updateProgress(0);main.classList.add('offline')}
 async function sync(){try{const response=await fetch(API_BASE+'/api/summary');if(!response.ok)throw new Error();render(await response.json())}catch{offline()}}
 const hideButton=document.getElementById('hideButton');function hideCompanion(){try{const result=window.kitcodeCompanion?.hide?.();if(result&&typeof result.catch==='function')result.catch(()=>window.close());if(!result)window.close()}catch{window.close()}}
@@ -47,7 +47,9 @@ sync();const events=new EventSource(API_BASE+'/api/events');events.addEventListe
 
   // Since 2026-10-22 its label names the cycle counted in from cycle 2 on, "KITCODE CYCLE 2" where it says "KITCODE COUNTER",
   // on the same two lines, so that the counters keep their room (docs/reward-rules.md §2, "Cycles"); its percent is that
-  // cycle's, as the summary's is.
+  // cycle's, as the summary's is. Since 2026-10-23 (tracking/2-cli; D4 of docs/plans/2026-10-22-server-tracking-config.md) it
+  // reads "KITCODE ENDED" once the summary says the campaign has ended, `reward.campaign.ended`, whatever the cycle; the counters
+  // go on, as counting does.
   //
   // The button opens the dashboard, where each milestone reached shows its message: "See more". Until 2026-10-01 it was
   // "Show code", and lit while a 10–30 % code was ready to show there; the break codes are gone (the operator's decision

package/src/hook-prompt.mjs

@@ -7,6 +7,7 @@ import {getDiskRewardSummary, getReadyUnannouncedTiers, markTiersAnnounced} from
 import {STORE_DIR, StateLockError, withStateLock} from './store.mjs';
 import {isProcessAlive, readTrackerRecord} from './tracker-instance.mjs';
 import {problemSentences, TRACKER_STOPPED} from './tracker-problems.mjs';
+import {campaignEnded, trackingConfigInForce} from './tracking-config.mjs';
 
 export const HOOK_LOG_PATH = path.join(STORE_DIR, 'hook.log');
 
@@ -209,6 +210,14 @@ export async function runPromptHook({source}) {
       return;
     }
 
+    // After the campaign's end, by this computer's clock (since 2026-10-23, tracking/2-cli; D4 of
+    // docs/plans/2026-10-22-server-tracking-config.md), the hook adds nothing: no progress, no milestone, no notification, and nothing
+    // written. The end is the last good copy's, read from disk with its bounds checked and no signature: the hook never fetches
+    // (src/tracking-config.mjs; hard rule 7). Counting goes on in the tracker, so an end moved later brings every word back.
+    if (campaignEnded(trackingConfigInForce())) {
+      return;
+    }
+
     const {reward, announced} = collectPromptProgress(source);
 
     if (announced.length === 0) {

package/src/milestones-reached.mjs

@@ -1,7 +1,7 @@
 import {equalsLedgerFrom} from './equals-ledger.mjs';
 import {focusTimeFrom} from './focus-clock.mjs';
 import {readMilestoneRecord} from './milestone-record.mjs';
-import {decideMilestones, MILESTONE_PERCENTS, REWARD_TIERS} from './reward.mjs';
+import {decideMilestones, MILESTONE_PERCENTS, milestonesOf, 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`:
@@ -63,7 +63,12 @@ function redeemedIn(stored) {
 // `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} = {}) {
+//
+// Since 2026-10-23 (tracking/2-cli) a milestone is found reached against the targets in force (reward.mjs milestonesOf;
+// tracking-config.mjs), or `config`'s, a tracking config, when one is given: the record keeps every milestone it holds whatever
+// the targets do, so a raise takes nothing reached away, and a target lowered under what the milestone in progress earned is
+// recorded reached by this write.
+export function noteMilestonesReached(stored, now = new Date(Date.now()), {focusSeconds, config} = {}) {
   const record = stored.milestonesReached;
   const read = readMilestoneRecord(record, MILESTONE_PERCENTS);
 
@@ -72,7 +77,7 @@ export function noteMilestonesReached(stored, now = new Date(Date.now()), {focus
   }
 
   const totals = totalsIn(stored, focusSeconds);
-  const decided = decideMilestones({totals, record, redeemed: redeemedIn(stored)});
+  const decided = decideMilestones({totals, record, redeemed: redeemedIn(stored), ...(config === undefined ? {} : {milestones: milestonesOf(config)})});
   const at = now.toISOString();
   const atTotals = {at, focusSeconds: totals.seconds, equals: totals.equals};
 

package/src/reward.mjs

@@ -5,6 +5,7 @@ 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';
 
 export const REWARD_TIERS = KITCODE_REWARD_TIERS;
 export const CAMPAIGN_MILESTONES = KITCODE_DISPLAY_MILESTONES;
@@ -18,15 +19,26 @@ export const MILESTONE_PERCENTS = REWARD_MILESTONES.map((milestone) => milestone
 // 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.
+// 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;
-// 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 = LAST_MILESTONE.requiredEquals;
 
 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);
 }
@@ -201,7 +213,12 @@ function stackedReached(totals, redeemed) {
 // 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()}) {
+//
+// 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') {
@@ -222,7 +239,7 @@ export function decideMilestones({totals, record, redeemed = new Set()}) {
   let start = later ? {...current.start} : {seconds: 0, equals: 0};
   let startKnown = true;
 
-  for (const milestone of REWARD_MILESTONES) {
+  for (const milestone of milestones) {
     const entry = before.get(milestone.percent);
 
     if (start === null) {
@@ -282,15 +299,22 @@ function timeLeft(totals, milestones) {
 // 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}) {
+//
+// 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 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 decided = decideMilestones({totals, record, redeemed, milestones: targets});
   const laterCycle = !decided.stacked && decided.cycle.number > 1;
-  const milestones = REWARD_MILESTONES.map((milestone, index) => {
+  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;
@@ -319,14 +343,18 @@ export function buildRewardSummary({earnedSeconds, totalEquals, ledger, record})
     status: milestone.status,
   }));
 
+  const last = targets[targets.length - 1];
+  const ended = campaignEnded(config, now);
   const summary = {
-    requiredSeconds: REWARD_SECONDS,
-    requiredEquals: FINAL_EQUALS,
+    requiredSeconds: last.requiredSeconds,
+    requiredEquals: last.requiredEquals,
     earnedSeconds: normalizedEarnedSeconds,
     totalEquals: normalizedTotalEquals,
     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,
   };
@@ -335,7 +363,7 @@ export function buildRewardSummary({earnedSeconds, totalEquals, ledger, record})
   // §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;
 }
 

package/src/tracking-config.mjs

@@ -0,0 +1,501 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {writeFileAtomically} from './atomic-file.mjs';
+import {cycleReceiptKey} from './cycle-receipt.mjs';
+import {CYCLE_RECEIPT_PUBLIC_KEY, DASHBOARD_URL, KITCODE_DISPLAY_MILESTONES, KITCODE_REWARD_TIERS} from './integration-spec.mjs';
+import {STORE_DIR} from './store.mjs';
+
+// The campaign's targets and its end, from the server (docs/plans/2026-10-22-server-tracking-config.md, THE TRACKER; docs/backend.md,
+// "The tracking config"; docs/reward-rules.md §2). The claim backend serves one signed document at the dashboard's address plus
+// /v1/tracking-config: the six milestone targets in force and when the campaign ends. A tracker of a build that carries the claim
+// backend's public key fetches it about once an hour, checks its signature, and counts by it; so a change of targets reaches every
+// install within the hour, with no new version of KitCode to install. Nothing else fetches it: never the prompt hook, a command or a
+// window (hard rule 7). The repository's own build carries no key, and so never fetches, and counts by the table it bundles (R22.1).
+//
+//   <payload>.<signature>
+//
+// `payload` is base64url (no padding) of the UTF-8 JSON {"v":1,"issuedAt":…,"milestones":[{"percent":30,"focusSeconds":…,"equals":…},
+// {"percent":50,…},{"percent":100,…}],"campaignEndsAt":…|null}, those four fields alone; `signature`, base64url of the 64-byte Ed25519
+// signature of the ASCII text `kitcode-tracking-config-1.` followed by `payload` as it stands, with the cycle receipts' key
+// (cycle-receipt.mjs), whose text is `kitcode-cycle-receipt-1.`: a receipt never passes for a config, or a config for a receipt. The
+// contract is packages/claim-contract/tracking-config.mjs, which only tests read; this reader is the CLI's own, held to the
+// contract's fixtures by test/tracking-config.test.mjs, problem for problem, in the contract's order.
+//
+// What the tracker took is kept in memory, and in ~/.kitcode/tracking-config.json, its last good copy: written whole, 0600, never
+// state.json (hard rule 4), and never deleted or written over by anything but a later good document. The targets in force are,
+// in order: the copy the tracker took this run, the last good copy on disk, then the table this KitCode bundles
+// (integration-spec.mjs). The prompt hook and the commands read the copy on disk and check its shape and bounds, never its
+// signature, which only the tracker checks, as it fetched it; and `targets.source` says which of the three is in force, so that a
+// fallback never looks like the healthy path.
+
+export const TRACKING_CONFIG_CONTEXT = 'kitcode-tracking-config-1.';
+export const TRACKING_CONFIG_PATH = path.join(STORE_DIR, 'tracking-config.json');
+export const TRACKING_CONFIG_DISPLAY_PATH = '~/.kitcode/tracking-config.json';
+// The longest document read, in characters, and the most of a body the tracker reads, in bytes: 2 KiB. A document is about 430.
+export const MAX_TRACKING_CONFIG_LENGTH = 2048;
+// The bounds (the operator's decision D2 of 2026-10-22): the percents 30, 50 and 100, in that order; each milestone's focus time
+// 60 to 172,800 s and its = 1 to 100,000; each milestone's targets at least the one before's.
+export const TRACKING_CONFIG_PERCENTS = Object.freeze([30, 50, 100]);
+export const TRACKING_CONFIG_BOUNDS = Object.freeze({
+  focusSeconds: Object.freeze({min: 60, max: 172_800}),
+  equals: Object.freeze({min: 1, max: 100_000}),
+});
+
+// When the tracker fetches: a random moment 5 to 120 s after it starts, so that a fleet started together does not ask at once;
+// then whenever its last try is over an hour old, which it checks every minute; and at once when it finds the computer has slept,
+// a check that came three minutes or more after the one before. 10 s for the whole answer, its body included.
+export const FIRST_FETCH_MS = Object.freeze({min: 5_000, max: 120_000});
+export const FETCH_AGAIN_AFTER_MS = 60 * 60 * 1000;
+export const CHECK_EVERY_MS = 60 * 1000;
+export const WOKE_AFTER_MS = 3 * CHECK_EVERY_MS;
+export const FETCH_TIMEOUT_MS = 10_000;
+
+const FILE_MODE = 0o600;
+const PAYLOAD_KEYS = ['v', 'issuedAt', 'milestones', 'campaignEndsAt'];
+const MILESTONE_KEYS = ['percent', 'focusSeconds', 'equals'];
+const DOCUMENT_TEXT = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{86})$/u;
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const SILENT_LOG = {info() {}, warn() {}, error() {}};
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasExactly(value, keys) {
+  return isObject(value) && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function isInstantText(value) {
+  return typeof value === 'string' && INSTANT.test(value);
+}
+
+function isRealInstant(value) {
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value;
+}
+
+function within(value, {min, max}) {
+  return value >= min && value <= max;
+}
+
+// Whether `words`, a payload as JSON.parse reads it, is a tracking config: {ok: true, config: {issuedAt, milestones, campaignEndsAt}},
+// a copy of its words, or {ok: false, problem}, the contract's: 'version', a `v` present and not 1, a later version, refused whole;
+// 'unreadable', not the contract's shape, or an instant that is not a real one; 'bounds', outside the bounds above. Pure. What the
+// tracker holds a signed document to, and what the hook and the commands hold the last good copy's words to.
+export function judgeTrackingConfig(words) {
+  if (!isObject(words)) {
+    return {ok: false, problem: 'unreadable'};
+  }
+
+  if (Object.hasOwn(words, 'v') && words.v !== 1) {
+    return {ok: false, problem: 'version'};
+  }
+
+  const shaped = hasExactly(words, PAYLOAD_KEYS)
+    && isInstantText(words.issuedAt)
+    && (words.campaignEndsAt === null || isInstantText(words.campaignEndsAt))
+    && Array.isArray(words.milestones) && words.milestones.length === TRACKING_CONFIG_PERCENTS.length
+    && words.milestones.every((milestone) => hasExactly(milestone, MILESTONE_KEYS) && MILESTONE_KEYS.every((key) => Number.isInteger(milestone[key])));
+
+  if (!shaped || !isRealInstant(words.issuedAt) || (words.campaignEndsAt !== null && !isRealInstant(words.campaignEndsAt))) {
+    return {ok: false, problem: 'unreadable'};
+  }
+
+  const inBounds = words.milestones.every((milestone, index) => {
+    const before = words.milestones[index - 1];
+
+    return milestone.percent === TRACKING_CONFIG_PERCENTS[index]
+      && within(milestone.focusSeconds, TRACKING_CONFIG_BOUNDS.focusSeconds)
+      && within(milestone.equals, TRACKING_CONFIG_BOUNDS.equals)
+      && (before === undefined || (milestone.focusSeconds >= before.focusSeconds && milestone.equals >= before.equals));
+  });
+
+  if (!inBounds) {
+    return {ok: false, problem: 'bounds'};
+  }
+
+  return {
+    ok: true,
+    config: {
+      issuedAt: words.issuedAt,
+      milestones: words.milestones.map(({percent, focusSeconds, equals}) => ({percent, focusSeconds, equals})),
+      campaignEndsAt: words.campaignEndsAt,
+    },
+  };
+}
+
+// The public key a build carries: the cycle receipts' own (integration-spec.mjs, CYCLE_RECEIPT_PUBLIC_KEY). Null when it is not one.
+export function trackingConfigKey(text = CYCLE_RECEIPT_PUBLIC_KEY) {
+  return cycleReceiptKey(text);
+}
+
+// Reads `text` with `publicKey` (a KeyObject, trackingConfigKey's): {ok: true, config}, or {ok: false, problem}, the first of the
+// contract's, in its order: 'oversized', longer than MAX_TRACKING_CONFIG_LENGTH; 'unreadable', not two base64url parts joined by a
+// dot; 'signature', not signed over the context and the payload with the key's pair, checked over the bytes as they came, before
+// anything in them is read; then judgeTrackingConfig's; and 'stale', an issuedAt no later than `after`, the issuedAt of the last
+// document taken: an older one replayed, or the same one again.
+export function readTrackingConfig(text, publicKey, {after = null} = {}) {
+  if (after !== null && !(isInstantText(after) && isRealInstant(after))) {
+    throw new TypeError(`after must be an instant, as toISOString writes it, or null: ${String(after)}`);
+  }
+
+  if (typeof text !== 'string') {
+    return {ok: false, problem: 'unreadable'};
+  }
+
+  if (text.length > MAX_TRACKING_CONFIG_LENGTH) {
+    return {ok: false, problem: 'oversized'};
+  }
+
+  const parts = DOCUMENT_TEXT.exec(text);
+
+  if (parts === null) {
+    return {ok: false, problem: 'unreadable'};
+  }
+
+  const [, payload, signature] = parts;
+  let signed;
+
+  try {
+    signed = crypto.verify(null, Buffer.from(`${TRACKING_CONFIG_CONTEXT}${payload}`, 'ascii'), publicKey, Buffer.from(signature, 'base64url'));
+  } catch {
+    signed = false;
+  }
+
+  if (!signed) {
+    return {ok: false, problem: 'signature'};
+  }
+
+  let words;
+
+  try {
+    words = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+  } catch {
+    return {ok: false, problem: 'unreadable'};
+  }
+
+  const judged = judgeTrackingConfig(words);
+
+  if (!judged.ok) {
+    return judged;
+  }
+
+  if (after !== null && Date.parse(judged.config.issuedAt) <= Date.parse(after)) {
+    return {ok: false, problem: 'stale'};
+  }
+
+  return judged;
+}
+
+// Where this build fetches: DASHBOARD_URL plus v1/tracking-config, an https URL, or, for this repository's tests, an http one on this
+// machine; and only in a build that carries a key. Null otherwise: such a build never fetches, and never reads a copy either.
+export function trackingConfigUrl({dashboardUrl = DASHBOARD_URL, publicKey = CYCLE_RECEIPT_PUBLIC_KEY} = {}) {
+  if (trackingConfigKey(publicKey) === null || typeof dashboardUrl !== 'string') {
+    return null;
+  }
+
+  try {
+    const url = new URL('v1/tracking-config', dashboardUrl);
+    const loopback = url.hostname === '127.0.0.1' || url.hostname === 'localhost' || url.hostname === '[::1]';
+    return url.protocol === 'https:' || (url.protocol === 'http:' && loopback) ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+// --- The targets in force ----------------------------------------------------------------------------------------------------
+
+// The table this KitCode bundles, in the document's words: the milestone table in force (integration-spec.mjs, MILESTONE_TABLE).
+export const BUNDLED_TRACKING_CONFIG = Object.freeze({
+  issuedAt: null,
+  milestones: Object.freeze([...KITCODE_REWARD_TIERS, ...KITCODE_DISPLAY_MILESTONES]
+    .map(({percent, requiredSeconds, requiredEquals}) => Object.freeze({percent, focusSeconds: requiredSeconds, equals: requiredEquals}))),
+  campaignEndsAt: null,
+});
+
+// What the tracker took this run: {config, document}. Only the tracker's loop sets it, once a document is taken; nothing else in
+// any process does.
+let held = null;
+// The last good copy as last read, by the file's identity, so that a summary built every second reads the file again only once it
+// has changed.
+let savedRead = {identity: null, copy: null};
+
+function fileIdentity(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    return `${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+  } catch {
+    return 'missing';
+  }
+}
+
+// The last good copy on disk, {document, issuedAt, milestones, campaignEndsAt, receivedAt}, its words checked against the shape and
+// the bounds, not its signature; null when there is none, or it cannot be read, or its words are not a tracking config's. Never
+// throws, never writes: a copy that is not one is left as it is, and the bundled table counts.
+export function readSavedTrackingConfig() {
+  const identity = fileIdentity(TRACKING_CONFIG_PATH);
+
+  if (identity === savedRead.identity) {
+    return savedRead.copy;
+  }
+
+  let copy = null;
+
+  try {
+    const stored = JSON.parse(fs.readFileSync(TRACKING_CONFIG_PATH, 'utf8'));
+    const judged = isObject(stored)
+      ? judgeTrackingConfig({v: 1, issuedAt: stored.issuedAt, milestones: stored.milestones, campaignEndsAt: stored.campaignEndsAt})
+      : {ok: false};
+
+    if (judged.ok) {
+      copy = {
+        document: typeof stored.document === 'string' ? stored.document : null,
+        ...judged.config,
+        receivedAt: typeof stored.receivedAt === 'string' ? stored.receivedAt : null,
+      };
+    }
+  } catch {
+    copy = null;
+  }
+
+  savedRead = {identity, copy};
+  return copy;
+}
+
+// Writes the last good copy: the document as it came, its words, and when this tracker took it. Whole, 0600; throws what the write
+// throws, and the copy before stays as it was.
+export function saveTrackingConfig({config, document}, receivedAt = new Date()) {
+  fs.mkdirSync(STORE_DIR, {recursive: true});
+  const copy = {document, issuedAt: config.issuedAt, milestones: config.milestones, campaignEndsAt: config.campaignEndsAt, receivedAt: receivedAt.toISOString()};
+  writeFileAtomically(TRACKING_CONFIG_PATH, `${JSON.stringify(copy, null, 2)}\n`, {mode: FILE_MODE});
+}
+
+// Whether this build fetches, worked out once: the key and the address are the build's own, and never change while it runs.
+let fetches;
+
+function buildFetches() {
+  fetches ??= trackingConfigUrl() !== null;
+  return fetches;
+}
+
+// The targets and the end in force now: {source, issuedAt, milestones, campaignEndsAt}, `source` 'server' for the document this
+// tracker took this run, 'saved' for the last good copy, 'bundled' for the table this KitCode bundles; `milestones` in the
+// document's words, {percent, focusSeconds, equals}. A build that never fetches counts by the bundled table alone.
+export function trackingConfigInForce() {
+  if (!buildFetches()) {
+    return {source: 'bundled', ...BUNDLED_TRACKING_CONFIG};
+  }
+
+  if (held !== null) {
+    return {source: 'server', ...held.config};
+  }
+
+  const saved = readSavedTrackingConfig();
+
+  if (saved !== null) {
+    return {source: 'saved', issuedAt: saved.issuedAt, milestones: saved.milestones, campaignEndsAt: saved.campaignEndsAt};
+  }
+
+  return {source: 'bundled', ...BUNDLED_TRACKING_CONFIG};
+}
+
+// Whether the campaign has ended by `now`, the user's clock: an end set, and reached.
+export function campaignEnded(config, now = Date.now()) {
+  return typeof config?.campaignEndsAt === 'string' && Date.parse(config.campaignEndsAt) <= now;
+}
+
+// For this repository's tests alone: forgets what this process took, as a tracker that has just started.
+export function forgetHeldTrackingConfig() {
+  held = null;
+  savedRead = {identity: null, copy: null};
+}
+
+// --- The fetch ---------------------------------------------------------------------------------------------------------------
+
+// The body, at most `limit` bytes, or null past it: a length declared above it is refused before a byte is read, and a body
+// that grows past it is cancelled as it does.
+async function readLimited(response, limit) {
+  const declared = Number(response.headers.get('content-length'));
+
+  if (Number.isFinite(declared) && declared > limit) {
+    await response.body?.cancel().catch(() => {});
+    return null;
+  }
+
+  if (!response.body) {
+    return '';
+  }
+
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+
+  for (;;) {
+    const {done, value} = await reader.read();
+
+    if (done) {
+      break;
+    }
+
+    size += value.byteLength;
+
+    if (size > limit) {
+      await reader.cancel().catch(() => {});
+      return null;
+    }
+
+    chunks.push(value);
+  }
+
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// One try: one GET of `url`, with no redirect followed, no cookie, and nothing of this install, the user or this KitCode's version
+// in it; `timeoutMs` for the whole answer. The document is judged against what this tracker holds, `current`, {config, document}
+// or null. Returns {outcome: 'taken', config, document}; {outcome: 'unchanged'}, the very document `current` holds, fetched again;
+// {outcome: 'refused', problem, status?}, an answer that is not a document to take, for the first of: 'status', not 200 (a
+// redirect among them); 'oversized', a body over 2 KiB; the reader's problems; or {outcome: 'failed', problem}: 'timeout', or
+// 'unreachable'. Never throws.
+export async function fetchTrackingConfig({url, publicKey, current = null, fetchImpl = globalThis.fetch, timeoutMs = FETCH_TIMEOUT_MS, signal} = {}) {
+  const deadline = AbortSignal.timeout(timeoutMs);
+  const abort = signal ? AbortSignal.any([signal, deadline]) : deadline;
+
+  try {
+    const response = await fetchImpl(url, {method: 'GET', redirect: 'manual', credentials: 'omit', signal: abort});
+
+    if (response.status !== 200) {
+      await response.body?.cancel().catch(() => {});
+      return {outcome: 'refused', problem: 'status', status: response.status};
+    }
+
+    const text = await readLimited(response, MAX_TRACKING_CONFIG_LENGTH);
+
+    if (text === null) {
+      return {outcome: 'refused', problem: 'oversized'};
+    }
+
+    if (current !== null && text === current.document) {
+      return {outcome: 'unchanged'};
+    }
+
+    const read = readTrackingConfig(text, publicKey, {after: current?.config.issuedAt ?? null});
+    return read.ok ? {outcome: 'taken', config: read.config, document: text} : {outcome: 'refused', problem: read.problem};
+  } catch (error) {
+    return {outcome: 'failed', problem: deadline.aborted || error?.name === 'TimeoutError' ? 'timeout' : 'unreachable'};
+  }
+}
+
+// What a try did, for tracker.log: fixed words, the address and the instants alone.
+function describeTry(result, url, inForce) {
+  const kept = `KitCode keeps the targets it had (${inForce.source}${inForce.issuedAt ? `, issued ${inForce.issuedAt}` : ''})`;
+
+  switch (result.outcome) {
+    case 'taken':
+      return `took the campaign's targets issued ${result.config.issuedAt} from ${url}${result.config.campaignEndsAt ? `, the campaign ending ${result.config.campaignEndsAt}` : ', no end set'}.`;
+    case 'unchanged':
+      return `the campaign's targets from ${url} are unchanged (issued ${inForce.issuedAt}).`;
+    case 'refused':
+      return `refused the answer from ${url} (${result.problem}${result.status === undefined ? '' : ` ${result.status}`}); ${kept}.`;
+    default:
+      return `could not fetch the campaign's targets from ${url} (${result.problem}); ${kept}.`;
+  }
+}
+
+// While the tracker runs (bin/kitcode.mjs, runDaemon): the fetches, as above, each try alone, and none of them able to stop, block or
+// slow the tracker; every failure stays here, in tracker.log. A document taken is saved, then held: the tracker counts by it at once.
+// In a build that never fetches it does nothing. `now`, the wall clock, which tells a sleep from a minute; `random`, for the first
+// fetch's moment. Returns {stop, tryNow}: `stop` ends the loop and any try under way; `tryNow`, a try at once, for tests.
+export function startTrackingConfigLoop({log = SILENT_LOG, fetchImpl = globalThis.fetch, now = () => Date.now(), random = Math.random, url = trackingConfigUrl(), publicKey = trackingConfigKey(), timeoutMs = FETCH_TIMEOUT_MS} = {}) {
+  if (url === null || publicKey === null) {
+    return {stop: async () => {}, tryNow: async () => ({outcome: 'disabled'})};
+  }
+
+  const controller = new AbortController();
+  let lastTry = null;
+  let lastCheck = now();
+  let trying = null;
+  let stopped = false;
+
+  // The copy this try is judged against: what this run took, or the last good copy, whose issuedAt a document must be later than.
+  const current = () => {
+    if (held !== null) {
+      return held;
+    }
+
+    const saved = readSavedTrackingConfig();
+    return saved === null ? null : {config: {issuedAt: saved.issuedAt, milestones: saved.milestones, campaignEndsAt: saved.campaignEndsAt}, document: saved.document};
+  };
+
+  const attempt = async () => {
+    const before = current();
+    const result = await fetchTrackingConfig({url, publicKey, current: before, fetchImpl, timeoutMs, signal: controller.signal});
+
+    if (result.outcome === 'taken' || result.outcome === 'unchanged') {
+      const taken = result.outcome === 'taken' ? {config: result.config, document: result.document} : before;
+      const saved = readSavedTrackingConfig();
+
+      // Saved first, unless the copy on disk is this one already; held whatever the save does, so that the tracker counts by what
+      // it checked, and a save that failed is tried again at the next try.
+      if (saved === null || saved.document !== taken.document) {
+        try {
+          saveTrackingConfig(taken, new Date(now()));
+        } catch (error) {
+          log.warn(`KitCode could not save the campaign's targets to ${TRACKING_CONFIG_DISPLAY_PATH} (${error?.code ?? error?.name ?? 'error'}); it counts by them until it stops, and tries again at its next fetch.`);
+        }
+      }
+
+      held = taken;
+    }
+
+    (result.outcome === 'taken' ? log.info : result.outcome === 'unchanged' ? () => {} : log.warn)(describeTry(result, url.href, trackingConfigInForce()));
+    return result;
+  };
+
+  const tryNow = () => {
+    if (trying !== null) {
+      return trying;
+    }
+
+    lastTry = now();
+    trying = attempt().catch(() => ({outcome: 'failed', problem: 'error'})).finally(() => {
+      trying = null;
+    });
+    return trying;
+  };
+
+  const first = setTimeout(() => {
+    if (!stopped && lastTry === null) {
+      tryNow();
+    }
+  }, FIRST_FETCH_MS.min + Math.floor(random() * (FIRST_FETCH_MS.max - FIRST_FETCH_MS.min + 1)));
+
+  const check = setInterval(() => {
+    const at = now();
+    const woke = at - lastCheck >= WOKE_AFTER_MS;
+    lastCheck = at;
+
+    if (stopped || trying !== null) {
+      return;
+    }
+
+    // Before the first try, only a wake brings it forward. After it: a try over an hour old, a wake, or a clock moved back past it.
+    if (lastTry === null ? woke : woke || at - lastTry > FETCH_AGAIN_AFTER_MS || at < lastTry) {
+      tryNow();
+    }
+  }, CHECK_EVERY_MS);
+
+  first.unref?.();
+  check.unref?.();
+
+  return {
+    tryNow,
+    async stop() {
+      stopped = true;
+      clearTimeout(first);
+      clearInterval(check);
+      controller.abort();
+      await trying?.catch(() => {});
+    },
+  };
+}