dw-kit 1.4.0 → 1.7.0-rc.1

package/src/lib/active-index.mjs

@@ -12,7 +12,13 @@ function parseFrontmatter(content) {
   const fm = {};
   for (const line of lines) {
     const kv = line.match(/^(\w+):\s*(.+)$/);
-    if (kv) fm[kv[1]] = kv[2].trim();
+    if (kv) {
+      let value = kv[2].trim();
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      fm[kv[1]] = value;
+    }
   }
   return fm;
 }
@@ -21,6 +27,18 @@ function readTaskStatus(taskDir) {
   const fullPath = join(TASKS_DIR, taskDir);
   if (!statSync(fullPath).isDirectory()) return null;
 
+  const timelineV3 = join(fullPath, 'task.md');
+  if (existsSync(timelineV3)) {
+    const fm = parseFrontmatter(readFileSync(timelineV3, 'utf8'));
+    return {
+      name: taskDir,
+      status: fm.status || 'unknown',
+      lastUpdated: fm.last_updated || fm.created || '—',
+      blockers: fm.blockers || 'none',
+      format: 'v3',
+    };
+  }
+
   const trackingV2 = join(fullPath, 'tracking.md');
   if (existsSync(trackingV2)) {
     const fm = parseFrontmatter(readFileSync(trackingV2, 'utf8'));

package/src/lib/agent-claim.mjs

@@ -0,0 +1,173 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlinkSync, renameSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+
+const CLAIMS_DIR = '.dw/cache/agents/claims';
+const SCHEMA_PATH = '.dw/core/schemas/agent-claim.schema.json';
+const BUNDLED_SCHEMA = join(__dirname, '..', '..', '.dw', 'core', 'schemas', 'agent-claim.schema.json');
+
+export function claimsDir(rootDir = process.cwd()) {
+  return join(rootDir, CLAIMS_DIR);
+}
+
+function loadSchema(rootDir) {
+  const local = join(rootDir, SCHEMA_PATH);
+  if (existsSync(local)) return JSON.parse(readFileSync(local, 'utf8'));
+  if (existsSync(BUNDLED_SCHEMA)) return JSON.parse(readFileSync(BUNDLED_SCHEMA, 'utf8'));
+  return null;
+}
+
+const validatorCache = new Map();
+function getValidator(rootDir) {
+  // Reviewer Warning #1: key by rootDir so programmatic use across multiple repos
+  // doesn't lock the first-seen schema permanently.
+  if (validatorCache.has(rootDir)) return validatorCache.get(rootDir);
+  let Ajv;
+  try { Ajv = require('ajv'); } catch { return null; }
+  const ctor = Ajv.default || Ajv;
+  const ajv = new ctor({ strict: false, allErrors: true });
+  const schema = loadSchema(rootDir);
+  if (!schema) return null;
+  const v = ajv.compile(schema);
+  validatorCache.set(rootDir, v);
+  return v;
+}
+
+export function validateClaim(claim, rootDir = process.cwd()) {
+  const validate = getValidator(rootDir);
+  if (!validate) return { ok: true, warnings: ['ajv or schema not available — skipped validation'] };
+  const valid = validate(claim);
+  return {
+    ok: valid,
+    errors: valid ? [] : (validate.errors || []).map((e) => ({
+      path: e.instancePath || '/',
+      message: e.message || 'invalid',
+      params: e.params,
+    })),
+  };
+}
+
+export function nowIsoUtc() {
+  return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+export function generateClaimId(taskId, subtasks) {
+  const stamp = nowIsoUtc().replace(/[-:]/g, '').replace('T', 'T').replace('Z', 'Z');
+  const subSlug = subtasks.map((s) => s.toLowerCase()).join('-') || 'task';
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `${taskId}-${subSlug}-${stamp}-${rand}`;
+}
+
+export function createClaim({ taskId, agent, subtasks, writeScope = [], readScope = [], leaseSeconds = 3600, worktreePath = null }, rootDir = process.cwd()) {
+  const created = nowIsoUtc();
+  const expires = new Date(Date.now() + leaseSeconds * 1000).toISOString().replace(/\.\d+Z$/, 'Z');
+  const claim = {
+    schema_version: 'agent-claim@v1',
+    claim_id: generateClaimId(taskId, subtasks),
+    task_id: taskId,
+    agent,
+    subtasks,
+    write_scope: writeScope,
+    read_scope: readScope,
+    lease_expires: expires,
+    lease_duration_seconds: leaseSeconds,
+    status: 'created',
+    created_at: created,
+  };
+  if (worktreePath) claim.worktree_path = worktreePath;
+  return claim;
+}
+
+export function persistClaim(claim, rootDir = process.cwd()) {
+  const dir = claimsDir(rootDir);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const target = join(dir, `${claim.claim_id}.json`);
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, JSON.stringify(claim, null, 2) + '\n', 'utf8');
+  renameSync(tmp, target);
+  return target;
+}
+
+export function loadClaim(claimId, rootDir = process.cwd()) {
+  const file = join(claimsDir(rootDir), `${claimId}.json`);
+  if (!existsSync(file)) return null;
+  try { return JSON.parse(readFileSync(file, 'utf8')); }
+  catch { return null; }
+}
+
+export function listClaims(rootDir = process.cwd(), { taskId, status, includeStale = false } = {}) {
+  const dir = claimsDir(rootDir);
+  if (!existsSync(dir)) return [];
+  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  const out = [];
+  const now = Date.now();
+  for (const f of files) {
+    try {
+      const c = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+      if (taskId && c.task_id !== taskId) continue;
+      const effectiveExpiry = computeEffectiveExpiry(c);
+      const isExpired = effectiveExpiry < now && c.status !== 'released' && c.status !== 'expired' && c.status !== 'invalidated';
+      const liveStatus = isExpired ? 'expired' : c.status;
+      if (status && liveStatus !== status) continue;
+      if (!includeStale && (c.status === 'released' || c.status === 'invalidated')) continue;
+      out.push({ ...c, _live_status: liveStatus, _file: join(dir, f) });
+    } catch { /* skip malformed */ }
+  }
+  out.sort((a, b) => a.created_at.localeCompare(b.created_at));
+  return out;
+}
+
+export function computeEffectiveExpiry(claim) {
+  // Both fields must be present + parseable; malformed silently expiring is a footgun
+  // (reviewer Warning #2). Return Infinity (= always active) when both are unusable
+  // so the claim doesn't disappear from listings without warning; caller surfaces it.
+  const wallRaw = Date.parse(claim.lease_expires);
+  const createdRaw = Date.parse(claim.created_at);
+  const wallClock = Number.isFinite(wallRaw) ? wallRaw : null;
+  const created = Number.isFinite(createdRaw) ? createdRaw : null;
+  const relative = created != null && Number.isFinite(claim.lease_duration_seconds)
+    ? created + claim.lease_duration_seconds * 1000
+    : null;
+  if (wallClock == null && relative == null) {
+    return Number.POSITIVE_INFINITY;
+  }
+  return Math.max(wallClock ?? -Infinity, relative ?? -Infinity);
+}
+
+export function transitionClaim(claimId, newStatus, opts = {}, rootDir = process.cwd()) {
+  const claim = loadClaim(claimId, rootDir);
+  if (!claim) return { ok: false, reason: 'not-found' };
+  // Lifecycle per ADR-0009 R2-1: created can also expire (agent crashed before
+  // activation; lease elapsed before any edit). Terminal states are immutable.
+  const allowed = {
+    created: ['active', 'released', 'expired', 'invalidated'],
+    active: ['released', 'expired', 'invalidated'],
+    released: [],
+    expired: [],
+    invalidated: [],
+  };
+  if (!(allowed[claim.status] || []).includes(newStatus)) {
+    return { ok: false, reason: `invalid-transition: ${claim.status}→${newStatus}` };
+  }
+  claim.status = newStatus;
+  const ts = nowIsoUtc();
+  if (newStatus === 'active' && !claim.activated_at) claim.activated_at = ts;
+  if (['released', 'expired', 'invalidated'].includes(newStatus)) {
+    claim.released_at = ts;
+    if (opts.reason) claim.release_reason = opts.reason;
+  }
+  persistClaim(claim, rootDir);
+  return { ok: true, claim };
+}
+
+export function deleteClaim(claimId, rootDir = process.cwd()) {
+  const file = join(claimsDir(rootDir), `${claimId}.json`);
+  if (!existsSync(file)) return false;
+  unlinkSync(file);
+  return true;
+}

package/src/lib/agent-conflict.mjs

@@ -0,0 +1,137 @@
+import { listClaims, loadClaim, computeEffectiveExpiry } from './agent-claim.mjs';
+
+// Glob → RegExp following gitignore-style semantics:
+//   `**`     matches zero-or-more path segments (including empty)
+//   `*`      matches anything within a segment (no `/`)
+//   `?`      matches single char (no `/`)
+// Behaviour validated by reviewer Critical #1: src/**/*.js MUST match src/x.js.
+export function globToRegex(glob) {
+  let pattern = '';
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        // `**` — zero or more path segments. Greedy match across `/`.
+        // Variants: `**/`, `/**`, mid-path `/**/`, or bare `**`.
+        if (glob[i + 2] === '/') {
+          // `**/foo` → match zero-or-more segments-with-trailing-slash, then foo
+          pattern += '(?:.*\\/)?';
+          i += 2;
+        } else if (i > 0 && glob[i - 1] === '/') {
+          // `/foo/**` at end → zero or more trailing segments (optionally with leading slash).
+          // `/` is not in the escape set (we emit it as literal), so drop 1 char not 2.
+          pattern = pattern.slice(0, -1);
+          pattern += '(?:\\/.*)?';
+          i += 1;
+        } else {
+          pattern += '.*';
+          i += 1;
+        }
+      } else {
+        pattern += '[^/]*';
+      }
+    } else if (ch === '?') {
+      pattern += '[^/]';
+    } else if ('.+^${}()|[]\\'.indexOf(ch) >= 0) {
+      pattern += '\\' + ch;
+    } else {
+      pattern += ch;
+    }
+  }
+  return new RegExp(`^${pattern}$`);
+}
+
+export function pathMatchesScope(path, scope) {
+  for (const pattern of scope) {
+    if (globToRegex(pattern).test(path)) return true;
+  }
+  return false;
+}
+
+// Two globs/paths overlap if there exists a concrete path matching both.
+// We approximate by:
+//   - exact string equality
+//   - exact path matches a glob in the other set
+//   - both contain wildcards: try a small biased sample set at depths 0/1/2
+export function scopesOverlap(a, b) {
+  if (a === b) return true;
+  const aHasGlob = /[*?]/.test(a);
+  const bHasGlob = /[*?]/.test(b);
+  const ra = globToRegex(a);
+  const rb = globToRegex(b);
+
+  // Concrete path vs glob: test the concrete one against the glob, both ways.
+  if (!aHasGlob && bHasGlob) return rb.test(a);
+  if (aHasGlob && !bHasGlob) return ra.test(b);
+
+  // Both globs — synthesise candidate concrete paths and test against both.
+  const samples = new Set();
+  for (const g of [a, b]) {
+    samples.add(g.replace(/\*\*\//g, '').replace(/\*\*/g, '').replace(/\*/g, 'X').replace(/\?/g, 'Y'));
+    samples.add(g.replace(/\*\*\//g, 'd/').replace(/\*\*/g, 'd').replace(/\*/g, 'X').replace(/\?/g, 'Y'));
+    samples.add(g.replace(/\*\*\//g, 'd/e/').replace(/\*\*/g, 'd/e').replace(/\*/g, 'X').replace(/\?/g, 'Y'));
+  }
+  for (const s of samples) {
+    if (ra.test(s) && rb.test(s)) return true;
+  }
+  return false;
+}
+
+export function detectClaimOverlaps(rootDir = process.cwd(), { taskId, includeAllTasks = false } = {}) {
+  // Per reviewer Warning 3: write_scope overlaps must be detected globally
+  // (cross-task), even when caller scoped to a single task.
+  const taskScoped = taskId ? listClaims(rootDir, { taskId }) : listClaims(rootDir);
+  const repoWide = includeAllTasks || !taskId ? listClaims(rootDir) : null;
+
+  const active = (taskScoped).filter((c) => {
+    const ls = c._live_status;
+    return ls === 'created' || ls === 'active';
+  });
+  const activeRepoWide = repoWide
+    ? repoWide.filter((c) => c._live_status === 'created' || c._live_status === 'active')
+    : active;
+
+  const conflicts = [];
+  const seen = new Set();
+  for (let i = 0; i < active.length; i++) {
+    for (let j = 0; j < activeRepoWide.length; j++) {
+      const a = active[i];
+      const b = activeRepoWide[j];
+      if (a.claim_id === b.claim_id) continue;
+      const key = [a.claim_id, b.claim_id].sort().join('::');
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      // Subtask overlap only meaningful within same task
+      const subtaskOverlap = a.task_id === b.task_id
+        ? a.subtasks.filter((s) => b.subtasks.includes(s))
+        : [];
+      const writeOverlap = [];
+      for (const pa of a.write_scope) {
+        for (const pb of b.write_scope) {
+          if (scopesOverlap(pa, pb)) writeOverlap.push({ a: pa, b: pb });
+        }
+      }
+
+      if (subtaskOverlap.length || writeOverlap.length) {
+        conflicts.push({
+          claim_a: a.claim_id,
+          agent_a: a.agent.id,
+          claim_b: b.claim_id,
+          agent_b: b.agent.id,
+          task_id: a.task_id === b.task_id ? a.task_id : `${a.task_id},${b.task_id}`,
+          subtask_overlap: subtaskOverlap,
+          write_overlap: writeOverlap,
+        });
+      }
+    }
+  }
+  return conflicts;
+}
+
+export function detectOutOfScopeEdits(claimId, editedFiles, rootDir = process.cwd()) {
+  const claim = loadClaim(claimId, rootDir);
+  if (!claim) return { ok: false, reason: 'claim-not-found' };
+  const outside = editedFiles.filter((f) => !pathMatchesScope(f, claim.write_scope));
+  return { ok: true, outside, total_edits: editedFiles.length };
+}

package/src/lib/agent-events.mjs

@@ -0,0 +1,43 @@
+import { appendFileSync, existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const TASKS_DIR = '.dw/tasks';
+const MAX_EVENT_BYTES = 4096;
+
+export function eventsFile(taskId, rootDir = process.cwd()) {
+  return join(rootDir, TASKS_DIR, taskId, 'events.jsonl');
+}
+
+export function logAgentEvent(taskId, event, rootDir = process.cwd()) {
+  const file = eventsFile(taskId, rootDir);
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const enriched = {
+    ts: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+    ...event,
+  };
+  let line = JSON.stringify(enriched) + '\n';
+  const originalBytes = Buffer.byteLength(line, 'utf8');
+  if (originalBytes > MAX_EVENT_BYTES) {
+    const trimmed = { ts: enriched.ts, event: enriched.event || 'unknown', _truncated: true, _original_size_bytes: originalBytes };
+    line = JSON.stringify(trimmed) + '\n';
+  }
+  try {
+    appendFileSync(file, line, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readEvents(taskId, rootDir = process.cwd()) {
+  const file = eventsFile(taskId, rootDir);
+  if (!existsSync(file)) return [];
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  const out = [];
+  for (const line of lines) {
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+  }
+  return out;
+}

package/src/lib/agent-report.mjs

@@ -0,0 +1,96 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import yaml from 'js-yaml';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+
+const TASKS_DIR = '.dw/tasks';
+const SCHEMA_PATH = '.dw/core/schemas/agent-report.schema.json';
+const BUNDLED_SCHEMA = join(__dirname, '..', '..', '.dw', 'core', 'schemas', 'agent-report.schema.json');
+
+export function reportsDir(taskId, rootDir = process.cwd()) {
+  return join(rootDir, TASKS_DIR, taskId, 'reports');
+}
+
+function loadSchema(rootDir) {
+  const local = join(rootDir, SCHEMA_PATH);
+  if (existsSync(local)) return JSON.parse(readFileSync(local, 'utf8'));
+  if (existsSync(BUNDLED_SCHEMA)) return JSON.parse(readFileSync(BUNDLED_SCHEMA, 'utf8'));
+  return null;
+}
+
+const validatorCache = new Map();
+function getValidator(rootDir) {
+  if (validatorCache.has(rootDir)) return validatorCache.get(rootDir);
+  let Ajv;
+  try { Ajv = require('ajv'); } catch { return null; }
+  const ctor = Ajv.default || Ajv;
+  const ajv = new ctor({ strict: false, allErrors: true });
+  const schema = loadSchema(rootDir);
+  if (!schema) return null;
+  const v = ajv.compile(schema);
+  validatorCache.set(rootDir, v);
+  return v;
+}
+
+export function parseReport(filePath) {
+  if (!existsSync(filePath)) return null;
+  const raw = readFileSync(filePath, 'utf8');
+  const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!fmMatch) return { frontmatter: {}, body: raw, _file: filePath };
+  let fm = {};
+  try { fm = yaml.load(fmMatch[1], { schema: yaml.CORE_SCHEMA }) || {}; }
+  catch { /* malformed yaml */ }
+  return { frontmatter: fm, body: raw.slice(fmMatch[0].length), _file: filePath };
+}
+
+export function validateReportFrontmatter(fm, rootDir = process.cwd()) {
+  const validate = getValidator(rootDir);
+  if (!validate) return { ok: true, warnings: ['ajv or schema not available'] };
+  const valid = validate(fm);
+  return {
+    ok: valid,
+    errors: valid ? [] : (validate.errors || []).map((e) => ({ path: e.instancePath || '/', message: e.message })),
+  };
+}
+
+export function listReports(rootDir = process.cwd(), { taskId, agentId } = {}) {
+  const tasksRoot = join(rootDir, TASKS_DIR);
+  if (!existsSync(tasksRoot)) return [];
+  const taskFolders = taskId
+    ? [taskId]
+    : readdirSync(tasksRoot).filter((e) => {
+        try { return statSync(join(tasksRoot, e)).isDirectory() && e !== 'archive'; }
+        catch { return false; }
+      });
+
+  const out = [];
+  for (const t of taskFolders) {
+    const dir = reportsDir(t, rootDir);
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+      const parsed = parseReport(join(dir, f));
+      if (!parsed) continue;
+      if (agentId && parsed.frontmatter.agent_id !== agentId) continue;
+      out.push({ ...parsed.frontmatter, _file: parsed._file, _task: t });
+    }
+  }
+  out.sort((a, b) => (b.created_at || '').localeCompare(a.created_at || ''));
+  return out;
+}
+
+export function writeReport(taskId, frontmatter, body, rootDir = process.cwd()) {
+  const dir = reportsDir(taskId, rootDir);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const ts = (frontmatter.created_at || new Date().toISOString().replace(/\.\d+Z$/, 'Z')).replace(/[-:]/g, '');
+  const filename = `${frontmatter.agent_id || 'agent'}-${ts}.md`;
+  const target = join(dir, filename);
+  const fmYaml = yaml.dump(frontmatter, { schema: yaml.CORE_SCHEMA, lineWidth: 100 });
+  const content = `---\n${fmYaml}---\n\n${body || ''}`;
+  writeFileSync(target, content, 'utf8');
+  return target;
+}

package/src/lib/frontmatter.mjs

@@ -0,0 +1,72 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import yaml from 'js-yaml';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+
+const SCHEMA_PATH = join(__dirname, '..', '..', '.dw', 'core', 'schemas', 'task-frontmatter.schema.json');
+
+export const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+export function extractFrontmatterBlock(content) {
+  const m = content.match(FRONTMATTER_RE);
+  if (!m) return { raw: '', body: content, hasFrontmatter: false };
+  return {
+    raw: m[1],
+    body: content.slice(m[0].length),
+    hasFrontmatter: true,
+  };
+}
+
+export function parseFrontmatter(content) {
+  const { raw, hasFrontmatter } = extractFrontmatterBlock(content);
+  if (!hasFrontmatter) return {};
+  try {
+    return yaml.load(raw, { schema: yaml.CORE_SCHEMA }) || {};
+  } catch {
+    return {};
+  }
+}
+
+export function stringifyFrontmatter(obj) {
+  const body = yaml.dump(obj, {
+    schema: yaml.CORE_SCHEMA,
+    lineWidth: 100,
+    noRefs: true,
+    quotingType: '"',
+    forceQuotes: false,
+  });
+  return `---\n${body}---\n`;
+}
+
+export function loadSchema(rootDir = process.cwd()) {
+  const local = join(rootDir, '.dw', 'core', 'schemas', 'task-frontmatter.schema.json');
+  if (existsSync(local)) return JSON.parse(readFileSync(local, 'utf8'));
+  if (existsSync(SCHEMA_PATH)) return JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+  return null;
+}
+
+export function validateFrontmatter(fm, schema) {
+  let Ajv;
+  try {
+    Ajv = require('ajv');
+  } catch {
+    return { ok: true, warnings: ['ajv not available — skipping schema validation'] };
+  }
+  const ajv = new Ajv.default ? new Ajv.default({ strict: false, allErrors: true }) : new Ajv({ strict: false, allErrors: true });
+  const validate = ajv.compile(schema);
+  const valid = validate(fm);
+  return {
+    ok: valid,
+    errors: valid ? [] : (validate.errors || []).map((e) => ({
+      path: e.instancePath || '/',
+      message: e.message || 'invalid',
+      keyword: e.keyword,
+      params: e.params,
+    })),
+  };
+}

package/src/lib/goal-events.mjs

@@ -0,0 +1,79 @@
+import { appendFileSync, existsSync, readFileSync, mkdirSync, statSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const EVENTS_FILE_RELATIVE = '.dw/events-global.jsonl';
+const MAX_EVENT_BYTES = 4096;
+const ROTATE_BYTES = 500 * 1024;     // C-4: 500KB
+const ROTATE_LINES = 5000;            // C-4: 5000 lines
+
+export function eventsGlobalFile(rootDir = process.cwd()) {
+  return join(rootDir, EVENTS_FILE_RELATIVE);
+}
+
+function shouldRotate(file) {
+  if (!existsSync(file)) return false;
+  const st = statSync(file);
+  if (st.size >= ROTATE_BYTES) return true;
+  let lines = 0;
+  const content = readFileSync(file, 'utf8');
+  for (let i = 0; i < content.length; i++) {
+    if (content.charCodeAt(i) === 10) lines++;
+    if (lines >= ROTATE_LINES) return true;
+  }
+  return false;
+}
+
+function rotateIfNeeded(file) {
+  if (!shouldRotate(file)) return;
+  const now = new Date();
+  const yyyy = now.getUTCFullYear();
+  const mm = String(now.getUTCMonth() + 1).padStart(2, '0');
+  const archive = file.replace(/events-global\.jsonl$/, `events-global-${yyyy}${mm}.jsonl`);
+  if (existsSync(archive)) {
+    const existing = readFileSync(file, 'utf8');
+    appendFileSync(archive, existing, 'utf8');
+    try {
+      const { unlinkSync } = require('node:fs');
+      unlinkSync(file);
+    } catch { /* best-effort */ }
+  } else {
+    renameSync(file, archive);
+  }
+}
+
+export function logGoalEvent(event, rootDir = process.cwd()) {
+  const file = eventsGlobalFile(rootDir);
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  rotateIfNeeded(file);
+
+  const enriched = {
+    ts: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+    ...event,
+  };
+  let line = JSON.stringify(enriched) + '\n';
+  const originalBytes = Buffer.byteLength(line, 'utf8');
+  if (originalBytes > MAX_EVENT_BYTES) {
+    const trimmed = { ts: enriched.ts, event: enriched.event || 'unknown', _truncated: true, _original_size_bytes: originalBytes };
+    line = JSON.stringify(trimmed) + '\n';
+  }
+  try {
+    appendFileSync(file, line, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readGoalEvents(rootDir = process.cwd(), { limit = 100, offset = 0 } = {}) {
+  const file = eventsGlobalFile(rootDir);
+  if (!existsSync(file)) return [];
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  const sliced = lines.slice(Math.max(0, lines.length - offset - limit), lines.length - offset);
+  const out = [];
+  for (const line of sliced) {
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+  }
+  return out;
+}