@skrr-ai/cli 0.1.126 → 0.1.128

package/dist/commands/commitments/update.js

@@ -6,10 +6,24 @@ const commitment_product_1 = require("../../lib/commitment-product");
 const data_provider_2 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const prompt_1 = require("../../lib/prompt");
+const commitment_attention_copy_1 = require("../../lib/commitment-attention-copy");
 const web_url_1 = require("../../lib/web-url");
 const prompt_2 = require("../../lib/prompt");
 const triggers_1 = require("../../lib/triggers");
 const commitments_1 = require("../../lib/commitments");
+/**
+ * Every field a stored cadence can carry. `satisfies` makes a key the type does not know a
+ * compile error; `update.cadence-preservation.spec.ts` pins the other direction.
+ */
+const CARRIED_CADENCE_KEYS = [
+    'mode',
+    'intervalMs',
+    'times',
+    'jitterRatio',
+    'activeHours',
+    'daysOfWeek',
+    'timezone',
+];
 /**
  * `skrr commitments update <id>` — edit the contract.
  *
@@ -32,13 +46,15 @@ const commitments_1 = require("../../lib/commitments");
  */
 class CommitmentsUpdate extends base_command_1.BaseCommand {
     static description = "Update a commitment's contract (title, target, cadence, sources). A cadence is manual, an interval or daily clock times; " +
-        'activeHours and daysOfWeek in --from-json select hours and weekdays. No holiday, business-day or trading-calendar fields';
+        'activeHours and daysOfWeek in --from-json select hours and weekdays. No holiday, business-day or trading-calendar fields. ' +
+        'The Compass a commitment is bound to ("compassId" in the create body) cannot be changed: create a successor commitment instead';
     static examples = [
         '<%= config.bin %> commitments update <commitment-id> --cadence 12h',
         '<%= config.bin %> commitments update <commitment-id> --title "Ship v2 (Q3)" --outcome "v2 is live for all users"',
         '<%= config.bin %> commitments update <commitment-id> --watch tasks --watch github',
         '<%= config.bin %> commitments update <commitment-id> --criterion "signups confirmed" --evaluator metric --measure <measure-id>',
         '<%= config.bin %> commitments update <commitment-id> --agent-directive-file ./review-policy.md',
+        '# Nudges: how many times a day it may interrupt you. 0 mutes it; "unlimited" removes the limit.\n<%= config.bin %> commitments update <commitment-id> --max-nudges 2\n<%= config.bin %> commitments update <commitment-id> --max-nudges unlimited',
         `# Read the current contract and use its version for --if-version.
 <%= config.bin %> commitments show <commitment-id> --json
 cat > commitment-patch.json <<'JSON'
@@ -48,6 +64,11 @@ cat > commitment-patch.json <<'JSON'
 }
 JSON
 <%= config.bin %> commitments update <commitment-id> --from-json commitment-patch.json --if-version <observed-version> --json`,
+        `# Quiet hours: no messages to you from 22:00 to 07:00. Times are HH:MM (00:00-23:59); without a timezone UTC is used.
+cat > quiet-hours.json <<'JSON'
+{ "policy": { "quietHours": { "enabled": true, "start": "22:00", "end": "07:00", "timezone": "America/Los_Angeles" } } }
+JSON
+<%= config.bin %> commitments update <commitment-id> --from-json quiet-hours.json`,
     ];
     static args = {
         id: core_1.Args.string({ description: 'Commitment ID', required: true, ignoreStdin: true }),
@@ -59,7 +80,7 @@ JSON
             description: 'Skip the confirmation prompt for an irreversible status change',
         }),
         'from-json': core_1.Flags.string({
-            description: 'JSON patch file (or "-" for stdin). See examples below. JSON cadence and watchedSources replace those fields; policy is deep-merged.',
+            description: `JSON patch file (or "-" for stdin). See examples below. JSON cadence and watchedSources replace those fields; policy is deep-merged. ${commitment_attention_copy_1.QUIET_HOURS_HELP} ${commitment_attention_copy_1.EVENT_SOURCES_HELP}`,
         }),
         'if-version': core_1.Flags.integer({
             description: 'Only update this observed contract version; returns a conflict if it changed',
@@ -126,6 +147,11 @@ JSON
                 'to be in a Git repository with an initial commit.',
             options: [...commitments_1.COMMITMENT_EXECUTION_ISOLATION_MODES],
         }),
+        'max-nudges': core_1.Flags.string({
+            // Sent as a single-key `policy` patch, which the API deep-merges. Before this flag the only
+            // way back to unlimited was hand-writing {"policy":{"maxUserNudgesPerDay":null}}.
+            description: commitment_attention_copy_1.MAX_NUDGES_FLAG_HELP,
+        }),
         'max-concurrent-runs': core_1.Flags.string({
             description: 'Set 1..100, or "unlimited" to remove the owner cap. Finite values require --concurrency-reason.',
         }),
@@ -301,7 +327,11 @@ JSON
             if (wantsCadence) {
                 const existing = current?.cadence ?? {};
                 const storedCadence = {};
-                for (const key of ['mode', 'intervalMs', 'times', 'jitterRatio', 'timezone']) {
+                // Every authored cadence field. The API replaces `cadence` wholesale, so a field left out
+                // of this list is erased from the Commitment by an edit that never mentioned it: omitting
+                // `activeHours`/`daysOfWeek` turned "weekdays 09:00-22:00" into "around the clock" on
+                // `--cadence 2h` (OSK-18366). Mirrors `cadenceShape` in api/server/routes/commitments.js.
+                for (const key of CARRIED_CADENCE_KEYS) {
                     if (existing[key] !== undefined)
                         storedCadence[key] = existing[key];
                 }
@@ -350,6 +380,11 @@ JSON
                         delete cadence.jitterRatio;
                     }
                 }
+                // A daily cadence's rhythm is its times, and the API refuses an `intervalMs` beside them.
+                // Dropping the inherited one also repairs a row an earlier build let store both.
+                if (cadence.mode === 'daily' && !Object.hasOwn(authoredCadence ?? {}, 'intervalMs')) {
+                    delete cadence.intervalMs;
+                }
                 if (!['interval', 'daily', 'event_plus_interval'].includes(String(cadence.mode)) &&
                     !Object.hasOwn(authoredCadence ?? {}, 'activeHours'))
                     delete cadence.activeHours;
@@ -365,13 +400,16 @@ JSON
                 rawValue: flags['max-concurrent-runs'],
                 reason: flags['concurrency-reason'],
             });
-            if (flags.isolation || concurrencyPatch) {
+            const maxNudges = (0, commitment_attention_copy_1.parseMaxNudgesFlag)(flags['max-nudges']);
+            if (flags.isolation || concurrencyPatch || maxNudges !== undefined) {
                 const existingPolicy = payload.policy && typeof payload.policy === 'object' && !Array.isArray(payload.policy)
                     ? payload.policy
                     : {};
                 const nextPolicy = { ...existingPolicy };
                 if (flags.isolation)
                     nextPolicy.executionIsolation = flags.isolation;
+                if (maxNudges !== undefined)
+                    nextPolicy.maxUserNudgesPerDay = maxNudges;
                 if (concurrencyPatch) {
                     const existingEnvelope = nextPolicy.executionBudget &&
                         typeof nextPolicy.executionBudget === 'object' &&
@@ -390,6 +428,9 @@ JSON
                 !Array.isArray(finalPolicy.executionBudget)
                 ? finalPolicy.executionBudget
                 : undefined;
+            const quietHoursProblem = (0, commitment_attention_copy_1.quietHoursInputProblem)(finalPolicy);
+            if (quietHoursProblem)
+                throw new Error(quietHoursProblem);
             if (process.env.OVERSKY_AUTONOMOUS_SESSION === '1' &&
                 finalEnvelope &&
                 Object.prototype.hasOwnProperty.call(finalEnvelope, 'maxConcurrentRuns')) {

package/dist/commands/commitments/wake-capabilities.js

@@ -7,6 +7,7 @@ const base_command_1 = require("../../base-command");
 const commitments_1 = require("../../lib/commitments");
 const format_1 = require("../../lib/format");
 const commitment_event_wakes_1 = require("../../lib/commitment-event-wakes");
+const commitment_attention_copy_1 = require("../../lib/commitment-attention-copy");
 /**
  * The headline used to stop at "configured sources may wake the Agent within lifecycle and execution
  * budgets", over a column marked ACTIVE, which read as bound while `trigger-status` said no event
@@ -84,6 +85,18 @@ class CommitmentsWakeCapabilities extends base_command_1.BaseCommand {
         }
         for (const line of wakePolicyLines(result))
             this.log(line);
+        // The owner's allowlist of event sources (OSK-21113): the response does not carry it, and for
+        // unset, [], a bogus name and a real source this output was byte-identical. Read from the
+        // Commitment's own policy; unread, the line is left out rather than claim "all allowed".
+        try {
+            const policy = (await commitments_1.commitmentApi.get(args.commitmentId))?.commitment?.policy;
+            if (policy) {
+                this.log(`Event sources: ${(0, commitment_attention_copy_1.describeEventSources)(policy.executionBudget?.allowedEventSources)}`);
+            }
+        }
+        catch {
+            // The wake table below does not depend on it.
+        }
         const visible = new Set(result.visibleCapabilities.map((item) => item.id));
         (0, format_1.renderTable)(result.eligibleCapabilities.map((item) => ({
             id: item.id,

package/dist/commands/compass/archive.js

@@ -58,6 +58,10 @@ class CompassArchive extends base_command_1.BaseCommand {
             this.log(JSON.stringify(result, null, 2));
             return;
         }
+        if (result.alreadyArchived) {
+            this.log(`Already archived. ${result.id} is unchanged — no new revision was written.`);
+            return;
+        }
         this.log(`Archived ${result.id}. Revisions remain readable via \`compass revisions\`.`);
     }
 }

package/dist/commands/compass/commitments.js

@@ -38,10 +38,24 @@ class CompassCommitments extends base_command_1.BaseCommand {
             return;
         }
         const rows = response.data ?? [];
+        // The list carries no compass status, so one read says whether it governs these at all. Best
+        // effort: when it fails the rows still print, with no claim either way about governance.
+        let status;
+        try {
+            status = (await compasses_1.compassApi.get(args.compassId, { agentId: flags.agent })).status;
+        }
+        catch {
+            status = undefined;
+        }
+        const archived = status === 'archived';
         if (rows.length === 0) {
-            this.log('No commitments are governed by this compass.');
+            this.log(archived
+                ? 'No commitments are bound to this compass.'
+                : 'No commitments are governed by this compass.');
             return;
         }
+        if (archived)
+            this.log((0, compasses_1.describeBoundCommitments)(rows.length, status));
         (0, format_1.renderTable)(rows.map((row) => ({
             id: String(row.id ?? ''),
             title: String(row.title ?? ''),

package/dist/commands/compass/create.js

@@ -5,6 +5,7 @@ const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const prompt_1 = require("../../lib/prompt");
 const compasses_1 = require("../../lib/compasses");
+const compass_body_help_1 = require("../../lib/compass-body-help");
 const web_url_1 = require("../../lib/web-url");
 /**
  * Stamp the owning agent onto a compass the API returned without one.
@@ -33,11 +34,17 @@ function withCompassAgentContext(compass, agentId) {
  * without turning the CLI into a schema.
  */
 class CompassCreate extends base_command_1.BaseCommand {
-    static description = 'Create a compass for an agent';
+    static description = `Create a compass for an agent.
+
+${compass_body_help_1.COMPASS_BODY_HELP}
+
+To govern a Commitment with this compass, put "compassId" in the Commitment's --from-json create body (see: commitments create --help). The binding is fixed at creation.`;
     static examples = [
         '<%= config.bin %> compass create --agent agent_abc --title "Production reliability" --domain reliability',
         '<%= config.bin %> compass create --agent agent_abc --title "FinOps" --invariant "Cloud spend stays under $10k/mo"',
         '<%= config.bin %> compass create --agent agent_abc --json-body ./compass.json',
+        `${compass_body_help_1.COMPASS_BODY_EXAMPLE}
+<%= config.bin %> compass create --agent agent_abc --json-body compass.json`,
     ];
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
@@ -45,11 +52,12 @@ class CompassCreate extends base_command_1.BaseCommand {
         title: core_1.Flags.string({ description: 'Human-readable direction, e.g. "Production reliability"' }),
         domain: core_1.Flags.string({ description: 'Broad subject area, e.g. "aws" or "finops"' }),
         invariant: core_1.Flags.string({
-            description: 'Invariant target description (repeatable). The state the agent keeps true.',
+            description: 'Invariant target description (repeatable, at most 25). The state the agent keeps true. ' +
+                'Each gets the id invariant_<position> and no domainKind: use --json-body for ids and domains.',
             multiple: true,
         }),
         'json-body': core_1.Flags.string({
-            description: 'Path to a JSON file with the full body (merged under the flags)',
+            description: 'Path to a JSON file with the full body (merged under the flags). Field names and limits are listed in the description above.',
         }),
     };
     async run() {

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;