agent-relay 1.6.0 → 2.0.0

package/SESSION_HANDOFF.md

@@ -0,0 +1,67 @@
+# Session Handoff - NPM Package Extraction Project
+
+**Last Updated**: Session end (Jan 22, 2026 ~12:45 UTC)
+
+## Current State Summary
+
+### Completed
+- **Phases 1-4**: 14 packages extracted (protocol, config, storage, state, policy, memory, utils, hooks)
+- **Phase 6A**: User-directory extracted (broke circular deps)
+- **Phase 5A**: Cloud extraction complete, build GREEN
+
+### In Progress - NEEDS ATTENTION
+- **Phase 5B** (Staff): Dashboard-server extraction
+  - Last confirmed: 12:37 UTC
+  - ETA: 45-60 minutes to build green
+  - Status: APPEARS IDLE - no updates for 15+ minutes
+  
+- **Phase 6B** (FullStack): Daemon extraction  
+  - Last confirmed: 12:21 UTC
+  - ETA: 60 minutes
+  - Status: UNRESPONSIVE - no updates for 40+ minutes
+
+### Queued
+- Phase 6C: CLI extraction (FullStack, after 6B)
+- Phase 6D: Final integrations (15-30 min)
+
+## Test Baseline
+Maintain 2468 passing tests throughout
+
+## Critical Reminders
+
+### Build Order
+Trajectory and Hooks MUST build BEFORE Memory
+
+### Relay Protocol
+Write to ~/.agent-relay/outbox/[Agent]/msg with TO: Lead header
+
+### Package Paths
+- Config: @agent-relay/config/*
+- Daemon: @agent-relay/daemon/*
+- Wrapper: @agent-relay/wrapper/*
+- Cloud: @agent-relay/cloud/*
+
+## Immediate Next Steps
+
+1. Ping Staff: Phase 5B dashboard-server status?
+2. Ping FullStack: What is blocking Phase 6B daemon extraction?
+3. Unblock both agents
+4. Resume parallel execution
+5. Monitor to completion
+
+## Key Files
+
+- Handoff notes: ~/.agent-relay/outbox/Lead/session-handoff
+- Phase 6 plan: .beads/phase6-execution-plan.md
+- Cloud package: packages/cloud/ (COMPLETE)
+- Dashboard-server: packages/dashboard-server/ (IN PROGRESS)
+- Daemon: packages/daemon/ (IN PROGRESS)
+
+## Timeline to Completion
+- Phase 5B: 50-60 min remaining
+- Phase 6B: 60 min (parallel)
+- Phase 6C: 30-45 min
+- Final integration: 15-30 min
+- TOTAL: 2-2.5 hours
+
+Risk Level: MODERATE (both agents appear stuck, need immediate wake-up)

package/deploy/workspace/entrypoint.sh

@@ -29,6 +29,7 @@ if [[ "$(id -u)" == "0" ]]; then
     # - Allow password auth (for CLI simplicity)
     # - Listen on port 3022 (non-privileged)
     # - Allow TCP forwarding (for port tunneling)
+    mkdir -p /etc/ssh/sshd_config.d
     cat > /etc/ssh/sshd_config.d/workspace.conf <<SSHEOF
 Port ${SSH_PORT}
 PasswordAuthentication yes
@@ -69,6 +70,12 @@ export HOME="${_USER_HOME}"
 export AGENT_RELAY_USER_ID="${WORKSPACE_OWNER_USER_ID:-}"
 export AGENT_RELAY_DATA_DIR="${_DATA_DIR}"
 export AGENT_RELAY_API_KEY="${AGENT_RELAY_API_KEY:-}"
+
+# Source GH_TOKEN from user-writable file if available (written after startup)
+# This enables SSH sessions to use the token fetched during container init
+if [[ -f "${_USER_HOME}/.gh_token" ]]; then
+  source "${_USER_HOME}/.gh_token"
+fi
 ENVEOF
     chmod 644 /etc/profile.d/workspace-env.sh
   fi
@@ -139,6 +146,40 @@ if [[ -n "${CLOUD_API_URL:-}" && -n "${WORKSPACE_ID:-}" && -n "${WORKSPACE_TOKEN
   git config --global credential.useHttpPath true
   export GIT_TERMINAL_PROMPT=0
 
+  # ============================================================================
+  # PRE-FETCH GitHub token at startup and export to environment
+  # This ensures GH_TOKEN is available for git operations and spawned agents
+  # even if cloud API becomes unreachable later. The credential helper's
+  # fallback chain will use this token (env > hosts.yml > gh CLI > cloud API).
+  # ============================================================================
+  if [[ -z "${GH_TOKEN:-}" ]]; then
+    log "Fetching GitHub token from cloud API..."
+    GH_TOKEN_RESPONSE=$(curl -sf --max-time 10 \
+      -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
+      "${CLOUD_API_URL}/api/git/token?workspaceId=${WORKSPACE_ID}" 2>/dev/null) || true
+
+    if [[ -n "${GH_TOKEN_RESPONSE}" ]]; then
+      # Extract userToken (preferred) or token from JSON response
+      FETCHED_TOKEN=$(echo "${GH_TOKEN_RESPONSE}" | jq -r '.userToken // .token // empty' 2>/dev/null)
+      if [[ -n "${FETCHED_TOKEN}" && "${FETCHED_TOKEN}" != "null" ]]; then
+        export GH_TOKEN="${FETCHED_TOKEN}"
+        export GITHUB_TOKEN="${FETCHED_TOKEN}"
+        # Persist token for SSH sessions (sourced by /etc/profile.d/workspace-env.sh)
+        echo "export GH_TOKEN=\"${FETCHED_TOKEN}\"" > "${HOME}/.gh_token"
+        echo "export GITHUB_TOKEN=\"${FETCHED_TOKEN}\"" >> "${HOME}/.gh_token"
+        chmod 600 "${HOME}/.gh_token"
+        log "GH_TOKEN set from cloud API (token available for git operations and SSH sessions)"
+      else
+        log "WARN: Cloud API returned no token; git may require manual auth"
+      fi
+    else
+      log "WARN: Failed to fetch GitHub token from cloud API; git may require manual auth"
+      log "      Fallback: run 'gh auth login' or set GH_TOKEN manually"
+    fi
+  else
+    log "GH_TOKEN already set in environment"
+  fi
+
   # Configure git identity for commits
   # Use env vars if set, otherwise default to "Agent Relay" / "agent@agent-relay.com"
   DEFAULT_GIT_EMAIL="${AGENT_NAME:-agent}@agent-relay.com"
@@ -205,16 +246,19 @@ clone_or_update_repo() {
     git -C "${target}" pull --ff-only >/dev/null 2>&1 || true
   else
     log "Cloning ${repo}..."
-    git clone "${url}" "${target}" >/dev/null 2>&1 || {
-      log "WARN: Failed to clone ${repo}"
-    }
-  fi
-
-  # Mark directory as safe to prevent "dubious ownership" errors
-  # This is needed when git runs as a different user (e.g., root via SSH)
-  if [[ -d "${target}/.git" ]]; then
-    git config --global --add safe.directory "${target}" 2>/dev/null || true
+    # Use shallow clone for faster initial setup (full history not needed for most agent work)
+    # SHALLOW_CLONE env var can be set to "false" to disable this optimization
+    if [[ "${SHALLOW_CLONE:-true}" == "true" ]]; then
+      git clone --depth=1 "${url}" "${target}" >/dev/null 2>&1 || {
+        log "WARN: Failed to clone ${repo}"
+      }
+    else
+      git clone "${url}" "${target}" >/dev/null 2>&1 || {
+        log "WARN: Failed to clone ${repo}"
+      }
+    fi
   fi
+  # Note: safe.directory config is done after all clones complete (batched)
 }
 
 if [[ -n "${REPO_LIST}" ]]; then
@@ -224,8 +268,29 @@ if [[ -n "${REPO_LIST}" ]]; then
   fi
 
   IFS=',' read -ra repos <<< "${REPO_LIST}"
+
+  # Clone repositories in PARALLEL for faster startup
+  # Each clone runs in background, then we wait for all to complete
+  log "Cloning ${#repos[@]} repositories in parallel..."
+  for repo in "${repos[@]}"; do
+    clone_or_update_repo "${repo}" &
+  done
+
+  # Wait for all background clone jobs to complete
+  wait
+  log "All repository clones complete"
+
+  # Batch configure safe.directory for all cloned repos (runs once, not per-repo)
+  # This prevents "dubious ownership" errors when git runs as different user
   for repo in "${repos[@]}"; do
-    clone_or_update_repo "${repo}"
+    repo="${repo// /}"
+    if [[ -n "${repo}" ]]; then
+      repo_name="$(basename "${repo}")"
+      target="${WORKSPACE_DIR}/${repo_name}"
+      if [[ -d "${target}/.git" ]]; then
+        git config --global --add safe.directory "${target}" 2>/dev/null || true
+      fi
+    fi
   done
 fi
 
@@ -448,8 +513,11 @@ log "Detected workspace path: ${ACTUAL_WORKSPACE}"
 # Change to the detected workspace before starting daemon
 cd "${ACTUAL_WORKSPACE}"
 
+# Set RELAY_PROJECT from WORKSPACE_ID at runtime (MCP socket discovery uses this)
+export RELAY_PROJECT="${WORKSPACE_ID:-${RELAY_PROJECT:-default}}"
+
 log "Starting agent-relay daemon on port ${PORT} from ${ACTUAL_WORKSPACE}"
-args=(/app/dist/cli/index.js up --port "${PORT}")
+args=(/app/dist/src/cli/index.js up --dashboard --port "${PORT}")
 
 if [[ "${SUPERVISOR_ENABLED:-true}" == "true" ]]; then
   args+=("--watch")

package/deploy/workspace/git-credential-relay

@@ -2,15 +2,23 @@
 #
 # Git Credential Helper for Agent Relay Workspaces
 #
-# This script fetches fresh GitHub tokens from the cloud API gateway.
-# Nango handles token refresh, so tokens are always valid.
+# This script provides GitHub authentication for git operations using
+# a multi-source fallback chain. It works offline and without cloud
+# connectivity when local credentials are available.
+#
+# FALLBACK CHAIN (in order):
+#   1. GH_TOKEN or GITHUB_TOKEN env vars - fastest, no I/O
+#   2. ~/.config/gh/hosts.yml - gh CLI config file
+#   3. gh auth token command - runs gh CLI
+#   4. Cloud API - workspace-scoped token from Nango
 #
 # Usage: git config --global credential.helper /usr/local/bin/git-credential-relay
 #
-# Environment variables:
-#   WORKSPACE_ID      - Required: The workspace ID for token lookup
-#   CLOUD_API_URL     - Required: The cloud API base URL
-#   WORKSPACE_TOKEN   - Required: Bearer token for API auth
+# Environment variables (only needed if fallbacks 1-3 fail):
+#   WORKSPACE_ID      - The workspace ID for cloud token lookup
+#   CLOUD_API_URL     - The cloud API base URL
+#   WORKSPACE_TOKEN   - Bearer token for cloud API auth
+#   GIT_CREDENTIAL_DEBUG=1 - Enable debug logging
 #
 
 set -euo pipefail
@@ -45,20 +53,130 @@ if [[ "$host" != "github.com" ]]; then
   exit 0
 fi
 
-# Check required environment variables
+# =====================================================================
+# FALLBACK CHAIN (order matters - fastest/most reliable first):
+# 1. GH_TOKEN/GITHUB_TOKEN env vars - direct, no lookup needed
+# 2. ~/.config/gh/hosts.yml - local gh CLI config file
+# 3. gh auth token command - runs gh CLI to get token
+# 4. Cloud API - workspace-scoped token from Nango (requires network)
+# =====================================================================
+
+# Helper function to output credentials and exit successfully
+output_credentials() {
+  local token="$1"
+  local source="$2"
+  debug "Using token from: $source"
+  echo "protocol=https"
+  echo "host=github.com"
+  echo "username=x-access-token"
+  echo "password=${token}"
+  exit 0
+}
+
+# Helper function to extract token from gh hosts.yml
+extract_gh_hosts_token() {
+  local hosts_file="$1"
+  [[ ! -f "$hosts_file" ]] && return 1
+
+  # Parse YAML to find github.com section and extract oauth_token or token
+  local in_github_section=0
+  while IFS= read -r line; do
+    # Check for github.com host section (not indented)
+    if [[ "$line" =~ ^github\.com: ]] || [[ "$line" == "github.com:" ]]; then
+      in_github_section=1
+      continue
+    fi
+    # Check if we've left the github.com section (new unindented line)
+    if [[ $in_github_section -eq 1 ]] && [[ -n "$line" ]] && [[ ! "$line" =~ ^[[:space:]] ]]; then
+      in_github_section=0
+    fi
+    # Extract token if in github.com section
+    if [[ $in_github_section -eq 1 ]]; then
+      if [[ "$line" =~ ^[[:space:]]*(oauth_token|token):[[:space:]]*(.+)$ ]]; then
+        local token="${BASH_REMATCH[2]}"
+        # Strip quotes and comments
+        token="${token%%#*}"
+        token="${token%\"}"
+        token="${token#\"}"
+        token="${token%\'}"
+        token="${token#\'}"
+        token="${token// /}"
+        if [[ -n "$token" ]]; then
+          echo "$token"
+          return 0
+        fi
+      fi
+    fi
+  done < "$hosts_file"
+  return 1
+}
+
+# FALLBACK 1: Environment variables (fastest - no I/O needed)
+if [[ -n "${GH_TOKEN:-}" || -n "${GITHUB_TOKEN:-}" ]]; then
+  token="${GH_TOKEN:-${GITHUB_TOKEN}}"
+  output_credentials "$token" "GH_TOKEN/GITHUB_TOKEN env"
+fi
+
+# FALLBACK 2: gh CLI config file (~/.config/gh/hosts.yml)
+# Check multiple possible locations for the hosts.yml file
+gh_hosts_paths=(
+  "${XDG_CONFIG_HOME:-$HOME/.config}/gh/hosts.yml"
+  "$HOME/.config/gh/hosts.yml"
+)
+
+for hosts_path in "${gh_hosts_paths[@]}"; do
+  if [[ -f "$hosts_path" ]]; then
+    debug "Checking gh hosts.yml: $hosts_path"
+    token=$(extract_gh_hosts_token "$hosts_path")
+    if [[ -n "$token" ]]; then
+      output_credentials "$token" "gh hosts.yml ($hosts_path)"
+    fi
+  fi
+done
+
+# FALLBACK 3: gh CLI command (requires gh to be installed and authenticated)
+if command -v gh &>/dev/null; then
+  debug "Trying gh auth token command"
+  if token=$(gh auth token --hostname github.com 2>/dev/null); then
+    token="${token// /}"
+    if [[ -n "$token" ]]; then
+      output_credentials "$token" "gh auth token"
+    fi
+  fi
+fi
+
+# FALLBACK 4: Cloud API (requires workspace env vars)
+# Check required environment variables for cloud fallback
 if [[ -z "${WORKSPACE_ID:-}" ]]; then
-  echo "git-credential-relay: WORKSPACE_ID not set" >&2
-  echo "git-credential-relay: Hint - check if env vars are passed to agent process" >&2
+  echo "git-credential-relay: All credential sources failed." >&2
+  echo "git-credential-relay: Fallback chain tried:" >&2
+  echo "git-credential-relay:   1. GH_TOKEN/GITHUB_TOKEN env - not set" >&2
+  echo "git-credential-relay:   2. ~/.config/gh/hosts.yml - no token found" >&2
+  echo "git-credential-relay:   3. gh auth token - failed or not installed" >&2
+  echo "git-credential-relay:   4. Cloud API - unavailable (WORKSPACE_ID not set)" >&2
+  echo "git-credential-relay: Fix: Run 'gh auth login' or set GH_TOKEN env var" >&2
   exit 1
 fi
 
 if [[ -z "${CLOUD_API_URL:-}" ]]; then
-  echo "git-credential-relay: CLOUD_API_URL not set" >&2
+  echo "git-credential-relay: All credential sources failed." >&2
+  echo "git-credential-relay: Fallback chain tried:" >&2
+  echo "git-credential-relay:   1. GH_TOKEN/GITHUB_TOKEN env - not set" >&2
+  echo "git-credential-relay:   2. ~/.config/gh/hosts.yml - no token found" >&2
+  echo "git-credential-relay:   3. gh auth token - failed or not installed" >&2
+  echo "git-credential-relay:   4. Cloud API - unavailable (CLOUD_API_URL not set)" >&2
+  echo "git-credential-relay: Fix: Run 'gh auth login' or set GH_TOKEN env var" >&2
   exit 1
 fi
 
 if [[ -z "${WORKSPACE_TOKEN:-}" ]]; then
-  echo "git-credential-relay: WORKSPACE_TOKEN not set" >&2
+  echo "git-credential-relay: All credential sources failed." >&2
+  echo "git-credential-relay: Fallback chain tried:" >&2
+  echo "git-credential-relay:   1. GH_TOKEN/GITHUB_TOKEN env - not set" >&2
+  echo "git-credential-relay:   2. ~/.config/gh/hosts.yml - no token found" >&2
+  echo "git-credential-relay:   3. gh auth token - failed or not installed" >&2
+  echo "git-credential-relay:   4. Cloud API - unavailable (WORKSPACE_TOKEN not set)" >&2
+  echo "git-credential-relay: Fix: Run 'gh auth login' or set GH_TOKEN env var" >&2
   exit 1
 fi
 
@@ -68,8 +186,8 @@ debug "Fetching token from ${CLOUD_API_URL}/api/git/token?workspaceId=${WORKSPAC
 http_code=""
 response=""
 if [[ "${GIT_CREDENTIAL_DEBUG:-}" == "1" ]]; then
-  # With debug, show full curl output
-  response=$(curl -sf -w "\n%{http_code}" \
+  # With debug, show full curl output (5 second timeout)
+  response=$(curl -sf --max-time 5 -w "\n%{http_code}" \
     -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
     "${CLOUD_API_URL}/api/git/token?workspaceId=${WORKSPACE_ID}" \
     2>&1) || true
@@ -78,15 +196,21 @@ if [[ "${GIT_CREDENTIAL_DEBUG:-}" == "1" ]]; then
   debug "HTTP response code: $http_code"
   debug "Response: ${response:0:200}"
 else
-  response=$(curl -sf \
+  # 5 second timeout to prevent git operations from hanging
+  response=$(curl -sf --max-time 5 \
     -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
     "${CLOUD_API_URL}/api/git/token?workspaceId=${WORKSPACE_ID}" \
     2>/dev/null) || true
 fi
 
 if [[ -z "$response" ]]; then
-  echo "git-credential-relay: Failed to fetch token from gateway" >&2
-  echo "git-credential-relay: Check that CLOUD_API_URL is accessible: ${CLOUD_API_URL}" >&2
+  echo "git-credential-relay: All credential sources failed." >&2
+  echo "git-credential-relay: Fallback chain tried:" >&2
+  echo "git-credential-relay:   1. GH_TOKEN/GITHUB_TOKEN env - not set" >&2
+  echo "git-credential-relay:   2. ~/.config/gh/hosts.yml - no token found" >&2
+  echo "git-credential-relay:   3. gh auth token - failed or not installed" >&2
+  echo "git-credential-relay:   4. Cloud API (${CLOUD_API_URL}) - failed to fetch" >&2
+  echo "git-credential-relay: Fix: Run 'gh auth login' or set GH_TOKEN env var" >&2
   exit 1
 fi
 
@@ -105,21 +229,22 @@ if [[ -z "$token" ]]; then
   hint=$(echo "$response" | jq -r '.hint // empty')
   details=$(echo "$response" | jq -r '.details // empty')
 
+  echo "git-credential-relay: All credential sources failed." >&2
+  echo "git-credential-relay: Fallback chain tried:" >&2
+  echo "git-credential-relay:   1. GH_TOKEN/GITHUB_TOKEN env - not set" >&2
+  echo "git-credential-relay:   2. ~/.config/gh/hosts.yml - no token found" >&2
+  echo "git-credential-relay:   3. gh auth token - failed or not installed" >&2
+  echo "git-credential-relay:   4. Cloud API - " >&2
   if [[ -n "$error" ]]; then
-    echo "git-credential-relay: ERROR: $error" >&2
-    if [[ -n "$code" ]]; then
-      echo "git-credential-relay: Code: $code" >&2
-    fi
-    if [[ -n "$hint" ]]; then
-      echo "git-credential-relay: Hint: $hint" >&2
-    fi
-    if [[ -n "$details" ]]; then
-      echo "git-credential-relay: Details: $details" >&2
-    fi
+    echo "git-credential-relay:      Error: $error" >&2
+    [[ -n "$code" ]] && echo "git-credential-relay:      Code: $code" >&2
+    [[ -n "$hint" ]] && echo "git-credential-relay:      Hint: $hint" >&2
+    [[ -n "$details" ]] && echo "git-credential-relay:      Details: $details" >&2
   else
-    echo "git-credential-relay: No token in response" >&2
+    echo "git-credential-relay:      No token in response" >&2
     debug "Raw response: $response"
   fi
+  echo "git-credential-relay: Fix: Run 'gh auth login' or set GH_TOKEN env var" >&2
   exit 1
 fi
 

package/deploy/workspace/git-credential-relay.test.sh

@@ -0,0 +1,230 @@
+#!/usr/bin/env bash
+#
+# Test suite for git-credential-relay fallback chain
+# Run with: bash deploy/workspace/git-credential-relay.test.sh
+#
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CREDENTIAL_HELPER="$SCRIPT_DIR/git-credential-relay"
+
+# Test counter
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Test helper functions
+pass() {
+  echo -e "${GREEN}✓${NC} $1"
+  TESTS_PASSED=$((TESTS_PASSED + 1))
+}
+
+fail() {
+  echo -e "${RED}✗${NC} $1"
+  echo "  Expected: $2"
+  echo "  Got: $3"
+  TESTS_FAILED=$((TESTS_FAILED + 1))
+}
+
+# Create temp directory for test fixtures
+TEST_DIR=$(mktemp -d)
+trap "rm -rf $TEST_DIR" EXIT
+
+# ============================================================
+# TEST 1: GH_TOKEN env var takes priority
+# ============================================================
+test_gh_token_env() {
+  local output
+  output=$(echo -e "protocol=https\nhost=github.com\n" | \
+    GH_TOKEN=ghp_env_token \
+    WORKSPACE_ID="" \
+    CLOUD_API_URL="" \
+    WORKSPACE_TOKEN="" \
+    "$CREDENTIAL_HELPER" get 2>/dev/null)
+
+  if echo "$output" | grep -q "password=ghp_env_token"; then
+    pass "GH_TOKEN env var is used"
+  else
+    fail "GH_TOKEN env var" "password=ghp_env_token" "$output"
+  fi
+}
+
+# ============================================================
+# TEST 2: GITHUB_TOKEN env var works when GH_TOKEN not set
+# ============================================================
+test_github_token_env() {
+  local output
+  output=$(echo -e "protocol=https\nhost=github.com\n" | \
+    GH_TOKEN="" \
+    GITHUB_TOKEN=ghp_github_token \
+    WORKSPACE_ID="" \
+    CLOUD_API_URL="" \
+    WORKSPACE_TOKEN="" \
+    "$CREDENTIAL_HELPER" get 2>/dev/null)
+
+  if echo "$output" | grep -q "password=ghp_github_token"; then
+    pass "GITHUB_TOKEN env var is used when GH_TOKEN not set"
+  else
+    fail "GITHUB_TOKEN env var" "password=ghp_github_token" "$output"
+  fi
+}
+
+# ============================================================
+# TEST 3: hosts.yml file is parsed correctly
+# ============================================================
+test_hosts_yml() {
+  # Create mock hosts.yml
+  mkdir -p "$TEST_DIR/gh"
+  cat > "$TEST_DIR/gh/hosts.yml" << 'EOF'
+github.com:
+    user: testuser
+    oauth_token: gho_hostsfile_token
+    git_protocol: https
+EOF
+
+  local output
+  output=$(echo -e "protocol=https\nhost=github.com\n" | \
+    GH_TOKEN="" \
+    GITHUB_TOKEN="" \
+    XDG_CONFIG_HOME="$TEST_DIR" \
+    WORKSPACE_ID="" \
+    CLOUD_API_URL="" \
+    WORKSPACE_TOKEN="" \
+    "$CREDENTIAL_HELPER" get 2>/dev/null)
+
+  if echo "$output" | grep -q "password=gho_hostsfile_token"; then
+    pass "hosts.yml file is parsed and token extracted"
+  else
+    fail "hosts.yml parsing" "password=gho_hostsfile_token" "$output"
+  fi
+}
+
+# ============================================================
+# TEST 4: hosts.yml with 'token' field (alternative format)
+# ============================================================
+test_hosts_yml_token_field() {
+  # Create mock hosts.yml with 'token' instead of 'oauth_token'
+  # Note: XDG_CONFIG_HOME should point to parent of gh/ directory
+  mkdir -p "$TEST_DIR/config2/gh"
+  cat > "$TEST_DIR/config2/gh/hosts.yml" << 'EOF'
+github.com:
+    user: anotheruser
+    token: gho_token_field
+    git_protocol: https
+EOF
+
+  local output
+  output=$(echo -e "protocol=https\nhost=github.com\n" | \
+    GH_TOKEN="" \
+    GITHUB_TOKEN="" \
+    XDG_CONFIG_HOME="$TEST_DIR/config2" \
+    WORKSPACE_ID="" \
+    CLOUD_API_URL="" \
+    WORKSPACE_TOKEN="" \
+    "$CREDENTIAL_HELPER" get 2>/dev/null)
+
+  if echo "$output" | grep -q "password=gho_token_field"; then
+    pass "hosts.yml with 'token' field works"
+  else
+    fail "hosts.yml token field" "password=gho_token_field" "$output"
+  fi
+}
+
+# ============================================================
+# TEST 5: Non-github.com hosts are ignored
+# ============================================================
+test_non_github_host() {
+  local output
+  local exit_code=0
+  output=$(echo -e "protocol=https\nhost=gitlab.com\n" | \
+    GH_TOKEN="should_not_be_used" \
+    "$CREDENTIAL_HELPER" get 2>/dev/null) || exit_code=$?
+
+  # Should exit 0 but produce no credentials
+  if [[ $exit_code -eq 0 ]] && [[ -z "$output" || ! "$output" =~ "password=" ]]; then
+    pass "Non-github.com hosts are ignored"
+  else
+    fail "Non-github.com handling" "empty output" "$output (exit: $exit_code)"
+  fi
+}
+
+# ============================================================
+# TEST 6: Clear error message when no credentials found
+# ============================================================
+test_error_message() {
+  local output
+  local exit_code=0
+  output=$(echo -e "protocol=https\nhost=github.com\n" | \
+    GH_TOKEN="" \
+    GITHUB_TOKEN="" \
+    XDG_CONFIG_HOME="/nonexistent" \
+    HOME="/nonexistent" \
+    WORKSPACE_ID="" \
+    CLOUD_API_URL="" \
+    WORKSPACE_TOKEN="" \
+    "$CREDENTIAL_HELPER" get 2>&1) || exit_code=$?
+
+  if [[ $exit_code -ne 0 ]] && echo "$output" | grep -q "Fallback chain tried"; then
+    pass "Clear error message shows fallback chain"
+  else
+    fail "Error message" "Contains 'Fallback chain tried'" "$output"
+  fi
+}
+
+# ============================================================
+# TEST 7: GH_TOKEN takes priority over hosts.yml
+# ============================================================
+test_env_priority_over_file() {
+  # Create mock hosts.yml
+  mkdir -p "$TEST_DIR/gh3"
+  cat > "$TEST_DIR/gh3/hosts.yml" << 'EOF'
+github.com:
+    oauth_token: gho_should_not_use_this
+EOF
+
+  local output
+  output=$(echo -e "protocol=https\nhost=github.com\n" | \
+    GH_TOKEN=ghp_env_wins \
+    GITHUB_TOKEN="" \
+    XDG_CONFIG_HOME="$TEST_DIR/gh3" \
+    WORKSPACE_ID="" \
+    CLOUD_API_URL="" \
+    WORKSPACE_TOKEN="" \
+    "$CREDENTIAL_HELPER" get 2>/dev/null)
+
+  if echo "$output" | grep -q "password=ghp_env_wins"; then
+    pass "GH_TOKEN env takes priority over hosts.yml"
+  else
+    fail "Priority: env > file" "password=ghp_env_wins" "$output"
+  fi
+}
+
+# ============================================================
+# Run all tests
+# ============================================================
+echo "=========================================="
+echo "git-credential-relay Fallback Chain Tests"
+echo "=========================================="
+echo ""
+
+test_gh_token_env
+test_github_token_env
+test_hosts_yml
+test_hosts_yml_token_field
+test_non_github_host
+test_error_message
+test_env_priority_over_file
+
+echo ""
+echo "=========================================="
+echo "Results: $TESTS_PASSED passed, $TESTS_FAILED failed"
+echo "=========================================="
+
+if [[ $TESTS_FAILED -gt 0 ]]; then
+  exit 1
+fi