@kintsugi-ai/core 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Munkhin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @kintsugi-ai/core
+
+Core engine for [Kintsugi](https://github.com/Munkhin/kintsugi), the visual UX
+regression guard for AI coding agents.
+
+- **Capture** — headless Playwright replay of recorded flows (screenshots,
+  aria snapshots, optional video) via `captureCurrentState`.
+- **Compare** — pixel-diff (pixelmatch) per step with configurable thresholds;
+  large diffs are escalated to a classifier tier for intent analysis.
+- **Flow storage** — save/load/list/delete flows under `.kintsugi/flows/<name>/`
+  (`metadata.json`, `steps.json`, `screenshots/`, `aria/`).
+- **Classifier client** — hosted `POST /v1/classify` with self-hosted fallback.
+
+This is a library package; use it through the
+[`@kintsugi-ai/cli`](https://www.npmjs.com/package/@kintsugi-ai/cli) or the
+[MCP server](https://www.npmjs.com/package/@kintsugi-ai/mcp).

package/dist/agentConfig.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Stop-hook command registered with each agent. Defaults to the published npm
+ * package; set KINTSUGI_HOOK_COMMAND to override (e.g. "node /path/to/packages/hook/dist/index.js
+ * --event stop" for development).
+ */
+export declare function stopHookCommand(): string;
+/** Antigravity (agy): Stop entry under the kintsugi-visual-guard key in .agents/hooks.json. */
+export declare function writeAntigravityHook(projectDir: string): Promise<void>;
+/** Claude Code: Stop entry (and removal of legacy per-edit PostToolUse) in .claude/settings.json. */
+export declare function writeClaudeStopHook(projectDir: string): Promise<void>;
+/**
+ * Codex CLI: Stop entry in .codex/hooks.json — top-level `Stop` array (NOT the
+ * Claude settings `hooks.Stop` nesting; the VS Code writer shipped that wrong
+ * shape for a while — this module is now the single source of truth).
+ */
+export declare function writeCodexStopHook(projectDir: string): Promise<void>;
+//# sourceMappingURL=agentConfig.d.ts.map

package/dist/agentConfig.js

@@ -0,0 +1,91 @@
+/**
+ * Shared agent hook-config writer — the single source of truth for how the
+ * Stop hook is registered with Claude Code, Codex CLI, and Antigravity.
+ * Used by `kintsugi init` (CLI) and the VS Code extension's auto-setup, which
+ * previously carried diverging copies.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Stop-hook command registered with each agent. Defaults to the published npm
+ * package; set KINTSUGI_HOOK_COMMAND to override (e.g. "node /path/to/packages/hook/dist/index.js
+ * --event stop" for development).
+ */
+export function stopHookCommand() {
+    return process.env.KINTSUGI_HOOK_COMMAND?.trim() || 'npx -y @kintsugi-ai/hook --event stop';
+}
+/** Matches a registered hook entry that runs Kintsugi, in current or legacy form. */
+const KINTSUGI_HOOK_PATTERN = /kintsugi-hook|@kintsugi-ai\/hook/;
+async function readJsonIfExists(filePath) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, 'utf-8'));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        return {};
+    }
+}
+async function writeJson(filePath, data) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+/** Antigravity (agy): Stop entry under the kintsugi-visual-guard key in .agents/hooks.json. */
+export async function writeAntigravityHook(projectDir) {
+    const hooksPath = path.join(projectDir, '.agents', 'hooks.json');
+    const data = await readJsonIfExists(hooksPath);
+    data['kintsugi-visual-guard'] = {
+        Stop: [{ type: 'command', command: stopHookCommand() }],
+    };
+    await writeJson(hooksPath, data);
+}
+/** Claude Code: Stop entry (and removal of legacy per-edit PostToolUse) in .claude/settings.json. */
+export async function writeClaudeStopHook(projectDir) {
+    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+    const data = await readJsonIfExists(settingsPath);
+    if (!data.hooks)
+        data.hooks = {};
+    removeKintsugiHooks(data.hooks, 'PostToolUse');
+    // Always re-write the Stop entry so command overrides (KINTSUGI_HOOK_COMMAND)
+    // and upgrades from legacy `npx kintsugi-hook` entries take effect.
+    removeKintsugiHooks(data.hooks, 'Stop');
+    if (!Array.isArray(data.hooks.Stop))
+        data.hooks.Stop = [];
+    data.hooks.Stop.push({ hooks: [{ type: 'command', command: stopHookCommand() }] });
+    await writeJson(settingsPath, data);
+}
+/**
+ * Codex CLI: Stop entry in .codex/hooks.json — top-level `Stop` array (NOT the
+ * Claude settings `hooks.Stop` nesting; the VS Code writer shipped that wrong
+ * shape for a while — this module is now the single source of truth).
+ */
+export async function writeCodexStopHook(projectDir) {
+    const hooksPath = path.join(projectDir, '.codex', 'hooks.json');
+    const data = await readJsonIfExists(hooksPath);
+    removeKintsugiHooks(data, 'PostToolUse');
+    removeKintsugiHooks(data, 'Stop');
+    if (!Array.isArray(data.Stop))
+        data.Stop = [];
+    data.Stop.push({ hooks: [{ type: 'command', command: stopHookCommand() }] });
+    await writeJson(hooksPath, data);
+}
+/**
+ * Removes kintsugi hook entries registered under the given event name
+ * (e.g. legacy per-edit PostToolUse entries, or Stop entries that need a
+ * command refresh).
+ */
+function removeKintsugiHooks(hooks, eventName) {
+    if (!Array.isArray(hooks[eventName]))
+        return false;
+    const filtered = hooks[eventName].filter((h) => !KINTSUGI_HOOK_PATTERN.test(JSON.stringify(h)));
+    if (filtered.length === hooks[eventName].length)
+        return false;
+    if (filtered.length === 0) {
+        delete hooks[eventName];
+    }
+    else {
+        hooks[eventName] = filtered;
+    }
+    return true;
+}
+//# sourceMappingURL=agentConfig.js.map

package/dist/agentInstructions.d.ts

@@ -0,0 +1,11 @@
+export declare const INSTRUCTIONS_BEGIN = "<!-- kintsugi:begin -->";
+export declare const INSTRUCTIONS_END = "<!-- kintsugi:end -->";
+export declare function getCoverageInstructions(): string;
+/**
+ * Insert or refresh the marker block in one instruction file. Creates the
+ * file if missing; replaces only the content between the markers otherwise.
+ */
+export declare function injectInstructionsFile(filePath: string): Promise<void>;
+/** Inject the block into AGENTS.md and CLAUDE.md at the project root. */
+export declare function injectAgentInstructions(projectDir: string): Promise<void>;
+//# sourceMappingURL=agentInstructions.d.ts.map

package/dist/agentInstructions.js

@@ -0,0 +1,58 @@
+/**
+ * The persistent agent instruction block injected into AGENTS.md / CLAUDE.md
+ * at project root by `kintsugi init`. Marker-delimited so re-running init can
+ * update the block in place without touching anything else in the file.
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+export const INSTRUCTIONS_BEGIN = '<!-- kintsugi:begin -->';
+export const INSTRUCTIONS_END = '<!-- kintsugi:end -->';
+export function getCoverageInstructions() {
+    return `${INSTRUCTIONS_BEGIN}
+## UI regression coverage (Kintsugi)
+
+Recorded flows are replayed at the end of every agent turn to catch UI regressions.
+
+- When you build a NEW user-facing page, view, or feature, record a flow for it with the \`save_flow\` MCP tool (stable selectors, under 8 steps), pass the source files it covers in \`source_files\`, then call \`capture_baseline\`.
+- When you substantially change an existing flow's behavior, re-record that flow and refresh its baseline.
+- Do not record flows for trivial styling-only changes.
+${INSTRUCTIONS_END}`;
+}
+/**
+ * Insert or refresh the marker block in one instruction file. Creates the
+ * file if missing; replaces only the content between the markers otherwise.
+ */
+export async function injectInstructionsFile(filePath) {
+    const block = getCoverageInstructions();
+    let existing = '';
+    try {
+        existing = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        existing = '';
+    }
+    let next;
+    const beginIdx = existing.indexOf(INSTRUCTIONS_BEGIN);
+    if (beginIdx === -1) {
+        next = existing ? `${existing.replace(/\s*$/, '')}\n\n${block}\n` : `${block}\n`;
+    }
+    else {
+        const endIdx = existing.indexOf(INSTRUCTIONS_END, beginIdx);
+        if (endIdx === -1) {
+            // Corrupt marker (begin without end): append a fresh block after it.
+            next = `${existing.replace(/\s*$/, '')}\n\n${block}\n`;
+        }
+        else {
+            next = existing.slice(0, beginIdx) + block + existing.slice(endIdx + INSTRUCTIONS_END.length);
+        }
+    }
+    if (next !== existing) {
+        await fs.writeFile(filePath, next, 'utf-8');
+    }
+}
+/** Inject the block into AGENTS.md and CLAUDE.md at the project root. */
+export async function injectAgentInstructions(projectDir) {
+    await injectInstructionsFile(path.join(projectDir, 'AGENTS.md'));
+    await injectInstructionsFile(path.join(projectDir, 'CLAUDE.md'));
+}
+//# sourceMappingURL=agentInstructions.js.map

package/dist/auth.d.ts

@@ -8,6 +8,10 @@ type Logger = {
 export declare function computeDeviceHash(): string;
 /** Writes (or replaces) one KEY=VALUE line in ~/.kintsugi/.env, preserving other lines. */
 export declare function writeGlobalEnvValue(key: string, value: string): string;
+/** Removes one KEY=VALUE line from an env file (if present). */
+export declare function removeEnvValueAt(envPath: string, key: string): void;
+/** Removes the key from ~/.kintsugi/.env and <project>/.kintsugi/.env. */
+export declare function removeApiTokenEverywhere(tokenEnvVar: string, projectDir?: string): void;
 /**
  * Returns the hosted-API key, bootstrapping an anonymous free key (written to
  * ~/.kintsugi/.env) when none exists. Returns undefined on network failure —
@@ -27,8 +31,20 @@ export interface ApiAccountStatus {
     upgradeUrl?: string;
 }
 export declare function getAccountStatus(apiKey: string, endpoint: string, fetchImpl?: typeof fetch): Promise<ApiAccountStatus | undefined>;
+/**
+ * Deregisters a flow fingerprint server-side so deleted/renamed/rewritten
+ * flows stop occupying free-plan quota. Best-effort: self-hosted or offline
+ * setups return false and callers carry on — the server stays authoritative
+ * at classify time regardless.
+ */
+export declare function deregisterFlow(apiKey: string, endpoint: string, flowHash: string, fetchImpl?: typeof fetch): Promise<boolean>;
 /** Stripe Payment Link URL for the $29/mo Pro upgrade, or undefined when billing is unavailable. */
 export declare function createCheckoutUrl(apiKey: string, endpoint: string, fetchImpl?: typeof fetch): Promise<string | undefined>;
+/** Stripe Customer Portal URL (cancel/update card), or undefined when unavailable. */
+export declare function createPortalUrl(apiKey: string, endpoint: string, fetchImpl?: typeof fetch): Promise<{
+    url?: string;
+    error?: string;
+}>;
 /**
  * Polls account status until the plan becomes 'pro' (the Stripe webhook flips
  * it server-side shortly after payment) or the timeout elapses. Called from
@@ -41,6 +57,25 @@ export declare function waitForPlanUpgrade(apiKey: string, endpoint: string, opt
     shouldContinue?: () => boolean;
     onPoll?: (status: ApiAccountStatus | undefined) => void;
 }): Promise<ApiAccountStatus | undefined>;
+/**
+ * Polls account status until the plan becomes 'free' again (portal cancel →
+ * subscription.deleted webhook). Called from `kintsugi cancel`.
+ */
+export declare function waitForPlanDowngrade(apiKey: string, endpoint: string, options?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    shouldContinue?: () => boolean;
+    onPoll?: (status: ApiAccountStatus | undefined) => void;
+}): Promise<ApiAccountStatus | undefined>;
+/**
+ * Rotates the API key server-side: the account (plan, subscription, flow
+ * quota) is kept, the old key stops working. Returns the new raw key exactly
+ * once — write it where the next machine can read it before losing it.
+ */
+export declare function rotateApiKey(apiKey: string, endpoint: string, fetchImpl?: typeof fetch): Promise<string | undefined>;
+/** Deletes the account (key + flows + usage, subscription cancelled). */
+export declare function deleteAccount(apiKey: string, endpoint: string, fetchImpl?: typeof fetch): Promise<boolean>;
 /**
  * Shared classifier-context builder used by the hook, `kintsugi check`, and
  * the MCP server — one code path decides when classification is active.

package/dist/auth.js

@@ -7,6 +7,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { createHash } from 'node:crypto';
 import { resolveApiToken, globalKintsugiEnvPath } from './classifier.js';
+import { writeClassifierState } from './classifier-state.js';
 /** Stable per-machine fingerprint used to issue anonymous keys. */
 export function computeDeviceHash() {
     return createHash('sha256').update(`${os.hostname()}|${os.homedir()}`).digest('hex').slice(0, 32);
@@ -14,6 +15,30 @@ export function computeDeviceHash() {
 /** Writes (or replaces) one KEY=VALUE line in ~/.kintsugi/.env, preserving other lines. */
 export function writeGlobalEnvValue(key, value) {
     const envPath = globalKintsugiEnvPath();
+    writeEnvValueAt(envPath, key, value);
+    return envPath;
+}
+/** Removes one KEY=VALUE line from an env file (if present). */
+export function removeEnvValueAt(envPath, key) {
+    let content = '';
+    try {
+        content = fs.readFileSync(envPath, 'utf-8');
+    }
+    catch {
+        return; // no file, nothing to remove
+    }
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`^${escapedKey}=.*\\n?`, 'm');
+    fs.writeFileSync(envPath, content.replace(re, ''));
+}
+/** Removes the key from ~/.kintsugi/.env and <project>/.kintsugi/.env. */
+export function removeApiTokenEverywhere(tokenEnvVar, projectDir) {
+    removeEnvValueAt(globalKintsugiEnvPath(), tokenEnvVar);
+    if (projectDir) {
+        removeEnvValueAt(path.join(projectDir, '.kintsugi', '.env'), tokenEnvVar);
+    }
+}
+function writeEnvValueAt(envPath, key, value) {
     fs.mkdirSync(path.dirname(envPath), { recursive: true });
     let content = '';
     try {
@@ -31,7 +56,6 @@ export function writeGlobalEnvValue(key, value) {
             ? content + line
             : content + '\n' + line;
     fs.writeFileSync(envPath, updated.endsWith('\n') ? updated : updated + '\n');
-    return envPath;
 }
 /**
  * Returns the hosted-API key, bootstrapping an anonymous free key (written to
@@ -77,6 +101,24 @@ export async function getAccountStatus(apiKey, endpoint, fetchImpl) {
         return undefined;
     }
 }
+/**
+ * Deregisters a flow fingerprint server-side so deleted/renamed/rewritten
+ * flows stop occupying free-plan quota. Best-effort: self-hosted or offline
+ * setups return false and callers carry on — the server stays authoritative
+ * at classify time regardless.
+ */
+export async function deregisterFlow(apiKey, endpoint, flowHash, fetchImpl) {
+    try {
+        const res = await (fetchImpl ?? fetch)(`${endpoint.replace(/\/$/, '')}/flows/${encodeURIComponent(flowHash)}`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
 /** Stripe Payment Link URL for the $29/mo Pro upgrade, or undefined when billing is unavailable. */
 export async function createCheckoutUrl(apiKey, endpoint, fetchImpl) {
     try {
@@ -93,6 +135,22 @@ export async function createCheckoutUrl(apiKey, endpoint, fetchImpl) {
         return undefined;
     }
 }
+/** Stripe Customer Portal URL (cancel/update card), or undefined when unavailable. */
+export async function createPortalUrl(apiKey, endpoint, fetchImpl) {
+    try {
+        const res = await (fetchImpl ?? fetch)(`${endpoint.replace(/\/$/, '')}/billing/portal`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            return { error: body.error ?? `portal_${res.status}` };
+        return { url: body.url, error: body.error };
+    }
+    catch {
+        return { error: 'unreachable' };
+    }
+}
 /**
  * Polls account status until the plan becomes 'pro' (the Stripe webhook flips
  * it server-side shortly after payment) or the timeout elapses. Called from
@@ -110,6 +168,55 @@ export async function waitForPlanUpgrade(apiKey, endpoint, options = {}) {
     }
     return undefined;
 }
+/**
+ * Polls account status until the plan becomes 'free' again (portal cancel →
+ * subscription.deleted webhook). Called from `kintsugi cancel`.
+ */
+export async function waitForPlanDowngrade(apiKey, endpoint, options = {}) {
+    const interval = options.intervalMs ?? 3000;
+    const deadline = Date.now() + (options.timeoutMs ?? 180_000);
+    while (Date.now() < deadline && (options.shouldContinue?.() ?? true)) {
+        const status = await getAccountStatus(apiKey, endpoint, options.fetchImpl);
+        if (status?.plan === 'free')
+            return status;
+        options.onPoll?.(status);
+        await new Promise(resolve => setTimeout(resolve, interval));
+    }
+    return undefined;
+}
+/**
+ * Rotates the API key server-side: the account (plan, subscription, flow
+ * quota) is kept, the old key stops working. Returns the new raw key exactly
+ * once — write it where the next machine can read it before losing it.
+ */
+export async function rotateApiKey(apiKey, endpoint, fetchImpl) {
+    try {
+        const res = await (fetchImpl ?? fetch)(`${endpoint.replace(/\/$/, '')}/keys/rotate`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return body.key;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Deletes the account (key + flows + usage, subscription cancelled). */
+export async function deleteAccount(apiKey, endpoint, fetchImpl) {
+    try {
+        const res = await (fetchImpl ?? fetch)(`${endpoint.replace(/\/$/, '')}/keys/me`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Shared classifier-context builder used by the hook, `kintsugi check`, and
  * the MCP server — one code path decides when classification is active.
@@ -141,11 +248,24 @@ export async function buildClassifierContext(config, options = {}) {
         endpoint: config.classifier.endpoint,
         turnContext: options.context || '(none)',
     });
+    const projectDir = options.projectDir;
     return {
         config: config.classifier,
         apiToken,
         context: options.context,
         logger: log,
+        // Report free-plan exhaustion to <project>/.kintsugi/.classifier-state.json
+        // so the VS Code extension can flip its status bar and offer the upgrade.
+        onFlowLimit: projectDir
+            ? info => {
+                try {
+                    writeClassifierState(projectDir, { exhausted: true, ...info });
+                }
+                catch {
+                    // status file is best-effort — never fail the check over it
+                }
+            }
+            : undefined,
     };
 }
 //# sourceMappingURL=auth.js.map

package/dist/baseline.d.ts

@@ -4,5 +4,14 @@ export declare function listFlows(projectDir: string): Promise<FlowMetadata[]>;
 export declare function loadFlow(projectDir: string, name: string): Promise<FlowRecording>;
 export declare function saveFlow(projectDir: string, recording: FlowRecording): Promise<void>;
 export declare function deleteFlow(projectDir: string, name: string): Promise<void>;
+/** Moves a flow to a new name, rewriting metadata.name. Throws if the target exists. */
+export declare function renameFlow(projectDir: string, oldName: string, newName: string): Promise<void>;
+/**
+ * Removes baseline artifacts for steps that no longer exist after a flow is
+ * re-saved with fewer steps — otherwise loadFlow's sorted-glob fallback can
+ * pair stale screenshots with new steps and fabricate regressions. The replay
+ * video of the old flow is stale as well.
+ */
+export declare function pruneBaselineArtifacts(projectDir: string, name: string, stepCount: number): Promise<void>;
 export declare function updateBaseline(projectDir: string, name: string, capture: CaptureResult): Promise<void>;
 //# sourceMappingURL=baseline.d.ts.map

package/dist/baseline.js

@@ -95,6 +95,53 @@ export async function saveFlow(projectDir, recording) {
 export async function deleteFlow(projectDir, name) {
     const flowDir = getFlowDir(projectDir, name);
     await fs.rm(flowDir, { recursive: true, force: true });
+    // Replay scratch dir for this flow goes with it.
+    await fs.rm(path.join(projectDir, '.kintsugi', '.tmp', name), { recursive: true, force: true });
+}
+/** Moves a flow to a new name, rewriting metadata.name. Throws if the target exists. */
+export async function renameFlow(projectDir, oldName, newName) {
+    const oldDir = getFlowDir(projectDir, oldName);
+    const newDir = getFlowDir(projectDir, newName);
+    const metaExists = await fs.stat(path.join(oldDir, 'metadata.json')).then(() => true).catch(() => false);
+    if (!metaExists) {
+        throw new Error(`Flow "${oldName}" not found`);
+    }
+    const targetExists = await fs.stat(path.join(newDir, 'metadata.json')).then(() => true).catch(() => false);
+    if (targetExists) {
+        throw new Error(`A flow named "${newName}" already exists`);
+    }
+    await fs.rename(oldDir, newDir);
+    const metaPath = path.join(newDir, 'metadata.json');
+    const metadata = JSON.parse(await fs.readFile(metaPath, 'utf-8'));
+    metadata.name = newName;
+    await fs.writeFile(metaPath, JSON.stringify(metadata, null, 2));
+    // Stale scratch dir under the old name; scratch under the new name, if any, is stale too.
+    await fs.rm(path.join(projectDir, '.kintsugi', '.tmp', oldName), { recursive: true, force: true });
+}
+/**
+ * Removes baseline artifacts for steps that no longer exist after a flow is
+ * re-saved with fewer steps — otherwise loadFlow's sorted-glob fallback can
+ * pair stale screenshots with new steps and fabricate regressions. The replay
+ * video of the old flow is stale as well.
+ */
+export async function pruneBaselineArtifacts(projectDir, name, stepCount) {
+    const flowDir = getFlowDir(projectDir, name);
+    for (const dir of [path.join(flowDir, 'screenshots'), path.join(flowDir, 'aria')]) {
+        let files = [];
+        try {
+            files = await fs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            const match = /^(?:step_|aria_step_)(\d+)\.(?:png|yml)$/.exec(file);
+            if (match && Number(match[1]) >= stepCount) {
+                await fs.rm(path.join(dir, file), { force: true });
+            }
+        }
+    }
+    await fs.rm(path.join(flowDir, 'video.webm'), { force: true });
 }
 export async function updateBaseline(projectDir, name, capture) {
     const flowDir = getFlowDir(projectDir, name);

package/dist/capturer.js

@@ -24,10 +24,12 @@ export async function captureCurrentState(options) {
         recordVideo: { dir: videoDir }
     });
     const page = await context.newPage();
+    const captureStart = Date.now();
     const result = {
         screenshots: [],
         screenshotPaths: [],
         ariaSnapshots: [],
+        stepTimings: [],
         completedSteps: 0,
         totalSteps: flow.steps.length,
         errors: []
@@ -37,6 +39,7 @@ export async function captureCurrentState(options) {
         let navigated = false;
         for (let i = 0; i < flow.steps.length; i++) {
             const step = flow.steps[i];
+            const stepStartMs = Date.now() - captureStart;
             try {
                 if (!navigated && page.url() === 'about:blank' && step.action !== 'navigate') {
                     await page.goto(url, { waitUntil: 'networkidle' });
@@ -73,9 +76,12 @@ export async function captureCurrentState(options) {
                 result.screenshots.push(buffer);
                 result.screenshotPaths.push(screenshotPath);
                 result.ariaSnapshots.push(aria);
+                result.stepTimings?.push({ startMs: stepStartMs, endMs: Date.now() - captureStart });
                 result.completedSteps++;
             }
             catch (err) {
+                // A timing window for the failed attempt too, so playback clips can frame it.
+                result.stepTimings?.push({ startMs: stepStartMs, endMs: Date.now() - captureStart });
                 result.errors.push(`Step ${i} (${step.action}) failed: ${err.message}`);
                 break;
             }

package/dist/classifier-state.d.ts

@@ -0,0 +1,13 @@
+export interface ClassifierState {
+    exhausted: boolean;
+    kind?: 'flow_limit_reached' | 'monthly_cap_reached';
+    flowsUsed?: number;
+    flowLimit?: number;
+    upgradeUrl?: string;
+    timestamp: string;
+}
+export declare function classifierStatePath(projectDir: string): string;
+export declare function writeClassifierState(projectDir: string, state: Omit<ClassifierState, 'timestamp'>): void;
+export declare function readClassifierState(projectDir: string): ClassifierState | undefined;
+export declare function clearClassifierState(projectDir: string): void;
+//# sourceMappingURL=classifier-state.d.ts.map

package/dist/classifier-state.js

@@ -0,0 +1,39 @@
+/**
+ * Classifier quota state, shared between the processes that classify (hook,
+ * `kintsugi check`, MCP) and the VS Code extension. When a hosted-classifier
+ * call hits the free plan's limits (429 flow_limit_reached/monthly_cap_reached)
+ * the writer records the exhaustion in <project>/.kintsugi/.classifier-state.json
+ * so the extension can flip its status bar to "Classifier Off" and offer the
+ * upgrade path. The file lives inside the gitignored .kintsugi dir.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export function classifierStatePath(projectDir) {
+    return path.join(projectDir, '.kintsugi', '.classifier-state.json');
+}
+export function writeClassifierState(projectDir, state) {
+    const filePath = classifierStatePath(projectDir);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify({ ...state, timestamp: new Date().toISOString() }, null, 2));
+}
+export function readClassifierState(projectDir) {
+    try {
+        const raw = fs.readFileSync(classifierStatePath(projectDir), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.exhausted !== 'boolean')
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function clearClassifierState(projectDir) {
+    try {
+        fs.unlinkSync(classifierStatePath(projectDir));
+    }
+    catch {
+        // already gone
+    }
+}
+//# sourceMappingURL=classifier-state.js.map

package/dist/comparator.d.ts

@@ -9,6 +9,13 @@ export interface ClassifierContext {
         info: (msg: string, data?: unknown) => void;
         warn: (msg: string, data?: unknown) => void;
     };
+    /** Invoked when the hosted classifier reports the free plan's limits are exhausted (429). */
+    onFlowLimit?: (info: {
+        kind: 'flow_limit_reached' | 'monthly_cap_reached';
+        flowsUsed?: number;
+        flowLimit?: number;
+        upgradeUrl?: string;
+    }) => void;
 }
 export interface CompareOptions {
     outputDir?: string;

package/dist/comparator.js

@@ -167,6 +167,12 @@ async function classifySteps(candidates, baseline, current, classifier) {
                     flowsUsed: err.flowsUsed,
                     flowLimit: err.flowLimit,
                 });
+                classifier.onFlowLimit?.({
+                    kind: err.kind,
+                    flowsUsed: err.flowsUsed,
+                    flowLimit: err.flowLimit,
+                    upgradeUrl: err.upgradeUrl,
+                });
                 const where = err.kind === 'monthly_cap_reached'
                     ? 'monthly classification cap reached on the free plan'
                     : `free plan flow limit reached (${err.flowsUsed ?? '?'}/${err.flowLimit ?? '?'} flows guarded)`;

package/dist/config.js

@@ -29,20 +29,14 @@ export function getDefaultConfig() {
             type: 'auto',
             maxRetries: 3,
         },
-        recording: {
-            passive: true,
-            collectorPort: 4321,
-        },
         uiFilePatterns: ['src/**/*.tsx', 'src/**/*.ts', 'src/**/*.jsx', 'src/**/*.js'],
     };
 }
 export async function ensureKintsugiDir(projectDir) {
     const kintsugiDir = path.join(projectDir, '.kintsugi');
     const flowsDir = path.join(kintsugiDir, 'flows');
-    const recordingsDir = path.join(kintsugiDir, 'recordings');
     await fs.mkdir(kintsugiDir, { recursive: true });
     await fs.mkdir(flowsDir, { recursive: true });
-    await fs.mkdir(recordingsDir, { recursive: true });
 }
 export async function loadConfig(projectDir) {
     const configPath = path.join(projectDir, '.kintsugi', 'config.json');