fix(claude): name the expired login or usage limit instead of a generic API error

apps/server/src/provider/Drivers/ClaudeHome.test.ts

@@ -6,6 +6,7 @@ import * as Effect from "effect/Effect";
 import * as Path from "effect/Path";
 
 import {
+  claudeSignedOutMessage,
   makeClaudeCapabilitiesCacheKey,
   makeClaudeContinuationGroupKey,
   makeClaudeEnvironment,
@@ -39,6 +40,17 @@ it.layer(NodeServices.layer)("ClaudeHome", (it) => {
       }),
     );
 
+    it("points the signed-out hint at the configured Claude home", () => {
+      expect(claudeSignedOutMessage({ configDir: undefined, cwd: "/synthetic" })).toContain(
+        "run `claude auth login`",
+      );
+      const configDir = "/synthetic/Claude work's $literal";
+      const message = claudeSignedOutMessage({ configDir, cwd: "/synthetic/project" });
+      expect(message).toContain(`CLAUDE_CONFIG_DIR set to "${configDir}"`);
+      expect(message).not.toContain("CLAUDE_CONFIG_DIR=");
+      expect(message).toContain("then start a new thread");
+    });
+
     it.effect("separates capability probes by cwd", () =>
       Effect.gen(function* () {
         const config = { binaryPath: "claude", homePath: "" };

apps/server/src/provider/Drivers/ClaudeHome.ts

@@ -3,9 +3,12 @@ import * as NodeOS from "node:os";
 import type { ClaudeSettings } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
 
 import { expandHomePath } from "../../pathExpansion.ts";
 
+const quotePath = Schema.encodeSync(Schema.fromJsonString(Schema.String));
+
 export const resolveClaudeHomePath = Effect.fn("resolveClaudeHomePath")(function* (
   config: Pick<ClaudeSettings, "homePath">,
 ): Effect.fn.Return<string, never, Path.Path> {
@@ -50,3 +53,18 @@ export const makeClaudeCapabilitiesCacheKey = Effect.fn("makeClaudeCapabilitiesC
     return `${config.binaryPath}\0${resolvedHomePath}\0${cwd ?? ""}`;
   },
 );
+
+/**
+ * Describe the spawned CLI's environment separately from the login command so
+ * paths remain literal on every shell, including relative inherited values.
+ */
+export const claudeSignedOutMessage = (input: {
+  readonly configDir: string | undefined;
+  readonly cwd: string;
+}): string => {
+  const configuration =
+    input.configDir !== undefined
+      ? ` from ${quotePath(input.cwd)}, with CLAUDE_CONFIG_DIR set to ${quotePath(input.configDir)}`
+      : "";
+  return `Claude could not authenticate. For subscription login, run \`claude auth login\` on this environment's machine${configuration}, then start a new thread. For API-key authentication, check this instance's configured credentials.`;
+};