Harden feedback honesty and CLI help exit path

Ship blockers from the OSS panel: --help exits 0 via CliHelpError,
feedback says queued not sent with truncation notice, hide /feedback
from the slash menu until survey env ids are set, and drop a bare
feedback arm when another slash command runs.

Author: TheGreatAxios

docs/TELEMETRY.md

@@ -160,7 +160,10 @@ still win — `DO_NOT_TRACK=1` or `CORBITS_TELEMETRY=0/false/off/no` block
 
 Survey id / question id come from env (`CORBITS_FEEDBACK_SURVEY_ID`,
 `CORBITS_FEEDBACK_QUESTION_ID`). Both must be set or capture fails closed with
-an “not configured” message — no default survey is baked into the client.
+an “not configured” message — no default survey is baked into the client. When
+ids are missing the command is also hidden from the slash menu (still callable
+if typed). Success copy says “queued,” not delivered; free text over 2000
+characters is truncated with an explicit notice.
 
 ## Opting out
 

src/config.test.ts

@@ -3,7 +3,7 @@ import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { buildBifrostSource, buildOpenAISource, buildProviderCatalog, catalogEntryAsProviderSettings, KEYLESS_API_KEY, loadConfig, providerCatalogToSettings, runtimeSettingsWithCatalog, SOURCE_MAX_TOKENS } from "./config/index.js";
+import { buildBifrostSource, buildOpenAISource, buildProviderCatalog, catalogEntryAsProviderSettings, CliHelpError, CLI_HELP_TEXT, KEYLESS_API_KEY, loadConfig, providerCatalogToSettings, runtimeSettingsWithCatalog, SOURCE_MAX_TOKENS } from "./config/index.js";
 import type { Config, UnconfiguredConfig } from "./config/index.js";
 import { mergeProviderIntoSettings, type ResolvedProvider, type Settings } from "./config/settings.js";
 import { OPENCODE_GO_BASE_URL } from "../packages/opencode-go/src/index.js";
@@ -362,6 +362,22 @@ describe("loadConfig", () => {
     }
   });
 
+  test("--help throws CliHelpError with exitCode 0 and full help text", async () => {
+    await expect(loadConfig(["--help"], { globalSettingsPath: NO_SETTINGS })).rejects.toBeInstanceOf(
+      CliHelpError,
+    );
+    try {
+      await loadConfig(["-h"], { globalSettingsPath: NO_SETTINGS });
+      expect.unreachable("expected CliHelpError");
+    } catch (err) {
+      expect(err).toBeInstanceOf(CliHelpError);
+      const help = err as CliHelpError;
+      expect(help.exitCode).toBe(0);
+      expect(help.message).toBe(CLI_HELP_TEXT);
+      expect(help.message).toContain("resume");
+    }
+  });
+
   test("rejects unknown flags", async () => {
     await expect(
       loadConfig(["--unknown"], { globalSettingsPath: NO_SETTINGS }),

src/config/index.ts

@@ -379,6 +379,19 @@ Flags:
   --help, -h                  show this help
 `;
 
+/**
+ * Thrown when the operator asked for CLI help. Entry points must print
+ * `message` to stdout and exit 0 — not treat this as a crash.
+ */
+export class CliHelpError extends Error {
+  readonly exitCode = 0 as const;
+
+  constructor(text: string = CLI_HELP_TEXT) {
+    super(text);
+    this.name = "CliHelpError";
+  }
+}
+
 export type LoadConfigOptions = {
   // Override the global settings file location (for tests / non-standard homes).
   globalSettingsPath?: string;
@@ -444,7 +457,7 @@ export async function loadConfig(
   }
 
   if (args[0] === "--help" || args[0] === "-h") {
-    throw new Error(CLI_HELP_TEXT);
+    throw new CliHelpError();
   }
 
 

src/index.ts

@@ -4,7 +4,7 @@ import { primeCrashReporting, writeCrashReport, type CrashKind } from "./crash/r
 import { getActiveRun, markCrashed } from "./session/active-run.js";
 import { getActiveDisposeHost } from "./session/active-host.js";
 import { saveCrashState } from "./session/state.js";
-import { loadConfig } from "./config/index.js";
+import { loadConfig, CliHelpError } from "./config/index.js";
 import { ensureTelemetrySettings, globalSettingsPath } from "./config/settings.js";
 import { installFileLogSink } from "./logging/sink.js";
 import { flushPerfToOtel } from "./perf/index.js";
@@ -297,8 +297,14 @@ if (import.meta.main) {
   try {
     code = await main(process.argv.slice(2));
   } catch (err: unknown) {
-    process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
-    code = 1;
+    // Help is an intentional early exit, not a crash — stdout + 0.
+    if (err instanceof CliHelpError) {
+      process.stdout.write(`${err.message}\n`);
+      code = err.exitCode;
+    } else {
+      process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+      code = 1;
+    }
   }
   process.exit(code);
 }

src/telemetry/feedback.test.ts

@@ -148,6 +148,20 @@ describe("captureFeedback", () => {
     expect(events).toHaveLength(0);
   });
 
+  test("reports truncation when free text exceeds the cap", () => {
+    const { telemetry, events } = captureSpy();
+    const long = "x".repeat(FEEDBACK_MAX_CHARS + 50);
+    const status = captureFeedback(telemetry, long, {
+      env: {
+        CORBITS_FEEDBACK_SURVEY_ID: "s1",
+        CORBITS_FEEDBACK_QUESTION_ID: "q1",
+      },
+    });
+    expect(status).toBe("sent_truncated");
+    expect(events).toHaveLength(1);
+    expect(String(events[0]?.properties.$survey_response).length).toBe(FEEDBACK_MAX_CHARS);
+  });
+
   test("rejects non-survey events on the intentional door", () => {
     const { telemetry, events } = captureSpy();
     expect(telemetry.captureIntentional("cli_start")).toBe(false);
@@ -157,7 +171,8 @@ describe("captureFeedback", () => {
 
 describe("feedbackResultMessage", () => {
   test("maps statuses to operator-facing lines", () => {
-    expect(feedbackResultMessage("sent")).toContain("Thanks");
+    expect(feedbackResultMessage("sent")).toBe("Thanks — feedback queued.");
+    expect(feedbackResultMessage("sent_truncated")).toContain("truncated");
     expect(feedbackResultMessage("blocked")).toContain("could not be sent");
     expect(feedbackResultMessage("unconfigured")).toContain("not configured");
     expect(feedbackResultMessage("empty")).toContain("No feedback");

src/telemetry/feedback.ts

@@ -12,7 +12,10 @@ export const FEEDBACK_MAX_CHARS = 2000;
 export const FEEDBACK_PROMPT =
   "Please share your feedback. When done please hit enter. (Empty Enter cancels.)";
 
-export const FEEDBACK_THANKS = "Thanks — feedback sent.";
+export const FEEDBACK_THANKS = "Thanks — feedback queued.";
+
+export const FEEDBACK_THANKS_TRUNCATED =
+  "Thanks — feedback queued (truncated to 2000 characters).";
 
 export const FEEDBACK_EMPTY = "No feedback text provided.";
 
@@ -37,6 +40,11 @@ export function feedbackQuestionId(env: NodeJS.ProcessEnv = process.env): string
   return env.CORBITS_FEEDBACK_QUESTION_ID?.trim() ?? "";
 }
 
+/** True when both survey env ids are present (command is useful to show). */
+export function isFeedbackConfigured(env: NodeJS.ProcessEnv = process.env): boolean {
+  return feedbackSurveyId(env).length > 0 && feedbackQuestionId(env).length > 0;
+}
+
 export function capFeedbackMessage(message: string): string {
   if (message.length <= FEEDBACK_MAX_CHARS) return message;
   return message.slice(0, FEEDBACK_MAX_CHARS);
@@ -74,6 +82,8 @@ export function buildSurveyProperties(
 /**
  * Capture intentional survey response. Returns whether the event was queued.
  * Empty/whitespace-only text is not sent. Missing survey/question ids fail closed.
+ * "sent" means queued for flush (not a network delivery ack); "sent_truncated"
+ * is the same after the free-text cap was applied.
  */
 export function captureFeedback(
   telemetry: Telemetry,
@@ -82,26 +92,30 @@ export function captureFeedback(
     turnTraceId?: string | undefined;
     env?: NodeJS.ProcessEnv;
   } = {},
-): "empty" | "blocked" | "unconfigured" | "sent" {
+): "empty" | "blocked" | "unconfigured" | "sent" | "sent_truncated" {
   const trimmed = message.trim();
   if (trimmed.length === 0) return "empty";
   const env = options.env ?? process.env;
-  if (feedbackSurveyId(env).length === 0 || feedbackQuestionId(env).length === 0) {
+  if (!isFeedbackConfigured(env)) {
     return "unconfigured";
   }
+  const truncated = trimmed.length > FEEDBACK_MAX_CHARS;
   const ok = telemetry.captureIntentional(
     "survey sent",
     buildSurveyProperties(trimmed, options),
   );
-  return ok ? "sent" : "blocked";
+  if (!ok) return "blocked";
+  return truncated ? "sent_truncated" : "sent";
 }
 
 export function feedbackResultMessage(
-  status: "empty" | "blocked" | "unconfigured" | "sent",
+  status: "empty" | "blocked" | "unconfigured" | "sent" | "sent_truncated",
 ): string {
   switch (status) {
     case "sent":
       return FEEDBACK_THANKS;
+    case "sent_truncated":
+      return FEEDBACK_THANKS_TRUNCATED;
     case "blocked":
       return FEEDBACK_BLOCKED;
     case "unconfigured":

src/tui/commands/built-in.test.ts

@@ -177,12 +177,12 @@ describe("/feedback command", () => {
       signalClear: () => {},
       submitFeedback: (text) => {
         sent.push(text);
-        return "Thanks — feedback sent.";
+        return "Thanks — feedback queued.";
       },
     };
     expect(getCommand("feedback")!.handler("love the TUI", ctx)).toEqual({
       type: "message",
-      text: "Thanks — feedback sent.",
+      text: "Thanks — feedback queued.",
     });
     expect(sent).toEqual(["love the TUI"]);
   });

src/tui/commands/built-in.ts

@@ -5,7 +5,7 @@ import {
   parseChangelog,
   resolveChangelogPath,
 } from "../../changelog/index.js";
-import { FEEDBACK_PROMPT } from "../../telemetry/feedback.js";
+import { FEEDBACK_PROMPT, isFeedbackConfigured } from "../../telemetry/feedback.js";
 
 /**
  * Register every built-in slash command.
@@ -166,10 +166,12 @@ export function registerBuiltInCommands(): void {
 
   // Intentional product feedback → PostHog survey (headless). Can ship when
   // ambient telemetry is off; env kill switches still block. Free text 2000 cap.
+  // Hidden from the slash menu until survey env ids are set (still callable).
   registerCommand({
     name: "feedback",
     description: "Send product feedback (env kill switches still apply)",
     argumentHint: "[your feedback]",
+    available: () => isFeedbackConfigured(),
     handler: (args, ctx) => {
       const text = args.trim();
       if (text.length === 0) {

src/tui/runner.ts

@@ -392,6 +392,11 @@ export function createSubmitHandler(
       return;
     }
     if (route.kind === "command") {
+      // Any other slash command drops a bare-/feedback arm so the next
+      // free-text line is not mis-routed as survey text.
+      if (feedbackPending && route.name !== "feedback") {
+        deps.cancelFeedbackCapture?.();
+      }
       deps.dispatchCommand(route.name, route.args);
       return;
     }

src/tui/submit-handler.test.ts

@@ -103,29 +103,34 @@ describe("composer submit handler", () => {
       isFeedbackCapturePending: () => isFeedbackCapturePending(),
       onFeedbackText: (text) => {
         feedbackTexts.push(text);
-        return "Thanks — feedback sent.";
+        return "Thanks — feedback queued.";
+
       },
     });
     armFeedbackCapture();
     h.submit("the UI is snappy");
     expect(feedbackTexts).toEqual(["the UI is snappy"]);
     expect(h.prompts).toEqual([]);
-    expect(h.notices).toEqual(["Thanks — feedback sent."]);
+    expect(h.notices).toEqual(["Thanks — feedback queued."]);
+
     expect(h.telemetry()).toBe(0);
   });
 
   test("slash commands still dispatch while feedback capture is pending", () => {
     const h = harness({
       isFeedbackCapturePending: () => isFeedbackCapturePending(),
+      cancelFeedbackCapture: () => {
+        cancelFeedbackCapture();
+      },
       onFeedbackText: () => "should not run",
     });
     armFeedbackCapture();
     h.submit("/help");
     expect(h.dispatched).toEqual([{ name: "help", args: "" }]);
     expect(h.prompts).toEqual([]);
     expect(h.notices).toEqual([]);
-    // Still pending — only a non-command line consumes it.
-    expect(isFeedbackCapturePending()).toBe(true);
+    // Other slash commands drop the arm so the next free-text line is a prompt.
+    expect(isFeedbackCapturePending()).toBe(false);
   });
 
   test("empty Enter while armed cancels instead of trapping the operator", () => {