@skrr-ai/cli 0.1.127 → 0.1.128

package/dist/commands/compass/effective-policy.d.ts

@@ -1,6 +1,7 @@
 import { BaseCommand } from '../../base-command';
 export default class CompassEffectivePolicy extends BaseCommand {
     static description: string;
+    static examples: string[];
     static args: {
         compassId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };

package/dist/commands/compass/effective-policy.js

@@ -5,7 +5,13 @@ const base_command_1 = require("../../base-command");
 const compasses_1 = require("../../lib/compasses");
 class CompassEffectivePolicy extends base_command_1.BaseCommand {
     static description = 'Read a Compass policy revision, effective defaults and field provenance';
-    static args = { compassId: core_1.Args.string({ description: 'Compass ID', required: true, ignoreStdin: true }) };
+    static examples = [
+        '<%= config.bin %> compass effective-policy agch_abc123 --agent agent_xyz',
+        '<%= config.bin %> compass effective-policy agch_abc123 --agent agent_xyz --json',
+    ];
+    static args = {
+        compassId: core_1.Args.string({ description: 'Compass ID', required: true, ignoreStdin: true }),
+    };
     static flags = {
         agent: core_1.Flags.string({ description: 'Agent ID that owns the Compass', required: true }),
         json: core_1.Flags.boolean({ description: 'Output the complete policy and provenance as JSON' }),
@@ -19,12 +25,7 @@ class CompassEffectivePolicy extends base_command_1.BaseCommand {
                 this.log(JSON.stringify(policy, null, 2));
                 return;
             }
-            this.log(`Compass ${policy.compassId}, revision ${policy.compassVersion}: ${policy.status}`);
-            this.log(`Applies to runtime: ${policy.appliesToRuntime === true ? 'yes' : 'no'}`);
-            this.log(`Autonomy defaults: ${JSON.stringify(policy.autonomy ?? {})}`);
-            this.log(`Communication defaults: ${JSON.stringify(policy.communication ?? {})}`);
-            this.log(`Authority: ${policy.authority ?? 'unknown'}`);
-            this.log(`Field provenance: ${JSON.stringify(policy.fieldProvenance ?? {})}`);
+            (0, compasses_1.renderEffectivePolicy)(policy, (line) => this.log(line));
         }
         catch (error) {
             this.handleApiError(error);

package/dist/commands/compass/revert.d.ts

@@ -6,6 +6,13 @@ import { BaseCommand } from '../../base-command';
  * The ledger therefore records that someone chose to go back, and versions 4–8
  * stay readable instead of vanishing. That is the difference between an audit
  * trail and an undo button.
+ *
+ * Like `update`, a revert is version-fenced: `--expected-version` pins the
+ * version the caller looked at, and without it the current version is read at
+ * the start and said so on stderr, so a concurrent edit is a named conflict
+ * rather than a surprise. A revert restores the configuration and keeps the
+ * compass's current status; it says when it wrote nothing and when it removed
+ * enforced rules.
  */
 export default class CompassRevert extends BaseCommand {
     static description: string;
@@ -18,6 +25,7 @@ export default class CompassRevert extends BaseCommand {
         agent: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'to-version': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'expected-version': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/compass/revert.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const compasses_1 = require("../../lib/compasses");
+const update_1 = require("./update");
 /**
  * `skrr compass revert <compass-id> --agent <id> --to-version 3`
  *
@@ -10,12 +11,20 @@ const compasses_1 = require("../../lib/compasses");
  * The ledger therefore records that someone chose to go back, and versions 4–8
  * stay readable instead of vanishing. That is the difference between an audit
  * trail and an undo button.
+ *
+ * Like `update`, a revert is version-fenced: `--expected-version` pins the
+ * version the caller looked at, and without it the current version is read at
+ * the start and said so on stderr, so a concurrent edit is a named conflict
+ * rather than a surprise. A revert restores the configuration and keeps the
+ * compass's current status; it says when it wrote nothing and when it removed
+ * enforced rules.
  */
 class CompassRevert extends base_command_1.BaseCommand {
     static description = 'Restore an earlier compass version (as a NEW forward revision)';
     static examples = [
         '<%= config.bin %> compass revert agch_abc --agent agent_xyz --to-version 3',
         '<%= config.bin %> compass revert agch_abc --agent agent_xyz --to-version 3 --reason "new SLO was wrong"',
+        '<%= config.bin %> compass revert agch_abc --agent agent_xyz --to-version 3 --expected-version 9',
     ];
     static args = {
         compassId: core_1.Args.string({ ignoreStdin: true, description: 'Compass ID', required: true }),
@@ -29,15 +38,30 @@ class CompassRevert extends base_command_1.BaseCommand {
             min: 1,
         }),
         reason: core_1.Flags.string({ description: 'Why — recorded on the revision ledger' }),
+        'expected-version': core_1.Flags.integer({
+            min: 1,
+            description: 'Compass version this revert is based on; it is refused if the compass moved. ' +
+                'Defaults to the version read at the start of this command.',
+        }),
     };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(CompassRevert);
+        this.compassRef = {
+            compassId: args.compassId,
+            agentId: flags.agent,
+            toVersion: flags['to-version'],
+        };
         let compass;
         try {
+            const expected = await (0, update_1.resolveExpectedVersion)(flags['expected-version'], {}, async () => (await compasses_1.compassApi.get(args.compassId, { agentId: flags.agent })).version);
+            if (expected.source === 'current' && !flags.json) {
+                this.logToStderr(`No --expected-version given; reverting from the current version (v${String(expected.version)}).`);
+            }
             compass = await compasses_1.compassApi.revert(args.compassId, {
                 agentId: flags.agent,
                 toVersion: flags['to-version'],
+                expectedVersion: expected.version,
                 ...(flags.reason ? { reason: flags.reason } : {}),
             });
         }
@@ -48,7 +72,7 @@ class CompassRevert extends base_command_1.BaseCommand {
             this.log(JSON.stringify(compass, null, 2));
             return;
         }
-        this.log(`Restored v${flags['to-version']} as v${compass.version} — the intermediate versions stay in the ledger.`);
+        (0, compasses_1.renderRevertResult)(compass, flags['to-version'], flags.agent, (line) => this.log(line));
         this.log('');
         (0, compasses_1.renderCompass)(compass, (line) => this.log(line));
     }

package/dist/commands/compass/revisions.d.ts

@@ -1,4 +1,6 @@
 import { BaseCommand } from '../../base-command';
+/** What to say under a list the ledger had more rows for. */
+export declare function revisionsFooter(shown: number): string;
 /**
  * `skrr compass revisions <compass-id> --agent <id>` — the append-only ledger.
  *

package/dist/commands/compass/revisions.js

@@ -1,8 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.revisionsFooter = revisionsFooter;
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const compasses_1 = require("../../lib/compasses");
+/** What to say under a list the ledger had more rows for. */
+function revisionsFooter(shown) {
+    return shown >= 100
+        ? `Showing ${shown} of at least ${shown + 1} revisions. --limit is capped at 100, so older ones cannot be listed yet.`
+        : `Showing ${shown} of at least ${shown + 1} revisions — use --limit (up to 100) to see more.`;
+}
 /**
  * `skrr compass revisions <compass-id> --agent <id>` — the append-only ledger.
  *
@@ -21,7 +28,11 @@ class CompassRevisions extends base_command_1.BaseCommand {
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
         agent: core_1.Flags.string({ description: 'Agent ID that owns the compass', required: true }),
-        limit: core_1.Flags.integer({ description: 'Max revisions (1..100)', min: 1, max: 100 }),
+        limit: core_1.Flags.integer({
+            description: 'Max revisions (1..100, default 20); newest first',
+            min: 1,
+            max: 100,
+        }),
     };
     async run() {
         this.requireAuth();
@@ -40,7 +51,12 @@ class CompassRevisions extends base_command_1.BaseCommand {
             this.log(JSON.stringify(response, null, 2));
             return;
         }
-        (0, compasses_1.renderRevisionList)(response.data ?? [], (line) => this.log(line));
+        const rows = response.data ?? [];
+        (0, compasses_1.renderRevisionList)(rows, (line) => this.log(line));
+        // The API reads one row past the page, so `has_more` is true only when older rows exist. A
+        // 22-revision ledger used to list 20 rows and stop, with v1 (the create) silently missing.
+        if (response.has_more)
+            this.log(revisionsFooter(rows.length));
     }
 }
 exports.default = CompassRevisions;

package/dist/commands/compass/tactic.d.ts

@@ -2,9 +2,11 @@ import { BaseCommand } from '../../base-command';
 /**
  * `skrr compass tactic <compass-id> --agent <id> --description "..."`
  *
- * Appends to the bounded, rolling "what has worked before" list. It is a
- * separate verb from `update` on purpose: expressing an append as a full-object
- * write would let two concurrent learners clobber each other's entry.
+ * Appends to the bounded, rolling "what has worked before" list, or updates the
+ * entry that carries the same `--id`. It is a separate verb from `update` on
+ * purpose: expressing an append as a full-object write would let two concurrent
+ * learners clobber each other's entry. It says which of appended / updated /
+ * unchanged happened, and names any tactic that rolled off the end.
  */
 export default class CompassTactic extends BaseCommand {
     static description: string;

package/dist/commands/compass/tactic.js

@@ -6,12 +6,14 @@ const compasses_1 = require("../../lib/compasses");
 /**
  * `skrr compass tactic <compass-id> --agent <id> --description "..."`
  *
- * Appends to the bounded, rolling "what has worked before" list. It is a
- * separate verb from `update` on purpose: expressing an append as a full-object
- * write would let two concurrent learners clobber each other's entry.
+ * Appends to the bounded, rolling "what has worked before" list, or updates the
+ * entry that carries the same `--id`. It is a separate verb from `update` on
+ * purpose: expressing an append as a full-object write would let two concurrent
+ * learners clobber each other's entry. It says which of appended / updated /
+ * unchanged happened, and names any tactic that rolled off the end.
  */
 class CompassTactic extends base_command_1.BaseCommand {
-    static description = 'Append a learned tactic to a compass';
+    static description = 'Record a learned tactic on a compass (appends, or updates the tactic with the same --id)';
     static examples = [
         '<%= config.bin %> compass tactic agch_abc --agent agent_xyz --description "Roll back before paging on a deploy regression"',
     ];
@@ -23,7 +25,7 @@ class CompassTactic extends base_command_1.BaseCommand {
         agent: core_1.Flags.string({ description: 'Agent ID that owns the compass', required: true }),
         description: core_1.Flags.string({ description: 'The tactic, in one sentence', required: true }),
         id: core_1.Flags.string({
-            description: 'Stable tactic ID (updates that entry instead of adding one)',
+            description: 'Stable tactic ID. A known ID with a different description updates that entry; with the same description nothing is written.',
         }),
         reason: core_1.Flags.string({ description: 'Why — recorded on the revision ledger' }),
     };
@@ -46,8 +48,7 @@ class CompassTactic extends base_command_1.BaseCommand {
             this.log(JSON.stringify(compass, null, 2));
             return;
         }
-        const count = (compass.learnedTactics ?? []).length;
-        this.log(`Appended. ${compass.id} now carries ${count} learned tactic(s) (v${compass.version}).`);
+        (0, compasses_1.renderTacticResult)(compass, (line) => this.log(line));
     }
 }
 exports.default = CompassTactic;

package/dist/commands/compass/update.js

@@ -6,6 +6,7 @@ const base_command_1 = require("../../base-command");
 const prompt_1 = require("../../lib/prompt");
 const compasses_1 = require("../../lib/compasses");
 const web_url_1 = require("../../lib/web-url");
+const compass_body_help_1 = require("../../lib/compass-body-help");
 /**
  * The server fences every compass write on the version the caller last saw
  * (`expectedVersion`, required), so a stale writer gets a conflict instead of
@@ -33,7 +34,11 @@ async function resolveExpectedVersion(explicit, fileBody, fetchCurrentVersion) {
  * winning for some domain — replacement makes the new set the whole answer.
  */
 class CompassUpdate extends base_command_1.BaseCommand {
-    static description = 'Update a compass (bumps the version, writes a revision)';
+    static description = `Update a compass (bumps the version, writes a revision).
+
+${compass_body_help_1.COMPASS_BODY_HELP}
+
+On update, invariantTargets (and --invariant) REPLACE the whole list, so send every target you want to keep; identity, scope, autonomyDefaults and communicationDefaults merge field by field onto what is stored; rules replace the list. An archived compass stays archived unless you pass --status active.`;
     static examples = [
         '<%= config.bin %> compass update agch_abc --agent agent_xyz --title "Reliability & cost"',
         '<%= config.bin %> compass update agch_abc --agent agent_xyz --invariant "p99 under 300ms" --reason "new SLO"',
@@ -50,7 +55,8 @@ class CompassUpdate extends base_command_1.BaseCommand {
         domain: core_1.Flags.string({ description: 'New domain' }),
         status: core_1.Flags.string({ description: 'New status', options: [...compasses_1.COMPASS_STATUSES] }),
         invariant: core_1.Flags.string({
-            description: 'Invariant target description (repeatable; REPLACES the list)',
+            description: 'Invariant target description (repeatable, at most 25; REPLACES the list). ' +
+                'Each gets the id invariant_<position> and no domainKind, so it drops the ids and domains of the targets it replaces: use --json-body to keep them.',
             multiple: true,
         }),
         reason: core_1.Flags.string({ description: 'Why — recorded on the revision ledger' }),
@@ -59,7 +65,9 @@ class CompassUpdate extends base_command_1.BaseCommand {
             description: 'Compass version this change is based on; the update is refused if it moved. ' +
                 'Defaults to the version read at the start of this command.',
         }),
-        'json-body': core_1.Flags.string({ description: 'Path to a JSON file with the full body' }),
+        'json-body': core_1.Flags.string({
+            description: 'Path to a JSON file with the body (merged under the flags). Field names and limits are listed in the description above.',
+        }),
     };
     async run() {
         this.requireAuth();
@@ -81,10 +89,14 @@ class CompassUpdate extends base_command_1.BaseCommand {
         if (Object.keys(body).length <= 1) {
             this.error('Nothing to update — pass at least one field flag or --json-body.');
         }
+        this.compassRef = { compassId: args.compassId, agentId: flags.agent };
         let compass;
         try {
             const expected = await resolveExpectedVersion(flags['expected-version'], fileBody, async () => (await compasses_1.compassApi.get(args.compassId, { agentId: flags.agent })).version);
             body.expectedVersion = expected.version;
+            if (typeof expected.version === 'number') {
+                this.compassRef = { ...this.compassRef, expectedVersion: expected.version };
+            }
             if (expected.source === 'current' && !flags.json) {
                 this.logToStderr(`No --expected-version given; updating from the current version (v${String(expected.version)}).`);
             }
@@ -100,6 +112,10 @@ class CompassUpdate extends base_command_1.BaseCommand {
             return;
         }
         this.log(`Updated ${withContext.id} → v${withContext.version}.`);
+        // An edit keeps the status (docs: it never resurrects). Say so, or the edit looks live.
+        if (withContext.status === 'archived' && body.status !== 'archived') {
+            this.log('Compass is archived: this edit has no runtime effect until it is reactivated (`--status active`).');
+        }
         if (url)
             this.log(`View it at ${url}`);
         this.log('');

package/dist/commands/followups/act.js

@@ -105,7 +105,7 @@ class FollowupsAct extends base_command_1.BaseCommand {
             this.log(producerNotice);
         const row = response.followup;
         if (response.reused) {
-            this.log(`Already armed: ${row?.id} — the same act exists and was not duplicated.`);
+            this.log((0, followups_1.reusedWithoutChangeMessage)(row, 'the same act on this subject'));
             return;
         }
         if (response.dropped) {

package/dist/commands/followups/cancel.js

@@ -30,6 +30,16 @@ class FollowupsCancel extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(FollowupsCancel);
+        // Best effort, and only to warn: cancelling the SLA backstop of a paired watch leaves that watch
+        // armed with no deadline, and the answer used to be the same bare "cancelled".
+        let wasSlaFallback = false;
+        try {
+            const before = await followups_1.followupsApi.show(args.id);
+            wasSlaFallback = Boolean(before?.followup?.slaFallback && !before.followup.terminal);
+        }
+        catch {
+            // The cancel below reports any real problem with the id.
+        }
         let result;
         try {
             result = (await followups_1.followupsApi.cancel(args.id, {
@@ -45,6 +55,9 @@ class FollowupsCancel extends base_command_1.BaseCommand {
             return;
         }
         this.log((0, followups_1.settledLine)(args.id, result, 'cancelled'));
+        if (wasSlaFallback) {
+            this.log('That was the SLA backstop of a paired watch. The watch itself is still armed and now has no deadline: cancel or resolve it too if you meant to end the wait.');
+        }
     }
 }
 exports.default = FollowupsCancel;

package/dist/commands/followups/observability.js

@@ -6,6 +6,23 @@ const format_1 = require("../../lib/format");
 const followups_1 = require("../../lib/followups");
 const agent_resolver_1 = require("../../lib/agent-resolver");
 const rate = (value) => value === null ? '—' : `${Math.round(value * 100)}%`;
+/**
+ * What today's budget turned away. A creation refused or dropped makes no row, so
+ * this is the only place it shows (OSK-21209). `—` is "this kind has no budget",
+ * `?` is "the counter could not be read", `0` is a real zero.
+ */
+const turnedAway = (budget) => {
+    if (!budget)
+        return '—';
+    const { droppedToday, refusedToday } = budget;
+    if (droppedToday == null || refusedToday == null)
+        return '?';
+    const parts = [
+        droppedToday > 0 ? `${droppedToday} dropped` : null,
+        refusedToday > 0 ? `${refusedToday} refused` : null,
+    ].filter(Boolean);
+    return parts.length > 0 ? parts.join(' · ') : '0';
+};
 /** `resolved 3 · abandoned 1` — the outcomes that happened, not five zeros. */
 const outcomes = (terminal) => Object.entries(terminal)
     .filter(([, count]) => count > 0)
@@ -97,6 +114,7 @@ class FollowupsObservability extends base_command_1.BaseCommand {
                     ? `$${kind.spend.today.toFixed(2)} / $${kind.spend.total.toFixed(2)}`
                     : '—',
                 budget: kind.budget ? `${kind.budget.used}/${kind.budget.limit ?? '∞'}` : '—',
+                turnedAway: turnedAway(kind.budget),
                 silence: rate(kind.silenceRate),
             })), [
                 { key: 'kind', header: 'KIND' },
@@ -109,10 +127,11 @@ class FollowupsObservability extends base_command_1.BaseCommand {
                 { key: 'fires', header: 'FIRES' },
                 { key: 'spend', header: 'SPENT TODAY/ALL' },
                 { key: 'budget', header: 'TODAY/LIMIT' },
+                { key: 'turnedAway', header: 'TURNED AWAY' },
                 { key: 'silence', header: 'SILENT' },
             ], (line) => this.log(line));
         });
-        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.`);
+        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); TURNED AWAY is what that budget kept from being created today: dropped is a check-in the API answered with no error (the CLI prints one for you; an Agent's own check-in is not told), refused is a watch or act answered FOLLOWUP_BUDGET_EXCEEDED; SILENT is how often a check-in chose to stay quiet.`);
     }
 }
 exports.default = FollowupsObservability;

package/dist/commands/followups/plans/create.js

@@ -5,6 +5,7 @@ const base_command_1 = require("../../../base-command");
 const prompt_1 = require("../../../lib/prompt");
 const lookbackPlans_1 = require("../../../lib/lookbackPlans");
 const lookbackPlanHelp_1 = require("../../../lib/lookbackPlanHelp");
+const followups_1 = require("../../../lib/followups");
 class LookbackPlansCreate extends base_command_1.BaseCommand {
     static description = 'Schedule a bounded plan of 1–10 lookbacks, each free to stay silent\n\n' + lookbackPlanHelp_1.LOOKBACK_PLAN_INPUT_HELP +
         '\n\nCreate also accepts {"agentId":"...","pinnedConversationId":"...","plan":{...}}. Source and delivery destination are separate; pin the original conversation to return there.';
@@ -27,7 +28,17 @@ class LookbackPlansCreate extends base_command_1.BaseCommand {
         }
         try {
             const result = await lookbackPlans_1.lookbackPlansApi.create(body);
-            this.log(flags.json ? JSON.stringify(result, null, 2) : (0, lookbackPlans_1.lookbackArmingLine)(result));
+            if (flags.json) {
+                this.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            // The four create commands say when the server recorded weaker provenance than the CLI
+            // claimed; a plan is recorded the same way (`producerDowngraded` is in the route's answer)
+            // and only `plans show` ever said so.
+            const notice = (0, followups_1.producerDowngradeNotice)(result);
+            if (notice)
+                this.log(notice);
+            this.log((0, lookbackPlans_1.lookbackArmingLine)(result));
         }
         catch (err) {
             if ((0, lookbackPlans_1.isLookbackMutationOutcomeUnknown)(err)) {

package/dist/commands/followups/show.js

@@ -9,6 +9,7 @@ const GATE_LABEL = {
     exempt_user_directed: 'fires without approval (you asked for it)',
     exempt_system: 'fires without approval (system)',
     user_directed_guarded: 'fires without approval (you asked for it); still held by quiet hours, approval-only action classes and the spend cap',
+    exempt_notification: 'delivered to you as a notification (no agent turn, so no approval step applies)',
     autonomy_ladder: "follows the agent's autonomy mode",
     approval_ladder: 'needs approval unless the autonomy mode allows it',
 };
@@ -49,6 +50,12 @@ class FollowupsShow extends base_command_1.BaseCommand {
                 'settled',
                 row.terminal ? `${row.terminalAt ?? '—'} by ${row.terminalBy ?? 'unknown'}` : undefined,
             ],
+            [
+                'role',
+                row.slaFallback
+                    ? 'the SLA backstop of a paired watch, not a second watch: it escalates that watch when its wait outlives the deadline, and cancelling it leaves the watch without one'
+                    : undefined,
+            ],
             ['deadline', row.deadlineAt],
             [
                 'waiting',
@@ -56,6 +63,12 @@ class FollowupsShow extends base_command_1.BaseCommand {
                     ? `on an offline machine since ${row.parkedAt} (escalates after 60 minutes)`
                     : undefined,
             ],
+            [
+                'held',
+                row.held && !row.terminal
+                    ? `moved to ${row.held.until} — ${row.held.note ?? row.held.reason ?? 'it could not run when it came due'}`
+                    : undefined,
+            ],
             ['escalated to', row.escalatedInitiativeId],
         ]) {
             if (value)

package/dist/commands/followups/watch.js

@@ -242,7 +242,7 @@ class FollowupsWatch extends base_command_1.BaseCommand {
             this.log(producerNotice);
         const row = response.followup;
         if (response.reused) {
-            this.log(`Already armed: ${row?.id} — an identical watch exists and was not duplicated.`);
+            this.log((0, followups_1.reusedWithoutChangeMessage)(row, 'an identical watch'));
             return;
         }
         if (response.dropped) {

package/dist/commands/goals/planner-config.d.ts

@@ -35,6 +35,17 @@ export type GoalPlannerView = {
      * choose between those two, because the CLI cannot tell them apart.
      */
     tickLockedAt: string | null;
+    /**
+     * Why an armed planner will not tick, or null. The scheduler only creates the planner's trigger
+     * for an ACTIVE, unarchived Goal (`GoalPlanner.shouldScheduleGoal`); for any other status the
+     * cadence is stored and `nextTickAt` is set, but nothing ever fires. Stating the cadence alone
+     * read as "armed" (dogfooded: a `planned` Goal showed `nextTickAt` in the past for good).
+     */
+    notRunning: {
+        goalId: string | null;
+        reason: 'archived' | 'status';
+        status: string | null;
+    } | null;
 };
 /** Read the planner state off a Goal document (lean or typed). */
 export declare function goalPlannerView(goal: Record<string, unknown> | undefined | null): GoalPlannerView;

package/dist/commands/goals/planner-config.js

@@ -13,6 +13,14 @@ function goalPlannerView(goal) {
     const g = (goal ?? {});
     const tickIntervalMs = typeof g.tickIntervalMs === 'number' ? g.tickIntervalMs : null;
     const enabled = tickIntervalMs != null;
+    const status = str(g.status);
+    const notRunning = !enabled
+        ? null
+        : g.archivedAt
+            ? { goalId: str(g.id), reason: 'archived', status }
+            : status && status !== 'active'
+                ? { goalId: str(g.id), reason: 'status', status }
+                : null;
     return {
         enabled,
         tickIntervalMs,
@@ -21,6 +29,7 @@ function goalPlannerView(goal) {
         nextTickAt: enabled ? str(g.nextTickAt) : null,
         lastTickedAt: str(g.lastTickedAt),
         tickLockedAt: str(g.tickLockedAt),
+        notRunning,
     };
 }
 /**
@@ -44,6 +53,13 @@ function renderGoalPlannerLines(view) {
         lines.push(`  nextTickAt:      ${view.nextTickAt}`);
     if (view.lastTickedAt)
         lines.push(`  lastTickedAt:    ${view.lastTickedAt}`);
+    if (view.notRunning) {
+        const { goalId, reason, status } = view.notRunning;
+        lines.push(reason === 'archived'
+            ? '  not running:     this Goal is archived, and the planner only ticks for an active Goal'
+            : `  not running:     this Goal is ${status}, and the planner only ticks for an active Goal` +
+                ` — \`skrr goals update ${goalId ?? '<goal-id>'} --status active\``);
+    }
     if (view.tickLockedAt) {
         lines.push(`  tickLockedAt:    ${view.tickLockedAt} (a claimed tick has not released this lock)`);
     }

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

@@ -1,11 +1,11 @@
 import { BaseCommand } from '../../base-command';
 /**
- * Rename / describe / tag a machine.
+ * Rename / describe / tag a machine, and choose its icon.
  *
  * `preferences` is the ONLY user-editable part of a machine — identities,
  * capabilities and lifecycle stay authoritative in the daemon, harness and
- * lease records this aggregate reads. The name set here is yours: it does not
- * rename the machine for anyone else.
+ * lease records this aggregate reads. The name and icon set here are yours: they
+ * do not rename or re-draw the machine for anyone else.
  */
 export default class MachinesUpdate extends BaseCommand {
     static description: string;
@@ -19,6 +19,8 @@ export default class MachinesUpdate extends BaseCommand {
         description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tag: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'clear-tags': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        icon: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'icon-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }