fix(shell): sync github auth env and improve docker error handling

Author: skulidropek

README.md

@@ -101,6 +101,47 @@ MCP errors in `codex` UI:
 - `handshaking ... initialize response`:
   - The configured MCP command is not a real MCP server (example: `command="echo"`).
 
+Docker permission error (`/var/run/docker.sock`):
+- Symptom:
+  - `permission denied while trying to connect to the docker API at unix:///var/run/docker.sock`
+- Check:
+  ```bash
+  id
+  ls -l /var/run/docker.sock
+  docker version
+  ```
+- Fix (works in `fish` and `bash`):
+  ```bash
+  sudo chgrp docker /var/run/docker.sock
+  sudo chmod 660 /var/run/docker.sock
+  sudo mkdir -p /etc/systemd/system/docker.socket.d
+  printf '[Socket]\nSocketGroup=docker\nSocketMode=0660\n' | sudo tee /etc/systemd/system/docker.socket.d/override.conf >/dev/null
+  sudo systemctl daemon-reload
+  sudo systemctl restart docker.socket docker
+  ```
+- Verify:
+  ```bash
+  ls -l /var/run/docker.sock
+  docker version
+  ```
+- Note:
+  - Do not run `pnpm run docker-git ...` with `sudo`.
+
+Clone auth error (`Invalid username or token`):
+- Symptom:
+  - `remote: Invalid username or token. Password authentication is not supported for Git operations.`
+- Check and fix token:
+  ```bash
+  pnpm run docker-git auth github status
+  pnpm run docker-git auth github logout
+  pnpm run docker-git auth github login --token '<GITHUB_TOKEN>'
+  pnpm run docker-git auth github status
+  ```
+- Token requirements:
+  - Token must have access to the target repository.
+  - For org repositories with SSO/SAML, authorize the token for that organization.
+  - Recommended scopes: `repo,workflow,read:org`.
+
 ## Security Notes
 
 The generated Codex config uses:

packages/app/src/docker-git/program.ts

@@ -117,6 +117,7 @@ export const program = pipe(
       Effect.logWarning(renderError(error)),
       Effect.asVoid
     )),
+  Effect.catchTag("DockerCommandError", logWarningAndExit),
   Effect.catchTag("AuthError", logWarningAndExit),
   Effect.catchTag("CommandFailedError", logWarningAndExit),
   Effect.matchEffect({

packages/lib/src/usecases/auth-sync.ts

@@ -3,6 +3,7 @@ import type * as FileSystem from "@effect/platform/FileSystem"
 import type * as Path from "@effect/platform/Path"
 import { Effect } from "effect"
 
+import { parseEnvEntries, removeEnvKey, upsertEnvKey } from "./env-file.js"
 import { withFsPathContext } from "./runtime.js"
 
 type CopyDecision = "skip" | "copy"
@@ -69,6 +70,69 @@ const shouldCopyEnv = (sourceText: string, targetText: string): CopyDecision =>
   return "skip"
 }
 
+const isGithubTokenKey = (key: string): boolean =>
+  key === "GITHUB_TOKEN" || key === "GH_TOKEN" || key.startsWith("GITHUB_TOKEN__")
+
+// CHANGE: synchronize GitHub auth keys between env files
+// WHY: avoid stale per-project tokens that cause clone auth failures after token rotation
+// QUOTE(ТЗ): n/a
+// REF: user-request-2026-02-11-clone-invalid-token
+// SOURCE: n/a
+// FORMAT THEOREM: ∀k ∈ github_token_keys: source(k)=v → merged(k)=v
+// PURITY: CORE
+// INVARIANT: non-auth keys in target are preserved
+// COMPLEXITY: O(n) where n = |env entries|
+export const syncGithubAuthKeys = (sourceText: string, targetText: string): string => {
+  const sourceTokenEntries = parseEnvEntries(sourceText).filter((entry) => isGithubTokenKey(entry.key))
+  if (sourceTokenEntries.length === 0) {
+    return targetText
+  }
+
+  const targetTokenKeys = parseEnvEntries(targetText)
+    .filter((entry) => isGithubTokenKey(entry.key))
+    .map((entry) => entry.key)
+
+  let next = targetText
+  for (const key of targetTokenKeys) {
+    next = removeEnvKey(next, key)
+  }
+  for (const entry of sourceTokenEntries) {
+    next = upsertEnvKey(next, entry.key, entry.value)
+  }
+
+  return next
+}
+
+const syncGithubTokenKeysInFile = (
+  sourcePath: string,
+  targetPath: string
+): Effect.Effect<void, PlatformError, FileSystem.FileSystem | Path.Path> =>
+  withFsPathContext(({ fs }) =>
+    Effect.gen(function*(_) {
+      const sourceExists = yield* _(fs.exists(sourcePath))
+      if (!sourceExists) {
+        return
+      }
+      const targetExists = yield* _(fs.exists(targetPath))
+      if (!targetExists) {
+        return
+      }
+      const sourceInfo = yield* _(fs.stat(sourcePath))
+      const targetInfo = yield* _(fs.stat(targetPath))
+      if (sourceInfo.type !== "File" || targetInfo.type !== "File") {
+        return
+      }
+
+      const sourceText = yield* _(fs.readFileString(sourcePath))
+      const targetText = yield* _(fs.readFileString(targetPath))
+      const mergedText = syncGithubAuthKeys(sourceText, targetText)
+      if (mergedText !== targetText) {
+        yield* _(fs.writeFileString(targetPath, mergedText))
+        yield* _(Effect.log(`Synced GitHub auth keys from ${sourcePath} to ${targetPath}`))
+      }
+    })
+  )
+
 const copyFileIfNeeded = (
   sourcePath: string,
   targetPath: string
@@ -249,6 +313,7 @@ export const syncAuthArtifacts = (
       const targetCodex = resolvePathFromBase(path, spec.targetBase, spec.target.codexAuthPath)
 
       yield* _(copyFileIfNeeded(sourceGlobal, targetGlobal))
+      yield* _(syncGithubTokenKeysInFile(sourceGlobal, targetGlobal))
       yield* _(copyFileIfNeeded(sourceProject, targetProject))
       yield* _(fs.makeDirectory(targetCodex, { recursive: true }))
       if (sourceCodex !== targetCodex) {

packages/lib/src/usecases/errors.ts

@@ -44,7 +44,10 @@ const renderPrimaryError = (error: NonParseError): string | null => {
   }
 
   if (error._tag === "DockerCommandError") {
-    return `docker compose failed with exit code ${error.exitCode}`
+    return [
+      `docker compose failed with exit code ${error.exitCode}`,
+      "Hint: ensure Docker daemon is running and current user can access /var/run/docker.sock (for example via the docker group)."
+    ].join("\n")
   }
 
   if (error._tag === "CloneFailedError") {

packages/lib/tests/usecases/auth-sync.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "@effect/vitest"
+
+import { syncGithubAuthKeys } from "../../src/usecases/auth-sync.js"
+
+describe("syncGithubAuthKeys", () => {
+  it("updates github token keys from source and preserves non-auth target keys", () => {
+    const source = [
+      "# docker-git env",
+      "# KEY=value",
+      "GITHUB_TOKEN=token_new",
+      "GITHUB_TOKEN__WORK=token_work",
+      "SOME_SOURCE_ONLY=value",
+      ""
+    ].join("\n")
+    const target = [
+      "# docker-git env",
+      "# KEY=value",
+      "GITHUB_TOKEN=token_old",
+      "GH_TOKEN=legacy_old",
+      "CUSTOM_FLAG=1",
+      ""
+    ].join("\n")
+
+    const next = syncGithubAuthKeys(source, target)
+
+    expect(next).toContain("GITHUB_TOKEN=token_new")
+    expect(next).toContain("GITHUB_TOKEN__WORK=token_work")
+    expect(next).not.toContain("GH_TOKEN=legacy_old")
+    expect(next).toContain("CUSTOM_FLAG=1")
+  })
+
+  it("keeps target unchanged when source has no github token keys", () => {
+    const source = [
+      "# docker-git env",
+      "# KEY=value",
+      "UNRELATED=1",
+      ""
+    ].join("\n")
+    const target = [
+      "# docker-git env",
+      "# KEY=value",
+      "GITHUB_TOKEN=token_old",
+      "CUSTOM_FLAG=1",
+      ""
+    ].join("\n")
+
+    const next = syncGithubAuthKeys(source, target)
+
+    expect(next).toBe(target)
+  })
+})

packages/lib/tests/usecases/errors.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "@effect/vitest"
+
+import { DockerCommandError } from "../../src/shell/errors.js"
+import { renderError } from "../../src/usecases/errors.js"
+
+describe("renderError", () => {
+  it("includes docker daemon access hint for DockerCommandError", () => {
+    const message = renderError(new DockerCommandError({ exitCode: 1 }))
+
+    expect(message).toContain("docker compose failed with exit code 1")
+    expect(message).toContain("/var/run/docker.sock")
+  })
+})