entrypoint.go

package sbox

import (
	"bufio"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"log/slog"
	"os"
	"context"
	"os/exec"
	"os/signal"
	"path/filepath"
	"runtime"
	"slices"
	"sort"
	"strings"
	"syscall"
	"time"

	"github.com/kaptinlin/jsonmerge"
	cli "github.com/streamingfast/cli"
	"go.uber.org/zap"
	"gopkg.in/yaml.v3"
)

// entrypointLogFile is the path for entrypoint debug logging
const entrypointLogFile = "/tmp/sbox-entrypoint.log"

// elog is the entrypoint file logger (initialized by initEntrypointLog)
var elog *slog.Logger

// initEntrypointLog initializes the file logger for entrypoint debugging.
// Logs are appended to /tmp/sbox-entrypoint.log
func initEntrypointLog() func() {
	f, err := os.OpenFile(entrypointLogFile, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
	if err != nil {
		// Can't log to file, use a no-op logger
		elog = slog.New(slog.NewTextHandler(io.Discard, nil))
		return func() {}
	}

	// Write separator for new run (extra blank line before makes consecutive runs easy to spot)
	fmt.Fprintf(f, "\n\n========== sbox entrypoint new run at %s ==========\n", time.Now().Format(time.RFC3339))

	elog = slog.New(slog.NewTextHandler(f, &slog.HandlerOptions{
		Level: slog.LevelDebug,
	}))

	return func() { f.Close() }
}

// logEnvironment logs relevant environment variables for debugging
func logEnvironment() {
	env := os.Environ()
	sort.Strings(env)

	// Log interesting env vars
	interesting := []string{
		"HOME", "USER", "PWD", "SHELL",
		"WORKSPACE_DIR",
		"CLAUDE", "CLAUDECODE", "IS_SANDBOX",
		"PATH",
	}

	elog.Info("environment snapshot")
	for _, key := range interesting {
		if val := os.Getenv(key); val != "" {
			elog.Debug("env", "key", key, "value", val)
		}
	}

	// Log all env vars at trace level (as debug with prefix)
	elog.Debug("full environment", "count", len(env))
	for _, e := range env {
		elog.Debug("env.full", "entry", e)
	}
}

// EntrypointConfigVersion is the current version of the entrypoint config format.
// Increment this when making breaking changes to the config structure.
const EntrypointConfigVersion = 1

// EntrypointConfig is the configuration file exchanged between `sbox run` (host)
// and `sbox entrypoint` (container). It's written to .sbox/entrypoint.yaml.
type EntrypointConfig struct {
	// Version is the config format version for compatibility checking
	Version int `yaml:"version"`

	// Plugins to install in the sandbox
	Plugins []EntrypointPlugin `yaml:"plugins,omitempty"`

	// Agents to install in the sandbox
	Agents []EntrypointAgent `yaml:"agents,omitempty"`

	// Agent specifies which AI agent to run ("claude" or "opencode")
	Agent string `yaml:"agent,omitempty"`

	// Prompt is an optional prompt to pass to the agent via -p flag.
	// When set, the agent runs non-interactively with this prompt.
	// Used by `sbox loop` to pass the loop prompt to the agent.
	Prompt string `yaml:"prompt,omitempty"`

	// Loop mode fields — when LoopMode is true, the entrypoint runs the agent
	// in a loop until the goal is confirmed complete.
	LoopMode          bool `yaml:"loop_mode,omitempty"`
	MaxIterations     int  `yaml:"max_iterations,omitempty"`
	LoopConfirmations int  `yaml:"loop_confirmations,omitempty"`

	// OpenCode contains settings specific to the OpenCode agent.
	OpenCode *OpenCodeSettings `yaml:"opencode,omitempty"`

	// Developer contains developer-oriented settings for debugging and development
	Developer *DeveloperSettings `yaml:"developer,omitempty"`
}

// OpenCodeSettings contains entrypoint settings specific to the OpenCode agent.
type OpenCodeSettings struct {
	// LoadClaudeSkills enables converting installed Claude Code plugin SKILL.md files
	// into OpenCode rules at startup.
	LoadClaudeSkills bool `yaml:"load_claude_skills,omitempty"`
}

// DeveloperSettings contains developer-oriented settings for debugging and development.
type DeveloperSettings struct {
	// StartupDelay delays agent startup inside the sandbox.
	// If not set (nil), no delay. If 0, infinite delay (wait forever).
	// Otherwise, waits for the specified duration before starting the agent.
	StartupDelay *Duration `yaml:"startup_delay,omitempty"`
}

// EntrypointPlugin describes a plugin to be installed in the sandbox
type EntrypointPlugin struct {
	// Name is the plugin identifier (e.g., "test-plugin@official")
	Name string `yaml:"name"`

	// Path is the relative path within .sbox/ where the plugin files are stored
	// e.g., "plugins/official/test-plugin/abc123"
	Path string `yaml:"path"`

	// Version is the plugin version string
	Version string `yaml:"version,omitempty"`

	// PackageVersion is the package/commit hash
	PackageVersion string `yaml:"package_version,omitempty"`
}

// EntrypointAgent describes an agent to be installed in the sandbox
type EntrypointAgent struct {
	// Name is the agent name (filename without .json extension)
	Name string `yaml:"name"`

	// Path is the relative path within .sbox/ where the agent file is stored
	// e.g., "agents/my-agent.json"
	Path string `yaml:"path"`
}

// WriteEntrypointConfig writes the entrypoint configuration to .sbox/entrypoint.yaml
func WriteEntrypointConfig(workspaceDir string, config *EntrypointConfig) error {
	config.Version = EntrypointConfigVersion

	sboxDir := filepath.Join(workspaceDir, ".sbox")
	if err := os.MkdirAll(sboxDir, 0755); err != nil {
		return fmt.Errorf("failed to create .sbox directory: %w", err)
	}

	configPath := filepath.Join(sboxDir, "entrypoint.yaml")

	data, err := yaml.Marshal(config)
	if err != nil {
		return fmt.Errorf("failed to marshal entrypoint config: %w", err)
	}

	if err := os.WriteFile(configPath, data, 0644); err != nil {
		return fmt.Errorf("failed to write entrypoint config: %w", err)
	}

	return nil
}

// ReadEntrypointConfig reads the entrypoint configuration from .sbox/entrypoint.yaml
// Returns an error if the config version is incompatible.
func ReadEntrypointConfig(workspaceDir string) (*EntrypointConfig, error) {
	configPath := filepath.Join(workspaceDir, ".sbox", "entrypoint.yaml")

	data, err := os.ReadFile(configPath)
	if err != nil {
		return nil, fmt.Errorf("failed to read entrypoint config: %w", err)
	}

	var config EntrypointConfig
	if err := yaml.Unmarshal(data, &config); err != nil {
		return nil, fmt.Errorf("failed to parse entrypoint config: %w", err)
	}

	if config.Version == 0 {
		return nil, fmt.Errorf("entrypoint config missing version field")
	}

	if config.Version > EntrypointConfigVersion {
		return nil, fmt.Errorf("entrypoint config version %d is newer than supported version %d; please update sbox", config.Version, EntrypointConfigVersion)
	}

	// Future: handle migration from older versions if needed
	// For now, we only support the current version

	return &config, nil
}

// WriteEntrypointEnv writes resolved environment variables to .sbox/env
// Each line is in the format KEY=value (already resolved, no passthrough)
func WriteEntrypointEnv(workspaceDir string, envs []string) error {
	sboxDir := filepath.Join(workspaceDir, ".sbox")
	if err := os.MkdirAll(sboxDir, 0755); err != nil {
		return fmt.Errorf("failed to create .sbox directory: %w", err)
	}

	envPath := filepath.Join(sboxDir, "env")

	// Build content with resolved values
	var content string
	for _, env := range envs {
		content += env + "\n"
	}

	if err := os.WriteFile(envPath, []byte(content), 0644); err != nil {
		return fmt.Errorf("failed to write env file: %w", err)
	}

	return nil
}

// ReadEntrypointEnv reads environment variables from .sbox/env
// Returns a slice of KEY=value strings
func ReadEntrypointEnv(workspaceDir string) ([]string, error) {
	envPath := filepath.Join(workspaceDir, ".sbox", "env")

	data, err := os.ReadFile(envPath)
	if err != nil {
		if os.IsNotExist(err) {
			return nil, nil // No env file is OK
		}
		return nil, fmt.Errorf("failed to read env file: %w", err)
	}

	var envs []string
	for _, line := range splitLines(string(data)) {
		line = trimSpace(line)
		if line != "" && !hasPrefix(line, "#") {
			envs = append(envs, line)
		}
	}

	return envs, nil
}

// Helper functions to avoid importing strings package for simple operations
func splitLines(s string) []string {
	var lines []string
	start := 0
	for i := 0; i < len(s); i++ {
		if s[i] == '\n' {
			lines = append(lines, s[start:i])
			start = i + 1
		}
	}
	if start < len(s) {
		lines = append(lines, s[start:])
	}
	return lines
}

func trimSpace(s string) string {
	start := 0
	end := len(s)
	for start < end && (s[start] == ' ' || s[start] == '\t' || s[start] == '\r') {
		start++
	}
	for end > start && (s[end-1] == ' ' || s[end-1] == '\t' || s[end-1] == '\r') {
		end--
	}
	return s[start:end]
}

func hasPrefix(s, prefix string) bool {
	return len(s) >= len(prefix) && s[:len(prefix)] == prefix
}

// SandboxPersistentEnvFile is the path to the persistent environment file in the sandbox.
// We use /etc/profile.d/ rather than /etc/sandbox-persistent.sh because:
//   - /etc/sandbox-persistent.sh is managed by the Docker sandbox infrastructure (CLAUDE_ENV_FILE)
//     and may have permissions that prevent the agent user from writing to it
//   - /etc/profile.d/*.sh files are sourced by login shells (bash -l) which is the recommended
//     invocation pattern in the sandbox CLAUDE.md
const SandboxPersistentEnvFile = "/etc/profile.d/sbox-env.sh"

// ReadWorkspacePath returns the workspace directory.
// Docker sandbox sets PWD and WORKSPACE_DIR to the workspace path.
// Returns empty string if workspace cannot be determined.
func ReadWorkspacePath() string {
	// WORKSPACE_DIR is explicitly set by docker sandbox
	if dir := os.Getenv("WORKSPACE_DIR"); dir != "" {
		return dir
	}
	// Fallback to PWD
	if dir := os.Getenv("PWD"); dir != "" {
		return dir
	}
	// Last resort: get current working directory
	if dir, err := os.Getwd(); err == nil {
		return dir
	}
	return ""
}

// DefaultSandboxClaudeHome is the default Claude home directory inside the sandbox.
// Docker sandbox may mount the host's .claude at the host path instead.
// Use FindClaudeHome() to locate the actual directory.
const DefaultSandboxClaudeHome = "/home/agent/.claude"

// FindClaudeHome locates Claude's config directory inside the sandbox.
// Docker sandbox mounts the host's .claude at the host path (e.g., /Users/username/.claude).
// We search common locations to find where it actually is.
func FindAgentHome(agentType AgentType) string {
	spec := GetAgentSpec(agentType)
	configDirName := spec.ConfigDirName()

	// Check environment variable first (for backwards compatibility with CLAUDE_CONFIG_DIR)
	envVar := strings.ToUpper(spec.BinaryName()) + "_CONFIG_DIR"
	if dir := os.Getenv(envVar); dir != "" {
		if _, err := os.Stat(dir); err == nil {
			return dir
		}
	}

	// Check default location
	defaultHome := filepath.Join("/home/agent", configDirName)
	if _, err := os.Stat(defaultHome); err == nil {
		return defaultHome
	}

	// Search /Users (macOS host mounts)
	entries, _ := os.ReadDir("/Users")
	for _, e := range entries {
		if e.IsDir() {
			agentDir := filepath.Join("/Users", e.Name(), configDirName)
			if _, err := os.Stat(agentDir); err == nil {
				return agentDir
			}
		}
	}

	// Search /home (Linux host mounts)
	entries, _ = os.ReadDir("/home")
	for _, e := range entries {
		if e.IsDir() && e.Name() != "agent" { // Skip agent, already checked
			agentDir := filepath.Join("/home", e.Name(), configDirName)
			if _, err := os.Stat(agentDir); err == nil {
				return agentDir
			}
		}
	}

	// Fallback to default
	return defaultHome
}

// SboxEntrypointMarkerFile is written when sbox entrypoint runs successfully.
// Claude can check this file to verify the entrypoint ran.
const SboxEntrypointMarkerFile = "/tmp/sbox-entrypoint-ran"

// ClaudeCacheDir is the subdirectory in .sbox/ where we cache the .claude folder
// for persistence across sandbox recreations.
const ClaudeCacheDir = "claude-cache"

// OpenCodeCacheDir is the subdirectory in .sbox/ where we cache the .config/opencode folder
// for persistence across sandbox recreations.
const OpenCodeCacheDir = "opencode-cache"

// OpenCodeShareCacheDir is the subdirectory in .sbox/ where we cache the .local/share/opencode folder
// for persistence across sandbox recreations.
const OpenCodeShareCacheDir = "opencode-share-cache"

// RunEntrypoint executes the entrypoint logic inside the sandbox.
// It reads the configuration from .sbox/, sets up plugins/agents/env,
// then execs claude with the provided arguments.
func RunEntrypoint(args []string) error {
	// Initialize file logger (note: log file won't be closed since we exec)
	_ = initEntrypointLog()

	elog.Info("=== RunEntrypoint starting ===", "version", cli.GetDisplayVersion(Version), "args", args)
	logEnvironment()

	zlog.Info("running sbox entrypoint")

	// Read workspace path from env var set by wrapper
	workspaceDir := ReadWorkspacePath()
	elog.Info("workspace lookup", "WORKSPACE_DIR", os.Getenv("WORKSPACE_DIR"), "PWD", os.Getenv("PWD"), "result", workspaceDir)

	if workspaceDir == "" {
		// No workspace found, just exec default agent directly
		elog.Warn("workspace directory not found, exec default agent directly")
		zlog.Info("workspace directory not found, starting default agent directly")
		return execAgent(DefaultAgent, args, nil)
	}

	elog.Info("found workspace directory", "path", workspaceDir)
	zlog.Info("found workspace directory", zap.String("path", workspaceDir))

	// Check for dev override binary. If .sbox/sbox-dev exists, exec it
	// to continue the entrypoint with a newer version of sbox. This enables
	// fast iteration without rebuilding the Docker image.
	if err := maybeExecDevBinary(workspaceDir, args); err != nil {
		// maybeExecDevBinary only returns on error (exec replaces the process on success)
		return err
	}

	// Check .sbox directory contents
	sboxDir := filepath.Join(workspaceDir, ".sbox")
	if entries, err := os.ReadDir(sboxDir); err == nil {
		var files []string
		for _, e := range entries {
			files = append(files, e.Name())
		}
		elog.Info(".sbox directory contents", "path", sboxDir, "files", files)
	} else {
		elog.Warn(".sbox directory not readable", "path", sboxDir, "error", err)
	}

	// Read entrypoint config
	configPath := filepath.Join(sboxDir, "entrypoint.yaml")
	elog.Info("reading entrypoint config", "path", configPath)

	config, err := ReadEntrypointConfig(workspaceDir)
	if err != nil {
		// If no config, just exec default agent directly (backwards compatibility)
		if errors.Is(err, os.ErrNotExist) {
			elog.Warn("no entrypoint config found, exec default agent directly", "path", configPath)
			zlog.Info("no entrypoint config found, starting default agent directly")
			return execAgent(DefaultAgent, args, nil)
		}
		elog.Error("failed to read entrypoint config", "error", err)
		return fmt.Errorf("failed to read entrypoint config: %w", err)
	}

	// Default to claude if no agent specified
	agentType := config.Agent
	if agentType == "" {
		agentType = string(AgentClaude)
	}

	elog.Info("loaded entrypoint config",
		"version", config.Version,
		"plugins", len(config.Plugins),
		"agents", len(config.Agents),
		"agent", agentType)
	zlog.Info("loaded entrypoint config",
		zap.Int("version", config.Version),
		zap.Int("plugins", len(config.Plugins)),
		zap.Int("agents", len(config.Agents)),
		zap.String("agent", agentType))

	// Disable the agent's built-in auto-updater so it doesn't overwrite our shim
	// wrapper. We handle updates ourselves via a background updater that correctly
	// re-shims after each update.
	spec := GetAgentSpec(AgentType(agentType))
	if envVars := spec.DisableAutoUpdateEnv(); envVars != nil {
		for k, v := range envVars {
			os.Setenv(k, v)
			elog.Info("set auto-update disable env var", "key", k, "value", v)
		}
	}

	// Log plugin details
	for i, p := range config.Plugins {
		elog.Debug("plugin", "index", i, "name", p.Name, "path", p.Path)
	}
	// Log agent details
	for i, a := range config.Agents {
		elog.Debug("agent", "index", i, "name", a.Name, "path", a.Path)
	}

	// Find agent home
	agent := AgentType(agentType)
	agentHome := FindAgentHome(agent)
	elog.Info("agent home directory", "path", agentHome, "agent", agentType)

	// Restore agent cache if present (for persistence across recreations)
	elog.Info("checking for agent cache to restore")
	if err := restoreAgentCache(workspaceDir, agent, agentHome); err != nil {
		elog.Warn("failed to restore agent cache", "error", err)
		// Non-fatal - continue anyway
	}

	// Setup CLAUDE.md/AGENTS.md (copy from .sbox to agent home)
	elog.Info("setting up CLAUDE.md/AGENTS.md")
	if err := setupRules(workspaceDir, agent); err != nil {
		elog.Error("failed to setup rules file", "error", err)
		// Non-fatal - continue anyway
	}

	// Setup plugins
	elog.Info("setting up plugins", "count", len(config.Plugins))
	if err := setupPlugins(workspaceDir, config.Plugins); err != nil {
		elog.Error("failed to setup plugins", "error", err)
		return fmt.Errorf("failed to setup plugins: %w", err)
	}

	// Setup agents
	elog.Info("setting up agents", "count", len(config.Agents))
	if err := setupAgents(workspaceDir, agent, config.Agents); err != nil {
		elog.Error("failed to setup agents", "error", err)
		return fmt.Errorf("failed to setup agents: %w", err)
	}

	// Setup Claude settings files — merge with existing sandbox config so that
	// sandbox-side changes (e.g. model selection, theme) are preserved while
	// host-side updates (e.g. MCP servers) are applied.
	if agent == AgentClaude {
		claudeSettingsSrc := filepath.Join(workspaceDir, ".sbox", "claude-settings.json")
		if _, err := os.Stat(claudeSettingsSrc); err == nil {
			claudeSettingsDst := filepath.Join(agentHome, "settings.json")
			elog.Info("merging claude settings.json into agent home", "src", claudeSettingsSrc, "dst", claudeSettingsDst)
			if err := mergeConfigFile(claudeSettingsSrc, claudeSettingsDst); err != nil {
				elog.Warn("failed to merge claude settings.json", "error", err)
				zlog.Warn("failed to merge claude settings.json into agent home", zap.Error(err))
				// Non-fatal - continue anyway
			} else {
				elog.Info("successfully merged claude settings.json")
				zlog.Info("merged claude settings.json into agent home", zap.String("dst", claudeSettingsDst))
			}

			// Always enforce bypass-permissions mode after merge — the sandbox must
			// run without permission prompts regardless of what the cached or host
			// config had.
			for key, val := range map[string]any{
				"defaultMode":                       "bypassPermissions",
				"bypassPermissionsModeAccepted":     true,
				"skipDangerousModePermissionPrompt": true,
			} {
				if err := enforceJSONField(claudeSettingsDst, key, val); err != nil {
					elog.Warn("failed to enforce field in settings.json", "key", key, "error", err)
				}
			}
		} else {
			elog.Debug("claude-settings.json not found in .sbox, skipping", "path", claudeSettingsSrc)
			zlog.Debug("claude-settings.json not found in .sbox, skipping", zap.String("path", claudeSettingsSrc))
		}

		claudeSettingsLocalSrc := filepath.Join(workspaceDir, ".sbox", "claude-settings.local.json")
		if _, err := os.Stat(claudeSettingsLocalSrc); err == nil {
			claudeSettingsLocalDst := filepath.Join(agentHome, "settings.local.json")
			elog.Info("merging claude settings.local.json into agent home", "src", claudeSettingsLocalSrc, "dst", claudeSettingsLocalDst)
			if err := mergeConfigFile(claudeSettingsLocalSrc, claudeSettingsLocalDst); err != nil {
				elog.Warn("failed to merge claude settings.local.json", "error", err)
				zlog.Warn("failed to merge claude settings.local.json into agent home", zap.Error(err))
				// Non-fatal - continue anyway
			} else {
				elog.Info("successfully merged claude settings.local.json")
				zlog.Info("merged claude settings.local.json into agent home", zap.String("dst", claudeSettingsLocalDst))
			}
		} else {
			elog.Debug("claude-settings.local.json not found in .sbox, skipping", "path", claudeSettingsLocalSrc)
			zlog.Debug("claude-settings.local.json not found in .sbox, skipping", zap.String("path", claudeSettingsLocalSrc))
		}
	}

	// Setup OpenCode config and auth files
	if agent == AgentOpenCode {
		// Setup opencode.json (config file) — merge with existing sandbox config
		// so that sandbox-side changes (e.g. model selection) are preserved while
		// host-side updates (e.g. permissions) are applied.
		opencodeConfigSrc := filepath.Join(workspaceDir, ".sbox", "opencode.json")
		if _, err := os.Stat(opencodeConfigSrc); err == nil {
			opencodeConfigDst := filepath.Join(agentHome, "opencode.json")
			elog.Info("merging opencode.json into agent home", "src", opencodeConfigSrc, "dst", opencodeConfigDst)
			if err := mergeConfigFile(opencodeConfigSrc, opencodeConfigDst); err != nil {
				elog.Warn("failed to merge opencode.json", "error", err)
				zlog.Warn("failed to merge opencode.json into agent home", zap.Error(err))
				// Non-fatal - continue anyway
			} else {
				elog.Info("successfully merged opencode.json")
				zlog.Info("merged opencode.json into agent home", zap.String("dst", opencodeConfigDst))
			}

			// Always enforce full permissions after merge — the sandbox must run
			// with all permissions allowed regardless of what the cached or host
			// config had.
			if err := enforceJSONField(opencodeConfigDst, "permission", map[string]any{"*": "allow"}); err != nil {
				elog.Warn("failed to enforce permissions in opencode.json", "error", err)
			}
		} else {
			elog.Debug("opencode.json not found in .sbox, skipping", "path", opencodeConfigSrc)
			zlog.Debug("opencode.json not found in .sbox, skipping", zap.String("path", opencodeConfigSrc))
		}

		// Setup tui.json (TUI config file) — merge with existing sandbox config
		opencodeTUIConfigSrc := filepath.Join(workspaceDir, ".sbox", "tui.json")
		if _, err := os.Stat(opencodeTUIConfigSrc); err == nil {
			opencodeTUIConfigDst := filepath.Join(agentHome, "tui.json")
			elog.Info("merging tui.json into agent home", "src", opencodeTUIConfigSrc, "dst", opencodeTUIConfigDst)
			if err := mergeConfigFile(opencodeTUIConfigSrc, opencodeTUIConfigDst); err != nil {
				elog.Warn("failed to merge tui.json", "error", err)
				zlog.Warn("failed to merge tui.json into agent home", zap.Error(err))
				// Non-fatal - continue anyway
			} else {
				elog.Info("successfully merged tui.json")
				zlog.Info("merged tui.json into agent home", zap.String("dst", opencodeTUIConfigDst))
			}
		} else {
			elog.Debug("tui.json not found in .sbox, skipping", "path", opencodeTUIConfigSrc)
			zlog.Debug("tui.json not found in .sbox, skipping", zap.String("path", opencodeTUIConfigSrc))
		}

		// Setup auth.json (authentication file)
		opencodeAuthSrc := filepath.Join(workspaceDir, ".sbox", "opencode-auth.json")
		if _, err := os.Stat(opencodeAuthSrc); err == nil {
			// OpenCode auth goes in XDG data directory: ~/.local/share/opencode/auth.json
			authDir := filepath.Join("/home/agent", ".local", "share", "opencode")
			if err := os.MkdirAll(authDir, 0755); err != nil {
				elog.Warn("failed to create auth directory", "dir", authDir, "error", err)
				zlog.Warn("failed to create opencode auth directory", zap.String("dir", authDir), zap.Error(err))
			} else {
				opencodeAuthDst := filepath.Join(authDir, "auth.json")
				elog.Info("copying opencode auth.json to data directory", "src", opencodeAuthSrc, "dst", opencodeAuthDst)
				if err := copyFile(opencodeAuthSrc, opencodeAuthDst); err != nil {
					elog.Warn("failed to copy opencode auth.json", "error", err)
					zlog.Warn("failed to copy opencode auth.json", zap.Error(err))
					// Non-fatal - continue anyway
				} else {
					elog.Info("successfully copied opencode auth.json")
					zlog.Info("copied opencode auth.json to data directory", zap.String("dst", opencodeAuthDst))
				}
			}
		} else {
			elog.Debug("opencode auth.json not found in .sbox, skipping", "path", opencodeAuthSrc)
			zlog.Debug("opencode auth.json not found in .sbox, skipping", zap.String("path", opencodeAuthSrc))
		}

		// Restore share cache AFTER individual file setup so cached state from a previous
		// session takes precedence over the initially seeded files (e.g. auth.json).
		if err := restoreOpenCodeShareCache(workspaceDir); err != nil {
			elog.Warn("failed to restore opencode share cache", "error", err)
			// Non-fatal - continue anyway
		}

		// Convert Claude Code plugin SKILL.md files to OpenCode rules (opt-in).
		// Done after cache restore so generated rules always overwrite any stale cached versions.
		if config.OpenCode != nil && config.OpenCode.LoadClaudeSkills {
			if err := setupOpencodeSkills(workspaceDir, agentHome); err != nil {
				elog.Warn("failed to setup opencode skills from claude plugins", "error", err)
				// Non-fatal - continue anyway
			}
		}
	}

	// Load environment variables
	elog.Info("loading environment variables")
	if err := loadEntrypointEnv(workspaceDir); err != nil {
		elog.Error("failed to load environment", "error", err)
		return fmt.Errorf("failed to load environment: %w", err)
	}

	// Collect plugin directories for --plugin-dir flags
	var pluginDirs []string
	for _, plugin := range config.Plugins {
		// Plugin path is relative to .sbox/, e.g. "plugins/claude-plugins-official/code-simplifier/1.0.0"
		pluginDir := filepath.Join(workspaceDir, ".sbox", plugin.Path)
		if _, err := os.Stat(pluginDir); err == nil {
			pluginDirs = append(pluginDirs, pluginDir)
			elog.Info("adding plugin directory", "name", plugin.Name, "path", pluginDir)
		} else {
			elog.Warn("plugin directory not found", "name", plugin.Name, "path", pluginDir)
		}
	}

	elog.Info("=== setup complete, exec agent ===", "agent", agentType, "pluginDirs", pluginDirs)

	// Apply startup delay if configured (developer setting)
	if config.Developer != nil && config.Developer.StartupDelay != nil {
		delay := config.Developer.StartupDelay.Duration
		if delay == 0 {
			elog.Info("startup delay set to 0, waiting forever (use Ctrl+C to cancel)")
			fmt.Println("[sbox] startup-delay is 0, waiting forever without starting agent (Ctrl+C to cancel)")
			select {} // Block forever
		} else {
			elog.Info("applying startup delay", "duration", delay)
			fmt.Printf("[sbox] startup-delay: waiting %s before starting agent...\n", delay)
			time.Sleep(delay)
			elog.Info("startup delay complete, proceeding")
		}
	}

	// Loop mode: run the agent repeatedly until the goal is confirmed complete.
	// The entrypoint handles all iterations internally so the sandbox stays warm.
	if config.LoopMode && config.Prompt != "" {
		elog.Info("entering loop mode", "prompt_length", len(config.Prompt), "max_iterations", config.MaxIterations)
		return runLoop(config, AgentType(agentType), args, pluginDirs, workspaceDir)
	}

	// Single prompt mode (non-loop): run agent once with stream transformer.
	if config.Prompt != "" {
		elog.Info("adding prompt from entrypoint config", "prompt_length", len(config.Prompt))

		// Agent-specific flags for prompt mode, then positional prompt last
		args = append(spec.PromptArgs(), args...)
		args = append(args, config.Prompt)
		return runAgentWithStreamTransformer(AgentType(agentType), args, pluginDirs)
	}

	// For OpenCode, if no args provided, pass the workspace directory
	// OpenCode expects: opencode [project]
	agentTypeEnum := AgentType(agentType)
	if agentTypeEnum == AgentOpenCode && len(args) == 0 {
		args = []string{workspaceDir}
		elog.Info("adding workspace path as first arg for OpenCode", "workspace", workspaceDir)
	}

	// Run the agent as a child process with signal forwarding and background updates
	return runAgent(agentTypeEnum, args, pluginDirs, workspaceDir)
}

// setupRules copies .sbox/CLAUDE.md to agent home/CLAUDE.md or AGENTS.md
// depending on the agent type (Claude uses CLAUDE.md, OpenCode uses AGENTS.md)
func setupRules(workspaceDir string, agentType AgentType) error {
	srcPath := filepath.Join(workspaceDir, ".sbox", "CLAUDE.md")

	// Check if source exists
	if _, err := os.Stat(srcPath); os.IsNotExist(err) {
		zlog.Debug("no rules file in .sbox, skipping")
		return nil
	}

	agentHome := FindAgentHome(agentType)

	// Determine destination filename based on agent type
	// Claude uses CLAUDE.md for backward compatibility
	// OpenCode uses AGENTS.md as the standard name
	var dstFilename string
	if agentType == AgentOpenCode {
		dstFilename = "AGENTS.md"
	} else {
		dstFilename = "CLAUDE.md"
	}
	dstPath := filepath.Join(agentHome, dstFilename)

	// Ensure agent home exists
	if err := os.MkdirAll(agentHome, 0755); err != nil {
		return fmt.Errorf("failed to create agent home: %w", err)
	}

	if err := copyFile(srcPath, dstPath); err != nil {
		return fmt.Errorf("failed to copy %s: %w", dstFilename, err)
	}

	zlog.Info("installed agent instructions file",
		zap.String("agent", string(agentType)),
		zap.String("filename", dstFilename),
		zap.String("src", srcPath),
		zap.String("dst", dstPath))

	return nil
}

// setupPlugins is now a no-op - plugins are loaded via --plugin-dir flag
// The plugin directories in .sbox/plugins/ are passed directly to claude
func setupPlugins(workspaceDir string, plugins []EntrypointPlugin) error {
	// Nothing to do - plugins are loaded via --plugin-dir from .sbox/plugins/
	zlog.Debug("plugins will be loaded via --plugin-dir", zap.Int("count", len(plugins)))
	return nil
}

// setupAgents copies agents from .sbox/agents/ to agent home/agents/
func setupAgents(workspaceDir string, agentType AgentType, agents []EntrypointAgent) error {
	if len(agents) == 0 {
		zlog.Debug("no agents to setup")
		return nil
	}

	agentHome := FindAgentHome(agentType)
	zlog.Info("using agent home directory for agents", zap.String("path", agentHome), zap.String("agent", string(agentType)))

	// Ensure agent home exists with proper permissions
	if err := os.MkdirAll(agentHome, 0755); err != nil {
		return fmt.Errorf("failed to create agent home directory: %w", err)
	}

	agentsDir := filepath.Join(agentHome, "agents")
	if err := os.MkdirAll(agentsDir, 0755); err != nil {
		return fmt.Errorf("failed to create agents directory: %w", err)
	}

	for _, agent := range agents {
		srcPath := filepath.Join(workspaceDir, ".sbox", agent.Path)
		// Use the original filename from Path to preserve extension (.md or .json)
		dstPath := filepath.Join(agentsDir, filepath.Base(agent.Path))

		zlog.Debug("copying agent",
			zap.String("name", agent.Name),
			zap.String("src", srcPath),
			zap.String("dst", dstPath))

		if err := copyFile(srcPath, dstPath); err != nil {
			zlog.Warn("failed to copy agent, skipping",
				zap.String("name", agent.Name),
				zap.Error(err))
			continue
		}

		zlog.Info("agent installed",
			zap.String("name", agent.Name),
			zap.String("path", dstPath))
	}

	return nil
}

// setupOpencodeSkills converts Claude Code plugin SKILL.md files into OpenCode rules files.
// OpenCode rules are always-on markdown files in ~/.config/opencode/rules/ that are included
// in the system prompt automatically, bridging Claude Code's on-demand skill concept to OpenCode.
//
// For each installed plugin, skill files at .sbox/plugins/<publisher>/<plugin>/<ver>/skills/<skill>/SKILL.md
// are stripped of their YAML frontmatter and written to <agentHome>/rules/<plugin>-<skill>.md.
// !command interpolation in the skill body is left as-is for the agent to handle.
func setupOpencodeSkills(workspaceDir string, agentHome string) error {
	pluginsDir := filepath.Join(workspaceDir, ".sbox", "claude-plugins")
	rulesDir := filepath.Join(agentHome, "rules")

	if err := os.MkdirAll(rulesDir, 0755); err != nil {
		return fmt.Errorf("failed to create opencode rules directory: %w", err)
	}

	// Pattern: <publisher>/<plugin-name>/<version>/skills/<skill-name>/SKILL.md
	pattern := filepath.Join(pluginsDir, "*", "*", "*", "skills", "*", "SKILL.md")
	matches, err := filepath.Glob(pattern)
	if err != nil {
		return fmt.Errorf("failed to glob skill files: %w", err)
	}

	count := 0
	for _, skillPath := range matches {
		rel, err := filepath.Rel(pluginsDir, skillPath)
		if err != nil {
			continue
		}
		// parts: [publisher, plugin-name, version, "skills", skill-name, "SKILL.md"]
		parts := strings.SplitN(rel, string(filepath.Separator), 7)
		if len(parts) < 6 {
			continue
		}
		pluginName := parts[1]
		skillName := parts[4]

		content, err := os.ReadFile(skillPath)
		if err != nil {
			zlog.Warn("failed to read skill file, skipping", zap.String("path", skillPath), zap.Error(err))
			continue
		}

		ruleFileName := pluginName + "-" + skillName + ".md"
		rulePath := filepath.Join(rulesDir, ruleFileName)
		if err := os.WriteFile(rulePath, []byte(stripFrontmatter(string(content))), 0644); err != nil {
			zlog.Warn("failed to write opencode rule file, skipping", zap.String("path", rulePath), zap.Error(err))
			continue
		}

		count++
		elog.Info("converted skill to opencode rule", "plugin", pluginName, "skill", skillName, "rule", ruleFileName)
	}

	elog.Info("setup opencode skills as rules", "count", count, "rules_dir", rulesDir)
	return nil
}

// stripFrontmatter removes YAML frontmatter (the leading ---...--- block) from markdown content.
// Returns the content unchanged if no frontmatter is present.
func stripFrontmatter(content string) string {
	if !strings.HasPrefix(content, "---") {
		return content
	}
	rest := content[3:]
	if strings.HasPrefix(rest, "\n") {
		rest = rest[1:]
	}
	end := strings.Index(rest, "\n---")
	if end < 0 {
		return content
	}
	body := rest[end+4:]
	if strings.HasPrefix(body, "\n") {
		body = body[1:]
	}
	return body
}

// SboxDevBinaryEnvVar is set when running via the dev override binary to prevent
// infinite recursion (the dev binary would find itself and try to exec again).
const SboxDevBinaryEnvVar = "SBOX_DEV_ENTRYPOINT"

// maybeExecDevBinary checks for .sbox/sbox-dev and execs it if present.
// Returns nil if no dev binary is found (caller should continue normally).
// On successful exec, this function never returns (process is replaced).
// Returns an error only if the binary exists but cannot be executed.
func maybeExecDevBinary(workspaceDir string, args []string) error {
	// Don't recurse: if we ARE the dev binary, skip this check
	if os.Getenv(SboxDevBinaryEnvVar) == "1" {
		elog.Info("running as dev binary, skipping dev override check")
		return nil
	}

	devBinaryPath := filepath.Join(workspaceDir, ".sbox", "sbox-dev")
	if _, err := os.Stat(devBinaryPath); err != nil {
		return nil // No dev binary, continue normally
	}

	elog.Info("found dev override binary, exec'ing it", "path", devBinaryPath)
	zlog.Info("found sbox-dev override binary, replacing entrypoint",
		zap.String("path", devBinaryPath))
	fmt.Fprintf(os.Stderr, "sbox: using dev override binary at %s\n", devBinaryPath)

	// Build argv: sbox-dev entrypoint [args...]
	argv := append([]string{"sbox-dev", "entrypoint"}, args...)

	// Set env var to prevent the dev binary from recursing
	env := os.Environ()
	env = append(env, SboxDevBinaryEnvVar+"=1")

	err := syscall.Exec(devBinaryPath, argv, env)

	// syscall.Exec only returns on error
	if errors.Is(err, syscall.ENOEXEC) {
		return fmt.Errorf(
			"sbox-dev binary at %s has wrong architecture (exec format error); "+
				"rebuild it for the sandbox platform (linux/%s) with: "+
				"GOOS=linux GOARCH=%s go build -o .sbox/sbox-dev ./cmd/sbox",
			devBinaryPath, runtime.GOARCH, runtime.GOARCH,
		)
	}

	return fmt.Errorf("failed to exec dev binary %s: %w", devBinaryPath, err)
}

// loadEntrypointEnv reads .sbox/env and sets env vars in the current process.
// It also attempts to write exports to the persistent env file for login shells.
func loadEntrypointEnv(workspaceDir string) error {
	envs, err := ReadEntrypointEnv(workspaceDir)
	if err != nil {
		return err
	}

	if len(envs) == 0 {
		zlog.Debug("no environment variables to load")
		return nil
	}

	// Parse all env vars first and set them in the current process.
	// This ensures they're available to the exec'd claude process regardless
	// of whether we can write the persistent file.
	type envEntry struct {
		key, value string
	}
	var entries []envEntry
	for _, env := range envs {
		idx := strings.Index(env, "=")
		if idx < 0 {
			continue // Skip invalid entries
		}
		key := env[:idx]
		value := env[idx+1:]

		os.Setenv(key, value)
		entries = append(entries, envEntry{key, value})
		zlog.Debug("loaded environment variable", zap.String("key", key))
	}

	// Write to persistent env file so vars are available in login shells (bash -l).
	// This is non-fatal: if we can't write the file, env vars are still set in
	// the current process and will be inherited by claude via syscall.Exec.
	f, err := os.OpenFile(SandboxPersistentEnvFile, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0644)
	if err != nil {
		zlog.Warn("could not open persistent env file, env vars will only be available via process environment",
			zap.String("path", SandboxPersistentEnvFile),
			zap.Error(err))
	} else {
		defer f.Close()

		if _, err := f.WriteString("\n# sbox entrypoint environment variables\n"); err != nil {
			zlog.Warn("failed to write to persistent env file", zap.Error(err))
		} else {
			for _, e := range entries {
				exportLine := fmt.Sprintf("export %s=%q\n", e.key, e.value)
				if _, err := f.WriteString(exportLine); err != nil {
					zlog.Warn("failed to write env var to persistent file",
						zap.String("key", e.key), zap.Error(err))
					break
				}
			}
		}
	}

	zlog.Info("loaded environment variables",
		zap.Int("count", len(entries)))

	return nil
}

// execAgent replaces the current process with the specified agent using syscall.Exec
// Uses the AgentSpec interface to get agent-specific configuration
func execAgent(agentType AgentType, args []string, pluginDirs []string) error {
	spec := GetAgentSpec(agentType)

	// Find the agent binary
	binaryPath, err := spec.FindBinary()
	if err != nil {
		if elog != nil {
			elog.Error("failed to find agent binary", "agent", agentType, "error", err)
		}
		fmt.Fprintf(os.Stderr, "\nERROR: %s binary not found in the sandbox.\n", spec.BinaryName())
		fmt.Fprintf(os.Stderr, "%s must be installed in the sandbox to use --agent=%s\n", spec.BinaryName(), agentType)
		fmt.Fprintf(os.Stderr, "Searched locations: /home/agent/.local/bin/%s, /usr/local/bin/%s, /usr/bin/%s\n\n",
			spec.BinaryName(), spec.BinaryName(), spec.BinaryName())
		return fmt.Errorf("failed to find %s: %w", spec.BinaryName(), err)
	}

	// Build argv with agent-specific arguments plus additional args
	argv := spec.ExecArgs(pluginDirs)
	argv = append(argv, args...)

	if elog != nil {
		elog.Info("executing agent (syscall.Exec)", "agent", agentType, "path", binaryPath, "argv", argv)
	}
	zlog.Info("executing agent",
		zap.String("agent", string(agentType)),
		zap.String("path", binaryPath),
		zap.Strings("args", argv))

	// Exec replaces current process (log file will be closed automatically)
	return syscall.Exec(binaryPath, argv, os.Environ())
}

const (
	// agentUpdateCheckInterval is how often the background updater checks
	// whether an update is needed.
	agentUpdateCheckInterval = 15 * time.Minute

	// agentUpdateThreshold is the minimum time between actual update attempts.
	agentUpdateThreshold = 24 * time.Hour

	// lastAgentUpdateFile is the filename in .sbox/ that stores the last update timestamp.
	lastAgentUpdateFile = "last-agent-update"
)

// runAgent spawns the agent as a child process with signal forwarding and a
// background updater that periodically updates the agent binary and re-shims.
func runAgent(agentType AgentType, args []string, pluginDirs []string, workspaceDir string) error {
	spec := GetAgentSpec(agentType)

	binaryPath, err := spec.FindBinary()
	if err != nil {
		if elog != nil {
			elog.Error("failed to find agent binary", "agent", agentType, "error", err)
		}
		fmt.Fprintf(os.Stderr, "\nERROR: %s binary not found in the sandbox.\n", spec.BinaryName())
		return fmt.Errorf("failed to find %s: %w", spec.BinaryName(), err)
	}

	argv := spec.ExecArgs(pluginDirs)
	argv = append(argv, args...)

	if elog != nil {
		elog.Info("running agent as child process", "agent", agentType, "path", binaryPath, "argv", argv)
	}

	cmd := exec.Command(binaryPath, argv[1:]...)
	cmd.Stdin = os.Stdin
	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr

	if err := cmd.Start(); err != nil {
		return fmt.Errorf("failed to start agent: %w", err)
	}

	// Forward signals to the child process
	sigCh := make(chan os.Signal, 1)
	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT, syscall.SIGHUP)
	go func() {
		for sig := range sigCh {
			_ = cmd.Process.Signal(sig)
		}
	}()

	// Start background updater
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()
	if spec.UpdateArgs() != nil {
		go runAgentUpdater(ctx, spec, workspaceDir)
	}

	err = cmd.Wait()
	signal.Stop(sigCh)
	close(sigCh)

	if err != nil {
		if exitErr, ok := err.(*exec.ExitError); ok {
			os.Exit(exitErr.ExitCode())
		}
		return err
	}
	return nil
}

// runAgentUpdater periodically checks if the agent needs updating and performs
// the update + shim restoration if the last update was more than agentUpdateThreshold ago.
func runAgentUpdater(ctx context.Context, spec AgentSpec, workspaceDir string) {
	ticker := time.NewTicker(agentUpdateCheckInterval)
	defer ticker.Stop()

	for {
		select {
		case <-ctx.Done():
			return
		case <-ticker.C:
			if err := maybeUpdateAgent(spec, workspaceDir); err != nil {
				if elog != nil {
					elog.Error("agent auto-update failed", "agent", spec.BinaryName(), "error", err)
				}
			}
		}
	}
}

// maybeUpdateAgent checks the last update timestamp and performs an update if stale.
func maybeUpdateAgent(spec AgentSpec, workspaceDir string) error {
	sboxDir := filepath.Join(workspaceDir, ".sbox")
	updateFile := filepath.Join(sboxDir, lastAgentUpdateFile)

	if info, err := os.Stat(updateFile); err == nil {
		age := time.Since(info.ModTime())
		if age < agentUpdateThreshold {
			if elog != nil {
				elog.Info("agent auto-update skipped, last update is recent enough",
					"agent", spec.BinaryName(),
					"last_update_age", age.Round(time.Second).String(),
					"threshold", agentUpdateThreshold.String())
			}
			return nil
		}
	}

	if elog != nil {
		elog.Info("agent auto-update starting", "agent", spec.BinaryName())
	}

	if err := performAgentUpdate(spec); err != nil {
		return err
	}

	if elog != nil {
		elog.Info("agent auto-update completed successfully", "agent", spec.BinaryName())
	}

	// Touch the timestamp file (content doesn't matter, we use ModTime)
	return os.WriteFile(updateFile, []byte(time.Now().Format(time.RFC3339)+"\n"), 0644)
}

// performAgentUpdate runs the agent's update command, then repairs the shim so
// that the wrapper remains the entry point for the agent binary name.
//
// The update flow:
//  1. Run <agent>-real update (e.g. claude-real update)
//  2. The updater may overwrite the <agent> symlink to point to the new version
//  3. Read where <agent> now points — that's the new real binary
//  4. Update <agent>-real to point to the new version
//  5. Restore <agent> to point back to our wrapper shim
func performAgentUpdate(spec AgentSpec) error {
	realBinaryPath, err := spec.FindBinary()
	if err != nil {
		return fmt.Errorf("cannot find agent binary for update: %w", err)
	}

	updateArgs := spec.UpdateArgs()
	if elog != nil {
		elog.Info("running agent update command", "binary", realBinaryPath, "args", updateArgs)
	}

	cmd := exec.Command(realBinaryPath, updateArgs...)
	output, err := cmd.CombinedOutput()
	if elog != nil && len(output) > 0 {
		elog.Info("agent update command output", "output", string(output))
	}
	if err != nil {
		return fmt.Errorf("agent update command failed: %w", err)
	}

	if elog != nil {
		elog.Info("agent update command exited successfully, ensuring shim is intact")
	}

	return ensureAgentShim(spec, realBinaryPath)
}

// ensureAgentShim verifies and repairs the shim setup after an update.
//
// Given realBinaryPath (e.g. /home/agent/.local/bin/claude-real), the agent
// path is derived by stripping the "-real" suffix (e.g. /home/agent/.local/bin/claude).
//
// If the updater overwrote the agent symlink, we capture where it now points,
// update <agent>-real to that target, and restore <agent> to point to our wrapper.
func ensureAgentShim(spec AgentSpec, realBinaryPath string) error {
	binaryName := spec.BinaryName()
	dir := filepath.Dir(realBinaryPath)
	agentPath := filepath.Join(dir, binaryName)
	wrapperPath := filepath.Join("/usr/local/bin", spec.WrapperName())

	// Check if the agent symlink still points to our wrapper
	currentTarget, err := os.Readlink(agentPath)
	if err == nil && currentTarget == wrapperPath {
		if elog != nil {
			elog.Info("shim is intact, no repair needed")
		}
		return nil
	}

	if elog != nil {
		elog.Info("shim was overwritten by update, repairing",
			"agent_path", agentPath,
			"current_target", currentTarget,
			"expected_wrapper", wrapperPath)
	}

	// The updater changed <agent> — figure out the new real binary location.
	// If <agent> is a symlink, the target is the new version.
	// If <agent> is a regular file, move it to <agent>-real.
	if currentTarget != "" {
		// It's a symlink — update <agent>-real to point to the same target
		os.Remove(realBinaryPath)
		if err := os.Symlink(currentTarget, realBinaryPath); err != nil {
			return fmt.Errorf("failed to update %s-real symlink: %w", binaryName, err)
		}
	} else {
		// It's a regular file (or readlink failed) — move it to <agent>-real
		if err := os.Rename(agentPath, realBinaryPath); err != nil {
			return fmt.Errorf("failed to move updated binary to %s-real: %w", binaryName, err)
		}
	}

	// Restore <agent> to point to our wrapper
	os.Remove(agentPath)
	if err := os.Symlink(wrapperPath, agentPath); err != nil {
		return fmt.Errorf("failed to restore wrapper symlink: %w", err)
	}

	if elog != nil {
		elog.Info("shim repaired successfully",
			"agent_path", agentPath, "target", wrapperPath,
			"real_path", realBinaryPath)
	}

	return nil
}

// runAgentWithStreamTransformer spawns the agent as a subprocess and pipes its
// stdout through a stream printer. Used in loop mode and single prompt mode
// where the agent outputs JSON and we want to display human-readable progress.
func runAgentWithStreamTransformer(agentType AgentType, args []string, pluginDirs []string) error {
	spec := GetAgentSpec(agentType)

	binaryPath, err := spec.FindBinary()
	if err != nil {
		fmt.Fprintf(os.Stderr, "\nERROR: %s binary not found in the sandbox.\n", spec.BinaryName())
		return fmt.Errorf("failed to find %s: %w", spec.BinaryName(), err)
	}

	argv := spec.ExecArgs(pluginDirs)
	argv = append(argv, args...)

	if elog != nil {
		elog.Info("running agent with stream transformer", "agent", agentType, "path", binaryPath, "argv", argv)
	}

	cmd := exec.Command(binaryPath, argv[1:]...) // argv[0] is the binary name
	cmd.Stdin = os.Stdin
	cmd.Stderr = os.Stderr

	stdout, err := cmd.StdoutPipe()
	if err != nil {
		return fmt.Errorf("failed to create stdout pipe: %w", err)
	}

	if err := cmd.Start(); err != nil {
		return fmt.Errorf("failed to start agent: %w", err)
	}

	printer := spec.NewStreamPrinter(os.Stdout)

	scanner := bufio.NewScanner(stdout)
	scanner.Buffer(make([]byte, 1024*1024), 1024*1024) // 1MB buffer for large JSON lines
	for scanner.Scan() {
		printer.ProcessLine(scanner.Text())
	}

	if err := scanner.Err(); err != nil {
		if elog != nil {
			elog.Error("scanner error reading agent stdout", "error", err)
		}
	}

	return cmd.Wait()
}

// LoopPromptSuffix is appended to the user's prompt to instruct the agent
// about loop mode behavior and completion signaling.
const LoopPromptSuffix = `

## Loop Mode Instructions

You are running inside an automated loop managed by 'sbox loop'. Your ultimate goal is described above.

**Your task on each iteration:**
1. First, assess whether the goal described above has ALREADY been fully achieved.
2. If the goal is NOT yet achieved, work toward completing it. Make meaningful progress.
3. If the goal IS fully achieved (either it was already done or you just completed it), write a completion file at '.sbox/loop.completion' with a brief summary of what was accomplished.

**Important rules:**
- The file '.sbox/loop.completion' must be written ONLY when the goal is truly complete.
- If you write the completion file, also include a brief summary of the completed work as the file content.
- If the goal is not yet complete, do NOT write the completion file. Just work toward the goal and exit.
- You will be re-launched automatically if the goal is not yet complete.
`

// runLoop runs the agent in a loop inside the container until the goal is
// confirmed complete the required number of consecutive times, or max iterations is exceeded.
func runLoop(config *EntrypointConfig, agentType AgentType, baseArgs []string, pluginDirs []string, workspaceDir string) error {
	ui := DefaultUI
	completionFile := filepath.Join(workspaceDir, ".sbox", LoopCompletionFile)
	fullPrompt := config.Prompt + LoopPromptSuffix

	requiredConfirmations := config.LoopConfirmations
	if requiredConfirmations <= 0 {
		requiredConfirmations = 2
	}

	completionCount := 0
	iteration := 0

	for {
		iteration++

		if config.MaxIterations > 0 && iteration > config.MaxIterations {
			ui.MaxReached(config.MaxIterations)
			return nil
		}

		// Remove completion file before each run
		os.Remove(completionFile)

		// Build iteration-specific prompt
		iterationPrompt := fullPrompt
		if iteration > 1 {
			iterationPrompt = fmt.Sprintf("%s\n\n**Iteration %d**: This is loop iteration #%d. The goal has not yet been confirmed as complete. Continue working toward it.\n", fullPrompt, iteration, iteration)
		}

		ui.Iteration(iteration, completionCount)

		// Build args for this iteration: agent-specific prompt flags, then prompt last
		spec := GetAgentSpec(agentType)
		args := append(spec.PromptArgs(), baseArgs...)
		args = append(args, iterationPrompt)

		if err := runAgentWithStreamTransformer(agentType, args, pluginDirs); err != nil {
			ui.AgentError(err)
			return fmt.Errorf("loop stopped: agent exited with error: %w", err)
		}

		// Check for completion file
		content, err := os.ReadFile(completionFile)
		if err == nil && len(strings.TrimSpace(string(content))) > 0 {
			completionCount++
			ui.Completed(completionCount, requiredConfirmations)

			if completionCount >= requiredConfirmations {
				ui.Confirmed(iteration)
				return nil
			}

			// Don't print "Re-running to confirm" if next iteration would exceed max
			if config.MaxIterations <= 0 || iteration+1 <= config.MaxIterations {
				ui.Reconfirming()
			}
		} else {
			completionCount = 0
			ui.Continuing()
		}
	}
}

// copyDir recursively copies a directory
func copyDir(src, dst string) error {
	srcInfo, err := os.Stat(src)
	if err != nil {
		return err
	}

	if err := os.MkdirAll(dst, srcInfo.Mode()); err != nil {
		return err
	}

	entries, err := os.ReadDir(src)
	if err != nil {
		return err
	}

	for _, entry := range entries {
		srcPath := filepath.Join(src, entry.Name())
		dstPath := filepath.Join(dst, entry.Name())

		if entry.IsDir() {
			if err := copyDir(srcPath, dstPath); err != nil {
				return err
			}
		} else {
			if err := copyFile(srcPath, dstPath); err != nil {
				return err
			}
		}
	}

	return nil
}

// copyFile copies a single file
func copyFile(src, dst string) error {
	srcFile, err := os.Open(src)
	if err != nil {
		return err
	}
	defer srcFile.Close()

	srcInfo, err := srcFile.Stat()
	if err != nil {
		return err
	}

	dstFile, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, srcInfo.Mode())
	if err != nil {
		return err
	}
	defer dstFile.Close()

	_, err = io.Copy(dstFile, srcFile)
	return err
}

// mergeConfigFile merges a source config file (from .sbox/, host-prepared) into
// a destination config file (in the sandbox agent home). If the destination
// already exists, the two are deep-merged with the destination (sandbox) winning
// for any conflicting keys. If the destination does not exist, the source is
// simply copied.
//
// Supports both JSON (.json) and YAML (.yaml, .yml) files. The file format is
// determined by the source file extension.
func mergeConfigFile(src, dst string) error {
	srcData, err := os.ReadFile(src)
	if err != nil {
		return fmt.Errorf("failed to read source config %s: %w", src, err)
	}

	isYAML := strings.HasSuffix(src, ".yaml") || strings.HasSuffix(src, ".yml")

	// Parse source into map
	srcMap := make(map[string]any)
	if isYAML {
		if err := yaml.Unmarshal(srcData, &srcMap); err != nil {
			return fmt.Errorf("failed to parse source YAML %s: %w", src, err)
		}
	} else {
		if err := json.Unmarshal(srcData, &srcMap); err != nil {
			return fmt.Errorf("failed to parse source JSON %s: %w", src, err)
		}
	}

	// If destination doesn't exist, just write the source
	dstData, err := os.ReadFile(dst)
	if err != nil {
		if os.IsNotExist(err) {
			return copyFile(src, dst)
		}
		return fmt.Errorf("failed to read destination config %s: %w", dst, err)
	}

	// Parse destination into map
	dstMap := make(map[string]any)
	if isYAML {
		if err := yaml.Unmarshal(dstData, &dstMap); err != nil {
			// Destination is corrupted, overwrite with source
			if elog != nil {
				elog.Warn("destination config is invalid, overwriting", "dst", dst, "error", err)
			}
			return copyFile(src, dst)
		}
	} else {
		if err := json.Unmarshal(dstData, &dstMap); err != nil {
			if elog != nil {
				elog.Warn("destination config is invalid, overwriting", "dst", dst, "error", err)
			}
			return copyFile(src, dst)
		}
	}

	// Merge using RFC 7386 JSON Merge Patch semantics:
	// source (host-prepared) is the target, destination (sandbox) is the patch.
	// This means sandbox values override host values — sandbox wins for conflicts.
	result, err := jsonmerge.Merge(srcMap, dstMap)
	if err != nil {
		return fmt.Errorf("failed to merge configs: %w", err)
	}

	// Write merged result
	var outData []byte
	if isYAML {
		outData, err = yaml.Marshal(result.Doc)
	} else {
		outData, err = json.MarshalIndent(result.Doc, "", "  ")
		if err == nil {
			outData = append(outData, '\n')
		}
	}
	if err != nil {
		return fmt.Errorf("failed to marshal merged config: %w", err)
	}

	return os.WriteFile(dst, outData, 0644)
}

// enforceJSONField reads a JSON file, sets the given key to the given value
// (overriding whatever was there), and writes it back. This is used to enforce
// critical fields like permissions that must always have a specific value
// regardless of merge results.
func enforceJSONField(path string, key string, value any) error {
	data, err := os.ReadFile(path)
	if err != nil {
		return err
	}

	var m map[string]any
	if err := json.Unmarshal(data, &m); err != nil {
		return err
	}

	m[key] = value

	out, err := json.MarshalIndent(m, "", "  ")
	if err != nil {
		return err
	}

	return os.WriteFile(path, append(out, '\n'), 0644)
}

// PrepareSboxDirectory populates the .sbox/ directory in the workspace with
// plugins, agents, env vars, CLAUDE.md, and the entrypoint config. This is called by
// `sbox run` before starting the sandbox.
func PrepareSboxDirectory(workspaceDir string, config *Config, globalEnvs, projectEnvs, sboxFileEnvs []string, backend BackendType, agent AgentType, opts BackendOptions) error {
	sboxDir := filepath.Join(workspaceDir, ".sbox")

	zlog.Info("preparing .sbox directory",
		zap.String("workspace", workspaceDir),
		zap.String("sbox_dir", sboxDir),
		zap.String("backend", string(backend)),
		zap.String("agent", string(agent)))

	// Create .sbox directory
	if err := os.MkdirAll(sboxDir, 0755); err != nil {
		return fmt.Errorf("failed to create .sbox directory: %w", err)
	}

	// Prepare merged CLAUDE.md file with backend-specific context
	if err := prepareRules(workspaceDir, sboxDir, backend); err != nil {
		zlog.Warn("failed to prepare rules file", zap.Error(err))
		// Continue - rules file is optional
	}

	entrypointConfig := &EntrypointConfig{
		Agent:             string(agent),
		Prompt:            opts.Prompt,
		LoopMode:          opts.LoopMode,
		MaxIterations:     opts.MaxIterations,
		LoopConfirmations: opts.LoopConfirmations,
	}

	if opts.SboxFile != nil && opts.SboxFile.Config != nil && opts.SboxFile.Config.OpenCode != nil {
		entrypointConfig.OpenCode = &OpenCodeSettings{
			LoadClaudeSkills: opts.SboxFile.Config.OpenCode.LoadClaudeSkills,
		}
	}

	// Copy developer settings from backend options
	if opts.StartupDelay != nil {
		entrypointConfig.Developer = &DeveloperSettings{
			StartupDelay: &Duration{Duration: *opts.StartupDelay},
		}
	}

	// Copy plugins and agents from agent-specific home directory
	agentHome := config.GetAgentHome(agent)
	zlog.Info("preparing plugins and agents",
		zap.String("agent", string(agent)),
		zap.String("agent_home", agentHome))

	// Copy plugins
	plugins, err := preparePlugins(agentHome, sboxDir, "plugins")
	if err != nil {
		zlog.Warn("failed to prepare plugins", zap.Error(err))
		// Continue - plugins are optional
	} else {
		entrypointConfig.Plugins = plugins
	}

	// Copy agents
	agents, err := prepareAgents(agentHome, sboxDir)
	if err != nil {
		zlog.Warn("failed to prepare agents", zap.Error(err))
		// Continue - agents are optional
	} else {
		entrypointConfig.Agents = agents
	}

	// When running OpenCode with LoadClaudeSkills, also copy Claude Code plugins to
	// .sbox/claude-plugins/ so the entrypoint can convert SKILL.md files to OpenCode rules.
	if agent == AgentOpenCode && entrypointConfig.OpenCode != nil && entrypointConfig.OpenCode.LoadClaudeSkills {
		claudeHome := config.GetAgentHome(AgentClaude)
		if _, err := preparePlugins(claudeHome, sboxDir, "claude-plugins"); err != nil {
			zlog.Warn("failed to prepare claude plugins for opencode skills", zap.Error(err))
			// Non-fatal - continue anyway
		}
	}

	// Prepare Claude settings files
	if agent == AgentClaude {
		if err := prepareClaudeSettings(agentHome, sboxDir); err != nil {
			zlog.Warn("failed to prepare claude settings", zap.Error(err))
			// Non-fatal - continue anyway
		}
	}

	// Prepare OpenCode files (config and auth)
	if agent == AgentOpenCode {
		if err := prepareOpencodeConfig(agentHome, sboxDir); err != nil {
			zlog.Warn("failed to prepare opencode.json", zap.Error(err))
			// Non-fatal - continue anyway
		}
		if err := prepareOpencodeAuth(sboxDir); err != nil {
			zlog.Warn("failed to prepare opencode auth.json", zap.Error(err))
			// Non-fatal - continue anyway
		}
		if err := prepareOpencodeTUIConfig(agentHome, sboxDir); err != nil {
			zlog.Warn("failed to prepare tui.json", zap.Error(err))
			// Non-fatal - continue anyway
		}
	}

	// Write entrypoint config
	if err := WriteEntrypointConfig(workspaceDir, entrypointConfig); err != nil {
		return fmt.Errorf("failed to write entrypoint config: %w", err)
	}

	// Prepare and write environment variables
	resolvedEnvs := resolveEnvs(globalEnvs, projectEnvs, sboxFileEnvs)
	resolvedEnvs = addTerminalEnvs(resolvedEnvs)
	if err := WriteEntrypointEnv(workspaceDir, resolvedEnvs); err != nil {
		return fmt.Errorf("failed to write env file: %w", err)
	}

	zlog.Info("prepared .sbox directory",
		zap.Int("plugins", len(entrypointConfig.Plugins)),
		zap.Int("agents", len(entrypointConfig.Agents)),
		zap.Int("envs", len(resolvedEnvs)))

	return nil
}

// preparePlugins copies installed plugins to .sbox/<subDir>/
func preparePlugins(claudeHome, sboxDir, subDir string) ([]EntrypointPlugin, error) {
	pluginsJSONPath := filepath.Join(claudeHome, "plugins", "installed_plugins.json")
	hostCachePath := filepath.Join(claudeHome, "plugins", "cache")

	// Check if installed_plugins.json exists
	if _, err := os.Stat(pluginsJSONPath); os.IsNotExist(err) {
		zlog.Debug("installed_plugins.json not found, skipping plugins")
		return nil, nil
	}

	// Read the file
	content, err := os.ReadFile(pluginsJSONPath)
	if err != nil {
		return nil, fmt.Errorf("failed to read installed_plugins.json: %w", err)
	}

	// Parse JSON
	var installedPlugins InstalledPlugins
	if err := json.Unmarshal(content, &installedPlugins); err != nil {
		return nil, fmt.Errorf("failed to parse installed_plugins.json: %w", err)
	}

	var plugins []EntrypointPlugin

	for pluginName, entries := range installedPlugins.Plugins {
		for _, entry := range entries {
			// Verify the plugin directory exists
			if _, err := os.Stat(entry.InstallPath); os.IsNotExist(err) {
				zlog.Warn("plugin install path not found, skipping",
					zap.String("plugin", pluginName),
					zap.String("path", entry.InstallPath))
				continue
			}

			// Check if path is under cache directory
			if !strings.HasPrefix(entry.InstallPath, hostCachePath) {
				zlog.Warn("plugin install path not under cache directory, skipping",
					zap.String("plugin", pluginName),
					zap.String("path", entry.InstallPath))
				continue
			}

			// Get relative path from cache directory
			relativePath := strings.TrimPrefix(entry.InstallPath, hostCachePath)
			relativePath = strings.TrimPrefix(relativePath, "/")

			// Destination path in .sbox
			dstPath := filepath.Join(sboxDir, subDir, relativePath)

			zlog.Debug("copying plugin",
				zap.String("plugin", pluginName),
				zap.String("src", entry.InstallPath),
				zap.String("dst", dstPath))

			// Copy plugin directory
			if err := copyDir(entry.InstallPath, dstPath); err != nil {
				zlog.Warn("failed to copy plugin, skipping",
					zap.String("plugin", pluginName),
					zap.Error(err))
				continue
			}

			plugins = append(plugins, EntrypointPlugin{
				Name:           pluginName,
				Path:           filepath.Join(subDir, relativePath),
				Version:        entry.Version,
				PackageVersion: entry.GitCommitSha,
			})

			zlog.Info("copied plugin to .sbox",
				zap.String("plugin", pluginName),
				zap.String("path", dstPath))
		}
	}

	return plugins, nil
}

// prepareAgents copies agent files to .sbox/agents/
func prepareAgents(claudeHome, sboxDir string) ([]EntrypointAgent, error) {
	agentsDir := filepath.Join(claudeHome, "agents")

	// Check if agents directory exists
	if _, err := os.Stat(agentsDir); os.IsNotExist(err) {
		zlog.Debug("agents directory not found, skipping agents")
		return nil, nil
	}

	entries, err := os.ReadDir(agentsDir)
	if err != nil {
		return nil, fmt.Errorf("failed to read agents directory: %w", err)
	}

	var agents []EntrypointAgent
	dstAgentsDir := filepath.Join(sboxDir, "agents")

	if err := os.MkdirAll(dstAgentsDir, 0755); err != nil {
		return nil, fmt.Errorf("failed to create agents directory: %w", err)
	}

	for _, entry := range entries {
		if entry.IsDir() {
			continue
		}

		// Support both .md and .json agent files
		name := entry.Name()
		if !strings.HasSuffix(name, ".md") && !strings.HasSuffix(name, ".json") {
			continue
		}

		srcPath := filepath.Join(agentsDir, name)
		dstPath := filepath.Join(dstAgentsDir, name)

		// Get agent name (filename without extension)
		agentName := strings.TrimSuffix(name, filepath.Ext(name))

		zlog.Debug("copying agent",
			zap.String("name", agentName),
			zap.String("src", srcPath),
			zap.String("dst", dstPath))

		if err := copyFile(srcPath, dstPath); err != nil {
			zlog.Warn("failed to copy agent, skipping",
				zap.String("name", agentName),
				zap.Error(err))
			continue
		}

		agents = append(agents, EntrypointAgent{
			Name: agentName,
			Path: filepath.Join("agents", name),
		})

		zlog.Info("copied agent to .sbox",
			zap.String("agent", agentName),
			zap.String("path", dstPath))
	}

	return agents, nil
}

// prepareClaudeSettings copies settings.json and settings.local.json from the agent home
// to .sbox/ so the entrypoint can merge them into the sandbox config on startup.
// For settings.json, sandbox bypass-permissions fields are enforced so they always take
// effect regardless of what the host config has.
func prepareClaudeSettings(agentHome, sboxDir string) error {
	settingsPath := filepath.Join(agentHome, "settings.json")
	dstPath := filepath.Join(sboxDir, "claude-settings.json")

	config := make(map[string]interface{})

	if data, err := os.ReadFile(settingsPath); err == nil {
		if err := json.Unmarshal(data, &config); err != nil {
			zlog.Warn("failed to parse existing settings.json, using default",
				zap.String("path", settingsPath),
				zap.Error(err))
			config = make(map[string]interface{})
		} else {
			zlog.Info("loaded existing settings.json", zap.String("path", settingsPath))
		}
	} else if !os.IsNotExist(err) {
		zlog.Warn("failed to read settings.json, using default",
			zap.String("path", settingsPath),
			zap.Error(err))
	}

	// Enforce bypass-permissions fields for sandbox execution
	config["defaultMode"] = "bypassPermissions"
	config["bypassPermissionsModeAccepted"] = true
	config["skipDangerousModePermissionPrompt"] = true

	data, err := json.MarshalIndent(config, "", "  ")
	if err != nil {
		return fmt.Errorf("failed to marshal claude settings: %w", err)
	}

	if err := os.WriteFile(dstPath, append(data, '\n'), 0644); err != nil {
		return fmt.Errorf("failed to write claude settings: %w", err)
	}

	zlog.Info("prepared claude-settings.json with bypass permissions",
		zap.String("dst", dstPath),
		zap.Int("fields", len(config)))

	// Copy settings.local.json as-is if it exists
	settingsLocalPath := filepath.Join(agentHome, "settings.local.json")
	if _, err := os.Stat(settingsLocalPath); err == nil {
		dstLocalPath := filepath.Join(sboxDir, "claude-settings.local.json")
		if err := copyFile(settingsLocalPath, dstLocalPath); err != nil {
			zlog.Warn("failed to copy settings.local.json", zap.Error(err))
			// Non-fatal
		} else {
			zlog.Info("copied settings.local.json to .sbox",
				zap.String("src", settingsLocalPath),
				zap.String("dst", dstLocalPath))
		}
	}

	return nil
}

// prepareOpencodeConfig creates or updates opencode.json with full permissions for sandbox use.
// If the user has an existing config, it loads it and ensures permissions are set to allow all.
// If no config exists, it creates a default one with full permissions.
// All other user config fields (like "model") are preserved.
func prepareOpencodeConfig(agentHome, sboxDir string) error {
	opencodeConfigPath := filepath.Join(agentHome, "opencode.json")
	dstPath := filepath.Join(sboxDir, "opencode.json")

	// Use generic map to preserve all user fields
	config := make(map[string]interface{})

	// Try to read existing config
	if data, err := os.ReadFile(opencodeConfigPath); err == nil {
		// Parse existing config as generic JSON
		if err := json.Unmarshal(data, &config); err != nil {
			zlog.Warn("failed to parse existing opencode.json, using default",
				zap.String("path", opencodeConfigPath),
				zap.Error(err))
			// Fall through to use default config (empty map)
			config = make(map[string]interface{})
		} else {
			zlog.Info("loaded existing opencode.json", zap.String("path", opencodeConfigPath))
		}
	} else if !os.IsNotExist(err) {
		// File exists but couldn't be read
		zlog.Warn("failed to read opencode.json, using default",
			zap.String("path", opencodeConfigPath),
			zap.Error(err))
	} else {
		zlog.Info("no opencode.json found, creating default", zap.String("path", opencodeConfigPath))
	}

	// Ensure schema is set if not present
	if _, hasSchema := config["$schema"]; !hasSchema {
		config["$schema"] = "https://opencode.ai/config.json"
	}

	// Always set full permissions for sandbox/container environment
	// This overrides any existing permission settings
	config["permission"] = map[string]string{
		"*": "allow",
	}

	// Write config to .sbox/
	data, err := json.MarshalIndent(config, "", "  ")
	if err != nil {
		return fmt.Errorf("failed to marshal opencode config: %w", err)
	}

	if err := os.WriteFile(dstPath, data, 0644); err != nil {
		return fmt.Errorf("failed to write opencode config: %w", err)
	}

	zlog.Info("prepared opencode.json with full permissions",
		zap.String("dst", dstPath),
		zap.Int("fields", len(config)))

	return nil
}

// prepareOpencodeTUIConfig copies tui.json from the agent home to .sbox/ if it exists.
func prepareOpencodeTUIConfig(agentHome, sboxDir string) error {
	srcPath := filepath.Join(agentHome, "tui.json")
	dstPath := filepath.Join(sboxDir, "tui.json")

	if _, err := os.Stat(srcPath); os.IsNotExist(err) {
		zlog.Debug("tui.json not found, skipping", zap.String("path", srcPath))
		return nil
	} else if err != nil {
		return fmt.Errorf("failed to stat tui.json: %w", err)
	}

	if err := copyFile(srcPath, dstPath); err != nil {
		return fmt.Errorf("failed to copy tui.json: %w", err)
	}

	zlog.Info("copied tui.json to .sbox",
		zap.String("src", srcPath),
		zap.String("dst", dstPath))

	return nil
}

// prepareOpencodeAuth copies the OpenCode auth.json file if it exists.
// Auth file is located at ~/.local/share/opencode/auth.json on the host.
func prepareOpencodeAuth(sboxDir string) error {
	homeDir, err := os.UserHomeDir()
	if err != nil {
		return fmt.Errorf("failed to get home directory: %w", err)
	}

	// OpenCode auth is stored in XDG data directory
	authPath := filepath.Join(homeDir, ".local", "share", "opencode", "auth.json")
	dstPath := filepath.Join(sboxDir, "opencode-auth.json")

	// Check if auth file exists
	if _, err := os.Stat(authPath); os.IsNotExist(err) {
		zlog.Debug("opencode auth.json not found, skipping", zap.String("path", authPath))
		return nil
	} else if err != nil {
		return fmt.Errorf("failed to stat auth file: %w", err)
	}

	// Copy auth file as-is
	if err := copyFile(authPath, dstPath); err != nil {
		return fmt.Errorf("failed to copy auth file: %w", err)
	}

	zlog.Info("copied opencode auth.json to .sbox",
		zap.String("src", authPath),
		zap.String("dst", dstPath))

	return nil
}

// resolveEnvs merges and resolves environment variables from all sources.
// Passthrough variables (NAME without =) are resolved from the current environment.
// Returns a slice of KEY=value strings ready to write to .sbox/env.
func resolveEnvs(globalEnvs, projectEnvs, sboxFileEnvs []string) []string {
	merged, _ := MergeEnvs(globalEnvs, projectEnvs, sboxFileEnvs)

	var resolved []string
	for _, env := range merged {
		if idx := strings.Index(env, "="); idx >= 0 {
			// Already has value
			resolved = append(resolved, env)
		} else {
			// Passthrough - resolve from host environment
			value := os.Getenv(env)
			if value != "" {
				resolved = append(resolved, env+"="+value)
				zlog.Debug("resolved passthrough env",
					zap.String("name", env))
			} else {
				zlog.Debug("passthrough env not set on host, skipping",
					zap.String("name", env))
			}
		}
	}

	return resolved
}

// addTerminalEnvs appends terminal-capability env vars from the host if not already present in envs.
// These are needed for proper TUI rendering and OSC 8 hyperlink support (e.g. clickable URLs).
// Written to .sbox/env so they're picked up by loadEntrypointEnv on every run, including
// existing containers that were created before these vars were added.
func addTerminalEnvs(envs []string) []string {
	configured := make(map[string]bool, len(envs))
	for _, env := range envs {
		if idx := strings.Index(env, "="); idx > 0 {
			configured[env[:idx]] = true
		}
	}
	for _, name := range []string{"TERM", "COLORTERM", "TERM_PROGRAM", "TERM_PROGRAM_VERSION"} {
		if configured[name] {
			continue
		}
		if value := os.Getenv(name); value != "" {
			envs = append(envs, name+"="+value)
		}
	}
	return envs
}

// SaveAgentCache saves the agent's config state to .sbox/ for persistence across recreations.
// For Claude, saves /home/agent/.claude to .sbox/claude-cache/.
// For OpenCode, saves /home/agent/.config/opencode to .sbox/opencode-cache/ and
// /home/agent/.local/share/opencode to .sbox/opencode-share-cache/.
// Uses rsync inside the container since .sbox/ is mounted and visible on the host.
func SaveAgentCache(workspaceDir string, agentType AgentType, backend Backend) error {
	zlog.Info("saving agent cache",
		zap.String("workspace", workspaceDir),
		zap.String("agent", string(agentType)))

	info, err := backend.FindRunning(workspaceDir)
	if err != nil {
		return fmt.Errorf("failed to find running container: %w", err)
	}
	if info == nil {
		return fmt.Errorf("no running container found")
	}

	var execPrefix []string
	if backend.Name() == BackendSandbox {
		execPrefix = []string{"docker", "sandbox", "exec", info.ID}
	} else {
		execPrefix = []string{"docker", "exec", info.ID}
	}

	switch agentType {
	case AgentOpenCode:
		return saveOpenCodeAgentCache(workspaceDir, execPrefix)
	default:
		return saveClaudeAgentCache(workspaceDir, execPrefix)
	}
}

// saveClaudeAgentCache saves /home/agent/.claude to .sbox/claude-cache/ via rsync inside the container.
func saveClaudeAgentCache(workspaceDir string, execPrefix []string) error {
	cachePath := filepath.Join(workspaceDir, ".sbox", ClaudeCacheDir)

	if err := os.MkdirAll(cachePath, 0755); err != nil {
		return fmt.Errorf("failed to create cache directory: %w", err)
	}

	claudeHome := "/home/agent/.claude"

	// Use rsync inside the container to sync .claude to .sbox/claude-cache/
	// The .sbox directory is mounted in the workspace, so changes are visible on host
	// --archive preserves permissions, timestamps, etc.
	// --delete ensures cache is an exact mirror (removes stale files from cache)
	rsyncArgs := append(slices.Clone(execPrefix), "rsync", "-a", "--delete", claudeHome+"/", cachePath+"/")
	cmd := exec.Command(rsyncArgs[0], rsyncArgs[1:]...)
	output, err := cmd.CombinedOutput()
	if err != nil {
		zlog.Warn("rsync failed",
			zap.Error(err),
			zap.String("output", string(output)))
		return fmt.Errorf("rsync failed: %w", err)
	}

	zlog.Info("claude cache saved successfully", zap.String("cache_path", cachePath))
	return nil
}

// saveOpenCodeAgentCache saves OpenCode config and share dirs to .sbox/ via rsync inside the container.
// Saves /home/agent/.config/opencode → .sbox/opencode-cache/
// Saves /home/agent/.local/share/opencode → .sbox/opencode-share-cache/ (non-fatal if missing)
func saveOpenCodeAgentCache(workspaceDir string, execPrefix []string) error {
	// Save .config/opencode → opencode-cache
	configCachePath := filepath.Join(workspaceDir, ".sbox", OpenCodeCacheDir)
	if err := os.MkdirAll(configCachePath, 0755); err != nil {
		return fmt.Errorf("failed to create opencode cache directory: %w", err)
	}

	openCodeConfigHome := "/home/agent/.config/opencode"
	configArgs := append(slices.Clone(execPrefix), "rsync", "-a", "--delete", openCodeConfigHome+"/", configCachePath+"/")
	if output, err := exec.Command(configArgs[0], configArgs[1:]...).CombinedOutput(); err != nil {
		zlog.Warn("rsync failed for opencode config cache",
			zap.Error(err),
			zap.String("output", string(output)))
		return fmt.Errorf("rsync failed for opencode config: %w", err)
	}
	zlog.Info("opencode config cache saved successfully", zap.String("cache_path", configCachePath))

	// Save .local/share/opencode → opencode-share-cache
	// Non-fatal: the share dir may not exist if OpenCode hasn't written anything there yet.
	shareCachePath := filepath.Join(workspaceDir, ".sbox", OpenCodeShareCacheDir)
	if err := os.MkdirAll(shareCachePath, 0755); err != nil {
		zlog.Warn("failed to create opencode share cache directory", zap.Error(err))
		return nil
	}

	openCodeShareHome := "/home/agent/.local/share/opencode"
	shareArgs := append(slices.Clone(execPrefix), "rsync", "-a", "--delete", openCodeShareHome+"/", shareCachePath+"/")
	if output, err := exec.Command(shareArgs[0], shareArgs[1:]...).CombinedOutput(); err != nil {
		zlog.Warn("rsync failed for opencode share cache (non-fatal)",
			zap.Error(err),
			zap.String("output", string(output)))
	} else {
		zlog.Info("opencode share cache saved successfully", zap.String("cache_path", shareCachePath))
	}

	return nil
}

// restoreAgentCache restores the agent's config dir from .sbox/ cache if present.
// For Claude, restores .sbox/claude-cache/ → agentHome.
// For OpenCode, restores .sbox/opencode-cache/ → agentHome.
// Uses rsync to efficiently sync the cache to the agent home directory.
func restoreAgentCache(workspaceDir string, agentType AgentType, agentHome string) error {
	var cacheDir string
	switch agentType {
	case AgentOpenCode:
		cacheDir = OpenCodeCacheDir
	default:
		cacheDir = ClaudeCacheDir
	}

	cachePath := filepath.Join(workspaceDir, ".sbox", cacheDir)

	// Check if cache exists and has content
	entries, err := os.ReadDir(cachePath)
	if os.IsNotExist(err) || len(entries) == 0 {
		elog.Debug("no agent cache found or empty", "path", cachePath, "agent", string(agentType))
		zlog.Debug("no agent cache found, skipping restore", zap.String("agent", string(agentType)))
		return nil
	}
	if err != nil {
		return fmt.Errorf("failed to read cache directory: %w", err)
	}

	elog.Info("restoring agent cache", "src", cachePath, "dst", agentHome, "agent", string(agentType))
	zlog.Info("restoring agent cache from .sbox",
		zap.String("cache_path", cachePath),
		zap.String("agent_home", agentHome),
		zap.String("agent", string(agentType)))

	if err := os.MkdirAll(agentHome, 0755); err != nil {
		return fmt.Errorf("failed to create agent home: %w", err)
	}

	// Use rsync to restore cache to agent home
	// --archive preserves permissions, timestamps, etc.
	// We don't use --delete here to preserve any existing data
	cmd := exec.Command("rsync", "-a", cachePath+"/", agentHome+"/")
	output, err := cmd.CombinedOutput()
	if err != nil {
		elog.Error("rsync restore failed", "error", err, "output", string(output))
		return fmt.Errorf("rsync failed: %w", err)
	}

	elog.Info("agent cache restored successfully", "agent", string(agentType))
	zlog.Info("agent cache restored successfully", zap.String("agent", string(agentType)))
	return nil
}

// restoreOpenCodeShareCache restores .local/share/opencode from .sbox/opencode-share-cache/ if present.
// This is called after the individual OpenCode file setup so that cached state from a previous
// session takes precedence over the initially seeded files (e.g. auth.json).
func restoreOpenCodeShareCache(workspaceDir string) error {
	cachePath := filepath.Join(workspaceDir, ".sbox", OpenCodeShareCacheDir)

	entries, err := os.ReadDir(cachePath)
	if os.IsNotExist(err) || len(entries) == 0 {
		elog.Debug("no opencode share cache found or empty", "path", cachePath)
		zlog.Debug("no opencode share cache found, skipping restore")
		return nil
	}
	if err != nil {
		return fmt.Errorf("failed to read opencode share cache directory: %w", err)
	}

	shareDir := filepath.Join("/home/agent", ".local", "share", "opencode")
	elog.Info("restoring opencode share cache", "src", cachePath, "dst", shareDir)
	zlog.Info("restoring opencode share cache from .sbox",
		zap.String("cache_path", cachePath),
		zap.String("share_dir", shareDir))

	if err := os.MkdirAll(shareDir, 0755); err != nil {
		return fmt.Errorf("failed to create opencode share directory: %w", err)
	}

	cmd := exec.Command("rsync", "-a", cachePath+"/", shareDir+"/")
	output, err := cmd.CombinedOutput()
	if err != nil {
		elog.Error("rsync opencode share restore failed", "error", err, "output", string(output))
		return fmt.Errorf("rsync failed: %w", err)
	}

	elog.Info("opencode share cache restored successfully")
	zlog.Info("opencode share cache restored successfully")
	return nil
}

// prepareRules uses PrepareMDForSandbox to discover and concatenate MD files,
// then copies the result to .sbox/CLAUDE.md. These rules apply to all agent types.
func prepareRules(workspaceDir, sboxDir string, backend BackendType) error {
	// Use existing function to discover and concatenate CLAUDE.md and AGENTS.md files
	// with backend-specific context
	srcPath, err := PrepareMDForSandbox(workspaceDir, backend)
	if err != nil {
		return fmt.Errorf("failed to prepare MD files: %w", err)
	}

	// Copy to .sbox/CLAUDE.md (shared for all agents)
	dstPath := filepath.Join(sboxDir, "CLAUDE.md")
	if err := copyFile(srcPath, dstPath); err != nil {
		return fmt.Errorf("failed to copy rules file to .sbox: %w", err)
	}

	zlog.Info("prepared rules file in .sbox",
		zap.String("src", srcPath),
		zap.String("dst", dstPath))

	return nil
}