@skrr-ai/cli 0.1.47 → 0.1.49

package/README.md

@@ -53,7 +53,7 @@ observability), and shared links.
 | **tasks result**                      | `submit`, `show` (immutable Result versions and exact Review state)                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | **tasks resource**                    | `add`, `list` (versioned inputs, references, evidence, attachments, and Deliverables)                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | **tasks deliverable**                 | `add`, `list`, `confirm` (the user-facing produced-Resource workflow)                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| **tasks labels**                      | `list`, `create`, `delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| **tasks labels**                      | `list`, `create`, `delete`, `attach`, `detach`, `suggest` (label vocabulary + per-task attachment; `suggest` asks the model to pick from the declared vocabulary, advisory only)                                                                                                                                                                                                                                                                                                                         |
 | **tasks approvals**                   | `list`, `create`, `delete`, `resolve`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | **tasks attachments**                 | `list`, `delete`, `upload`, `download`                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | **integrations**                      | `toolkits`, `search`, `execute`, `tools list`, `tools allow`, `connections connect`, `connections list`, `connections finalize`, `connections disconnect`, `connections reconnect`                                                                                                                                                                                                                                                                                                                    |

package/dist/base-command.d.ts

@@ -403,6 +403,24 @@ export declare function describeHarnessUnavailable(body: Record<string, unknown>
  * Exported for tests.
  */
 export declare function describeGitHubUnavailable(): string;
+/**
+ * Frame a typed `LABEL_SUGGESTION_UNAVAILABLE` failure as what it is — the
+ * suggestion's hosted-inference call found no billing payer — rather than a
+ * control-plane outage.
+ *
+ * `POST /api/tasks/:taskId/labels/suggest` answers 503 with this code when
+ * `resolveHostedUtilityBillingContext` cannot resolve a payer. The generic
+ * 503 handler would otherwise announce "service outage, retry once it
+ * recovers" and record an incident — all false: the platform answered, the
+ * task and its labels are untouched, and an immediate retry resolves the
+ * same nothing. Lead with the server's `cause`/`remedy` when present (the
+ * 5xx redaction boundary lets both through), falling back to the CLI's own
+ * sentence keyed on the code — in production the redaction generalizes the
+ * message to "An unexpected error occurred."
+ *
+ * Exported for tests.
+ */
+export declare function describeLabelSuggestionUnavailable(body: Record<string, unknown> | null, bin?: string): string;
 /** A deployment setting cannot recover through a client retry. */
 export declare function describeGitHubAppNotConfigured(): string;
 export declare function describeResourceNotFound(serverMessage: string | undefined, bin?: string, baseURL?: string): string | null;

package/dist/base-command.js

@@ -7,6 +7,7 @@ exports.apiRefusal = apiRefusal;
 exports.withSubject = withSubject;
 exports.describeHarnessUnavailable = describeHarnessUnavailable;
 exports.describeGitHubUnavailable = describeGitHubUnavailable;
+exports.describeLabelSuggestionUnavailable = describeLabelSuggestionUnavailable;
 exports.describeGitHubAppNotConfigured = describeGitHubAppNotConfigured;
 exports.describeResourceNotFound = describeResourceNotFound;
 exports.describeAssigneeNotInSpace = describeAssigneeNotInSpace;
@@ -19,6 +20,7 @@ const core_1 = require("@oclif/core");
 Object.defineProperty(exports, "Flags", { enumerable: true, get: function () { return core_1.Flags; } });
 const option_hint_1 = require("./lib/option-hint");
 const failed_lookup_1 = require("./lib/failed-lookup");
+const http_error_1 = require("./lib/http-error");
 // Re-exported from its home in `lib/keychain`, beside the other profile
 // functions. It lived here while `init()` was its only caller; a lib module
 // needing it would otherwise have to import the command base class, and with
@@ -797,9 +799,27 @@ class BaseCommand extends core_1.Command {
         if (optionHint) {
             err.message = `${err.message}\n\n${optionHint}`;
         }
+        // A transport error that reaches here uncaught still carries the server's
+        // coded refusal in its body — node adapter `err.body` text, axios-shaped
+        // `err.response.data` — but the envelope below reads only `err.code` and
+        // the transport line. `commitments import` answered a fingerprint-mismatch
+        // 400 as `CLI_PARSE_ERROR` while the body named the mismatch. Lift the
+        // body's code and message onto the error so the JSON envelope and the
+        // `super.catch` line both report the refusal the API actually sent.
+        const httpBody = (0, http_error_1.httpBodyOf)(err);
+        const httpStatus = (0, http_error_1.httpStatusOf)(err);
+        if (httpBody && httpStatus !== undefined && httpStatus >= 400) {
+            const bodyCode = stringProp(httpBody, 'code') || stringProp(httpBody, 'errorType');
+            const bodyMessage = stringProp(httpBody, 'message') || stringProp(httpBody, 'error');
+            err.code ??= bodyCode || `HTTP_${httpStatus}`;
+            if (bodyMessage && !err.message.includes(bodyMessage)) {
+                err.message = `${bodyMessage} — ${err.message}`;
+            }
+        }
         if (this.wantsJsonOutput()) {
             const exit = err.exitCode ?? err.oclif?.exit ?? 1;
             process.exitCode = exit;
+            const details = detailsFromCaughtError(err) ?? httpBody;
             this.log(JSON.stringify({
                 ok: false,
                 error: {
@@ -808,7 +828,7 @@ class BaseCommand extends core_1.Command {
                     retryable: err.retryable ?? false,
                     command: this.id ?? null,
                     server: this.cliConfig?.baseURL ?? null,
-                    ...(detailsFromCaughtError(err) ? { details: detailsFromCaughtError(err) } : {}),
+                    ...(details ? { details } : {}),
                 },
             }, null, 2));
             return;
@@ -931,6 +951,20 @@ class BaseCommand extends core_1.Command {
                     details: body ?? undefined,
                 });
             }
+            else if (bodyCode === 'LABEL_SUGGESTION_UNAVAILABLE') {
+                // The label-suggestion route found no inference payer — a per-call
+                // condition the API deliberately reported, not a platform outage,
+                // even though it answers 503. Intercept before the outage heuristic
+                // so the user is not told skrr is down and no incident is recorded.
+                this.failWithCliError({
+                    message: say(describeLabelSuggestionUnavailable(body, this.config.bin)),
+                    code: bodyCode,
+                    status: e.status,
+                    exit: 1,
+                    retryable: false,
+                    details: body ?? undefined,
+                });
+            }
             else if (bodyCode === 'ASSIGNEE_NOT_IN_SPACE') {
                 // Code-specific enrichment takes precedence over the status heuristic:
                 // the server rejects a non-member assignee by id with no next step, so
@@ -1467,6 +1501,32 @@ function describeGitHubUnavailable() {
     return ('GitHub is temporarily unreachable, so this request could not be completed. ' +
         'skrr itself answered, so this is not a skrr outage — try again shortly.');
 }
+/**
+ * Frame a typed `LABEL_SUGGESTION_UNAVAILABLE` failure as what it is — the
+ * suggestion's hosted-inference call found no billing payer — rather than a
+ * control-plane outage.
+ *
+ * `POST /api/tasks/:taskId/labels/suggest` answers 503 with this code when
+ * `resolveHostedUtilityBillingContext` cannot resolve a payer. The generic
+ * 503 handler would otherwise announce "service outage, retry once it
+ * recovers" and record an incident — all false: the platform answered, the
+ * task and its labels are untouched, and an immediate retry resolves the
+ * same nothing. Lead with the server's `cause`/`remedy` when present (the
+ * 5xx redaction boundary lets both through), falling back to the CLI's own
+ * sentence keyed on the code — in production the redaction generalizes the
+ * message to "An unexpected error occurred."
+ *
+ * Exported for tests.
+ */
+function describeLabelSuggestionUnavailable(body, bin = 'skrr') {
+    const cause = stringProp(body, 'cause') ||
+        'Label suggestion is unavailable — it runs on hosted inference, and no ' +
+            'billing payer could be resolved for this call.';
+    const remedy = stringProp(body, 'remedy') ||
+        `Attach a label directly with \`${bin} tasks labels attach <task-id> --label <id>\` — ` +
+            'a suggestion is a convenience, not a requirement.';
+    return `${cause}\n  → ${remedy}`;
+}
 /** A deployment setting cannot recover through a client retry. */
 function describeGitHubAppNotConfigured() {
     return ('The GitHub App is not configured on this deployment. ' +

package/dist/commands/agent-worker.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class AgentWorker extends Command {
+    static summary: string;
+    static description: string;
+    static flags: {
+        socket: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'heartbeat-ms': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    /** `revoked`/`invalid_handle` — the binding is gone, not the transport. */
+    private bindingRefused;
+}

package/dist/commands/agent-worker.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const guest_service_1 = require("../lib/guest-service");
+/**
+ * `skrr agent-worker` — the long-lived guest agent worker (§10.2).
+ *
+ * The blessed `agent` service template runs this command inside a Dedicated
+ * Runtime guest. The control plane mints the binding at service-create admit
+ * and injects it into the spec's env:
+ *
+ *   SKRR_AGENT_ID      the agent this worker holds presence for
+ *   SKRR_AGENT_HANDLE  the presence capability — `awh_<id>.aws_<secret>`
+ *
+ * On start the worker registers with the daemon's broker socket, then
+ * heartbeats until it is stopped (SIGTERM → bye) or the binding is revoked —
+ * `service remove` deletes the spec, the broker's next answer is `revoked`,
+ * and the worker exits. The service lifecycle IS the handle lifecycle.
+ *
+ * The handle is never logged and never echoed — the daemon's reply names the
+ * agent and service it validated, which is everything worth printing.
+ */
+const DEFAULT_SOCKET = '/run/skrr-dedicated-runtime/agent-worker/agent-worker.sock';
+const DEFAULT_HEARTBEAT_MS = 30_000;
+/** Register retries cover a service started while the daemon is restarting. */
+const REGISTER_RETRY_MS = 3_000;
+const REGISTER_BUDGET_MS = 120_000;
+/** Consecutive transport failures before the worker gives up and lets the reconciler see the crash. */
+const HEARTBEAT_FAILURE_LIMIT = 10;
+const BYE_TIMEOUT_MS = 5_000;
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+class AgentWorker extends core_1.Command {
+    static summary = 'Run the agent-worker presence loop for this machine (launched by the agent service template)';
+    static description = 'Reads the server-issued binding from SKRR_AGENT_ID / SKRR_AGENT_HANDLE, registers with ' +
+        'the machine’s daemon over the agent-worker socket, and holds presence with heartbeats ' +
+        'until the service is stopped or the binding is revoked. Not meant to be run by hand — ' +
+        'declare it with `skrr machines dedicated service create --template agent --param agent=<agent-id>` ' +
+        'or the service API.';
+    static flags = {
+        socket: core_1.Flags.string({
+            description: 'Agent-worker socket path (defaults to the machine’s broker socket)',
+            env: 'SKRR_AGENT_WORKER_SOCKET',
+        }),
+        'heartbeat-ms': core_1.Flags.integer({
+            description: 'Heartbeat interval override in milliseconds (the broker’s answer wins)',
+            min: 1000,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AgentWorker);
+        const agentId = (process.env.SKRR_AGENT_ID ?? '').trim();
+        const handle = (process.env.SKRR_AGENT_HANDLE ?? '').trim();
+        if (!agentId || !handle) {
+            this.error('SKRR_AGENT_ID and SKRR_AGENT_HANDLE must both be set — the control plane injects them ' +
+                'when a service is created with an agent binding. This process is not meant to be run ' +
+                'by hand; create the service with `--template agent --param agent=<agent-id>` instead.', { exit: 2 });
+        }
+        const socketPath = flags.socket ?? DEFAULT_SOCKET;
+        const heartbeatOverride = flags['heartbeat-ms'];
+        const call = (verb, timeoutMs) => (0, guest_service_1.callGuestServiceSocket)({ verb, handle }, { socketPath, ...(timeoutMs ? { timeoutMs } : {}) });
+        // ---- register --------------------------------------------------------
+        // The service can start while the daemon is restarting; transport errors
+        // retry inside a budget, a refused binding never does.
+        const deadline = Date.now() + REGISTER_BUDGET_MS;
+        let heartbeatMs = heartbeatOverride ?? DEFAULT_HEARTBEAT_MS;
+        for (;;) {
+            try {
+                const reply = await call('register');
+                if (typeof reply.agentId === 'string' && reply.agentId !== agentId) {
+                    this.error(`The daemon validated this handle for ${reply.agentId}, not ${agentId} — ` +
+                        'the service spec is inconsistent. Remove and recreate the service.', { exit: 2 });
+                }
+                if (typeof reply.heartbeatMs === 'number' && reply.heartbeatMs >= 1000) {
+                    heartbeatMs = reply.heartbeatMs;
+                }
+                this.log(`agent-worker registered: agent=${reply.agentId ?? agentId} ` +
+                    `service=${reply.serviceName ?? '?'} heartbeat=${heartbeatMs}ms`);
+                break;
+            }
+            catch (error) {
+                if (this.bindingRefused(error)) {
+                    this.error(`The daemon refused this worker's binding: ${error.message}. ` +
+                        'The service spec predates the handle — remove and recreate the service.', { exit: 1 });
+                }
+                if (Date.now() >= deadline) {
+                    this.error(`The agent-worker socket never answered within ${REGISTER_BUDGET_MS / 1000}s ` +
+                        `(${error.message}) — the machine's daemon is not offering the ` +
+                        'agent-worker lane.', { exit: 1 });
+                }
+                await sleep(REGISTER_RETRY_MS);
+            }
+        }
+        // ---- heartbeat -------------------------------------------------------
+        let failures = 0;
+        let stopping = false;
+        const stop = () => {
+            stopping = true;
+        };
+        process.on('SIGTERM', stop);
+        process.on('SIGINT', stop);
+        while (!stopping) {
+            await sleep(heartbeatMs);
+            if (stopping)
+                break;
+            try {
+                await call('heartbeat');
+                failures = 0;
+            }
+            catch (error) {
+                if (this.bindingRefused(error)) {
+                    // The binding is dead — almost always `service remove` having
+                    // deleted the spec. Exit cleanly: there is nothing to retry, and
+                    // under an on-failure restart policy a clean exit keeps the
+                    // reconciler from flapping a corpse.
+                    this.log('The agent binding was revoked — exiting.');
+                    process.exit(0);
+                }
+                failures += 1;
+                if (failures >= HEARTBEAT_FAILURE_LIMIT) {
+                    this.error(`Lost the agent-worker socket ${failures} times in a row ` +
+                        `(${error.message}) — exiting so the service state is honest.`, { exit: 1 });
+                }
+                this.warn(`agent-worker heartbeat missed (${failures}/${HEARTBEAT_FAILURE_LIMIT})`);
+            }
+        }
+        // ---- bye ---------------------------------------------------------------
+        try {
+            await call('bye', BYE_TIMEOUT_MS);
+        }
+        catch {
+            /* a dead socket cannot hear goodbye — the missed heartbeats say it */
+        }
+    }
+    /** `revoked`/`invalid_handle` — the binding is gone, not the transport. */
+    bindingRefused(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return /revoked|invalid_handle|forbidden/i.test(message);
+    }
+}
+exports.default = AgentWorker;

package/dist/commands/agents/chat.d.ts

@@ -120,6 +120,27 @@ export declare function chatStreamHeaderLines(input: {
     agentUrl?: string | null;
     threadRootMessageId?: string;
 }): string[];
+/**
+ * The machine-pinning fragment of the chat-start payload. `--local-skill`
+ * already pins through the resolved skill daemon; `--daemon` alone pins the
+ * turn the same way (OSK-11797 — the flag was previously accepted and
+ * dropped). 'local' is the fail-closed pin: the server refuses rather than
+ * silently running on another machine when the named daemon is unavailable.
+ */
+export declare function daemonPinFields(localSkills: {
+    daemonId: string;
+    refs: Array<{
+        name: string;
+        pathHash: string;
+    }>;
+} | null, daemonFlag: string | undefined): {
+    executionEnvironment: 'local';
+    preferredDaemonId: string;
+    skillRefs?: Array<{
+        name: string;
+        pathHash: string;
+    }>;
+} | Record<string, never>;
 export default class AgentsChat extends BaseCommand {
     static description: string;
     static examples: string[];

package/dist/commands/agents/chat.js

@@ -8,6 +8,7 @@ exports.inspectTurnCommand = inspectTurnCommand;
 exports.noOutputFailureMessage = noOutputFailureMessage;
 exports.noStreamJsonPayload = noStreamJsonPayload;
 exports.chatStreamHeaderLines = chatStreamHeaderLines;
+exports.daemonPinFields = daemonPinFields;
 const node_fs_1 = require("node:fs");
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
@@ -190,6 +191,26 @@ function chatStreamHeaderLines(input) {
     lines.push(`Agent URL: ${agentUrl ?? '-'}`);
     return lines;
 }
+/**
+ * The machine-pinning fragment of the chat-start payload. `--local-skill`
+ * already pins through the resolved skill daemon; `--daemon` alone pins the
+ * turn the same way (OSK-11797 — the flag was previously accepted and
+ * dropped). 'local' is the fail-closed pin: the server refuses rather than
+ * silently running on another machine when the named daemon is unavailable.
+ */
+function daemonPinFields(localSkills, daemonFlag) {
+    if (localSkills) {
+        return {
+            skillRefs: localSkills.refs,
+            executionEnvironment: 'local',
+            preferredDaemonId: localSkills.daemonId,
+        };
+    }
+    if (daemonFlag) {
+        return { executionEnvironment: 'local', preferredDaemonId: daemonFlag };
+    }
+    return {};
+}
 class AgentsChat extends base_command_1.BaseCommand {
     static description = 'Run an agent turn with live streaming, tool events, cancellation, and reconnects';
     static examples = [
@@ -246,8 +267,10 @@ class AgentsChat extends base_command_1.BaseCommand {
             multiple: true,
         }),
         daemon: core_1.Flags.string({
-            description: 'The machine whose skills --local-skill names. Defaults to your only connected daemon.',
-            dependsOn: ['local-skill'],
+            description: 'Run this turn on this machine — a daemon id from `skrr daemons`. With ' +
+                '--local-skill it names the machine whose skills are invoked; without it ' +
+                'the turn itself is pinned to that daemon and fails rather than running ' +
+                'elsewhere if it is unavailable.',
         }),
         task: core_1.Flags.string({
             description: 'Bind this turn to a task (UUID or OSK-####). Injects the canonical task id, ' +
@@ -461,13 +484,7 @@ class AgentsChat extends base_command_1.BaseCommand {
                 // turn is asked to run on the machine that listed them. An agent whose
                 // execution policy places it elsewhere keeps that placement, and the
                 // run fails saying why rather than running without the skill.
-                ...(localSkills
-                    ? {
-                        skillRefs: localSkills.refs,
-                        executionEnvironment: 'local',
-                        preferredDaemonId: localSkills.daemonId,
-                    }
-                    : {}),
+                ...daemonPinFields(localSkills, flags.daemon),
             });
         }
         catch (err) {

package/dist/commands/balance/usage/breakdown.d.ts

@@ -0,0 +1,14 @@
+import type { TSkyCodeUsageBreakdown } from '@skrr-ai/data-provider';
+import { BaseCommand } from '../../../base-command';
+export default class BalanceUsageBreakdown extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        from: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        to: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'product-family': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+export declare function renderSkyCodeUsageBreakdown(breakdown: TSkyCodeUsageBreakdown, log: (line: string) => void): void;

package/dist/commands/balance/usage/breakdown.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderSkyCodeUsageBreakdown = renderSkyCodeUsageBreakdown;
+const core_1 = require("@oclif/core");
+const auth_core_1 = require("@skrr-ai/auth-core");
+const base_command_1 = require("../../../base-command");
+const balance_1 = require("../../../lib/balance");
+class BalanceUsageBreakdown extends base_command_1.BaseCommand {
+    static description = `Aggregate settled ${auth_core_1.FIRST_PARTY_HARNESS.displayName} usage by model, surface, agent and member`;
+    static examples = [
+        '<%= config.bin %> balance usage breakdown',
+        '<%= config.bin %> balance usage breakdown --json',
+        '<%= config.bin %> balance usage breakdown --workspace <workspace-id>',
+        '<%= config.bin %> balance usage breakdown --from 2026-09-01 --to 2026-09-15',
+        '<%= config.bin %> balance usage breakdown --product-family sky-code-api',
+    ];
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        from: core_1.Flags.string({ description: 'Inclusive ISO start time; defaults to 30 days ago' }),
+        to: core_1.Flags.string({ description: 'Inclusive ISO end time; defaults to now' }),
+        'product-family': core_1.Flags.string({
+            description: 'Restrict to one product family (e.g. sky-code-api for PAYG spend)',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(BalanceUsageBreakdown);
+        const workspaceId = flags.workspace;
+        let breakdown;
+        try {
+            breakdown = await (0, balance_1.getSkyCodeUsageBreakdown)(workspaceId, {
+                from: flags.from,
+                to: flags.to,
+                productFamily: flags['product-family'],
+            });
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(breakdown, null, 2));
+            return;
+        }
+        renderSkyCodeUsageBreakdown(breakdown, (line) => this.log(line));
+    }
+}
+exports.default = BalanceUsageBreakdown;
+function renderSkyCodeUsageBreakdown(breakdown, log) {
+    log(`${auth_core_1.FIRST_PARTY_HARNESS.displayName} usage breakdown · ${breakdown.ownerType} ${breakdown.ownerId}`);
+    log(`  Window ${breakdown.from} to ${breakdown.to}`);
+    log(`  Total ${(0, balance_1.formatCreditsWithUsd)(breakdown.total.usageMicros)} across ${breakdown.total.events} settled authorization${breakdown.total.events === 1 ? '' : 's'}`);
+    const section = (title, rows) => {
+        if (rows.length === 0)
+            return;
+        log(`  ${title}`);
+        for (const row of rows) {
+            const balance = row.balanceMicros > 0 ? ` · ${(0, balance_1.formatMicros)(row.balanceMicros)} billed to balance` : '';
+            log(`    ${row.label}  ${(0, balance_1.formatCreditsWithUsd)(row.usageMicros)} · ${row.events} event${row.events === 1 ? '' : 's'}${balance}`);
+        }
+    };
+    section('By model', breakdown.byModel.map((row) => ({
+        ...row,
+        label: [row.provider, row.model].filter(Boolean).join('/') || 'unknown',
+    })));
+    section('By surface', breakdown.bySurface.map((row) => ({ ...row, label: row.surface ?? 'unknown' })));
+    section('By agent', breakdown.byAgent.map((row) => ({ ...row, label: row.agentId ?? 'unattributed' })));
+    section('By member', breakdown.byMember.map((row) => ({ ...row, label: row.memberUserId ?? 'unattributed' })));
+}

package/dist/commands/balance/usage.js

@@ -51,8 +51,32 @@ function renderSkyCodeUsage(usage, log) {
     log(`  5-hour limit            ${(0, balance_1.formatCreditsWithUsd)(usage.fiveHour.limitUsageMicros)}`);
     log(`  5-hour reset            ${usage.fiveHour.resetsAt ?? 'unavailable'}`);
     log(`  Concurrent sessions     ${usage.fiveHour.activeSessions}/${usage.fiveHour.maxConcurrentSessions}`);
+    if (usage.weekly) {
+        log(`  Weekly used             ${(0, balance_1.formatCreditsWithUsd)(usage.weekly.usedUsageMicros)}`);
+        log(`  Weekly reserved         ${(0, balance_1.formatCreditsWithUsd)(usage.weekly.reservedUsageMicros)}`);
+        log(`  Weekly limit            ${(0, balance_1.formatCreditsWithUsd)(usage.weekly.limitUsageMicros)}`);
+        log(`  Weekly reset            ${usage.weekly.resetsAt ?? 'unavailable'}`);
+    }
+    if (usage.weeklyPremium && usage.weeklyPremium.limitUsageMicros > 0) {
+        log(`  Premium weekly used     ${(0, balance_1.formatCreditsWithUsd)(usage.weeklyPremium.usedUsageMicros)}`);
+        log(`  Premium weekly reserved ${(0, balance_1.formatCreditsWithUsd)(usage.weeklyPremium.reservedUsageMicros)}`);
+        log(`  Premium weekly limit    ${(0, balance_1.formatCreditsWithUsd)(usage.weeklyPremium.limitUsageMicros)}`);
+        log(`  Premium weekly reset    ${usage.weeklyPremium.resetsAt ?? 'unavailable'}`);
+    }
+    if (usage.degraded) {
+        log(`  Economy fallback        ${(0, balance_1.formatCreditsWithUsd)(usage.degraded.usedUsageMicros)} used of ${(0, balance_1.formatCreditsWithUsd)(usage.degraded.includedUsageMicros)}`);
+    }
     log(`  Available overage       ${(0, balance_1.formatCreditsWithUsd)(usage.balance.availableMicros)}`);
     log(`  Overage consent         ${usage.overageEnabled ? 'enabled' : 'disabled'}`);
+    if (usage.overage) {
+        log(`  Overage mode            ${usage.overage.mode}`);
+        if (usage.overage.mode === 'postpaid') {
+            log(`  Postpaid accrued        ${(0, balance_1.formatCreditsWithUsd)(usage.overage.postpaidAccruedMicros ?? 0)}`);
+        }
+        if (usage.overage.spendCapMicros != null) {
+            log(`  Overage spend cap       ${(0, balance_1.formatCreditsWithUsd)(usage.overage.spendCapMicros)}`);
+        }
+    }
     if (usage.dataStatus === 'partial') {
         if (usage.partialReasons?.includes('missing_entitlement_period')) {
             log('  Entitlement             period unavailable; catalog limits shown');

package/dist/commands/commerce/entitlements/explain.d.ts

@@ -0,0 +1,22 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * `skrr commerce entitlements explain` — WHY a subject can or cannot do a thing.
+ *
+ * The read that pays for this whole topic. "This account says it cannot do X"
+ * is a support question, and the answer is a trace through offers, contracts
+ * and grants. Tracing it from a terminal — and pasting the JSON into the
+ * ticket — is the case a console makes slow.
+ *
+ * The body is passed through because the question has a real shape (subject,
+ * capability, scope type and id) that the server validates. It is a QUESTION,
+ * so nothing is mutated by asking it.
+ */
+export default class CommerceEntitlementsExplain extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        file: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/commerce/entitlements/explain.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const base_command_1 = require("../../../base-command");
+const commerce_1 = require("../../../lib/commerce");
+const commerce_command_1 = require("../../../lib/commerce-command");
+/**
+ * `skrr commerce entitlements explain` — WHY a subject can or cannot do a thing.
+ *
+ * The read that pays for this whole topic. "This account says it cannot do X"
+ * is a support question, and the answer is a trace through offers, contracts
+ * and grants. Tracing it from a terminal — and pasting the JSON into the
+ * ticket — is the case a console makes slow.
+ *
+ * The body is passed through because the question has a real shape (subject,
+ * capability, scope type and id) that the server validates. It is a QUESTION,
+ * so nothing is mutated by asking it.
+ */
+class CommerceEntitlementsExplain extends base_command_1.BaseCommand {
+    static description = 'Explain why a subject does or does not hold a capability at a scope (admin). A question — it changes nothing.';
+    static examples = [
+        '<%= config.bin %> commerce entitlements explain --file ./question.json',
+        'echo \'{"subject":{...},"capability":"...","scopeType":"workspace","scopeId":"..."}\' | <%= config.bin %> commerce entitlements explain --file -',
+    ];
+    static flags = { ...commerce_command_1.jsonBodyFlags };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(CommerceEntitlementsExplain);
+        const body = await (0, commerce_command_1.jsonBodyFrom)(this, flags.file);
+        let result;
+        try {
+            result = await (0, commerce_1.explainCommerceEntitlement)(body);
+        }
+        catch (error) {
+            this.handleApiError(error);
+            return;
+        }
+        this.log(JSON.stringify(result, null, 2));
+    }
+}
+exports.default = CommerceEntitlementsExplain;

package/dist/commands/commerce/incidents/audit.d.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * What was DONE to an incident, as opposed to what it is.
+ *
+ * Kept a separate verb from `show` because the two answer different questions
+ * and one of them is the one you need when an incident looks resolved and
+ * nobody remembers who resolved it.
+ */
+export default class CommerceIncidentsAudit extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        kind: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        incident: 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/commerce/incidents/audit.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../../base-command");
+const commerce_1 = require("../../../lib/commerce");
+/**
+ * What was DONE to an incident, as opposed to what it is.
+ *
+ * Kept a separate verb from `show` because the two answer different questions
+ * and one of them is the one you need when an incident looks resolved and
+ * nobody remembers who resolved it.
+ */
+class CommerceIncidentsAudit extends base_command_1.BaseCommand {
+    static description = 'Show the audit trail of one marketplace incident — who acted on it and when (admin).';
+    static examples = ['<%= config.bin %> commerce incidents audit integrity <incident-id>'];
+    static args = {
+        kind: core_1.Args.string({ description: 'Incident kind', required: true, ignoreStdin: true }),
+        incident: core_1.Args.string({ description: 'Incident id', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args } = await this.parse(CommerceIncidentsAudit);
+        let result;
+        try {
+            result = await (0, commerce_1.listMarketplaceIncidentAudit)(args.kind, args.incident);
+        }
+        catch (error) {
+            this.handleApiError(error);
+            return;
+        }
+        this.log(JSON.stringify(result, null, 2));
+    }
+}
+exports.default = CommerceIncidentsAudit;