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

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
@@ -261,10 +279,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 +322,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

@@ -90,6 +90,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,7 +285,9 @@ 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).
+// 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();
   const next = reward.nextBreak;
@@ -294,6 +298,10 @@ function printRewardSummary() {
   console.log(`  active time: ${formatDuration(reward.earnedSeconds)}`);
   console.log(`  campaign progress: ${reward.progressPercent}%`);
 
+  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(', ')}`);
   }

package/package.json

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

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},
+    })),
   };
 }

package/src/companion-window.mjs

@@ -32,10 +32,10 @@ button{cursor:pointer}
 ${COMPANION_HIDE_CSS}
 `;
   const script = `
-const API_BASE=${JSON.stringify(apiBase)};const 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');
+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)));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;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 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()}}
@@ -45,6 +45,10 @@ dashboardButton.addEventListener('click',()=>{if(window.kitcodeCompanion?.openDa
 sync();const events=new EventSource(API_BASE+'/api/events');events.addEventListener('summary',(event)=>{try{render(JSON.parse(event.data))}catch{offline()}});events.onerror=offline;
 `;
 
+  // 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.
+  //
   // 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
   // 6), and a milestone reached stays reached, so nothing lights it now. The Mini cannot show a message itself: the
@@ -55,5 +59,5 @@ sync();const events=new EventSource(API_BASE+'/api/events');events.addEventListe
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="${contentSecurityPolicy({script, style, connect: [apiBase || "'self'"]})}"><meta name="viewport" content="width=device-width, initial-scale=1">
 <title>KitCode Counter</title><style>${style}</style></head>
-<body><main class="widget-window" id="main" data-testid="companion-counter-bar">${renderCompanionTitleBar()}<div class="widget-body"><div class="brand-label" aria-label="KitCode Counter">KITCODE<br>COUNTER</div><strong class="percentage" id="percent" data-testid="mini-percent">--</strong><div class="progress-box" aria-hidden="true"><div class="progress-fill" id="progressFill"><div class="progress-row">========================</div><div class="progress-row">========================</div></div></div><div class="metrics-group" aria-label="KitCode counters"><div class="metric-item"><div class="metric-value" id="countValue" data-testid="mini-count">--</div><div class="metric-label">= COUNT</div></div><div class="metric-item"><div class="metric-value" id="workedValue" data-testid="mini-worked">--</div><div class="metric-label">WORKED</div></div><div class="metric-item"><div class="metric-value" id="idleValue" data-testid="mini-idle">--</div><div class="metric-label">IDLE</div></div></div><button class="claim-btn" id="dashboardButton" data-testid="companion-dashboard" type="button" title="Open the dashboard, where each milestone reached shows its message">See more</button></div></main><script>${script}</script></body></html>`;
+<body><main class="widget-window" id="main" data-testid="companion-counter-bar">${renderCompanionTitleBar()}<div class="widget-body"><div class="brand-label" id="brandLabel" aria-label="KitCode Counter" data-testid="mini-brand">KITCODE<br><span id="brandSecond">COUNTER</span></div><strong class="percentage" id="percent" data-testid="mini-percent">--</strong><div class="progress-box" aria-hidden="true"><div class="progress-fill" id="progressFill"><div class="progress-row">========================</div><div class="progress-row">========================</div></div></div><div class="metrics-group" aria-label="KitCode counters"><div class="metric-item"><div class="metric-value" id="countValue" data-testid="mini-count">--</div><div class="metric-label">= COUNT</div></div><div class="metric-item"><div class="metric-value" id="workedValue" data-testid="mini-worked">--</div><div class="metric-label">WORKED</div></div><div class="metric-item"><div class="metric-value" id="idleValue" data-testid="mini-idle">--</div><div class="metric-label">IDLE</div></div></div><button class="claim-btn" id="dashboardButton" data-testid="companion-dashboard" type="button" title="Open the dashboard, where each milestone reached shows its message">See more</button></div></main><script>${script}</script></body></html>`;
 }

package/src/cors.mjs

@@ -1,5 +1,7 @@
 // The origins a tracker allows with nothing configured: the hosted dashboard's and the local development
-// servers'. Pinned by local-api.test.mjs.
+// servers'. Pinned by local-api.test.mjs. Since 2026-10-22 (production/1-cli) the hosted dashboard is production's,
+// https://kitcode.vn, where it was https://kitcode.vercel.app, the previous project's site; a tester build's copy has the
+// staging site's in its place (scripts/tester-build.mjs).
 export const DEFAULT_ALLOWED_ORIGINS = new Set([
   // The staging dashboard this tester build is for (scripts/tester-build.mjs in the repository).
   "https://staging.kitcode.vn",