@skrr-ai/cli 0.1.104 → 0.1.105

package/dist/commands/daemon/logs.d.ts

@@ -19,6 +19,7 @@ export interface DaemonLogsFlags {
     stderr?: boolean;
     path?: boolean;
     profile?: string;
+    rotated?: boolean;
 }
 /**
  * Older daemons already kept logs in this profile-scoped location, even
@@ -116,6 +117,37 @@ export declare function resolveForwardedLogPath(flags: Pick<DaemonLogsFlags, 'st
  * forwarding to the bug, so the CLI forwards only at or above this version.
  */
 export declare const 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.
+ */
+export declare const 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.
+ */
+export declare function rotatedLogSiblings(filePath: string, readdir?: (dir: string) => string[]): string[];
+/** The sentence shown when rotated siblings hold older lines the view leaves out. */
+export declare function describeRotatedSiblings(filePath: string, siblings: readonly string[]): string | null;
+/**
+ * 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.
+ */
+export declare function readLastLines(filePath: string, maxLines: number): string[];
+/**
+ * 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.
+ */
+export declare function readLastLinesAcross(files: readonly string[], maxLines: number): string[];
+/** Every byte of `files`, in order, to `out` — streamed, honouring back-pressure. */
+export declare function streamLogFiles(files: readonly string[], out: NodeJS.WritableStream): Promise<void>;
 /** `x.y.z` from a version string, or null. A prerelease suffix is ignored. */
 export declare function parseRuntimeVersion(text: string): [number, number, number] | null;
 /** Whether `version` is at least `floor`; null when either is not a version. */
@@ -130,8 +162,11 @@ export declare function probeRuntimeVersion(capture?: typeof execRuntimeBinaryCa
  */
 export declare function probeStatusLogPath(flags: Pick<DaemonLogsFlags, 'profile'>, capture?: typeof execRuntimeBinaryCapture): Promise<string | null>;
 /** What `skrr daemon logs` does: forward to the runtime, or read a file itself. */
-export type DaemonLogsPlan = {
+export type DaemonLogsPlan = 
+/** `runtimeVersion` decides whether a flag newer than 0.8.119 may be forwarded. */
+{
     kind: 'forward';
+    runtimeVersion: string | null;
 }
 /** `note` goes to stderr before any log content; never printed for `--path`. */
  | {
@@ -171,13 +206,15 @@ export declare function readDaemonLogTail(filePath: string, maxLines: number): s
  * or it parses successfully and is then silently dropped.
  */
 export declare function buildDaemonLogsArgs(flags: DaemonLogsFlags): string[];
+/** `--stderr` help, word for word the runtime's own (`daemon/src/index.ts`). */
+export declare const 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";
 export default class DaemonLogs extends Command {
     static aliases: string[];
     static description: string;
     /**
-     * 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.
@@ -187,6 +224,7 @@ export default class DaemonLogs extends Command {
         lines: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         stderr: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         path: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        rotated: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         profile: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     static examples: string[];

package/dist/commands/daemon/logs.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIVE_LOG_RESOLUTION_RUNTIME_VERSION = void 0;
+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;
@@ -11,6 +11,11 @@ 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;
@@ -22,6 +27,7 @@ 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}$/;
@@ -188,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)
@@ -213,6 +221,119 @@ async function resolveForwardedLogPath(flags, capture = exec_runtime_binary_1.ex
  * 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);
@@ -300,13 +421,13 @@ async function planDaemonLogs(flags, deps) {
     }
     // Help could not be read: nothing to go on, keep the old behaviour.
     if (supports === null)
-        return { kind: 'forward' };
+        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' };
+        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 ` +
@@ -315,12 +436,12 @@ async function planDaemonLogs(flags, deps) {
             `${deps.profilePath} instead of the live log.`;
     if (!live) {
         if (current === null)
-            return { kind: 'forward' };
+            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' };
+        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) {
@@ -391,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
@@ -400,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.
@@ -414,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({
@@ -438,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() {
@@ -466,7 +602,7 @@ class DaemonLogs extends core_1.Command {
             // 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.
-            const plan = await planDaemonLogs(flags, {
+            let plan = await planDaemonLogs(flags, {
                 supportsLogs: () => (0, exec_runtime_binary_1.runtimeBinarySupportsSubcommand)('logs'),
                 runtimeVersion: () => probeRuntimeVersion(),
                 statusLogPath: () => probeStatusLogPath(flags),
@@ -481,22 +617,63 @@ class DaemonLogs extends core_1.Command {
                     }
                 },
             });
+            // 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;
-                // `--path` prints the one path and nothing else, on either stream.
+                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}. ${plan.missingHint}`, { exit: 1 });
                 }
-                const lines = readDaemonLogTail(logPath, flags.lines ?? 200);
-                if (lines.length > 0)
-                    this.log(lines.join('\n'));
+                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'));
+                }
                 if (flags.follow) {
                     let position = (0, node_fs_1.statSync)(logPath).size;
                     (0, node_fs_1.watchFile)(logPath, { interval: 500 }, () => {
@@ -528,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";
 }

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

@@ -3,7 +3,7 @@ export default class ProposalsKeep 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: "keep";
 }

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

@@ -1,4 +1,11 @@
 import { BaseCommand } from '../../base-command';
+/**
+ * What an empty page means. With a filter AND a next cursor it does NOT mean "none": the inbox reads a
+ * bounded page of each source and applies some filters (the Commitment, the kind of row) afterwards,
+ * so an unmatched id pages through every page of an 864-row inbox before the cursor ends (OSK-15369).
+ * Without a cursor the inbox is exhausted and "none" is true.
+ */
+export declare function emptyPageLines(narrowed: boolean, nextCursor: string | null | undefined): string[];
 export default class ProposalsList extends BaseCommand {
     static description: string;
     static flags: {

package/dist/commands/proposals/list.js

@@ -1,10 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyPageLines = emptyPageLines;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const proposals_1 = require("../../lib/proposals");
 const format_1 = require("../../lib/format");
+/**
+ * What an empty page means. With a filter AND a next cursor it does NOT mean "none": the inbox reads a
+ * bounded page of each source and applies some filters (the Commitment, the kind of row) afterwards,
+ * so an unmatched id pages through every page of an 864-row inbox before the cursor ends (OSK-15369).
+ * Without a cursor the inbox is exhausted and "none" is true.
+ */
+function emptyPageLines(narrowed, nextCursor) {
+    if (!nextCursor)
+        return [narrowed ? 'No proposals match.' : 'No proposals.'];
+    return narrowed
+        ? [
+            'No proposals on this page match your filter.',
+            'The inbox applies some filters after reading each page, so a later page can still match; ' +
+                'it may take many pages to be sure there is none. The cursor below continues.',
+        ]
+        : ['No proposals on this page; the cursor below continues.'];
+}
 /** A snoozed proposal reads `proposed` in its disposition; the wake time is what tells them apart. */
 function noteFor(row) {
     if (row.sourceStatus === 'snoozed' && row.snoozedUntil)
@@ -14,7 +32,7 @@ function noteFor(row) {
     return '—';
 }
 class ProposalsList extends base_command_1.BaseCommand {
-    static description = 'List the bounded proposal inbox and source coverage';
+    static description = "List the bounded proposal inbox and source coverage. BASIS is how the proposal's own cost/benefit estimate was established (agent_estimate, human_confirmed or measured); — means it carries none.";
     static flags = {
         json: core_1.Flags.boolean(),
         kind: core_1.Flags.string({ options: [...data_provider_1.PROPOSAL_KINDS] }),
@@ -23,7 +41,11 @@ class ProposalsList extends base_command_1.BaseCommand {
         'agent-id': core_1.Flags.string(),
         limit: core_1.Flags.integer({ min: 1, max: 100, default: 50 }),
         cursor: core_1.Flags.string(),
-        sort: core_1.Flags.string({ options: ['recent', 'value'], default: 'recent' }),
+        sort: core_1.Flags.string({
+            options: ['recent', 'value'],
+            default: 'recent',
+            description: 'recent: newest first, page by page through every source. value: rows you can decide now first, then by estimated savings per effort hour (risk-discounted; a row with no estimate after every row that has one), then newest. value ranks one bounded window and is not exhaustive.',
+        }),
     };
     async run() {
         this.requireAuth();
@@ -47,13 +69,17 @@ class ProposalsList extends base_command_1.BaseCommand {
             this.log(JSON.stringify(result, null, 2));
             return;
         }
-        if (!result.data.length)
-            this.log('No proposals returned on this page.');
+        if (!result.data.length) {
+            const narrowed = Boolean(flags.kind || flags.disposition || flags['commitment-id'] || flags['agent-id']);
+            for (const line of emptyPageLines(narrowed, result.nextCursor))
+                this.log(line);
+        }
         (0, format_1.renderTable)(result.data.map((row) => ({
             id: row.id,
             title: row.title,
             disposition: row.disposition,
-            basis: row.economics?.basis || 'unknown',
+            // Most proposals carry no estimate; "unknown" read as a failure to determine one (OSK-15377).
+            basis: row.economics?.basis || '—',
             deadline: row.deadline || '—',
             note: noteFor(row),
         })), [

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

@@ -1,9 +1,10 @@
 import { BaseCommand } from '../../base-command';
 export default class ProposalsShow extends BaseCommand {
     static description: string;
+    static examples: 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 flags: {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;