@skrr-ai/cli 0.1.39 → 0.1.40

package/README.md

@@ -38,7 +38,7 @@ observability), and shared links.
 | **spaces widgets**                    | `list`, `add`, `remove`                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **spaces skills**                     | `list`, `add`, `remove`, `pin`                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | **spaces labels**                     | `list`, `add`, `remove` (attach/detach; filter with `spaces list --label`)                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| **labels**                            | `list`, `palette`, `create`, `update`, `archive`, `restore`, `delete`, `reorder` (unified labels across `user`, `space`, and `workspace` scopes)                                                                                                                                                                                                                                                                                                                                                      |
+| **labels**                            | `list`, `palette`, `create`, `update`, `archive`, `restore`, `delete`, `reorder` (unified labels across `user` and `workspace` scopes)                                                                                                                                                                                                                                                                                                                                                       |
 | **chats triggers**                    | `show`, `set`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | **dm**                                | `list`, `show`, `messages`, `threads`, `thread show/messages/follow/mute/share`, `send` (agent 1:1 main chat and Slack-style Thread controls)                                                                                                                                                                                                                                                                                                                                                         |
 | **diagnostics**                       | `context`, `doctor`, `usage`, `commands` (agent-friendly runtime identity, readiness, progressive token-budgeted discovery, and complete machine-readable schemas)                                                                                                                                                                                                                                                                                                                                    |

package/dist/base-command.js

@@ -16,6 +16,7 @@ exports.isTypedServerRefusal = isTypedServerRefusal;
 exports.isRetryableFailure = isRetryableFailure;
 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 failed_lookup_1 = require("./lib/failed-lookup");
 // Re-exported from its home in `lib/keychain`, beside the other profile
 // functions. It lived here while `init()` was its only caller; a lib module
@@ -788,6 +789,13 @@ class BaseCommand extends core_1.Command {
         if (retiredHint) {
             err.message = `${err.message}\n\n${retiredHint}`;
         }
+        // Sibling domains spell one lifecycle differently (`in_progress` for a
+        // space, `active` for a goal), and oclif's enum refusal named neither the
+        // difference nor the value to use (OSK-9735).
+        const optionHint = (0, option_hint_1.invalidOptionHint)(err.message || '');
+        if (optionHint) {
+            err.message = `${err.message}\n\n${optionHint}`;
+        }
         if (this.wantsJsonOutput()) {
             const exit = err.exitCode ?? err.oclif?.exit ?? 1;
             process.exitCode = exit;

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

@@ -64,6 +64,13 @@ export declare function agentCreateMissingFields(payload: Record<string, unknown
  * a failed create would be worse than the silence.
  */
 export declare function unappliedPayloadKeys(sent: Record<string, unknown>, created: unknown, ignore?: readonly string[]): string[];
+/**
+ * Why a key can come back missing. Both readings are live: a typo of a real
+ * field (`max_turns` for `maxTurns`), and a real field only the server sets
+ * (`nativeRole`, `author`). Naming only the first told a caller who had tried
+ * to claim a platform role that they had misspelled something.
+ */
+export declare function unappliedPayloadKeysWarning(keys: readonly string[]): string;
 export declare function backgroundLoopLines(agentId: string, relationshipLoopsSkipped: boolean): string[];
 export default class AgentsCreate extends BaseCommand {
     static description: string;

package/dist/commands/agents/create.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.agentCreateMissingFieldsMessage = agentCreateMissingFieldsMessage;
 exports.agentCreateMissingFields = agentCreateMissingFields;
 exports.unappliedPayloadKeys = unappliedPayloadKeys;
+exports.unappliedPayloadKeysWarning = unappliedPayloadKeysWarning;
 exports.backgroundLoopLines = backgroundLoopLines;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
@@ -105,6 +106,17 @@ function unappliedPayloadKeys(sent, created, ignore = []) {
         .filter((key) => !Object.prototype.hasOwnProperty.call(back, key))
         .sort();
 }
+/**
+ * Why a key can come back missing. Both readings are live: a typo of a real
+ * field (`max_turns` for `maxTurns`), and a real field only the server sets
+ * (`nativeRole`, `author`). Naming only the first told a caller who had tried
+ * to claim a platform role that they had misspelled something.
+ */
+function unappliedPayloadKeysWarning(keys) {
+    const one = keys.length === 1;
+    return (`The server did not keep ${keys.join(', ')}: ${one ? 'it is not an agent field' : 'they are not agent fields'}, ` +
+        `or only the server sets ${one ? 'it' : 'them'}. \`skrr agents show <id> --json\` shows what the agent stores.`);
+}
 function backgroundLoopLines(agentId, relationshipLoopsSkipped) {
     if (relationshipLoopsSkipped) {
         return [
@@ -368,7 +380,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
         // Agent document field and is intentionally absent from the response.
         const unapplied = unappliedPayloadKeys(payload, created, ['relationshipLoops']);
         if (unapplied.length > 0) {
-            this.warn(`The server did not keep ${unapplied.join(', ')} — ${unapplied.length === 1 ? 'that field is' : 'those fields are'} not part of the agent it created. Check \`skrr agents show <id> --json\`.`);
+            this.warn(unappliedPayloadKeysWarning(unapplied));
         }
         if (flags.json) {
             this.log(JSON.stringify((0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, created), null, 2));

package/dist/commands/agents/triggers/policy.d.ts

@@ -15,6 +15,7 @@ export default class AgentsTriggersPolicy extends BaseCommand {
         'max-per-hour': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'working-hours': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'quiet-hours': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'followup-budget': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

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

@@ -8,6 +8,28 @@ const triggers_1 = require("../../../lib/triggers");
 // used to carry its own copy that stopped one rung short, so `auto_run` was
 // accepted by the API and unreachable from the CLI.
 const data_provider_1 = require("@skrr-ai/data-provider");
+/** `watch=10 checkin=default` → `{ watch: 10, checkin: null }`; the server validates the pools. */
+function parseFollowUpBudget(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const budget = {};
+    for (const entry of (0, triggers_1.splitRepeated)(values) ?? []) {
+        const [pool, raw] = entry.split('=');
+        if (!pool || raw === undefined || raw === '') {
+            throw new Error(`--followup-budget expects pool=count, got "${entry}"`);
+        }
+        if (raw === 'default') {
+            budget[pool] = null;
+            continue;
+        }
+        const count = Number(raw);
+        if (!Number.isInteger(count) || count < 0) {
+            throw new Error(`--followup-budget ${pool} must be a non-negative integer or "default"`);
+        }
+        budget[pool] = count;
+    }
+    return budget;
+}
 class AgentsTriggersPolicy extends base_command_1.BaseCommand {
     static description = "Show or update an agent's initiative policy for agent-scoped triggers";
     static examples = [
@@ -38,6 +60,10 @@ class AgentsTriggersPolicy extends base_command_1.BaseCommand {
         'max-per-hour': core_1.Flags.integer({ description: 'Agent initiative hourly fire cap' }),
         'working-hours': core_1.Flags.string({ description: 'Policy workingHours JSON object' }),
         'quiet-hours': core_1.Flags.string({ description: 'Policy quietHours JSON object' }),
+        'followup-budget': core_1.Flags.string({
+            description: 'Daily follow-up creation cap for this agent, as pool=count (pools: watch, checkin, act; count "default" clears it). Repeatable',
+            multiple: true,
+        }),
     };
     async run() {
         this.requireAuth();
@@ -52,6 +78,7 @@ class AgentsTriggersPolicy extends base_command_1.BaseCommand {
                 maxPerHour: flags['max-per-hour'],
                 workingHours: (0, triggers_1.parseJsonObject)(flags['working-hours'], '--working-hours'),
                 quietHours: (0, triggers_1.parseJsonObject)(flags['quiet-hours'], '--quiet-hours'),
+                followUpBudget: parseFollowUpBudget(flags['followup-budget']),
             });
         }
         catch (err) {
@@ -77,6 +104,11 @@ class AgentsTriggersPolicy extends base_command_1.BaseCommand {
         this.log(`Allowed kinds:    ${Array.isArray(policy.allowedKinds) ? policy.allowedKinds.join(', ') : '-'}`);
         this.log(`Max fires/day:    ${String(policy.maxFiresPerDay ?? '-')}`);
         this.log(`Max/hour:         ${String(policy.maxPerHour ?? '-')}`);
+        const followUpBudget = policy.followUpBudget;
+        const budgetEntries = Object.entries(followUpBudget ?? {}).filter(([, v]) => v != null);
+        this.log(`Follow-up caps:   ${budgetEntries.length > 0
+            ? budgetEntries.map(([pool, cap]) => `${pool} ${String(cap)}/day`).join(', ')
+            : 'defaults'}`);
         if (Object.keys(counts).length > 0) {
             this.log(`Triggers:         ${String(counts.total ?? 0)} total, ${String(counts.enabled ?? 0)} enabled`);
         }

package/dist/commands/agents/update.js

@@ -186,13 +186,14 @@ class AgentsUpdate extends base_command_1.BaseCommand {
             this.handleApiError(err);
         }
         // The same check `agents create` makes. Without it, a key the server does
-        // not model — or a typo of one that it does, `max_turns` for `maxTurns` —
-        // was discarded with the same "Updated agent" line as a real change.
+        // not model, a typo of one that it does (`max_turns` for `maxTurns`), or a
+        // field only the server sets was discarded with the same "Updated agent"
+        // line as a real change.
         // `removeProjectIds` is an instruction, not a stored field, so it never
         // comes back and is not reported.
         const unapplied = (0, create_1.unappliedPayloadKeys)(payload, updated, ['removeProjectIds']);
         if (unapplied.length > 0) {
-            this.warn(`The server did not keep ${unapplied.join(', ')} — ${unapplied.length === 1 ? 'that field is' : 'those fields are'} not part of the agent. Check \`skrr agents show <id> --json\` for the field names it stores.`);
+            this.warn((0, create_1.unappliedPayloadKeysWarning)(unapplied));
         }
         if (flags.json) {
             this.log(JSON.stringify((0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, updated), null, 2));

package/dist/commands/followups/observability.js

@@ -24,7 +24,7 @@ const outcomes = (terminal) => Object.entries(terminal)
  * every agent only with `--all-agents`.
  */
 class FollowupsObservability extends base_command_1.BaseCommand {
-    static description = 'Per-agent, per-kind rollup — created, outcomes, escalation, budget, check-in silence';
+    static description = 'Per-agent, per-kind rollup — created, outcomes, escalation, spend, budget, check-in silence';
     static examples = [
         '<%= config.bin %> followups observability',
         '<%= config.bin %> followups observability --agent agent_1',
@@ -93,6 +93,9 @@ class FollowupsObservability extends base_command_1.BaseCommand {
                 outcomes: outcomes(kind.terminal),
                 escalated: rate(kind.escalationRate),
                 fires: String(kind.fires),
+                spend: kind.spend
+                    ? `$${kind.spend.today.toFixed(2)} / $${kind.spend.total.toFixed(2)}`
+                    : '—',
                 budget: kind.budget ? `${kind.budget.used}/${kind.budget.limit ?? '∞'}` : '—',
                 silence: rate(kind.silenceRate),
             })), [
@@ -104,11 +107,12 @@ class FollowupsObservability extends base_command_1.BaseCommand {
                 { key: 'outcomes', header: 'OUTCOMES' },
                 { key: 'escalated', header: 'ESCALATED' },
                 { key: 'fires', header: 'FIRES' },
+                { key: 'spend', header: 'SPENT TODAY/ALL' },
                 { key: 'budget', header: 'TODAY/LIMIT' },
                 { key: 'silence', header: 'SILENT' },
             ], (line) => this.log(line));
         });
-        this.log(`\nAs of ${report.generatedAt ?? 'now'}. TODAY/LIMIT is the daily budget (reminders are not metered); SILENT is how often a check-in chose to stay quiet.`);
+        this.log(`\nAs of ${report.generatedAt ?? 'now'}. SPENT is the agent turns these follow-ups woke (USD, today / all time); TODAY/LIMIT is the daily creation budget (reminders are not metered); SILENT is how often a check-in chose to stay quiet.`);
     }
 }
 exports.default = FollowupsObservability;

package/dist/commands/followups/remind.js

@@ -15,11 +15,14 @@ class FollowupsRemind extends base_command_1.BaseCommand {
     static description = 'Remind the owner at a time — the reminder follow-up';
     static examples = [
         '<%= config.bin %> followups remind --subject task:OSK-42 --content "pick the deploy up" --in 2h',
-        '<%= config.bin %> followups remind --subject conversation:conv_9 --content "ask how the move went" --at 2026-09-20T09:00:00Z',
+        '<%= config.bin %> followups remind --subject conversation:conv_9 --content "ask how the move went" --at 2026-09-20T09:00:00Z --active --agent agent_1',
         '<%= config.bin %> followups remind --subject task:OSK-42 --content "ping me" --at 2026-09-20T09:00:00Z --active --agent agent_1',
     ];
     static flags = {
-        subject: core_1.Flags.string({ description: 'Subject ref: type:externalKey', required: true }),
+        subject: core_1.Flags.string({
+            description: 'Subject ref: type:externalKey. A passive reminder attaches to a task, project, goal or wiki_page; use --active for a conversation',
+            required: true,
+        }),
         content: core_1.Flags.string({ description: "The reminder's own words", required: true }),
         at: core_1.Flags.string({ description: 'ISO-8601 instant to remind at', exclusive: ['in'] }),
         in: core_1.Flags.string({

package/dist/commands/followups/reschedule.js

@@ -42,7 +42,8 @@ class FollowupsReschedule extends base_command_1.BaseCommand {
             this.log(JSON.stringify(result, null, 2));
             return;
         }
-        this.log(`Follow-up ${args.id} rescheduled to ${at}.`);
+        const next = result.followup?.nextRunAt;
+        this.log(`Follow-up ${args.id} rescheduled to ${typeof next === 'string' ? next : at}.`);
     }
 }
 exports.default = FollowupsReschedule;

package/dist/commands/followups/show.js

@@ -35,6 +35,10 @@ class FollowupsShow extends base_command_1.BaseCommand {
             ['intent', row.intentKey],
             ['producer', row.producer],
             ['terminal', row.terminal ? `${row.terminal} (${row.terminalReason ?? '—'})` : undefined],
+            [
+                'settled',
+                row.terminal ? `${row.terminalAt ?? '—'} by ${row.terminalBy ?? 'unknown'}` : undefined,
+            ],
             ['deadline', row.deadlineAt],
             ['escalated to', row.escalatedInitiativeId],
         ]) {

package/dist/commands/followups/watch.d.ts

@@ -15,6 +15,7 @@ import { BaseCommand } from '../../base-command';
  *              cannot stop is a leak.
  */
 export default class FollowupsWatch extends BaseCommand {
+    static summary: string;
     static description: string;
     static examples: string[];
     static flags: {

package/dist/commands/followups/watch.js

@@ -21,7 +21,11 @@ const triggers_1 = require("../../lib/triggers");
  *              cannot stop is a leak.
  */
 class FollowupsWatch extends base_command_1.BaseCommand {
-    static description = 'Watch an asynchronous tail until it settles — the watch follow-up';
+    static summary = 'Watch an asynchronous tail until it settles — the watch follow-up';
+    static description = [
+        'Two forms, and they cost different amounts. Prefer the predicate form whenever the state is readable over HTTPS: --url + --until is evaluated by the server, wakes the agent once when the condition settles, and always ends at --deadline.',
+        "The recipe form (--check / --success / --abort) wakes the agent for one turn per check, and every turn counts against the agent's watch budget. Use it only for a check a predicate cannot express.",
+    ].join('\n\n');
     static examples = [
         '<%= config.bin %> followups watch --subject task:OSK-42 --why "deploy still running" --url https://ci.example.com/api/build/9 --until \'{"path":"status","op":"equals","value":"done"}\' --deadline 6h',
         '<%= config.bin %> followups watch --subject task:OSK-42 --why "pr review" --check "gh pr view 42 --json state" --success "state == MERGED" --abort "state == CLOSED" --wait event --wait-entity github --wait-event pull_request_merged --wait-fallback 2h',
@@ -34,7 +38,7 @@ class FollowupsWatch extends base_command_1.BaseCommand {
         // predicate form
         url: core_1.Flags.string({ description: 'HTTPS endpoint to observe (predicate form)' }),
         until: core_1.Flags.string({
-            description: 'Predicate tree as JSON (predicate form): a leaf {"path","op","value"} or {"all"|"any": [...]}. op is equals, not_equals, contains, starts_with, in, gt, lt, exists, … — an unknown op is refused with the full list',
+            description: 'Predicate tree as JSON (predicate form — the server evaluates it; no agent turn per check): a leaf {"path","op","value"} or {"all"|"any": [...]}. op is equals, not_equals, contains, starts_with, in, gt, lt, exists, … — an unknown op is refused with the full list',
         }),
         grant: core_1.Flags.string({ description: 'Grant id supplying the watch credentials' }),
         deadline: core_1.Flags.string({ description: 'When the watch must stop (predicate form, required)' }),
@@ -43,7 +47,9 @@ class FollowupsWatch extends base_command_1.BaseCommand {
         'root-path': core_1.Flags.string({ description: 'JSON root path inside the response' }),
         'resume-prompt': core_1.Flags.string({ description: 'What to tell the settling turn' }),
         // recipe form
-        check: core_1.Flags.string({ description: 'The deterministic check to run (recipe form)' }),
+        check: core_1.Flags.string({
+            description: 'The check the agent runs (recipe form) — every check wakes the agent for one turn, counted against the watch budget',
+        }),
         success: core_1.Flags.string({ description: 'What state means the wait resolved (recipe form)' }),
         abort: core_1.Flags.string({ description: 'When to stop and escalate (recipe form)' }),
         wait: core_1.Flags.string({

package/dist/commands/tasks/lifecycle/detach.js

@@ -43,11 +43,26 @@ class TasksLifecycleDetach extends base_command_1.BaseCommand {
                 return this.log('No lifecycle is attached to this Task — nothing to detach.');
             this.log(`Would detach ${lifecycle.packId ? `pack ${lifecycle.packId}` : `definition ${lifecycle.definitionId}`}` +
                 ` at generation ${lifecycle.generation}, stage ${lifecycle.currentStageKey ?? '—'}.`);
-            this.log('  The run is cancelled and kept as history; nothing already recorded is removed.');
-            this.log('  The generation is bumped, so no in-flight writer from the old run can land.');
+            if (lifecycle.runId) {
+                this.log('  The run is cancelled and kept as history; nothing already recorded is removed.');
+                this.log('  The generation is bumped, so no in-flight writer from the old run can land.');
+            }
+            else {
+                this.log('  It has not started, so there is no run to cancel.');
+            }
             this.log('  Re-attaching afterwards starts a NEW generation — it does not resume this one.');
             return;
         }
+        // The server clears runId on detach, so whether there WAS a run to cancel
+        // is only knowable before the write. Best-effort: a failed read must not
+        // block the detach, it only costs the sentence its precision.
+        let hadRun;
+        try {
+            hadRun = Boolean((await data_provider_1.dataService.getTaskLifecycle(taskId)).lifecycle?.runId);
+        }
+        catch {
+            hadRun = undefined;
+        }
         let response;
         try {
             response = await data_provider_1.dataService.detachTaskLifecycle({
@@ -62,9 +77,15 @@ class TasksLifecycleDetach extends base_command_1.BaseCommand {
             return this.log(JSON.stringify(response, null, 2));
         const lifecycle = response.lifecycle;
         // Name what changed. "Detached lifecycle from the Task." left the reader to
-        // diff the state afterwards to learn what had happened.
-        this.log(`Detached${lifecycle?.packId ? ` pack ${lifecycle.packId}` : ''} — the run is cancelled and` +
-            ` kept as history, and the binding is now generation ${lifecycle?.generation ?? '?'}` +
+        // diff the state afterwards to learn what had happened — and saying a run
+        // was cancelled when none had started is the same problem the other way.
+        const runSentence = hadRun === false
+            ? 'it had not started, so there was no run to cancel'
+            : hadRun
+                ? 'the run is cancelled and kept as history'
+                : 'any run is cancelled and kept as history';
+        this.log(`Detached${lifecycle?.packId ? ` pack ${lifecycle.packId}` : ''} — ${runSentence},` +
+            ` and the binding is now generation ${lifecycle?.generation ?? '?'}` +
             ` (${lifecycle?.status ?? 'detached'}).`);
         this.log('Re-attach with: skrr tasks lifecycle attach <task-id> --pack <pack>');
     }

package/dist/lib/dedicated-lease-command.js

@@ -127,7 +127,10 @@ class DedicatedLeaseCommand extends base_command_1.BaseCommand {
             return await fn();
         }
         catch (err) {
-            const message = (0, dedicated_machines_1.formatDedicatedRuntimeApiError)(err);
+            const message = (0, dedicated_machines_1.formatDedicatedRuntimeApiError)(err, {
+                command: this.id,
+                bin: this.config.bin,
+            });
             if (message) {
                 this.failWithCliError({
                     message,

package/dist/lib/dedicated-machines.d.ts

@@ -643,5 +643,12 @@ export declare function dedicatedRuntimeApiErrorCode(err: unknown): string | und
  * second list would only drift from the first.
  */
 export declare function dedicatedRuntimeApiErrorDetails(err: unknown): Record<string, unknown> | undefined;
-export declare function formatDedicatedRuntimeApiError(err: unknown): string | null;
+/** What a refused command knows about itself, so advice can be one it can follow. */
+export interface DedicatedApiErrorContext {
+    /** oclif command id, e.g. `machines:dedicated:create`. */
+    command?: string;
+    bin?: string;
+    leaseId?: string;
+}
+export declare function formatDedicatedRuntimeApiError(err: unknown, context?: DedicatedApiErrorContext): string | null;
 export {};

package/dist/lib/dedicated-machines.js

@@ -1134,9 +1134,9 @@ function dedicatedRuntimeApiErrorDetails(err) {
  * say nothing to the person running it (OSK-8768); `--json` keeps them in
  * `error.details.reasons`.
  */
-function describeRefusalReasons(err) {
+function describeRefusalReasons(err, context = {}) {
     const details = dedicatedRuntimeApiErrorDetails(err);
-    const spend = describeSpendingCapRefusal(err.body, details);
+    const spend = describeSpendingCapRefusal(err.body, details, context);
     if (spend)
         return spend;
     const sentences = (0, harnesses_1.describeHealthReasonSentences)(details?.reasons, details?.state);
@@ -1148,7 +1148,7 @@ function describeRefusalReasons(err) {
  * the cap. Without them "would exceed the monthly cap" left a user guessing by
  * how much, and which cap (OSK-9552).
  */
-function describeSpendingCapRefusal(body, details) {
+function describeSpendingCapRefusal(body, details, context = {}) {
     let code;
     try {
         code = JSON.parse(body || '{}').code;
@@ -1172,9 +1172,25 @@ function describeSpendingCapRefusal(body, details) {
     ].filter(Boolean);
     if (parts.length === 0)
         return '';
-    return ` ${parts.join('; ')}. Raise the cap with \`machines dedicated spending-limit <lease-id> --cents <n>\`.`;
+    return ` ${parts.join('; ')}. ${raiseCapHint(context)}`;
 }
-function formatDedicatedRuntimeApiError(err) {
+/**
+ * How to get past a cap refusal, for the command that was refused. A create or
+ * a restore makes a NEW machine and takes its cap as a flag; only an existing
+ * machine has a lease id to raise. Every refusal used to say
+ * `machines dedicated spending-limit <lease-id>`, which a user refused on create
+ * had no lease id to run (OSK-9552).
+ */
+function raiseCapHint(context) {
+    const bin = context.bin || 'skrr';
+    const creates = context.command === 'machines:dedicated:create' ||
+        context.command === 'machines:dedicated:restore';
+    if (creates) {
+        return 'Pass a higher --spending-limit-cents: the cap is compared with the whole month, not with this machine alone.';
+    }
+    return `Raise the cap with \`${bin} machines dedicated spending-limit ${context.leaseId || '<lease-id>'} --cents <n>\`.`;
+}
+function formatDedicatedRuntimeApiError(err, context = {}) {
     if (!(err instanceof api_fetch_1.ApiFetchError) || !err.body) {
         return null;
     }
@@ -1202,7 +1218,7 @@ function formatDedicatedRuntimeApiError(err) {
         // Machine noun even though the caller named a Dedicated Runtime. Do not
         // repeat that contradictory product name while a mixed deployment rolls.
         const sentence = (parsed.message || parsed.error || parsed.code)?.replace(/(?:skrr )?Hosted Machine/g, 'Dedicated Runtime');
-        return sentence ? `${sentence}${describeRefusalReasons(err)}` : null;
+        return sentence ? `${sentence}${describeRefusalReasons(err, context)}` : null;
     }
     catch {
         return err.body.trim() || null;

package/dist/lib/dedicated-wait.js

@@ -17,8 +17,21 @@ function backupIsNewer(current, previous) {
     const b = Date.parse(previous);
     return Number.isFinite(a) && Number.isFinite(b) ? a > b : current !== previous;
 }
+/**
+ * `recovering` is also the state an image move replaces the machine through, on
+ * purpose. Reading every `recovering` as a failed action being retried told an
+ * owner watching an ordinary `update-image --wait` that destroy was available
+ * "if it never settles".
+ */
+const PLANNED_REPLACEMENT_PROGRESS = {
+    dedicated_runtime_image_update: 'replacing the machine',
+    dedicated_runtime_image_update_rolling_back: 'replacing the machine again',
+};
 function progressOf(lease) {
     const state = (0, dedicated_machines_1.dedicatedLeaseState)(lease);
+    const planned = lease.stateReason ? PLANNED_REPLACEMENT_PROGRESS[lease.stateReason] : undefined;
+    if (state === 'recovering' && planned)
+        return planned;
     if (state === 'recovering') {
         // `recovering` is where a failed provision or action lands, retried with
         // backoff. It can settle — or never, which is why destroy is allowed from it.

package/dist/lib/followups.d.ts

@@ -34,6 +34,8 @@ export interface FollowUpRow {
     terminal?: string | null;
     terminalAt?: string | null;
     terminalReason?: string | null;
+    /** Who settled it: `trigger_fire` for the runtime, otherwise the actor. */
+    terminalBy?: string | null;
     escalatedInitiativeId?: string | null;
     capsule?: unknown;
     nextRunAt?: string | null;
@@ -62,6 +64,12 @@ export interface FollowUpObservability {
             terminal: Record<string, number>;
             escalationRate: number | null;
             fires: number;
+            /** USD from the fires' UsageLog rows; null when the ledger could not be read. */
+            spend?: {
+                today: number;
+                total: number;
+                currency: string;
+            } | null;
             budget: {
                 pool: string | null;
                 used: number;

package/dist/lib/label-ref.d.ts

@@ -59,12 +59,19 @@ export declare function closestNames(typed: string, names: string[], limit?: num
 export interface LabelVocabularyContext {
     /** Narrow to labels attachable to this entity type. Omit for all of them. */
     applicableTo?: LabelApplicable;
-    /** Narrows to the workspace scope; `--workspace` / OVERSKY_WORKSPACE_ID. */
+    /**
+     * Narrows to this workspace scope. When omitted the AMBIENT workspace is
+     * resolved (`--workspace` / OVERSKY_WORKSPACE_ID / the server's default
+     * workspace): a session that never selected a workspace still writes to
+     * one, and a vocabulary that cannot see it refuses names that exist.
+     */
     workspaceId?: string;
     /** Archived labels are excluded unless asked for. */
     includeArchived?: boolean;
     /** Injected in tests. */
     getLabels?: typeof dataService.getLabels;
+    /** Injected in tests; defaults to `workspaces.ambientWorkspaceId`. */
+    resolveWorkspaceId?: () => Promise<string | undefined>;
 }
 export interface LabelRefContext extends LabelVocabularyContext {
     /** Which entity the resolved labels will be attached to. */

package/dist/lib/label-ref.js

@@ -39,6 +39,7 @@ exports.closestNames = closestNames;
 exports.collectLabelVocabulary = collectLabelVocabulary;
 exports.resolveLabelRefs = resolveLabelRefs;
 const data_provider_1 = require("@skrr-ai/data-provider");
+const workspaces_1 = require("./workspaces");
 /** A canonical v4 uuid, which is what every label id is. */
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function looksLikeLabelId(ref) {
@@ -89,9 +90,18 @@ function closestNames(typed, names, limit = 3) {
  */
 async function collectLabelVocabulary(context) {
     const getLabels = context.getLabels ?? data_provider_1.dataService.getLabels;
+    let workspaceId = context.workspaceId;
+    if (!workspaceId) {
+        try {
+            workspaceId = await (context.resolveWorkspaceId ?? workspaces_1.ambientWorkspaceId)();
+        }
+        catch {
+            workspaceId = undefined;
+        }
+    }
     const requests = [{ scope: 'user' }];
-    if (context.workspaceId)
-        requests.push({ scope: 'workspace', scopeId: context.workspaceId });
+    if (workspaceId)
+        requests.push({ scope: 'workspace', scopeId: workspaceId });
     const settled = await Promise.allSettled(requests.map((request) => getLabels({
         ...request,
         ...(context.applicableTo ? { applicableTo: context.applicableTo } : {}),

package/dist/lib/option-hint.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A "did you mean" for oclif's enum refusal (OSK-9735).
+ *
+ * Tasks, spaces, goals and key results each spell one lifecycle their own way —
+ * "under way" is `in_progress` for a space and `active` for a goal; "finished"
+ * is `done`, `completed` or `achieved` — and oclif's
+ * `Expected --status=in_progress to be one of: …` was the only place a user
+ * learned that. This names the value the command uses for the word that was
+ * typed, and otherwise the nearest spelling.
+ *
+ * It suggests and never substitutes. Some of the differences are deliberate (a
+ * key result's status is a health reading, not a lifecycle), so writing a mapped
+ * value would record a status nobody chose.
+ */
+export declare function invalidOptionHint(message: string): string | null;

package/dist/lib/option-hint.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * A "did you mean" for oclif's enum refusal (OSK-9735).
+ *
+ * Tasks, spaces, goals and key results each spell one lifecycle their own way —
+ * "under way" is `in_progress` for a space and `active` for a goal; "finished"
+ * is `done`, `completed` or `achieved` — and oclif's
+ * `Expected --status=in_progress to be one of: …` was the only place a user
+ * learned that. This names the value the command uses for the word that was
+ * typed, and otherwise the nearest spelling.
+ *
+ * It suggests and never substitutes. Some of the differences are deliberate (a
+ * key result's status is a health reading, not a lifecycle), so writing a mapped
+ * value would record a status nobody chose.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invalidOptionHint = invalidOptionHint;
+/**
+ * Spellings of one concept across the CLI's vocabularies. A value is suggested
+ * only when it shares a group with what was typed.
+ */
+const CONCEPT_GROUPS = [
+    new Set(['in_progress', 'inprogress', 'active', 'started', 'ongoing', 'running', 'doing']),
+    new Set(['done', 'completed', 'complete', 'achieved', 'finished', 'closed', 'resolved']),
+    new Set(['cancelled', 'canceled', 'abandoned']),
+    new Set(['in_review', 'inreview', 'review', 'reviewing']),
+    new Set(['planned', 'todo', 'to_do', 'not_started']),
+];
+const REFUSAL = /Expected (--[\w-]+)=(.+?) to be one of: ([^\n]+)/;
+const normalize = (value) => value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s-]+/g, '_');
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const above = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length];
+}
+function invalidOptionHint(message) {
+    const match = REFUSAL.exec(message || '');
+    if (!match)
+        return null;
+    const [, flag, input, list] = match;
+    const options = list
+        .split(',')
+        .map((option) => option.trim())
+        .filter(Boolean);
+    const typed = normalize(input);
+    const exact = options.find((option) => normalize(option) === typed);
+    if (exact)
+        return `  Did you mean ${flag} ${exact}?`;
+    const group = CONCEPT_GROUPS.find((concept) => concept.has(typed));
+    const synonym = group && options.find((option) => group.has(normalize(option)));
+    if (synonym) {
+        return `  Did you mean ${flag} ${synonym}? Here "${input}" is spelled "${synonym}".`;
+    }
+    let nearest = null;
+    for (const option of options) {
+        const distance = editDistance(typed, normalize(option));
+        if (!nearest || distance < nearest.distance)
+            nearest = { option, distance };
+    }
+    if (nearest && nearest.distance <= Math.max(2, Math.floor(typed.length / 4))) {
+        return `  Did you mean ${flag} ${nearest.option}?`;
+    }
+    return null;
+}

package/dist/lib/workspaces.d.ts

@@ -56,6 +56,9 @@ export interface WorkspaceListing {
  */
 export declare function describeUnselectedWorkspace(listing: WorkspaceListing): string;
 export declare function listWorkspaces(): Promise<WorkspaceRow[]>;
+export declare function ambientWorkspaceId(env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/** Test seam — a memoized network result must not leak between specs. */
+export declare function clearAmbientWorkspaceCache(): void;
 /** `listWorkspaces`, keeping the envelope's caller-level fields. */
 export declare function listWorkspaceListing(): Promise<WorkspaceListing>;
 export declare function getWorkspace(workspaceId: string): Promise<WorkspaceRow>;