@kitkat-vn/kitcode 0.2.0-staging.3 → 0.2.0-staging.5

package/src/git.mjs

@@ -182,11 +182,24 @@ const OWN_COMMIT = /^commit(?: \((?:amend|initial)\))?:(?: |$)/;
 // names are 40 hex characters, or 64 in a SHA-256 repository.
 const REFLOG_LINE = /^([0-9a-f]{40}|[0-9a-f]{64}) ([0-9a-f]{40}|[0-9a-f]{64}) [^\t]*(?:\t(.*))?$/;
 
-// The files git leaves while an operation waits for the user: a merge (a pull's, too) stopped on a
-// conflict or run with --no-commit, a cherry-pick, a revert, a rebase, `git am`, and a squash merge not
-// yet committed. What they brought is in the working tree before any reflog line says so.
-const WAITING_OPERATIONS = ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'REBASE_HEAD', 'rebase-merge', 'rebase-apply', 'SQUASH_MSG'];
-const GIT_PATHS = ['logs/HEAD', 'index', 'index.lock', ...WAITING_OPERATIONS];
+// The files git leaves while an operation waits for the user, the ones git itself goes by to say that one
+// is in progress (wt-status.c): a merge (a pull's, too) stopped on a conflict or run with --no-commit,
+// MERGE_HEAD; a cherry-pick, CHERRY_PICK_HEAD; a revert, REVERT_HEAD; a rebase, rebase-merge/, or
+// rebase-apply/ with the apply backend; `git am`, rebase-apply/. What they brought is in the working tree
+// before any reflog line says so. Each goes when the operation is finished, aborted or quit, and for as
+// long as it stays git says the operation is in progress. Until 2026-10-01 REBASE_HEAD was among them: git
+// writes it when a rebase stops, and leaves it behind when the rebase ends after its last pick stopped
+// (--continue, --skip) or is left with --quit. Of the everyday commands only the next rebase removes it, a
+// commit, a checkout or a reset does not, while git says no rebase is in progress, and every scan of the
+// project was a baseline (docs/lessons-learned.md F22).
+const WAITING_OPERATIONS = ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply'];
+// A squash merge leaves no MERGE_HEAD and moves no HEAD: what it brought waits in the index, and SQUASH_MSG
+// is the message git offers the commit that records it. git leaves SQUASH_MSG behind when that is restored
+// away (git restore, git checkout -- <path>), and says nothing is in progress; the next commit, a reset or a
+// switch of branch removes it. So SQUASH_MSG says a squash merge waits only while the index differs from
+// HEAD.
+const SQUASH_MESSAGE = 'SQUASH_MSG';
+const GIT_PATHS = ['logs/HEAD', 'index', 'index.lock', ...WAITING_OPERATIONS, SQUASH_MESSAGE];
 
 // A command writing the index (a checkout, a merge, add, commit) holds index.lock while it writes the
 // working tree, and moves HEAD and writes its reflog line just after it lets go. A lock is waited for
@@ -370,6 +383,29 @@ function readReflog(logPath, from) {
   }
 }
 
+// Whether the index differs from HEAD: anything staged, a conflict too. When git cannot say (no commit
+// yet, say), it is taken to: when in doubt, a baseline. diff-index reads the index and HEAD's tree, and
+// writes nothing.
+function indexDiffersFromHead(repoRoot) {
+  try {
+    runGit(repoRoot, ['diff-index', '--cached', '--quiet', 'HEAD', '--']);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+// The operations waiting for the user, by the files git leaves for them: none, or their names.
+function waitingOperations(repoRoot, paths) {
+  const waiting = WAITING_OPERATIONS.filter((name) => fs.existsSync(paths[name]));
+
+  if (fs.existsSync(paths[SQUASH_MESSAGE]) && indexDiffersFromHead(repoRoot)) {
+    waiting.push(SQUASH_MESSAGE);
+  }
+
+  return waiting;
+}
+
 // Whether the reflog explains how HEAD got from `since` to `now`, and how. `arrival`: null when HEAD did
 // not move, or moved only by the user's own commits; 'moved' when it moved some other way; 'unexplained'
 // when the reflog was rewritten, is gone, or does not lead from one to the other (HEAD moved with no
@@ -412,7 +448,9 @@ function arrivalFromReflog(since, now, log) {
 // before, and the position now, for the next scan to start from. `arrival`:
 //   null           nothing: HEAD is where it was, or moved only by the user's own commits;
 //   'moved'        HEAD moved some other way: a pull, a merge, a checkout, a rebase, a reset …;
-//   'waiting'      a merge, a cherry-pick, a revert, a rebase, am or a squash merge waits for the user;
+//   'waiting'      a merge, a cherry-pick, a revert, a rebase, am or a squash merge waits for the user,
+//                  and `waiting` names the files git left for it (the tracker reports it, runtime.mjs
+//                  noteGitWaiting, since 2026-10-01);
 //   'locked'       index.lock stayed for longer than LOCK_WAIT_MS: a long command, or a git that died
 //                  holding it, which git itself refuses to run past until the file is removed (until
 //                  2026-09-25 this was 'waiting'; the tracker now reports it, runtime.mjs noteGitLock);
@@ -440,8 +478,10 @@ export function gitArrival(repoRoot, since) {
     return {arrival: 'locked', operation: true, position};
   }
 
-  if (WAITING_OPERATIONS.some((name) => fs.existsSync(paths[name]))) {
-    return {arrival: 'waiting', operation: true, position};
+  const waiting = waitingOperations(repoRoot, paths);
+
+  if (waiting.length > 0) {
+    return {arrival: 'waiting', operation: true, position, waiting};
   }
 
   return {...reflog, position};

package/src/hook-prompt.mjs

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import {spawn} from 'node:child_process';
+import {hookFinished, hookStarted} from './diagnostics.mjs';
 import {appendLogLine} from './log-file.mjs';
 import {formatBreakDuration, nextBreakReminder} from './next-break-reminder.mjs';
 import {getDiskRewardSummary, getReadyUnannouncedTiers, markTiersAnnounced} from './reward.mjs';
@@ -100,6 +101,9 @@ function notify(title, message) {
   }
 }
 
+// A milestone reached is said in neutral words (the operator's decisions 5 and 6 of 2026-10-01): its message, from the
+// campaign, is on the dashboard, and no milestone is a reward ready, or a code. Until then this said "Reward ready at",
+// and the announcement below "KitCode break code ready".
 function progressContextFor(reward) {
   const nextBreak = reward.nextBreak ?? nextBreakReminder(reward);
   const ready = reward.milestones.filter((entry) => entry.status === 'ready' && !entry.redeemed);
@@ -108,7 +112,7 @@ function progressContextFor(reward) {
   ];
 
   if (ready.length > 0) {
-    parts.push(`Reward ready at ${ready.map((entry) => `${entry.percent}%`).join(', ')}. Mention \`kitcode dashboard\` briefly after this turn.`);
+    parts.push(`Milestone reached at ${ready.map((entry) => `${entry.percent}%`).join(', ')}. Mention \`kitcode dashboard\` briefly after this turn.`);
   }
 
   if (nextBreak) {
@@ -140,7 +144,7 @@ function hookOutputFor({tiers = [], reward = null}) {
   const command = 'kitcode dashboard';
   const additionalContext = [
     progressContext,
-    `KitCode break code ready (${labels}). Briefly tell the user they can open the dashboard with \`${command}\` after this turn.`,
+    `KitCode milestone reached (${labels}). Briefly tell the user they can open the dashboard with \`${command}\` after this turn.`,
   ].filter(Boolean).join(' ');
 
   return {
@@ -172,11 +176,20 @@ function collectPromptProgress(source) {
   }
 }
 
+// In a tester build alone (src/diagnostics.mjs), each run also leaves a start marker, which it removes as it ends, so that a
+// run its agent stopped at the timeout is found later by whatever sends, since it cannot record its own end; and it records
+// a failure, by the error's code and name, or else a run past 2 s: one event at most, one small file. The hook never touches
+// the network: a tester build's tracker, or a command, sends what it recorded. Neither call ever throws; in any other build
+// each returns at once.
 export async function runPromptHook({source}) {
   if (isDisabled()) {
     return;
   }
 
+  const started = Date.now();
+  const marker = hookStarted(source, started);
+  let failure = null;
+
   try {
     const input = await readStdin();
     const payload = JSON.parse(input || '{}');
@@ -193,9 +206,12 @@ export async function runPromptHook({source}) {
     }
 
     const label = announced.map((tier) => `${tier.percent}%`).join(', ');
-    notify('KitCode break code ready', `Milestone ${label} unlocked. Open kitcode dashboard.`);
+    notify('KitCode milestone reached', `Milestone ${label} unlocked. Open kitcode dashboard.`);
     process.stdout.write(`${JSON.stringify(hookOutputFor({tiers: announced, reward}))}\n`);
   } catch (error) {
+    failure = error;
     logHookError(error);
+  } finally {
+    hookFinished(marker, source, Date.now() - started, failure);
   }
 }

package/src/integration-spec.mjs

@@ -1,24 +1,33 @@
 export const CLI_PACKAGE_NAME = '@kitkat-vn/kitcode';
 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, once one is published under npm's `staging` tag (stagingSetupPromptFor, below).
+// 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`;
 export const CLI_GLOBAL_COMMAND = 'kitcode';
 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";
 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'];
 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, code: 'if(tired){return 10;}', requiredEquals: 3},
-  {percent: 20, code: 'takeBreak(20);', requiredEquals: 6},
-  {percent: 30, code: 'while(working)break(30);', requiredEquals: 9},
+  {percent: 10, requiredEquals: 3},
+  {percent: 20, requiredEquals: 6},
+  {percent: 30, requiredEquals: 9},
 ];
 
 export const KITCODE_DISPLAY_MILESTONES = [
-  {percent: 50, code: 'mediumStake.unlock(50);', requiredEquals: 12, displayOnly: true},
-  {percent: 100, code: 'finalBreak.claim(100);', requiredEquals: 15, displayOnly: true},
+  {percent: 50, requiredEquals: 12, displayOnly: true},
+  {percent: 100, requiredEquals: 15, displayOnly: true},
 ];
 
 export const AGENT_SPECS = {
@@ -147,7 +156,7 @@ export function kitCodeSkillMarkdown(source) {
     '',
     'Use this skill only as an opt-in break reward. Never block, gate, delay, or nag about work.',
     '',
-    'KitCode is local-first. The CLI owns tracking, reward state, and break codes. The durable local state lives at:',
+    'KitCode is local-first. The CLI owns tracking and reward state. The durable local state lives at:',
     '',
     `    ${STATE_DISPLAY_PATH}`,
     '',
@@ -155,11 +164,11 @@ export function kitCodeSkillMarkdown(source) {
     '',
     `    ${LOCAL_SERVER_URL}`,
     '',
-    'When KitCode hook context says a reward is ready, briefly tell the user they can open:',
+    'When KitCode hook context says a milestone was reached, briefly tell the user they can open:',
     '',
     `    ${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 reward readiness. Treat that hook context as authoritative.',
+    '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.',
     '',
     '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.',
@@ -201,15 +210,9 @@ export function kitCodeSkillMarkdown(source) {
   ].join('\n');
 }
 
-function rewardTierLines() {
-  return KITCODE_REWARD_TIERS
-    .map((tier) => `- ${tier.percent}% reward tier: ${tier.code} after enough tracked time and ${tier.requiredEquals} counted = characters.`)
-    .join('\n');
-}
-
-function displayMilestoneLines() {
-  return KITCODE_DISPLAY_MILESTONES
-    .map((milestone) => `- ${milestone.percent}% dashboard milestone: ${milestone.code} is display-only unless the CLI later exposes it as a reward tier.`)
+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.`)
     .join('\n');
 }
 
@@ -260,16 +263,28 @@ export function assistantSetupPromptFor(source) {
   ].join('\n');
 }
 
+// What the staging setup prompt says of the tester build's diagnostics (src/diagnostics.mjs; the operator's decision 2 of
+// the voucher scheme's phase 4, 2026-10-01): that it sends them, where to, and what they never hold. In the tester's own
+// 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 setup prompt a staging dashboard copies for its invited testers (apps/web src/lib/staging-prompts.ts): the one
-// above, line for line, with three changes and no other. Step 2 installs the round's tester build, from the file the
-// tester downloaded from the staging site, which the dashboard's steps link (install 'file'), or, once a staging
-// version is published, from npm's `staging` tag (install 'npm'), and checks its version. Then, before step 3 turns
-// KitCode on, it stops a tracker an earlier build left running. And it holds no URL: the public docs the prompt above
-// links are not public yet (docs/lessons-learned.md F5). 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.
-export function stagingSetupPromptFor(source, {testerVersion, fileName, install}) {
-  if (install !== 'file' && install !== 'npm') {
-    throw new Error('stagingSetupPromptFor installs from a file or from npm: install must be \'file\' or \'npm\'.');
+// 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
+// no URL: the public docs the prompt above links are not public yet (docs/lessons-learned.md F5). And, since the voucher
+// scheme's phase 4, it says, under the round's line, that the tester build sends diagnostic logs to KitCode's staging
+// 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.
+//
+// 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
+// caller still asking for the file is told so rather than given npm in silence.
+export function stagingSetupPromptFor(source, options) {
+  const {testerVersion, ...others} = options;
+
+  if (Object.keys(others).length > 0) {
+    throw new Error(`stagingSetupPromptFor takes the tester build's version alone, and installs it from npm's staging tag: it does not know ${Object.keys(others).join(', ')}.`);
   }
 
   const lines = assistantSetupPromptFor(source).split('\n');
@@ -291,15 +306,10 @@ export function stagingSetupPromptFor(source, {testerVersion, fileName, install}
     throw new Error('stagingSetupPromptFor found no blank line after the public docs: 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.`);
+  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}`,
-    install === 'npm'
-      ? `with: ${CLI_STAGING_INSTALL_COMMAND}`
-      : `from the tester build I downloaded from KitCode's staging site, ${fileName}. Look for it in my Downloads folder, and if it is not there, ask me where it is. In the folder that holds it, run: npm install -g ./${fileName}`,
-  );
+  lines[installLine] = lines[installLine].replace(`with: ${CLI_GLOBAL_INSTALL_COMMAND}`, `with: ${CLI_STAGING_INSTALL_COMMAND}`);
 
   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(
@@ -341,11 +351,10 @@ export function setupPromptFor(source, options = {}) {
     `- The web dashboard reads local tracking and reward data from that server.`,
     `- Tracking and reward state is stored in: ${STATE_DISPLAY_PATH}`,
     '- Git Mode tracks commit totals and source-change batches; Vibe Mode tracks the same source-change batches without git metadata.',
-    '- The CLI/package is the source of truth for tracking, reward eligibility, which break codes were shown, and hook output.',
+    '- The CLI/package is the source of truth for tracking, the milestones reached, and hook output.',
     '',
     'Reward model:',
-    rewardTierLines(),
-    displayMilestoneLines(),
+    milestoneLines(),
     '- Do not reimplement reward calculations manually. Use KitCode CLI output and state.',
     '',
     'Required checks:',

package/src/onboarding-electron.mjs

@@ -4,6 +4,7 @@ import {app, BrowserWindow, dialog, ipcMain, nativeTheme} from 'electron';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {describeProjects, listProjectRecords, registerNewProjects, removeProject, resolveInitialProjectSuggestion} from './runtime.mjs';
+import {diagnosticsEnabled, readInvitedEmail, setInvitedEmail} from './diagnostics.mjs';
 import {DASHBOARD_URL} from './integration-spec.mjs';
 import {onboardingPreferences, saveOnboardingPreferences, STORE_DIR} from './store.mjs';
 import {resolveSetupPlatform} from './onboarding-platform.mjs';
@@ -154,6 +155,8 @@ app.whenReady().then(() => {
       ...onboardingPreferences(),
       projects: listProjectRecords(),
       suggestedProjects: initialSuggestedProjects(),
+      // A tester build's: the email the tester gave before, if any (src/diagnostics.mjs).
+      ...(diagnosticsEnabled() ? {invitedEmail: readInvitedEmail()} : {}),
     };
   });
   ipcMain.handle('kitcode:onboarding-select-folders', async (event) => {
@@ -164,6 +167,11 @@ app.whenReady().then(() => {
   });
   ipcMain.handle('kitcode:onboarding-submit', async (event, input) => {
     if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.'};
+    // A tester build's invited email, kept outside state.json, before anything else is saved; one that is not an address is
+    // asked for again, and nothing is saved.
+    if (diagnosticsEnabled() && typeof input?.invitedEmail === 'string' && !setInvitedEmail(input.invitedEmail).ok) {
+      return {ok: false, error: 'That email address does not look right: check it, or leave it empty.'};
+    }
     const folders = validFolders(input?.folders);
     if (!folders.length && !listProjectRecords().length) return {ok: false, error: 'Add at least one readable project folder.'};
     try { registerNewProjects(folders); } catch { return {ok: false, error: 'KitCode could not register one of those folders.'}; }

package/src/onboarding-window.mjs

@@ -1,3 +1,4 @@
+import {diagnosticsEnabled} from './diagnostics.mjs';
 import {
   renderPlatformChrome,
   resolveSetupPlatform,
@@ -5,7 +6,11 @@ import {
 } from './onboarding-platform.mjs';
 import {contentSecurityPolicy, fontFaces} from './window-page.mjs';
 
-export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
+// `diagnostics`: whether this is a tester build (src/diagnostics.mjs), unless a test says. Then, and only then, Welcome says
+// that the build sends diagnostic logs to KitCode's staging server, and what they never hold, and asks, optionally, for the
+// email the tester was invited with, so that staff can find their logs by it. Without it the page is as it was, byte for
+// byte.
+export function renderOnboardingWindow(platform = resolveSetupPlatform(), {diagnostics = diagnosticsEnabled()} = {}) {
   const theme = setupPlatformTheme(platform);
   // The page's one stylesheet and one script, kept apart so that its policy allows exactly them.
   const style = `
@@ -460,7 +465,28 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
     .status-text[data-state="success"] { color: var(--red-color); }
 
     .keyboard-hint.status-shortcuts { color: var(--white-text); }
-  `;
+${diagnostics ? `
+    /* With a third step the steps outgrow the panel at the window's own 960 x 640: the projects step must not shrink, as it
+       does alone to fill the panel, or its list and + ADD PROJECTS spill under the diagnostics step, whose email field then
+       takes their clicks (found 2026-10-02). The panel scrolls instead, as its rail expects. */
+    .projects-step { flex: 0 0 auto; }
+
+    .diagnostics-step p { color: var(--white-text); font-size: 10px; line-height: 1.5; margin-bottom: 10px; max-width: 560px; }
+
+    .diagnostics-step label { display: block; color: var(--grey-text); font-size: 10px; margin-bottom: 6px; }
+
+    .diagnostics-step input {
+      width: 100%;
+      max-width: 360px;
+      padding: 7px 9px;
+      background: transparent;
+      color: var(--white-text);
+      border: 1px dashed var(--grey-border);
+      -webkit-app-region: no-drag;
+    }
+
+    .diagnostics-step input:focus-visible { outline: none; border-color: var(--red-color); }
+` : ''}  `;
   const script = `
     const bridge = window.kitcodeOnboarding;
     const projectList = document.getElementById('projectList');
@@ -472,7 +498,8 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
     const setupContent = document.getElementById('setupContent');
     const railItems = [...document.querySelectorAll('.rail-item')];
     const stepSections = [...document.querySelectorAll('[data-setup-step]')];
-    const SAVE_LABEL = '+ SAVE AND OPEN KITCODE ->';
+    const SAVE_LABEL = '+ SAVE AND OPEN KITCODE ->';${diagnostics ? `
+    const invitedEmail = document.getElementById('invitedEmail');` : ''}
     const FOLDER_ICON = '<svg class="dropzone-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"></path></svg>';
     let persistedProjects = [];
     let pendingProjects = [];
@@ -713,7 +740,8 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
         const result = await bridge.submit({
           folders: pendingProjects.map((project) => project.repoRoot),
           autoTrack,
-          companionView,
+          companionView,${diagnostics ? `
+          invitedEmail: invitedEmail.value,` : ''}
         });
 
         if (Array.isArray(result.projects)) {
@@ -777,7 +805,8 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
           suggestedCount += 1;
         }
 
-        document.querySelector('input[name="autoTrack"][value="' + (state.autoTrack === false ? 'no' : 'yes') + '"]').checked = true;
+        document.querySelector('input[name="autoTrack"][value="' + (state.autoTrack === false ? 'no' : 'yes') + '"]').checked = true;${diagnostics ? `
+        invitedEmail.value = typeof state.invitedEmail === 'string' ? state.invitedEmail : '';` : ''}
         document.querySelectorAll('.option-group').forEach(syncOptionGroup);
         renderProjects();
 
@@ -826,7 +855,12 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
           <div class="rail-item" data-step="projects" data-testid="setup-rail-projects">
             <span class="rail-badge tech-box-red">02</span>
             <span class="rail-label">PROJECTS</span>
-          </div>
+          </div>${diagnostics ? `
+          <div class="step-connector" aria-hidden="true"></div>
+          <div class="rail-item" data-step="diagnostics" data-testid="setup-rail-diagnostics">
+            <span class="rail-badge tech-box-red">03</span>
+            <span class="rail-label">DIAGNOSTICS</span>
+          </div>` : ''}
         </aside>
         <div class="content">
           <fieldset class="step" id="trackingStep" data-setup-step="tracking">
@@ -852,7 +886,13 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
               <button class="terminal-button tech-box-red" id="pickFolders" type="button" data-testid="add-projects">+ ADD PROJECTS</button>
               <p class="hint">Existing files become the baseline.<br>Source and diffs stay local.</p>
             </div>
-          </section>
+          </section>${diagnostics ? `
+          <section class="step diagnostics-step" aria-labelledby="diagnosticsTitle" data-setup-step="diagnostics" data-testid="setup-diagnostics">
+            <h2 class="section-title" id="diagnosticsTitle">This test build sends diagnostic logs</h2>
+            <p>This test build of KitCode sends diagnostic logs to KitCode’s staging server: KitCode’s own events and errors, such as the tracker starting or a hook failing, so that a problem you meet can be traced without asking you for it. They never hold your code, your files, your prompts or your project names.</p>
+            <label for="invitedEmail">The email address you were invited with, optional: staff find your logs by it.</label>
+            <input id="invitedEmail" name="invitedEmail" type="email" autocomplete="email" maxlength="254" spellcheck="false" data-testid="invited-email">
+          </section>` : ''}
         </div>
       </div>
       <div class="dashed-divider section-divider" aria-hidden="true">==================================================================================================================================================================================================</div>

package/src/reward.mjs

@@ -3,7 +3,7 @@ import {equalsLedgerFrom, storedEqualsLedger} from './equals-ledger.mjs';
 import {focusTimeFrom} from './focus-clock.mjs';
 import {nextBreakReminder} from './next-break-reminder.mjs';
 import {KITCODE_DISPLAY_MILESTONES, KITCODE_REWARD_TIERS} from './integration-spec.mjs';
-import {loadState, updateState, withStateLock} from './store.mjs';
+import {loadState, updateState} from './store.mjs';
 
 // The focus time the 100 % milestone needs, fixed (operator decision Q5, 2026-09-25; docs/reward-rules.md
 // §3). Until then it was a setting, down to 1 s: --reward-seconds, KITCODE_REWARD_SECONDS, and
@@ -147,7 +147,6 @@ export function buildRewardSummary({earnedSeconds, totalEquals, ledger}) {
     const redeemed = Boolean(record?.redeemed_at);
 
     return {
-      code: tier.code,
       percent: tier.percent,
       requiredEquals: tier.requiredEquals,
       requiredSeconds: requiredTimeSeconds,
@@ -174,7 +173,6 @@ export function buildRewardSummary({earnedSeconds, totalEquals, ledger}) {
       const unlocked = timeReached && equalsReached;
 
       return {
-        code: tier?.code ?? milestone.code,
         percent: milestone.percent,
         requiredEquals: milestone.requiredEquals,
         requiredSeconds: requiredTimeSeconds,
@@ -225,44 +223,9 @@ function saveTierRecords(changes) {
   });
 }
 
-export function redeemReadyTiers(percent = null) {
-  const requestedPercent = percent === null ? null : normalizeTierPercent(percent);
-
-  if (percent !== null && !requestedPercent) {
-    return {redeemed: [], skipped: [], reward: getDiskRewardSummary()};
-  }
-
-  // Readiness is checked and the redeem recorded under one lock, so a tier is redeemed once.
-  return withStateLock(() => {
-    const reward = getDiskRewardSummary();
-    const now = new Date().toISOString();
-    const redeemed = [];
-    const skipped = [];
-
-    for (const tier of reward.tiers) {
-      if (requestedPercent && tier.percent !== requestedPercent) {
-        continue;
-      }
-
-      if (tier.status !== 'ready') {
-        skipped.push(tier);
-        continue;
-      }
-
-      redeemed.push({...tier, redeemed: true, redeemedAt: now, status: 'redeemed'});
-    }
-
-    if (redeemed.length > 0) {
-      saveTierRecords(redeemed.map((tier) => [tier.percent, (record) => ({...record, redeemed_at: now})]));
-    }
-
-    return {
-      redeemed,
-      skipped,
-      reward: getDiskRewardSummary(),
-    };
-  });
-}
+// Since 2026-10-01 nothing records a code as shown (the operator's decision 6: the break codes are gone). A tier whose
+// code an earlier version recorded as shown keeps its redeemed_at, and so its status, `redeemed`: it was reached, and
+// the record says so (docs/reward-rules.md §7).
 
 export function markTiersAnnounced(source, tiers) {
   const normalizedSource = normalizeSource(source);

package/src/runtime.mjs

@@ -787,8 +787,10 @@ function enqueue(runtime, projectId, run, job) {
 }
 
 // What is wrong with the tracker, by fixed code (the prompt hook turns each code into fixed words,
-// so nothing from a file reaches the agent): the projects affected, and since when.
-function reportProblem(runtime, code, projectId, message) {
+// so nothing from a file reaches the agent): the projects affected, and since when. `onProblem` hears of each project's
+// problem raised and cleared, with the error that raised it where there is one: a tester build's diagnostics
+// (src/diagnostics.mjs) record it, by the code, an opaque reference to the project and the error's code alone.
+function reportProblem(runtime, code, projectId, message, error = null) {
   const problem = runtime.problems.get(code) ?? {since: new Date().toISOString(), projects: new Set()};
 
   if (problem.projects.has(projectId)) {
@@ -798,6 +800,7 @@ function reportProblem(runtime, code, projectId, message) {
   problem.projects.add(projectId);
   runtime.problems.set(code, problem);
   runtime.log.warn(message);
+  runtime.watcherOptions?.onProblem?.({code, projectId, state: 'raised', error});
   runtime.watcherOptions?.onStatus?.(trackerStatus(runtime));
 }
 
@@ -813,6 +816,7 @@ function clearProblem(runtime, code, projectId) {
   }
 
   runtime.log.info(`${code} cleared for ${runtime.state.projects[projectId]?.repoRoot ?? projectId}`);
+  runtime.watcherOptions?.onProblem?.({code, projectId, state: 'cleared', error: null});
   runtime.watcherOptions?.onStatus?.(trackerStatus(runtime));
 }
 
@@ -837,7 +841,7 @@ function scanFailed(runtime, projectId, error) {
   // stays as it is, and the next scan tries again.
   const root = runtime.state.projects[projectId]?.repoRoot ?? projectId;
   const missing = error?.code === 'ENOENT' || error?.code === 'ENOTDIR';
-  reportProblem(runtime, missing ? 'project-missing' : 'scan-failed', projectId, `Scanning ${root} failed (${error?.code ?? 'error'}: ${error?.message ?? error}); its snapshot is kept, and nothing in it is counted until a scan succeeds.`);
+  reportProblem(runtime, missing ? 'project-missing' : 'scan-failed', projectId, `Scanning ${root} failed (${error?.code ?? 'error'}: ${error?.message ?? error}); its snapshot is kept, and nothing in it is counted until a scan succeeds.`, error);
 }
 
 // A Git project whose index stayed locked through a scan (index.lock, git.mjs gitArrival 'locked'): the
@@ -855,6 +859,23 @@ function noteGitLock(runtime, projectId, read) {
   reportProblem(runtime, 'git-locked', projectId, `The git index of ${root} has stayed locked (index.lock) through a scan: its scans are baselines, so nothing in it is counted until the lock goes. A git command that crashed can leave that file behind.`);
 }
 
+// A Git project in which git shows an operation waiting for the user through a scan (a merge, a rebase, a
+// cherry-pick, a revert, am or a squash merge; git.mjs gitArrival 'waiting'): the scan was a baseline, so
+// nothing in the project counts until the operation is finished or aborted. Said as a problem, in fixed
+// words, and cleared, as a lock is (noteGitLock); the log names the files git left. Until 2026-10-01
+// nothing said so, and a REBASE_HEAD that a finished rebase left behind made every scan of a project a
+// baseline for hours (docs/lessons-learned.md F22).
+function noteGitWaiting(runtime, projectId, read) {
+  if (read.baseline !== 'waiting') {
+    clearProblem(runtime, 'git-unfinished', projectId);
+    return;
+  }
+
+  const root = runtime.state.projects[projectId]?.repoRoot ?? projectId;
+  const files = Array.isArray(read.gitWaiting) ? read.gitWaiting.join(', ') : 'unknown';
+  reportProblem(runtime, 'git-unfinished', projectId, `Git shows an unfinished operation in ${root} (${files}): its scans are baselines, so nothing in it is counted until the operation is finished or aborted.`);
+}
+
 // Folds a read into state.json and follows it in the tracker's copy. `activityAt` says, from what the
 // fold changed, when the project was active, or null when it was not: activity is decided by the fold
 // that counted the change, never before it. When the lock stays busy, the same read is folded a little
@@ -921,6 +942,7 @@ function queueFullScan(runtime, projectId, reason) {
     const base = snapshotOf(project) ?? emptySnapshot();
     const read = await runtime.scanner.read({root: project.repoRoot, sourceType: project.sourceType, since: base.git});
     noteGitLock(runtime, projectId, read);
+    noteGitWaiting(runtime, projectId, read);
     applyRead(runtime, projectId, run, read, base, (result) => (reason !== 'start' && changedByUser(read, result) ? Date.now() : null));
   });
 }
@@ -943,6 +965,7 @@ async function scanChangedPaths(runtime, projectId, run, batch) {
   const read = await runtime.scanner.read({root: project.repoRoot, sourceType: project.sourceType, changedPaths: [...batch.keys()], since: base.git});
   const firstEvents = new Map([...batch].map(([fileName, at]) => [relativeTo(project.repoRoot, fileName), at]));
   noteGitLock(runtime, projectId, read);
+  noteGitWaiting(runtime, projectId, read);
 
   applyRead(runtime, projectId, run, read, base, (result) => {
     if (!changedByUser(read, result)) {
@@ -1002,12 +1025,12 @@ function watchFailed(runtime, projectId, run, error) {
   const root = runtime.state.projects[projectId]?.repoRoot ?? projectId;
 
   if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
-    reportProblem(runtime, 'project-missing', projectId, `Watching ${root} failed (${error.code}: ${error.message}): the folder is gone, so nothing in it is counted.`);
+    reportProblem(runtime, 'project-missing', projectId, `Watching ${root} failed (${error.code}: ${error.message}): the folder is gone, so nothing in it is counted.`, error);
     return;
   }
 
   run.poll = setInterval(() => queueFullScan(runtime, projectId, 'poll'), POLL_INTERVAL_MS);
-  reportProblem(runtime, 'watch-failed', projectId, `Watching ${root} failed (${error?.code ?? 'error'}: ${error?.message ?? error}); polling it every ${POLL_INTERVAL_MS / 1000} s instead.`);
+  reportProblem(runtime, 'watch-failed', projectId, `Watching ${root} failed (${error?.code ?? 'error'}: ${error?.message ?? error}); polling it every ${POLL_INTERVAL_MS / 1000} s instead.`, error);
 }
 
 function watchProject(runtime, projectId, run) {
@@ -1251,15 +1274,9 @@ export function buildSummary(runtime) {
   };
 }
 
-// The ledger changed on disk (a redeem, say): read it again for the next summary.
-export function refreshRuntimeLedger(runtime) {
-  if (runtime.ledger) {
-    runtime.ledger = loadEqualsLedger();
-  }
-}
-
 // Starts the tracker's work. `options.log` records what goes wrong; `options.onStatus` hears how the
-// tracker is doing whenever that changes, and after every save.
+// tracker is doing whenever that changes, and after every save; `options.onProblem`, each project's problem as it is raised
+// and cleared (reportProblem).
 export function startWatchers(runtime, options = {}) {
   runtime.watcherOptions = options;
   runtime.log = options.log ?? SILENT_LOG;