codeep 2.21.0 → 2.22.0

package/dist/api/index.js

@@ -1,6 +1,6 @@
 import * as http from 'node:http';
 import * as https from 'node:https';
-import { config, getApiKey, resolveBaseUrl } from '../config/index.js';
+import { config, getApiKey, resolveBaseUrl, describeUnsendableKey } from '../config/index.js';
 import { withRetry, isNetworkError } from '../utils/retry.js';
 import { checkApiRateLimit } from '../utils/ratelimit.js';
 import { getProvider, getProviderBaseUrl, getProviderAuthHeader, usesMaxCompletionTokens, requiresDefaultTemperature, modelRejectsSamplingParams, reasoningParamsFor } from '../config/providers.js';
@@ -147,6 +147,28 @@ function parseApiError(status, body) {
     const truncated = body.length > 200 ? body.slice(0, 200) + '...' : body;
     return `${status} - ${truncated}`;
 }
+/**
+ * Put the key in the right header, refusing early if it cannot be sent.
+ *
+ * `fetch` throws "Cannot convert argument to a ByteString because the character
+ * at index N…" for a header value outside Latin-1, counting from the start of
+ * `Bearer <key>` — so the index points four characters left of where anyone
+ * would look, and the message never mentions the key at all. Worse, the caller
+ * treats it as a transient API error and retries twice more, which cannot
+ * possibly help.
+ */
+function applyAuthHeader(headers, apiKey, authHeader) {
+    const problem = describeUnsendableKey(apiKey);
+    if (problem) {
+        throw new ApiError(`This API key cannot be used: ${problem}. Re-copy it and run /login to set it again.`, 400);
+    }
+    if (authHeader === 'Bearer') {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+    else {
+        headers['x-api-key'] = apiKey;
+    }
+}
 export async function chat(message, history = [], onChunk, onRetry, projectContext, abortSignal) {
     // Update project context if provided
     if (projectContext !== undefined) {
@@ -377,12 +399,7 @@ async function chatOpenAI(message, history, model, apiKey, onChunk, abortSignal)
     const headers = {
         'Content-Type': 'application/json',
     };
-    if (authHeader === 'Bearer') {
-        headers['Authorization'] = `Bearer ${apiKey}`;
-    }
-    else {
-        headers['x-api-key'] = apiKey;
-    }
+    applyAuthHeader(headers, apiKey, authHeader);
     // OpenRouter: branding headers + opt in to `usage.cost` so the
     // chat path reports authoritative per-call cost just like agentChat
     // does. Kept identical to the agentChat block so the two paths stay
@@ -650,12 +667,7 @@ async function chatAnthropic(message, history, model, apiKey, onChunk, abortSign
         'Content-Type': 'application/json',
         'anthropic-version': '2023-06-01',
     };
-    if (authHeader === 'Bearer') {
-        headers['Authorization'] = `Bearer ${apiKey}`;
-    }
-    else {
-        headers['x-api-key'] = apiKey;
-    }
+    applyAuthHeader(headers, apiKey, authHeader);
     try {
         // Anthropic prompt caching: wrap system as an array with a
         // `cache_control` marker so the static system prompt (typically large
@@ -797,12 +809,7 @@ export async function validateApiKey(apiKey, providerId) {
     const headers = {
         'Content-Type': 'application/json',
     };
-    if (authHeader === 'Bearer') {
-        headers['Authorization'] = `Bearer ${apiKey}`;
-    }
-    else {
-        headers['x-api-key'] = apiKey;
-    }
+    applyAuthHeader(headers, apiKey, authHeader);
     if (protocol === 'anthropic') {
         headers['anthropic-version'] = '2023-06-01';
     }

package/dist/config/index.d.ts

@@ -37,6 +37,12 @@ export interface ConfigSchema {
      *  user (reply language, style, stack, preferences). Default true; set false
      *  to keep the profile files but stop injecting them. Managed via `/me`. */
     userProfile: boolean;
+    /** Append a record of what each agent run touched to `.codeep/audit/`.
+     *  Reads and refusals included — `history.ts` records neither, because it
+     *  exists to undo writes rather than to say what happened. On unless set
+     *  false: a record you must remember to enable is not one you can rely on
+     *  having when you need it. */
+    auditLog: boolean;
     /** Auto-learn: at session save, run one LLM pass to extract durable facts /
      *  preferences about the user and merge them into `~/.codeep/profile.learned.md`
      *  (injected alongside the hand-written profile). OFF by default — opt in via
@@ -318,3 +324,17 @@ export declare function loadProfile(name: string): Profile | null;
 export declare function applyProfile(profile: Profile): void;
 export declare function listProfiles(): string[];
 export declare function deleteProfile(name: string): boolean;
+/**
+ * Whether a key can survive being put in an HTTP header.
+ *
+ * `fetch` encodes header values as Latin-1 and throws "Cannot convert argument
+ * to a ByteString" on anything outside it. A key pasted from a web page or a
+ * chat message can pick up a non-breaking space, a zero-width character or a
+ * curly quote, and the resulting failure names neither the key nor the
+ * character — only "the character at index N", counted across the whole header
+ * value with `Bearer ` included, which is not where anyone would look.
+ *
+ * Returns null when the key is fine, or a description that locates the problem
+ * without ever reproducing the key itself.
+ */
+export declare function describeUnsendableKey(apiKey: string): string | null;

package/dist/config/index.js

@@ -175,6 +175,7 @@ function createConfig() {
         autoSessionTitle: true,
         autoSummarizeHistory: true,
         userProfile: true,
+        auditLog: true,
         autoLearnProfile: false,
         trustedHookProjects: [],
         currentSessionId: '',
@@ -1264,3 +1265,34 @@ export function deleteProfile(name) {
         return false;
     }
 }
+/**
+ * Whether a key can survive being put in an HTTP header.
+ *
+ * `fetch` encodes header values as Latin-1 and throws "Cannot convert argument
+ * to a ByteString" on anything outside it. A key pasted from a web page or a
+ * chat message can pick up a non-breaking space, a zero-width character or a
+ * curly quote, and the resulting failure names neither the key nor the
+ * character — only "the character at index N", counted across the whole header
+ * value with `Bearer ` included, which is not where anyone would look.
+ *
+ * Returns null when the key is fine, or a description that locates the problem
+ * without ever reproducing the key itself.
+ */
+export function describeUnsendableKey(apiKey) {
+    for (let i = 0; i < apiKey.length; i++) {
+        const code = apiKey.charCodeAt(i);
+        if (code > 0xFF) {
+            const name = code === 0x200B ? 'a zero-width space'
+                : code === 0x2018 || code === 0x2019 ? 'a curly quote'
+                    : code === 0x201C || code === 0x201D ? 'a curly double quote'
+                        : `U+${code.toString(16).toUpperCase().padStart(4, '0')}`;
+            return `character ${i + 1} of the key is ${name}, which cannot be sent in an HTTP header`;
+        }
+        // 0xA0 is inside Latin-1 and technically sendable, but a non-breaking space
+        // in a key is never intentional and produces a 401 that reads as a bad key.
+        if (code === 0xA0) {
+            return `character ${i + 1} of the key is a non-breaking space — probably picked up when copying`;
+        }
+    }
+    return null;
+}

package/dist/renderer/commands/registry.js

@@ -205,6 +205,7 @@ export const COMMANDS = [
         usage: ['init [project]', 'learn [on|off]', 'sync', 'off', 'forget'],
     },
     { name: 'agents', description: 'List sub-agents the agent can delegate to (researcher / reviewer / tester / your own)', category: 'settings' },
+    { name: 'audit', description: 'What agents did in this project — runs, tools used, and anything the boundary refused', category: 'settings', usage: ['on', 'off'] },
     { name: 'insights', description: 'Activity summary — runs, files, tools, projects over the last N days (default 7)', category: 'settings', usage: ['--days N'] },
     { name: 'openrouter', description: 'OpenRouter routing prefs (prefer/ignore providers, fallbacks, privacy)', category: 'settings' },
     // ── extensions & mcp ───────────────────────────────────────────────────────

package/dist/renderer/commands.js

@@ -445,6 +445,23 @@ export async function handleCommand(command, args, ctx) {
             });
             break;
         }
+        case 'audit': {
+            const { formatAuditLog } = await import('../utils/auditLog.js');
+            const sub = args[0]?.toLowerCase();
+            if (sub === 'on' || sub === 'off') {
+                config.set('auditLog', sub === 'on');
+                ctx.app.notify(sub === 'on'
+                    ? 'Audit recording on — runs are recorded to .codeep/audit/.'
+                    : 'Audit recording off. Records already written are kept.');
+                break;
+            }
+            if (sub) {
+                ctx.app.notify(`Unknown audit subcommand: ${sub}. Use /audit, /audit on, or /audit off`);
+                break;
+            }
+            ctx.app.addMessage({ role: 'system', content: formatAuditLog(ctx.projectPath) });
+            break;
+        }
         case 'agents': {
             // List sub-agents the agent can `delegate` to (built-in + .codeep/agents/).
             const { formatAgentList } = await import('../utils/agents.js');

package/dist/utils/agent.d.ts

@@ -6,6 +6,7 @@
 import { ProjectContext } from './project';
 import { loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent } from './agentChat';
 import type { AgentChatResponse } from './agentChat';
+import { type Personality } from './personalities';
 export { loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent };
 export type { AgentChatResponse };
 import { ToolCall, ToolResult, ActionLog } from './tools';
@@ -83,6 +84,12 @@ export interface AgentOptions {
      *  sub-agent's tool actions still record into the parent's session, so undo
      *  spans delegation. */
     nested?: boolean;
+    /** Run under this capability boundary instead of whatever the user has
+     *  selected. Used by non-interactive callers that must pin the boundary
+     *  themselves — a CI fix, for example, runs files+tests regardless of the
+     *  machine's active bot. Enforced by the same gate as any other bot; this
+     *  chooses which one applies, never whether one does. */
+    personalityOverride?: Personality;
     /** Delegation depth. 0 = top-level orchestrator (gets the `delegate` tool);
      *  sub-agents run at depth 1 and cannot delegate further (v1). */
     depth?: number;

package/dist/utils/agent.js

@@ -14,6 +14,7 @@ const debug = (...args) => {
 import { agentChat, getAgentSystemPrompt, getFallbackSystemPrompt, loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent, summarizeEarlierHistory, } from './agentChat.js';
 import { ApiError } from '../api/index.js';
 import { loadUserProfilePrompt } from './userProfile.js';
+import { beginAuditRun, endAuditRun, recordAuditEvent, describeAuditTarget } from './auditLog.js';
 import { getActivePersonality, getPersonalityToolAllowlist, isPersonalityToolCallAllowed, resolvePersonalityRuntimeModel, } from './personalities.js';
 export { loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent };
 /**
@@ -172,6 +173,30 @@ const DEFAULT_OPTIONS = {
     maxDuration: 20 * 60 * 1000, // 20 minutes
     usePlanning: false, // Disable task planning - causes more problems than it solves
 };
+/**
+ * Sleep that gives up when the run is stopped.
+ *
+ * A plain `setTimeout` promise ignores the abort signal, so pressing Stop
+ * during "retrying in 10s" did nothing until the wait expired — and then the
+ * loop went on to retry anyway. Ctrl-C behaved the same way, because both
+ * routes set the same signal that nothing was reading.
+ *
+ * Resolves early on abort. Callers must still check `aborted` afterwards; this
+ * only stops the waiting, it does not decide what to do next.
+ */
+function abortableSleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise(resolve => {
+        const timer = setTimeout(finish, ms);
+        function finish() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', finish);
+            resolve();
+        }
+        signal?.addEventListener('abort', finish, { once: true });
+    });
+}
 /**
  * Run the agent loop
  */
@@ -190,7 +215,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
     const messages = [];
     // A structured custom bot is resolved once per run. This keeps a cloud sync
     // or file edit from changing policy halfway through an in-flight request.
-    const activePersonality = getActivePersonality(projectContext.root);
+    const activePersonality = opts.personalityOverride ?? getActivePersonality(projectContext.root);
     const currentRuntime = {
         providerId: String(config.get('provider')),
         model: String(config.get('model')),
@@ -208,8 +233,18 @@ export async function runAgent(prompt, projectContext, options = {}) {
     // The return value is unused — startSession's point here is the side
     // effect of opening the history session. Binding it hid that from
     // noUnusedLocals, so the dead binding is gone and the call stays.
+    const auditRoot = projectContext.root || process.cwd();
     if (!opts.nested)
-        startSession(prompt, projectContext.root || process.cwd());
+        startSession(prompt, auditRoot);
+    // A delegated sub-agent records into the parent's run for the same reason it
+    // shares the parent's history session: its actions are part of what the run
+    // did, not a separate story. Only the top-level call opens a run.
+    let auditFailure;
+    const auditRun = opts.nested ? '' : beginAuditRun(auditRoot, {
+        prompt,
+        agent: activePersonality?.displayName,
+        capabilities: activePersonality?.declaredTools,
+    });
     // Task planning phase (if enabled)
     // Use planning for complex keywords or multi-word prompts
     let taskPlan = null;
@@ -431,6 +466,9 @@ export async function runAgent(prompt, projectContext, options = {}) {
     messages.push({ role: 'user', content: initialPrompt });
     let iteration = 0;
     let finalResponse = '';
+    // Initialised rather than merely declared: the `finally` reads it to decide
+    // the audit outcome, and TypeScript is right that a throw before assignment
+    // would leave it unset.
     let result;
     let consecutiveTimeouts = 0;
     let incompleteWorkRetries = 0;
@@ -575,7 +613,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
                 const totalTokensEstimate = messages.reduce((sum, m) => sum + Math.ceil(m.content.length / 4), 0);
                 const throttleMs = Math.min(Math.floor(totalTokensEstimate / 10000) * 1000, 5000);
                 if (throttleMs > 0)
-                    await new Promise(resolve => setTimeout(resolve, throttleMs));
+                    await abortableSleep(throttleMs, opts.abortSignal);
             }
             // Compress messages if context window is getting full (silent)
             const compressed = compressMessages(messages, actions);
@@ -668,7 +706,11 @@ export async function runAgent(prompt, projectContext, options = {}) {
                             break;
                         }
                         // Wait before retry (exponential backoff)
-                        await new Promise(resolve => setTimeout(resolve, 1000 * retryCount));
+                        await abortableSleep(1000 * retryCount, opts.abortSignal);
+                        // Stopping during a backoff must actually stop. Without this the
+                        // wait ended and the loop retried the request the user cancelled.
+                        if (opts.abortSignal?.aborted)
+                            break;
                         continue;
                     }
                     // Don't retry on 4xx client errors except 429 (rate limit)
@@ -732,7 +774,12 @@ export async function runAgent(prompt, projectContext, options = {}) {
                         });
                         break; // Break retry loop, continue main loop
                     }
-                    await new Promise(resolve => setTimeout(resolve, waitSec * 1000));
+                    await abortableSleep(waitSec * 1000, opts.abortSignal);
+                    // Stopping during a rate-limit wait must actually stop. Without
+                    // this the wait ran to completion and the loop retried the request
+                    // the user had already cancelled.
+                    if (opts.abortSignal?.aborted)
+                        break;
                     continue;
                 }
             }
@@ -837,6 +884,13 @@ export async function runAgent(prompt, projectContext, options = {}) {
                     };
                     opts.onToolResult?.(denied, toolCall);
                     actions.push(createActionLog(toolCall, denied));
+                    // The one event nothing recorded before. A boundary you cannot audit
+                    // is a boundary you have to take on faith.
+                    recordAuditEvent(auditRoot, {
+                        ts: Date.now(), run: auditRun, tool: toolCall.tool, action: 'refused',
+                        target: describeAuditTarget(toolCall), outcome: 'refused',
+                        detail: `blocked by custom bot "${activePersonality.displayName}"; allowed: ${allowed}`,
+                    });
                     toolResults.push(`Tool ${toolCall.tool} is blocked by the active custom bot. Allowed capabilities: ${allowed}.`);
                     continue;
                 }
@@ -944,6 +998,14 @@ export async function runAgent(prompt, projectContext, options = {}) {
                 // Log action
                 const actionLog = createActionLog(toolCall, toolResult);
                 actions.push(actionLog);
+                // createActionLog already classified this; reuse its verdict rather than
+                // re-deriving the action type in a second place that could drift.
+                recordAuditEvent(auditRoot, {
+                    ts: Date.now(), run: auditRun, tool: toolCall.tool, action: actionLog.type,
+                    target: describeAuditTarget(toolCall),
+                    outcome: toolResult.success ? 'ok' : 'error',
+                    detail: toolResult.success ? undefined : toolResult.error,
+                });
                 // ── Infinite loop detection for write/edit ──────────────────────────
                 if (toolCall.tool === 'write_file' || toolCall.tool === 'edit_file') {
                     const filePath = toolCall.parameters.path || '';
@@ -1125,6 +1187,13 @@ export async function runAgent(prompt, projectContext, options = {}) {
                                 };
                                 opts.onToolResult?.(denied, toolCall);
                                 actions.push(createActionLog(toolCall, denied));
+                                // The one event nothing recorded before. A boundary you cannot audit
+                                // is a boundary you have to take on faith.
+                                recordAuditEvent(auditRoot, {
+                                    ts: Date.now(), run: auditRun, tool: toolCall.tool, action: 'refused',
+                                    target: describeAuditTarget(toolCall), outcome: 'refused',
+                                    detail: `blocked by custom bot "${activePersonality.displayName}"`,
+                                });
                                 fixResults.push(`Tool ${toolCall.tool} blocked by the active custom bot.`);
                                 continue;
                             }
@@ -1145,6 +1214,14 @@ export async function runAgent(prompt, projectContext, options = {}) {
                             opts.onToolResult?.(toolResult, toolCall);
                             const actionLog = createActionLog(toolCall, toolResult);
                             actions.push(actionLog);
+                            // createActionLog already classified this; reuse its verdict rather than
+                            // re-deriving the action type in a second place that could drift.
+                            recordAuditEvent(auditRoot, {
+                                ts: Date.now(), run: auditRun, tool: toolCall.tool, action: actionLog.type,
+                                target: describeAuditTarget(toolCall),
+                                outcome: toolResult.success ? 'ok' : 'error',
+                                detail: toolResult.success ? undefined : toolResult.error,
+                            });
                             if (toolResult.success) {
                                 const truncated = truncateToolResult(toolResult.output, toolCall.tool);
                                 fixResults.push(`Tool ${toolCall.tool} succeeded:\n${truncated}`);
@@ -1203,6 +1280,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
     }
     catch (error) {
         const err = error;
+        auditFailure = err.message;
         result = {
             success: false,
             iterations: iteration,
@@ -1215,8 +1293,22 @@ export async function runAgent(prompt, projectContext, options = {}) {
     finally {
         // End session and save history. Skipped for nested runs so we don't write
         // a separate session file or null out the parent's open session.
-        if (!opts.nested)
+        if (!opts.nested) {
             endSession();
+            // In `finally`, so a run that throws still closes its record. An audit
+            // trail that only survives success is worth very little — the runs you
+            // most want to read are the ones that went wrong.
+            //
+            // The outcome comes from the result, not from whether an exception
+            // escaped. Several failure paths — a user abort, a 4xx from the provider
+            // — return `success: false` with a plain `return`, and reading only the
+            // catch recorded those as successful runs. An audit record that says a
+            // failed run passed is worse than having no record at all.
+            const failed = auditFailure ?? (result === undefined || result.success
+                ? undefined
+                : (result.aborted ? 'stopped by the user' : (result.error ?? 'run did not succeed')));
+            endAuditRun(auditRoot, auditRun, failed ? 'error' : 'ok', failed);
+        }
     }
 }
 /**

package/dist/utils/auditLog.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Audit record — what an agent actually touched.
+ *
+ * Distinct from `history.ts`, which exists to undo things: that journal keeps
+ * file contents so a write can be reversed, records only mutations, and lives
+ * in `~/.codeep/history/`. This one answers a different question — *what did
+ * this agent do to this project* — so it records reads and refusals too, keeps
+ * no file contents at all, and lives with the project it describes.
+ *
+ * The most valuable entry is the one nothing recorded before: a tool call the
+ * capability boundary refused. A boundary you cannot audit is a boundary you
+ * have to take on faith.
+ *
+ * Format is JSON Lines. Appending one line per event survives a crash mid-run,
+ * needs no read-modify-write, and stays greppable without a parser.
+ *
+ * PRIVACY: entries carry command lines and file paths, not file contents. A
+ * command can still contain a secret someone typed into it, exactly as shell
+ * history can — treat the directory like shell history, not like source.
+ *
+ * It sits under `.codeep/`, which most projects already ignore, but Codeep does
+ * not edit anyone's `.gitignore` and this module must not claim otherwise. If a
+ * project tracks `.codeep/`, the audit log will be committed with it.
+ */
+/** One thing an agent did, or was stopped from doing. */
+export interface AuditEvent {
+    /** Epoch millis. */
+    ts: number;
+    /** Groups every event from one agent run. */
+    run: string;
+    /** Provider-facing tool name, e.g. `read_file`. Absent on run markers. */
+    tool?: string;
+    /** What kind of thing happened. `refused` is a boundary denial. */
+    action: 'run-start' | 'run-end' | 'read' | 'write' | 'edit' | 'delete' | 'command' | 'search' | 'list' | 'mkdir' | 'fetch' | 'refused';
+    /** File path, command line, or URL — truncated, never file contents. */
+    target?: string;
+    outcome?: 'ok' | 'error' | 'refused';
+    /** Short reason or note. Never a file body. */
+    detail?: string;
+    /** Run markers only: the active custom bot and what it was granted. */
+    agent?: string;
+    capabilities?: string[];
+    prompt?: string;
+}
+/** A one-line, content-free description of what a tool call was aimed at.
+ *  Paths, commands and URLs are the point of the record; file bodies are not,
+ *  and `content`/`old_string` style arguments are never read here. */
+export declare function describeAuditTarget(call: {
+    tool: string;
+    parameters: Record<string, unknown>;
+}): string;
+/** Audit is on unless explicitly disabled. A record you have to remember to
+ *  switch on is not a record you can rely on having. */
+export declare function isAuditEnabled(): boolean;
+/**
+ * Append one event. Never throws: an unwritable project (read-only checkout,
+ * full disk, a directory we lack permission for) must not take the agent down
+ * with it. A missing audit line is a gap in the record; a crashed run is worse.
+ */
+export declare function recordAuditEvent(projectRoot: string, event: AuditEvent): void;
+/** Open a run and return its id. Records the agent and the capabilities it was
+ *  granted, so a later reader can tell what the boundary *was* at the time —
+ *  a bot edited afterwards must not rewrite the history of what it could do. */
+export declare function beginAuditRun(projectRoot: string, opts: {
+    prompt: string;
+    agent?: string;
+    capabilities?: string[];
+}): string;
+export declare function endAuditRun(projectRoot: string, run: string, outcome: 'ok' | 'error', detail?: string): void;
+/** One run, reassembled from its lines. */
+export interface AuditRun {
+    run: string;
+    startedAt: number;
+    endedAt?: number;
+    prompt?: string;
+    agent?: string;
+    capabilities?: string[];
+    outcome?: 'ok' | 'error';
+    events: AuditEvent[];
+    refusals: number;
+}
+/**
+ * Read back the most recent runs, newest first.
+ *
+ * Malformed lines are skipped rather than throwing: an append-only log written
+ * by a process that may be killed mid-write will occasionally end in a partial
+ * line, and one torn line must not make the whole record unreadable.
+ */
+export declare function readAuditRuns(projectRoot: string, limit?: number): AuditRun[];
+/** Render recent runs for `/audit`. Deliberately compact: the question this
+ *  answers is "what has been happening here", and a wall of every event
+ *  answers it worse than a summary with the refusals called out. */
+export declare function formatAuditLog(projectRoot: string, limit?: number): string;

package/dist/utils/auditLog.js

@@ -0,0 +1,217 @@
+/**
+ * Audit record — what an agent actually touched.
+ *
+ * Distinct from `history.ts`, which exists to undo things: that journal keeps
+ * file contents so a write can be reversed, records only mutations, and lives
+ * in `~/.codeep/history/`. This one answers a different question — *what did
+ * this agent do to this project* — so it records reads and refusals too, keeps
+ * no file contents at all, and lives with the project it describes.
+ *
+ * The most valuable entry is the one nothing recorded before: a tool call the
+ * capability boundary refused. A boundary you cannot audit is a boundary you
+ * have to take on faith.
+ *
+ * Format is JSON Lines. Appending one line per event survives a crash mid-run,
+ * needs no read-modify-write, and stays greppable without a parser.
+ *
+ * PRIVACY: entries carry command lines and file paths, not file contents. A
+ * command can still contain a secret someone typed into it, exactly as shell
+ * history can — treat the directory like shell history, not like source.
+ *
+ * It sits under `.codeep/`, which most projects already ignore, but Codeep does
+ * not edit anyone's `.gitignore` and this module must not claim otherwise. If a
+ * project tracks `.codeep/`, the audit log will be committed with it.
+ */
+import { existsSync, mkdirSync, appendFileSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+import { config } from '../config/index.js';
+/** A one-line, content-free description of what a tool call was aimed at.
+ *  Paths, commands and URLs are the point of the record; file bodies are not,
+ *  and `content`/`old_string` style arguments are never read here. */
+export function describeAuditTarget(call) {
+    const p = call.parameters ?? {};
+    const str = (k) => (typeof p[k] === 'string' ? p[k] : undefined);
+    const command = str('command');
+    if (command) {
+        const args = Array.isArray(p.args) ? p.args.map(String) : [];
+        return [command, ...args].join(' ');
+    }
+    return str('path') ?? str('url') ?? str('pattern') ?? str('query') ?? str('directory') ?? call.tool;
+}
+const MAX_TARGET = 300;
+const MAX_DETAIL = 200;
+const MAX_PROMPT = 400;
+function auditDir(projectRoot) {
+    return join(projectRoot, '.codeep', 'audit');
+}
+/** One file per day keeps a long-lived project from growing a single huge log
+ *  while staying trivial to find — no index, no rotation logic. */
+function auditFile(projectRoot) {
+    const day = new Date().toISOString().slice(0, 10);
+    return join(auditDir(projectRoot), `${day}.jsonl`);
+}
+function clip(value, max) {
+    if (value === undefined)
+        return undefined;
+    const flat = value.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? flat.slice(0, max - 1) + '…' : flat;
+}
+/** Audit is on unless explicitly disabled. A record you have to remember to
+ *  switch on is not a record you can rely on having. */
+export function isAuditEnabled() {
+    return config.get('auditLog') !== false;
+}
+/**
+ * Append one event. Never throws: an unwritable project (read-only checkout,
+ * full disk, a directory we lack permission for) must not take the agent down
+ * with it. A missing audit line is a gap in the record; a crashed run is worse.
+ */
+export function recordAuditEvent(projectRoot, event) {
+    if (!isAuditEnabled())
+        return;
+    try {
+        const dir = auditDir(projectRoot);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const line = {
+            ...event,
+            target: clip(event.target, MAX_TARGET),
+            detail: clip(event.detail, MAX_DETAIL),
+            prompt: clip(event.prompt, MAX_PROMPT),
+        };
+        // Drop undefined keys so a line stays small and diffs stay readable.
+        const compact = Object.fromEntries(Object.entries(line).filter(([, v]) => v !== undefined));
+        appendFileSync(auditFile(projectRoot), JSON.stringify(compact) + '\n');
+    }
+    catch {
+        /* an unwritable audit log must never fail the run */
+    }
+}
+/** Open a run and return its id. Records the agent and the capabilities it was
+ *  granted, so a later reader can tell what the boundary *was* at the time —
+ *  a bot edited afterwards must not rewrite the history of what it could do. */
+export function beginAuditRun(projectRoot, opts) {
+    const run = randomBytes(6).toString('hex');
+    recordAuditEvent(projectRoot, {
+        ts: Date.now(),
+        run,
+        action: 'run-start',
+        prompt: opts.prompt,
+        agent: opts.agent,
+        capabilities: opts.capabilities,
+    });
+    return run;
+}
+export function endAuditRun(projectRoot, run, outcome, detail) {
+    recordAuditEvent(projectRoot, { ts: Date.now(), run, action: 'run-end', outcome, detail });
+}
+/**
+ * Read back the most recent runs, newest first.
+ *
+ * Malformed lines are skipped rather than throwing: an append-only log written
+ * by a process that may be killed mid-write will occasionally end in a partial
+ * line, and one torn line must not make the whole record unreadable.
+ */
+export function readAuditRuns(projectRoot, limit = 20) {
+    const dir = auditDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = readdirSync(dir)
+            .filter(f => f.endsWith('.jsonl'))
+            .sort()
+            .reverse();
+    }
+    catch {
+        return [];
+    }
+    const runs = new Map();
+    for (const file of files) {
+        let raw;
+        try {
+            const path = join(dir, file);
+            if (statSync(path).size > 8 * 1024 * 1024)
+                continue; // skip an absurd file
+            raw = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!event || typeof event.run !== 'string' || typeof event.ts !== 'number')
+                continue;
+            let entry = runs.get(event.run);
+            if (!entry) {
+                entry = { run: event.run, startedAt: event.ts, events: [], refusals: 0 };
+                runs.set(event.run, entry);
+            }
+            if (event.action === 'run-start') {
+                entry.startedAt = event.ts;
+                entry.prompt = event.prompt;
+                entry.agent = event.agent;
+                entry.capabilities = event.capabilities;
+            }
+            else if (event.action === 'run-end') {
+                entry.endedAt = event.ts;
+                entry.outcome = event.outcome === 'error' ? 'error' : 'ok';
+            }
+            else {
+                entry.events.push(event);
+                if (event.action === 'refused')
+                    entry.refusals++;
+            }
+        }
+        if (runs.size >= limit * 2)
+            break; // enough files read to satisfy `limit`
+    }
+    return [...runs.values()]
+        .sort((a, b) => b.startedAt - a.startedAt)
+        .slice(0, limit);
+}
+/** Render recent runs for `/audit`. Deliberately compact: the question this
+ *  answers is "what has been happening here", and a wall of every event
+ *  answers it worse than a summary with the refusals called out. */
+export function formatAuditLog(projectRoot, limit = 10) {
+    const runs = readAuditRuns(projectRoot, limit);
+    if (runs.length === 0) {
+        return isAuditEnabled()
+            ? 'No agent runs recorded in this project yet.\n\nThe record starts at the next run and lives in `.codeep/audit/`.'
+            : 'Audit recording is off for this project. Turn it on with `/audit on`.';
+    }
+    const lines = ['**Recent agent runs** — `.codeep/audit/`', ''];
+    for (const run of runs) {
+        const when = new Date(run.startedAt).toLocaleString();
+        const took = run.endedAt ? `${Math.max(1, Math.round((run.endedAt - run.startedAt) / 1000))}s` : 'unfinished';
+        const who = run.agent ? `**${run.agent}**` : 'default agent';
+        const grant = run.capabilities?.length ? ` (${run.capabilities.join(', ')})` : '';
+        const mark = run.outcome === 'error' ? '✗' : '✓';
+        lines.push(`${mark} ${when} · ${who}${grant} · ${took}`);
+        if (run.prompt)
+            lines.push(`   ${run.prompt}`);
+        // Summarise by action so a hundred reads collapse to "read ×100".
+        const tally = new Map();
+        for (const e of run.events)
+            tally.set(e.action, (tally.get(e.action) ?? 0) + 1);
+        const summary = [...tally.entries()].map(([a, n]) => (n > 1 ? `${a} ×${n}` : a)).join(', ');
+        if (summary)
+            lines.push(`   ${summary}`);
+        // Refusals are the reason this record exists, so they are never collapsed.
+        for (const e of run.events.filter(e => e.action === 'refused')) {
+            lines.push(`   ⨯ refused: ${e.tool}${e.target ? ` → ${e.target}` : ''}`);
+        }
+        lines.push('');
+    }
+    lines.push('_Paths and commands only — file contents are never recorded._');
+    return lines.join('\n');
+}

package/dist/utils/headlessReview.d.ts

@@ -1,3 +1,4 @@
+import { type FixPlan } from './reviewFix.js';
 import { ReviewResult } from './codeReview.js';
 export type FailOn = 'error' | 'warning' | 'info' | 'none';
 export interface ReviewArgs {
@@ -7,8 +8,12 @@ export interface ReviewArgs {
     rules: boolean;
     ai: boolean;
     help: boolean;
+    /** Hand the findings to an agent and let it edit the working tree. */
+    fix: boolean;
+    /** Lowest severity the fix run may act on. Suggestions are never eligible. */
+    fixMinSeverity: 'error' | 'warning';
 }
-export declare const REVIEW_HELP = "Usage: codeep review [options] [files...]\n\nRun a deterministic, offline code review (no API key required). With no files,\nreviews your unstaged git changes, falling back to a src/ scan when the tree is\nclean. Pass files (or let your CI pass the PR's changed files) to scope it.\n\nCustom/disabled rules come from .codeep/review.yml (or .json) in the repo.\n\nOptions:\n  --json              Print the result as JSON instead of the markdown report\n  --fail-on <level>   Exit non-zero when an issue at or above <level> is found:\n                      error | warning | info | none   (default: error)\n  --rules             List the built-in rule ids (for \"disable\" in .codeep/review.*) and exit\n  --ai                After the offline pass, ask your configured provider for a\n                      contextual second opinion on the working-tree diff\n                      (advisory; needs an API key; never affects the exit code)\n  -h, --help          Show this help\n\nExit code: 0 when nothing at/above --fail-on is found, 1 otherwise.";
+export declare const REVIEW_HELP = "Usage: codeep review [options] [files...]\n\nRun a deterministic, offline code review (no API key required). With no files,\nreviews your unstaged git changes, falling back to a src/ scan when the tree is\nclean. Pass files (or let your CI pass the PR's changed files) to scope it.\n\nCustom/disabled rules come from .codeep/review.yml (or .json) in the repo.\n\nOptions:\n  --json              Print the result as JSON instead of the markdown report\n  --fail-on <level>   Exit non-zero when an issue at or above <level> is found:\n                      error | warning | info | none   (default: error)\n  --fix               After the review, let an agent fix what it found. Edits the\n                      working tree and stops there \u2014 it never commits, branches\n                      or pushes. Runs under a files+tests boundary: no shell, no\n                      network, no git. Needs an API key.\n  --fix-min-severity  Lowest severity --fix may act on: error | warning\n                      (default: warning). Suggestions are never eligible.\n  --rules             List the built-in rule ids (for \"disable\" in .codeep/review.*) and exit\n  --ai                After the offline pass, ask your configured provider for a\n                      contextual second opinion on the working-tree diff\n                      (advisory; needs an API key; never affects the exit code)\n  -h, --help          Show this help\n\nExit code: 0 when nothing at/above --fail-on is found, 1 otherwise.";
 /** Parse `codeep review` argv (everything after the subcommand). Pure. */
 export declare function parseReviewArgs(argv: string[]): ReviewArgs;
 /** Exit code for a result under a fail-on threshold. Pure. */
@@ -29,6 +34,9 @@ export interface ReviewDeps {
         provider?: string;
         model?: string;
     };
+    /** Run an agent over a fix plan. Returns a human summary, or null when it
+     *  could not run at all (no API key, provider unreachable). */
+    applyFixes: (plan: FixPlan) => Promise<string | null>;
 }
 /**
  * Orchestrate a headless review and return the process exit code. Side effects

package/dist/utils/headlessReview.js

@@ -1,3 +1,4 @@
+import { buildFixPlan, summariseFixPlan } from './reviewFix.js';
 // Headless `codeep review` — a non-interactive entry point around the
 // deterministic reviewer in codeReview.ts. No API key, no TUI: it scans, prints
 // a report (markdown or JSON), and exits non-zero when issues at/above a chosen
@@ -24,6 +25,12 @@ Options:
   --json              Print the result as JSON instead of the markdown report
   --fail-on <level>   Exit non-zero when an issue at or above <level> is found:
                       error | warning | info | none   (default: error)
+  --fix               After the review, let an agent fix what it found. Edits the
+                      working tree and stops there — it never commits, branches
+                      or pushes. Runs under a files+tests boundary: no shell, no
+                      network, no git. Needs an API key.
+  --fix-min-severity  Lowest severity --fix may act on: error | warning
+                      (default: warning). Suggestions are never eligible.
   --rules             List the built-in rule ids (for "disable" in .codeep/review.*) and exit
   --ai                After the offline pass, ask your configured provider for a
                       contextual second opinion on the working-tree diff
@@ -33,7 +40,10 @@ Options:
 Exit code: 0 when nothing at/above --fail-on is found, 1 otherwise.`;
 /** Parse `codeep review` argv (everything after the subcommand). Pure. */
 export function parseReviewArgs(argv) {
-    const out = { files: [], json: false, failOn: 'error', rules: false, ai: false, help: false };
+    const out = {
+        files: [], json: false, failOn: 'error', rules: false, ai: false, help: false,
+        fix: false, fixMinSeverity: 'warning',
+    };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '--json') {
@@ -45,6 +55,19 @@ export function parseReviewArgs(argv) {
         else if (arg === '--ai') {
             out.ai = true;
         }
+        else if (arg === '--fix') {
+            out.fix = true;
+        }
+        else if (arg === '--fix-min-severity') {
+            const v = argv[++i];
+            if (v === 'error' || v === 'warning')
+                out.fixMinSeverity = v;
+        }
+        else if (arg.startsWith('--fix-min-severity=')) {
+            const v = arg.slice('--fix-min-severity='.length);
+            if (v === 'error' || v === 'warning')
+                out.fixMinSeverity = v;
+        }
         else if (arg === '-h' || arg === '--help') {
             out.help = true;
         }
@@ -104,12 +127,26 @@ export async function runHeadlessReview(argv, deps = defaultDeps()) {
     }
     const result = deps.review(args.files.length ? args.files : undefined);
     const aiText = args.ai ? await deps.aiReview(result) : null;
+    // Fixing happens after reporting, and never changes the exit code. CI decides
+    // pass or fail from what the reviewer found; whether an agent then managed to
+    // repair some of it is a separate question, and letting a successful fix turn
+    // a red check green would hide the finding rather than resolve it.
+    let fixSummary = null;
+    if (args.fix) {
+        const plan = buildFixPlan(result.issues, { minSeverity: args.fixMinSeverity });
+        fixSummary = plan.skipped ? summariseFixPlan(plan) : await deps.applyFixes(plan);
+    }
     if (args.json) {
-        deps.write(JSON.stringify(args.ai ? { ...result, aiReview: aiText } : result, null, 2));
+        deps.write(JSON.stringify({
+            ...result,
+            ...(args.ai ? { aiReview: aiText } : {}),
+            ...(args.fix ? { fix: fixSummary } : {}),
+        }, null, 2));
     }
     else {
         const md = formatReviewResult(result);
-        deps.write(args.ai ? appendAiSection(md, aiText, deps.aiMeta()) : md);
+        const withAi = args.ai ? appendAiSection(md, aiText, deps.aiMeta()) : md;
+        deps.write(fixSummary ? `${withAi}\n\n## Fix run\n\n${fixSummary}\n` : withAi);
     }
     return exitCodeForResult(result, args.failOn);
 }
@@ -132,6 +169,7 @@ function defaultDeps() {
         review: (files) => performCodeReview(minimalContext(cwd), files),
         write: (text) => process.stdout.write(text + '\n'),
         listRules: () => formatBuiltinRules(),
+        applyFixes: (plan) => runFixPlan(plan, minimalContext(cwd)),
         aiMeta: () => {
             try {
                 return { provider: getCurrentProvider().name, model: String(config.get('model') || '') };
@@ -165,3 +203,39 @@ function defaultDeps() {
         },
     };
 }
+/**
+ * Run a fix plan through the agent.
+ *
+ * The plan's personality is passed as the active one, so the same enforcement
+ * any custom bot gets applies here: the model is offered `files` and `tests`
+ * and nothing else. It edits the working tree and stops — branching, committing
+ * and opening a pull request belong to whatever called this, which in CI is the
+ * action that holds the token.
+ */
+async function runFixPlan(plan, context) {
+    try {
+        const { runAgent } = await import('./agent.js');
+        // No cast here. `as never` on this call once hid the fact that
+        // personalityOverride did not exist, which would have run the CI fix with
+        // no boundary at all while the tests happily asserted otherwise.
+        const result = await runAgent(plan.prompt, context, {
+            personalityOverride: plan.personality,
+            maxIterations: 12,
+        });
+        const edited = new Set(result.actions
+            .filter(a => a.type === 'write' || a.type === 'edit')
+            .map(a => a.target));
+        if (!result.success) {
+            return `${summariseFixPlan(plan)} The run did not finish: ${result.error ?? 'unknown error'}.`;
+        }
+        if (edited.size === 0) {
+            return `${summariseFixPlan(plan)} Nothing was changed — the agent judged the findings not mechanically fixable.`;
+        }
+        return `${summariseFixPlan(plan)} Edited ${edited.size} file${edited.size === 1 ? '' : 's'}: ${[...edited].join(', ')}.`;
+    }
+    catch (error) {
+        // A missing key or an unreachable provider must not fail the review. The
+        // findings are already reported and the exit code already decided.
+        return `Could not run the fix: ${error.message}`;
+    }
+}

package/dist/utils/reviewFix.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deciding what a CI agent may attempt to fix, and under what boundary.
+ *
+ * The reviewer already finds problems. This decides which of them are worth
+ * handing to an agent, caps how much it may take on, and pins the capabilities
+ * it runs with. It deliberately stops there: it produces a plan, never a
+ * commit. Staging, branching and opening a pull request belong to the action,
+ * which has the token — and keeping git out of the agent's reach is half the
+ * reason this is safe to run in CI at all.
+ *
+ * The boundary is the point. A fix run gets `files` (it must edit) and `tests`
+ * (it must check its own work) and nothing else. No shell, no git, no network.
+ * Enforced by the same machinery as any other custom bot, so an agent that
+ * decides it would like to curl something simply has no tool to do it with.
+ */
+import type { ReviewIssue } from './codeReview.js';
+import type { Personality } from './personalities.js';
+export interface FixPlanOptions {
+    /** Lowest severity to attempt. Defaults to `warning`. */
+    minSeverity?: 'error' | 'warning';
+    /** Most issues to hand over in one run. */
+    maxIssues?: number;
+    /** Most files to touch. A fix that rewrites half the repo is not a fix. */
+    maxFiles?: number;
+}
+export interface FixPlan {
+    /** The issues the agent is being asked to address, in file order. */
+    issues: ReviewIssue[];
+    /** Files it is allowed to be working in. */
+    files: string[];
+    /** Why nothing is being attempted, when that is the case. */
+    skipped?: 'no-issues' | 'nothing-fixable';
+    /** The instruction handed to the agent. */
+    prompt: string;
+    /** The capability boundary the run executes under. */
+    personality: Personality;
+}
+/**
+ * `suggestion` and `info` are opinion — style preferences, "consider extracting
+ * this". Acting on them unasked produces churn in someone else's pull request
+ * and buries the findings that matter. Only what the reviewer states as a
+ * defect is eligible.
+ */
+export declare function isFixable(issue: ReviewIssue, minSeverity: 'error' | 'warning'): boolean;
+/**
+ * The capability set a CI fix runs under.
+ *
+ * Not a suggestion in the prompt — a real `custom-bot/v1` personality, enforced
+ * by `isPersonalityToolCallAllowed` and by the tool registry filter, exactly as
+ * a bot built in Agent Studio would be. An agent running unattended against
+ * someone else's repository is precisely where a boundary has to be real.
+ */
+export declare function ciFixPersonality(): Personality;
+/**
+ * Turn a review into a bounded instruction, or decline.
+ *
+ * Caps matter more than they look. An agent handed sixty findings across forty
+ * files will produce a pull request nobody reviews, which is the same as no
+ * pull request — except it also burned tokens and someone's afternoon.
+ */
+export declare function buildFixPlan(issues: ReviewIssue[], options?: FixPlanOptions): FixPlan;
+/** The instruction the agent receives: the findings, grouped by file. */
+export declare function formatFixPrompt(issues: ReviewIssue[]): string;
+/** A one-line summary for the pull request body the action opens. */
+export declare function summariseFixPlan(plan: FixPlan): string;

package/dist/utils/reviewFix.js

@@ -0,0 +1,141 @@
+/**
+ * Deciding what a CI agent may attempt to fix, and under what boundary.
+ *
+ * The reviewer already finds problems. This decides which of them are worth
+ * handing to an agent, caps how much it may take on, and pins the capabilities
+ * it runs with. It deliberately stops there: it produces a plan, never a
+ * commit. Staging, branching and opening a pull request belong to the action,
+ * which has the token — and keeping git out of the agent's reach is half the
+ * reason this is safe to run in CI at all.
+ *
+ * The boundary is the point. A fix run gets `files` (it must edit) and `tests`
+ * (it must check its own work) and nothing else. No shell, no git, no network.
+ * Enforced by the same machinery as any other custom bot, so an agent that
+ * decides it would like to curl something simply has no tool to do it with.
+ */
+/** Severities an agent may act on, in descending confidence. */
+const FIXABLE_SEVERITIES = ['error', 'warning'];
+const DEFAULTS = { minSeverity: 'warning', maxIssues: 20, maxFiles: 10 };
+/**
+ * `suggestion` and `info` are opinion — style preferences, "consider extracting
+ * this". Acting on them unasked produces churn in someone else's pull request
+ * and buries the findings that matter. Only what the reviewer states as a
+ * defect is eligible.
+ */
+export function isFixable(issue, minSeverity) {
+    if (!FIXABLE_SEVERITIES.includes(issue.severity))
+        return false;
+    return minSeverity === 'warning' ? true : issue.severity === 'error';
+}
+/**
+ * The capability set a CI fix runs under.
+ *
+ * Not a suggestion in the prompt — a real `custom-bot/v1` personality, enforced
+ * by `isPersonalityToolCallAllowed` and by the tool registry filter, exactly as
+ * a bot built in Agent Studio would be. An agent running unattended against
+ * someone else's repository is precisely where a boundary has to be real.
+ */
+export function ciFixPersonality() {
+    return {
+        name: 'ci-fix',
+        displayName: 'CI Fix',
+        description: 'Applies review findings in CI. Files and tests only.',
+        prompt: [
+            'You are fixing problems a reviewer already found in a pull request.',
+            '',
+            'Rules:',
+            '- Fix only the issues listed. Do not refactor around them.',
+            '- Do not reformat untouched lines; the diff should read as a fix, not a rewrite.',
+            '- Run the project tests when you are done and fix what you broke.',
+            '- If an issue needs a judgement call you cannot make from the code, leave it and say so.',
+        ].join('\n'),
+        scope: 'project',
+        structured: true,
+        schemaValid: true,
+        modelPreference: 'automatic',
+        restrictTools: true,
+        tools: ['files', 'tests'],
+        declaredTools: ['files', 'tests'],
+        projectScope: 'all',
+    };
+}
+/**
+ * Turn a review into a bounded instruction, or decline.
+ *
+ * Caps matter more than they look. An agent handed sixty findings across forty
+ * files will produce a pull request nobody reviews, which is the same as no
+ * pull request — except it also burned tokens and someone's afternoon.
+ */
+export function buildFixPlan(issues, options = {}) {
+    const { minSeverity, maxIssues, maxFiles } = { ...DEFAULTS, ...options };
+    const personality = ciFixPersonality();
+    if (issues.length === 0) {
+        return { issues: [], files: [], skipped: 'no-issues', prompt: '', personality };
+    }
+    const eligible = issues
+        .filter(issue => isFixable(issue, minSeverity))
+        // Errors before warnings, then by file so one file's issues arrive together.
+        .sort((a, b) => {
+        if (a.severity !== b.severity)
+            return a.severity === 'error' ? -1 : 1;
+        return a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0);
+    });
+    if (eligible.length === 0) {
+        return { issues: [], files: [], skipped: 'nothing-fixable', prompt: '', personality };
+    }
+    // Take whole files rather than cutting a file's issues in half — a partial
+    // fix to one file is the worst outcome available, since it looks addressed.
+    const files = [];
+    const taken = [];
+    for (const issue of eligible) {
+        const knownFile = files.includes(issue.file);
+        if (!knownFile && files.length >= maxFiles)
+            continue;
+        if (taken.length >= maxIssues && !knownFile)
+            continue;
+        if (!knownFile)
+            files.push(issue.file);
+        taken.push(issue);
+    }
+    return { issues: taken, files, prompt: formatFixPrompt(taken), personality };
+}
+/** The instruction the agent receives: the findings, grouped by file. */
+export function formatFixPrompt(issues) {
+    const byFile = new Map();
+    for (const issue of issues) {
+        const list = byFile.get(issue.file) ?? [];
+        list.push(issue);
+        byFile.set(issue.file, list);
+    }
+    const lines = [
+        `Fix the following ${issues.length} review finding${issues.length === 1 ? '' : 's'}.`,
+        '',
+    ];
+    for (const [file, found] of byFile) {
+        lines.push(`## ${file}`);
+        for (const issue of found) {
+            const where = issue.line ? `line ${issue.line}` : 'file';
+            lines.push(`- [${issue.severity}] ${where}: ${issue.message}`);
+            if (issue.suggestion)
+                lines.push(`  suggested: ${issue.suggestion}`);
+        }
+        lines.push('');
+    }
+    lines.push('Change nothing outside these files.');
+    return lines.join('\n');
+}
+/** A one-line summary for the pull request body the action opens. */
+export function summariseFixPlan(plan) {
+    if (plan.skipped === 'no-issues')
+        return 'The review found nothing.';
+    if (plan.skipped === 'nothing-fixable') {
+        return 'The review found only suggestions, which are left for a human to weigh.';
+    }
+    const errors = plan.issues.filter(i => i.severity === 'error').length;
+    const warnings = plan.issues.length - errors;
+    const parts = [
+        errors ? `${errors} error${errors === 1 ? '' : 's'}` : '',
+        warnings ? `${warnings} warning${warnings === 1 ? '' : 's'}` : '',
+    ].filter(Boolean);
+    return `Attempting ${parts.join(' and ')} across ${plan.files.length} file${plan.files.length === 1 ? '' : 's'}.`;
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "2.21.0";
+export declare const VERSION = "2.22.0";

package/dist/version.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/gen-version.js — do not edit by hand.
 // Baked from package.json at build time so the bun-compiled binary reports
 // the right version (it has no package.json on disk to read at runtime).
-export const VERSION = '2.21.0';
+export const VERSION = '2.22.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeep",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "AI-powered coding assistant built for the terminal. Multiple LLM providers, project-aware context, and a seamless development workflow.",
   "type": "module",
   "main": "dist/index.js",