@phnx-labs/agents-cli 1.22.11 → 1.22.13

package/dist/lib/events.js

@@ -1,8 +1,8 @@
 /**
  * Centralized event logging for agents-cli.
  *
- * Structured JSONL audit log at ~/.agents/.history/events/events.jsonl with lossless numbered
- * gzip rotation at 10 MB and rich metadata for debugging/auditing.
+ * Structured JSONL audit logs at ~/.agents/.history/events/YYYY-MM-DD/events.jsonl with
+ * lossless numbered gzip rotation at 10 MiB and bounded retention.
  *
  * Features:
  * - Rich metadata: hostname, platform, arch, pid, timezone
@@ -17,7 +17,7 @@ import * as os from 'os';
 import { createHash } from 'node:crypto';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { ensureLockTarget, withFileLock } from './fs-atomic.js';
-import { getHistoryDir } from './state.js';
+import { getUserAgentsDir } from './state.js';
 import { stampProvenance, resetEventProvenanceForTest } from './event-provenance.js';
 /** Lazy perf warehouse write — avoids a hard cycle at module load. */
 function recordPerfTiming(payload) {
@@ -47,14 +47,42 @@ function recordPerfTiming(payload) {
 // unlike _resetForTest it survives a bare reset AND propagates to CLI subprocesses
 // a test spawns, so fixture events can never land in the user's real log (#910).
 let _eventsPath;
-function eventsPath() {
-    return (_eventsPath ??= process.env.AGENTS_EVENTS_PATH || path.join(getHistoryDir(), 'events', 'events.jsonl'));
+let _eventsPathOverride = false;
+let _legacyMigrationChecked = false;
+let _userAgentsDirOverride;
+function userAgentsDir() {
+    return _userAgentsDirOverride ?? getUserAgentsDir();
 }
-function eventsDir() {
-    return path.dirname(eventsPath());
+function localDateKey(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+function eventsRoot() {
+    if (_eventsPathOverride && _eventsPath)
+        return path.dirname(_eventsPath);
+    return path.join(userAgentsDir(), '.history', 'events');
+}
+function eventsPath(date = new Date()) {
+    if (_eventsPathOverride && _eventsPath)
+        return _eventsPath;
+    const override = _userAgentsDirOverride ? undefined : process.env.AGENTS_EVENTS_PATH;
+    if (override) {
+        _eventsPathOverride = true;
+        return (_eventsPath = override);
+    }
+    return path.join(eventsRoot(), localDateKey(date), 'events.jsonl');
+}
+function eventsDir(date = new Date()) {
+    return path.dirname(eventsPath(date));
 }
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 7;
+/** Default total footprint for the active log plus gzip archives (50 MiB). */
+const DEFAULT_MAX_STORAGE_BYTES = 50 * 1024 * 1024;
+/** Cross-process marker used to avoid a full archive scan on every append. */
+const PRUNE_MARKER = '.last-prune';
 /** Default max length for truncated strings. */
 const DEFAULT_TRUNCATE_LENGTH = 500;
 /** Gzip rotation threshold in bytes (10 MB). */
@@ -154,6 +182,8 @@ function getTimezoneName() {
     }
 }
 function ensureLogsDir() {
+    eventsPath(); // Resolve an explicit AGENTS_EVENTS_PATH before migration checks.
+    migrateLegacyEventLogs();
     if (!fs.existsSync(eventsDir())) {
         fs.mkdirSync(eventsDir(), { recursive: true, mode: DIR_MODE });
     }
@@ -167,6 +197,102 @@ function ensureLogsDir() {
         }
     }
 }
+/**
+ * Move root-level and interim flat-history event families into dated directories.
+ *
+ * The common case is a whole-family rename into an empty destination. A
+ * Each segment is assigned to the local calendar day of its filesystem mtime;
+ * new writes are split by day at source. A partially completed migration keeps
+ * the destination active file authoritative and assigns a fresh archive number,
+ * so no record is overwritten or silently discarded. The legacy active-file
+ * lock serializes this with older installed processes that still append there.
+ */
+export function migrateLegacyEventLogs(userDir = userAgentsDir()) {
+    if (_eventsPathOverride || _legacyMigrationChecked)
+        return 0;
+    _legacyMigrationChecked = true;
+    const destinationRoot = path.join(userDir, '.history', 'events');
+    const legacyActive = path.join(userDir, 'events.jsonl');
+    const interimActive = path.join(destinationRoot, 'events.jsonl');
+    const listArchives = (dir) => {
+        try {
+            return fs.readdirSync(dir)
+                .map((file) => ({ file, match: file.match(/^events\.(\d+)\.jsonl\.gz$/) }))
+                .filter((entry) => entry.match !== null)
+                .map((entry) => ({ file: entry.file, number: Number(entry.match[1]) }))
+                .sort((a, b) => a.number - b.number);
+        }
+        catch {
+            return [];
+        }
+    };
+    const hasSourceFiles = fs.existsSync(legacyActive) || fs.existsSync(interimActive) ||
+        listArchives(userDir).length > 0 || listArchives(destinationRoot).length > 0;
+    if (!hasSourceFiles)
+        return 0;
+    try {
+        fs.mkdirSync(destinationRoot, { recursive: true, mode: DIR_MODE });
+        ensureLockTarget(legacyActive, '', DIR_MODE);
+        return withFileLock(legacyActive, () => {
+            ensureLockTarget(interimActive, '', DIR_MODE);
+            return withFileLock(interimActive, () => {
+                const sourceFamilies = [
+                    { dir: userDir, active: legacyActive, archives: listArchives(userDir) },
+                    { dir: destinationRoot, active: interimActive, archives: listArchives(destinationRoot) },
+                ];
+                let moved = 0;
+                const nextArchiveNumber = (dir) => {
+                    const numbers = fs.readdirSync(dir)
+                        .map((file) => file.match(/^events\.(\d+)\.jsonl\.gz$/))
+                        .filter((match) => match !== null)
+                        .map((match) => Number(match[1]));
+                    return (numbers.length ? Math.max(...numbers) : 0) + 1;
+                };
+                const withDestinationLock = (dayDir, fn) => {
+                    const destinationActive = path.join(dayDir, 'events.jsonl');
+                    fs.mkdirSync(dayDir, { recursive: true, mode: DIR_MODE });
+                    ensureLockTarget(destinationActive, '', DIR_MODE);
+                    return withFileLock(destinationActive, fn);
+                };
+                for (const family of sourceFamilies) {
+                    const activeBytes = fs.existsSync(family.active) ? fs.statSync(family.active).size : 0;
+                    if (activeBytes > 0) {
+                        const activeStat = fs.statSync(family.active);
+                        const dayDir = path.join(destinationRoot, localDateKey(activeStat.mtime));
+                        withDestinationLock(dayDir, () => {
+                            const archivePath = path.join(dayDir, `events.${nextArchiveNumber(dayDir)}.jsonl.gz`);
+                            fs.writeFileSync(archivePath, gzipSync(fs.readFileSync(family.active)), { mode: FILE_MODE });
+                            fs.utimesSync(archivePath, activeStat.atime, activeStat.mtime);
+                            fs.truncateSync(family.active, 0);
+                        });
+                        moved++;
+                    }
+                    for (const archive of family.archives) {
+                        const source = path.join(family.dir, archive.file);
+                        const dayDir = path.join(destinationRoot, localDateKey(fs.statSync(source).mtime));
+                        withDestinationLock(dayDir, () => {
+                            const destination = path.join(dayDir, `events.${nextArchiveNumber(dayDir)}.jsonl.gz`);
+                            fs.renameSync(source, destination);
+                        });
+                        moved++;
+                    }
+                    try {
+                        if (fs.existsSync(family.active) && fs.statSync(family.active).size === 0)
+                            fs.unlinkSync(family.active);
+                    }
+                    catch { /* an older process may have reopened it */ }
+                }
+                return moved;
+            });
+        });
+    }
+    catch {
+        // Audit logging must remain fail-soft. Files stay at the legacy path and a
+        // later process retries because this guard is process-local.
+        _legacyMigrationChecked = false;
+        return 0;
+    }
+}
 // ─── Redaction ────────────────────────────────────────────────────────────────
 /**
  * Replace a prompt string with length + short SHA so we can correlate runs
@@ -380,7 +506,8 @@ export function emit(event, payload = {}, overrides = {}) {
                     // May fail if not owner
                 }
             }
-            maybeGzipRotateLocked(logPath);
+            const rotated = maybeGzipRotateLocked(logPath);
+            maybePruneLocked(rotated);
         });
     }
     catch {
@@ -657,7 +784,7 @@ export function emitFriction(surface, failureId, payload = {}) {
 function maybeGzipRotateLocked(logPath) {
     const stat = fs.statSync(logPath);
     if (stat.size < GZIP_ROTATION_BYTES)
-        return;
+        return false;
     const raw = fs.readFileSync(logPath);
     const tmpArchive = path.join(eventsDir(), `.events.1.jsonl.gz.${process.pid}.tmp`);
     fs.writeFileSync(tmpArchive, gzipSync(raw), { mode: FILE_MODE });
@@ -672,6 +799,7 @@ function maybeGzipRotateLocked(logPath) {
         }
         fs.renameSync(tmpArchive, path.join(eventsDir(), 'events.1.jsonl.gz'));
         fs.truncateSync(logPath, 0);
+        return true;
     }
     catch (err) {
         try {
@@ -681,45 +809,179 @@ function maybeGzipRotateLocked(logPath) {
         throw err;
     }
 }
-// ─── Rotation ─────────────────────────────────────────────────────────────────
-/**
- * Remove log files older than the retention period.
- * Removes numbered gzip archives whose filesystem mtime exceeds retention.
- *
- * @param retentionDays - Number of days to keep (default 7, from DEFAULT_RETENTION_DAYS)
- * @returns Number of files removed
- */
-export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
-    try {
-        if (!fs.existsSync(eventsDir()))
-            return 0;
-        const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
-        const files = fs.readdirSync(eventsDir()).filter(f => /^events\.\d+\.jsonl\.gz$/.test(f));
-        let removed = 0;
-        for (const file of files) {
-            const filePath = path.join(eventsDir(), file);
-            if (fs.statSync(filePath).mtimeMs < cutoff) {
-                fs.unlinkSync(filePath);
-                removed++;
+function listEventLogFiles() {
+    const current = eventsPath();
+    const files = [];
+    const addFile = (filePath, gzip) => {
+        try {
+            const stat = fs.statSync(filePath);
+            files.push({
+                path: filePath,
+                gzip,
+                currentActive: filePath === current,
+                mtimeMs: stat.mtimeMs,
+                size: stat.size,
+            });
+        }
+        catch { /* file may rotate while an unlocked reader enumerates */ }
+    };
+    const addDirectory = (dir) => {
+        let names = [];
+        try {
+            names = fs.readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name !== 'events.jsonl' && !/^events\.\d+\.jsonl\.gz$/.test(name))
+                continue;
+            addFile(path.join(dir, name), name.endsWith('.gz'));
+        }
+    };
+    if (_eventsPathOverride) {
+        if (path.basename(current) !== 'events.jsonl') {
+            addFile(current, false);
+            let names = [];
+            try {
+                names = fs.readdirSync(eventsDir());
+            }
+            catch {
+                return files;
+            }
+            for (const name of names) {
+                if (/^events\.\d+\.jsonl\.gz$/.test(name))
+                    addFile(path.join(eventsDir(), name), true);
             }
+            return files;
         }
-        return removed;
+        addDirectory(eventsDir());
+        return files;
+    }
+    let days = [];
+    try {
+        days = fs.readdirSync(eventsRoot()).filter((name) => /^\d{4}-\d{2}-\d{2}$/.test(name));
     }
     catch {
-        return 0;
+        return files;
     }
+    for (const day of days)
+        addDirectory(path.join(eventsRoot(), day));
+    return files;
 }
-/**
- * Lazy rotation - runs at most once per day per process.
- */
-let lastRotationCheck = 0;
-export function maybeRotate() {
-    const now = Date.now();
+function removeEmptyDayDirectories() {
+    if (_eventsPathOverride)
+        return;
+    let days = [];
+    try {
+        days = fs.readdirSync(eventsRoot()).filter((name) => /^\d{4}-\d{2}-\d{2}$/.test(name));
+    }
+    catch {
+        return;
+    }
+    for (const day of days) {
+        const dir = path.join(eventsRoot(), day);
+        try {
+            if (fs.readdirSync(dir).length === 0)
+                fs.rmdirSync(dir);
+        }
+        catch { /* best effort */ }
+    }
+}
+function finalizePastDayLogs() {
+    if (_eventsPathOverride)
+        return;
+    const currentDay = localDateKey();
+    for (const file of listEventLogFiles()) {
+        if (path.basename(file.path) !== 'events.jsonl')
+            continue;
+        if (path.basename(path.dirname(file.path)) === currentDay)
+            continue;
+        try {
+            withFileLock(file.path, () => {
+                const dir = path.dirname(file.path);
+                const numbers = fs.readdirSync(dir)
+                    .map((name) => name.match(/^events\.(\d+)\.jsonl\.gz$/))
+                    .filter((match) => match !== null)
+                    .map((match) => Number(match[1]));
+                const next = (numbers.length ? Math.max(...numbers) : 0) + 1;
+                const target = path.join(dir, `events.${next}.jsonl.gz`);
+                const sourceStat = fs.statSync(file.path);
+                fs.writeFileSync(target, gzipSync(fs.readFileSync(file.path)), { mode: FILE_MODE });
+                fs.utimesSync(target, sourceStat.atime, sourceStat.mtime);
+                fs.unlinkSync(file.path);
+            });
+        }
+        catch { /* retry on the next prune */ }
+    }
+}
+function pruneEventLogsLocked(retentionDays = DEFAULT_RETENTION_DAYS, maxStorageBytes = DEFAULT_MAX_STORAGE_BYTES) {
+    finalizePastDayLogs();
+    const result = { removedByAge: 0, removedBySize: 0, bytesReclaimed: 0 };
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    let files = listEventLogFiles();
+    for (const file of files) {
+        if (file.currentActive || file.mtimeMs >= cutoff)
+            continue;
+        try {
+            fs.unlinkSync(file.path);
+            result.removedByAge++;
+            result.bytesReclaimed += file.size;
+        }
+        catch { /* another process may already have removed it */ }
+    }
+    files = listEventLogFiles();
+    let totalBytes = files.reduce((sum, file) => sum + file.size, 0);
+    const oldestFirst = files
+        .filter((file) => !file.currentActive)
+        .sort((a, b) => a.mtimeMs - b.mtimeMs || a.path.localeCompare(b.path));
+    for (const file of oldestFirst) {
+        if (totalBytes <= maxStorageBytes)
+            break;
+        try {
+            fs.unlinkSync(file.path);
+            totalBytes -= file.size;
+            result.removedBySize++;
+            result.bytesReclaimed += file.size;
+        }
+        catch { /* another process may already have removed it */ }
+    }
+    removeEmptyDayDirectories();
+    return result;
+}
+/** Apply age retention and the total-size ceiling immediately. */
+export function rotate(retentionDays = DEFAULT_RETENTION_DAYS, maxStorageBytes = DEFAULT_MAX_STORAGE_BYTES) {
+    try {
+        ensureLogsDir();
+        const active = eventsPath();
+        ensureLockTarget(active, '', DIR_MODE);
+        return withFileLock(active, () => pruneEventLogsLocked(retentionDays, maxStorageBytes));
+    }
+    catch {
+        return { removedByAge: 0, removedBySize: 0, bytesReclaimed: 0 };
+    }
+}
+/** Prune daily across processes, and immediately after a size rotation. */
+function maybePruneLocked(force) {
+    const marker = path.join(eventsRoot(), PRUNE_MARKER);
     const oneDayMs = 24 * 60 * 60 * 1000;
-    if (now - lastRotationCheck > oneDayMs) {
-        lastRotationCheck = now;
-        rotate();
+    let due = force;
+    try {
+        due ||= Date.now() - fs.statSync(marker).mtimeMs > oneDayMs;
     }
+    catch {
+        due = true;
+    }
+    if (!due)
+        return;
+    const maxBytes = force
+        ? DEFAULT_MAX_STORAGE_BYTES - GZIP_ROTATION_BYTES
+        : DEFAULT_MAX_STORAGE_BYTES;
+    pruneEventLogsLocked(DEFAULT_RETENTION_DAYS, maxBytes);
+    try {
+        fs.writeFileSync(marker, '', { mode: FILE_MODE });
+    }
+    catch { /* retry next append */ }
 }
 // ─── Query ────────────────────────────────────────────────────────────────────
 /**
@@ -731,19 +993,9 @@ export function maybeRotate() {
 export function query(options) {
     const { startDate, endDate = new Date(), eventTypes, level, agent, sessionId, caller, command, module, bundle, limit } = options;
     const results = [];
-    if (!fs.existsSync(eventsDir()))
-        return results;
-    const files = [];
-    if (fs.existsSync(eventsPath()))
-        files.push({ path: eventsPath(), gzip: false });
-    const archives = fs.readdirSync(eventsDir())
-        .map((file) => ({ file, match: file.match(/^events\.(\d+)\.jsonl\.gz$/) }))
-        .filter((entry) => entry.match !== null)
-        .map((entry) => ({ file: entry.file, number: Number(entry.match[1]) }))
-        .sort((a, b) => a.number - b.number);
-    for (const archive of archives) {
-        files.push({ path: path.join(eventsDir(), archive.file), gzip: true });
-    }
+    eventsPath(); // Resolve AGENTS_EVENTS_PATH before deciding whether to migrate.
+    migrateLegacyEventLogs();
+    const files = listEventLogFiles().sort((a, b) => Number(b.currentActive) - Number(a.currentActive) || b.mtimeMs - a.mtimeMs || b.path.localeCompare(a.path));
     const startMs = startDate?.getTime();
     const endMs = endDate?.getTime();
     for (const file of files) {
@@ -849,16 +1101,9 @@ export function stats(options = {}) {
     let fileCount = 0;
     let totalBytes = 0;
     try {
-        if (fs.existsSync(eventsDir())) {
-            const files = fs.readdirSync(eventsDir()).filter(f => f === 'events.jsonl' || /^events\.\d+\.jsonl\.gz$/.test(f));
-            fileCount = files.length;
-            for (const f of files) {
-                try {
-                    totalBytes += fs.statSync(path.join(eventsDir(), f)).size;
-                }
-                catch { /* skip */ }
-            }
-        }
+        const files = listEventLogFiles();
+        fileCount = files.length;
+        totalBytes = files.reduce((sum, file) => sum + file.size, 0);
     }
     catch { /* skip */ }
     return {
@@ -876,9 +1121,11 @@ export function stats(options = {}) {
 export function getLogsPath() {
     return eventsPath();
 }
-export function _resetForTest(overrideEventsPath) {
+export function _resetForTest(overrideEventsPath, overrideUserAgentsDir) {
     _eventsPath = overrideEventsPath;
+    _eventsPathOverride = Boolean(overrideEventsPath);
+    _userAgentsDirOverride = overrideUserAgentsDir;
+    _legacyMigrationChecked = false;
     resetEventProvenanceForTest();
     _chmoddedPath = undefined;
-    lastRotationCheck = 0;
 }

package/dist/lib/exec.js

@@ -14,7 +14,7 @@ import { parseTimeout } from './routines.js';
 import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { isTierToken, resolveTier } from './model-tiers.js';
-import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
+import { createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
 import { getShimsDir, getHistoryDir, getUserAgentsDir } from './state.js';
@@ -1399,7 +1399,6 @@ async function spawnAgent(options) {
     const runId = launchId;
     options = { ...options, env: { ...options.env, AGENT_LAUNCH_ID: launchId } };
     const watcherState = await setupBudgetWatcher(options, cwd, runId);
-    maybeRotate();
     const timer = createTimer('agent.run', {
         agent: options.agent,
         version: options.version,

package/dist/lib/migrate.d.ts

@@ -133,5 +133,13 @@ export declare function migrateRoutineDeviceToDevices(routinesDir?: string): voi
  * real routines dir (and without racing the routine module's own tests).
  */
 export declare function migrateWatchdogSentinelToRoutine(sentinelPath?: string, ensure?: (enabled: boolean) => void): void;
+/**
+ * Rename cli/ → clis/ in each of the given `.agents/` directories.
+ *
+ * One-way, idempotent: no-op when src is absent. Throws when both
+ * `<dir>/cli` and `<dir>/clis` exist — the user must resolve the conflict
+ * manually before proceeding. Exported for unit-testing with temp dirs.
+ */
+export declare function migrateCliDirToClis(agentsDirs: string[]): void;
 /** Run all idempotent migrations. Safe to call multiple times. */
 export declare function runMigration(): Promise<void>;

package/dist/lib/migrate.js

@@ -998,7 +998,6 @@ function migrateRuntimeToHistory() {
     moveDirOnce(path.join(USER_DIR, '.backups'), path.join(HISTORY_DIR, 'backups'));
     moveDirOnce(path.join(USER_DIR, 'routines', 'runs'), path.join(HISTORY_DIR, 'runs'));
     moveDirOnce(path.join(USER_DIR, 'teams', 'agents'), path.join(HISTORY_DIR, 'teams', 'agents'));
-    migrateEventLogsToHistory();
     // Drop any empty leftover skeletons created mid-rename (e.g. `versions/<agent>/<v>/home/`
     // recreated by a concurrent process). The real data is already under .history/.
     rmEmptyDirTree(path.join(USER_DIR, 'versions'));
@@ -1014,66 +1013,6 @@ function migrateRuntimeToHistory() {
         catch { /* best-effort */ }
     }
 }
-/** Move the operational event stream out of the git-backed user-repo root. */
-function migrateEventLogsToHistory() {
-    const destination = path.join(HISTORY_DIR, 'events');
-    let files = [];
-    try {
-        files = fs.readdirSync(USER_DIR).filter((file) => file === 'events.jsonl' || /^events\.\d+\.jsonl\.gz$/.test(file));
-    }
-    catch {
-        return;
-    }
-    try {
-        fs.mkdirSync(destination, { recursive: true, mode: 0o700 });
-    }
-    catch {
-        return;
-    }
-    const active = files.find((file) => file === 'events.jsonl');
-    if (active) {
-        const src = path.join(USER_DIR, active);
-        const dest = path.join(destination, active);
-        if (!fs.existsSync(dest)) {
-            moveFileOnce(src, dest);
-        }
-        else {
-            try {
-                const lines = [fs.readFileSync(src, 'utf-8'), fs.readFileSync(dest, 'utf-8')]
-                    .flatMap((content) => content.split('\n').filter(Boolean))
-                    .map((line, index) => {
-                    try {
-                        const timestamp = Date.parse(JSON.parse(line).ts ?? '');
-                        return { line, index, timestamp: Number.isNaN(timestamp) ? Number.MAX_SAFE_INTEGER : timestamp };
-                    }
-                    catch {
-                        return { line, index, timestamp: Number.MAX_SAFE_INTEGER };
-                    }
-                })
-                    .sort((a, b) => a.timestamp - b.timestamp || a.index - b.index)
-                    .map(({ line }) => line);
-                atomicWriteFileSync(dest, `${lines.join('\n')}\n`, { mode: 0o600 });
-                fs.unlinkSync(src);
-            }
-            catch { /* preserve the source for a later retry */ }
-        }
-    }
-    const archives = files
-        .map((file) => ({ file, match: file.match(/^events\.(\d+)\.jsonl\.gz$/) }))
-        .filter((entry) => entry.match !== null)
-        .sort((a, b) => Number(a.match[1]) - Number(b.match[1]));
-    let nextArchive = fs.readdirSync(destination).reduce((max, file) => {
-        const match = file.match(/^events\.(\d+)\.jsonl\.gz$/);
-        return match ? Math.max(max, Number(match[1])) : max;
-    }, 0) + 1;
-    for (const archive of archives) {
-        const preferred = path.join(destination, archive.file);
-        const dest = fs.existsSync(preferred)
-            ? path.join(destination, `events.${nextArchive++}.jsonl.gz`)
-            : preferred;
-        moveFileOnce(path.join(USER_DIR, archive.file), dest);
-    }
-}
 /**
  * Restore plugins from the cache bucket back to the user-root.
  *
@@ -1694,7 +1633,7 @@ function containsOnlyDsStore(dir) {
 function warnSystemOrphans() {
     const SHIPPED_ALLOWLIST = new Set([
         // resource directories shipped by the npm package
-        'commands', 'hooks', 'skills', 'rules', 'mcp', 'cli', 'permissions', 'subagents', 'profiles', 'agents', 'routines',
+        'commands', 'hooks', 'skills', 'rules', 'mcp', 'clis', 'permissions', 'subagents', 'profiles', 'agents', 'routines',
         // top-level metadata files
         'agents.yaml', 'hooks.yaml', 'README.md', 'CHANGELOG.md',
         // git + repo metadata
@@ -2074,10 +2013,35 @@ export function migrateWatchdogSentinelToRoutine(sentinelPath = path.join(CACHE_
     catch { /* already gone */ }
     console.error('Migrated watchdog: legacy enable sentinel → watchdog routine (kept enabled)');
 }
+/**
+ * Rename cli/ → clis/ in each of the given `.agents/` directories.
+ *
+ * One-way, idempotent: no-op when src is absent. Throws when both
+ * `<dir>/cli` and `<dir>/clis` exist — the user must resolve the conflict
+ * manually before proceeding. Exported for unit-testing with temp dirs.
+ */
+export function migrateCliDirToClis(agentsDirs) {
+    for (const agentsDir of agentsDirs) {
+        const src = path.join(agentsDir, 'cli');
+        const dest = path.join(agentsDir, 'clis');
+        if (!fs.existsSync(src))
+            continue;
+        if (fs.existsSync(dest)) {
+            throw new Error(`Migration conflict: both ${src} and ${dest} exist. ` +
+                `Remove or merge the old cli/ directory into clis/ manually.`);
+        }
+        fs.renameSync(src, dest);
+    }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
     // MUST run first: every other migrator reads SYSTEM_DIR (the new path).
     foldLegacySystemRepo();
+    const cliMigrateDirs = [USER_DIR, SYSTEM_DIR];
+    const projectDotAgents = path.join(process.cwd(), '.agents');
+    if (fs.existsSync(projectDotAgents))
+        cliMigrateDirs.push(projectDotAgents);
+    migrateCliDirToClis(cliMigrateDirs);
     migrateAgentsYaml();
     deleteSystemPromptsJson();
     migrateSystemConfigJson();