@hellcoder/companion 0.104.4-preview.20260619104321.2961437 → 0.105.0

package/server/session-types.ts

@@ -139,6 +139,12 @@ export interface CLIResultMessage {
   is_error: boolean;
   result?: string;
   errors?: string[];
+  /**
+   * HTTP status of the underlying API error, when the turn failed at the API
+   * layer (e.g. 401 for expired/invalid credentials). Present on the wire but
+   * historically untyped — declared here so auth failures can be surfaced.
+   */
+  api_error_status?: number;
   duration_ms: number;
   duration_api_ms: number;
   num_turns: number;
@@ -165,6 +171,57 @@ export interface CLIResultMessage {
   session_id: string;
 }
 
+/**
+ * User-facing guidance shown when a turn fails because the Claude credentials
+ * are missing/expired/invalid. Shared by the server (auth banner on relaunch
+ * skip) and the client (error bubble) so the wording stays consistent.
+ */
+export const AUTH_EXPIRED_MESSAGE =
+  "Your Claude login has expired or is invalid — re-authenticate (run `claude login` in a terminal), then use Reconnect to resume this session.";
+
+/**
+ * Text patterns that reliably indicate an authentication/authorization failure
+ * in free-form output (a CLI `result` message or a tail of stderr).
+ *
+ * Bare "401"/"403" and a standalone "unauthorized" are deliberately NOT matched:
+ * they appear in stack-trace line numbers, tool exit codes, file-permission
+ * messages and unrelated HTTP logs, and matching them would misclassify a
+ * RECOVERABLE crash as an auth failure — which suppresses auto-relaunch and
+ * leaves the session dead (a brand-new hang, the opposite of the intent). We
+ * require an explicit auth phrase, or a status code paired with
+ * unauthorized/forbidden. The structured `api_error_status` field (checked in
+ * isAuthErrorResult) remains the primary, reliable signal.
+ */
+const AUTH_ERROR_TEXT_RE =
+  /invalid authentication credentials|authentication_failed|\b40[13]\s+(?:unauthorized|forbidden)\b|(?:unauthorized|forbidden)[^\n]{0,12}\b40[13]\b|please run\s+`?\/?login|claude login|credentials?\s+(?:expired|invalid|revoked)|oauth token|token\s+(?:expired|revoked)/i;
+
+/**
+ * True when free-form text (a result message or stderr tail) looks like an
+ * auth/credential failure. Shared by isAuthErrorResult and the launcher's
+ * process-exit classifier so the two cannot drift.
+ */
+export function looksLikeAuthErrorText(text: string): boolean {
+  return AUTH_ERROR_TEXT_RE.test(text);
+}
+
+/**
+ * True when a CLI `result` indicates an authentication/authorization failure.
+ * The CLI reports these as a result with `is_error` and either
+ * `api_error_status` 401/403 or an auth phrase in `result`/`errors` — it does
+ * NOT populate the `errors[]` array, which is why the old `errors?.length`
+ * gate silently swallowed expired-token results.
+ */
+export function isAuthErrorResult(r: {
+  is_error?: boolean;
+  api_error_status?: number;
+  result?: string;
+  errors?: string[];
+}): boolean {
+  if (!r.is_error) return false;
+  if (r.api_error_status === 401 || r.api_error_status === 403) return true;
+  return looksLikeAuthErrorText(`${r.result ?? ""} ${(r.errors ?? []).join(" ")}`);
+}
+
 export interface CLIStreamEventMessage {
   type: "stream_event";
   event: unknown;

package/server/ws-bridge-types.ts

@@ -61,6 +61,26 @@ export interface Session {
   stateMachine: SessionStateMachine;
   /** Cleanup function for state machine transition listener — call on session teardown. */
   unsubscribeStateMachine?: () => void;
+  /**
+   * Serialized (JSON) user_message that has been dispatched to the backend but
+   * has not yet produced any model output (assistant/stream_event/result).
+   * If the CLI dies before responding, this is replayed to the relaunched
+   * `--resume` process so the prompt isn't silently lost. Cleared the moment
+   * any output for the turn arrives. Runtime-only (not persisted).
+   */
+  inFlightUserTurn?: string;
+  /**
+   * Guards against replaying a "poison" prompt that crashes the CLI on every
+   * resume: an in-flight turn is replayed at most once per turn. Reset when a
+   * new user_message is dispatched.
+   */
+  inFlightTurnReplayed?: boolean;
+  /**
+   * Set when the last turn failed authentication (expired/invalid credentials).
+   * Auto-relaunch is skipped while this is set — relaunching cannot fix auth —
+   * and a re-login banner is surfaced instead. Cleared on a successful result.
+   */
+  authBlocked?: boolean;
 }
 
 export type GitSessionKey =

package/server/ws-bridge.test.ts

@@ -547,6 +547,36 @@ describe("CLI handlers", () => {
     expect(session.state.model).toBe("claude-opus-4-6");
   });
 
+  it("clears authBlocked when the CLI (re)initializes via session_init", async () => {
+    // Regression: after an auth failure sets authBlocked=true, a freshly booted/
+    // reattached CLI (e.g. user re-ran `claude login` + Reconnect) must clear the
+    // block. Otherwise a later UNRELATED crash is wrongly treated as auth and
+    // denied keepalive relaunch, leaving the session silently dead.
+    mockExecSync.mockImplementation(() => { throw new Error("not a git repo"); });
+    const cli = makeCliSocket("s1");
+    bridge.handleCLIOpen(cli, "s1");
+    await bridge.handleCLIMessage(cli, makeInitMsg());
+
+    const session = bridge.getSession("s1")!;
+    session.authBlocked = true;
+
+    // Re-init through the adapter pipeline (the server-owned adapter path where
+    // the authBlocked clear lives).
+    const adapter = session.backendAdapter as any;
+    adapter.browserMessageCb({
+      type: "session_init",
+      session: {
+        session_id: "cli-internal",
+        model: "claude-sonnet-4-6",
+        cwd: "/test",
+        tools: [],
+        permissionMode: "default",
+      },
+    });
+
+    expect(session.authBlocked).toBe(false);
+  });
+
   it("handleCLIMessage: updates state from init (model, cwd, tools, permissionMode)", async () => {
     mockExecSync.mockImplementation(() => {
       throw new Error("not a git repo");
@@ -4795,3 +4825,151 @@ describe("User message during initializing phase", () => {
     expect(session.stateMachine.phase).toBe("streaming");
   });
 });
+
+// ─── In-flight turn replay + auth surfacing ──────────────────────────────────
+// These cover the two reported failures: (A) a user prompt sent to a CLI that
+// dies before answering must be replayed after relaunch instead of being lost
+// ("no answers"); (B) a 401 auth result must flag the session and surface an
+// auth banner instead of silently looping.
+describe("in-flight user turn replay", () => {
+  function makeAdapter(opts: { connected?: boolean; send?: any } = {}) {
+    let onBrowserMessage: ((msg: any) => void) | undefined;
+    const send = opts.send ?? vi.fn(() => true);
+    const adapter = {
+      isConnected: () => opts.connected ?? true,
+      send,
+      disconnect: async () => {},
+      onBrowserMessage: (cb: (msg: any) => void) => { onBrowserMessage = cb; },
+      onSessionMeta: () => {},
+      onDisconnect: () => {},
+      onInitError: () => {},
+    };
+    return { adapter, send, fire: (msg: any) => onBrowserMessage?.(msg) };
+  }
+
+  it("sets inFlightUserTurn on dispatch and clears it when the backend produces output", () => {
+    const browser = makeBrowserSocket("inflight-1");
+    bridge.handleBrowserOpen(browser, "inflight-1");
+    const { adapter, fire } = makeAdapter();
+    bridge.attachBackendAdapter("inflight-1", adapter as any, "codex");
+
+    bridge.handleBrowserMessage(browser, JSON.stringify({ type: "user_message", content: "do the thing" }));
+
+    const session = bridge.getSession("inflight-1")!;
+    expect(session.inFlightUserTurn).toBeDefined();
+    expect(JSON.parse(session.inFlightUserTurn!).content).toBe("do the thing");
+    expect(session.inFlightTurnReplayed).toBe(false);
+
+    // First sign of output for the turn clears the replay copy.
+    fire({ type: "stream_event", event: { type: "content_block_delta", delta: { type: "text_delta", text: "hi" } }, parent_tool_use_id: null });
+    expect(session.inFlightUserTurn).toBeUndefined();
+  });
+
+  it("replays an unanswered in-flight turn through the relaunched adapter", () => {
+    const browser = makeBrowserSocket("inflight-2");
+    bridge.handleBrowserOpen(browser, "inflight-2");
+    const first = makeAdapter();
+    bridge.attachBackendAdapter("inflight-2", first.adapter as any, "codex");
+
+    bridge.handleBrowserMessage(browser, JSON.stringify({ type: "user_message", content: "unanswered prompt" }));
+    const session = bridge.getSession("inflight-2")!;
+    expect(session.inFlightUserTurn).toBeDefined();
+    // It was delivered (send returned true), so it is NOT sitting in the queue.
+    expect(session.pendingMessages).toHaveLength(0);
+
+    // CLI dies before answering → a fresh adapter attaches (relaunch).
+    const second = makeAdapter();
+    bridge.attachBackendAdapter("inflight-2", second.adapter as any, "codex");
+
+    const replayed = (second.send.mock.calls as any[][]).find(([m]) => m?.type === "user_message");
+    expect(replayed?.[0]?.content).toBe("unanswered prompt");
+    expect(session.inFlightTurnReplayed).toBe(true);
+    expect(session.pendingMessages).toHaveLength(0);
+  });
+
+  it("does not replay the same in-flight turn twice (poison-prompt guard)", () => {
+    const browser = makeBrowserSocket("inflight-3");
+    bridge.handleBrowserOpen(browser, "inflight-3");
+    bridge.attachBackendAdapter("inflight-3", makeAdapter().adapter as any, "codex");
+    bridge.handleBrowserMessage(browser, JSON.stringify({ type: "user_message", content: "poison" }));
+
+    // First relaunch replays it.
+    bridge.attachBackendAdapter("inflight-3", makeAdapter().adapter as any, "codex");
+    const session = bridge.getSession("inflight-3")!;
+    expect(session.inFlightTurnReplayed).toBe(true);
+
+    // Second relaunch (still no answer) must NOT replay again.
+    const third = makeAdapter();
+    bridge.attachBackendAdapter("inflight-3", third.adapter as any, "codex");
+    const replayedAgain = (third.send.mock.calls as any[][]).find(([m]) => m?.type === "user_message");
+    expect(replayedAgain).toBeUndefined();
+  });
+
+  it("flags authBlocked on a 401 result and forwards it without a duplicate auth_status bubble", () => {
+    const browser = makeBrowserSocket("auth-1");
+    bridge.handleBrowserOpen(browser, "auth-1");
+    const { adapter, fire } = makeAdapter();
+    bridge.attachBackendAdapter("auth-1", adapter as any, "codex");
+    browser.send.mockClear();
+
+    fire({
+      type: "result",
+      data: {
+        type: "result",
+        subtype: "success",
+        is_error: true,
+        api_error_status: 401,
+        result: "Failed to authenticate. API Error: 401 Invalid authentication credentials",
+        duration_ms: 1,
+        duration_api_ms: 0,
+        num_turns: 1,
+        total_cost_usd: 0,
+        stop_reason: null,
+        usage: { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 },
+        uuid: "u-auth",
+        session_id: "auth-1",
+      },
+    });
+
+    const session = bridge.getSession("auth-1")!;
+    // The session is flagged so auto-relaunch is skipped (the orchestrator
+    // surfaces the re-login banner when it declines to relaunch).
+    expect(session.authBlocked).toBe(true);
+    const broadcast = (browser.send.mock.calls as any[][]).map(([raw]) => JSON.parse(raw));
+    // The raw result is forwarded so the client renders the re-login banner via
+    // describeResultError (guidance + the specific error detail)...
+    expect(broadcast.some((m: any) => m.type === "result")).toBe(true);
+    // ...and we do NOT also emit an auth_status bubble on this path — that would
+    // duplicate the same guidance in a second stacked system message.
+    expect(broadcast.some((m: any) => m.type === "auth_status")).toBe(false);
+  });
+
+  it("clears authBlocked after a subsequent successful result", () => {
+    const browser = makeBrowserSocket("auth-2");
+    bridge.handleBrowserOpen(browser, "auth-2");
+    const { adapter, fire } = makeAdapter();
+    bridge.attachBackendAdapter("auth-2", adapter as any, "codex");
+
+    const session = bridge.getSession("auth-2")!;
+    session.authBlocked = true;
+
+    fire({
+      type: "result",
+      data: {
+        type: "result",
+        subtype: "success",
+        is_error: false,
+        duration_ms: 1,
+        duration_api_ms: 0,
+        num_turns: 1,
+        total_cost_usd: 0,
+        stop_reason: "end_turn",
+        usage: { input_tokens: 1, output_tokens: 1, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 },
+        uuid: "u-ok",
+        session_id: "auth-2",
+      },
+    });
+
+    expect(session.authBlocked).toBe(false);
+  });
+});

package/server/ws-bridge.ts

@@ -7,6 +7,7 @@ import type {
   BackendType,
   McpServerConfig,
 } from "./session-types.js";
+import { isAuthErrorResult } from "./session-types.js";
 import type { SessionStore } from "./session-store.js";
 import type { IBackendAdapter } from "./backend-adapter.js";
 import { ClaudeAdapter } from "./claude-adapter.js";
@@ -442,6 +443,12 @@ export class WsBridge {
           ...cwdOverride,
           backend_type: session.backendType,
         };
+        // A freshly booted/reattached CLI invalidates any prior auth-block: the
+        // credentials may have been refreshed out-of-band (e.g. `claude login`
+        // + Reconnect). Clear it here so a later unrelated crash isn't wrongly
+        // treated as an auth failure and denied keepalive relaunch. authBlocked
+        // is re-set the moment another auth-error result arrives.
+        session.authBlocked = false;
         this.refreshGitInfo(session, { notifyPoller: true });
         this.broadcastToBrowsers(session, { type: "session_init", session: session.state });
         session.stateMachine.transition("ready", "system_init");
@@ -501,6 +508,9 @@ export class WsBridge {
 
       // -- assistant: append to history, notify listeners ------------------
       if (msg.type === "assistant") {
+        // The turn is producing output — it was delivered, so drop the in-flight
+        // replay copy (no need to re-send it after a future relaunch).
+        session.inFlightUserTurn = undefined;
         const assistantMsg = { ...msg, timestamp: msg.timestamp || Date.now() };
         this.appendHistory(session, assistantMsg);
         this.persistSession(session);
@@ -508,12 +518,29 @@ export class WsBridge {
       }
 
       if (msg.type === "stream_event") {
+        session.inFlightUserTurn = undefined;
         companionBus.emit("message:stream_event", { sessionId: session.id, message: msg });
       }
 
       // -- result: update session cost/turns, refresh git, notify listeners
       if (msg.type === "result") {
         const resultData = msg.data;
+        // The turn completed (even if it errored) — no replay needed.
+        session.inFlightUserTurn = undefined;
+        // Detect auth failures (expired/invalid credentials). The CLI keeps
+        // running in stream-json mode, so this is the primary auth signal — not
+        // a process exit. Flag the session so auto-relaunch is skipped (the
+        // orchestrator surfaces a re-login banner when it declines to relaunch).
+        // We do NOT broadcast auth_status here: the raw result is forwarded to
+        // browsers below (catch-all broadcast) and the client renders it via
+        // describeResultError, which already includes the re-login guidance plus
+        // the specific error detail — a second auth_status bubble would just
+        // duplicate that same guidance.
+        if (isAuthErrorResult(resultData)) {
+          session.authBlocked = true;
+        } else if (!resultData.is_error) {
+          session.authBlocked = false;
+        }
         session.state.total_cost_usd = resultData.total_cost_usd;
         session.state.num_turns = resultData.num_turns;
         if (typeof resultData.total_lines_added === "number") {
@@ -674,6 +701,28 @@ export class WsBridge {
       this.broadcastToBrowsers(session, { type: "error", message: error });
     });
 
+    // Replay a turn that was dispatched but never answered before the previous
+    // CLI died. --resume restores the conversation context but does NOT re-run
+    // an unanswered prompt, so without this the relaunched session sits idle
+    // forever ("no answer"). Replay at most once per turn to avoid a poison
+    // prompt looping the CLI. Prepended so it runs ahead of any later queue.
+    if (
+      !isLegacyWsClaude &&
+      session.inFlightUserTurn &&
+      !session.inFlightTurnReplayed &&
+      !session.pendingMessages.includes(session.inFlightUserTurn)
+    ) {
+      session.pendingMessages.unshift(session.inFlightUserTurn);
+      session.inFlightTurnReplayed = true;
+      log.info("ws-bridge", "Replaying in-flight user turn after relaunch", {
+        sessionId,
+      });
+      this.broadcastToBrowsers(session, {
+        type: "error",
+        message: "Reconnected — re-sending your last message, which the previous session didn't answer.",
+      });
+    }
+
     // Flush pending messages for server-owned backends (Codex + stdio Claude),
     // where attachment is the transport-open event. The legacy WS Claude
     // transport flushes in handleCLIOpen after attachWebSocket instead.
@@ -1170,6 +1219,16 @@ export class WsBridge {
       }
       this.persistSession(session);
       this.broadcastToBrowsers(session, userMessage);
+      // Track this turn as in-flight so it can be replayed if the CLI dies
+      // before answering. Stored as the original outgoing message so the
+      // relaunch flush can re-send it verbatim. A new turn resets the
+      // one-shot replay guard.
+      session.inFlightUserTurn = JSON.stringify(msg);
+      session.inFlightTurnReplayed = false;
+      // A fresh turn is an attempt to make progress (e.g. after the user
+      // re-authenticated), so clear any stale auth-block — a genuine crash on
+      // this new turn should be allowed to auto-relaunch again.
+      session.authBlocked = false;
     }
 
     // -- permission_response: populate updatedInput fallback from pending, then remove -------