evrex-mcp 0.7.0 → 0.8.1

package/dist/index.js

@@ -63,7 +63,14 @@ var init_client = __esm({
       // Evidence-only retrieval (BM25 + embedding), no LLM synthesis call — see
       // apps/backend/src/query/query.service.ts#search. Used by evrex_search,
       // which wants ranked hits fast, not a synthesized paragraph.
-      search: (repoPath, text, filePaths) => post("/search", { repoPath, text, filePaths })
+      search: (repoPath, text, filePaths) => post("/search", { repoPath, text, filePaths }),
+      // Everything that happened in a repo, newest first, bounded by days — the
+      // same query the desktop Timeline screen makes. Sessions and commits
+      // interleaved, each with the handle evrex_expand takes.
+      feedback: (body) => post("/feedback", body),
+      timeline: (repoPath, days) => get(
+        `/timeline?repoPath=${encodeURIComponent(repoPath)}&days=${encodeURIComponent(String(days))}`
+      )
     };
   }
 });
@@ -434,11 +441,13 @@ var MAX_ITEMS_PER_CATEGORY = 6;
 var EXTRACTION_SYSTEM_PROMPT = [
   "You extract structured reasoning from a real coding-agent session transcript for Evrex, a tool that recovers WHY code changed, not just what changed.",
   `Each line is labeled "user" (the human engineer actually typed this), "assistant" (the agent), or "tool_result" (raw output from a tool call, e.g. command stdout \u2014 NOT something either party said; never attribute a "tool_result" line's content to "engineer" as raisedBy/source).`,
+  'Only tool calls that FAILED are included, truncated. A "tool_result" line is evidence that the approach the assistant was taking at that point was tried and did not work: read it together with the assistant lines around it, and where the failure led to a change of approach, record the abandoned one as a rejected approach with the failure as its reason. A trivial failure \u2014 a typo in a path, a command re-run successfully a line later \u2014 is not a rejected approach.',
   "Only extract items explicitly present in the transcript below. Never invent, infer beyond the text, or pad categories with generic filler.",
   "If a category has nothing genuinely present, return an empty array for it \u2014 an empty result is correct and expected, not a failure.",
   `Cap each array at ${MAX_ITEMS_PER_CATEGORY} items \u2014 pick the most consequential ones.`,
   '"atMessage" is the [N] index of the transcript line the item came from.',
-  'For a rejected approach, "reason" is why it was turned down and "tradeoff" is what was given up by not taking it. Fill "tradeoff" from the transcript whenever the cost is stated or clearly implied; leave it empty only when the transcript genuinely says nothing about it.'
+  'For a rejected approach, "reason" is why it was turned down and "tradeoff" is what was given up by not taking it. Fill "tradeoff" from the transcript whenever the cost is stated or clearly implied; leave it empty only when the transcript genuinely says nothing about it.',
+  'A "procedure" is a reusable, multi-step way of doing something in this repository that the transcript shows actually working \u2014 adding and registering a migration, cutting a release, installing a hook, running a particular check \u2014 written as the concrete steps somebody would follow next time, each step one line with the real command or file where the transcript has it. Only when the steps are visible in the transcript and were carried out, never a plan that was proposed and not done; a one-off fix is not a procedure.'
 ].join(" ");
 
 // ../../packages/llm-core/src/synthesis.ts
@@ -637,6 +646,29 @@ ${request2.user}`;
 // ../../packages/llm-core/src/provider-clients.ts
 import Anthropic3 from "@anthropic-ai/sdk";
 var NOOP = { warn: () => void 0, error: () => void 0 };
+var BATCH_POLL_MS = 5e3;
+var BATCH_TIMEOUT_MS = 6 * 60 * 60 * 1e3;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function totalize(items, results) {
+  for (const item of items) if (!results.has(item.id)) results.set(item.id, null);
+  return results;
+}
+function totalizeIds(ids, results) {
+  for (const id of ids) if (!results.has(id)) results.set(id, null);
+  return results;
+}
+async function pollToCompletion(handle, resolve, sleepFn, onTimeout) {
+  const startedAt = Date.now();
+  for (; ; ) {
+    const resolved = await resolve(handle);
+    if (resolved) return resolved;
+    if (Date.now() - startedAt > BATCH_TIMEOUT_MS) {
+      onTimeout(handle.id);
+      return null;
+    }
+    await sleepFn(BATCH_POLL_MS);
+  }
+}
 var realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var MAX_RETRIES = 4;
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
@@ -644,12 +676,12 @@ function isExhaustedStatus(status, retriesSpent) {
   if (status === 401 || status === 403) return true;
   return status === 429 && retriesSpent;
 }
-async function waitBeforeRetry(response, attempt, sleep) {
+async function waitBeforeRetry(response, attempt, sleep2) {
   const header = response.headers.get("retry-after") ?? response.headers.get("x-ratelimit-reset-tokens");
   const seconds = header ? parseDuration(header) : null;
   const backoff = Math.min(8 * 2 ** attempt, 60);
   const wait = Math.min(seconds ?? backoff, MAX_RETRY_WAIT_SECONDS);
-  await sleep(wait * 1e3);
+  await sleep2(wait * 1e3);
 }
 var MAX_RETRY_WAIT_SECONDS = 90;
 function parseDuration(value) {
@@ -669,7 +701,7 @@ function parseJsonBody(text) {
     return null;
   }
 }
-var AnthropicClient = class {
+var AnthropicClient = class _AnthropicClient {
   constructor(key, model, logger) {
     this.model = model;
     this.logger = logger;
@@ -678,37 +710,47 @@ var AnthropicClient = class {
   provider = "anthropic";
   exhausted = false;
   sdk;
+  // The one place a ModelRequest becomes Anthropic's message params, so the
+  // single and batch paths cannot drift on the cache breakpoint or the
+  // json_schema wiring.
+  messageParams(request2) {
+    return {
+      model: request2.model ?? this.model,
+      max_tokens: request2.maxTokens ?? DEFAULT_MAX_TOKENS,
+      // The breakpoint sits at the end of the system prompt, which is the
+      // only part of these requests that repeats. Rendering order is
+      // tools -> system -> messages, so a marker here caches everything
+      // ahead of the transcript.
+      //
+      // Deliberately NOT on the user block. That block is a different
+      // transcript chunk on every call, so a breakpoint there would write a
+      // fresh cache entry per request and read none of them back — paying
+      // the write premium for nothing, which is worse than not caching.
+      system: [
+        {
+          type: "text",
+          text: request2.system,
+          cache_control: { type: "ephemeral" }
+        }
+      ],
+      messages: [{ role: "user", content: request2.user }],
+      ...request2.schema ? {
+        output_config: {
+          format: { type: "json_schema", schema: request2.schema }
+        }
+      } : {}
+    };
+  }
+  static messageText(message) {
+    return message.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+  }
   async completeJson(request2) {
     try {
-      const message = await this.sdk.messages.create({
-        model: request2.model ?? this.model,
-        max_tokens: request2.maxTokens ?? DEFAULT_MAX_TOKENS,
-        // The breakpoint sits at the end of the system prompt, which is the
-        // only part of these requests that repeats. Rendering order is
-        // tools -> system -> messages, so a marker here caches everything
-        // ahead of the transcript.
-        //
-        // Deliberately NOT on the user block. That block is a different
-        // transcript chunk on every call, so a breakpoint there would write a
-        // fresh cache entry per request and read none of them back — paying
-        // the write premium for nothing, which is worse than not caching.
-        system: [
-          {
-            type: "text",
-            text: request2.system,
-            cache_control: { type: "ephemeral" }
-          }
-        ],
-        messages: [{ role: "user", content: request2.user }],
-        ...request2.schema ? {
-          output_config: {
-            format: { type: "json_schema", schema: request2.schema }
-          }
-        } : {}
-      });
+      const message = await this.sdk.messages.create(
+        this.messageParams(request2)
+      );
       this.reportCacheUsage(message.usage);
-      const text = message.content.filter((b) => b.type === "text").map((b) => b.text).join("");
-      return parseJsonBody(text);
+      return parseJsonBody(_AnthropicClient.messageText(message));
     } catch (err) {
       const status = err?.status;
       if (typeof status === "number" && isExhaustedStatus(status, true)) {
@@ -718,6 +760,58 @@ var AnthropicClient = class {
       return null;
     }
   }
+  async submitBatch(items) {
+    if (items.length === 0) return null;
+    try {
+      const created = await this.sdk.messages.batches.create({
+        requests: items.map((item) => ({
+          custom_id: item.id,
+          params: this.messageParams(item.request)
+        }))
+      });
+      return { provider: "anthropic", id: created.id, itemIds: items.map((i) => i.id) };
+    } catch (err) {
+      const status = err?.status;
+      if (typeof status === "number" && isExhaustedStatus(status, true)) {
+        this.exhausted = true;
+      }
+      this.logger.warn(`anthropic batch submit failed: ${describeError(err)}`);
+      return null;
+    }
+  }
+  async resolveBatch(handle) {
+    try {
+      const batch = await this.sdk.messages.batches.retrieve(handle.id);
+      if (batch.processing_status !== "ended") return null;
+      const results = /* @__PURE__ */ new Map();
+      for await (const entry of await this.sdk.messages.batches.results(
+        handle.id
+      )) {
+        results.set(
+          entry.custom_id,
+          entry.result.type === "succeeded" ? parseJsonBody(_AnthropicClient.messageText(entry.result.message)) : null
+        );
+      }
+      return totalizeIds(handle.itemIds, results);
+    } catch (err) {
+      this.logger.warn(`anthropic batch resolve failed: ${describeError(err)}`);
+      return totalizeIds(handle.itemIds, /* @__PURE__ */ new Map());
+    }
+  }
+  async completeJsonBatch(items) {
+    if (items.length === 0) return /* @__PURE__ */ new Map();
+    const handle = await this.submitBatch(items);
+    if (!handle) return totalize(items, /* @__PURE__ */ new Map());
+    const resolved = await pollToCompletion(
+      handle,
+      (h) => this.resolveBatch(h),
+      sleep,
+      (id) => this.logger.warn(
+        `anthropic batch ${id} did not finish within the cap; the sessions it covers stay unextracted until the next pass`
+      )
+    );
+    return resolved ?? totalize(items, /* @__PURE__ */ new Map());
+  }
   /**
    * Says out loud whether the cache was actually used.
    *
@@ -744,12 +838,12 @@ var AnthropicClient = class {
     );
   }
 };
-var GoogleClient = class {
-  constructor(key, model, logger, sleep = realSleep) {
+var GoogleClient = class _GoogleClient {
+  constructor(key, model, logger, sleep2 = realSleep) {
     this.key = key;
     this.model = model;
     this.logger = logger;
-    this.sleep = sleep;
+    this.sleep = sleep2;
   }
   provider = "google";
   exhausted = false;
@@ -792,56 +886,129 @@ ${JSON.stringify(request2.schema)}` : "";
       return null;
     }
   }
+  static GEMINI_BASE = "https://generativelanguage.googleapis.com/v1beta";
+  async submitBatch(items) {
+    if (items.length === 0) return null;
+    const model = items[0].request.model ?? this.model;
+    try {
+      const create = await fetch(
+        `${_GoogleClient.GEMINI_BASE}/models/${encodeURIComponent(model)}:batchGenerateContent`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-goog-api-key": this.key
+          },
+          body: JSON.stringify({
+            batch: {
+              display_name: "evrex-extraction",
+              input_config: {
+                requests: {
+                  requests: items.map((item) => {
+                    const shape = item.request.schema ? `
+
+Respond with JSON matching exactly this schema:
+${JSON.stringify(item.request.schema)}` : "";
+                    return {
+                      request: {
+                        systemInstruction: {
+                          parts: [{ text: item.request.system + shape }]
+                        },
+                        contents: [
+                          { role: "user", parts: [{ text: item.request.user }] }
+                        ],
+                        generationConfig: { responseMimeType: "application/json" }
+                      },
+                      metadata: { key: item.id }
+                    };
+                  })
+                }
+              }
+            }
+          })
+        }
+      );
+      if (!create.ok) {
+        if (isExhaustedStatus(create.status, true)) this.exhausted = true;
+        this.logger.warn(
+          `google batch submit failed: ${create.status} ${(await create.text()).slice(0, 200)}`
+        );
+        return null;
+      }
+      const name = (await create.json()).name;
+      if (!name) {
+        this.logger.warn("google batch: no job name returned");
+        return null;
+      }
+      return { provider: "google", id: name, itemIds: items.map((i) => i.id) };
+    } catch (err) {
+      this.logger.warn(`google batch submit failed: ${describeError(err)}`);
+      return null;
+    }
+  }
+  async resolveBatch(handle) {
+    try {
+      const poll = await fetch(`${_GoogleClient.GEMINI_BASE}/${handle.id}`, {
+        headers: { "x-goog-api-key": this.key }
+      });
+      if (!poll.ok) {
+        this.logger.warn(`google batch poll failed: ${poll.status}`);
+        return totalizeIds(handle.itemIds, /* @__PURE__ */ new Map());
+      }
+      const job = await poll.json();
+      const state = job.state ?? "";
+      if (state === "JOB_STATE_FAILED" || state === "JOB_STATE_CANCELLED" || state === "JOB_STATE_EXPIRED") {
+        this.logger.warn(`google batch ${handle.id} ended ${state}`);
+        return totalizeIds(handle.itemIds, /* @__PURE__ */ new Map());
+      }
+      if (state !== "JOB_STATE_SUCCEEDED") return null;
+      const inlined = job.response?.inlinedResponses ?? [];
+      const results = /* @__PURE__ */ new Map();
+      handle.itemIds.forEach((id, i) => {
+        const text = inlined[i]?.response?.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("");
+        results.set(id, text ? parseJsonBody(text) : null);
+      });
+      return totalizeIds(handle.itemIds, results);
+    } catch (err) {
+      this.logger.warn(`google batch resolve failed: ${describeError(err)}`);
+      return totalizeIds(handle.itemIds, /* @__PURE__ */ new Map());
+    }
+  }
+  async completeJsonBatch(items) {
+    if (items.length === 0) return /* @__PURE__ */ new Map();
+    const handle = await this.submitBatch(items);
+    if (!handle) return totalize(items, /* @__PURE__ */ new Map());
+    const resolved = await pollToCompletion(
+      handle,
+      (h) => this.resolveBatch(h),
+      this.sleep,
+      (id) => this.logger.warn(
+        `google batch ${id} did not finish within the cap; leaving its sessions for a later pass`
+      )
+    );
+    return resolved ?? totalize(items, /* @__PURE__ */ new Map());
+  }
 };
 var OpenAiCompatibleClient = class {
-  constructor(provider, baseUrl, key, model, logger, sleep = realSleep) {
+  constructor(provider, baseUrl, key, model, logger, sleep2 = realSleep) {
     this.provider = provider;
     this.baseUrl = baseUrl;
     this.key = key;
     this.model = model;
     this.logger = logger;
-    this.sleep = sleep;
+    this.sleep = sleep2;
+    if (this.provider === "openai") {
+      this.completeJsonBatch = (items) => this.runBatch(items);
+    }
   }
   exhausted = false;
+  completeJsonBatch;
   async completeJson(request2, attempt = 0) {
-    const strict = this.provider === "openai";
-    const shape = request2.schema && !strict ? `
-
-Respond with JSON matching exactly this schema:
-${JSON.stringify(request2.schema)}` : "";
     try {
       const res = await fetch(`${this.baseUrl}/chat/completions`, {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          // A local server does not want one, and some reject an empty bearer
-          // token outright.
-          ...this.key ? { Authorization: `Bearer ${this.key}` } : {}
-        },
-        body: JSON.stringify({
-          model: request2.model ?? this.model,
-          messages: [
-            { role: "system", content: request2.system + shape },
-            { role: "user", content: request2.user }
-          ],
-          ...request2.schema && strict ? {
-            response_format: {
-              type: "json_schema",
-              json_schema: {
-                name: "evrex_result",
-                strict: true,
-                schema: request2.schema
-              }
-            }
-          } : { response_format: { type: "json_object" } },
-          // Extraction is a reading task with a right answer, not a writing
-          // task, and a default sampling temperature makes it a different
-          // answer each run: one model scored 53% and then 20% on the same ten
-          // sessions before this was pinned. Indexing twice must not produce
-          // two different histories.
-          temperature: 0,
-          stream: false
-        })
+        headers: this.authHeaders(),
+        body: JSON.stringify(this.chatBody(request2))
       });
       if (RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES) {
         await waitBeforeRetry(res, attempt, this.sleep);
@@ -862,6 +1029,147 @@ ${JSON.stringify(request2.schema)}` : "";
       return null;
     }
   }
+  authHeaders() {
+    return {
+      "Content-Type": "application/json",
+      // A local server does not want one, and some reject an empty bearer token.
+      ...this.key ? { Authorization: `Bearer ${this.key}` } : {}
+    };
+  }
+  // One place a ModelRequest becomes the chat body, so completeJson and the
+  // batch path cannot drift on response_format or the pinned temperature.
+  chatBody(request2) {
+    const strict = this.provider === "openai";
+    const shape = request2.schema && !strict ? `
+
+Respond with JSON matching exactly this schema:
+${JSON.stringify(request2.schema)}` : "";
+    return {
+      model: request2.model ?? this.model,
+      messages: [
+        { role: "system", content: request2.system + shape },
+        { role: "user", content: request2.user }
+      ],
+      ...request2.schema && strict ? {
+        response_format: {
+          type: "json_schema",
+          json_schema: {
+            name: "evrex_result",
+            strict: true,
+            schema: request2.schema
+          }
+        }
+      } : { response_format: { type: "json_object" } },
+      // A reading task with a right answer: temperature pinned so indexing
+      // twice is the same history.
+      temperature: 0,
+      stream: false
+    };
+  }
+  async runBatch(items) {
+    const results = /* @__PURE__ */ new Map();
+    if (items.length === 0) return results;
+    const auth = this.key ? { Authorization: `Bearer ${this.key}` } : {};
+    try {
+      const jsonl = items.map(
+        (item) => JSON.stringify({
+          custom_id: item.id,
+          method: "POST",
+          url: "/v1/chat/completions",
+          body: this.chatBody(item.request)
+        })
+      ).join("\n");
+      const form = new FormData();
+      form.append("purpose", "batch");
+      form.append(
+        "file",
+        new Blob([jsonl], { type: "application/jsonl" }),
+        "evrex-batch.jsonl"
+      );
+      const upload = await fetch(`${this.baseUrl}/files`, {
+        method: "POST",
+        headers: auth,
+        body: form
+      });
+      if (!upload.ok) {
+        if (isExhaustedStatus(upload.status, true)) this.exhausted = true;
+        this.logger.warn(
+          `openai batch upload failed: ${upload.status} ${(await upload.text()).slice(0, 200)}`
+        );
+        return totalize(items, results);
+      }
+      const fileId = (await upload.json()).id;
+      if (!fileId) return totalize(items, results);
+      const created = await fetch(`${this.baseUrl}/batches`, {
+        method: "POST",
+        headers: this.authHeaders(),
+        body: JSON.stringify({
+          input_file_id: fileId,
+          endpoint: "/v1/chat/completions",
+          completion_window: "24h"
+        })
+      });
+      if (!created.ok) {
+        this.logger.warn(
+          `openai batch create failed: ${created.status} ${(await created.text()).slice(0, 200)}`
+        );
+        return totalize(items, results);
+      }
+      const batchId = (await created.json()).id;
+      if (!batchId) return totalize(items, results);
+      let status = "";
+      let outputFileId;
+      const startedAt = Date.now();
+      while (status !== "completed") {
+        if (Date.now() - startedAt > BATCH_TIMEOUT_MS) {
+          this.logger.warn(
+            `openai batch ${batchId} did not finish within the cap; leaving its sessions for a later pass`
+          );
+          return totalize(items, results);
+        }
+        await this.sleep(BATCH_POLL_MS);
+        const poll = await fetch(`${this.baseUrl}/batches/${batchId}`, {
+          headers: auth
+        });
+        if (!poll.ok) {
+          this.logger.warn(`openai batch poll failed: ${poll.status}`);
+          return totalize(items, results);
+        }
+        const job = await poll.json();
+        status = job.status ?? "";
+        outputFileId = job.output_file_id;
+        if (status === "failed" || status === "expired" || status === "cancelled") {
+          this.logger.warn(`openai batch ${batchId} ended ${status}`);
+          return totalize(items, results);
+        }
+      }
+      if (!outputFileId) return totalize(items, results);
+      const out = await fetch(`${this.baseUrl}/files/${outputFileId}/content`, {
+        headers: auth
+      });
+      if (!out.ok) {
+        this.logger.warn(`openai batch results fetch failed: ${out.status}`);
+        return totalize(items, results);
+      }
+      for (const line of (await out.text()).split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          const row = JSON.parse(line);
+          const content = row.response?.body?.choices?.[0]?.message?.content;
+          if (row.custom_id) {
+            results.set(
+              row.custom_id,
+              typeof content === "string" ? parseJsonBody(content) : null
+            );
+          }
+        } catch {
+        }
+      }
+    } catch (err) {
+      this.logger.warn(`openai batch failed: ${describeError(err)}`);
+    }
+    return totalize(items, results);
+  }
 };
 function describeError(err) {
   return err instanceof Error ? err.message : String(err);
@@ -873,9 +1181,9 @@ function createModelClient(key, options = {}) {
   const model = options.model ?? DEFAULT_MODELS[provider];
   const trimmed = key.trim();
   if (provider === "anthropic") return new AnthropicClient(trimmed, model, logger);
-  const sleep = options.sleep ?? realSleep;
+  const sleep2 = options.sleep ?? realSleep;
   if (provider === "google")
-    return new GoogleClient(trimmed, model, logger, sleep);
+    return new GoogleClient(trimmed, model, logger, sleep2);
   const cli = CLI_SPECS[provider];
   if (cli) return new CliClient(cli, model, logger);
   if (provider === "local") {
@@ -885,7 +1193,7 @@ function createModelClient(key, options = {}) {
       null,
       model,
       logger,
-      sleep
+      sleep2
     );
   }
   const baseUrl = options.baseUrl ?? OPENAI_COMPATIBLE_BASE_URLS[provider];
@@ -896,7 +1204,7 @@ function createModelClient(key, options = {}) {
     trimmed,
     model,
     logger,
-    sleep
+    sleep2
   );
 }
 
@@ -1166,28 +1474,60 @@ async function evrexWhy(filePath, question) {
   const byRelevance = (items) => [...items].sort(
     (a, b) => Number(aboutTarget(b)) - Number(aboutTarget(a))
   );
+  const commitShas = [...new Set(evidence.filter((e) => e.kind === "commit").map((e) => e.refId))].slice(0, MAX_ITEMS);
+  const commits = (await Promise.all(commitShas.map((sha) => evrexApi.commit(sha).catch(() => null)))).filter(
+    (c) => c !== null && (c.statedInsights?.length ?? 0) > 0
+  );
+  const statedOf = (kind) => commits.flatMap(
+    (c) => (c.statedInsights ?? []).filter((i) => i.kind === kind).map((i) => ({ text: i.text, stated: `commit:${c.sha.slice(0, 12)}` }))
+  );
   const rejected = byRelevance(sessions.flatMap((s) => s.rejected)).slice(0, MAX_ITEMS);
   const constraints = byRelevance(sessions.flatMap((s) => s.constraints)).slice(0, MAX_ITEMS);
   const decisions = byRelevance(sessions.flatMap((s) => s.decisions)).slice(0, MAX_ITEMS);
+  const procedures = byRelevance(sessions.flatMap((s) => s.procedures ?? [])).slice(0, MAX_ITEMS);
+  const statedRejected = statedOf("rejected").slice(0, MAX_ITEMS);
+  const statedConstraints = statedOf("constraint").slice(0, MAX_ITEMS);
+  const statedDecisions = statedOf("decision").slice(0, MAX_ITEMS);
+  const statedLine = (i) => `- ${i.text} (stated in ${i.stated})`;
   const parts = [];
+  const marked = sessions.filter((s) => (s.feedback ?? []).some((f) => f.itemId === null && f.signal !== "helpful"));
+  if (marked.length > 0) {
+    parts.push(
+      marked.map((s) => `session:${s.id} \u2014 ${feedbackLines((s.feedback ?? []).filter((f) => f.itemId === null))}`).join("\n")
+    );
+  }
   const heuristic = sessions.some((s) => s.insightsSource === "heuristic");
-  if (rejected.length > 0) {
+  if (rejected.length + statedRejected.length > 0) {
+    parts.push(
+      "REJECTED APPROACHES (do not re-propose these without new information):\n" + [
+        ...rejected.map((r) => `- ${r.title} \u2014 ${r.reason}${r.tradeoff ? ` (tradeoff: ${r.tradeoff})` : ""}${itemMark(sessions.flatMap((s) => s.feedback ?? []), r.id)}`),
+        ...statedRejected.map(statedLine)
+      ].join("\n")
+    );
+  }
+  if (constraints.length + statedConstraints.length > 0) {
     parts.push(
-      "REJECTED APPROACHES (do not re-propose these without new information):\n" + rejected.map((r) => `- ${r.title} \u2014 ${r.reason}${r.tradeoff ? ` (tradeoff: ${r.tradeoff})` : ""}`).join("\n")
+      "CONSTRAINTS:\n" + [...constraints.map((c) => `- [${c.source}] ${c.text}`), ...statedConstraints.map(statedLine)].join("\n")
     );
   }
-  if (constraints.length > 0) {
-    parts.push("CONSTRAINTS:\n" + constraints.map((c) => `- [${c.source}] ${c.text}`).join("\n"));
+  if (decisions.length + statedDecisions.length > 0) {
+    parts.push(
+      "PRIOR DECISIONS:\n" + [...decisions.map((d) => `- ${d.title}: ${d.detail}`), ...statedDecisions.map(statedLine)].join("\n")
+    );
   }
-  if (decisions.length > 0) {
-    parts.push("PRIOR DECISIONS:\n" + decisions.map((d) => `- ${d.title}: ${d.detail}`).join("\n"));
+  const proceduresText = proceduresBlock(procedures);
+  if (proceduresText) parts.push(proceduresText);
+  if (commits.length > 0) {
+    parts.push(
+      `Items marked "stated in commit:\u2026" were written as Evrex-Rejected / Evrex-Constraint / Evrex-Decision trailers by whoever committed \u2014 the committer's own account at the moment, not extracted by a model.`
+    );
   }
   if (heuristic && (rejected.length > 0 || constraints.length > 0 || decisions.length > 0)) {
     parts.push(
       "NOTE: the blocks above were extracted by cue-phrase matching, not by a model reading the conversation \u2014 they may be incomplete or miss context."
     );
   }
-  const hasBlocks = rejected.length > 0 || constraints.length > 0 || decisions.length > 0;
+  const hasBlocks = rejected.length + statedRejected.length > 0 || constraints.length + statedConstraints.length > 0 || decisions.length + statedDecisions.length > 0;
   if (synthesisEnabled()) {
     const answer = await synthesize(text, evidence);
     parts.push(
@@ -1229,7 +1569,7 @@ async function evrexSearch(query) {
   const lines = results.slice(0, MAX_ITEMS * 2).map(({ repo, e }) => {
     const conf = confidenceLabel(e.provenance);
     const repoTag = multiRepo ? ` \xB7 ${repo.name}` : "";
-    const handle = `${e.kind}:${e.refId.slice(0, 12)}`;
+    const handle = e.kind === "commit" ? `commit:${e.refId.slice(0, 12)}` : `${e.kind}:${e.refId}`;
     return `- ${handle} [${evidenceLabel(e)} ${conf.trim()}${dateLabel(e.at)}${spentLabel(e.spentTokens)}${repoTag}] ${truncate(e.excerpt.replace(/\s+/g, " ").trim(), INDEX_EXCERPT)}`;
   });
   return [
@@ -1238,6 +1578,63 @@ async function evrexSearch(query) {
     "Where a line says `N spent`, that is what the conversation behind it cost in tokens \u2014 the records most expensive to rediscover are usually the ones worth expanding first. This is the index, not the record \u2014 each line is a gist, roughly a quarter of what the underlying item says. If one of them looks like the answer, call evrex_expand with its handle (several at once) to read it in full along with any decisions, constraints and rejected approaches attached to it. Expanding everything costs more than the old single-shot search did; expanding the two that matter costs much less. If none of them look relevant, say the record does not cover it rather than expanding on spec."
   ].join("\n");
 }
+var TIMELINE_DEFAULT_DAYS = 7;
+var TIMELINE_MAX_DAYS = 90;
+var TIMELINE_DEFAULT_LIMIT = 30;
+var TIMELINE_MAX_LIMIT = 200;
+async function evrexTimeline(days = TIMELINE_DEFAULT_DAYS, limit = TIMELINE_DEFAULT_LIMIT) {
+  const window = Math.min(TIMELINE_MAX_DAYS, Math.max(1, Math.floor(days) || TIMELINE_DEFAULT_DAYS));
+  const cap2 = Math.min(TIMELINE_MAX_LIMIT, Math.max(1, Math.floor(limit) || TIMELINE_DEFAULT_LIMIT));
+  const repos = await resolveRepos();
+  if (repos.length === 0) return "No indexed repos found (GET /repos returned none).";
+  const multiRepo = repos.length > 1;
+  const perRepo = await Promise.all(
+    repos.map(async (repo) => {
+      try {
+        const entries = await evrexApi.timeline(repo.id, window);
+        return entries.map((entry) => ({ repo, entry }));
+      } catch {
+        return [];
+      }
+    })
+  );
+  const all = perRepo.flat().sort((a, b) => Date.parse(b.entry.at) - Date.parse(a.entry.at));
+  const where = multiRepo ? "the indexed repos" : repos[0].name;
+  if (all.length === 0) {
+    return `Nothing recorded in ${where} in the last ${window} day${window === 1 ? "" : "s"}. No captured session and no ingested commit fall in that window; work done without capture would not appear here. Widen the window with a larger \`days\`.`;
+  }
+  const shown = all.slice(0, cap2);
+  const lines = shown.map(({ repo, entry }) => formatTimelineLine(entry, multiRepo ? repo.name : null));
+  const omitted = all.length - shown.length;
+  return [
+    `Last ${window} day${window === 1 ? "" : "s"} in ${where}, newest first \u2014 ${all.length} record${all.length === 1 ? "" : "s"}${omitted > 0 ? `, ${shown.length} shown` : ""}:`,
+    ...lines,
+    "",
+    (omitted > 0 ? `${omitted} older record${omitted === 1 ? "" : "s"} in the window not shown; raise \`limit\` to see them. ` : "") + "This is the index, not the record. A commit line nests under its session (`\u21B3 session:\u2026`) when the link is verified or matched. For what a session decided, call evrex_expand with its handle; to continue its work, evrex_bottle; for a commit's story, evrex_commit_context. Expand only what the task needs."
+  ].join("\n");
+}
+function formatTimelineLine(entry, repoName) {
+  const handle = entry.kind === "commit" ? `commit:${entry.refId.slice(0, 12)}` : `session:${entry.refId}`;
+  const tags = [entry.kind === "session" ? entry.sourceKind ?? "session" : "commit"];
+  if (entry.kind === "commit") {
+    if (entry.linkStatus === "inferred" && entry.confidence !== void 0) {
+      tags.push(`${Math.round(entry.confidence * 100)}%`);
+    } else if (entry.linkStatus) {
+      tags.push(entry.linkStatus);
+    }
+  }
+  if (entry.author && entry.author !== "Unknown") tags.push(entry.author);
+  if (entry.meta) tags.push(entry.meta);
+  if (repoName) tags.push(repoName);
+  const nest = entry.kind === "commit" && entry.sessionId && entry.linkStatus !== "inferred" ? ` \u21B3 session:${entry.sessionId}` : "";
+  const title = truncate(entry.title.replace(/\s+/g, " ").trim(), INDEX_EXCERPT);
+  return `- ${dateLabel(entry.at).trim() || "undated"} ${handle} [${tags.join(" \xB7 ")}${nest}] ${title}`;
+}
+function proceduresBlock(procedures) {
+  if (procedures.length === 0) return "";
+  return "PROCEDURES (how this was done here, as steps that worked once \u2014 check they still apply before following them):\n" + procedures.slice(0, MAX_ITEMS).map((p) => `- ${p.title}
+${p.steps.slice(0, 12).map((step, i) => `    ${i + 1}. ${step}`).join("\n")}`).join("\n");
+}
 async function evrexExpand(handles) {
   if (handles.length === 0) return "No handles given. Pass ids from evrex_search, e.g. commit:069a0b5.";
   const parts = [];
@@ -1263,9 +1660,20 @@ Open in Evrex: evrex://open?handle=commit:${id}`);
       `${handle.toUpperCase()}: ${session.intent}`,
       `Open in Evrex: evrex://open?handle=session:${id}`
     ];
+    if (session.parentSessionId) {
+      const what = session.subagent?.agentType ? ` (${session.subagent.agentType})` : "";
+      block.push(`SUB-AGENT${what} of session:${session.parentSessionId} \u2014 expand that for what it was asked to do and what became of it.`);
+    }
+    if (session.subagentIds && session.subagentIds.length > 0) {
+      block.push(
+        `RAN ${session.subagentIds.length} SUB-AGENT${session.subagentIds.length === 1 ? "" : "S"}: ` + session.subagentIds.map((s) => `session:${s}`).join(", ") + " \u2014 their own decisions and rejected approaches are in their own records."
+      );
+    }
+    const fb = feedbackLines(session.feedback);
+    if (fb) block.push(fb);
     if (session.rejected.length > 0) {
       block.push(
-        "REJECTED APPROACHES:\n" + session.rejected.slice(0, MAX_ITEMS).map((r) => `- ${r.title} \u2014 ${r.reason}${r.tradeoff ? ` (tradeoff: ${r.tradeoff})` : ""}`).join("\n")
+        "REJECTED APPROACHES:\n" + session.rejected.slice(0, MAX_ITEMS).map((r) => `- ${r.title} \u2014 ${r.reason}${r.tradeoff ? ` (tradeoff: ${r.tradeoff})` : ""}${itemMark(session.feedback, r.id)}`).join("\n")
       );
     }
     if (session.constraints.length > 0) {
@@ -1278,6 +1686,8 @@ Open in Evrex: evrex://open?handle=commit:${id}`);
         "PRIOR DECISIONS:\n" + session.decisions.slice(0, MAX_ITEMS).map((d) => `- ${d.title}: ${d.detail}`).join("\n")
       );
     }
+    const procedures = proceduresBlock(session.procedures ?? []);
+    if (procedures) block.push(procedures);
     parts.push(block.join("\n"));
   }
   parts.push(
@@ -1285,6 +1695,46 @@ Open in Evrex: evrex://open?handle=commit:${id}`);
   );
   return parts.join("\n\n");
 }
+var FEEDBACK_SIGNALS = ["helpful", "not_helpful", "stale", "wrong", "superseded"];
+function feedbackLines(feedback) {
+  if (!feedback || feedback.length === 0) return "";
+  const lines = feedback.slice(0, MAX_ITEMS).map((f) => {
+    const scope = f.itemId ? ` on ${f.itemId}` : "";
+    const by = f.supersededBy ? ` by ${f.supersededBy}` : "";
+    const note = f.note ? `: ${truncate(f.note, 160)}` : "";
+    return `- ${f.signal}${by}${scope}${dateLabel(f.at)}${note}`;
+  });
+  return `READER FEEDBACK (what someone said after reading this \u2014 weigh it above the record's own date):
+${lines.join("\n")}`;
+}
+function itemMark(feedback, itemId) {
+  const marks = (feedback ?? []).filter((f2) => f2.itemId === itemId && f2.signal !== "helpful");
+  if (marks.length === 0) return "";
+  const f = marks[0];
+  return ` [marked ${f.signal}${f.supersededBy ? ` by ${f.supersededBy}` : ""}${dateLabel(f.at)}${f.note ? `: ${truncate(f.note, 100)}` : ""}]`;
+}
+async function evrexFeedback(handle, signal, note, itemId, supersededBy) {
+  if (!FEEDBACK_SIGNALS.includes(signal)) {
+    return `"${signal}" is not a signal. One of: ${FEEDBACK_SIGNALS.join(", ")}.`;
+  }
+  if (signal === "superseded" && !supersededBy) {
+    return `"superseded" names the record that replaced this one \u2014 pass superseded_by with its handle.`;
+  }
+  try {
+    const saved = await evrexApi.feedback({
+      target: handle.trim(),
+      signal,
+      ...note ? { note } : {},
+      ...itemId ? { itemId } : {},
+      ...supersededBy ? { supersededBy } : {}
+    });
+    const where = itemId ? ` (item ${itemId})` : "";
+    const effect = signal === "stale" || signal === "wrong" || signal === "superseded" ? itemId ? "The item will carry this label wherever it is shown." : "The record now ranks at half weight in retrieval and carries this label wherever it is shown; it is not hidden." : "Recorded beside the record.";
+    return `Recorded ${saved.signal} on ${handle}${where}${saved.supersededBy ? ` \u2014 superseded by ${saved.supersededBy}` : ""}. ${effect}`;
+  } catch (err) {
+    return `Could not record feedback: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}
 var BOTTLE_PAGE = 200;
 var BOTTLE_TAIL_TURNS = 400;
 async function evrexBottle(sessionRef) {
@@ -1308,6 +1758,23 @@ async function evrexBottle(sessionRef) {
     `For what it concluded \u2014 decisions, constraints, rejected approaches \u2014 use evrex_expand ["session:${id}"].`
   ].join("\n\n");
 }
+function statedBlocks(items, handle) {
+  const of = (kind) => items.filter((i) => i.kind === kind).map((i) => `- ${i.text}`);
+  const rejected = of("rejected");
+  const constraints = of("constraint");
+  const decisions = of("decision");
+  if (rejected.length + constraints.length + decisions.length === 0) return "";
+  const parts = [
+    `STATED IN THE COMMIT (${handle} wrote these as trailers at commit time \u2014 the committer's own account, not extracted by a model):`
+  ];
+  if (rejected.length) parts.push(`REJECTED:
+${rejected.join("\n")}`);
+  if (constraints.length) parts.push(`CONSTRAINTS:
+${constraints.join("\n")}`);
+  if (decisions.length) parts.push(`DECISIONS:
+${decisions.join("\n")}`);
+  return parts.join("\n");
+}
 async function evrexCommitContext(sha) {
   const commit = await evrexApi.commit(sha);
   if (!commit) return `No commit found for sha ${sha}.`;
@@ -1315,6 +1782,8 @@ async function evrexCommitContext(sha) {
     `COMMIT ${commit.sha.slice(0, 8)}: ${commit.message}${commit.body ? `
 ${truncate(commit.body, MAX_EXCERPT)}` : ""}`
   ];
+  const commitFeedback = feedbackLines(commit.feedback);
+  if (commitFeedback) parts.push(commitFeedback);
   if (commit.link) {
     const session = await evrexApi.session(commit.link.sessionId);
     const status = commit.link.provenance.status;
@@ -1339,9 +1808,16 @@ ${truncate(commit.body, MAX_EXCERPT)}` : ""}`
       }
       parts.push(`OUTCOME: ${truncate(session.outcome, MAX_EXCERPT)}`);
     }
-  } else {
+  } else if (!commit.agentTrailers?.length) {
     parts.push("No session linked \u2014 no recorded reasoning behind this commit.");
   }
+  const stated = statedBlocks(commit.statedInsights ?? [], `commit:${commit.sha.slice(0, 12)}`);
+  if (stated) parts.push(stated);
+  for (const t of commit.agentTrailers ?? []) {
+    parts.push(
+      `SESSION RECORDED ELSEWHERE (${t.label}): ${t.value} \u2014 evrex holds this pointer, not the transcript, so nothing below was extracted from it. Open it for the reasoning behind this commit; do not treat this line as recovered context.`
+    );
+  }
   if (commit.relatedCommitIds.length > 0) {
     const relatedShas = commit.relatedCommitIds.slice(0, MAX_ITEMS);
     const related = (await Promise.all(relatedShas.map((s) => evrexApi.commit(s)))).filter(
@@ -1355,7 +1831,7 @@ ${lines.join("\n")}`);
 }
 
 // src/index.ts
-var VERSION = "0.4.0";
+var VERSION = "0.8.0";
 var server = new McpServer({ name: "evrex", version: VERSION });
 server.registerTool(
   "evrex_why",
@@ -1400,6 +1876,39 @@ server.registerTool(
     return { content: [{ type: "text", text }] };
   }
 );
+server.registerTool(
+  "evrex_timeline",
+  {
+    title: "What happened in this repo lately",
+    description: "Everything recorded in this repo in the last N days, newest first \u2014 captured agent sessions and ingested commits interleaved, each line a handle evrex_expand or evrex_bottle takes. Use it to pick up a repo after time away ('what happened this week', 'what did the team do while I was out', 'what is in progress'), or before proposing work that may already be underway. It is ordered by time, not relevance: evrex_search cannot answer 'what is recent' because nothing about recency is in a query. Returns an index, not the record \u2014 expand only the handles the task needs.",
+    inputSchema: {
+      days: z.number().int().min(1).max(90).optional().describe("How far back to look, in days. Default 7, maximum 90."),
+      limit: z.number().int().min(1).max(200).optional().describe("At most this many lines, newest first. Default 30, maximum 200.")
+    }
+  },
+  async ({ days, limit }) => {
+    const text = await evrexTimeline(days, limit);
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.registerTool(
+  "evrex_feedback",
+  {
+    title: "Say something about a record after reading it",
+    description: "Mark a record \u2014 a session or a commit from evrex_search / evrex_why / evrex_expand \u2014 as helpful, not_helpful, stale, wrong, or superseded by another record. Use it when the record led you astray: a decision a later change reversed, a rejected approach that turned out to be the right one, a constraint that no longer holds \u2014 or when it saved real work. A stale/wrong/superseded record ranks lower afterwards and carries the label on every surface; it is never hidden. Pass item_id (e.g. rej:llm:2) to mark one item rather than the whole record.",
+    inputSchema: {
+      handle: z.string().describe("session:<id> or commit:<sha>, as evrex_search prints it"),
+      signal: z.enum(["helpful", "not_helpful", "stale", "wrong", "superseded"]),
+      note: z.string().optional().describe("One line on why \u2014 what you found instead"),
+      item_id: z.string().optional().describe("One item within the record, e.g. rej:llm:2, con:llm:0, dec:llm:1"),
+      superseded_by: z.string().optional().describe("For superseded: the handle of the record that replaced it")
+    }
+  },
+  async ({ handle, signal, note, item_id, superseded_by }) => {
+    const text = await evrexFeedback(handle, signal, note, item_id, superseded_by);
+    return { content: [{ type: "text", text }] };
+  }
+);
 server.registerTool(
   "evrex_bottle",
   {