@ouro.bot/cli 0.1.0-alpha.273 → 0.1.0-alpha.274

package/changelog.json

@@ -1,6 +1,16 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.274",
+      "changes": [
+        "feat(nerves): daemon log rotation is now 25 MB x 5 gzipped generations instead of 50 MB x 2 uncompressed, dropping peak disk per stream from ~150 MB to ~30 MB. `createNdjsonFileSink` and `rotateIfNeeded` in `src/nerves/index.ts` accept an options object `{ maxSizeBytes, maxGenerations, compress, rotationCheckIntervalBytes }` (with number-form backcompat for the old positional API). Rotation uses a rename-then-gzip pattern so active writers can keep their fd alive while the renamed file gets compressed. Legacy uncompressed `.1.ndjson`/`.2.ndjson` files from the old scheme are tolerated and gzip-migrated on first rotation. Lifecycle emits paired `nerves.rotation_start` / `nerves.rotation_end` events with a shared trace_id, plus `nerves.rotation_error` on failure via a completion-flag try/catch.",
+        "feat(log-tailer): `ouro logs` can now read rotated `.ndjson.gz` generations, so `--lines N` spans across historical files. `discoverLogFiles` matches both `.ndjson` and `.ndjson.gz`, parses filenames into (streamBase, rank) tuples, and sorts chronologically (oldest generation first, active last). A new internal `readNdjsonFileContents` helper dispatches to `zlib.gunzipSync` for `.gz` paths while preserving the DI-stubbed plain-file path for existing tests. Follow mode only watches the active stream — gzipped generations are historical by definition and never tailed.",
+        "feat(logs-prune): new `ouro logs prune` subcommand applies the active rotation policy to every oversized `.ndjson` file in the agent daemon logs directory. Idempotent — a second run on a compliant dir is a no-op. Concurrent-writer-safe because it delegates to `rotateIfNeeded`'s rename-then-gzip pattern (no locking needed). Emits paired `nerves.logs_prune_start` / `nerves.logs_prune_end` with `nerves.logs_prune_error` on failure. Prints `compacted N file(s), freed M bytes` to stdout. New module `src/heart/daemon/logs-prune.ts` exports `pruneDaemonLogs(options)`; the CLI wire-up adds a `daemon.logs.prune` command kind across cli-types/cli-parse/cli-exec and a `pruneDaemonLogs` dep to `createDefaultOuroCliDeps`.",
+        "fix(launchd): drop the stale `StandardErrorPath` plist key that pointed at `ouro-daemon-stderr.log`. The file grew to 366 MB in the wild because the daemon stopped writing to it (the nerves ndjson pipeline has been the source of truth for diagnostics since the nerves layer landed) but nothing ever removed the plist key, so launchd kept the path registered and occasional process-level stderr still dripped in. Removing the key lets launchd forward stray stderr to the system log forwarder where the OS rotates it. The 366 MB orphaned file on disk at `~/AgentBundles/slugger.ouro/state/daemon/logs/ouro-daemon-stderr.log` is safe to delete manually and is flagged in the PR summary for user cleanup.",
+        "refactor(runtime-logging,cli-logging): every `createNdjsonFileSink` call site now passes an explicit `{ maxSizeBytes, maxGenerations, compress }` options object. No callsite silently relies on the old 50 MB default — the policy is visible at each wire-up point. This also removes the `/* v8 ignore */` around the rotation trigger in the sink's flush() loop; tests now exercise it directly via the new `rotationCheckIntervalBytes` option."
+      ]
+    },
     {
       "version": "0.1.0-alpha.273",
       "changes": [

package/dist/heart/daemon/cli-defaults.js

@@ -63,6 +63,7 @@ const runtime_mode_1 = require("./runtime-mode");
 const agent_discovery_1 = require("./agent-discovery");
 const bundle_manifest_1 = require("../../mind/bundle-manifest");
 const ouro_bot_global_installer_1 = require("../versioning/ouro-bot-global-installer");
+const logs_prune_1 = require("./logs-prune");
 const launchd_1 = require("./launchd");
 const socket_client_1 = require("./socket-client");
 const session_activity_1 = require("../session-activity");
@@ -534,6 +535,7 @@ function createDefaultOuroCliDeps(socketPath = socket_client_1.DEFAULT_DAEMON_SO
         },
         /* v8 ignore stop */
         syncGlobalOuroBotWrapper: ouro_bot_global_installer_1.syncGlobalOuroBotWrapper,
+        pruneDaemonLogs: logs_prune_1.pruneDaemonLogs,
         ensureSkillManagement: skill_management_installer_1.ensureSkillManagement,
         ensureDaemonBootPersistence: defaultEnsureDaemonBootPersistence,
         /* v8 ignore start -- dev-mode defaults: tests inject mocks for mode detection and binary resolution @preserve */

package/dist/heart/daemon/cli-exec.js

@@ -1080,6 +1080,17 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         deps.tailLogs();
         return "";
     }
+    if (command.kind === "daemon.logs.prune") {
+        if (!deps.pruneDaemonLogs) {
+            const message = "logs prune unavailable (dep not wired)";
+            deps.writeStdout(message);
+            return message;
+        }
+        const result = deps.pruneDaemonLogs();
+        const message = `compacted ${result.filesCompacted} file${result.filesCompacted === 1 ? "" : "s"}, freed ${result.bytesFreed} bytes`;
+        deps.writeStdout(message);
+        return message;
+    }
     if (command.kind === "outlook") {
         let status;
         try {

package/dist/heart/daemon/cli-parse.js

@@ -696,8 +696,11 @@ function parseOuroCommand(args) {
         return { kind: "daemon.stop" };
     if (head === "status")
         return { kind: "daemon.status" };
-    if (head === "logs")
+    if (head === "logs") {
+        if (second === "prune")
+            return { kind: "daemon.logs.prune" };
         return { kind: "daemon.logs" };
+    }
     if (head === "outlook")
         return { kind: "outlook", ...(args.includes("--json") ? { json: true } : {}) };
     if (head === "hatch")

package/dist/heart/daemon/launchd.js

@@ -78,7 +78,13 @@ function generateDaemonPlist(options) {
         lines.push(`  <key>EnvironmentVariables</key>`, `  <dict>`, `    <key>PATH</key>`, `    <string>${options.envPath}</string>`, `  </dict>`);
     }
     if (options.logDir) {
-        lines.push(`  <key>StandardOutPath</key>`, `  <string>${path.join(options.logDir, "ouro-daemon-stdout.log")}</string>`, `  <key>StandardErrorPath</key>`, `  <string>${path.join(options.logDir, "ouro-daemon-stderr.log")}</string>`);
+        // PR 1 decision: we no longer emit `StandardErrorPath` for the daemon.
+        // The daemon's structured nerves ndjson pipeline (rotated + gzipped via
+        // createNdjsonFileSink) is the source of truth for diagnostics. Writing
+        // raw process stderr to an unrotated file grew to 366 MB in the wild;
+        // dropping the key lets launchd forward stray stderr to the system log
+        // where it gets rotated by the OS.
+        lines.push(`  <key>StandardOutPath</key>`, `  <string>${path.join(options.logDir, "ouro-daemon-stdout.log")}</string>`);
     }
     lines.push(`</dict>`, `</plist>`, ``);
     return lines.join("\n");

package/dist/heart/daemon/log-tailer.js

@@ -38,6 +38,7 @@ exports.readLastLines = readLastLines;
 exports.formatLogLine = formatLogLine;
 exports.tailLogs = tailLogs;
 const path = __importStar(require("path"));
+const zlib = __importStar(require("zlib"));
 const nerves_1 = require("../../nerves");
 const runtime_1 = require("../../nerves/runtime");
 const identity_1 = require("../identity");
@@ -47,6 +48,39 @@ const LEVEL_COLORS = {
     warn: "\x1b[33m",
     error: "\x1b[31m",
 };
+/**
+ * Parse a log filename into a (streamBase, generationRank) tuple.
+ *
+ * - `daemon.ndjson`          → { streamBase: "daemon", rank: 0 }   (active, newest)
+ * - `daemon.1.ndjson.gz`     → { streamBase: "daemon", rank: 1 }
+ * - `daemon.5.ndjson.gz`     → { streamBase: "daemon", rank: 5 }   (oldest)
+ * - Anything else            → null (not a log file).
+ *
+ * Higher rank = older. Used to sort so the oldest generation is read first
+ * and the active stream is read last, producing chronological output.
+ */
+function parseLogFilename(name) {
+    if (name.endsWith(".ndjson.gz")) {
+        // e.g. daemon.1.ndjson.gz → base "daemon.1", strip ".gz" then ".ndjson" then ".<n>"
+        const withoutGz = name.slice(0, -".gz".length); // daemon.1.ndjson
+        const withoutNdjson = withoutGz.slice(0, -".ndjson".length); // daemon.1
+        const genMatch = withoutNdjson.match(/^(.+)\.(\d+)$/);
+        if (!genMatch)
+            return null;
+        return { streamBase: genMatch[1], rank: parseInt(genMatch[2], 10) };
+    }
+    if (name.endsWith(".ndjson")) {
+        const withoutNdjson = name.slice(0, -".ndjson".length);
+        // Active file: daemon.ndjson → base "daemon", rank 0
+        // Legacy numeric gen: daemon.1.ndjson → base "daemon", rank 1 (treat same as gzipped)
+        const legacyMatch = withoutNdjson.match(/^(.+)\.(\d+)$/);
+        if (legacyMatch) {
+            return { streamBase: legacyMatch[1], rank: parseInt(legacyMatch[2], 10) };
+        }
+        return { streamBase: withoutNdjson, rank: 0 };
+    }
+    return null;
+}
 function discoverLogFiles(options) {
     /* v8 ignore start -- integration: default DI stubs for real OS @preserve */
     const existsSync = options.existsSync ?? (() => false);
@@ -55,22 +89,51 @@ function discoverLogFiles(options) {
     const logDir = options.homeDir
         ? path.join(options.homeDir, "AgentBundles", `${options.agentName ?? "slugger"}.ouro`, "state", "daemon", "logs")
         : (0, identity_1.getAgentDaemonLogsDir)(options.agentName);
-    const files = [];
+    const entries = [];
     if (existsSync(logDir)) {
         for (const name of readdirSync(logDir)) {
-            if (!name.endsWith(".ndjson"))
+            const parsed = parseLogFilename(name);
+            if (!parsed)
                 continue;
             if (options.agentFilter && !name.includes(options.agentFilter))
                 continue;
-            files.push(path.join(logDir, name));
+            entries.push({ name, parsed });
         }
     }
-    return files.sort();
+    // Sort chronologically: for each stream, oldest generation first, active last.
+    // Across streams, sort alphabetically by streamBase so output is stable.
+    entries.sort((a, b) => {
+        if (a.parsed.streamBase !== b.parsed.streamBase) {
+            return a.parsed.streamBase < b.parsed.streamBase ? -1 : 1;
+        }
+        // Same stream: higher rank = older = read first.
+        return b.parsed.rank - a.parsed.rank;
+    });
+    return entries.map((e) => path.join(logDir, e.name));
+}
+/**
+ * Read a log file as a string, transparently handling gzipped rotations.
+ *
+ * For `.ndjson.gz` files we read the raw bytes via `fs.readFileSync` (ignoring
+ * any caller-supplied DI `readFileSync`, since that stub returns a `string`
+ * and would corrupt gzip bytes) and then `zlib.gunzipSync` to recover the
+ * original text. For plain `.ndjson` files we defer to the DI stub so tests
+ * can keep mocking fs.
+ */
+function readNdjsonFileContents(filePath, readFileSync) {
+    if (filePath.endsWith(".gz")) {
+        // Binary path: tests can mock readFileSync to return a Buffer (typed as
+        // string) via `as unknown as string` — we accept both Buffer and Uint8Array.
+        const raw = readFileSync(filePath);
+        const buf = typeof raw === "string" ? Buffer.from(raw, "binary") : Buffer.from(raw);
+        return zlib.gunzipSync(buf).toString("utf-8");
+    }
+    return readFileSync(filePath, "utf-8");
 }
 function readLastLines(filePath, count, readFileSync) {
     let content;
     try {
-        content = readFileSync(filePath, "utf-8");
+        content = readNdjsonFileContents(filePath, readFileSync);
     }
     catch {
         return [];
@@ -100,12 +163,17 @@ function tailLogs(options = {}) {
     const files = discoverLogFiles(options);
     (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.log_tailer_started", message: "log tailer started", meta: { fileCount: files.length, follow: !!options.follow } });
     const fileSizes = new Map();
-    // Read initial lines
+    // Read initial lines from each discovered file (oldest gz → newest gz → active).
+    // Gzipped files are historical and never tailed in follow mode.
     for (const file of files) {
         const lines = readLastLines(file, lineCount, readFileSync);
         for (const line of lines) {
             writer(`${formatLogLine(line)}\n`);
         }
+        if (file.endsWith(".gz")) {
+            // Historical rotation — skip size tracking, never followed.
+            continue;
+        }
         try {
             const content = readFileSync(file, "utf-8");
             fileSizes.set(file, content.length);
@@ -114,9 +182,10 @@ function tailLogs(options = {}) {
             fileSizes.set(file, 0);
         }
     }
-    // Follow mode
+    // Follow mode: only the active (non-gzipped) stream is watched.
     if (options.follow && watchFile && unwatchFile) {
-        for (const file of files) {
+        const activeFiles = files.filter((f) => !f.endsWith(".gz"));
+        for (const file of activeFiles) {
             watchFile(file, () => {
                 let content;
                 try {
@@ -138,7 +207,7 @@ function tailLogs(options = {}) {
             });
         }
         return () => {
-            for (const file of files) {
+            for (const file of activeFiles) {
                 unwatchFile(file);
             }
         };

package/dist/heart/daemon/logs-prune.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pruneDaemonLogs = pruneDaemonLogs;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const nerves_1 = require("../../nerves");
+const runtime_1 = require("../../nerves/runtime");
+const identity_1 = require("../identity");
+function pruneDaemonLogs(options = {}) {
+    /* v8 ignore next -- defensive: tests always pass logsDir to avoid prod paths @preserve */
+    const logsDir = options.logsDir ?? (0, identity_1.getAgentDaemonLogsDir)(options.agentName);
+    const maxSizeBytes = options.maxSizeBytes ?? nerves_1.DEFAULT_MAX_LOG_SIZE_BYTES;
+    const maxGenerations = options.maxGenerations ?? nerves_1.DEFAULT_MAX_GENERATIONS;
+    const traceId = (0, crypto_1.randomUUID)();
+    (0, runtime_1.emitNervesEvent)({
+        component: "nerves",
+        event: "nerves.logs_prune_start",
+        trace_id: traceId,
+        message: "pruning daemon logs",
+        meta: { logsDir, maxSizeBytes, maxGenerations },
+    });
+    let completed = false;
+    try {
+        if (!(0, fs_1.existsSync)(logsDir)) {
+            completed = true;
+            (0, runtime_1.emitNervesEvent)({
+                component: "nerves",
+                event: "nerves.logs_prune_end",
+                trace_id: traceId,
+                message: "daemon logs dir does not exist",
+                meta: { logsDir, filesCompacted: 0, bytesFreed: 0 },
+            });
+            return { filesCompacted: 0, bytesFreed: 0 };
+        }
+        let filesCompacted = 0;
+        let bytesFreed = 0;
+        // Enumerate and rotate each active .ndjson stream. We explicitly skip
+        // .gz and other files — only the active stream can be a rotation
+        // candidate. Legacy .N.ndjson uncompressed files are handled inside
+        // rotateIfNeeded's generation-shift step, so we skip them here to
+        // avoid double-rotating.
+        for (const name of (0, fs_1.readdirSync)(logsDir)) {
+            if (!name.endsWith(".ndjson"))
+                continue;
+            // Skip legacy generation files like daemon.1.ndjson; rotateIfNeeded
+            // will migrate them on the next rotation of their parent stream.
+            if (/\.\d+\.ndjson$/.test(name))
+                continue;
+            const filePath = (0, path_1.join)(logsDir, name);
+            let sizeBefore;
+            try {
+                sizeBefore = (0, fs_1.statSync)(filePath).size;
+                /* v8 ignore start -- defensive: file disappears between readdir and stat @preserve */
+            }
+            catch {
+                continue;
+            }
+            /* v8 ignore stop */
+            if (sizeBefore < maxSizeBytes)
+                continue;
+            // rotateIfNeeded returns true because we pre-checked sizeBefore >=
+            // maxSizeBytes above. The false branch of `if (rotated)` is defensive
+            // and unreachable under normal flow; we skip it from coverage so a
+            // future refactor that weakens the pre-check still reports correct
+            // counts without needing a contrived test.
+            const rotated = (0, nerves_1.rotateIfNeeded)(filePath, {
+                maxSizeBytes,
+                maxGenerations,
+                compress: true,
+            });
+            /* v8 ignore next 3 -- defensive: pre-check guarantees rotated=true @preserve */
+            if (!rotated) {
+                continue;
+            }
+            filesCompacted += 1;
+            bytesFreed += sizeBefore;
+        }
+        completed = true;
+        (0, runtime_1.emitNervesEvent)({
+            component: "nerves",
+            event: "nerves.logs_prune_end",
+            trace_id: traceId,
+            message: "daemon logs pruned",
+            meta: { logsDir, filesCompacted, bytesFreed },
+        });
+        return { filesCompacted, bytesFreed };
+    }
+    catch (err) {
+        /* v8 ignore next -- defensive: completed=true only reached after try returns @preserve */
+        if (!completed) {
+            /* v8 ignore next -- defensive: rotation always throws real Errors @preserve */
+            const reason = err instanceof Error ? err.message : String(err);
+            (0, runtime_1.emitNervesEvent)({
+                component: "nerves",
+                event: "nerves.logs_prune_error",
+                trace_id: traceId,
+                level: "error",
+                message: "daemon logs prune failed",
+                meta: { logsDir, error: reason },
+            });
+        }
+        throw err;
+    }
+}

package/dist/heart/daemon/runtime-logging.js

@@ -119,12 +119,20 @@ function configureDaemonRuntimeLogger(processName, options = {}) {
     const logsDir = options.homeDir
         ? path.join(options.homeDir, "AgentBundles", `${agentName}.ouro`, "state", "daemon", "logs")
         : (0, identity_1.getAgentDaemonLogsDir)(agentName);
+    // Rotation policy per daemon ndjson stream (Unit 1c):
+    //   25 MB threshold x 5 gzipped generations = ~30 MB peak per stream.
+    // Call sites previously relied on the implicit 50 MB default; we now pass
+    // the options object explicitly so the policy is visible at the call site.
     const sinks = config.sinks.map((sinkName) => {
         if (sinkName === "terminal") {
             return (0, nerves_1.createTerminalSink)();
         }
         const ndjsonPath = path.join(logsDir, `${processName}.ndjson`);
-        return (0, nerves_1.createNdjsonFileSink)(ndjsonPath);
+        return (0, nerves_1.createNdjsonFileSink)(ndjsonPath, {
+            maxSizeBytes: 25 * 1024 * 1024,
+            maxGenerations: 5,
+            compress: true,
+        });
     });
     const logger = (0, nerves_1.createLogger)({
         level: config.level,

package/dist/nerves/cli-logging.js

@@ -28,7 +28,13 @@ function configureCliRuntimeLogger(_friendId, options = {}) {
             // for an interactive session. Full detail goes to the ndjson file.
             return filterSink((0, nerves_1.createTerminalSink)(), "warn");
         }
-        return (0, nerves_1.createNdjsonFileSink)((0, config_1.logPath)("cli", "runtime"));
+        // Rotation policy for the CLI runtime sink (Unit 1c):
+        // 25 MB x 5 gzipped generations, matching the daemon stream policy.
+        return (0, nerves_1.createNdjsonFileSink)((0, config_1.logPath)("cli", "runtime"), {
+            maxSizeBytes: 25 * 1024 * 1024,
+            maxGenerations: 5,
+            compress: true,
+        });
     });
     const logger = (0, nerves_1.createLogger)({
         level,

package/dist/nerves/index.js

@@ -1,5 +1,39 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_GENERATIONS = exports.DEFAULT_MAX_LOG_SIZE_BYTES = void 0;
 exports.createTraceId = createTraceId;
 exports.ensureTraceId = ensureTraceId;
 exports.createFanoutSink = createFanoutSink;
@@ -14,6 +48,12 @@ exports.createLogger = createLogger;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const crypto_1 = require("crypto");
+const zlib = __importStar(require("zlib"));
+// NOTE: runtime.ts imports `createLogger` and `ensureTraceId` from this file.
+// The cycle is safe in CommonJS because runtime.ts only uses those values
+// lazily inside `getRuntimeLogger()`, and we only call `emitNervesEvent` from
+// inside `rotateIfNeeded` — never at module top level.
+const runtime_1 = require("./runtime");
 const LEVEL_PRIORITY = {
     debug: 10,
     info: 20,
@@ -103,13 +143,44 @@ catch { /* EPIPE: daemon detached, no terminal */ } }, colorize = true) {
 function createStderrSink(write) {
     return createTerminalSink(write);
 }
-const DEFAULT_MAX_LOG_SIZE_BYTES = 50 * 1024 * 1024; // 50MB
-const ROTATION_CHECK_INTERVAL_BYTES = 1024 * 1024; // ~1MB between stat checks
+exports.DEFAULT_MAX_LOG_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB per active stream
+exports.DEFAULT_MAX_GENERATIONS = 5; // keep 5 gzipped historical generations
+const DEFAULT_ROTATION_CHECK_INTERVAL_BYTES = 1024 * 1024; // ~1MB between stat checks
+/** Internal: compute the gzipped generation path for a given ndjson file. */
+function generationGzPath(base, ext, n) {
+    return ext === ".ndjson" ? `${base}.${n}.ndjson.gz` : `${base}.${n}.gz`;
+}
+/** Internal: compute the legacy uncompressed generation path for a given file. */
+function generationPlainPath(base, ext, n) {
+    return ext === ".ndjson" ? `${base}.${n}.ndjson` : `${base}.${n}`;
+}
 /**
- * Rotate a log file: shift .1 -> .2, delete old .2, rename current -> .1.
- * Uses the ndjson extension pattern: file.ndjson -> file.1.ndjson -> file.2.ndjson
+ * Rotate a log file in place.
+ *
+ * Scheme (25 MB × 5 gzipped generations by default):
+ *   active       : foo.ndjson
+ *   newest gen   : foo.1.ndjson.gz
+ *   oldest gen   : foo.5.ndjson.gz (dropped on next rotation)
+ *
+ * Legacy tolerance: uncompressed `foo.1.ndjson` / `foo.2.ndjson` files from the
+ * old scheme are treated as the corresponding generation and gzipped on first
+ * rotation.
+ *
+ * Concurrent-writer safety: the active file is renamed (inode stays alive for
+ * any open writer fd) then gzipped at the renamed path. An active writer
+ * continues writing to its original fd; on the next write cycle it sees the
+ * old path is missing and creates a fresh file.
+ *
+ * Backwards-compatible signature: passing a `number` as the second argument
+ * (the old API) is still accepted and interpreted as `maxSizeBytes`.
  */
-function rotateIfNeeded(filePath, maxSizeBytes) {
+function rotateIfNeeded(filePath, optionsOrMaxSize) {
+    const options = typeof optionsOrMaxSize === "number"
+        ? { maxSizeBytes: optionsOrMaxSize }
+        : optionsOrMaxSize ?? {};
+    const maxSizeBytes = options.maxSizeBytes ?? exports.DEFAULT_MAX_LOG_SIZE_BYTES;
+    const maxGenerations = options.maxGenerations ?? exports.DEFAULT_MAX_GENERATIONS;
+    const compress = options.compress ?? true;
     let size;
     try {
         size = (0, fs_1.statSync)(filePath).size;
@@ -121,39 +192,124 @@ function rotateIfNeeded(filePath, maxSizeBytes) {
         return false;
     const ext = filePath.endsWith(".ndjson") ? ".ndjson" : "";
     const base = ext ? filePath.slice(0, -ext.length) : filePath;
-    const file1 = `${base}.1${ext}`;
-    const file2 = `${base}.2${ext}`;
+    const traceId = (0, crypto_1.randomUUID)();
+    (0, runtime_1.emitNervesEvent)({
+        component: "nerves",
+        event: "nerves.rotation_start",
+        trace_id: traceId,
+        message: "rotating log file",
+        meta: { path: filePath, currentSize: size, threshold: maxSizeBytes, generation: 1 },
+    });
+    let completed = false;
     try {
-        (0, fs_1.unlinkSync)(file2);
-    }
-    catch { /* may not exist */ }
-    try {
-        (0, fs_1.renameSync)(file1, file2);
+        // Step 1: drop / shift existing generations starting from the oldest.
+        // For each slot N (maxGenerations..2), find whatever occupies slot (N-1)
+        // (as .gz or legacy uncompressed) and move it to slot N. Slot N occupants
+        // get overwritten (oldest is dropped). Non-existent slots are skipped.
+        for (let n = maxGenerations; n >= 2; n--) {
+            const destGz = generationGzPath(base, ext, n);
+            const srcGz = generationGzPath(base, ext, n - 1);
+            const srcPlain = generationPlainPath(base, ext, n - 1);
+            // Drop whatever currently occupies the destination slot (oldest generation).
+            if ((0, fs_1.existsSync)(destGz)) {
+                (0, fs_1.unlinkSync)(destGz);
+            }
+            const destPlain = generationPlainPath(base, ext, n);
+            if ((0, fs_1.existsSync)(destPlain)) {
+                (0, fs_1.unlinkSync)(destPlain);
+            }
+            // Prefer moving .gz → .gz (cheap rename).
+            if ((0, fs_1.existsSync)(srcGz)) {
+                (0, fs_1.renameSync)(srcGz, destGz);
+                continue;
+            }
+            // Legacy migration: if a plain .ndjson generation file exists from the
+            // old scheme, read it, gzip it into the destination slot, and delete
+            // the plain source.
+            if ((0, fs_1.existsSync)(srcPlain)) {
+                if (compress) {
+                    const buf = (0, fs_1.readFileSync)(srcPlain);
+                    const compressed = zlib.gzipSync(buf);
+                    (0, fs_1.writeFileSync)(destGz, compressed);
+                    (0, fs_1.unlinkSync)(srcPlain);
+                }
+                else {
+                    // compress=false: just rename
+                    (0, fs_1.renameSync)(srcPlain, destPlain);
+                }
+            }
+        }
+        // Step 2: rename the active file to the generation-1 plain path. The
+        // active writer keeps its open fd; the file path now points elsewhere.
+        const plain1 = generationPlainPath(base, ext, 1);
+        // If a stale .1 plain path exists (e.g. a previous compress=false run),
+        // remove it so the rename can claim the slot cleanly.
+        if ((0, fs_1.existsSync)(plain1)) {
+            (0, fs_1.unlinkSync)(plain1);
+        }
+        (0, fs_1.renameSync)(filePath, plain1);
+        // Step 3: gzip (or keep plain) the renamed file into the .1 generation.
+        if (compress) {
+            const gz1 = generationGzPath(base, ext, 1);
+            // Remove any lingering .1.ndjson.gz to avoid "file exists" on write.
+            if ((0, fs_1.existsSync)(gz1)) {
+                (0, fs_1.unlinkSync)(gz1);
+            }
+            const buf = (0, fs_1.readFileSync)(plain1);
+            const compressed = zlib.gzipSync(buf);
+            (0, fs_1.writeFileSync)(gz1, compressed);
+            (0, fs_1.unlinkSync)(plain1);
+        }
+        completed = true;
+        (0, runtime_1.emitNervesEvent)({
+            component: "nerves",
+            event: "nerves.rotation_end",
+            trace_id: traceId,
+            message: "log rotation complete",
+            meta: { path: filePath, compressedPath: compress ? generationGzPath(base, ext, 1) : plain1, bytesFreed: size },
+        });
+        return true;
     }
-    catch { /* may not exist */ }
-    try {
-        (0, fs_1.renameSync)(filePath, file1);
+    catch (err) {
+        /* v8 ignore next -- defensive: completed=true only reached after the try block's return @preserve */
+        if (!completed) {
+            /* v8 ignore next -- defensive: fs ops throw real Errors @preserve */
+            const reason = err instanceof Error ? err.message : String(err);
+            (0, runtime_1.emitNervesEvent)({
+                component: "nerves",
+                event: "nerves.rotation_error",
+                trace_id: traceId,
+                level: "error",
+                message: "log rotation failed",
+                meta: { path: filePath, error: reason },
+            });
+        }
+        throw err;
     }
-    catch { /* best effort */ }
-    return true;
 }
-function createNdjsonFileSink(filePath, maxSizeBytes) {
+function createNdjsonFileSink(filePath, optionsOrMaxSize) {
     (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
+    const options = typeof optionsOrMaxSize === "number"
+        ? { maxSizeBytes: optionsOrMaxSize }
+        : optionsOrMaxSize ?? {};
+    const rotationCheckInterval = options.rotationCheckIntervalBytes ?? DEFAULT_ROTATION_CHECK_INTERVAL_BYTES;
     const queue = [];
     let flushing = false;
     let bytesSinceCheck = 0;
-    const maxSize = maxSizeBytes ?? DEFAULT_MAX_LOG_SIZE_BYTES;
     function flush() {
         if (flushing || queue.length === 0)
             return;
         flushing = true;
         const line = queue.shift();
-        /* v8 ignore start — rotation triggers only after ~1MB of writes @preserve */
-        if (bytesSinceCheck >= ROTATION_CHECK_INTERVAL_BYTES) {
+        if (bytesSinceCheck >= rotationCheckInterval) {
             bytesSinceCheck = 0;
-            rotateIfNeeded(filePath, maxSize);
+            try {
+                rotateIfNeeded(filePath, options);
+            }
+            catch {
+                // Rotation errors are surfaced via nerves events; never block writes.
+            }
         }
-        /* v8 ignore stop */
         (0, fs_1.appendFile)(filePath, line, "utf8", () => {
             flushing = false;
             flush();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.273",
+  "version": "0.1.0-alpha.274",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",