@skrr-ai/cli 0.1.8

package/dist/lib/commitments.js

@@ -0,0 +1,889 @@
+"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_AUTONOMY_MODES = 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.normalizeCreateBody = normalizeCreateBody;
+exports.parseIntervalToMs = parseIntervalToMs;
+exports.describeEvidenceHealth = describeEvidenceHealth;
+exports.describeIntervalMs = describeIntervalMs;
+exports.buildSuccessCriteria = buildSuccessCriteria;
+exports.cadenceLabel = cadenceLabel;
+exports.renderCommitmentList = renderCommitmentList;
+exports.effectiveAutonomyMode = effectiveAutonomyMode;
+exports.describeAutonomyLine = describeAutonomyLine;
+exports.renderCommitmentSummary = renderCommitmentSummary;
+exports.describeWakeDecision = describeWakeDecision;
+exports.renderCheckList = renderCheckList;
+exports.renderCommitmentLedger = renderCommitmentLedger;
+exports.renderCommitmentTrace = renderCommitmentTrace;
+exports.renderCommitmentObservations = renderCommitmentObservations;
+exports.renderCommitmentHypotheses = renderCommitmentHypotheses;
+exports.renderCommitmentLineage = renderCommitmentLineage;
+exports.renderCommitmentMetrics = renderCommitmentMetrics;
+/**
+ * commitments.ts — request-based client for the Commitments subsystem
+ * (`/api/commitments/*`).
+ *
+ * Mirrors the `triggerApi` / `scheduleApi` pattern: these endpoints are not
+ * exposed as `dataService.*` functions, so the CLI talks to them through the
+ * shared `request` transport.
+ *
+ * Concept: a **Commitment** is a durable, agent-scoped contract —
+ * "hold this outcome true, and watch these sources on this cadence". It is NOT a
+ * unit of work. It sits ABOVE goals/tasks (which it watches as sensors) and runs
+ * its own closed control loop: a fast `commitment_check` (sense → project open
+ * loops → decide a posture → route actions) and a slower reflection that retunes
+ * the commitment's own cadence from realized outcomes.
+ *
+ * Two `kind`s: `achieve` (bounded, deadline-bearing) and `maintain` (perpetual
+ * "hold this state", derived from a Compass invariant — not authored here).
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+Object.defineProperty(exports, "COMMITMENT_WATCHED_SOURCES", { enumerable: true, get: function () { return data_provider_1.COMMITMENT_WATCHED_SOURCES; } });
+Object.defineProperty(exports, "COMMITMENT_TEMPLATE_IDS", { enumerable: true, get: function () { return data_provider_1.COMMITMENT_TEMPLATE_IDS; } });
+Object.defineProperty(exports, "COMMITMENT_CADENCE_MODES", { enumerable: true, get: function () { return data_provider_1.COMMITMENT_CADENCE_MODES; } });
+Object.defineProperty(exports, "COMMITMENT_CADENCE_TIME_PATTERN", { enumerable: true, get: function () { return data_provider_1.COMMITMENT_CADENCE_TIME_PATTERN; } });
+Object.defineProperty(exports, "COMMITMENT_CADENCE_MAX_TIMES", { enumerable: true, get: function () { return data_provider_1.COMMITMENT_CADENCE_MAX_TIMES; } });
+const format_1 = require("./format");
+const triggers_1 = require("./triggers");
+/**
+ * oclif's `options:` needs runtime arrays, but data-provider models these two as
+ * union TYPES only. The values live here — and both directions of drift are a
+ * COMPILE error: `satisfies` rejects an invalid or extra value, and the
+ * `_Exhaustive*` guards fail to resolve if a canonical value is missing.
+ */
+exports.COMMITMENT_STATUSES = [
+    'draft',
+    'active',
+    'paused',
+    'completed',
+    'cancelled',
+    'archived',
+];
+const _statusDriftGuard = true;
+void _statusDriftGuard;
+/** Autonomy ladder — how much the commitment may act without asking. */
+exports.COMMITMENT_AUTONOMY_MODES = [
+    'off',
+    'suggestions_only',
+    'ask_first',
+    'auto_run_limited',
+    'auto_run',
+];
+const _autonomyDriftGuard = true;
+void _autonomyDriftGuard;
+/**
+ * Interval bounds for `cadence.intervalMs`.
+ *
+ * The REST schema permits up to 30d, but the mirrored
+ * `TriggerDefinition.schedule.intervalMs` is capped at 24h and
+ * `CommitmentTriggerSync` swallows the resulting validation failure — so a cadence
+ * over 24h yields a commitment whose control loop NEVER fires while every surface
+ * reports success. Cap at 24h so that state is unreachable from the CLI.
+ */
+exports.MIN_COMMITMENT_INTERVAL_MS = 60_000;
+exports.MAX_COMMITMENT_INTERVAL_MS = 24 * 60 * 60 * 1000;
+function base(id) {
+    return `/api/commitments/${encodeURIComponent(id)}`;
+}
+function packBase(id) {
+    return `/api/commitment-packs/${encodeURIComponent(id)}`;
+}
+exports.commitmentPackApi = {
+    list: () => data_provider_1.request.get('/api/commitment-packs'),
+    plan: (body) => data_provider_1.request.post('/api/commitment-packs/plan', body),
+    bind: (body) => data_provider_1.request.post('/api/commitment-packs/bind', body),
+    preflight: (id, nextRunCount) => data_provider_1.request.post(`${packBase(id)}/preflight`, {
+        ...(typeof nextRunCount === 'number' ? { nextRunCount } : {}),
+    }),
+    shadow: (id) => data_provider_1.request.post(`${packBase(id)}/shadow`, {}),
+    promote: (id) => data_provider_1.request.post(`${packBase(id)}/promote`, {}),
+};
+exports.commitmentApi = {
+    /**
+     * The lib owns every URL in this domain, and the parity spec depends on that:
+     * a command that builds its own `/api/commitments/...` string is invisible to
+     * the coverage check, which is how an endpoint ends up unreachable without
+     * anything failing.
+     */
+    list: (query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)('/api/commitments', query)),
+    manifest: (id) => data_provider_1.request.get(`${base(id)}/manifest`),
+    import: (body) => data_provider_1.request.post('/api/commitments/import', body),
+    fork: (id, body) => data_provider_1.request.post(`${base(id)}/fork`, body),
+    // GET /:id returns `{ commitment, latestCheck }` — NOT a bare contract.
+    // Unwrap before rendering, or every field reads as undefined.
+    get: (id) => data_provider_1.request.get(base(id)),
+    create: (body) => data_provider_1.request.post('/api/commitments', body),
+    update: (id, body) => data_provider_1.request.patch(base(id), body),
+    workLinks: (id, includeInactive = false) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/links`, { ...(includeInactive ? { includeInactive: true } : {}) })),
+    createWorkLink: (id, body) => data_provider_1.request.post(`${base(id)}/links`, body),
+    updateWorkLink: (id, linkId, body) => data_provider_1.request.patch(`${base(id)}/links/${encodeURIComponent(linkId)}`, body),
+    detachWorkLink: (id, linkId) => data_provider_1.request.delete(`${base(id)}/links/${encodeURIComponent(linkId)}`),
+    plan: (body) => data_provider_1.request.post('/api/commitments/plan', body),
+    checkNow: (id) => data_provider_1.request.post(`${base(id)}/check-now`, {}),
+    checks: (id, limit) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/checks`, { limit })),
+    actionHistory: (id, limit) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/action-history`, { limit })),
+    preflight: (id, nextRunCount) => data_provider_1.request.post(`${base(id)}/preflight`, {
+        ...(typeof nextRunCount === 'number' ? { nextRunCount } : {}),
+    }),
+    effectivePolicy: (id) => data_provider_1.request.get(`${base(id)}/effective-policy`),
+    pause: (id) => data_provider_1.request.post(`${base(id)}/pause`, {}),
+    resume: (id) => data_provider_1.request.post(`${base(id)}/resume`, {}),
+    complete: (id) => data_provider_1.request.post(`${base(id)}/complete`, {}),
+    autonomy: (id, body) => data_provider_1.request.post(`${base(id)}/autonomy`, body),
+    operatingReview: (agentId) => data_provider_1.request.get(`/api/commitments/agents/${encodeURIComponent(agentId)}/operating-review`),
+    reflection: (id) => data_provider_1.request.get(`${base(id)}/reflection`),
+    decideReflectionProposal: (id, proposalKey, decision) => data_provider_1.request.post(`${base(id)}/reflection/proposals/${encodeURIComponent(proposalKey)}/decision`, {
+        decision,
+    }),
+    /** Case and remediation-proposal reads make a commitment's open loop inspectable. */
+    cases: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/cases`, query)),
+    caseDetail: (id, caseId) => data_provider_1.request.get(`${base(id)}/cases/${encodeURIComponent(caseId)}`),
+    remediationProposals: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/remediation-proposals`, query)),
+    remediationProposal: (id, proposalId) => data_provider_1.request.get(`${base(id)}/remediation-proposals/${encodeURIComponent(proposalId)}`),
+    proposeRemediation: (id, caseId, body) => data_provider_1.request.post(`${base(id)}/cases/${encodeURIComponent(caseId)}/remediation-proposals`, body),
+    decideRemediationProposal: (id, proposalId, body) => data_provider_1.request.post(`${base(id)}/remediation-proposals/${encodeURIComponent(proposalId)}/decision`, body),
+    executeRemediationProposal: (id, proposalId, retryExecuting = false) => data_provider_1.request.post(`${base(id)}/remediation-proposals/${encodeURIComponent(proposalId)}/execute`, {
+        retryExecuting,
+    }),
+    /* ------------------------------------------------------------------------ *
+     * Observability and lineage
+     *
+     * These four answer questions the contract alone cannot: what the scheduler
+     * ACTUALLY has for this commitment (`triggerStatus`), what work it produced
+     * (`workLineage`), what its durable runs did (`ledger`), and which wakes an
+     * Agent is even allowed to pick (`wakeCapabilities`). Each has a distinct
+     * authority, which is why none of them is a field on `show`.
+     * ------------------------------------------------------------------------ */
+    triggerStatus: (id, limit) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/trigger-status`, { limit })),
+    workLineage: (id, limit) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/work-lineage`, { limit })),
+    /** One ordered explanation surface across the immutable commitment ledgers. */
+    /**
+     * Soft delete: the contract drops out of every read while the ledgers that
+     * reference it stay resolvable. Refused for an active or system-managed
+     * commitment — see CommitmentControl.deleteCommitment.
+     */
+    remove: (id, reason) => data_provider_1.request.delete((0, triggers_1.withQuery)(base(id), reason ? { reason } : {})),
+    trace: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/trace`, query)),
+    ledger: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/ledger`, query)),
+    wakeCapabilities: (id) => data_provider_1.request.get(`${base(id)}/wake-capabilities`),
+    dailyMetrics: (id, limit) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/daily-metrics`, { limit })),
+    cadenceDecisions: (id, limit) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/cadence-decisions`, { limit })),
+    /**
+     * What this commitment's RUNS claim to have seen (agent-as-sensor).
+     *
+     * Distinct from every other read on this object: it is the only one whose
+     * rows the control plane did not gather itself, so each carries
+     * `agent_reported` authority, a capped confidence, and the server's own
+     * `changed` verdict beside the agent's value. Default is the human view —
+     * pass `declaredOnly` for the rows that can actually move the loop.
+     */
+    /**
+     * The causal ledger — what its runs concluded about WHY, and what would have
+     * proven each conclusion wrong.
+     *
+     * `--status refuted` is the read that pays for the whole feature: it answers
+     * "what have we already ruled out", which is the question a second
+     * investigation of the same drift most needs answered before it starts.
+     */
+    hypotheses: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/hypotheses`, query)),
+    observations: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/observations`, query)),
+    /* ------------------------------------------------------------------------ *
+     * Steering
+     * ------------------------------------------------------------------------ */
+    /** One-tap feedback on a check — the signal Reflection retunes cadence from. */
+    checkFeedback: (id, checkId, body) => data_provider_1.request.post(`${base(id)}/checks/${encodeURIComponent(checkId)}/feedback`, body),
+    /** Bounded, named corrections — never a free-form contract edit. */
+    remediate: (id, body) => data_provider_1.request.post(`${base(id)}/remediation`, body),
+    /** Approve/reject an Agent-proposed cadence change the server parked. */
+    decideAutonomyRequest: (id, requestId, approved) => data_provider_1.request.post(`${base(id)}/autonomy-requests/${encodeURIComponent(requestId)}/decision`, {
+        approved,
+    }),
+    linkGoal: (id, goalId) => data_provider_1.request.put(`${base(id)}/goals/${encodeURIComponent(goalId)}`, {}),
+    unlinkGoal: (id, goalId) => data_provider_1.request.delete(`${base(id)}/goals/${encodeURIComponent(goalId)}`),
+};
+/** One-tap check feedback. `handled` means "I dealt with it", not "good nudge". */
+exports.COMMITMENT_FEEDBACK_KINDS = ['useful', 'noisy', 'wrong', 'handled'];
+/**
+ * Bounded remediation actions. This is a CLOSED set on purpose: remediation is
+ * the "this commitment is misbehaving, calm it down" lever, and a free-form
+ * contract edit would defeat the point of having one.
+ */
+exports.COMMITMENT_REMEDIATION_ACTIONS = [
+    'pause_commitment',
+    'mute_user_nudges',
+    'reduce_nudge_frequency',
+    'tighten_policy',
+    'mark_noop',
+];
+/** The only keys `createBodySchema` (a `z.strictObject`) accepts. */
+exports.COMMITMENT_CREATE_KEYS = [
+    'agentId',
+    'kind',
+    'compassId',
+    'compassOrigin',
+    'goalId',
+    'title',
+    'description',
+    'agentDirective',
+    'status',
+    'target',
+    'watchedSources',
+    'policy',
+    'cadence',
+    'subject',
+    'sensors',
+    'grants',
+    'reports',
+    'createdVia',
+];
+/**
+ * Normalize a `--from-json` body into something the create endpoint accepts.
+ *
+ * Two real hazards this removes:
+ *  1. `skrr commitments plan --json` emits the ENVELOPE `{proposal, message, …}` —
+ *     unwrap `proposal` so the documented plan → create pipe works unedited.
+ *  2. `createBodySchema` is a `z.strictObject`, so any extra key is a 400. A
+ *     contract dumped from `list --json` carries id/version/state/ownerUserId/…
+ *     — drop everything the schema does not declare.
+ *
+ * `status` is additionally narrowed: create only permits `draft|active`, but a
+ * dumped contract may carry `paused`/`completed`.
+ */
+function normalizeCreateBody(input) {
+    const envelope = input;
+    const src = envelope && typeof envelope.proposal === 'object' && envelope.proposal !== null
+        ? envelope.proposal
+        : input || {};
+    const out = {};
+    for (const key of exports.COMMITMENT_CREATE_KEYS) {
+        if (src[key] !== undefined)
+            out[key] = src[key];
+    }
+    if (out.status !== 'draft' && out.status !== 'active') {
+        delete out.status;
+    }
+    return out;
+}
+/**
+ * Parse a human interval ("15m", "6h", "1d", or a bare number of minutes) into
+ * milliseconds. Throws on unparseable input, on trailing junk, and on values
+ * outside the API's `cadence.intervalMs` bounds — silently clamping a cadence is
+ * dangerous on an active commitment.
+ */
+// Longest-first alternation, and the FULL pattern is anchored so the ENTIRE
+// string must be consumed. Without that anchor "1 month" matches `1` + `m` and
+// silently means ONE MINUTE — catastrophic on an active commitment.
+const INTERVAL_UNIT = '(?:weeks?|w|days?|d|hours?|hrs?|h|minutes?|mins?|m)';
+const INTERVAL_FULL = new RegExp(`^(?:\\d+(?:\\.\\d+)?\\s*${INTERVAL_UNIT}\\s*)+$`);
+const INTERVAL_TOKEN = new RegExp(`(\\d+(?:\\.\\d+)?)\\s*(${INTERVAL_UNIT})`, 'g');
+function parseIntervalToMs(input) {
+    const raw = String(input ?? '')
+        .trim()
+        .toLowerCase();
+    if (!raw)
+        throw new Error('Empty interval. Use a form like "15m", "6h", "1d", or "360".');
+    let minutes;
+    if (/^\d+(\.\d+)?$/.test(raw)) {
+        minutes = Number(raw);
+    }
+    else {
+        if (!INTERVAL_FULL.test(raw)) {
+            throw new Error(`Could not parse interval "${input}". Use minutes/hours/days/weeks — e.g. "15m", "6h", "1d", "2h30m". ` +
+                '(Months and seconds are not units here.)');
+        }
+        let total = 0;
+        INTERVAL_TOKEN.lastIndex = 0;
+        let m;
+        while ((m = INTERVAL_TOKEN.exec(raw)) !== null) {
+            const n = Number(m[1]);
+            const unit = m[2];
+            if (unit.startsWith('w'))
+                total += n * 60 * 24 * 7;
+            else if (unit.startsWith('d'))
+                total += n * 60 * 24;
+            else if (unit.startsWith('h'))
+                total += n * 60;
+            else
+                total += n;
+        }
+        minutes = total;
+    }
+    const ms = Math.round(minutes * 60_000);
+    // Throw rather than clamp: silently turning a requested 90d cadence into 30d
+    // (or 0 into 1m) hides a real misconfiguration on a live control loop.
+    if (ms < exports.MIN_COMMITMENT_INTERVAL_MS || ms > exports.MAX_COMMITMENT_INTERVAL_MS) {
+        throw new Error(`Interval "${input}" is out of range — must be between 1m and 24h (got ${describeIntervalMs(ms)}).`);
+    }
+    return ms;
+}
+/**
+ * One line an author can act on, or nothing.
+ *
+ * Returns undefined when evidence is healthy — a line saying everything is fine
+ * is noise in a summary someone reads to find what is wrong.
+ */
+function describeEvidenceHealth(health, criteriaCount) {
+    const state = health?.state;
+    if (!state || state === 'healthy_evidence') {
+        return undefined;
+    }
+    // The coarse `*_indeterminate` reasons ride alongside a precise one and say
+    // only "something was indeterminate", so showing them crowds out the reason
+    // that names what to do.
+    const reasons = (health?.reasons || []).filter((r) => !/_indeterminate$/.test(r));
+    const detail = reasons.length ? ` (${reasons.join(', ')})` : '';
+    if (state === 'unevidenceable_criteria') {
+        // This is not the same problem as criteria that exist but cannot be
+        // measured. The default contract has neither a criterion nor a Measure,
+        // so telling its owner to rewrite "the criteria below" points to a list
+        // that does not exist and hides the only viable next action.
+        if (criteriaCount === 0 && reasons.includes('no_outcome_measure')) {
+            return `${state}${detail} — this commitment has no success criteria or Measure, so its health remains unknown; add a --criterion with --evaluator metric --measure <measure-id>`;
+        }
+        return `unevidenceable_criteria${detail} — the criteria below cannot be judged from what this commitment observes; rewrite them or attach a Measure`;
+    }
+    if (state === 'degraded_observability') {
+        return `degraded_observability${detail} — an evaluator could not run; this is a fault, not a criteria problem`;
+    }
+    return `${state}${detail}`;
+}
+/** Render an interval back as a compact human string. */
+function describeIntervalMs(ms) {
+    if (!ms || !Number.isFinite(ms))
+        return '-';
+    const minutes = Math.round(ms / 60_000);
+    if (minutes % (60 * 24) === 0)
+        return `${minutes / (60 * 24)}d`;
+    if (minutes % 60 === 0)
+        return `${minutes / 60}h`;
+    return `${minutes}m`;
+}
+/**
+ * Success-criterion evaluators expressible from the CLI flags (OSK-4882). The
+ * server enum also has `task_state` / `goal_state` / `llm_review`, but those
+ * carry evaluator-specific `config` that has no ergonomic flag surface — reach
+ * them through `--from-json`.
+ *
+ * `source_state` belongs HERE rather than with those three: its config is one
+ * string naming a watched source, which is exactly as spellable as `metric`'s
+ * `--measure`. It is also the evaluator built for a source-watching Guardian,
+ * the one shape of commitment that previously had no evaluator available to it
+ * at all — so leaving it JSON-only would mean the CLI could not express the
+ * criterion its own `sky commitments show` tells the user to add.
+ */
+exports.COMMITMENT_CLI_EVALUATORS = ['manual', 'metric', 'source_state'];
+/**
+ * Build the `target.successCriteria` array from CLI flags, assigning the
+ * client-supplied `id` the API requires (its absence is the 400 the finding
+ * hit) and wiring `evaluator: 'metric'` + `config.measureId` so a user need not
+ * hand-write JSON or read the server schema to attach a measure.
+ */
+function buildSuccessCriteria(labels, opts = {}) {
+    const measureId = opts.measureId?.trim() || undefined;
+    const source = opts.source?.trim() || undefined;
+    // A measure implies the metric evaluator, and a source implies source_state;
+    // spelling both is allowed but must agree.
+    const evaluator = opts.evaluator ?? (measureId ? 'metric' : source ? 'source_state' : 'manual');
+    if (evaluator === 'metric' && !measureId) {
+        throw new Error('--evaluator metric requires --measure <measure-id>.');
+    }
+    if (measureId && evaluator !== 'metric') {
+        throw new Error('--measure only applies to --evaluator metric.');
+    }
+    // Named rather than defaulted: the evaluator reads the status of ONE watched
+    // source, and guessing which one when a commitment watches several would make
+    // the criterion silently judge something the author did not choose.
+    if (evaluator === 'source_state' && !source) {
+        throw new Error('--evaluator source_state requires --source <watched-source>.');
+    }
+    if (source && evaluator !== 'source_state') {
+        throw new Error('--source only applies to --evaluator source_state.');
+    }
+    if (measureId && labels.length !== 1) {
+        throw new Error('Attach a measure to exactly one --criterion. For multiple metric criteria, use --from-json.');
+    }
+    return labels.map((label, i) => ({
+        id: `c${i + 1}`,
+        label,
+        evaluator,
+        ...(evaluator === 'metric' && measureId ? { config: { measureId } } : {}),
+        ...(evaluator === 'source_state' && source ? { config: { source } } : {}),
+    }));
+}
+function cadenceLabel(commitment) {
+    const cadence = commitment.cadence;
+    if (!cadence || !cadence.mode || cadence.mode === 'manual')
+        return 'manual';
+    // `daily` cannot be described by an interval — that is the entire reason the
+    // mode exists — and `sampled` must not read like a fixed schedule, or a user
+    // will expect wakes at times the sampler never promised.
+    if (cadence.mode === 'daily') {
+        const times = (cadence.times || []).join(',');
+        return times ? `daily ${times}${cadence.timezone ? ` ${cadence.timezone}` : ''}` : 'daily';
+    }
+    if (cadence.mode === 'sampled') {
+        return `~${describeIntervalMs(cadence.intervalMs)} (sampled)`;
+    }
+    return `${cadence.mode === 'event_plus_interval' ? 'event+' : ''}${describeIntervalMs(cadence.intervalMs)}`;
+}
+function renderCommitmentList(commitments, log) {
+    if (commitments.length === 0) {
+        log('No commitments.');
+        return;
+    }
+    (0, format_1.renderTable)(commitments.map((o) => ({
+        id: o.id ?? '-',
+        title: o.title ?? '-',
+        status: o.status ?? '-',
+        health: o.state?.health ?? '-',
+        cadence: cadenceLabel(o),
+        autonomy: o.policy?.autonomyMode ?? '-',
+        agent: o.agentId ?? '-',
+    })), [
+        { key: 'title', header: 'TITLE', maxWidth: 34 },
+        { key: 'status', header: 'STATUS', maxWidth: 10 },
+        { key: 'health', header: 'HEALTH', maxWidth: 16 },
+        { key: 'cadence', header: 'CADENCE', maxWidth: 10 },
+        { key: 'autonomy', header: 'AUTONOMY', maxWidth: 18 },
+        { key: 'agent', header: 'AGENT', verbatim: true },
+        // Commitment ids are routinely pasted into `check-now`, so this column
+        // is never clipped. Widening the guess (28 → 44) fixed today's
+        // 40-character ids and would break on the next longer prefix.
+        { key: 'id', header: 'ID', verbatim: true },
+    ], log);
+}
+/**
+ * The autonomy mode a check ACTUALLY ran at, read from its policy trace
+ * (OSK-4881).
+ *
+ * A commitment's STATED autonomy (`policy.autonomyMode`) is only a ceiling: the
+ * arbiter clamps it to the stricter of the agent's initiative policy and the
+ * workspace's governance, then records the mode it settled on in the check's
+ * `decision.policyTrace`. The arbiter's own decision carries it as
+ * `autonomyMode`; the workspace-governance entry carries the clamped ceiling as
+ * `effectiveAutonomyMode`. Either answers "what governed this run". Returns the
+ * effective mode when the trace carries one, else undefined.
+ *
+ * Exported for tests.
+ */
+function effectiveAutonomyMode(check) {
+    const trace = check?.decision?.policyTrace;
+    if (!Array.isArray(trace))
+        return undefined;
+    for (const entry of trace) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const e = entry;
+        const mode = e.autonomyMode ?? e.effectiveAutonomyMode;
+        if (typeof mode === 'string' && mode.length)
+            return mode;
+    }
+    return undefined;
+}
+/**
+ * The `Autonomy:` line — the stated mode, annotated when the latest check
+ * actually ran at a STRICTER one (OSK-4881). Without the caveat, a commitment
+ * created `auto_run_limited` whose every check the workspace clamped to
+ * `suggestions_only` reads as though it were acting when it is only suggesting,
+ * and only `preflight --json` reveals otherwise.
+ *
+ * Exported for tests.
+ */
+function describeAutonomyLine(commitment, latestCheck) {
+    const stated = commitment.policy?.autonomyMode ?? '-';
+    const effective = effectiveAutonomyMode(latestCheck);
+    const envelopeEnabled = commitment.policy?.autonomyEnvelope?.enabled;
+    const envelope = typeof envelopeEnabled === 'boolean'
+        ? ` [envelope: ${envelopeEnabled ? 'enabled' : 'disabled'}]`
+        : '';
+    if (effective && effective !== stated) {
+        return `${stated} (effective: ${effective} — capped by initiative or workspace policy)${envelope}`;
+    }
+    return `${stated}${envelope}`;
+}
+function renderCommitmentSummary(commitment, log, 
+/**
+ * The most recent check, when the caller has one. Optional because pause /
+ * complete / detach / reports render this same summary and hold only the
+ * contract — they should not be made to fetch a check to print one line.
+ */
+latestCheck) {
+    log(`ID:        ${commitment.id ?? '-'}`);
+    log(`Title:     ${commitment.title ?? '-'}`);
+    log(`Kind:      ${commitment.kind ?? 'achieve'}`);
+    log(`Status:    ${commitment.status ?? '-'}`);
+    log(`Agent:     ${commitment.agentId ?? '-'}`);
+    if (commitment.goalId)
+        log(`Goal:      ${commitment.goalId}`);
+    if (commitment.northstarId)
+        log(`Northstar: ${commitment.northstarId}`);
+    if (commitment.target?.outcome)
+        log(`Outcome:   ${commitment.target.outcome}`);
+    if (commitment.target?.deadlineAt)
+        log(`Deadline:  ${commitment.target.deadlineAt}`);
+    log(`Cadence:   ${cadenceLabel(commitment)}`);
+    if (commitment.cadence?.nextCheckAt)
+        log(`Next check:${` ${commitment.cadence.nextCheckAt}`}`);
+    log(`Autonomy:  ${describeAutonomyLine(commitment, latestCheck)}`);
+    const criteria = commitment.target?.successCriteria || [];
+    const evidenceHealth = latestCheck?.inputs?.evidenceHealth;
+    const evidenceLine = describeEvidenceHealth(evidenceHealth, criteria.length);
+    const health = commitment.state?.health ?? 'unknown';
+    const healthExplanation = health === 'unknown' && evidenceHealth?.state === 'unevidenceable_criteria'
+        ? ' — evidence cannot establish a positive health verdict as configured'
+        : '';
+    log(`Health:    ${health}${healthExplanation}`);
+    if (commitment.state?.lastCheckedAt)
+        log(`Checked:   ${commitment.state.lastCheckedAt}`);
+    if (typeof commitment.state?.consecutiveUnresolvedChecks === 'number') {
+        log(`Unresolved checks in a row:${` ${commitment.state.consecutiveUnresolvedChecks}`}`);
+    }
+    const sources = (commitment.watchedSources || [])
+        .filter((s) => s.enabled !== false)
+        .map((s) => s.source);
+    if (sources.length)
+        log(`Watching:  ${sources.join(', ')}`);
+    // Whether the criteria below can be EVIDENCED at all.
+    //
+    // Without this an author reads `Health: at_risk` beside five criteria and has
+    // no way to learn that none of them can be judged — the state existed only in
+    // the JSON payload. `unevidenceable_criteria` is the author's problem to fix
+    // (rewrite the criterion, or attach a real Measure); `degraded_observability`
+    // is the platform's. Naming which one it is here is the whole point of having
+    // split them.
+    if (evidenceLine)
+        log(`Evidence:  ${evidenceLine}`);
+    if (criteria.length) {
+        log('Success criteria:');
+        for (const c of criteria)
+            log(`  - [${c.evaluator ?? 'manual'}] ${c.label}`);
+    }
+    if (commitment.state?.summary) {
+        log('');
+        log(commitment.state.summary);
+    }
+}
+/**
+ * Short humanization of a skipped invocation's reason CODE (OSK-4884). The
+ * server records why it declined to wake the agent as a machine token; a reader
+ * scanning the table needs it in words.
+ */
+const INVOCATION_SKIP_REASONS = {
+    state_watch_intact: 'watch intact',
+    // NAMES THE ENVELOPE, not "autonomy", because they are different fields.
+    //
+    // The server sets this code from `autonomyEnvelope.enabled !== true`
+    // (`WakeIntentResolver.js:35`, `CommitmentAutonomyService.js:12`). It was
+    // rendered as "autonomy off", which a reader maps onto `policy.autonomyMode`
+    // — the field the CLI prints as `Autonomy:` and the one `commitments autonomy`
+    // sets. So a commitment sitting at `suggestions_only` reported "autonomy off",
+    // which is false about the field it appears to name, and sends the reader to
+    // change a setting that was never the cause.
+    autonomy_envelope_disabled: 'autonomy envelope off',
+    compass_direction_missing: 'no compass direction',
+    auto_run_daily_cap: 'daily run cap',
+    // `posture_does_not_admit_agent_run` is handled specially — it carries the
+    // posture that declined, which is more useful than a generic label.
+};
+/**
+ * Whether a check woke the agent, in plain words (OSK-4884).
+ *
+ * The commitment control loop records its wake decision as a
+ * `rule: 'commitment_invocation'` entry in `decision.policyTrace`, but the CLI
+ * never surfaced it — so `checks` could not answer the first question a reader
+ * has: did this check start an agent run, and if not, why not? Reads the trace
+ * entry and renders `yes` / `no — <reason>`; `-` when the check carries no
+ * invocation decision.
+ *
+ * Exported for tests.
+ */
+function describeWakeDecision(check) {
+    const trace = check.decision?.policyTrace;
+    if (!Array.isArray(trace))
+        return '-';
+    const entry = trace.find((e) => e && typeof e === 'object' && e.rule === 'commitment_invocation');
+    if (!entry)
+        return '-';
+    const verdict = typeof entry.verdict === 'string' ? entry.verdict : '';
+    if (verdict === 'enqueued')
+        return 'yes';
+    if (verdict === 'deduped')
+        return 'yes (deduped)';
+    if (verdict === 'skipped') {
+        const reason = typeof entry.reason === 'string' ? entry.reason : '';
+        if (reason === 'posture_does_not_admit_agent_run') {
+            const posture = typeof entry.posture === 'string' ? entry.posture : '';
+            return posture ? `no — ${posture}` : 'no — posture';
+        }
+        const label = INVOCATION_SKIP_REASONS[reason];
+        if (label)
+            return `no — ${label}`;
+        return reason ? `no — ${reason}` : 'no';
+    }
+    return verdict ? `(${verdict})` : '-';
+}
+/**
+ * Render the commitment's own decision history — one row per check. `POSTURE` is
+ * the loop's judgment (stay_quiet / act_silently / nudge_user / escalate …), so
+ * this is the fastest way to see what a commitment has actually been deciding.
+ * `WOKE` says whether the check started an agent run, and why not when it did
+ * not (OSK-4884).
+ */
+function renderCheckList(checks, log) {
+    if (checks.length === 0) {
+        log('No checks recorded.');
+        return;
+    }
+    (0, format_1.renderTable)(checks.map((c) => ({
+        started: c.startedAt ?? '-',
+        kind: c.checkKind ?? '-',
+        status: c.status ?? '-',
+        posture: c.decision?.posture ?? '-',
+        loops: String(c.openLoops?.length ?? 0),
+        actions: String(c.actionPlan?.length ?? 0),
+        woke: describeWakeDecision(c),
+        why: c.decision?.whyNow ?? c.reason ?? '',
+        id: c.id ?? '-',
+    })), [
+        { key: 'started', header: 'STARTED', maxWidth: 24 },
+        { key: 'kind', header: 'KIND', maxWidth: 10 },
+        { key: 'status', header: 'STATUS', maxWidth: 10 },
+        { key: 'posture', header: 'POSTURE', maxWidth: 16 },
+        { key: 'loops', header: 'LOOPS' },
+        { key: 'actions', header: 'ACTIONS' },
+        { key: 'woke', header: 'WOKE', maxWidth: 22 },
+        { key: 'why', header: 'WHY NOW', maxWidth: 40 },
+        // Last, and verbatim: every other column is something to read, this is
+        // the one thing to copy. Without it, naming a check for `ledger`/`trace`
+        // meant re-running the command with `--json` (OSK-6175).
+        { key: 'id', header: 'ID', verbatim: true },
+    ], log);
+}
+function records(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => Boolean(item) && typeof item === 'object')
+        : [];
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function text(value, fallback = '-') {
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return fallback;
+    const rendered = String(value).trim();
+    return rendered || fallback;
+}
+function firstValue(row, keys) {
+    for (const key of keys) {
+        if (row[key] !== undefined && row[key] !== null && row[key] !== '')
+            return row[key];
+    }
+    return undefined;
+}
+function count(value) {
+    return String(records(value).length);
+}
+function renderRows(rows, 
+// Derived from `renderTable`, not restated. A second declaration is how a
+// column option (`verbatim`) exists on one surface and silently not on the
+// other.
+columns, empty, log) {
+    if (!rows.length) {
+        log(empty);
+        return;
+    }
+    (0, format_1.renderTable)(rows, columns, log);
+}
+/** Human view for `commitments ledger`; JSON remains the automation surface. */
+function renderCommitmentLedger(ledger, log) {
+    const checks = records(ledger.checks);
+    const runs = records(ledger.runs);
+    log(`Ledger: ${checks.length} checks, ${runs.length} runs`);
+    if (!checks.length && !runs.length)
+        log('No checks or runs recorded.');
+    if (checks.length) {
+        log('Recent checks:');
+        renderRows(checks.map((item) => {
+            const decision = record(item.decision);
+            return {
+                started: text(firstValue(item, ['startedAt', 'createdAt'])),
+                status: text(item.status),
+                posture: text(decision?.posture),
+                loops: count(item.openLoops),
+                actions: count(item.actionPlan),
+                why: text(firstValue(decision || {}, ['whyNow', 'summary']), text(item.reason, '')),
+            };
+        }), [
+            { key: 'started', header: 'STARTED', maxWidth: 24 },
+            { key: 'status', header: 'STATUS', maxWidth: 12 },
+            { key: 'posture', header: 'POSTURE', maxWidth: 16 },
+            { key: 'loops', header: 'LOOPS' },
+            { key: 'actions', header: 'ACTIONS' },
+            { key: 'why', header: 'WHY', maxWidth: 48 },
+        ], 'No checks recorded.', log);
+    }
+    if (runs.length) {
+        log('Runs:');
+        renderRows(runs.map((item) => ({
+            id: text(item.id),
+            status: text(item.status),
+            attempt: `${text(item.attempt, '0')}/${text(item.maxAttempts, '-')}`,
+            reason: text(firstValue(item, ['reason', 'error']), ''),
+            finished: text(firstValue(item, ['completedAt', 'updatedAt', 'startedAt'])),
+        })), [
+            { key: 'id', header: 'RUN ID', verbatim: true },
+            { key: 'status', header: 'STATUS', maxWidth: 12 },
+            { key: 'attempt', header: 'ATTEMPT' },
+            { key: 'reason', header: 'REASON', maxWidth: 36 },
+            { key: 'finished', header: 'LAST UPDATED', maxWidth: 24 },
+        ], 'No runs recorded.', log);
+    }
+    const wakeState = record(ledger.wakeState);
+    if (wakeState) {
+        log(`Wake state: ${wakeState.dirty === true ? 'pending' : 'clean'} (${text(wakeState.processedRev, '0')}/${text(wakeState.wakeRev, '0')} revisions processed)`);
+    }
+}
+/** Human view for the ordered commitment trace. */
+function renderCommitmentTrace(trace, log) {
+    const events = records(trace.events);
+    renderRows(events.map((item) => ({
+        at: text(firstValue(item, ['occurredAt', 'createdAt', 'startedAt'])),
+        type: text(firstValue(item, ['type', 'kind'])),
+        status: text(item.status),
+        summary: text(firstValue(item, ['summary', 'reason', 'title']), ''),
+    })), [
+        { key: 'at', header: 'AT', maxWidth: 24 },
+        { key: 'type', header: 'TYPE', maxWidth: 28 },
+        { key: 'status', header: 'STATUS', maxWidth: 28 },
+        { key: 'summary', header: 'SUMMARY', maxWidth: 72 },
+    ], 'No trace events recorded.', log);
+    if (trace.has_more === true && trace.next_cursor) {
+        log(`More events are available; continue with --cursor ${text(trace.next_cursor)}.`);
+    }
+}
+/** Human view for run-reported observations. */
+/**
+ * Yes/no for a server-owned boolean verdict.
+ *
+ * `text()` falls back to `-` for anything that is not a string or number, so a
+ * boolean column rendered through it was structurally dead: `changed: false`
+ * and "the server recorded no verdict" both printed `-`.
+ */
+function yesNo(value) {
+    if (value === true)
+        return 'yes';
+    if (value === false)
+        return 'no';
+    return '-';
+}
+function renderCommitmentObservations(response, log) {
+    const data = records(response.data);
+    renderRows(data.map((item) => ({
+        at: text(firstValue(item, ['observedAt', 'createdAt', 'updatedAt'])),
+        key: text(firstValue(item, ['key', 'observationKey', 'name'])),
+        value: (0, format_1.formatCell)(firstValue(item, ['value', 'observedValue', 'latestValue'])),
+        changed: yesNo(firstValue(item, ['changed', 'changeVerdict', 'verdict'])),
+        // `declared` decides whether a row can move the loop at all: an undeclared
+        // key is recorded and inert, and "the sensor saw nothing" must not look
+        // like "the sensor saw something we did not ask about". An observation
+        // has no `authority` field — that is a hypothesis concept — so the column
+        // that used to read it could never render.
+        declared: yesNo(item.declared),
+        access: text(item.accessStatus),
+        confidence: (0, format_1.formatCell)(item.confidence),
+    })), [
+        { key: 'at', header: 'OBSERVED', maxWidth: 24 },
+        { key: 'key', header: 'KEY', maxWidth: 30 },
+        { key: 'value', header: 'VALUE', maxWidth: 38 },
+        { key: 'changed', header: 'CHANGED', maxWidth: 8 },
+        { key: 'declared', header: 'DECLARED', maxWidth: 9 },
+        { key: 'access', header: 'ACCESS', maxWidth: 13 },
+        { key: 'confidence', header: 'CONF', maxWidth: 6 },
+    ], 'No observations recorded.', log);
+}
+/** Human view for causal hypotheses. */
+function renderCommitmentHypotheses(response, log) {
+    const data = records(response.data);
+    renderRows(data.map((item) => ({
+        // `proposedAt` is the domain's own "when was this recorded". Rendering
+        // `createdAt` under a RECORDED header while the server sorts by
+        // `updatedAt` made a re-verdicted hypothesis float above a newer one and
+        // the column read as unsorted.
+        at: text(firstValue(item, ['proposedAt', 'createdAt', 'updatedAt'])),
+        status: text(item.status),
+        claim: text(firstValue(item, ['claim', 'statement', 'summary', 'title']), ''),
+        // `observation_key` means the SERVER can settle this from a declared
+        // observation cursor with no model call; `agent_check` means only a run
+        // can. That is the whole point of the falsifiability constraint, so it
+        // belongs on the list. (A hypothesis carries no `confidence` — that is an
+        // observation concept — so the column that read it was always empty.)
+        falsifier: text(record(item.falsifier)?.kind),
+        authority: text(item.authority),
+        episode: (0, format_1.formatCell)(item.episode),
+    })), [
+        { key: 'at', header: 'RECORDED', maxWidth: 24 },
+        { key: 'status', header: 'STATUS', maxWidth: 12 },
+        { key: 'claim', header: 'CLAIM', maxWidth: 62 },
+        { key: 'falsifier', header: 'FALSIFIER', maxWidth: 16 },
+        { key: 'authority', header: 'AUTHORITY', maxWidth: 18 },
+        { key: 'episode', header: 'EP', maxWidth: 4 },
+    ], 'No hypotheses recorded.', log);
+}
+function renderLineageRows(label, value, log) {
+    const rows = records(value);
+    if (!rows.length)
+        return;
+    log(`${label}:`);
+    renderRows(rows.map((item) => ({
+        id: text(item.id),
+        status: text(item.status),
+        summary: text(firstValue(item, ['title', 'summary', 'kind', 'reason']), ''),
+    })), [
+        { key: 'id', header: 'ID', verbatim: true },
+        { key: 'status', header: 'STATUS', maxWidth: 16 },
+        { key: 'summary', header: 'SUMMARY', maxWidth: 72 },
+    ], `No ${label.toLowerCase()} recorded.`, log);
+}
+/** Human view for the commitment → work lineage projection. */
+function renderCommitmentLineage(lineage, log) {
+    const commitment = record(lineage.commitment);
+    if (commitment) {
+        log(`Commitment: ${text(commitment.title, text(commitment.id))} (${text(commitment.status)})`);
+    }
+    const groups = [
+        ['Goals', lineage.goals],
+        ['Tasks', lineage.tasks],
+        ['Runs', lineage.runs],
+    ];
+    if (groups.every(([, value]) => records(value).length === 0)) {
+        log('No linked goals, tasks, or runs recorded.');
+        return;
+    }
+    for (const [label, value] of groups)
+        renderLineageRows(label, value, log);
+}
+/** Human view for daily control-loop metrics. */
+function renderCommitmentMetrics(response, log) {
+    const data = records(response.data);
+    renderRows(data.map((item) => {
+        const totals = record(item.totals) || {};
+        const health = record(item.health) || {};
+        return {
+            date: text(firstValue(item, ['date', 'dateStart'])),
+            checks: text(firstValue(totals, ['checks', 'totalChecks']), '0'),
+            succeeded: text(firstValue(totals, ['succeededChecks', 'succeeded']), '0'),
+            health: (0, format_1.formatCell)(health),
+            sources: records(item.sources)
+                .map((source) => text(source.source, 'source'))
+                .join(', '),
+        };
+    }), [
+        { key: 'date', header: 'DATE', maxWidth: 24 },
+        { key: 'checks', header: 'CHECKS' },
+        { key: 'succeeded', header: 'SUCCEEDED' },
+        { key: 'health', header: 'HEALTH', maxWidth: 28 },
+        { key: 'sources', header: 'SOURCES', maxWidth: 48 },
+    ], 'No daily metrics recorded.', log);
+}