fix: improve error handling in onboarding bypass

- Handle timeout as expected (claude -p writes config before API call)
- Catch FileNotFoundError/OSError if claude is not installed
- Check returncode explicitly instead of dead CalledProcessError catch
- Guard on ~/.claude.json existence before writing onboarding flag
- Replace contextlib.suppress with explicit try/except that logs
- Update module docstring and README wording

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: akshithg

README.md

@@ -116,15 +116,15 @@ claude          # Ready to work
 
 ## Token-Based Auth (Headless)
 
-For non-interactive setups (CI, headless servers, or skipping the login wizard):
+For headless servers or to skip the interactive login wizard:
 
 ```bash
 claude setup-token                          # run on host, one-time
 export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
 devc rebuild                                # rebuilds with token
 ```
 
-The token is forwarded into the container. On first create, `post_install.py` runs a one-shot auth handshake so `claude` starts without the login wizard.
+The token is forwarded into the container. On each container creation, `post_install.py` runs a one-shot auth handshake so `claude` starts without the login wizard.
 
 This works around Claude Code's interactive onboarding wizard always showing in containers, even with valid credentials ([#8938](https://github.com/anthropics/claude-code/issues/8938)).
 

post_install.py

@@ -2,6 +2,7 @@
 """Post-install configuration for Claude Code devcontainer.
 
 Runs on container creation to set up:
+- Onboarding bypass (when CLAUDE_CODE_OAUTH_TOKEN is set)
 - Claude settings (bypassPermissions mode)
 - Tmux configuration (200k history, mouse support)
 - Directory ownership fixes for mounted volumes
@@ -16,10 +17,14 @@
 
 
 def setup_onboarding_bypass():
-    """Bypass the interactive onboarding wizard using CLAUDE_CODE_OAUTH_TOKEN.
+    """Bypass the interactive onboarding wizard when CLAUDE_CODE_OAUTH_TOKEN is set.
+
+    Runs `claude -p` to seed ~/.claude.json with auth state. The subprocess
+    writes the config file during startup before the API call completes, so
+    a timeout is expected and acceptable. After the subprocess finishes (or
+    times out), we check whether ~/.claude.json was populated and only then
+    set hasCompletedOnboarding.
 
-    When a token is set, runs a one-shot `claude -p` to populate auth state,
-    then marks onboarding as complete so the TUI skips the login wizard.
     Workaround for https://github.com/anthropics/claude-code/issues/8938.
     """
     token = os.environ.get("CLAUDE_CODE_OAUTH_TOKEN", "").strip()
@@ -32,25 +37,51 @@ def setup_onboarding_bypass():
 
     claude_json = Path.home() / ".claude.json"
 
-    # Run a one-shot claude -p to trigger non-interactive auth
     print("[post_install] Running claude -p to populate auth state...", file=sys.stderr)
     try:
-        subprocess.run(
+        result = subprocess.run(
             ["claude", "-p", "ok"],
             capture_output=True,
             text=True,
             timeout=30,
         )
-    except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
-        print(f"[post_install] Warning: claude -p failed: {e}", file=sys.stderr)
+        if result.returncode != 0:
+            print(
+                f"[post_install] claude -p exited {result.returncode}: "
+                f"{result.stderr.strip()}",
+                file=sys.stderr,
+            )
+    except subprocess.TimeoutExpired:
+        print(
+            "[post_install] claude -p timed out (expected on cold start)",
+            file=sys.stderr,
+        )
+    except (FileNotFoundError, OSError) as e:
+        print(
+            f"[post_install] Warning: could not run claude ({e}) — "
+            "onboarding bypass skipped",
+            file=sys.stderr,
+        )
+        return
 
-    # Read existing ~/.claude.json or start fresh
-    config = {}
-    if claude_json.exists():
-        with contextlib.suppress(json.JSONDecodeError):
-            config = json.loads(claude_json.read_text())
+    if not claude_json.exists():
+        print(
+            f"[post_install] Warning: {claude_json} not created by claude -p — "
+            "onboarding bypass skipped",
+            file=sys.stderr,
+        )
+        return
+
+    config: dict = {}
+    try:
+        config = json.loads(claude_json.read_text())
+    except json.JSONDecodeError as e:
+        print(
+            f"[post_install] Warning: {claude_json} has invalid JSON ({e}), "
+            "starting fresh",
+            file=sys.stderr,
+        )
 
-    # Mark onboarding as complete
     config["hasCompletedOnboarding"] = True
 
     claude_json.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")