evrex-mcp 0.6.0 → 0.8.0

package/dist/index.js

@@ -54,11 +54,23 @@ var init_client = __esm({
       commit: (sha) => getOrNull(`/commits/${encodeURIComponent(sha)}`),
       sessions: (repoPath) => get(`/sessions?repoPath=${encodeURIComponent(repoPath)}`),
       session: (id) => getOrNull(`/sessions/${encodeURIComponent(id)}`),
+      // The paginated transcript — see reads.service.ts#getSessionTurns. `ts, id`
+      // ordering server-side makes offsets stable across requests.
+      sessionTurns: (id, offset, limit) => getOrNull(
+        `/sessions/${encodeURIComponent(id)}/turns?offset=${offset}&limit=${limit}`
+      ),
       ask: (repoPath, text, filePaths) => post("/ask", { repoPath, text, filePaths }),
       // 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))}`
+      )
     };
   }
 });
@@ -344,7 +356,7 @@ import { z } from "zod";
 
 // src/tools.ts
 init_client();
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve as resolvePath } from "node:path";
 
@@ -429,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
@@ -948,6 +962,96 @@ async function synthesize(question, evidence) {
   return { sentences: result.sentences };
 }
 
+// src/hook-runtime.ts
+import { execFileSync } from "node:child_process";
+function dateLabel(at) {
+  if (!at) return "";
+  const d = new Date(at);
+  return Number.isNaN(d.getTime()) ? "" : ` ${d.toISOString().slice(0, 10)}`;
+}
+function localCommitDates(root, shas) {
+  const out = /* @__PURE__ */ new Map();
+  if (!root || shas.length === 0) return out;
+  try {
+    const raw = execFileSync("git", ["show", "-s", "--format=%H%x09%cI", ...shas], {
+      cwd: root,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1500
+    }).toString("utf-8");
+    for (const line of raw.split("\n")) {
+      const [sha, iso] = line.split("	");
+      if (sha && iso) out.set(sha, iso);
+    }
+  } catch {
+  }
+  return out;
+}
+function datedEvidence(items, root) {
+  const missing = items.filter((e) => !e.at && e.kind === "commit").map((e) => e.refId);
+  if (missing.length === 0) return items;
+  const dates = localCommitDates(root, missing);
+  return items.map(
+    (e) => e.at || e.kind !== "commit" ? e : { ...e, at: dates.get(e.refId) ?? void 0 }
+  );
+}
+function spentLabel(tokens) {
+  if (!tokens || tokens <= 0) return "";
+  const short = tokens >= 1e6 ? `${(tokens / 1e6).toFixed(1)}M` : tokens >= 1e3 ? `${Math.round(tokens / 1e3)}k` : String(tokens);
+  return ` \xB7 ${short} spent`;
+}
+
+// src/bottle.ts
+var HUMAN_CAP = 700;
+var AGENT_CAP = 500;
+function cap(text, max) {
+  const trimmed = text.trim();
+  return trimmed.length > max ? `${trimmed.slice(0, max - 1)}\u2026` : trimmed;
+}
+function renderEntriesToBottle(entries, preamble, budgetChars) {
+  if (entries.length === 0) return "";
+  const kept = [];
+  let spent = 0;
+  let truncated = false;
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const text = entries[i].text;
+    if (spent + text.length > budgetChars) {
+      truncated = true;
+      break;
+    }
+    kept.unshift(text);
+    spent += text.length;
+  }
+  if (kept.length === 0) return "";
+  return [
+    "<evrex-bottle>",
+    preamble,
+    truncated ? "(Older history did not fit and was dropped from the top.)" : "",
+    "",
+    ...kept,
+    "</evrex-bottle>"
+  ].filter((l, i) => l !== "" || i === 3).join("\n");
+}
+function bottleFromTurns(turns, who, budgetChars = 12e3) {
+  const entries = [];
+  for (const t of turns) {
+    if (t.isToolOutput) continue;
+    const body = t.body?.trim();
+    if (!body) continue;
+    if (t.role === "engineer") {
+      entries.push({ text: `HUMAN: ${cap(body, HUMAN_CAP)}` });
+    } else if (body.startsWith("[tool_call:")) {
+      entries.push({ text: cap(body.split("\n")[0] ?? body, 110) });
+    } else {
+      entries.push({ text: `ASSISTANT: ${cap(body, AGENT_CAP)}` });
+    }
+  }
+  return renderEntriesToBottle(
+    entries,
+    `The recorded conversation of ${who}, as ingested \u2014 human and assistant messages verbatim, tool work reduced to one-line markers. This is what was said then, not a statement of what is true now: pick up from where it leaves off, verify against the code before asserting anything it claims, and do not re-try what it shows already failing.`,
+    budgetChars
+  );
+}
+
 // src/tools.ts
 var MAX_EXCERPT = 220;
 function confidenceLabel(p) {
@@ -955,6 +1059,7 @@ function confidenceLabel(p) {
   return p.status;
 }
 var MAX_ITEMS = 5;
+var INDEX_EXCERPT = 110;
 function evidenceLabel(e) {
   return e.kind === "session" ? e.sourceKind ?? "session" : e.kind;
 }
@@ -987,7 +1092,7 @@ function normalizeRepoRemote(url) {
 }
 function git(cwd, args) {
   try {
-    return execFileSync("git", args, {
+    return execFileSync2("git", args, {
       cwd,
       maxBuffer: 1024 * 1024 * 8,
       stdio: ["ignore", "pipe", "ignore"]
@@ -1054,11 +1159,12 @@ async function resolveRepos() {
 async function evrexWhy(filePath, question) {
   const { repoRef, root } = resolveRepoContext(filePath);
   const text = question ?? `What decisions, constraints, and rejected approaches apply to ${filePath}?`;
-  const { evidence } = await evrexApi.search(repoRef, text, [
+  const { evidence: rawEvidence } = await evrexApi.search(repoRef, text, [
     toRepoRelative(isAbsolute(filePath) ? filePath : resolvePath(process.cwd(), filePath), root)
   ]);
+  const evidence = datedEvidence(rawEvidence, root);
   if (evidence.length === 0) {
-    return `No recorded reasoning found for ${filePath}. Nothing in the indexed sessions or commit history covers this file's design.`;
+    return `No recorded reasoning found for ${filePath}. Nothing in the indexed sessions or commit history covers this file's design. This is an answer, not a failure \u2014 and not a reason to stop: carry on and work it out from the code as you would have without this tool, and say the history does not cover it rather than implying there was nothing to find.`;
   }
   const sessionIds = [...new Set(evidence.filter((e) => e.kind === "session").map((e) => e.refId))];
   const sessions = (await Promise.all(sessionIds.map((id) => evrexApi.session(id)))).filter(
@@ -1069,28 +1175,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})` : ""}`).join("\n")
+      "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 > 0) {
-    parts.push("CONSTRAINTS:\n" + constraints.map((c) => `- [${c.source}] ${c.text}`).join("\n"));
+  if (constraints.length + statedConstraints.length > 0) {
+    parts.push(
+      "CONSTRAINTS:\n" + [...constraints.map((c) => `- [${c.source}] ${c.text}`), ...statedConstraints.map(statedLine)].join("\n")
+    );
   }
-  if (decisions.length > 0) {
-    parts.push("PRIOR DECISIONS:\n" + decisions.map((d) => `- ${d.title}: ${d.detail}`).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")
+    );
+  }
+  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(
@@ -1098,11 +1236,11 @@ async function evrexWhy(filePath, question) {
     );
   } else {
     parts.push(
-      hasBlocks ? "HOW TO USE THIS: treat the constraints and rejected approaches above as binding \u2014 they are what this team already decided, not suggestions. Do not re-propose a rejected approach unless you have new information that specifically invalidates the stated reason, and say so if you do. Answer the user from the evidence below; if it does not actually cover their question, say that rather than inferring." : "HOW TO USE THIS: no decisions, constraints or rejected approaches were extracted for this file \u2014 only the raw evidence below. Treat it as history to read, not as settled policy, and say so if it does not cover the question."
+      hasBlocks ? "HOW TO USE THIS: treat the constraints and rejected approaches above as binding \u2014 they are what this team already decided, not suggestions. Do not re-propose a rejected approach unless you have new information that specifically invalidates the stated reason, and say so if you do.\nThis is a record of what was said, dated, not a statement of what is true now. Two rules follow, and skipping them is measurably worse than not asking at all: check any claim you are about to make against the code before you make it, and where two records disagree prefer the later one \u2014 a decision here may have been reversed by a commit further down this list. If the evidence does not cover the question, say so rather than inferring." : "HOW TO USE THIS: no decisions, constraints or rejected approaches were extracted for this file \u2014 only the raw evidence below, dated. Treat it as history to read, not as settled policy: verify against the code anything you intend to assert, prefer a later record to an earlier one, and say plainly if it does not cover the question."
     );
   }
   const evidenceLines = evidence.slice(0, MAX_ITEMS).map((e) => {
-    return `- [${evidenceLabel(e)} ${confidenceLabel(e.provenance)}] ${truncate(e.excerpt, MAX_EXCERPT)}`;
+    return `- [${evidenceLabel(e)} ${confidenceLabel(e.provenance)}${dateLabel(e.at)}] ${truncate(e.excerpt, MAX_EXCERPT)}`;
   });
   parts.push(`EVIDENCE:
 ${evidenceLines.join("\n")}`);
@@ -1124,15 +1262,219 @@ async function evrexSearch(query) {
     })
   );
   const results = perRepo.flat();
-  if (results.length === 0) return `No matches for "${query}" across indexed sessions and commits.`;
+  if (results.length === 0) {
+    return `No matches for "${query}" across indexed sessions and commits. Nothing was recorded on this, which is an answer rather than an error. Continue with normal exploration \u2014 read the code, git log, git blame \u2014 and answer from that, noting that the reasoning was never written down.`;
+  }
   const rank = (e) => e.provenance.status === "verified" ? 1 : e.provenance.confidence ?? 0;
   results.sort((a, b) => rank(b.e) - rank(a.e));
   const lines = results.slice(0, MAX_ITEMS * 2).map(({ repo, e }) => {
     const conf = confidenceLabel(e.provenance);
     const repoTag = multiRepo ? ` \xB7 ${repo.name}` : "";
-    return `- [${evidenceLabel(e)} ${e.refId.slice(0, 8)} ${conf}${repoTag}] ${truncate(e.excerpt.replace(/\s+/g, " ").trim(), MAX_EXCERPT)}`;
+    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 lines.join("\n");
+  return [
+    ...lines,
+    "",
+    "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 = [];
+  for (const handle of handles.slice(0, MAX_ITEMS)) {
+    const [kind, ...rest] = handle.split(":");
+    const id = rest.join(":");
+    if (!id) {
+      parts.push(`${handle}: not a handle. Expected kind:id, as evrex_search prints it.`);
+      continue;
+    }
+    if (kind === "commit") {
+      parts.push(`${await evrexCommitContext(id)}
+
+Open in Evrex: evrex://open?handle=commit:${id}`);
+      continue;
+    }
+    const session = await evrexApi.session(id);
+    if (!session) {
+      parts.push(`${handle}: no such record, or it was never uploaded.`);
+      continue;
+    }
+    const block = [
+      `${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})` : ""}${itemMark(session.feedback, r.id)}`).join("\n")
+      );
+    }
+    if (session.constraints.length > 0) {
+      block.push(
+        "CONSTRAINTS:\n" + session.constraints.slice(0, MAX_ITEMS).map((c) => `- [${c.source}] ${c.text}`).join("\n")
+      );
+    }
+    if (session.decisions.length > 0) {
+      block.push(
+        "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(
+    "This is what was said, dated \u2014 not what is true now. Verify against the code anything you are about to assert, and prefer a later record where two disagree."
+  );
+  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) {
+  const id = sessionRef.startsWith("session:") ? sessionRef.slice("session:".length) : sessionRef;
+  if (!id.trim()) return "Pass a session id or a session:<id> handle from evrex_search.";
+  const first = await evrexApi.sessionTurns(id, 0, 1);
+  if (!first) return `No session found for ${id}, or it was never uploaded.`;
+  if (first.total === 0) return `Session ${id} is recorded but has no stored turns to render.`;
+  const from = Math.max(0, first.total - BOTTLE_TAIL_TURNS);
+  const pages = await Promise.all([
+    evrexApi.sessionTurns(id, from, BOTTLE_PAGE),
+    first.total - from > BOTTLE_PAGE ? evrexApi.sessionTurns(id, from + BOTTLE_PAGE, BOTTLE_PAGE) : Promise.resolve(null)
+  ]);
+  const turns = pages.flatMap((p) => p?.turns ?? []);
+  const session = await evrexApi.session(id);
+  const who = session ? `session ${id.slice(0, 8)} ("${session.intent}")` : `session ${id.slice(0, 8)}`;
+  const bottle = bottleFromTurns(turns, who);
+  if (!bottle) return `Session ${id} holds only tool traffic \u2014 nothing conversational to render.`;
+  return [
+    bottle,
+    `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);
@@ -1141,6 +1483,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;
@@ -1165,9 +1509,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(
@@ -1181,7 +1532,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",
@@ -1212,6 +1563,67 @@ server.registerTool(
     return { content: [{ type: "text", text }] };
   }
 );
+server.registerTool(
+  "evrex_expand",
+  {
+    title: "Read Evrex records in full",
+    description: "The second half of evrex_search. That returns an index of gists with a handle on each line (`commit:069a0b5`, `slack:a1b2\u2026`); this returns the full record for the handles you pick \u2014 the whole excerpt plus any decisions, constraints and rejected approaches attached to it. Batch the handles you actually want in one call. Expanding every result costs more than a single-shot search would have; expanding the two that look like the answer costs far less, which is the entire point of the split. If nothing in the index looked relevant, say the record does not cover it rather than expanding on spec.",
+    inputSchema: {
+      handles: z.array(z.string()).describe("Handles exactly as evrex_search printed them, e.g. ['commit:069a0b5']")
+    }
+  },
+  async ({ handles }) => {
+    const text = await evrexExpand(handles);
+    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",
+  {
+    title: "Read a session's conversation, ready to continue",
+    description: "The recorded conversation of an ingested session \u2014 a teammate's, or an earlier one of your own \u2014 with the tool traffic wrung out: human and assistant messages verbatim, each tool call one line, tool output dropped. Use it to pick up unfinished work mid-flow ('continue Jeff's session'): the last exchanges carry the plan half-stated and the instruction not yet acted on, which the extracted insights do not. For what a session concluded rather than how it went, use evrex_expand instead. Takes a session id or a session:<id> handle from evrex_search.",
+    inputSchema: {
+      session: z.string().describe("Session id, or a session:<id> handle as evrex_search prints it")
+    }
+  },
+  async ({ session }) => {
+    const text = await evrexBottle(session);
+    return { content: [{ type: "text", text }] };
+  }
+);
 server.registerTool(
   "evrex_commit_context",
   {