backlens 0.2.0 → 0.2.2

package/README.md

@@ -47,7 +47,9 @@ backlens: 2 new issues. Fix them, or accept with --update-baseline.
 
 ## Missing indexes
 
-For each distinct SELECT, backlens asks Postgres for its plan with `EXPLAIN (GENERIC_PLAN)` (Postgres 16+). Plain EXPLAIN never runs the query, and the generic plan needs no parameter values. When a table is read row by row while filtering on columns that no index starts with, the Issues tab names the table and columns and gives the `CREATE INDEX` to add. It checks whether an index exists, not how fast the query was, so it is right on a small dev database too.
+For each distinct SELECT, backlens asks Postgres for its plan with `EXPLAIN (GENERIC_PLAN)` (Postgres 16+). Plain EXPLAIN never runs the query, and the generic plan needs no parameter values. When a table is read row by row while filtering on columns that no index starts with, the Issues tab names the table and columns and gives the `CREATE INDEX` to add. It checks whether an index exists, not how fast the query was, so it is right on a small dev database too. When the query also sorts (`ORDER BY … LIMIT`), the sort columns go after the filter columns, so Postgres reads rows already in order.
+
+**Create on this database** builds the index on the database your app is connected to, through the app's own connection: backlens never sees a database password. It shows which database first, builds with `CONCURRENTLY` so writes are not blocked, checks that Postgres can use the index for the query, and **Undo** drops it again. Only an index on the columns backlens checked can be created this way, never arbitrary SQL. Use it on a development database, then add the SQL to a migration.
 
 ## Before and after
 
@@ -55,7 +57,7 @@ In the Compare tab, save a snapshot, change your code, restart, use the same pag
 
 ## Explain and fix, with proof
 
-Every issue has **Explain** and **Suggest fix**. A fix goes: a preview of exactly what would be sent and to whom, the model's answer as a diff, **Apply and check** (only on files with no uncommitted changes, with a backup), then backlens rebuilds if needed, restarts your app, replays the request that showed the issue and runs your tests. Only a fix that removes the issue and keeps the tests green is marked proven. Keep it, or revert to the exact files you had.
+Every issue has **Explain** and **Suggest fix**. A fix goes: a preview of exactly what would be sent and to whom, the model's answer as a diff, **Apply and check** (with an exact copy of each file kept first, uncommitted changes included; Revert refuses to overwrite edits you made after the fix was applied), then backlens rebuilds if needed, restarts your app, replays the request that showed the issue and runs your tests. Only a fix that removes the issue and keeps the tests green is marked proven. Keep it, or revert to the exact files you had.
 
 Who answers is set up in **AI settings**, all from the dashboard. The first-run setup asks too.
 

package/ai/fixes.js

@@ -14,8 +14,8 @@ import { promiseAll } from './templates.js';
 /**
  * Explain and Fix. A fix runs like a careful developer at a terminal, and every step is written to
  * a live feed the dashboard shows: read the code, ask the model, check each edit fits the code
- * (sending problems back, up to twice), apply only to files with no uncommitted changes (with a
- * backup), typecheck (sending type errors back, up to twice), rebuild if needed, restart, replay
+ * (sending problems back, up to twice), apply (keeping an exact copy of each file as it was, uncommitted
+ * changes included), typecheck (sending type errors back, up to twice), rebuild if needed, restart, replay
  * the request that showed the issue, run the tests. Only then is it called proven.
  */
 
@@ -139,7 +139,7 @@ export function createAI(deps) {
   }
 
   const view = (job) => {
-    const { ctx, issue, backups, convo, abort, ...rest } = job;
+    const { ctx, issue, backups, convo, abort, afterTrace, written, ...rest } = job;
     return { ...rest, now: Date.now(), issueTitle: issue.title, issueRoute: issue.route, spentTodayUsd: spentToday(), budgetUsd: settings.dailyBudgetUsd };
   };
 
@@ -296,6 +296,14 @@ export function createAI(deps) {
     }
   }
 
+  function readSafe(file) {
+    try {
+      return readFileSync(file, 'utf8');
+    } catch {
+      return null;
+    }
+  }
+
   function restoreBackups(job) {
     for (const b of job.backups || []) copyFileSync(b.backup, join(root, b.file));
   }
@@ -387,6 +395,7 @@ export function createAI(deps) {
         job.stage = ok.length ? 'proposed' : 'no-edits';
       } catch (err) {
         job.error = err.message;
+        job.errorCode = err.code || null;
         job.stage = 'error';
       }
     })();
@@ -401,17 +410,17 @@ export function createAI(deps) {
       return null; // not a git repository: backups are the only undo
     }
     const out = execFileSync('git', ['-C', root, 'status', '--porcelain', '--', ...files.map((f) => join(root, f))], { encoding: 'utf8' });
-    return out.trim().split('\n').filter(Boolean).map((l) => l.slice(3));
+    // Porcelain lines are 'XY path': the status columns can start with a space, so no trim before slicing.
+    return out.split('\n').filter((l) => l.trim()).map((l) => l.slice(3));
   }
 
   function apply(id) {
     const job = jobs.get(id);
     if (!job || job.stage !== 'proposed') throw new Error('There is no suggestion ready to apply.');
     const files = [...new Set(job.edits.map((e) => e.file))];
-    const dirty = gitDirty(files);
-    if (dirty && dirty.length) {
-      throw new Error(`${dirty.join(', ')} ${dirty.length === 1 ? 'has' : 'have'} uncommitted changes. Commit or stash ${dirty.length === 1 ? 'it' : 'them'} first, so this fix can always be undone cleanly.`);
-    }
+    // Files with uncommitted changes (an earlier kept fix, work in progress) are fine: the backup
+    // is an exact copy of the file as it is now, and Revert puts that copy back.
+    const dirty = gitDirty(files) || [];
     const backupDir = join(dir, 'ai', job.id);
     job.backups = [];
     for (const f of files) {
@@ -421,7 +430,13 @@ export function createAI(deps) {
       job.backups.push({ file: f, backup: dest });
     }
     writeEdits(job.edits);
-    ev(job, 'apply', `Applied ${job.edits.length} edit${job.edits.length === 1 ? '' : 's'} to ${files.join(', ')}`, { detail: 'backup kept until you keep or revert' });
+    // What backlens wrote, so Revert can tell whether someone edited the file afterwards.
+    job.written = Object.fromEntries(files.map((f) => [f, readFileSync(join(root, f), 'utf8')]));
+    ev(job, 'apply', `Applied ${job.edits.length} edit${job.edits.length === 1 ? '' : 's'} to ${files.join(', ')}`, {
+      detail: dirty.length
+        ? `a copy of ${dirty.join(', ')} as it was, uncommitted changes included, is kept until you keep or revert`
+        : 'backup kept until you keep or revert',
+    });
     job.stage = 'verifying';
     deps.pauseWatch(true);
     verify(job)
@@ -468,6 +483,12 @@ export function createAI(deps) {
     return { ok: r.code === 0, errors: r.out };
   }
 
+  /** What a request cost: the numbers shown before and after a fix. */
+  function stats(trace) {
+    const count = (kind) => trace.spans.filter((x) => x.kind === kind).length;
+    return { status: trace.status, ms: trace.duration, queries: count('db'), redis: count('redis'), http: count('http') };
+  }
+
   function replay(job, payload, port) {
     return new Promise((resolve) => {
       const timer = setTimeout(() => {
@@ -501,6 +522,7 @@ export function createAI(deps) {
       const ok = await propose(job, `Asking again with the type errors (${round + 1} of ${TYPE_REPAIRS})`);
       if (!ok.length) return finish(job, false, 'The model could not produce a change that typechecks.');
       writeEdits(ok);
+      job.written = Object.fromEntries(job.backups.map((b) => [b.file, readSafe(join(root, b.file))]));
       ev(job, 'apply', `Applied ${ok.length} corrected edit${ok.length === 1 ? '' : 's'}`);
     }
 
@@ -532,6 +554,9 @@ export function createAI(deps) {
       r.status = 'skip';
       r.detail = settings.replay ? 'the request that showed this issue is no longer in memory; use the page again to record a fresh one' : 'replay is off in AI settings';
     } else {
+      // The app has just restarted, so its first request pays for cold caches and new connections.
+      // A read is sent once to warm up, and the second one is measured.
+      if (!isWrite) await replay(job, payload, deps.appPort());
       const trace = await replay(job, payload, deps.appPort());
       if (!trace) {
         r.status = 'fail';
@@ -544,6 +569,8 @@ export function createAI(deps) {
       const before = original ? `${original.status} in ${original.duration} ms, ${original.spans.length} calls` : '';
       r.status = !still && sameClass ? 'done' : 'fail';
       r.detail = `before: ${before}\nafter:  ${trace.status} in ${trace.duration} ms, ${trace.spans.length} calls${still ? ', issue still there' : ', issue gone'}`;
+      job.compare = { before: original ? stats(original) : null, after: stats(trace), issueGone: !still, warmed: !isWrite };
+      job.afterTrace = trace;
       if (trace.status === 401 && original && original.status !== 401) r.detail += '\nThe recorded login may have expired: sign in again and use the page once more.';
       if (r.status === 'fail') return finish(job, false, still ? 'The issue is still there after the change.' : `The request now answers ${trace.status}.`);
     }
@@ -585,6 +612,8 @@ export function createAI(deps) {
     append(historyFile, { at: new Date().toISOString(), type: job.issue.type, tier: job.route.tier || job.route.kind, model: job.route.model, verified: Boolean(job.verified), kept: true });
     cleanup(job);
     job.stage = 'kept';
+    // The measured request joins the normal list, and the issue leaves it until a request shows it again.
+    if (deps.markFixed) deps.markFixed(job.issue.key, job.afterTrace && job.compare && job.compare.issueGone ? job.afterTrace : null);
     ev(job, 'done', 'Kept. Review it in your editor and commit when ready.');
     return view(job);
   }
@@ -592,6 +621,11 @@ export function createAI(deps) {
   async function revert(id) {
     const job = jobs.get(id);
     if (!job || !job.backups || !job.backups.length) throw new Error('Nothing to revert.');
+    // Never overwrite edits made after the fix was applied.
+    const changed = job.backups.filter((b) => job.written && job.written[b.file] !== undefined && readSafe(join(root, b.file)) !== job.written[b.file]);
+    if (changed.length) {
+      throw new Error(`${changed.map((b) => b.file).join(', ')} changed after the fix was applied, so backlens did not overwrite it. The version from before the fix is at ${changed.map((b) => relative(root, b.backup)).join(', ')}.`);
+    }
     restoreBackups(job);
     append(historyFile, { at: new Date().toISOString(), type: job.issue.type, tier: job.route.tier || job.route.kind, model: job.route.model, verified: Boolean(job.verified), kept: false });
     cleanup(job);

package/ai/providers.js

@@ -362,7 +362,12 @@ async function anthropic(task, messages, routeInfo) {
   } catch (err) {
     if (err instanceof Anthropic.AuthenticationError) throw new Error('Claude rejected the key. Paste a new one in AI settings.');
     if (err instanceof Anthropic.RateLimitError) throw new Error('Claude rate limit reached. Wait a minute and try again.');
-    if (err instanceof Anthropic.APIError) throw new Error(`Claude error ${err.status}: ${err.message}`);
+    // The SDK's message carries the raw JSON body; show the API's own sentence instead.
+    const said = err?.error?.error?.message || err.message;
+    if (err instanceof Anthropic.APIError && /credit balance/i.test(said)) {
+      throw Object.assign(new Error('Your Anthropic account has no credit left, so nothing was sent or charged. Add credits in the Anthropic Console, then try again.'), { code: 'billing' });
+    }
+    if (err instanceof Anthropic.APIError) throw new Error(`Claude error ${err.status}: ${said}`);
     throw err;
   }
   const cost = costUsd(routeInfo.tier, response.usage);

package/analyze.js

@@ -236,7 +236,11 @@ function percentile(values, p) {
 }
 
 /** Routes and issues across every trace kept. */
-export function summarize(traces, known = [], advice = []) {
+/**
+ * fixed: issue key -> when a fix for it was kept. Such an issue is hidden until a request after
+ * that moment shows it again.
+ */
+export function summarize(traces, known = [], advice = [], fixed = new Map()) {
   const routes = new Map();
   const issues = new Map();
   for (const trace of traces) {
@@ -259,6 +263,7 @@ export function summarize(traces, known = [], advice = []) {
       agg.seen++;
       agg.costTotal += issue.cost;
       agg.example = trace.id;
+      agg.lastAt = Math.max(agg.lastAt || 0, trace.at || 0);
     }
   }
   // Index advice: one issue per route that ran the query. Its location skips wrapper lines that
@@ -281,11 +286,15 @@ export function summarize(traces, known = [], advice = []) {
       const span = trace.spans.find((s) => s.kind === 'db' && normalizeSql(s.name) === sql);
       if (!span) continue;
       const route = routeOf(trace.method, trace.url, trace.template);
-      if (!perRoute.has(route)) perRoute.set(route, { seen: 0, example: trace.id, span });
+      if (!perRoute.has(route)) perRoute.set(route, { seen: 0, example: trace.id, span, lastAt: 0 });
       perRoute.get(route).seen++;
+      perRoute.get(route).lastAt = Math.max(perRoute.get(route).lastAt, trace.at || 0);
     }
     const big = a.rows >= 1000;
-    const name = `${a.table}_${a.columns.join('_')}_idx`.slice(0, 63);
+    // Filter columns first, then the ORDER BY columns, so rows come out already sorted.
+    const cols = [...a.columns.map((c) => ({ name: c, desc: false })), ...(Array.isArray(a.sort) ? a.sort : []).filter((c) => c && typeof c.name === 'string')];
+    const name = `${a.table}_${cols.map((c) => c.name).join('_')}_idx`.slice(0, 63);
+    const colText = cols.map((c) => `${c.name}${c.desc ? ' DESC' : ''}`).join(', ');
     for (const [route, info] of perRoute) {
       const key = `index|${route}|${sql}|${a.table}`;
       routes.get(route)?.issueKeys.add(key);
@@ -293,7 +302,8 @@ export function summarize(traces, known = [], advice = []) {
         type: 'index',
         severity: big ? 'warn' : 'hint',
         title: `No index for ${a.table} filtered by ${a.columns.join(', ')}`,
-        fix: `Postgres reads every row of ${a.table} (${a.rows.toLocaleString('en')} now${big ? '' : ', fine while small, slow as it grows'}). Add: CREATE INDEX CONCURRENTLY ${name} ON ${a.schema === 'public' ? '' : `${a.schema}.`}${a.table} (${a.columns.join(', ')});`,
+        fix: `Postgres reads every row of ${a.table} (${a.rows.toLocaleString('en')} now${big ? '' : ', fine while small, slow as it grows'}). Add: CREATE INDEX CONCURRENTLY ${name} ON ${a.schema === 'public' ? '' : `${a.schema}.`}${a.table} (${colText});`,
+        index: { schema: a.schema || 'public', table: a.table, name, columns: cols, sql: a.sql },
         sql,
         sites: appFrame(info.span.frames) ? [at(appFrame(info.span.frames))] : [],
         frames: [info.span.frames],
@@ -302,6 +312,7 @@ export function summarize(traces, known = [], advice = []) {
         route,
         seen: info.seen,
         example: info.example,
+        lastAt: info.lastAt,
         costTotal: 0,
       });
     }
@@ -311,6 +322,12 @@ export function summarize(traces, known = [], advice = []) {
   for (const route of known) {
     if (!routes.has(route)) routes.set(route, { route, calls: 0, durations: [], queries: 0, redis: 0, http: 0, errors: 0, issueKeys: new Set(), last: 0 });
   }
+  for (const [key, issue] of issues) {
+    if (fixed.has(key) && fixed.get(key) >= (issue.lastAt || 0)) {
+      issues.delete(key);
+      routes.get(issue.route)?.issueKeys.delete(key);
+    }
+  }
   const routeList = [...routes.values()]
     .map((r) => ({
       route: r.route,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlens",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Run your Node backend through backlens and see every request, every query, and what is wrong with them.",
   "license": "MIT",
   "type": "module",

package/register.cjs

@@ -232,6 +232,10 @@ if (TARGET && !globalThis.__backlens) {
           if (address && typeof address === 'object') post('/listening', { port: address.port, pid: process.pid, source: SOURCE });
         } catch {}
       }
+      if (event === 'request' && req && res && req.url === '/__backlens/index' && req.method === 'POST' && tokenOk(req.headers['x-backlens-token'])) {
+        handleCommand(req, res);
+        return true;
+      }
       if (event !== 'request' || !req || !res || req.headers['x-backlens'] === 'skip' || INTERNAL.test(req.url || '')) return emit.apply(this, arguments);
       const trace = {
         id: randomUUID(),
@@ -304,13 +308,25 @@ if (TARGET && !globalThis.__backlens) {
     return cols;
   }
 
-  function seqScans(node, out = []) {
+  /** 'reviews.updated_at DESC' -> { table: 'reviews', name: 'updated_at', desc: true } */
+  function sortKey(key) {
+    const m = String(key).match(/^(?:"?(\w+)"?\.)?"?([a-z_]\w*)"?(?:\s+(ASC|DESC))?(?:\s+NULLS\s+(?:FIRST|LAST))?$/i);
+    return m ? { table: m[1] || null, name: m[2], desc: /desc/i.test(m[3] || '') } : null;
+  }
+
+  // A sort above the scan (ORDER BY … LIMIT) is worth putting in the index after the filter
+  // columns: Postgres then reads rows already in order and stops at the limit.
+  function seqScans(node, out = [], sort = []) {
     if (!node) return out;
+    if (/Sort$/.test(node['Node Type']) && Array.isArray(node['Sort Key'])) sort = node['Sort Key'].map(sortKey);
     if (node['Node Type'] === 'Seq Scan' && node['Relation Name'] && node.Filter) {
       const columns = columnsCompared(node.Filter);
-      if (columns.length) out.push({ table: node['Relation Name'], schema: node.Schema || 'public', columns, filter: node.Filter });
+      const alias = node.Alias || node['Relation Name'];
+      const order = sort.every((k) => k && (!k.table || k.table === alias)) ? sort.filter((k) => !columns.includes(k.name)) : [];
+      if (columns.length) out.push({ table: node['Relation Name'], schema: node.Schema || 'public', columns, sort: order.map(({ name, desc }) => ({ name, desc })), filter: node.Filter });
     }
-    for (const child of node.Plans || []) seqScans(child, out);
+    const keep = /^(Sort|Incremental Sort|Limit|Gather|Gather Merge|Result)$/.test(node['Node Type']) ? sort : [];
+    for (const child of node.Plans || []) seqScans(child, out, keep);
     return out;
   }
 
@@ -336,10 +352,101 @@ if (TARGET && !globalThis.__backlens) {
       if (!rows[0]) continue;
       const leading = rows[0].leading || [];
       if (scan.columns.some((col) => leading.includes(col))) continue;
-      post('/advice', { sql: text, table: scan.table, schema: scan.schema, columns: scan.columns, rows: Math.max(0, Number(rows[0].rows)) });
+      post('/advice', { sql: text, table: scan.table, schema: scan.schema, columns: scan.columns, sort: scan.sort, rows: Math.max(0, Number(rows[0].rows)) });
     }
   }
 
+  // ---- creating the suggested index, when the user asks in the dashboard ----------------
+  // The dashboard sends one internal request to the app, with its private token. Only an index
+  // on named columns can be created or dropped, built here from checked names, never from SQL
+  // text; the plan check only re-explains a statement this process already explained.
+  const IDENT = /^[a-z_][a-z0-9_$]{0,62}$/i;
+  const q = (name) => `"${name}"`;
+
+  function tokenOk(value) {
+    if (!TOKEN || typeof value !== 'string' || value.length !== TOKEN.length) return false;
+    return require('node:crypto').timingSafeEqual(Buffer.from(value), Buffer.from(TOKEN));
+  }
+
+  async function indexCommand(body) {
+    if (!advisorPool) throw new Error('The app has not used Postgres yet. Use the page once, then try again.');
+    const pool = advisorPool;
+    if (body.action === 'info') {
+      const { rows } = await pool.query('select current_database() as database, inet_server_addr()::text as address, inet_server_port() as port');
+      const o = pool.options || {};
+      let host = o.host;
+      try {
+        if (!host && o.connectionString) host = new URL(o.connectionString).hostname;
+      } catch {}
+      return { database: rows[0].database, host: host || rows[0].address || 'local socket', port: rows[0].port };
+    }
+    const { schema, table, name } = body;
+    const columns = Array.isArray(body.columns) ? body.columns : [];
+    if (![schema, table, name].every((x) => typeof x === 'string' && IDENT.test(x)) || !columns.length || columns.length > 8 || !columns.every((c) => c && typeof c.name === 'string' && IDENT.test(c.name))) {
+      throw new Error('That is not an index backlens suggested.');
+    }
+    if (body.action === 'create') {
+      const cols = columns.map((c) => `${q(c.name)}${c.desc ? ' DESC' : ''}`).join(', ');
+      // CONCURRENTLY builds without blocking writes; it cannot run inside a transaction, so a
+      // plain pool query (its own connection, autocommit) is used.
+      await pool.query(`CREATE INDEX CONCURRENTLY IF NOT EXISTS ${q(name)} ON ${q(schema)}.${q(table)} (${cols})`);
+      const { rows } = await pool.query(
+        `select i.indisvalid as valid from pg_class c join pg_index i on i.indexrelid = c.oid join pg_namespace n on n.oid = c.relnamespace where c.relname = $1 and n.nspname = $2`,
+        [name, schema],
+      );
+      if (!rows[0] || !rows[0].valid) throw new Error('Postgres did not finish building the index. Drop it and try again.');
+      // Can Postgres use it for the query that showed the issue? On a small table it still
+      // prefers reading every row, so the check asks with sequential scans turned off.
+      let usable = null;
+      if (typeof body.sql === 'string' && explained.has(body.sql)) {
+        const client = await pool.connect();
+        try {
+          await client.query('BEGIN');
+          await client.query('SET LOCAL enable_seqscan = off');
+          const prefix = /\$\d/.test(body.sql) ? 'EXPLAIN (GENERIC_PLAN, FORMAT JSON) ' : 'EXPLAIN (FORMAT JSON) ';
+          const plan = JSON.stringify((await client.query(prefix + body.sql)).rows[0]['QUERY PLAN']);
+          usable = plan.includes(`"Index Name":"${name}"`);
+        } catch {
+          usable = null;
+        } finally {
+          await client.query('ROLLBACK').catch(() => {});
+          client.release();
+        }
+      }
+      return { created: true, usable };
+    }
+    if (body.action === 'drop') {
+      await pool.query(`DROP INDEX CONCURRENTLY IF EXISTS ${q(schema)}.${q(name)}`);
+      return { dropped: true };
+    }
+    throw new Error('Unknown action.');
+  }
+
+  function handleCommand(req, res) {
+    let raw = '';
+    req.on('data', (c) => {
+      raw += c;
+      if (raw.length > 64 * 1024) req.destroy();
+    });
+    req.on('end', () => {
+      let body = null;
+      try {
+        body = JSON.parse(raw);
+      } catch {}
+      const send = (status, payload) => {
+        res.writeHead(status, { 'content-type': 'application/json' });
+        res.end(JSON.stringify(payload));
+      };
+      if (!body) return send(400, { error: 'Bad request.' });
+      storage.exit(() =>
+        indexCommand(body).then(
+          (out) => send(200, out),
+          (err) => send(400, { error: String((err && err.message) || err) }),
+        ),
+      );
+    });
+  }
+
   function maybeAdvise(text) {
     if (!advisorPool || advisorOff || explained.has(text) || explained.size >= MAX_EXPLAINS) return;
     if (!/^\s*(select|with)\b/i.test(text) || text.includes(';') || /\bpg_(class|index|attribute|namespace)\b/.test(text)) return;

package/server.js

@@ -30,6 +30,35 @@ export function startServer({ port, root = process.cwd(), token, manualArgv = nu
   let config = manualArgv ? { app: null, test: null, autoRestart: false } : loadConfig(root);
 
   const traces = [];
+  // Issue key -> when its fix was kept (see summarize).
+  const fixedAt = new Map();
+  // Issue key -> the index created for it from the dashboard, so Undo still knows it.
+  const createdIndexes = new Map();
+
+  /** Sends one command to the recorder inside the app (see register.cjs). */
+  function appCommand(port, body) {
+    return new Promise((resolve, reject) => {
+      const payload = JSON.stringify(body);
+      const r = http.request(
+        { host: '127.0.0.1', port, method: 'POST', path: '/__backlens/index', headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload), 'x-backlens-token': token } },
+        (res) => {
+          let raw = '';
+          res.on('data', (c) => (raw += c));
+          res.on('end', () => {
+            let out = null;
+            try {
+              out = JSON.parse(raw);
+            } catch {}
+            if (res.statusCode === 200 && out) resolve(out);
+            else reject(new Error((out && out.error) || 'The app did not answer. Is it running with backlens?'));
+          });
+        },
+      );
+      r.setTimeout(10 * 60 * 1000, () => r.destroy(new Error('Creating the index took over 10 minutes.')));
+      r.on('error', (err) => reject(new Error(`Could not reach the app: ${err.message}`)));
+      r.end(payload);
+    });
+  }
   let received = 0;
   const known = new Map();
   const advice = new Map();
@@ -207,15 +236,15 @@ export function startServer({ port, root = process.cwd(), token, manualArgv = nu
 
     // From the dashboard.
     if (req.method === 'GET' && url.pathname === '/api/state') {
-      const { routes, issues } = summarize(traces, [...known.keys()], [...advice.values()]);
+      const { routes, issues } = summarize(traces, [...known.keys()], [...advice.values()], fixedAt);
       const recent = traces
         .slice(-300)
         .reverse()
-        .map((t) => ({ id: t.id, at: t.at, method: t.method, url: t.url, route: routeOf(t.method, t.url, t.template), status: t.status, duration: t.duration, spans: t.spans.length, aborted: Boolean(t.aborted) }));
+        .map((t) => ({ id: t.id, at: t.at, method: t.method, url: t.url, route: routeOf(t.method, t.url, t.template), status: t.status, duration: t.duration, spans: t.spans.length, aborted: Boolean(t.aborted), afterFix: Boolean(t.afterFix) }));
       return json(res, 200, { routes, issues, recent, total: traces.length, received });
     }
     if (req.method === 'GET' && url.pathname === '/api/map') {
-      const { issues } = summarize(traces, [...known.keys()], [...advice.values()]);
+      const { issues } = summarize(traces, [...known.keys()], [...advice.values()], fixedAt);
       return json(res, 200, { ...mapOf(traces, issues), advice: [...advice.values()].map((a) => ({ table: a.table, columns: a.columns })) });
     }
     if (req.method === 'GET' && url.pathname.startsWith('/api/trace/')) {
@@ -228,12 +257,13 @@ export function startServer({ port, root = process.cwd(), token, manualArgv = nu
       traces.length = 0;
       received = 0;
       advice.clear();
+      fixedAt.clear();
       return json(res, 200, { ok: true });
     }
     if (req.method === 'POST' && url.pathname === '/api/snapshot') {
       const name = (url.searchParams.get('name') || '').toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
       if (!name) return json(res, 400, { error: 'Give the snapshot a name.' });
-      const { routes, issues } = summarize(traces, [...known.keys()], [...advice.values()]);
+      const { routes, issues } = summarize(traces, [...known.keys()], [...advice.values()], fixedAt);
       mkdirSync(snapshotDir, { recursive: true });
       writeFileSync(join(snapshotDir, `${name}.json`), `${JSON.stringify({ name, at: Date.now(), requests: traces.length, routes: routes.filter((r) => r.calls), issues: issues.length }, null, 2)}\n`);
       return json(res, 200, { ok: true, name });
@@ -300,6 +330,34 @@ export function startServer({ port, root = process.cwd(), token, manualArgv = nu
       tests.start(scriptCommand(pm, config.test), root);
       return json(res, 200, { ok: true });
     }
+    // Creating a suggested index on the database the app is using, through the app itself.
+    if (req.method === 'POST' && url.pathname.startsWith('/api/index/')) {
+      const action = url.pathname.slice('/api/index/'.length);
+      if (!['info', 'create', 'drop'].includes(action)) return json(res, 404, { error: 'not found' });
+      if (!app || !app.port) return json(res, 409, { error: 'The app is not running. Start it first.' });
+      const body = (await readJson(req)) || {};
+      let index = null;
+      if (action !== 'info') {
+        const { issues } = summarize(traces, [...known.keys()], [...advice.values()]);
+        const issue = issues.find((i) => i.key === body.key);
+        index = issue && issue.index ? issue.index : createdIndexes.get(body.key);
+        if (!index) return json(res, 404, { error: 'That suggestion is gone. Refresh the list.' });
+      }
+      try {
+        const out = await appCommand(app.port, { action, ...(index || {}) });
+        if (action === 'create') {
+          createdIndexes.set(body.key, index);
+          fixedAt.set(body.key, Date.now());
+        }
+        if (action === 'drop') {
+          createdIndexes.delete(body.key);
+          fixedAt.delete(body.key);
+        }
+        return json(res, 200, { ...out, index });
+      } catch (err) {
+        return json(res, 400, { error: err.message });
+      }
+    }
     if (url.pathname.startsWith('/api/ai/')) {
       try {
         const body = req.method === 'POST' ? (await readJson(req)) || {} : {};
@@ -360,10 +418,19 @@ export function startServer({ port, root = process.cwd(), token, manualArgv = nu
         pauseWatch: (on) => (watchPaused = on),
         testsTail: () => tests.lines.slice(-14).map((l) => l.text).join('\n'),
         getIssue: (key) => {
-          const { issues } = summarize(traces, [...known.keys()], [...advice.values()]);
+          const { issues } = summarize(traces, [...known.keys()], [...advice.values()], fixedAt);
           return issues.find((i) => i.key === key) || (testRun.report ? testRun.report.issues.find((i) => i.key === key) : null);
         },
         getTrace: (id) => traces.find((t) => t.id === id) || testRun.traces.find((t) => t.id === id),
+        markFixed: (key, after) => {
+          fixedAt.set(key, Date.now());
+          if (after) {
+            const { replayOf, ...trace } = after;
+            traces.push({ ...trace, afterFix: true });
+            received++;
+            if (traces.length > KEEP) replays.delete(traces.shift().id);
+          }
+        },
         getReplay: (id) => replays.get(id),
         restartApp: async () => {
           app.port = null;

package/ui.html

@@ -154,7 +154,15 @@
   .opt-card:has(input:checked) { border-color: var(--accent); background: #ffffff05; }
   .opt-card { cursor: default; } .opt-card > label { cursor: pointer; }
   .opt-card a { color: var(--accent); }
-  .opt-card .btn { text-decoration: none; display: inline-block; }
+  a.btn { text-decoration: none; display: inline-block; }
+  .compare-card { border: 1px solid var(--line); border-radius: 8px; padding: 12px 14px; margin: 4px 0 14px; }
+  .compare-card h4 { margin: 0 0 8px; font-size: 13px; }
+  .compare-card table { width: auto; border-collapse: collapse; font: 13px var(--mono); }
+  .compare-card th { text-align: left; font-weight: 400; color: var(--sub); padding: 3px 18px 3px 0; }
+  .compare-card td { padding: 3px 10px 3px 0; }
+  .compare-card .arrow { color: var(--sub); }
+  .compare-card .better { color: #4ade80; } .compare-card .worse { color: #f87171; } .compare-card .same { color: var(--text); }
+  .compare-card .delta { font-size: 12px; }
   .field input[type=password] { flex: 1; font: 13px var(--mono); color: var(--text); background: var(--bg); border: 1px solid var(--line-2); border-radius: 6px; padding: 6px 8px; }
   .progress { height: 6px; border-radius: 3px; background: var(--raise); overflow: hidden; margin: 10px 0 0; }
   .progress > div { height: 100%; background: var(--accent); transition: width .4s; }
@@ -363,7 +371,7 @@ function renderRequests() {
   return `<h2>${routeFilter ? `<button class="ghost" type="button" id="unfilter">${esc(routeFilter)} ✕</button>` : `latest ${list.length} requests`}</h2><table>
     <thead><tr><th>when</th><th>request</th><th class="n">status</th><th class="n">time</th><th class="n hide-sm">calls</th></tr></thead>
     <tbody>${list.map((t) => `<tr data-trace="${esc(t.id)}" class="${openTrace && openTrace.trace.id === t.id ? 'sel' : ''}">
-      <td class="muted">${ago(t.at)}</td><td><span class="method">${esc(t.method)}</span><span class="route">${esc(t.url)}</span></td>
+      <td class="muted">${ago(t.at)}</td><td><span class="method">${esc(t.method)}</span><span class="route">${esc(t.url)}</span>${t.afterFix ? ' <span class="chip live">after fix</span>' : ''}</td>
       <td class="n ${statusClass(t.status)}">${t.aborted ? 'cancelled' : t.status}</td><td class="n">${ms(t.duration)}</td><td class="n hide-sm muted">${t.spans}</td></tr>`).join('')}</tbody></table>`;
 }
 
@@ -727,9 +735,10 @@ function renderFix() {
     <div class="kicker2">fix${j.attempt ? ', second attempt' : ''}</div><h2>${esc(j.issueTitle)}</h2><div class="meta">${esc(j.issueRoute || '')}</div>
     <div class="chips" style="margin-top:10px"><span class="chip">${esc(r.label)}</span><span class="chip">${r.kind === 'anthropic' ? (j.costUsd ? `spent ${usd(j.costUsd)}` : `about ${usd(r.estimateUsd)}`) : 'free'}</span>${busy ? '<span class="chip live"><span class="spin"></span> working</span>' : ''}</div></div>`;
   if (j.stage === 'template') {
-    html += `<ol class="feed"><li class="fi">${'<span class="dot ok">●</span>'}<div><div class="bubble">${esc(j.explanation)}</div></div></li></ol><div class="editor"><div class="editor-head"><span class="dots"><i></i><i></i><i></i></span>migration</div><div class="editor-body"><div class="cl add"><span class="ln">1</span><span class="mk">+</span><span class="cx">${hl(j.sql)}</span></div></div></div><p class="note">${esc(j.notes)}</p>
-      <div class="fix-actions"><button class="primary" type="button" data-copy="${esc(j.sql)}">Copy SQL</button></div>`;
-    el.innerHTML = html; return;
+    html += `<ol class="feed"><li class="fi">${'<span class="dot ok">●</span>'}<div><div class="bubble">${esc(j.explanation)}</div></div></li></ol><div class="editor"><div class="editor-head"><span class="dots"><i></i><i></i><i></i></span>migration</div><div class="editor-body"><div class="cl add"><span class="ln">1</span><span class="mk">+</span><span class="cx">${hl(j.sql)}</span></div></div></div><p class="note">${esc(j.notes)}</p>${indexPanel(j)}`;
+    el.innerHTML = html;
+    if (!idx.db && !idx.loading) loadIndexInfo();
+    return;
   }
   if (j.stage === 'preview') {
     html += `<section class="plan"><h4>Why this model</h4><ul class="reasons">${r.reasons.map((x) => `<li>${esc(x)}</li>`).join('')}</ul>
@@ -740,6 +749,7 @@ function renderFix() {
     el.innerHTML = html; return;
   }
   html += `<ol class="feed">${j.events.map(feedItem).join('')}${j.stage === 'error' ? `<li class="fi"><span class="dot bad">●</span><div class="verdict bad">${esc(j.error)}</div></li>` : ''}</ol>`;
+  html += compareCard(j);
   const act = [];
   if (j.stage === 'proposed') act.push('<button class="primary" type="button" id="fix-apply">Apply and check</button><button class="ghost" type="button" id="fix-close-2">Discard</button>');
   if (j.stage === 'no-edits') act.push(`<span class="note">No change was applied.</span>${escalateBtn(j)}`);
@@ -747,14 +757,76 @@ function renderFix() {
   if (j.stage === 'failed') act.push('<button class="primary" type="button" id="fix-revert">Revert</button><button class="ghost" type="button" id="fix-keep">Keep anyway</button>');
   if (j.stage === 'unverified') act.push('<button class="ghost" type="button" id="fix-keep">Keep</button><button class="ghost" type="button" id="fix-revert">Revert</button>');
   if (j.stage === 'reverted' || j.stage === 'error') act.push(escalateBtn(j));
-  if (j.stage === 'proposed') act.push('<span class="note">Only applies if these files have no uncommitted changes, with a backup.</span>');
+  if (j.stage === 'proposed') act.push('<span class="note">backlens keeps an exact copy of each file first, uncommitted changes included. Revert puts it back.</span>');
   if (act.length || fixError) html += `<div class="fix-actions">${act.join('')}<span class="error" role="alert">${esc(fixError)}</span></div>`;
   el.innerHTML = html;
   el.querySelectorAll('[data-autoscroll]').forEach((t) => (t.scrollTop = t.scrollHeight));
   el.scrollTop = atBottom || busy ? el.scrollHeight : keepScroll;
 }
 
+/** The same request before and after the change, side by side. */
+function compareCard(j) {
+  const c = j.compare;
+  if (!c || !c.before || !['verified', 'failed', 'unverified', 'kept', 'reverted'].includes(j.stage)) return '';
+  const pct = (a, b) => (a ? Math.round(((b - a) / a) * 100) : 0);
+  const row = (label, a, b, fmt = (x) => x, lowerIsBetter = true) => {
+    const d = pct(a, b);
+    const tone = a === b ? 'same' : (b < a) === lowerIsBetter ? 'better' : 'worse';
+    return `<tr><th>${label}</th><td>${fmt(a)}</td><td class="arrow">→</td><td class="${tone}">${fmt(b)}</td><td class="${tone} delta">${a === b ? '' : `${d > 0 ? '+' : ''}${d}%`}</td></tr>`;
+  };
+  const kind = esc((j.issueTitle || '').split(':')[0]);
+  return `<section class="compare-card"><h4>Same request, before and after the change</h4><table>
+    ${row('time', c.before.ms, c.after.ms, (x) => ms(x))}
+    ${row('database queries', c.before.queries, c.after.queries)}
+    ${c.before.redis || c.after.redis ? row('redis calls', c.before.redis, c.after.redis) : ''}
+    ${c.before.http || c.after.http ? row('outgoing http', c.before.http, c.after.http) : ''}
+    <tr><th>status</th><td>${c.before.status}</td><td class="arrow">→</td><td class="${c.before.status === c.after.status ? 'same' : 'worse'}">${c.after.status}</td><td></td></tr>
+    <tr><th>issue</th><td>${kind || 'found'}</td><td class="arrow">→</td><td class="${c.issueGone ? 'better' : 'worse'}">${c.issueGone ? 'gone' : 'still there'}</td><td></td></tr>
+  </table><p class="note">One request each${c.warmed ? ', the after one measured once the restarted app was warm' : ''}. Query counts are exact; times vary a few ms from run to run.</p></section>`;
+}
+
+// ---- creating a suggested index from the drawer ----------------------------------------
+let idx = {};
+async function loadIndexInfo() {
+  idx.loading = true;
+  try { idx.db = await aiPost('/api/index/info', {}); } catch (err) { idx.dbError = err.message; }
+  idx.loading = false;
+  renderFix();
+}
+
+function indexPanel(j) {
+  const where = idx.db ? `<b>${esc(idx.db.database)}</b> on ${esc(idx.db.host)}${idx.db.port ? `:${idx.db.port}` : ''}` : idx.dbError ? '' : 'checking…';
+  const steps = [];
+  if (idx.result && idx.result.created) {
+    steps.push(`<li class="fi"><span class="dot ok">●</span><div><div class="fh"><b>Created</b> ${esc(idx.result.index.name)}</div><div class="sub2">on ${where}, built without blocking writes</div></div></li>`);
+    const u = idx.result.usable;
+    steps.push(`<li class="fi"><span class="dot ${u ? 'ok' : u === false ? 'bad' : 'skip'}">●</span><div><div class="fh"><b>Plan check</b></div><div class="sub2">${u ? 'Postgres can answer this query from the new index.' : u === false ? 'Postgres would still not use it for this query.' : 'Could not check the plan for this query.'}</div></div></li>`);
+  }
+  if (idx.dropped) steps.push(`<li class="fi"><span class="dot skip">●</span><div><div class="fh"><b>Dropped</b> the index again</div></div></li>`);
+  const actions = idx.result && idx.result.created
+    ? `<button class="ghost" type="button" id="idx-drop" ${idx.busy ? 'disabled' : ''}>Undo (drop it)</button><button class="ghost" type="button" data-copy="${esc(j.sql)}">Copy SQL for a migration</button>`
+    : `<button class="primary" type="button" id="idx-create" ${idx.busy || !idx.db ? 'disabled' : ''}>${idx.busy ? 'Creating…' : 'Create on this database'}</button><button class="ghost" type="button" data-copy="${esc(j.sql)}">Copy SQL</button>`;
+  return `${steps.length ? `<ol class="feed">${steps.join('')}</ol>` : ''}
+    <p class="note">${idx.dbError ? esc(idx.dbError) : `Runs on the database your app is connected to right now: ${where}. Only use it on a development database.`}${idx.result && idx.result.created ? ' This changed only this database: add the SQL to a migration so other environments get it too.' : ''}</p>
+    <div class="fix-actions">${actions}<span class="error" role="alert">${esc(idx.error || '')}</span></div>`;
+}
+
+document.addEventListener('click', async (e) => {
+  const create = e.target.closest('#idx-create');
+  const drop = e.target.closest('#idx-drop');
+  if (!create && !drop) return;
+  idx.busy = true; idx.error = ''; renderFix();
+  try {
+    if (create) { idx.result = await aiPost('/api/index/create', { key: fixJob.issueKey }); idx.dropped = false; }
+    else { await aiPost('/api/index/drop', { key: fixJob.issueKey }); idx.result = null; idx.dropped = true; }
+    lastTotal = -1; poll();
+  } catch (err) { idx.error = err.message; }
+  idx.busy = false;
+  renderFix();
+});
+
 function escalateBtn(j) {
+  if (j.errorCode === 'billing') return `<a class="btn primary" href="https://console.anthropic.com/settings/billing" target="_blank" rel="noopener">Add credits</a>`;
   return j.attempt === 0 && j.route.kind === 'anthropic' ? `<button class="ghost" type="button" id="fix-escalate">Try a stronger model</button>` : '';
 }
 
@@ -884,6 +956,7 @@ document.addEventListener('click', async (e) => {
     const issue = issueFrom(fx.dataset.aiFix);
     if (!issue) return;
     fixError = '';
+    idx = {};
     try { fixJob = await aiPost('/api/ai/fix', { key: issue.key }); }
     catch (err) { fixJob = null; fixError = err.message; }
     renderFix();