@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/scripts/enforce-pbr-workflow.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+/**
+ * PBR workflow enforcement checks.
+ *
+ * Provides advisory and blocking checks that ensure PBR workflow is
+ * followed even when the user doesn't explicitly invoke /pbr:* commands.
+ *
+ * Functions:
+ *   loadEnforcementConfig(planningDir) — reads config.json for enforcement level
+ *   checkUnmanagedSourceWrite(data)    — PreToolUse Write|Edit: warns/blocks unmanaged source writes
+ *   checkNonPbrAgent(data)             — PreToolUse Task: advises using pbr:* agents
+ *   checkUnmanagedCommit(data)         — PreToolUse Bash: advises git commits to use /pbr:quick
+ *
+ * All functions return null for pass, or { exitCode, output } for action.
+ * checkNonPbrAgent defaults to blocking (exitCode 2) — blocks non-PBR agents.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { resolveSessionPath } = require('./lib/core');
+
+/**
+ * Load the enforcement configuration from .planning/config.json.
+ * Also checks for .planning/.native-mode which bypasses all enforcement.
+ *
+ * @param {string} planningDir - absolute path to the .planning directory
+ * @returns {{ level: "advisory"|"block"|"off" }}
+ */
+function loadEnforcementConfig(planningDir) {
+  // .native-mode bypass takes precedence over all config settings
+  const nativeModeFile = path.join(planningDir, '.native-mode');
+  if (fs.existsSync(nativeModeFile)) {
+    return { level: 'off' };
+  }
+
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const level = parsed.workflow && parsed.workflow.enforce_pbr_skills;
+    if (level === 'advisory' || level === 'block' || level === 'off') {
+      return { level };
+    }
+  } catch (_e) {
+    // No config or parse error — use default
+  }
+
+  return { level: 'advisory' };
+}
+
+/**
+ * PreToolUse Write|Edit: warns or blocks source file writes that happen
+ * without an active PBR skill.
+ *
+ * Skip conditions:
+ *   - No .planning/ directory (not a PBR project)
+ *   - .planning/.active-skill exists (PBR skill is managing the session)
+ *   - Target file is inside .planning/ (planning files are always OK)
+ *   - Enforcement level is "off"
+ *
+ * @param {Object} data - parsed hook input from Claude Code
+ * @returns {null|{ exitCode: number, output: Object }}
+ */
+function checkUnmanagedSourceWrite(data) {
+  const filePath = data.tool_input && (data.tool_input.file_path || data.tool_input.path);
+  if (!filePath) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Skip if not a PBR project
+  if (!fs.existsSync(planningDir)) return null;
+
+  // Skip if a PBR skill is active — session-scoped when session_id available
+  const { sessionLoad } = require('./lib/core');
+  const sessionId = data.session_id || null;
+  let activeSkill = sessionLoad(planningDir, sessionId).activeSkill || '';
+  if (!activeSkill) {
+    const skillPath = sessionId
+      ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+      : path.join(planningDir, '.active-skill');
+    try { activeSkill = fs.readFileSync(skillPath, 'utf8').trim(); } catch (_) { /* file missing */ }
+  }
+  if (activeSkill) return null;
+
+  // Skip if writing inside .planning/
+  const normalizedFile = filePath.replace(/\\/g, '/');
+  const normalizedPlanning = planningDir.replace(/\\/g, '/');
+  if (normalizedFile.startsWith(normalizedPlanning)) return null;
+
+  // Also check with resolved symlinks (macOS /var → /private/var)
+  try {
+    const resolvedPlanning = fs.realpathSync(planningDir).replace(/\\/g, '/');
+    if (normalizedFile.startsWith(resolvedPlanning)) return null;
+  } catch (_e) { /* not resolvable */ }
+
+  const config = loadEnforcementConfig(planningDir);
+  if (config.level === 'off') return null;
+
+  const message =
+    'PBR workflow required: You are editing source code without an active PBR skill. ' +
+    'Route this work through a PBR command: /pbr:quick (small fix), /pbr:execute-phase (planned work), ' +
+    'or /pbr:do (auto-route). Set workflow.enforce_pbr_skills: off in config to disable.';
+
+  if (config.level === 'block') {
+    logHook('enforce-pbr-workflow', 'PreToolUse', 'block', { file: path.basename(filePath), level: 'block' });
+    return {
+      exitCode: 2,
+      output: { decision: 'block', reason: message }
+    };
+  }
+
+  // advisory (default)
+  logHook('enforce-pbr-workflow', 'PreToolUse', 'advisory', { file: path.basename(filePath), level: 'advisory' });
+  return {
+    exitCode: 0,
+    output: { additionalContext: '[pbr] ' + message }
+  };
+}
+
+/**
+ * Agent type → PBR agent mapping for advisory messages.
+ */
+const AGENT_MAPPING = {
+  'Explore': 'pbr:researcher or pbr:codebase-mapper',
+  'general-purpose': 'pbr:general',
+  'Plan': 'pbr:planner',
+  'Bash': 'pbr:executor'
+};
+
+/**
+ * PreToolUse Task: advises using pbr:* agents instead of generic agents.
+ *
+ * Skip conditions:
+ *   - No .planning/ directory (not a PBR project)
+ *   - subagent_type starts with "pbr:" (already using PBR agent)
+ *   - subagent_type is missing/empty (can't determine type)
+ *   - Enforcement level is "off"
+ *
+ * Defaults to **blocking** (exitCode 2) unless config overrides to "advisory".
+ * This is stricter than checkUnmanagedSourceWrite/checkUnmanagedCommit because
+ * non-PBR agents bypass audit logging, workflow context, and project-aware prompts.
+ *
+ * @param {Object} data - parsed hook input from Claude Code
+ * @returns {null|{ exitCode: number, output: Object }}
+ */
+function checkNonPbrAgent(data) {
+  const subagentType = data.tool_input && data.tool_input.subagent_type;
+  if (!subagentType || typeof subagentType !== 'string') return null;
+
+  // Already using a PBR agent
+  if (subagentType.startsWith('pbr:')) return null;
+
+  // Per-call bypass: user says "use native agents" and the LLM includes [native] in description
+  const description = (data.tool_input && data.tool_input.description) || '';
+  if (/\[native\]/i.test(description)) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Skip if not a PBR project
+  if (!fs.existsSync(planningDir)) return null;
+
+  const config = loadEnforcementConfig(planningDir);
+  if (config.level === 'off') return null;
+
+  // For agent enforcement, determine the effective level.
+  // Priority: workflow.enforce_pbr_agents > workflow.enforce_pbr_skills > default "block"
+  // Agent enforcement is stricter than source write/commit checks — blocks by default.
+  let agentLevel = 'block'; // default: block non-PBR agents
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const agentExplicit = parsed.workflow && parsed.workflow.enforce_pbr_agents;
+    const skillExplicit = parsed.workflow && parsed.workflow.enforce_pbr_skills;
+    if (agentExplicit === 'advisory' || agentExplicit === 'block' || agentExplicit === 'off') {
+      agentLevel = agentExplicit;
+    } else if (skillExplicit === 'advisory' || skillExplicit === 'block' || skillExplicit === 'off') {
+      agentLevel = skillExplicit;
+    }
+  } catch (_e) {
+    // No config — keep default (block)
+  }
+
+  if (agentLevel === 'off') return null;
+
+  const suggestion = AGENT_MAPPING[subagentType] || 'a pbr:* agent (e.g., pbr:researcher, pbr:general, pbr:executor)';
+
+  // Block non-PBR agents unless explicitly set to advisory
+  if (agentLevel !== 'advisory') {
+    const blockMessage =
+      `PBR workflow violation: spawning generic agent "${subagentType}" is blocked. ` +
+      `Use ${suggestion} instead. ` +
+      'PBR agents are auto-loaded via subagent_type — just change the type, no extra setup needed. ' +
+      'If the user explicitly requested a native agent, add [native] to the Task description to bypass this check.';
+
+    logHook('enforce-pbr-workflow', 'PreToolUse', 'block', { agentType: subagentType, suggestion });
+    return {
+      exitCode: 2,
+      output: { decision: 'block', reason: '[pbr] ' + blockMessage }
+    };
+  }
+
+  // advisory (default)
+  const message =
+    `PBR workflow advisory: spawning generic agent "${subagentType}" without PBR routing. ` +
+    `Use ${suggestion} instead to maintain audit logging and workflow context. ` +
+    'PBR agents are auto-loaded via subagent_type — no extra setup needed.';
+
+  logHook('enforce-pbr-workflow', 'PreToolUse', 'advisory', { agentType: subagentType, suggestion });
+  return {
+    exitCode: 0,
+    output: { additionalContext: '[pbr] ' + message }
+  };
+}
+
+/**
+ * PreToolUse Bash: advises using /pbr:quick when git commit is run without
+ * an active PBR skill.
+ *
+ * Skip conditions:
+ *   - No .planning/ directory (not a PBR project)
+ *   - .planning/.active-skill exists (PBR skill is managing the session)
+ *   - Command is not a git commit
+ *   - Enforcement level is "off"
+ *
+ * @param {Object} data - parsed hook input from Claude Code
+ * @returns {null|{ exitCode: 0, output: Object }}
+ */
+function checkUnmanagedCommit(data) {
+  const command = data.tool_input && data.tool_input.command;
+  if (!command || typeof command !== 'string') return null;
+
+  // Only check git commit commands
+  if (!/\bgit\s+commit\b/.test(command)) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Skip if not a PBR project
+  if (!fs.existsSync(planningDir)) return null;
+
+  // Skip if a PBR skill is active — session-scoped when session_id available
+  const { sessionLoad } = require('./lib/core');
+  const sessionIdCommit = data.session_id || null;
+  let activeSkillCommit = sessionLoad(planningDir, sessionIdCommit).activeSkill || '';
+  if (!activeSkillCommit) {
+    const skillPath = sessionIdCommit
+      ? resolveSessionPath(planningDir, '.active-skill', sessionIdCommit)
+      : path.join(planningDir, '.active-skill');
+    try { activeSkillCommit = fs.readFileSync(skillPath, 'utf8').trim(); } catch (_) { /* file missing */ }
+  }
+  if (activeSkillCommit) return null;
+
+  const config = loadEnforcementConfig(planningDir);
+  if (config.level === 'off') return null;
+
+  const message =
+    'Committing without PBR tracking. Use /pbr:quick to track this work. ' +
+    'PBR quick tasks create atomic commits with proper scope and audit trail.';
+
+  logHook('enforce-pbr-workflow', 'PreToolUse', 'advisory', { check: 'unmanaged-commit' });
+  return {
+    exitCode: 0,
+    output: { additionalContext: '[pbr] ' + message }
+  };
+}
+
+module.exports = {
+  loadEnforcementConfig,
+  checkUnmanagedSourceWrite,
+  checkNonPbrAgent,
+  checkUnmanagedCommit
+};

package/plugins/pbr/scripts/event-handler.js

@@ -14,15 +14,16 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
-// configLoad not used here to avoid mtime-based cache issues across directories.
-// Config is read directly in shouldAutoVerify().
+const { incrementTracker } = require('./session-tracker');
+const { shouldAutoVerify, getPhaseFromState, writeAutoVerifySignal, isMultiRoundActive, isTrustTrackingEnabled } = require('./lib/auto-verify');
+const { handleDecisionExtraction, extractDecisions } = require('./lib/decision-extraction');
 
 function readStdin() {
   try {
     const input = fs.readFileSync(0, 'utf8').trim();
     if (input) return JSON.parse(input);
   } catch (_e) {
-    // empty or non-JSON stdin
+    // Intentional silence: stdin may be empty or non-JSON, this is expected
   }
   return {};
 }
@@ -38,125 +39,174 @@ function isExecutorAgent(data) {
 }
 
 /**
- * Determine whether auto-verification should run based on config.
- * @param {string} planningDir - Path to .planning directory
+ * Check if the stdin data represents a verifier agent completion.
+ * @param {object} data - Parsed stdin JSON from SubagentStop event
  * @returns {boolean}
  */
-function shouldAutoVerify(planningDir) {
-  // Read config directly instead of using configLoad to avoid mtime-based
-  // cache issues when called repeatedly with different planning directories.
-  const configPath = path.join(planningDir, 'config.json');
-  let config;
-  try {
-    if (!fs.existsSync(configPath)) return false;
-    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-  } catch (_e) {
-    return false;
-  }
-  if (config === null) return false;
-
-  // Check explicit goal_verification toggle
-  if (config.features && config.features.goal_verification === false) return false;
-
-  // Check depth profile
-  const depth = (config.depth || 'standard').toLowerCase();
-  if (depth === 'quick') return false;
+function isVerifierAgent(data) {
+  const agentType = data.agent_type || data.subagent_type || null;
+  return agentType === 'pbr:verifier';
+}
 
-  // "standard", "comprehensive", and any other depth default to true
-  return true;
+/**
+ * Build verify hint from executor output for downstream context.
+ * @param {string} lastMsg - last_assistant_message from agent output
+ * @returns {string}
+ */
+function buildVerifyHint(lastMsg) {
+  if (!lastMsg) return '';
+  const lowerMsg = lastMsg.toLowerCase();
+  if (lowerMsg.includes('error') || lowerMsg.includes('failed') || lowerMsg.includes('warning')) {
+    return ' Note: executor output mentions errors/warnings — verification should pay close attention.';
+  }
+  return '';
 }
 
 /**
- * Parse current phase info from STATE.md.
+ * Core logic for handling executor completion and auto-verify queueing.
+ * Shared between main() (stdin mode) and handleHttp (server mode).
+ * @param {object} data - Parsed event data
  * @param {string} planningDir - Path to .planning directory
- * @returns {{ phase: number, total: number, status: string } | null}
+ * @returns {{ additionalContext: string }|null}
  */
-function getPhaseFromState(planningDir) {
-  const statePath = path.join(planningDir, 'STATE.md');
-  try {
-    if (!fs.existsSync(statePath)) return null;
-    const content = fs.readFileSync(statePath, 'utf8');
+function processExecutorCompletion(data, planningDir) {
+  const agentType = data.agent_type || data.subagent_type || '';
 
-    const phaseMatch = content.match(/Phase:\s*(\d+)\s+of\s+(\d+)/);
-    if (!phaseMatch) return null;
+  logHook('event-handler', 'SubagentStop', 'executor-complete', { agent_type: agentType });
+  logEvent('workflow', 'executor-complete', { agent_type: agentType });
 
-    const statusMatch = content.match(/\*{0,2}(?:Phase\s+)?Status\*{0,2}:\s*["']?(\w+)["']?/i);
-    const status = statusMatch ? statusMatch[1] : null;
+  if (!planningDir || !fs.existsSync(planningDir)) return null;
 
-    return {
-      phase: parseInt(phaseMatch[1], 10),
-      total: parseInt(phaseMatch[2], 10),
-      status: status
-    };
-  } catch (_e) {
+  const stateInfo = getPhaseFromState(planningDir);
+  if (!stateInfo || stateInfo.status !== 'building') {
+    logHook('event-handler', 'SubagentStop', 'skip-verify', {
+      reason: stateInfo ? `status=${stateInfo.status}` : 'no-state'
+    });
+    return null;
+  }
+
+  // Increment session phase counter (before auto-verify gate)
+  try {
+    incrementTracker(planningDir);
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'increment-tracker-error', { error: e.message });
+  }
+
+  if (!shouldAutoVerify(planningDir)) {
+    logHook('event-handler', 'SubagentStop', 'skip-verify', { reason: 'config/depth' });
     return null;
   }
+
+  // Multi-round QA: suppress inter-round auto-verify signal
+  // The build skill manages the QA loop — event handler should not
+  // trigger independent verification between rounds.
+  if (isMultiRoundActive(planningDir)) {
+    logHook('event-handler', 'SubagentStop', 'multi-round-active',
+      { message: 'Suppressing auto-verify signal — build skill manages QA rounds' });
+    return null;
+  }
+
+  writeAutoVerifySignal(planningDir, stateInfo.phase);
+
+  const verifyHint = buildVerifyHint(data.last_assistant_message || '');
+  return {
+    additionalContext: `Executor complete. Auto-verification queued for Phase ${stateInfo.phase}.${verifyHint}`
+  };
 }
 
 /**
- * Write signal file for orchestrator to pick up and spawn verifier.
- * @param {string} planningDir - Path to .planning directory
- * @param {number} phaseNumber - Current phase number
+ * Handle verifier agent completion — log trust-update-queued.
+ * @param {object} data - Parsed event data
+ * @param {string|null} planningDir - Path to .planning directory
  */
-function writeAutoVerifySignal(planningDir, phaseNumber) {
-  const signalPath = path.join(planningDir, '.auto-verify');
-  const payload = {
-    phase: phaseNumber,
-    timestamp: new Date().toISOString()
-  };
-  fs.writeFileSync(signalPath, JSON.stringify(payload, null, 2), 'utf8');
+function processVerifierCompletion(data, planningDir) {
+  const agentType = data.agent_type || data.subagent_type;
+  logHook('event-handler', 'SubagentStop', 'verifier-complete', { agent_type: agentType });
+  logEvent('workflow', 'verifier-complete', { agent_type: agentType });
+
+  if (planningDir && fs.existsSync(planningDir) && isTrustTrackingEnabled(planningDir)) {
+    logEvent(planningDir, 'trust-update-queued', { agent: 'pbr:verifier' });
+  }
 }
 
-function main() {
-  const data = readStdin();
+/**
+ * Handle decision extraction for any agent type.
+ * @param {object} data - Parsed event data
+ * @param {string} planningDir - Path to .planning directory
+ */
+function processDecisionExtraction(data, planningDir) {
+  const agentType = data.agent_type || data.subagent_type || '';
+  if (!agentType || !planningDir || !fs.existsSync(planningDir)) return;
 
-  // Only handle executor agent completions
-  if (!isExecutorAgent(data)) {
-    process.exit(0);
+  const agentOutput = data.output || data.stdout || data.last_assistant_message || '';
+  try {
+    handleDecisionExtraction(planningDir, agentOutput, agentType.replace('pbr:', ''));
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'decision-extraction-error', { error: e.message });
   }
+}
 
-  const agentType = data.agent_type || data.subagent_type;
+function main() {
+  const data = readStdin();
+  const planningDir = path.join(process.cwd(), '.planning');
 
-  logHook('event-handler', 'SubagentStop', 'executor-complete', { agent_type: agentType });
-  logEvent('workflow', 'executor-complete', { agent_type: agentType });
+  // Decision extraction runs for ALL agent types (not just executor)
+  processDecisionExtraction(data, planningDir);
 
-  const planningDir = path.join(process.cwd(), '.planning');
-  if (!fs.existsSync(planningDir)) {
+  // Handle verifier agent completions — log trust-update-queued
+  if (isVerifierAgent(data)) {
+    processVerifierCompletion(data, planningDir);
     process.exit(0);
   }
 
-  if (!shouldAutoVerify(planningDir)) {
-    logHook('event-handler', 'SubagentStop', 'skip-verify', { reason: 'config/depth' });
+  // Only handle executor agent completions for auto-verify
+  if (!isExecutorAgent(data)) {
     process.exit(0);
   }
 
-  const stateInfo = getPhaseFromState(planningDir);
-  if (!stateInfo || stateInfo.status !== 'building') {
-    logHook('event-handler', 'SubagentStop', 'skip-verify', {
-      reason: stateInfo ? `status=${stateInfo.status}` : 'no-state'
-    });
-    process.exit(0);
+  const result = processExecutorCompletion(data, planningDir);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
   }
+  process.exit(0);
+}
 
-  writeAutoVerifySignal(planningDir, stateInfo.phase);
+/**
+ * HTTP handler for hook-server.js integration.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, ... }.
+ * Must NOT call process.exit().
+ * @param {{ data: object, planningDir: string }} reqBody
+ * @returns {{ additionalContext: string }|null}
+ */
+function handleHttp(reqBody) {
+  const data = reqBody.data || {};
+  const planningDir = reqBody.planningDir;
 
-  // Extract last_assistant_message for verification context hints
-  const lastMsg = data.last_assistant_message || '';
-  let verifyHint = '';
-  if (lastMsg) {
-    // Look for error/failure indicators that might inform verification priority
-    const lowerMsg = lastMsg.toLowerCase();
-    if (lowerMsg.includes('error') || lowerMsg.includes('failed') || lowerMsg.includes('warning')) {
-      verifyHint = ' Note: executor output mentions errors/warnings — verification should pay close attention.';
-    }
+  // Decision extraction runs for ALL agent types
+  processDecisionExtraction(data, planningDir);
+
+  // Handle verifier completions — log trust-update-queued
+  if (isVerifierAgent(data)) {
+    processVerifierCompletion(data, planningDir);
+    return null;
   }
 
-  const output = {
-    additionalContext: `Executor complete. Auto-verification queued for Phase ${stateInfo.phase}.${verifyHint}`
-  };
-  process.stdout.write(JSON.stringify(output));
-  process.exit(0);
+  if (!isExecutorAgent(data)) return null;
+
+  return processExecutorCompletion(data, planningDir);
 }
 
-module.exports = { isExecutorAgent, shouldAutoVerify, getPhaseFromState };
+module.exports = {
+  isExecutorAgent,
+  isVerifierAgent,
+  shouldAutoVerify,
+  getPhaseFromState,
+  handleHttp,
+  extractDecisions,
+  handleDecisionExtraction,
+  // New exports for internal use
+  writeAutoVerifySignal,
+  isMultiRoundActive,
+  isTrustTrackingEnabled,
+};
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/event-logger.js

@@ -10,25 +10,53 @@
  * Usage as CLI:
  *   node event-logger.js <category> <event> [JSON-details]
  *
- * Log file: .planning/logs/events.jsonl
- * Format: One JSON line per entry (JSONL)
- * Rotation: Keeps last 1000 entries max
+ * Log files: .planning/logs/events-YYYY-MM-DD.jsonl (one file per day, no size cap)
+ * Format: One JSON line per entry (JSONL), append-only
+ * Retention: Old daily files are cleaned up after MAX_DAYS days by session-cleanup.js
  */
 
 const fs = require('fs');
 const path = require('path');
 
-const MAX_ENTRIES = 1000;
+const MAX_DAYS = 30;
 
-function getLogPath() {
-  const cwd = process.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  if (!fs.existsSync(planningDir)) return null;
-  const logsDir = path.join(planningDir, 'logs');
+/** Return today's date string as YYYY-MM-DD (local time). */
+function getTodayDate() {
+  const d = new Date();
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+/** Return the log filename for a given date (defaults to today). */
+function getLogFilename(date) {
+  return `events-${date || getTodayDate()}.jsonl`;
+}
+
+/** Return the full path to the events log for a given date (defaults to today). */
+function getLogPath(date) {
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const logsDir = path.join(cwd, '.planning', 'logs');
+  // Auto-create .planning/logs/ if needed.
   if (!fs.existsSync(logsDir)) {
     fs.mkdirSync(logsDir, { recursive: true });
   }
-  return path.join(logsDir, 'events.jsonl');
+
+  // One-time migration: rename legacy events.jsonl to yesterday's dated file.
+  const legacyPath = path.join(logsDir, 'events.jsonl');
+  if (fs.existsSync(legacyPath)) {
+    const yesterday = new Date(Date.now() - 86400000);
+    const yDate = `${yesterday.getFullYear()}-${String(yesterday.getMonth() + 1).padStart(2, '0')}-${String(yesterday.getDate()).padStart(2, '0')}`;
+    const migratedPath = path.join(logsDir, `events-${yDate}.jsonl`);
+    if (!fs.existsSync(migratedPath)) {
+      try { fs.renameSync(legacyPath, migratedPath); } catch (_e) { /* best-effort */ }
+    } else {
+      try { fs.unlinkSync(legacyPath); } catch (_e) { /* best-effort */ }
+    }
+  }
+
+  return path.join(logsDir, getLogFilename(date));
 }
 
 function logEvent(category, event, details = {}) {
@@ -43,23 +71,28 @@ function logEvent(category, event, details = {}) {
   };
 
   try {
-    let lines = [];
-    if (fs.existsSync(logPath)) {
-      const content = fs.readFileSync(logPath, 'utf8').trim();
-      if (content) {
-        lines = content.split('\n');
-      }
-    }
-
-    lines.push(JSON.stringify(entry));
+    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
+  } catch (_e) {
+    // Best-effort logging — never fail the caller
+  }
+}
 
-    if (lines.length > MAX_ENTRIES) {
-      lines = lines.slice(lines.length - MAX_ENTRIES);
+/**
+ * Delete events-*.jsonl files older than MAX_DAYS days.
+ * Called by session-cleanup.js at session end.
+ */
+function cleanOldEventLogs(logsDir) {
+  try {
+    const cutoff = Date.now() - MAX_DAYS * 86400000;
+    const files = fs.readdirSync(logsDir);
+    for (const file of files) {
+      if (!/^events-\d{4}-\d{2}-\d{2}\.jsonl$/.test(file)) continue;
+      const filePath = path.join(logsDir, file);
+      const stat = fs.statSync(filePath);
+      if (stat.mtimeMs < cutoff) fs.unlinkSync(filePath);
     }
-
-    fs.writeFileSync(logPath, lines.join('\n') + '\n', 'utf8');
   } catch (_e) {
-    // Best-effort logging — never fail the caller
+    // Best-effort cleanup — never fail the caller
   }
 }
 
@@ -89,4 +122,4 @@ function main() {
 }
 
 if (require.main === module || process.argv[1] === __filename) { main(); }
-module.exports = { logEvent };
+module.exports = { logEvent, getLogPath, getLogFilename, cleanOldEventLogs };