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

package/src/integration-spec.mjs

@@ -1,15 +1,45 @@
-export const CLI_PACKAGE_NAME = '@kitkat-vn/kitcode';
+// The CLI's own package.json, for its name and its version, which live there alone (hard rule 6). Since 2026-10-22
+// (production/1-cli) the production setup prompt installs this version by number, and the dashboard, which bundles this file,
+// takes both from here: a JSON module, which Node loads without a warning from 22.12.0, the engines floor, and of which Vite
+// bundles only the two fields read. Until then this file imported nothing.
+import cliPackage from '../package.json' with {type: 'json'};
+
+// Since 2026-10-22 (production/1-cli; the operator's two names of 2026-10-02, and Q5 and Q7 of the plan of 2026-10-22) the
+// package is production's, `@kitkatvn/kitcode`, at 0.2.0: package.json's name and version. A tester build's copy names the
+// staging package there instead (scripts/tester-build.mjs), and so here. Until then `@kitkat-vn/kitcode`, written here.
+export const CLI_PACKAGE_NAME = cliPackage.name;
+export const CLI_VERSION = cliPackage.version;
 export const CLI_PACKAGE_COMMAND = `npx ${CLI_PACKAGE_NAME}`;
 export const CLI_GLOBAL_INSTALL_COMMAND = `npm install -g ${CLI_PACKAGE_NAME}`;
-// A staging round's tester build, published under npm's `staging` tag: since 2026-10-02 the only way a tester installs it
-// (stagingSetupPromptFor, below).
-export const CLI_STAGING_INSTALL_COMMAND = `${CLI_GLOBAL_INSTALL_COMMAND}@staging`;
+// What the production setup prompt installs: this version, by number, so that the dashboard and the CLI it installs are one
+// commit's. A newer version on npm reaches the prompt only with a deploy of the dashboard built from its commit.
+export const CLI_PINNED_INSTALL_COMMAND = `${CLI_GLOBAL_INSTALL_COMMAND}@${CLI_VERSION}`;
+// The staging package, which every tester build is published as, under npm's `staging` tag: since 2026-10-02 the only way a
+// tester installs one (stagingSetupPromptFor, below). It installs the same `kitcode` command as the production package, so npm
+// refuses to install either over the other: each prompt removes the other package first.
+export const CLI_STAGING_PACKAGE_NAME = '@kitkat-vn/kitcode';
+export const CLI_STAGING_INSTALL_COMMAND = `npm install -g ${CLI_STAGING_PACKAGE_NAME}@staging`;
+// The package's previous name, under which 0.1.39 was published on 2026-08-06 and is still npm's `latest` (docs/project-overview.md,
+// "Current state"). It installs the same `kitcode` command too, so since 2026-10-22 (production/1-cli) each prompt removes it
+// first, in the same command as the other channel's package.
+export const CLI_PREVIOUS_PACKAGE_NAME = '@onedigitas/kitcode';
 export const CLI_GLOBAL_COMMAND = 'kitcode';
+// Production's dashboard since 2026-10-22 (production/1-cli): what `kitcode dashboard` opens, and the origin every tracker
+// `kitcode track` starts allows (src/cors.mjs, bin/kitcode.mjs). A tester build's copy names the staging site here. Until then
+// https://kitcode.vercel.app/, the previous project's site, which is not ours.
 export const DASHBOARD_URL = "https://staging.kitcode.vn/";
 // Where a tester build sends KitCode's own diagnostics (src/diagnostics.mjs; docs/backend.md, "Tester diagnostics"): the
 // staging dashboard's /v1/diagnostics, which scripts/tester-build.mjs alone writes here, as it writes DASHBOARD_URL. null in
 // the repository, and so in every release of it: such a CLI collects, writes and sends no diagnostics at all.
 export const DIAGNOSTICS_URL = "https://staging.kitcode.vn/v1/diagnostics";
+// The claim backend's public key for cycle receipts (src/cycle-receipt.mjs; docs/backend.md, "The cycle receipt"): base64url of
+// the 32 raw bytes of the Ed25519 key whose private half exists on the claim backend's server alone. The tracker begins a
+// cycle only on a receipt it signed (api.mjs, POST /api/claim/receipt). Public, as the repository is, and written here by
+// scripts/tester-build.mjs, from the key the staging server printed (deploy/staging/cycle-receipt.pub), as it writes
+// DIAGNOSTICS_URL; and since 2026-10-22 (production/1-cli) by scripts/release.mjs in a production release's copy, from the key
+// the production server printed (deploy/production/cycle-receipt.pub). null in the repository: a CLI run from it takes no
+// receipt, and never begins a second cycle.
+export const CYCLE_RECEIPT_PUBLIC_KEY = "QsSBNGXhReBhjz0qk32fFLYiVCDtqKEGQwFB30LflTw";
 export const LOCAL_SERVER_URL = 'http://127.0.0.1:4747';
 export const STATE_DISPLAY_PATH = '~/.kitcode/state.json';
 export const RUNNER_PATH_PARTS = ['.kitcode', 'bin', 'kitcode'];
@@ -17,18 +47,61 @@ export const RUNNER_DISPLAY_PATH = `~/${RUNNER_PATH_PARTS.join('/')}`;
 
 // The milestones and the = each needs (docs/reward-rules.md §2). Until 2026-10-01 each had a break code, one fixed line of
 // code shown to everyone; the operator's decision 6 of that day replaced them with a message the claim backend's
-// settings give each milestone, which the dashboard shows. The 10–30 % tiers still hold a record each in the state file:
-// the hook's announcements, and a code shown before then.
-export const KITCODE_REWARD_TIERS = [
-  {percent: 10, requiredEquals: 3},
-  {percent: 20, requiredEquals: 6},
-  {percent: 30, requiredEquals: 9},
-];
-
-export const KITCODE_DISPLAY_MILESTONES = [
-  {percent: 50, requiredEquals: 12, displayOnly: true},
-  {percent: 100, requiredEquals: 15, displayOnly: true},
-];
+// settings give each milestone, which the dashboard shows. A tier holds a record in the state file: the hook's
+// announcements, and a code shown before then.
+//
+// Since 2026-10-08 (rewards/1-milestones-bar; the operator: "change milestone to: 30% - 50% - 100%") the milestones are
+// 30, 50 and 100 %, each with the targets it had: 30 % the one tier, 50 and 100 % shown and never announced, as before.
+// Until then 10 % (3 =, 6 min) and 20 % (6 =, 12 min) were tiers too. A record an earlier version kept of either, an
+// announcement, a code shown or the time it was reached, stays in the file as it is, and nothing reads it.
+//
+// Since 2026-10-20 (rewards/2-no-stack; the plan of that day, decisions 1 and 4) each milestone's targets, its focus time
+// and its =, are counted fresh from the moment the milestone before it was reached, the first's from install, and each
+// milestone names its own focus time, where 3600 s × its percent was the time target until then (reward.mjs). Two tables,
+// both public: the tester table, the short one, which every build of this repository and every tester build counts by,
+// its numbers the ones the milestones had; and the production table, whose numbers are DRAFTS until the client gives the
+// campaign's length: 3 h and 300 =, 5 h and 500 =, 10 h and 1,000 =, so 18 h and 1,800 = in all to reach 100 %.
+// MILESTONE_TABLE names the one in force: 'tester' here, and so in every tester build; a production release's copy alone
+// says 'production', which scripts/release.mjs writes there, one line, checked line by line, as tester-build.mjs writes
+// DASHBOARD_URL.
+//
+// Since 2026-10-21 both tables hold the operator's numbers of that day ("change the progress to 30% - 3h - 300 = / 50% -
+// 5h - 500 = / 100% - 8h - 1000 =", then "1. staging too 2. as written"): 3 h and 300 =, 5 h and 500 =, 8 h and 1,000 =,
+// so 16 h and 1,800 = in all to reach 100 %. Tester builds have no short targets any more, which reverses the plan's
+// decision 4 for the tester table; the production table's numbers are no longer drafts, and its 100 % is 8 h where the
+// draft said 10. The two tables stay two, equal, so that production's can differ again by one table's edit (a ruling,
+// docs/reward-rules.md §2). Until then the tester table was 1080 s and 9 =, 1800 s and 12 =, 3600 s and 15 =.
+//
+// Since 2026-10-22 the tester table is that short one again (the operator: "scale down the focus time and = requirements as
+// the previous time for staging for testing easier, keep the same for production"): 18 minutes and 9 =, 30 and 12, 60 and
+// 15, so 108 minutes and 36 = in all to reach 100 %, each still counted fresh. The production table keeps the operator's
+// numbers of 2026-10-21, and the two differ again. The claim backend holds a claim to its own MILESTONE_* settings, which
+// staging's server sets to the tester table by hand (docs/deployment-target.md).
+export const MILESTONE_TABLES = Object.freeze({
+  tester: Object.freeze([
+    Object.freeze({percent: 30, requiredSeconds: 1080, requiredEquals: 9}),
+    Object.freeze({percent: 50, requiredSeconds: 1800, requiredEquals: 12}),
+    Object.freeze({percent: 100, requiredSeconds: 3600, requiredEquals: 15}),
+  ]),
+  production: Object.freeze([
+    Object.freeze({percent: 30, requiredSeconds: 10800, requiredEquals: 300}),
+    Object.freeze({percent: 50, requiredSeconds: 18000, requiredEquals: 500}),
+    Object.freeze({percent: 100, requiredSeconds: 28800, requiredEquals: 1000}),
+  ]),
+});
+
+export const MILESTONE_TABLE = 'tester';
+
+const MILESTONE_TARGETS = MILESTONE_TABLES[MILESTONE_TABLE];
+
+if (!Array.isArray(MILESTONE_TARGETS)) {
+  throw new Error(`MILESTONE_TABLE is ${JSON.stringify(MILESTONE_TABLE)}, which is not one of the milestone tables: ${Object.keys(MILESTONE_TABLES).join(', ')}.`);
+}
+
+// 30 %, the first milestone, is the one tier; 50 and 100 % are shown alone.
+export const KITCODE_REWARD_TIERS = MILESTONE_TARGETS.slice(0, 1).map((milestone) => ({...milestone}));
+
+export const KITCODE_DISPLAY_MILESTONES = MILESTONE_TARGETS.slice(1).map((milestone) => ({...milestone, displayOnly: true}));
 
 export const AGENT_SPECS = {
   codex: {
@@ -169,7 +242,7 @@ export function kitCodeSkillMarkdown(source) {
     `    ${RUNNER_DISPLAY_PATH} dashboard`,
     '',
     'The prompt hook runs after each prompt submit and may add compact progress context such as total `=` counted, active time, next break remaining (`=` left and time left), or milestones reached. Treat that hook context as authoritative.',
-    'When hook context includes remaining equals and time to the next break milestone, briefly mention both in one short line after your normal answer on every turn (for example: `Break next: 4 = to break · 18m to break (20%).`). Do not calculate these values yourself.',
+    'When hook context includes remaining equals and time to the next break milestone, briefly mention both in one short line after your normal answer on every turn (for example: `Break next: 120 = to break · 1h 20m to break (30%).`). Do not calculate these values yourself.',
     '',
     'Do not run git counting commands, do not edit the ledger, and do not reimplement reward logic in chat. Use the KitCode CLI/server/hook output as the authority.',
     '',
@@ -210,12 +283,53 @@ export function kitCodeSkillMarkdown(source) {
   ].join('\n');
 }
 
+// A milestone's time as the setup prompt says it: whole hours as "3h", and otherwise as next-break-reminder.mjs writes a time
+// left, "2h 30m", "18m". Here, since this file imports none of the CLI's modules (the dashboard bundles it).
+function targetTime(seconds) {
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+
+  if (hours > 0) {
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+
+  return minutes > 0 ? `${minutes}m` : `${seconds}s`;
+}
+
+// Since 2026-10-20 each line says where its milestone counts from: install for the first, and for each other the moment the
+// one before it was reached (docs/reward-rules.md §2). Since 2026-10-21 each names its time, "3h of tracked time", where it
+// said "enough tracked time": with the operator's targets of that day a milestone's time is 3 to 8 hours. Since 2026-10-22
+// the tester table's times read "18m", "30m" and "1h", the production table's still "3h", "5h" and "8h".
 function milestoneLines() {
-  return [...KITCODE_REWARD_TIERS, ...KITCODE_DISPLAY_MILESTONES]
-    .map((milestone) => `- ${milestone.percent}% milestone: reached after enough tracked time and ${milestone.requiredEquals} counted = characters; the dashboard shows its message.`)
+  const milestones = [...KITCODE_REWARD_TIERS, ...KITCODE_DISPLAY_MILESTONES];
+
+  return milestones
+    .map((milestone, index) => `- ${milestone.percent}% milestone: reached after ${targetTime(milestone.requiredSeconds)} of tracked time and ${milestone.requiredEquals} counted = characters, both counted ${index === 0 ? 'from install' : `from the moment the ${milestones[index - 1].percent}% milestone was reached`}; the dashboard shows its message.`)
     .join('\n');
 }
 
+// The lines of step 2 that name a package or a version: the other packages, removed first, in one command; this one, installed;
+// and the version `kitcode --version` must print. The staging prompt (below) changes these three, and the untrack line, and
+// nothing else of step 2. Since 2026-10-22 the removal names the package's previous name too, beside the other channel's.
+const removeOtherPackagesLine = (otherPackages) => `2. Once Node.js 22.12+ is ready, first remove the other KitCode packages, if an earlier setup installed one: npm uninstall -g ${otherPackages.join(' ')}`;
+// What the production prompts remove before they install: the staging package and the package's previous name.
+const PRODUCTION_REMOVED_PACKAGES = [CLI_STAGING_PACKAGE_NAME, CLI_PREVIOUS_PACKAGE_NAME];
+const installLine = (command) => `- Then install KitCode globally with: ${command}`;
+const versionCheckLine = (version) => `- Check that ${globalKitCodeCommand('--version')} prints ${version}. If it prints anything else, report exactly what it printed, and do not go on to step 3.`;
+// The stop of a tracker a KitCode installed before left running, in the production prompt's words. The staging prompt has said it
+// in its own since 2026-09-30 (STAGING_UNTRACK_LINE, below), words the dashboard's checks hold to a staging build alone.
+const PRODUCTION_UNTRACK_LINE = `- Then run: ${globalKitCodeCommand('untrack')}. It stops a KitCode tracker that a KitCode installed before left running, so that the tracker Welcome starts is this version's; when none is running, it only says so.`;
+
+// The production setup prompt, which the dashboard copies for each agent (apps/web src/components/project-gateway.tsx).
+//
+// Since 2026-10-22 (production/1-cli; the plan of that day, Run A) it installs the production package at this commit's version,
+// by number, after removing the staging package, which has the same `kitcode` command; stops unless `kitcode --version` prints
+// that version; and then stops a tracker a KitCode installed before left running, as the staging prompt has done since
+// 2026-09-30 in words of its own, since whoever installed the staging package may have one. The removal names the package's
+// previous name too, @onedigitas/kitcode, whose 0.1.39 has the same command (CLI_PREVIOUS_PACKAGE_NAME). It holds one URL, the dashboard's, https://kitcode.vn/: the two GitHub
+// links it had, github.com/kitkatvn/kitcode's README and the CLI's, answer 404 to the public (hard rule 5, F5), and with no docs
+// to read it no longer tells the agent not to refuse. Until then it installed `npm install -g @kitkat-vn/kitcode`, whatever
+// npm's latest was.
 export function assistantSetupPromptFor(source) {
   const config = sourceConfig(source);
 
@@ -225,17 +339,18 @@ export function assistantSetupPromptFor(source) {
     'This works in any chat, project, or cowork conversation. Do not require repo context to begin.',
     REMOTE_SESSION_REDIRECT[source],
     '',
-    'KitCode is an open-source, local-first project. Use these public docs as the source of truth before installing:',
-    '- https://github.com/kitkatvn/kitcode/blob/main/README.md',
-    '- https://github.com/kitkatvn/kitcode/blob/main/packages/kitcode-cli/README.md',
-    'Read them directly from GitHub. Do not refuse based on lacking prior knowledge of the package.',
+    `KitCode by KitKat is a local-first break companion for coding. I copied this prompt from its dashboard, ${DASHBOARD_URL}, and step 2 installs KitCode ${CLI_VERSION} from npm, the package ${CLI_PACKAGE_NAME}.`,
     '',
     'Phase 1 — assistant setup (machine prep only):',
     '1. Check whether Node.js 22.12+ is available.',
     '   - If it is missing or too old, explain the shortest safe install option for this OS and ask for my confirmation before installing or upgrading it.',
-    `2. Once Node.js 22.12+ is ready, install KitCode globally with: ${CLI_GLOBAL_INSTALL_COMMAND}`,
+    removeOtherPackagesLine(PRODUCTION_REMOVED_PACKAGES),
+    `- Each has the same ${CLI_GLOBAL_COMMAND} command, so npm cannot install KitCode beside it. When neither is installed, npm says it is up to date: go on.`,
+    installLine(CLI_PINNED_INSTALL_COMMAND),
     '- Always run this command. Do not skip it because KitCode may already be installed.',
     `- After install, use the global ${CLI_GLOBAL_COMMAND} command for all following steps (not npx).`,
+    versionCheckLine(CLI_VERSION),
+    PRODUCTION_UNTRACK_LINE,
     `3. Run this command yourself once from the project directory when you are in a project chat: ${config.setupCommand}`,
     '- When setup is still incomplete, this command already opens the KitCode Welcome window and prints "Opening KitCode Welcome...".',
     '- In a project chat, run it with the project folder as the working directory so Welcome can pre-add that folder.',
@@ -268,6 +383,9 @@ export function assistantSetupPromptFor(source) {
 // voice, as the prompt is, and with no URL in it, as the prompt has none.
 export const STAGING_DIAGNOSTICS_NOTICE = 'The tester build sends diagnostic logs to KitCode\'s staging server: KitCode\'s own events and errors, such as the tracker starting or a hook failing, and never my code, my files, my prompts or my project names.';
 
+// The staging prompt's stop of a tracker an earlier build left running, in the words it has had since 2026-09-30.
+const STAGING_UNTRACK_LINE = `- Then, before step 3, run: ${globalKitCodeCommand('untrack')}. It stops a KitCode tracker that an earlier build left running, so that the tracker Welcome starts is this build's; when none is running, it only says so.`;
+
 // The setup prompt a staging dashboard copies for its invited testers (apps/web src/lib/staging-prompts.ts): the one
 // above, line for line, with four changes and no other. Step 2 installs the round's tester build from npm's `staging` tag,
 // and checks its version. Then, before step 3 turns KitCode on, it stops a tracker an earlier build left running. It holds
@@ -276,6 +394,15 @@ export const STAGING_DIAGNOSTICS_NOTICE = 'The tester build sends diagnostic log
 // server (STAGING_DIAGNOSTICS_NOTICE). It is made from the prompt above as it stands, so that the two cannot drift: a line
 // it changes that is not there once throws, and check-integration-spec.mjs runs both.
 //
+// Since 2026-10-22 (production/1-cli) the prompt above is production's, with a version check and a stop of an earlier tracker of
+// its own, and the four changes are these: the round's line and the diagnostics notice where it names the dashboard; the
+// production package removed where it removes the staging package, beside the package's previous name, which both remove;
+// npm's `staging` tag installed where it installs its version;
+// and the tester build's version checked where it checks its own, with its own words for the stop of an earlier tracker where
+// production has its own. The removal is new to this prompt too, the first two lines of step 2, which installs on a line of its
+// own: a tester who installed the production package must remove it first, as npm installs no two packages with the same
+// `kitcode` command. Its other words are as they were.
+//
 // Until 2026-10-02 it could install a file the tester downloaded from the staging site instead (install 'file', with its
 // fileName). The operator's rule of that day is npm alone, "never let user download file even as tester, must be via npm
 // package only": it takes the tester build's version and nothing else, and refuses an option it does not know, so that a
@@ -298,33 +425,36 @@ export function stagingSetupPromptFor(source, options) {
     return found[0];
   };
 
-  // The paragraph of public docs, to the blank line after it, gives way to one line about the round.
-  const docs = onlyLine((line) => line.startsWith('KitCode is an open-source, local-first project.'), 'the public docs');
-  const docsEnd = lines.indexOf('', docs);
+  // The paragraph that names the dashboard, to the blank line after it, gives way to one line about the round.
+  const intro = onlyLine((line) => line.startsWith('KitCode by KitKat is a local-first break companion for coding.'), 'the dashboard\'s paragraph');
+  const introEnd = lines.indexOf('', intro);
 
-  if (docsEnd === -1) {
-    throw new Error('stagingSetupPromptFor found no blank line after the public docs: assistantSetupPromptFor changed, and stagingSetupPromptFor must follow it.');
+  if (introEnd === -1) {
+    throw new Error('stagingSetupPromptFor found no blank line after the dashboard\'s paragraph: assistantSetupPromptFor changed, and stagingSetupPromptFor must follow it.');
   }
 
-  lines.splice(docs, docsEnd - docs, `KitCode is a local-first project. I am an invited tester of its staging round, which needs KitCode's tester build, ${testerVersion}: step 2 installs it.`, STAGING_DIAGNOSTICS_NOTICE);
-
-  const installLine = onlyLine((line) => line.endsWith(`install KitCode globally with: ${CLI_GLOBAL_INSTALL_COMMAND}`), 'the install');
-  lines[installLine] = lines[installLine].replace(`with: ${CLI_GLOBAL_INSTALL_COMMAND}`, `with: ${CLI_STAGING_INSTALL_COMMAND}`);
+  lines.splice(intro, introEnd - intro, `KitCode is a local-first project. I am an invited tester of its staging round, which needs KitCode's tester build, ${testerVersion}: step 2 installs it.`, STAGING_DIAGNOSTICS_NOTICE);
 
-  const globalCommand = onlyLine((line) => line === `- After install, use the global ${CLI_GLOBAL_COMMAND} command for all following steps (not npx).`, 'the global command');
-  lines.splice(
-    globalCommand + 1,
-    0,
-    `- Check that ${globalKitCodeCommand('--version')} prints ${testerVersion}. If it prints anything else, report exactly what it printed, and do not go on to step 3.`,
-    `- Then, before step 3, run: ${globalKitCodeCommand('untrack')}. It stops a KitCode tracker that an earlier build left running, so that the tracker Welcome starts is this build's; when none is running, it only says so.`,
-  );
+  // Each of the three lines of step 2 that name a package or a version, found once, and replaced.
+  for (const [production, staging, what] of [
+    [removeOtherPackagesLine(PRODUCTION_REMOVED_PACKAGES), removeOtherPackagesLine([CLI_PACKAGE_NAME, CLI_PREVIOUS_PACKAGE_NAME]), 'the removal of the other packages'],
+    [installLine(CLI_PINNED_INSTALL_COMMAND), installLine(CLI_STAGING_INSTALL_COMMAND), 'the install'],
+    [versionCheckLine(CLI_VERSION), versionCheckLine(testerVersion), 'the version check'],
+    [PRODUCTION_UNTRACK_LINE, STAGING_UNTRACK_LINE, 'the stop of an earlier tracker'],
+  ]) {
+    lines[onlyLine((line) => line === production, what)] = staging;
+  }
 
   return lines.join('\n');
 }
 
-export function setupPromptFor(source, options = {}) {
+// The longer setup prompt, which ships in the package and which only check-integration-spec.mjs calls (docs/security.md, "The
+// setup prompt: F5"). Since 2026-10-22 (production/1-cli) it follows the production prompt above: no GitHub link, since none
+// resolves publicly, and so no README to read first and no `readmeUrl` option; the staging package and the package's previous
+// name removed before this version is installed, by number, and checked. Its URLs are the dashboard's and the tracker's own
+// address on this machine.
+export function setupPromptFor(source) {
   const config = sourceConfig(source);
-  const readmeUrl = options.readmeUrl ?? 'https://github.com/kitkatvn/kitcode/blob/main/README.md';
   const hookCommand = hookCommandFor(source);
   const expectedHook = hookConfigFor(source);
 
@@ -332,9 +462,6 @@ export function setupPromptFor(source, options = {}) {
     'Welcome to KitCode.',
     '',
     `You are ${config.agentName} helping me set up KitCode skills and hooks.`,
-    'Read the project README carefully before changing anything.',
-    '',
-    `Project README: ${readmeUrl}`,
     '',
     'Mission:',
     `- Set up KitCode for ${config.agentName} on the current local machine.`,
@@ -360,11 +487,11 @@ export function setupPromptFor(source, options = {}) {
     'Required checks:',
     '- Node.js 22.12+ is required.',
     '- Git is required for Git Mode.',
-    '- Official source and safety reference: https://github.com/kitkatvn/kitcode',
-    '- Read the public root README and packages/kitcode-cli/README.md instead of relying on prior knowledge of the package.',
-    `- Install KitCode globally with: ${CLI_GLOBAL_INSTALL_COMMAND}`,
+    `- First remove the other KitCode packages, if an earlier setup installed one: npm uninstall -g ${PRODUCTION_REMOVED_PACKAGES.join(' ')}. Each has the same ${CLI_GLOBAL_COMMAND} command, so npm cannot install KitCode beside it.`,
+    `- Install KitCode globally with: ${CLI_PINNED_INSTALL_COMMAND}`,
     '- Always run this command. Do not skip it because KitCode may already be installed.',
     `- After install, use the global ${CLI_GLOBAL_COMMAND} command for all following steps (not npx).`,
+    `- Check that ${globalKitCodeCommand('--version')} prints ${CLI_VERSION}. If it prints anything else, report exactly what it printed, and stop there.`,
     '',
     `${config.agentName} setup:`,
     `- Prefer the CLI installer from the project directory in a project chat: ${config.setupCommand}`,

package/src/milestone-record.mjs

@@ -0,0 +1,214 @@
+// The milestone record in state.json, `milestonesReached`, read (docs/reward-rules.md §6.1): what each milestone's entry
+// says, checked as KitCode writes it. Pure, with no imports: reward.mjs reads it to decide the milestones, and
+// milestones-reached.mjs to write the record and to report it in the claim bundle.
+//
+//   {"recordingSince": "2026-09-25T09:15:00.004Z",
+//    "milestones": {"30": {"reachedBeforeRecording": true},
+//                   "50": {"reachedAt": "2026-10-20T11:03:27.918Z", "focusSeconds": 3600, "equals": 15}},
+//    "freshSince": {"at": "2026-10-20T10:00:00.000Z", "focusSeconds": 2400, "equals": 11}}
+//
+// Since 2026-10-20 (rewards/2-no-stack) an entry the CLI writes also holds the totals at the moment the milestone was
+// reached, its focus seconds and its =, and `freshSince` the totals at the moment this KitCode first wrote a record that
+// holds a milestone reached without them: by an earlier KitCode, or before the record began. The milestone after such a
+// one counts from `freshSince` (the plan's decision 2). An entry an earlier KitCode wrote, `reachedAt` alone, stays as it
+// is, and so does every field this version does not know.
+//
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2) the record counts in cycles (the plan of 2026-10-21, decision 1: after a
+// claim, all progress resets). Cycle 1 is the record as it was, its entries in `milestones`; each later cycle is one entry of
+// `cycles`, added when the tracker takes a receipt the claim backend signed for the voucher of the cycle before
+// (milestones-reached.mjs, beginNextCycle), and never changed after but for its own milestones, added once each. Since 2026-10-22's
+// phase 3 a cycle is numbered as the claim backend counts, the one after its receipt's, so the numbers can skip: a KitCode installed
+// afresh in cycle 1 that takes the receipt of cycle 2 begins cycle 3.
+//
+//    "cycles": [{"cycle": 2, "startedAt": "2026-10-22T08:00:00.000Z", "focusSeconds": 57900, "equals": 1810,
+//                "receipt": {"claimId": "…", "issuedAt": "2026-10-22T07:58:00.000Z"},
+//                "milestones": {"30": {"reachedAt": "…", "focusSeconds": 68722, "equals": 2110}}}]
+//
+// A cycle's start is the totals since install at the moment it began, which its first milestone counts from; the totals keep
+// counting across cycles. Nothing of cycle 1 changes when cycle 2 begins: the record is additive only (hard rule 4).
+
+// A time as toISOString writes it, and a real one: 2026-02-30 is not.
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isInstant(value) {
+  if (typeof value !== 'string' || !INSTANT.test(value)) {
+    return false;
+  }
+
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value;
+}
+
+function isCount(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+const CLAIM_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+
+// A record as KitCode writes it: when it began, and its entries.
+export function isRecord(record) {
+  return isObject(record) && isInstant(record.recordingSince) && isObject(record.milestones);
+}
+
+// The totals an entry, or freshSince, holds: both, whole and not below 0, or neither (null). Anything else is undefined:
+// not what KitCode writes.
+function totalsOf(value) {
+  const hasSeconds = Object.hasOwn(value, 'focusSeconds');
+  const hasEquals = Object.hasOwn(value, 'equals');
+
+  if (!hasSeconds && !hasEquals) {
+    return null;
+  }
+
+  return hasSeconds && hasEquals && isCount(value.focusSeconds) && isCount(value.equals)
+    ? {seconds: value.focusSeconds, equals: value.equals}
+    : undefined;
+}
+
+// One milestone's entry: {kind: 'before-recording'} or {kind: 'reached', reachedAt, end}, `end` the totals it was reached
+// at, or null when the entry holds none; undefined when it is not an entry KitCode writes.
+function entryOf(entry) {
+  if (!isObject(entry)) {
+    return undefined;
+  }
+
+  if (entry.reachedBeforeRecording === true && entry.reachedAt === undefined) {
+    return totalsOf(entry) === null ? {kind: 'before-recording', reachedAt: null, end: null} : undefined;
+  }
+
+  if (isInstant(entry.reachedAt) && entry.reachedBeforeRecording === undefined) {
+    const end = totalsOf(entry);
+    return end === undefined ? undefined : {kind: 'reached', reachedAt: entry.reachedAt, end};
+  }
+
+  return undefined;
+}
+
+// A later cycle's entry, read for `percents`, `after` the number of the cycle before it: {cycle, startedAt, start, receipt,
+// entries}, or a problem's words, a string, when it is not what KitCode writes. Each of its milestones was reached with its
+// totals: a later cycle counts from a start it knows. Its number is past the one before it, by one when the tracker took the
+// receipt of the cycle it was in, and by more since 2026-10-22's phase 3, when it took one of a cycle ahead, as the claim
+// backend counts them (milestones-reached.mjs, beginNextCycle).
+function cycleOf(value, after, percents) {
+  if (!isObject(value) || !Number.isSafeInteger(value.cycle) || value.cycle <= after || !isInstant(value.startedAt) || !isCount(value.focusSeconds) || !isCount(value.equals)
+    || !isObject(value.receipt) || typeof value.receipt.claimId !== 'string' || !CLAIM_ID.test(value.receipt.claimId) || !isInstant(value.receipt.issuedAt)
+    || !isObject(value.milestones)) {
+    return `holds a cycle after cycle ${after} that KitCode does not write`;
+  }
+
+  const cycle = value.cycle;
+  const entries = new Map();
+
+  for (const percent of percents) {
+    if (!Object.hasOwn(value.milestones, String(percent))) {
+      continue;
+    }
+
+    const entry = entryOf(value.milestones[String(percent)]);
+
+    if (entry?.kind !== 'reached' || entry.end === null) {
+      return `holds an entry for ${percent} % in cycle ${cycle} that KitCode does not write`;
+    }
+
+    entries.set(percent, entry);
+  }
+
+  return {
+    cycle,
+    startedAt: value.startedAt,
+    start: {seconds: value.focusSeconds, equals: value.equals},
+    receipt: {claimId: value.receipt.claimId, issuedAt: value.receipt.issuedAt},
+    entries,
+  };
+}
+
+// The record, read for `percents`, the milestones in order (the retired 10 and 20 % are never among them, whatever their
+// entries hold):
+//
+//   {state: 'none'}: no record yet, a file from before it, or one 0.1.39 rewrote;
+//   {state: 'damaged', problem}: not what KitCode writes, which is left as it is, never repaired or written over;
+//   {state: 'kept', recordingSince, freshSince, entries, cycles, current}: `entries` maps each percent recorded in cycle 1 to
+//   its entry, and `freshSince` is cycle 1's {at, seconds, equals} or null; since 2026-10-22 `cycles` lists the later cycles,
+//   oldest first, each {cycle, startedAt, start, receipt, entries}, and `current` is the cycle the milestones count in now:
+//   {cycle: 1, startedAt: null, start: {seconds: 0, equals: 0}, receipt: null, entries, freshSince} with no later one, else
+//   the last, its freshSince null.
+//
+// A milestone with its totals, after one whose totals are not known, counts from freshSince: without it, the record is
+// not one KitCode writes.
+export function readMilestoneRecord(record, percents) {
+  if (record === undefined) {
+    return {state: 'none'};
+  }
+
+  if (!isRecord(record)) {
+    return {state: 'damaged', problem: 'is not the record KitCode writes'};
+  }
+
+  let freshSince = null;
+
+  if (record.freshSince !== undefined) {
+    const totals = isObject(record.freshSince) && isInstant(record.freshSince.at) ? totalsOf(record.freshSince) : undefined;
+
+    if (!totals) {
+      return {state: 'damaged', problem: 'holds a start of fresh counting (freshSince) that KitCode does not write'};
+    }
+
+    freshSince = {at: record.freshSince.at, ...totals};
+  }
+
+  const entries = new Map();
+
+  for (const percent of percents) {
+    if (!Object.hasOwn(record.milestones, String(percent))) {
+      continue;
+    }
+
+    const entry = entryOf(record.milestones[String(percent)]);
+
+    if (entry === undefined) {
+      return {state: 'damaged', problem: `holds an entry for ${percent} % that KitCode does not write`};
+    }
+
+    entries.set(percent, entry);
+  }
+
+  // Each milestone's start, in order: install for the first; for another, the totals the one before it was reached at,
+  // when its entry holds them, and otherwise freshSince.
+  let previousEnd = {seconds: 0, equals: 0};
+
+  for (const percent of percents) {
+    const entry = entries.get(percent);
+
+    if (entry?.end && previousEnd === null && freshSince === null) {
+      return {state: 'damaged', problem: `holds the totals ${percent} % was reached at, with no start for them to count from`};
+    }
+
+    previousEnd = entry?.end ?? null;
+  }
+
+  // Since 2026-10-22: the later cycles, oldest first, each past the one before it, the first past cycle 1.
+  const cycles = [];
+
+  if (record.cycles !== undefined) {
+    if (!Array.isArray(record.cycles)) {
+      return {state: 'damaged', problem: 'holds cycles that KitCode does not write'};
+    }
+
+    for (const value of record.cycles) {
+      const cycle = cycleOf(value, cycles.at(-1)?.cycle ?? 1, percents);
+
+      if (typeof cycle === 'string') {
+        return {state: 'damaged', problem: cycle};
+      }
+
+      cycles.push(cycle);
+    }
+  }
+
+  const current = cycles.at(-1) ?? {cycle: 1, startedAt: null, start: {seconds: 0, equals: 0}, receipt: null, entries, freshSince};
+  return {state: 'kept', recordingSince: record.recordingSince, freshSince, entries, cycles, current: {freshSince: null, ...current}};
+}