fix(claude): derive usage and name login or limit errors

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

@@ -11,6 +11,7 @@ import * as Path from "effect/Path";
 import { subscriptionRuntimeEnvironment } from "../../subscription-auth/runtime.ts";
 import { SubscriptionAuthService } from "../../subscription-auth/service.ts";
 import {
+  claudeSignedOutMessage,
   makeClaudeCapabilitiesCacheKey,
   makeClaudeContinuationGroupKey,
   makeClaudeEnvironment,
@@ -44,6 +45,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("marks CLAUDE_CONFIG_DIR explicit so saved API keys do not replace the account", () =>
       Effect.gen(function* () {
         const secretsDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "akeru-claude-home-"));

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

@@ -3,10 +3,13 @@ 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";
 import { withExplicitEnvironmentKeys } from "../../subscription-auth/runtime.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> {
@@ -51,3 +54,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.`;
+};