@skrr-ai/cli 0.1.37 → 0.1.39

package/dist/lib/dedicated-machines.d.ts

@@ -221,6 +221,46 @@ export declare function dedicatedRuntimeCreateInput(input: {
  */
 export declare function isDedicatedRepositoryRef(value: string): boolean;
 export declare function createDedicatedRuntime(input: CreateDedicatedRuntimeInput): Promise<DedicatedRuntimeResponse>;
+/** One offered tier as the operator price book checks it. */
+export interface DedicatedPriceBookPresetCheck {
+    sizePreset: string;
+    customerRateCentsPerHour: number | null;
+    providerCostCentsPerHour: number | null;
+    grossMarginBps: number | null;
+    priced: boolean;
+    providerCostRecorded: boolean;
+    marginTargetMet: boolean;
+}
+/** `GET /api/machines/dedicated/price-book` — admin only. */
+export interface DedicatedOperatorPriceBook {
+    timestamp?: string;
+    availability: 'available' | 'disabled';
+    disabledReason: string | null;
+    configError: string | null;
+    priceBook: {
+        required: boolean;
+        approved: boolean;
+        version: string | null;
+        pricingPolicyRef: string | null;
+        targetGrossMarginBps: number | null;
+        missingReason: string | null;
+        presetChecks: DedicatedPriceBookPresetCheck[];
+    };
+    sizeAvailability: Array<{
+        id: string;
+        offered: boolean;
+        withheldReason: string | null;
+    }>;
+}
+/**
+ * The Dedicated Runtime price book as an operator reads it: which version and
+ * which pricing policy, and each tier's rate, cost and margin. The customer
+ * catalog carries none of the policy or cost facts, and the admin plane that
+ * also serves this is not deployed in production (OSK-9562).
+ */
+export declare function getDedicatedOperatorPriceBook(): Promise<DedicatedOperatorPriceBook>;
+/** Human lines for `machines dedicated price-book`. Pure, so it can be pinned. */
+export declare function dedicatedOperatorPriceBookLines(read: DedicatedOperatorPriceBook): string[];
 export declare function listDedicatedRuntimes(options?: {
     limit?: number;
     state?: string;
@@ -389,10 +429,57 @@ export type DedicatedCopyPlan = {
 export declare function parseDedicatedCopyEndpoints(source: string, destination: string): DedicatedCopyPlan;
 export declare function dedicatedLeaseId(lease: DedicatedLease | HarnessLease | undefined | null): string;
 export declare function dedicatedLeaseState(lease: DedicatedLease | HarnessLease | undefined | null): string;
+/**
+ * What `destroy` should say when it keeps the workspace — or null when it does
+ * not.
+ *
+ * A destroy under retention class standard/extended archives the lease and keeps
+ * its workspace volume, which keeps billing storage until it is purged. Nothing
+ * said so at the moment it mattered: `destroy` printed the new state and exited,
+ * `list` showed `archived` in the same column as `terminated`, and the one way to
+ * find out was the bill (OSK-9593).
+ */
+export declare function dedicatedDestroyRetentionNote(priorLease: DedicatedLease | undefined | null, opts: {
+    purge: boolean;
+    retain: boolean;
+    bin: string;
+}): string | null;
+/**
+ * Month-to-date Dedicated Runtime spend for the scope a `list` shows.
+ *
+ * `billing.currentMonthSpendCents` is the SCOPE's spend for the product — the
+ * server aggregates by owner scope, not by lease — so every row carried the same
+ * figure, and a column headed MONTH/CAP on per-machine rows read as that
+ * machine's cost when it was every machine's (OSK-9576). It is said once instead.
+ */
+export declare function dedicatedScopeMonthSpendCents(leases: Array<DedicatedLease | undefined | null>): number | null;
+/**
+ * A lease's own cap, marked when the scope's spend has reached it. The mark is
+ * left off a terminal lease: its cap can no longer stop anything, and
+ * "$11.06/$10.00 OVER" on a machine terminated days ago read as that machine
+ * having overrun.
+ */
+export declare function dedicatedLeaseCapCell(lease: DedicatedLease | undefined | null): string;
+/**
+ * A lease's STATUS cell. `archived` and `terminated` are both "gone" to read, and
+ * only one of them is still charging — so a lease billing retained storage says
+ * so (OSK-9593).
+ */
+export declare function dedicatedLeaseStatusCell(lease: DedicatedLease | undefined | null): string;
 export declare function dedicatedLeaseDisplayName(lease: DedicatedLease | HarnessLease | undefined | null): string;
 /** `$12.34` — cents are what the API speaks; dollars are what a person reads. */
 export declare function formatUsdCents(cents: number | null | undefined): string;
-/** `this month $1.23 of $500.00 cap`, or why that sentence cannot be written. */
+/**
+ * `$1.23 this month for machines of this type · $500.00 cap for this machine`,
+ * or why that sentence cannot be written.
+ *
+ * The two figures are different scopes and the sentence has to say so. The spend
+ * is a shared pot the server computes for (owner, team, machineProduct), so every
+ * lease of the same product reports the same number — a machine created minutes
+ * ago with no active seconds still reports the month's total. The cap is this
+ * lease's own. Printed as "$1.23 this month of $500.00 cap" the only available
+ * reading was that this machine had spent it.
+ */
 export declare function dedicatedSpendSummary(lease: DedicatedLease): string;
 /**
  * The human rendering of `machines dedicated show`, as lines.
@@ -461,12 +548,15 @@ interface CatalogSize {
     vcpus?: number;
     memoryGiB?: number;
     accelerator?: string;
+    rateCentsPerHour?: number | null;
 }
 interface CatalogPriceLine {
     label?: string;
     display?: string;
     amountCents?: number | null;
     cadence?: string;
+    /** `charge` is billed, `hold` is reserved at start, `limit` is a cap. Absent means `charge`. */
+    kind?: 'charge' | 'hold' | 'limit';
 }
 export interface DedicatedCatalog {
     availability: string;
@@ -480,9 +570,15 @@ export interface DedicatedCatalog {
     };
     retentionClasses: string[];
     backupProfiles: string[];
+    /** Server-declared: what create applies when a flag is omitted. */
+    defaultSizePreset?: string;
+    defaultRetentionClass?: string;
+    defaultBackupProfile?: string;
     defaultMonthlySpendingLimitCents?: number | null;
     maxUserMonthlySpendingLimitCents?: number | null;
     priceLines: CatalogPriceLine[];
+    /** The price book the quoted prices come from — what a later pricing question cites. */
+    priceBookVersion?: string;
     headline?: string;
 }
 /**
@@ -493,6 +589,44 @@ export interface DedicatedCatalog {
  * gated by server flags — so this is where a caller learns which ones exist.
  */
 export declare function dedicatedCatalogFromProducts(payload: unknown): DedicatedCatalog | null;
+/**
+ * The catalog's size rows: spec, the size's own hourly price, and which one
+ * `create` uses by default. The rows used to carry spec alone, sorted by name,
+ * so the $1.40/hr tier came first with nothing saying what it cost or that
+ * $0.65/hr standard was the default; a reader had to join two blocks by name.
+ */
+export declare function dedicatedCatalogSizeLines(catalog: DedicatedCatalog): string[];
+export interface DedicatedCreateChoices {
+    name: string;
+    sizePreset: string;
+    storageGb?: number;
+    retentionClass?: string;
+    spendingLimitCents?: number;
+}
+/**
+ * What a create is about to buy, in the words and numbers the catalog uses.
+ *
+ * `create` provisioned a billable machine the moment it ran — no confirmation,
+ * no dry run, and every omitted flag silently took a paid default — while
+ * `destroy` asked first. A loop probing size validation bought two real
+ * machines, one of them $1.40/hr (OSK-9592). This is what `create` now shows
+ * before it asks, and what `--dry-run` prints instead of creating.
+ *
+ * Every default comes from the catalog, never from this file: a CLI that
+ * restates a default it does not own is how `--storage-gb` once billed twice the
+ * product's disk. A value the catalog does not declare is shown as "server
+ * default" rather than guessed.
+ */
+export declare function dedicatedCreateSummary(catalog: DedicatedCatalog | null, choices: DedicatedCreateChoices): string[];
+/**
+ * The catalog's money lines, grouped by what each amount IS.
+ *
+ * A start hold and a monthly cap used to print under "Prices" beside the hourly
+ * rates, so starting a machine read as a 33c charge and "$500 default monthly
+ * cap" read as a bill (OSK-9536). A line with no `kind` comes from a server that
+ * predates it and is shown the way every line used to be: as a charge.
+ */
+export declare function dedicatedCatalogPriceLineOutput(priceLines: CatalogPriceLine[], priceBookVersion?: string): string[];
 /**
  * The product refusal code the server sent (`DEDICATED_RUNTIME_NOT_ASSIGNABLE`,
  * …), for `this.error(message, { code })`. Without it a `--json` caller got the

package/dist/lib/dedicated-machines.js

@@ -5,6 +5,8 @@ exports.describeDedicatedImageStanding = describeDedicatedImageStanding;
 exports.dedicatedRuntimeCreateInput = dedicatedRuntimeCreateInput;
 exports.isDedicatedRepositoryRef = isDedicatedRepositoryRef;
 exports.createDedicatedRuntime = createDedicatedRuntime;
+exports.getDedicatedOperatorPriceBook = getDedicatedOperatorPriceBook;
+exports.dedicatedOperatorPriceBookLines = dedicatedOperatorPriceBookLines;
 exports.listDedicatedRuntimes = listDedicatedRuntimes;
 exports.getDedicatedRuntime = getDedicatedRuntime;
 exports.performDedicatedLeaseAction = performDedicatedLeaseAction;
@@ -21,6 +23,10 @@ exports.writeDedicatedRuntimeFileChunk = writeDedicatedRuntimeFileChunk;
 exports.parseDedicatedCopyEndpoints = parseDedicatedCopyEndpoints;
 exports.dedicatedLeaseId = dedicatedLeaseId;
 exports.dedicatedLeaseState = dedicatedLeaseState;
+exports.dedicatedDestroyRetentionNote = dedicatedDestroyRetentionNote;
+exports.dedicatedScopeMonthSpendCents = dedicatedScopeMonthSpendCents;
+exports.dedicatedLeaseCapCell = dedicatedLeaseCapCell;
+exports.dedicatedLeaseStatusCell = dedicatedLeaseStatusCell;
 exports.dedicatedLeaseDisplayName = dedicatedLeaseDisplayName;
 exports.formatUsdCents = formatUsdCents;
 exports.dedicatedSpendSummary = dedicatedSpendSummary;
@@ -33,6 +39,9 @@ exports.dedicatedLeaseIdForDaemon = dedicatedLeaseIdForDaemon;
 exports.dedicatedTerminalHarness = dedicatedTerminalHarness;
 exports.selectDedicatedAttachHarness = selectDedicatedAttachHarness;
 exports.dedicatedCatalogFromProducts = dedicatedCatalogFromProducts;
+exports.dedicatedCatalogSizeLines = dedicatedCatalogSizeLines;
+exports.dedicatedCreateSummary = dedicatedCreateSummary;
+exports.dedicatedCatalogPriceLineOutput = dedicatedCatalogPriceLineOutput;
 exports.dedicatedRuntimeApiErrorCode = dedicatedRuntimeApiErrorCode;
 exports.dedicatedRuntimeApiErrorDetails = dedicatedRuntimeApiErrorDetails;
 exports.formatDedicatedRuntimeApiError = formatDedicatedRuntimeApiError;
@@ -150,6 +159,59 @@ async function createDedicatedRuntime(input) {
     const { requestId, workspaceId, ...body } = input;
     return (0, api_fetch_1.apiFetch)(withDedicatedScope('/api/machines/dedicated', { workspaceId }), { method: 'POST', body, headers: { 'Idempotency-Key': requestId } });
 }
+/**
+ * The Dedicated Runtime price book as an operator reads it: which version and
+ * which pricing policy, and each tier's rate, cost and margin. The customer
+ * catalog carries none of the policy or cost facts, and the admin plane that
+ * also serves this is not deployed in production (OSK-9562).
+ */
+async function getDedicatedOperatorPriceBook() {
+    return (0, api_fetch_1.apiFetch)('/api/machines/dedicated/price-book');
+}
+function formatBps(bps) {
+    return bps === null ? 'unknown' : `${(bps / 100).toFixed(1)}%`;
+}
+function formatRateCents(cents) {
+    return cents === null ? 'none' : `$${(cents / 100).toFixed(2)}/hr`;
+}
+/** Human lines for `machines dedicated price-book`. Pure, so it can be pinned. */
+function dedicatedOperatorPriceBookLines(read) {
+    const book = read.priceBook;
+    const lines = [
+        `Dedicated Runtime price book — ${book.approved ? 'approved' : 'NOT approved'}${book.required ? '' : ' (not required here)'}`,
+        `  version       ${book.version ?? 'not recorded'}`,
+        `  policy        ${book.pricingPolicyRef ?? 'not recorded'}`,
+        `  target margin ${formatBps(book.targetGrossMarginBps)}`,
+    ];
+    if (!book.approved && book.missingReason)
+        lines.push(`  why           ${book.missingReason}`);
+    if (read.availability === 'disabled' && read.disabledReason) {
+        lines.push(`  product       disabled: ${read.disabledReason}`);
+    }
+    if (read.configError)
+        lines.push(`  config        unreadable: ${read.configError}`);
+    lines.push('', 'Offered tiers');
+    if (book.presetChecks.length === 0)
+        lines.push('  none');
+    for (const check of book.presetChecks) {
+        const verdict = !check.priced
+            ? 'UNPRICED'
+            : !check.providerCostRecorded
+                ? 'UNCOSTED'
+                : check.marginTargetMet
+                    ? 'meets target'
+                    : 'BELOW TARGET';
+        lines.push(`  ${check.sizePreset.padEnd(12)} rate ${formatRateCents(check.customerRateCentsPerHour)} · cost ${formatRateCents(check.providerCostCentsPerHour)} · margin ${formatBps(check.grossMarginBps)} · ${verdict}`);
+    }
+    const withheld = read.sizeAvailability.filter((entry) => !entry.offered);
+    if (withheld.length > 0) {
+        lines.push('', 'Withheld tiers');
+        for (const entry of withheld) {
+            lines.push(`  ${entry.id.padEnd(12)} ${entry.withheldReason ?? 'no reason recorded'}`);
+        }
+    }
+    return lines;
+}
 async function listDedicatedRuntimes(options = {}) {
     const query = new URLSearchParams();
     if (options.limit)
@@ -300,6 +362,71 @@ function dedicatedLeaseId(lease) {
 function dedicatedLeaseState(lease) {
     return String(lease?.state ?? 'unknown');
 }
+/**
+ * What `destroy` should say when it keeps the workspace — or null when it does
+ * not.
+ *
+ * A destroy under retention class standard/extended archives the lease and keeps
+ * its workspace volume, which keeps billing storage until it is purged. Nothing
+ * said so at the moment it mattered: `destroy` printed the new state and exited,
+ * `list` showed `archived` in the same column as `terminated`, and the one way to
+ * find out was the bill (OSK-9593).
+ */
+function dedicatedDestroyRetentionNote(priorLease, opts) {
+    if (opts.purge || !priorLease)
+        return null;
+    if (priorLease.state === 'archived')
+        return null; // destroying an archived lease purges it
+    const retentionClass = String(priorLease.storage?.retentionClass || 'none');
+    if (!opts.retain && retentionClass === 'none')
+        return null;
+    const id = dedicatedLeaseId(priorLease) || '<lease-id>';
+    const why = opts.retain ? '--retain-storage' : `retention class ${retentionClass}`;
+    return (`The workspace is kept (${why}), and its storage keeps billing until you delete it: ` +
+        `${opts.bin} machines dedicated destroy ${id} --purge-storage`);
+}
+const DEDICATED_TERMINAL_STATES = new Set(['terminated', 'failed', 'lost']);
+/**
+ * Month-to-date Dedicated Runtime spend for the scope a `list` shows.
+ *
+ * `billing.currentMonthSpendCents` is the SCOPE's spend for the product — the
+ * server aggregates by owner scope, not by lease — so every row carried the same
+ * figure, and a column headed MONTH/CAP on per-machine rows read as that
+ * machine's cost when it was every machine's (OSK-9576). It is said once instead.
+ */
+function dedicatedScopeMonthSpendCents(leases) {
+    for (const lease of leases) {
+        const cents = lease?.billing
+            ?.currentMonthSpendCents;
+        if (typeof cents === 'number' && Number.isFinite(cents))
+            return cents;
+    }
+    return null;
+}
+/**
+ * A lease's own cap, marked when the scope's spend has reached it. The mark is
+ * left off a terminal lease: its cap can no longer stop anything, and
+ * "$11.06/$10.00 OVER" on a machine terminated days ago read as that machine
+ * having overrun.
+ */
+function dedicatedLeaseCapCell(lease) {
+    const billing = lease?.billing;
+    if (!billing || typeof billing.monthlySpendLimitCents !== 'number')
+        return '-';
+    const reached = billing.spendingLimitExceeded && !DEDICATED_TERMINAL_STATES.has(dedicatedLeaseState(lease));
+    return `${formatUsdCents(billing.monthlySpendLimitCents)}${reached ? ' · reached' : ''}`;
+}
+/**
+ * A lease's STATUS cell. `archived` and `terminated` are both "gone" to read, and
+ * only one of them is still charging — so a lease billing retained storage says
+ * so (OSK-9593).
+ */
+function dedicatedLeaseStatusCell(lease) {
+    const state = dedicatedLeaseState(lease);
+    const billableState = lease?.billing
+        ?.billableState;
+    return billableState === 'storage' ? `${state} · billing storage` : state;
+}
 function dedicatedLeaseDisplayName(lease) {
     return lease?.displayName ? String(lease.displayName) : '-';
 }
@@ -310,7 +437,17 @@ function formatUsdCents(cents) {
     const sign = cents < 0 ? '-' : '';
     return `${sign}$${(Math.abs(cents) / 100).toFixed(2)}`;
 }
-/** `this month $1.23 of $500.00 cap`, or why that sentence cannot be written. */
+/**
+ * `$1.23 this month for machines of this type · $500.00 cap for this machine`,
+ * or why that sentence cannot be written.
+ *
+ * The two figures are different scopes and the sentence has to say so. The spend
+ * is a shared pot the server computes for (owner, team, machineProduct), so every
+ * lease of the same product reports the same number — a machine created minutes
+ * ago with no active seconds still reports the month's total. The cap is this
+ * lease's own. Printed as "$1.23 this month of $500.00 cap" the only available
+ * reading was that this machine had spent it.
+ */
 function dedicatedSpendSummary(lease) {
     const billing = lease.billing;
     if (!billing)
@@ -321,15 +458,33 @@ function dedicatedSpendSummary(lease) {
     }
     const spent = billing.currentMonthSpendCents;
     const projected = billing.projectedCurrentMonthSpendCents;
-    const parts = [`${formatUsdCents(spent)} this month of ${formatUsdCents(cap)} cap`];
+    const parts = [
+        `${formatUsdCents(spent)} this month for machines of this type`,
+        `${formatUsdCents(cap)} cap for this machine`,
+    ];
     if (typeof projected === 'number' && projected !== spent) {
         parts.push(`projected ${formatUsdCents(projected)}`);
     }
     if (billing.spendingLimitExceeded) {
-        parts.push('OVER CAP — compute is stopped, files are kept');
+        parts.push(`OVER CAP — ${overCapComputeClause(lease.state)}, files are kept`);
     }
     return parts.join(' · ');
 }
+/**
+ * What the cap has done to compute, in the tense the lease is actually in.
+ *
+ * This always said "compute is stopped", including for a machine that was still
+ * `requested` — which, over its cap, never provisions and cannot have its cap
+ * raised until it settles (OSK-9836). The reconciler stops compute for exactly
+ * `stopping`, `stopped` and `archived`; anything else is only on its way there.
+ */
+function overCapComputeClause(state) {
+    if (state === 'stopped' || state === 'archived')
+        return 'compute is stopped';
+    if (state === 'stopping')
+        return 'compute is stopping';
+    return 'compute will be stopped';
+}
 /**
  * The human rendering of `machines dedicated show`, as lines.
  *
@@ -743,14 +898,128 @@ function dedicatedCatalogFromProducts(payload) {
             : {}),
         retentionClasses: configuration.retentionClasses || [],
         backupProfiles: configuration.backupProfiles || [],
+        ...(typeof configuration.defaultSizePreset === 'string'
+            ? { defaultSizePreset: configuration.defaultSizePreset }
+            : {}),
+        ...(typeof configuration.defaultRetentionClass === 'string'
+            ? { defaultRetentionClass: configuration.defaultRetentionClass }
+            : {}),
+        ...(typeof configuration.defaultBackupProfile === 'string'
+            ? { defaultBackupProfile: configuration.defaultBackupProfile }
+            : {}),
         defaultMonthlySpendingLimitCents: billing.defaultMonthlySpendingLimitCents,
         maxUserMonthlySpendingLimitCents: billing.maxUserMonthlySpendingLimitCents,
         priceLines: Array.isArray(presentation.priceLines)
             ? presentation.priceLines
             : [],
+        ...(typeof billing.priceBook?.version === 'string'
+            ? { priceBookVersion: billing.priceBook.version }
+            : {}),
         ...(typeof presentation.headline === 'string' ? { headline: presentation.headline } : {}),
     };
 }
+/**
+ * The catalog's size rows: spec, the size's own hourly price, and which one
+ * `create` uses by default. The rows used to carry spec alone, sorted by name,
+ * so the $1.40/hr tier came first with nothing saying what it cost or that
+ * $0.65/hr standard was the default; a reader had to join two blocks by name.
+ */
+function dedicatedCatalogSizeLines(catalog) {
+    return catalog.sizes.map((size) => {
+        const spec = [
+            size.vcpus ? `${size.vcpus} vCPU` : '',
+            size.memoryGiB ? `${size.memoryGiB} GiB RAM` : '',
+            size.accelerator || '',
+            typeof size.rateCentsPerHour === 'number' && size.rateCentsPerHour > 0
+                ? `${formatUsdCents(size.rateCentsPerHour)}/hr`
+                : '',
+        ]
+            .filter(Boolean)
+            .join(' · ');
+        const isDefault = size.id !== undefined && size.id === catalog.defaultSizePreset;
+        return `  ${String(size.id).padEnd(14)}${spec}${isDefault ? '  (default)' : ''}`;
+    });
+}
+/**
+ * What a create is about to buy, in the words and numbers the catalog uses.
+ *
+ * `create` provisioned a billable machine the moment it ran — no confirmation,
+ * no dry run, and every omitted flag silently took a paid default — while
+ * `destroy` asked first. A loop probing size validation bought two real
+ * machines, one of them $1.40/hr (OSK-9592). This is what `create` now shows
+ * before it asks, and what `--dry-run` prints instead of creating.
+ *
+ * Every default comes from the catalog, never from this file: a CLI that
+ * restates a default it does not own is how `--storage-gb` once billed twice the
+ * product's disk. A value the catalog does not declare is shown as "server
+ * default" rather than guessed.
+ */
+function dedicatedCreateSummary(catalog, choices) {
+    const size = catalog?.sizes.find((entry) => entry.id === choices.sizePreset);
+    const spec = size
+        ? [
+            size.vcpus ? `${size.vcpus} vCPU` : '',
+            size.memoryGiB ? `${size.memoryGiB} GiB RAM` : '',
+            typeof size.rateCentsPerHour === 'number' && size.rateCentsPerHour > 0
+                ? `${formatUsdCents(size.rateCentsPerHour)} per running hour`
+                : '',
+        ]
+            .filter(Boolean)
+            .join(' · ')
+        : 'not in the catalog this server offers';
+    const storagePrice = catalog?.priceLines.find((line) => line.cadence === 'per-gb-month');
+    const storageGb = choices.storageGb ?? catalog?.storage?.defaultGb;
+    const storage = storageGb !== undefined
+        ? `${storageGb} GiB${choices.storageGb === undefined ? ' (catalog default)' : ''}`
+        : 'server default';
+    const retentionClass = choices.retentionClass ?? catalog?.defaultRetentionClass;
+    const retention = retentionClass
+        ? `${retentionClass}${choices.retentionClass === undefined ? ' (catalog default)' : ''}`
+        : 'server default';
+    const retains = retentionClass !== undefined && retentionClass !== 'none';
+    const capCents = choices.spendingLimitCents ?? catalog?.defaultMonthlySpendingLimitCents;
+    const cap = capCents !== undefined && capCents !== null
+        ? `${formatUsdCents(capCents)} per month${choices.spendingLimitCents === undefined ? ' (catalog default)' : ''}`
+        : 'server default';
+    return [
+        `Create Dedicated Runtime "${choices.name}" — it bills while it runs:`,
+        `  size         ${choices.sizePreset} — ${spec}`,
+        `  storage      ${storage}${storagePrice?.display ? ` — ${storagePrice.display}` : ''}`,
+        `  retention    ${retention}${retains ? ' — destroy keeps the workspace, and its storage bills until you purge it' : ''}`,
+        `  monthly cap  ${cap}`,
+    ];
+}
+/**
+ * The catalog's money lines, grouped by what each amount IS.
+ *
+ * A start hold and a monthly cap used to print under "Prices" beside the hourly
+ * rates, so starting a machine read as a 33c charge and "$500 default monthly
+ * cap" read as a bill (OSK-9536). A line with no `kind` comes from a server that
+ * predates it and is shown the way every line used to be: as a charge.
+ */
+function dedicatedCatalogPriceLineOutput(priceLines, priceBookVersion) {
+    // The version is what a charge dispute later cites; it was in the payload and
+    // the command dropped it (OSK-9562).
+    const pricesHeading = priceBookVersion ? `Prices (price book ${priceBookVersion})` : 'Prices';
+    const groups = [
+        { kind: 'charge', heading: pricesHeading },
+        { kind: 'hold', heading: 'Held against your cap at start (not billed)' },
+        { kind: 'limit', heading: 'Monthly caps (--spending-limit-cents)' },
+    ];
+    if (priceLines.length === 0)
+        return ['', pricesHeading, '  not published by this server'];
+    const output = [];
+    for (const group of groups) {
+        const lines = priceLines.filter((line) => (line.kind || 'charge') === group.kind);
+        if (lines.length === 0)
+            continue;
+        output.push('', group.heading);
+        for (const line of lines) {
+            output.push(`  ${line.display || `${formatUsdCents(line.amountCents)} ${line.label || ''}`}`);
+        }
+    }
+    return output;
+}
 /**
  * Dedicated Runtime commands are unusually likely to meet a server that has
  * never heard of them.
@@ -867,9 +1136,44 @@ function dedicatedRuntimeApiErrorDetails(err) {
  */
 function describeRefusalReasons(err) {
     const details = dedicatedRuntimeApiErrorDetails(err);
+    const spend = describeSpendingCapRefusal(err.body, details);
+    if (spend)
+        return spend;
     const sentences = (0, harnesses_1.describeHealthReasonSentences)(details?.reasons, details?.state);
     return sentences ? ` Reasons: ${sentences}` : '';
 }
+/**
+ * The numbers behind a cap refusal: the cap, this month's spend so far, and
+ * where the refused action would have taken it — plus the command that raises
+ * the cap. Without them "would exceed the monthly cap" left a user guessing by
+ * how much, and which cap (OSK-9552).
+ */
+function describeSpendingCapRefusal(body, details) {
+    let code;
+    try {
+        code = JSON.parse(body || '{}').code;
+    }
+    catch {
+        return '';
+    }
+    if (code !== 'RUNTIME_SPENDING_LIMIT_EXCEEDED' || !details)
+        return '';
+    const cents = (key) => {
+        const value = details[key];
+        return typeof value === 'number' && Number.isFinite(value) ? value : null;
+    };
+    const limit = cents('limitCents');
+    const spent = cents('currentSpendCents');
+    const projected = cents('projectedCents');
+    const parts = [
+        limit !== null ? `Cap ${formatUsdCents(limit)}` : '',
+        spent !== null ? `spent this month ${formatUsdCents(spent)}` : '',
+        projected !== null ? `this would bring it to ${formatUsdCents(projected)}` : '',
+    ].filter(Boolean);
+    if (parts.length === 0)
+        return '';
+    return ` ${parts.join('; ')}. Raise the cap with \`machines dedicated spending-limit <lease-id> --cents <n>\`.`;
+}
 function formatDedicatedRuntimeApiError(err) {
     if (!(err instanceof api_fetch_1.ApiFetchError) || !err.body) {
         return null;

package/dist/lib/failed-lookup.d.ts

@@ -0,0 +1,3 @@
+export declare function isFailedLookupValue(value: unknown): boolean;
+/** The shared explanation, so every resolver refuses in the same words. */
+export declare function describeFailedLookupValue(value: string, noun: string): string;

package/dist/lib/failed-lookup.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFailedLookupValue = isFailedLookupValue;
+exports.describeFailedLookupValue = describeFailedLookupValue;
+/**
+ * Values a script produces when a lookup upstream has ALREADY failed.
+ *
+ * `jq -r .id` on a missing field prints `null`. A JavaScript value that was
+ * never set stringifies to `undefined`; an object to `[object Object]`. Python
+ * prints `None`, Ruby `nil`, and a boolean field read as an id gives `true` or
+ * `false`. No person types any of these as a reference to a Task, a Space or a
+ * member — and a script passes one exactly when its previous step went wrong.
+ *
+ * The reference resolvers are generous by design: a person can type part of a
+ * title, and when exactly one title contains it, that is the one they meant.
+ * The same generosity turned `tasks complete "$ID"` with `ID=null` into
+ * "complete whichever single task mentions null". So these are refused before
+ * any search runs. Matching is on the WHOLE trimmed value, case-insensitively:
+ * a real title that merely contains one of these words still resolves.
+ */
+const FAILED_LOOKUP_VALUES = new Set([
+    'null',
+    'undefined',
+    'none',
+    'nil',
+    'nan',
+    'true',
+    'false',
+    '[object object]',
+]);
+function isFailedLookupValue(value) {
+    return typeof value === 'string' && FAILED_LOOKUP_VALUES.has(value.trim().toLowerCase());
+}
+/** The shared explanation, so every resolver refuses in the same words. */
+function describeFailedLookupValue(value, noun) {
+    return (`"${value.trim()}" is not a ${noun} reference — it is what a failed lookup prints ` +
+        '(for example `jq -r` on a missing field, or an unset variable). Refusing to search ' +
+        'names for it, because a single accidental match would be acted on.\n' +
+        '  → check the step that produced this value; it most likely failed.');
+}

package/dist/lib/first-party-harness-agent.js

@@ -242,10 +242,17 @@ async function resolveFirstPartyHarnessAgent(explicit, deps = {}, options = {})
     // Asked, not told: the caller opted out of creation, so "no default" is a fact
     // about this machine rather than a failure, and the remedy is a real command.
     if (options.createDefault === false) {
-        throw new FirstPartyHarnessAgentError('agent-unset', `nothing is configured and you have no ${auth_core_1.FIRST_PARTY_HARNESS.displayName} default agent yet. ` +
+        throw new FirstPartyHarnessAgentError('agent-unset', 
+        // No roster here. The question was which agent a session runs as, and a
+        // hundred names in front of the one sentence that answers it buried the
+        // answer (OSK-9396). A person choosing one has `agents list` for that.
+        `nothing is configured and you have no ${auth_core_1.FIRST_PARTY_HARNESS.displayName} default agent yet. ` +
             'One is created automatically the first time you run a managed session — ' +
             `or make it now with \`${auth_core_1.FIRST_PARTY_HARNESS.command} skrr-agent --create\`` +
-            (rows.length ? `. Yours: ${candidates(rows)}` : ''));
+            (rows.length
+                ? `, or pick one of your ${rows.length} with ` +
+                    `\`${auth_core_1.FIRST_PARTY_HARNESS.command} skrr-agent --set <id-or-name>\` (see \`skrr agents list\`)`
+                : ''));
     }
     // The endpoint answered without an agent. Nothing here can repair that, but
     // the user still has every ordinary way to name one.

package/dist/lib/first-party-harness-doctor.d.ts

@@ -35,6 +35,21 @@ export interface DoctorCheck {
     detail: string;
     /** What to do about it. Only present when there is something to do. */
     remedy?: string;
+    /** The files and directories a check looked at, for `--json` consumers. */
+    sources?: DoctorSource[];
+}
+/** One place the engine reads instructions or skills from. */
+export interface DoctorSource {
+    /** As a person would type it: relative for the project, `~/` for the user. */
+    path: string;
+    kind: 'instructions' | 'skills';
+    owner: 'engine' | 'compatibility';
+    scope: 'project' | 'user';
+    present: boolean;
+    /** Skill directories holding a SKILL.md; only for a present skill root. */
+    skills?: number;
+    /** Why the engine will not read it although it exists, when it will not. */
+    disabled?: string;
 }
 export interface DoctorReport {
     checks: DoctorCheck[];