@skrr-ai/cli 0.1.92 → 0.1.93

package/dist/lib/agent-ref.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRefError = void 0;
+exports.cliFirstPartyHosts = cliFirstPartyHosts;
+exports.resolveAgentRef = resolveAgentRef;
+exports.attributedListingUrl = attributedListingUrl;
+exports.installAttribution = installAttribution;
+exports.shellQuote = shellQuote;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const http_error_1 = require("./http-error");
+const web_url_1 = require("./web-url");
+class AgentRefError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'AgentRefError';
+    }
+}
+exports.AgentRefError = AgentRefError;
+/**
+ * An agent id is a single opaque token (`agent_…` today). Anything with a
+ * slash, a colon, whitespace or a dot is a link, a path or a typo — none of
+ * which may be sent to the API as if it were an id, because the server would
+ * answer "not found" and the person would conclude the agent does not exist.
+ */
+const AGENT_ID_TOKEN = /^[A-Za-z0-9_-]+$/;
+function hostOf(origin) {
+    try {
+        return new URL(origin).host.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The built-in first-party hosts plus every origin the configured deployment
+ * serves (a dev or self-hosted `baseURL` is first-party for its own user).
+ */
+function cliFirstPartyHosts(baseURL) {
+    const hosts = new Set(data_provider_1.FIRST_PARTY_HOSTS.map((host) => host.toLowerCase()));
+    if (baseURL) {
+        for (const origin of [baseURL, ...(0, web_url_1.firstPartyWebOrigins)(baseURL)]) {
+            const host = hostOf(origin);
+            if (host) {
+                hosts.add(host);
+                if (!host.startsWith('www.'))
+                    hosts.add(`www.${host}`);
+            }
+        }
+    }
+    return [...hosts];
+}
+async function defaultResolveCode(code) {
+    try {
+        return await data_provider_1.dataService.resolveDistributionCode(code);
+    }
+    catch (err) {
+        if ((0, http_error_1.httpStatusOf)(err) === 404)
+            return null;
+        throw err;
+    }
+}
+async function defaultResolveVanity(handle, slug) {
+    try {
+        return await data_provider_1.dataService.resolveAgentVanity({ handle, slug });
+    }
+    catch (err) {
+        if ((0, http_error_1.httpStatusOf)(err) === 404)
+            return null;
+        throw err;
+    }
+}
+async function resolveByVanity(value, handle, slug, attribution, options) {
+    const resolved = await (options.resolveVanity ?? defaultResolveVanity)(handle, slug);
+    if (resolved?.entity?.kind !== 'agent' || !resolved.entity.id) {
+        throw new AgentRefError(`No public agent answers to "${value}". The publisher may have unpublished it; their ` +
+            `page lists what they publish: skrr open ${(0, data_provider_1.entityPath)({ kind: 'publisher', handle })}`, 'AGENT_REF_VANITY_UNRESOLVED');
+    }
+    // An alias is an address, not a share: it carries no attribution of its own.
+    return { agentId: resolved.entity.id, source: 'vanity', attribution };
+}
+function withChannel(attribution, channel) {
+    if (attribution.channel)
+        return attribution;
+    const normalized = (0, data_provider_1.normalizeDistributionChannel)(channel);
+    return normalized ? { ...attribution, channel: normalized } : attribution;
+}
+async function resolveByCode(value, attribution, options) {
+    const code = attribution.code;
+    const resolved = await (options.resolveCode ?? defaultResolveCode)(code);
+    if (!resolved?.entity) {
+        throw new AgentRefError(`The share code in "${value}" does not point at a public agent: it may have been ` +
+            'unpublished, or the link was copied incompletely.', 'AGENT_REF_CODE_UNRESOLVED');
+    }
+    if (resolved.entity.kind !== 'agent') {
+        throw new AgentRefError(`"${value}" is a link to a ${resolved.entity.kind.replace(/_/g, ' ')}, not an agent.`, 'AGENT_REF_NOT_AN_AGENT');
+    }
+    return {
+        agentId: resolved.entity.id,
+        source: 'code',
+        // The link's own `ch` wins; the code's minted channel fills a link without one.
+        attribution: withChannel(attribution, resolved.channel),
+    };
+}
+async function resolveAgentRef(input, options = {}) {
+    const value = String(input ?? '').trim();
+    if (!value) {
+        throw new AgentRefError(`Name the agent: pass its id (agent_…) or a ${data_provider_1.BRAND.displayName} link to it.`, 'AGENT_REF_EMPTY');
+    }
+    if (AGENT_ID_TOKEN.test(value)) {
+        return { agentId: value, source: 'id', attribution: {} };
+    }
+    const inspected = (0, data_provider_1.inspectSkrrLink)(value, {
+        firstPartyHosts: cliFirstPartyHosts(options.baseURL),
+    });
+    if (!inspected) {
+        throw /^[a-z][a-z0-9+.-]*:\/\//i.test(value)
+            ? new AgentRefError(`"${value}" is not a ${data_provider_1.BRAND.displayName} link, so it was not followed. Pass an agent ` +
+                `id or a link on ${data_provider_1.BRAND.displayName}'s own site.`, 'AGENT_REF_FOREIGN')
+            : unsupported(value);
+    }
+    const { link, attribution } = inspected;
+    switch (link.kind) {
+        case 'agent':
+        case 'store_agent':
+        case 'agent_owner':
+            return { agentId: link.agentId, source: 'link', attribution };
+        case 'agent_vanity':
+            // A code on the link names the agent exactly; a bare alias is resolved
+            // by the server's vanity store.
+            if (attribution.code)
+                return resolveByCode(value, attribution, options);
+            return resolveByVanity(value, link.handle, link.slug, attribution, options);
+        case 'unknown':
+            if (attribution.code)
+                return resolveByCode(value, attribution, options);
+            throw unsupported(value);
+        default:
+            throw new AgentRefError(`"${value}" is a link to a ${link.kind.replace(/_/g, ' ')}, not an agent.`, 'AGENT_REF_NOT_AN_AGENT');
+    }
+}
+function unsupported(value) {
+    return new AgentRefError(`"${value}" is not an agent id or a link to an agent. Pass the id (agent_…) or its ` +
+        'listing link (…/a/<id>).', 'AGENT_REF_UNSUPPORTED');
+}
+/**
+ * The canonical public address of a resolved agent, keeping the attribution it
+ * arrived with — what a command prints when it echoes a link back (an install
+ * command, an `open`), so following the echo credits the same share.
+ */
+function attributedListingUrl(baseURL, ref) {
+    return (0, data_provider_1.buildShareUrl)((0, web_url_1.webOrigin)(baseURL), { kind: 'agent', id: ref.agentId }, {
+        code: ref.attribution.code,
+        channel: ref.attribution.channel,
+    });
+}
+/** The install body fields an attribution maps to; empty for an unattributed ref. */
+function installAttribution(attribution) {
+    return {
+        ...(attribution.code ? { distributionCode: attribution.code } : {}),
+        ...(attribution.channel ? { channel: attribution.channel } : {}),
+    };
+}
+/** Quote a URL for a POSIX shell: `?` and `&` in an attributed link are metacharacters. */
+function shellQuote(value) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/lib/api-fetch.d.ts

@@ -37,6 +37,8 @@ export declare class ApiFetchError extends Error {
      * attributed by guesswork — see `node-adapter.ts`.
      */
     readonly requestId?: string;
+    /** Milliseconds the server asked us to wait (`Retry-After`) on a 429. */
+    retryAfterMs?: number;
     /**
      * Set on a 401 when this CLI's own refresh was refused AND the local
      * daemon, asked for a hand-off, refused too (OSK-12474). The daemon's reason

package/dist/lib/api-fetch.js

@@ -47,6 +47,7 @@ const daemonBroker_1 = require("./daemonBroker");
 const dpop_auth_1 = require("./dpop-auth");
 const workspace_header_1 = require("./workspace-header");
 const non_json_response_1 = require("./non-json-response");
+const rate_limit_retry_1 = require("./rate-limit-retry");
 class ApiFetchError extends Error {
     status;
     body;
@@ -63,6 +64,8 @@ class ApiFetchError extends Error {
      * attributed by guesswork — see `node-adapter.ts`.
      */
     requestId;
+    /** Milliseconds the server asked us to wait (`Retry-After`) on a 429. */
+    retryAfterMs;
     /**
      * Set on a 401 when this CLI's own refresh was refused AND the local
      * daemon, asked for a hand-off, refused too (OSK-12474). The daemon's reason
@@ -186,13 +189,19 @@ async function apiFetch(pathOrUrl, opts = {}) {
         // OSK-12020 — a fresh proof per attempt for a DPoP-bound hand-off token
         // (the 401 retry below re-enters here and gets its own). No-op otherwise.
         Object.assign(headers, await (0, dpop_auth_1.dpopHeadersFor)(credential.token, method, url));
-        return fetch(url, {
+        const sent = (0, workspace_header_1.withWorkspaceHeader)(headers);
+        // E6: a 429 on a GET or an idempotency-keyed write is retried (bounded,
+        // jittered, honouring Retry-After). The last 429's wait is kept for the error.
+        const { response, retryAfterMs } = await (0, rate_limit_retry_1.fetchWithRateLimitRetry)(() => fetch(url, {
             method,
-            headers: (0, workspace_header_1.withWorkspaceHeader)(headers),
+            headers: sent,
             body,
             ...(opts.signal ? { signal: opts.signal } : {}),
-        });
+        }), { method, headers: sent, signal: opts.signal });
+        lastRetryAfterMs = retryAfterMs;
+        return response;
     };
+    let lastRetryAfterMs;
     let res = await fetchWithCredential(cred);
     let brokerFailure = null;
     if (res.status === 401 && delegatedCli) {
@@ -271,6 +280,8 @@ async function apiFetch(pathOrUrl, opts = {}) {
         const error = new ApiFetchError(`HTTP ${res.status} ${res.statusText} — ${method} ${pathOrUrl}`, res.status, text, code, method, res.headers.get('x-request-id') || undefined);
         if (brokerFailure)
             error.brokerFailure = brokerFailure;
+        if (res.status === 429 && lastRetryAfterMs !== undefined)
+            error.retryAfterMs = lastRetryAfterMs;
         throw error;
     }
     // 204/205 carry no body by definition; an empty body has no content-type

package/dist/lib/command-hygiene.d.ts

@@ -26,6 +26,8 @@ export type CommandHygieneReport = {
         domains: number;
         budgetErrors: number;
     };
+    /** The verb rules the findings below are measured against (P8). */
+    namingGrammar: readonly string[];
     issues: CommandHygieneIssue[];
 };
 export declare function auditCommands({ rootDir, manifest, }: {
@@ -37,3 +39,14 @@ export declare function auditCommands({ rootDir, manifest, }: {
      */
     manifest?: CommandManifest;
 }): CommandHygieneReport;
+/**
+ * The domains an agent drives most. A missing description or `--json` output
+ * here is a build error (P10); elsewhere it stays a warning until that domain's
+ * offenders are fixed, so the gate can ratchet outward one domain at a time.
+ */
+export declare const ENFORCED_HYGIENE_DOMAINS: readonly ["tasks", "spaces", "projects"];
+/**
+ * The verb grammar `commands --audit` checks, stated once so a reader of the
+ * report sees the rule and not only the findings it produced.
+ */
+export declare const NAMING_GRAMMAR: readonly ["Verbs: list, show, create, update, delete, archive, unarchive, move. A reversible state flip is its own verb, never a flag on its inverse.", "Scope: a list verb takes its parent scope as an optional filter flag; a verb that cannot work without a scope says so in its description.", "Output: every command in tasks, spaces and projects takes --json and has a description (audit errors)."];

package/dist/lib/command-hygiene.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAMING_GRAMMAR = exports.ENFORCED_HYGIENE_DOMAINS = void 0;
 exports.auditCommands = auditCommands;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -120,6 +121,32 @@ function auditCommands({ rootDir, manifest, }) {
                     });
                 }
             }
+            // Without a generated manifest (a source checkout, most CI jobs) the
+            // manifest rules below never run, so the P10 gate for tasks/spaces/projects
+            // would pass by not looking. Read the same two facts off the source.
+            if (!manifest && isEnforcedDomain(command)) {
+                // A spread of a shared flag set (`...paginatedExportFlags(...)`) may carry
+                // --json from another file; only the manifest can tell, so do not guess.
+                const spreadsSharedFlags = /\.\.\.[\w.]*Flags\b/.test(source);
+                if (!hasJson && !spreadsSharedFlags && isMachineRelevantCommand(command)) {
+                    issues.push({
+                        code: 'JSON_SUCCESS_OUTPUT_MISSING',
+                        severity: 'error',
+                        command,
+                        file: rel,
+                        message: 'Machine-relevant command has no --json success-output flag. Keep human-only commands intentional.',
+                    });
+                }
+                if (!/static (?:override )?description\s*=/.test(source)) {
+                    issues.push({
+                        code: 'COMMAND_DESCRIPTION_MISSING',
+                        severity: 'error',
+                        command,
+                        file: rel,
+                        message: 'Command is missing a description.',
+                    });
+                }
+            }
             if (hasFromJson && !hasJson) {
                 issues.push({
                     code: 'FROM_JSON_WITHOUT_JSON_OUTPUT',
@@ -153,7 +180,7 @@ function auditCommands({ rootDir, manifest, }) {
             if (!command?.description?.trim()) {
                 issues.push({
                     code: 'COMMAND_DESCRIPTION_MISSING',
-                    severity: 'warning',
+                    severity: isEnforcedDomain(id) ? 'error' : 'warning',
                     command: id,
                     message: 'Command is missing a description in the manifest.',
                 });
@@ -161,11 +188,22 @@ function auditCommands({ rootDir, manifest, }) {
             if (!hasJsonFlag(command?.flags) && isMachineRelevantCommand(id)) {
                 issues.push({
                     code: 'JSON_SUCCESS_OUTPUT_MISSING',
-                    severity: 'warning',
+                    severity: isEnforcedDomain(id) ? 'error' : 'warning',
                     command: id,
                     message: 'Machine-relevant command has no --json success-output flag. Keep human-only commands intentional.',
                 });
             }
+            // P8: a state flip is a verb (`archive` / `unarchive`), not a flag on its
+            // inverse. `spaces unarchive` follows the grammar; `tasks archive
+            // --unarchive` and `projects archive --unarchive` do not.
+            if (isEnforcedDomain(id) && hasFlag(command?.flags, 'unarchive')) {
+                issues.push({
+                    code: 'VERB_GRAMMAR_INVERSE_AS_FLAG',
+                    severity: 'warning',
+                    command: id,
+                    message: `Naming grammar: a state flip is its own verb (\`${id.replace(/:archive$/, ':unarchive').replace(/:/g, ' ')}\`), not --unarchive on the forward verb. Keep the flag as a deprecated alias when adding the verb.`,
+                });
+            }
         }
     }
     const errors = issues.filter((issue) => issue.severity === 'error').length;
@@ -190,6 +228,7 @@ function auditCommands({ rootDir, manifest, }) {
             domains: (0, usage_discovery_1.usageDomains)(manifestForCatalog).length,
             budgetErrors: usageBudgetIssues.length,
         },
+        namingGrammar: exports.NAMING_GRAMMAR,
         issues,
     };
 }
@@ -213,6 +252,27 @@ function commandIdFromRelativePath(relativePath) {
 function hasJsonFlag(flags) {
     return Boolean(flags && typeof flags === 'object' && 'json' in flags);
 }
+/**
+ * The domains an agent drives most. A missing description or `--json` output
+ * here is a build error (P10); elsewhere it stays a warning until that domain's
+ * offenders are fixed, so the gate can ratchet outward one domain at a time.
+ */
+exports.ENFORCED_HYGIENE_DOMAINS = ['tasks', 'spaces', 'projects'];
+function isEnforcedDomain(id) {
+    return exports.ENFORCED_HYGIENE_DOMAINS.some((domain) => id === domain || id.startsWith(`${domain}:`));
+}
+function hasFlag(flags, name) {
+    return Boolean(flags && typeof flags === 'object' && name in flags);
+}
+/**
+ * The verb grammar `commands --audit` checks, stated once so a reader of the
+ * report sees the rule and not only the findings it produced.
+ */
+exports.NAMING_GRAMMAR = [
+    'Verbs: list, show, create, update, delete, archive, unarchive, move. A reversible state flip is its own verb, never a flag on its inverse.',
+    'Scope: a list verb takes its parent scope as an optional filter flag; a verb that cannot work without a scope says so in its description.',
+    'Output: every command in tasks, spaces and projects takes --json and has a description (audit errors).',
+];
 function isMachineRelevantCommand(id) {
     return !(id === 'login' ||
         id === 'logout' ||

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

@@ -63,6 +63,11 @@ export declare function describeLastAutoStopLines(last: DedicatedRuntimePowerSum
 };
 /** The latest wake decision and who asked, as lines; empty when there is none. */
 export declare function describeLastWakeDecisionLines(wake: DedicatedRuntimePowerSummary['lastWakeDecision'], when?: WhenOptions): string[];
+/**
+ * The announced-but-not-yet-done stop, in the shared words (`describePendingStop`). Empty when the
+ * summary carries none, which is also what an older server sends: absent is not "no stop coming".
+ */
+export declare function describePendingStopLines(summary: Pick<DedicatedRuntimePowerSummary, 'leaseId' | 'pendingStop'>, when?: WhenOptions): string[];
 /** The lines of `power show`. */
 export declare function describePowerSummary(summary: DedicatedRuntimePowerSummary, when?: WhenOptions): string[];
 /** The lines of `power explain`; the fix is always last. */

package/dist/lib/dedicated-power.js

@@ -12,6 +12,7 @@ exports.describePrewarm = describePrewarm;
 exports.describePowerDecisionLines = describePowerDecisionLines;
 exports.describeLastAutoStopLines = describeLastAutoStopLines;
 exports.describeLastWakeDecisionLines = describeLastWakeDecisionLines;
+exports.describePendingStopLines = describePendingStopLines;
 exports.describePowerSummary = describePowerSummary;
 exports.describePowerExplanation = describePowerExplanation;
 exports.describeBudget = describeBudget;
@@ -50,7 +51,7 @@ async function setDedicatedPowerPolicy(leaseId, request, scope = {}) {
             return {
                 ok: false,
                 refusal: {
-                    error: String(body.error ?? 'on_demand is not available for this machine yet.'),
+                    error: String(body.error ?? 'On demand is not available for this machine yet.'),
                     code: 'ON_DEMAND_INELIGIBLE',
                     reason: reason,
                     detail: String(body.detail ?? copy?.detail ?? ''),
@@ -204,7 +205,10 @@ function describePrewarm(prewarm, when = {}) {
 function describePowerDecisionLines(decision) {
     const copy = (0, data_provider_1.describePowerReason)(decision.reason);
     const VERBS = { stay: 'Staying on', stop: 'Stopped', wake: 'Wake' };
-    const verb = VERBS[decision.question] ?? decision.question;
+    // `stop_scheduled` answers the stop question for a machine that is still running.
+    const verb = decision.reason === 'stop_scheduled'
+        ? 'Scheduled to stop'
+        : (VERBS[decision.question] ?? decision.question);
     return {
         // The headline is the human label only; the reason token lives in `--json` and `power explain`.
         // With no shared copy and no server detail there is no sentence, so the token is the last resort.
@@ -275,6 +279,28 @@ function describeLastWakeDecisionLines(wake, when = {}) {
         lines.push(`          ${wake.fix}`);
     return lines;
 }
+/** What the Keep awake offered by the stop notice means in the CLI: two hours. */
+const PENDING_STOP_KEEP_AWAKE_HOURS = 2;
+/**
+ * The announced-but-not-yet-done stop, in the shared words (`describePendingStop`). Empty when the
+ * summary carries none, which is also what an older server sends: absent is not "no stop coming".
+ */
+function describePendingStopLines(summary, when = {}) {
+    const pending = summary.pendingStop;
+    if (!pending)
+        return [];
+    const words = (0, data_provider_1.describePendingStop)(pending, {
+        nowMs: (when.now ?? new Date()).getTime(),
+        when: (0, format_1.formatWhen)(pending.stopsAt, when),
+        capWhen: pending.unreachableStopsAt ? (0, format_1.formatWhen)(pending.unreachableStopsAt, when) : null,
+        keepAwakeHours: PENDING_STOP_KEEP_AWAKE_HOURS,
+    });
+    const lines = [`Stop:     ${words.headline}`];
+    if (words.detail)
+        lines.push(`          ${words.detail}`);
+    lines.push(`          ${words.fix} skrr machines dedicated power keep-awake ${summary.leaseId} --for ${PENDING_STOP_KEEP_AWAKE_HOURS}h`);
+    return lines;
+}
 /** The lines of `power show`. */
 function describePowerSummary(summary, when = {}) {
     const { power } = summary;
@@ -303,6 +329,7 @@ function describePowerSummary(summary, when = {}) {
             lines.push('Decision: nothing to explain for this state');
         }
     }
+    lines.push(...describePendingStopLines(summary, when));
     lines.push(...describeLastAutoStopLines(summary.lastAutoStop, summary.decision?.detail, when).lines);
     lines.push(...describeLastWakeDecisionLines(summary.lastWakeDecision, when));
     if (summary.holders === null) {
@@ -347,6 +374,7 @@ function describePowerExplanation(summary, when = {}) {
         lines.push(`At:       ${(0, format_1.formatWhen)(d.at, when)}`);
     if (text.detail)
         lines.push(`Detail:   ${text.detail}`);
+    lines.push(...describePendingStopLines(summary, when));
     const stop = describeLastAutoStopLines(summary.lastAutoStop, d.detail, when);
     lines.push(...stop.lines);
     lines.push(...wakeLines);

package/dist/lib/dry-run-plans.d.ts

@@ -0,0 +1,50 @@
+type Row = Record<string, unknown>;
+export type ProjectAction = 'archive' | 'unarchive' | 'delete';
+export declare function planProjectChange(action: ProjectAction, project: Row, projectRef: string): {
+    object: string;
+    source: string;
+    ok: boolean;
+    action: ProjectAction;
+    project: {
+        id: unknown;
+        ref: {};
+        title: unknown;
+        archived: boolean;
+    };
+    changes: {
+        deletesProject: boolean;
+        detachedTasksEstimate: number | null;
+        reversible: boolean;
+        archived?: undefined;
+    } | {
+        archived: boolean;
+        reversible: boolean;
+        deletesProject?: undefined;
+        detachedTasksEstimate?: undefined;
+    };
+    errors: string[];
+    notes: string[];
+};
+export type BulkUpdateInput = {
+    id: string;
+    patch: Row;
+};
+export declare function planBulkUpdate(updates: BulkUpdateInput[], currentById: Record<string, Row | null | undefined>, failedReads?: Record<string, string>): {
+    object: string;
+    source: string;
+    ok: boolean;
+    requested: number;
+    wouldChange: number;
+    invalid: number;
+    results: {
+        id: string;
+        ok: boolean;
+        changes: Record<string, {
+            from: unknown;
+            to: unknown;
+        }>;
+        noop: boolean;
+        errors: string[];
+    }[];
+};
+export {};

package/dist/lib/dry-run-plans.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planProjectChange = planProjectChange;
+exports.planBulkUpdate = planBulkUpdate;
+/**
+ * Client-side validated previews for `--dry-run` (audit P5).
+ *
+ * Each plan is built from READS only (a GET of the current row) and answers three
+ * things a caller needs before a destructive call: would it be accepted, what
+ * would change, and what is the blast radius. It is a preview, not a promise:
+ * the real call re-validates server-side, and a concurrent writer can still
+ * change the outcome. Where the server has no validate-only path the plan says
+ * `source: 'client_preview'` so nobody mistakes it for one.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+function planProjectChange(action, project, projectRef) {
+    const archived = Boolean(project.archivedAt);
+    const taskCounts = (project.taskCounts ?? {});
+    const errors = [];
+    const notes = [];
+    if (action === 'archive' && archived)
+        notes.push('Already archived; archiving again is a no-op.');
+    if (action === 'unarchive' && !archived)
+        notes.push('Not archived; unarchiving is a no-op.');
+    return {
+        object: 'project_change_dry_run',
+        source: 'client_preview',
+        ok: errors.length === 0,
+        action,
+        project: {
+            id: project.id,
+            ref: project.identifier ?? projectRef,
+            title: project.title,
+            archived,
+        },
+        changes: action === 'delete'
+            ? {
+                deletesProject: true,
+                // Member tasks are detached, never deleted (invariant P3).
+                detachedTasksEstimate: taskCounts.total ?? null,
+                reversible: false,
+            }
+            : { archived: action === 'archive', reversible: true },
+        errors,
+        notes,
+    };
+}
+function planBulkUpdate(updates, currentById, failedReads = {}) {
+    const rows = updates.map(({ id, patch }) => {
+        const errors = [];
+        const current = currentById[id];
+        if (failedReads[id])
+            errors.push(`could not read task: ${failedReads[id]}`);
+        else if (!current)
+            errors.push('task not found');
+        const status = patch.status;
+        if (status !== undefined && !data_provider_1.TASK_STATUSES.includes(status)) {
+            errors.push(`status must be one of: ${data_provider_1.TASK_STATUSES.join(', ')}`);
+        }
+        const changes = {};
+        for (const [field, to] of Object.entries(patch)) {
+            if (to === undefined)
+                continue;
+            const from = current?.[field];
+            if (JSON.stringify(from) !== JSON.stringify(to))
+                changes[field] = { from, to };
+        }
+        return {
+            id,
+            ok: errors.length === 0,
+            changes,
+            noop: errors.length === 0 && Object.keys(changes).length === 0,
+            errors,
+        };
+    });
+    return {
+        object: 'task_bulk_update_dry_run',
+        source: 'client_preview',
+        ok: rows.every((r) => r.ok),
+        requested: rows.length,
+        wouldChange: rows.filter((r) => r.ok && !r.noop).length,
+        invalid: rows.filter((r) => !r.ok).length,
+        results: rows,
+    };
+}

package/dist/lib/json-output.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Storage-field stripping for `--json` output (audit P9).
+ *
+ * The API returns Mongo documents, so every row carries `_id` and `__v` beside
+ * the real `id`: 47 keys per task row, two of which are storage detail an agent
+ * pays tokens for and can mistake for the identifier (OSK-12205 was exactly
+ * that: a 24-hex `_id` passed where a task id was wanted).
+ *
+ * This runs at the CLI SERIALIZER only (`BaseCommand.log`), never in the API or
+ * the data layer, so no other consumer's payload changes. `--raw` (or
+ * `OVERSKY_CLI_RAW=1`) turns it off for the caller that does want them.
+ *
+ * Two rules, both conservative:
+ *   - `__v` is the Mongoose version key and is always dropped.
+ *   - `_id` is dropped only when the same object has a usable `id`. A row that
+ *     has ONLY `_id` (some legacy collections) keeps it: removing the sole
+ *     identifier would turn a cosmetic cleanup into data loss.
+ */
+type Json = unknown;
+/**
+ * Returns the SAME reference when nothing needed stripping, so a caller can tell
+ * "unchanged" apart from "rebuilt" and leave the original text alone.
+ */
+export declare function stripStorageFields(value: Json): Json;
+/**
+ * Apply {@link stripStorageFields} to one line of CLI output. Anything that is
+ * not a JSON object/array (prose, a bare string, malformed text) is returned
+ * untouched, as is JSON with nothing to strip, so existing formatting survives.
+ */
+export declare function stripStorageFieldsFromText(text: string): string;
+export {};