multi-agent-mux/docs/design/reviews/review-agy-fd384d6b.md

Design Review Report: Worktree Creator Operating Model

Reviewer: Antigravity (herdr:reviewer-agy-01) Job ID: fd384d6b Target Document: docs/design/worktree-creator-model.md Branch / Commit: design/worktree-model @ fe96db1 Date: 2026-09-14 Status: Review Complete

---

1. Executive Summary

The proposal in docs/design/worktree-creator-model.md addresses two critical limitations resulting from MAM's historical assumption that "workspace" == "single checkout path":

1. Inability to run concurrent issue workflows: Multiple feature branches cannot be checked out simultaneously in a single working tree.
2. Accidental branch switching collisions: In Issue #18, a checkout switch caused 12 consecutive commits to accumulate directly on main without isolation.

The proposal evaluates three candidate models:

• Candidate A (Full Worktree Isolation): Spawns 5 full agent instances per issue/worktree.
• Candidate B (Orchestrator-Only Worktree): Isolates orchestrator commits while keeping all agents in the root checkout.
• Candidate C (Proposed - Worktree Creator with Shared Reviewer Pool): Isolates only mutating agents (Creators) in dedicated git worktrees while sharing a persistent, read-only Reviewer pool and centralized .mam control plane in the root checkout.

Recommendation

Candidate C is fundamentally sound, resource-efficient, and practical. It minimizes token quota consumption while providing strict git branch isolation for code modifications. With the targeted code supplements detailed below (addressing brief path relativity, loop runner worktree diff collection, reviewer test isolation, and worktree lifecycle cleanup), Candidate C is fully adoptable.

---

2. Responses to Document §6 Questions

Q1: Does Candidate C's role separation solve the two problems? What failure paths are missed?

• Verdict: Agree with Supplement (보완).
• Analysis:
  • Branch Switching Collision: Resolved completely. The Creator is the only agent that edits source code and creates git commits. Binding the Creator's cwd to $WT (e.g. fix/issue-20) guarantees that commits can only land on the issue branch. Even if another process alters HEAD in $MAIN, the worktree's HEAD remains untouched.
  • Parallelism: Resolved for implementation. Multiple Creators can work simultaneously on separate worktrees without filesystem contention.
• Missed Failure Paths & Countermeasures:
  1. Reviewer Test Pollution in Worktree: §3 states that reviewers run tests in the worktree path ($WT). However, standard test runners (e.g. pytest) create untracked artifacts (.pytest_cache, __pycache__, .pyc, and temporary scratch files) directly in $WT. This contaminates the Creator's working tree and risks accidental inclusion in git commits. Countermeasure: Reviewers must run verification with cache suppression (e.g., PYTHONDONTWRITEBYTECODE=1 pytest -o cache_dir=/tmp/...), or tests must be executed with --basetemp outside $WT.
  2. Stale Session Rows After Worktree Deletion: When an issue branch is merged and $WT is unlinked (git worktree remove $WT), the Creator session row in agent-sessions.yaml still records pane.cwd: $WT. If the session is resumed or reconciled later, missing paths can trigger errors. Countermeasure: Establish a documented retirement procedure (scripts/worktree_remove.sh) enforcing that multi-agent-mux-stop --session <name> --purge runs before git worktree remove.

---

Q2: Is control plane sharing via environment override safe in current code?

• Verdict: Agree with Supplement (보완).
• Analysis across Skill Tooling:
  • lib.sh:26: Correctly prioritizes ${WORKSPACE_ROOT:-$SKILL_DIR/../..}. Overriding WORKSPACE_ROOT="$MAIN", AGENT_SESSIONS_YAML="$MAIN/.mam/agent-sessions.yaml", MAM_JOBS_DIR="$MAIN/.mam/jobs", and DELEGATE_JOB_LOGS_DIR successfully routes all state into the primary repository.
  • multi-agent-mux-create/scripts/create_session.sh:309: Records pane.cwd: $WORKSPACE ($WT) in the YAML row, while registering into $AGENT_SESSIONS_YAML.
  • multi-agent-mux-monitor/scripts/reconcile.sh:745-752: Drift C conversation discovery uses cwd = (s.get('pane') or {}).get('cwd', '') and key = workspace_key(cwd). Because Claude stores conversations under ~/.claude/projects/<key> derived from cwd, Claude conversation IDs are accurately resolved against $WT!
  • multi-agent-mux-status/scripts/status.sh:59, 220: Accurately reads pane.cwd and displays the worktree directory without drift errors.
  • multi-agent-mux-stop/scripts/stop_session.sh:133, 143: Retrieves TARGET_CWD directly from the row's pane.cwd.
  • multi-agent-mux-resume/scripts/resume_session.sh:42, 52 & workspace_uuid.py:57-58: Resolves UUID by matching s_cwd == ws. Resuming a Creator requires --workspace "$WT".
  • Cautionary Bug Identified: In create_session.sh:526:

    (bash "$WORKSPACE/.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh" --once >/dev/null 2>&1 &) || true
    

    This background subshell executes inside $WT without explicitly inheriting the exported WORKSPACE_ROOT / AGENT_SESSIONS_YAML variables, risking spawning a monitor tied to $WT/.mam. The recipe must ensure these envs are propagated.

---

Q3: Cost/benefit evaluation of Candidates A, B, and C?

• Verdict: Agree (동의).
• Analysis:
  • Candidate A: Highly wasteful. Spawning 5 agents per issue multiplies token consumption and rate limits by N. Reviewer context is completely discarded between issues.
  • Candidate B: Ineffective. Preserves the single-checkout bottleneck and fails to eliminate checkout collisions for creators.
  • Candidate C: Achieves optimal resource efficiency. Exactly 1 lightweight Creator agent is spawned per worktree; all Reviewers remain warm and retain conversational memory in the main session pool.

---

Q4: Evaluation of §5 Task Items & Multi-Loop Contention

• Verdict: Supplement (보완).
• Analysis of §5 Items:
  • Items 1, 2, 3, 5: High priority, straightforward, and essential.
  • Item 4 (Multi-Loop Contention): Concurrently executing multiple loops against a single .mam directory is currently infeasible due to hardcoded singletons in the codebase:
    1. lib_py/loop/runner.py:60: self.checkpoint_file = self.mam_dir / "loop-checkpoint.json". Two loops will overwrite each other's checkpoint.
    2. lib_py/loop/runner.py:801: When one loop finishes, it calls checkpoint.remove_checkpoint(), unlinking the checkpoint file while the other loop is still active!
    3. lib_py/loop/runner.py:427: Guard marker is hardcoded to .mam/loop-guard-active.
    4. lib_py/loop/runner.py:312-326: When a reviewer is busy, the runner retries once after 30s. If a reviewer in Loop 1 is running tests for 2 minutes, Loop 2 fails with exit code 5 immediately.
• Phasing Recommendation:
  • Phase 1 (Immediate): "Parallel Creators, Serial Loops" (루프는 하나씩, 구현만 병렬). Creators can implement code in parallel in their respective worktrees. Loops are triggered sequentially. This delivers immediate branch isolation and parallel coding without requiring a major rewrite of the loop control plane.
  • Phase 2 (Future): Support fully concurrent loops by parameterizing loop-checkpoint-<id>.json, loop-guard-active-<id>, and implementing a proper reviewer dispatch queue.

---

Q5: Ordering relative to Issue #17 Item 4 (Shell Layer Reduction)

• Verdict: Agree (동의).
• Rationale:
  • Documenting and validating Candidate C via recipes and targeted wrapper patches first establishes clear operational requirements.
  • When Issue #17 Item 4 consolidates shell wrappers into Python (lib_py), the distinction between worktree_root (code under test) and control_plane_root (shared .mam registry) can be implemented natively in Python classes (LoopRunner, Registry) without having to refactor bash scripts twice.

---

3. Code-Level Evidence and Review Checklist

3.1 lib.sh:26 and Environment Overrides

• Finding: Overrides for WORKSPACE_ROOT, AGENT_SESSIONS_YAML, MAM_JOBS_DIR, and DELEGATE_JOB_LOGS_DIR are respected across all skill tools.
• Evidence:
  • lib.sh:26, 34: Defaults are evaluated with ${VAR:-...}, permitting clean external injection.
  • create_session.sh:353, 372: Respects MAM_JOBS_DIR and AGENT_SESSIONS_YAML.
  • stop_session.sh:99, 151: Respects AGENT_SESSIONS_YAML and MAM_JOBS_DIR.

3.2 Prompt Injection Relative Brief Paths (§5-1)

• Finding: Prompt injection templates currently hardcode relative paths (.mam/jobs/<id>/brief.md), which will break when an agent's cwd is $WT.
• Evidence:
  • multi-agent-mux-delegate-job:199: "task brief file at: .mam/jobs/$JOB_ID/brief.md. Please READ and follow .mam/jobs/$JOB_ID/brief.md"
  • multi-agent-mux-delegate-job:455: "documented in the task brief file at: .mam/jobs/$JOB_ID/brief.md"
  • multi-agent-mux-delegate-job:352: - **Output Report Path**: .mam/jobs/$JOB_ID/${clean_session}-reports/report-final.md
• Actionable Fix: Update these three lines to use absolute path $REGISTRY_DIR/$JOB_ID/brief.md and $REGISTRY_DIR/$JOB_ID/${clean_session}-reports/report-final.md.

3.3 Loop Runner Diff Collection & base_commit (§5-2)

• Finding: LoopRunner currently evaluates git status strictly against self.workspace_root ($MAIN).
• Evidence:
  • lib_py/loop/runner.py:564: subprocess.run(["git", "rev-parse", "HEAD"], cwd=str(self.workspace_root))
  • lib_py/loop/runner.py:402, 408: subprocess.run(..., cwd=str(self.workspace_root))
• Actionable Fix: Introduce --worktree <path> (or MAM_LOOP_WORKTREE). Set self.worktree_root = Path(args.worktree).resolve() if args.worktree else self.workspace_root. Execute git rev-parse HEAD and collect_changes_diff() in cwd=str(self.worktree_root).

---

4. Specific Document Modifications

Section in Document	Proposed Modification	Rationale
§3 (동작 방식)	create_session.sh 호출 시 create_session.sh:526 백그라운드 reconcile 호출에 env 가 상속되도록 레시피 보강. 워크트리 준비 시 .mam.env 복사/링크 항목 명시.	누락 시 $WT 기준의 고아 monitor 가 기동되거나 MQTT 비밀정보가 누락될 위험 차단.
§4 (기대 효과와 한계)	"다중 루프 동시 기동"을 2단계(1단계: 병렬 구현 + 순차 루프 검증, 2단계: 다중 루프 동시 기동)로 명확히 분리 서술.	loop-checkpoint.json 및 단일 loop-guard-active 파일 충돌로 인한 즉시 결함 방지.
§5 (필요한 변경)	§5-6 추가: 리뷰어 테스트 실행 격리 규칙 추가 (PYTHONDONTWRITEBYTECODE=1, -p no:cacheprovider, 임시 디렉터리 기반 테스트).	리뷰어가 $WT 에 빌드 아티팩트나 캐시 파일을 남겨 커밋을 오염시키는 문제 방지.
§5 (필요한 변경)	§5-7 추가: 워크트리 종료 헬퍼 scripts/worktree_remove.sh 추가 (multi-agent-mux-stop --purge 후 git worktree remove).	워크트리 삭제 후 agent-sessions.yaml 에 죽은 경로의 세션 행이 잔류하는 문제 방지.

---

5. Final Verdict

The proposal accurately diagnoses the architectural limitation and provides a high-leverage, elegant solution. The recommended supplements are non-breaking and address operational robustness.

[VERDICT: PASS]