@skrr-ai/cli 0.1.127 → 0.1.129

package/dist/commands/commitments/preflight.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nextRunsLines = nextRunsLines;
+exports.preflightHeadline = preflightHeadline;
 exports.preflightGateLines = preflightGateLines;
+exports.attentionFooterLines = attentionFooterLines;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const commitments_1 = require("../../lib/commitments");
 const prompt_1 = require("../../lib/prompt");
+const commitment_attention_copy_1 = require("../../lib/commitment-attention-copy");
 const preflight_copy_1 = require("../../lib/preflight-copy");
 /**
  * The lines one preflight gate contributes.
@@ -41,7 +44,26 @@ function nextRunsLines(report) {
         : 'Next runs:';
     return ['', header, ...report.nextRuns.map((run) => `  ${run}`)];
 }
-function preflightGateLines(gate, verbose = false) {
+/**
+ * The first line of a preflight. `Ready to run` is a statement about activation (no blocking gate),
+ * and it sat directly above a spend-gate warning that the daily Run budget is 0, i.e. that no agent
+ * turn can ever start (OSK-21224). The verdict stays `ready` on purpose: a zero ACTION budget does
+ * not stop the sensing lane, so refusing activation would be wrong for a Commitment that only
+ * observes. The headline carries the caveat instead of contradicting the gate below it.
+ */
+function preflightHeadline(report, persisted) {
+    const label = persisted ? 'Preflight' : 'Pre-create preview (nothing persisted)';
+    if (report.verdict === 'blocked')
+        return `${label}: Run is blocked`;
+    if (report.verdict !== 'ready')
+        return `${label}: A capability or configuration check is still needed`;
+    const reasons = report.gates?.find((gate) => gate.id === 'budget_bounds')?.detail?.reasons;
+    const noActionRuns = Array.isArray(reasons) && reasons.includes('action_runs_zero');
+    return noActionRuns
+        ? `${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, 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
@@ -50,15 +72,42 @@ function preflightGateLines(gate, verbose = false) {
     // (OSK-15420). Say what it is in words, and which setting moves it.
     if (gate.id === 'attention' && gate.verdict === 'block') {
         const copy = (0, data_provider_1.describeSuppression)(gate.reason);
+        // "Held until your quiet hours end." named no time and no zone; the report has both (OSK-21122).
+        const quietEnd = gate.reason === 'policy_quiet_hours'
+            ? (0, commitment_attention_copy_1.describeQuietHoursEnd)(gate.detail?.quietHours)
+            : null;
         const lines = [
             `  ${'info'.padEnd(5)} ${gate.label} — ${copy.title.toLowerCase()}${verbose && gate.reason ? ` (${gate.reason})` : ''}`,
-            `        ${copy.detail}`,
+            `        ${quietEnd ?? copy.detail}`,
         ];
-        if (copy.settingKey)
+        // Whose quiet hours these are, when they are not the Commitment's own (OSK-21151): a reader
+        // would otherwise be sent to a field this Commitment does not hold.
+        const note = gate.detail?.note;
+        if (typeof note === 'string' && note.trim())
+            lines.push(`        ${note.trim()}`);
+        // The policy field is a path into JSON, not something to type: the sentence above says what
+        // it means, so the path joins the code behind --verbose (OSK-21124).
+        if (verbose && copy.settingKey)
             lines.push(`        Setting: ${copy.settingKey}`);
         return lines;
     }
-    const mark = gate.verdict === 'pass' ? 'ok' : gate.verdict === 'block' ? 'BLOCK' : 'warn';
+    // 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.
+    //
+    // 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'
+            ? 'ok'
+            : gate.verdict === 'block'
+                ? 'BLOCK'
+                : 'warn';
     // A BLOCKING gate always states its reason. `ok` gates got a helpful `note`
     // and `warn` gates got a reason token, and the BLOCK gates — the only ones
     // that stop the run — got the label and nothing: two of them side by side,
@@ -75,7 +124,9 @@ function preflightGateLines(gate, verbose = false) {
     const hasNote = typeof note === 'string' && Boolean(note.trim());
     const showReason = verbose || (gate.verdict === 'block' && !hasNote);
     const lines = [
-        `  ${mark.padEnd(5)} ${gate.label}${showReason && gate.reason ? ` — ${gate.reason}` : ''}`,
+        `  ${mark.padEnd(5)} ${gate.label}${showReason && gate.reason ? ` — ${gate.reason}` : ''}` +
+            (advisoryBlock ? ' (advisory: does not stop a run)' : '') +
+            (stopsActivationOnly ? ' (stops activation, not a run that is already live)' : ''),
     ];
     if (hasNote) {
         lines.push(`        ${String(note).trim()}`);
@@ -92,6 +143,13 @@ function preflightGateLines(gate, verbose = false) {
         else if (status === 'invalid') {
             lines.push('        Active owner rules: unknown (stored rules invalid).');
         }
+        else if (status === 'archived' &&
+            typeof count === 'number' &&
+            Number.isSafeInteger(count) &&
+            count >= 0) {
+            // The Compass is archived, not unreadable: its rules are counted, and still enforced.
+            lines.push(`        Active owner rules: ${count} (on the archived Compass, still enforced).`);
+        }
         else if (status === 'available' &&
             typeof count === 'number' &&
             Number.isSafeInteger(count) &&
@@ -116,6 +174,29 @@ function preflightGateLines(gate, verbose = false) {
         lines.push(`        ${sentence}`);
     return lines;
 }
+/**
+ * The `Attention:` footer, and under it the settings behind the verdict (OSK-21120).
+ *
+ * "delivery allowed now" is the same words for a cap of 1, a mute lifted and no limit at all, so
+ * the cap, the gap and the no-reply rule are said beside it. `policy` is the stored policy the
+ * report was computed from, or the unsaved one under `--from-json`; without it nothing is said
+ * about the settings, rather than a guess. The raw reason code (`policy_nudge_muted`) is printed only
+ * with `--verbose`: beside the sentence it said the same thing twice, in a vocabulary nobody types
+ * (OSK-21124).
+ */
+function attentionFooterLines(attention, policy, verbose = false) {
+    const code = verbose && attention?.suppressedBy ? ` (${attention.suppressedBy})` : '';
+    const lines = [
+        '',
+        `Attention: ${attention?.allowed ? 'delivery allowed now' : `held back — ${(0, data_provider_1.describeSuppression)(attention?.suppressedBy).title.toLowerCase()}${code}`}`,
+    ];
+    if (policy) {
+        for (const line of (0, commitment_attention_copy_1.nudgeSettingLines)((0, commitment_attention_copy_1.nudgeSettingsFromPolicy)(policy)))
+            lines.push(`  ${line}`);
+        lines.push(`  Quiet hours: ${(0, commitment_attention_copy_1.describeQuietHours)(policy.quietHours)}`);
+    }
+    return lines;
+}
 class CommitmentsPreflight extends base_command_1.BaseCommand {
     static description = 'Dry-run a commitment: runtime gates, capabilities, attention policy and upcoming runs (runs nothing)';
     static examples = [
@@ -151,16 +232,37 @@ class CommitmentsPreflight extends base_command_1.BaseCommand {
             this.error('--next must be between 1 and 10', { exit: 1 });
         }
         let report;
+        // The policy the verdict was computed from, for the settings printed under it.
+        let policy = null;
         try {
-            report = args.id
-                ? await commitments_1.commitmentApi.preflight(args.id, flags.next)
-                : await commitments_1.commitmentApi.draftPreflight({
-                    commitment: (0, commitments_1.normalizeCreateBody)(await (0, prompt_1.readJsonBody)(flags['from-json'])),
+            if (args.id) {
+                report = await commitments_1.commitmentApi.preflight(args.id, flags.next);
+                try {
+                    policy =
+                        (await commitments_1.commitmentApi.get(args.id))?.commitment?.policy ?? null;
+                }
+                catch {
+                    policy = null;
+                }
+            }
+            else {
+                const rawBody = await (0, prompt_1.readJsonBody)(flags['from-json']);
+                const draft = (0, commitments_1.normalizeCreateBody)(rawBody);
+                const ignoredWarning = (0, commitments_1.ignoredCreateKeysWarning)((0, commitments_1.ignoredCreateKeys)(rawBody));
+                if (ignoredWarning)
+                    this.warn(ignoredWarning);
+                policy = draft.policy ?? {};
+                const quietHoursProblem = (0, commitment_attention_copy_1.quietHoursInputProblem)(policy);
+                if (quietHoursProblem)
+                    throw new Error(quietHoursProblem);
+                report = await commitments_1.commitmentApi.draftPreflight({
+                    commitment: draft,
                     ...(flags['event-fixture']
                         ? { eventFixture: await (0, prompt_1.readJsonBody)(flags['event-fixture']) }
                         : {}),
                     ...(flags.next !== undefined ? { nextRunCount: flags.next } : {}),
                 });
+            }
         }
         catch (err) {
             this.handleApiError(err);
@@ -170,7 +272,9 @@ class CommitmentsPreflight extends base_command_1.BaseCommand {
             this.log(JSON.stringify(report, null, 2));
             return;
         }
-        this.log(`${args.id ? 'Preflight' : 'Pre-create preview (nothing persisted)'}: ${report.verdict === 'ready' ? 'Ready to run' : report.verdict === 'blocked' ? 'Run is blocked' : 'A capability or configuration check is still needed'}`);
+        this.log(preflightHeadline(report, Boolean(args.id)));
+        for (const line of (0, commitments_1.activationRefusalLines)(report.activation))
+            this.log(line);
         // Whose permissions the run will use (OSK-11975), before the gates, so an
         // Execute Commitment on a plan-mode Agent is the first thing read
         // (OSK-12065).
@@ -183,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) {
@@ -211,7 +316,8 @@ class CommitmentsPreflight extends base_command_1.BaseCommand {
                 (endpoint.reason ? ` (${endpoint.reason})` : '') +
                 (!endpoint.available && endpoint.detail ? ` — ${endpoint.detail}` : ''));
         }
-        this.log(`\nAttention: ${report.attention?.allowed ? 'delivery allowed now' : `held back — ${(0, data_provider_1.describeSuppression)(report.attention?.suppressedBy).title.toLowerCase()}${report.attention?.suppressedBy ? ` (${report.attention.suppressedBy})` : ''}`}`);
+        for (const line of attentionFooterLines(report.attention, policy, flags.verbose))
+            this.log(line);
         if (report.verdict === 'blocked')
             process.exitCode = 1;
     }

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/commitments/trigger-status.js

@@ -82,6 +82,14 @@ function formatTriggerStatus(status) {
                 '(fired or disabled — cannot wake this commitment)');
         }
     }
+    // The plan can be converged and every row enabled while nothing can wake (Always-On off). `convergence`
+    // is a fact about the rows; this is the other fact, from the same projection `commitments status` reads.
+    const wake = status.wake;
+    if (wake?.held) {
+        lines.push(`Wakes:       HELD — ${wake.reason ?? 'blocked'}`);
+        if (wake.detail)
+            lines.push(`  ${String(wake.detail).replace(/\s+/g, ' ').trim()}`);
+    }
     const bindings = Array.isArray(status.bindings) ? status.bindings : [];
     lines.push('');
     if (bindings.length === 0) {

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

@@ -49,6 +49,7 @@ export default class CommitmentsUpdate extends BaseCommand {
         'cadence-mode': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         timezone: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         isolation: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'max-nudges': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'max-concurrent-runs': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'concurrency-reason': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };

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>;
 }