Summary

When a user asks Archon to clone a project in a Docker environment, the agent follows the system prompt template (~/.archon/workspaces/) which the shell expands to $HOME/.archon/workspaces/. In the Docker container, HOME=/home/appuser, so the clone lands at /home/appuser/.archon/workspaces/ — not under the actual Archon data root /.archon/workspaces/.

This path is ephemeral and not persisted. After a container restart all git operations in worktree sessions fail with:

fatal: not a git repository: /home/appuser/.archon/workspaces/.../worktrees/thread-*

Environment

Root Cause

Two components are correct individually but inconsistent with each other:

1. getArchonHome() in packages/paths/src/archon-paths.ts:56-74 correctly returns /.archon when ARCHON_DOCKER=true.
2. The system prompt clone template uses the literal string ~/.archon/workspaces/{owner}/{repo}/source. When the agent runs this via Bash, the shell expands ~ to $HOME = /home/appuser — bypassing archon-paths.ts entirely.

The clone succeeds (git reports Cloning into '/home/appuser/.archon/workspaces/...') but into an ephemeral, non-persisted directory. On next container start the base repo is gone. Worktrees created under /.archon/worktrees/ retain .git pointer files referencing the missing path — all git operations are broken.

Concrete evidence from archon.db (reproduced live):

agent tool call:
  git clone https://github.com/ztech-gthb/ZoltiConverter-v2.git \
    ~/.archon/workspaces/ztech-gthb/ZoltiConverter-v2/source

shell output:
  "Cloning into '/home/appuser/.archon/workspaces/ztech-gthb/ZoltiConverter-v2/source'..."

DB-registered path:  /home/appuser/.archon/workspaces/ztech-gthb/ZoltiConverter-v2/source
Actual Archon root:  /.archon/workspaces/  (empty)

Impact

• Registered project paths in DB point to a non-existent location after container restart
• Worktree .git pointers broken — git status, git diff, git log all fail
• Pushes/commits require GitHub API workaround instead of normal git
• /.archon/workspaces/ remains empty despite successful clone

Expected Behavior

The clone target should resolve to /.archon/workspaces/{owner}/{repo}/source in Docker — consistent with what getArchonWorkspacesPath() already returns correctly.

Fix Options

Option A (preferred): Inject the resolved ARCHON_WORKSPACES_PATH into the system prompt at startup (value already computed correctly by getArchonWorkspacesPath()), replacing the hardcoded ~/.archon/workspaces/ template string.

Option B: In the clone/register handler, validate that the target path is under getArchonWorkspacesPath() and remap it if not.

Option C (workaround only): Set HOME=/.archon in the Dockerfile — but this is a hack and breaks other tooling expectations.

Relevant Code

• packages/paths/src/archon-paths.ts:43-49 — isDocker() detection correct
• packages/paths/src/archon-paths.ts:56-74 — getArchonHome() correct
• System prompt clone template — uses literal ~/.archon/workspaces/ — wrong in Docker