@skrr-ai/cli 0.1.127 → 0.1.129

package/dist/lib/commitments.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COMMITMENT_CLI_EVALUATORS = exports.COMMITMENT_CREATE_KEYS = exports.COMMITMENT_REMEDIATION_ACTIONS = exports.COMMITMENT_FEEDBACK_KINDS = exports.commitmentApi = exports.commitmentPackApi = exports.MAX_COMMITMENT_INTERVAL_MS = exports.MIN_COMMITMENT_INTERVAL_MS = exports.COMMITMENT_EXECUTION_ISOLATION_MODES = exports.COMMITMENT_AUTHORABLE_CADENCE_MODES = exports.COMMITMENT_KIND_VALUES = exports.COMMITMENT_STATUSES = exports.COMMITMENT_CADENCE_MAX_TIMES = exports.COMMITMENT_CADENCE_TIME_PATTERN = exports.COMMITMENT_CADENCE_MODES = exports.COMMITMENT_TEMPLATE_IDS = exports.COMMITMENT_WATCHED_SOURCES = void 0;
+exports.activationRefusalLines = activationRefusalLines;
+exports.gateRefusesActivation = gateRefusesActivation;
 exports.permissionLines = permissionLines;
 exports.scheduleIssueLines = scheduleIssueLines;
 exports.retiredFieldsLine = retiredFieldsLine;
 exports.readCommitmentAgentDirective = readCommitmentAgentDirective;
+exports.unrecognizedCreateKeys = unrecognizedCreateKeys;
+exports.ignoredCreateKeys = ignoredCreateKeys;
+exports.ignoredCreateKeysWarning = ignoredCreateKeysWarning;
 exports.normalizeCreateBody = normalizeCreateBody;
 exports.parseCommitmentConcurrencyLimit = parseCommitmentConcurrencyLimit;
 exports.commitmentConcurrencyEnvelopePatch = commitmentConcurrencyEnvelopePatch;
@@ -29,6 +34,9 @@ exports.withLiveAssessment = withLiveAssessment;
 exports.commitmentWriteWarnings = commitmentWriteWarnings;
 exports.renderCommitmentWriteWarnings = renderCommitmentWriteWarnings;
 exports.describeCommitmentRevision = describeCommitmentRevision;
+exports.describeCommitmentPriority = describeCommitmentPriority;
+exports.describeBoundCompass = describeBoundCompass;
+exports.explainCompassLines = explainCompassLines;
 exports.renderCommitmentSummary = renderCommitmentSummary;
 exports.describeWakeDecision = describeWakeDecision;
 exports.renderCheckList = renderCheckList;
@@ -37,6 +45,7 @@ exports.renderCommitmentTrace = renderCommitmentTrace;
 exports.renderProactivenessScorecard = renderProactivenessScorecard;
 exports.formatCommitmentCycles = formatCommitmentCycles;
 exports.hypothesisRefusalLines = hypothesisRefusalLines;
+exports.wakeOutcomeLines = wakeOutcomeLines;
 exports.formatCommitmentExplanation = formatCommitmentExplanation;
 exports.renderListPageHint = renderListPageHint;
 exports.describeObservationArtifacts = describeObservationArtifacts;
@@ -80,6 +89,7 @@ Object.defineProperty(exports, "COMMITMENT_EXECUTION_ISOLATION_MODES", { enumera
 Object.defineProperty(exports, "COMMITMENT_STATUSES", { enumerable: true, get: function () { return data_provider_2.COMMITMENT_STATUSES; } });
 Object.defineProperty(exports, "COMMITMENT_KIND_VALUES", { enumerable: true, get: function () { return data_provider_2.COMMITMENT_KIND_VALUES; } });
 const commitment_product_1 = require("./commitment-product");
+const commitment_attention_copy_1 = require("./commitment-attention-copy");
 const instruction_input_1 = require("./instruction-input");
 const format_1 = require("./format");
 const triggers_1 = require("./triggers");
@@ -95,6 +105,41 @@ exports.COMMITMENT_AUTHORABLE_CADENCE_MODES = data_provider_2.COMMITMENT_CADENCE
  */
 exports.MIN_COMMITMENT_INTERVAL_MS = 60_000;
 exports.MAX_COMMITMENT_INTERVAL_MS = 365 * 24 * 60 * 60 * 1000;
+/**
+ * The lines preflight prints when the server says activation would be refused (OSK-21258). The gate
+ * list marks an advisory gate `info (advisory: does not stop a run)`, which is true of a run and false
+ * of activation: `resume` refused the same gate with a 409 while preflight read as if nothing stopped
+ * it. The server owns which gates refuse; this lays out its answer and never re-derives it. Nothing
+ * for an allowed activation or an older server that does not send the block.
+ */
+function activationRefusalLines(activation) {
+    if (!activation || activation.canActivate !== false)
+        return [];
+    const blockers = activation.blockers ?? [];
+    if (!blockers.length)
+        return ['Activation: would be refused (the server named no gate)'];
+    const lines = ['Activation: would be refused'];
+    for (const blocker of blockers) {
+        lines.push(`  - ${blocker.label || blocker.gate}${blocker.reason ? ` (${blocker.reason})` : ''}`);
+        if (blocker.hint)
+            lines.push(`    ${blocker.hint}`);
+    }
+    return lines;
+}
+/**
+ * Whether the server's activation answer names this gate as one that refuses activation (OSK-21258).
+ * A gate can be advisory for a run (`admission: 'advisory'`) and still be what `resume` refuses with a
+ * 409; the gate list printed it `info (advisory: does not stop a run)` right under an "Activation:
+ * would be refused" section naming the same gate. Matches on the gate id, and on the reason too when
+ * both sides carry one, so a gate advisory for one reason is not promoted by another. An older server
+ * that sends no answer promotes nothing.
+ */
+function gateRefusesActivation(activation, gate) {
+    if (!activation || activation.canActivate !== false || !gate?.id)
+        return false;
+    return (activation.blockers ?? []).some((blocker) => blocker.gate === gate.id &&
+        (!blocker.reason || !gate.reason || blocker.reason === gate.reason));
+}
 /**
  * The lines every Commitment read surface prints for "whose permissions does a
  * run use?" — `show`, `effective-policy` and `preflight` share it so the three
@@ -414,6 +459,87 @@ async function readCommitmentAgentDirective({ directive, file, }) {
     }
     return (0, instruction_input_1.readInstructionBody)({ body: directive, file });
 }
+/**
+ * What a contract dumped from `show`/`list --json` carries that is the server's, not the author's. These are
+ * dropped on purpose and never reported.
+ */
+const SERVER_OWNED_CONTRACT_KEYS = new Set([
+    'id',
+    'ownerUserId',
+    'workspaceId',
+    'version',
+    'createdAt',
+    'updatedAt',
+    'createdBy',
+    'updatedBy',
+    'state',
+    'firstActivatedAt',
+    'executionEpoch',
+    'alwaysOnGeneration',
+    'requiresAlwaysOn',
+    'assessment',
+    'abilities',
+    'url',
+    'latestCheck',
+    'operatingState',
+    'triggerPlan',
+    'executorHandovers',
+    'priority',
+    'proposal',
+    'rationale',
+    'droppedFields',
+    'warnings',
+]);
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const above = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length];
+}
+/**
+ * The top-level keys of a `--from-json` body that `create`/`preflight` will not send. A key within two edits
+ * of a real one is a `typo`; the rest are `ignored`. A server-owned dump field is neither.
+ */
+function unrecognizedCreateKeys(src) {
+    const known = exports.COMMITMENT_CREATE_KEYS;
+    const typos = [];
+    const ignored = [];
+    for (const key of Object.keys(src || {})) {
+        if (known.includes(key) || SERVER_OWNED_CONTRACT_KEYS.has(key))
+            continue;
+        const near = key.length >= 4
+            ? known.find((candidate) => candidate.length >= 4 &&
+                editDistance(key.toLowerCase(), candidate.toLowerCase()) <= 2)
+            : undefined;
+        if (near)
+            typos.push({ key, suggestion: near });
+        else
+            ignored.push(key);
+    }
+    return { typos, ignored };
+}
+/** The keys of a `--from-json` body that are neither sent nor server-owned and not a typo: to be warned about. */
+function ignoredCreateKeys(input) {
+    const envelope = input;
+    const src = envelope && typeof envelope.proposal === 'object' && envelope.proposal !== null
+        ? envelope.proposal
+        : input || {};
+    return unrecognizedCreateKeys(src).ignored;
+}
+/** The one sentence `create` and `preflight` print for them. */
+function ignoredCreateKeysWarning(keys) {
+    if (keys.length === 0)
+        return null;
+    return (`--from-json: ${keys.map((key) => `"${key}"`).join(', ')} ${keys.length === 1 ? 'is' : 'are'} not sent ` +
+        '(the CLI does not forward it), so the Commitment is built without it.');
+}
 /**
  * Normalize a `--from-json` body into something the create endpoint accepts.
  *
@@ -433,6 +559,16 @@ function normalizeCreateBody(input) {
     const src = envelope && typeof envelope.proposal === 'object' && envelope.proposal !== null
         ? envelope.proposal
         : input || {};
+    // Dropping a key the body does not declare is deliberate for what a dumped contract carries (id, version,
+    // state, ...). It is not for a typo of a real field: `cadance` was dropped and the Commitment created with
+    // the default manual cadence, exit 0, while the same body over REST is a 400 (dogfood
+    // df-261031-commitment-authoring, OSK-21246).
+    const { typos } = unrecognizedCreateKeys(src);
+    if (typos.length > 0) {
+        throw new Error(`--from-json has ${typos.length === 1 ? 'a field' : 'fields'} the API does not know: ` +
+            `${typos.map((t) => `"${t.key}" (did you mean "${t.suggestion}"?)`).join(', ')}. ` +
+            'Nothing was sent: the API refuses unknown fields, and dropping them here would create the Commitment without them.');
+    }
     const out = {};
     for (const key of exports.COMMITMENT_CREATE_KEYS) {
         if (src[key] !== undefined)
@@ -976,6 +1112,12 @@ function describeExecutorBlocked(commitment) {
  * operation and reason is printed as it always was.
  */
 function describeOperation(operation, reason) {
+    // "Cannot tell" travels as `blocked` + this reason (the server's `storedOperation`: no status
+    // recorded yet for this version of the contract, or the recorded one expired). A Commitment that
+    // was turned on a moment ago is in exactly that state, and `blocked` read as a refused activation
+    // while `show` said `ready` seconds later (OSK-21105).
+    if (reason === 'operation_read_unavailable')
+        return 'not read yet — no status is recorded for the current contract, which is not a failure; `skrr commitments show` reads it live';
     const lifecycle = typeof reason === 'string' ? /^lifecycle_([a-z_]+)$/.exec(reason) : null;
     if (!lifecycle)
         return `${operation ?? 'blocked'}${reason ? ` — ${reason}` : ''}`;
@@ -1135,6 +1277,56 @@ function describeCommitmentRevision(revision) {
     }
     return `Updated commitment (version ${revision.previousVersion} -> ${revision.version}):`;
 }
+/**
+ * A commitment's priority, as one line: `high · weight 70 · from northstar`.
+ *
+ * Linking a commitment to a northstar rewrites its priority (`source: northstar`) and a governor
+ * reprioritization changes it again, so the place a person looks to confirm either is `show`, which
+ * printed everything but this and sent them to `--json`. An unset priority says so rather than
+ * printing nothing.
+ */
+function describeCommitmentPriority(priority) {
+    const parts = [];
+    if (priority?.tier)
+        parts.push(priority.tier);
+    if (typeof priority?.weight === 'number')
+        parts.push(`weight ${priority.weight}`);
+    if (priority?.source === 'northstar')
+        parts.push('from northstar');
+    else if (priority?.source === 'manual')
+        parts.push('set manually');
+    return parts.length ? parts.join(' · ') : 'not set';
+}
+/**
+ * The `Compass:` line of a bound commitment. A commitment names its compass (`compassId`) but the
+ * read does not carry that compass's STATUS, and an archived one governs nothing (the commitment
+ * runs on defaults), so the id alone could be read as "governed by it". Only what is known is
+ * stated: the id, and the command that says whether it is active (OSK-21242).
+ */
+function describeBoundCompass(commitment) {
+    const id = commitment.compassId ?? '-';
+    const agent = commitment.agentId ?? '<agent-id>';
+    return `Compass:   ${id} — status not shown here; an archived compass governs nothing: \`skrr compass show ${id} --agent ${agent}\``;
+}
+/**
+ * The bound Compass, as `explain` prints it (OSK-21332). `explain` is where a person asks "why does
+ * this Commitment behave this way", and a bound Compass (or an archived one, which runs the
+ * Commitment on defaults) is part of the answer. The explain payload names neither the Compass nor
+ * its status, so the caller reads the Commitment itself, the same read `show` renders, and hands the
+ * result here: the line is `describeBoundCompass`, the one `show` prints, not a second wording.
+ *
+ * `null` means that read did not come back. It is said, not skipped: a silent skip is
+ * indistinguishable from "no Compass is bound". A Commitment bound to none prints nothing, as in
+ * `show`.
+ */
+function explainCompassLines(commitmentId, commitment) {
+    if (!commitment) {
+        return [
+            `Compass:   not shown — the commitment could not be read just now; \`skrr commitments show ${commitmentId}\` prints it`,
+        ];
+    }
+    return commitment.compassId ? [describeBoundCompass(commitment)] : [];
+}
 function renderCommitmentSummary(commitment, log, 
 /**
  * The most recent check, when the caller has one. Optional because pause /
@@ -1174,6 +1366,9 @@ scheduleIssues) {
         log(`Goal:      ${commitment.goalId}`);
     if (commitment.northstarId)
         log(`Northstar: ${commitment.northstarId}`);
+    if (commitment.compassId)
+        log(describeBoundCompass(commitment));
+    log(`Priority:  ${describeCommitmentPriority(commitment.priority)}`);
     if (commitment.target?.outcome)
         log(`Outcome:   ${commitment.target.outcome}`);
     if (commitment.target?.deadlineAt)
@@ -1184,6 +1379,13 @@ scheduleIssues) {
     log(`Delivery:  ${(0, commitment_product_1.deliveryLabel)(commitment.delivery?.mode)}${commitment.delivery?.repo ? ` · ${commitment.delivery.repo}` : ''}${commitment.delivery?.baseBranch ? ` → ${commitment.delivery.baseBranch}` : ''}`);
     log(`Concurrency: ${describeCommitmentConcurrency(commitment)}`);
     log(`Evidence gate: ${describeEvidenceGate(commitment)}`);
+    // How much it may interrupt the owner (OSK-21120). A server that sent no policy prints
+    // nothing, rather than a guess that reads as "unlimited".
+    if (commitment.policy) {
+        for (const line of (0, commitment_attention_copy_1.nudgeSettingLines)((0, commitment_attention_copy_1.nudgeSettingsFromPolicy)(commitment.policy)))
+            log(line);
+        log(`Quiet hours: ${(0, commitment_attention_copy_1.describeQuietHours)(commitment.policy.quietHours)}`);
+    }
     const criteria = commitment.target?.successCriteria || [];
     const evidenceHealth = latestCheck?.inputs?.evidenceHealth;
     const evidenceLine = describeEvidenceHealth(evidenceHealth, criteria.length);
@@ -1643,6 +1845,9 @@ const CYCLE_GLYPH = {
     stopped: '●',
     quiet: '○',
     in_flight: '◌',
+    // An applied result whose agent said work is warranted and left nothing the platform can see
+    // (OSK-21608): not a tick, because the work is still owed, and not a stop, because it applied.
+    owed: '◐',
 };
 /** `MM-DD HH:MM` in the reader's local time; `-` when the time is unknown. */
 function cycleTime(value) {
@@ -1672,6 +1877,11 @@ function cycleSummary(cycle) {
         return `${question}  ${reason || gate} — ${fix || detail || 'stopped'}${moved}`;
     }
     if (cycle.outcome === 'advanced') {
+        if (cycle.owed) {
+            return cycle.advancementKinds?.length
+                ? `${cycle.advancementKinds.join(', ')} — ${data_provider_2.COMMITMENT_CYCLE_OWED_SENTENCE}`
+                : data_provider_2.COMMITMENT_CYCLE_OWED_SENTENCE;
+        }
         return cycle.advancementKinds?.length
             ? cycle.advancementKinds.join(', ')
             : 'applied an agent result';
@@ -1682,6 +1892,13 @@ function cycleSummary(cycle) {
     }
     return cycle.note || cycle.decision?.summary || cycle.decision?.posture || 'nothing to act on';
 }
+/** A record-only follow-through says what it is, and what it noted, instead of claiming progress. */
+function recordOnlyEchoSummary(cycle) {
+    const noted = cycle.advancementKinds?.length
+        ? ` (noted: ${cycle.advancementKinds.join(', ')})`
+        : '';
+    return `records the earlier run's outcome; no work of its own${noted}`;
+}
 /** Content-free rows admitted by the native sensor loader; licenses stay unknown. */
 function platformFetchLines(cycle) {
     const lines = [];
@@ -1713,8 +1930,17 @@ function formatCommitmentCycles(page) {
         return ['No cycles recorded yet.'];
     const lines = [];
     for (const cycle of cycles) {
-        const glyph = CYCLE_GLYPH[cycle.outcome] || '?';
-        lines.push(`${cycleTime(cycle.startedAt)}  ${glyph} ${String(cycle.outcome).padEnd(9)}  ${cycleWake(cycle).padEnd(18)}  ${cycleSummary(cycle)}`);
+        // A follow-through Check that only records the Run before it is not what the loop did, and
+        // `✓ advanced` above a stopped Run reads as if the work had moved (OSK-21240).
+        const echo = (0, data_provider_2.isRecordOnlyEchoCycle)(cycle);
+        const owed = !echo && cycle.outcome === 'advanced' && cycle.owed === true;
+        const glyph = echo
+            ? CYCLE_GLYPH.quiet
+            : owed
+                ? CYCLE_GLYPH.owed
+                : CYCLE_GLYPH[cycle.outcome] || '?';
+        const word = echo ? 'recorded' : owed ? 'owed' : String(cycle.outcome);
+        lines.push(`${cycleTime(cycle.startedAt)}  ${glyph} ${word.padEnd(9)}  ${cycleWake(cycle).padEnd(18)}  ${echo ? recordOnlyEchoSummary(cycle) : cycleSummary(cycle)}`);
         lines.push(...platformFetchLines(cycle));
         lines.push(...formatCycleLatency(cycle));
         for (const task of cycle.tasks || []) {
@@ -1730,6 +1956,8 @@ function formatCommitmentCycles(page) {
                 lines.push(`             run ${run.id} report: ${run.reportPayload.status === 'rejected' ? 'structured report rejected; plain summary used' : 'structured report validated (delivery tracked separately)'}`);
             for (const line of hypothesisRefusalLines(run))
                 lines.push(`             ${line}`);
+            for (const line of wakeOutcomeLines(run))
+                lines.push(`             ${line}`);
             if (!['machine', 'contract', 'work'].includes(run.failureClass))
                 continue;
             const owner = run.failureOwner === 'model' ? 'model' : run.failureOwner || 'work';
@@ -1784,6 +2012,20 @@ const HYPOTHESIS_REFUSAL_REASON = {
 function hypothesisRefusalLines(run) {
     return (run.hypothesisRefusals || []).map((refusal) => `${refusal.count} ${refusal.count === 1 ? 'hypothesis' : 'hypotheses'} not recorded: ${HYPOTHESIS_REFUSAL_REASON[refusal.reason] || refusal.reason} (${refusal.reason})`);
 }
+/**
+ * A wake the Agent asked for and the platform did not arm, in the server's words.
+ * The only record used to be `ledger --json`; the cycle read `advanced` (OSK-21132).
+ */
+function wakeOutcomeLines(run) {
+    const wake = run.wake;
+    if (!wake?.detail)
+        return [];
+    const label = wake.status === 'awaiting_approval' ? 'wake request waiting' : 'wake not armed';
+    return [
+        `${label}: ${wake.detail}${wake.reason ? ` (${wake.reason})` : ''}`,
+        ...(wake.fix ? [`  Fix: ${wake.fix}`] : []),
+    ];
+}
 function formatCommitmentExplanation(explanation) {
     const cycle = explanation.cycle;
     const lines = [
@@ -1819,6 +2061,8 @@ function formatCommitmentExplanation(explanation) {
                 lines.push(`  run ${run.id} report: ${run.reportPayload.status === 'rejected' ? 'structured report rejected; plain summary used' : 'structured report validated (delivery tracked separately)'}`);
             for (const line of hypothesisRefusalLines(run))
                 lines.push(`  ${line}`);
+            for (const line of wakeOutcomeLines(run))
+                lines.push(`  ${line}`);
         }
     }
     lines.push(...permissionLines(explanation.permissions));
@@ -1827,6 +2071,10 @@ function formatCommitmentExplanation(explanation) {
 /**
  * Print the continuation hint for a paged `object:'list'` response — the line
  * that makes history beyond the newest page reachable instead of invisible.
+ *
+ * Text mode ONLY. Under `--json` stdout must be one JSON document, and the same
+ * facts are already in it as `has_more` / `next_cursor`: a caller that prints
+ * this after the JSON makes `| json.load` fail (OSK-21118).
  */
 function renderListPageHint(page, log) {
     if (page?.has_more === true && page.next_cursor) {

package/dist/lib/compass-body-help.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What `--json-body` takes on `skrr compass create` and `skrr compass update` (OSK-21154).
+ *
+ * The flag's help said only "a JSON file with the full body", so the field names, the
+ * invariant-target limit and the quiet-hours rules were found by guessing and by being refused. One
+ * declaration, read by both commands' help so they cannot drift apart. The server owns every rule
+ * stated here (`api/server/services/AgentCompass/CompassPolicyContract.js` and the route schemas); the
+ * limits are written out because a help screen is read before the first request is sent, and
+ * `docs/cli/SKRR_COMPASS.md` ("Body shape") carries the same table.
+ *
+ * ONE SHORT LINE PER FIELD, each beginning with its full path. oclif runs a description through
+ * `wrap-ansi` (hard wrap at the terminal width minus 2, 80 when not a terminal) which TRIMS every
+ * line's leading spaces, so the indentation this list used to carry collapsed (`id` and
+ * `description` read as top-level fields) and its long lines broke mid-sentence. A path prefix is
+ * not whitespace, so the nesting survives, and no line is longer than 77 characters, so none wraps
+ * (`help.spec.ts` runs the real wrap over it) (OSK-21243).
+ */
+export declare const COMPASS_BODY_HELP: string;
+/** An example body: two targets (one domain-scoped, one general) and a quiet-hours window. */
+export declare const COMPASS_BODY_EXAMPLE = "# compass.json\n{\n  \"title\": \"Production reliability\",\n  \"invariantTargets\": [\n    { \"id\": \"api-latency\", \"domainKind\": \"reliability\", \"description\": \"p99 API latency stays under 300 ms\" },\n    { \"id\": \"general\", \"description\": \"Nothing the owner has not seen ships on a Friday\" }\n  ],\n  \"autonomyDefaults\": {\n    \"mode\": \"ask_first\",\n    \"quietHours\": { \"enabled\": true, \"start\": \"22:00\", \"end\": \"07:00\", \"timezone\": \"America/New_York\" }\n  }\n}";

package/dist/lib/compass-body-help.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPASS_BODY_EXAMPLE = exports.COMPASS_BODY_HELP = void 0;
+/**
+ * What `--json-body` takes on `skrr compass create` and `skrr compass update` (OSK-21154).
+ *
+ * The flag's help said only "a JSON file with the full body", so the field names, the
+ * invariant-target limit and the quiet-hours rules were found by guessing and by being refused. One
+ * declaration, read by both commands' help so they cannot drift apart. The server owns every rule
+ * stated here (`api/server/services/AgentCompass/CompassPolicyContract.js` and the route schemas); the
+ * limits are written out because a help screen is read before the first request is sent, and
+ * `docs/cli/SKRR_COMPASS.md` ("Body shape") carries the same table.
+ *
+ * ONE SHORT LINE PER FIELD, each beginning with its full path. oclif runs a description through
+ * `wrap-ansi` (hard wrap at the terminal width minus 2, 80 when not a terminal) which TRIMS every
+ * line's leading spaces, so the indentation this list used to carry collapsed (`id` and
+ * `description` read as top-level fields) and its long lines broke mid-sentence. A path prefix is
+ * not whitespace, so the nesting survives, and no line is longer than 77 characters, so none wraps
+ * (`help.spec.ts` runs the real wrap over it) (OSK-21243).
+ */
+exports.COMPASS_BODY_HELP = [
+    '--json-body takes the API body as a JSON file; the flags are merged over it.',
+    'Each line below names one field by its full path:',
+    'title, domain, reason: strings (reason is what the revision ledger shows)',
+    'invariantTargets[]: what the agent keeps true',
+    'invariantTargets[]: AT MOST 25: more is refused with the count sent',
+    'invariantTargets[].id: optional, unique in the list (a repeat is refused)',
+    'invariantTargets[].id: default invariant_<position>',
+    'invariantTargets[].description: required on create',
+    'invariantTargets[].domainKind: optional; leave it off ONE target',
+    'invariantTargets[].domainKind: the target without one is the general fallback',
+    'invariantTargets[].maintainedState[]: list of strings',
+    'invariantTargets[].successMetrics[]: list of strings',
+    'invariantTargets[].boundaries[]: list of strings',
+    'invariantTargets[].cadence, .escalation, .stateMonitor: advanced',
+    'invariantTargets[].learnedTactics[]: advanced; see docs/cli/SKRR_COMPASS.md',
+    'autonomyDefaults.mode: off | suggestions_only | ask_first | auto_run_limited',
+    'autonomyDefaults.mode: auto_run (short forms: suggest, auto)',
+    'autonomyDefaults.quietHours = {"enabled":true,"start":"22:00","end":"07:00"}',
+    'autonomyDefaults.quietHours.start, .end: HH:MM, 00:00 to 23:59',
+    'autonomyDefaults.quietHours: start must differ from end; refused otherwise',
+    'autonomyDefaults.quietHours.timezone: an IANA zone, e.g. America/New_York',
+    'communicationDefaults: mode, destination, fallbackDestination, quietHours',
+    'communicationDefaults.allowedDestinations[]: list of strings',
+    'communicationDefaults.requireApprovalRiskLevels[]: list of strings',
+    'communicationDefaults: any other key is stored as a note and never read',
+    'rules[]: owner-enforced, Agent owner only; see docs/cli/SKRR_COMPASS.md',
+].join('\n');
+/** An example body: two targets (one domain-scoped, one general) and a quiet-hours window. */
+exports.COMPASS_BODY_EXAMPLE = `# compass.json
+{
+  "title": "Production reliability",
+  "invariantTargets": [
+    { "id": "api-latency", "domainKind": "reliability", "description": "p99 API latency stays under 300 ms" },
+    { "id": "general", "description": "Nothing the owner has not seen ships on a Friday" }
+  ],
+  "autonomyDefaults": {
+    "mode": "ask_first",
+    "quietHours": { "enabled": true, "start": "22:00", "end": "07:00", "timezone": "America/New_York" }
+  }
+}`;

package/dist/lib/compass-refusals.d.ts

@@ -0,0 +1,35 @@
+/**
+ * compass-refusals.ts — the words for the two Compass refusals a person acts on.
+ *
+ * `COMPASS_VERSION_CONFLICT` (409) and `COMPASS_REVISION_NOT_FOUND` (404) used to reach the
+ * terminal as `HTTP_409` and `NOT_FOUND`, with the one fact that makes each actionable dropped:
+ * where the Compass is now, and which version was missing (OSK-21162, OSK-21152).
+ *
+ * The route sends the code in upper-case `error` (and now in `code` too). `refusalCodeOf` does
+ * not read the first as a code, and widening it for every route is not this module's call, so
+ * `compassRefusalCode` reads both spellings here, for these two codes only. No imports: this is
+ * pure, and `base-command` loads it.
+ */
+export declare const COMPASS_VERSION_CONFLICT = "COMPASS_VERSION_CONFLICT";
+export declare const COMPASS_REVISION_NOT_FOUND = "COMPASS_REVISION_NOT_FOUND";
+export type CompassRefusalCode = typeof COMPASS_VERSION_CONFLICT | typeof COMPASS_REVISION_NOT_FOUND;
+/**
+ * What the failing request was about, for a refusal whose remedy is a command that names it. The
+ * command sets this before it sends, as it sets `requestFieldFlags`. The server's own body wins
+ * where it carries the same fact; these cover a server that does not send it yet.
+ */
+export interface CompassRefusalContext {
+    compassId?: string;
+    agentId?: string;
+    /** The version the caller based the change on. */
+    expectedVersion?: number;
+    /** The version a revert asked for. */
+    toVersion?: number;
+}
+/** The Compass refusal an API error body carries, under `code` or the legacy `error`. */
+export declare function compassRefusalCode(body: Record<string, unknown> | null | undefined): CompassRefusalCode | undefined;
+/**
+ * The refusal as a sentence, then the command to run next on its own line (the shape
+ * `COMMITMENT_ACTIVATION_BLOCKED` uses: `→`).
+ */
+export declare function describeCompassRefusal(code: CompassRefusalCode, body: Record<string, unknown> | null | undefined, context: CompassRefusalContext, bin: string): string;

package/dist/lib/compass-refusals.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * compass-refusals.ts — the words for the two Compass refusals a person acts on.
+ *
+ * `COMPASS_VERSION_CONFLICT` (409) and `COMPASS_REVISION_NOT_FOUND` (404) used to reach the
+ * terminal as `HTTP_409` and `NOT_FOUND`, with the one fact that makes each actionable dropped:
+ * where the Compass is now, and which version was missing (OSK-21162, OSK-21152).
+ *
+ * The route sends the code in upper-case `error` (and now in `code` too). `refusalCodeOf` does
+ * not read the first as a code, and widening it for every route is not this module's call, so
+ * `compassRefusalCode` reads both spellings here, for these two codes only. No imports: this is
+ * pure, and `base-command` loads it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPASS_REVISION_NOT_FOUND = exports.COMPASS_VERSION_CONFLICT = void 0;
+exports.compassRefusalCode = compassRefusalCode;
+exports.describeCompassRefusal = describeCompassRefusal;
+exports.COMPASS_VERSION_CONFLICT = 'COMPASS_VERSION_CONFLICT';
+exports.COMPASS_REVISION_NOT_FOUND = 'COMPASS_REVISION_NOT_FOUND';
+/** The Compass refusal an API error body carries, under `code` or the legacy `error`. */
+function compassRefusalCode(body) {
+    for (const key of ['code', 'error']) {
+        const value = body?.[key];
+        if (value === exports.COMPASS_VERSION_CONFLICT || value === exports.COMPASS_REVISION_NOT_FOUND)
+            return value;
+    }
+    return undefined;
+}
+function versionOf(value) {
+    return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+}
+/**
+ * The refusal as a sentence, then the command to run next on its own line (the shape
+ * `COMMITMENT_ACTIVATION_BLOCKED` uses: `→`).
+ */
+function describeCompassRefusal(code, body, context, bin) {
+    const compassId = context.compassId ?? '<compass-id>';
+    const agentId = context.agentId ?? '<agent-id>';
+    const current = versionOf(body?.currentVersion);
+    if (code === exports.COMPASS_VERSION_CONFLICT) {
+        const sent = versionOf(body?.expectedVersion) ?? context.expectedVersion;
+        const where = current !== undefined ? `it is at v${current} now` : 'it changed while this was being saved';
+        return (`Compass version conflict: ${where}${sent !== undefined ? `, and this change was based on v${sent}` : ''}.\n` +
+            `  → Re-read it with \`${bin} compass show ${compassId} --agent ${agentId}\`, review what changed, and retry.`);
+    }
+    const asked = versionOf(body?.toVersion) ?? context.toVersion;
+    return (`Compass revision ${asked !== undefined ? `v${asked} ` : ''}not found` +
+        `${current !== undefined ? `: the Compass is at v${current}` : ''}.\n` +
+        `  → List its versions with \`${bin} compass revisions ${compassId} --agent ${agentId}\`, then pass one as --to-version.`);
+}