@sireai/optimus 0.1.14 → 0.1.16

package/dist/cli/optimus.js

@@ -2,7 +2,7 @@
 import { buildDefaultConfig, loadConfig } from "../config/load-config.js";
 import { createReadStream, createWriteStream } from "node:fs";
 import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFile, spawn } from "node:child_process";
 import { createInterface } from "node:readline/promises";
@@ -29,7 +29,10 @@ import { TaskDeliveryDispatcher } from "../task-environment/delivery/task-delive
 import { TaskDeliveryService } from "../task-environment/delivery/task-delivery-service.js";
 import { FeishuAnalysisDocService } from "../task-environment/delivery/feishu-analysis-doc-service.js";
 import { TaskPublicationService } from "../task-environment/delivery/task-publication-service.js";
-import { FeishuAuthService } from "../integrations/feishu/feishu-auth-service.js";
+import { FeishuClient } from "../integrations/feishu/feishu-client.js";
+import { FeishuUserService } from "../integrations/feishu/feishu-user-service.js";
+import { createFeedbackReport } from "./feedback.js";
+import { DEFAULT_FEEDBACK_RECIPIENT_EMAIL, FeishuFeedbackDeliveryService, resolveDefaultFeedbackRecipientFallbackOpenId } from "./feedback-delivery.js";
 import { resolveDefaultConfigPath, resolveDefaultEnvPath, resolveOptimusHomeDir } from "../config/optimus-paths.js";
 import { checkForSelfUpdate, installSelfUpdate, recordSkippedSelfUpdate, readSelfUpdateState, shouldPromptForCachedStartupUpdate } from "./self-update.js";
 const CLI_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -61,6 +64,11 @@ function renderSetupResult(result) {
         lines.push(`Codex Auth: ${result.codexAuth.mode} | ${result.codexAuth.configured ? `${envLabel} configured` : `${envLabel} missing`}${providerLabel}`);
     }
     lines.push("");
+    lines.push("Next");
+    lines.push("- optimus start");
+    lines.push("- optimus submit --title \"Login crash\" --description \"Crash on startup\"");
+    lines.push("- optimus doctor --quick");
+    lines.push("");
     lines.push(renderQuickDoctorReport(result.doctorQuick));
     return lines.join("\n");
 }
@@ -138,16 +146,41 @@ function renderCliHelp() {
         "Usage:",
         "  optimus <command> [options]",
         "",
-        "Get started:",
-        "  optimus setup",
-        "  optimus start",
-        "  optimus submit --title \"Login crash\" --description \"Crash on startup\"",
+        "First time here:",
+        "  1. optimus setup",
+        "  2. optimus start",
+        "  3. optimus submit --title \"Login crash\" --description \"Crash on startup\"",
+        "",
+        "Everyday commands:",
+        "  setup                First-time setup or update config",
+        "  start                Start the resident runtime",
+        "  submit               Submit a problem for Optimus to handle",
+        "  task-status          Check what is running now",
+        "  task-result          Read the latest result for a task",
+        "  doctor --quick       Quick readiness check",
+        "  version              Show the installed package version",
+        "",
+        "Need more?",
+        "  optimus help advanced        Show integration, retry, and developer commands",
+        "  optimus help <command>       Show details for one command",
         "",
-        "User commands:",
+        "Notes:",
+        `  - Optimus stores config and runtime data under ${resolveOptimusHomeDir()}.`,
+        "  - Jira and Sentry are optional integrations. You can enable them later in `optimus setup`."
+    ].join("\n");
+}
+function renderAdvancedCliHelp() {
+    return [
+        "Optimus CLI",
+        "",
+        "Advanced command index",
+        "",
+        "Everyday commands:",
         "  help [command]       Show CLI help or command help",
         "  setup                Configure Optimus for first use or update config",
         "  start                Start the resident runtime",
         "  submit               Submit a manual task",
+        "  feedback             Create a local user feedback bundle",
         "  retry-task           Requeue an existing task",
         "  cancel-task          Cancel a queued or running task",
         "  task-status          Show task execution status",
@@ -166,7 +199,6 @@ function renderCliHelp() {
         "  postrun-retry         Rebuild postrun artifacts and optionally replay publication",
         "",
         "Integration commands:",
-        "  feishu auth login|status|logout",
         "  jira-search|jira-get-issue|jira-search-assigned-open|jira-submit-issue|jira-submit-assigned-open|jira-add-comment|jira-refresh-auth|jira-poll-once|jira-poll-daemon",
         "  sentry-get-event|sentry-submit-event",
         "  Example: optimus help jira-submit-issue",
@@ -178,11 +210,7 @@ function renderCliHelp() {
         "",
         "Global options:",
         "  -h, --help            Show this help",
-        "  -v, --version         Show the installed package version",
-        "",
-        "Notes:",
-        "  - `optimus` with no command prints help instead of starting runtime.",
-        `  - Run \`optimus setup\` once; Optimus stores config and runtime data under ${resolveOptimusHomeDir()}.`
+        "  -v, --version         Show the installed package version"
     ].join("\n");
 }
 function renderCommandHelp(command) {
@@ -207,6 +235,27 @@ function renderCommandHelp(command) {
             "Example:",
             "  optimus submit --title \"Login crash\" --description \"Crash on startup\" --repo ohos-pre"
         ].join("\n"),
+        feedback: [
+            "optimus feedback",
+            "",
+            "Usage:",
+            "  optimus feedback --title <title> --description <text>",
+            "",
+            "Required:",
+            "  --title <title>              Feedback title",
+            "  --description <text>         Feedback description",
+            "",
+            "Behavior:",
+            "  - writes a local feedback bundle under ~/.optimus/runtime/feedback",
+            "  - creates a .tar.gz archive for the bundle",
+            "  - attaches runtime and runtime-trace logs for the submission date when present",
+            `  - creates a Feishu feedback document for ${DEFAULT_FEEDBACK_RECIPIENT_EMAIL}`,
+            "  - grants that document edit access to the fixed feedback recipient",
+            "  - sends a Feishu app card message with the feedback document link",
+            "",
+            "Example:",
+            "  optimus feedback --title \"Upgrade prompt missing\" --description \"upgrade --check found 0.1.14 but start did not open the upgrade prompt.\""
+        ].join("\n"),
         "retry-task": [
             "optimus retry-task",
             "",
@@ -301,6 +350,34 @@ function renderCommandHelp(command) {
             "  --json                       Print JSON when used with --quick",
             "  --format text                Print text report"
         ].join("\n"),
+        advanced: renderAdvancedCliHelp(),
+        "notify-test": [
+            "optimus notify-test",
+            "",
+            "Usage:",
+            "  optimus notify-test [options]",
+            "",
+            "Optional:",
+            "  --channel <auto|webhook|app> Select delivery path to validate, default auto",
+            "  --format <card|text>         Override Feishu message format for this test",
+            "  --title <title>              Override message title",
+            "  --task-id <task-id>          Override synthetic task id",
+            "  --task-type <type>           Override synthetic task type",
+            "  --outcome <value>            Override synthetic outcome",
+            "  --repo <alias>               Override synthetic repo",
+            "  --decision <text>            Override decision line",
+            "  --validation <text>          Override validation line",
+            "  --next-action <text>         Override next action line",
+            "  --print-message true         Preview the final payload without dispatch",
+            "  --print-env-status true      Print Feishu runtime status only",
+            "",
+            "Examples:",
+            "  optimus notify-test",
+            "  optimus notify-test --channel webhook",
+            `  optimus notify-test --channel app --title "Optimus Feishu app smoke test"`,
+            "  optimus notify-test --format text",
+            "  optimus notify-test --format card --print-message true"
+        ].join("\n"),
         upgrade: [
             "optimus upgrade",
             "",
@@ -317,32 +394,6 @@ function renderCommandHelp(command) {
             "  optimus upgrade --check --channel snapshot",
             "  optimus upgrade --channel snapshot"
         ].join("\n"),
-        feishu: [
-            "optimus feishu auth",
-            "",
-            "Usage:",
-            "  optimus feishu auth login [--json]",
-            "  optimus feishu auth status [--json]",
-            "  optimus feishu auth logout",
-            "",
-            "Notes:",
-            "  - `login` starts Feishu device-code login for document upload and real @mentions.",
-            "  - `status` shows whether the current Optimus Feishu session is still valid.",
-            "  - `logout` clears the local Optimus Feishu auth token."
-        ].join("\n"),
-        "feishu auth": [
-            "optimus feishu auth",
-            "",
-            "Usage:",
-            "  optimus feishu auth login [--json]",
-            "  optimus feishu auth status [--json]",
-            "  optimus feishu auth logout",
-            "",
-            "Notes:",
-            "  - `login` starts Feishu device-code login for document upload and real @mentions.",
-            "  - `status` shows whether the current Optimus Feishu session is still valid.",
-            "  - `logout` clears the local Optimus Feishu auth token."
-        ].join("\n"),
         "jira-submit-issue": [
             "optimus jira-submit-issue",
             "",
@@ -696,6 +747,26 @@ async function maybeHandleStartupSelfUpdate(input) {
         interactivePromptAllowed: isInteractiveSelfUpdatePromptAllowed()
     });
     if (!check.checked) {
+        if (check.reason === "cached") {
+            const intervalHours = Math.max(1, selfUpdateConfig.checkIntervalHours);
+            const lastCheckedAt = check.state.lastCheckedAt ?? null;
+            const lastCheckedAtMs = lastCheckedAt ? Date.parse(lastCheckedAt) : Number.NaN;
+            const nextCheckAt = Number.isFinite(lastCheckedAtMs)
+                ? new Date(lastCheckedAtMs + intervalHours * 60 * 60 * 1000).toISOString()
+                : null;
+            await input.logger.info("self_update.cached", {
+                command: input.command,
+                currentVersion: check.currentVersion,
+                latestVersion: check.latestVersion ?? null,
+                channel: check.channel,
+                installSource: check.installSource,
+                intervalHours,
+                lastCheckedAt,
+                nextCheckAt,
+                updateAvailable: check.updateAvailable,
+                promptPlanned: shouldPromptCachedUpdate
+            });
+        }
         if (!shouldPromptCachedUpdate && check.reason === "cached" && check.updateAvailable && check.latestVersion) {
             console.log(`[optimus] update available ${check.currentVersion} -> ${check.latestVersion}. Run \`optimus upgrade\`.`);
         }
@@ -843,57 +914,107 @@ function buildPublicationReviewSummary(attempts) {
 }
 async function buildFeishuDoctorStatus(config) {
     const webhookConfigured = Boolean(config.delivery.feishu.webhook?.trim() || config.delivery.feishu.webhooks?.some((value) => value.trim()));
-    const authStatus = new FeishuAuthService().readStatus();
-    const hasAppId = Boolean(config.delivery.feishu.appId?.trim() || process.env.FEISHU_APP_ID?.trim());
-    const hasAppSecret = Boolean(config.delivery.feishu.appSecret?.trim() || process.env.FEISHU_APP_SECRET?.trim());
-    const appCredentialConfigured = hasAppId && hasAppSecret;
-    const authReady = authStatus.authenticated || appCredentialConfigured;
-    const authMode = authStatus.authenticated
-        ? "user_access_token"
-        : appCredentialConfigured
-            ? "app_credentials"
-            : "none";
+    const client = new FeishuClient({ config });
+    const userService = new FeishuUserService({ config });
+    const appReady = client.isConfigured();
+    const mentionReady = userService.isConfigured();
     return {
         webhook: {
             configured: webhookConfigured,
             signed: Boolean(config.delivery.feishu.secret?.trim())
         },
         auth: {
-            configured: authReady,
-            baseUrl: authStatus.baseUrl,
-            mode: authMode,
-            accessTokenExpired: authStatus.accessTokenExpired,
-            refreshTokenExpired: authStatus.refreshTokenExpired,
-            ...(authStatus.userId ? { userId: authStatus.userId } : {}),
-            ...(authStatus.openId ? { openId: authStatus.openId } : {}),
-            ...(authStatus.accessTokenExpiresAt ? { accessTokenExpiresAt: authStatus.accessTokenExpiresAt } : {}),
-            ...(authStatus.refreshTokenExpiresAt ? { refreshTokenExpiresAt: authStatus.refreshTokenExpiresAt } : {}),
-            detail: authStatus.authenticated
-                ? "Feishu auth token is ready for document upload and real @mentions."
-                : appCredentialConfigured
-                    ? "Feishu runtime auth is available for document upload and user lookup."
-                    : "Feishu webhook delivery can still work, but document upload and real @mentions are unavailable until Optimus signs in to Feishu.",
-            ...(authReady ? {} : { recommendation: "Run `optimus feishu auth login` to enable analysis docs and real @mentions." })
+            configured: appReady,
+            baseUrl: config.delivery.feishu.baseUrl?.trim() || process.env.FEISHU_BASE_URL?.trim() || "https://open.feishu.cn",
+            mode: "builtin_app",
+            detail: appReady
+                ? "Built-in Optimus Feishu app is ready for message delivery, document publishing, and capability probes."
+                : "Feishu app delivery is unavailable."
         },
         mentions: {
             requiresOpenId: true,
-            ready: authReady,
-            detail: authReady
-                ? "Authenticated Feishu user lookup is ready for real @mentions."
-                : "Real @mentions require `optimus feishu auth login`.",
-            ...(authReady ? {} : { recommendation: "Run `optimus feishu auth login`." })
+            ready: mentionReady,
+            mode: mentionReady ? "app_identity" : "unavailable",
+            detail: mentionReady
+                ? "App-identity user lookup is ready for private delivery and real @mentions."
+                : "Real @mentions require Feishu app availability.",
+            ...(mentionReady
+                ? {}
+                : { recommendation: "Rerun `optimus doctor --quick` after restoring Feishu app availability." })
         }
     };
 }
-function buildFeishuRuntimeStatus(config) {
-    const authStatus = new FeishuAuthService().readStatus();
+function buildFeishuRuntimeStatus(config, env = process.env) {
+    const client = new FeishuClient({ config, env });
+    return {
+        webhook: Boolean(config.delivery.feishu.webhook?.trim()),
+        webhooks: Boolean(config.delivery.feishu.webhooks?.some((value) => value.trim())),
+        secret: Boolean(config.delivery.feishu.secret?.trim() || env.OPTIMUS_FEISHU_SECRET?.trim()),
+        auth: client.isConfigured()
+    };
+}
+function buildNotifyTestConfig(config, channel) {
+    if (channel === "auto") {
+        return config;
+    }
+    if (channel === "webhook") {
+        return {
+            ...config,
+            delivery: {
+                ...config.delivery,
+                feishu: {
+                    ...config.delivery.feishu
+                }
+            }
+        };
+    }
     return {
-        webhook: Boolean(config.delivery.feishu.webhook?.trim() || process.env.OPTIMUS_FEISHU_WEBHOOK?.trim()),
-        webhooks: Boolean(config.delivery.feishu.webhooks?.some((value) => value.trim()) || process.env.OPTIMUS_FEISHU_WEBHOOKS?.trim()),
-        secret: Boolean(config.delivery.feishu.secret?.trim() || process.env.OPTIMUS_FEISHU_SECRET?.trim()),
-        auth: authStatus.authenticated || Boolean((config.delivery.feishu.appId?.trim() || process.env.FEISHU_APP_ID?.trim()) && (config.delivery.feishu.appSecret?.trim() || process.env.FEISHU_APP_SECRET?.trim()))
+        ...config,
+        delivery: {
+            ...config.delivery,
+            feishu: {
+                ...config.delivery.feishu,
+                webhook: "",
+                webhooks: []
+            }
+        }
     };
 }
+function buildNotifyTestEnv(channel) {
+    return process.env;
+}
+function resolveNotifyTestDefaultTitle(channel) {
+    if (channel === "app") {
+        return "Optimus Feishu app smoke test";
+    }
+    return "Optimus Feishu webhook smoke test";
+}
+function buildNotifyTestInvocationId(now = new Date()) {
+    const timestamp = now.toISOString().replace(/[-:TZ.]/gu, "").slice(0, 14);
+    const randomSuffix = Math.random().toString(36).slice(2, 6);
+    return `${timestamp}-${randomSuffix}`;
+}
+function resolveNotifyTestDefaultDecision(channel) {
+    if (channel === "app") {
+        return "Manual Feishu app smoke test.";
+    }
+    return "Manual webhook smoke test.";
+}
+function resolveNotifyTestDefaultNextAction(channel) {
+    if (channel === "app") {
+        return "If this arrives, app delivery is working.";
+    }
+    return "If this arrives, webhook delivery is working.";
+}
+function isNotifyTestEnvReady(envStatus, channel) {
+    if (channel === "app") {
+        return envStatus.auth;
+    }
+    if (channel === "webhook") {
+        return envStatus.webhook || envStatus.webhooks;
+    }
+    return envStatus.webhook || envStatus.webhooks || envStatus.auth;
+}
 function extractCommandFailureDetail(error) {
     if (!(error instanceof Error)) {
         return typeof error === "string" ? error : undefined;
@@ -911,7 +1032,7 @@ async function promptSetupAnswers(defaults) {
     let scriptedIndex = 0;
     const ask = async (prompt) => {
         if (scriptedAnswers) {
-            output.write(prompt);
+            output.write(`${prompt}\n`);
             const answer = scriptedAnswers[scriptedIndex] ?? "";
             scriptedIndex += 1;
             return answer;
@@ -924,18 +1045,38 @@ async function promptSetupAnswers(defaults) {
             console.log(detail);
         }
     };
+    const printSetupHint = (detail) => {
+        console.log(`  -> ${detail}`);
+    };
     const renderSetupPrompt = (label, promptLabel, defaultValue) => {
         const suffix = defaultValue !== undefined ? ` [${defaultValue}]` : "";
         return `[${label}] ${promptLabel}${suffix}: `;
     };
+    const resolveOptionalTextAnswer = (rawAnswer, defaultValue) => {
+        const trimmed = rawAnswer.trim();
+        if (trimmed === '""' || trimmed === "''") {
+            return null;
+        }
+        if (trimmed.length === 0) {
+            return defaultValue;
+        }
+        return trimmed;
+    };
     try {
+        console.log("Optimus setup");
+        console.log("This usually takes about 2 minutes.");
+        console.log("Required: repository + Codex auth. Optional: Feishu webhook, Jira, Sentry.");
+        console.log("You can rerun `optimus setup` later to change anything.");
         if (await pathExists(configPath)) {
             console.log(`Existing config found at ${configPath}. Press Enter to keep current values.`);
         }
-        printSetupSection("Repository", "Register the primary local repository used by Optimus.");
+        printSetupSection("Repository", "Point Optimus at the main local repository it should work in.");
+        printSetupHint("Repository path: the local code directory Optimus will read and edit.");
         const repoPath = (await ask(renderSetupPrompt("Required", "Repository path", defaults.repoPath))).trim() || defaults.repoPath;
+        printSetupHint("Repository alias: the short name used later in commands like --repo ohos-pre.");
         const repoAlias = (await ask(renderSetupPrompt("Required", "Repository alias", defaults.repoAlias))).trim() || defaults.repoAlias;
-        printSetupSection("Codex", "Choose one authentication mode, then fill the fields that follow.");
+        printSetupSection("Codex", "Choose one model authentication mode. This is required before tasks can run.");
+        printSetupHint("Codex auth mode: choose how Optimus reaches the model you want to use.");
         const codexAuthMode = await askSetupCodexAuthMode({ ask, defaultMode: defaults.codexAuthMode });
         let codexApiKey;
         let codexProviderId;
@@ -943,54 +1084,56 @@ async function promptSetupAnswers(defaults) {
         let codexProviderBaseUrl;
         let codexProviderApiKeyEnvName;
         if (codexAuthMode === "openai_api_key") {
+            printSetupHint("OpenAI API key: used only when you choose direct OpenAI API authentication.");
             codexApiKey = (await ask(renderSetupPrompt("Optional", "OpenAI API key for OPENAI_API_KEY", "leave blank to keep existing"))).trim() || undefined;
         }
         else if (codexAuthMode === "model_provider") {
+            printSetupHint("Provider id: a short stable id for this model provider, for example palebluedot.");
             codexProviderId = (await ask(renderSetupPrompt("Required", "Provider id", defaults.codexProviderId ?? ""))).trim() || defaults.codexProviderId;
+            printSetupHint("Provider display name: what Optimus shows in status and doctor output.");
             codexProviderDisplayName = (await ask(renderSetupPrompt("Required", "Provider display name", defaults.codexProviderDisplayName ?? ""))).trim() || defaults.codexProviderDisplayName;
+            printSetupHint("Provider base URL: the model API endpoint root Optimus should call.");
             codexProviderBaseUrl = (await ask(renderSetupPrompt("Required", "Provider base URL", defaults.codexProviderBaseUrl ?? ""))).trim() || defaults.codexProviderBaseUrl;
+            printSetupHint("Provider API key env name: the environment variable name Optimus will read at runtime.");
             codexProviderApiKeyEnvName = (await ask(renderSetupPrompt("Required", "Provider API key env name", defaults.codexProviderApiKeyEnvName ?? ""))).trim() || defaults.codexProviderApiKeyEnvName;
             const providerKeyLabel = codexProviderApiKeyEnvName || defaults.codexProviderApiKeyEnvName || "the configured provider env";
+            printSetupHint(`Provider API key value: optional here; leave blank to keep the current ${providerKeyLabel} value.`);
             codexApiKey = (await ask(renderSetupPrompt("Optional", `Provider API key value for ${providerKeyLabel}`, "leave blank to keep existing"))).trim() || undefined;
         }
-        printSetupSection("Feishu", "Enable this module when task notifications should be sent to Feishu. Use `optimus feishu auth login` later for analysis docs and real @mentions.");
-        const enableFeishuInput = (await ask(renderSetupPrompt("Optional module", "Enable Feishu delivery", defaults.enableFeishu ? "Y/n" : "y/N"))).trim().toLowerCase();
-        const enableFeishu = enableFeishuInput.length === 0
-            ? defaults.enableFeishu
-            : ["y", "yes"].includes(enableFeishuInput);
-        const feishuWebhook = enableFeishu
-            ? (await ask(renderSetupPrompt("Required", "Feishu webhook", defaults.feishuWebhook ? "configured" : ""))).trim() || defaults.feishuWebhook
-            : undefined;
-        const feishuSecret = enableFeishu
-            ? (await ask(renderSetupPrompt("Optional", "Feishu secret", defaults.feishuSecret ? "configured" : ""))).trim() || defaults.feishuSecret
-            : undefined;
-        printSetupSection("Jira", "Enable this module when Optimus should read issues or comment back to Jira.");
-        const enableJiraInput = (await ask(renderSetupPrompt("Optional module", "Enable Jira integration", defaults.enableJira ? "Y/n" : "y/N"))).trim().toLowerCase();
+        printSetupSection("Feishu", "Built-in Feishu app delivery is already available. Add a webhook only if group notifications should go to a chat first. Type \"\" to clear an existing optional value.");
+        printSetupHint("Feishu webhook: optional; leave empty to use direct Feishu app delivery only.");
+        const feishuWebhook = resolveOptionalTextAnswer(await ask(renderSetupPrompt("Optional", "Feishu webhook", defaults.feishuWebhook ? "configured" : "")), defaults.feishuWebhook ?? undefined);
+        printSetupHint("Feishu secret: optional; only needed when the webhook itself requires signature verification.");
+        const feishuSecret = resolveOptionalTextAnswer(await ask(renderSetupPrompt("Optional", "Feishu secret", defaults.feishuSecret ? "configured" : "")), defaults.feishuSecret ?? undefined);
+        printSetupSection("Jira", "Optional. Turn this on only if you want this machine to read Jira issues or write Jira comments.");
+        printSetupHint("If disabled, Optimus still works; Jira commands just stay unavailable on this machine.");
+        const enableJiraInput = (await ask(renderSetupPrompt("Optional integration", "Enable Jira integration", defaults.enableJira ? "Y/n" : "y/N"))).trim().toLowerCase();
         const enableJira = enableJiraInput.length === 0
             ? defaults.enableJira
             : ["y", "yes"].includes(enableJiraInput);
         const jiraBaseUrl = enableJira
-            ? (await ask(renderSetupPrompt("Required", "Jira base URL", defaults.jiraBaseUrl ?? ""))).trim() || defaults.jiraBaseUrl
+            ? (printSetupHint("Jira base URL: the Jira site root, for example https://jira.example.com/."), (await ask(renderSetupPrompt("Required", "Jira base URL", defaults.jiraBaseUrl ?? ""))).trim() || defaults.jiraBaseUrl)
             : undefined;
         const jiraPersonalToken = enableJira
-            ? (await ask(renderSetupPrompt("Required", "Jira personal token", defaults.jiraPersonalToken ? "configured" : ""))).trim() || defaults.jiraPersonalToken
+            ? (printSetupHint("Jira personal token: required for Jira reads, comments, and issue submission commands."), (await ask(renderSetupPrompt("Required", "Jira personal token", defaults.jiraPersonalToken ? "configured" : ""))).trim() || defaults.jiraPersonalToken)
             : undefined;
         const jiraCasCookieName = enableJira
-            ? (await ask(renderSetupPrompt("Optional", "Jira CAS cookie name", defaults.jiraCasCookieName ?? "_aegis_cas_p"))).trim() || defaults.jiraCasCookieName || "_aegis_cas_p"
+            ? (printSetupHint("Jira CAS cookie name: optional helper for environments that need refreshed CAS login cookies."), (await ask(renderSetupPrompt("Optional", "Jira CAS cookie name", defaults.jiraCasCookieName ?? "_aegis_cas_p"))).trim() || defaults.jiraCasCookieName || "_aegis_cas_p")
             : undefined;
-        printSetupSection("Sentry", "Enable this module when tasks can be created from Sentry events.");
-        const enableSentryInput = (await ask(renderSetupPrompt("Optional module", "Enable Sentry integration", defaults.enableSentry ? "Y/n" : "y/N"))).trim().toLowerCase();
+        printSetupSection("Sentry", "Optional. Turn this on only if you want this machine to read Sentry events and create tasks from them.");
+        printSetupHint("If disabled, Optimus still works; Sentry commands just stay unavailable on this machine.");
+        const enableSentryInput = (await ask(renderSetupPrompt("Optional integration", "Enable Sentry integration", defaults.enableSentry ? "Y/n" : "y/N"))).trim().toLowerCase();
         const enableSentry = enableSentryInput.length === 0
             ? defaults.enableSentry
             : ["y", "yes"].includes(enableSentryInput);
         const sentryBaseUrl = enableSentry
-            ? (await ask(renderSetupPrompt("Required", "Sentry base URL", defaults.sentryBaseUrl ?? ""))).trim() || defaults.sentryBaseUrl
+            ? (printSetupHint("Sentry base URL: the Sentry site root, for example https://sentry.example.com/."), (await ask(renderSetupPrompt("Required", "Sentry base URL", defaults.sentryBaseUrl ?? ""))).trim() || defaults.sentryBaseUrl)
             : undefined;
         const sentryOrg = enableSentry
-            ? (await ask(renderSetupPrompt("Required", "Sentry org", defaults.sentryOrg ?? ""))).trim() || defaults.sentryOrg
+            ? (printSetupHint("Sentry org: the organization slug used in Sentry API requests."), (await ask(renderSetupPrompt("Required", "Sentry org", defaults.sentryOrg ?? ""))).trim() || defaults.sentryOrg)
             : undefined;
         const sentryAuthToken = enableSentry
-            ? (await ask(renderSetupPrompt("Required", "Sentry auth token", defaults.sentryAuthToken ? "configured" : ""))).trim() || defaults.sentryAuthToken
+            ? (printSetupHint("Sentry auth token: required if this machine should read events from Sentry."), (await ask(renderSetupPrompt("Required", "Sentry auth token", defaults.sentryAuthToken ? "configured" : ""))).trim() || defaults.sentryAuthToken)
             : undefined;
         return {
             repoPath,
@@ -1001,9 +1144,8 @@ async function promptSetupAnswers(defaults) {
             ...(codexProviderDisplayName ? { codexProviderDisplayName } : {}),
             ...(codexProviderBaseUrl ? { codexProviderBaseUrl } : {}),
             ...(codexProviderApiKeyEnvName ? { codexProviderApiKeyEnvName } : {}),
-            enableFeishu,
-            ...(feishuWebhook ? { feishuWebhook } : {}),
-            ...(feishuSecret ? { feishuSecret } : {}),
+            ...(feishuWebhook !== undefined ? { feishuWebhook } : {}),
+            ...(feishuSecret !== undefined ? { feishuSecret } : {}),
             enableJira,
             ...(jiraBaseUrl ? { jiraBaseUrl } : {}),
             ...(jiraPersonalToken ? { jiraPersonalToken } : {}),
@@ -1034,7 +1176,6 @@ async function resolveDefaultSetupAnswers() {
             repoPath: "",
             repoAlias: "",
             codexAuthMode: defaults.codex.auth.mode,
-            enableFeishu: false,
             enableJira: false,
             enableSentry: false
         };
@@ -1054,7 +1195,6 @@ async function resolveDefaultSetupAnswers() {
         ...(provider?.displayName ? { codexProviderDisplayName: provider.displayName } : {}),
         ...(provider?.baseUrl ? { codexProviderBaseUrl: provider.baseUrl } : {}),
         ...(provider?.apiKeyEnvName ? { codexProviderApiKeyEnvName: provider.apiKeyEnvName } : {}),
-        enableFeishu: config.delivery.channels.includes("feishu"),
         ...(config.delivery.feishu.webhook ? { feishuWebhook: config.delivery.feishu.webhook } : {}),
         ...(config.delivery.feishu.secret ? { feishuSecret: config.delivery.feishu.secret } : {}),
         enableJira: config.jira.enabled,
@@ -1126,9 +1266,6 @@ function validateSetupAnswers(answers) {
     if (answers.codexAuthMode === "model_provider" && !answers.codexProviderApiKeyEnvName?.trim()) {
         return "setup requires provider API key env name when Codex auth mode is model_provider.";
     }
-    if (answers.enableFeishu && !answers.feishuWebhook?.trim()) {
-        return "setup requires a Feishu webhook when Feishu delivery is enabled.";
-    }
     if (answers.enableJira && !answers.jiraBaseUrl?.trim()) {
         return "setup requires a Jira base URL when Jira integration is enabled.";
     }
@@ -1244,12 +1381,19 @@ function buildSetupConfig(answers, rawConfig) {
     else {
         delete config.codex.setupCache;
     }
-    config.delivery.channels = answers.enableFeishu ? ["console", "feishu"] : ["console"];
+    config.delivery.channels = ["console", "feishu"];
     config.delivery.feishu = {
         ...config.delivery.feishu,
-        ...(answers.enableFeishu && answers.feishuWebhook ? { webhook: answers.feishuWebhook } : {}),
-        ...(answers.enableFeishu && answers.feishuSecret ? { secret: answers.feishuSecret } : {})
+        ...(typeof answers.feishuWebhook === "string" ? { webhook: answers.feishuWebhook } : {}),
+        ...(typeof answers.feishuSecret === "string" ? { secret: answers.feishuSecret } : {})
     };
+    if (answers.feishuWebhook === null) {
+        delete config.delivery.feishu.webhook;
+        delete config.delivery.feishu.webhooks;
+    }
+    if (answers.feishuSecret === null) {
+        delete config.delivery.feishu.secret;
+    }
     config.jira.enabled = answers.enableJira;
     if (answers.enableJira) {
         config.jira.baseUrl = answers.jiraBaseUrl ?? config.jira.baseUrl;
@@ -1456,31 +1600,12 @@ async function runQuickDoctor(configPath = resolveDefaultConfigPath()) {
             next.add("git config user.email \"you@example.com\"");
         }
     }
-    const feishuEnabled = config.delivery.channels.includes("feishu");
-    const configuredFeishuTargets = [
-        config.delivery.feishu.webhook?.trim(),
-        ...(config.delivery.feishu.webhooks ?? []).map((value) => value.trim())
-    ].filter((value) => Boolean(value));
-    if (feishuEnabled && configuredFeishuTargets.length === 0) {
-        blocking.push({
-            code: "feishu_webhook_missing",
-            message: "Feishu delivery is enabled, but no webhook is configured.",
-            fix: "Rerun `optimus setup` and provide a Feishu webhook."
-        });
-        next.add("optimus setup");
-    }
-    if (!feishuEnabled) {
+    const feishuEnabled = config.delivery.enabled && config.delivery.channels.includes("feishu");
+    if (!config.delivery.enabled) {
         warnings.push({
             code: "feishu_disabled",
-            message: "Feishu delivery is disabled.",
-            impact: "Notifications will stay console-only."
-        });
-    }
-    else if (!new FeishuAuthService().readStatus().authenticated && (!config.delivery.feishu.appId?.trim() || !config.delivery.feishu.appSecret?.trim())) {
-        warnings.push({
-            code: "feishu_auth_missing",
-            message: "Feishu auth token is missing.",
-            impact: "Webhook messages can still be sent, but analysis document upload and real @mentions will be skipped."
+            message: "Task delivery is disabled.",
+            impact: "Console, Feishu, and analysis-document delivery are all paused."
         });
     }
     if (config.jira.enabled) {
@@ -1606,15 +1731,25 @@ function inferArtifactDir(artifacts, bundle) {
     }
     return dirname(artifactPath);
 }
-function inferTaskRootDir(artifactDir) {
+function inferTaskRootDir(artifactDir, fallbackTaskRootDir) {
     if (!artifactDir) {
-        return undefined;
+        return fallbackTaskRootDir;
+    }
+    if (fallbackTaskRootDir) {
+        const resolvedArtifactDir = resolve(artifactDir);
+        const resolvedFallbackTaskRootDir = resolve(fallbackTaskRootDir);
+        if (resolvedArtifactDir === resolvedFallbackTaskRootDir
+            || resolvedArtifactDir.startsWith(`${resolvedFallbackTaskRootDir}${sep}`)) {
+            return resolve(artifactDir, "..", "..");
+        }
+        return resolvedFallbackTaskRootDir;
     }
     return resolve(artifactDir, "..", "..");
 }
 async function buildReplayExecutionContext(input) {
     const artifactDir = inferArtifactDir(input.artifacts, input.deliveryBundle);
-    const taskRootDir = inferTaskRootDir(artifactDir);
+    const fallbackTaskRootDir = join(input.config.storage.rootDir, "workspaces", input.taskId);
+    const taskRootDir = inferTaskRootDir(artifactDir, fallbackTaskRootDir);
     const sourceDir = input.deliveryBundle?.publication?.git?.repoDir?.trim()
         || input.latestRun?.addresses?.visibleRepoDir?.trim()
         || input.latestRun?.addresses?.workspaceDir?.trim();
@@ -1870,56 +2005,7 @@ async function main() {
         return;
     }
     if (command === "feishu") {
-        const [firstSubcommand, secondSubcommand] = commandArgs;
-        const args = parseArgs(commandArgs.slice(2));
-        if (firstSubcommand !== "auth" || !secondSubcommand) {
-            console.log(renderCommandHelp("feishu") ?? renderCliHelp());
-            process.exitCode = 1;
-            return;
-        }
-        const authService = new FeishuAuthService();
-        if (secondSubcommand === "status") {
-            const status = authService.readStatus();
-            if (args.json === "true") {
-                console.log(JSON.stringify(status, null, 2));
-            }
-            else if (status.authenticated) {
-                console.log(`Feishu auth is ready. user=${status.userId ?? "unknown"} open_id=${status.openId ?? "unknown"} access_token_expires=${status.accessTokenExpiresAt ?? "unknown"} refresh_token_expires=${status.refreshTokenExpiresAt ?? "unknown"}`);
-            }
-            else {
-                console.log("Feishu auth is not ready. Run `optimus feishu auth login`.");
-            }
-            process.exitCode = status.authenticated ? 0 : 1;
-            return;
-        }
-        if (secondSubcommand === "login") {
-            const result = await authService.login({
-                onPrompt: ({ verificationUrl, expiresInSeconds }) => {
-                    console.error(`Open this URL to authorize:\n${verificationUrl}\n`);
-                    console.error(`Waiting for authorization (expires in ${expiresInSeconds}s)...`);
-                }
-            });
-            if (args.json === "true") {
-                console.log(JSON.stringify({
-                    ok: true,
-                    userId: result.userId ?? null,
-                    openId: result.openId ?? null,
-                    verificationUrl: result.verificationUrl,
-                    accessTokenExpiresAt: new Date(result.expiresAtMs).toISOString(),
-                    refreshTokenExpiresAt: new Date(result.refreshExpiresAtMs).toISOString()
-                }, null, 2));
-            }
-            else {
-                console.log(`Feishu auth succeeded. user=${result.userId ?? "unknown"} open_id=${result.openId ?? "unknown"}`);
-            }
-            return;
-        }
-        if (secondSubcommand === "logout") {
-            await authService.logout();
-            console.log("Feishu auth cleared.");
-            return;
-        }
-        console.log(renderCommandHelp("feishu") ?? renderCliHelp());
+        console.log("Feishu user-session commands have been removed. Optimus now uses the built-in Feishu app for delivery and document publishing.");
         process.exitCode = 1;
         return;
     }
@@ -1949,7 +2035,13 @@ async function main() {
     }
     catch (error) {
         if (error?.code === "ENOENT") {
-            console.error("Configuration is missing. Run `optimus setup` first.");
+            console.error([
+                "Optimus is not set up on this machine yet.",
+                "Next:",
+                "  1. optimus setup",
+                "  2. optimus start",
+                "  3. optimus submit --title \"Login crash\" --description \"Crash on startup\""
+            ].join("\n"));
             process.exitCode = 1;
             return;
         }
@@ -2023,6 +2115,42 @@ async function main() {
         console.log(`[optimus] wrote submission ${inboxPath}`);
         return;
     }
+    if (command === "feedback") {
+        const args = parseArgs(commandArgs);
+        const title = args.title?.trim();
+        const description = (args.desc ?? args.description)?.trim();
+        if (!title || !description) {
+            console.error("feedback requires both --title and --description");
+            process.exitCode = 1;
+            return;
+        }
+        const result = await createFeedbackReport({
+            title,
+            description,
+            currentVersion,
+            packageRoot: CLI_ROOT_DIR
+        });
+        console.log("[optimus] feedback saved locally");
+        console.log(`id: ${result.id}`);
+        console.log(`path: ${result.feedbackDir}`);
+        console.log(`report: ${result.reportPath}`);
+        console.log(`archive: ${result.archivePath}`);
+        console.log(`logs: ${result.files.filter((file) => file.found).length}/${result.files.length}`);
+        const feedbackDelivery = new FeishuFeedbackDeliveryService({
+            config
+        });
+        const deliveryResult = await feedbackDelivery.deliver({
+            title,
+            description,
+            currentVersion,
+            report: result
+        });
+        console.log(`recipient: ${deliveryResult.recipientEmail}`);
+        console.log(`open_id: ${deliveryResult.recipientOpenId}`);
+        console.log(`doc: ${deliveryResult.document.status}${deliveryResult.document.url ? ` (${deliveryResult.document.url})` : deliveryResult.document.reason ? ` (${deliveryResult.document.reason})` : ""}`);
+        console.log(`notify: ${deliveryResult.notification.status}${deliveryResult.notification.reason ? ` (${deliveryResult.notification.reason})` : ""}`);
+        return;
+    }
     if (command === "retry-task") {
         const args = parseArgs(commandArgs);
         const taskId = args["task-id"];
@@ -2044,17 +2172,32 @@ async function main() {
     }
     if (command === "notify-test") {
         const args = parseArgs(commandArgs);
-        const title = args.title?.trim() || "Optimus Feishu webhook smoke test";
-        const taskId = args["task-id"]?.trim() || "task-feishu-smoke";
+        const requestedChannel = args.channel?.trim().toLowerCase();
+        if (requestedChannel && requestedChannel !== "auto" && requestedChannel !== "webhook" && requestedChannel !== "app") {
+            console.error("notify-test only supports --channel auto, webhook, or app");
+            process.exitCode = 1;
+            return;
+        }
+        const requestedFormat = args.format?.trim().toLowerCase();
+        if (requestedFormat && requestedFormat !== "text" && requestedFormat !== "card") {
+            console.error("notify-test only supports --format text or --format card");
+            process.exitCode = 1;
+            return;
+        }
+        const notifyChannel = requestedChannel === "webhook" || requestedChannel === "app" ? requestedChannel : "auto";
+        const invocationId = buildNotifyTestInvocationId();
+        const title = args.title?.trim() || `${resolveNotifyTestDefaultTitle(notifyChannel)} [${invocationId}]`;
+        const taskId = args["task-id"]?.trim() || `task-feishu-smoke-${invocationId}`;
+        const runId = `run-feishu-smoke-${invocationId}`;
         const taskType = args["task-type"]?.trim() || "bugfix";
         const outcome = args.outcome?.trim() || "analysis_only";
         const repo = args.repo?.trim() || "optimus";
-        const decision = args.decision?.trim() || "Manual webhook smoke test.";
+        const decision = args.decision?.trim() || resolveNotifyTestDefaultDecision(notifyChannel);
         const validation = args.validation?.trim() || "Triggered from local CLI.";
-        const nextAction = args["next-action"]?.trim() || "If this arrives, webhook delivery is working.";
+        const nextAction = args["next-action"]?.trim() || resolveNotifyTestDefaultNextAction(notifyChannel);
         const bundle = {
             taskId,
-            runId: "run-feishu-smoke",
+            runId,
             taskType,
             outcome: outcome,
             createdAt: new Date().toISOString(),
@@ -2063,7 +2206,13 @@ async function main() {
                 repo,
                 decision,
                 validation,
-                nextAction
+                nextAction,
+                ...(notifyChannel === "app" ? {
+                    qAssignee: {
+                        displayName: "wangkai39",
+                        email: DEFAULT_FEEDBACK_RECIPIENT_EMAIL
+                    }
+                } : {})
             },
             artifacts: {
                 extras: []
@@ -2078,7 +2227,7 @@ async function main() {
         const publicationAttempts = args["review-url"] || args["change-id"]
             ? [{
                     taskId,
-                    runId: "run-feishu-smoke",
+                    runId,
                     mode: "review_submit",
                     status: "submitted",
                     summary: args["review-summary"]?.trim() || "Review submission completed for 1/1 target(s).",
@@ -2087,12 +2236,50 @@ async function main() {
                     ...(changeIds.length > 0 ? { changeId: changeIds[0], changeIds } : {})
                 }]
             : [];
-        const reviewAwareNotifier = new FeishuNotifier({ config, publicationAttempts, format: config.delivery.feishu.format });
+        const effectiveFormat = requestedFormat === "text" || requestedFormat === "card"
+            ? requestedFormat
+            : config.delivery.feishu.format;
+        const notifyConfig = buildNotifyTestConfig(config, notifyChannel);
+        const notifyEnv = buildNotifyTestEnv(notifyChannel);
+        let appResolution;
+        if (notifyChannel === "app" && args["print-message"] !== "true") {
+            const assigneeEmail = bundle.summary.qAssignee?.email?.trim();
+            appResolution = assigneeEmail ? { requestedEmail: assigneeEmail } : {};
+            if (assigneeEmail) {
+                try {
+                    const resolvedOpenId = await new FeishuUserService({ config: notifyConfig }).resolveOpenId(assigneeEmail);
+                    if (resolvedOpenId && bundle.summary.qAssignee) {
+                        bundle.summary.qAssignee.openId = resolvedOpenId;
+                        appResolution.resolvedOpenId = resolvedOpenId;
+                    }
+                }
+                catch (error) {
+                    appResolution.error = extractCommandFailureDetail(error) ?? String(error);
+                    // Keep the smoke test non-blocking and let the notifier report the final delivery status.
+                }
+                if (!bundle.summary.qAssignee?.openId) {
+                    const fallbackOpenId = resolveDefaultFeedbackRecipientFallbackOpenId(notifyEnv, notifyConfig);
+                    if (fallbackOpenId && bundle.summary.qAssignee) {
+                        bundle.summary.qAssignee.openId = fallbackOpenId;
+                        appResolution.resolvedOpenId = fallbackOpenId;
+                        if (!appResolution.error) {
+                            appResolution.error = "lookup_unavailable_used_fallback_open_id";
+                        }
+                    }
+                }
+            }
+        }
+        const reviewAwareNotifier = new FeishuNotifier({
+            config: notifyConfig,
+            env: notifyEnv,
+            publicationAttempts,
+            format: effectiveFormat
+        });
         const message = reviewAwareNotifier.previewMessage(bundle);
-        const envStatus = buildFeishuRuntimeStatus(config);
+        const envStatus = buildFeishuRuntimeStatus(notifyConfig, notifyEnv);
         if (args["print-env-status"] === "true") {
-            console.log(JSON.stringify({ envStatus }, null, 2));
-            process.exitCode = envStatus.webhook || envStatus.webhooks ? 0 : 1;
+            console.log(JSON.stringify({ channel: notifyChannel, envStatus }, null, 2));
+            process.exitCode = isNotifyTestEnvReady(envStatus, notifyChannel) ? 0 : 1;
             return;
         }
         if (args["print-message"] === "true") {
@@ -2101,7 +2288,17 @@ async function main() {
             return;
         }
         const attempts = await reviewAwareNotifier.dispatch(bundle);
-        console.log(JSON.stringify({ envStatus, message, attempts }, null, 2));
+        console.log(JSON.stringify({
+            channel: notifyChannel,
+            envStatus,
+            format: effectiveFormat,
+            ...(notifyChannel === "app" ? {
+                receiver: bundle.summary.qAssignee,
+                appResolution
+            } : {}),
+            message,
+            attempts
+        }, null, 2));
         process.exitCode = attempts.every((attempt) => attempt.status === "dispatched") ? 0 : 1;
         return;
     }
@@ -2176,6 +2373,7 @@ async function main() {
         const existingBundle = await store.getLatestTaskDeliveryBundle(taskId);
         const latestRun = (await store.listTaskRuns()).filter((run) => run.taskId === taskId).at(-1) ?? null;
         const replayContext = await buildReplayExecutionContext({
+            taskId,
             config,
             taskType: task.taskType,
             taskRepo: taskPackage.repo,