@skrr-ai/cli 0.1.47 → 0.1.49

package/dist/commands/commitments/cost.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCostWindow = resolveCostWindow;
+exports.formatCostWindow = formatCostWindow;
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const commitments_1 = require("../../lib/commitments");
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_WINDOW_DAYS = 7;
+/**
+ * Resolve a cost window to UTC day boundaries.
+ *
+ * `CommitmentPeriodClose.readCostWindow` REFUSES a window that is not exactly
+ * on UTC day starts (`RangeError: cost windows must use UTC day boundaries`),
+ * because the closed daily metrics it sums are bucketed that way — a window
+ * that started mid-day would silently include or exclude a whole bucket. So the
+ * CLI snaps to the boundary itself rather than forwarding a wall-clock time and
+ * letting the operator meet a 500 they cannot act on.
+ *
+ * Snapping is a real change to what was asked for, so it is deliberately
+ * TRUNCATION in both directions — `--to 2026-09-19T18:00Z` reports through the
+ * start of the 19th, not the end of it. The command prints the window it
+ * actually used for that reason.
+ *
+ * The default window ends at TODAY's UTC day start, not now: today's metrics
+ * are not closed yet, so including the partial day would report a cost that
+ * changes when you re-run the same command.
+ */
+function resolveCostWindow(input = {}, now = new Date()) {
+    const dayStart = (date) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+    const parse = (value, flag) => {
+        const parsed = new Date(value);
+        if (Number.isNaN(parsed.getTime())) {
+            throw new Error(`${flag} is not a date: ${value}`);
+        }
+        return parsed;
+    };
+    const to = input.to ? dayStart(parse(input.to, '--to')) : dayStart(now);
+    const from = input.from
+        ? dayStart(parse(input.from, '--from'))
+        : new Date(to.getTime() - DEFAULT_WINDOW_DAYS * DAY_MS);
+    if (to.getTime() <= from.getTime()) {
+        throw new Error('--to must be a later UTC day than --from.');
+    }
+    return { from: from.toISOString(), to: to.toISOString() };
+}
+/**
+ * `skrr commitments cost <id>` — closed-period spend for one commitment.
+ *
+ * Money on this path has no other bound the operator can read: a Commitment's
+ * agent turns are `AgentOutcome` rows carrying no cost fields, so
+ * `spendLimitDailyUsd` cannot see them and `maxRunsPerDay` IS the spend control
+ * (see `autonomyEnvelope.maxRunsPerDay` in the API's own schema note). This is
+ * the read that says what those runs actually cost.
+ *
+ * `metrics` shows the daily rows; this sums the closed ones over a window and,
+ * critically, reports how much of the window was ATTRIBUTABLE.
+ */
+class CommitmentsCost extends base_command_1.BaseCommand {
+    static description = "Sum a commitment's closed-period run cost over a UTC day window";
+    static examples = [
+        '<%= config.bin %> commitments cost obj_abc123',
+        '<%= config.bin %> commitments cost obj_abc123 --from 2026-09-01 --to 2026-09-15',
+        '<%= config.bin %> commitments cost obj_abc123 --json',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Commitment ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        from: core_1.Flags.string({
+            description: `Window start, truncated to its UTC day (default: ${DEFAULT_WINDOW_DAYS} days before --to)`,
+        }),
+        to: core_1.Flags.string({
+            description: "Window end, truncated to its UTC day (default: today's UTC day start)",
+        }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(CommitmentsCost);
+        let window;
+        try {
+            window = resolveCostWindow({ from: flags.from, to: flags.to });
+        }
+        catch (err) {
+            this.error(err.message, { exit: 1 });
+        }
+        let data;
+        try {
+            data = await commitments_1.commitmentApi.cost(args.id, window);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        for (const line of formatCostWindow(data))
+            this.log(line);
+    }
+}
+exports.default = CommitmentsCost;
+/**
+ * Pure renderer for the cost window.
+ *
+ * `costStatus` is printed BEFORE the dollar figure, on purpose. `partial` and
+ * `unavailable` mean some runs reported no cost attribution at all, so the
+ * total understates the spend; a reader who sees the number first has already
+ * formed a belief by the time they reach the caveat.
+ */
+function formatCostWindow(data) {
+    const micros = Number(data.costUsdMicros || 0);
+    const runs = Number(data.runCount || 0);
+    const unattributed = Number(data.unavailableRunCount || 0);
+    const status = data.costStatus ?? 'not_applicable';
+    const caveat = {
+        reported: 'every run in the window reported a cost',
+        partial: 'some runs reported no cost — the total below is a FLOOR',
+        unavailable: 'no run in the window reported a cost — the total below is meaningless',
+        not_applicable: 'no closed runs in the window',
+    };
+    return [
+        `Cost for ${data.commitmentId ?? '-'}`,
+        `Window:      ${data.from ?? '-'} → ${data.to ?? '-'} (${Number(data.dayCount || 0)} closed day(s))`,
+        `Attribution: ${status} — ${caveat[status] ?? 'unrecognized cost status'}`,
+        `Cost:        $${(micros / 1_000_000).toFixed(4)}`,
+        `Runs:        ${runs} (${Number(data.reportedRunCount || 0)} with cost, ${unattributed} without)`,
+    ];
+}

package/dist/commands/commitments/create.js

@@ -197,7 +197,7 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
         agent: core_1.Flags.string({ description: 'Agent that owns and watches this commitment (required)' }),
         kind: core_1.Flags.string({
             description: 'Lifecycle kind: achieve is terminal-capable; maintain is perpetual',
-            options: ['achieve', 'maintain'],
+            options: [...commitments_1.COMMITMENT_KIND_VALUES],
         }),
         title: core_1.Flags.string({ description: 'Short commitment title (required)' }),
         outcome: core_1.Flags.string({

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

@@ -22,6 +22,7 @@ export default class CommitmentsDelete extends BaseCommand {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         reason: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'stop-open-work': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/commands/commitments/delete.js

@@ -30,16 +30,43 @@ class CommitmentsDelete extends base_command_1.BaseCommand {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
         reason: core_1.Flags.string({ description: 'Why it was deleted (recorded on the boundary ledger)' }),
         yes: core_1.Flags.boolean({ char: 'y', description: 'Skip confirmation prompt' }),
+        'stop-open-work': core_1.Flags.boolean({
+            description: 'Cancel the open Tasks this Commitment produced. Without it they KEEP RUNNING — deleting the producer has never stopped the product.',
+            allowNo: true,
+        }),
     };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(CommitmentsDelete);
-        // The repo's own destructive-confirm helper rather than a second prompt:
-        // it also refuses to hang on a non-TTY, exiting 7 with an instruction to
-        // pass --yes, which is what makes this safe to call from a script.
+        let preview = null;
+        try {
+            preview = (await commitments_1.commitmentApi.deletionPreview(args.id));
+        }
+        catch {
+            // An older server has no preview route. Proceed — the delete itself
+            // still refuses to guess when there is open work.
+        }
+        // The API refuses to delete an active Commitment, and rightly so. But a
+        // deliberate step is not the same as a dead end: the person has already
+        // said what they want, so the step becomes part of THIS gesture rather
+        // than a second command they have to go and find. Same rule the web
+        // dialog applies, so the two surfaces cannot drift.
+        const mustPauseFirst = preview?.requiresStopFirst === true;
+        const openTasks = Number(preview?.openTaskCount || 0);
+        if (openTasks > 0 && flags['stop-open-work'] === undefined) {
+            this.error(`${args.id} has ${openTasks} open task(s), and deleting it does NOT stop them.\n` +
+                `  skrr commitments delete ${args.id} --stop-open-work      # cancel them too\n` +
+                `  skrr commitments delete ${args.id} --no-stop-open-work   # leave them running`, { exit: 1 });
+        }
+        const fate = openTasks === 0
+            ? 'Its checks, runs and cases stay readable.'
+            : flags['stop-open-work']
+                ? `Its ${openTasks} open task(s) will be CANCELLED.`
+                : `Its ${openTasks} open task(s) will KEEP RUNNING.`;
+        const verb = mustPauseFirst ? 'Pause and delete' : 'Delete';
         let confirmed;
         try {
-            confirmed = await (0, prompt_1.confirmDestructive)(`Delete commitment ${args.id}? Its checks, runs and cases stay readable.`, flags.yes);
+            confirmed = await (0, prompt_1.confirmDestructive)(`${verb} commitment ${args.id}? ${fate}`, flags.yes);
         }
         catch (err) {
             if (err.exit === 7) {
@@ -51,9 +78,23 @@ class CommitmentsDelete extends base_command_1.BaseCommand {
             this.log('Cancelled.');
             return;
         }
+        if (mustPauseFirst) {
+            try {
+                await commitments_1.commitmentApi.pause(args.id);
+                this.log(`Paused ${args.id}.`);
+            }
+            catch (err) {
+                // Report WHICH half failed. "Could not delete" would be wrong and
+                // would send the reader looking in the wrong place.
+                this.log(`Could not pause ${args.id} — it was not deleted.`);
+                this.handleApiError(err);
+            }
+        }
         let result;
         try {
-            result = await commitments_1.commitmentApi.remove(args.id, flags.reason);
+            result = await commitments_1.commitmentApi.remove(args.id, flags.reason, {
+                stopOpenWork: flags['stop-open-work'],
+            });
         }
         catch (err) {
             this.handleApiError(err);
@@ -66,7 +107,16 @@ class CommitmentsDelete extends base_command_1.BaseCommand {
         this.log(`Deleted ${String(commitment.id ?? args.id)}.`);
         if (commitment.title)
             this.log(`  ${String(commitment.title)}`);
-        this.log('  Its checks, runs, cases and linked Tasks remain readable.');
+        const work = (result.work ?? {});
+        // Lead with what still ACTS. What remains readable is reassurance; what
+        // remains running is the fact the reader needs.
+        if (work.openTasksStopped)
+            this.log(`  ${work.openTasksStopped} open task(s) cancelled.`);
+        if (work.openTasksLeftRunning) {
+            this.log(`  ${work.openTasksLeftRunning} open task(s) are STILL RUNNING.`);
+        }
+        this.log('  Its checks, runs and cases remain readable.');
+        this.log(`  Restore it with: skrr commitments restore ${String(commitment.id ?? args.id)}`);
     }
 }
 exports.default = CommitmentsDelete;

package/dist/commands/commitments/feedback.js

@@ -53,7 +53,15 @@ class CommitmentsFeedback extends base_command_1.BaseCommand {
             this.log(JSON.stringify(result, null, 2));
             return;
         }
-        this.log(`Recorded "${flags.kind}" on ${args.checkId}. Reflection will weigh it next cycle.`);
+        // A contradictory click used to acknowledge identically to a fresh verdict
+        // (OSK-10955) — the server reports what already stands on the check, and
+        // this copy keeps it visible.
+        const prior = Array.isArray(result?.priorFeedbackKinds)
+            ? result.priorFeedbackKinds.filter(Boolean)
+            : [];
+        const priorClause = prior.length ? ` Earlier feedback on this check: ${prior.join(', ')}.` : '';
+        const reaffirmClause = result?.reaffirmed ? ' (reaffirmed — same verdict as before)' : '';
+        this.log(`Recorded "${flags.kind}" on ${args.checkId}.${reaffirmClause} Reflection will weigh it next cycle.${priorClause}`);
     }
 }
 exports.default = CommitmentsFeedback;

package/dist/commands/commitments/handover.js

@@ -78,6 +78,22 @@ class CommitmentsHandover extends base_command_1.BaseCommand {
         }
         const agentLabel = target.name ? `${target.name} (${target.id})` : target.id;
         this.log(`Handed commitment ${args.id} over to ${agentLabel}`);
+        // The transition summary — without it a mid-check/mid-run handover reads
+        // as a silent success and the operator cannot tell whether in-flight work
+        // kept the old executor or was fenced.
+        const inFlight = result?.inFlight;
+        if (inFlight) {
+            const claimed = Number(inFlight.claimedRuns) || 0;
+            const fencedRuns = Number(inFlight.fencedRuns) || 0;
+            const fencedChecks = Number(inFlight.fencedChecks) || 0;
+            if (claimed > 0) {
+                this.log(`  ${claimed} claimed run(s) keep the old executor until they finish`);
+            }
+            if (fencedRuns > 0 || fencedChecks > 0) {
+                this.log(`  fenced ${fencedRuns} unclaimed run(s) and ${fencedChecks} in-flight check(s) — cancelled before start`);
+            }
+            this.log(`  the new executor takes over from the next wake`);
+        }
         // The audit entry the server appended — echo it so "from whom" is answered
         // without a second call. Absent on a server that predates the trail.
         const commitment = result?.commitment ??

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

@@ -22,6 +22,7 @@ export default class CommitmentsHypotheses extends BaseCommand {
         limit: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         status: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'investigation-key': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        cursor: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/commitments/hypotheses.js

@@ -35,6 +35,9 @@ class CommitmentsHypotheses extends base_command_1.BaseCommand {
         'investigation-key': core_1.Flags.string({
             description: 'Narrow to one investigation (an open loop subject key)',
         }),
+        cursor: core_1.Flags.string({
+            description: 'Continue from the next_cursor emitted by a previous page',
+        }),
     };
     async run() {
         this.requireAuth();
@@ -45,6 +48,7 @@ class CommitmentsHypotheses extends base_command_1.BaseCommand {
                 limit: flags.limit,
                 status: flags.status,
                 investigationKey: flags['investigation-key'],
+                cursor: flags.cursor,
             });
         }
         catch (err) {
@@ -52,9 +56,20 @@ class CommitmentsHypotheses extends base_command_1.BaseCommand {
         }
         if (flags.json) {
             this.log(JSON.stringify(response, null, 2));
-            return;
         }
-        (0, commitments_1.renderCommitmentHypotheses)(response, (line) => this.log(line));
+        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 });
+        }
+        (0, commitments_1.renderListPageHint)(response, (line) => this.log(line));
     }
 }
 exports.default = CommitmentsHypotheses;

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

@@ -34,7 +34,10 @@ class CommitmentsLinksList extends base_command_1.BaseCommand {
             return;
         }
         for (const link of links) {
-            this.log(`${link.id}  ${link.targetType}:${link.target?.title || link.targetId}  [${link.roles.join(', ')}]  ${link.status}`);
+            // `origin: 'goal_lineage'` rows are derived from `goal.commitmentId`, not
+            // a work-link row — `links detach` cannot remove them (OSK-10960).
+            const provenance = link.origin === 'goal_lineage' ? '  (via goals link — remove with goals unlink)' : '';
+            this.log(`${link.id}  ${link.targetType}:${link.target?.title || link.targetId}  [${link.roles.join(', ')}]  ${link.status}${provenance}`);
         }
     }
 }

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

@@ -0,0 +1,18 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr commitments liveness` — is the liveness witness itself alive?
+ *
+ * Per-commitment health is on `show`; this is the SWEEP's health — the marker
+ * the reconciler writes each pass. A stale sweep means every per-commitment
+ * verdict is also stale, which no single-commitment surface can tell you
+ * (OSK-10958). `healthy: false` or a null `lastSweepAt` means the witness is
+ * not running, not that commitments are fine.
+ */
+export default class CommitmentsLiveness extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/commitments/liveness.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const commitments_1 = require("../../lib/commitments");
+/**
+ * `skrr commitments liveness` — is the liveness witness itself alive?
+ *
+ * Per-commitment health is on `show`; this is the SWEEP's health — the marker
+ * the reconciler writes each pass. A stale sweep means every per-commitment
+ * verdict is also stale, which no single-commitment surface can tell you
+ * (OSK-10958). `healthy: false` or a null `lastSweepAt` means the witness is
+ * not running, not that commitments are fine.
+ */
+class CommitmentsLiveness extends base_command_1.BaseCommand {
+    static description = 'Show liveness sweep health — when the witness last ran and what it saw';
+    static examples = [
+        '<%= config.bin %> commitments liveness',
+        '<%= config.bin %> commitments liveness --json',
+    ];
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(CommitmentsLiveness);
+        let health;
+        try {
+            health = (await commitments_1.commitmentApi.livenessSweep());
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(health, null, 2));
+            return;
+        }
+        for (const line of formatSweepHealth(health))
+            this.log(line);
+    }
+}
+exports.default = CommitmentsLiveness;
+function formatSweepHealth(health) {
+    const lines = [];
+    if (!health.lastSweepAt) {
+        lines.push('Liveness sweep: NO SWEEP RECORDED');
+        lines.push('  The reconciler has never completed a sweep on this deployment —');
+        lines.push('  every per-commitment health verdict is unverified.');
+        return lines;
+    }
+    const age = health.sweepAgeSeconds ?? 0;
+    const status = health.healthy ? 'healthy' : 'STALE';
+    lines.push(`Liveness sweep: ${status} (${formatAge(age)} old)`);
+    lines.push(`  last sweep:    ${health.lastSweepAt}`);
+    const tick = health.lastTick;
+    if (tick) {
+        lines.push(`  last tick:     scanned ${tick.scanned ?? 0}` +
+            ` | on_track ${tick.onTrack ?? 0}` +
+            ` | stalled ${tick.stalled ?? 0}` +
+            ` | unknown ${tick.unknown ?? 0}` +
+            ` | unjudged ${tick.unjudged ?? 0}` +
+            ` | alerted ${tick.alerted ?? 0}` +
+            ` | errors ${tick.errors ?? 0}`);
+    }
+    if (health.cursor?.id) {
+        lines.push(`  cursor:        ${health.cursor.id}${health.cursor.at ? ` @ ${health.cursor.at}` : ''}`);
+    }
+    return lines;
+}
+function formatAge(seconds) {
+    if (seconds < 90)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 90)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h ${minutes % 60}m`;
+    return `${Math.floor(hours / 24)}d ${hours % 24}h`;
+}

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

@@ -15,6 +15,7 @@ export default class CommitmentsMetrics extends BaseCommand {
     static flags: {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         limit: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        cursor: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/commitments/metrics.js

@@ -22,13 +22,19 @@ class CommitmentsMetrics extends base_command_1.BaseCommand {
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
         limit: core_1.Flags.integer({ description: 'Days to include', min: 1, max: 200 }),
+        cursor: core_1.Flags.string({
+            description: 'Continue from the next_cursor emitted by a previous page',
+        }),
     };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(CommitmentsMetrics);
         let response;
         try {
-            response = await commitments_1.commitmentApi.dailyMetrics(args.commitmentId, flags.limit);
+            response = await commitments_1.commitmentApi.dailyMetrics(args.commitmentId, {
+                limit: flags.limit,
+                cursor: flags.cursor,
+            });
         }
         catch (err) {
             this.handleApiError(err);
@@ -38,6 +44,7 @@ class CommitmentsMetrics extends base_command_1.BaseCommand {
             return;
         }
         (0, commitments_1.renderCommitmentMetrics)(response, (line) => this.log(line));
+        (0, commitments_1.renderListPageHint)(response, (line) => this.log(line));
     }
 }
 exports.default = CommitmentsMetrics;

package/dist/commands/commitments/next-tick.d.ts

@@ -0,0 +1,39 @@
+import { BaseCommand } from '../../base-command';
+import { type CommitmentNextTickProjection } from '../../lib/commitments';
+/**
+ * `skrr commitments next-tick <id>` — what the NEXT check would decide.
+ *
+ * Every other read on a commitment is retrospective: `checks` says what it
+ * decided, `receipt` says what one wake produced, `trigger-status` says when it
+ * will fire again. None of them answers the question an operator actually has
+ * when a commitment is about to nudge somebody — "what is it about to do, and
+ * on what grounds" — and the only way to find out used to be to run a real
+ * check, which changes the thing you were trying to observe.
+ *
+ * The server's projection stops at the DecisionEnvelope → Arbiter boundary: no
+ * Check row, no budget debit, no delivery gate, no contract write. That is what
+ * makes this safe to ask from a terminal, and it is why the envelope is only
+ * printed under `--json` — the decision and its policy trail are the answer;
+ * the envelope is the evidence behind it.
+ */
+export default class CommitmentsNextTick extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}
+/**
+ * Pure renderer for the next-tick projection.
+ *
+ * Kept separate from the command for the same reason `formatTriggerStatus` is:
+ * it can be unit-tested without a live API, and the command body stays a thin
+ * fetch + print. Defensive about every field — this is a projection of a
+ * versioned envelope, so a missing key is a shape change, not a reason to throw
+ * in front of somebody debugging a live commitment.
+ */
+export declare function formatNextTick(projection: CommitmentNextTickProjection): string[];

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

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatNextTick = formatNextTick;
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const commitments_1 = require("../../lib/commitments");
+/**
+ * `skrr commitments next-tick <id>` — what the NEXT check would decide.
+ *
+ * Every other read on a commitment is retrospective: `checks` says what it
+ * decided, `receipt` says what one wake produced, `trigger-status` says when it
+ * will fire again. None of them answers the question an operator actually has
+ * when a commitment is about to nudge somebody — "what is it about to do, and
+ * on what grounds" — and the only way to find out used to be to run a real
+ * check, which changes the thing you were trying to observe.
+ *
+ * The server's projection stops at the DecisionEnvelope → Arbiter boundary: no
+ * Check row, no budget debit, no delivery gate, no contract write. That is what
+ * makes this safe to ask from a terminal, and it is why the envelope is only
+ * printed under `--json` — the decision and its policy trail are the answer;
+ * the envelope is the evidence behind it.
+ */
+class CommitmentsNextTick extends base_command_1.BaseCommand {
+    static description = 'Preview what the next check would decide, without running one (no budget, no side effects)';
+    static examples = [
+        '<%= config.bin %> commitments next-tick obj_abc123',
+        '<%= config.bin %> commitments next-tick obj_abc123 --json',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Commitment ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({
+            description: 'Output the full projection, including the DecisionEnvelope',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(CommitmentsNextTick);
+        let projection;
+        try {
+            projection = await commitments_1.commitmentApi.nextTick(args.id);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(projection, null, 2));
+            return;
+        }
+        for (const line of formatNextTick(projection))
+            this.log(line);
+    }
+}
+exports.default = CommitmentsNextTick;
+/**
+ * Pure renderer for the next-tick projection.
+ *
+ * Kept separate from the command for the same reason `formatTriggerStatus` is:
+ * it can be unit-tested without a live API, and the command body stays a thin
+ * fetch + print. Defensive about every field — this is a projection of a
+ * versioned envelope, so a missing key is a shape change, not a reason to throw
+ * in front of somebody debugging a live commitment.
+ */
+function formatNextTick(projection) {
+    const decision = projection.decision ?? {};
+    const lines = [
+        `Next tick for ${projection.commitmentId ?? '-'} (projected ${projection.projectedAt ?? '-'})`,
+        '',
+        // The header states what this did NOT do, because the value of the command
+        // 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.',
+        '',
+        `Posture:    ${decision.posture ?? '-'}`,
+        `Health:     ${decision.health ?? '-'}`,
+        `Risk:       ${decision.riskLevel ?? '-'}`,
+        `Confidence: ${decision.confidence ?? '-'}`,
+    ];
+    if (decision.whyNow)
+        lines.push(`Why now:    ${decision.whyNow}`);
+    // OSK-11433 — the projected envelope health is a delta read; the stored
+    // liveness verdict is the independent witness. Print the witness too so a
+    // dispatch-refusal loop can't hide behind an on_track projection.
+    if (projection.health || projection.liveness) {
+        const census = projection.liveness?.terminalDispositionCensus;
+        const detail = [
+            projection.liveness?.diagnosisKind,
+            census?.workFailures
+                ? `${census.workFailures} recent run failure${census.workFailures === 1 ? '' : 's'}`
+                : null,
+        ]
+            .filter(Boolean)
+            .join(', ');
+        lines.push(`Liveness:   ${projection.health ?? '-'}` + (detail ? ` (${detail})` : ''));
+    }
+    const actions = decision.actionPlan ?? [];
+    lines.push('');
+    if (actions.length === 0) {
+        lines.push('Action plan: none');
+    }
+    else {
+        lines.push(`Action plan (${actions.length}):`);
+        for (const action of actions) {
+            const label = action.summary || action.title || '';
+            lines.push(`  - ${action.kind || action.type || 'action'}${label ? `: ${label}` : ''}`);
+        }
+    }
+    const trace = decision.policyTrace ?? [];
+    lines.push('');
+    if (trace.length === 0) {
+        lines.push('Policy trace: none');
+    }
+    else {
+        lines.push(`Policy trace (${trace.length}):`);
+        for (const entry of trace) {
+            lines.push(`  ${entry.rule ?? '-'} → ${entry.decision ?? '-'}` +
+                (entry.reason ? ` — ${entry.reason}` : ''));
+        }
+    }
+    return lines;
+}

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

@@ -26,6 +26,7 @@ export default class CommitmentsObservations extends BaseCommand {
         'declared-only': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'changed-only': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         since: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        cursor: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }