@skrr-ai/cli 0.1.108 → 0.1.110

package/README.md

@@ -1780,8 +1780,18 @@ sky tasks retry-schedule <task-id> --at 2026-06-02T15:00:00Z
 # Pause / resume a recurring schedule without losing its definition
 sky tasks pause-schedule <task-id>
 sky tasks resume-schedule <task-id>
+
+# A finished occurrence whose next occurrence was never armed (`tasks show` says
+# "The next occurrence was not scheduled: ..."): continue the series from it.
+# `tasks schedule` refuses a finished Task; this is the way back. --cron fixes an
+# invalid pattern first.
+skrr tasks rearm-recurrence <finished-task-id>
+skrr tasks rearm-recurrence <finished-task-id> --cron "0 9 * * 1-5"
 ```
 
+A pattern is validated when it is written: `--cron nonsense` is refused with the
+expected format and an example, never stored and armed at some other time.
+
 Pass `--from-json schedule.json` to `schedule` for fields not exposed as
 typed flags (matches the `TaskScheduleParams` shape).
 

package/dist/base-command.d.ts

@@ -1,5 +1,7 @@
 import { Command, Flags, type Interfaces } from '@oclif/core';
 export { resolveProfileFromArgv } from './lib/keychain';
+import { dataService } from '@skrr-ai/data-provider';
+import { type WriteTarget } from './lib/write-target';
 import { type AssigneeResolution, type MemberKind, type SpaceMember } from './lib/assignee-resolver';
 import { type CliConfig } from './lib/config';
 import { type OutboxMethod } from './lib/outbox';
@@ -59,6 +61,24 @@ export declare abstract class BaseCommand extends Command {
      */
     log(message?: string, ...args: unknown[]): void;
     protected wantsRawJson(): boolean;
+    /**
+     * Print a command's `--json` RESULT: pretty JSON, with `ok` on an object so a
+     * script can test one field for success and failure alike (OSK-16425).
+     *
+     * A failure already prints `{ok:false, error}`; a success printed whatever the
+     * server sent, so `jq '{id, title}'` turned the failure into `{id:null,
+     * title:null}` — an empty success. `ok` is added HERE, by the command that
+     * knows its own outcome, and not in `log()`: `log` cannot see the exit status
+     * to come, and several commands print a document and then exit non-zero.
+     * Pass `{ ok: false }` for one of those; the command still owns its exit code.
+     *
+     * An array is printed as it is (it cannot carry a field), and an object that
+     * already has `ok` keeps its own. The exit status stays the test for a command
+     * that has not been moved here yet.
+     */
+    protected printJsonResult(value: unknown, options?: {
+        ok?: boolean;
+    }): void;
     protected cliConfig: CliConfig;
     /**
      * Resolved credential for this process. Populated in `init()` and
@@ -220,6 +240,17 @@ export declare abstract class BaseCommand extends Command {
      * friendly error on any API failure, so callers can `await` it directly.
      */
     protected resolveCurrentUserId(): Promise<string>;
+    /**
+     * The signed-in user, read ONCE per command run.
+     *
+     * `me`, the default-assignee policy and the write-target notice all need it,
+     * and a command that touches many nodes (`create-tree` with ninety-four)
+     * asked for it once per node. Who you are does not change during one command,
+     * so one read answers every caller — and a failed read is not remembered, so a
+     * transient error does not poison the rest of the run.
+     */
+    private currentUserRead?;
+    protected fetchCurrentUser(): Promise<Awaited<ReturnType<typeof dataService.getUser>>>;
     /**
      * Decide who owns a task this invocation is creating, when the caller did
      * not say.
@@ -249,6 +280,27 @@ export declare abstract class BaseCommand extends Command {
      * worse, resolve a typo to a stranger the caller never intended to name.
      */
     protected loadSpaceMembers(spaceId: string): Promise<SpaceMember[]>;
+    /** Lazily created: a command built without its constructor (specs do) must still work. */
+    private spaceMemberReads?;
+    /**
+     * Where a write from this invocation is about to land: the signed-in account,
+     * the server and the workspace. Best effort on the account (a failed read
+     * leaves it null and the line says so) — it is a statement, not a gate; the
+     * gate is `assertWriteTarget`.
+     */
+    protected describeWriteTarget(): Promise<WriteTarget>;
+    /**
+     * Say where a bulk write is about to land, and refuse if the caller said it
+     * should land somewhere else.
+     *
+     * The line goes to stderr and only when stderr is a person's terminal: an
+     * agent capturing `2>&1` gets no extra bytes (the update nudge taught that
+     * lesson), and gets the same facts in-band instead — the commands that call
+     * this put `target` in their `--json`. `--expect-target` is the control for a
+     * caller that cannot watch: it is checked HERE, before the first write, and a
+     * mismatch is a non-retryable usage error.
+     */
+    protected assertWriteTarget(expected?: readonly string[]): Promise<WriteTarget>;
     /**
      * Turn free-text assignee references ("frank", "frank@example.com", "me",
      * or a raw id) into ids, failing the command if ANY of them can't be pinned
@@ -316,6 +368,13 @@ export declare abstract class BaseCommand extends Command {
      * subject is folded into the message, so the human line and the `--json`
      * envelope carry the same identifying text.
      */
+    /**
+     * Request body paths this invocation built from its flags, each mapped to the flag that wrote
+     * it. Set by a command before it sends a body it assembled from flags, and left unset when the
+     * person supplied the body themselves; `handleApiError` uses it to name the flag instead of a
+     * path the person never typed. See `lib/request-field-flags.ts`.
+     */
+    protected requestFieldFlags?: Readonly<Record<string, string>>;
     protected handleApiError(err: unknown, { subject }?: {
         subject?: string;
     }): never;
@@ -526,6 +585,21 @@ export declare function isTypedServerRefusal(body: Record<string, unknown> | nul
  */
 export declare function isApplicationCodedUnavailable(status: number | undefined, body: Record<string, unknown> | null): boolean;
 export declare function isRetryableFailure(status: number | undefined, body: Record<string, unknown> | null): boolean;
+/**
+ * The `details` of a CLI error envelope, in ONE shape. The server's refusal body becomes the
+ * envelope's details; when that body carries its own `details` object (a typed refusal's
+ * findings, e.g. `signalableNodeKeys`), those fields are lifted to the same level instead of
+ * arriving as `error.details.details`, a depth no other error used (OSK-16494). A body without
+ * a nested object is passed through unchanged.
+ */
+export declare function envelopeDetails(body: Record<string, unknown> | null | undefined): unknown;
+/**
+ * The hint for a `Nonexistent flags:` refusal, or null. Two cases:
+ *  - a flag retired from THIS command, which this command does not define again: where it went;
+ *  - a flag token holding a space (`"--outcome failed"` passed as one argument): what happened,
+ *    which oclif reports only as an unknown flag.
+ */
+export declare function retiredFlagHint(message: string, commandId?: string, definedFlags?: readonly string[]): string | null;
 /**
  * P6: a parse error used to say what was wrong and drop the remedy that text
  * mode (and every domain error) carries. Adds `fix` (one imperative line an

package/dist/base-command.js

@@ -17,12 +17,16 @@ exports.describeDaemonScopedCredential = describeDaemonScopedCredential;
 exports.isTypedServerRefusal = isTypedServerRefusal;
 exports.isApplicationCodedUnavailable = isApplicationCodedUnavailable;
 exports.isRetryableFailure = isRetryableFailure;
+exports.envelopeDetails = envelopeDetails;
+exports.retiredFlagHint = retiredFlagHint;
 exports.parseErrorRemedy = parseErrorRemedy;
 const node_fs_1 = require("node:fs");
 const core_1 = require("@oclif/core");
 Object.defineProperty(exports, "Flags", { enumerable: true, get: function () { return core_1.Flags; } });
 const option_hint_1 = require("./lib/option-hint");
+const request_field_flags_1 = require("./lib/request-field-flags");
 const json_output_1 = require("./lib/json-output");
+const json_mode_1 = require("./lib/json-mode");
 const failed_lookup_1 = require("./lib/failed-lookup");
 const internal_id_1 = require("./lib/internal-id");
 const http_error_1 = require("./lib/http-error");
@@ -36,6 +40,7 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const auth_core_1 = require("@skrr-ai/auth-core");
 const auth_failure_1 = require("./lib/auth-failure");
 const list_output_1 = require("./lib/list-output");
+const write_target_1 = require("./lib/write-target");
 const assignee_resolver_1 = require("./lib/assignee-resolver");
 const task_ref_resolver_1 = require("./lib/task-ref-resolver");
 const space_resolver_1 = require("./lib/space-resolver");
@@ -176,6 +181,24 @@ class BaseCommand extends core_1.Command {
     wantsRawJson() {
         return this.argv.includes('--raw') || process.env.OVERSKY_CLI_RAW === '1';
     }
+    /**
+     * Print a command's `--json` RESULT: pretty JSON, with `ok` on an object so a
+     * script can test one field for success and failure alike (OSK-16425).
+     *
+     * A failure already prints `{ok:false, error}`; a success printed whatever the
+     * server sent, so `jq '{id, title}'` turned the failure into `{id:null,
+     * title:null}` — an empty success. `ok` is added HERE, by the command that
+     * knows its own outcome, and not in `log()`: `log` cannot see the exit status
+     * to come, and several commands print a document and then exit non-zero.
+     * Pass `{ ok: false }` for one of those; the command still owns its exit code.
+     *
+     * An array is printed as it is (it cannot carry a field), and an object that
+     * already has `ok` keeps its own. The exit status stays the test for a command
+     * that has not been moved here yet.
+     */
+    printJsonResult(value, options = {}) {
+        this.log(JSON.stringify((0, json_output_1.withOk)(value, options.ok ?? true), null, 2));
+    }
     cliConfig;
     /**
      * Resolved credential for this process. Populated in `init()` and
@@ -928,7 +951,7 @@ class BaseCommand extends core_1.Command {
     async resolveCurrentUserId() {
         let user;
         try {
-            user = await data_provider_1.dataService.getUser();
+            user = await this.fetchCurrentUser();
         }
         catch (err) {
             this.handleApiError(err);
@@ -941,6 +964,25 @@ class BaseCommand extends core_1.Command {
         }
         return user.id;
     }
+    /**
+     * The signed-in user, read ONCE per command run.
+     *
+     * `me`, the default-assignee policy and the write-target notice all need it,
+     * and a command that touches many nodes (`create-tree` with ninety-four)
+     * asked for it once per node. Who you are does not change during one command,
+     * so one read answers every caller — and a failed read is not remembered, so a
+     * transient error does not poison the rest of the run.
+     */
+    currentUserRead;
+    fetchCurrentUser() {
+        if (!this.currentUserRead) {
+            this.currentUserRead = data_provider_1.dataService.getUser().catch((err) => {
+                this.currentUserRead = undefined;
+                throw err;
+            });
+        }
+        return this.currentUserRead;
+    }
     /**
      * Decide who owns a task this invocation is creating, when the caller did
      * not say.
@@ -979,6 +1021,12 @@ class BaseCommand extends core_1.Command {
      * worse, resolve a typo to a stranger the caller never intended to name.
      */
     async loadSpaceMembers(spaceId) {
+        // A space's roster does not change during one command; a tree of ninety-four
+        // nodes that name people read it ninety-four times.
+        const reads = (this.spaceMemberReads ??= new Map());
+        const cached = reads.get(spaceId);
+        if (cached)
+            return cached;
         let response;
         try {
             response = await data_provider_1.dataService.getResourcePermissions(data_provider_1.ResourceType.SPACE, spaceId);
@@ -987,7 +1035,67 @@ class BaseCommand extends core_1.Command {
             this.handleApiError(err);
         }
         const principals = (response.principals ?? []);
-        return (0, assignee_resolver_1.membersFromPrincipals)(principals);
+        const members = (0, assignee_resolver_1.membersFromPrincipals)(principals);
+        reads.set(spaceId, Promise.resolve(members));
+        return members;
+    }
+    /** Lazily created: a command built without its constructor (specs do) must still work. */
+    spaceMemberReads;
+    /**
+     * Where a write from this invocation is about to land: the signed-in account,
+     * the server and the workspace. Best effort on the account (a failed read
+     * leaves it null and the line says so) — it is a statement, not a gate; the
+     * gate is `assertWriteTarget`.
+     */
+    async describeWriteTarget() {
+        let user;
+        try {
+            user = await this.fetchCurrentUser();
+        }
+        catch {
+            user = undefined;
+        }
+        const workspace = process.env.OVERSKY_SESSION_WORKSPACE_ID?.trim() ||
+            process.env.OVERSKY_WORKSPACE_ID?.trim() ||
+            null;
+        return {
+            server: this.cliConfig?.baseURL ?? '',
+            account: user?.email ?? null,
+            accountId: user?.id ?? null,
+            workspace,
+        };
+    }
+    /**
+     * Say where a bulk write is about to land, and refuse if the caller said it
+     * should land somewhere else.
+     *
+     * The line goes to stderr and only when stderr is a person's terminal: an
+     * agent capturing `2>&1` gets no extra bytes (the update nudge taught that
+     * lesson), and gets the same facts in-band instead — the commands that call
+     * this put `target` in their `--json`. `--expect-target` is the control for a
+     * caller that cannot watch: it is checked HERE, before the first write, and a
+     * mismatch is a non-retryable usage error.
+     */
+    async assertWriteTarget(expected) {
+        const target = await this.describeWriteTarget();
+        const unmet = (0, write_target_1.firstUnmetExpectation)(target, expected);
+        if (unmet !== undefined) {
+            this.failWithCliError({
+                message: `Refusing to write: this command would write to ${(0, write_target_1.formatWriteTarget)(target)}, ` +
+                    `which does not match --expect-target ${unmet}. Nothing was created.`,
+                code: 'WRITE_TARGET_MISMATCH',
+                exit: 2,
+                retryable: false,
+                details: {
+                    suggestion: `Sign in to the intended account or server (\`${this.config.bin} login\`, \`${this.config.bin} whoami\`), or correct --expect-target.`,
+                    context: { target, expected: [...(expected ?? [])] },
+                },
+            });
+        }
+        if (process.stderr.isTTY) {
+            process.stderr.write(`Writing to ${(0, write_target_1.formatWriteTarget)(target)}\n`);
+        }
+        return target;
     }
     /**
      * Turn free-text assignee references ("frank", "frank@example.com", "me",
@@ -1085,7 +1193,7 @@ class BaseCommand extends core_1.Command {
         // so a caller following older instructions — including the managed block the
         // platform itself installed — got a bare `Nonexistent flags:` with no hint
         // that the capability moved rather than vanished. Name where each went.
-        const retiredHint = retiredFlagHint(err.message || '');
+        const retiredHint = retiredFlagHint(err.message || '', this.id, Object.keys(this.constructor.flags ?? {}));
         if (retiredHint) {
             err.message = `${err.message}\n\n${retiredHint}`;
         }
@@ -1170,6 +1278,13 @@ class BaseCommand extends core_1.Command {
      * subject is folded into the message, so the human line and the `--json`
      * envelope carry the same identifying text.
      */
+    /**
+     * Request body paths this invocation built from its flags, each mapped to the flag that wrote
+     * it. Set by a command before it sends a body it assembled from flags, and left unset when the
+     * person supplied the body themselves; `handleApiError` uses it to name the flag instead of a
+     * path the person never typed. See `lib/request-field-flags.ts`.
+     */
+    requestFieldFlags;
     handleApiError(err, { subject } = {}) {
         // An error this command already raised for the user is not an API failure
         // to translate. `this.error()` throws a CLIError carrying `oclif.exit`, and
@@ -1194,7 +1309,8 @@ class BaseCommand extends core_1.Command {
             this.lastRetryAfterMs = e.retryAfterMs;
             const body = parseErrorBody(e.body);
             const bodyCode = stringProp(body, 'code') || stringProp(body, 'errorType');
-            const bodyMessage = stringProp(body, 'message') || stringProp(body, 'error');
+            // A body path the person never typed is read back as the flag that wrote it (OSK-15313).
+            const bodyMessage = (0, request_field_flags_1.translateRequestFieldPaths)(stringProp(body, 'message') || stringProp(body, 'error'), this.requestFieldFlags);
             // `requireAuth()` catches this before requests for normal commands, but
             // keep the API-error check too: a handful of commands make a direct
             // request and a supplied `--token` can bypass their normal preflight.
@@ -1222,7 +1338,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 2,
                     retryable: false,
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                 });
             }
             else if (bodyCode === 'AGENT_RUNTIME_UNAVAILABLE') {
@@ -1236,7 +1352,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 1,
                     retryable: false,
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                 });
             }
             else if (bodyCode === 'GITHUB_APP_NOT_CONFIGURED') {
@@ -1246,7 +1362,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 2,
                     retryable: false,
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                 });
             }
             else if (bodyCode === 'GITHUB_UNAVAILABLE') {
@@ -1262,7 +1378,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 5,
                     retryable: true,
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                 });
             }
             else if (bodyCode === 'LABEL_SUGGESTION_UNAVAILABLE') {
@@ -1276,7 +1392,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 1,
                     retryable: false,
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                 });
             }
             else if (bodyCode === 'ASSIGNEE_NOT_IN_SPACE') {
@@ -1289,7 +1405,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 2,
                     retryable: false,
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                 });
             }
             else if (e.status === 401) {
@@ -1438,6 +1554,10 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 4,
                     retryable: false,
+                    // A typed 404 carries what the server found (a workflow signal names the nodes it CAN
+                    // resolve); dropping the body here made the 404 the one refusal with no machine-readable
+                    // details while every 409 kept them (OSK-16473).
+                    ...(body ? { details: envelopeDetails(body) } : {}),
                 });
             }
             else if (e.code === 'ECONNREFUSED' ||
@@ -1470,7 +1590,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 1,
                     retryable: isRetryableFailure(e.status, body),
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                     requestId: stringProp(body, 'requestId') || e.requestId,
                 });
             }
@@ -1509,7 +1629,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: retryable ? 5 : 1,
                     retryable,
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                     ...(requestId ? { requestId } : {}),
                 });
             }
@@ -1547,7 +1667,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 5,
                     retryable: true,
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                 });
             }
             else if (typeof e.status === 'number' && e.status >= 500) {
@@ -1575,7 +1695,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 1,
                     retryable: isRetryableFailure(e.status, body),
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                 });
             }
             else {
@@ -1585,7 +1705,7 @@ class BaseCommand extends core_1.Command {
                     status: e.status,
                     exit: 1,
                     retryable: isRetryableFailure(e.status, body),
-                    details: body ?? undefined,
+                    details: envelopeDetails(body),
                 });
             }
         }
@@ -1817,10 +1937,7 @@ class BaseCommand extends core_1.Command {
             process.stderr.write(`${line}\n`);
     }
     wantsJsonOutput() {
-        return (this.argv.includes('--json') ||
-            this.argv.includes('--ndjson') ||
-            process.env.SKY_JSON === '1' ||
-            process.env.OVERSKY_CLI_JSON === '1');
+        return (0, json_mode_1.wantsJsonFromArgv)(this.argv);
     }
 }
 exports.BaseCommand = BaseCommand;
@@ -2343,13 +2460,54 @@ const RETIRED_FLAG_REPLACEMENTS = {
         '`tasks deliverable add`.',
     '--supersede': '--supersede is implicit: submitting again creates a new Result version.',
 };
-function retiredFlagHint(message) {
+/**
+ * The `details` of a CLI error envelope, in ONE shape. The server's refusal body becomes the
+ * envelope's details; when that body carries its own `details` object (a typed refusal's
+ * findings, e.g. `signalableNodeKeys`), those fields are lifted to the same level instead of
+ * arriving as `error.details.details`, a depth no other error used (OSK-16494). A body without
+ * a nested object is passed through unchanged.
+ */
+function envelopeDetails(body) {
+    if (!body)
+        return undefined;
+    const nested = body.details;
+    if (!nested || typeof nested !== 'object' || Array.isArray(nested))
+        return body;
+    const { details: _nested, ...rest } = body;
+    return { ...rest, ...nested };
+}
+/**
+ * The commands those flags were retired FROM. The table was applied to every command, so a
+ * mis-quoted `"--outcome failed"` on `triggers audit` (where --outcome is a live flag) was told
+ * "--outcome is now --summary" (OSK-16494). A rename is a fact about one command.
+ */
+const RETIRED_FLAG_COMMANDS = new Set(['tasks:complete', 'tasks:result:submit']);
+/**
+ * The hint for a `Nonexistent flags:` refusal, or null. Two cases:
+ *  - a flag retired from THIS command, which this command does not define again: where it went;
+ *  - a flag token holding a space (`"--outcome failed"` passed as one argument): what happened,
+ *    which oclif reports only as an unknown flag.
+ */
+function retiredFlagHint(message, commandId, definedFlags = []) {
     if (!/nonexistent flag/i.test(message))
         return null;
-    const hits = Object.keys(RETIRED_FLAG_REPLACEMENTS).filter((flag) => new RegExp(`${flag}(?![\\w-])`).test(message));
-    if (hits.length === 0)
-        return null;
-    return hits.map((flag) => `  ${RETIRED_FLAG_REPLACEMENTS[flag]}`).join('\n');
+    const lines = [];
+    const quoted = /(?:^|[\s,:])(--[a-z][\w-]*)[ =]([^\s,][^,\n]*)/i.exec(message.slice(message.search(/nonexistent flag/i)));
+    const quotedFlag = quoted?.[1];
+    if (quotedFlag && definedFlags.includes(quotedFlag.replace(/^--/, ''))) {
+        lines.push(`  "${quoted[0].trim()}" reached the command as ONE argument, so it was read as a flag named ` +
+            `"${quoted[0].trim()}". Pass the flag and its value separately: ${quotedFlag} ${quoted[2].trim()}`);
+    }
+    if (commandId && RETIRED_FLAG_COMMANDS.has(commandId)) {
+        for (const flag of Object.keys(RETIRED_FLAG_REPLACEMENTS)) {
+            if (definedFlags.includes(flag.replace(/^--/, '')))
+                continue;
+            if (new RegExp(`${flag}(?![\\w-])`).test(message)) {
+                lines.push(`  ${RETIRED_FLAG_REPLACEMENTS[flag]}`);
+            }
+        }
+    }
+    return lines.length ? lines.join('\n') : null;
 }
 /**
  * P6: a parse error used to say what was wrong and drop the remedy that text

package/dist/commands/agents/triggers/create.js

@@ -76,7 +76,7 @@ class AgentsTriggersCreate extends base_command_1.BaseCommand {
             description: 'ISO-8601 datetime after which a schedule stops firing (--kind schedule)',
         }),
         'stale-catchup-ms': core_1.Flags.integer({
-            description: 'How late a missed occurrence may still run, in ms (a positive number). After downtime, an occurrence more than this overdue is skipped rather than run late, and the schedule moves to its next future slot. Unset: 3600000 (1 hour).',
+            description: 'How late a missed occurrence may still run, in ms, from 1000 (1 second) to 31622400000 (366 days). After downtime, an occurrence more than this overdue is skipped rather than run late, and the schedule moves to its next future slot. Unset: 3600000 (1 hour).',
         }),
         // once
         at: core_1.Flags.string({

package/dist/commands/agents/triggers/update.js

@@ -63,7 +63,7 @@ class AgentsTriggersUpdate extends base_command_1.BaseCommand {
             description: 'ISO-8601 datetime after which a schedule stops firing',
         }),
         'stale-catchup-ms': core_1.Flags.integer({
-            description: 'How late a missed occurrence may still run, in ms (a positive number). After downtime, an occurrence more than this overdue is skipped rather than run late, and the schedule moves to its next future slot. Unset: 3600000 (1 hour).',
+            description: 'How late a missed occurrence may still run, in ms, from 1000 (1 second) to 31622400000 (366 days). After downtime, an occurrence more than this overdue is skipped rather than run late, and the schedule moves to its next future slot. Unset: 3600000 (1 hour).',
         }),
         at: core_1.Flags.string({ description: 'ISO-8601 datetime for once triggers' }),
         entity: core_1.Flags.string({

package/dist/commands/agents/update.d.ts

@@ -1,3 +1,4 @@
+import { type AgentWriteReceipt } from '@skrr-ai/data-provider';
 import { BaseCommand } from '../../base-command';
 export default class AgentsUpdate extends BaseCommand {
     static description: string;
@@ -72,9 +73,33 @@ export default class AgentsUpdate extends BaseCommand {
  *   through `--from-json` was reported as "not an agent field" after the server
  *   had cleared it on purpose (OSK-12167).
  *
+ * All of that is the fallback for a server that predates `writeReceipt`. When
+ * the response carries a receipt, the server's own account of each key is used
+ * instead and nothing is inferred from the response's shape (OSK-15070).
+ *
  * Exported for tests.
  */
 export declare function agentUpdateWarnings(payload: Record<string, unknown>, updated: unknown): string[];
+/**
+ * The Agent row inside an update reply: the reply itself for an ordinary
+ * PATCH, `agent` inside the Always-On control envelope, or null when the
+ * control reply carries none (a PATCH of `isAlwaysOn` alone). Exported for tests.
+ */
+export declare function agentRowFromUpdate(updated: unknown): Record<string, unknown> | null;
+/**
+ * One line for an `isAlwaysOn` write, from the receipt: applied, or already in
+ * that state so nothing changed (OSK-16477). Exported for tests.
+ */
+export declare function alwaysOnReceiptLine(payload: Record<string, unknown>, updated: unknown): string | null;
+/**
+ * Warnings from the server's `writeReceipt` (OSK-15070). The receipt names
+ * every key the write saw as applied (and through which control: the legacy
+ * `isAlwaysOn` goes to the Always-On control and is applied, not "not kept") or
+ * ignored with a reason. A sent key it does not mention never reached the write.
+ *
+ * Exported for tests.
+ */
+export declare function writeReceiptWarnings(payload: Record<string, unknown>, receipt: AgentWriteReceipt): string[];
 /**
  * The per-Agent mutation fence's "another request holds this right now"
  * refusals. `updateAgent` takes a short lease on the Agent before it writes, so