comisai 1.0.34 → 1.0.36

package/node_modules/@comis/cli/dist/commands/agent.js

@@ -1,12 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Agent management commands: list, create, configure, delete, models.
+ * Agent management commands: list, create, configure, delete, models, set-oauth-profile.
  *
- * Provides `comis agent [list|create|configure|delete|models]` subcommands
- * for managing agent configurations via the daemon RPC interface.
+ * Provides `comis agent [list|create|configure|delete|models|set-oauth-profile]`
+ * subcommands for managing agent configurations via the daemon RPC interface.
  *
  * @module
  */
+import { validateProfileId } from "@comis/core";
 import { ensureWorkspace, resolveWorkspaceDir } from "@comis/agent";
 import chalk from "chalk";
 import { withClient } from "../client/rpc-client.js";
@@ -127,6 +128,48 @@ export function registerAgentCommand(program) {
             process.exit(1);
         }
     });
+    // agent set-oauth-profile <agentId> <profileId>
+    //
+    // Pin a per-agent OAuth profile preference. The provider is derived from
+    // the profile-id's `<provider>:<identity>` portion — there is NO separate
+    // --provider flag (single-source-of-truth). Validation runs client-side
+    // via validateProfileId; the daemon's agents.update handler additionally
+    // rejects unknown profile IDs via OAuthCredentialStore.has(). Daemon
+    // errors substring-matching "not found" are surfaced verbatim with
+    // exit 1; format violations exit 2.
+    agent
+        .command("set-oauth-profile <agentId> <profileId>")
+        .description("Set the OAuth profile preference for an agent (provider derived from profile-id)")
+        .action(async (agentId, profileId) => {
+        const validated = validateProfileId(profileId);
+        if (!validated.ok) {
+            error(`Invalid profile ID: ${validated.error.message}. Expected format: <provider>:<identity>.`);
+            process.exit(2);
+        }
+        const { provider } = validated.value;
+        try {
+            await withSpinner(`Setting OAuth profile for "${agentId}"...`, () => withClient(async (client) => {
+                return await client.call("agents.update", {
+                    agentId,
+                    config: { oauthProfiles: { [provider]: profileId } },
+                });
+            }));
+            success(`Set agent ${agentId} oauthProfiles[${provider}] = ${profileId}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // The daemon's PROFILE_NOT_FOUND surfaces with "not found" in the
+            // message. Substring-match to surface as exit 1 with the daemon's
+            // actionable wording (which already names the profile and references
+            // `comis auth list`).
+            if (msg.includes("not found")) {
+                error(msg);
+                process.exit(1);
+            }
+            error(`Failed to set oauth profile: ${msg}`);
+            process.exit(1);
+        }
+    });
     // agent delete <name>
     agent
         .command("delete <name>")

package/node_modules/@comis/cli/dist/commands/auth.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `comis auth` CLI command tree.
+ *
+ * Four subcommands operating directly against the OAuthCredentialStorePort
+ * (no daemon RPC — store is the IPC primitive between CLI and daemon, with
+ * the daemon picking up changes via the chokidar watcher):
+ *
+ * - `comis auth login`   — interactive OAuth login (browser + manual paste).
+ *                          Accepts `--profile <id>` to override the storage
+ *                          key; the user-supplied id replaces the
+ *                          JWT-derived `<provider>:<email>` while the
+ *                          identity fields on the persisted profile remain
+ *                          JWT-derived. Provider portion of `--profile` must
+ *                          equal `--provider` or the command exits 2.
+ * - `comis auth list`    — list stored profiles in a 5-column table; supports
+ *                          `--provider <id>` filter — pure client-side string
+ *                          match, no validation against pi-ai's known list.
+ * - `comis auth logout`  — remove a profile by ID
+ * - `comis auth status`  — per-provider summary (count + nextExpiry); supports
+ *                          `--provider <id>` filter with the same semantics
+ *                          as `auth list`.
+ *
+ * Only `--provider openai-codex` is supported for `auth login` today. Other
+ * providers ship later. The `--provider` filter on `list` / `status` is
+ * unconstrained because the filter is purely cosmetic.
+ *
+ * All commands run in the CLI process; the local OAuth callback server
+ * (pi-ai's hardcoded localhost:1455) binds to the user's interactive
+ * machine — daemon may be on a remote host.
+ *
+ * @module
+ */
+import type { Command } from "commander";
+/**
+ * Register the `auth` command group on the program.
+ */
+export declare function registerAuthCommand(program: Command): void;

package/node_modules/@comis/cli/dist/commands/auth.js

@@ -0,0 +1,433 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `comis auth` CLI command tree.
+ *
+ * Four subcommands operating directly against the OAuthCredentialStorePort
+ * (no daemon RPC — store is the IPC primitive between CLI and daemon, with
+ * the daemon picking up changes via the chokidar watcher):
+ *
+ * - `comis auth login`   — interactive OAuth login (browser + manual paste).
+ *                          Accepts `--profile <id>` to override the storage
+ *                          key; the user-supplied id replaces the
+ *                          JWT-derived `<provider>:<email>` while the
+ *                          identity fields on the persisted profile remain
+ *                          JWT-derived. Provider portion of `--profile` must
+ *                          equal `--provider` or the command exits 2.
+ * - `comis auth list`    — list stored profiles in a 5-column table; supports
+ *                          `--provider <id>` filter — pure client-side string
+ *                          match, no validation against pi-ai's known list.
+ * - `comis auth logout`  — remove a profile by ID
+ * - `comis auth status`  — per-provider summary (count + nextExpiry); supports
+ *                          `--provider <id>` filter with the same semantics
+ *                          as `auth list`.
+ *
+ * Only `--provider openai-codex` is supported for `auth login` today. Other
+ * providers ship later. The `--provider` filter on `list` / `status` is
+ * unconstrained because the filter is purely cosmetic.
+ *
+ * All commands run in the CLI process; the local OAuth callback server
+ * (pi-ai's hardcoded localhost:1455) binds to the user's interactive
+ * machine — daemon may be on a remote host.
+ *
+ * @module
+ */
+import { homedir } from "node:os";
+import open from "open";
+import { loadConfigFile, validateConfig, safePath, validateProfileId, } from "@comis/core";
+import { selectOAuthCredentialStore, loginOpenAICodexOAuth, isRemoteEnvironment, redactEmailForLog, } from "@comis/agent";
+import { createLogger } from "@comis/infra";
+import { error, info, success } from "../output/format.js";
+import { renderTable } from "../output/table.js";
+import { formatRelativeExpiry } from "../output/relative-time.js";
+import { createClackAdapter } from "../wizard/clack-adapter.js";
+const PROVIDER_OPENAI_CODEX = "openai-codex";
+const ACTIVE_THRESHOLD_MS = 5 * 60_000; // 5 minutes — match status logic
+// ---------------------------------------------------------------------------
+// OAuthError discrimination helpers.
+//
+// `exitOnOAuthError` translates a structured OAuthError into stderr output +
+// exit code 1; `isOAuthError` is a defensive type guard so the catch blocks
+// can route OAuthError values through the structured handler while letting
+// generic JS errors fall through to the existing `Failed to ${verb}: ${msg}`
+// pattern.
+//
+// Per CLAUDE.md "Logging" — CLI uses `format.ts` (stderr/stdout) NOT Pino;
+// this is the documented exception. The literal "Re-authenticate with: comis
+// auth login --provider <providerId>" line is the acceptance literal the
+// integration test grep-asserts (test/integration/oauth-refresh-token-reused.test.ts).
+// ---------------------------------------------------------------------------
+/**
+ * Translate a structured OAuthError into stderr output + exit code 1.
+ *
+ * When `errorKind === "refresh_token_reused"`, the CLI prints the canonical
+ * re-login command with exit code 1. Other errorKinds (invalid_grant, etc.)
+ * get tailored messages; unknown OAuthErrors fall through to the generic
+ * shape.
+ *
+ * Returns `never` — always exits the process.
+ */
+function exitOnOAuthError(err) {
+    if (err.errorKind === "refresh_token_reused") {
+        error("Refresh token was reused. The OpenAI account has been auto-locked for security.");
+        info(`Re-authenticate with: comis auth login --provider ${err.providerId}`);
+        process.exit(1);
+    }
+    if (err.errorKind === "invalid_grant") {
+        const profileSlug = err.profileId ?? "unknown";
+        error(`Refresh token was rejected by OpenAI (invalid_grant) for profile "${profileSlug}".`);
+        info(`Re-authenticate with: comis auth login --provider ${err.providerId}`);
+        process.exit(1);
+    }
+    error(`OAuthError (${err.code}): ${err.message}`);
+    if (err.hint)
+        info(err.hint);
+    process.exit(1);
+}
+/**
+ * Type guard: detect an OAuthError shape on a caught unknown value.
+ * Distinguishes the structured error from generic JS errors so the CLI can
+ * route through `exitOnOAuthError` (above). Match against the 5 known
+ * `OAuthError.code` values to avoid false positives on third-party errors
+ * that happen to carry `code`/`providerId`/`message` keys.
+ */
+function isOAuthError(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v.code === "string" &&
+        typeof v.message === "string" &&
+        typeof v.providerId === "string" &&
+        [
+            "NO_PROVIDER",
+            "NO_CREDENTIALS",
+            "REFRESH_FAILED",
+            "STORE_FAILED",
+            "PROFILE_NOT_FOUND",
+        ].includes(v.code));
+}
+// Module-scoped logger. The CLI process runs short-lived commands; one
+// logger instance is shared across all 4 subcommands. Per CLAUDE.md, every
+// log call also sets `submodule: "auth-cli"` for filterability.
+const logger = createLogger({ name: "auth-cli" });
+// ---------------------------------------------------------------------------
+// Internal: open the OAuth credential store using the same selector the
+// daemon uses. Reads appConfig.oauth.storage from the user's config file
+// with safe defaults when no config exists (e.g., daemon never set up).
+//
+// Both loadConfigFile and validateConfig are Result-typed (per @comis/core),
+// so this function never throws — config errors fall through to the file
+// adapter default, which is the safe operator-friendly behavior for a
+// freshly-installed CLI.
+// ---------------------------------------------------------------------------
+function openOAuthStoreFromConfig() {
+    const dataDir = safePath(homedir(), ".comis");
+    // eslint-disable-next-line no-restricted-syntax -- CLI bootstrap before SecretManager
+    const envPaths = process.env.COMIS_CONFIG_PATHS;
+    const configPath = envPaths?.split(",")[0] ?? safePath(homedir(), ".comis", "config.yaml");
+    const loadResult = loadConfigFile(configPath);
+    if (!loadResult.ok) {
+        // No config file → default to file storage (the file adapter creates
+        // ~/.comis/auth-profiles.json on first set).
+        return selectOAuthCredentialStore({ storage: "file", dataDir });
+    }
+    const validateResult = validateConfig(loadResult.value);
+    if (!validateResult.ok) {
+        // Invalid config — fail fast with a clear hint pointing at the daemon
+        // bootstrap message that surfaces the same Zod issue.
+        error(`Failed to load config: ${validateResult.error.message}. ` +
+            "Hint: run `comis configure` or fix the YAML at " +
+            `${configPath} before retrying.`);
+        process.exit(1);
+    }
+    const storage = validateResult.value.oauth.storage;
+    if (storage === "encrypted") {
+        // Encrypted-mode bootstrap from CLI requires SECRETS_MASTER_KEY + the
+        // secrets DB. The CLI does NOT spin up the SecretsCrypto/secretsDb
+        // here — surface a fail-fast error pointing at the daemon's
+        // encrypted-mode path. Operators with encrypted storage must run
+        // `comis auth login` from the daemon host (where SECRETS_MASTER_KEY
+        // is exported), or switch to file storage.
+        error("OAuth storage mode is 'encrypted' but the CLI cannot bootstrap the encrypted store. " +
+            "Hint: Either (1) export SECRETS_MASTER_KEY in this shell and rerun, or (2) change " +
+            "appConfig.oauth.storage to 'file' for `comis auth login` flows.");
+        process.exit(1);
+    }
+    return selectOAuthCredentialStore({ storage: "file", dataDir });
+}
+// ---------------------------------------------------------------------------
+// Internal: build a status string from an absolute expiry timestamp.
+// ---------------------------------------------------------------------------
+function profileStatus(expiresAtMs) {
+    return expiresAtMs - Date.now() > ACTIVE_THRESHOLD_MS ? "active" : "expired";
+}
+// ---------------------------------------------------------------------------
+// Public boundary
+// ---------------------------------------------------------------------------
+/**
+ * Register the `auth` command group on the program.
+ */
+export function registerAuthCommand(program) {
+    const auth = program
+        .command("auth")
+        .description("OAuth authentication management");
+    // -------------------------------------------------------------------------
+    // login
+    // -------------------------------------------------------------------------
+    auth
+        .command("login")
+        .description("Log in to an OAuth-enabled provider")
+        .requiredOption("--provider <id>", "OAuth provider id (must be 'openai-codex')")
+        .option("--remote", "Force remote/headless mode (no browser)")
+        .option("--local", "Force local/desktop mode (try to open browser)")
+        .option("--profile <id>", "Override the auto-derived profile ID (provider portion must match --provider)")
+        .option("--method <method>", "Login method: 'browser' (default) or 'device-code' (SSH/no-clipboard)")
+        .action(async (opts) => {
+        // Provider must be openai-codex.
+        if (opts.provider !== PROVIDER_OPENAI_CODEX) {
+            error("--provider must be 'openai-codex' (other providers ship later)");
+            process.exit(2);
+        }
+        // Validate --profile override when supplied.
+        // The user-supplied id becomes the storage key; the provider portion
+        // MUST match --provider (defense against accidentally writing an
+        // anthropic profile under an openai-codex login flow).
+        if (opts.profile) {
+            const validated = validateProfileId(opts.profile);
+            if (!validated.ok) {
+                error(`Invalid --profile value: ${validated.error.message}. Expected format: <provider>:<identity>.`);
+                process.exit(2);
+            }
+            if (validated.value.provider !== opts.provider) {
+                error(`--profile provider portion ("${validated.value.provider}") must match --provider value ("${opts.provider}") — provider mismatch.`);
+                process.exit(2);
+            }
+        }
+        // Validate --method flag.
+        // Defense-in-depth: any value other than "device-code" silently
+        // maps to "browser" — the CLI never crashes on an unknown method,
+        // it falls back to the safe default.
+        const method = opts.method === "device-code" ? "device-code" : "browser";
+        if (method === "device-code" && opts.provider !== PROVIDER_OPENAI_CODEX) {
+            error("--method device-code is only supported with --provider openai-codex " +
+                "(other providers do not support device-code today)");
+            process.exit(2);
+        }
+        try {
+            const store = openOAuthStoreFromConfig();
+            const isRemote = isRemoteEnvironment({
+                env: process.env,
+                force: opts.remote ? "remote" : opts.local ? "local" : undefined,
+            });
+            const prompter = createClackAdapter();
+            const result = await loginOpenAICodexOAuth({
+                prompter,
+                isRemote,
+                openUrl: open,
+                logger,
+                method,
+            });
+            if (!result.ok) {
+                error(result.error.message);
+                if (result.error.hint)
+                    info(result.error.hint);
+                process.exit(1);
+            }
+            const v = result.value;
+            // When --profile is set, override the storage key.
+            // email/accountId/displayName remain JWT-derived (preserved on the
+            // profile object) so the operator can still identify which upstream
+            // account backs the alias.
+            const finalProfileId = opts.profile ?? v.profileId;
+            const profile = {
+                provider: PROVIDER_OPENAI_CODEX,
+                profileId: finalProfileId,
+                access: v.access,
+                refresh: v.refresh,
+                expires: v.expires,
+                accountId: v.accountId,
+                email: v.email,
+                displayName: v.displayName,
+                version: 1,
+            };
+            const writeResult = await store.set(finalProfileId, profile);
+            if (!writeResult.ok) {
+                error(`Failed to persist OAuth profile: ${writeResult.error.message}`);
+                process.exit(1);
+            }
+            // Silent overwrite policy; INFO-log records every login write.
+            logger.info({
+                provider: PROVIDER_OPENAI_CODEX,
+                profileId: finalProfileId,
+                identity: redactEmailForLog(v.email) ?? `id-${v.accountId ?? "<unknown>"}`,
+                action: "login",
+                submodule: "auth-cli",
+            }, "OAuth profile written by CLI");
+            success(`Logged in as ${v.email ?? v.displayName ?? v.profileId} (profile: ${finalProfileId})`);
+        }
+        catch (err) {
+            // Structured OAuthError values route through `exitOnOAuthError`
+            // for the canonical re-login hint; generic errors fall through to
+            // the existing pattern.
+            if (isOAuthError(err)) {
+                exitOnOAuthError(err);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            error(`Failed to log in: ${msg}`);
+            process.exit(1);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // list
+    // -------------------------------------------------------------------------
+    auth
+        .command("list")
+        .description("List stored OAuth profiles")
+        .option("--provider <id>", "Filter to one provider")
+        .action(async (opts) => {
+        try {
+            const store = openOAuthStoreFromConfig();
+            const listResult = await store.list();
+            if (!listResult.ok) {
+                error(`Failed to list OAuth profiles: ${listResult.error.message}`);
+                process.exit(1);
+            }
+            const profiles = listResult.value;
+            // Client-side string-match filter; we explicitly opt OUT of
+            // validating the provider value against pi-ai's known list (the
+            // filter is purely an in-memory display sieve).
+            const filtered = opts.provider
+                ? profiles.filter((p) => p.provider === opts.provider)
+                : profiles;
+            if (filtered.length === 0) {
+                if (opts.provider) {
+                    info(`No OAuth profiles stored for provider "${opts.provider}".`);
+                }
+                else {
+                    info("No OAuth profiles stored.");
+                }
+                return;
+            }
+            renderTable(["Provider", "ProfileId", "Identity", "ExpiresIn", "Status"], filtered.map((p) => [
+                p.provider,
+                p.profileId,
+                p.email ?? p.profileId.split(":")[1] ?? "—",
+                formatRelativeExpiry(p.expires),
+                profileStatus(p.expires),
+            ]));
+        }
+        catch (err) {
+            // Structured OAuthError gets the re-login hint.
+            if (isOAuthError(err)) {
+                exitOnOAuthError(err);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            error(`Failed to list profiles: ${msg}`);
+            process.exit(1);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // logout
+    // -------------------------------------------------------------------------
+    auth
+        .command("logout")
+        .description("Remove a stored OAuth profile")
+        .requiredOption("--profile <id>", "Profile ID to remove (e.g., openai-codex:user@example.com)")
+        .action(async (opts) => {
+        try {
+            const store = openOAuthStoreFromConfig();
+            const has = await store.has(opts.profile);
+            if (!has.ok) {
+                error(`Failed to check profile existence: ${has.error.message}`);
+                process.exit(1);
+            }
+            if (!has.value) {
+                error(`profile ${opts.profile} not found`);
+                process.exit(1);
+            }
+            const delResult = await store.delete(opts.profile);
+            if (!delResult.ok) {
+                error(`Failed to remove profile: ${delResult.error.message}`);
+                process.exit(1);
+            }
+            logger.info({
+                profileId: opts.profile,
+                action: "logout",
+                submodule: "auth-cli",
+            }, "OAuth profile removed by CLI");
+            success(`Logged out of ${opts.profile}`);
+        }
+        catch (err) {
+            // Structured OAuthError gets the re-login hint.
+            if (isOAuthError(err)) {
+                exitOnOAuthError(err);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            error(`Failed to log out: ${msg}`);
+            process.exit(1);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // status
+    // -------------------------------------------------------------------------
+    auth
+        .command("status")
+        .description("Show per-provider OAuth status")
+        .option("--provider <id>", "Filter to one provider")
+        .action(async (opts) => {
+        try {
+            const store = openOAuthStoreFromConfig();
+            const listResult = await store.list();
+            if (!listResult.ok) {
+                error(`Failed to read OAuth status: ${listResult.error.message}`);
+                process.exit(1);
+            }
+            const profiles = listResult.value;
+            if (profiles.length === 0) {
+                // Empty store — even with --provider filter, the operator's
+                // intended diagnostic is the same: nothing here, optionally for
+                // the named provider.
+                if (opts.provider) {
+                    info(`No OAuth profiles stored for provider "${opts.provider}".`);
+                }
+                else {
+                    info("No OAuth profiles stored.");
+                }
+                return;
+            }
+            // Group by provider.
+            const byProvider = new Map();
+            for (const p of profiles) {
+                const arr = byProvider.get(p.provider) ?? [];
+                arr.push(p);
+                byProvider.set(p.provider, arr);
+            }
+            // Empty filter case: store has profiles, but none for the requested
+            // provider. Print provider-specific empty-state and exit 0 (the
+            // standard `return` here, since a missing provider in a populated
+            // store is not an error).
+            if (opts.provider && !byProvider.has(opts.provider)) {
+                info(`No OAuth profiles stored for provider "${opts.provider}".`);
+                return;
+            }
+            for (const [provider, group] of byProvider) {
+                // Skip non-matching groups when filter is set.
+                if (opts.provider && provider !== opts.provider)
+                    continue;
+                info(`${provider} (${group.length} profile${group.length !== 1 ? "s" : ""})`);
+                for (const p of group) {
+                    const identity = p.email ?? p.profileId.split(":")[1] ?? "—";
+                    info(`  ${p.profileId} — expires in ${formatRelativeExpiry(p.expires)} (${profileStatus(p.expires)}) — identity: ${identity}`);
+                }
+            }
+        }
+        catch (err) {
+            // Structured OAuthError gets the re-login hint.
+            if (isOAuthError(err)) {
+                exitOnOAuthError(err);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            error(`Failed to check OAuth status: ${msg}`);
+            process.exit(1);
+        }
+    });
+}

package/node_modules/@comis/cli/dist/commands/doctor.d.ts

@@ -12,8 +12,11 @@ import type { Command } from "commander";
  * Register the `doctor` command on the program.
  *
  * Provides:
- * - `comis doctor` -- run 5 health check categories
+ * - `comis doctor` -- run 6 health check categories (config, daemon, gateway,
+ *   channel, workspace, OAuth)
  * - `comis doctor --repair` -- auto-fix repairable issues
+ * - `comis doctor --refresh-test` -- opt-in refresh probe per profile.
+ *   WARNING: rotates the refresh token at OpenAI.
  *
  * @param program - The root Commander program
  */

package/node_modules/@comis/cli/dist/commands/doctor.js

@@ -20,16 +20,18 @@ import { daemonHealthCheck } from "../doctor/checks/daemon-health.js";
 import { gatewayHealthCheck } from "../doctor/checks/gateway-health.js";
 import { channelHealthCheck } from "../doctor/checks/channel-health.js";
 import { workspaceHealthCheck } from "../doctor/checks/workspace-health.js";
+import { oauthHealthCheck } from "../doctor/checks/oauth-health.js";
 import { repairConfig } from "../doctor/repairs/repair-config.js";
 import { repairDaemon } from "../doctor/repairs/repair-daemon.js";
 import { repairWorkspace } from "../doctor/repairs/repair-workspace.js";
-/** All doctor checks in execution order (5 categories). */
+/** All doctor checks in execution order (6 categories). */
 const ALL_CHECKS = [
     configHealthCheck,
     daemonHealthCheck,
     gatewayHealthCheck,
     channelHealthCheck,
     workspaceHealthCheck,
+    oauthHealthCheck,
 ];
 /**
  * Resolve default config paths from COMIS_CONFIG_PATHS env var or standard locations.
@@ -99,21 +101,30 @@ function buildDoctorContext(configPaths) {
  * Register the `doctor` command on the program.
  *
  * Provides:
- * - `comis doctor` -- run 5 health check categories
+ * - `comis doctor` -- run 6 health check categories (config, daemon, gateway,
+ *   channel, workspace, OAuth)
  * - `comis doctor --repair` -- auto-fix repairable issues
+ * - `comis doctor --refresh-test` -- opt-in refresh probe per profile.
+ *   WARNING: rotates the refresh token at OpenAI.
  *
  * @param program - The root Commander program
  */
 export function registerDoctorCommand(program) {
     program
         .command("doctor")
-        .description("Diagnose configuration, daemon, gateway, channel, and workspace health")
+        .description("Diagnose configuration, daemon, gateway, channel, workspace, and OAuth health")
         .option("--repair", "Auto-fix repairable issues")
         .option("-c, --config <paths...>", "Config file paths to check")
         .option("--format <format>", 'Output format: "table" or "json"', "table")
+        .option("--refresh-test", "Run a real OAuth refresh against the provider per profile. " +
+        "WARNING: rotates the refresh token at OpenAI; the stored token will " +
+        "be stale after this check. Default: OFF (opt-in).")
         .action(async (options) => {
         const configPaths = options.config ?? resolveDefaultConfigPaths();
-        const context = buildDoctorContext(configPaths);
+        const context = {
+            ...buildDoctorContext(configPaths),
+            refreshTest: options.refreshTest,
+        };
         const result = await withSpinner("Running diagnostics...", () => runDoctorChecks(ALL_CHECKS, context));
         // Render results
         if (options.format === "json") {
@@ -156,7 +167,11 @@ export function registerDoctorCommand(program) {
             }
             // Re-run diagnostics after repairs
             info("Re-running diagnostics...");
-            const rerunResult = await withSpinner("Verifying repairs...", () => runDoctorChecks(ALL_CHECKS, buildDoctorContext(configPaths)));
+            const rerunContext = {
+                ...buildDoctorContext(configPaths),
+                refreshTest: options.refreshTest,
+            };
+            const rerunResult = await withSpinner("Verifying repairs...", () => runDoctorChecks(ALL_CHECKS, rerunContext));
             if (options.format === "json") {
                 renderDoctorJson(rerunResult);
             }

package/node_modules/@comis/cli/dist/doctor/checks/oauth-health.d.ts

@@ -0,0 +1,39 @@
+/**
+ * OAuth health check for `comis doctor`.
+ *
+ * Per-profile diagnostics: JWT decode → expiry + numeric `secsUntilExpiry`;
+ * flag profiles expiring < 7 days as warn, expired as fail; surface
+ * schema-version mismatch from the file adapter's hard-fail verbatim
+ * (`port.list()` returns `err()` whose message already contains the version
+ * + remediation hint). Environmental sub-checks: ca-certificates bundle
+ * existence with distro-aware install hint, HTTPS_PROXY env-var heuristic
+ * (Node's built-in fetch ignores HTTPS_PROXY by default), TLS preflight
+ * against `auth.openai.com` (delegates to `runOAuthTlsPreflight`).
+ *
+ * Optional `--refresh-test` flag (default OFF): exercises a real OAuth
+ * refresh against the provider; rotates the refresh token at OpenAI's end
+ * as a side effect (--help warns the operator). Doctor does NOT persist
+ * the new credentials; the success suggestion warns the stored token is
+ * now stale.
+ *
+ * Storage mode handling: the CLI process cannot bootstrap the encrypted
+ * secrets store without `SECRETS_MASTER_KEY`, so when
+ * `appConfig.oauth.storage === "encrypted"` the per-profile sub-check
+ * returns a single skip finding pointing the operator at the daemon host.
+ *
+ * NEVER prints `profile.access` or `profile.refresh` in any DoctorFinding
+ * field. Identity labels go through `redactEmailForLog`. The token-leakage
+ * test in oauth-health.test.ts asserts no `TEST_LEAK_SENTINEL` substring
+ * leakage.
+ *
+ * @module
+ */
+import type { DoctorCheck } from "../types.js";
+/**
+ * Doctor check: OAuth subsystem health.
+ *
+ * Returns 4 baseline sub-checks (per-profile expiry × N + ca-certificates +
+ * HTTPS_PROXY + TLS preflight); +N when `context.refreshTest === true`.
+ * Never throws — every failure path returns a finding.
+ */
+export declare const oauthHealthCheck: DoctorCheck;