@agentprojectcontext/apx 1.0.3

package/src/core/apx-skill.md

@@ -0,0 +1,78 @@
+# APX — Agent Project Framework
+
+The daemon runs on `127.0.0.1:7430` and auto-starts on first `apx` call.
+
+---
+
+## Coordinate with other agents
+
+**First: can you spawn a subagent natively in this IDE?**
+
+If yes — do that. No APX needed. Claude Code, Cursor, and other IDEs can spawn subagents directly using your current context.
+
+Use `apx run` only when:
+- The user explicitly asks to run the agent in a specific external runtime ("run this in Codex", "run the QA agent outside this session")
+- You need to run an agent in a runtime different from the one you're in
+- You're orchestrating from outside any IDE (e.g. a script, Telegram bot, CI)
+
+```bash
+# Run agent in an external runtime — full isolated session
+apx run <slug> --runtime claude-code "<prompt>"
+apx run <slug> --runtime codex        "<prompt>"
+apx run <slug> --runtime opencode     "<prompt>"
+
+# Example: run the qa agent in codex with a specific task
+apx run qa --runtime codex "run the full test suite and report failures"
+```
+
+The output is the agent's full stdout. If it printed `APC_RESULT: <value>`, that value is captured as structured output.
+
+```bash
+# Quick one-shot LLM call (no external CLI needed, uses ~/.apx/config.json engine key)
+apx exec <slug> "<prompt>"
+```
+
+## MCP tools
+
+MCPs declared in `.apc/mcps.json` are proxied through the APX daemon. Use `apx mcp` only for MCPs registered there — not for MCPs that are already running locally in your IDE session.
+
+```bash
+apx mcp list                            # MCPs registered in .apc/mcps.json
+apx mcp tools <server>                  # tools a server exposes
+apx mcp run   <server> <tool> '<json>'  # call a tool
+
+# Example:
+apx mcp tools filesystem
+apx mcp run filesystem read_file '{"path": "README.md"}'
+```
+
+## Memory
+
+```bash
+apx memory <slug>                       # read agent's memory.md
+apx memory <slug> --append "<fact>"     # append a durable note
+apx memory <slug> --replace < file.md  # replace entire memory from stdin
+```
+
+## Sessions
+
+```bash
+apx session new <slug> --title "What you did"   # create session file
+apx session list <slug>                          # list sessions
+apx session check                                # exits 1 if session already active
+```
+
+## Observe activity
+
+```bash
+apx messages tail                               # last 50 messages, all channels
+apx messages tail --channel runtime             # only agent invocations
+apx messages tail --agent <slug> -n 20
+```
+
+## APC_RESULT
+
+Print on the last meaningful line of your output so the invoker captures it:
+```
+APC_RESULT: <one-line summary or value>
+```

package/src/core/config.js

@@ -0,0 +1,129 @@
+// Global APX config under ~/.apx/config.json. Cross-platform.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const APX_HOME = path.join(os.homedir(), ".apx");
+export const CONFIG_PATH = path.join(APX_HOME, "config.json");
+export const PID_PATH = path.join(APX_HOME, "daemon.pid");
+export const LOG_PATH = path.join(APX_HOME, "daemon.log");
+export const TELEGRAM_STATE_PATH = path.join(APX_HOME, "telegram-state.json");
+// Global channel messages (telegram, direct, whatsapp, …) live here,
+// separated from any project.  Structure: ~/.apx/messages/<channel>/YYYY-MM-DD.jsonl
+export const GLOBAL_MESSAGES_DIR = path.join(APX_HOME, "messages");
+
+const DEFAULT_CONFIG = {
+  port: 7430,
+  host: "127.0.0.1",
+  log_level: "info",
+  projects: [],
+  telegram: {
+    enabled: false,
+    bot_token: "",
+    chat_id: "",
+    poll_interval_ms: 1500,
+    route_to_agent: "",                 // slug of the agent that auto-replies (single-channel mode)
+    respond_with_engine: true,          // false → just log, never auto-reply
+    channels: [],                       // multi-channel mode; each item: {name, bot_token, chat_id, route_to_agent, project, respond_with_engine}
+  },
+  super_agent: {
+    enabled: false,
+    name: "apx",
+    model: "",                          // e.g. "ollama:llama3.2:3b"
+    system: "",                         // optional override; defaults baked into super-agent.js
+  },
+  engines: {
+    anthropic: { api_key: "" },
+    openai: { api_key: "" },
+    gemini: { api_key: "" },
+    ollama: { base_url: "http://localhost:11434" },
+  },
+};
+
+function ensureHome() {
+  fs.mkdirSync(APX_HOME, { recursive: true });
+}
+
+export function readConfig() {
+  ensureHome();
+  if (!fs.existsSync(CONFIG_PATH)) {
+    writeConfig(DEFAULT_CONFIG);
+    return structuredClone(DEFAULT_CONFIG);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+  } catch (e) {
+    throw new Error(`invalid ${CONFIG_PATH}: ${e.message}`);
+  }
+  return mergeDefaults(raw);
+}
+
+export function writeConfig(cfg) {
+  ensureHome();
+  const tmp = `${CONFIG_PATH}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n");
+  fs.renameSync(tmp, CONFIG_PATH);
+}
+
+export function mergeDefaults(cfg) {
+  return {
+    ...DEFAULT_CONFIG,
+    ...cfg,
+    telegram: {
+      ...DEFAULT_CONFIG.telegram,
+      ...(cfg.telegram || {}),
+      channels: Array.isArray(cfg.telegram?.channels) ? cfg.telegram.channels : [],
+    },
+    super_agent: { ...DEFAULT_CONFIG.super_agent, ...(cfg.super_agent || {}) },
+    engines: {
+      ...DEFAULT_CONFIG.engines,
+      ...(cfg.engines || {}),
+      anthropic: { ...DEFAULT_CONFIG.engines.anthropic, ...(cfg.engines?.anthropic || {}) },
+      openai:    { ...DEFAULT_CONFIG.engines.openai,    ...(cfg.engines?.openai    || {}) },
+      gemini:    { ...DEFAULT_CONFIG.engines.gemini,    ...(cfg.engines?.gemini    || {}) },
+      ollama:    { ...DEFAULT_CONFIG.engines.ollama,    ...(cfg.engines?.ollama    || {}) },
+    },
+    projects: Array.isArray(cfg.projects) ? cfg.projects : [],
+  };
+}
+
+export function effectivePort(cfg) {
+  const env = process.env.APX_PORT;
+  if (env && /^\d+$/.test(env)) return parseInt(env, 10);
+  return cfg.port || DEFAULT_CONFIG.port;
+}
+
+export function effectiveHost(cfg) {
+  return process.env.APX_HOST || cfg.host || DEFAULT_CONFIG.host;
+}
+
+export function addProject(cfg, projectPath) {
+  const abs = path.resolve(projectPath);
+  if (!fs.existsSync(path.join(abs, "AGENTS.md"))) {
+    throw new Error(`not an APC project: ${abs} (no AGENTS.md)`);
+  }
+  if (!fs.existsSync(path.join(abs, ".apc", "project.json"))) {
+    throw new Error(`not an APC project: ${abs} (no .apc/project.json)`);
+  }
+  const exists = cfg.projects.find((p) => path.resolve(p.path) === abs);
+  if (exists) return { added: false, project: exists };
+
+  const entry = { path: abs };
+  cfg.projects.push(entry);
+  writeConfig(cfg);
+  return { added: true, project: entry };
+}
+
+export function removeProject(cfg, idOrPath) {
+  const before = cfg.projects.length;
+  if (typeof idOrPath === "number" || /^\d+$/.test(String(idOrPath))) {
+    const idx = parseInt(idOrPath, 10) - 1;
+    if (idx >= 0 && idx < cfg.projects.length) cfg.projects.splice(idx, 1);
+  } else {
+    const abs = path.resolve(String(idOrPath));
+    cfg.projects = cfg.projects.filter((p) => path.resolve(p.path) !== abs);
+  }
+  if (cfg.projects.length !== before) writeConfig(cfg);
+  return { removed: before - cfg.projects.length };
+}

package/src/core/identity.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export const IDENTITY_PATH = path.join(os.homedir(), ".apx", "identity.json");
+
+export function readIdentity() {
+  try {
+    return JSON.parse(fs.readFileSync(IDENTITY_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeIdentity(fields) {
+  const existing = readIdentity() || {};
+  const now = new Date().toISOString();
+  const updated = { ...existing, ...fields, updated: now };
+  if (!updated.created) updated.created = now;
+  fs.mkdirSync(path.dirname(IDENTITY_PATH), { recursive: true });
+  fs.writeFileSync(IDENTITY_PATH, JSON.stringify(updated, null, 2) + "\n");
+  return updated;
+}

package/src/core/messages-store.js

@@ -0,0 +1,421 @@
+// Messages store: filesystem source-of-truth + SQLite cache mirror.
+//
+// On disk (project-specific — runtime, a2a, exec):
+//   <project>/.apc/messages/YYYY-MM-DD.jsonl
+//
+// On disk (global cross-project channels — telegram, direct, whatsapp, …):
+//   ~/.apx/messages/<channel>/YYYY-MM-DD.jsonl
+//
+// Each line:
+//   {"ts":"...","channel":"...","direction":"in|out","author":"...","body":"...","meta":{...}}
+//
+// Why JSONL: same shape as Claude Code's ~/.claude/projects/<id>.jsonl.
+// Streamable, structured, no markdown parsing fragility.
+//
+// Daemon writes go through `appendMessage` (project) or `appendGlobalMessage`
+// (cross-project channel). `rebuildMessagesFromFs` is idempotent — wipes the
+// SQL cache then reads every project day file in order.
+
+import fs from "node:fs";
+import path from "node:path";
+import { GLOBAL_MESSAGES_DIR } from "./config.js";
+
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+
+function dayPathJsonl(projectRoot, ts) {
+  const day = (ts || nowIso()).slice(0, 10);
+  return path.join(projectRoot, ".apc", "messages", `${day}.jsonl`);
+}
+
+function dayPathMd(projectRoot, ts) {
+  const day = (ts || nowIso()).slice(0, 10);
+  return path.join(projectRoot, ".apc", "messages", `${day}.md`);
+}
+
+export function appendMessageToFs({ projectRoot, channel, direction, author, body, meta = {}, ts, agent_slug, session_id, external_id }) {
+  ts = ts || nowIso();
+  const file = dayPathJsonl(projectRoot, ts);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  // Compose meta from explicit fields plus the bag
+  const fullMeta = {
+    ...(agent_slug ? { agent: agent_slug } : {}),
+    ...(session_id ? { session_id } : {}),
+    ...(external_id ? { external_id } : {}),
+    ...meta,
+  };
+
+  const record = {
+    ts,
+    channel,
+    direction,
+    author: author || null,
+    body: body || "",
+    ...(Object.keys(fullMeta).length ? { meta: fullMeta } : {}),
+  };
+
+  fs.appendFileSync(file, JSON.stringify(record) + "\n");
+  return { ts, file };
+}
+
+// Insert a row into the SQL cache. Used by both appendMessage and rebuild.
+export function insertMessageRow(db, m) {
+  let agent_id = null;
+  if (m.agent_slug) {
+    const a = db.prepare("SELECT id FROM agents WHERE slug = ?").get(m.agent_slug);
+    if (a) agent_id = a.id;
+  }
+  return db
+    .prepare(
+      `INSERT INTO messages (agent_id, session_id, channel, direction, external_id, author, body, meta_json, ts)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    )
+    .run(
+      agent_id,
+      m.session_id || null,
+      m.channel,
+      m.direction,
+      m.external_id || null,
+      m.author || null,
+      m.body || "",
+      JSON.stringify(m.meta || {}),
+      m.ts
+    );
+}
+
+// Single entry point used by everywhere the daemon writes a message.
+export function appendMessage({ projectRoot, db, channel, direction, author, body, meta = {}, ts, agent_slug, session_id, external_id }) {
+  const written = appendMessageToFs({
+    projectRoot,
+    channel,
+    direction,
+    author,
+    body,
+    meta,
+    ts,
+    agent_slug,
+    session_id,
+    external_id,
+  });
+  insertMessageRow(db, {
+    channel,
+    direction,
+    author,
+    body,
+    meta,
+    ts: written.ts,
+    agent_slug,
+    session_id,
+    external_id,
+  });
+  return written;
+}
+
+// Parse one .jsonl day file into [{...}, ...]
+export function parseDayJsonl(text) {
+  const out = [];
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let obj;
+    try { obj = JSON.parse(trimmed); } catch { continue; }
+    if (!obj || typeof obj !== "object") continue;
+    const meta = obj.meta || {};
+    out.push({
+      ts: obj.ts,
+      channel: obj.channel,
+      direction: obj.direction,
+      author: obj.author,
+      body: obj.body || "",
+      meta,
+      agent_slug: meta.agent,
+      session_id: typeof meta.apc_session_id === "number" ? meta.apc_session_id : null,
+      external_id: meta.external_id,
+    });
+  }
+  return out;
+}
+
+// Parse the legacy .md format (kept so rebuild still picks up files written
+// by older versions of the daemon).
+export function parseDayFile(text) {
+  const out = [];
+  const blocks = text.split(/\n(?=## \d{4}-\d{2}-\d{2}T)/);
+  for (const block of blocks) {
+    const m = block.match(/^## (\S+)\s+(\S+)\s+(in|out)\s+(.*?)\n([\s\S]*)$/);
+    if (!m) continue;
+    const ts = m[1];
+    const channel = m[2];
+    const direction = m[3];
+    const author = m[4].trim();
+    let body = m[5];
+    let meta = {};
+    const metaMatch = body.match(/<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/);
+    if (metaMatch) {
+      try { meta = JSON.parse(metaMatch[1]); } catch {}
+      body = body.replace(metaMatch[0], "");
+    }
+    body = body.trim();
+    out.push({
+      ts, channel, direction, author, body, meta,
+      agent_slug: meta.agent,
+      session_id: typeof meta.apc_session_id === "number" ? meta.apc_session_id : null,
+      external_id: meta.external_id,
+    });
+  }
+  return out;
+}
+
+// Pull the recent conversation for a given Telegram chat_id from the messages
+// table. Returns the messages in CHRONOLOGICAL order (oldest first), shaped
+// for use as `previousMessages` to runSuperAgent / callEngine.
+//
+// Filters:
+//   - channel = 'telegram'
+//   - meta_json.chat_id matches chat_id
+//   - ts within `max_age_hours` (default 24)
+//   - up to `limit` rows, taking the most recent
+//
+// `direction='in'` becomes role:"user", `direction='out'` becomes
+// role:"assistant". The current inbound (the one we're answering NOW) is
+// expected to be excluded by the caller — usually by passing a `before` ts
+// or by simply running this query BEFORE the inbound is logged.
+export function getRecentTelegramTurns(
+  db,
+  { chat_id, limit = 12, max_age_hours = 24 }
+) {
+  if (!chat_id) return [];
+  const cutoff = new Date(Date.now() - max_age_hours * 3600_000)
+    .toISOString()
+    .replace(/\.\d{3}Z$/, "Z");
+  const rows = db
+    .prepare(
+      `SELECT direction, body, meta_json, ts FROM messages
+       WHERE channel = 'telegram'
+         AND ts >= ?
+       ORDER BY ts DESC
+       LIMIT ?`
+    )
+    .all(cutoff, limit * 4) // overshoot, then filter by chat_id in JS
+    .filter((r) => {
+      try {
+        const meta = JSON.parse(r.meta_json || "{}");
+        return String(meta.chat_id ?? "") === String(chat_id);
+      } catch {
+        return false;
+      }
+    })
+    .slice(0, limit);
+
+  // We pulled DESC; reverse to get oldest-first for the model.
+  return rows.reverse().map((r) => {
+    const role = r.direction === "in" ? "user" : "assistant";
+    let content = r.body;
+    if (role === "assistant") content = sanitizeAssistantForContext(content);
+    return { role, content };
+  });
+}
+
+// Aggressively redact assistant turns before sending them as context. The
+// problem we're solving: when the model sees its own past answer with
+// concrete factual claims (agent names, model ids, paths, MCPs), it tends
+// to "amplify" them in the next turn — composing a plausible-looking new
+// answer that mixes fragments of the old one with hallucinations. The
+// failure observed with qwen2.5:14b was:
+//
+//   prev assistant: "agente sandbox con modelo ollama:llama3.2:3b"
+//   user: "y en el otro proyecto qué agente tiene?"
+//   assistant (alucinated): "agente assistant con modelo ollama:llama3.2:3b"
+//                           (sofia exists, not "assistant", and her model is
+//                            claude-haiku-4-5, not the carry-over from above)
+//
+// Solution: replace any assistant turn that *looks* like it contains data
+// with a generic "I answered" placeholder. The model loses the cache to
+// copy from but keeps enough hint to track the conversation flow.
+function sanitizeAssistantForContext(content) {
+  if (!content) return "";
+  // Heuristics — if any of these match, the turn likely contains facts
+  // the model should re-derive from tools rather than parrot from cache.
+  const FACTUAL_PATTERNS = [
+    /\b(claude-|gpt-|gemini|llama|qwen|sonnet|haiku|opus|deepseek|kimi|mistral|gemma)\b/i,
+    /\b(ollama:|anthropic:|openai:|gemini:)/i,
+    /\b(role|rol|model|modelo|skills?|habilidades?)\s*[:=]/i,
+    /^- \w+/m,             // bulleted list
+    /\*\*\w+\*\*/,         // bold names
+    /\.(jsonl|md|json|sqlite|db|yaml|toml)\b/i,
+    /\/Users\/|\/Volumes\/|\/home\//i,
+  ];
+  for (const re of FACTUAL_PATTERNS) {
+    if (re.test(content)) {
+      return "(I answered with data here. Re-call the tool to get the current values — do not paraphrase from memory.)";
+    }
+  }
+  // Otherwise it's conversational small-talk; keep up to 200 chars.
+  if (content.length > 200) {
+    return content.slice(0, 200).replace(/\s+/g, " ").trim() + "…";
+  }
+  return content;
+}
+
+// ---------------------------------------------------------------------------
+// File-based project message queries (no SQL required)
+// ---------------------------------------------------------------------------
+
+export function readProjectMessages(projectRoot, { channel, agent_slug, since, limit = 100 } = {}) {
+  const dir = path.join(projectRoot, ".apc", "messages");
+  if (!fs.existsSync(dir)) return [];
+  const all = [];
+  for (const f of fs.readdirSync(dir).sort()) {
+    const full = path.join(dir, f);
+    const text = fs.readFileSync(full, "utf8");
+    let msgs = [];
+    if (/^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)) msgs = parseDayJsonl(text);
+    else if (/^\d{4}-\d{2}-\d{2}\.md$/.test(f)) msgs = parseDayFile(text);
+    for (const m of msgs) {
+      if (channel && m.channel !== channel) continue;
+      if (agent_slug && m.agent_slug !== agent_slug) continue;
+      if (since && m.ts < since) continue;
+      all.push(m);
+    }
+  }
+  all.sort((a, b) => (b.ts || "").localeCompare(a.ts || ""));
+  return all.slice(0, Math.min(limit, 1000));
+}
+
+export function searchProjectMessages(projectRoot, query, limit = 50) {
+  if (!query) return [];
+  const q = query.toLowerCase();
+  const dir = path.join(projectRoot, ".apc", "messages");
+  if (!fs.existsSync(dir)) return [];
+  const all = [];
+  for (const f of fs.readdirSync(dir).sort()) {
+    const full = path.join(dir, f);
+    const text = fs.readFileSync(full, "utf8");
+    let msgs = [];
+    if (/^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)) msgs = parseDayJsonl(text);
+    else if (/^\d{4}-\d{2}-\d{2}\.md$/.test(f)) msgs = parseDayFile(text);
+    for (const m of msgs) {
+      if ((m.body || "").toLowerCase().includes(q)) all.push(m);
+    }
+  }
+  all.sort((a, b) => (b.ts || "").localeCompare(a.ts || ""));
+  return all.slice(0, Math.min(limit, 500));
+}
+
+// File-based Telegram turn history: reads from ~/.apx/messages/telegram/ JSONL.
+// Pass _globalMessagesDir to override the default dir (useful in tests).
+export function getRecentTelegramTurnsFromFs({
+  chat_id,
+  limit = 12,
+  max_age_hours = 24,
+  _globalMessagesDir,
+} = {}) {
+  if (!chat_id) return [];
+  const cutoff = new Date(Date.now() - max_age_hours * 3600_000)
+    .toISOString()
+    .replace(/\.\d{3}Z$/, "Z");
+  const base = _globalMessagesDir || GLOBAL_MESSAGES_DIR;
+  const dir = path.join(base, "telegram");
+  if (!fs.existsSync(dir)) return [];
+  const all = [];
+  for (const f of fs.readdirSync(dir).sort()) {
+    if (!/^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)) continue;
+    const text = fs.readFileSync(path.join(dir, f), "utf8");
+    for (const m of parseDayJsonl(text)) {
+      if (m.ts < cutoff) continue;
+      all.push(m);
+    }
+  }
+  all.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
+  const filtered = all
+    .filter((m) => String(m.meta?.chat_id ?? "") === String(chat_id))
+    .slice(-limit);
+  return filtered.map((m) => {
+    const role = m.direction === "in" ? "user" : "assistant";
+    let content = m.body;
+    if (role === "assistant") content = sanitizeAssistantForContext(content);
+    return { role, content };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Global message store  (~/.apx/messages/<channel>/YYYY-MM-DD.jsonl)
+// ---------------------------------------------------------------------------
+
+// Write a message to the global channel store.  No SQL cache — JSONL only.
+export function appendGlobalMessage({ channel, direction, author, body, meta = {}, ts, agent_slug, external_id }) {
+  ts = ts || nowIso();
+  const dir = path.join(GLOBAL_MESSAGES_DIR, channel);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `${ts.slice(0, 10)}.jsonl`);
+  const fullMeta = {
+    ...(agent_slug ? { agent: agent_slug } : {}),
+    ...(external_id ? { external_id } : {}),
+    ...meta,
+  };
+  const record = {
+    ts,
+    channel,
+    direction,
+    author: author || null,
+    body: body || "",
+    ...(Object.keys(fullMeta).length ? { meta: fullMeta } : {}),
+  };
+  fs.appendFileSync(file, JSON.stringify(record) + "\n");
+  return { ts, file };
+}
+
+// Read recent global channel messages from disk.
+// Returns parsed records sorted oldest-first.
+export function readGlobalMessages({ channel, limit = 100, since } = {}) {
+  const channels = channel
+    ? [channel]
+    : (fs.existsSync(GLOBAL_MESSAGES_DIR) ? fs.readdirSync(GLOBAL_MESSAGES_DIR).filter((f) => {
+        const full = path.join(GLOBAL_MESSAGES_DIR, f);
+        return fs.statSync(full).isDirectory();
+      }) : []);
+
+  const all = [];
+  for (const ch of channels) {
+    const dir = path.join(GLOBAL_MESSAGES_DIR, ch);
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir).sort()) {
+      if (!/^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)) continue;
+      const text = fs.readFileSync(path.join(dir, f), "utf8");
+      for (const m of parseDayJsonl(text)) {
+        if (since && m.ts < since) continue;
+        all.push({ ...m, channel: ch });
+      }
+    }
+  }
+  all.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
+  return all.slice(-limit);
+}
+
+// Wipe the cache and re-populate from .apc/messages/*. Reads BOTH `.jsonl`
+// (current format) and `.md` (legacy). Called by rebuild.
+export function rebuildMessagesFromFs(db, projectRoot) {
+  const dir = path.join(projectRoot, ".apc", "messages");
+  if (!fs.existsSync(dir)) return { count: 0 };
+  db.prepare("DELETE FROM messages").run();
+
+  // Collect every line from every .jsonl + .md, parse, sort by ts so the
+  // SQL row ids end up in the right order.
+  const all = [];
+  for (const f of fs.readdirSync(dir).sort()) {
+    const full = path.join(dir, f);
+    const text = fs.readFileSync(full, "utf8");
+    if (/^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)) {
+      all.push(...parseDayJsonl(text));
+    } else if (/^\d{4}-\d{2}-\d{2}\.md$/.test(f)) {
+      all.push(...parseDayFile(text));
+    }
+  }
+  all.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
+
+  const tx = db.transaction(() => {
+    for (const m of all) insertMessageRow(db, m);
+  });
+  tx();
+  return { count: all.length };
+}