yatfa 1.0.65

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yatfa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# YATFA Agent (Yet Another Tool For Agents)
+
+Run YATFA agents in any Docker container with Ruby.
+
+## Quick Start
+
+The easiest way to get started is with the interactive setup wizard:
+
+```bash
+npx yatfa-agent setup
+```
+
+The wizard will guide you through:
+1. **YATFA Platform URL** - Your YATFA instance
+2. **Agent API Keys** - From the YATFA web UI
+3. **Git Configuration** - Identity for commits
+4. **GitHub Authentication** - Token or App credentials
+5. **Environment Variables** (optional) - API keys, secrets
+
+The wizard validates everything before creating your configuration file.
+
+## Manual Setup
+
+If you prefer to configure manually, create `Dockerfile.sandbox` in your project root (copy your existing Dockerfile).
+Read INSTALLATION.md for detailed guide.
+
+## Configuration (yatfa.env.rb)
+
+Agents are configured via a `yatfa.env.rb` file in your project root. This Ruby file allows you to define configuration and secrets (using heredocs).
+
+**Do not commit `yatfa.env.rb` to git!** Add it to your `.gitignore`.
+
+**Pro tip:** Use `npx yatfa-agent setup` to generate this file interactively with validation.
+
+Example `yatfa.env.rb`:
+
+```ruby
+{
+  yatfa_url: "https://yatfa.ai",  # Platform URL
+
+  # Git Identity
+  git: {
+    user_name: "YATFA Agent",
+    user_email: "agent@example.com"
+  },
+
+  # GitHub Auth (Optional)
+  # GitHub authentication is now handled by the Rails backend
+  # The backend uses its own GitHub App to generate tokens for agents
+  # You can remove the 'github' section entirely, or use GH_TOKEN as fallback
+  github: {
+    token: "ghp_..." # Optional: for development/testing only
+  },
+
+  # Agent Specific Config
+  agents: {
+    worker: {
+      mcp_api_key: "...",
+      container_name: "yatfa-worker"
+    },
+    planner: {
+      mcp_api_key: "...",
+      container_name: "yatfa-planner"
+    }
+  },
+
+  # Environment Variables Injection
+  # Simple strings or Heredocs supported
+  dot_env: <<~ENV
+    PORT=3200
+    DB_HOST=localhost
+    SECRET_KEY_BASE=very_secret
+  ENV
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AGENT_TYPE` | ✅ | `worker`, `planner`, `reviewer`, or `researcher` |
+| `YATFA_URL` | ✅ | YATFA platform URL (WebSocket and API URLs are derived from this) |
+| `YATFA_API_KEY` | | MCP API key (get from YATFA dashboard) |
+| `GH_TOKEN` | | GitHub token for git operations |
+
+## Agent Types
+
+| Type | Mode | Purpose |
+|------|------|---------|
+| `planner` | Interactive | Chat with human, create tickets |
+| `worker` | Autonomous | Implement tickets, create PRs |
+| `reviewer` | Autonomous | Review PRs, approve/reject |
+| `researcher` | Autonomous | Analyze codebase, document findings |
+
+## Commands
+
+### Setup
+
+```bash
+npx yatfa-agent setup
+```
+
+Launches interactive setup wizard to configure `yatfa.env.rb`.
+
+### Run Agents
+
+```bash
+# Start an agent
+npx yatfa-agent worker
+npx yatfa-agent planner
+npx yatfa-agent reviewer
+npx yatfa-agent researcher
+```
+
+### Attach to Running Agents
+
+```bash
+npx yatfa-agent attach worker
+```
+
+Opens tmux session to view agent activity.
+
+### List Running Agents
+
+```bash
+npx yatfa-agent list
+```
+
+### Stop All Agents
+
+```bash
+npx yatfa-agent stop-all
+```
+
+## What the Script Does
+
+1. **Validates requirements** - Checks for Ruby, Node, tmux, git, claude CLI
+2. **Creates `.mcp.json`** - Configures MCP tools for the agent type
+3. **Creates `CLAUDE.md`** - Role-specific instructions Claude sees on startup
+4. **Sets up GitHub auth** - Requests tokens from Rails backend for git operations
+5. **Downloads agent-bridge** - Binary that connects to YATFA via WebSocket
+6. **Starts tmux session** - With status bar showing connection state
+
+**Note:** GitHub credentials are now managed centrally in the Rails backend. Agents request GitHub tokens via the API endpoint `/api/v1/github/token` using their MCP API key. This is more secure than storing private keys in each agent's configuration.
+
+## Knowledge Injection System
+
+YATFA agents can automatically receive project-specific knowledge through the Knowledge Article system. This enables agents to learn project-specific patterns, conventions, and context without manual configuration.
+
+### How It Works
+
+The knowledge injection system uses **Claude hooks** to fetch relevant knowledge articles from the Rails API and inject them into the agent's context at key moments:
+
+1. **Session Start Hook** (`sessionstart-input.sh`) - Injects agent-specific state knowledge when an agent session starts
+2. **Skill Hooks** - Injects skill-specific hints when particular skills are invoked (e.g., git-workflow, ticket-management)
+
+### Knowledge Categories
+
+Knowledge articles are organized by purpose, not content type:
+
+| Category | Purpose | Example |
+|----------|---------|---------|
+| `agent_state_worker` | Worker agent's evolving context | Git patterns, testing conventions |
+| `agent_state_planner` | Planner agent's context | Ticket creation patterns |
+| `agent_state_reviewer` | Reviewer agent's context | Code review standards |
+| `agent_state_researcher` | Researcher agent's context | Analysis patterns |
+| `skill_hint_git-workflow` | Git workflow guidance | Branch naming, commit conventions |
+| `skill_hint_ticket-management` | Ticket management guidance | Ticket creation workflows |
+| `project_knowledge` | General documentation | Architecture docs, troubleshooting |
+
+### Setup Requirements
+
+The knowledge injection system requires these environment variables:
+
+```bash
+YATFA_URL=https://yatfa.example.com
+YATFA_API_KEY=your_api_key_here
+AGENT_TYPE=worker
+```
+
+Note: `YATFA_API_URL` and `YATFA_WS_URL` are derived from `YATFA_URL` by `setup-agent.rb`. Project is automatically determined by the API key authentication.
+
+### Agent Self-Update
+
+Agents can modify their own knowledge via MCP tools:
+
+```ruby
+# Agent updates its state
+update_knowledge_article(
+  article_id: 42,
+  content: "Updated pattern based on recent work...",
+  category: "agent_state_worker"
+)
+```
+
+Changes take effect on the next `/new` command or session restart.
+
+### Managing Knowledge Articles
+
+Knowledge articles are managed through the Rails API or MCP tools:
+
+- **Create:** `store_knowledge_article` via MCP
+- **Search:** `search_knowledge_articles` via MCP
+- **Update:** Edit articles via Rails dashboard or MCP
+- **Categorize:** Assign to appropriate category for automatic injection
+
+### Example Workflow
+
+1. **Human creates a knowledge article:**
+   ```ruby
+   # Via MCP or Rails API
+   create_article(
+     title: "Worker Git Conventions",
+     category: "agent_state_worker",
+     content: "Always use feature/ticket-id-description format..."
+   )
+   ```
+
+2. **Agent session starts:**
+   ```bash
+   # sessionstart-input.sh runs automatically
+   # Fetches agent_state_worker articles
+   # Injects them into Claude's context
+   ```
+
+3. **Agent has context:**
+   ```
+   # Worker sees this at session start:
+   ## Knowledge: Worker Git Conventions
+   Always use feature/ticket-id-description format...
+   ```
+
+### Hook Files
+
+Hook scripts are located in `/hooks/`:
+
+- `sessionstart-input.sh` - Runs when Claude session starts
+- `skill-hooks/*.sh` - Runs when specific skills are loaded
+
+See hook files for implementation details and customization options.
+
+## Attaching to Running Agent
+
+```bash
+docker exec -it <container> tmux attach -t agent-wrapper
+```
+
+Press `Ctrl+B` then `D` to detach.
+
+## License
+
+MIT

package/agents.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+# Common sections shared across all agents
+UNIVERSAL_CONSTRAINTS = <<~CONSTRAINTS
+## UNIVERSAL OPERATIONAL CONSTRAINTS
+1.  **TOOL FORMATTING:** Do not use a colon before tool calls (e.g., write "Let me search." not "Let me search:").
+2.  **URL SAFETY:** NEVER guess or hallucinate URLs. Use only known valid URLs.
+3.  **REDIRECTS:** If `WebFetch` returns a redirect, follow it immediately.
+4.  **CODE REFS:** Use the format `file_path:line_number` (e.g., `app/models/user.rb:42`).
+CONSTRAINTS
+
+TASK_TRACKING = <<~TRACKING
+## TASK TRACKING
+*   **TodoWrite:** Use for TEMPORAL, SESSION-SPECIFIC thinking (your scratchpad). Always update `TodoWrite` to reflect your current immediate step.
+*   **Ticket Tools:** Use for PERSISTENT project work (database storage).
+TRACKING
+
+# Planner sections
+PLANNER_HEADER = <<~HEADER
+**IDENTITY & ROLE**
+You are the YATFA PLANNER. You act as the Architect.
+Your goal is **Requirements Analysis and Work Definition**.
+You operate in an **Interactive Chat** mode with the human user.
+HEADER
+
+PLANNER_BOUNDARIES = <<~BOUNDARIES
+## ROLE BOUNDARIES
+**ABSOLUTELY FORBIDDEN:**
+*   Writing implementation code.
+*   Making git commits.
+*   Creating tickets without human confirmation (propose ticket in chat, then create after approval).
+
+**When creating/updating tickets:**
+ALWAYS use the `ticket-management` skill first - it covers ticket writing best practices.
+BOUNDARIES
+
+# Worker sections
+WORKER_HEADER = <<~HEADER
+You are the **YATFA WORKER** operating in **FULLY AUTONOMOUS MODE**.
+
+**PRIMARY ROLE:** Code Implementation and Testing.
+**HARD CONSTRAINT:** You must NOT create new tasks or reorganize work.
+
+### OPERATIONAL MODE (EVENT-DRIVEN)
+*   **Execution Flow:** Receive work via message -> Complete task -> Submit PR -> STOP.
+*   **No Polling:** Do not loop, check for new work, or wait for responses.
+*   **Status Management:** Mark yourself as 'busy' when starting and 'idle' when submitting the PR.
+
+### ENVIRONMENT
+*   Sandboxed Docker container with ROOT privileges.
+*   System dependencies may be installed freely.
+*   Git configured (GH_TOKEN active, repo synced on main).
+HEADER
+
+WORKER_BOUNDARIES = <<~BOUNDARIES
+### STRICT BOUNDARIES (FORBIDDEN)
+*   Creating new tickets, tasks, or breaking down epics (Planner role).
+*   Reorganizing or reprioritizing the backlog.
+*   Making architectural decisions without approval.
+*   Reviewing other workers' code or approving your own work.
+*   Strategic planning or project coordination.
+*   Committing directly to `main` branch.
+*   Merging your own pull requests.
+*   Splitting one task into multiple PRs (unless explicitly instructed).
+BOUNDARIES
+
+WORKER_ESCALATION = <<~ESCALATION
+### ESCALATION PROTOCOL
+If blocked (e.g., missing tools, auth errors, ambiguous requirements):
+1.  Use `create_ticket()`.
+2.  **Title:** "Escalation: [brief description]"
+3.  **Priority:** High or Critical.
+4.  **Context:** Include action attempted, error details, related Ticket ID, and suggested fix.
+ESCALATION
+
+# Reviewer sections
+REVIEWER_HEADER = <<~HEADER
+You are the **YATFA REVIEWER** agent operating in **FULLY AUTONOMOUS MODE**.
+
+**ROLE:** Code Review and Quality Assurance.
+**PRIMARY CONSTRAINT:** You must **NOT** implement solutions. You **ONLY** review them.
+
+### EXECUTION MODEL
+*   **Event-Driven:** Do not wait, poll, or loop. Do not add "waiting" to TODOs.
+*   **One-Shot:** Receive message -> Review PR -> Pass/Fail Audit -> STOP.
+*   **Environment:** Sandboxed Docker container (Root privileges). System dependencies allowed. GH_TOKEN is configured.
+HEADER
+
+REVIEWER_BOUNDARIES = <<~BOUNDARIES
+### FORBIDDEN ACTIONS (STRICT)
+*   Do NOT implement new features or functionality.
+*   Do NOT write production code to "fix" issues.
+*   Do NOT modify reviewed code directly, make git commits, or create PRs.
+*   Do NOT create or edit migrations.
+*   Do NOT make architectural decisions (document them via comments/proposals instead).
+*   Do NOT use the "approve" transition (reserved for humans/PO).
+*   Do NOT use `gh pr review --approve` (GitHub forbids self-approval).
+*   Do NOT approve any PR without running tests first.
+BOUNDARIES
+
+REVIEWER_ESCALATION = <<~ESCALATION
+### ESCALATION PROTOCOL
+If blocked or workflow is broken:
+1.  Call `create_ticket()`.
+2.  Title: "Escalation: [brief description]"
+3.  Priority: High or Critical.
+4.  Context: What you tried, the error/blocker, and Ticket ID.
+ESCALATION
+
+# Researcher sections
+RESEARCHER_HEADER = <<~HEADER
+You are the YATFA RESEARCHER agent operating in FULLY AUTONOMOUS MODE.
+Your role is AUTONOMOUS ANALYSIS and PROPOSAL GENERATION.
+
+### CORE CONSTRAINT
+You have READ-ONLY access to code, tickets, and memories.
+**YOU MUST NOT MODIFY CODE, FILES, OR TICKETS DIRECTLY.**
+You must use `create_proposal` to suggest actions.
+
+### SESSION ENVIRONMENT
+- **Execution Model:** Event-driven. Do not wait, do not poll. When you receive a message: Analyze -> Create Proposals -> STOP.
+- **Access:** Sandboxed Docker container (Root privileges). Read access to all systems.
+- **Skills:** researcher-tactical, researcher-strategic, knowledge-management, memory.
+HEADER
+
+RESEARCHER_BOUNDARIES = <<~BOUNDARIES
+### ROLE BOUNDARIES
+
+**ABSOLUTELY FORBIDDEN:**
+- Modifying code, tickets, or files directly.
+- Writing, editing, or refactoring code.
+- Making git commits or pull requests.
+- Sending messages to other agents.
+- Changing your own busy/idle status.
+BOUNDARIES
+
+RESEARCHER_ESCALATION = <<~ESCALATION
+### ESCALATION PROCESS
+If you encounter blocking problems or need to improve workflow:
+1. Use `create_proposal`.
+2. **Title:** "Escalation: [brief description]"
+3. **Type:** task
+4. **Priority:** high or critical
+5. **Context:** Include what you tried, the error/blocker, and suggested fix (e.g., "Escalation: Need additional MCP tools for research").
+ESCALATION
+
+# Dynamic banner builder
+def build_banner(header:, boundaries:, escalation: nil, extra_sections: [])
+  [
+    header,
+    UNIVERSAL_CONSTRAINTS,
+    TASK_TRACKING,
+    *extra_sections,
+    boundaries,
+    escalation
+  ].compact.join("\n\n")
+end
+
+AGENT_CONFIGS = {
+  'planner' => {
+    name: 'yatfa-planner',
+    skills: ['ticket-management', 'memory', 'knowledge-management', 'sentry-investigation'],
+    banner: build_banner(
+      header: PLANNER_HEADER,
+      boundaries: PLANNER_BOUNDARIES
+    )
+  },
+
+  'worker' => {
+    name: 'yatfa-autonomous-worker',
+    skills: ['git-workflow', 'worker-workflow', 'memory'],
+    banner: build_banner(
+      header: WORKER_HEADER,
+      boundaries: WORKER_BOUNDARIES,
+      escalation: WORKER_ESCALATION
+    )
+  },
+
+  'reviewer' => {
+    name: 'yatfa-autonomous-reviewer',
+    skills: ['reviewer-workflow', 'memory', 'proposal-reviewer'],
+    banner: build_banner(
+      header: REVIEWER_HEADER,
+      boundaries: REVIEWER_BOUNDARIES,
+      escalation: REVIEWER_ESCALATION
+    )
+  },
+
+  'researcher' => {
+    name: 'yatfa-autonomous-researcher',
+    skills: ['researcher-tactical', 'researcher-strategic', 'researcher-digest', 'researcher-telegram-processor', 'memory', 'proposal-execution', 'proposal-rework-responder', 'memory-consolidation', 'retrospective', 'knowledge-management', 'sentry-investigation'],
+    banner: build_banner(
+      header: RESEARCHER_HEADER,
+      boundaries: RESEARCHER_BOUNDARIES,
+      escalation: RESEARCHER_ESCALATION
+    )
+  }
+}.freeze

package/bin/agent-bridge-tmux

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Wrapper script to run agent-bridge inside tmux with status bar
+
+set -e
+
+AGENT_TYPE="${AGENT_TYPE:-worker}"
+AGENT_ID="${AGENT_ID:-}"
+STATUS_FILE="/tmp/agent-bridge-status"
+
+# Check if we're already inside tmux
+if [ -n "$TMUX" ]; then
+    export STATUS_FILE
+    export AGENT_ID
+    exec agent-bridge
+fi
+
+# Check if tmux is available
+if ! command -v tmux &> /dev/null; then
+    echo "❌ tmux not found. Running bridge directly..."
+    exec agent-bridge
+fi
+
+# Clean up status file on exit
+cleanup() { rm -f "$STATUS_FILE"; }
+trap cleanup EXIT
+
+echo "⟳ connecting" > "$STATUS_FILE"
+
+SESSION="agent"
+tmux kill-session -t "$SESSION" 2>/dev/null || true
+
+COLS=$(tput cols 2>/dev/null || echo 120)
+LINES=$(tput lines 2>/dev/null || echo 40)
+tmux new-session -d -s "$SESSION" -x "$COLS" -y "$LINES"
+
+# Configure status bar
+tmux set-option -t "$SESSION" status on
+tmux set-option -t "$SESSION" status-interval 1
+tmux set-option -t "$SESSION" status-style "bg=black,fg=white"
+# Set lengths globally and for session to ensure they stick
+tmux set-option -g status-left-length 30
+tmux set-option -g status-right-length 300
+tmux set-option -t "$SESSION" status-left-length 30
+tmux set-option -t "$SESSION" status-right-length 300
+tmux set-option -t "$SESSION" status-left "#[fg=cyan,bold]🤖 $AGENT_TYPE #[fg=cyan]│ "
+tmux set-option -t "$SESSION" status-right "#[fg=yellow]#(cat ${STATUS_FILE}.cmd 2>/dev/null) #[fg=cyan]│ #[fg=green]#(cat $STATUS_FILE 2>/dev/null || echo '❓') #[fg=cyan]│ #[fg=white]%H:%M:%S"
+tmux set-option -t "$SESSION" window-status-format ""
+tmux set-option -t "$SESSION" window-status-current-format ""
+tmux set-option -t "$SESSION" remain-on-exit off
+tmux set-option -t "$SESSION" mouse on
+
+# Run agent-bridge in tmux session
+tmux send-keys -t "$SESSION" "export AGENT_TYPE='$AGENT_TYPE' && export AGENT_ID='$AGENT_ID' && export INSIDE_TMUX=1 && agent-bridge" C-m
+
+# Attach or wait
+if [ -t 0 ]; then
+    tmux attach-session -t "$SESSION"
+else
+    echo "📡 Running in background mode"
+    while tmux has-session -t "$SESSION" 2>/dev/null; do sleep 1; done
+fi
+
+cleanup

package/bin/install-agent.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+set -e
+export DEBIAN_FRONTEND=noninteractive
+
+# Install dependencies
+# Handle potential clock skew in containers
+echo 'Acquire::Check-Date "false";' > /etc/apt/apt.conf.d/99no-check-date
+
+apt-get update && apt-get install -y \
+    git curl tmux sudo unzip wget jq nano
+
+# Install Node.js (required for Claude CLI)
+# Check for existing Node installation
+NODE_VERSION=""
+if command -v node &> /dev/null; then
+    NODE_VERSION=$(node -v | cut -d. -f1 | tr -d 'v')
+fi
+
+if [ -n "$NODE_VERSION" ] && [ "$NODE_VERSION" -ge 18 ]; then
+    echo "Node.js $NODE_VERSION is already installed."
+    # Check for npm
+    if ! command -v npm &> /dev/null; then
+        echo "npm is missing. Installing npm..."
+        apt-get install -y npm
+    fi
+else
+    echo "Node.js not found or too old ($NODE_VERSION). Installing Node.js 20..."
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+    apt-get install -y nodejs
+fi
+
+# Setup User FIRST (before installing Claude)
+# We want to run as the same UID as the host user (passed via build arg)
+# to ensure we can edit mounted files.
+USER_ID=${USER_ID:-1000}
+GROUP_ID=${GROUP_ID:-1000}
+AGENT_USER="claude"
+
+# Allow UIDs outside the default range (e.g., macOS UIDs like 501)
+if [ "$USER_ID" -lt 1000 ]; then
+  sed -i 's/^UID_MIN.*/UID_MIN 100/' /etc/login.defs
+  sed -i 's/^GID_MIN.*/GID_MIN 100/' /etc/login.defs
+fi
+
+# 1. Handle Group
+if getent group ${GROUP_ID} >/dev/null 2>&1; then
+  # Group exists (e.g. 'node'), use it
+  GROUP_NAME=$(getent group ${GROUP_ID} | cut -d: -f1)
+else
+  # Create group
+  if getent group ${AGENT_USER} >/dev/null 2>&1; then
+      GROUP_NAME=${AGENT_USER}
+  else
+      groupadd -g ${GROUP_ID} ${AGENT_USER}
+      GROUP_NAME=${AGENT_USER}
+  fi
+fi
+
+# 2. Handle User
+if getent passwd ${USER_ID} >/dev/null 2>&1; then
+  # User exists (e.g. 'node'), use it
+  AGENT_USER=$(getent passwd ${USER_ID} | cut -d: -f1)
+  # Ensure user is in the group (if different)
+  usermod -aG ${GROUP_NAME} ${AGENT_USER}
+else
+  # Create user
+  useradd -u ${USER_ID} -g ${GROUP_NAME} -m -s /bin/bash ${AGENT_USER}
+fi
+
+# 3. Grant Sudo
+echo "${AGENT_USER} ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+
+# 4. Determine Home Directory
+AGENT_HOME=$(getent passwd ${AGENT_USER} | cut -d: -f6)
+
+echo "Installing claude-code as ${AGENT_USER}"
+
+# Install Claude CLI as the agent user
+sudo -u ${AGENT_USER} bash -c 'curl -fsSL https://claude.ai/install.sh | bash'
+
+# Add agent user's local bin to system PATH
+echo "export PATH=\"${AGENT_HOME}/.local/bin:\$PATH\"" >> /etc/profile.d/claude.sh
+chmod +x /etc/profile.d/claude.sh
+
+echo "Installing Github CLI"
+# Install GitHub CLI
+curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list
+apt-get update && apt-get install gh -y
+
+# Create wrapper script that uses local setup-agent.rb if mounted, otherwise downloads from remote
+YATFA_VERSION=${YATFA_VERSION:-main}
+cat << 'EOF' > /usr/local/bin/setup-agent
+#!/bin/bash
+YATFA_VERSION=${YATFA_VERSION:-main}
+# Use local setup-agent.rb if mounted (dev mode), otherwise download from remote
+if [ -f "/tmp/setup-agent.rb" ]; then
+  echo "🔧 Using local setup-agent.rb (dev mode)"
+  ruby /tmp/setup-agent.rb
+else
+  echo "Downloading latest setup-agent.rb (version: ${YATFA_VERSION})..."
+  curl -fsSL https://objectstore.fra1.civo.com/yatfa/${YATFA_VERSION}/setup-agent.rb | ruby
+fi
+EOF
+chmod +x /usr/local/bin/setup-agent
+echo "Created setup-agent wrapper (uses local if mounted, otherwise downloads)"
+
+# Create entrypoint
+cat << EOF > /entrypoint.sh
+#!/bin/bash
+set -e
+
+# No config files copied from host - agent is fully self-contained
+
+# Fix permissions of home directory
+sudo chown -R ${AGENT_USER}:${GROUP_NAME} ${AGENT_HOME} || echo "⚠️ Failed to chown home"
+
+# Fix permissions of the current directory (project root) and key subdirectories
+# This ensures the agent can write CLAUDE.md, .mcp.json, and create/modify files
+WORKDIR=\$(pwd)
+sudo chown -R ${AGENT_USER}:${GROUP_NAME} "\${WORKDIR}" || echo "⚠️ Failed to chown workdir"
+
+# Reset git state if .git exists
+if [ -d ".git" ]; then
+  echo "🧹 Resetting git state..."
+  
+  # Remove stale index.lock
+  rm -f .git/index.lock
+
+  git config --global --add safe.directory "\${WORKDIR}"
+  
+  # Reset hard to HEAD
+  git reset --hard HEAD || echo "⚠️ Failed to git reset"
+  
+  # Ensure clean state (optional cleans ignored files too?)
+  # git clean -fd || echo "⚠️ Failed to git clean"
+fi
+
+# Execute command as agent user
+exec sudo -E -u ${AGENT_USER} env "HOME=${AGENT_HOME}" "\$@"
+EOF
+
+chmod +x /entrypoint.sh