@kitkat-vn/kitcode 0.2.0-staging.3

package/src/integration-installers.mjs

@@ -0,0 +1,28 @@
+import {hookStatus, installHook, uninstallHook} from './hook-installers.mjs';
+import {installRunner, runnerStatus} from './runner-installer.mjs';
+import {installSkill, skillStatus, uninstallSkill} from './skill-installer.mjs';
+
+export function installIntegration(source) {
+  const runner = installRunner();
+
+  return {
+    runner,
+    hook: installHook(source),
+    skill: installSkill(source),
+  };
+}
+
+export function uninstallIntegration(source) {
+  return {
+    hook: uninstallHook(source),
+    skill: uninstallSkill(source),
+  };
+}
+
+export function integrationStatus(source) {
+  return {
+    runner: runnerStatus(),
+    hook: hookStatus(source),
+    skill: skillStatus(source),
+  };
+}

package/src/integration-spec.mjs

@@ -0,0 +1,398 @@
+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).
+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/";
+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('/')}`;
+
+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},
+];
+
+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},
+];
+
+export const AGENT_SPECS = {
+  codex: {
+    source: 'codex',
+    agentName: 'Codex',
+    setupCommand: `${CLI_GLOBAL_COMMAND} codex on`,
+    statusCommand: `${CLI_GLOBAL_COMMAND} codex status`,
+    offCommand: `${CLI_GLOBAL_COMMAND} codex off`,
+    skillPathParts: ['.codex', 'skills', 'kitcode', 'SKILL.md'],
+    hookConfigPathParts: ['.codex', 'hooks.json'],
+    hookEventName: 'UserPromptSubmit',
+  },
+  claude: {
+    source: 'claude',
+    agentName: 'Claude',
+    setupCommand: `${CLI_GLOBAL_COMMAND} claude on`,
+    statusCommand: `${CLI_GLOBAL_COMMAND} claude status`,
+    offCommand: `${CLI_GLOBAL_COMMAND} claude off`,
+    skillPathParts: ['.claude', 'skills', 'kitcode', 'SKILL.md'],
+    hookConfigPathParts: ['.claude', 'settings.json'],
+    hookEventName: 'UserPromptSubmit',
+  },
+};
+
+export function kitCodeCommand(command = '') {
+  return command ? `${CLI_PACKAGE_COMMAND} ${command}` : CLI_PACKAGE_COMMAND;
+}
+
+export function globalKitCodeCommand(command = '') {
+  return command ? `${CLI_GLOBAL_COMMAND} ${command}` : CLI_GLOBAL_COMMAND;
+}
+
+export function sourceConfig(source) {
+  const config = AGENT_SPECS[source];
+
+  if (!config) {
+    throw new Error(`Unsupported KitCode integration source: ${source}`);
+  }
+
+  return config;
+}
+
+export function displayHomePath(pathParts) {
+  return `~/${pathParts.join('/')}`;
+}
+
+export function shellQuote(value) {
+  const text = String(value);
+
+  if (/^[A-Za-z0-9_./:@%+=,~-]+$/.test(text)) {
+    return text;
+  }
+
+  return `'${text.replaceAll("'", "'\"'\"'")}'`;
+}
+
+// On Windows, Claude Code runs a hook's command in Git Bash, or in PowerShell when Git Bash is not
+// installed, and Codex runs it in PowerShell (docs/security.md, "The prompt hook on Windows"). A command
+// a shell cannot parse fails there, and one bash cannot parse exits 2, which blocks the user's prompt and
+// erases it. So on Windows the command is one both shells read the same way: `node`, which both find on
+// PATH, then the runner module beside the runner (runner-installer.mjs), as one quoted argument with
+// forward slashes, which both take in a path and neither reads as an escape. It is in double quotes,
+// unless the path holds $ or a backtick, which both expand there, or a quote PowerShell ends them with;
+// then in single quotes, in which neither expands anything, unless the path also holds a quote either
+// shell ends those with. Such a path keeps the command macOS and Linux have, which bash parses whatever
+// the path, and so never exits 2 for.
+const DOUBLE_QUOTED_UNSAFE = /[$`"“”„]/u;
+const SINGLE_QUOTED_UNSAFE = /['‘’‚‛]/u;
+
+function windowsRunnerArgument(runnerPath) {
+  const runnerModule = `${runnerPath.replaceAll('\\', '/')}.mjs`;
+
+  if (!DOUBLE_QUOTED_UNSAFE.test(runnerModule)) {
+    return `"${runnerModule}"`;
+  }
+
+  return SINGLE_QUOTED_UNSAFE.test(runnerModule) ? null : `'${runnerModule}'`;
+}
+
+export function hookCommandFor(source, options = {}) {
+  sourceConfig(source);
+
+  const runnerPath = options.runnerPath ?? RUNNER_DISPLAY_PATH;
+  // globalThis: the dashboard bundles this file for its setup prompts, and a browser has no process.
+  const platform = options.platform ?? globalThis.process?.platform;
+  const windowsArgument = platform === 'win32' && options.runnerPath !== undefined ? windowsRunnerArgument(runnerPath) : null;
+
+  // Everywhere else, and in the display form the setup prompts show, the command KitCode has always
+  // written: Codex makes its users approve a hook again whenever its command changes (docs/security.md).
+  return windowsArgument === null
+    ? `${shellQuote(runnerPath)} hook prompt --source ${source}`
+    : `node ${windowsArgument} hook prompt --source ${source}`;
+}
+
+export function legacyHookCommandFor(source) {
+  sourceConfig(source);
+
+  return `kitcode hook prompt --source ${source}`;
+}
+
+export function hookConfigFor(source, options = {}) {
+  return {
+    type: 'command',
+    command: hookCommandFor(source, options),
+    timeout: 5,
+  };
+}
+
+const REMOTE_SESSION_REDIRECT = {
+  codex: 'Run commands on my local machine shell, not a remote sandbox. If you only have a remote session, tell me to paste this prompt into Codex Task or a Codex project chat instead.',
+  claude: 'Run commands on my local machine shell, not a remote sandbox. If you only have a remote session, tell me to paste this prompt into Claude Code instead.',
+};
+
+export function kitCodeSkillMarkdown(source) {
+  const config = sourceConfig(source);
+  const skillPath = displayHomePath(config.skillPathParts);
+
+  return [
+    '---',
+    'name: kitcode',
+    `description: "KitKat Have-a-break -- local-first reward companion for ${config.agentName}. Use for KitCode setup, tracker status, rewards, and dashboard requests. Use KitCode CLI and hook context as the source of truth; do not calculate or mutate rewards yourself."`,
+    '---',
+    '',
+    '# KitCode',
+    '',
+    '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:',
+    '',
+    `    ${STATE_DISPLAY_PATH}`,
+    '',
+    'The local dashboard reads from the KitCode server at:',
+    '',
+    `    ${LOCAL_SERVER_URL}`,
+    '',
+    'When KitCode hook context says a reward is ready, 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.',
+    '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.',
+    '',
+    '## Chat actions',
+    '',
+    'When the user directly asks to open a KitCode surface, run the matching command without asking for confirmation. These actions are opt-in and local:',
+    '',
+    `- Open dashboard — for “mở dashboard”, “xem tiến độ”, “show my KitCode progress”, or equivalent: \`${RUNNER_DISPLAY_PATH} dashboard\`.`,
+    '',
+    'When the user starts a message with `/kitcode`, treat it as a KitCode management shortcut and run the matching local CLI command:',
+    '',
+    `- \`/kitcode track\` or \`/kitcode start\` — run \`${RUNNER_DISPLAY_PATH} track\`.`,
+    `- \`/kitcode summary\`, \`/kitcode progress\`, or \`/kitcode status\` — run \`${RUNNER_DISPLAY_PATH} summary\` or \`${RUNNER_DISPLAY_PATH} status\`.`,
+    `- \`/kitcode award\`, \`/kitcode awards\`, or \`/kitcode rewards\` — run \`${RUNNER_DISPLAY_PATH} awards\`.`,
+    `- \`/kitcode dashboard\` — run \`${RUNNER_DISPLAY_PATH} dashboard\`.`,
+    `- \`/kitcode setup\` — run \`${RUNNER_DISPLAY_PATH} setup\`.`,
+    '',
+    'If the tracker is not running, run the requested command first and report its CLI error; only start it with the user’s explicit request to start tracking.',
+    '',
+    'Useful checks:',
+    '',
+    `    ${RUNNER_DISPLAY_PATH} ${source} status`,
+    `    ${RUNNER_DISPLAY_PATH} track`,
+    `    ${RUNNER_DISPLAY_PATH} status`,
+    `    ${RUNNER_DISPLAY_PATH} summary`,
+    `    ${RUNNER_DISPLAY_PATH} awards`,
+    `    ${RUNNER_DISPLAY_PATH} dashboard`,
+    `    ${RUNNER_DISPLAY_PATH} list`,
+    '',
+    'Uninstall:',
+    '',
+    `    ${globalKitCodeCommand('uninstall')}`,
+    '',
+    `Or turn off only this integration: ${config.offCommand}`,
+    '',
+    `This skill is installed at ${skillPath}.`,
+    '',
+  ].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.`)
+    .join('\n');
+}
+
+export function assistantSetupPromptFor(source) {
+  const config = sourceConfig(source);
+
+  return [
+    'Set up KitCode on my local computer.',
+    '',
+    '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.',
+    '',
+    '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}`,
+    '- 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).`,
+    `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.',
+    `- This installs a KitCode skill plus a UserPromptSubmit hook for ${config.agentName}. The hook should run after each submitted prompt, fail open, and add compact KitCode context when tracking is active.`,
+    `4. Verify integration with: ${config.statusCommand}`,
+    `- Do NOT run ${globalKitCodeCommand('setup')} if step 3 printed "Opening KitCode Welcome..." and did not report a Welcome launch failure. That means Welcome is already open.`,
+    `- Run ${globalKitCodeCommand('setup')} only once, and only if step 3 did not print "Opening KitCode Welcome..." and I confirm Welcome never appeared.`,
+    '- If Welcome launch fails (Electron missing or exits immediately), report the exact error. Do NOT tell me Welcome is open, and do NOT ask me to complete a window that never appeared.',
+    '- Never open Welcome twice. If unsure whether Welcome opened, ask me before running setup.',
+    '- Welcome should open as a single stable desktop window without flashing a terminal or other KitCode surface first.',
+    '',
+    'Do NOT during Phase 1:',
+    `- Do NOT run ${globalKitCodeCommand('add')} or ${globalKitCodeCommand('track')}.`,
+    '- Do NOT manually edit KitCode state or calculate rewards.',
+    '',
+    'Phase 2 — human setup (required for success):',
+    '- Only after Welcome actually opened: I must complete the KitCode Welcome window: confirm project folder(s) and background tracking YES/NO.',
+    '- In a project chat, Welcome should already list the current project folder. Outside a project chat, I add folder(s) manually.',
+    '- Setup is not complete until I save Welcome with at least one project folder.',
+    '',
+    'Actually execute the commands. Do not stop after printing instructions for me to run in another terminal.',
+    '- If a command fails, report the exact failure after attempting it and continue with any safe local checks that can unblock setup.',
+    '',
+    'After Phase 1, tell me to finish Welcome only if Welcome actually opened. Only then is KitCode ready to track.',
+  ].join('\n');
+}
+
+// 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\'.');
+  }
+
+  const lines = assistantSetupPromptFor(source).split('\n');
+  const onlyLine = (matches, what) => {
+    const found = lines.flatMap((line, index) => (matches(line) ? [index] : []));
+
+    if (found.length !== 1) {
+      throw new Error(`stagingSetupPromptFor found ${what} ${found.length} times in the setup prompt, not once: assistantSetupPromptFor changed, and stagingSetupPromptFor must follow it.`);
+    }
+
+    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);
+
+  if (docsEnd === -1) {
+    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.`);
+
+  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}`,
+  );
+
+  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.`,
+  );
+
+  return lines.join('\n');
+}
+
+export function setupPromptFor(source, options = {}) {
+  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);
+
+  return [
+    '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.`,
+    '- This works in any chat context. Do not require repo context or infer a project path to begin.',
+    '- Do not assume a fixed operating system. Infer paths from the environment.',
+    '- If the OS or home directory cannot be inferred, ask one short question before editing.',
+    '- Keep the setup local-first, opt-in, and non-blocking.',
+    '',
+    'What KitCode does:',
+    `- Project folders are registered in the KitCode Welcome window or later with: ${globalKitCodeCommand('add')}`,
+    `- Background tracking starts from Welcome or later with: ${globalKitCodeCommand('track')}`,
+    `- During initial setup, do NOT run ${globalKitCodeCommand('add')} or ${globalKitCodeCommand('track')}.`,
+    `- The tracker serves local data at: ${LOCAL_SERVER_URL}`,
+    `- 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.',
+    '',
+    'Reward model:',
+    rewardTierLines(),
+    displayMilestoneLines(),
+    '- Do not reimplement reward calculations manually. Use KitCode CLI output and state.',
+    '',
+    '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}`,
+    '- 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).`,
+    '',
+    `${config.agentName} setup:`,
+    `- Prefer the CLI installer from the project directory in a project chat: ${config.setupCommand}`,
+    `- When onboarding is incomplete, ${config.setupCommand} opens Welcome and pre-adds the current project folder from the working directory.`,
+    `- The installer creates or updates the ${config.agentName} skill file at: ${displayHomePath(config.skillPathParts)}`,
+    `- The installer creates or updates the ${config.hookEventName} hook config at: ${displayHomePath(config.hookConfigPathParts)}`,
+    `- The installer creates a durable local runner at: ${RUNNER_DISPLAY_PATH}`,
+    `- The hook command should be: ${hookCommand}`,
+    '- The hook must fail open and must never block prompts.',
+    `- After ${config.setupCommand}, the KitCode Welcome window should open when onboarding is incomplete.`,
+    `- If Welcome launch fails (Electron missing or exits immediately), report the exact error and do NOT ask me to complete a window that never appeared.`,
+    `- If Welcome did not open and there was no clear launch failure message, run: ${globalKitCodeCommand('setup')}`,
+    '- Setup is not complete until I save Welcome with at least one project folder.',
+    '',
+    'Expected hook command object:',
+    JSON.stringify(expectedHook, null, 2),
+    '',
+    `SKILL.md content for ${displayHomePath(config.skillPathParts)}:`,
+    '----- BEGIN SKILL.md -----',
+    kitCodeSkillMarkdown(source),
+    '----- END SKILL.md -----',
+    '',
+    'How to check after setup:',
+    `- Integration status: ${config.statusCommand}`,
+    '- Finish KitCode Welcome only after it actually opened: choose project folder(s) and background tracking.',
+    `- After Welcome is saved, tracker and dashboard checks: ${globalKitCodeCommand('track')}`,
+    `- Dashboard: ${globalKitCodeCommand('dashboard')}`,
+    `- Added projects: ${globalKitCodeCommand('list')}`,
+    `- Compact progress: ${globalKitCodeCommand('summary')}`,
+    `- Reward and milestone readiness: ${globalKitCodeCommand('awards')}`,
+    `- Local state file: ${STATE_DISPLAY_PATH}`,
+    `- Dashboard: ${DASHBOARD_URL}`,
+    '',
+    'How to uninstall:',
+    `- Remove everything locally: ${globalKitCodeCommand('uninstall')}`,
+    `- Or turn off only this integration: ${config.offCommand}`,
+    '',
+    'Finish with a concise summary of files changed, commands run, and anything I should run next.',
+  ].join('\n');
+}

package/src/log-file.mjs

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// KitCode's own logs, ~/.kitcode/hook.log and tracker.log, are bounded. When a log reaches
+// LOG_MAX_BYTES, its last LOG_MAX_BYTES become <file>.1, replacing the one before, and the log starts
+// again: the two hold about twice that at most, even after a version that had no limit. They name
+// local paths, so they are private to their user.
+export const LOG_MAX_BYTES = 256 * 1024;
+const LOG_FILE_MODE = 0o600;
+
+function rotate(filePath, maxBytes) {
+  let size;
+
+  try {
+    size = fs.statSync(filePath).size;
+  } catch {
+    return;
+  }
+
+  if (size < maxBytes) {
+    return;
+  }
+
+  const tail = Buffer.alloc(maxBytes);
+  const fd = fs.openSync(filePath, 'r');
+  let length;
+
+  try {
+    length = fs.readSync(fd, tail, 0, maxBytes, size - maxBytes);
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  // From the first whole line on.
+  const kept = tail.subarray(0, length);
+  const firstLine = size > maxBytes ? kept.indexOf(0x0a) + 1 : 0;
+  fs.writeFileSync(`${filePath}.1`, kept.subarray(firstLine), {mode: LOG_FILE_MODE});
+  fs.chmodSync(`${filePath}.1`, LOG_FILE_MODE);
+  fs.rmSync(filePath, {force: true});
+}
+
+// Appends one line, stamped with the time. It never throws: a log that cannot be written must not
+// stop the prompt hook or the tracker.
+export function appendLogLine(filePath, text, {maxBytes = LOG_MAX_BYTES} = {}) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), {recursive: true});
+    rotate(filePath, maxBytes);
+    fs.appendFileSync(filePath, `${new Date().toISOString()} ${text}\n`, {mode: LOG_FILE_MODE});
+  } catch {
+    // Nothing else to do.
+  }
+}
+
+export function createLog(filePath, options) {
+  return {
+    info: (text) => appendLogLine(filePath, `info ${text}`, options),
+    warn: (text) => appendLogLine(filePath, `warn ${text}`, options),
+    error: (text) => appendLogLine(filePath, `error ${text}`, options),
+  };
+}

package/src/milestones-reached.mjs

@@ -0,0 +1,130 @@
+import {equalsLedgerFrom} from './equals-ledger.mjs';
+import {focusTimeFrom} from './focus-clock.mjs';
+import {buildRewardSummary, REWARD_MILESTONES} from './reward.mjs';
+
+// When each milestone first became ready (docs/reward-rules.md §6.1), for the claim bundle. Kept in
+// state.json, where the tracker writes the progress it belongs to, as `milestonesReached`:
+//
+//   {"recordingSince": "2026-09-25T09:15:00.004Z",
+//    "milestones": {"10": {"reachedBeforeRecording": true}, "50": {"reachedAt": "2026-09-25T11:03:27.918Z"}}}
+//
+// It is written where progress goes up, and nowhere else: the tracker's save, which moves the focus
+// clock, and the updates that credit = (runtime.mjs persistRuntimeState, foldScan, switchProjectRules).
+// Never by the prompt hook, which runs on every message a user sends; never by a redeem, a removal or a
+// load. An entry once written is never changed or removed: a rules switch, a re-baseline, a restart or
+// progress going down again leaves it where it is.
+//
+// 0.1.39 drops it when it rewrites the file (install-id.mjs says how). The next write of this version then
+// begins a new record, and a milestone reached by then is recorded as reached before recording began:
+// the time it was reached is lost, and none is made up.
+
+export const MILESTONE_PERCENTS = REWARD_MILESTONES.map((milestone) => milestone.percent);
+
+// 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);
+}
+
+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;
+}
+
+// A record as KitCode writes it: when it began, and its entries.
+function isRecord(record) {
+  return isObject(record) && isInstant(record.recordingSince) && isObject(record.milestones);
+}
+
+// The milestones reached by `state` now: every milestone up to the highest one that is ready or
+// redeemed. A milestone's targets are never below a lower one's, so a higher milestone ready means every
+// lower one was ready then too, even one that reads locked now: a redeemed tier keeps its status when
+// its = go down (docs/reward-rules.md §6, E8).
+function reachedNow(state) {
+  const ledger = equalsLedgerFrom(state);
+  const reward = buildRewardSummary({earnedSeconds: focusTimeFrom(state).activeSeconds, totalEquals: ledger.total_equals, ledger});
+  const highest = Math.max(0, ...reward.milestones.filter((milestone) => milestone.status !== 'locked').map((milestone) => milestone.percent));
+
+  return MILESTONE_PERCENTS.filter((percent) => percent <= highest);
+}
+
+// Records, in `stored`, each milestone first found reached: `stored` is the file's own object, inside
+// updateState, after the update has written the progress it is making. The first write of a KitCode that
+// keeps the record begins it, at `now`, and a milestone already reached then is recorded as reached
+// before recording began, with no time, since none is known. From then on, a milestone newly reached is
+// recorded at `now`. A record, or an entry, that is not what KitCode writes is left exactly as it is:
+// never repaired, never written over. `now` is the tracker's clock, which a test can move.
+export function noteMilestonesReached(stored, now = new Date(Date.now())) {
+  const record = stored.milestonesReached;
+
+  if (record !== undefined && !isRecord(record)) {
+    return;
+  }
+
+  const reached = reachedNow(stored);
+  const at = now.toISOString();
+
+  if (record === undefined) {
+    stored.milestonesReached = {
+      recordingSince: at,
+      milestones: Object.fromEntries(reached.map((percent) => [String(percent), {reachedBeforeRecording: true}])),
+    };
+    return;
+  }
+
+  for (const percent of reached) {
+    if (!Object.hasOwn(record.milestones, String(percent))) {
+      record.milestones[String(percent)] = {reachedAt: at};
+    }
+  }
+}
+
+// A milestone record that is not what KitCode writes. The claim bundle does not guess at it.
+export class MilestoneRecordError extends Error {
+  constructor(problem) {
+    super(`The record of when each milestone was reached, in state.json, ${problem}. KitCode has left it as it is.`);
+    this.name = 'MilestoneRecordError';
+  }
+}
+
+function entryFor(percent, record) {
+  const key = String(percent);
+
+  if (!Object.hasOwn(record.milestones, key)) {
+    return {percent, status: 'not-reached', reachedAt: null};
+  }
+
+  const entry = record.milestones[key];
+
+  if (isObject(entry) && entry.reachedBeforeRecording === true && entry.reachedAt === undefined) {
+    return {percent, status: 'reached-before-recording', reachedAt: null};
+  }
+
+  if (isObject(entry) && isInstant(entry.reachedAt) && entry.reachedBeforeRecording === undefined) {
+    return {percent, status: 'reached', reachedAt: entry.reachedAt};
+  }
+
+  throw new MilestoneRecordError(`holds an entry for ${percent} % that KitCode does not write`);
+}
+
+// The record as the claim bundle reports it: when it began, or null when it has not, and each
+// milestone's status and time, from 10 to 100 %. Reads only; a damaged record throws a
+// MilestoneRecordError.
+export function milestonesReachedFrom(state) {
+  const record = state.milestonesReached;
+
+  if (record === undefined) {
+    return {recordingSince: null, milestones: MILESTONE_PERCENTS.map((percent) => ({percent, status: 'not-reached', reachedAt: null}))};
+  }
+
+  if (!isRecord(record)) {
+    throw new MilestoneRecordError('is not the record KitCode writes');
+  }
+
+  return {recordingSince: record.recordingSince, milestones: MILESTONE_PERCENTS.map((percent) => entryFor(percent, record))};
+}