@skrr-ai/cli 0.1.127 → 0.1.128

package/dist/commands/commitments/hypotheses.js

@@ -55,20 +55,20 @@ class CommitmentsHypotheses extends base_command_1.BaseCommand {
             this.handleApiError(err);
         }
         if (flags.json) {
+            // One JSON document and nothing else: has_more / next_cursor are in it.
             this.log(JSON.stringify(response, null, 2));
+            return;
         }
-        else {
-            // A filtered-out list is not an empty ledger — say which filter did it
-            // (OSK-10953).
-            const filters = [
-                flags.status ? `--status ${flags.status}` : null,
-                flags['investigation-key'] ? `--investigation-key ${flags['investigation-key']}` : null,
-            ].filter(Boolean);
-            const emptyMessage = filters.length
-                ? `No hypotheses match ${filters.join(' ')}.`
-                : 'No hypotheses recorded.';
-            (0, commitments_1.renderCommitmentHypotheses)(response, (line) => this.log(line), { emptyMessage });
-        }
+        // A filtered-out list is not an empty ledger — say which filter did it
+        // (OSK-10953).
+        const filters = [
+            flags.status ? `--status ${flags.status}` : null,
+            flags['investigation-key'] ? `--investigation-key ${flags['investigation-key']}` : null,
+        ].filter(Boolean);
+        const emptyMessage = filters.length
+            ? `No hypotheses match ${filters.join(' ')}.`
+            : 'No hypotheses recorded.';
+        (0, commitments_1.renderCommitmentHypotheses)(response, (line) => this.log(line), { emptyMessage });
         (0, commitments_1.renderListPageHint)(response, (line) => this.log(line));
     }
 }

package/dist/commands/commitments/next-tick.js

@@ -71,6 +71,11 @@ function formatNextTick(projection) {
         // is entirely in that: a reader who thinks a check just ran will misread
         // every number on the commitment afterwards.
         'Projection only — no check was recorded, no budget spent, no action routed.',
+        // And what it does not MODEL (OSK-21104): it decides from the evidence alone. A real Check also
+        // applies the repeat-evidence window, earlier Runs and owed retries, today's Run budget, the
+        // dispatch breaker and the attention contract, so it can stop sooner than this, or run a
+        // retry this does not show. Without the sentence a projected `enqueue_agent_turn` reads as a promise.
+        "It decides from the evidence alone: a real check also applies the repeat-evidence window, earlier runs and owed retries, today's run budget, the dispatch breaker and the attention contract, so it can stop sooner (or run a retry) than shown here.",
         '',
         `Posture:    ${decision.posture ?? '-'}`,
         `Health:     ${decision.health ?? '-'}`,

package/dist/commands/commitments/observations.js

@@ -152,25 +152,26 @@ class CommitmentsObservations extends base_command_1.BaseCommand {
             this.handleApiError(err);
         }
         if (flags.json) {
+            // One JSON document and nothing else: has_more / next_cursor are in it
+            // (OSK-21118).
             this.printJsonResult(response);
+            return;
         }
-        else {
-            // "The commitment has none" and "your filter matched none" are different
-            // facts; a filter that empties the list must not claim the first
-            // (OSK-10953).
-            const filters = [
-                flags.latest ? '--latest' : null,
-                flags['declared-only'] ? '--declared-only' : null,
-                flags['changed-only'] ? '--changed-only' : null,
-                flags.since ? `--since ${flags.since}` : null,
-            ].filter(Boolean);
-            const emptyMessage = filters.length
-                ? `No observations match ${filters.join(' ')}.`
-                : 'No observations recorded.';
-            if (response?.truncated)
-                this.log(`TRUNCATED: ${response.omitted} current keys omitted; increase --limit (max 200).`);
-            (0, commitments_1.renderCommitmentObservations)(response, (line) => this.log(line), { emptyMessage });
-        }
+        // "The commitment has none" and "your filter matched none" are different
+        // facts; a filter that empties the list must not claim the first
+        // (OSK-10953).
+        const filters = [
+            flags.latest ? '--latest' : null,
+            flags['declared-only'] ? '--declared-only' : null,
+            flags['changed-only'] ? '--changed-only' : null,
+            flags.since ? `--since ${flags.since}` : null,
+        ].filter(Boolean);
+        const emptyMessage = filters.length
+            ? `No observations match ${filters.join(' ')}.`
+            : 'No observations recorded.';
+        if (response?.truncated)
+            this.log(`TRUNCATED: ${response.omitted} current keys omitted; increase --limit (max 200).`);
+        (0, commitments_1.renderCommitmentObservations)(response, (line) => this.log(line), { emptyMessage });
         (0, commitments_1.renderListPageHint)(response, (line) => this.log(line));
     }
 }

package/dist/commands/commitments/pack/list.js

@@ -41,7 +41,8 @@ class CommitmentsPackList extends base_command_1.BaseCommand {
         (0, format_1.renderTable)(rows.map((pack) => ({
             id: String(pack.id),
             version: String(pack.version),
-            title: String(pack.title || ''),
+            // The catalogue names a Pack `label`; reading only `title` printed a blank column for all eight.
+            title: String(pack.label || pack.title || ''),
         })), [
             // No maxWidth: a clipped pack id cannot be pasted into `pack plan --pack` (OSK-6175).
             { key: 'id', header: 'PACK ID' },

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

@@ -1,4 +1,10 @@
 import { BaseCommand } from '../../../base-command';
+import { type CommitmentPackPlanResponse } from '../../../lib/commitments';
+/**
+ * Lines for what the plan says will stop the loop from ever being activated. `bind` would still
+ * write a draft, so a reader who sees only "Nothing was created" must also see this.
+ */
+export declare function formatReadiness(readiness: CommitmentPackPlanResponse['readiness']): string[];
 /**
  * Draft what a Pack WOULD create, without creating it.
  *

package/dist/commands/commitments/pack/plan.js

@@ -1,8 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatReadiness = formatReadiness;
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../../base-command");
 const commitments_1 = require("../../../lib/commitments");
+/**
+ * Lines for what the plan says will stop the loop from ever being activated. `bind` would still
+ * write a draft, so a reader who sees only "Nothing was created" must also see this.
+ */
+function formatReadiness(readiness) {
+    if (!readiness?.length)
+        return [];
+    const lines = [];
+    for (const item of readiness) {
+        lines.push(`Not ready:  ${item.label} — ${item.reason}`);
+        if (item.hint)
+            lines.push(`            ${item.hint}`);
+    }
+    lines.push('            `bind` would still create the draft, but `pack activate` will be refused until this is fixed.');
+    return lines;
+}
 /**
  * Draft what a Pack WOULD create, without creating it.
  *
@@ -87,6 +104,8 @@ class CommitmentsPackPlan extends base_command_1.BaseCommand {
             const holder = placement.holder === 'space_lead' ? ' (the Space lead)' : '';
             this.log(`Space loop: ${placement.spaceId}, held by ${placement.agentId}${holder}`);
         }
+        for (const line of formatReadiness(result.readiness))
+            this.log(line);
         this.log('\nNothing was created. Pass this digest to `skrr commitments pack bind --plan-digest`.');
     }
 }

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

@@ -35,7 +35,26 @@ export declare function nextRunsLines(report: {
     verdict?: string;
     nextRuns?: string[];
 }): string[];
+/**
+ * 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.
+ */
+export declare function preflightHeadline(report: Pick<CommitmentPreflightReport, 'verdict' | 'gates'>, persisted: boolean): string;
 export declare function preflightGateLines(gate: PreflightGate, verbose?: boolean): string[];
+/**
+ * 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).
+ */
+export declare function attentionFooterLines(attention: CommitmentPreflightReport['attention'] | undefined, policy?: Record<string, any> | null, verbose?: boolean): string[];
 export default class CommitmentsPreflight extends BaseCommand {
     static description: string;
     static examples: string[];

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,6 +44,25 @@ function nextRunsLines(report) {
         : 'Next runs:';
     return ['', header, ...report.nextRuns.map((run) => `  ${run}`)];
 }
+/**
+ * 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) {
     // "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,
@@ -50,15 +72,36 @@ 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.
+    const advisoryBlock = gate.verdict === 'block' && gate.admission === 'advisory';
+    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 +118,8 @@ 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)' : ''),
     ];
     if (hasNote) {
         lines.push(`        ${String(note).trim()}`);
@@ -92,6 +136,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 +167,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 +225,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 +265,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).
@@ -211,7 +308,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/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() {