@jossuealcala/madre 0.2.0

package/src/commands.mjs

@@ -0,0 +1,98 @@
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const exists = (path) => access(path).then(() => true, () => false);
+
+// Slash commands the human types in the composer. Some are client-side
+// (/create, /stopall, /image arm things in the UI); these run on the server,
+// read-only, inside the project, and land in the room as a command card so
+// agents and humans share the same facts without spending an agent turn.
+
+async function run(command, args, cwd, timeout = 15000) {
+  try {
+    const { stdout, stderr } = await execFileAsync(command, args, { cwd, timeout, env: { ...process.env, NO_COLOR: '1', GIT_PAGER: 'cat', PAGER: 'cat' }, maxBuffer: 2 * 1024 * 1024 });
+    return { ok: true, text: `${stdout}${stderr ? `\n${stderr}` : ''}`.trim() };
+  } catch (error) {
+    return { ok: false, text: (error.stderr || error.stdout || error.message || '').toString().trim() };
+  }
+}
+
+export const COMMANDS = [
+  {
+    name: 'git',
+    module: 'git-pulse',
+    title: 'Git Pulse',
+    usage: '/git [status|log|diff|branches]',
+    summary: 'Repository status, recent commits, uncommitted changes and branches, read-only, from the project itself.',
+    async available({ projectRoot }) {
+      return exists(join(projectRoot, '.git'));
+    },
+    async execute({ projectRoot, args }) {
+      const what = (args[0] ?? 'status').toLowerCase();
+      const sections = [];
+      const add = async (title, gitArgs) => {
+        const result = await run('git', gitArgs, projectRoot);
+        sections.push(`## ${title}\n${result.text || '(nothing)'}`);
+      };
+      if (what === 'status' || what === 'all') {
+        await add('branch', ['-c', 'color.ui=never', 'status', '-sb']);
+        await add('changes', ['-c', 'color.ui=never', 'status', '--short']);
+        await add('last commits', ['-c', 'color.ui=never', 'log', '--oneline', '--decorate', '-n', '8']);
+      } else if (what === 'log') {
+        await add('last commits', ['-c', 'color.ui=never', 'log', '--oneline', '--decorate', '--stat', '-n', String(Math.min(Number(args[1]) || 10, 50))]);
+      } else if (what === 'diff') {
+        await add('uncommitted diff (stat)', ['-c', 'color.ui=never', 'diff', '--stat']);
+        await add('staged (stat)', ['-c', 'color.ui=never', 'diff', '--cached', '--stat']);
+      } else if (what === 'branches') {
+        await add('branches', ['-c', 'color.ui=never', 'branch', '-avv']);
+      } else {
+        return { ok: false, title: 'Git Pulse', text: `Unknown subcommand "${what}". Use /git status, /git log [n], /git diff or /git branches.` };
+      }
+      return { ok: true, title: `Git Pulse · ${what}`, text: sections.join('\n\n') };
+    },
+  },
+  {
+    name: 'ahp',
+    module: 'ahp',
+    title: 'AHP+',
+    usage: '/ahp [status|check|context]',
+    summary: 'Ask the AHP+ installed in this project for its verified status, checks or session context.',
+    async available({ projectRoot }) {
+      return exists(join(projectRoot, '.ahp', 'manifest.json')) && exists(join(projectRoot, 'node_modules', '.bin', 'ahp'));
+    },
+    async execute({ projectRoot, args }) {
+      const what = (args[0] ?? 'status').toLowerCase();
+      const map = {
+        status: ['project', 'status', '.'],
+        check: ['project', 'check', '.'],
+        context: ['session', 'context', '.', '--format', 'markdown', '--budget', '4000'],
+      };
+      if (!map[what]) return { ok: false, title: 'AHP+', text: `Unknown subcommand "${what}". Use /ahp status, /ahp check or /ahp context.` };
+      const result = await run(join(projectRoot, 'node_modules', '.bin', 'ahp'), map[what], projectRoot, 60000);
+      return { ok: result.ok, title: `AHP+ · ${what}`, text: result.text || '(no output)' };
+    },
+  },
+];
+
+export const commandByName = (name) => COMMANDS.find((command) => command.name === String(name ?? '').toLowerCase()) ?? null;
+
+export async function listCommands({ projectRoot }) {
+  return Promise.all(COMMANDS.map(async (command) => ({
+    name: command.name,
+    module: command.module,
+    title: command.title,
+    usage: command.usage,
+    summary: command.summary,
+    available: await command.available({ projectRoot }),
+  })));
+}
+
+// "/git log 5" → { name: 'git', args: ['log', '5'] }; null when not a command.
+export function parseCommand(text) {
+  const match = String(text ?? '').trim().match(/^\/([a-z][\w-]*)(?:\s+([\s\S]*))?$/i);
+  if (!match) return null;
+  return { name: match[1].toLowerCase(), args: (match[2] ?? '').trim().split(/\s+/).filter(Boolean), raw: match[0] };
+}

package/src/config.mjs

@@ -0,0 +1,59 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+// User preferences that should survive terminals: `~/.pulse/config.json`.
+// Environment variables always win over the file, so a one-off override
+// never has to touch it.
+
+export const configPath = (root = process.env.PULSE_HOME ?? join(homedir(), '.pulse')) => join(root, 'config.json');
+
+export async function loadConfig(root) {
+  try {
+    const parsed = JSON.parse(await readFile(configPath(root), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return {};
+    throw error;
+  }
+}
+
+export async function saveConfig(root, config) {
+  const file = configPath(root);
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  return file;
+}
+
+export async function updateConfig(root, patch) {
+  const current = await loadConfig(root);
+  const next = { ...current, ...patch };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) next[key] = { ...(current[key] ?? {}), ...value };
+  }
+  await saveConfig(root, next);
+  return next;
+}
+
+// Applies file-backed preferences to the process environment without
+// overriding anything the user already exported.
+export function applyConfigToEnv(config, env = process.env) {
+  const applied = {};
+  const set = (name, value) => {
+    if (value === undefined || value === null || value === '' || env[name] !== undefined) return;
+    env[name] = String(value);
+    applied[name] = String(value);
+  };
+  set('PULSE_OPENCODE_MODEL', config.opencode?.model);
+  set('PULSE_SOFT_TOKEN_BUDGET', config.room?.softTokenBudget);
+  set('PULSE_CONTEXT_MAX_CHARS', config.room?.contextMaxChars);
+  set('PULSE_AGENT_TIMEOUT_MS', config.timeouts?.default);
+  if (config.room?.delegation === false) set('PULSE_DELEGATION', '0');
+  set('PULSE_GEMINI_IDLE_MS', config.gemini?.idleMs);
+  set('PULSE_GEMINI_RETRIES', config.gemini?.retries);
+  set('PULSE_MAX_PLAN_STEPS', config.room?.maxPlanSteps);
+  for (const [agent, value] of Object.entries(config.timeouts ?? {})) {
+    if (agent !== 'default') set(`PULSE_${agent.toUpperCase()}_TIMEOUT_MS`, value);
+  }
+  return applied;
+}

package/src/conversation-context.mjs

@@ -0,0 +1,59 @@
+export function messageEntry(event) {
+  if (event.type === 'message.failed') {
+    // Failures are part of the conversation: an orchestrator closing a plan
+    // must know that a step never answered, and why.
+    const { messageId, target, error } = event.payload;
+    if (typeof error !== 'string' || !error.trim()) return null;
+    return { sequence: event.sequence, messageId: `${messageId}:failed`, role: 'failed', sender: target ?? 'room', target: 'you', text: error.trim() };
+  }
+  if (event.type === 'command.output') {
+    const { name, title, text } = event.payload;
+    if (typeof text !== 'string' || !text.trim()) return null;
+    return { sequence: event.sequence, messageId: `${event.id}:command`, role: 'command', sender: `/${name}`, target: 'room', text: `${title}\n${text.trim()}`.slice(0, 6000) };
+  }
+  if (event.type !== 'message.created') return null;
+  const { messageId, role, sender, target, text } = event.payload;
+  if (typeof text !== 'string' || !text.trim()) return null;
+  return { sequence: event.sequence, messageId, role, sender, target, text: text.trim() };
+}
+
+export function buildConversationContext(events, { excludeMessageId, maxChars = 16000 } = {}) {
+  const messages = events
+    .map(messageEntry)
+    .filter((message) => message && message.messageId !== excludeMessageId);
+  const selected = [];
+  let remaining = Math.max(0, Number(maxChars) || 0);
+
+  for (let index = messages.length - 1; index >= 0 && remaining > 0; index -= 1) {
+    const message = messages[index];
+    const label = `${message.sender} (${message.role})`;
+    const allowance = Math.max(0, remaining - label.length - 2);
+    if (!allowance) break;
+    const text = message.text.length > allowance
+      ? allowance <= 3
+        ? '.'.repeat(allowance)
+        : `...${message.text.slice(message.text.length - allowance + 3)}`
+      : message.text;
+    selected.unshift({ ...message, text });
+    remaining -= label.length + text.length + 2;
+  }
+
+  return {
+    messages: selected,
+    omittedMessages: messages.length - selected.length,
+    firstSequence: selected[0]?.sequence ?? null,
+    throughSequence: selected.at(-1)?.sequence ?? null,
+    previousAgent: [...messages].reverse().find((message) => message.role === 'assistant')?.sender ?? null,
+  };
+}
+
+export function formatConversationContext(context) {
+  if (!context.messages.length) return '';
+  const omitted = context.omittedMessages
+    ? `[${context.omittedMessages} earlier message(s) omitted]\n`
+    : '';
+  const transcript = context.messages
+    .map((message) => `${message.sender} (${message.role}): ${message.text}`)
+    .join('\n\n');
+  return `${omitted}${transcript}`;
+}

package/src/directives.mjs

@@ -0,0 +1,70 @@
+// Agent-to-agent delegation. An agent answering in the room may end its reply
+// with a fenced block that puts other agents to work, in order:
+//
+//   ```pulse
+//   @gemini: Synthesize who Jossue is in one paragraph.
+//   @codex: Same question; name the least supported claim.
+//   @claude: Compare both syntheses and mark where they diverge.
+//   ```
+//
+// MADRE runs the steps sequentially as regular room turns, each recorded,
+// each subject to handoff, budget and timeout, and each stoppable by the
+// human. A step addressed to the orchestrator itself becomes its closing
+// turn once the others have answered. Delegated agents cannot delegate
+// further (depth is capped at one), so a plan always terminates.
+
+export const DELEGATION_HELP = (self, others, maxSteps) => [
+  `You may put other agents to work: ${others.map((id) => `@${id}`).join(', ')}.`,
+  'Only do so when the human asked you to coordinate, or when it clearly serves the request.',
+  'To delegate, end your answer with one fenced block, one step per line, in the order they should run:',
+  '```pulse',
+  `@${others[0] ?? 'codex'}: <question for that agent>`,
+  `@${self}: <what you will do with their answers, optional closing turn for you>`,
+  '```',
+  `MADRE runs the steps in order (at most ${maxSteps}), shows every answer in the room, then hands you the closing turn if you asked for one.`,
+  'The plan block must be the very last thing in your reply: nothing after it, not even a closing sentence. Say everything else before it.',
+  'Address each agent once. Do not delegate what you can answer yourself.',
+].join('\n');
+
+// Only a plan block that closes the reply counts. Blocks quoted earlier in
+// the text (examples, explanations) are never executed.
+export function parseDirectives(text, { self, available = [], maxSteps = 4 } = {}) {
+  const source = String(text ?? '');
+  const blocks = [...source.matchAll(/```pulse\s*\n([\s\S]*?)```/gi)];
+  if (!blocks.length) return { steps: [], closing: null, ignored: [] };
+  const last = blocks.at(-1);
+  const trailing = source.slice(last.index + last[0].length);
+  if (trailing.trim()) {
+    return { steps: [], closing: null, ignored: [{ line: '```pulse … ```', reason: 'a plan block must be the last thing in the reply' }] };
+  }
+  const steps = [];
+  const ignored = [];
+  let closing = null;
+  const seen = new Set();
+  for (const block of [last]) {
+    for (const raw of block[1].split('\n')) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const match = line.match(/^[-*]?\s*@([a-z0-9_-]+)\s*[:：]\s*(.+)$/i);
+      if (!match) { ignored.push({ line, reason: 'not a step (expected "@agent: text")' }); continue; }
+      const agent = match[1].toLowerCase();
+      const instruction = match[2].trim();
+      if (agent === self) {
+        if (closing) { ignored.push({ line, reason: 'only one closing step for the orchestrator' }); continue; }
+        closing = instruction;
+        continue;
+      }
+      if (!available.includes(agent)) { ignored.push({ line, reason: `@${agent} is not available in this room` }); continue; }
+      if (seen.has(agent)) { ignored.push({ line, reason: `@${agent} already has a step` }); continue; }
+      if (steps.length >= maxSteps) { ignored.push({ line, reason: `plan is capped at ${maxSteps} steps` }); continue; }
+      seen.add(agent);
+      steps.push({ agent, text: instruction });
+    }
+  }
+  return { steps, closing, ignored };
+}
+
+// The reply text without the plan block, for readers who only want the prose.
+export function stripDirectives(text) {
+  return String(text ?? '').replace(/```pulse\s*\n[\s\S]*?```/gi, '').trim();
+}

package/src/distiller.mjs

@@ -0,0 +1,78 @@
+// The archivist's turn: every so often the cheapest agent in the room reads
+// the exchanges nobody has distilled yet and writes the few notes worth
+// keeping for every later turn. Pure functions here; the room schedules and
+// invokes. Nothing in this file talks to a model.
+
+import { MEMORY_KINDS } from './memory.mjs';
+
+// Cheapest first, by the models these CLIs run by default.
+export const DISTILLER_ORDER = ['gemini', 'opencode', 'codex', 'claude'];
+export const MAX_MEMORIES_PER_RUN = 5;
+export const MAX_MEMORY_CHARS = 240;
+
+// The agent that pays for distillation: the human's pick if it is usable, else
+// the cheapest ready one that has an adapter and no turn in flight.
+export function pickDistiller(agents, { preferred = null, busy = new Set(), invokers = null } = {}) {
+  const usable = (agent) => agent?.detected && agent.ready && !busy.has(agent.id) && (!invokers || Boolean(invokers[agent.adapter]));
+  if (preferred) {
+    const chosen = agents.find((agent) => agent.id === preferred);
+    if (usable(chosen)) return chosen;
+  }
+  for (const id of DISTILLER_ORDER) {
+    const chosen = agents.find((agent) => agent.id === id);
+    if (usable(chosen)) return chosen;
+  }
+  return agents.find(usable) ?? null;
+}
+
+export function distillPrompt({ entries, projectName = 'the project', existing = [] }) {
+  const transcript = entries.map((entry) => {
+    const who = entry.role === 'command' ? entry.sender : `@${entry.sender}`;
+    const to = entry.target && entry.target !== 'room' ? ` → ${entry.target === 'you' ? 'human' : `@${entry.target}`}` : '';
+    return `[#${entry.sequence} · ${who} (${entry.role})${to}] ${entry.text}`;
+  }).join('\n\n');
+  const known = existing.length ? `\nAlready remembered (do not repeat these):\n${existing.map((memory) => `- ${memory.text}`).join('\n')}\n` : '';
+  return [
+    `You are the archivist of a MADRE project room for "${projectName}", shared by a human and several AI agents. Do not read or modify any file: everything you need is below.`,
+    'Read these room exchanges (each stamped with its ledger sequence) and write only the memories worth keeping for future turns of any agent:',
+    `- decision: something the human or the room settled on (what and, briefly, why)`,
+    `- fact: a verified statement about the project or its environment that is not obvious from the code`,
+    `- preference: how the human wants things done or said`,
+    `- question: something left open that a later turn should not forget`,
+    'Skip greetings, restatements, transient status, anything a reader of the code would see anyway, and anything the exchanges do not actually establish.',
+    `Output only JSON lines, one object per memory, at most ${MAX_MEMORIES_PER_RUN}, nothing else:`,
+    `{"kind":"decision|fact|preference|question","text":"one self-contained sentence in the language the room uses, at most ${MAX_MEMORY_CHARS} characters, naming files, agents and numbers exactly","sources":[sequence numbers it comes from]}`,
+    'If nothing durable was said, output exactly: NONE',
+    known,
+    '<exchanges>',
+    transcript,
+    '</exchanges>',
+  ].filter((line) => line !== null && line !== undefined).join('\n');
+}
+
+// Whatever came back, only the well-formed memories survive: known kinds,
+// non-empty text within the limit, sources inside the batch.
+export function parseDistillation(text, { fromSequence, throughSequence } = {}) {
+  const memories = [];
+  const seen = new Set();
+  for (const raw of String(text ?? '').split(/\r?\n/)) {
+    const line = raw.trim().replace(/^```(?:json)?$|^```$/g, '').replace(/^[-*]\s+/, '');
+    const start = line.indexOf('{');
+    const end = line.lastIndexOf('}');
+    if (start < 0 || end <= start) continue;
+    let parsed;
+    try { parsed = JSON.parse(line.slice(start, end + 1)); } catch { continue; }
+    if (!parsed || typeof parsed !== 'object') continue;
+    const memoryText = String(parsed.text ?? '').replace(/\s+/g, ' ').trim();
+    if (!memoryText) continue;
+    const kind = MEMORY_KINDS.includes(parsed.kind) ? parsed.kind : 'fact';
+    const inRange = (n) => Number.isInteger(n) && (fromSequence == null || n >= fromSequence) && (throughSequence == null || n <= throughSequence);
+    const sources = (Array.isArray(parsed.sources) ? parsed.sources : []).map(Number).filter(inRange);
+    const key = memoryText.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    memories.push({ kind, text: memoryText.length > MAX_MEMORY_CHARS ? `${memoryText.slice(0, MAX_MEMORY_CHARS - 1)}…` : memoryText, sources });
+    if (memories.length >= MAX_MEMORIES_PER_RUN) break;
+  }
+  return memories;
+}

package/src/embeddings.mjs

@@ -0,0 +1,80 @@
+// Embeddings for the room memory: meaning-aware recall on top of the lexical
+// index. Gemini's embedding model through the user's own key (the same key
+// Image Studio and the Gemini CLI use); no key, no embeddings, and recall stays
+// lexical. PULSE_EMBED_FAKE=1 swaps in a deterministic local embedder so tests
+// never call Google.
+
+export const DEFAULT_EMBED_MODEL = 'gemini-embedding-001';
+export const DEFAULT_EMBED_DIMS = 768;
+const MAX_TEXT_CHARS = 2000;   // one entry is embedded from its first 2000 characters
+const BATCH = 100;             // batchEmbedContents accepts up to 100 requests
+
+export function cosine(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i += 1) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+  return na && nb ? dot / Math.sqrt(na * nb) : 0;
+}
+
+export function toBlob(vector) { return Buffer.from(Float32Array.from(vector).buffer); }
+export function fromBlob(blob) {
+  const bytes = blob instanceof Uint8Array ? blob : new Uint8Array(blob);
+  return new Float32Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+}
+
+// Hashed word and trigram bag, unit length: stable, local, good enough to test the plumbing.
+export function fakeEmbedding(text, dims = 64) {
+  const vector = new Float32Array(dims);
+  const clean = String(text ?? '').toLowerCase();
+  const hash = (s) => { let h = 2166136261; for (let i = 0; i < s.length; i += 1) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619); } return h >>> 0; };
+  for (const word of clean.split(/[^\p{L}\p{N}]+/u).filter((w) => w.length > 2)) {
+    vector[hash(word) % dims] += 1;
+    for (let i = 0; i + 3 <= word.length; i += 1) vector[hash(word.slice(i, i + 3)) % dims] += 0.35;
+  }
+  let norm = 0;
+  for (const value of vector) norm += value * value;
+  norm = Math.sqrt(norm) || 1;
+  return vector.map((value) => value / norm);
+}
+
+async function geminiEmbed(texts, { key, model, dims, query, fetchImpl, timeoutMs }) {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:batchEmbedContents?key=${encodeURIComponent(key)}`;
+  const out = [];
+  for (let start = 0; start < texts.length; start += BATCH) {
+    const slice = texts.slice(start, start + BATCH);
+    const body = {
+      requests: slice.map((text) => ({
+        model: `models/${model}`,
+        content: { parts: [{ text: String(text ?? '').slice(0, MAX_TEXT_CHARS) || ' ' }] },
+        taskType: query ? 'RETRIEVAL_QUERY' : 'RETRIEVAL_DOCUMENT',
+        outputDimensionality: dims,
+      })),
+    };
+    const response = await fetchImpl(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '');
+      const error = new Error(`Gemini embeddings HTTP ${response.status}${detail ? `: ${detail.slice(0, 200)}` : ''}`);
+      error.status = response.status;
+      throw error;
+    }
+    const payload = await response.json();
+    const vectors = payload?.embeddings ?? [];
+    if (vectors.length !== slice.length) throw new Error(`Gemini embeddings returned ${vectors.length} vectors for ${slice.length} texts.`);
+    for (const item of vectors) out.push(Float32Array.from(item.values ?? []));
+  }
+  return out;
+}
+
+// The embedder the memory uses: { model, dims, embed(texts, { query }) } or null when off.
+export function createEmbedder({ key = null, env = process.env, fetchImpl = globalThis.fetch, timeoutMs = Number(env.PULSE_EMBED_TIMEOUT_MS ?? 8000) } = {}) {
+  if (env.PULSE_EMBED === '0') return null;
+  if (env.PULSE_EMBED_FAKE === '1') {
+    return { model: 'fake-64', dims: 64, embed: async (texts) => texts.map((text) => fakeEmbedding(text)) };
+  }
+  if (!key) return null;
+  const model = env.PULSE_EMBED_MODEL ?? DEFAULT_EMBED_MODEL;
+  const dims = Number(env.PULSE_EMBED_DIMS ?? DEFAULT_EMBED_DIMS);
+  return { model: `${model}@${dims}`, dims, embed: (texts, { query = false } = {}) => geminiEmbed(texts, { key, model, dims, query, fetchImpl, timeoutMs }) };
+}

package/src/event-store.mjs

@@ -0,0 +1,152 @@
+import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+
+export class EventStore {
+  #file;
+  #nextSequence = 1;
+  #writeQueue = Promise.resolve();
+  #lockDirectory;
+
+  constructor(file) {
+    this.#file = file;
+    this.#lockDirectory = `${file}.lock`;
+  }
+
+  async initialize() {
+    await mkdir(dirname(this.#file), { recursive: true });
+    const existing = await this.readAll();
+    this.#nextSequence = (existing.at(-1)?.sequence ?? 0) + 1;
+    return this;
+  }
+
+  async readAll() {
+    const release = await this.#acquireLock();
+    try {
+      return await this.#readAllUnlocked();
+    } finally {
+      await release();
+    }
+  }
+
+  // Reads only the bytes appended after `offset`. Appends are whole lines
+  // written under the lock, so a locked read never sees a partial line; the
+  // trailing-newline guard is defensive. A shrunken file restarts from zero.
+  async tail(offset = 0) {
+    const release = await this.#acquireLock();
+    try {
+      let handle;
+      try {
+        handle = await open(this.#file, 'r');
+      } catch (error) {
+        if (error.code === 'ENOENT') return { events: [], offset: 0 };
+        throw error;
+      }
+      try {
+        const { size } = await handle.stat();
+        const start = size < offset ? 0 : offset;
+        if (size === start) return { events: [], offset: start };
+        const buffer = Buffer.alloc(size - start);
+        await handle.read(buffer, 0, buffer.length, start);
+        let text = buffer.toString('utf8');
+        const lastNewline = text.lastIndexOf('\n');
+        if (lastNewline < 0) return { events: [], offset: start };
+        text = text.slice(0, lastNewline + 1);
+        const events = text.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+        return { events, offset: start + Buffer.byteLength(text, 'utf8') };
+      } finally {
+        await handle.close();
+      }
+    } finally {
+      await release();
+    }
+  }
+
+  async #readAllUnlocked() {
+    try {
+      const text = await readFile(this.#file, 'utf8');
+      return text.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+    } catch (error) {
+      if (error.code === 'ENOENT') return [];
+      throw error;
+    }
+  }
+
+  async #acquireLock() {
+    const token = randomUUID();
+    const ownerFile = join(this.#lockDirectory, 'owner.json');
+    for (let attempt = 0; attempt < 500; attempt += 1) {
+      let created = false;
+      try {
+        await mkdir(this.#lockDirectory);
+        created = true;
+        await writeFile(ownerFile, JSON.stringify({ pid: process.pid, token }));
+        return async () => {
+          try {
+            const owner = JSON.parse(await readFile(ownerFile, 'utf8'));
+            if (owner.token === token) await rm(this.#lockDirectory, { recursive: true, force: true });
+          } catch (error) {
+            if (error.code !== 'ENOENT') throw error;
+          }
+        };
+      } catch (error) {
+        if (created) {
+          await rm(this.#lockDirectory, { recursive: true, force: true });
+          throw error;
+        }
+        if (error.code !== 'EEXIST') throw error;
+        try {
+          const owner = JSON.parse(await readFile(ownerFile, 'utf8'));
+          try {
+            process.kill(owner.pid, 0);
+          } catch (ownerError) {
+            if (ownerError.code === 'ESRCH') {
+              await rm(this.#lockDirectory, { recursive: true, force: true });
+              continue;
+            }
+          }
+        } catch (ownerError) {
+          if (ownerError.code !== 'ENOENT' && !(ownerError instanceof SyntaxError)) throw ownerError;
+          const lock = await stat(this.#lockDirectory).catch(() => null);
+          if (lock && Date.now() - lock.mtimeMs > 10000) {
+            await rm(this.#lockDirectory, { recursive: true, force: true });
+            continue;
+          }
+        }
+        await delay(20);
+      }
+    }
+    throw new Error(`Timed out waiting for event store lock: ${this.#file}`);
+  }
+
+  append(type, payload) {
+    const operation = async () => {
+      const release = await this.#acquireLock();
+      try {
+        const existing = await this.#readAllUnlocked();
+        const sequence = (existing.at(-1)?.sequence ?? 0) + 1;
+        const event = {
+          id: randomUUID(),
+          sequence,
+          type,
+          timestamp: new Date().toISOString(),
+          payload,
+        };
+        const handle = await open(this.#file, 'a');
+        try {
+          await handle.writeFile(`${JSON.stringify(event)}\n`);
+          await handle.sync();
+        } finally {
+          await handle.close();
+        }
+        this.#nextSequence = sequence + 1;
+        return event;
+      } finally {
+        await release();
+      }
+    };
+    this.#writeQueue = this.#writeQueue.then(operation, operation);
+    return this.#writeQueue;
+  }
+}