codehere 0.7.1 → 1.0.1

package/dist/application/use-cases/generate-acceptance-criteria.js

@@ -0,0 +1,223 @@
+/**
+ * Acceptance-criteria agent — REQUEST_METHOD.md stage 2 (the Contract), the
+ * keystone of the request method.
+ *
+ * Before an agent runs, derive 2-5 testable acceptance criteria from the
+ * request: the up-front, checkable definition of "done" that verify (stage 5)
+ * later grades AGAINST, instead of judging the result post-hoc. This is the one
+ * change that turns "route a prompt and audit it after" into "make the agent
+ * work to a contract and prove it met it."
+ *
+ * Mirrors generate-thread-title.ts: single-shot, no streaming, `claude --bare`,
+ * ~1 cheap call, degrades SILENTLY to [] when no provider responds (a request
+ * with no contract still runs — the method is additive, never a hard gate here).
+ */
+import { spawn } from 'child_process';
+import { isMockMode } from '../../infrastructure/orchestration/mocks/resolve-agent-spawn.js';
+const CRITERIA_TIMEOUT_MS = 15_000;
+const MAX_CRITERIA = 5;
+const PROMPT_TEMPLATE = (firstPrompt, cwd) => `Generate 2 to 5 acceptance criteria for this coding request. Each criterion is one short, testable statement of what "done" means — something a reviewer could check pass/fail.
+
+Working directory: ${cwd}
+Request: ${firstPrompt}
+
+Rules:
+- 2 to 5 criteria, ONE per line
+- Each is a checkable OUTCOME (e.g. "greet() throws a TypeError when name is not a string"), not a step and not a vibe
+- Ground each in the request only; do not invent scope
+- No numbering, no bullets, no preamble, no trailing period
+- Output ONLY the criteria, one per line
+
+Criteria:`;
+/**
+ * Parse model output into criteria. Rejects refusal/error-shaped lines (the
+ * `claude --bare` call can return rate-limit / auth text on stdout with exit 0,
+ * same failure mode the title agent guards against).
+ */
+export function sanitizeCriteria(raw) {
+    const bad = /\b(i cannot|i can'?t|i apologi[sz]e|i'?m sorry|as an ai|rate.?limit|unauthorized|request id|api key)\b/i;
+    return String(raw || '')
+        .split('\n')
+        .map((l) => l.replace(/^[\s\-*•–>#\d.)\]]+/, '').trim())
+        .filter((l) => l.length >= 3 && l.length <= 140 && !bad.test(l))
+        .slice(0, MAX_CRITERIA)
+        .map((text) => ({ text, met: null }));
+}
+/**
+ * The scaling principle (REQUEST_METHOD §"no ceremony tax"): a trivial ask gets
+ * no contract. Trivial = very short, or a short read-only lookup. Everything
+ * else earns a contract. Keeps "just type and go" free for simple requests and
+ * skips the per-request LLM call where it would only be noise.
+ */
+export function isTrivialRequest(prompt) {
+    const p = String(prompt || '')
+        .trim()
+        .toLowerCase();
+    if (!p)
+        return true;
+    const words = p.split(/\s+/).filter(Boolean).length;
+    if (words <= 3)
+        return true;
+    if (words <= 6 && /^(list|ls|show|cat|print|echo|pwd|help|read|open|what is|what'?s)\b/.test(p))
+        return true;
+    return false;
+}
+/** Deterministic mock: grounded-enough criteria for demos + tests, no LLM. */
+export function mockCriteria(firstPrompt) {
+    const p = String(firstPrompt || '').toLowerCase();
+    const out = [];
+    if (/rate.?limit|throttle/.test(p))
+        out.push('The rate limit is enforced under load');
+    if (/throw|error|validation|validate|guard|invalid/.test(p))
+        out.push('Invalid input is rejected with a clear error');
+    if (/test/.test(p))
+        out.push('Tests are added and pass');
+    if (!out.length)
+        out.push('The change does what the request asked', 'No existing behaviour regresses');
+    return out.slice(0, MAX_CRITERIA).map((text) => ({ text, met: null }));
+}
+function selectProviderBinary() {
+    const override = process.env.CODEHERE_CRITERIA_BINARY;
+    if (override)
+        return [override];
+    return ['claude'];
+}
+const GRADE_PROMPT = (criteria, ctx) => `You are grading whether a coding task met its acceptance criteria. For EACH criterion, answer strictly MET or UNMET based only on the evidence. If the evidence does not clearly show a criterion was met, answer UNMET (never guess "met").
+
+Request: ${ctx.prompt}
+Result summary: ${ctx.reportSummary || '(none)'}
+Files changed: ${(ctx.files || []).join(', ') || '(none)'}
+
+Criteria (one per line):
+${criteria.map((c, i) => `${i + 1}. ${c.text}`).join('\n')}
+
+Output exactly one line per criterion, in order, each "MET" or "UNMET" — nothing else.`;
+/** Parse "MET/UNMET" lines back onto the criteria, in order. */
+export function applyGrades(criteria, raw) {
+    const verdicts = String(raw || '')
+        .split('\n')
+        .map((l) => l.trim().toUpperCase())
+        .filter((l) => l === 'MET' || l === 'UNMET');
+    return criteria.map((c, i) => {
+        const v = verdicts[i];
+        return { text: c.text, met: v === 'MET' ? true : v === 'UNMET' ? false : (c.met ?? null) };
+    });
+}
+/**
+ * Deterministic mock grade — honest by the same rule as the real one: a
+ * criterion is met ONLY if the run was verified AND the criterion's salient
+ * terms show up in the result; otherwise unmet. No fake green.
+ */
+export function mockGrade(criteria, ctx) {
+    const hay = ((ctx.reportSummary || '') + ' ' + (ctx.files || []).join(' ')).toLowerCase();
+    return criteria.map((c) => {
+        if (!ctx.verdictGreen)
+            return { text: c.text, met: false };
+        const terms = c.text
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((w) => w.length > 4);
+        const hit = terms.filter((t) => hay.includes(t)).length;
+        return { text: c.text, met: hit >= Math.max(1, Math.ceil(terms.length * 0.3)) };
+    });
+}
+/**
+ * Grade the contract against the result (REQUEST_METHOD stage 5). Runs at
+ * completion. Real path is a small single-shot assessment; folding this into
+ * the existing final-report call (truly no new call) is a noted follow-up.
+ * Returns the criteria unchanged (all pending) if grading can't run — never
+ * marks met without evidence.
+ */
+export async function gradeAcceptanceCriteria(criteria, ctx) {
+    if (!Array.isArray(criteria) || !criteria.length)
+        return criteria || [];
+    if (isMockMode())
+        return mockGrade(criteria, ctx);
+    const prompt = GRADE_PROMPT(criteria, ctx);
+    for (const binary of selectProviderBinary()) {
+        const raw = await new Promise((resolve) => {
+            let out = '';
+            let settled = false;
+            const done = (r) => {
+                if (!settled) {
+                    settled = true;
+                    resolve(r);
+                }
+            };
+            const child = spawn(binary, ['--bare', '-p', prompt], { stdio: ['ignore', 'pipe', 'pipe'] });
+            const to = setTimeout(() => {
+                child.kill('SIGTERM');
+                done(null);
+            }, CRITERIA_TIMEOUT_MS);
+            child.on('error', () => {
+                clearTimeout(to);
+                done(null);
+            });
+            child.stdout?.on('data', (c) => {
+                out += c.toString('utf-8');
+            });
+            child.on('exit', (code) => {
+                clearTimeout(to);
+                done(code === 0 ? out : null);
+            });
+        });
+        if (raw)
+            return applyGrades(criteria, raw);
+    }
+    return criteria; // no grade available → stay pending, never fake a green
+}
+function tryProvider(binary, prompt) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const child = spawn(binary, ['--bare', '-p', prompt], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const timeout = setTimeout(() => {
+            child.kill('SIGTERM');
+            if (process.env.CODEHERE_DEBUG === '1') {
+                console.error(`[criteria-agent] ${binary} timeout after ${CRITERIA_TIMEOUT_MS}ms`);
+            }
+            finish(null);
+        }, CRITERIA_TIMEOUT_MS);
+        child.on('error', () => {
+            clearTimeout(timeout);
+            finish(null);
+        });
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf-8');
+        });
+        child.on('exit', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                finish(null);
+                return;
+            }
+            const criteria = sanitizeCriteria(stdout);
+            finish(criteria.length ? criteria : null);
+        });
+    });
+}
+/**
+ * The contract. Returns [] (not null) when no provider responds so callers can
+ * store the field unconditionally; an empty contract simply means the request
+ * ran without one (never blocks the run).
+ */
+export async function generateAcceptanceCriteria(firstPrompt, cwd) {
+    if (isMockMode())
+        return mockCriteria(firstPrompt);
+    const prompt = PROMPT_TEMPLATE(firstPrompt, cwd);
+    for (const binary of selectProviderBinary()) {
+        const result = await tryProvider(binary, prompt);
+        if (result)
+            return result;
+    }
+    return [];
+}
+//# sourceMappingURL=generate-acceptance-criteria.js.map

package/dist/application/use-cases/generate-final-report.js

@@ -21,7 +21,10 @@
  * was available, and NEVER implies success — so a completed task always shows a
  * deliverable, and it's honest about which kind it is (see `source`).
  */
-const MAX_SUMMARY_CHARS = 1600;
+// Generous cap — the old 1600 clipped reports mid-code-block (a code fence +
+// prose easily exceeds it). High enough to never trim a real report's code,
+// still bounded against a runaway agent dump.
+const MAX_SUMMARY_CHARS = 20000;
 /**
  * UAT-003 — patterns indicating the agent's own text is actually a network /
  * auth / quota failure, not a real summary. Such "summaries" must NOT be shown
@@ -31,6 +34,33 @@ const NETWORK_FAILURE_PATTERNS = /(?:all connection attempts failed|ECONNREFUSED
 function isLikelyNetworkFailureSummary(text) {
     return NETWORK_FAILURE_PATTERNS.test(text);
 }
+/**
+ * UAT (real-mode dogfood 2026-06-13) — some CLIs (aider) have no narration
+ * channel; their captured "say" text is setup/housekeeping chatter, not a
+ * summary of the work ("You can skip this check with --no-gitignore", the
+ * `.gitignore` housekeeping, the version banner). Shown as the report it reads
+ * as broken — and it buries the honest deterministic facts (files changed +
+ * trust score). Strip the housekeeping; if nothing real is left, fall through.
+ */
+const TOOL_NOISE_PATTERNS = [
+    /you can skip this check with --no-gitignore/gi,
+    /added\s+\.?aider\*?\s+to\s+\.?gitignore/gi,
+    /\baider v[\d.]+(?:\s*\([^)]*\))?/gi,
+    /\binitialized empty git repository[^\n]*/gi,
+    // aider session-banner lines (loop-1 sweep 2026-07-06: real runs whose whole
+    // "summary" was this chatter passed the length bar and rendered as the report)
+    /\bnote: in-chat filenames are always relative to[^\n.]*\.?/gi,
+    /\bcur working dir:[^\n]*/gi,
+    /\bgit working dir:[^\n]*/gi,
+    /\brepo-map can't include[^\n]*/gi,
+    /\bhas it been deleted from the file system but not from git\?/gi,
+];
+function stripToolNoise(text) {
+    let t = text;
+    for (const re of TOOL_NOISE_PATTERNS)
+        t = t.replace(re, ' ');
+    return t.replace(/\s+/g, ' ').trim();
+}
 /**
  * ENGINE: the agent's own narration. kind:'say' steps are the words the agent
  * already emitted (reasoning + wrap-up). Joined newest-context-last, they ARE
@@ -42,7 +72,19 @@ function extractAgentSummary(steps) {
         .map((s) => s.label.trim());
     if (!says.length)
         return null;
-    const text = says.join('\n\n').slice(0, MAX_SUMMARY_CHARS);
+    // Inverted pyramid (loop-1 lesson 2026-07-06): agents narrate chronologically,
+    // so joined-in-order reports LEAD with opening narration ("Let me check…")
+    // while the finding sits at the end — and every summary-of-the-summary
+    // downstream (glance, cards, search snippets) inherits the wrong lead. The
+    // agent's LAST say is its wrap-up: put it first, keep the earlier narration
+    // below under an honest label. Content intact, order presented, not invented.
+    const ordered = says.length > 1 ? [says[says.length - 1], 'Earlier notes:', ...says.slice(0, -1)] : says;
+    const text = ordered.join('\n\n').slice(0, MAX_SUMMARY_CHARS);
+    // A "summary" that is only tool housekeeping (no real prose left after
+    // stripping it) is NOT a summary → let the deterministic fallback give the
+    // honest facts (files changed + trust score) instead of chatter.
+    if (stripToolNoise(text).length < 12)
+        return null;
     // Too short to be a real summary (e.g. a one-word ack) → let the fallback give facts.
     return text.length >= 12 ? text : null;
 }
@@ -56,10 +98,13 @@ function buildDeterministicReport(input) {
     const noGit = input.artifacts?.noGitTracking;
     const agentName = input.agent === 'conductor' ? 'the agent codehere chose' : input.agent;
     const parts = [
-        `No plain-English summary was available for this run — ${agentName} didn't leave a written summary, and codehere doesn't fabricate one. Here are the recorded facts.`,
+        `No written summary for this run. ${agentName} didn't leave one, and codehere doesn't fabricate one. Here are the recorded facts.`,
         `The session ran ${input.steps.length} step${input.steps.length === 1 ? '' : 's'}` +
             (toolSteps.length
-                ? ` (${toolSteps.slice(0, 5).map((s) => s.label).join(', ')}${toolSteps.length > 5 ? ', …' : ''})`
+                ? ` (${toolSteps
+                    .slice(0, 5)
+                    .map((s) => s.label)
+                    .join(', ')}${toolSteps.length > 5 ? ', …' : ''})`
                 : '') +
             `.`,
     ];
@@ -78,19 +123,99 @@ function buildDeterministicReport(input) {
     }
     return { summary: parts.join('\n\n'), generatedAt: Date.now(), durationMs: 0, source: 'deterministic' };
 }
+/** Per-vendor recovery hints — the SPECIFIC auth/quota fix for EACH agent, so a
+ *  failure report names the right login command + provider, not a claude-centric
+ *  or generic guess. Commands/URLs mirror the readiness authHints (Phase 1):
+ *  codex→`codex login`/platform.openai.com, gemini→AI-Studio free tier, aider→its
+ *  LiteLLM model provider (free Gemini path), opencode→`opencode auth`. */
+const VENDOR_FIX = {
+    'claude-code': {
+        label: 'Claude',
+        auth: 'codehere runs Claude through your *subscription* (your `claude` login) — it ignores `ANTHROPIC_API_KEY` on purpose. Open a terminal, run `claude`, complete `/login`, then rerun.',
+        quota: "If you authenticate with an API key, top up at console.anthropic.com; if you're on a Claude subscription, check your plan's usage limits — then rerun.",
+    },
+    codex: {
+        label: 'Codex',
+        auth: 'Run `codex login` with a ChatGPT Plus/Pro account (flat, no per-token charge), or set `OPENAI_API_KEY` — then rerun.',
+        quota: 'OpenAI quota exhausted — top up at platform.openai.com, or switch to a free agent (gemini / opencode).',
+    },
+    gemini: {
+        label: 'Gemini',
+        auth: 'Set `GEMINI_API_KEY` from the free tier (https://aistudio.google.com/apikey), then rerun.',
+        quota: "Gemini's free-tier limit was hit — wait for it to reset, raise your AI Studio limits, or switch agents.",
+    },
+    aider: {
+        label: 'Aider',
+        // Provider-neutral on purpose: codehere can't know WHICH provider aider was
+        // pointed at, so name the credential for each path rather than leading with one.
+        auth: 'Aider needs a model + a matching provider key. Set the key for whatever provider you point it at — a billed `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` (with credit), or a free `GEMINI_API_KEY` run as `--model gemini/gemini-2.5-flash` — then rerun.',
+        quota: 'The provider key aider is using has no credit — top up that provider, or switch aider to a free one (e.g. a Gemini key with `--model gemini/…`, or a local Ollama model).',
+    },
+    opencode: {
+        label: 'OpenCode',
+        auth: 'Run `opencode auth` once to add a provider (a local Ollama model or a free endpoint = $0), then rerun.',
+        quota: 'The provider OpenCode is using hit its limit — run `opencode auth` to switch providers, or point at a local Ollama model.',
+    },
+};
+const GENERIC_FIX = {
+    label: 'The agent',
+    auth: "Sign in to the agent's provider — run `codehere health` to see which agent and how — then rerun.",
+    quota: "Top up or switch the agent's provider; `codehere health` shows the per-agent status. codehere is vendor-neutral.",
+};
+/** Read the captured error/output text and name the SPECIFIC failure + the fix
+ *  FOR THIS AGENT, instead of a generic "network hiccup" or a claude-only guess.
+ *  Uses input.errorText (codehere:error events) + steps' errorText/output. The
+ *  detection patterns are vendor-neutral (each adapter forwards the provider's
+ *  native auth/quota/rate words); the RECOVERY text is selected per input.agent.
+ *  Returns null when the text doesn't clearly indicate a known failure — honest:
+ *  we don't fabricate a specific cause we can't see. */
+function diagnoseFailure(input) {
+    const blob = (input.errorText ? [input.errorText] : [])
+        .concat((input.steps || []).map((s) => `${s.errorText || ''} ${s.output || ''} ${s.kind === 'say' ? s.label : ''}`))
+        .join(' ')
+        .toLowerCase();
+    if (!blob.trim())
+        return null;
+    // Prefer the direct agent's fix; for a conductor task, fall back to the
+    // specialist it delegated to (so a conductor→codex failure names codex's fix,
+    // not the generic one); only then the vendor-neutral generic.
+    const fix = VENDOR_FIX[input.agent] ?? (input.delegatedTo ? VENDOR_FIX[input.delegatedTo] : undefined) ?? GENERIC_FIX;
+    if (/not logged in|please run.{0,6}\/login|\/login|no valid session|unauthorized|invalid api key|api key not valid|401\b/.test(blob)) {
+        return `**${fix.label} isn't logged in.** ${fix.auth}`;
+    }
+    if (/credit balance is too low|insufficient.{0,12}credit|out of credit|quota|billing/.test(blob)) {
+        return `**Out of credits / quota.** ${fix.quota}`;
+    }
+    if (/rate.?limit|\b429\b|too many requests/.test(blob)) {
+        return `**Rate limited by the provider.** Wait a minute and rerun, or switch agents — codehere is vendor-neutral.`;
+    }
+    return null;
+}
 function buildErrorRecoveryReport(input, durationMs) {
     const agentName = input.agent === 'conductor' ? 'the agent codehere chose' : input.agent;
-    return {
-        summary: `The ${agentName} session ended without completing the task. ` +
-            `This usually means a network hiccup, an expired login, or a rate limit on the provider.\n\n` +
-            `What to try: check your internet, run \`codehere health\` to confirm reachability + auth, ` +
-            `or wait a minute and rerun the same prompt. If it keeps happening, try a different agent ` +
-            `from the dropdown — codehere is vendor-neutral on purpose.\n\n` +
-            `codehere couldn't confirm any file changes from this attempt.`,
-        generatedAt: Date.now(),
-        durationMs,
-        source: 'error-recovery',
-    };
+    const specific = diagnoseFailure(input);
+    // When we can't classify the failure but the agent TOLD us why, show its real
+    // words — not a generic three-way guess. A product whose pitch is "show the
+    // truth" should surface "You've hit your usage limit — try again Jul 14", not
+    // "this usually means a network hiccup, an expired login, or a rate limit".
+    const realReason = (input.errorText || '').trim();
+    // NEVER claim "no files changed" without checking. A failed run that still
+    // edited files must say so — claiming otherwise is a lie the dogfood caught
+    // (opencode edited the file, codehere reported "no files were changed").
+    const files = (input.artifacts?.files || []).filter(Boolean);
+    const filesTail = files.length
+        ? `Note: ${files.length} file${files.length === 1 ? '' : 's'} ${files.length === 1 ? 'was' : 'were'} already changed before it stopped (${files.slice(0, 5).join(', ')}${files.length > 5 ? ', …' : ''}) — review before retrying.`
+        : `codehere couldn't confirm any file changes from this attempt.`;
+    const summary = specific
+        ? `The ${agentName} session couldn't complete.\n\n${specific}\n\n${filesTail}`
+        : realReason
+            ? `The ${agentName} session couldn't complete. It reported:\n\n${realReason}\n\n${filesTail}`
+            : `The ${agentName} session ended without completing the task. ` +
+                `This usually means a network hiccup, an expired login, or a rate limit on the provider.\n\n` +
+                `What to try: check your internet, run \`codehere health\` to confirm reachability + auth, ` +
+                `or wait a minute and rerun the same prompt. If it keeps happening, try a different agent ` +
+                `from the dropdown — codehere is vendor-neutral on purpose.\n\n${filesTail}`;
+    return { summary, generatedAt: Date.now(), durationMs, source: 'error-recovery' };
 }
 /**
  * Generate a Final Report. Reuses the agent's own summary; falls back to a

package/dist/application/use-cases/generate-narration.js

@@ -16,7 +16,7 @@
  * anti-hallucination rule as generate-final-report (ground every claim
  * in the structured data).
  *
- * Provider strategy: same as generate-final-report (try claude-free
+ * Provider strategy: env override, else claude (the dead claude-free
  * first, fall back to claude). Returns null if neither is installed.
  */
 import { spawn } from 'child_process';
@@ -32,11 +32,13 @@ function buildPrompt(input) {
     return renderTemplate(template, input);
 }
 function selectProviderBinary() {
-    // Same precedence as generate-final-report: env override → claude-free → claude.
+    // MED #27 (atomic audit) · the old chain led with 'claude-free' (the dead
+    // FCC/NIM proxy final-report.ts abandoned) — every narration burned its
+    // timeout against a down proxy first. Env override → claude, that's it.
     const override = process.env.CODEHERE_NARRATOR_BINARY?.trim();
     if (override)
         return [override];
-    return ['claude-free', 'claude'];
+    return ['claude'];
 }
 export async function generateNarration(input) {
     if (isMockMode()) {

package/dist/application/use-cases/generate-thread-title.js

@@ -7,7 +7,7 @@
  * tab + future thread switcher UI.
  *
  * Companion to generate-final-report.ts:
- *   - Same provider chain pattern (claude-free → claude → graceful skip)
+ *   - Provider: env override → claude → graceful skip (dead claude-free hop removed)
  *   - Same single-shot, no streaming, returns string
  *   - Different prompt (terse title generation, NOT 3-paragraph narrative)
  *   - Cheaper budget (~50 tokens per title vs 200 per Final Report paragraph)
@@ -43,10 +43,13 @@ Rules:
 
 Title:`;
 function selectProviderBinary() {
+    // MED #28 (atomic audit) · same dead 'claude-free' first hop as narration —
+    // removed so a title either comes from claude or degrades fast, not after
+    // a proxy timeout.
     const override = process.env.CODEHERE_TITLE_BINARY;
     if (override)
         return [override];
-    return ['claude-free', 'claude'];
+    return ['claude'];
 }
 function tryProvider(binary, prompt) {
     return new Promise((resolve) => {

package/dist/application/use-cases/narrator-prompt-template.js

@@ -79,7 +79,7 @@ Write the paragraph now. Do not preface with "Update:" or anything similar.
 Plain prose. No "I'm currently…" — narrate the AGENT, not yourself.
 `;
 function templateFile() {
-    return join(homedir(), '.codehere', 'narrator-prompt.md');
+    return join(process.env.CODEHERE_HOME || homedir(), '.codehere', 'narrator-prompt.md');
 }
 /** Read the user-customized template if present and valid. Falls back to
  *  baked-in default on missing file, parse failure, or missing required

package/dist/application/use-cases/plan-auto-review.js

@@ -0,0 +1,57 @@
+/**
+ * Tier 2.1 · slice 2b — turn the eligibility decision into a concrete,
+ * loop-safe plan for the auto cross-vendor review spawn. Still pure: it decides
+ * WHAT to spawn (vendor, prompt, cwd, tag), not how — the live spawn + the
+ * real-spend verification are the next slice. Kept pure so the loop guard and
+ * the refute framing are unit-testable without a daemon or spend.
+ *
+ * THE LOOP GUARD is the load-bearing safety here: an auto-review is itself a
+ * task that completes and flows through the same completion handler. Without a
+ * guard it would trigger its own auto-review, recursing + burning spend forever.
+ * A reviewer session is tagged; planAutoReview returns null for tagged sessions.
+ *
+ * The reviewer runs in REFUTE mode and READ-ONLY: codehere proves the PROCESS
+ * (a different vendor independently reviewed + recorded findings), it never
+ * adjudicates code correctness (assess-cross-vendor honesty note). The prompt
+ * asks the reviewer to try to disprove "done", not to fix anything.
+ */
+import { shouldAutoReview } from './should-auto-review.js';
+/** Tag stamped on an auto-review reviewer session so it never triggers its own
+ *  auto-review (the loop guard) and so surfaces can label it. */
+export const AUTO_REVIEW_TAG = 'auto-cross-vendor-review';
+/** The refute-mode brief: read-only, adversarial, names the writer's files. */
+function buildRefutePrompt(writerAgent, files) {
+    const fileList = files.length <= 10 ? files.join(', ') : `${files.slice(0, 10).join(', ')} (+${files.length - 10} more)`;
+    return (`A different agent (${writerAgent}) just changed these files in this repo: ${fileList}. ` +
+        `Independently review that work READ-ONLY — do not edit anything. ` +
+        `Try to disprove that the task is correctly done: look for bugs, missed edge cases, ` +
+        `or claims the diff doesn't actually support. Report what you find (or that it holds up). ` +
+        `You are the second vendor in a cross-vendor check; your job is to refute, not to fix.`);
+}
+/**
+ * Build the auto-review spawn plan, or null if it shouldn't / can't run.
+ * Returns null (with no side effects) for: the loop guard, or any failed
+ * eligibility gate. Pure.
+ */
+export function planAutoReview(facts, thresholds) {
+    // Loop guard FIRST — a reviewer's own completion must never spawn a review.
+    if (facts.isAutoReviewSession)
+        return null;
+    const inputs = {
+        writerAgent: facts.writerAgent,
+        installedAgents: facts.installedAgents,
+        filesChanged: facts.writerFiles.length,
+        budgetRemainingUsd: facts.budgetRemainingUsd,
+    };
+    const decision = shouldAutoReview(inputs, thresholds);
+    if (!decision.eligible || !decision.reviewerVendor)
+        return null;
+    return {
+        reviewerVendor: decision.reviewerVendor,
+        prompt: buildRefutePrompt(facts.writerAgent, facts.writerFiles),
+        cwd: facts.cwd,
+        tag: AUTO_REVIEW_TAG,
+        reason: decision.reason,
+    };
+}
+//# sourceMappingURL=plan-auto-review.js.map

package/dist/application/use-cases/reconcile-audit.js

@@ -0,0 +1,100 @@
+/**
+ * Tier 1.2 (verdict-trust punch list, 2026-06-09) · reconcile the AUDIT against
+ * the real on-disk effect.
+ *
+ * The gap this closes: an audit entry records the agent's DECLARED tool call
+ * (PreToolUse intent for claude, a post-hoc mirror for the others) — not an
+ * independent observation that the write actually landed. An agent (or adapter)
+ * that emits a file-write tool_use which never really changed anything lands that
+ * fiction in the integrity-checked chain as a first-class entry. The chain then
+ * faithfully shows the CLAIM was never casually edited — it never checks the claim
+ * against reality.
+ *
+ * This reconciles the audit's file-write tool calls against the SAME git-diff
+ * ground truth verify-claim already uses for file claims. It does NOT mutate the
+ * append-only, hash-chained audit (that would break tamper-evidence) — it's a
+ * read-only layer that produces an honest verdict the surface can show:
+ *   - consistent   · writes recorded AND files changed on disk
+ *   - unconfirmed  · writes recorded but codehere couldn't tie them to a tracked
+ *                    git change. Honest, NOT an accusation: the writes may have
+ *                    targeted gitignored / scratch / .codehere paths (which the
+ *                    git-diff ground truth excludes), been reverted within the
+ *                    run, or — the case worth a look — never really happened.
+ *                    "couldn't confirm", never "it's fake" (refuter 2026-06-09:
+ *                    a false fabrication accusation on honest work is the worst
+ *                    error class on a proof surface).
+ *   - no-writes    · nothing claimed, nothing to reconcile
+ *   - unobservable · not a git repo, so codehere can't confirm
+ *
+ * Count-based by design: toolInput is truncated/heterogeneous across adapters, so
+ * per-file path matching is unreliable; the file-write COUNT vs the git-change
+ * count is robust. Bash/shell tools can also write files but codehere can't tell,
+ * so they're deliberately NOT counted as declared writes (conservative — never
+ * fabricates a "declared-not-observed" the user can't act on).
+ */
+/** Tool names that explicitly mutate a file on disk, across every adapter.
+ *  Derived from the real audit's toolName distribution (Write/Edit/write_file/
+ *  edit_file observed) plus the standard variants. Shell tools are excluded — a
+ *  bash `echo > f` can't be distinguished from a read, so counting it would
+ *  manufacture false "declared-not-observed" verdicts. */
+// Matched case-INSENSITIVELY (adapters emit varied casings: claude 'Edit',
+// codex 'Delete', gemini raw tool_name like 'write_file'/'replace'). A DELETE is
+// a real file mutation that shows in git — omitting it made a codex delete-only
+// run falsely read "no writes recorded" (self-audit 2026-06-09). Keep this broad;
+// over-counting a non-write is far less harmful than a false "nothing happened".
+const WRITE_TOOLS = new Set(
+// SPECIFIC file-mutation tool names only. Bare generic verbs ('replace',
+// 'patch') are deliberately EXCLUDED — a non-file tool named 'replace' (an
+// in-memory string replace) would false-count and produce a false 'consistent'
+// (worse than under-counting, which is an honest 'unconfirmed'). A real write
+// the set misses → 'unconfirmed' (honest), never a fabricated-write laundered
+// into green (self-audit round 2, 2026-06-09).
+[
+    'Write',
+    'Edit',
+    'MultiEdit',
+    'NotebookEdit',
+    'Delete',
+    'write_file',
+    'edit_file',
+    'create_file',
+    'delete_file',
+    'str_replace',
+    'str_replace_editor',
+    'apply_patch',
+].map((t) => t.toLowerCase()));
+export function reconcileAudit(entries, artifacts) {
+    const writeToolCalls = entries.filter((e) => WRITE_TOOLS.has((e.toolName || '').toLowerCase())).length;
+    const filesObserved = artifacts?.files?.length ?? 0;
+    if (artifacts?.noGitTracking) {
+        return {
+            writeToolCalls,
+            filesObserved: 0,
+            verdict: 'unobservable',
+            note: `${writeToolCalls} file-write tool call${writeToolCalls === 1 ? '' : 's'} recorded, but this folder isn't a git repo — codehere can't confirm them against disk.`,
+        };
+    }
+    if (writeToolCalls === 0) {
+        return {
+            writeToolCalls,
+            filesObserved,
+            verdict: 'no-writes',
+            note: 'No file-write tool calls recorded — nothing to reconcile against disk.',
+        };
+    }
+    if (filesObserved === 0) {
+        return {
+            writeToolCalls,
+            filesObserved,
+            verdict: 'unconfirmed',
+            note: `${writeToolCalls} file-write tool call${writeToolCalls === 1 ? '' : 's'} recorded, but codehere couldn't confirm them against tracked git changes — they may have targeted gitignored/scratch paths or been reverted. Worth a look, not proof of a problem.`,
+        };
+    }
+    return {
+        writeToolCalls,
+        filesObserved,
+        verdict: 'consistent',
+        note: `${writeToolCalls} file-write tool call${writeToolCalls === 1 ? '' : 's'} recorded · ${filesObserved} file${filesObserved === 1 ? '' : 's'} confirmed changed on disk.`,
+    };
+}
+//# sourceMappingURL=reconcile-audit.js.map