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

package/README.md

@@ -1,8 +1,8 @@
-# @kitkat-vn/kitcode
+# @kitkatvn/kitcode
 
 Local break companion for coding campaigns. This package is the **source of truth** for tracking, the milestones reached, hooks, and the local Mini companion.
 
-Published package: `@kitkat-vn/kitcode`
+Published package: `@kitkatvn/kitcode`. Its tester builds, for the invited testers of KitCode's staging round, are published as `@kitkat-vn/kitcode` (see Releases, below).
 
 ---
 
@@ -29,7 +29,9 @@ Use the permission setting that lets setup commands run without stopping between
 
 ### Quick Start
 
-Install KitCode first, from the dist-tag meant for you (see Releases, below): no `latest` release exists yet, and `staging` is for the invited testers of the staging round.
+Install KitCode first: `npm install -g @kitkatvn/kitcode`. The setup prompt on KitCode's dashboard does it for you, at the version it was made for.
+
+If `@kitkat-vn/kitcode` is installed, or `@onedigitas/kitcode`, the name KitCode was published under until 0.1.39, remove it first, with `npm uninstall -g @kitkat-vn/kitcode @onedigitas/kitcode`: each package installs the `kitcode` command, and npm does not install one over another. When neither is installed, npm says it is up to date.
 
 <table>
   <tr>
@@ -184,25 +186,41 @@ Both modes count `=` by the same line rules. In Git Mode, KitCode reads only the
 
 ## Reward model
 
-The time target is fixed at `3600` active seconds: no flag or variable changes it.
-
-Each milestone needs both enough active time and enough counted `=`:
+The time targets are fixed, each milestone's own (below): no flag or variable changes them.
 
-- time target for a percent = `ceil(3600 * percent / 100)` seconds: 360 for 10%, 720 for 20%, 1080 for 30%, 1800 for 50%, and 3600 for 100%
-- equals target comes from the table below
+Each milestone needs both enough active time and enough counted `=`, each counted from the moment the milestone before it
+was reached: `30%` from install, `50%` from the moment `30%` was reached, `100%` from the moment `50%` was. Nothing earned
+before that moment counts toward it, neither time earned while waiting for `=` nor `=` while waiting for time, so `100%`
+takes 16 hours and 1,800 `=` in all in a release. What was reached stays reached.
 
 ### Milestones
 
-| Milestone | Required counted `=` |
-| ---: | ---: |
-| `10%` | 3 |
-| `20%` | 6 |
-| `30%` | 9 |
-| `50%` | 12 |
-| `100%` | 15 |
+A release, `@kitkatvn/kitcode` under `latest`, counts by the production table:
+
+| Milestone | Active time, from the milestone before | Counted `=`, from the milestone before |
+| ---: | ---: | ---: |
+| `30%` | 3 hours (10800 s), from install | 300, from install |
+| `50%` | 5 hours (18000 s) | 500 |
+| `100%` | 8 hours (28800 s) | 1,000 |
+
+A tester build, `@kitkat-vn/kitcode` under `staging`, counts by the tester table, the short one, so that testers reach each
+milestone quickly; `100%` takes 108 minutes and 36 `=` in all:
+
+| Milestone | Active time, from the milestone before | Counted `=`, from the milestone before |
+| ---: | ---: | ---: |
+| `30%` | 18 minutes (1080 s), from install | 9, from install |
+| `50%` | 30 minutes (1800 s) | 12 |
+| `100%` | 60 minutes (3600 s) | 15 |
+
+`MILESTONE_TABLE` in `src/integration-spec.mjs` says which this package counts by, and `kitcode summary` names what the next
+milestone still needs.
+Until 2026-10-08 there were 10% and 20% milestones too, and until 2026-10-20 every milestone counted from install. From
+2026-10-21 to 2026-10-22 the tester table held the production table's numbers; since 2026-10-22 it is the short one again.
 
 Once a milestone is reached, the dashboard shows its message: the campaign's own words, which the campaign's server gives each milestone. The prompt hook and the desktop notification say only that a milestone was reached. `summary` and `awards` show which are ready.
 
+Since 2026-10-22 the milestones count in cycles. Once the campaign's server issues a voucher for a claim, its page links back to the dashboard with a receipt the server signed, and the dashboard hands it to the tracker, which begins the next cycle: `30%`, `50%` and `100%` count again from that moment, each needing its full target, and the active time and the counted `=` keep counting. Nothing else begins one, and a claim that fails or is abandoned changes nothing. A build takes a receipt only if it carries its server's public key: a release under `latest` carries the campaign server's, and a tester build the staging server's. From cycle 2 on, `summary`, the prompt hook and the Mini name the cycle.
+
 Until 2026-10-01 each milestone had a break code, a line of code shown in the dashboard, which recorded it as shown on this machine. The codes are gone, and nothing records one as shown; a code an earlier version recorded as shown stays in `~/.kitcode/state.json`, and its milestone reads as ready.
 
 ## Codex and Claude integrations
@@ -234,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
@@ -253,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
@@ -261,10 +284,11 @@ GET  /api/summary
 GET  /api/projects
 GET  /api/events
 GET  /api/claim/bundle
+POST /api/claim/receipt
 GET  /companion
 ```
 
-The API answers only requests addressed to `127.0.0.1` or `localhost` on its port, and web pages only from an allowed origin (below) or its own. `GET /api/claim/bundle` needs an allowed origin; every `POST` needs an allowed origin and a JSON body, and none is left that changes anything.
+The API answers only requests addressed to `127.0.0.1` or `localhost` on its port, and web pages only from an allowed origin (below) or its own. `GET /api/claim/bundle` needs an allowed origin; every `POST` needs an allowed origin and a JSON body. Since 2026-10-22 one changes something, `POST /api/claim/receipt`: it begins the next cycle on a receipt signed with the key the build carries, for this install, of the cycle it is in or a later one, once, and refuses anything else, changing nothing. A receipt of a later cycle, as after KitCode is installed afresh, begins the cycle after it, numbered as the server counts (since 2026-10-22's phase 3).
 
 `/api/events` is SSE and emits `summary` every second.
 
@@ -303,19 +327,17 @@ With nothing configured, the local API allows the origin of the dashboard `kitco
 
 ## Releases
 
-Nobody runs `npm publish` for this package. A release comes from a pushed tag, `cli-v<version>`: the project's CI runs
+Nobody runs `npm publish` for these packages. A release comes from a pushed tag, `cli-v<version>`: the project's CI runs
 its checks on the tagged commit, packs the tarball from that commit, and stages it on npm with `npm stage publish`. A
-staged version becomes public only when a maintainer approves it with two-factor authentication. The package's first
-version is the one exception to CI's staging: a maintainer stages CI's tarball by hand, once, since npm lets CI stage
-only for a package that exists.
+staged version becomes public only when a maintainer approves it with two-factor authentication. Each package's first
+version is the one exception to CI's staging: a maintainer publishes CI's tarball by hand, once, with two-factor
+authentication, since npm lets CI stage only for a package that exists.
 
-Two dist-tags:
-
-| Dist-tag | Versions | Install |
-| --- | --- | --- |
-| `latest` | `<x>.<y>.<z>`, the version in `package.json` | `npm install -g @kitkat-vn/kitcode` |
-| `staging` | `<x>.<y>.<z>-staging.<N>`, the tester build of a tagged commit, for the invited testers of the staging round. Its dashboard is KitCode's protected staging site, which only they can open | `npm install -g @kitkat-vn/kitcode@staging` |
+Two packages, each with its own dist-tag:
 
-No `latest` release exists yet.
+| Package | Dist-tag | Versions | Install |
+| --- | --- | --- | --- |
+| `@kitkatvn/kitcode` | `latest` | `<x>.<y>.<z>`, the version in `package.json`. Its dashboard is `https://kitcode.vn/` | `npm install -g @kitkatvn/kitcode` |
+| `@kitkat-vn/kitcode` | `staging` | `<x>.<y+1>.0-staging.<N>`, the tester build of a tagged commit, for the invited testers of the staging round. Its dashboard is KitCode's protected staging site, which only they can open, and it sends KitCode's own diagnostics there | `npm install -g @kitkat-vn/kitcode@staging` |
 
-What each dist-tag points at now: `npm view @kitkat-vn/kitcode dist-tags`.
+What each dist-tag points at now: `npm view @kitkatvn/kitcode dist-tags` and `npm view @kitkat-vn/kitcode dist-tags`.

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';
 
@@ -90,6 +91,8 @@ function trackerAllowedOrigins() {
       .filter(Boolean),
   );
 
+  // The dashboard's origin, or, for a DASHBOARD_URL that is not a URL, production's (since 2026-10-22, where it was
+  // https://kitcode.vercel.app). A tester build's copy has no fallback (scripts/tester-build.mjs).
   try {
     origins.add(new URL(DASHBOARD_URL).origin);
   } catch {
@@ -283,9 +286,14 @@ function formatDuration(seconds) {
 
 // The numbers come from the summary: the same ones the Mini and the dashboard show
 // (docs/reward-rules.md §10). The next milestone follows the ready ones: until 2026-10-01 a ready milestone hid it, and
-// showing a 10–30 % code was what cleared one; with the codes gone nothing does (docs/reward-rules.md §7).
-function printRewardSummary() {
-  const reward = getDiskRewardSummary();
+// 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.
+//
+// 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);
 
@@ -294,6 +302,14 @@ 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}`);
+  }
+
   if (ready.length > 0) {
     console.log(`  ready: ${ready.map((milestone) => `${milestone.percent}%`).join(', ')}`);
   }
@@ -315,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) {
@@ -335,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);
 }
 
 
@@ -926,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;
@@ -965,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));
     },
   });
 
@@ -982,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);
   };
@@ -997,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.2.0-staging.9",
+  "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": "e2f3a9f874571a418b186a9cb8b5152eb0692b05"
+  "gitHead": "1e310fb2aaf244ede82956f5f6046ea9f52a7eb1"
 }

package/src/api.mjs

@@ -3,12 +3,13 @@ import {MAX_EVENT_STREAMS, requireDashboardOrigin, requireDashboardRead, require
 import {claimBundleFromState} from './claim-bundle.mjs';
 import {corsMiddleware} from './cors.mjs';
 import {renderCompanionWindow} from './companion-window.mjs';
+import {cycleReceiptKey, readCycleReceipt} from './cycle-receipt.mjs';
 import {describeOutcome, diagnosticsStatus, sendQueued} from './diagnostics.mjs';
 import {INSTALL_ID_DISPLAY_PATH, InstallIdError, readInstallId} from './install-id.mjs';
-import {STATE_DISPLAY_PATH} from './integration-spec.mjs';
+import {CYCLE_RECEIPT_PUBLIC_KEY, STATE_DISPLAY_PATH} from './integration-spec.mjs';
 import {MilestoneRecordError} from './milestones-reached.mjs';
-import {buildSummary} from './runtime.mjs';
-import {loadState, StateFileError} from './store.mjs';
+import {buildSummary, startNextCycle} from './runtime.mjs';
+import {loadState, StateFileError, StateLockError} from './store.mjs';
 
 const projectLevelGone = (_req, res) => {
   res.status(410).json({error: 'Project-level metadata is no longer exposed'});
@@ -21,6 +22,20 @@ const redeemGone = (_req, res) => {
   res.status(410).json({error: 'Break codes are no longer shown or recorded: each milestone reached shows its message on the dashboard.'});
 };
 
+// What POST /api/claim/receipt says when it changes nothing (docs/security.md, "The cycle receipt"): fixed words, numbers and
+// the times the record holds, never anything of the receipt but its cycle, and "Nothing changed." last, which is true of each.
+const NOTHING_CHANGED = 'Nothing changed.';
+const RECEIPT_WORDS = {
+  'no-key': `This build of KitCode takes no receipts: only a build for a campaign with a claim server does. ${NOTHING_CHANGED}`,
+  unreadable: `This is not a receipt KitCode can read. ${NOTHING_CHANGED}`,
+  signature: `This receipt was not signed by KitCode's claim server, so KitCode did not take it. ${NOTHING_CHANGED}`,
+  'install-id': `This receipt is for another KitCode install than the one on this computer. ${NOTHING_CHANGED}`,
+  used: (cycle, at) => `This receipt began cycle ${cycle} on this computer already, at ${at}. ${NOTHING_CHANGED}`,
+  behind: (cycle, current) => `This receipt is for cycle ${cycle}, and KitCode on this computer is in cycle ${current} already. ${NOTHING_CHANGED}`,
+  // Until 2026-10-22's phase 3 a receipt of a cycle ahead was refused, `ahead`; since then it begins the cycle after it, as the
+  // claim backend counts (milestones-reached.mjs, beginNextCycle).
+};
+
 // `diagnostics` is the tracker's send loop (src/diagnostics.mjs, startDiagnosticsLoop), for Send logs now.
 export function createServer(runtime, version, {diagnostics = null} = {}) {
   const app = express();
@@ -107,6 +122,93 @@ export function createServer(runtime, version, {diagnostics = null} = {}) {
     }
   });
 
+  // A cycle receipt (src/cycle-receipt.mjs; docs/backend.md, "The cycle receipt"; the plan of 2026-10-21, decision 1): the
+  // dashboard posts it once the claim backend's pages hand it back, after a voucher was issued, and the tracker begins the
+  // next cycle, whose milestones all count fresh from now (runtime.mjs, startNextCycle). A write, so it passes every write's
+  // guards first, a loopback Host, an allow-listed Origin and a JSON body (api-access.mjs); then it must be signed with the
+  // claim backend's key, which this build carries, name this install's id, and be the receipt of the cycle this install is in:
+  // anything else is refused in plain words and changes nothing. The signature is checked here alone, never by the prompt
+  // hook, which reads the record's cycle as it reads the rest (hard rule 7).
+  app.post('/api/claim/receipt', (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    const refuse = (status, reason, error, extra = {}) => res.status(status).json({error, reason, ...extra});
+    const text = req.body !== null && typeof req.body === 'object' && !Array.isArray(req.body) && typeof req.body.receipt === 'string' ? req.body.receipt : null;
+    const key = cycleReceiptKey(CYCLE_RECEIPT_PUBLIC_KEY);
+
+    if (key === null) {
+      refuse(503, 'no-key', RECEIPT_WORDS['no-key']);
+      return;
+    }
+
+    if (text === null) {
+      refuse(400, 'unreadable', `Send the receipt as {"receipt": "…"}. ${NOTHING_CHANGED}`);
+      return;
+    }
+
+    const read = readCycleReceipt(text, key);
+
+    if (!read.ok) {
+      refuse(422, read.problem, RECEIPT_WORDS[read.problem]);
+      return;
+    }
+
+    let installId;
+
+    try {
+      installId = readInstallId();
+    } catch (error) {
+      if (error instanceof InstallIdError) {
+        refuse(500, 'install-id-unreadable', `KitCode cannot read its install id, ${INSTALL_ID_DISPLAY_PATH}, and has left it as it is. ${NOTHING_CHANGED}`);
+        return;
+      }
+
+      throw error;
+    }
+
+    if (installId === null) {
+      refuse(503, 'no-install-id', `KitCode has no install id yet: the tracker makes one as it starts. Run \`kitcode untrack\`, then \`kitcode track\`. ${NOTHING_CHANGED}`);
+      return;
+    }
+
+    if (read.receipt.installId !== installId) {
+      refuse(422, 'install-id', RECEIPT_WORDS['install-id']);
+      return;
+    }
+
+    let outcome;
+
+    try {
+      outcome = startNextCycle(runtime, read.receipt);
+    } catch (error) {
+      if (error instanceof StateLockError) {
+        res.setHeader('Retry-After', '2');
+        refuse(503, 'busy', `KitCode's progress file is busy: try again in a moment. ${NOTHING_CHANGED}`);
+        return;
+      }
+
+      if (error instanceof StateFileError) {
+        refuse(500, 'state-unreadable', `KitCode cannot read ${STATE_DISPLAY_PATH}. ${NOTHING_CHANGED}`);
+        return;
+      }
+
+      throw error;
+    }
+
+    switch (outcome.outcome) {
+      case 'started':
+        res.json({cycle: outcome.cycle, startedAt: outcome.startedAt});
+        return;
+      case 'used':
+        refuse(409, 'used', RECEIPT_WORDS.used(outcome.cycle, outcome.startedAt), {cycle: outcome.cycle});
+        return;
+      case 'cycle':
+        refuse(409, 'behind', RECEIPT_WORDS.behind(read.receipt.cycle, outcome.current), {cycle: outcome.current});
+        return;
+      default:
+        refuse(500, 'record-damaged', `The record of when each milestone was reached, in ${STATE_DISPLAY_PATH}, is not one KitCode writes, and has been left as it is. ${NOTHING_CHANGED}`);
+    }
+  });
+
   // A tester build's diagnostics, for the staging dashboard (docs/security.md, "Tester diagnostics"): whether this tracker
   // sends them, its install id, which the dashboard links its own events by, what waits, and the last send. Only to an
   // allow-listed Origin, as the claim bundle, which holds the same install id; never the events, or the invited email.

package/src/break-progress.mjs

@@ -2,6 +2,11 @@
 // dashboard all show breakProgressPercent, so they agree. Every number is floored: none of them
 // reaches a milestone's percent before both of that milestone's targets are reached.
 //
+// Since 2026-10-20 (rewards/2-no-stack) each milestone counts from the moment the one before it was reached, and a summary
+// says where, `countedFrom` on each milestone (reward.mjs): every number here is then the progress within the current
+// milestone, what was earned since its start, and nothing earned before it. A summary from a tracker before then has no
+// `countedFrom`, and each number is what it was: every milestone counted from install.
+//
 // Pure, with no imports: the web app imports this file at build time.
 
 function earnedOf(reward) {
@@ -11,16 +16,59 @@ function earnedOf(reward) {
   };
 }
 
+function targetsOf(milestone) {
+  return {
+    seconds: Math.max(0, Number(milestone?.requiredSeconds) || 0),
+    equals: Math.max(0, Number(milestone?.requiredEquals) || 0),
+  };
+}
+
 function ladderOf(milestones) {
   return (Array.isArray(milestones) ? milestones : [])
     .map((milestone) => ({
       percent: Number(milestone?.percent) || 0,
-      seconds: Math.max(0, Number(milestone?.requiredSeconds) || 0),
-      equals: Math.max(0, Number(milestone?.requiredEquals) || 0),
+      ...targetsOf(milestone),
+      milestone,
     }))
     .sort((a, b) => a.percent - b.percent);
 }
 
+// Whether a summary's milestones count fresh, each from where it says: a tracker's since 2026-10-20.
+function countsFresh(milestones) {
+  return Array.isArray(milestones) && milestones.some((milestone) => milestone !== null && typeof milestone === 'object' && Object.hasOwn(milestone, 'countedFrom'));
+}
+
+// A milestone the summary says is reached: ready, or a code an earlier KitCode recorded as shown.
+function isReached(milestone) {
+  return milestone?.unlocked === true || milestone?.redeemed === true || milestone?.status === 'ready' || milestone?.status === 'redeemed';
+}
+
+// What counts toward `milestone`, {seconds, equals}. Counted fresh: what was earned since its start, `countedFrom`;
+// nothing for one that has not begun; and for one reached, its targets, which it met. From a tracker before 2026-10-20:
+// the totals since install.
+export function earnedToward(reward, milestone) {
+  const earned = earnedOf(reward);
+
+  if (milestone === null || typeof milestone !== 'object' || !Object.hasOwn(milestone, 'countedFrom')) {
+    return earned;
+  }
+
+  if (isReached(milestone)) {
+    return targetsOf(milestone);
+  }
+
+  const from = milestone.countedFrom;
+
+  if (from === null || typeof from !== 'object') {
+    return {seconds: 0, equals: 0};
+  }
+
+  return {
+    seconds: Math.max(0, earned.seconds - Math.floor(Math.max(0, Number(from.seconds) || 0))),
+    equals: Math.max(0, earned.equals - Math.max(0, Number(from.equals) || 0)),
+  };
+}
+
 // How far `value` has got from one target to the next, from 0 to 1.
 function segmentFraction(value, from, to) {
   if (!(to > from)) {
@@ -47,10 +95,33 @@ function climb(ladder, reached, fraction) {
   return previous.percent;
 }
 
+// Counted fresh: past every milestone reached, that one's percent plus `share` of the way to the next, floored, and at
+// most `cap(step)`.
+function climbFresh(reward, milestones, share, cap = (step) => step.percent - 1) {
+  let previous = 0;
+
+  for (const step of ladderOf(milestones)) {
+    if (!isReached(step.milestone)) {
+      const earned = earnedToward(reward, step.milestone);
+      const percent = Math.floor(previous + share(earned, step) * (step.percent - previous));
+      return Math.max(previous, Math.min(cap(step), percent));
+    }
+
+    previous = step.percent;
+  }
+
+  return previous;
+}
+
+function shareOf(value, target) {
+  return target > 0 ? Math.min(1, value / target) : 1;
+}
+
 // Percent of the way to one milestone: floor(100 × min(time ÷ its time, = ÷ its =)), at most 100.
-// It is 100 only when both targets are reached, so a locked milestone never shows 100 %.
+// It is 100 only when both targets are reached, so a locked milestone never shows 100 %. Counted fresh, the time and the
+// = are what was earned toward it (earnedToward).
 export function milestoneProgressPercent(reward, milestone) {
-  const {seconds, equals} = earnedOf(reward);
+  const {seconds, equals} = earnedToward(reward, milestone);
   const requiredSeconds = Math.max(0, Number(milestone?.requiredSeconds) || 0);
   const requiredEquals = Math.max(0, Number(milestone?.requiredEquals) || 0);
   const time = requiredSeconds > 0 ? Math.floor((100 * seconds) / requiredSeconds) : 100;
@@ -59,10 +130,15 @@ export function milestoneProgressPercent(reward, milestone) {
   return Math.max(0, Math.min(100, time, equalsPercent));
 }
 
-// The one progress number: how far along the 10, 20, 30, 50, 100 % milestones both targets have
-// got together. It is at least the percent of every milestone reached, and below the percent of the
-// first one that is not.
+// The one progress number: how far along the milestones, 30, 50 and 100 % since 2026-10-08 (10, 20, 30, 50 and 100 %
+// until then), both targets have got together. It is at least the percent of every milestone reached, and below the percent of the
+// first one that is not. Counted fresh, the share of the way to the next milestone is the share of its own targets earned
+// since its start.
 export function breakProgressPercent(reward, milestones = reward?.milestones) {
+  if (countsFresh(milestones)) {
+    return climbFresh(reward, milestones, (earned, step) => Math.min(shareOf(earned.seconds, step.seconds), shareOf(earned.equals, step.equals)));
+  }
+
   const {seconds, equals} = earnedOf(reward);
 
   return climb(
@@ -72,15 +148,24 @@ export function breakProgressPercent(reward, milestones = reward?.milestones) {
   );
 }
 
-// Time alone, placed on the same milestones.
+// Time alone, placed on the same milestones. Counted fresh, it reaches the next milestone's percent once its time is
+// earned, and goes no further: time earned past it while waiting for = counts toward nothing.
 export function timeProgressPercent(reward, milestones = reward?.milestones) {
+  if (countsFresh(milestones)) {
+    return climbFresh(reward, milestones, (earned, step) => shareOf(earned.seconds, step.seconds), (step) => step.percent);
+  }
+
   const {seconds} = earnedOf(reward);
 
   return climb(ladderOf(milestones), (step) => seconds >= step.seconds, (from, to) => segmentFraction(seconds, from.seconds, to.seconds));
 }
 
-// = alone, placed on the same milestones.
+// = alone, placed on the same milestones, as time alone is.
 export function equalsProgressPercent(reward, milestones = reward?.milestones) {
+  if (countsFresh(milestones)) {
+    return climbFresh(reward, milestones, (earned, step) => shareOf(earned.equals, step.equals), (step) => step.percent);
+  }
+
   const {equals} = earnedOf(reward);
 
   return climb(ladderOf(milestones), (step) => equals >= step.equals, (from, to) => segmentFraction(equals, from.equals, to.equals));

package/src/claim-bundle.mjs

@@ -3,8 +3,11 @@ import {focusTimeFrom} from './focus-clock.mjs';
 import {milestonesReachedFrom} from './milestones-reached.mjs';
 import {RULES_VERSION} from './source-snapshot.mjs';
 
-// The claim bundle (docs/backend.md, "The contract"): what a claim for the 50 or 100 % milestone carries,
-// in the shape of the contract's schema version 1 (packages/claim-contract). Totals only: the focus time
+// The claim bundle (docs/backend.md, "The contract"): what a claim for the 100 % milestone carries, in the shape of the
+// contract's schema version 4 (packages/claim-contract) since 2026-10-22, the milestones of the cycle counted in, with the
+// cycle and where it began, `cycle` and `cycleStart`; version 3 from 2026-10-20, whose milestones, 30, 50 and 100 %, each
+// carry the totals they counted from and were reached at, `start` and `end`; version 2 from 2026-10-08, the same milestones
+// without them; until then version 1, with 10, 20, 30, 50 and 100 %. Totals only: the focus time
 // and the = counted, when each milestone was reached, the counting rules, the CLI's version and the
 // install id, with when the bundle and the milestone record were made.
 //
@@ -13,13 +16,13 @@ import {RULES_VERSION} from './source-snapshot.mjs';
 // The CLI never sends it anywhere: the local API gives it to the dashboard, which carries it on in a later
 // phase.
 
-export const CLAIM_BUNDLE_SCHEMA_VERSION = 1;
+export const CLAIM_BUNDLE_SCHEMA_VERSION = 4;
 
 // The bundle for `state`, the user's state.json as read. Pure: it reads nothing else, and writes nothing.
 // A milestone record that is not what KitCode writes throws (milestones-reached.mjs).
 export function claimBundleFromState(state, {installId, cliVersion, createdAt}) {
   const ledger = equalsLedgerFrom(state);
-  const {recordingSince, milestones} = milestonesReachedFrom(state);
+  const {recordingSince, cycle, cycleStart, milestones} = milestonesReachedFrom(state);
 
   return {
     schemaVersion: CLAIM_BUNDLE_SCHEMA_VERSION,
@@ -32,6 +35,16 @@ export function claimBundleFromState(state, {installId, cliVersion, createdAt})
       equals: ledger.total_equals,
     },
     recordingSince,
-    milestones,
+    // The cycle counted in, and where it began: picked by name, as everything here is.
+    cycle,
+    cycleStart: {at: cycleStart.at, focusSeconds: cycleStart.focusSeconds, equals: cycleStart.equals},
+    // Picked by name too: each milestone's start and end are totals, {focusSeconds, equals}, or null.
+    milestones: milestones.map(({percent, status, reachedAt, start, end}) => ({
+      percent,
+      status,
+      reachedAt,
+      start: start === null ? null : {focusSeconds: start.focusSeconds, equals: start.equals},
+      end: end === null ? null : {focusSeconds: end.focusSeconds, equals: end.equals},
+    })),
   };
 }