reprobe 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,280 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { launchAgent } from "./agent.js";
+import { appendEvidence, caseDirFor, loadPack, readAgentReplay, readGathered } from "./case.js";
+import { assertCasesOutsideRepo, config, loadConfig } from "./config.js";
+import { caseIdFor, detect } from "./detectors.js";
+import { validateDiagnosis } from "./diagnosis.js";
+import { doctor } from "./doctor.js";
+import { retryingFetch } from "./exec.js";
+import { gather } from "./gather.js";
+import { writeInit } from "./init.js";
+import { narrate } from "./llm.js";
+import { redactText, redactValue } from "./redact.js";
+import { renderMarkdown } from "./report.js";
+import { fetchTrace, langfuseClient, parseLangfuseTrace } from "./sources/langfuse.js";
+import { gatherLangsmith, parseLangsmithShare } from "./sources/langsmith.js";
+import { gatherArchive, gatherLogs } from "./sources/logs.js";
+import { connect } from "./sources/postgres.js";
+import { gatherSentry } from "./sources/sentry.js";
+import { assertSafeCheckoutPath, assertSafeRelativePath, cleanWorktrees, verifyReplay } from "./verify.js";
+const USAGE = `reprobe "<complaint>" [--trace <langfuse|langsmith url or id>] [--user <id|phone|email>] [--chat <id>]
+        [--sentry <issue>] [--since 2h] [--at <iso>] [--agent claude|codex|none] [--model <m>] [--summary]
+    Gather evidence read-only, run the detectors, write a case, then hand it to your coding agent.
+
+reprobe agent <case> [--agent claude|codex] [--model <m>] [--headless]   (re)start the agent on a case
+reprobe init [--force]                                      detect sources and write .reprobe/config.json
+reprobe doctor                                              check every source with a real read
+
+Tools the agent uses (each appends citable evidence to the case):
+reprobe query <case> "<SELECT ...>"                        one read-only query
+reprobe logs <case> [--grep <text>]... [--since <iso>] [--until <iso>]
+reprobe sentry <case> [--issue <id>] [--user <id>]
+reprobe trace <case> <langfuse|langsmith url or id>
+reprobe verify <case> <commit>...                         run the replay in a detached worktree per commit
+reprobe report <case>                                      validate diagnosis.json citations, render report.md
+
+reprobe analyze <case>     re-run detectors and the report from the saved evidence, offline
+reprobe clean              remove reprobe's worktrees for this repo
+Global: --config <path to .reprobe/config.json>`;
+export function parseDuration(s) {
+    const m = s.trim().match(/^(\d+(?:\.\d+)?)\s*(m|min|h|d)$/i);
+    if (!m)
+        throw new Error(`bad duration "${s}" (use 30m, 2h, 3d)`);
+    return Number(m[1]) * { m: 60_000, min: 60_000, h: 3_600_000, d: 86_400_000 }[m[2].toLowerCase()];
+}
+const say = (s) => process.stderr.write(`reprobe: ${redactText(s)}\n`);
+const out = (s) => process.stdout.write(`${redactText(s)}\n`);
+export function formatDoctorCheck(c) {
+    return `${c.ok ? 'ok  ' : c.required ? 'FAIL' : 'MISS'} ${redactText(c.name)}: ${redactText(c.detail)}${c.fix && !c.ok ? `\n     fix: ${redactText(c.fix)}` : ''}\n`;
+}
+function caseReplay(dir, g, pack) {
+    return readAgentReplay(dir) ?? detect(g, pack).find((f) => f.replay)?.replay;
+}
+function readDiagnosis(dir, g) {
+    const file = join(dir, 'diagnosis.json');
+    return existsSync(file) ? redactValue(validateDiagnosis(JSON.parse(readFileSync(file, 'utf8')), new Set(g.evidence.map((e) => e.id)))) : null;
+}
+export function replayFingerprint(replay) {
+    return createHash('sha256').update(JSON.stringify(replay)).digest('hex');
+}
+export function readVerify(dir, replay) {
+    const file = join(dir, 'verify.json');
+    if (!existsSync(file))
+        return [];
+    const results = JSON.parse(readFileSync(file, 'utf8'));
+    const fingerprint = replayFingerprint(replay);
+    return results.filter((result) => result.replayFingerprint === fingerprint);
+}
+export function writeReplayFiles(dir, findings) {
+    for (const finding of findings) {
+        for (const file of finding.replay?.files ?? []) {
+            assertSafeRelativePath(file.path, 'replay file');
+            const target = assertSafeCheckoutPath(dir, join('replay', file.path));
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, file.content);
+        }
+    }
+}
+function write(dir, g, findings, narrative, verify) {
+    const caseId = caseIdFor(g);
+    const safe = redactValue({ g, findings, narrative, verify });
+    mkdirSync(dir, { recursive: true });
+    const evidencePath = assertSafeCheckoutPath(dir, 'evidence.json');
+    const findingsPath = assertSafeCheckoutPath(dir, 'findings.json');
+    const verifyPath = assertSafeCheckoutPath(dir, 'verify.json');
+    const reportPath = assertSafeCheckoutPath(dir, 'report.md');
+    writeFileSync(evidencePath, JSON.stringify(safe.g, null, 2));
+    writeFileSync(findingsPath, JSON.stringify({ caseId, subject: safe.g.subject, window: safe.g.window, sources: safe.g.sources, findings: safe.findings }, null, 2));
+    writeReplayFiles(dir, safe.findings);
+    writeFileSync(verifyPath, JSON.stringify(safe.verify, null, 2));
+    writeFileSync(reportPath, renderMarkdown(caseId, safe.g, safe.findings, safe.narrative, safe.verify, readDiagnosis(dir, safe.g)));
+}
+export async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            config: { type: 'string' },
+            trace: { type: 'string' },
+            user: { type: 'string' },
+            chat: { type: 'string' },
+            sentry: { type: 'string' },
+            reporter: { type: 'string' },
+            since: { type: 'string', default: '2h' },
+            until: { type: 'string' },
+            at: { type: 'string' },
+            out: { type: 'string' },
+            agent: { type: 'string' },
+            model: { type: 'string' },
+            summary: { type: 'boolean', default: false },
+            'no-llm': { type: 'boolean', default: false },
+            'no-agent': { type: 'boolean', default: false },
+            headless: { type: 'boolean', default: false },
+            verify: { type: 'string', multiple: true, default: [] },
+            grep: { type: 'string', multiple: true, default: [] },
+            issue: { type: 'string' },
+            force: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const [cmd, ...rest] = positionals;
+    if (values.help || !cmd)
+        return out(USAGE);
+    loadConfig(values.config);
+    if (cmd === 'init') {
+        const { path, detected } = writeInit(config.repo, values.force);
+        out(`wrote ${path}`);
+        for (const f of detected.found)
+            out(`  found: ${f}`);
+        for (const t of detected.todo)
+            out(`  todo:  ${t}`);
+        out('next: edit the todos, then `reprobe doctor`');
+        return;
+    }
+    const pack = await loadPack();
+    if (cmd === 'doctor') {
+        const { checks, ok } = await doctor(pack);
+        for (const c of checks)
+            process.stdout.write(formatDoctorCheck(c));
+        out(ok ? '\nrequired sources ready' : '\nrequired sources missing (see FAIL lines)');
+        process.exitCode = ok ? 0 : 1;
+        return;
+    }
+    if (cmd === 'clean')
+        return out(`removed ${(await cleanWorktrees()).length} worktree(s)`);
+    if (['agent', 'analyze', 'verify', 'report', 'query', 'logs', 'sentry', 'trace'].includes(cmd)) {
+        if (!rest[0])
+            throw new Error(`${cmd} needs a case dir`);
+        const dir = caseDirFor(rest[0]);
+        assertCasesOutsideRepo(dir, config.repo);
+        const g = readGathered(dir);
+        const add = (items, show = (e) => `${e.at ?? '-'}  ${e.summary}`) => {
+            const saved = appendEvidence(dir, items);
+            if (!items.length)
+                out('(nothing found)');
+            for (const e of redactValue(saved))
+                out(`[${e.id}] ${show(e)}`);
+        };
+        switch (cmd) {
+            case 'agent': {
+                process.exitCode = await launchAgent(dir, g, detect(g, pack), { agent: values.agent, model: values.model, headless: values.headless });
+                return;
+            }
+            case 'analyze': {
+                const findings = detect(g, pack);
+                const replay = caseReplay(dir, g, pack);
+                write(dir, g, findings, values.summary ? await narrate(g, findings) : null, replay ? readVerify(dir, replay) : []);
+                return out(join(dir, 'report.md'));
+            }
+            case 'verify': {
+                const replay = caseReplay(dir, g, pack);
+                if (!replay)
+                    throw new Error('this case has no replay: write replay.json (see the playbook) or let a detector produce one');
+                const verifyPath = assertSafeCheckoutPath(dir, 'verify.json');
+                const results = await verifyReplay(dir, replay, rest.slice(1), pack, say);
+                const fingerprint = replayFingerprint(replay);
+                const kept = [...readVerify(dir, replay).filter((v) => !results.some((r) => r.sha === v.sha)), ...results]
+                    .map((result) => ({ ...result, replayFingerprint: fingerprint }));
+                writeFileSync(verifyPath, JSON.stringify(redactValue(kept), null, 2));
+                for (const v of results)
+                    out(`${v.commit} ${v.sha.slice(0, 10)} ${v.outcome.toUpperCase()} ${v.detail}\n  log: ${v.logFile}`);
+                return;
+            }
+            case 'report': {
+                const findings = detect(g, pack);
+                const replay = caseReplay(dir, g, pack);
+                write(dir, g, findings, null, replay ? readVerify(dir, replay) : []);
+                const d = readDiagnosis(dir, g);
+                out(join(dir, 'report.md'));
+                if (!d)
+                    out('no diagnosis.json yet: only detector findings are in the report');
+                else
+                    out(`diagnosis: ${d.rootCause ? `[${d.rootCause.confidence}] ${d.rootCause.text.slice(0, 160)}` : 'no root cause survived citation checks'}; ${d.dropped.length} claim(s) dropped`);
+                return;
+            }
+            case 'query': {
+                const sql = rest[1];
+                if (!sql)
+                    throw new Error('query needs SQL');
+                const { db, status } = await connect();
+                if (!db)
+                    throw new Error(`postgres: ${status.detail}`);
+                const rows = await db.query(sql);
+                const id = `query:${createHash('sha256').update(sql).digest('hex').slice(0, 10)}`;
+                add([{ id, source: 'query', at: null, kind: 'query.rows', summary: `${rows.length} row(s) for: ${sql.replace(/\s+/g, ' ').slice(0, 160)}`, data: { sql, rows: rows.slice(0, 200), truncated: rows.length > 200 } }], (e) => e.summary);
+                out(JSON.stringify(redactValue(rows.slice(0, 50)), null, 1).slice(0, 20_000));
+                return;
+            }
+            case 'logs': {
+                const w = { from: values.since && /^\d{4}-/.test(values.since) ? values.since : g.window.from, to: values.until ?? g.window.to };
+                const ids = values.grep.length ? values.grep : [g.subject.userId, ...g.subject.sessionIds].filter((x) => Boolean(x));
+                const results = [...(await gatherLogs(w, ids)), await gatherArchive(w, ids)];
+                for (const r of results)
+                    if (r.status.state !== 'ok')
+                        say(`${r.status.source} ${r.status.state}: ${r.status.detail}`);
+                const lines = results.flatMap((r) => r.evidence).filter((e) => !values.grep.length || values.grep.some((t) => JSON.stringify(e.data).includes(t)));
+                return add(lines);
+            }
+            case 'sentry': {
+                const r = await gatherSentry({ window: g.window, userId: values.user ?? g.subject.userId, issue: values.issue });
+                if (r.status.state !== 'ok')
+                    say(`sentry ${r.status.state}: ${r.status.detail}`);
+                return add(r.evidence);
+            }
+            case 'trace': {
+                const ref = rest[1];
+                if (!ref)
+                    throw new Error('trace needs a Langfuse or LangSmith url or id');
+                const lfId = parseLangfuseTrace(ref);
+                const share = lfId ? null : parseLangsmithShare(ref);
+                if (lfId) {
+                    const lf = await langfuseClient();
+                    if (!lf)
+                        throw new Error('langfuse is not configured or its keys did not resolve');
+                    const r = await fetchTrace(lf, lfId, pack?.observation);
+                    if (r.status.state !== 'ok')
+                        say(`langfuse ${r.status.state}: ${r.status.detail}`);
+                    return add(r.evidence);
+                }
+                if (!share)
+                    throw new Error('not a Langfuse trace or a LangSmith share link');
+                const r = await gatherLangsmith(share, retryingFetch());
+                if (r.status.state !== 'ok')
+                    say(`langsmith ${r.status.state}: ${r.status.detail}`);
+                return add(r.evidence);
+            }
+        }
+    }
+    const g = await gather({ complaint: cmd, trace: values.trace, user: values.user, chat: values.chat, sentry: values.sentry, reporter: values.reporter, at: values.at, sinceMs: parseDuration(values.since) }, pack, say);
+    const dir = resolve(values.out ?? config.casesDir, caseIdFor(g));
+    assertCasesOutsideRepo(dir, config.repo);
+    const findings = detect(g, pack);
+    const summary = values.summary && !values['no-llm'] ? (say('asking the LLM for a cited summary'), await narrate(g, findings)) : null;
+    const replay = findings.find((f) => f.replay)?.replay;
+    mkdirSync(dir, { recursive: true });
+    const verify = values.verify.length && replay
+        ? (await verifyReplay(dir, replay, values.verify, pack, say)).map((result) => ({ ...result, replayFingerprint: replayFingerprint(replay) }))
+        : [];
+    write(dir, g, findings, summary, verify);
+    const top = findings[0];
+    out(join(dir, 'report.md'));
+    out(top ? `top: [${top.confidence}] ${top.title}${top.replay ? `\nreplay: ${top.replay.files.map((f) => f.path).join(', ')}` : ''}` : 'no signature matched');
+    for (const v of verify)
+        out(`verify ${v.commit}: ${v.outcome.toUpperCase()} ${v.detail}`);
+    const wantAgent = !values['no-agent'] && values.agent !== 'none' && process.stdin.isTTY && process.stdout.isTTY;
+    if (wantAgent)
+        process.exitCode = await launchAgent(dir, g, findings, { agent: values.agent, model: values.model });
+    else
+        out(`next: reprobe agent ${dir}`);
+}
+const fail = (e) => {
+    process.stderr.write(`reprobe: ${redactText(e?.message ?? String(e))}\n`);
+    process.exitCode = 2;
+};
+export const run = (argv) => main(argv).catch(fail);
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url))
+    void run(process.argv.slice(2));

package/dist/config.d.ts

@@ -0,0 +1,100 @@
+import { type Runner } from './exec.ts';
+/**
+ * Where a credential comes from. Config files hold references, never values:
+ * - "env:NAME" reads an environment variable.
+ * - { cmd: [...] } runs a command (no shell) and takes its stdout; `json` or `kv` picks one key from it.
+ *   "{repo}" in an argument is replaced with the repo path.
+ */
+export type SecretRef = string | {
+    cmd: string[];
+    cwd?: string;
+    json?: string;
+    kv?: string;
+};
+export type LogSource = {
+    name: string;
+    railway: {
+        service: string;
+        cwd?: string;
+    };
+}
+/** Any CLI that prints log lines: fly logs, vercel logs, kubectl logs, docker logs. "{since}"/"{until}" are ISO times. */
+ | {
+    name: string;
+    command: string[];
+    cwd?: string;
+} | {
+    name: string;
+    file: string;
+};
+export type SetupStep = 
+/** Install node_modules for this directory once per lockfile hash, cached outside the worktree, then symlink it in.
+ *  Like every step, it runs only for replays whose cwd is inside its directory. */
+{
+    nodeModules: string;
+} | {
+    cwd: string;
+    run: string[];
+};
+export interface FileConfig {
+    repo?: string;
+    reporter?: string;
+    pack?: string;
+    sources?: {
+        postgres?: {
+            url: SecretRef;
+        };
+        langfuse?: {
+            baseUrl: SecretRef;
+            publicKey: SecretRef;
+            secretKey: SecretRef;
+        };
+        sentry?: {
+            org: string;
+            projects: string[];
+            url?: string;
+        };
+        logs?: LogSource[];
+        /** Log-shaped tool output in saved Claude Code transcripts: a fallback once live logs have expired. */
+        archive?: {
+            dir: string;
+            glob: string;
+        };
+    };
+    verify?: {
+        setup?: SetupStep[];
+        allow?: string[];
+    };
+}
+export interface Config extends Required<Pick<FileConfig, 'sources'>> {
+    /** The config file, or null when running without one. */
+    file: string | null;
+    /** The code checkout that replays run against (in detached worktrees, never in place). */
+    repo: string;
+    reporter?: string;
+    pack: string | null;
+    cacheDir: string;
+    casesDir: string;
+    llmModel: string;
+    verify: {
+        setup: SetupStep[];
+        allow: string[];
+    };
+}
+/**
+ * Case evidence must never be committable: outside every git work tree, or at a path git ignores.
+ * Symlink aliases are resolved first.
+ */
+export declare function assertCasesOutsideRepo(casesPath: string, repoPath: string): void;
+/** --config, then REPROBE_CONFIG, then .reprobe/config.json at the top of the current git repo. */
+export declare function findConfigFile(flag?: string, cwd?: string, env?: NodeJS.ProcessEnv): string | null;
+export declare function buildConfig(file: string | null, raw: FileConfig, cwd?: string, env?: NodeJS.ProcessEnv): Config;
+export declare let config: Config;
+export declare function loadConfig(flag?: string): Config;
+/** Tests and packs set config directly. */
+export declare function setConfig(c: Config): void;
+export declare function resolveSecret(ref: SecretRef | undefined, runner?: Runner): Promise<{
+    value: string | null;
+    detail: string;
+}>;
+export declare function firstLine(s: string): string;

package/dist/config.js

@@ -0,0 +1,149 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { run } from "./exec.js";
+import { redactText } from "./redact.js";
+const expand = (p, base) => {
+    const home = p === '~' || p.startsWith('~/') ? join(homedir(), p.slice(1)) : p;
+    return isAbsolute(home) ? home : resolve(base, home);
+};
+function canonicalPath(p) {
+    const abs = resolve(p);
+    if (existsSync(abs))
+        return realpathSync(abs);
+    const parent = dirname(abs);
+    return parent === abs ? abs : join(canonicalPath(parent), basename(abs));
+}
+function containingGitTop(path) {
+    let cursor = canonicalPath(path);
+    while (!existsSync(cursor)) {
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            return null;
+        cursor = parent;
+    }
+    try {
+        return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: cursor, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Case evidence must never be committable: outside every git work tree, or at a path git ignores.
+ * Symlink aliases are resolved first.
+ */
+export function assertCasesOutsideRepo(casesPath, repoPath) {
+    const cases = canonicalPath(casesPath);
+    const repo = canonicalPath(repoPath);
+    const rel = relative(repo, cases);
+    const inConfiguredRepo = rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+    const top = inConfiguredRepo ? repo : containingGitTop(cases);
+    if (top && !gitIgnores(top, cases)) {
+        throw new Error(`case directory must be outside the repo or ignored by git (${casesPath})`);
+    }
+}
+function gitIgnores(top, path) {
+    try {
+        execFileSync('git', ['-C', top, 'check-ignore', '-q', '--no-index', '--', path], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function gitTop(cwd) {
+    try {
+        return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** --config, then REPROBE_CONFIG, then .reprobe/config.json at the top of the current git repo. */
+export function findConfigFile(flag, cwd = process.cwd(), env = process.env) {
+    if (flag)
+        return resolve(cwd, flag);
+    if (env.REPROBE_CONFIG)
+        return resolve(cwd, env.REPROBE_CONFIG);
+    const top = gitTop(cwd);
+    const candidate = top ? join(top, '.reprobe/config.json') : null;
+    return candidate && existsSync(candidate) ? candidate : null;
+}
+export function buildConfig(file, raw, cwd = process.cwd(), env = process.env) {
+    const base = file ? (basename(dirname(file)) === '.reprobe' ? dirname(dirname(file)) : dirname(file)) : cwd;
+    const repo = raw.repo ? expand(raw.repo, base) : (gitTop(base) ?? base);
+    const cacheDir = env.REPROBE_CACHE_DIR ? expand(env.REPROBE_CACHE_DIR, cwd) : join(homedir(), '.cache/reprobe');
+    const sources = raw.sources ?? {};
+    const casesDir = join(env.REPROBE_CASES_DIR ? expand(env.REPROBE_CASES_DIR, cwd) : join(homedir(), '.reprobe/cases'), basename(repo));
+    return {
+        file,
+        repo,
+        reporter: env.REPROBE_REPORTER ?? raw.reporter,
+        pack: raw.pack ? expand(raw.pack, file ? dirname(file) : cwd) : null,
+        cacheDir,
+        casesDir,
+        llmModel: env.REPROBE_LLM_MODEL ?? 'sonnet',
+        sources: {
+            ...sources,
+            archive: sources.archive ? { ...sources.archive, dir: expand(sources.archive.dir, base) } : undefined,
+        },
+        verify: { setup: raw.verify?.setup ?? [], allow: raw.verify?.allow ?? [] },
+    };
+}
+export let config = buildConfig(null, {});
+export function loadConfig(flag) {
+    const file = findConfigFile(flag);
+    const raw = file ? JSON.parse(readFileSync(file, 'utf8')) : {};
+    config = buildConfig(file, raw);
+    secretCache.clear();
+    return config;
+}
+/** Tests and packs set config directly. */
+export function setConfig(c) {
+    config = c;
+    secretCache.clear();
+}
+const secretCache = new Map();
+export async function resolveSecret(ref, runner = run) {
+    if (!ref)
+        return { value: null, detail: 'not configured' };
+    if (typeof ref === 'string') {
+        if (!ref.startsWith('env:'))
+            return { value: ref, detail: 'inline value in config' };
+        const v = process.env[ref.slice(4)];
+        return v ? { value: v, detail: ref } : { value: null, detail: `${ref.slice(4)} is not set` };
+    }
+    const key = JSON.stringify(ref);
+    const cached = secretCache.get(key);
+    if (cached)
+        return { value: cached, detail: `\`${ref.cmd[0]}\`` };
+    const args = ref.cmd.slice(1).map((a) => a.replaceAll('{repo}', config.repo));
+    const r = await runner(ref.cmd[0], args, { cwd: ref.cwd ? expand(ref.cwd, config.repo) : config.repo, timeoutMs: 30_000 });
+    if (r.code === 127)
+        return { value: null, detail: `${ref.cmd[0]} is not installed` };
+    if (r.code !== 0)
+        return { value: null, detail: `${ref.cmd[0]} failed: ${firstLine(r.stderr || r.stdout)}` };
+    let value = r.stdout.trim();
+    if (ref.json) {
+        try {
+            const v = JSON.parse(value)[ref.json];
+            value = typeof v === 'string' && v ? v : null;
+        }
+        catch {
+            value = null;
+        }
+    }
+    else if (ref.kv) {
+        const line = r.stdout.split('\n').find((l) => l.startsWith(`${ref.kv}=`));
+        value = line ? line.slice(ref.kv.length + 1).trim() : null;
+    }
+    if (!value)
+        return { value: null, detail: `${ref.cmd[0]} returned no ${ref.json ?? ref.kv ?? 'value'}` };
+    secretCache.set(key, value);
+    return { value, detail: `\`${ref.cmd[0]}\`` };
+}
+export function firstLine(s) {
+    return redactText((s.split('\n').find((l) => l.trim() && !/Config as Code|Migrate:|Existing files keep/.test(l)) ?? '').trim()).slice(0, 200);
+}

package/dist/detectors.d.ts

@@ -0,0 +1,8 @@
+import type { Detector, Evidence, Finding, Gathered, Pack } from './types.ts';
+export declare const ms: (s: string | null) => number;
+export declare const d: <T>(e: Evidence) => T;
+export declare const byStableTime: (a: Evidence, b: Evidence) => number;
+export declare function caseIdFor(g: Gathered): string;
+export declare function routeTemplate(path: string): string;
+export declare const CORE_DETECTORS: Detector[];
+export declare function detect(g: Gathered, pack?: Pack | null): Finding[];

package/dist/detectors.js

@@ -0,0 +1,136 @@
+import { createHash } from 'node:crypto';
+import { parseIntent } from "./gather.js";
+export const ms = (s) => {
+    if (!s)
+        return NaN;
+    const normalized = /^\d{4}-\d\d-\d\dT\d\d:\d\d(?::\d\d(?:\.\d+)?)?$/.test(s) ? `${s}Z` : s;
+    return Date.parse(normalized);
+};
+export const d = (e) => e.data;
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export const byStableTime = (a, b) => {
+    const atA = ms(a.at);
+    const atB = ms(b.at);
+    return (Number.isFinite(atA) && Number.isFinite(atB) ? atA - atB : cmp(a.at ?? '', b.at ?? '')) || cmp(a.id, b.id);
+};
+export function caseIdFor(g) {
+    const h = createHash('sha256').update(JSON.stringify([g.input.complaint, g.input.trace ?? '', g.input.user ?? '', g.input.chat ?? '', g.window.to])).digest('hex');
+    return `${g.window.to.slice(0, 10)}-${h.slice(0, 6)}`;
+}
+export function routeTemplate(path) {
+    return path
+        .split('?')[0]
+        .replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '/:id')
+        .replace(/\/c[a-z0-9]{24}\b/g, '/:id')
+        .replace(/\/\d+(?=\/|$)/g, '/:n');
+}
+// ── A deliberate 4xx turned into a 500 (Nest/Spring-style `*Exception` names) ────────────────────────────────────
+const CLIENT_EXCEPTIONS = /\b(BadRequest|Unauthorized|Forbidden|NotFound|Conflict|Gone|PayloadTooLarge|UnprocessableEntity|PreconditionFailed|UnsupportedMediaType)Exception: ([^|]+?)\s*(?:\||$)/;
+const maskedClientError = ({ ev, intent }) => {
+    const lines = ev.filter((e) => e.source === 'logs' || e.source === 'archive');
+    const failed = lines.filter((e) => (d(e).status ?? 0) >= 500 && d(e).path);
+    const groups = new Map();
+    for (const e of lines) {
+        const m = d(e).text.match(CLIENT_EXCEPTIONS);
+        if (!m)
+            continue;
+        const near = failed.filter((f) => {
+            const delta = Math.abs(ms(f.at) - ms(e.at));
+            if (!Number.isFinite(delta) || delta > 2_000)
+                return false;
+            const matches = lines.flatMap((candidate) => {
+                const match = d(candidate).text.match(CLIENT_EXCEPTIONS);
+                const timeDelta = Math.abs(ms(f.at) - ms(candidate.at));
+                return match && Number.isFinite(timeDelta) && timeDelta <= 2_000 ? [`${match[1]} ${match[2]}`] : [];
+            });
+            return new Set(matches).size === 1 && matches[0] === `${m[1]} ${m[2]}`;
+        });
+        if (!near.length)
+            continue;
+        if (new Set(near.map((n) => `${d(n).method} ${routeTemplate(d(n).path)}`)).size !== 1)
+            continue;
+        const http = d(near[0]);
+        const route = routeTemplate(http.path);
+        const key = `${http.method} ${route} ${m[1]} ${m[2]}`;
+        const g = groups.get(key) ?? { exc: e, name: `${m[1]}Exception`, message: m[2].replace(/\s+\(\+\d+ms\)$/, ''), route, method: http.method ?? '?', hits: [], triggers: [] };
+        for (const n of near)
+            if (!g.hits.includes(n))
+                g.hits.push(n);
+        for (const w of lines) {
+            if (d(w).level === 'warn' && ms(w.at) <= ms(e.at) && ms(e.at) - ms(w.at) <= 1_000 && !g.triggers.includes(w))
+                g.triggers.push(w);
+        }
+        groups.set(key, g);
+    }
+    const out = [];
+    for (const g of groups.values()) {
+        const attempts = g.hits.length;
+        const subjects = new Set(g.hits.map((h) => d(h).path)).size;
+        const trigger = g.triggers.slice().sort(byStableTime)[0];
+        const cited = [g.exc.id, ...g.hits.map((h) => h.id), ...g.triggers.slice(0, 3).map((t) => t.id)];
+        const retriesNote = intent.retries ? ` The complaint says the user tried ${intent.retries} time(s); the logs show ${attempts} failed attempt(s) on ${subjects} distinct ${subjects === 1 ? 'resource' : 'resources'}.` : '';
+        const orderedHits = [...g.hits].sort(byStableTime);
+        out.push({
+            signature: 'client-error-masked-as-500',
+            title: `${g.method} ${g.route} answered 500 for a deliberate ${g.name}`,
+            confidence: 'high',
+            rootCause: `A ${g.name} ("${g.message}") and HTTP 500 evidence occur within two seconds on ${g.method} ${g.route} ` +
+                `(${attempts} matching response(s), ${orderedHits[0].at ?? 'time unknown'} to ${orderedHits.at(-1)?.at ?? 'time unknown'}). The available rows do not establish a shared request ID.` +
+                (trigger ? ` A nearby warning says: "${d(trigger).text.replace(/^.*?\b(?:LOG|ERROR|WARN|DEBUG|VERBOSE)\s+\[[^\]]+\]\s*/, '').slice(0, 200)}".` : '') +
+                ` Likely cause, which the replay tests: the handler turns this deliberate ${g.name} into a 500, which a client usually shows as a generic, retryable failure, so the user retries a rejection that can never succeed.` +
+                retriesNote,
+            evidence: cited,
+            unknowns: [
+                'whether the exception and HTTP 500 share a request ID; only route and timing co-occurrence are available',
+                'the request body the client sent (the server does not log it), so why the client built that request is not observable here',
+            ],
+        });
+    }
+    return out;
+};
+// ── Everything else that looks wrong, without a signature ─────────────────
+const anomalies = ({ ev }) => {
+    const kinds = [
+        ['agent run failed', (e) => e.kind === 'agent.run' && /FAILED|CANCELLED/.test(e.summary)],
+        ['chat turn marked run_failed', (e) => e.kind === 'chat.user' && e.summary.includes('RUN FAILED')],
+        ['Langfuse span at ERROR level', (e) => e.source === 'langfuse' && e.summary.includes('level ERROR')],
+        ['server 5xx', (e) => e.kind === 'http.5xx'],
+        ['server error log', (e) => e.kind === 'log.error'],
+        ['Sentry issue', (e) => e.kind === 'sentry.issue'],
+        ['in-app bug report', (e) => e.kind === 'bug.report'],
+    ];
+    const out = [];
+    for (const [title, match] of kinds) {
+        const hits = ev.filter(match);
+        if (!hits.length)
+            continue;
+        out.push({
+            signature: `anomaly:${title.replace(/\s+/g, '-').toLowerCase()}`,
+            title: `${hits.length} × ${title}`,
+            confidence: 'low',
+            rootCause: `Seen in the window but not matched to a known failure signature: ${hits.slice(0, 3).map((h) => h.summary.slice(0, 120)).join(' | ')}`,
+            evidence: hits.slice(0, 10).map((h) => h.id),
+            unknowns: [],
+        });
+    }
+    return out;
+};
+export const CORE_DETECTORS = [maskedClientError, anomalies];
+const RANK = { high: 0, medium: 1, low: 2 };
+export function detect(g, pack = null) {
+    const ev = [...g.evidence].sort(byStableTime);
+    const ctx = { g, intent: parseIntent(g.input.complaint), caseId: caseIdFor(g), ev };
+    const all = [...(pack?.detectors ?? []), ...CORE_DETECTORS].flatMap((det) => det(ctx)).map((f) => (f.replay || !pack?.replayFor ? f : { ...f, replay: pack.replayFor(f, ctx) }));
+    const signatures = new Set(all.filter((f) => !f.signature.startsWith('anomaly:')).flatMap((f) => f.evidence));
+    return all
+        .map((f) => {
+        if (!f.signature.startsWith('anomaly:'))
+            return f;
+        const evidence = f.evidence.filter((id) => !signatures.has(id));
+        const hits = evidence.map((id) => ev.find((e) => e.id === id)).filter((e) => Boolean(e));
+        const suffix = f.signature.slice('anomaly:'.length).replace(/-/g, ' ');
+        return { ...f, title: `${evidence.length} × ${suffix}`, rootCause: `Seen in the window but not matched to a known failure signature: ${hits.slice(0, 3).map((h) => h.summary.slice(0, 120)).join(' | ')}`, evidence };
+    })
+        .filter((f) => f.evidence.length)
+        .sort((a, b) => RANK[a.confidence] - RANK[b.confidence] || b.evidence.length - a.evidence.length || (a.signature < b.signature ? -1 : a.signature > b.signature ? 1 : 0));
+}