@skrr-ai/cli 0.1.103 → 0.1.105

package/dist/commands/daemon/logs.js

@@ -3,18 +3,31 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STDERR_FLAG_DESCRIPTION = exports.ROTATED_LOGS_RUNTIME_VERSION = exports.LIVE_LOG_RESOLUTION_RUNTIME_VERSION = void 0;
 exports.describeLogAge = describeLogAge;
 exports.resolveLegacyDaemonLogPath = resolveLegacyDaemonLogPath;
 exports.resolveDaemonLogsProfile = resolveDaemonLogsProfile;
+exports.installedServiceLogDestinations = installedServiceLogDestinations;
 exports.installedServiceLogCandidates = installedServiceLogCandidates;
 exports.chooseLegacyFallbackLog = chooseLegacyFallbackLog;
 exports.resolveForwardedLogPath = resolveForwardedLogPath;
+exports.rotatedLogSiblings = rotatedLogSiblings;
+exports.describeRotatedSiblings = describeRotatedSiblings;
+exports.readLastLines = readLastLines;
+exports.readLastLinesAcross = readLastLinesAcross;
+exports.streamLogFiles = streamLogFiles;
+exports.parseRuntimeVersion = parseRuntimeVersion;
+exports.runtimeVersionAtLeast = runtimeVersionAtLeast;
+exports.probeRuntimeVersion = probeRuntimeVersion;
+exports.probeStatusLogPath = probeStatusLogPath;
+exports.planDaemonLogs = planDaemonLogs;
 exports.readDaemonLogTail = readDaemonLogTail;
 exports.buildDaemonLogsArgs = buildDaemonLogsArgs;
 const core_1 = require("@oclif/core");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = __importDefault(require("node:path"));
+const node_events_1 = require("node:events");
 const exec_runtime_binary_1 = require("../../lib/exec-runtime-binary");
 const MAX_FALLBACK_LOG_BYTES = 1024 * 1024;
 const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -93,22 +106,22 @@ function resolveDaemonLogsProfile(flags, options = {}) {
     return profile ?? 'default';
 }
 /**
- * Log files the installed launchd definition for this profile sends output to
- * (OSK-15993). The desktop supervisor starts the daemon with
+ * Read the installed launchd definition's log destinations (OSK-15993). The
+ * desktop supervisor starts the daemon with
  * `--log-file ~/Library/Logs/Skrr/daemon.app.log` and redirects stderr to
  * `daemon.stderr.log`, so the profile's `logs/` directory can hold a file
  * nobody has written for a week. Read-only: the plist is parsed, never loaded.
  */
-function installedServiceLogCandidates(profile, stderr, options = {}) {
+function installedServiceLogDestinations(profile, options = {}) {
     if ((options.platform ?? process.platform) !== 'darwin')
-        return [];
+        return null;
     const plist = node_path_1.default.join(options.home ?? (0, node_os_1.homedir)(), 'Library', 'LaunchAgents', `ai.skrr.daemon.${profile}.plist`);
     let xml;
     try {
         xml = (0, node_fs_1.readFileSync)(plist, 'utf8');
     }
     catch {
-        return [];
+        return null;
     }
     const unescape = (v) => v
         .replace(/&lt;/g, '<')
@@ -120,22 +133,28 @@ function installedServiceLogCandidates(profile, stderr, options = {}) {
         const m = new RegExp(`<key>\\s*${key}\\s*</key>\\s*<string>([\\s\\S]*?)</string>`).exec(xml);
         return m?.[1]?.trim() ? unescape(m[1].trim()) : null;
     };
-    if (stderr) {
-        const errPath = stringFor('StandardErrorPath');
-        return errPath ? [errPath] : [];
-    }
-    const out = [];
+    let logFile = null;
     const array = /<key>\s*ProgramArguments\s*<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(xml);
     if (array?.[1]) {
         const args = [...array[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unescape(m[1].trim()));
         const at = args.lastIndexOf('--log-file');
         if (at >= 0 && args[at + 1] && !args[at + 1].startsWith('-'))
-            out.push(args[at + 1]);
+            logFile = args[at + 1];
     }
-    const stdoutPath = stringFor('StandardOutPath');
-    if (stdoutPath)
-        out.push(stdoutPath);
-    return out;
+    return {
+        logFile,
+        stdoutPath: stringFor('StandardOutPath'),
+        stderrPath: stringFor('StandardErrorPath'),
+    };
+}
+/** The installed service's log files for the main log, or for `--stderr`. */
+function installedServiceLogCandidates(profile, stderr, options = {}) {
+    const dest = installedServiceLogDestinations(profile, options);
+    if (!dest)
+        return [];
+    if (stderr)
+        return dest.stderrPath ? [dest.stderrPath] : [];
+    return [dest.logFile, dest.stdoutPath].filter((p) => Boolean(p));
 }
 /**
  * Pick the file the legacy fallback reads. An old daemon cannot say which file
@@ -164,7 +183,7 @@ function chooseLegacyFallbackLog(args) {
             (profileMtime === null
                 ? `the profile log ${args.profilePath}, which does not exist.`
                 : `the profile log ${args.profilePath}, which has not been written since.`) +
-            ' This daemon predates `logs`, so it cannot name its live log itself.',
+            ` ${args.reason ?? 'This daemon predates `logs`, so it cannot name its live log itself.'}`,
     };
 }
 /**
@@ -175,7 +194,9 @@ function chooseLegacyFallbackLog(args) {
  */
 async function resolveForwardedLogPath(flags, capture = exec_runtime_binary_1.execRuntimeBinaryCapture) {
     try {
-        const out = await capture(buildDaemonLogsArgs({ ...flags, path: true }), {
+        // Only what decides the file: --rotated would list siblings first, and the
+        // last line is still the current file, but there is no reason to ask.
+        const out = await capture(buildDaemonLogsArgs({ stderr: flags.stderr, profile: flags.profile, path: true }), {
             timeoutMs: 5_000,
         });
         if (out.code !== 0)
@@ -191,6 +212,266 @@ async function resolveForwardedLogPath(flags, capture = exec_runtime_binary_1.ex
         return null;
     }
 }
+/**
+ * The first runtime whose own `logs` reads the LIVE daemon's `--log-file`
+ * (OSK-15993, `daemon/src/daemon-log-target.ts`). 0.8.112 through 0.8.118 have
+ * a `logs` subcommand, so the subcommand probe says "supported", but it reads
+ * the profile's `logs/daemon.log` unconditionally — with a desktop-managed
+ * daemon, a file nobody has written for a week. Forwarding to one of those is
+ * forwarding to the bug, so the CLI forwards only at or above this version.
+ */
+exports.LIVE_LOG_RESOLUTION_RUNTIME_VERSION = '0.8.119';
+/**
+ * The first runtime whose `logs` knows `--rotated` (OSK-16214). An older one
+ * rejects it as an unknown option, so the CLI never forwards the flag below
+ * this version: it asks the runtime which file it reads (`--path`) and reads
+ * that file and its rotated siblings itself.
+ */
+exports.ROTATED_LOGS_RUNTIME_VERSION = '0.8.120';
+/**
+ * Rotated siblings of a log, OLDEST FIRST (OSK-16214). The daemon's logger
+ * renames `daemon.app.log` to `daemon.app.1.log`, `.1` to `.2` and so on at
+ * 10 MB (`daemon/src/logger.ts` `maybeRotate`), and `logs` never reached them —
+ * `--lines 5000 | grep <run id>` found nothing while `daemon.app.1.log` held the
+ * run. A copy of `daemon/src/rotated-log-files.ts`, for runtimes that predate
+ * `--rotated`. Never throws.
+ */
+function rotatedLogSiblings(filePath, readdir = (dir) => (0, node_fs_1.readdirSync)(dir)) {
+    const dir = node_path_1.default.dirname(filePath);
+    const ext = node_path_1.default.extname(filePath);
+    const base = node_path_1.default.basename(filePath, ext);
+    const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`^${escape(base)}\\.(\\d+)${escape(ext)}$`);
+    let names;
+    try {
+        names = readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .map((name) => ({ name, index: Number(pattern.exec(name)?.[1] ?? NaN) }))
+        .filter(({ index }) => Number.isSafeInteger(index) && index >= 1)
+        .sort((a, b) => b.index - a.index)
+        .map(({ name }) => node_path_1.default.join(dir, name));
+}
+/** The sentence shown when rotated siblings hold older lines the view leaves out. */
+function describeRotatedSiblings(filePath, siblings) {
+    if (siblings.length === 0)
+        return null;
+    const names = siblings.map((s) => node_path_1.default.basename(s));
+    const listed = names.length === 1 ? names[0] : `${names.at(-1)} … ${names[0]}`;
+    return (`Older lines are in ${siblings.length} rotated file${siblings.length === 1 ? '' : 's'} ` +
+        `beside ${filePath} (${listed}). Add --rotated to read them too, oldest first.`);
+}
+/**
+ * The last `maxLines` lines of one file, read backwards in chunks so the cost
+ * follows the lines asked for, not the file's size. Bytes are decoded once, so
+ * a multi-byte character split across a chunk boundary survives.
+ */
+function readLastLines(filePath, maxLines) {
+    if (maxLines <= 0)
+        return [];
+    const { size } = (0, node_fs_1.statSync)(filePath);
+    const descriptor = (0, node_fs_1.openSync)(filePath, 'r');
+    try {
+        let start = size;
+        const chunks = [];
+        let newlines = 0;
+        while (start > 0 && newlines <= maxLines) {
+            const length = Math.min(64 * 1024, start);
+            start -= length;
+            const buffer = Buffer.alloc(length);
+            (0, node_fs_1.readSync)(descriptor, buffer, 0, length, start);
+            chunks.unshift(buffer);
+            for (const byte of buffer)
+                if (byte === 0x0a)
+                    newlines += 1;
+        }
+        const lines = Buffer.concat(chunks).toString('utf8').split('\n');
+        if (lines.at(-1) === '')
+            lines.pop();
+        if (start > 0)
+            lines.shift();
+        return lines.slice(-maxLines);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(descriptor);
+    }
+}
+/**
+ * The last `maxLines` lines across `files` (OLDEST FIRST) as if they were one
+ * file. A file renamed away between the listing and the read is skipped.
+ */
+function readLastLinesAcross(files, maxLines) {
+    const collected = [];
+    let remaining = maxLines;
+    for (let i = files.length - 1; i >= 0 && remaining > 0; i -= 1) {
+        try {
+            const lines = readLastLines(files[i], remaining);
+            collected.unshift(lines);
+            remaining -= lines.length;
+        }
+        catch {
+            // Rotated away mid-read; the rest are still worth showing.
+        }
+    }
+    return collected.flat();
+}
+/** Every byte of `files`, in order, to `out` — streamed, honouring back-pressure. */
+async function streamLogFiles(files, out) {
+    for (const file of files) {
+        try {
+            for await (const chunk of (0, node_fs_1.createReadStream)(file)) {
+                if (!out.write(chunk))
+                    await (0, node_events_1.once)(out, 'drain');
+            }
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                continue;
+            throw err;
+        }
+    }
+}
+/** `x.y.z` from a version string, or null. A prerelease suffix is ignored. */
+function parseRuntimeVersion(text) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(text);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+/** Whether `version` is at least `floor`; null when either is not a version. */
+function runtimeVersionAtLeast(version, floor) {
+    const a = parseRuntimeVersion(version);
+    const b = parseRuntimeVersion(floor);
+    if (!a || !b)
+        return null;
+    for (let i = 0; i < 3; i += 1) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return true;
+}
+/** The installed runtime's `--version`, or null when it cannot say in time. */
+async function probeRuntimeVersion(capture = exec_runtime_binary_1.execRuntimeBinaryCapture) {
+    try {
+        const out = await capture(['--version'], { timeoutMs: 5_000 });
+        if (out.code !== 0)
+            return null;
+        const parsed = parseRuntimeVersion(out.stdout);
+        return parsed ? parsed.join('.') : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The live daemon's log as the runtime's `status --json` reports it
+ * (`service.logs`). Status has named the live `--log-file` since before `logs`
+ * did, so on 0.8.117 status is right while logs is wrong. Null when status
+ * cannot answer, or answers with anything but an absolute path.
+ */
+async function probeStatusLogPath(flags, capture = exec_runtime_binary_1.execRuntimeBinaryCapture) {
+    try {
+        const out = await capture([...(flags.profile ? ['--profile', flags.profile] : []), 'status', '--json'], { timeoutMs: 15_000 });
+        // `status` exits non-zero when it reports problems; the JSON is still the answer.
+        const start = out.stdout.indexOf('{');
+        if (start < 0)
+            return null;
+        const parsed = JSON.parse(out.stdout.slice(start));
+        const logs = parsed?.service?.logs;
+        return typeof logs === 'string' && node_path_1.default.isAbsolute(logs) ? logs : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sameLogFile(a, b) {
+    return Boolean(a && b && node_path_1.default.resolve(a) === node_path_1.default.resolve(b));
+}
+/**
+ * Decide which runtime, if any, `skrr daemon logs` may trust (OSK-15993).
+ *
+ * - No `logs` subcommand: the legacy fallback, as before.
+ * - A runtime at or above {@link LIVE_LOG_RESOLUTION_RUNTIME_VERSION}: forward.
+ * - An older runtime, or one whose version cannot be read: ask its `status`
+ *   which file the live daemon writes and read that file here. When status
+ *   cannot answer, an older runtime gets the legacy fallback (the newest of the
+ *   profile log and the installed service's logs); an unknown one is forwarded.
+ */
+async function planDaemonLogs(flags, deps) {
+    const legacy = (reason) => {
+        const chosen = chooseLegacyFallbackLog({
+            profilePath: deps.profilePath,
+            serviceCandidates: (flags.stderr
+                ? [deps.service?.stderrPath]
+                : [deps.service?.logFile, deps.service?.stdoutPath]).filter((p) => Boolean(p)),
+            mtimeOf: deps.mtimeOf,
+            reason,
+        });
+        return {
+            kind: 'read',
+            path: chosen.path,
+            note: chosen.note,
+            missingHint: 'The installed daemon predates `oversky logs`; start it or upgrade it, then retry.',
+        };
+    };
+    const supports = await deps.supportsLogs();
+    if (supports === false) {
+        return legacy('This daemon predates `logs`, so it cannot name its live log itself.');
+    }
+    // Help could not be read: nothing to go on, keep the old behaviour.
+    if (supports === null)
+        return { kind: 'forward', runtimeVersion: null };
+    const version = await deps.runtimeVersion();
+    const current = version
+        ? runtimeVersionAtLeast(version, exports.LIVE_LOG_RESOLUTION_RUNTIME_VERSION)
+        : null;
+    if (current === true)
+        return { kind: 'forward', runtimeVersion: version };
+    const live = await deps.statusLogPath();
+    const predates = version !== null
+        ? `The installed runtime (${version}) predates \`logs\` following the live daemon's ` +
+            `--log-file (${exports.LIVE_LOG_RESOLUTION_RUNTIME_VERSION}), so it would read ${deps.profilePath}.`
+        : `The installed runtime did not report its version, so its \`logs\` may read ` +
+            `${deps.profilePath} instead of the live log.`;
+    if (!live) {
+        if (current === null)
+            return { kind: 'forward', runtimeVersion: version };
+        return legacy(`${predates} Its \`status\` did not name the live log either.`);
+    }
+    // The live daemon writes the profile log itself: the runtime's answer is right.
+    if (sameLogFile(live, node_path_1.default.join(node_path_1.default.dirname(deps.profilePath), 'daemon.log'))) {
+        return { kind: 'forward', runtimeVersion: version };
+    }
+    const missingHint = 'The live daemon has not written it yet; `skrr daemon status` shows whether one is running.';
+    if (!flags.stderr) {
+        return {
+            kind: 'read',
+            path: live,
+            note: `Showing ${live}, the live daemon's log as \`skrrd status\` reports it. ${predates}`,
+            missingHint,
+        };
+    }
+    // --stderr: trust the installed definition's redirect only when it is the
+    // one that launched this daemon (its --log-file is the live one) — the same
+    // rule the runtime's own resolution applies.
+    if (deps.service?.stderrPath && sameLogFile(deps.service.logFile, live)) {
+        return {
+            kind: 'read',
+            path: deps.service.stderrPath,
+            note: `Showing ${deps.service.stderrPath}, the live daemon's stderr as its service definition ` +
+                `redirects it; its full log, WARN and ERROR included, is ${live}. ${predates}`,
+            missingHint,
+        };
+    }
+    return {
+        kind: 'read',
+        path: live,
+        note: `Showing ${live}, the live daemon's log as \`skrrd status\` reports it; it carries every ` +
+            `WARN and ERROR line. ${predates}`,
+        missingHint,
+    };
+}
 /** Read a bounded trailing window, so an unrotated legacy err log is safe. */
 function readDaemonLogTail(filePath, maxLines) {
     if (maxLines === 0)
@@ -231,8 +512,13 @@ function buildDaemonLogsArgs(flags) {
         ...(flags.lines !== undefined ? ['--lines', String(flags.lines)] : []),
         ...(flags.stderr ? ['--stderr'] : []),
         ...(flags.path ? ['--path'] : []),
+        // Only ever reached for a runtime at ROTATED_LOGS_RUNTIME_VERSION or later;
+        // `run` reads the files itself for an older one.
+        ...(flags.rotated ? ['--rotated'] : []),
     ];
 }
+/** `--stderr` help, word for word the runtime's own (`daemon/src/index.ts`). */
+exports.STDERR_FLAG_DESCRIPTION = "Read the daemon's raw stderr instead of its log: the file its installed service redirects stderr to, or the profile's daemon.err.log. A daemon started with --log-file by anything else has no known stderr file, so its live log (which carries every WARN and ERROR) is shown instead, with a note";
 class DaemonLogs extends core_1.Command {
     // `skrr daemons <sub>` — the plural is advertised as an alias for the
     // whole topic, and without a per-command alias only the bare topic
@@ -240,9 +526,9 @@ class DaemonLogs extends core_1.Command {
     static aliases = ['daemons:logs'];
     static description = 'Tail or print recent skrr daemon logs';
     /**
-     * Mirrors the four options `oversky logs` actually implements
+     * Mirrors the options `oversky logs` actually implements
      * (`daemon/src/index.ts` — `-n/--lines`, `-f/--follow`, `--stderr`,
-     * `--path`). Typed flags are deliberate — they give `skrr daemon logs --help`
+     * `--path`, and since 0.8.120 `--rotated`). Typed flags are deliberate — they give `skrr daemon logs --help`
      * something real to print, which raw `strict = false` passthrough never did.
      * The trade is that anything NOT declared here becomes unreachable, so this
      * list has to stay in step with the daemon command.
@@ -254,17 +540,26 @@ class DaemonLogs extends core_1.Command {
         }),
         lines: core_1.Flags.integer({
             char: 'n',
-            description: 'Number of recent log lines to print',
+            description: 'Number of recent log lines to print (default 200; every line with --rotated)',
             // `oversky logs` validates `>= 0`; keep the two in step so `-n 0` is not
             // rejected here only to be accepted there.
             min: 0,
         }),
+        // OSK-16213: this said "daemon.err.log — every WARN and ERROR". Since
+        // OSK-15993 it is the process's raw stderr as the service redirects it
+        // (`planDaemonLogs` here, `resolveDaemonLogTarget` in the runtime), and a
+        // structured --log-file is what carries WARN and ERROR. The runtime's own
+        // `--stderr` help says the same words; logs.spec.ts compares the two.
         stderr: core_1.Flags.boolean({
-            description: 'Read daemon.err.log — every WARN and ERROR — instead of daemon.log',
+            description: exports.STDERR_FLAG_DESCRIPTION,
         }),
         path: core_1.Flags.boolean({
             description: 'Print the resolved log file path and exit',
         }),
+        // OSK-16214: the rotated files (`daemon.app.1.log` …) were unreachable.
+        rotated: core_1.Flags.boolean({
+            description: 'Include the rotated files (daemon.app.1.log …) before the current one, oldest first; with --path, list them all',
+        }),
         // Every other daemon verb reaches a non-default profile with --profile; this
         // one could only be steered by OVERSKY_PROFILE (OSK-10001).
         profile: core_1.Flags.string({
@@ -278,6 +573,7 @@ class DaemonLogs extends core_1.Command {
         '<%= config.bin %> daemon logs --lines 500',
         '<%= config.bin %> daemon logs --stderr',
         '<%= config.bin %> daemon logs --path',
+        '<%= config.bin %> daemon logs --rotated | grep arun_',
         '<%= config.bin %> daemon logs --profile dogfood-laptop --lines 50',
     ];
     async run() {
@@ -301,33 +597,83 @@ class DaemonLogs extends core_1.Command {
             // `oversky 0.2.x` has profiles and writes the same files, but has no
             // `logs` subcommand. Probe top-level help first so forwarding does not
             // print an unrelated "unknown option" error before the useful output.
-            if ((await (0, exec_runtime_binary_1.runtimeBinarySupportsSubcommand)('logs')) === false) {
-                const chosen = chooseLegacyFallbackLog({
-                    profilePath: resolveLegacyDaemonLogPath(flags),
-                    serviceCandidates: installedServiceLogCandidates(resolveDaemonLogsProfile(flags), flags.stderr === true),
-                    mtimeOf: (filePath) => {
-                        try {
-                            return (0, node_fs_1.statSync)(filePath).mtimeMs;
-                        }
-                        catch {
-                            return null;
-                        }
-                    },
-                });
-                const logPath = chosen.path;
-                if (chosen.note)
-                    this.logToStderr(chosen.note);
+            //
+            // OSK-15993: a runtime that HAS `logs` is not necessarily one to trust
+            // with it — 0.8.112–0.8.118 read the profile log even when the live
+            // daemon writes elsewhere. `planDaemonLogs` forwards only to a runtime
+            // that resolves the live log itself.
+            let plan = await planDaemonLogs(flags, {
+                supportsLogs: () => (0, exec_runtime_binary_1.runtimeBinarySupportsSubcommand)('logs'),
+                runtimeVersion: () => probeRuntimeVersion(),
+                statusLogPath: () => probeStatusLogPath(flags),
+                profilePath: resolveLegacyDaemonLogPath(flags),
+                service: installedServiceLogDestinations(resolveDaemonLogsProfile(flags)),
+                mtimeOf: (filePath) => {
+                    try {
+                        return (0, node_fs_1.statSync)(filePath).mtimeMs;
+                    }
+                    catch {
+                        return null;
+                    }
+                },
+            });
+            // OSK-16214: `--rotated` is new in ROTATED_LOGS_RUNTIME_VERSION, and an
+            // older runtime rejects it as an unknown option. Its `--path` is still
+            // the live-aware answer, so read that file and its siblings here.
+            const runtimeKnowsRotated = plan.kind === 'forward' &&
+                plan.runtimeVersion !== null &&
+                runtimeVersionAtLeast(plan.runtimeVersion, exports.ROTATED_LOGS_RUNTIME_VERSION) === true;
+            if (plan.kind === 'forward' && flags.rotated && !runtimeKnowsRotated) {
+                const resolved = await resolveForwardedLogPath(flags);
+                if (!resolved) {
+                    this.error(`The installed runtime${plan.runtimeVersion ? ` (${plan.runtimeVersion})` : ''} predates ` +
+                        `--rotated (${exports.ROTATED_LOGS_RUNTIME_VERSION}) and did not name its log file, so its ` +
+                        'rotated files cannot be found. Upgrade it (`skrr daemon update`), or list the ' +
+                        'directory `skrr daemon logs --path` prints.', { exit: 1 });
+                }
+                plan = {
+                    kind: 'read',
+                    path: resolved,
+                    note: null,
+                    missingHint: 'The live daemon has not written it yet; `skrr daemon status` shows whether one is running.',
+                };
+            }
+            if (plan.kind === 'read') {
+                const logPath = plan.path;
+                const siblings = rotatedLogSiblings(logPath);
+                // `--path` prints the one path and nothing else, on either stream —
+                // under --rotated, every file oldest first, the current one last.
                 if (flags.path) {
+                    for (const file of flags.rotated ? siblings : [])
+                        this.log(file);
                     this.log(logPath);
                     return;
                 }
+                if (plan.note)
+                    this.logToStderr(plan.note);
+                if (flags.rotated && siblings.length === 0) {
+                    this.logToStderr(`No rotated files beside ${logPath}.`);
+                }
+                else if (!flags.rotated) {
+                    const hint = describeRotatedSiblings(logPath, siblings);
+                    if (hint)
+                        this.logToStderr(hint);
+                }
                 showAge(logPath);
                 if (!(0, node_fs_1.existsSync)(logPath)) {
-                    this.error(`No daemon log at ${logPath}. The installed daemon predates \`oversky logs\`; start it or upgrade it, then retry.`, { exit: 1 });
+                    this.error(`No daemon log at ${logPath}. ${plan.missingHint}`, { exit: 1 });
+                }
+                if (flags.rotated && flags.lines === undefined) {
+                    // Every line of every file, streamed rather than held whole.
+                    await streamLogFiles([...siblings, logPath], process.stdout);
+                }
+                else {
+                    const lines = flags.rotated
+                        ? readLastLinesAcross([...siblings, logPath], flags.lines ?? 200)
+                        : readDaemonLogTail(logPath, flags.lines ?? 200);
+                    if (lines.length > 0)
+                        this.log(lines.join('\n'));
                 }
-                const lines = readDaemonLogTail(logPath, flags.lines ?? 200);
-                if (lines.length > 0)
-                    this.log(lines.join('\n'));
                 if (flags.follow) {
                     let position = (0, node_fs_1.statSync)(logPath).size;
                     (0, node_fs_1.watchFile)(logPath, { interval: 500 }, () => {
@@ -359,8 +705,16 @@ class DaemonLogs extends core_1.Command {
             }
             // The banner must describe the file the runtime will actually print —
             // the live daemon's log (OSK-15993) — not the profile default.
-            if (!flags.path)
-                showAge(await resolveForwardedLogPath(flags));
+            if (!flags.path) {
+                const forwardedPath = await resolveForwardedLogPath(flags);
+                // A runtime that knows --rotated says this itself; an older one cannot.
+                if (!runtimeKnowsRotated && forwardedPath) {
+                    const hint = describeRotatedSiblings(forwardedPath, rotatedLogSiblings(forwardedPath));
+                    if (hint)
+                        this.logToStderr(hint);
+                }
+                showAge(forwardedPath);
+            }
             const code = await (0, exec_runtime_binary_1.execRuntimeBinary)(args);
             this.exit(code);
         }

package/dist/commands/followups/act.js

@@ -23,7 +23,10 @@ class FollowupsAct extends base_command_1.BaseCommand {
             required: true,
         }),
         at: core_1.Flags.string({ description: 'ISO-8601 instant to act at', exclusive: ['in'] }),
-        in: core_1.Flags.string({ description: 'Duration from now (2h, 3d)', exclusive: ['at'] }),
+        in: core_1.Flags.string({
+            description: 'Duration from now (2h, 3d), between 1m and 30d',
+            exclusive: ['at'],
+        }),
         agent: core_1.Flags.string({ description: 'Agent ID (default: bound session agent)' }),
         endpoint: core_1.Flags.string({ description: 'Delivery endpoint id (EndpointRegistry)' }),
         'endpoint-target': core_1.Flags.string({ description: 'Channel target for channel endpoints' }),
@@ -42,6 +45,15 @@ class FollowupsAct extends base_command_1.BaseCommand {
                 retryable: false,
             });
         }
+        const problem = (0, followups_1.whenFlagProblem)(flags.at ? 'at' : 'in', at);
+        if (problem) {
+            this.failWithCliError({
+                message: problem,
+                code: 'FOLLOWUP_INVALID_FIELD',
+                exit: 2,
+                retryable: false,
+            });
+        }
         const action = (0, triggers_1.parseJsonObject)(flags.action, '--action');
         if (typeof action?.builtinType !== 'string' || !action.builtinType) {
             this.failWithCliError({

package/dist/commands/followups/checkin.js

@@ -23,7 +23,7 @@ class FollowupsCheckin extends base_command_1.BaseCommand {
         subject: core_1.Flags.string({ description: followups_1.FOLLOWUP_SUBJECT_FLAG_HELP, required: true }),
         why: core_1.Flags.string({ description: 'Why this wake exists, in one line', required: true }),
         in: core_1.Flags.string({
-            description: 'Duration from now (90m, 2h) — the once form',
+            description: 'Duration from now (90m, 2h), between 1m and 30d — the once form',
             exclusive: ['frequency'],
         }),
         frequency: core_1.Flags.string({
@@ -64,6 +64,15 @@ class FollowupsCheckin extends base_command_1.BaseCommand {
                 retryable: false,
             });
         }
+        const problem = (0, followups_1.whenFlagProblem)('in', flags.in);
+        if (problem) {
+            this.failWithCliError({
+                message: problem,
+                code: 'FOLLOWUP_INVALID_FIELD',
+                exit: 2,
+                retryable: false,
+            });
+        }
         let agent;
         try {
             agent = (0, followups_1.resolveFollowUpAgent)(flags.agent);
@@ -106,7 +115,7 @@ class FollowupsCheckin extends base_command_1.BaseCommand {
         if (response.dropped && producer === 'user_explicit') {
             this.failWithCliError({
                 message: budgetRefusalMessage(agent.id, response.budget),
-                code: 'FOLLOWUP_BUDGET_EXHAUSTED',
+                code: 'FOLLOWUP_BUDGET_EXCEEDED',
                 exit: 1,
                 retryable: false,
                 details: { budget: response.budget ?? null, response },

package/dist/commands/followups/reschedule.js

@@ -15,7 +15,10 @@ class FollowupsReschedule extends base_command_1.BaseCommand {
     };
     static flags = {
         at: core_1.Flags.string({ description: 'New instant (ISO-8601)', exclusive: ['in'] }),
-        in: core_1.Flags.string({ description: 'New offset from now (90m, 2h)', exclusive: ['at'] }),
+        in: core_1.Flags.string({
+            description: 'New offset from now (90m, 2h); between 1m and 30d',
+            exclusive: ['at'],
+        }),
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
     };
     async run() {
@@ -30,6 +33,15 @@ class FollowupsReschedule extends base_command_1.BaseCommand {
                 retryable: false,
             });
         }
+        const problem = (0, followups_1.whenFlagProblem)(flags.at ? 'at' : 'in', at);
+        if (problem) {
+            this.failWithCliError({
+                message: problem,
+                code: 'FOLLOWUP_INVALID_FIELD',
+                exit: 2,
+                retryable: false,
+            });
+        }
         let result;
         try {
             result = (await followups_1.followupsApi.reschedule(args.id, { at }));

package/dist/commands/proposals/discard.d.ts

@@ -3,7 +3,7 @@ export default class ProposalsDiscard extends ProposalDecisionCommand {
     static description: string;
     static args: {
         kind: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
-        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        id: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static decision: "discard";
 }