@kintsugi-ai/hook 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,18 @@
+# @kintsugi-ai/hook
+
+Turn-end Stop hook for [Kintsugi](https://github.com/Munkhin/kintsugi), the visual
+UX regression guard for AI coding agents.
+
+Registered by `npx @kintsugi-ai/cli init` into Claude Code (`.claude/settings.json`),
+Codex CLI (`.codex/hooks.json`), and Antigravity (`.agents/hooks.json`) as:
+
+```
+npx -y @kintsugi-ai/hook --event stop
+```
+
+At the end of every agent turn it replays all recorded flows, compares them against
+baselines, and — when a flow is broken — blocks the stop with actionable fix feedback
+in each agent's native protocol (`decision: block/continue` JSON on stdout, or
+exit 2 + stderr for Codex). Escalations feed the VS Code split view.
+
+You normally never install this package directly; the CLI registers it for you.

package/dist/coverage-nudge.d.ts

@@ -0,0 +1,14 @@
+import type { FlowMetadata } from '@kintsugi-ai/core';
+/** Changed files in the working tree (staged, unstaged and untracked). */
+export declare function getChangedFiles(projectDir: string): Promise<string[]>;
+/**
+ * Non-blocking coverage suggestion: when UI files changed this turn but no
+ * recorded flow covers them, build the "record a flow" message. Emitted every
+ * qualifying turn (no rate limit) — appended to the block reason when a
+ * regression is already blocking, otherwise written to stderr. Returns an
+ * empty string when everything changed is covered.
+ */
+export declare function maybeBuildCoverageNudge(projectDir: string, flows: FlowMetadata[], logger?: {
+    info: (msg: string, data?: unknown) => void;
+}, uiFilePatterns?: string[]): Promise<string>;
+//# sourceMappingURL=coverage-nudge.d.ts.map

package/dist/coverage-nudge.js

@@ -0,0 +1,46 @@
+import { execFile } from 'node:child_process';
+import { isUIFile, DEFAULT_UI_PATTERNS } from './ui-file-detector.js';
+import { anyFlowCovers } from './flow-matcher.js';
+/** Changed files in the working tree (staged, unstaged and untracked). */
+export async function getChangedFiles(projectDir) {
+    const run = (args) => new Promise((resolve) => {
+        execFile('git', args, { cwd: projectDir }, (err, stdout) => resolve(err ? '' : stdout));
+    });
+    // -uall lists untracked files individually (porcelain collapses new dirs).
+    const out = await run(['status', '--porcelain', '-uall']);
+    if (!out)
+        return [];
+    return out
+        .split('\n')
+        .map(line => line.slice(3).trim())
+        .filter(f => f !== '' && !f.includes(' -> ')) // skip renames' old side
+        .map(f => f.replace(/^"|"$/g, '').replace(/ -> .+$/, ''));
+}
+/**
+ * Non-blocking coverage suggestion: when UI files changed this turn but no
+ * recorded flow covers them, build the "record a flow" message. Emitted every
+ * qualifying turn (no rate limit) — appended to the block reason when a
+ * regression is already blocking, otherwise written to stderr. Returns an
+ * empty string when everything changed is covered.
+ */
+export async function maybeBuildCoverageNudge(projectDir, flows, logger, uiFilePatterns) {
+    let changed = [];
+    try {
+        changed = await getChangedFiles(projectDir);
+    }
+    catch {
+        return '';
+    }
+    const uiChanged = changed.filter(f => isUIFile(f, uiFilePatterns ?? DEFAULT_UI_PATTERNS));
+    if (uiChanged.length === 0)
+        return '';
+    const uncovered = uiChanged.filter(f => !anyFlowCovers([f], flows));
+    if (uncovered.length === 0)
+        return '';
+    const fileList = uncovered.slice(0, 10).map(f => `  - ${f}`).join('\n');
+    logger?.info('coverage nudge emitted', { uncoveredCount: uncovered.length });
+    return (`Kintsugi coverage gap: UI files changed with no flow covering them:\n${fileList}\n` +
+        `Record a flow for this UI (save_flow with source_files, then capture_baseline) so future regressions are caught automatically. ` +
+        `If the page was removed, delete_flow the flows that guarded it.`);
+}
+//# sourceMappingURL=coverage-nudge.js.map

package/dist/escalation.d.ts

@@ -1,28 +1,7 @@
-import type { ComparisonResult } from '@kintsugi-ai/core';
-export interface EscalationSignal {
-    flowName: string;
-    result: ComparisonResult;
-    oldVideoPath?: string;
-    newVideoPath?: string;
-    timestamp: string;
-    attempt: number;
-    maxAttempts: number;
-}
 /**
- * Writes an escalation signal for the VS Code extension.
- * @param projectDir The project directory.
- * @param signal The escalation signal data.
+ * Escalation signals live in @kintsugi-ai/core (shared with the CLI and the
+ * VS Code extension). Re-exported here for the hook's own imports.
  */
-export declare function writeEscalation(projectDir: string, signal: EscalationSignal): Promise<void>;
-/**
- * Reads the current escalation signal.
- * @param projectDir The project directory.
- * @returns The current escalation signal or null if not found.
- */
-export declare function readEscalation(projectDir: string): Promise<EscalationSignal | null>;
-/**
- * Clears the escalation signal.
- * @param projectDir The project directory.
- */
-export declare function clearEscalation(projectDir: string): Promise<void>;
+export { writeEscalation, readEscalation, clearEscalation, removeFlowFromEscalation, escalationPath, normalizeEscalation, } from '@kintsugi-ai/core';
+export type { EscalationSignal, RegressionEscalation, PlaybackFailureEscalation, EscalationFlowEntry, } from '@kintsugi-ai/core';
 //# sourceMappingURL=escalation.d.ts.map

package/dist/escalation.js

@@ -1,48 +1,6 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-function getEscalationFilePath(projectDir) {
-    return path.join(projectDir, '.kintsugi', '.escalation.json');
-}
 /**
- * Writes an escalation signal for the VS Code extension.
- * @param projectDir The project directory.
- * @param signal The escalation signal data.
+ * Escalation signals live in @kintsugi-ai/core (shared with the CLI and the
+ * VS Code extension). Re-exported here for the hook's own imports.
  */
-export async function writeEscalation(projectDir, signal) {
-    const filePath = getEscalationFilePath(projectDir);
-    const dir = path.dirname(filePath);
-    await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(filePath, JSON.stringify(signal, null, 2), 'utf-8');
-}
-/**
- * Reads the current escalation signal.
- * @param projectDir The project directory.
- * @returns The current escalation signal or null if not found.
- */
-export async function readEscalation(projectDir) {
-    const filePath = getEscalationFilePath(projectDir);
-    try {
-        const content = await fs.readFile(filePath, 'utf-8');
-        return JSON.parse(content);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Clears the escalation signal.
- * @param projectDir The project directory.
- */
-export async function clearEscalation(projectDir) {
-    const filePath = getEscalationFilePath(projectDir);
-    try {
-        await fs.unlink(filePath);
-    }
-    catch (err) {
-        const isNotFound = typeof err === 'object' && err !== null && 'code' in err && err.code === 'ENOENT';
-        if (!isNotFound) {
-            throw err;
-        }
-    }
-}
+export { writeEscalation, readEscalation, clearEscalation, removeFlowFromEscalation, escalationPath, normalizeEscalation, } from '@kintsugi-ai/core';
 //# sourceMappingURL=escalation.js.map

package/dist/flow-matcher.d.ts

@@ -1,9 +1,13 @@
 import type { FlowMetadata } from '@kintsugi-ai/core';
 /**
- * Determines which flows are affected by a file change.
- * @param filePath The modified file path.
- * @param flows The list of available flows.
- * @returns Array of affected flow names.
+ * Matches changed files to the flows that cover them. A flow covers a file if:
+ *  - the flow was saved with explicit `sourceFiles` containing the path, or
+ *  - the flow's URL has a distinctive path segment (e.g. /products) that
+ *    appears as a segment of the changed file's path (app/products/page.tsx).
+ * Flows without either signal match nothing (conservative for coverage
+ * nudging; turn-end checks still replay every flow regardless).
  */
-export declare function findAffectedFlows(filePath: string, flows: FlowMetadata[]): string[];
+export declare function findAffectedFlows(changedFiles: string[], flows: FlowMetadata[]): FlowMetadata[];
+/** True when any changed file is covered by at least one flow. */
+export declare function anyFlowCovers(changedFiles: string[], flows: FlowMetadata[]): boolean;
 //# sourceMappingURL=flow-matcher.d.ts.map

package/dist/flow-matcher.js

@@ -1,12 +1,48 @@
 /**
- * Determines which flows are affected by a file change.
- * @param filePath The modified file path.
- * @param flows The list of available flows.
- * @returns Array of affected flow names.
+ * Matches changed files to the flows that cover them. A flow covers a file if:
+ *  - the flow was saved with explicit `sourceFiles` containing the path, or
+ *  - the flow's URL has a distinctive path segment (e.g. /products) that
+ *    appears as a segment of the changed file's path (app/products/page.tsx).
+ * Flows without either signal match nothing (conservative for coverage
+ * nudging; turn-end checks still replay every flow regardless).
  */
-export function findAffectedFlows(filePath, flows) {
-    // A conservative approach: for now, assume all flows might be affected by the UI change.
-    // Future enhancements can check if the file path matches explicit mappings.
-    return flows.map(f => f.name);
+export function findAffectedFlows(changedFiles, flows) {
+    return flows.filter(flow => changedFiles.some(f => flowCoversFile(flow, f)));
+}
+/** True when any changed file is covered by at least one flow. */
+export function anyFlowCovers(changedFiles, flows) {
+    return changedFiles.some(f => flows.some(flow => flowCoversFile(flow, f)));
+}
+function flowCoversFile(flow, file) {
+    const norm = file.replace(/\\/g, '/');
+    if (flow.sourceFiles && flow.sourceFiles.some(sf => pathsMatch(sf, norm))) {
+        return true;
+    }
+    // URL heuristic: a distinctive path segment of the flow's start URL
+    // (/products, /checkout) maps to source files under a matching segment
+    // (app/products/page.tsx, pages/checkout.tsx).
+    const segments = urlSegments(flow.url).filter(s => s.length > 2);
+    if (segments.length === 0)
+        return false;
+    const parts = norm.split('/');
+    return segments.some(seg => parts.some(part => part === seg || part.startsWith(`${seg}.`) || part.startsWith(`${seg}Page`)));
+}
+function pathsMatch(sourceFile, file) {
+    const a = sourceFile.replace(/\\/g, '/').replace(/^\.\//, '');
+    const b = file.replace(/\\/g, '/').replace(/^\.\//, '');
+    return a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`);
+}
+/** Meaningful path segments of a URL ("/", route params and bare ids excluded). */
+function urlSegments(url) {
+    let pathname = '';
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        return [];
+    }
+    return pathname
+        .split('/')
+        .filter(s => s.length > 0 && !s.startsWith(':') && !/^[0-9]+$/.test(s));
 }
 //# sourceMappingURL=flow-matcher.js.map

package/dist/index.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
-import { loadConfig, listFlows, loadFlow, captureCurrentState, compareFlow, formatAgentFeedback, buildClassifierContext, loadKintsugiEnv, DiffResult } from '@kintsugi-ai/core';
+import { loadConfig, listFlows, loadFlow, captureCurrentState, compareFlow, formatAgentFeedback, buildClassifierContext, loadKintsugiEnv, getAccountStatus, isUrlReachable, readClassifierState, clearClassifierState, DiffResult, } from '@kintsugi-ai/core';
 import { detectAgent, outputFeedback, exitWithResult } from './agent-detect.js';
 import { extractTurnContext } from './context.js';
 import { writeEscalation, readEscalation, clearEscalation } from './escalation.js';
+import { maybeBuildCoverageNudge } from './coverage-nudge.js';
 import { createLogger } from './logger.js';
 async function main() {
     const earlyWarnings = [];
@@ -65,7 +66,8 @@ async function main() {
  * Turn-end visual check: verifies every recorded flow in parallel (each in
  * its own browser context), classifies oversized diffs in parallel, and on a
  * regression blocks the agent's stop with fix-it feedback until it passes or
- * maxAttempts is reached.
+ * maxAttempts is reached — at which point the failed playback escalates to
+ * the user instead of blocking forever.
  */
 async function runTurnEndCheck(agent, input, projectDir, log) {
     // Pick up gitignored <project>/.kintsugi/.env before resolving the token
@@ -80,64 +82,155 @@ async function runTurnEndCheck(agent, input, projectDir, log) {
         bootstrapKey: true,
         projectDir,
     });
+    // Quota-exhausted fast path: while the free-plan limit (or monthly cap)
+    // holds, skip classify HTTP entirely and degrade unclassified pixel diffs
+    // to warnings — blocking on them was a false-positive loop. The state is
+    // re-verified against the live account so upgrades / freed quota recover
+    // immediately, and the monthly cap expires with its month.
+    let degraded = false;
+    const state = readClassifierState(projectDir);
+    if (state?.exhausted) {
+        const monthlyCapExpired = state.kind === 'monthly_cap_reached' &&
+            Date.now() - Date.parse(state.timestamp) > 32 * 24 * 60 * 60 * 1000;
+        if (monthlyCapExpired) {
+            clearClassifierState(projectDir);
+        }
+        else if (classifierContext && config.classifier.provider === 'kintsugi') {
+            const status = await getAccountStatus(classifierContext.apiToken, config.classifier.endpoint);
+            if (status && (status.plan === 'pro' || (status.flowLimit !== null && status.flowsUsed < status.flowLimit))) {
+                clearClassifierState(projectDir);
+                log.info('classifier quota recovered — resuming classification', { plan: status.plan, flowsUsed: status.flowsUsed });
+            }
+            else {
+                degraded = true;
+            }
+        }
+        else {
+            degraded = true;
+        }
+        if (degraded) {
+            log.warn('classifier quota exhausted — degraded mode (unclassified diffs warn only)', { kind: state.kind });
+        }
+    }
+    const effectiveClassifier = degraded ? undefined : classifierContext;
     const flows = await listFlows(projectDir);
     log.info('flows discovered', {
         flowsDir: path.join(projectDir, '.kintsugi', 'flows'),
         count: flows.length,
         names: flows.map(f => f.name),
     });
+    // Coverage nudge, computed once and delivered every qualifying turn:
+    // appended to the block reason when a regression already blocks (the
+    // model sees it), otherwise a stderr notice. Never blocks on its own.
+    const nudge = await maybeBuildCoverageNudge(projectDir, flows, log, config.uiFilePatterns);
     if (flows.length === 0) {
         log.info('no recorded flows — nothing to check');
+        if (nudge)
+            process.stderr.write(`${nudge}\n`);
         outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
         process.exit(0);
     }
     const maxAttempts = config.agent.maxRetries;
     const outcomes = await Promise.all(flows.map(async (flow) => {
         try {
-            return await checkFlow(flow.name, config, classifierContext, projectDir, log);
+            return await checkFlow(flow.name, config, effectiveClassifier, projectDir, log, degraded);
         }
         catch (err) {
             log.error('flow check crashed', { flowName: flow.name, error: err.message });
             return { flowName: flow.name, isRegression: false };
         }
     }));
+    // Every flow skipped means the dev server is unreachable —
+    // infrastructure, not a regression. Never block over it.
+    const skipped = outcomes.filter(o => o.skippedReason);
+    if (skipped.length > 0) {
+        const urls = [...new Set(skipped.map(s => s.skippedReason))];
+        process.stderr.write(`Kintsugi: dev server not reachable (${urls.join(', ')}) — visual check skipped for ${skipped.length}/${outcomes.length} flow${skipped.length === 1 ? '' : 's'}. This is not a regression.\n`);
+    }
+    if (skipped.length === outcomes.length) {
+        log.warn('dev server unreachable — whole visual check skipped', { urls: [...new Set(skipped.map(s => s.skippedReason))] });
+        outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
+        process.exit(0);
+    }
+    if (degraded) {
+        const unclassified = outcomes.filter(o => o.comparisonResult?.result === DiffResult.CHANGED);
+        if (unclassified.length > 0) {
+            process.stderr.write(`Kintsugi (degraded — free plan flow limit reached): ${unclassified.length} flow${unclassified.length === 1 ? '' : 's'} show unclassified visual changes; not blocking. Run \`kintsugi upgrade\` for intent classification.\n`);
+        }
+    }
     const broken = outcomes.filter(o => o.isRegression);
     if (broken.length === 0) {
         // Clean pass — either nothing broke or the agent just fixed the
         // previous regression. Either way the agent may stop.
         log.info('turn-end check passed — clearing any previous escalation');
         await clearEscalation(projectDir);
+        if (nudge)
+            process.stderr.write(`${nudge}\n`);
         outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
         process.exit(0);
     }
     // The fresh check above is the source of truth; only treat a pending
     // escalation as "still unfixed" now that the current state is known broken.
-    const pendingEscalation = await readEscalation(projectDir);
-    if (pendingEscalation && pendingEscalation.attempt >= maxAttempts) {
-        log.info('max fix attempts reached — allowing agent to stop', {
-            flowName: pendingEscalation.flowName,
-            attempt: pendingEscalation.attempt,
+    const pending = await readEscalation(projectDir);
+    // A previous give-up already showed the user the failed playback for
+    // exactly these flows — stay non-blocking until the broken set changes.
+    const pendingFailure = pending?.type === 'playback_failure' ? pending : undefined;
+    if (pendingFailure && broken.every(b => pendingFailure.flows.includes(b.flowName))) {
+        log.info('already escalated to the user for these flows — allowing stop', {
+            flows: broken.map(b => b.flowName),
+        });
+        outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
+        process.exit(0);
+    }
+    const pendingRegression = pending && pending.type !== 'playback_failure' ? pending : undefined;
+    if (pendingRegression && pendingRegression.attempt >= maxAttempts) {
+        // Give up blocking; escalate the failing playback to the human.
+        const worst = broken.find(b => b.flowName === pendingRegression.flows[0]?.flowName) ?? broken[0];
+        const failedStep = worst.comparisonResult?.failedStep ?? 0;
+        await writeEscalation(projectDir, {
+            version: 2,
+            type: 'playback_failure',
+            flowName: worst.flowName,
+            flows: broken.map(b => b.flowName),
+            clipPath: worst.videoPath,
+            failedStep,
+            stepDescription: worst.failedStepDescription ?? `step ${failedStep}`,
+            analysis: formatAgentFeedback(worst.comparisonResult, worst.flowName).slice(0, 4000),
+            stepTimings: worst.stepTimings,
+            timestamp: new Date().toISOString(),
+            attempt: pendingRegression.attempt,
             maxAttempts,
         });
-        await clearEscalation(projectDir);
+        log.warn('max fix attempts reached — escalating failed playback to the user, allowing stop', {
+            flows: broken.map(b => b.flowName),
+            attempt: pendingRegression.attempt,
+            maxAttempts,
+        });
+        process.stderr.write(`Kintsugi: the agent could not fix [${broken.map(b => b.flowName).join(', ')}] after ${maxAttempts} attempts — showing the failed playback to the user.\n`);
         outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
         process.exit(0);
     }
-    const first = broken[0];
-    const attempt = (pendingEscalation?.attempt || 0) + 1;
+    // Every broken flow reaches the escalation queue (the VS Code split view
+    // iterates it); the agent feedback below also covers all of them.
+    const attempt = (pendingRegression?.attempt || 0) + 1;
     await writeEscalation(projectDir, {
-        flowName: first.flowName,
-        result: first.comparisonResult,
-        oldVideoPath: first.oldPath ?? '',
-        newVideoPath: first.newPath ?? '',
+        version: 2,
+        flows: broken.map(o => ({
+            flowName: o.flowName,
+            result: o.comparisonResult,
+            oldImagePath: o.oldPath,
+            newImagePath: o.newPath,
+            videoPath: o.videoPath,
+            stepTimings: o.stepTimings,
+        })),
         timestamp: new Date().toISOString(),
         attempt,
         maxAttempts,
     });
-    // Fix-it feedback covers every broken flow: aria diffs, image pairs, per-pair fixes
-    const combinedFeedback = broken
-        .map(o => formatAgentFeedback(o.comparisonResult, o.flowName))
-        .join('\n\n');
+    // Fix-it feedback covers every broken flow: aria diffs, image pairs, per-pair
+    // fixes — plus the coverage nudge while it is still relevant.
+    const combinedFeedback = broken.map(o => formatAgentFeedback(o.comparisonResult, o.flowName)).join('\n\n') +
+        (nudge ? `\n\n${nudge}` : '');
     log.warn('turn-end regression — blocking agent stop with feedback', {
         flows: broken.map(b => b.flowName),
         attempt,
@@ -147,34 +240,56 @@ async function runTurnEndCheck(agent, input, projectDir, log) {
     exitWithResult(agent, true);
 }
 /** Replays one flow and compares it against its baseline. */
-async function checkFlow(flowName, config, classifierContext, projectDir, log) {
+async function checkFlow(flowName, config, classifierContext, projectDir, log, degraded) {
     const flowRecord = await loadFlow(projectDir, flowName);
     if (!flowRecord) {
         log.warn('flow metadata listed but could not be loaded', { flowName });
         return { flowName, isRegression: false };
     }
     log.info('checking flow', { flowName, stepCount: flowRecord.steps.length, baselineScreenshots: flowRecord.screenshotPaths.length });
+    // Same URL resolution as the MCP tools: the flow's own URL wins.
+    const url = flowRecord.metadata.url || config.devServerUrl;
+    // Pre-flight: an unreachable URL is infrastructure, not a regression —
+    // a wrong port must never turn every turn into a blocked "regression".
+    if (!(await isUrlReachable(url))) {
+        log.warn('flow URL unreachable — skipping replay', { flowName, url });
+        return { flowName, isRegression: false, skippedReason: url };
+    }
     const outputDir = path.join(projectDir, '.kintsugi', '.tmp', flowName);
     fs.mkdirSync(outputDir, { recursive: true });
     const currentState = await captureCurrentState({
-        url: config.devServerUrl,
+        url,
         flow: flowRecord,
         outputDir,
         viewport: config.viewport,
     });
-    log.info('current state captured', { flowName, url: config.devServerUrl, screenshots: currentState.screenshots.length, errors: currentState.errors.length });
+    log.info('current state captured', { flowName, url, screenshots: currentState.screenshots.length, errors: currentState.errors.length });
+    // Step 0 is always the navigate step (save_flow prepends it) — failing
+    // there means the page or server is unreachable, not a UI regression.
+    if (currentState.completedSteps === 0) {
+        const reason = currentState.errors[0] ?? 'navigation failed';
+        log.warn('replay could not reach the page — skipping flow', { flowName, url, reason });
+        return { flowName, isRegression: false, skippedReason: `${url} (${reason})` };
+    }
     const comparisonResult = await compareFlow(flowRecord, currentState, { outputDir, classifier: classifierContext });
     log.info('comparison finished', { flowName, result: comparisonResult.result });
     // Any definite visual change (CHANGED) or broken capture is a regression —
     // the baseline flow no longer matches the live page. INTENTIONAL means the
-    // classifier accepted the change.
-    const isRegression = comparisonResult.result !== DiffResult.IDENTICAL &&
-        comparisonResult.result !== DiffResult.MINOR &&
-        comparisonResult.result !== DiffResult.INTENTIONAL;
+    // classifier accepted the change. In degraded mode (quota exhausted, no
+    // classifier) CHANGED diffs only warn: blocking on unclassified pixel
+    // diffs was a false-positive loop.
+    const passes = comparisonResult.result === DiffResult.IDENTICAL ||
+        comparisonResult.result === DiffResult.MINOR ||
+        comparisonResult.result === DiffResult.INTENTIONAL;
+    const isRegression = !passes && !(degraded && comparisonResult.result === DiffResult.CHANGED);
     if (!isRegression) {
         if (comparisonResult.result === DiffResult.INTENTIONAL) {
             log.info('large visual change accepted as intentional by classifier', { flowName });
         }
+        // Clean replays don't keep their video — only escalations retain clips.
+        if (currentState.videoPath) {
+            await fs.promises.rm(path.dirname(currentState.videoPath), { recursive: true, force: true }).catch(() => { });
+        }
         return { flowName, isRegression: false, comparisonResult };
     }
     log.warn('REGRESSION detected', { flowName, result: comparisonResult.result });
@@ -185,6 +300,9 @@ async function checkFlow(flowName, config, classifierContext, projectDir, log) {
         comparisonResult,
         oldPath: flowRecord.screenshotPaths[failedIndex] ?? flowRecord.screenshotPaths[0] ?? '',
         newPath: currentState.screenshotPaths[failedIndex] ?? currentState.screenshotPaths[0] ?? '',
+        videoPath: currentState.videoPath,
+        stepTimings: currentState.stepTimings,
+        failedStepDescription: flowRecord.steps[failedIndex]?.description,
     };
 }
 function stdinLength() {
@@ -201,9 +319,10 @@ main().catch((e) => {
         log.error('hook crashed', e);
     }
     catch { /* ignore */ }
-    // Exit non-zero so the agent knows something went wrong.
-    // Write a diagnostic to stderr for agents that capture it.
-    process.stderr.write(`kintsugi hook crashed: ${e instanceof Error ? e.message : String(e)}\n`);
-    process.exit(1);
+    // Exit 0 for every agent: a crashed check is not a check verdict, and a
+    // non-zero exit on Stop reads as a broken hook configuration (Claude Code
+    // shows it to the user as an error and the model gets nothing).
+    process.stderr.write(`kintsugi hook crashed (check skipped, turn allowed): ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(0);
 });
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,14 +1,29 @@
 {
   "name": "@kintsugi-ai/hook",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent hook script for Kintsugi visual regression checks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Munkhin/kintsugi.git",
+    "directory": "packages/hook"
+  },
+  "bugs": {
+    "url": "https://github.com/Munkhin/kintsugi/issues"
+  },
+  "homepage": "https://github.com/Munkhin/kintsugi#readme",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
     "kintsugi-hook": "./dist/index.js"
   },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map"
+  ],
   "dependencies": {
-    "@kintsugi-ai/core": "0.1.0"
+    "@kintsugi-ai/core": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/.kintsugi/logs/hook.log

@@ -1,11 +0,0 @@
-[2026-09-23T12:36:50.957Z] hook invoked {"argv":["--help"],"cwd":"/Users/munch/Documents/coding/kintsugi/packages/hook","projectDir":"/Users/munch/Documents/coding/kintsugi/packages/hook","stdinBytes":0}
-[2026-09-23T12:36:50.957Z] WARN: stdin was empty — agent sent no hook payload
-[2026-09-23T12:36:50.957Z] agent detected {"agent":"codex","isStopEvent":false,"isExplicitStopEvent":false,"inputKeys":[]}
-[2026-09-23T12:36:50.957Z] non-stop event — deferring visual check to turn end
-[2026-09-23T12:36:53.296Z] hook invoked {"argv":["--event","stop"],"cwd":"/Users/munch/Documents/coding/kintsugi/packages/hook","projectDir":"/Users/munch/Documents/coding/kintsugi/packages/hook","stdinBytes":0}
-[2026-09-23T12:36:53.296Z] agent detected {"agent":"codex","isStopEvent":true,"isExplicitStopEvent":true,"inputKeys":[]}
-[2026-09-23T12:36:53.296Z] config loaded {"devServerUrl":"http://localhost:3000","classifierModel":"kintsugi-hosted"}
-[2026-09-23T12:36:54.063Z] WARN: could not obtain a kintsugi api key: fetch failed
-[2026-09-23T12:36:54.064Z] WARN: no API token found (env KINTSUGI_API_KEY, <project>/.kintsugi/.env, or ~/.kintsugi/.env) — classifier disabled, large diffs will escalate without classification
-[2026-09-23T12:36:54.065Z] flows discovered {"flowsDir":"/Users/munch/Documents/coding/kintsugi/packages/hook/.kintsugi/flows","count":0,"names":[]}
-[2026-09-23T12:36:54.065Z] no recorded flows — nothing to check

package/dist/agent-detect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-detect.d.ts","sourceRoot":"","sources":["../src/agent-detect.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;AAEpE,MAAM,WAAW,SAAS;IAEtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE;YACH,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;SAC1B,CAAC;KACL,CAAC;IAGF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KAC1B,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CA2BxD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAuB1F;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7D,IAAI,CAqCN;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,GAAG,KAAK,CAY9E"}

package/dist/agent-detect.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-detect.js","sourceRoot":"","sources":["../src/agent-detect.ts"],"names":[],"mappings":"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"}

package/dist/agent-detect.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=agent-detect.test.d.ts.map

package/dist/agent-detect.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-detect.test.d.ts","sourceRoot":"","sources":["../src/agent-detect.test.ts"],"names":[],"mappings":""}