fix(docker): create /.archon subdirs in entrypoint for bind mounts (#1260)

[leex279]

Summary

Fixes #1260 — Docker bind mounts break startup because /.archon/workspaces does not exist inside the container, causing the Claude subprocess to spawn with a missing cwd and silently time out after 60s.

Root Cause

• The Dockerfile creates /.archon/workspaces and /.archon/worktrees via RUN mkdir -p (Dockerfile:125).
• Named volumes inherit these directories from the image layer on first run, so the app works out of the box.
• Bind mounts replace the image-layer content with the host directory, so the subdirectories are never created — orchestrator-agent.ts then spawns Claude with a non-existent cwd and the SDK fails silently.

Fix

Add mkdir -p /.archon/workspaces /.archon/worktrees at the top of docker-entrypoint.sh (before the chown). This is:

• Idempotent — no-op on named volumes where the dirs already exist
• Minimal — 1 line of behavior, 3 lines of comment explaining the why
• Correct timing — runs before chown -Rh appuser:appuser /.archon, so freshly-created dirs get the right ownership

Test Plan

• docker compose up -d with ARCHON_DATA unset (named volume): app starts, messages get responses (no regression)
• docker compose up -d with ARCHON_DATA=/some/empty/host/path (bind mount): app starts, sending "hi" in the Web UI gets a response (previously timed out)
• Verify /.archon/workspaces and /.archon/worktrees exist inside the container and are owned by appuser in both cases

Summary by CodeRabbit

• Chores
  • Improved Docker startup initialization to ensure proper directory structure creation before application startup.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 031a6441-80ad-4cca-b272-a35668c1cfdf

📥 Commits

Reviewing files that changed from the base of the PR and between 301a139 and a7337d6.

📒 Files selected for processing (1)

• docker-entrypoint.sh

---

📝 Walkthrough

Walkthrough

The docker-entrypoint.sh script now creates the /.archon/workspaces and /.archon/worktrees directories via mkdir -p before privilege dropping. This ensures these directories exist when using bind mounts, preventing silent subprocess failures that previously caused timeouts.

Changes

Cohort / File(s)	Summary
Docker Entrypoint Setup docker-entrypoint.sh	Added early directory creation for /.archon/workspaces and /.archon/worktrees to ensure subdirectories exist for both named volumes and bind mount scenarios.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 A rabbit hops to fix the path,
Where bind mounts caused such painful wrath,
Now directories bloom before we go,
No timeouts now—just subprocess flow!
✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides a clear summary with problem statement, root cause analysis, and fix explanation. However, it lacks several required template sections including architecture diagrams, label snapshot, validation evidence, security impact, compatibility, human verification, and rollback plan.	Complete the description by adding the missing template sections, particularly validation evidence (test results from the checklist), security impact analysis, compatibility notes, and rollback plan.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: creating /.archon subdirectories in the Docker entrypoint to fix bind mount issues.
Linked Issues check	✅ Passed	The code changes directly address all primary coding requirements from issue #1260: creating subdirectories before ownership changes, idempotent operation, and proper timing before chown.
Out of Scope Changes check	✅ Passed	All changes are scoped to the docker-entrypoint.sh startup script and are directly necessary to fix the bind mount issue described in issue #1260.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-1260-docker-bind-mount-dirs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[leex279]

Code Review

Target: PR #1272 — fix(docker): create /.archon subdirs in entrypoint for bind mounts (#1260)
Date: 2026-04-17
Files Reviewed: 1 (docker-entrypoint.sh, +5 / -0)
Verdict: APPROVE

---

Summary

Minimal, correct fix for a real bug. The root cause in #1260 is verified: orchestrator-agent.ts:800 spawns the Claude subprocess with getArchonWorkspacesPath() as cwd (resolves to /.archon/workspaces in Docker), and bind mounts don't inherit the image-layer mkdir from Dockerfile:125. Adding mkdir -p in the entrypoint is the right place to fix it — idempotent for named volumes, corrective for bind mounts, and positioned before the chown so newly-created dirs get the right ownership.

Implementation Context

Artifact	Path
Implementation Report	Not found (trivial fix, no report needed)
Original Plan	Not found (fix was specified in issue #1260)
Documented Deviations	N/A

---

Critical Issues

None.

High Priority

None.

Medium Priority

None.

Low Priority / Nits

None worth raising. The comment already captures the non-obvious "why" (bind mount vs named volume semantics), which is exactly what CLAUDE.md asks for.

---

Edge Cases Considered

Scenario	Outcome
Named volume (existing setup)	mkdir -p is a no-op — no regression
Bind mount with empty host dir	Dirs created, chown fixes ownership, Claude cwd resolves — fixes the reported bug
Non-root runtime (e.g. Kubernetes --user)	If /.archon isn't writable by the user, mkdir -p fails under set -e — louder than current silent 60s timeout, which is an improvement
/.archon itself missing	mkdir -p creates it as a regular dir in the container layer; chown succeeds. Current code would fail at chown -Rh on a missing target
Re-entry (container restart)	Idempotent — safe to run repeatedly

Placement Rationale

The mkdir -p is placed before the root/non-root branch rather than inside the root branch. This is correct because the bug surfaces regardless of which user runs the entrypoint — the SDK failure mode is "cwd doesn't exist," not "cwd has wrong ownership." Placing it earlier means the non-root Kubernetes case is also fixed.

When running as root, the dirs are created as root and the subsequent chown -Rh appuser:appuser /.archon fixes ownership — so no ownership regression.

---

Validation Results

Check	Status	Details
Shell syntax (bash -n)	PASS	Clean
Type Check	N/A	No TS changes
Lint	N/A	No TS changes
Tests	N/A	No test suite exists for this shell script
Full validation (bun run validate)	Not executed	Unrelated to the change; would test code paths not touched by this PR

The only way to meaningfully validate this change is a Docker-based smoke test (named volume + bind mount), which is documented in the PR test plan for a human to run.

Pattern Compliance

• Follows existing script style (bash, set -e, comments above behavior)
• Explains the non-obvious "why" in a comment (CLAUDE.md guidance)
• Minimal scope — no refactor, no drive-by changes (CLAUDE.md "Reversibility" principle)
• Idempotent and safe to revert (single commit, one file)
• No AI attribution in commit/PR

What's Good

• Root cause correctly diagnosed: The fix addresses the actual SDK spawn failure, not a symptom.
• Minimal blast radius: Single file, 5 lines, trivially revertable.
• Comment quality: Three lines of comment for one line of behavior — reader learns bind-mount vs named-volume semantics without hunting through issue history.
• Placement is right: Before chown means ownership is fixed in one pass.

Recommendation

APPROVE

This is a textbook small fix — correct diagnosis, minimal change, right placement, good comment. The only thing a human still needs to do is the bind-mount smoke test on a Linux or macOS Docker host to confirm end-to-end.