@skrr-ai/cli 0.1.22 → 0.1.24

package/dist/commands/code/jobs/cancel.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../../base-command';
+export default class CodeJobsCancel extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        job: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/code/jobs/cancel.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+class CodeJobsCancel extends base_command_1.BaseCommand {
+    static description = 'Stop a Hosted Job Machine job, and its billing';
+    static examples = [
+        '<%= config.bin %> code jobs cancel <job-id>',
+        '<%= config.bin %> code jobs cancel <job-id> --json',
+    ];
+    static args = {
+        job: core_1.Args.string({ description: 'Job id', required: true, ignoreStdin: true }),
+    };
+    static flags = { json: core_1.Flags.boolean({ description: 'Output as JSON' }) };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(CodeJobsCancel);
+        let task;
+        try {
+            const res = await data_provider_1.dataService.cancelCloudCodingTask(args.job);
+            task = res?.task;
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(task, null, 2));
+            return;
+        }
+        // Report the status the SERVER came back with, never the one we asked for.
+        // Cancel races a job that is already finishing, and printing "cancelled"
+        // over a `completed` row would be the CLI inventing an outcome.
+        this.log(`Job ${task?.id ?? args.job} is now ${task?.status ?? 'unknown'}.`);
+        if (task?.prUrl)
+            this.log(`  ${String(task.prUrl)}`);
+    }
+}
+exports.default = CodeJobsCancel;

package/dist/commands/code/jobs/index.d.ts

@@ -0,0 +1,19 @@
+import { Command } from '@oclif/core';
+/**
+ * `skrr code jobs` — the lifecycle of work running on a Hosted Job Machine.
+ *
+ * A job is the object, not the machine. A Hosted Job Machine is one-shot
+ * compute that exists for the duration of one job and is torn down after it, so
+ * there is nothing to create, update or resume; `skrr code handover` starts one
+ * and these verbs observe and stop it.
+ *
+ * They exist because `POST /api/cloud-coding/tasks` had a CLI binding and the
+ * rest of the surface did not. An operator could dispatch a job onto managed
+ * cloud compute and then had no way to see whether it was running, no way to
+ * read why it failed, and — the one that costs money — no way to cancel it.
+ */
+export default class CodeJobs extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/code/jobs/index.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+/**
+ * `skrr code jobs` — the lifecycle of work running on a Hosted Job Machine.
+ *
+ * A job is the object, not the machine. A Hosted Job Machine is one-shot
+ * compute that exists for the duration of one job and is torn down after it, so
+ * there is nothing to create, update or resume; `skrr code handover` starts one
+ * and these verbs observe and stop it.
+ *
+ * They exist because `POST /api/cloud-coding/tasks` had a CLI binding and the
+ * rest of the surface did not. An operator could dispatch a job onto managed
+ * cloud compute and then had no way to see whether it was running, no way to
+ * read why it failed, and — the one that costs money — no way to cancel it.
+ */
+class CodeJobs extends core_1.Command {
+    static description = 'Jobs running on a Hosted Job Machine';
+    static examples = [
+        '<%= config.bin %> code jobs run --to "Analyst" --prompt "..." --wait',
+        '<%= config.bin %> code jobs list',
+        '<%= config.bin %> code jobs show <job-id>',
+        '<%= config.bin %> code jobs cancel <job-id>',
+        '<%= config.bin %> code jobs approve <job-id>',
+    ];
+    async run() {
+        this.log('Hosted Job Machine job commands:');
+        this.log('  skrr code jobs run       run a prompt on a fresh machine, no repo');
+        this.log('  skrr code jobs list      list your jobs, newest first');
+        this.log('  skrr code jobs show      show one job and its timeline');
+        this.log('  skrr code jobs cancel    stop a job and its billing');
+        this.log('  skrr code jobs approve   land the pull request a repo job opened');
+        this.log('');
+        this.log('`run` needs no repository. For a job that clones a repo and opens a');
+        this.log('pull request, use `skrr code handover`.');
+    }
+}
+exports.default = CodeJobs;

package/dist/commands/code/jobs/list.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../../base-command';
+export default class CodeJobsList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        status: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        active: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/code/jobs/list.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const format_1 = require("../../../lib/format");
+/** Terminal states — a job here is no longer holding a machine or billing. */
+const TERMINAL = new Set(['completed', 'failed', 'cancelled', 'timed_out']);
+/** Cents are the server's unit for money everywhere else; jobs report dollars. */
+function costCell(task) {
+    const raw = task.costUsd;
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        return '-';
+    return `$${raw.toFixed(2)}`;
+}
+class CodeJobsList extends base_command_1.BaseCommand {
+    static description = 'List your Hosted Job Machine jobs, newest first';
+    static examples = [
+        '<%= config.bin %> code jobs list',
+        '<%= config.bin %> code jobs list --active',
+        '<%= config.bin %> code jobs list --status running --limit 5',
+        '<%= config.bin %> code jobs list --json',
+    ];
+    static flags = {
+        status: core_1.Flags.string({
+            description: 'Filter by one exact status (e.g. running, failed, completed)',
+        }),
+        // The question an operator actually opens this with is "what is costing me
+        // money right now", and the server has no such filter -- it takes one exact
+        // status. Filtering client-side is honest here because the page is already
+        // bounded by --limit.
+        active: core_1.Flags.boolean({
+            description: 'Show only jobs that are still running (and still billing)',
+            default: false,
+            exclusive: ['status'],
+        }),
+        limit: core_1.Flags.integer({ description: 'How many to return (1-100, default 20)' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(CodeJobsList);
+        let tasks = [];
+        try {
+            const res = await data_provider_1.dataService.listCloudCodingTasks({
+                ...(flags.status ? { status: flags.status } : {}),
+                ...(flags.limit ? { limit: flags.limit } : {}),
+            });
+            tasks = res?.data ?? [];
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.active) {
+            tasks = tasks.filter((t) => !TERMINAL.has(String(t.status)));
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(tasks, null, 2));
+            return;
+        }
+        if (tasks.length === 0) {
+            // Say what empty MEANS. With --active it is the reassuring answer, not an
+            // empty query: nothing is running, so nothing is being billed.
+            this.log(flags.active
+                ? 'No jobs running — nothing is holding a Hosted Job Machine, and nothing is accruing.'
+                : 'No jobs. Start one with `skrr code jobs run`, or `skrr code handover`\n' +
+                    'for a job that clones a repository and opens a pull request.');
+            return;
+        }
+        (0, format_1.renderTable)(tasks.map((t) => ({
+            id: (0, format_1.formatCell)(t.id),
+            status: (0, format_1.formatCell)(t.status),
+            repo: (0, format_1.formatCell)(t.repoFullName),
+            cost: costCell(t),
+            created: (0, format_1.localStamp)(t.createdAt),
+            pr: (0, format_1.formatCell)(t.prUrl),
+        })), [
+            { key: 'id', header: 'JOB' },
+            { key: 'status', header: 'STATUS' },
+            { key: 'repo', header: 'REPO', maxWidth: 28 },
+            { key: 'cost', header: 'COST' },
+            { key: 'created', header: 'CREATED' },
+            { key: 'pr', header: 'PR', maxWidth: 40 },
+        ], (line) => this.log(line));
+    }
+}
+exports.default = CodeJobsList;

package/dist/commands/code/jobs/run.d.ts

@@ -0,0 +1,32 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * `skrr code jobs run` — one-shot managed compute with no repository.
+ *
+ * OSK-7806. The sibling `skrr code handover` clones a GitHub repo, works it and
+ * opens a pull request. This runs the same Hosted Job Machine with no repo at
+ * all: a prompt in, a recorded result out, teardown. It is the shape for work
+ * that is not a code change — process some data, call an API, check something
+ * on a machine that is not yours and does not persist.
+ *
+ * Egress defaults to `isolated`: the control plane and nothing else. That is
+ * deliberate and worth knowing before you reach for `--egress`. The repository
+ * requirement used to be an abuse gate — burning managed compute meant first
+ * installing the GitHub App on a repo you own — and a job that needs no repo
+ * has no such gate, so its default reach must be the narrowest one that works.
+ */
+export default class CodeJobsRun extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        to: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        prompt: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'prompt-file': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        egress: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        wait: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        interval: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        timeout: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    private sleep;
+    run(): Promise<void>;
+}

package/dist/commands/code/jobs/run.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const code_handover_1 = require("../../../lib/code-handover");
+const TERMINAL = new Set(['completed', 'failed', 'cancelled', 'timed_out']);
+/**
+ * `skrr code jobs run` — one-shot managed compute with no repository.
+ *
+ * OSK-7806. The sibling `skrr code handover` clones a GitHub repo, works it and
+ * opens a pull request. This runs the same Hosted Job Machine with no repo at
+ * all: a prompt in, a recorded result out, teardown. It is the shape for work
+ * that is not a code change — process some data, call an API, check something
+ * on a machine that is not yours and does not persist.
+ *
+ * Egress defaults to `isolated`: the control plane and nothing else. That is
+ * deliberate and worth knowing before you reach for `--egress`. The repository
+ * requirement used to be an abuse gate — burning managed compute meant first
+ * installing the GitHub App on a repo you own — and a job that needs no repo
+ * has no such gate, so its default reach must be the narrowest one that works.
+ */
+class CodeJobsRun extends base_command_1.BaseCommand {
+    static description = 'Run a prompt on a one-shot Hosted Job Machine, with no repository';
+    static examples = [
+        '<%= config.bin %> code jobs run --to "Analyst" --prompt "summarise the attached figures" --wait',
+        '<%= config.bin %> code jobs run --to agent_abc --prompt-file ./brief.md',
+        '<%= config.bin %> code jobs run --to agent_abc --prompt "fetch and chart" --egress allowlist --json',
+    ];
+    static flags = {
+        to: core_1.Flags.string({ description: 'Agent that runs the job — id or name', required: true }),
+        prompt: core_1.Flags.string({ description: 'What the agent should do', exclusive: ['prompt-file'] }),
+        'prompt-file': core_1.Flags.string({
+            description: 'Read the prompt from a file (for prompts too long to type)',
+            exclusive: ['prompt'],
+        }),
+        egress: core_1.Flags.string({
+            description: 'Network reach. Default `isolated` — the control plane only, nothing else.',
+            options: ['isolated', 'allowlist', 'open'],
+        }),
+        wait: core_1.Flags.boolean({ description: 'Wait for the job to finish and print its result' }),
+        interval: core_1.Flags.integer({ description: 'Poll interval in seconds while waiting', default: 5 }),
+        timeout: core_1.Flags.integer({ description: 'Give up waiting after this many minutes', default: 30 }),
+        json: core_1.Flags.boolean({ description: 'Output the task as JSON' }),
+    };
+    async sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(CodeJobsRun);
+        let prompt = flags.prompt ?? '';
+        if (flags['prompt-file']) {
+            try {
+                prompt = (0, node_fs_1.readFileSync)(flags['prompt-file'], 'utf8');
+            }
+            catch (err) {
+                this.error(`Could not read --prompt-file: ${err.message}`);
+            }
+        }
+        if (!prompt.trim()) {
+            this.error('A prompt is required — pass --prompt or --prompt-file.');
+        }
+        let agents = [];
+        try {
+            const resp = await data_provider_1.dataService.listAgents({ requiredPermission: data_provider_1.PermissionBits.VIEW });
+            agents = (resp?.data ?? []).filter(Boolean);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const matched = (0, code_handover_1.matchAgent)(flags.to, agents);
+        if (matched.kind === 'none') {
+            this.error(`No agent matches "${flags.to}". Run \`skrr agents list\` to see the agents you can use.`);
+        }
+        if (matched.kind === 'ambiguous') {
+            this.error(`"${flags.to}" matches ${matched.candidates.length} agents. Pass the agent id instead:\n` +
+                matched.candidates.map((a) => `  ${a.id}  ${a.name ?? ''}`).join('\n'));
+        }
+        const target = matched.agent;
+        let task;
+        try {
+            const res = await data_provider_1.dataService.createCloudCodingTask({
+                agentId: target.id,
+                prompt,
+                mode: 'bare',
+                machineProduct: 'hosted-job-machine',
+                ...(flags.egress ? { egressPolicy: flags.egress } : {}),
+                clientRequestId: (0, node_crypto_1.randomUUID)(),
+            });
+            task = res?.task;
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const jobId = String(task?.id ?? '');
+        if (!flags.wait) {
+            if (flags.json) {
+                this.log(JSON.stringify(task, null, 2));
+                return;
+            }
+            this.log(`Job ${jobId} ${task?.status ?? 'queued'} on ${target.name ?? target.id}`);
+            this.log(`  ${this.config.bin} code jobs show ${jobId}`);
+            // It bills from here. Say the stop verb at the moment the spending starts,
+            // not only in the docs for a command they may never open.
+            this.log(`  ${this.config.bin} code jobs cancel ${jobId}   (it bills while it runs)`);
+            return;
+        }
+        const deadline = Date.now() + flags.timeout * 60_000;
+        let current = task;
+        while (!TERMINAL.has(String(current?.status)) && Date.now() < deadline) {
+            await this.sleep(Math.max(1, flags.interval) * 1000);
+            try {
+                current = (await data_provider_1.dataService.getCloudCodingTask(jobId))?.task;
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(current, null, 2));
+            return;
+        }
+        if (!TERMINAL.has(String(current?.status))) {
+            // A timed-out WAIT is not a timed-out job. The job is still running and
+            // still billing, so say which of the two happened and how to stop it.
+            this.log(`Still ${current?.status ?? 'running'} after ${flags.timeout}m — the job continues.`);
+            this.log(`  ${this.config.bin} code jobs show ${jobId}`);
+            this.log(`  ${this.config.bin} code jobs cancel ${jobId}`);
+            return;
+        }
+        this.log(`Job ${jobId} ${current?.status}`);
+        const result = current?.result;
+        if (result?.text) {
+            this.log('');
+            this.log(result.text);
+            if (result.truncated) {
+                this.log('');
+                this.log(`[truncated — ${result.bytes} bytes produced; full record in --json]`);
+            }
+        }
+        const error = current?.error;
+        if (error?.code || error?.message) {
+            this.log('');
+            this.log(`Error: ${[error.code, error.message].filter(Boolean).join(': ')}`);
+        }
+    }
+}
+exports.default = CodeJobsRun;

package/dist/commands/code/jobs/show.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../../base-command';
+export default class CodeJobsShow extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        job: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/code/jobs/show.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const format_1 = require("../../../lib/format");
+const TERMINAL = new Set(['completed', 'failed', 'cancelled', 'timed_out']);
+class CodeJobsShow extends base_command_1.BaseCommand {
+    static description = 'Show one Hosted Job Machine job and its timeline';
+    static examples = [
+        '<%= config.bin %> code jobs show <job-id>',
+        '<%= config.bin %> code jobs show <job-id> --json',
+    ];
+    static args = {
+        job: core_1.Args.string({ description: 'Job id', required: true, ignoreStdin: true }),
+    };
+    static flags = { json: core_1.Flags.boolean({ description: 'Output as JSON' }) };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(CodeJobsShow);
+        let task;
+        try {
+            const res = await data_provider_1.dataService.getCloudCodingTask(args.job);
+            task = res?.task;
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(task, null, 2));
+            return;
+        }
+        if (!task) {
+            this.log('Job not found.');
+            return;
+        }
+        const line = (label, value) => {
+            if (value === undefined || value === null || value === '')
+                return;
+            this.log(`${label.padEnd(14)}${String(value)}`);
+        };
+        line('ID:', task.id);
+        line('Status:', task.status);
+        line('Agent:', task.agentId);
+        if (task.repoFullName) {
+            line('Repo:', `${task.repoFullName}@${task.baseBranch ?? 'main'}`);
+        }
+        line('Work branch:', task.workBranch);
+        line('Machine:', task.machineProductLabel ?? task.machineProduct);
+        line('Lease:', task.machineLeaseId);
+        line('Model:', task.model);
+        if (typeof task.costUsd === 'number')
+            line('Cost:', `$${task.costUsd.toFixed(2)}`);
+        line('PR:', task.prUrl);
+        line('Preview:', task.previewUrl);
+        line('Created:', (0, format_1.localStamp)(task.createdAt));
+        const error = task.error;
+        if (error?.code || error?.message) {
+            line('Error:', [error.code, error.message].filter(Boolean).join(': '));
+        }
+        // The timeline is the closest thing to a log this surface has: the task
+        // persists its state transitions but not the agent's transcript, so this is
+        // where "what happened, and where did it stop" is answerable at all.
+        const timeline = Array.isArray(task.timeline) ? task.timeline : [];
+        if (timeline.length > 0) {
+            this.log('');
+            this.log('Timeline');
+            for (const entry of timeline) {
+                const at = entry.at ? (0, format_1.localStamp)(entry.at) : '-';
+                const took = typeof entry.durationMs === 'number' ? ` (${Math.round(entry.durationMs / 1000)}s)` : '';
+                const note = entry.note ? `  ${entry.note}` : '';
+                this.log(`  ${at}  ${String(entry.state ?? '-').padEnd(14)}${took}${note}`);
+            }
+        }
+        // A non-terminal job is still holding a machine. Say so, and say the verb —
+        // this is the whole reason the cancel binding exists.
+        if (!TERMINAL.has(String(task.status))) {
+            this.log('');
+            this.log(`Still running — it holds a machine and is billing. Stop it with:`);
+            this.log(`  ${this.config.bin} code jobs cancel ${task.id}`);
+        }
+        this.log('');
+        this.log('Full record: --json');
+    }
+}
+exports.default = CodeJobsShow;

package/dist/commands/commitments/preflight.js

@@ -24,12 +24,26 @@ const prompt_1 = require("../../lib/prompt");
  */
 function preflightGateLines(gate, verbose = false) {
     const mark = gate.verdict === 'pass' ? 'ok' : gate.verdict === 'block' ? 'BLOCK' : 'warn';
+    // A BLOCKING gate always states its reason. `ok` gates got a helpful `note`
+    // and `warn` gates got a reason token, and the BLOCK gates — the only ones
+    // that stop the run — got the label and nothing: two of them side by side,
+    // one meaning "still a draft" (completely benign) and one meaning "this
+    // runtime cannot enforce the contract", rendered identically. The reasons
+    // were in the `--json` payload the whole time; the plain renderer just
+    // dropped `reason` for exactly the verdict that needs it (OSK-7700).
+    //
+    // A gate that HAS a note keeps the reason behind `--verbose`, because the
+    // note is the same fact in words a reader can act on and the token beside it
+    // is then just noise: "Will the platform wake it? — status_paused" above
+    // "Resume it first." says one thing twice, in two vocabularies.
+    const note = gate.detail?.note;
+    const hasNote = typeof note === 'string' && Boolean(note.trim());
+    const showReason = verbose || (gate.verdict === 'block' && !hasNote);
     const lines = [
-        `  ${mark.padEnd(5)} ${gate.label}${verbose && gate.reason ? ` — ${gate.reason}` : ''}`,
+        `  ${mark.padEnd(5)} ${gate.label}${showReason && gate.reason ? ` — ${gate.reason}` : ''}`,
     ];
-    const note = gate.detail?.note;
-    if (typeof note === 'string' && note.trim()) {
-        lines.push(`        ${note.trim()}`);
+    if (hasNote) {
+        lines.push(`        ${String(note).trim()}`);
     }
     // `detail.hint` is the actionable plain-words sentence — why the gate is
     // capped and the exact command to lift it. It lived only in --json, so the

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

@@ -0,0 +1,39 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * The quarter to report when the caller names none.
+ *
+ * Computed in **UTC**, deliberately. The server buckets a quarter on UTC
+ * boundaries, so a local-time computation would disagree with it for a few
+ * hours either side of a quarter change — `skrr` would ask for Q3 and the
+ * server would answer about the Q4 it thinks we are in. Same clock, no seam.
+ *
+ * The previous calendar quarter is always closed, which is the cohort this
+ * endpoint reports on (`scope: 'closed_quarter'`); the current one is not, so
+ * it is never a safe default.
+ */
+export declare function previousClosedQuarter(now?: Date): {
+    year: number;
+    quarter: number;
+};
+/**
+ * `skrr commitments receipt-metrics <id>` — the closed-quarter rollup behind
+ * `commitments receipt`.
+ *
+ * `receipt` explains ONE wake. This aggregates a whole closed quarter, which is
+ * the window you need to answer "is this commitment actually delivering" rather
+ * than "what happened last night".
+ */
+export default class CommitmentsReceiptMetrics extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        year: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        quarter: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/commitments/receipt-metrics.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.previousClosedQuarter = previousClosedQuarter;
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const commitments_1 = require("../../lib/commitments");
+const commitment_product_1 = require("../../lib/commitment-product");
+/**
+ * The quarter to report when the caller names none.
+ *
+ * Computed in **UTC**, deliberately. The server buckets a quarter on UTC
+ * boundaries, so a local-time computation would disagree with it for a few
+ * hours either side of a quarter change — `skrr` would ask for Q3 and the
+ * server would answer about the Q4 it thinks we are in. Same clock, no seam.
+ *
+ * The previous calendar quarter is always closed, which is the cohort this
+ * endpoint reports on (`scope: 'closed_quarter'`); the current one is not, so
+ * it is never a safe default.
+ */
+function previousClosedQuarter(now = new Date()) {
+    const quarter = Math.floor(now.getUTCMonth() / 3) + 1;
+    if (quarter === 1)
+        return { year: now.getUTCFullYear() - 1, quarter: 4 };
+    return { year: now.getUTCFullYear(), quarter: quarter - 1 };
+}
+/**
+ * `skrr commitments receipt-metrics <id>` — the closed-quarter rollup behind
+ * `commitments receipt`.
+ *
+ * `receipt` explains ONE wake. This aggregates a whole closed quarter, which is
+ * the window you need to answer "is this commitment actually delivering" rather
+ * than "what happened last night".
+ */
+class CommitmentsReceiptMetrics extends base_command_1.BaseCommand {
+    static description = "Show a closed quarter's execution receipt metrics for a commitment";
+    static examples = [
+        '<%= config.bin %> commitments receipt-metrics obj_abc123',
+        '<%= config.bin %> commitments receipt-metrics obj_abc123 --year 2026 --quarter 2',
+        '<%= config.bin %> commitments receipt-metrics obj_abc123 --verbose',
+        '<%= config.bin %> commitments receipt-metrics obj_abc123 --json',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Commitment ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        year: core_1.Flags.integer({ description: 'Calendar year (defaults to the last closed quarter)' }),
+        quarter: core_1.Flags.integer({
+            description: 'Quarter 1-4 (defaults to the last closed quarter)',
+            min: 1,
+            max: 4,
+        }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        verbose: core_1.Flags.boolean({ description: 'Include the measurement basis behind the rates' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(CommitmentsReceiptMetrics);
+        // Both or neither. Filling in half of a caller's intent would silently
+        // report on a quarter they did not ask for — and the numbers would look
+        // perfectly plausible, which is the kind of wrong that gets acted on.
+        if ((flags.year === undefined) !== (flags.quarter === undefined)) {
+            this.error('Pass --year and --quarter together, or neither to use the last closed quarter.');
+        }
+        const fallback = previousClosedQuarter();
+        const year = flags.year ?? fallback.year;
+        const quarter = flags.quarter ?? fallback.quarter;
+        try {
+            const response = await commitments_1.commitmentApi.receiptQuarterlyMetrics(args.id, year, quarter);
+            if (flags.json)
+                return this.log(JSON.stringify(response, null, 2));
+            (0, commitment_product_1.renderExecutionReceiptQuarterlyMetrics)(response, (line) => this.log(line), flags.verbose);
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+    }
+}
+exports.default = CommitmentsReceiptMetrics;