---
phase: 06-default-repos-ssh-mount
plan: 01
subsystem: infra
tags: docker, ssh, volume-mounts, hermes, git, bitbucket

requires:
  - phase: 05-hermes-memory-hindsight
    provides: Hermes config structure, .env conventions
provides:
  - SSH key mounts for Bitbucket git auth
  - 3 default repo mounts (rai-ops, rai-deployment, rai-devtools)
  - session-init.sh mount verification script
  - DEFAULT_REPOS environment variable

affects: [07-session-skill, 08-cron-reporting]

tech-stack:
  added:
    - session-init.sh (bash script)
  patterns:
    - Per-file SSH key mounts (`:ro`) instead of full directory mount
    - Non-blocking shell init scripts (no `set -e`)
    - Subpath volume mounts with `:rw` parent dependency

key-files:
  created:
    - ~/.hermes/scripts/session-init.sh
  modified:
    - ~/.hermes/.env
    - ~/.hermes/config.yaml

key-decisions:
  - "Mounted SSH keys per-file (`:ro`) rather than full `~/.ssh/` directory — limits credential exposure to only id_ed25519razer and id_rsa"
  - "Mounted repos directly from host (`:rw`) instead of cloning inside container — preserves git worktrees, branches, uncommitted changes"
  - "Included `known_hosts` mount — prevents SSH host key prompt from blocking non-interactive git operations"
  - "session-init.sh uses `set -uo pipefail` (not `-e`) — session starts even if repos are missing"
  - "Parent `/workspace` mount verified `:rw` — subpath volume mounts work correctly"

patterns-established:
  - "Pattern 1: Per-file credential mounts for limited security boundary"
  - "Pattern 2: Non-blocking init scripts with graceful degradation"

requirements-completed: [REPO-01, REPO-02]

duration: 2 min
completed: 2026-06-15
---

# Phase 6 Plan 1: Default Repos & SSH Mount Summary

**SSH key mounts for Bitbucket auth, 3 default repo mounts (rai-ops, rai-deployment, rai-devtools), and session-init.sh non-blocking verification script — all verified end-to-end via Docker test container**

## Performance

- **Duration:** 2 min
- **Started:** 2026-06-15T12:03:47Z
- **Completed:** 2026-06-15T12:05:58Z
- **Tasks:** 3
- **Files modified:** 3

## Accomplishments

- SSH keys (`id_ed25519razer`, `id_rsa`, `config`, `known_hosts`) mounted read-only into Docker — Bitbucket auth verified: "authenticated via ssh key"
- 3 default repos (rai-ops, rai-deployment, rai-devtools) mounted at `/workspace/<name>` with `:rw` — no re-cloning needed across sessions
- `session-init.sh` created in `~/.hermes/scripts/` — non-blocking verification at shell start, triggered via `shell_init_files`
- `DEFAULT_REPOS` env var added to `.env` and forwarded into container via `docker_forward_env`
- On-demand git clone verified working (REPO-02 capability)
- Parent `/workspace` mount confirmed `:rw` — subpath volumes will not fail

## Task Commits

Each task was committed atomically:

1. **Task 1: Create session-init.sh script** — `ea56c05` (feat)
2. **Task 2: Update .env and config.yaml** — `2c3e96b` (feat)
3. **Task 3: Verify end-to-end Docker test** — `2ca590e` (test)

**Plan metadata:** (committed with SUMMARY below)

## Files Created/Modified

- `~/.hermes/scripts/session-init.sh` — Non-blocking mount verification script (25 lines)
- `~/.hermes/.env` — Added `DEFAULT_REPOS=rai-ops,rai-deployment,rai-devtools`
- `~/.hermes/config.yaml` — Added 4 SSH key mounts (`:ro`), 3 repo mounts (`:rw`), `shell_init_files`, `docker_forward_env` entry

## Decisions Made

- **Per-file SSH key mounts** over full `~/.ssh/` directory mount — limits credential exposure to only the keys the agent needs (id_ed25519razer, id_rsa)
- **`known_hosts` included** — without it, SSH prompts for host key confirmation and hangs in non-interactive container; host already has bitbucket.org keys
- **session-init.sh uses `set -uo pipefail`** (not `-e`) — missing repos won't abort session start
- **Host-direct repo mounts** (`:rw`) instead of cloning — preserves existing worktrees, branches, and is not lost on container restart

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] `rai-ansible` repo inaccessible for clone test**
- **Found during:** Task 3 (End-to-end verification)
- **Issue:** Plan specified `rai-ansible` for on-demand clone test, but this repo does not exist or the SSH key lacks access
- **Fix:** Used `rai-ops` (known accessible repo) for clone test, cloning to a different path (`/tmp/rai-ops-test`)
- **Files modified:** None (verification only)
- **Verification:** Clone succeeded, git repo contents visible
- **Committed in:** `2ca590e` (Task 3 commit)

**2. [Rule 3 - Blocking] Python `yaml` module not installed for validation**
- **Found during:** Task 2 (config.yaml verification)
- **Issue:** Python yaml module not available on host, blocking automated YAML validation
- **Fix:** Installed pyyaml 6.0.3 via pip3
- **Files modified:** None (host package, not in repo)
- **Verification:** All 10 YAML assertions passed
- **Committed in:** `2c3e96b` (Task 2 commit)

---

**Total deviations:** 2 auto-fixed (2 blocking)
**Impact on plan:** Both deviations minor — clone test used correct accessible repo, pyyaml installed temporarily for validation. No scope creep.

## Issues Encountered

- `rai-ansible` repo not accessible to the SSH key — used `rai-ops` cloned to alternate path instead. SSH auth itself is confirmed working.
- Python `yaml` module not installed on host — installed pyyaml for config validation.
- No pre-existing issues found.

## User Setup Required

None - no external service configuration required. SSH keys and repos already exist on the host filesystem. Changes to `~/.hermes/config.yaml` and `~/.hermes/.env` are ready for next Hermes session.

## Next Phase Readiness

- SSH auth and repo mounts fully verified — ready for Phase 7 (session skill)
- `session-init.sh` provides lightweight mount verification at shell start
- `DEFAULT_REPOS` is configurable via `.env` — user edits one variable + docker_volumes to add/remove repos
- On-demand clone capability verified — agent can clone additional repos during sessions

## Self-Check: PASSED

All commits verified, all files exist, all acceptance criteria met.

---

*Phase: 06-default-repos-ssh-mount*
*Completed: 2026-06-15*