@skrr-ai/cli 0.1.8

package/dist/base-command.js

@@ -0,0 +1,1252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Flags = exports.BaseCommand = void 0;
+exports.assigneePayloadNeedsResolution = assigneePayloadNeedsResolution;
+exports.parseGlobalFlags = parseGlobalFlags;
+exports.withSubject = withSubject;
+exports.describeHarnessUnavailable = describeHarnessUnavailable;
+exports.describeAssigneeNotInSpace = describeAssigneeNotInSpace;
+exports.isRetryableFailure = isRetryableFailure;
+const core_1 = require("@oclif/core");
+Object.defineProperty(exports, "Flags", { enumerable: true, get: function () { return core_1.Flags; } });
+const data_provider_1 = require("@skrr-ai/data-provider");
+const auth_core_1 = require("@skrr-ai/auth-core");
+const assignee_resolver_1 = require("./lib/assignee-resolver");
+const task_ref_resolver_1 = require("./lib/task-ref-resolver");
+const space_resolver_1 = require("./lib/space-resolver");
+const projects_1 = require("./lib/projects");
+const config_1 = require("./lib/config");
+const keychain_1 = require("./lib/keychain");
+const outbox_1 = require("./lib/outbox");
+const node_adapter_1 = require("./lib/node-adapter");
+const migrate_1 = require("./lib/migrate");
+const auth_core_init_1 = require("./lib/auth-core-init");
+const credential_resolver_1 = require("./lib/credential-resolver");
+const daemonBroker_1 = require("./lib/daemonBroker");
+const refresh_1 = require("./lib/refresh");
+const auth_storage_1 = require("./lib/auth-storage");
+const update_check_1 = require("./lib/update-check");
+const web_url_1 = require("./lib/web-url");
+const delegated_cli_1 = require("./lib/delegated-cli");
+const tasks_1 = require("./lib/tasks");
+function assigneePayloadNeedsResolution(payload) {
+    const fields = [
+        ['assigneeUserIds', 'user'],
+        ['addAssigneeUserIds', 'user'],
+        ['removeAssigneeUserIds', 'user'],
+        ['assigneeAgentIds', 'agent'],
+        ['addAssigneeAgentIds', 'agent'],
+        ['removeAssigneeAgentIds', 'agent'],
+    ];
+    return fields.some(([field, kind]) => (Array.isArray(payload[field]) ? payload[field] : []).some((value) => {
+        const query = String(value).trim();
+        return Boolean(query && !(0, assignee_resolver_1.looksLikeRawId)(query, kind));
+    }));
+}
+/**
+ * Base class for every CLI command.
+ *
+ * Responsibilities:
+ * - Run the one-shot auth-out-of-config migration (Phase H).
+ * - Parse global flags (`--bare`, `--token`) from argv once and thread
+ *   them through the credential resolver and the HTTP adapter.
+ * - Resolve the active credential via the CredentialResolver chain —
+ *   flag → env → helper → keychain → file (Phase H.1). Returns the
+ *   source name for display in `skrr whoami` / `skrr doctor`.
+ * - Wire the Node HttpAdapter into @skrr-ai/data-provider so
+ *   `dataService.*` calls use our fetch-based transport with bearer
+ *   auth that matches what the resolver surfaced.
+ * - Provide `requireAuth()` for commands that need a signed-in user,
+ *   and `handleApiError()` for uniform error translation.
+ */
+class BaseCommand extends core_1.Command {
+    /** Add the owning agent's web detail link without overwriting resource URLs. */
+    withAgentContext(agentId, value) {
+        const agentUrl = (0, web_url_1.agentUrlFrom)(this.cliConfig.baseURL, { id: agentId });
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return { ...value, agentUrl };
+        }
+        return { value, agentUrl };
+    }
+    agentJson(agentId, value) {
+        return JSON.stringify(this.withAgentContext(agentId, value), null, 2);
+    }
+    printAgentUrl(agentId) {
+        this.log(`Agent URL: ${(0, web_url_1.agentUrlFrom)(this.cliConfig.baseURL, { id: agentId }) ?? '-'}`);
+    }
+    /**
+     * Global flags available on every subclass via oclif's `baseFlags`
+     * inheritance. Subclasses that declare their own `static flags` are
+     * automatically merged with these, so `skrr whoami --token ...` and
+     * `skrr whoami --bare` both parse cleanly.
+     *
+     * The flag values also surface on `this.parse()` output under the
+     * same keys — command `run()` methods can read them if they need
+     * to, but the common path is to rely on `this.resolvedCredential`
+     * and `this.bareMode` populated in `init()`.
+     */
+    static baseFlags = {
+        bare: core_1.Flags.boolean({
+            description: 'Bare mode — ignore keychain/file credential sources. Token must come from env or --token.',
+            default: false,
+        }),
+        token: core_1.Flags.string({
+            description: 'Bearer token for this invocation (debugging/impersonation). Overrides env and stored creds.',
+        }),
+        workspace: core_1.Flags.string({
+            description: 'Workspace ID for workspace-scoped requests (also sets X-Workspace-Id).',
+        }),
+    };
+    cliConfig;
+    /**
+     * Resolved credential for this process. Populated in `init()` and
+     * reused by the node-adapter so we don't re-resolve on every HTTP
+     * call. Commands that need the source (e.g. `whoami`) read directly
+     * from here.
+     */
+    resolvedCredential;
+    bareMode = false;
+    async init() {
+        await super.init();
+        // A daemon-stamped autonomous process is a separate principal, not a
+        // convenient place to inherit the user's CLI login. Resolve this before
+        // touching migration, Keychain/file auth, refresh, or daemon auto-broker
+        // state. The restricted session token (or a null credential when it is
+        // missing) is the only adapter authority exposed to the command.
+        let autonomousCredential = (0, credential_resolver_1.resolveTrustedAutonomousCredential)();
+        if ((0, delegated_cli_1.isDelegatedCliSession)()) {
+            try {
+                const delegatedCredential = await (0, delegated_cli_1.fetchDelegatedCliCredential)();
+                if (!delegatedCredential) {
+                    this.failWithCliError({
+                        message: 'Daemon delegated Sky credential is unavailable.',
+                        code: 'DELEGATED_CLI_CREDENTIAL_UNAVAILABLE',
+                        exit: 75,
+                        retryable: true,
+                    });
+                    return;
+                }
+                autonomousCredential = delegatedCredential;
+            }
+            catch (err) {
+                this.failWithCliError({
+                    message: `Daemon delegated Sky credential is unavailable: ${err.message}`,
+                    code: 'DELEGATED_CLI_CREDENTIAL_UNAVAILABLE',
+                    exit: 75,
+                    retryable: true,
+                });
+            }
+        }
+        if (autonomousCredential) {
+            // Parse for normal oclif flag validation, but intentionally ignore both
+            // `--token` and the user's configured credential store.
+            await this.parseBaseFlags();
+            this.bareMode = true;
+            const autonomousBaseUrl = (process.env.OVERSKY_SERVER_URL || '').trim();
+            if (!autonomousBaseUrl) {
+                this.failWithCliError({
+                    message: 'This autonomous Agent process has no trusted OVERSKY_SERVER_URL; refusing to read the user CLI configuration.',
+                    code: 'AUTONOMOUS_SESSION_SERVER_MISSING',
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+            // Build the minimum metadata-only config in memory. `loadConfig()` is
+            // deliberately not called: old cli-config.json files may still contain
+            // a legacy human token awaiting migration.
+            this.cliConfig = { baseURL: (0, config_1.canonicalizeKnownBaseURL)(autonomousBaseUrl) };
+            (0, data_provider_1.setBaseURL)(this.cliConfig.baseURL);
+            // Normalize the legacy/current workspace alias for every downstream
+            // transport (dataService, direct fetches, and WebSockets). In an Agent
+            // process only the daemon-owned session value is authoritative; ambient
+            // provider env and command flags must not move the session across tenants.
+            const sessionWorkspaceId = process.env.OVERSKY_SESSION_WORKSPACE_ID?.trim();
+            if (sessionWorkspaceId) {
+                process.env.OVERSKY_WORKSPACE_ID = sessionWorkspaceId;
+            }
+            else {
+                delete process.env.OVERSKY_WORKSPACE_ID;
+            }
+            this.resolvedCredential = autonomousCredential;
+            (0, node_adapter_1.setAdapterCredentialOverride)(this.resolvedCredential);
+            (0, data_provider_1.setHttpAdapter)((0, node_adapter_1.createNodeAdapter)());
+            return;
+        }
+        // One-shot migration: legacy token/refreshToken in cli-config.json
+        // → keychain (macOS) or cli-auth.json (elsewhere). Idempotent.
+        try {
+            (0, migrate_1.migrateAuthOutOfConfig)();
+        }
+        catch {
+            // Never block a command on migration failure; the resolver still
+            // reads the legacy fields via the file slot in the interim.
+        }
+        // Parse base flags early. oclif's parser merges `baseFlags` with the
+        // concrete subclass's `flags`, so calling this.parse() here gives
+        // us `bare` and `token` without each subclass having to re-plumb
+        // them.
+        const parsed = await this.parseBaseFlags();
+        this.bareMode = parsed.bare;
+        if (parsed.workspace)
+            process.env.OVERSKY_WORKSPACE_ID = parsed.workspace;
+        this.cliConfig = (0, config_1.loadConfig)();
+        (0, data_provider_1.setBaseURL)(this.cliConfig.baseURL);
+        // L12 envelope + L11 device identity init — must run BEFORE
+        // resolveCredential so the keychain/file backends can decrypt any
+        // wrapped tokens on read. Bounded internally so a stuck KEK probe
+        // can't wedge the CLI; on timeout we fall through to legacy
+        // plaintext and the resolver still finds the token.
+        await (0, auth_core_init_1.prefetchCliAuth)();
+        // Resolve credential via the Phase H.1 precedence chain. The
+        // adapter then cherry-picks the token for the Authorization
+        // header; we hand it a pre-resolved override so it doesn't
+        // re-walk the chain on every request.
+        this.resolvedCredential = await (0, credential_resolver_1.resolveCredential)({
+            flagToken: parsed.token,
+            bareMode: this.bareMode,
+            // Auth recovery/cleanup must stay reachable even when the persisted
+            // envelope cannot initialize. Login/pair replace local authority;
+            // logout must always be able to erase it.
+            allowUnreadableStoredCredential: this.id === 'login' || this.id === 'logout' || this.id === 'pair',
+        });
+        let ignoredStoredCredential = null;
+        if (!this.resolvedCredential.token && !this.bareMode && !parsed.token) {
+            ignoredStoredCredential = (0, auth_storage_1.readFromBackend)(this.cliConfig.baseURL);
+        }
+        // Daemon-as-broker auto-mint. When the resolver came up empty AND
+        // a local `oversky` daemon is already authenticated for this user,
+        // silently mint a sibling cli-scope refresh family via the daemon's
+        // loopback handoff. This is the "logged-in daemon ⇒ logged-in sky,
+        // no `skrr login` ever needed" path.
+        //
+        // Skip rules are encapsulated in `maybeAutoBroker` (bare mode,
+        // env-token override, `OVERSKY_SKIP_DAEMON_BROKER=1`, and the
+        // auth-self-managed command list: login/logout/pair/...). When the
+        // broker writes a fresh bundle to the keychain, every subsequent
+        // skrr command reads it through the normal resolver chain — no
+        // per-command broker round-trip.
+        //
+        // Fail-quiet: any broker failure leaves resolvedCredential null and
+        // the command's own `requireAuth()` will surface the "Not signed
+        // in" error a moment later. Mismatched baseURL (a real foot-gun the
+        // user might not notice) is the one exception — we print a one-
+        // line hint so they know how to fix it.
+        if (!this.resolvedCredential.token) {
+            const autoResult = await (0, daemonBroker_1.maybeAutoBroker)({
+                cliConfig: this.cliConfig,
+                bareMode: this.bareMode,
+                commandId: this.id,
+            });
+            if (autoResult.triggered && autoResult.outcome) {
+                if (autoResult.outcome.ok) {
+                    // Persist the cliId now so a sibling skrr process spawned
+                    // immediately after sees the same identity.
+                    if (autoResult.updatedConfig) {
+                        try {
+                            (0, config_1.saveConfig)(autoResult.updatedConfig);
+                            this.cliConfig = autoResult.updatedConfig;
+                        }
+                        catch {
+                            // Persistence failure is non-fatal — the broker mint
+                            // succeeded and the token is in the keychain; only the
+                            // cliId roundtrip is lost. Next process will mint a new
+                            // cliId, which the server treats as a fresh device.
+                        }
+                    }
+                    const accessToken = autoResult.outcome.accessToken;
+                    this.resolvedCredential = {
+                        token: accessToken,
+                        // Best-effort source label. `writeToBackend` routes to
+                        // Keychain on darwin, file elsewhere; we don't re-probe
+                        // here, but a follow-up `skrr whoami` reads the actual
+                        // backend so the label there is authoritative.
+                        source: 'keychain',
+                        kind: (0, auth_core_1.classifyTokenKind)(accessToken),
+                    };
+                }
+                else if (autoResult.outcome.reason === 'base_url_mismatch' &&
+                    autoResult.outcome.daemonServerUrl) {
+                    // The user is about to see "Not signed in" — give them the
+                    // exact fix. One stderr line so it doesn't pollute --json
+                    // consumers on stdout.
+                    process.stderr.write(`[sky] Local oversky daemon is logged in to ${autoResult.outcome.daemonServerUrl}, ` +
+                        `but skrr is configured for ${this.cliConfig.baseURL}. ` +
+                        `Run \`skrr login --base-url ${autoResult.outcome.daemonServerUrl}\` to use the daemon.\n`);
+                }
+            }
+        }
+        if (!this.resolvedCredential.token && ignoredStoredCredential) {
+            if (ignoredStoredCredential.originStatus === 'mismatch') {
+                process.stderr.write(`[sky] Ignoring stored credentials issued by ${ignoredStoredCredential.storedServerOrigin}; ` +
+                    `skrr is configured for ${this.cliConfig.baseURL}. Run \`skrr login --base-url ${this.cliConfig.baseURL}\` ` +
+                    `or switch back to the issuing server.\n`);
+            }
+            else if (ignoredStoredCredential.originStatus === 'unbound') {
+                process.stderr.write(`[sky] Ignoring legacy credentials that are not bound to a server. ` +
+                    `Run \`skrr login --base-url ${this.cliConfig.baseURL}\` once to bind a fresh session.\n`);
+            }
+        }
+        if (this.resolvedCredential.token) {
+            const fresh = await (0, refresh_1.ensureFreshCliCredential)({
+                credential: this.resolvedCredential,
+                bareMode: this.bareMode,
+            });
+            if (fresh.credential.token) {
+                this.resolvedCredential = fresh.credential;
+            }
+        }
+        (0, node_adapter_1.setAdapterCredentialOverride)(this.resolvedCredential);
+        (0, data_provider_1.setHttpAdapter)((0, node_adapter_1.createNodeAdapter)());
+        // Non-blocking "a newer skrr is available" advisory. Decides from a ~4h
+        // on-disk cache (zero added latency) and refreshes in the background.
+        // Writes at most one line to stderr, never stdout, so --json consumers
+        // are unaffected; self-suppresses in bundled/non-TTY/opted-out contexts.
+        // Wrapped so an advisory can never break the command it precedes.
+        try {
+            (0, update_check_1.maybeWarnOutdatedCli)({
+                currentVersion: this.config.version,
+                baseURL: this.cliConfig.baseURL,
+            });
+        }
+        catch {
+            /* advisory is strictly best-effort */
+        }
+    }
+    /**
+     * Read only the two global base flags. A narrow parser — oclif's
+     * `this.parse()` would work but require threading the subclass
+     * constructor, which forces every caller path through a generic
+     * dance. Walking argv ourselves for these two boolean/string flags
+     * is simpler and sidesteps oclif's "unknown flag" strictness on
+     * subclass invocations during init().
+     */
+    async parseBaseFlags() {
+        return parseGlobalFlags(this.argv);
+    }
+    /**
+     * Opt out of automatic `--space` name resolution for this command.
+     *
+     * Nothing needs it today. It exists so a future command whose `--space`
+     * means something other than "one existing space" can say so declaratively
+     * instead of the resolution being quietly wrong.
+     */
+    static resolveSpaceFlag = true;
+    /**
+     * Turn a space reference into a space id, or fail the command.
+     *
+     * Raw ids short-circuit before any network call, so every script and agent
+     * prompt that passes UUIDs today keeps its exact previous behavior and its
+     * exact previous request count. Only a value that would otherwise have
+     * silently matched nothing reaches the search.
+     */
+    async resolveSpaceReference(value) {
+        const query = value.trim();
+        // Only canonical ids short-circuit. Human-readable refs are accepted by
+        // some read endpoints, but space-scoped mutation endpoints require the
+        // UUID, so refs go through the same exact-match resolution as titles.
+        if (!query || (0, space_resolver_1.looksLikeCanonicalSpaceId)(query))
+            return query;
+        const normalizedQuery = (0, space_resolver_1.normalizeSpaceRef)(query);
+        const load = async (includeArchived) => {
+            let response;
+            try {
+                response = await data_provider_1.dataService.listSpaces({ q: normalizedQuery, limit: 50, includeArchived });
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+            const rows = (response?.data ?? []);
+            return rows.map(space_resolver_1.spaceRefFrom).filter((s) => s !== null);
+        };
+        let outcome = (0, space_resolver_1.resolveSpaceRef)(normalizedQuery, await load(false));
+        // Only pay for the second request when the first found nothing — it exists
+        // to tell "you named an archived space" apart from "that name matches
+        // nothing", which are different problems with different fixes.
+        if (!outcome.ok && outcome.code === 'NOT_FOUND') {
+            const archived = await load(true);
+            if (archived.length > 0)
+                outcome = (0, space_resolver_1.resolveSpaceRef)(normalizedQuery, archived);
+        }
+        if (outcome.ok)
+            return outcome.space.id;
+        this.failWithCliError({
+            message: (0, space_resolver_1.formatSpaceResolutionFailure)(outcome, this.config.bin),
+            code: space_resolver_1.SPACE_CLI_ERROR_CODE[outcome.code],
+            exit: 2,
+            retryable: false,
+            details: {
+                suggestion: `Run \`${this.config.bin} spaces list --q "${normalizedQuery}"\` to see what matches.`,
+                context: { query: normalizedQuery, code: outcome.code, candidates: outcome.candidates },
+            },
+        });
+    }
+    async resolveProjectReference(value, spaceFlag, opts = {}) {
+        const spaceRequired = opts.spaceRequired !== false;
+        const { projectRef, spaceRef } = (0, projects_1.splitQualifiedProjectRef)(value, spaceFlag);
+        if (spaceRef) {
+            return { projectRef, spaceId: await this.resolveSpaceReference(spaceRef) };
+        }
+        // A bare ref (`OSK-P-12`) is unique only inside its space, so nothing can
+        // resolve it without one — not the space-scoped routes, not
+        // `/tasks?projectId=`, and not the by-id lookup below. One sentence for
+        // both contracts.
+        if (!(0, projects_1.looksLikeCanonicalProjectId)(projectRef)) {
+            this.failWithCliError({
+                message: 'Name the space: pass --space, or use the qualified ref `<space>/<project>` that `projects list` prints.',
+                code: 'PROJECT_REF_REQUIRES_SPACE',
+                exit: 2,
+                retryable: false,
+            });
+        }
+        if (!spaceRequired) {
+            return { projectRef };
+        }
+        // A canonical id is globally unique, but a space-scoped route still needs
+        // the owning space in its URL. Ask the server which space that is instead
+        // of making the caller know it: `skrr projects update <uuid> --title …`
+        // refused to run without `--space` while the docs promised the uuid
+        // "works alone", and five project updates in one batch died on exactly
+        // that. One request, paid only on this path.
+        return { projectRef, spaceId: await this.lookupProjectSpace(projectRef) };
+    }
+    /** Resolve a canonical project id to its owning space via `GET /api/projects/:id`. */
+    async lookupProjectSpace(projectId) {
+        try {
+            const project = await projects_1.projectApi.get(projectId);
+            return project.spaceId;
+        }
+        catch (err) {
+            if (err?.code === 'PROJECT_LOOKUP_UNSUPPORTED') {
+                // A server that predates the lookup. The caller's old remedy still
+                // works there, so the error names it rather than a server upgrade only.
+                this.failWithCliError({
+                    message: 'This skrr server cannot look a project up by id — name the space: pass --space, or use the qualified ref `<space>/<project>` that `projects list` prints.',
+                    code: 'PROJECT_REF_REQUIRES_SPACE',
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+            this.handleApiError(err, { subject: `project ${projectId}` });
+        }
+    }
+    /**
+     * Turn a task reference into something the API can look up, or fail the
+     * command.
+     *
+     * UUIDs and `OSK-2423` refs short-circuit before any network call — the
+     * server resolves the latter itself — so existing callers keep their
+     * behavior and their request count. Only a title reaches the search.
+     */
+    async resolveTaskReference(value) {
+        const direct = (0, task_ref_resolver_1.directTaskRef)(value);
+        if (direct)
+            return direct;
+        const query = value.trim();
+        if (!query)
+            return query;
+        let response;
+        try {
+            response = await data_provider_1.dataService.listTasks({ q: query, limit: 50 });
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const rows = (response?.data ?? []);
+        const candidates = rows.map(task_ref_resolver_1.taskRefFrom).filter((t) => t !== null);
+        const outcome = (0, task_ref_resolver_1.resolveTaskRef)(query, candidates);
+        if (outcome.ok)
+            return outcome.task.id;
+        this.failWithCliError({
+            message: (0, task_ref_resolver_1.formatTaskRefFailure)(outcome, this.config.bin),
+            code: task_ref_resolver_1.TASK_REF_CLI_ERROR_CODE[outcome.code],
+            exit: 2,
+            retryable: false,
+            details: {
+                suggestion: `Run \`${this.config.bin} tasks list --q "${query}"\` to see what matches.`,
+                context: { query, code: outcome.code, candidates: outcome.candidates },
+            },
+        });
+    }
+    /**
+     * Parse flags, then resolve any `--space` reference to an id.
+     *
+     * Done here rather than in each command because the failure this fixes was
+     * uniform across all 35 `--space` consumers and silent in every one of them:
+     * a name reached the API as a literal, matched no space, and came back as an
+     * empty result rather than an error. Fixing it per-command would leave the
+     * 36th command to reintroduce it. Commands whose `--space` is not a single
+     * space reference set `static resolveSpaceFlag = false`.
+     *
+     * `--space` is repeatable on `spaces reorder`, so both shapes are handled.
+     */
+    async parse(options, argv) {
+        const parsed = await super.parse(options, argv);
+        const ctor = this.constructor;
+        const flags = parsed.flags;
+        const raw = flags?.space;
+        if (ctor.resolveSpaceFlag !== false && raw !== undefined) {
+            if (typeof raw === 'string') {
+                flags.space = await this.resolveSpaceReference(raw);
+            }
+            else if (Array.isArray(raw)) {
+                const resolved = [];
+                for (const entry of raw) {
+                    resolved.push(typeof entry === 'string' ? await this.resolveSpaceReference(entry) : entry);
+                }
+                flags.space = resolved;
+            }
+        }
+        return parsed;
+    }
+    /**
+     * Yes/no confirmation for a destructive verb.
+     *
+     * Here rather than per-command: `logout` and `revoke-daemon` each carried a
+     * private copy, and the second one's comment said "reused pattern from
+     * `revoke-daemon`" — a copy that knows it is a copy. Three more were about to
+     * land with `engines forget` / `leases release` / `leases action destroy`.
+     *
+     * Defaults to NO on a bare Enter, which is the load-bearing half: every caller
+     * is about to do something it cannot undo, and an accidental ⏎ must not be the
+     * thing that does it.
+     *
+     * Answers false with no prompt when stdin is not a TTY. A piped or CI
+     * invocation cannot answer, and blocking forever on a read that will never
+     * arrive is worse than refusing — those callers pass `--yes`, which states the
+     * intent in the command line where it can be reviewed.
+     */
+    confirm(prompt) {
+        if (!process.stdin.isTTY) {
+            this.log('Refusing without a confirmation: stdin is not a terminal. Pass --yes to proceed.');
+            return Promise.resolve(false);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const readline = require('readline');
+        return new Promise((resolve) => {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(prompt, (answer) => {
+                rl.close();
+                const normalized = answer.trim().toLowerCase();
+                resolve(normalized === 'y' || normalized === 'yes');
+            });
+        });
+    }
+    /** Abort the command with a helpful message if the user isn't signed in. */
+    requireAuth() {
+        if (!this.resolvedCredential?.token) {
+            this.failWithCliError({
+                message: `Not signed in. Run \`${this.config.bin} login\` first.`,
+                code: 'NOT_SIGNED_IN',
+                exit: 2,
+                retryable: false,
+            });
+        }
+    }
+    /**
+     * Resolve the authenticated user's id via `GET /api/user`.
+     *
+     * Used by commands that author resources scoped to "the current user" —
+     * e.g. a `space_subscriber` trigger's `subscriberUserId`, which the web
+     * Schedule Board fills from the signed-in user. Exits with the standard
+     * friendly error on any API failure, so callers can `await` it directly.
+     */
+    async resolveCurrentUserId() {
+        let user;
+        try {
+            user = await data_provider_1.dataService.getUser();
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        // `handleApiError` returns `never`, so TypeScript treats `user` as
+        // definitely-assigned here — no optional chaining needed. The guard stays
+        // as defense against a malformed (id-less) success response.
+        if (!user.id) {
+            this.error('Could not determine the current user id from the API.', { exit: 1 });
+        }
+        return user.id;
+    }
+    /**
+     * Decide who owns a task this invocation is creating, when the caller did
+     * not say.
+     *
+     * Replaces `resolveDefaultTaskAgent()`, which asked the server which agents
+     * this account can edit and treated the answer as the caller's identity.
+     * That probe had two failure modes and no success mode worth keeping: with
+     * several agents it raised AGENT_CONTEXT_AMBIGUOUS and the command exited
+     * without recording the work at all; with exactly one it silently assigned
+     * an agent that had nothing to do with this session. Identity is now read
+     * only from what the session actually proves (`OVERSKY_SESSION_AGENT_ID`),
+     * and the decision itself lives in `@skrr-ai/data-provider` beside the
+     * copies the REST route and the MCP tools use.
+     *
+     * The calling user's id costs a request, so it is fetched only on the branch
+     * that can use it — a task whose declared executor is human.
+     */
+    async defaultTaskAssignees(payload) {
+        const claim = {
+            hasExplicitAssignee: (0, tasks_1.hasExplicitTaskAssignee)(payload),
+            executionMode: payload.executionMode,
+        };
+        const callerUserId = (0, data_provider_1.taskAssigneeDefaultNeedsCallerUser)(claim)
+            ? await this.resolveCurrentUserId()
+            : undefined;
+        return (0, tasks_1.applyTaskAssigneeDefaults)(payload, { callerUserId });
+    }
+    /**
+     * Load a space's assignable members (people + agents).
+     *
+     * Shared by every command that accepts an assignee reference. A failure is
+     * fatal rather than a silent fall-back to a global directory search: the
+     * server only accepts assignees who are members of the space
+     * (`ASSIGNEE_NOT_IN_SPACE`), so widening the lookup could only ever produce
+     * a request guaranteed to be rejected — or, worse, resolve a typo to a
+     * stranger the caller never intended to name.
+     */
+    async loadSpaceMembers(spaceId) {
+        let response;
+        try {
+            response = await data_provider_1.dataService.getResourcePermissions(data_provider_1.ResourceType.SPACE, spaceId);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const principals = (response.principals ?? []);
+        return (0, assignee_resolver_1.membersFromPrincipals)(principals);
+    }
+    /**
+     * Turn free-text assignee references ("frank", "frank@example.com", "me",
+     * or a raw id) into ids, failing the command if ANY of them can't be pinned
+     * to exactly one member.
+     *
+     * All-or-nothing on purpose: resolving 2 of 3 names and writing those two
+     * leaves the caller unsure what landed, and a retry of the same command
+     * would re-apply the ones that already succeeded.
+     */
+    async resolveAssignees(queries, kind, spaceId) {
+        const outcome = await (0, assignee_resolver_1.resolveAssigneeReferences)({
+            queries: queries ?? [],
+            kind,
+            spaceId,
+            loadMembers: (id) => this.loadSpaceMembers(id),
+            resolveSelfId: () => this.resolveCurrentUserId(),
+        });
+        if (outcome.failures.length > 0) {
+            const CLI_ERROR_CODE = {
+                AMBIGUOUS: 'ASSIGNEE_AMBIGUOUS',
+                NO_SPACE: 'ASSIGNEE_NO_SPACE_CONTEXT',
+                NOT_FOUND: 'ASSIGNEE_NOT_FOUND',
+            };
+            this.failWithCliError({
+                message: outcome.failures
+                    .map((f) => (0, assignee_resolver_1.formatResolutionFailure)(f, this.config.bin))
+                    .join('\n\n'),
+                code: CLI_ERROR_CODE[outcome.failures[0].code],
+                exit: 2,
+                retryable: false,
+                details: {
+                    suggestion: `Run \`${this.config.bin} spaces members list <space-id>\` to see who can be assigned.`,
+                    context: { failures: outcome.failures },
+                },
+            });
+        }
+        return outcome;
+    }
+    /**
+     * Rewrite every assignee field on a create/update payload in place, turning
+     * names / emails / "me" into ids.
+     *
+     * Applied to `assigneeUserIds`, `addAssigneeUserIds`,
+     * `removeAssigneeUserIds` and their agent counterparts, so `tasks create`
+     * and `tasks update` accept the same references `tasks assign` does.
+     *
+     * Strictly additive: `resolveAssigneeReferences` passes raw ids straight
+     * through and only fetches space membership when some entry actually needs
+     * resolving, so a payload that already carries ObjectIds/UUIDs — every
+     * existing script and agent prompt — behaves identically and issues no
+     * extra request.
+     */
+    async resolveAssigneesInPayload(payload, opts = {}) {
+        const FIELDS = [
+            ['assigneeUserIds', 'user'],
+            ['addAssigneeUserIds', 'user'],
+            ['removeAssigneeUserIds', 'user'],
+            ['assigneeAgentIds', 'agent'],
+            ['addAssigneeAgentIds', 'agent'],
+            ['removeAssigneeAgentIds', 'agent'],
+        ];
+        const present = FIELDS.filter(([field]) => Array.isArray(payload[field]));
+        if (present.length === 0)
+            return;
+        // Everything already an id ⇒ nothing to resolve, so we must not fetch the
+        // task or the space just to discover that. Bail before touching either.
+        const needsResolution = assigneePayloadNeedsResolution(payload);
+        if (!needsResolution)
+            return;
+        const spaceId = typeof payload.spaceId === 'string' && payload.spaceId
+            ? payload.spaceId
+            : await opts.resolveSpaceId?.();
+        for (const [field, kind] of present) {
+            const queries = payload[field].map((v) => String(v));
+            const { ids } = await this.resolveAssignees(queries, kind, spaceId);
+            payload[field] = ids;
+        }
+    }
+    /**
+     * Describe where the active token came from. Used by `skrr whoami`.
+     * Returns `null` when not signed in.
+     */
+    credentialSourceLabel() {
+        if (!this.resolvedCredential?.token)
+            return null;
+        return (0, credential_resolver_1.formatCredentialSource)(this.resolvedCredential.source);
+    }
+    async catch(err) {
+        if (isOclifExitError(err)) {
+            return super.catch(err);
+        }
+        if (this.wantsJsonOutput()) {
+            const exit = err.exitCode ?? err.oclif?.exit ?? 1;
+            process.exitCode = exit;
+            this.log(JSON.stringify({
+                ok: false,
+                error: {
+                    code: err.code ?? parseCliErrorCode(err),
+                    message: err.message || String(err),
+                    retryable: err.retryable ?? false,
+                    command: this.id ?? null,
+                    server: this.cliConfig?.baseURL ?? null,
+                    ...(detailsFromCaughtError(err) ? { details: detailsFromCaughtError(err) } : {}),
+                },
+            }, null, 2));
+            return;
+        }
+        return super.catch(err);
+    }
+    error(input, options = {}) {
+        if (options.exit === false) {
+            return super.error(input, options);
+        }
+        if (this.wantsJsonOutput()) {
+            const message = input instanceof Error ? input.message : input;
+            const code = options.code ??
+                (input instanceof Error && typeof input.code === 'string'
+                    ? input.code
+                    : 'CLI_ERROR');
+            this.writeJsonCliError({
+                message,
+                code,
+                exit: typeof options.exit === 'number' ? options.exit : 1,
+                retryable: false,
+                details: detailsFromPrettyError(options),
+            });
+        }
+        return super.error(input, options);
+    }
+    /**
+     * Translate a data-provider error into a friendly CLI error and exit.
+     *
+     * Always returns `never` — either throws via `this.error()` or re-throws
+     * the original. Call from a `catch` block:
+     *
+     *   try { ... } catch (err) { this.handleApiError(err); }
+     *
+     * `subject` names the resource the failing call was about — e.g.
+     * `Task 68ab…`. Server messages are written from the SERVER's point of
+     * view ("Task already has an active run") and so never carry the id the
+     * caller passed. That is fine for one interactive invocation and useless
+     * for a burst: N concurrent `skrr` processes share one stderr, so an
+     * anonymous line cannot be attributed to any of them (OSK-2076). The
+     * subject is folded into the message, so the human line and the `--json`
+     * envelope carry the same identifying text.
+     */
+    handleApiError(err, { subject } = {}) {
+        const say = (message) => withSubject(subject, message);
+        if (err instanceof Error) {
+            const e = err;
+            const body = parseErrorBody(e.body);
+            const bodyCode = stringProp(body, 'code') || stringProp(body, 'errorType');
+            const bodyMessage = stringProp(body, 'message') || stringProp(body, 'error');
+            if (bodyCode === 'AGENT_RUNTIME_UNAVAILABLE') {
+                // A specific agent's runtime is offline — not a platform outage, even
+                // though the server returns 503. Intercept before the 503→outage
+                // heuristic so we neither claim a service outage nor promise a
+                // fruitless retry (OSK-4965).
+                this.failWithCliError({
+                    message: say(describeHarnessUnavailable(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
+                // give it the same remedy the by-name path already carries (OSK-4864).
+                this.failWithCliError({
+                    message: say(describeAssigneeNotInSpace(bodyMessage, this.config.bin)),
+                    code: bodyCode,
+                    status: e.status,
+                    exit: 2,
+                    retryable: false,
+                    details: body ?? undefined,
+                });
+            }
+            else if (e.status === 401) {
+                // ADD-CLI6 — bare mode follows the `EX_TEMPFAIL` (75) convention
+                // for needs-reauth, matching the daemon's `bare-mode.ts:117`.
+                // CI scripts key off 75 to distinguish "re-authenticate" from
+                // "bad command" (exit 2); without this carve-out they had to
+                // string-match the stderr message, which was fragile.
+                const exitCode = this.bareMode ? 75 : 2;
+                // An `osk_ci_*` token is a DAEMON BOOTSTRAP credential — only
+                // `POST /api/daemons/token` accepts it. Telling its holder to run
+                // `login` sends a CI job to do the one thing it cannot, and hides the
+                // real mistake (dogfood OSK-4693). Name the credential instead.
+                const presentedCiToken = Boolean(this.resolvedCredential?.token?.startsWith('osk_ci_'));
+                this.failWithCliError({
+                    message: say(presentedCiToken
+                        ? `Authentication failed: this is an \`osk_ci_*\` token, which only bootstraps a ` +
+                            `daemon (\`OVERSKY_TOKEN=<token> oversky start\`). ${this.config.bin} commands do ` +
+                            `not accept it — sign in with \`${this.config.bin} login\` instead.`
+                        : `Authentication failed. Run \`${this.config.bin} login\` to sign in again.`),
+                    code: bodyCode || 'AUTHENTICATION_FAILED',
+                    status: e.status,
+                    exit: exitCode,
+                    retryable: true,
+                });
+            }
+            else if (e.status === 403) {
+                this.failWithCliError({
+                    message: say(bodyMessage || 'Forbidden: your account does not have access to this resource.'),
+                    code: bodyCode || 'FORBIDDEN',
+                    status: e.status,
+                    exit: 3,
+                    retryable: false,
+                });
+            }
+            else if (e.status === 404) {
+                this.failWithCliError({
+                    message: say(bodyMessage || 'Not found.'),
+                    code: bodyCode || 'NOT_FOUND',
+                    status: e.status,
+                    exit: 4,
+                    retryable: false,
+                });
+            }
+            else if (e.code === 'ECONNREFUSED' ||
+                e.message.includes('ECONNREFUSED') ||
+                e.message.includes('fetch failed')) {
+                this.failWithCliError({
+                    message: say(`Could not connect to ${this.cliConfig.baseURL}. Is the API server running?`),
+                    code: e.code || 'NETWORK_ERROR',
+                    exit: 5,
+                    retryable: true,
+                });
+            }
+            else if ((0, outbox_1.isOutageFailure)(e)) {
+                // A gateway/unavailable status is an OUTAGE, and saying so is the whole
+                // point. During the OSK-2806 incident these surfaced as bare
+                // `HTTP_503`s scattered across unrelated commands, so the failure read
+                // as "each of these features is broken" rather than "the control plane
+                // is down and nothing you did is at fault". Naming it once, with the
+                // same code everywhere, is what lets a user (or a script) tell a
+                // transient outage from a real refusal.
+                // Persist the observation before failing. A user in an outage is
+                // looking at several of these and trying to work out whether the
+                // problem is theirs; recording it is what lets the NEXT command, and
+                // `skrr doctor`, say "the platform was failing seconds ago" instead of
+                // every invocation looking like an isolated bug.
+                // The gate is `isOutageFailure`, NOT `isRetryableWrite`. The latter is
+                // the QUEUE decision and covers 401/408/425/429/500 — statuses where
+                // this prose would be false. Sending the two questions through one
+                // predicate is what made a single route's 500 read as a platform
+                // outage.
+                this.noteControlPlaneOutage(e.status);
+                this.failWithCliError({
+                    message: say(`${this.cliConfig.baseURL} is not serving requests right now` +
+                        `${e.status ? ` (HTTP ${e.status})` : ''}. ` +
+                        'This is a service outage, not a problem with your account or this command. ' +
+                        'Nothing was changed — retry once it recovers.'),
+                    code: 'CONTROL_PLANE_UNAVAILABLE',
+                    status: e.status,
+                    exit: 5,
+                    retryable: true,
+                    details: body ?? undefined,
+                });
+            }
+            else if (typeof e.status === 'number' && e.status >= 500) {
+                // The server ANSWERED and then failed. Report only that, because that
+                // is all one response supports. In particular do not claim the platform
+                // is down (it answered), do not absolve this command (a 500 is usually
+                // this very route), and do not claim nothing changed (unknowable — and
+                // false for routes that 500 after committing, e.g. `spaces move`
+                // returning `space_room_sync_failed` once the move is already durable).
+                //
+                // The server's own message is preserved rather than overwritten. In
+                // production `redactServerErrorResponses` generalizes it to "An
+                // unexpected error occurred." and attaches a `requestId`, which is then
+                // the only thing that makes the failure diagnosable — so it is promoted
+                // into the human line instead of living only in the `--json` envelope.
+                const requestId = stringProp(body, 'requestId');
+                this.failWithCliError({
+                    message: say(`${this.cliConfig.baseURL} returned HTTP ${e.status} for this request` +
+                        `${bodyMessage ? `: ${bodyMessage}` : '.'} ` +
+                        'The request reached the API and failed there, so this is a server-side fault on ' +
+                        'this operation rather than an outage. Whether the change was applied is not ' +
+                        'reported — check before retrying.' +
+                        (requestId ? ` Request id ${requestId} — quote it when reporting this.` : '')),
+                    code: bodyCode || `HTTP_${e.status}`,
+                    status: e.status,
+                    exit: 1,
+                    retryable: isRetryableFailure(e.status, body),
+                    details: body ?? undefined,
+                });
+            }
+            else {
+                this.failWithCliError({
+                    message: say(bodyMessage || e.message),
+                    code: bodyCode || e.code || (e.status ? `HTTP_${e.status}` : 'CLI_ERROR'),
+                    status: e.status,
+                    exit: 1,
+                    retryable: isRetryableFailure(e.status, body),
+                    details: body ?? undefined,
+                });
+            }
+        }
+        this.failWithCliError({
+            message: say(String(err)),
+            code: 'CLI_ERROR',
+            exit: 1,
+            retryable: false,
+        });
+    }
+    /**
+     * Record that the control plane is failing, for the incident surface.
+     *
+     * Best-effort and never throws: an unwritable config dir must not turn a
+     * service outage into a second, more confusing failure.
+     */
+    noteControlPlaneOutage(status) {
+        try {
+            (0, outbox_1.recordIncident)({ baseURL: this.cliConfig.baseURL, status }, (0, keychain_1.getActiveProfile)());
+        }
+        catch {
+            /* the surface is a convenience; never let it mask the real error */
+        }
+    }
+    /**
+     * Durably queue a write the control plane could not accept, then fail.
+     *
+     * For commands where the USER AUTHORED THE CONTENT — a completion summary, a
+     * comment body, a new Space — losing it to a 503 costs the thinking, not just
+     * a retry. Those commands call this instead of `handleApiError`, and the
+     * content lands in the outbox where `skrr outbox retry` can replay it.
+     *
+     * Two invariants the caller must honour, both load-bearing:
+     *
+     *   - `idempotencyKey` must be STABLE for the logical write. Replay without
+     *     one risks a double-create, which is strictly worse than the lost write
+     *     this exists to prevent. A command that cannot mint a stable key must
+     *     not call this.
+     *   - Queuing is NOT success. This still exits non-zero (`QUEUED_FOR_RETRY`),
+     *     because the write has not happened. A script that read it as done would
+     *     be wrong.
+     *
+     * Anything that is not an outage — every 4xx — falls through to the normal
+     * error path untouched, because replaying a refusal is just a slower refusal.
+     */
+    queueWriteOrFail(err, write) {
+        // The durable-write path, and the one this whole step is about. It must
+        // read the WIDE predicate: a 401 here is precisely the case where an
+        // authored payload was being dropped, because `outbox` only ever queued on
+        // `status >= 500`.
+        if (!(0, outbox_1.isRetryableWrite)(err)) {
+            this.handleApiError(err);
+        }
+        const e = err;
+        // ...but the incident note stays on the NARROW one, so an expired token
+        // does not get reported as the control plane being down.
+        if ((0, outbox_1.isOutageFailure)(err))
+            this.noteControlPlaneOutage(e.status);
+        const workspaceId = process.env.OVERSKY_SESSION_WORKSPACE_ID?.trim() || process.env.OVERSKY_WORKSPACE_ID?.trim();
+        let queuedId;
+        try {
+            const entry = (0, outbox_1.enqueueWrite)({
+                idempotencyKey: write.idempotencyKey,
+                command: write.command,
+                summary: write.summary,
+                method: write.method,
+                url: write.url,
+                body: write.body,
+                ...(workspaceId ? { workspaceId } : {}),
+                reason: {
+                    ...(e.status !== undefined ? { status: e.status } : {}),
+                    ...(e.code ? { code: e.code } : {}),
+                    message: e.message || 'control plane unavailable',
+                },
+            }, (0, keychain_1.getActiveProfile)());
+            queuedId = entry.id;
+        }
+        catch {
+            // The queue itself failed. Say so plainly rather than claiming a
+            // durability guarantee we did not deliver.
+            this.failWithCliError({
+                message: `${this.cliConfig.baseURL} could not accept this write and it could NOT be queued ` +
+                    'locally. Your content was not saved anywhere — copy it before retrying.',
+                code: 'CONTROL_PLANE_UNAVAILABLE',
+                status: e.status,
+                exit: 5,
+                retryable: true,
+            });
+        }
+        // Same discipline as `handleApiError`: only a real outage gets outage
+        // wording, and only an outage lets us say nothing was written. A 500 is
+        // queued too, but the server ran our request before failing, so what it did
+        // with it is unknown — and a replay is safe on the idempotency key rather
+        // than on an assumption that nothing landed.
+        const outage = (0, outbox_1.isOutageFailure)(err);
+        const statusSuffix = e.status ? ` (HTTP ${e.status})` : '';
+        const lead = outage
+            ? `${this.cliConfig.baseURL} is not serving requests right now${statusSuffix}. ` +
+                `Your ${write.summary} was queued locally as ${queuedId} — nothing has been written yet.`
+            : `${this.cliConfig.baseURL} did not accept this write${statusSuffix}. ` +
+                `Your ${write.summary} was queued locally as ${queuedId}; whether the server applied ` +
+                'any of it is not reported, so verify before replaying.';
+        this.failWithCliError({
+            message: `${lead} ` +
+                `Replay it with \`${this.config.bin} outbox retry\` (it carries an idempotency key, so a ` +
+                `replay will not double-apply), or discard it with \`${this.config.bin} outbox drop ${queuedId}\`.`,
+            code: 'QUEUED_FOR_RETRY',
+            status: e.status,
+            exit: 5,
+            retryable: true,
+            details: { outboxId: queuedId, idempotencyKey: write.idempotencyKey },
+        });
+    }
+    failWithCliError({ message, code, status, exit, retryable, details, }) {
+        if (this.wantsJsonOutput()) {
+            this.writeJsonCliError({ message, code, status, exit, retryable, details });
+        }
+        // Human path. Deliberately stderr-only: stdout is the SUCCESS channel, so
+        // `id=$(skrr tasks start "$x")` and `sky ... | jq` are never fed error
+        // prose, and 0 bytes of stdout on failure is the correct outcome. The
+        // status channel already works — `this.error` throws a CLIError carrying
+        // `oclif.exit`, so `handle()` exits with `exit` (never 0).
+        //
+        // What was missing is the DIAGNOSTIC channel's machine-readable half:
+        // `code` arrived here and was dropped, so only `--json` callers could
+        // tell `task_already_running` (benign, someone else won the race) from a
+        // terminal refusal or a 500. oclif's pretty-printer renders a `code` on a
+        // CLIError as its own `Code: <code>` line, so passing it through gives
+        // every skrr command a greppable failure line at no other cost.
+        this.error(message, { exit, code });
+    }
+    writeJsonCliError({ message, code, status, exit, retryable, details, }) {
+        this.log(JSON.stringify({
+            ok: false,
+            error: {
+                code,
+                message,
+                ...(status ? { status } : {}),
+                retryable,
+                command: this.id ?? null,
+                server: this.cliConfig?.baseURL ?? null,
+                ...(details ? { details } : {}),
+            },
+        }, null, 2));
+        this.exit(exit);
+    }
+    wantsJsonOutput() {
+        return (this.argv.includes('--json') ||
+            process.env.SKY_JSON === '1' ||
+            process.env.OVERSKY_CLI_JSON === '1');
+    }
+}
+exports.BaseCommand = BaseCommand;
+function parseGlobalFlags(argv) {
+    let bare = false;
+    let token;
+    let workspace;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--bare') {
+            bare = true;
+            continue;
+        }
+        if (arg === '--token') {
+            const value = argv[i + 1];
+            if (typeof value === 'string' && value.length > 0) {
+                token = value;
+                i++;
+            }
+            continue;
+        }
+        if (arg?.startsWith('--token=')) {
+            const v = arg.slice('--token='.length);
+            if (v.length > 0)
+                token = v;
+            continue;
+        }
+        if (arg === '--workspace') {
+            const value = argv[i + 1];
+            if (typeof value === 'string' && value.length > 0) {
+                workspace = value;
+                i++;
+            }
+            continue;
+        }
+        if (arg?.startsWith('--workspace=')) {
+            const v = arg.slice('--workspace='.length);
+            if (v.length > 0)
+                workspace = v;
+        }
+    }
+    return { bare, token, workspace };
+}
+function parseErrorBody(body) {
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stringProp(obj, key) {
+    const value = obj?.[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+/**
+ * Prefix a failure message with the resource it is about.
+ *
+ * Server messages are phrased from the server's point of view and never echo
+ * the id the caller passed ("Task already has an active run; start rejected").
+ * One interactive invocation doesn't need it — the operator just typed the id.
+ * A burst does: N concurrent `skrr` processes write to the SAME stderr, so an
+ * unattributed line names none of them (OSK-2076).
+ *
+ * Idempotent-ish: if the server already named the subject, don't stutter.
+ *
+ * Exported for tests.
+ */
+function withSubject(subject, message) {
+    const trimmed = subject?.trim();
+    if (!trimmed)
+        return message;
+    if (message.includes(trimmed))
+        return message;
+    return `${trimmed}: ${message}`;
+}
+/**
+ * Frame a typed `AGENT_RUNTIME_UNAVAILABLE` failure as what it is — a named
+ * agent's runtime being offline — rather than a control-plane outage (OSK-4965).
+ *
+ * The server returns this at HTTP 503 with a typed `cause` (which names the
+ * runtime and why it is unreachable) and a `remedy`. The generic 503 handler
+ * would otherwise report "service outage, retry once it recovers, nothing was
+ * changed" — all three false here: the platform is serving, an identical retry
+ * cannot revive an offline runtime, and the dispatch did change state (the task
+ * parks blocked). Lead with the server's `cause`, then its `remedy` if present,
+ * falling back to the CLI's own runtime commands.
+ *
+ * Exported for tests.
+ */
+function describeHarnessUnavailable(body, bin = 'skrr') {
+    const cause = stringProp(body, 'cause');
+    const remedy = stringProp(body, 'remedy');
+    const lead = cause ||
+        "The agent's runtime is unavailable — it is offline or unregistered, so the run " +
+            'could not be dispatched.';
+    const fix = remedy ||
+        `Inspect it with \`${bin} machines hosted status\`, or re-attach the agent's harness with ` +
+            `\`${bin} agents attach-harness\`.`;
+    return `${lead}\n  → ${fix}`;
+}
+/**
+ * Enrich the server's `ASSIGNEE_NOT_IN_SPACE` rejection with the same
+ * copy-pasteable remedy the by-name resolution failure already gives (OSK-4864).
+ *
+ * When a caller names an assignee that is not a member of the space, the CLI's
+ * own name-resolution path (`ASSIGNEE_NOT_FOUND`) says "add one with
+ * `skrr spaces members add`". The server's id-based rejection reaches
+ * `handleApiError` as a bare sentence that interpolates ids and offers no next
+ * step, so the two paths for the same mistake read very differently. Append the
+ * remedy unless the server already named it.
+ *
+ * Exported for tests.
+ */
+function describeAssigneeNotInSpace(serverMessage, bin = 'skrr') {
+    const base = serverMessage?.trim() || 'That assignee is not a member of this space.';
+    if (base.includes(`${bin} spaces members add`))
+        return base;
+    return (`${base}\n  → add it to the space with \`${bin} spaces members add\`, ` +
+        'or assign someone already in it.');
+}
+/**
+ * Server-declared TERMINAL refusals: a state conflict the caller must resolve
+ * by doing something DIFFERENT, never by repeating the identical request.
+ *
+ * `skrr tasks move --status done` on a checked-out task with no approved
+ * TASK_OUTPUT returns 409 `task_output_required`. 409 used to be in the
+ * transient set below, so the JSON envelope said `retryable: true` — and
+ * `daemon/CLAUDE.md` tells daemon-hosted agents to retry retryable errors, so
+ * they looped on a refusal that can never succeed on retry. The refusal names
+ * the supported path (`POST /:taskId/complete` / `skrr tasks complete`); the
+ * envelope has to agree that the ONLY way forward is that path.
+ */
+const TERMINAL_ERROR_CODES = new Set(['task_output_required', 'task_output_not_approved']);
+/**
+ * Whether an automated retry of the IDENTICAL request could plausibly succeed.
+ *
+ * Precedence:
+ *   1. An explicit `retryable` boolean in the error body — the server knows
+ *      more about its own failure than any status heuristic does.
+ *   2. A known terminal refusal code → never retryable.
+ *   3. Status heuristic, restricted to genuinely TRANSIENT conditions: request
+ *      timeout, too-early, rate limit, server error. 409 Conflict is
+ *      deliberately absent — by definition it means the request conflicts with
+ *      the resource's current state, which an identical retry cannot change.
+ *
+ * Exported for tests.
+ */
+function isRetryableFailure(status, body) {
+    const declared = body?.retryable;
+    if (typeof declared === 'boolean')
+        return declared;
+    const code = stringProp(body, 'code') || stringProp(body, 'errorType');
+    if (code && TERMINAL_ERROR_CODES.has(code))
+        return false;
+    return status === 408 || status === 425 || status === 429 || !!(status && status >= 500);
+}
+function detailsFromPrettyError(options) {
+    const details = {};
+    for (const key of ['suggestions', 'ref', 'showHelp']) {
+        if (options[key] !== undefined)
+            details[key] = options[key];
+    }
+    return Object.keys(details).length > 0 ? details : undefined;
+}
+function detailsFromCaughtError(err) {
+    const details = {};
+    if (err.suggestions !== undefined)
+        details.suggestions = err.suggestions;
+    if (err.oclif?.exit !== undefined)
+        details.exit = err.oclif.exit;
+    return Object.keys(details).length > 0 ? details : undefined;
+}
+function parseCliErrorCode(err) {
+    if (err.name && err.name !== 'Error') {
+        return err.name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+    }
+    return 'CLI_PARSE_ERROR';
+}
+function isOclifExitError(err) {
+    return err.name === 'ExitError' || err.message.startsWith('EEXIT:');
+}