@skrr-ai/cli 0.1.128 → 0.1.129

package/dist/base-command.d.ts

@@ -580,6 +580,18 @@ export declare function describeHarnessUnavailable(body: Record<string, unknown>
  * Exported for tests.
  */
 export declare function describeGitHubUnavailable(): string;
+/**
+ * Frame a typed `TASK_LIST_TIMEOUT` failure as what it is — a list too broad for the database's
+ * time limit — rather than a control-plane outage.
+ *
+ * `GET /api/tasks` answers 503 with this code when its one aggregate is cut off at `maxTimeMS`,
+ * which an unscoped list over every accessible Space reaches because no index serves its sort
+ * across the access filter. Lead with the server's `cause`/`remedy`, falling back to the CLI's
+ * own sentence: the 5xx redaction boundary generalizes a bare message in production.
+ *
+ * Exported for tests.
+ */
+export declare function describeTaskListTimeout(body: Record<string, unknown> | null, bin?: string): string;
 /**
  * Frame a typed `LABEL_SUGGESTION_UNAVAILABLE` failure as what it is — the
  * suggestion's hosted-inference call found no billing payer — rather than a

package/dist/base-command.js

@@ -9,6 +9,7 @@ exports.commitmentActivationHint = commitmentActivationHint;
 exports.withSubject = withSubject;
 exports.describeHarnessUnavailable = describeHarnessUnavailable;
 exports.describeGitHubUnavailable = describeGitHubUnavailable;
+exports.describeTaskListTimeout = describeTaskListTimeout;
 exports.describeLabelSuggestionUnavailable = describeLabelSuggestionUnavailable;
 exports.describeGitHubAppNotConfigured = describeGitHubAppNotConfigured;
 exports.describeResourceNotFound = describeResourceNotFound;
@@ -1573,6 +1574,20 @@ class BaseCommand extends core_1.Command {
                     details: envelopeDetails(body),
                 });
             }
+            else if (bodyCode === 'TASK_LIST_TIMEOUT') {
+                // The list was too broad for the database's time limit — a 503 the API sent on purpose,
+                // with the narrower question to ask. The outage branch below would say skrr is down,
+                // record an incident, and tell an agent to retry the very query that cannot finish
+                // (OSK-21284).
+                this.failWithCliError({
+                    message: say(describeTaskListTimeout(body, this.config.bin)),
+                    code: bodyCode,
+                    status: e.status,
+                    exit: 1,
+                    retryable: false,
+                    details: envelopeDetails(body),
+                });
+            }
             else if (bodyCode === 'LABEL_SUGGESTION_UNAVAILABLE') {
                 // The label-suggestion route found no inference payer — a per-call
                 // condition the API deliberately reported, not a platform outage,
@@ -2388,6 +2403,26 @@ function describeGitHubUnavailable() {
     return ('GitHub is temporarily unreachable, so this request could not be completed. ' +
         'skrr itself answered, so this is not a skrr outage — try again shortly.');
 }
+/**
+ * Frame a typed `TASK_LIST_TIMEOUT` failure as what it is — a list too broad for the database's
+ * time limit — rather than a control-plane outage.
+ *
+ * `GET /api/tasks` answers 503 with this code when its one aggregate is cut off at `maxTimeMS`,
+ * which an unscoped list over every accessible Space reaches because no index serves its sort
+ * across the access filter. Lead with the server's `cause`/`remedy`, falling back to the CLI's
+ * own sentence: the 5xx redaction boundary generalizes a bare message in production.
+ *
+ * Exported for tests.
+ */
+function describeTaskListTimeout(body, bin = 'skrr') {
+    const cause = stringProp(body, 'cause') ||
+        'The task list took too long: it spans every task you can see across all your workspaces and ' +
+            'Spaces, and the database could not return the newest page within its time limit.';
+    const remedy = stringProp(body, 'remedy') ||
+        `Name where to look: a workspace (\`${bin} workspaces use <workspace-id>\`, or \`--workspace <workspace-id>\`) ` +
+            `or a Space (\`${bin} tasks list --space <space-id>\`).`;
+    return `${cause}\n  → ${remedy}`;
+}
 /**
  * Frame a typed `LABEL_SUGGESTION_UNAVAILABLE` failure as what it is — the
  * suggestion's hosted-inference call found no billing payer — rather than a

package/dist/commands/agenda/trigger/list.d.ts

@@ -12,7 +12,8 @@ import { BaseCommand } from '../../../base-command';
 export declare function isUnconfirmedTurnCapture(trigger: Record<string, unknown>): boolean;
 /**
  * `skrr agenda trigger list <agent-id>` — show all triggers registered for
- * an agent (any kind, not just agenda-created ones).
+ * an agent (any kind, not just agenda-created ones), including the ones the
+ * platform manages for its Commitments (the daily self-reflection check).
  */
 export default class AgendaTriggerList extends BaseCommand {
     static description: string;

package/dist/commands/agenda/trigger/list.js

@@ -7,6 +7,7 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
 const format_1 = require("../../../lib/format");
 const triggers_1 = require("../../../lib/triggers");
+const agent_trigger_listing_1 = require("../../../lib/agent-trigger-listing");
 /**
  * A schedule persisted while handling a conversation turn, for which no explicit
  * confirmation was recorded.
@@ -27,10 +28,11 @@ function isUnconfirmedTurnCapture(trigger) {
 }
 /**
  * `skrr agenda trigger list <agent-id>` — show all triggers registered for
- * an agent (any kind, not just agenda-created ones).
+ * an agent (any kind, not just agenda-created ones), including the ones the
+ * platform manages for its Commitments (the daily self-reflection check).
  */
 class AgendaTriggerList extends base_command_1.BaseCommand {
-    static description = 'List every trigger registered against an agent.';
+    static description = "List every trigger registered against an agent, including the ones the platform manages for its Commitments (SOURCE 'system'). A passive agent (--initial-always-on off) still has a daily self-reflection check.";
     static examples = [
         '<%= config.bin %> agenda trigger list <agent-id>',
         '<%= config.bin %> agenda trigger list <agent-id> --unconfirmed',
@@ -55,17 +57,50 @@ class AgendaTriggerList extends base_command_1.BaseCommand {
         catch (err) {
             this.handleApiError(err);
         }
+        const r = response;
+        const listed = r?.data ?? [];
+        // The per-agent route lists `scope: 'agent'` rows only; the Commitment triggers a passive agent still owns
+        // live under `commitment_watcher`. `--unconfirmed` is about turn captures, which are agent-scoped, so it
+        // skips the extra read.
+        let extra = [];
+        let extraUnreadable = null;
+        if (!flags.unconfirmed) {
+            try {
+                const universal = await triggers_1.triggerApi.list((0, triggers_1.withQuery)('/api/triggers', { refEntity: [`agent:${args.agentId}`], limit: 200 }));
+                extra = (0, agent_trigger_listing_1.triggersMissingFromAgentList)(listed, (universal?.triggers ?? []));
+            }
+            catch (err) {
+                extraUnreadable = err instanceof Error ? err.message : String(err);
+            }
+        }
         if (flags.json) {
-            this.printJsonResult((0, list_output_1.listResult)(response));
+            this.printJsonResult((0, list_output_1.listResult)(r && typeof r === 'object'
+                ? {
+                    ...r,
+                    data: [...listed, ...extra],
+                    ...(extraUnreadable
+                        ? {
+                            warnings: [
+                                {
+                                    code: 'system_triggers_unreadable',
+                                    value: extraUnreadable,
+                                    hint: systemTriggersUnreadable(args.agentId, extraUnreadable),
+                                },
+                            ],
+                        }
+                        : {}),
+                }
+                : response));
             return;
         }
-        const r = response;
-        let items = r?.data ?? [];
+        let items = [...listed, ...extra];
         if (flags.unconfirmed) {
             items = items.filter((t) => isUnconfirmedTurnCapture(t));
         }
         if (items.length === 0) {
             this.log(flags.unconfirmed ? 'No unconfirmed turn-captured schedules.' : 'No triggers.');
+            if (extraUnreadable)
+                this.log(systemTriggersUnreadable(args.agentId, extraUnreadable));
             return;
         }
         const rows = items.map((t) => {
@@ -81,7 +116,7 @@ class AgendaTriggerList extends base_command_1.BaseCommand {
                 label: String(t.label ?? '-').slice(0, 40),
                 next: String(next).slice(0, 25),
                 fires: String(fires),
-                source: isUnconfirmedTurnCapture(t) ? 'turn*' : '-',
+                source: (0, agent_trigger_listing_1.sourceLabel)(t, isUnconfirmedTurnCapture(t)),
             };
         });
         (0, format_1.renderTable)(rows, [
@@ -93,6 +128,15 @@ class AgendaTriggerList extends base_command_1.BaseCommand {
             { key: 'fires', header: 'FIRES' },
             { key: 'source', header: 'SOURCE' },
         ], (line) => this.log(line));
+        if (rows.some((row) => row.source.startsWith('system'))) {
+            this.log('');
+            for (const line of (0, agent_trigger_listing_1.systemManagedLegend)(args.agentId, this.config.bin))
+                this.log(line);
+        }
+        if (extraUnreadable) {
+            this.log('');
+            this.log(systemTriggersUnreadable(args.agentId, extraUnreadable));
+        }
         if (rows.some((row) => row.source === 'turn*')) {
             // Deliberately not "the agent scheduled this by itself". The capture layer
             // cannot tell "remind me at 9" from a nudge the agent invented, so the
@@ -105,3 +149,8 @@ class AgendaTriggerList extends base_command_1.BaseCommand {
     }
 }
 exports.default = AgendaTriggerList;
+/** Said, not skipped: a missing read must not look like an agent with no Commitment triggers. */
+function systemTriggersUnreadable(agentId, reason) {
+    return (`Platform-managed (Commitment) triggers could not be read (${reason}); this list may be incomplete. ` +
+        `Try: skrr triggers list --ref-entity agent:${agentId}`);
+}

package/dist/commands/agents/create.js

@@ -245,7 +245,9 @@ class AgentsCreate extends base_command_1.BaseCommand {
             description: 'Default working directory for local Harness sessions',
         }),
         'initial-always-on': core_1.Flags.string({
-            description: 'Start autonomous work after creation (default: on). Use off for a passive agent; explicit chat still works. Relationship-loop seeding is configured separately.',
+            description: 'Start autonomous work after creation (default: on). Use off for a passive agent; explicit chat still works. ' +
+                'A passive agent is still seeded with the system-managed daily self-reflection Commitment: `agenda trigger list <agent>` shows its trigger (SOURCE "system", marked "suspended" while the platform holds it for Always-On being off) ' +
+                'and `commitments list --agent <agent> --include-system` finds the Commitment to pause. Relationship-loop seeding is configured separately.',
             options: ['on', 'off'],
         }),
         'no-relationship-loops': core_1.Flags.boolean({

package/dist/commands/browser/persistent-profile.d.ts

@@ -0,0 +1,22 @@
+import { Command } from '@oclif/core';
+/**
+ * Whether browser sessions on THIS computer share one profile that keeps its
+ * logins and cache, instead of a fresh one each.
+ *
+ * The setting lives in the daemon's own config on this computer, so it is
+ * forwarded to the daemon rather than sent to the API: a browser that stays
+ * signed in is the person at the machine's decision, and a request from the
+ * cloud must not be able to make it (the same boundary as `browser
+ * cloud-agents`). The profile is the daemon's own, never the everyday Chrome.
+ */
+export default class BrowserPersistentProfile extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        action: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/browser/persistent-profile.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const browser_1 = require("../browser");
+/**
+ * Whether browser sessions on THIS computer share one profile that keeps its
+ * logins and cache, instead of a fresh one each.
+ *
+ * The setting lives in the daemon's own config on this computer, so it is
+ * forwarded to the daemon rather than sent to the API: a browser that stays
+ * signed in is the person at the machine's decision, and a request from the
+ * cloud must not be able to make it (the same boundary as `browser
+ * cloud-agents`). The profile is the daemon's own, never the everyday Chrome.
+ */
+class BrowserPersistentProfile extends core_1.Command {
+    static description = 'Keep one browser profile (logins, cookies, cache) across browser sessions on this computer (off by default)';
+    static examples = [
+        '<%= config.bin %> browser persistent-profile status',
+        '<%= config.bin %> browser persistent-profile on',
+        '<%= config.bin %> browser persistent-profile off',
+        '<%= config.bin %> browser persistent-profile reset',
+    ];
+    static args = {
+        action: core_1.Args.string({
+            description: 'on, off, status, or reset (sign out of everything and delete the profile)',
+            required: true,
+            options: ['on', 'off', 'status', 'reset'],
+            // Without this oclif reads stdin for a missing positional, so the command
+            // hangs when run from a pipe or a non-tty instead of refusing. Enforced
+            // by ARG_IMPLICIT_STDIN_ENABLED in the command-hygiene audit.
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output JSON' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(BrowserPersistentProfile);
+        await (0, browser_1.forwardBrowserCommand)(this, [
+            'persistent-profile',
+            args.action,
+            ...(flags.json ? ['--json'] : []),
+        ]);
+    }
+}
+exports.default = BrowserPersistentProfile;

package/dist/commands/commitments/create.js

@@ -260,7 +260,9 @@ JSON
 <%= config.bin %> compass commitments <compass-id> --agent <agent-id>   # lists it once it is bound`,
     ];
     static flags = {
-        json: core_1.Flags.boolean({ description: 'Output the created commitment as JSON' }),
+        json: core_1.Flags.boolean({
+            description: 'Output the created commitment as JSON: the commitment itself, not wrapped (commitments show --json puts it under .commitment)',
+        }),
         'from-json': core_1.Flags.string({
             description: `JSON file (or "-" for stdin) for fields not exposed as flags. See examples below for daily times, named agent_run keys, zero budgets and "compassId" (binds a Compass; fixed at creation). ${commitment_attention_copy_1.QUIET_HOURS_HELP} ${commitment_attention_copy_1.EVENT_SOURCES_HELP}`,
         }),

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

@@ -7,6 +7,7 @@ const base_command_1 = require("../../base-command");
 const commitments_1 = require("../../lib/commitments");
 const commitment_product_1 = require("../../lib/commitment-product");
 const commitment_attention_copy_1 = require("../../lib/commitment-attention-copy");
+const northstars_1 = require("../../lib/northstars");
 /** Which limit binds the daily action runs — the fix lives on that object. */
 const RUN_LIMIT_BINDING_LABELS = {
     northstar_allocation: 'Northstar allocation',
@@ -71,6 +72,11 @@ function budgetDayLines(policy) {
                 ? 'no ceiling'
                 : `${value}/day`;
         lines.push(`Northstar shared pools: action runs ${pool(shared.actionRunsPerDay, shared.actionRunsPerDayState)} · observation runs ${pool(shared.observationRunsPerDay, shared.observationRunsPerDayState)}`);
+        // A pool below the number of linked active commitments is still handed out at the floor of
+        // 1/day each: the same sentence `northstars governance show` and `review-now` print (OSK-21334).
+        const floorNote = (0, northstars_1.runBudgetFloorNote)(policy.portfolio?.runBudgetFloor);
+        if (floorNote)
+            lines.push(`! ${floorNote}`);
     }
     return lines;
 }

package/dist/commands/commitments/explain.js

@@ -24,13 +24,22 @@ class CommitmentsExplain extends base_command_1.BaseCommand {
         this.requireAuth();
         const { args, flags } = await this.parse(CommitmentsExplain);
         try {
-            const explanation = await commitments_1.commitmentApi.explain(args.commitmentId);
+            // The explanation names neither the bound Compass nor its status, so the text view reads the
+            // Commitment beside it (the read `show` renders). `--json` stays the explanation as the
+            // server sent it, with no extra request. A failed read must not fail the explanation
+            // (OSK-21332): it becomes a "not shown" line instead.
+            const [explanation, read] = await Promise.all([
+                commitments_1.commitmentApi.explain(args.commitmentId),
+                flags.json ? null : commitments_1.commitmentApi.get(args.commitmentId).catch(() => null),
+            ]);
             if (flags.json) {
                 this.log(JSON.stringify(explanation, null, 2));
                 return;
             }
             for (const line of (0, commitments_1.formatCommitmentExplanation)(explanation))
                 this.log(line);
+            for (const line of (0, commitments_1.explainCompassLines)(args.commitmentId, read?.commitment))
+                this.log(line);
         }
         catch (err) {
             this.handleApiError(err);

package/dist/commands/commitments/plan.d.ts

@@ -18,6 +18,20 @@ import { BaseCommand } from '../../base-command';
  * the command body so it can be unit-tested without the oclif harness.
  */
 export declare function formatDroppedFields(droppedFields: string[] | undefined): string[];
+/**
+ * The zone a proposal's daily times will be read in, said before the person applies it (OSK-21336).
+ * The planner is not told a timezone unless `--timezone` is passed, and the proposal is printed as raw JSON,
+ * so "every day at 9am" came back as `times: ["09:00"]` with no zone; applied as it is, a daily cadence with
+ * no zone is read in UTC, while the web wizard writes the browser's zone for the same proposal and says so.
+ * Nothing for a proposal with no daily times.
+ */
+export declare function planTimezoneLines(proposal: {
+    cadence?: {
+        mode?: unknown;
+        times?: unknown;
+        timezone?: unknown;
+    };
+} | null | undefined, requestedTimezone?: string): string[];
 export default class CommitmentsPlan extends BaseCommand {
     static description: string;
     static examples: string[];

package/dist/commands/commitments/plan.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatDroppedFields = formatDroppedFields;
+exports.planTimezoneLines = planTimezoneLines;
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const commitments_1 = require("../../lib/commitments");
@@ -36,6 +37,35 @@ function formatDroppedFields(droppedFields) {
         lines.push(`  - ${field}`);
     return lines;
 }
+/**
+ * The zone a proposal's daily times will be read in, said before the person applies it (OSK-21336).
+ * The planner is not told a timezone unless `--timezone` is passed, and the proposal is printed as raw JSON,
+ * so "every day at 9am" came back as `times: ["09:00"]` with no zone; applied as it is, a daily cadence with
+ * no zone is read in UTC, while the web wizard writes the browser's zone for the same proposal and says so.
+ * Nothing for a proposal with no daily times.
+ */
+function planTimezoneLines(proposal, requestedTimezone) {
+    const cadence = proposal?.cadence;
+    if (!cadence || cadence.mode !== 'daily' || !Array.isArray(cadence.times) || !cadence.times.length) {
+        return [];
+    }
+    const times = cadence.times.filter((time) => typeof time === 'string');
+    if (!times.length)
+        return [];
+    const label = `daily time${times.length === 1 ? '' : 's'} ${times.join(', ')}`;
+    if (typeof cadence.timezone === 'string' && cadence.timezone) {
+        return ['', `The ${label} ${times.length === 1 ? 'is' : 'are'} read in ${cadence.timezone}.`];
+    }
+    return [
+        '',
+        `Note: the ${label} ${times.length === 1 ? 'carries' : 'carry'} no timezone, so applying this as it is reads ` +
+            `${times.length === 1 ? 'it' : 'them'} in UTC (the web wizard would use your browser's zone). ` +
+            (requestedTimezone
+                ? `You planned with --timezone ${requestedTimezone}, but the proposal did not keep it: add "timezone": ` +
+                    `"${requestedTimezone}" to its cadence.`
+                : 'Add "timezone": "<IANA zone>" to its cadence, or plan again with --timezone <IANA zone>.'),
+    ];
+}
 class CommitmentsPlan extends base_command_1.BaseCommand {
     static description = 'Draft a commitment contract from a sentence (read-only proposal — nothing is created)';
     static examples = [
@@ -115,6 +145,8 @@ class CommitmentsPlan extends base_command_1.BaseCommand {
             this.log('No proposal produced.');
             return;
         }
+        for (const line of planTimezoneLines(response.proposal, flags.timezone))
+            this.log(line);
         this.log('');
         this.log('Proposed contract:');
         this.log(JSON.stringify(response.proposal, null, 2));

package/dist/commands/commitments/preflight.d.ts

@@ -43,7 +43,7 @@ export declare function nextRunsLines(report: {
  * observes. The headline carries the caveat instead of contradicting the gate below it.
  */
 export declare function preflightHeadline(report: Pick<CommitmentPreflightReport, 'verdict' | 'gates'>, persisted: boolean): string;
-export declare function preflightGateLines(gate: PreflightGate, verbose?: boolean): string[];
+export declare function preflightGateLines(gate: PreflightGate, verbose?: boolean, refusesActivation?: boolean): string[];
 /**
  * The `Attention:` footer, and under it the settings behind the verdict (OSK-21120).
  *

package/dist/commands/commitments/preflight.js

@@ -63,7 +63,7 @@ function preflightHeadline(report, persisted) {
         ? `${label}: Ready to run, but its daily Run budget is 0, so no agent turn will start`
         : `${label}: Ready to run`;
 }
-function preflightGateLines(gate, verbose = false) {
+function preflightGateLines(gate, verbose = false, refusesActivation = false) {
     // "Could it contact you now?" is not a Run gate. It answers whether a message
     // would reach the owner, and a limit the owner set themselves (zero nudges a day,
     // quiet hours) is a chosen quiet, not a defect. It carried the same BLOCK tag, a
@@ -94,7 +94,13 @@ function preflightGateLines(gate, verbose = false) {
     // A `block` the report itself marks advisory stops nothing: it is not a Run-admission gate, so it
     // never feeds the verdict or `pack activate`. Printed BLOCK, `pack preflight` read "ready" above
     // two BLOCK lines (dogfooded on a goal_advance draft); the tag has to mean what the report means.
-    const advisoryBlock = gate.verdict === 'block' && gate.admission === 'advisory';
+    //
+    // An advisory gate the SERVER says refuses activation is a different case (OSK-21258): `resume`
+    // answers 409 for it, so it is tagged BLOCK and says what it stops. `info (advisory: does not stop a
+    // run)` beside an "Activation: would be refused" section naming the same gate was two answers to one
+    // question.
+    const advisoryBlock = gate.verdict === 'block' && gate.admission === 'advisory' && !refusesActivation;
+    const stopsActivationOnly = gate.verdict === 'block' && gate.admission === 'advisory' && refusesActivation;
     const mark = advisoryBlock
         ? 'info'
         : gate.verdict === 'pass'
@@ -119,7 +125,8 @@ function preflightGateLines(gate, verbose = false) {
     const showReason = verbose || (gate.verdict === 'block' && !hasNote);
     const lines = [
         `  ${mark.padEnd(5)} ${gate.label}${showReason && gate.reason ? ` — ${gate.reason}` : ''}` +
-            (advisoryBlock ? ' (advisory: does not stop a run)' : ''),
+            (advisoryBlock ? ' (advisory: does not stop a run)' : '') +
+            (stopsActivationOnly ? ' (stops activation, not a run that is already live)' : ''),
     ];
     if (hasNote) {
         lines.push(`        ${String(note).trim()}`);
@@ -280,7 +287,8 @@ class CommitmentsPreflight extends base_command_1.BaseCommand {
         }
         this.log('\nGates:');
         for (const gate of report.gates || []) {
-            for (const line of preflightGateLines(gate, flags.verbose))
+            const refusesActivation = (0, commitments_1.gateRefusesActivation)(report.activation, gate);
+            for (const line of preflightGateLines(gate, flags.verbose, refusesActivation))
                 this.log(line);
         }
         if (report.capabilities?.length) {

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

@@ -1,4 +1,13 @@
 import { BaseCommand } from '../../base-command';
+/**
+ * What `show --json` prints, said where the flag is read (OSK-21334, from OSK-21205): the server's
+ * read envelope, with the commitment UNDER `.commitment`. `create --json` and `update --json` print
+ * the commitment itself, so a script written against one raised `KeyError: 'priority'` on the other.
+ * The shape is kept (moving the commitment up a level would break every reader of `show --json`) and
+ * no top-level copy is added; `docs/cli/SKRR_COMMITMENTS.md` says why, and
+ * `__tests__/json-shapes.spec.ts` runs both commands against this sentence.
+ */
+export declare const SHOW_JSON_DESCRIPTION: string;
 /**
  * `skrr commitments show <id>` — the commitment's contract + live control-loop
  * state (health, last check, next check, unresolved-check streak), plus the most

package/dist/commands/commitments/show.js

@@ -1,10 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHOW_JSON_DESCRIPTION = void 0;
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const commitments_1 = require("../../lib/commitments");
 const web_url_1 = require("../../lib/web-url");
 const commitment_product_1 = require("../../lib/commitment-product");
+/**
+ * What `show --json` prints, said where the flag is read (OSK-21334, from OSK-21205): the server's
+ * read envelope, with the commitment UNDER `.commitment`. `create --json` and `update --json` print
+ * the commitment itself, so a script written against one raised `KeyError: 'priority'` on the other.
+ * The shape is kept (moving the commitment up a level would break every reader of `show --json`) and
+ * no top-level copy is added; `docs/cli/SKRR_COMMITMENTS.md` says why, and
+ * `__tests__/json-shapes.spec.ts` runs both commands against this sentence.
+ */
+exports.SHOW_JSON_DESCRIPTION = 'Output the read envelope as JSON: { commitment, latestCheck, operatingState, abilities, url }. ' +
+    'The commitment itself is under .commitment (so the priority is .commitment.priority); ' +
+    'create --json and update --json print the commitment unwrapped.';
 /**
  * `skrr commitments show <id>` — the commitment's contract + live control-loop
  * state (health, last check, next check, unresolved-check streak), plus the most
@@ -18,12 +30,13 @@ class CommitmentsShow extends base_command_1.BaseCommand {
     static examples = [
         '<%= config.bin %> commitments show <commitment-id>',
         '<%= config.bin %> commitments show <commitment-id> --json',
+        "<%= config.bin %> commitments show <commitment-id> --json | jq '.commitment.priority'",
     ];
     static args = {
         id: core_1.Args.string({ description: 'Commitment ID', required: true, ignoreStdin: true }),
     };
     static flags = {
-        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        json: core_1.Flags.boolean({ description: exports.SHOW_JSON_DESCRIPTION }),
         verbose: core_1.Flags.boolean({
             description: 'Include raw compatibility policy and check diagnostics',
         }),

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

@@ -1,6 +1,10 @@
 import { BaseCommand } from '../../base-command';
-/** What to say under a list the ledger had more rows for. */
-export declare function revisionsFooter(shown: number): string;
+/**
+ * What to say under a list the ledger had more rows for. `total` is the API's own count of the
+ * ledger; with it the footer is exact (`Showing 20 of 25`). A server that does not send it, or one
+ * whose count is not above what was shown, still gets the lookahead's true "at least" wording.
+ */
+export declare function revisionsFooter(shown: number, total?: number): string;
 /**
  * `skrr compass revisions <compass-id> --agent <id>` — the append-only ledger.
  *

package/dist/commands/compass/revisions.js

@@ -4,11 +4,18 @@ 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) {
+/**
+ * What to say under a list the ledger had more rows for. `total` is the API's own count of the
+ * ledger; with it the footer is exact (`Showing 20 of 25`). A server that does not send it, or one
+ * whose count is not above what was shown, still gets the lookahead's true "at least" wording.
+ */
+function revisionsFooter(shown, total) {
+    const of = typeof total === 'number' && Number.isInteger(total) && total > shown
+        ? `${total}`
+        : `at least ${shown + 1}`;
     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.`;
+        ? `Showing ${shown} of ${of} revisions. --limit is capped at 100, so older ones cannot be listed yet.`
+        : `Showing ${shown} of ${of} revisions — use --limit (up to 100) to see more.`;
 }
 /**
  * `skrr compass revisions <compass-id> --agent <id>` — the append-only ledger.
@@ -55,8 +62,9 @@ class CompassRevisions extends base_command_1.BaseCommand {
         (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.
+        // `total` (the ledger's own count) makes the footer exact when the server sends it.
         if (response.has_more)
-            this.log(revisionsFooter(rows.length));
+            this.log(revisionsFooter(rows.length, response.total));
     }
 }
 exports.default = CompassRevisions;

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

@@ -7,6 +7,10 @@ import { BaseCommand } from '../../base-command';
  * 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.
+ *
+ * `--invariant <target-id>` chooses the invariant target the tactic is filed under. Without it
+ * the API files it under the general target (the one with no domain), else the first, and the
+ * output says which; a Compass whose targets all carry a domain used to leave no way to choose.
  */
 export default class CompassTactic extends BaseCommand {
     static description: string;
@@ -19,6 +23,7 @@ export default class CompassTactic extends BaseCommand {
         agent: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         description: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         id: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        invariant: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;

package/dist/commands/compass/tactic.js

@@ -11,11 +11,16 @@ const compasses_1 = require("../../lib/compasses");
  * 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.
+ *
+ * `--invariant <target-id>` chooses the invariant target the tactic is filed under. Without it
+ * the API files it under the general target (the one with no domain), else the first, and the
+ * output says which; a Compass whose targets all carry a domain used to leave no way to choose.
  */
 class CompassTactic extends base_command_1.BaseCommand {
     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"',
+        '<%= config.bin %> compass tactic agch_abc --agent agent_xyz --invariant invariant_2 --description "Page the owner before restarting"',
     ];
     static args = {
         compassId: core_1.Args.string({ ignoreStdin: true, description: 'Compass ID', required: true }),
@@ -27,17 +32,26 @@ class CompassTactic extends base_command_1.BaseCommand {
         id: core_1.Flags.string({
             description: 'Stable tactic ID. A known ID with a different description updates that entry; with the same description nothing is written.',
         }),
+        invariant: core_1.Flags.string({
+            description: 'Invariant target ID to file the tactic under (the `id` that `compass show` prints for each target). ' +
+                'Default: the general target (the one with no domain), else the first. An unknown ID is refused with the IDs the compass has; ' +
+                'a tactic --id that already lives on another target is refused too, so name that target to update it.',
+        }),
         reason: core_1.Flags.string({ description: 'Why — recorded on the revision ledger' }),
     };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(CompassTactic);
+        if (flags.invariant !== undefined && !flags.invariant.trim()) {
+            this.error('--invariant needs an invariant target ID. `compass show` prints each target as `id <id>`; leave --invariant off to use the default target.');
+        }
         let compass;
         try {
             compass = await compasses_1.compassApi.appendTactic(args.compassId, {
                 agentId: flags.agent,
                 description: flags.description,
                 ...(flags.id ? { id: flags.id } : {}),
+                ...(flags.invariant ? { invariantTargetId: flags.invariant.trim() } : {}),
                 ...(flags.reason ? { reason: flags.reason } : {}),
             });
         }