@jmtrin/kevin-core 1.3.0

package/dist/QualityGate.js

@@ -0,0 +1,119 @@
+import { SUGGESTIONS } from "./Reflector.js";
+/**
+ * v0.4.0 (K4-003/K4-004 / plan §5.1) — QualityGate.
+ *
+ * Pure, NO-LLM predicates deciding whether a lesson is worth injecting into
+ * the model's prompt. Principle 11: never inject noise.
+ *
+ * - `evaluate` — classifies a lesson (rescued errorType, non-generic
+ *   suggestion, isActionable, strength).
+ * - `rescueErrorType` — a dispatched code overrides the coarse
+ *   `errorType` (e.g. `'unknown'` → `'TS2304'`), fixing the defect where
+ *   lessons said "fails with unknown" even when the Reflector DID identify
+ *   the error code.
+ * - `canInject` — per-session + per-fingerprint admission rules (K4-004).
+ */
+/** The v0.1.x fallback suggestions. A lesson whose suggestion is one of these
+ * (and has no dispatched code) carries no actionable information. */
+export const GENERIC_SUGGESTIONS = new Set(Object.values(SUGGESTIONS));
+export function isGenericSuggestion(suggestion) {
+    return GENERIC_SUGGESTIONS.has(suggestion);
+}
+export const QualityGate = {
+    /**
+     * A dispatched code always overrides the coarse errorType for display:
+     * `'unknown'` + `TS2304` → `'TS2304'`.
+     */
+    rescueErrorType(dispatch, errorType) {
+        if (dispatch?.code)
+            return dispatch.code;
+        return errorType;
+    },
+    /** Classify a lesson per §5.1 rule 1 (rescue) and the generic ban. */
+    evaluate(lesson, dispatch, errorType) {
+        const rescued = this.rescueErrorType(dispatch, errorType);
+        const generic = isGenericSuggestion(lesson.suggestion);
+        // §5.1 rule 2: the generic ban applies only when there is no
+        // dispatched code — a matched code always makes the lesson
+        // actionable (the lesson then carries a "Likely cause" hint).
+        const isActionable = !generic || dispatch?.code != null;
+        const strength = dispatch?.code != null || rescued !== "unknown" ? "strong" : "weak";
+        return {
+            errorType: rescued,
+            suggestion: lesson.suggestion,
+            isActionable,
+            strength,
+        };
+    },
+    /**
+     * v0.4.0 (K4-004 / plan §5.1 rules 2-4) — admission gate evaluated at
+     * injection time. A lesson is injectable only when:
+     *
+     * 1. its memory id was not already injected this session (seen-set),
+     * 2. its memory is not `stale`,
+     * 3. its fingerprint has not recurred since injection (`recurrenceCount
+     *    === 0` — a lesson that failed to prevent the error leaves the
+     *    prompt),
+     * 4. it is actionable AND strong — weak lessons with generic suggestions
+     *    are never injected (unless `qualityGateEnabled = false` for debug,
+     *    K4-023).
+     *
+     * v0.5.0 (K5-006 / plan §5.2, D5-04) — the boolean form is a thin
+     * wrapper over `canInjectVerdict`; the reason is never discarded by
+     * callers that use the verdict form.
+     */
+    canInject(memory, ctx, qualityGateEnabled = true) {
+        return this.canInjectVerdict(memory, ctx, qualityGateEnabled).allowed;
+    },
+    /**
+     * v0.5.0 (K5-006 / plan §5.2, D5-04) — the verdict form of `canInject`.
+     * Branch order preserves the v0.4.0 sequence with `ignored` inserted
+     * second:
+     *
+     * 0. `confidence < ctx.confidenceFloor` → `low_confidence` (v0.6.0,
+     *    K6-022 — runs FIRST: it is the cheapest check, and a memory below
+     *    the floor should not consume a seen-set slot it will never use)
+     * 1. seen this session            → `seen_this_session`
+     * 2. `memory.ignored === true`    → `ignored`
+     * 3. status !== 'active'          → `not_active`
+     * 4. recurrence in session        → `recurrence`
+     * 5. weak / not actionable        → `weak` (skipped entirely when
+     *    `qualityGateEnabled === false` — the debug flag bypasses the
+     *    quality check only, never the seen/ignored/status/recurrence bans)
+     *
+     * `ignored` is a human verdict (D5-07) and is enforced even in debug
+     * mode: the flag excludes a memory from retrieval entirely, so the gate
+     * is only ever asked about it defensively.
+     *
+     * The floor comparison is `>=`-admissive: a memory exactly AT the floor
+     * passes the branch (asserted in K6-022). A floor of '0' admits
+     * everything the other five branches allow.
+     */
+    canInjectVerdict(memory, ctx, qualityGateEnabled = true) {
+        if (memory.confidence !== undefined &&
+            ctx.confidenceFloor !== undefined &&
+            memory.confidence < ctx.confidenceFloor) {
+            return { allowed: false, reason: "low_confidence" };
+        }
+        if (ctx.seenThisSession.has(memory.id)) {
+            return { allowed: false, reason: "seen_this_session" };
+        }
+        if (memory.ignored === true) {
+            return { allowed: false, reason: "ignored" };
+        }
+        if (memory.status !== undefined && memory.status !== "active") {
+            return { allowed: false, reason: "not_active" };
+        }
+        if (ctx.recurrenceCount > 0) {
+            return { allowed: false, reason: "recurrence" };
+        }
+        if (!memory.isActionable || memory.strength === "weak") {
+            if (qualityGateEnabled) {
+                return { allowed: false, reason: "weak" };
+            }
+            // K4-023 debug mode: weak lessons are admitted but must be
+            // flagged by the caller (ContextInjector adds the marker).
+        }
+        return { allowed: true, reason: "ok" };
+    },
+};

package/dist/Reflector.d.ts

@@ -0,0 +1,91 @@
+import type { MemoryService } from "./MemoryService.js";
+import type { Metrics } from "./metrics.js";
+export interface ReflectionInput {
+    toolName: string;
+    argsSummary: string;
+    stderr: string;
+    stdout: string;
+    exitCode?: number;
+    errorType: string;
+    sessionId: string;
+    /** Optional project scope for v0.2.0 dedup + per-fingerprint throttle. */
+    projectId?: string | null;
+    /** v0.3.0 fix — callID of the failing tool_call. Used by onLinkError
+     * (see ReflectorOptions) to stamp tool_calls.error_fingerprint so the
+     * feedback loop can match recurrences by the SAME identity dimension
+     * the error memory uses. */
+    callID?: string;
+}
+export interface ReflectorOptions {
+    throttleMs?: number;
+    /** v0.3.0 (K3-018) — optional LLM enrichment callback. Default no-op. */
+    enrich?: (lesson: string, stderr: string, stdout: string) => Promise<string | null>;
+    /** v0.3.0 fix — link a failing tool_call to the stderr-based fingerprint
+     * the matching error memory uses. Default no-op. The caller (index.ts)
+     * provides an implementation that UPDATEs tool_calls.error_fingerprint
+     * for the given callID, so boost/penalize feedback queries stop missing
+     * recurrences by fingerprint mismatch. */
+    onLinkError?: (callID: string, fingerprint: string) => void;
+}
+export interface HeuristicLessonInput {
+    toolName: string;
+    errorType: string;
+    /** v0.4.0 (K4-005) — errorType shown in the `fails with` slot after
+     * rescue: the dispatched code when one matched, else the coarse
+     * errorType. Suggestion lookup still uses `errorType` (the coarse
+     * category) so the category suggestion is kept even when a code
+     * overrides the display. */
+    displayErrorType?: string;
+    firstErrorLine: string;
+    /** v0.2.0 (K2-018) — optional pre-computed dispatch result. When absent,
+     * dispatch is performed on `firstErrorLine` alone. */
+    dispatched?: DispatchedLesson | null;
+}
+/** Result of the per-error-code deterministic rule dispatch (K2-018 / D2-09). */
+export interface DispatchedLesson {
+    /** Stable short code captured from the source output (e.g. `TS2304`,
+     * `EADDRINUSE`, `F401`, the captured `Error: <Name>` class, the failing
+     * command string). `null` when no rule matches (fallback path). */
+    code: string | null;
+    /** Short deterministic hint, e.g. `import or typo`, `review syscall:
+     * EADDRINUSE`. `null` when `code` is null (the v0.1.x fallback path). */
+    hint: string | null;
+}
+export declare const ERROR_LINE_RE: RegExp;
+export declare const STRONG_ERROR_RE: RegExp;
+/**
+ * v0.1.x fallback table — keyed by `errorType`. RETAINED in v0.2.0 as the
+ * fallback for memos whose output does not match a deterministic code rule.
+ * The v0.2.0 per-error-code rule table below layers ON TOP of this fallback:
+ * when a code is matched, the hint is appended to the v0.1.x suggestion as a
+ * 'Likely cause:' line; when no code is matched, output is identical to v0.1.x.
+ *
+ * Exported since v0.4.0 (K4-003) so QualityGate can detect the generic
+ * fallback suggestions without duplicating the strings.
+ */
+export declare const SUGGESTIONS: Record<string, string>;
+export declare const TS_CODE_RULES: Record<string, string>;
+export declare class Reflector {
+    private memoryService;
+    private lastReflectionByFp;
+    private throttleMs;
+    private metrics;
+    private enrichFn;
+    private onLinkErrorFn;
+    constructor(memoryService: MemoryService, options?: ReflectorOptions, metrics?: Metrics | null);
+    invoke(input: ReflectionInput): Promise<string | null>;
+    generateHeuristicLesson(input: HeuristicLessonInput): string;
+    /**
+     * v0.2.0 (K2-018 / D2-09) — deterministic per-error-code rule dispatch.
+     * Pure regex sweep over `stderr + '\n' + stdout` with NO LLM hop. Returns
+     * a short stable `code` + `hint` pair when a known rule matches, or
+     * `{ code: null, hint: null }` for the v0.1.x fallback path (which keeps
+     * the v0.1.x `SUGGESTIONS[errorType]` suggestion verbatim).
+     *
+     * Exported for unit testing (K2-019).
+     */
+    dispatchLesson(stderr: string, stdout: string, errorType: string): DispatchedLesson;
+    redactPaths(text: string): string;
+    redactSecrets(text: string): string;
+    private extractFirstErrorLine;
+}

package/dist/Reflector.js

@@ -0,0 +1,307 @@
+import { fingerprint as computeFingerprint } from "./fingerprint.js";
+import { classify } from "./inferability.js";
+import { redactPaths as redactPathsText } from "./redact.js";
+const DEFAULT_THROTTLE_MS = 60_000;
+const MAX_CONTENT_CHARS = 4096;
+const MAX_ERROR_LINE_CHARS = 500;
+const TRUNC_SUFFIX = "... [truncated]";
+const CONTEXT_PREFIX = "\n\nContext:\n";
+export const ERROR_LINE_RE = /\b(error|failed|fail|cannot find|cannot resolve|TS\d{4,}|exception|traceback|panic|fatal|referenceerror|typeerror|syntaxerror|command failed|non-zero exit)\b/i;
+export const STRONG_ERROR_RE = /\b(cannot find|cannot resolve|TS\d{4,}|error TS\d|command failed|non-zero exit|exit code [1-9]\d*|traceback|referenceerror|typeerror|syntaxerror|fatal error|exception|failed to compile|build failed|compilation failed)\b/i;
+/**
+ * v0.1.x fallback table — keyed by `errorType`. RETAINED in v0.2.0 as the
+ * fallback for memos whose output does not match a deterministic code rule.
+ * The v0.2.0 per-error-code rule table below layers ON TOP of this fallback:
+ * when a code is matched, the hint is appended to the v0.1.x suggestion as a
+ * 'Likely cause:' line; when no code is matched, output is identical to v0.1.x.
+ *
+ * Exported since v0.4.0 (K4-003) so QualityGate can detect the generic
+ * fallback suggestions without duplicating the strings.
+ */
+export const SUGGESTIONS = {
+    typecheck: "Verify types and imports before running.",
+    lint: "Run linter and fix warnings before committing.",
+    test: "Run tests and fix failures before proceeding.",
+    runtime: "Check error message and stack trace for root cause.",
+    timeout: "Check for infinite loops or long-running operations.",
+    unknown: "Review the error output for details.",
+};
+// --- v0.2.0 (K2-018) lesson v2 — per-error-code deterministic dispatch (D2-09).
+// Pure TS, NO LLM hop. Order of dispatch matches the plan §B6.4 priority list:
+// (1) TS\d{4,5} > (2) Python lint > (3) syscall > (4) generic `Error: <Name>` >
+// (5) `Command "<cmd>" failed` > (6) v0.1.x SUGGESTIONS fallback.
+// v0.2.0 (K2-018) — shared per-error-code rule table. Exported so
+// kevin_why.ts reuses the SAME hints instead of duplicating them
+// (bug #6).
+// v0.4.0 (K4-022 / plan §5.4, D4-07) — expanded with the observed §3.3
+// cases: TS2307 (cannot find module), TS2339/TS2305 (missing member),
+// TS6133 (unused).
+export const TS_CODE_RULES = {
+    "2304": "import or typo",
+    "2322": "type mismatch",
+    "2740": "missing or wrong property",
+    "2552": "undefined identifier",
+    "18047": "possibly null",
+    "2307": "install the dependency or add it to package.json before importing",
+    "2339": "check the imported surface for the correct member name",
+    "2305": "check the imported surface for the correct member name",
+    "6133": "remove the declaration or use it",
+};
+const TS_CODE_RE = /\bTS(\d{4,5})\b/i;
+const PY_LINT_RE = /\b(ELIF\d{0,4})\b|\b(F\d{3,4})\b|flake8:\s+(\S+)/;
+const SYSCALL_RE = /\b(EADDRINUSE|ENOENT|EACCES|EPERM)\b/;
+// v0.4.0 (K4-022) — rust unresolved item/module (E0433/E0432).
+const RUST_CODE_RE = /\b(E0433|E0432)\b/;
+// v0.4.0 (K4-022) — shell command-not-found (`cmd: command not found`,
+// `The term 'cmd' is not recognized ...`).
+const COMMAND_NOT_FOUND_RE = /\b([a-zA-Z0-9_.-]+):\s+(?:command not found|The term\s+['"][^'"]+['"]\s+is not recognized)\b/i;
+const GENERIC_ERROR_RE = /\bError:\s+(\w+)/;
+const COMMAND_FAILED_RE = /Command\s+"([^"]+)"\s+failed/;
+const SECRET_PATTERNS = [
+    /\b(API_KEY|SECRET|PASSWORD|TOKEN)\b\s*[=:]\s*\S+/gi,
+    /\bBearer\s+\S+/gi,
+    // BUG-013 — same narrowing as ToolCallObserver: the old
+    // `\btoken\s+\S+/gi` mangled harmless phrasing ("token budget",
+    // "token count") in stderr/stdout — corrupting stored summaries AND
+    // the fingerprints derived from the redacted text. Credential
+    // contexts only: named token variables WITH an assignment, and
+    // `token=<value>` / `token: <value>` assignments.
+    /\b(access_?token|auth_?token|api_?token)\b\s*[=:]\s*\S+/gi,
+    /\btoken\s*[=:]\s*\S+/gi,
+];
+const PATH_PATTERNS_DEPRECATED = null;
+export class Reflector {
+    memoryService;
+    lastReflectionByFp = new Map();
+    throttleMs;
+    metrics;
+    enrichFn;
+    onLinkErrorFn;
+    constructor(memoryService, options, metrics) {
+        this.memoryService = memoryService;
+        this.throttleMs = options?.throttleMs ?? DEFAULT_THROTTLE_MS;
+        this.metrics = metrics ?? null;
+        this.enrichFn = options?.enrich ?? (async () => null);
+        this.onLinkErrorFn = options?.onLinkError ?? (() => { });
+    }
+    async invoke(input) {
+        const now = Date.now();
+        const redactedStderr = this.redactSecrets(this.redactPaths(input.stderr));
+        const redactedStdout = this.redactSecrets(this.redactPaths(input.stdout));
+        const sourceOutput = redactedStderr.length > 0 ? redactedStderr : redactedStdout;
+        const firstErrorLine = this.extractFirstErrorLine(sourceOutput);
+        // v0.4.0 (K4-005) — dispatch once and reuse for the rescued
+        // errorType AND metadata.dispatch.
+        const dispatched = this.dispatchLesson(redactedStderr, redactedStdout, input.errorType);
+        const lesson = this.generateHeuristicLesson({
+            toolName: input.toolName,
+            errorType: input.errorType,
+            displayErrorType: dispatched.code ?? input.errorType,
+            firstErrorLine,
+            dispatched,
+        });
+        // v0.3.0 fix (bug #5) — the per-fingerprint throttle check runs
+        // BEFORE the optional LLM enrichment, so throttled repeats never
+        // waste an LLM call. The fingerprint is computed from the source
+        // output when present, otherwise from the PRE-enrichment lesson,
+        // keeping the identity stable and identical to the saved memory's.
+        const projectId = input.projectId ?? null;
+        const fpContent = sourceOutput.length > 0 ? sourceOutput : lesson;
+        const fp = computeFingerprint(fpContent, projectId ?? undefined);
+        // v0.3.0 fix — stamp the failing tool_call with the stderr-based
+        // fingerprint so the feedback loop's recurrence queries can match
+        // it (closes the fingerprint-mismatch bug). Runs BEFORE the
+        // throttle check: throttled repeats (K4-025 recurrences) still
+        // stamp — the throttle only skips the expensive enrichment/save,
+        // but the recurrence signal (settle's COUNT, QualityGate,
+        // penalizeRecurringReflectors) must see every failing call.
+        if (input.callID && this.onLinkErrorFn) {
+            try {
+                this.onLinkErrorFn(input.callID, fp);
+            }
+            catch {
+                // linking failure is non-blocking
+            }
+        }
+        const last = this.lastReflectionByFp.get(fp) ?? 0;
+        if (now - last < this.throttleMs) {
+            this.metrics?.incr("reflections_throttled", 1);
+            return null;
+        }
+        this.lastReflectionByFp.set(fp, now);
+        const configurableMemoryService = this.memoryService;
+        const lessonMode = configurableMemoryService.getSetting?.("error_lesson_mode", "all") ??
+            "all";
+        const verdict = classify({
+            type: "error",
+            content: lesson,
+            metadata: { dispatch: { code: dispatched.code, hint: dispatched.hint } },
+        });
+        if (lessonMode === "triage_only" && verdict === "inferable") {
+            this.metrics?.incr("error_lessons_suppressed", 1);
+            return null;
+        }
+        // v0.3.0 (K3-018): optional LLM enrichment opt-in. Runs only when
+        // the throttle check passed (bug #5).
+        let enrichedLesson = lesson;
+        try {
+            const enrichment = await this.enrichFn(lesson, redactedStderr, redactedStdout);
+            if (enrichment) {
+                enrichedLesson = `${lesson}\n${enrichment}`;
+            }
+        }
+        catch {
+            // enrichment failures are non-blocking
+        }
+        const metadata = {};
+        if (input.callID) {
+            metadata.origin_call_id = input.callID;
+        }
+        // v0.4.0 (K4-005) — persist the dispatch result so injection and
+        // promotion can reuse the rescued errorType and hint without
+        // re-dispatching. Stored even when no code matched ({code:null,hint:null})
+        // so callers can distinguish "checked and unmatched" from "absent".
+        metadata.dispatch = { code: dispatched.code, hint: dispatched.hint };
+        let finalContent;
+        if (sourceOutput.length > 0) {
+            const fullLen = enrichedLesson.length + CONTEXT_PREFIX.length + sourceOutput.length;
+            if (fullLen <= MAX_CONTENT_CHARS) {
+                finalContent = `${enrichedLesson}${CONTEXT_PREFIX}${sourceOutput}`;
+            }
+            else {
+                const budget = MAX_CONTENT_CHARS -
+                    enrichedLesson.length -
+                    CONTEXT_PREFIX.length -
+                    TRUNC_SUFFIX.length;
+                const truncated = sourceOutput.slice(0, Math.max(0, budget));
+                finalContent = `${enrichedLesson}${CONTEXT_PREFIX}${truncated}${TRUNC_SUFFIX}`;
+                metadata.truncated = true;
+            }
+        }
+        else {
+            finalContent = enrichedLesson;
+        }
+        // K2-007: the per-fingerprint throttle check ran above (before
+        // enrichment); `fp` is reused here so dedup/throttle and the saved
+        // memory agree on identity.
+        const id = this.memoryService.save({
+            type: "error",
+            content: finalContent,
+            scope: "project",
+            sourceTool: input.toolName,
+            sourceSession: input.sessionId,
+            metadata,
+            origin: "reflector",
+            projectId: projectId ?? undefined,
+            fingerprint: fp,
+        });
+        return id;
+    }
+    generateHeuristicLesson(input) {
+        const dispatched = input.dispatched ??
+            this.dispatchLesson(input.firstErrorLine, "", input.errorType);
+        const suggestion = SUGGESTIONS[input.errorType] ?? SUGGESTIONS.unknown;
+        const shownErrorType = input.displayErrorType ?? input.errorType;
+        const line = input.firstErrorLine.length > MAX_ERROR_LINE_CHARS
+            ? `${input.firstErrorLine.slice(0, MAX_ERROR_LINE_CHARS)}...`
+            : input.firstErrorLine;
+        let lesson = `When ${input.toolName} fails with ${shownErrorType}: ${line}\nSuggestion: ${suggestion}`;
+        if (dispatched.code && dispatched.hint) {
+            lesson += `\nLikely cause: ${dispatched.hint} (code ${dispatched.code})`;
+        }
+        return lesson;
+    }
+    /**
+     * v0.2.0 (K2-018 / D2-09) — deterministic per-error-code rule dispatch.
+     * Pure regex sweep over `stderr + '\n' + stdout` with NO LLM hop. Returns
+     * a short stable `code` + `hint` pair when a known rule matches, or
+     * `{ code: null, hint: null }` for the v0.1.x fallback path (which keeps
+     * the v0.1.x `SUGGESTIONS[errorType]` suggestion verbatim).
+     *
+     * Exported for unit testing (K2-019).
+     */
+    dispatchLesson(stderr, stdout, errorType) {
+        const combined = `${stderr}\n${stdout}`;
+        const tsMatch = combined.match(TS_CODE_RE);
+        if (tsMatch) {
+            const num = tsMatch[1];
+            const hint = TS_CODE_RULES[num] ?? `review TS${num}`;
+            return { code: `TS${num}`, hint };
+        }
+        const pyMatch = combined.match(PY_LINT_RE);
+        if (pyMatch) {
+            const rule = pyMatch[1] || pyMatch[2] || pyMatch[3] || "unknown";
+            return { code: rule, hint: `review python lint: ${rule}` };
+        }
+        const rustMatch = combined.match(RUST_CODE_RE);
+        if (rustMatch) {
+            const code = rustMatch[1];
+            return {
+                code,
+                hint: "add the dependency to Cargo.toml or use a full path (crate::...)",
+            };
+        }
+        const sysMatch = combined.match(SYSCALL_RE);
+        if (sysMatch) {
+            const code = sysMatch[1];
+            const hint = code === "EADDRINUSE"
+                ? "free the port (netstat -ano | findstr :PORT) or change the port"
+                : `review syscall: ${code}`;
+            return { code, hint };
+        }
+        const cmdNotFoundMatch = combined.match(COMMAND_NOT_FOUND_RE);
+        if (cmdNotFoundMatch) {
+            const cmd = cmdNotFoundMatch[1];
+            return {
+                code: cmd,
+                hint: `install the tool (e.g. npm i -g ${cmd}) or call it by its full path`,
+            };
+        }
+        const errMatch = combined.match(GENERIC_ERROR_RE);
+        if (errMatch) {
+            const name = errMatch[1];
+            return { code: name, hint: `review error class: ${name}` };
+        }
+        const cmdMatch = combined.match(COMMAND_FAILED_RE);
+        if (cmdMatch) {
+            const cmd = cmdMatch[1];
+            return { code: cmd, hint: `review failing command: ${cmd}` };
+        }
+        return { code: null, hint: null };
+    }
+    redactPaths(text) {
+        return redactPathsText(text);
+    }
+    redactSecrets(text) {
+        let out = text;
+        for (const pat of SECRET_PATTERNS) {
+            out = out.replace(pat, (match) => {
+                // BUG-013 — preserve the original separator so
+                // `auth_token = abc123` keeps its spacing: only the
+                // value is replaced.
+                const m = match.match(/^(.+?)(\s*[=:]\s*)(\S+)$/);
+                if (m) {
+                    return `${m[1]}${m[2]}<redacted>`;
+                }
+                const parts = match.split(/\s+/);
+                return `${parts[0]} <redacted>`;
+            });
+        }
+        return out;
+    }
+    extractFirstErrorLine(text) {
+        const lines = text.split(/\r?\n/);
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.length > 0 && ERROR_LINE_RE.test(trimmed)) {
+                return trimmed;
+            }
+        }
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.length > 0)
+                return trimmed;
+        }
+        return "";
+    }
+}

package/dist/RepoIdentity.d.ts

@@ -0,0 +1,124 @@
+import type { ArtifactWriter } from "./ArtifactWriter.js";
+import type { HostSurface } from "./host.js";
+/**
+ * The four sources `resolve()` tries, in order (plan §5.2, D9-13).
+ */
+export type IdentitySource = "declared" | "remote" | "host" | "path";
+/**
+ * The outcome of resolving a repository identity.
+ */
+export interface ResolvedIdentity {
+    /** The repository-scoped id every Team scope is keyed on. */
+    repoId: string;
+    /** Which source produced `repoId`. */
+    source: IdentitySource;
+    /**
+     * A short, non-secret description of how the id was derived,
+     * surfaced by `kevin_project show`. Never contains a credential
+     * or an absolute path.
+     */
+    evidence: string;
+    /** The v0.7.0 project scope, always returned regardless of source. */
+    projectId: string;
+}
+/**
+ * Read the first `url = …` value inside `[remote "<name>"]` of a
+ * `.git/config`-style INI text.
+ *
+ * Line-oriented reader, not an INI library: tracks the current
+ * `[section "sub"]` header, tolerates tabs, spaces around `=`,
+ * CRLF, and comment lines. Returns `null` on anything unrecognised
+ * and never throws — on any input, including binary.
+ */
+export declare function parseGitConfigRemote(text: string, name?: string): string | null;
+/**
+ * Fold the URL shapes git accepts into one canonical string.
+ *
+ * Steps, in order (K8-005):
+ *   1. strip a trailing `.git`;
+ *   2. strip a `scheme://` prefix;
+ *   3. strip everything up to and including the last `@` in the
+ *      authority (userinfo and embedded credentials — a token must
+ *      never reach a hash that lands in a committed file, D8-04);
+ *   4. strip a numeric port (`:8443`, `:443`, …) so the same repo
+ *      served over different transports folds to one id;
+ *   5. rewrite the scp-style `host:path` separator to `host/path`;
+ *   6. strip a trailing `/`;
+ *   7. lowercase the whole result.
+ *
+ * Returns `null` when the result contains no `/` (e.g. a local
+ * path remote) — the caller falls through to the path source.
+ */
+export declare function normalizeRemote(url: string): string | null;
+/**
+ * Derive a repository id from a normalized remote (K8-006).
+ *
+ * The domain prefix means a repo id can never collide with a memory
+ * fingerprint computed over the same string, and it leaves room to
+ * version the derivation later.
+ */
+export declare function computeRepoId(normalized: string): string;
+/**
+ * Resolve the repository identity for `cwd`, trying the four
+ * sources in order (plan §5.2, D9-13):
+ *
+ *   1. `declared` — `.kevin/project.json` → `id` (validated as
+ *      exactly 16 lowercase hex characters; anything else is ignored
+ *      and falls through, because a hand-edited garbage id in a
+ *      committed file would otherwise scope a whole team's corpus
+ *      onto a typo);
+ *   2. `remote` — `.git/config` → `[remote "origin"] url`,
+ *      normalized and hashed;
+ *   3. `host` — the value the host resolved for this directory,
+ *      `host.project.worktree` first, `host.project.directory` as
+ *      fallback; both empty or absent falls through to `path`.
+ *      This is strictly better than cwd — the host's own
+ *      ToolContext documents "prefer this over cwd" —
+ *      but it sits below the explicit sources, because monorepos and
+ *      D8-03's confirmed re-keying depend on `.kevin/project.json`
+ *      winning;
+ *   4. `path` — `fingerprint(cwd)`, the v0.7.0 behaviour, preserved
+ *      exactly when `host` is absent.
+ *
+ * Never throws: a directory that is not a git repository, an
+ * unreadable `.git/config`, a malformed `project.json`, and a host
+ * with no usable project fields all fall through to source 4.
+ * `projectId` is always returned alongside `repoId`, regardless of
+ * which source won.
+ */
+export declare function resolve(cwd: string, host?: HostSurface): ResolvedIdentity;
+/**
+ * The outcome of `initProjectFile` (K8-008).
+ */
+export interface InitProjectResult {
+    /** Whether the file was written. */
+    ok: boolean;
+    /** The absolute path the file was written to, or refused. */
+    path: string;
+    /** Human-readable refusal reason when `ok` is false. */
+    reason?: string;
+    /** The pinned id when the file was written. */
+    id?: string;
+    /** The ISO-8601 Z timestamp written into the file. */
+    createdAt?: string;
+}
+/**
+ * Write `.kevin/project.json` pinning the repository identity (K8-008
+ * / plan §5.8). The id comes from the current `resolve(cwd)` — so `init`
+ * in a repository with a remote *pins* the remote-derived id, which is
+ * the point: it survives the organisation renaming the repo (a remote
+ * URL change would otherwise silently re-scope the corpus).
+ *
+ * The file is `{"id": "<16 hex>", "created_at": "<ISO-8601 Z>",
+ * "generator": "opencode-kevin/0.8.0"}` with sorted keys and a
+ * terminating newline (deterministic bytes, the codec discipline of
+ * plan §7.3). `init` refuses when the file already exists: overwriting
+ * it re-scopes a team's corpus, and that is `rekey`'s job (K8-009),
+ * with a confirmation.
+ *
+ * NOTE (K8-019): the write goes through `ArtifactWriter` in whole-file
+ * mode — `.kevin/project.json` is a Kevin-owned file, and D8-08 leaves
+ * no scenario in which a second raw write path is acceptable (asserted
+ * by tests/unit/single_write_path.test.ts).
+ */
+export declare function initProjectFile(cwd: string, writer: ArtifactWriter): InitProjectResult;