From adc13c6b5a4df676fa5cf16e32b0ea819cf70155 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?=
Date: Sun, 24 May 2026 20:12:26 +0100
Subject: [PATCH] feat: copy gitignored files from repo into new worktrees
(#946) (#950)
---
apps/backend/cmd/kandev/adapters.go | 2 +
.../agent/runtime/agentctl/client_files.go | 54 ++
.../lifecycle/env_preparer_worktree.go | 24 +
.../lifecycle/env_preparer_worktree_test.go | 65 ++
.../agent/runtime/lifecycle/manager_launch.go | 12 +
.../runtime/lifecycle/remote_copyfiles.go | 187 +++++
.../lifecycle/remote_copyfiles_test.go | 293 ++++++++
.../internal/agent/runtime/lifecycle/types.go | 9 +
.../internal/agentctl/server/api/server.go | 5 +
.../server/api/workspace_copyfiles.go | 82 +++
.../server/api/workspace_copyfiles_test.go | 150 ++++
.../agentctl/server/process/manager.go | 16 +
.../orchestrator/executor/executor.go | 7 +
.../orchestrator/executor/executor_execute.go | 4 +
apps/backend/internal/task/dto/dto.go | 2 +
apps/backend/internal/task/dto/requests.go | 2 +
.../task/handlers/repository_handlers.go | 8 +
.../task/handlers/repository_handlers_test.go | 85 +++
apps/backend/internal/task/models/models.go | 1 +
.../internal/task/repository/sqlite/base.go | 2 +
.../repository/sqlite/repository_entity.go | 22 +-
.../sqlite/repository_entity_test.go | 143 ++++
.../internal/task/service/service_requests.go | 2 +
.../task/service/service_resources.go | 4 +
.../task/service/service_resources_test.go | 26 +
.../internal/worktree/copyfiles/copyfiles.go | 634 ++++++++++++++++
.../worktree/copyfiles/copyfiles_test.go | 682 ++++++++++++++++++
apps/backend/internal/worktree/manager.go | 43 ++
.../worktree/manager_copyfiles_test.go | 195 +++++
.../internal/worktree/repository_adapter.go | 2 +
apps/backend/internal/worktree/worktree.go | 12 +
apps/web/app/actions/workspaces.ts | 2 +
.../workspace-repositories-client.tsx | 56 +-
.../workspace-repositories-dirty.test.ts | 50 ++
.../workspace/workspace-repositories-dirty.ts | 50 ++
.../automations/automation-payload.ts | 1 +
.../components/settings/repository-card.tsx | 31 +-
.../task/recent-task-switcher-model.test.ts | 1 +
apps/web/e2e/helpers/api-client.ts | 7 +-
.../tests/session/copyfiles-progress.spec.ts | 176 +++++
apps/web/hooks/use-responsive-breakpoint.ts | 77 +-
apps/web/lib/types/http.ts | 1 +
docs/decisions/0010-worktree-copy-files.md | 45 ++
docs/decisions/INDEX.md | 1 +
44 files changed, 3176 insertions(+), 97 deletions(-)
create mode 100644 apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree_test.go
create mode 100644 apps/backend/internal/agent/runtime/lifecycle/remote_copyfiles.go
create mode 100644 apps/backend/internal/agent/runtime/lifecycle/remote_copyfiles_test.go
create mode 100644 apps/backend/internal/agentctl/server/api/workspace_copyfiles.go
create mode 100644 apps/backend/internal/agentctl/server/api/workspace_copyfiles_test.go
create mode 100644 apps/backend/internal/task/handlers/repository_handlers_test.go
create mode 100644 apps/backend/internal/task/repository/sqlite/repository_entity_test.go
create mode 100644 apps/backend/internal/worktree/copyfiles/copyfiles.go
create mode 100644 apps/backend/internal/worktree/copyfiles/copyfiles_test.go
create mode 100644 apps/backend/internal/worktree/manager_copyfiles_test.go
create mode 100644 apps/web/app/settings/workspace/workspace-repositories-dirty.test.ts
create mode 100644 apps/web/app/settings/workspace/workspace-repositories-dirty.ts
create mode 100644 apps/web/e2e/tests/session/copyfiles-progress.spec.ts
create mode 100644 docs/decisions/0010-worktree-copy-files.md
diff --git a/apps/backend/cmd/kandev/adapters.go b/apps/backend/cmd/kandev/adapters.go
index 39c1f48ef5..a121fd0c48 100644
--- a/apps/backend/cmd/kandev/adapters.go
+++ b/apps/backend/cmd/kandev/adapters.go
@@ -95,6 +95,7 @@ func (a *lifecycleAdapter) LaunchAgent(ctx context.Context, req *executor.Launch
IsEphemeral: req.IsEphemeral,
IsPassthrough: req.IsPassthrough,
SetupScript: req.SetupScript,
+ CopyFiles: req.CopyFiles,
// Worktree configuration for concurrent agent execution
UseWorktree: req.UseWorktree,
WorktreeID: req.WorktreeID,
@@ -140,6 +141,7 @@ func (a *lifecycleAdapter) LaunchAgent(ctx context.Context, req *executor.Launch
PullBeforeWorktree: r.PullBeforeWorktree,
RepoSetupScript: r.RepoSetupScript,
RepoCleanupScript: r.RepoCleanupScript,
+ CopyFiles: r.CopyFiles,
})
}
launchReq.Repositories = specs
diff --git a/apps/backend/internal/agent/runtime/agentctl/client_files.go b/apps/backend/internal/agent/runtime/agentctl/client_files.go
index 5846f881db..d59f77f095 100644
--- a/apps/backend/internal/agent/runtime/agentctl/client_files.go
+++ b/apps/backend/internal/agent/runtime/agentctl/client_files.go
@@ -9,6 +9,7 @@ import (
"net/url"
"github.com/kandev/kandev/internal/agentctl/types/streams"
+ "github.com/kandev/kandev/internal/worktree/copyfiles"
"go.uber.org/zap"
)
@@ -328,3 +329,56 @@ type FileSearchResponse struct {
Files []string `json:"files"`
Error string `json:"error,omitempty"`
}
+
+// CopyFilesRequest is the body for POST /workspace/copy-files. Mirrors the
+// agentctl-side api.CopyFilesRequest shape — kept local rather than imported
+// to keep the client free of the api package dependency.
+type CopyFilesRequest struct {
+ Repo string `json:"repo,omitempty"`
+ Entries []copyfiles.Entry `json:"entries"`
+}
+
+// CopyFilesResponse mirrors api.CopyFilesResponse.
+type CopyFilesResponse struct {
+ Copied []string `json:"copied,omitempty"`
+ Warnings []string `json:"warnings,omitempty"`
+ Error string `json:"error,omitempty"`
+}
+
+// CopyFiles ships a batch of pre-planned files (from copyfiles.Plan on the
+// host) to agentctl's POST /workspace/copy-files endpoint, which writes
+// them into the workspace under the optional repo subpath. Idempotent —
+// existing destinations are skipped. Used by remote executors (Docker,
+// Sprites) to seed gitignored files after the in-container clone.
+func (c *Client) CopyFiles(ctx context.Context, repo string, entries []copyfiles.Entry) (*CopyFilesResponse, error) {
+ bodyBytes, err := json.Marshal(CopyFilesRequest{Repo: repo, Entries: entries})
+ if err != nil {
+ return nil, fmt.Errorf("failed to marshal request: %w", err)
+ }
+
+ reqURL := fmt.Sprintf("%s/api/v1/workspace/copy-files", c.baseURL)
+ req, err := http.NewRequestWithContext(ctx, "POST", reqURL, bytes.NewReader(bodyBytes))
+ if err != nil {
+ return nil, fmt.Errorf("failed to create request: %w", err)
+ }
+ req.Header.Set("Content-Type", "application/json")
+
+ resp, err := c.httpClient.Do(req)
+ if err != nil {
+ return nil, fmt.Errorf("failed to copy files: %w", err)
+ }
+ defer func() {
+ if err := resp.Body.Close(); err != nil {
+ c.logger.Debug("failed to close copy-files response body", zap.Error(err))
+ }
+ }()
+
+ var response CopyFilesResponse
+ if err := json.NewDecoder(resp.Body).Decode(&response); err != nil {
+ return nil, fmt.Errorf("failed to parse response: %w", err)
+ }
+ if response.Error != "" {
+ return &response, fmt.Errorf("copy-files error: %s", response.Error)
+ }
+ return &response, nil
+}
diff --git a/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree.go b/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree.go
index d24e45c1e1..6119ef6c12 100644
--- a/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree.go
+++ b/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree.go
@@ -12,6 +12,15 @@ import (
"github.com/kandev/kandev/internal/worktree"
)
+// copyFilesStep builds the "Copy N ignored files" prepare step shown after a
+// worktree's CopyFiles spec has been applied. repoLabel is appended for
+// multi-repo prepares; empty for single-repo. Thin adapter — see
+// buildCopyFilesStep for the actual step shape (shared with the
+// remote-executor path in remote_copyfiles.go).
+func copyFilesStep(wt *worktree.Worktree, repoLabel string) PrepareStep {
+ return buildCopyFilesStep(wt.CopiedFiles, wt.CopyFilesWarnings, repoLabel)
+}
+
// WorktreePreparer prepares a worktree-based execution environment.
// Steps: validate repository → create worktree → checkout PR branch (if set) → run setup script (if any).
type WorktreePreparer struct {
@@ -64,6 +73,13 @@ func (p *WorktreePreparer) Prepare(ctx context.Context, req *EnvPrepareRequest,
return &EnvPrepareResult{Success: false, Steps: steps, ErrorMessage: err.Error(), Duration: time.Since(start)}, nil
}
+ if len(wt.CopiedFiles) > 0 || len(wt.CopyFilesWarnings) > 0 {
+ totalSteps++
+ steps = append(steps, copyFilesStep(wt, ""))
+ reportProgress(onProgress, steps[len(steps)-1], stepIdx, totalSteps)
+ stepIdx++
+ }
+
workspacePath := wt.Path
mainRepoGitDir := filepath.Join(req.RepositoryPath, ".git")
@@ -408,6 +424,14 @@ func (p *WorktreePreparer) prepareOneRepo(
stepIdx++
}
+ if len(wt.CopiedFiles) > 0 || len(wt.CopyFilesWarnings) > 0 {
+ totalSteps++
+ step := copyFilesStep(wt, repoLabel)
+ steps = append(steps, step)
+ reportProgress(onProgress, step, stepIdx, totalSteps)
+ stepIdx++
+ }
+
// Per-repo setup script execution is owned by the worktree manager
// (createInTaskDir → runWorktreeSetupScript), which streams output to a
// "script_execution" chat message. Running it here as well caused the
diff --git a/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree_test.go b/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree_test.go
new file mode 100644
index 0000000000..357fccb388
--- /dev/null
+++ b/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree_test.go
@@ -0,0 +1,65 @@
+package lifecycle
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/kandev/kandev/internal/worktree"
+)
+
+func TestCopyFilesStep_SingleFile(t *testing.T) {
+ wt := &worktree.Worktree{CopiedFiles: []string{".env"}}
+ step := copyFilesStep(wt, "")
+ if step.Name != "Copy 1 ignored file" {
+ t.Errorf("name = %q, want %q", step.Name, "Copy 1 ignored file")
+ }
+ if step.Output != ".env" {
+ t.Errorf("output = %q, want %q", step.Output, ".env")
+ }
+ if step.Status != PrepareStepCompleted {
+ t.Errorf("status = %q, want completed", step.Status)
+ }
+ if step.Warning != "" {
+ t.Errorf("unexpected warning: %q", step.Warning)
+ }
+}
+
+func TestCopyFilesStep_MultipleFilesWithRepoLabel(t *testing.T) {
+ wt := &worktree.Worktree{CopiedFiles: []string{".env", "config/local.yml", "data.json"}}
+ step := copyFilesStep(wt, "frontend")
+ if step.Name != "Copy 3 ignored files (frontend)" {
+ t.Errorf("name = %q, want %q", step.Name, "Copy 3 ignored files (frontend)")
+ }
+ lines := strings.Split(step.Output, "\n")
+ if len(lines) != 3 {
+ t.Fatalf("expected 3 output lines, got %d: %q", len(lines), step.Output)
+ }
+}
+
+func TestCopyFilesStep_WarningsAttached(t *testing.T) {
+ wt := &worktree.Worktree{
+ CopiedFiles: []string{".env"},
+ CopyFilesWarnings: []string{`no matches for pattern "*.local"`, `invalid pattern "["`},
+ }
+ step := copyFilesStep(wt, "")
+ if step.Warning == "" {
+ t.Fatal("expected warning to be set when CopyFilesWarnings non-empty")
+ }
+ if !strings.Contains(step.WarningDetail, "*.local") || !strings.Contains(step.WarningDetail, "invalid pattern") {
+ t.Errorf("warningDetail = %q, expected both warnings joined", step.WarningDetail)
+ }
+}
+
+func TestCopyFilesStep_WarningsOnlyNoCopies(t *testing.T) {
+ wt := &worktree.Worktree{CopyFilesWarnings: []string{`no matches for pattern ".env"`}}
+ step := copyFilesStep(wt, "")
+ if step.Name != "Copy ignored files" {
+ t.Errorf("name = %q, want %q for zero-file warning case", step.Name, "Copy ignored files")
+ }
+ if step.Output != "" {
+ t.Errorf("unexpected output for zero copies: %q", step.Output)
+ }
+ if step.Warning == "" {
+ t.Error("expected warning to be set")
+ }
+}
diff --git a/apps/backend/internal/agent/runtime/lifecycle/manager_launch.go b/apps/backend/internal/agent/runtime/lifecycle/manager_launch.go
index 9dd0604100..b6719aef25 100644
--- a/apps/backend/internal/agent/runtime/lifecycle/manager_launch.go
+++ b/apps/backend/internal/agent/runtime/lifecycle/manager_launch.go
@@ -813,6 +813,18 @@ func (m *Manager) launchInternal(ctx context.Context, req *LaunchRequest) (*Agen
m.publishLaunchPrepareCompleted(req, prepResult, progressRecorder, workspacePath, false, err)
return nil, err
}
+
+ // Remote executors (Docker, Sprites) clone the workspace inside the
+ // container, so the worktree path's host-side copy_files never ran.
+ // Ship the bytes through agentctl now that the instance is up. The
+ // worktree path is already gated by reqWithWorktree.UseWorktree, so
+ // it's safe to skip when that's true. For multi-repo launches, loop
+ // over every per-repo spec — each repo's CopyFiles ships into its
+ // own RepoName subdir under the workspace.
+ if !reqWithWorktree.UseWorktree && execInstance != nil && execInstance.Client != nil {
+ shipRemoteCopyfilesForLaunch(ctx, m.logger, &reqWithWorktree, execInstance.Client, runtimeProgress, progressRecorder)
+ }
+
if prepResult != nil {
prepResult.Steps = progressRecorder.Steps()
}
diff --git a/apps/backend/internal/agent/runtime/lifecycle/remote_copyfiles.go b/apps/backend/internal/agent/runtime/lifecycle/remote_copyfiles.go
new file mode 100644
index 0000000000..4213813f7d
--- /dev/null
+++ b/apps/backend/internal/agent/runtime/lifecycle/remote_copyfiles.go
@@ -0,0 +1,187 @@
+package lifecycle
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "go.uber.org/zap"
+
+ client "github.com/kandev/kandev/internal/agent/runtime/agentctl"
+ "github.com/kandev/kandev/internal/common/logger"
+ "github.com/kandev/kandev/internal/worktree/copyfiles"
+)
+
+// shipRemoteCopyfilesForLaunch fires runRemoteCopyfiles once for the
+// single-repo top-level spec, or once per RepoLaunchSpec for multi-repo
+// launches. Each invocation gets its own progressRecorder.Callback so
+// the step ends up at the recorder's current tail; passing StepIndex=0
+// and TotalSteps=1 then resolves to absolute positions correctly,
+// regardless of where the prior steps left the recorder.
+func shipRemoteCopyfilesForLaunch(
+ ctx context.Context,
+ log *logger.Logger,
+ req *LaunchRequest,
+ cli *client.Client,
+ runtimeProgress PrepareProgressCallback,
+ progressRecorder *prepareProgressRecorder,
+) {
+ type repoCopy struct {
+ sourceRepoPath string
+ copyFilesSpec string
+ repoSubpath string
+ }
+ var jobs []repoCopy
+ if specs := req.Repositories; len(specs) > 0 {
+ for _, spec := range specs {
+ jobs = append(jobs, repoCopy{
+ sourceRepoPath: spec.RepositoryPath,
+ copyFilesSpec: spec.CopyFiles,
+ repoSubpath: spec.RepoName,
+ })
+ }
+ } else if req.RepositoryPath != "" {
+ jobs = append(jobs, repoCopy{
+ sourceRepoPath: req.RepositoryPath,
+ copyFilesSpec: req.CopyFiles,
+ repoSubpath: "", // single-repo: write at workspace root
+ })
+ }
+ for _, j := range jobs {
+ if strings.TrimSpace(j.copyFilesSpec) == "" {
+ continue
+ }
+ // Create a fresh recorder callback at the current tail per job so
+ // passing StepIndex=0 / TotalSteps=1 lands at the right absolute
+ // index regardless of how many steps the previous job appended.
+ var jobProgress PrepareProgressCallback
+ if runtimeProgress != nil {
+ jobProgress = progressRecorder.Callback(progressRecorder.Len())
+ }
+ runRemoteCopyfiles(ctx, log, remoteCopyfilesRequest{
+ SourceRepoPath: j.sourceRepoPath,
+ CopyFilesSpec: j.copyFilesSpec,
+ RepoSubpath: j.repoSubpath,
+ Client: cli,
+ OnProgress: jobProgress,
+ StepIndex: 0,
+ TotalSteps: 1,
+ })
+ }
+}
+
+// remoteCopyfilesRequest carries the inputs runRemoteCopyfiles needs.
+// Bundled so the call site in manager_launch.go stays readable —
+// remote-copy is a side action after CreateInstance, not part of the
+// executor's prepare pipeline.
+type remoteCopyfilesRequest struct {
+ SourceRepoPath string
+ CopyFilesSpec string
+ RepoSubpath string // optional: per-repo subdir under workspace (multi-repo)
+ Client *client.Client
+ OnProgress PrepareProgressCallback
+ StepIndex int
+ TotalSteps int
+}
+
+// runRemoteCopyfiles plans copy_files entries from the host source repo,
+// ships them via agentctl, and emits a single "Copy N ignored files"
+// prepare step matching the worktree path's naming. Best-effort: a
+// failure logs + emits a warning on the step but never aborts the
+// launch (parallels worktree.Manager.copyConfiguredFiles).
+//
+// Used by remote executors (Docker, Sprites) whose containers clone
+// their own workspace and therefore can't receive copy_files seeding
+// via the host-side worktree path.
+func runRemoteCopyfiles(ctx context.Context, log *logger.Logger, req remoteCopyfilesRequest) {
+ if req.Client == nil || strings.TrimSpace(req.CopyFilesSpec) == "" || req.SourceRepoPath == "" {
+ return
+ }
+ patterns := copyfiles.Parse(req.CopyFilesSpec)
+ if len(patterns) == 0 {
+ return
+ }
+
+ entries, planWarnings, err := copyfiles.Plan(ctx, req.SourceRepoPath, patterns, zapOrNil(log))
+ if err != nil {
+ log.Warn("remote-copyfiles: plan failed",
+ zap.String("source", req.SourceRepoPath),
+ zap.Error(err))
+ if req.OnProgress != nil {
+ req.OnProgress(buildCopyFilesStep(nil,
+ append(planWarnings, "plan failed: "+err.Error()), req.RepoSubpath),
+ req.StepIndex, req.TotalSteps)
+ }
+ return
+ }
+
+ var copied []string
+ var shipWarnings []string
+ if len(entries) > 0 {
+ resp, err := req.Client.CopyFiles(ctx, req.RepoSubpath, entries)
+ if err != nil {
+ log.Warn("remote-copyfiles: ship failed",
+ zap.String("repo_subpath", req.RepoSubpath),
+ zap.Error(err))
+ shipWarnings = append(shipWarnings, "ship failed: "+err.Error())
+ }
+ if resp != nil {
+ copied = resp.Copied
+ shipWarnings = append(shipWarnings, resp.Warnings...)
+ }
+ }
+
+ allWarnings := append(planWarnings, shipWarnings...) //nolint:gocritic // intentional new slice
+ if len(copied) == 0 && len(allWarnings) == 0 {
+ return
+ }
+ if req.OnProgress == nil {
+ return
+ }
+ req.OnProgress(buildCopyFilesStep(copied, allWarnings, req.RepoSubpath), req.StepIndex, req.TotalSteps)
+}
+
+// buildCopyFilesStep returns the "Copy N ignored files" prepare step
+// shared by the worktree (host-side) and remote (Docker/Sprites) paths.
+// Centralised so the user-facing wording stays in lockstep — the only
+// difference between the two callers is when in the launch pipeline the
+// step gets emitted.
+func buildCopyFilesStep(copied []string, warnings []string, repoLabel string) PrepareStep {
+ const (
+ nameZero = "Copy ignored files"
+ nameOne = "Copy 1 ignored file"
+ )
+ var name string
+ switch len(copied) {
+ case 0:
+ name = nameZero
+ case 1:
+ name = nameOne
+ default:
+ name = fmt.Sprintf("Copy %d ignored files", len(copied))
+ }
+ if repoLabel != "" {
+ name = fmt.Sprintf("%s (%s)", name, repoLabel)
+ }
+ step := beginStep(name)
+ if len(copied) > 0 {
+ step.Output = strings.Join(copied, "\n")
+ }
+ if len(warnings) > 0 {
+ step.Warning = warnings[0]
+ if len(warnings) > 1 {
+ step.WarningDetail = strings.Join(warnings, "\n")
+ }
+ }
+ completeStepSuccess(&step)
+ return step
+}
+
+// zapOrNil returns the underlying *zap.Logger or nil when log is nil.
+// Plan/WriteEntries accept a nil logger.
+func zapOrNil(log *logger.Logger) *zap.Logger {
+ if log == nil {
+ return nil
+ }
+ return log.Zap()
+}
diff --git a/apps/backend/internal/agent/runtime/lifecycle/remote_copyfiles_test.go b/apps/backend/internal/agent/runtime/lifecycle/remote_copyfiles_test.go
new file mode 100644
index 0000000000..5d44df5225
--- /dev/null
+++ b/apps/backend/internal/agent/runtime/lifecycle/remote_copyfiles_test.go
@@ -0,0 +1,293 @@
+package lifecycle
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ client "github.com/kandev/kandev/internal/agent/runtime/agentctl"
+ "github.com/kandev/kandev/internal/common/logger"
+ "github.com/kandev/kandev/internal/worktree/copyfiles"
+)
+
+func TestEmitCopyFilesStep_Pluralization(t *testing.T) {
+ t.Parallel()
+ cases := []struct {
+ name string
+ copied []string
+ expected string
+ }{
+ {"none", nil, "Copy ignored files"},
+ {"one", []string{".env"}, "Copy 1 ignored file"},
+ {"two", []string{".env", "config.yml"}, "Copy 2 ignored files"},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ var got PrepareStep
+ cb := func(step PrepareStep, _, _ int) { got = step }
+ cb(buildCopyFilesStep(tc.copied, nil, ""), 0, 1)
+ if got.Name != tc.expected {
+ t.Errorf("name = %q, want %q", got.Name, tc.expected)
+ }
+ if got.Status != PrepareStepCompleted {
+ t.Errorf("status = %q, want completed", got.Status)
+ }
+ })
+ }
+}
+
+func TestBuildCopyFilesStep_RepoLabelAppended(t *testing.T) {
+ t.Parallel()
+ got := buildCopyFilesStep([]string{".env"}, nil, "frontend")
+ if got.Name != "Copy 1 ignored file (frontend)" {
+ t.Errorf("name = %q, want %q", got.Name, "Copy 1 ignored file (frontend)")
+ }
+}
+
+func TestBuildCopyFilesStep_WarningsAttached(t *testing.T) {
+ t.Parallel()
+ got := buildCopyFilesStep([]string{".env"},
+ []string{"no matches for pattern \".local\"", "skipped \"big.bin\""}, "")
+ if got.Warning == "" {
+ t.Fatal("expected warning")
+ }
+ if !strings.Contains(got.WarningDetail, "big.bin") {
+ t.Errorf("warningDetail = %q, expected joined warnings", got.WarningDetail)
+ }
+}
+
+// stubCopyFilesServer spins up an httptest server speaking the agentctl
+// POST /workspace/copy-files contract. Returns the URL the agentctl
+// client should target.
+func stubCopyFilesServer(t *testing.T, respond func(req client.CopyFilesRequest) client.CopyFilesResponse) string {
+ t.Helper()
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/api/v1/workspace/copy-files" {
+ http.Error(w, "not found", http.StatusNotFound)
+ return
+ }
+ var req client.CopyFilesRequest
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return
+ }
+ resp := respond(req)
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(resp)
+ }))
+ t.Cleanup(srv.Close)
+ return srv.URL
+}
+
+func TestRunRemoteCopyfiles_HappyPath_EmitsStep(t *testing.T) {
+ // Source repo with files matching the spec.
+ src := t.TempDir()
+ if err := os.WriteFile(filepath.Join(src, ".env"), []byte("X=1"), 0o600); err != nil {
+ t.Fatalf("write src .env: %v", err)
+ }
+
+ // Stub agentctl that mirrors the entries back as "copied" — verifies
+ // the helper actually shipped bytes rather than no-opping.
+ var received client.CopyFilesRequest
+ url := stubCopyFilesServer(t, func(req client.CopyFilesRequest) client.CopyFilesResponse {
+ received = req
+ out := make([]string, len(req.Entries))
+ for i, e := range req.Entries {
+ out[i] = e.RelPath
+ }
+ return client.CopyFilesResponse{Copied: out}
+ })
+
+ cli := clientForStub(t, url)
+ var got PrepareStep
+ cb := func(step PrepareStep, _, _ int) { got = step }
+
+ runRemoteCopyfiles(context.Background(), logger.Default(), remoteCopyfilesRequest{
+ SourceRepoPath: src,
+ CopyFilesSpec: ".env",
+ Client: cli,
+ OnProgress: cb,
+ })
+
+ if len(received.Entries) != 1 || received.Entries[0].RelPath != ".env" {
+ t.Fatalf("received entries = %+v, expected [.env]", received.Entries)
+ }
+ if string(received.Entries[0].Content) != "X=1" {
+ t.Errorf("payload content = %q, want X=1", received.Entries[0].Content)
+ }
+ if got.Name != "Copy 1 ignored file" {
+ t.Errorf("step name = %q, want %q", got.Name, "Copy 1 ignored file")
+ }
+ if got.Output != ".env" {
+ t.Errorf("step output = %q, want %q", got.Output, ".env")
+ }
+}
+
+func TestRunRemoteCopyfiles_NoSpec_NoOp(t *testing.T) {
+ emitted := false
+ cb := func(_ PrepareStep, _, _ int) { emitted = true }
+ runRemoteCopyfiles(context.Background(), logger.Default(), remoteCopyfilesRequest{
+ SourceRepoPath: t.TempDir(),
+ CopyFilesSpec: "",
+ OnProgress: cb,
+ })
+ if emitted {
+ t.Error("expected no step when CopyFilesSpec is empty")
+ }
+}
+
+func TestRunRemoteCopyfiles_ShipFailure_StillEmitsWarning(t *testing.T) {
+ src := t.TempDir()
+ _ = os.WriteFile(filepath.Join(src, ".env"), []byte("X=1"), 0o600)
+
+ // Agentctl returns an HTTP 500 with an error payload.
+ url := stubCopyFilesServerErr(t)
+ cli := clientForStub(t, url)
+ var got PrepareStep
+ cb := func(step PrepareStep, _, _ int) { got = step }
+
+ runRemoteCopyfiles(context.Background(), logger.Default(), remoteCopyfilesRequest{
+ SourceRepoPath: src,
+ CopyFilesSpec: ".env",
+ Client: cli,
+ OnProgress: cb,
+ })
+
+ if got.Name == "" {
+ t.Fatal("expected step to be emitted on ship failure")
+ }
+ if got.Warning == "" {
+ t.Error("expected warning on ship failure")
+ }
+}
+
+func TestShipRemoteCopyfilesForLaunch_SingleRepoUsesTopLevelSpec(t *testing.T) {
+ src := t.TempDir()
+ _ = os.WriteFile(filepath.Join(src, ".env"), []byte("X=1"), 0o600)
+
+ var received []client.CopyFilesRequest
+ url := stubCopyFilesServer(t, func(req client.CopyFilesRequest) client.CopyFilesResponse {
+ received = append(received, req)
+ out := make([]string, len(req.Entries))
+ for i, e := range req.Entries {
+ out[i] = e.RelPath
+ }
+ return client.CopyFilesResponse{Copied: out}
+ })
+
+ rec := newPrepareProgressRecorder(nil)
+ cli := clientForStub(t, url)
+ shipRemoteCopyfilesForLaunch(context.Background(), logger.Default(),
+ &LaunchRequest{RepositoryPath: src, CopyFiles: ".env"}, cli,
+ rec.Callback(0), rec)
+
+ if len(received) != 1 {
+ t.Fatalf("expected 1 ship call, got %d", len(received))
+ }
+ if received[0].Repo != "" {
+ t.Errorf("single-repo Repo subpath = %q, want empty", received[0].Repo)
+ }
+ if len(received[0].Entries) != 1 || received[0].Entries[0].RelPath != ".env" {
+ t.Errorf("entries = %+v, expected [.env]", received[0].Entries)
+ }
+ steps := rec.Steps()
+ if len(steps) != 1 || steps[0].Name != "Copy 1 ignored file" {
+ t.Errorf("steps = %+v, want one 'Copy 1 ignored file'", steps)
+ }
+}
+
+func TestShipRemoteCopyfilesForLaunch_MultiRepoSkipsEmptySpecs(t *testing.T) {
+ srcA := t.TempDir()
+ srcB := t.TempDir()
+ _ = os.WriteFile(filepath.Join(srcA, ".env.a"), []byte("A"), 0o600)
+ _ = os.WriteFile(filepath.Join(srcB, ".env.b"), []byte("B"), 0o600)
+
+ var received []client.CopyFilesRequest
+ url := stubCopyFilesServer(t, func(req client.CopyFilesRequest) client.CopyFilesResponse {
+ received = append(received, req)
+ out := make([]string, len(req.Entries))
+ for i, e := range req.Entries {
+ out[i] = e.RelPath
+ }
+ return client.CopyFilesResponse{Copied: out}
+ })
+
+ rec := newPrepareProgressRecorder(nil)
+ cli := clientForStub(t, url)
+ shipRemoteCopyfilesForLaunch(context.Background(), logger.Default(),
+ &LaunchRequest{
+ // Top-level fields should be ignored when Repositories is set —
+ // the multi-repo loop is the source of truth.
+ RepositoryPath: "/should/not/be/used",
+ CopyFiles: "ignored",
+ Repositories: []RepoLaunchSpec{
+ {RepositoryPath: srcA, RepoName: "alpha", CopyFiles: ".env.a"},
+ {RepositoryPath: srcB, RepoName: "beta", CopyFiles: ""}, // empty spec → skip
+ {RepositoryPath: srcB, RepoName: "gamma", CopyFiles: ".env.b"},
+ },
+ }, cli, rec.Callback(0), rec)
+
+ if len(received) != 2 {
+ t.Fatalf("expected 2 ship calls (alpha + gamma), got %d", len(received))
+ }
+ if received[0].Repo != "alpha" || received[1].Repo != "gamma" {
+ t.Errorf("subpaths = [%q, %q], want [alpha, gamma]", received[0].Repo, received[1].Repo)
+ }
+
+ // Each per-repo job should land in its own recorder slot — verifies the
+ // per-job Callback(progressRecorder.Len()) wiring (the original
+ // double-offset bug emitted both steps at the same index, clobbering one).
+ steps := rec.Steps()
+ if len(steps) != 2 {
+ t.Fatalf("expected 2 distinct steps, got %d (steps=%+v)", len(steps), steps)
+ }
+ if steps[0].Name != "Copy 1 ignored file (alpha)" || steps[1].Name != "Copy 1 ignored file (gamma)" {
+ t.Errorf("step names = [%q, %q], want [Copy 1 ignored file (alpha), Copy 1 ignored file (gamma)]",
+ steps[0].Name, steps[1].Name)
+ }
+}
+
+func TestShipRemoteCopyfilesForLaunch_NoSpec_NoOp(t *testing.T) {
+ rec := newPrepareProgressRecorder(nil)
+ shipRemoteCopyfilesForLaunch(context.Background(), logger.Default(),
+ &LaunchRequest{RepositoryPath: t.TempDir(), CopyFiles: ""}, nil,
+ rec.Callback(0), rec)
+ if got := len(rec.Steps()); got != 0 {
+ t.Errorf("expected zero steps for empty spec, got %d", got)
+ }
+}
+
+func stubCopyFilesServerErr(t *testing.T) string {
+ t.Helper()
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusInternalServerError)
+ _ = json.NewEncoder(w).Encode(client.CopyFilesResponse{Error: "disk full"})
+ }))
+ t.Cleanup(srv.Close)
+ return srv.URL
+}
+
+// clientForStub builds an agentctl Client pointed at a test URL. Parses
+// host:port from the httptest server URL.
+func clientForStub(t *testing.T, baseURL string) *client.Client {
+ t.Helper()
+ // Strip the http:// scheme; client.NewClient takes host+port.
+ stripped := strings.TrimPrefix(baseURL, "http://")
+ host, port, ok := strings.Cut(stripped, ":")
+ if !ok {
+ t.Fatalf("malformed test server URL: %s", baseURL)
+ }
+ var p int
+ for _, ch := range port {
+ p = p*10 + int(ch-'0')
+ }
+ // Verify we can satisfy the package interface — keep imports honest.
+ _ = copyfiles.MaxEntryBytes
+ return client.NewClient(host, p, logger.Default())
+}
diff --git a/apps/backend/internal/agent/runtime/lifecycle/types.go b/apps/backend/internal/agent/runtime/lifecycle/types.go
index fa234989a9..3140f4c942 100644
--- a/apps/backend/internal/agent/runtime/lifecycle/types.go
+++ b/apps/backend/internal/agent/runtime/lifecycle/types.go
@@ -307,6 +307,7 @@ type RepoLaunchSpec struct {
PullBeforeWorktree bool
RepoSetupScript string // Repository-level setup script (optional)
RepoCleanupScript string // Repository-level cleanup script (optional)
+ CopyFiles string // Comma-separated paths/globs to copy from the source repo (gitignored .env / config files)
}
// RouteOverride carries a fully resolved provider profile for one
@@ -361,6 +362,13 @@ type LaunchRequest struct {
// Environment preparation
SetupScript string // Setup script to run before agent starts
+ // CopyFiles is the per-repository copy_files spec resolved from
+ // Repository.CopyFiles by the orchestrator. For worktree executors the
+ // worktree.Manager applies it host-side during Create. For remote
+ // executors (Docker, Sprites) the launch path ships the bytes via
+ // agentctl after CreateInstance. Empty disables the feature.
+ CopyFiles string
+
// Worktree configuration
UseWorktree bool // Whether to use a Git worktree for isolation
WorktreeID string // Existing worktree ID to reuse (skip creation if set)
@@ -406,6 +414,7 @@ func (r *LaunchRequest) RepoSpecs() []RepoLaunchSpec {
WorktreeID: r.WorktreeID,
WorktreeBranchPrefix: r.WorktreeBranchPrefix,
PullBeforeWorktree: r.PullBeforeWorktree,
+ CopyFiles: r.CopyFiles,
}}
}
diff --git a/apps/backend/internal/agentctl/server/api/server.go b/apps/backend/internal/agentctl/server/api/server.go
index 39602cbe2c..78ca1a8643 100644
--- a/apps/backend/internal/agentctl/server/api/server.go
+++ b/apps/backend/internal/agentctl/server/api/server.go
@@ -111,6 +111,11 @@ func (s *Server) setupRoutes() {
api.DELETE("/workspace/file", s.handleFileDelete)
api.GET("/workspace/search", s.handleFileSearch)
+ // Batched copy of files from the host (used by remote executors —
+ // Docker, Sprites — to seed the workspace with gitignored config
+ // after the in-container clone).
+ api.POST("/workspace/copy-files", s.handleWorkspaceCopyFiles)
+
// Shell access (HTTP endpoints only - streaming is via /workspace/stream)
api.GET("/shell/status", s.handleShellStatus)
api.GET("/shell/buffer", s.handleShellBuffer)
diff --git a/apps/backend/internal/agentctl/server/api/workspace_copyfiles.go b/apps/backend/internal/agentctl/server/api/workspace_copyfiles.go
new file mode 100644
index 0000000000..0c1861f247
--- /dev/null
+++ b/apps/backend/internal/agentctl/server/api/workspace_copyfiles.go
@@ -0,0 +1,82 @@
+package api
+
+import (
+ "net/http"
+
+ "github.com/gin-gonic/gin"
+ "go.uber.org/zap"
+
+ "github.com/kandev/kandev/internal/worktree/copyfiles"
+)
+
+// CopyFilesRequest is the JSON body for POST /workspace/copy-files.
+// Repo is the optional per-repo subpath inside the workspace root
+// (matches the convention used by the other workspace/file/* endpoints
+// for multi-repo task workspaces). Entries are the planned files to
+// write — the caller (kandev backend) is responsible for reading the
+// bytes from the source repo and applying the per-source path-traversal
+// guard via copyfiles.Plan. The handler re-validates against the target
+// root so a compromised caller cannot escape the workspace.
+type CopyFilesRequest struct {
+ Repo string `json:"repo,omitempty"`
+ Entries []copyfiles.Entry `json:"entries"`
+}
+
+// CopyFilesResponse mirrors the host-side copyfiles return shape.
+type CopyFilesResponse struct {
+ Copied []string `json:"copied,omitempty"`
+ Warnings []string `json:"warnings,omitempty"`
+ Error string `json:"error,omitempty"`
+}
+
+// handleWorkspaceCopyFiles writes a batch of pre-planned files into the
+// workspace (or a per-repo subdir). Idempotent: existing destinations are
+// skipped. Used by remote executors (Docker, Sprites) whose containers
+// clone the workspace independently of the host and therefore can't
+// receive copy_files seeding via the worktree path.
+func (s *Server) handleWorkspaceCopyFiles(c *gin.Context) {
+ var req CopyFilesRequest
+ if err := c.ShouldBindJSON(&req); err != nil {
+ c.JSON(http.StatusBadRequest, CopyFilesResponse{Error: "invalid request: " + err.Error()})
+ return
+ }
+ if len(req.Entries) == 0 {
+ c.JSON(http.StatusOK, CopyFilesResponse{})
+ return
+ }
+
+ targetDir, err := s.procMgr.ResolveRepoSubdir(req.Repo)
+ if err != nil {
+ c.JSON(http.StatusBadRequest, CopyFilesResponse{Error: err.Error()})
+ return
+ }
+
+ // Pass the agentctl WorkDir as the containment root — this is the
+ // trusted workspace bound that WriteEntries verifies targetDir lies
+ // under before any filesystem access. Both come from the same source
+ // (procMgr) but the explicit two-argument shape is what CodeQL needs
+ // to recognise the path-injection sanitizer.
+ copied, warnings, err := copyfiles.WriteEntries(
+ c.Request.Context(),
+ s.procMgr.WorkDir(),
+ targetDir,
+ req.Entries,
+ s.logger.Zap(),
+ )
+ if err != nil {
+ s.logger.Warn("workspace/copy-files: write failed",
+ zap.String("target", targetDir),
+ zap.Error(err))
+ c.JSON(http.StatusInternalServerError, CopyFilesResponse{
+ Copied: copied,
+ Warnings: warnings,
+ Error: err.Error(),
+ })
+ return
+ }
+ s.logger.Info("workspace/copy-files: completed",
+ zap.String("target", targetDir),
+ zap.Int("copied", len(copied)),
+ zap.Int("warnings", len(warnings)))
+ c.JSON(http.StatusOK, CopyFilesResponse{Copied: copied, Warnings: warnings})
+}
diff --git a/apps/backend/internal/agentctl/server/api/workspace_copyfiles_test.go b/apps/backend/internal/agentctl/server/api/workspace_copyfiles_test.go
new file mode 100644
index 0000000000..d1fec29a34
--- /dev/null
+++ b/apps/backend/internal/agentctl/server/api/workspace_copyfiles_test.go
@@ -0,0 +1,150 @@
+package api
+
+import (
+ "bytes"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/kandev/kandev/internal/agentctl/server/config"
+ "github.com/kandev/kandev/internal/agentctl/server/process"
+ "github.com/kandev/kandev/internal/worktree/copyfiles"
+)
+
+// newCopyFilesTestServer builds an agentctl Server with a real WorkDir on
+// disk so the handler can resolve and write into it.
+func newCopyFilesTestServer(t *testing.T) (*Server, string) {
+ t.Helper()
+ workDir := t.TempDir()
+ log := newTestLogger()
+ cfg := &config.InstanceConfig{Port: 0, WorkDir: workDir}
+ procMgr := process.NewManager(cfg, log)
+ s := NewServer(cfg, procMgr, nil, nil, log)
+ return s, workDir
+}
+
+func TestHandleWorkspaceCopyFiles_WritesEntries(t *testing.T) {
+ s, workDir := newCopyFilesTestServer(t)
+
+ body, _ := json.Marshal(CopyFilesRequest{
+ Entries: []copyfiles.Entry{
+ {RelPath: ".env", Mode: 0o600, Content: []byte("X=1")},
+ {RelPath: "config/local.yml", Mode: 0o644, Content: []byte("y")},
+ },
+ })
+ req := httptest.NewRequest(http.MethodPost, "/api/v1/workspace/copy-files", bytes.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ s.router.ServeHTTP(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected 200, got %d (body: %s)", w.Code, w.Body.String())
+ }
+ var resp CopyFilesResponse
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatalf("decode: %v", err)
+ }
+ if len(resp.Copied) != 2 {
+ t.Errorf("copied = %v, want 2 entries", resp.Copied)
+ }
+ if got, err := os.ReadFile(filepath.Join(workDir, ".env")); err != nil || string(got) != "X=1" {
+ t.Errorf(".env content = %q, err = %v", got, err)
+ }
+ if got, err := os.ReadFile(filepath.Join(workDir, "config", "local.yml")); err != nil || string(got) != "y" {
+ t.Errorf("config/local.yml content = %q, err = %v", got, err)
+ }
+}
+
+func TestHandleWorkspaceCopyFiles_RejectsPathTraversal(t *testing.T) {
+ s, workDir := newCopyFilesTestServer(t)
+
+ body, _ := json.Marshal(CopyFilesRequest{
+ Entries: []copyfiles.Entry{
+ {RelPath: "../escape.txt", Mode: 0o644, Content: []byte("leak")},
+ },
+ })
+ req := httptest.NewRequest(http.MethodPost, "/api/v1/workspace/copy-files", bytes.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ s.router.ServeHTTP(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected 200 (rejection surfaces as warning, not HTTP error), got %d", w.Code)
+ }
+ var resp CopyFilesResponse
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatalf("decode: %v", err)
+ }
+ if len(resp.Copied) != 0 {
+ t.Errorf("copied = %v, want zero", resp.Copied)
+ }
+ if len(resp.Warnings) == 0 {
+ t.Error("expected warning for traversal entry")
+ }
+ if _, err := os.Stat(filepath.Join(filepath.Dir(workDir), "escape.txt")); !os.IsNotExist(err) {
+ t.Errorf("escape.txt should NOT exist outside workDir; stat err = %v", err)
+ }
+}
+
+func TestHandleWorkspaceCopyFiles_SkipsIfExists(t *testing.T) {
+ s, workDir := newCopyFilesTestServer(t)
+
+ if err := os.WriteFile(filepath.Join(workDir, ".env"), []byte("PREEXISTING"), 0o644); err != nil {
+ t.Fatalf("seed: %v", err)
+ }
+
+ body, _ := json.Marshal(CopyFilesRequest{
+ Entries: []copyfiles.Entry{{RelPath: ".env", Mode: 0o644, Content: []byte("NEW")}},
+ })
+ req := httptest.NewRequest(http.MethodPost, "/api/v1/workspace/copy-files", bytes.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ s.router.ServeHTTP(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+ var resp CopyFilesResponse
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if len(resp.Copied) != 0 {
+ t.Errorf("copied = %v, want zero (skip-if-exists)", resp.Copied)
+ }
+ got, _ := os.ReadFile(filepath.Join(workDir, ".env"))
+ if string(got) != "PREEXISTING" {
+ t.Errorf("existing file overwritten: %q", got)
+ }
+}
+
+func TestHandleWorkspaceCopyFiles_EmptyEntries(t *testing.T) {
+ s, _ := newCopyFilesTestServer(t)
+
+ body, _ := json.Marshal(CopyFilesRequest{Entries: nil})
+ req := httptest.NewRequest(http.MethodPost, "/api/v1/workspace/copy-files", bytes.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ s.router.ServeHTTP(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected 200 for empty entries, got %d", w.Code)
+ }
+}
+
+func TestHandleWorkspaceCopyFiles_RejectsBadRepoSubpath(t *testing.T) {
+ s, _ := newCopyFilesTestServer(t)
+
+ body, _ := json.Marshal(CopyFilesRequest{
+ Repo: "../escape",
+ Entries: []copyfiles.Entry{{RelPath: "x", Mode: 0o644, Content: []byte("x")}},
+ })
+ req := httptest.NewRequest(http.MethodPost, "/api/v1/workspace/copy-files", bytes.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ s.router.ServeHTTP(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Errorf("expected 400 for bad repo subpath, got %d (body: %s)", w.Code, w.Body.String())
+ }
+}
diff --git a/apps/backend/internal/agentctl/server/process/manager.go b/apps/backend/internal/agentctl/server/process/manager.go
index e0c778d9b5..d01932719d 100644
--- a/apps/backend/internal/agentctl/server/process/manager.go
+++ b/apps/backend/internal/agentctl/server/process/manager.go
@@ -464,6 +464,22 @@ func (m *Manager) resolveSubpath(subpath string) (string, string, error) {
return cleaned, full, nil
}
+// WorkDir returns the absolute workspace root for this agentctl instance.
+// Handlers that bypass WorkspaceTracker (e.g. the batched copy-files endpoint
+// that writes into a per-repo subdir directly) need the resolved root.
+func (m *Manager) WorkDir() string {
+ return m.cfg.WorkDir
+}
+
+// ResolveRepoSubdir returns the absolute filesystem directory for an
+// optional repo subpath under the workspace. Same validation as the
+// internal resolveSubpath helper (rejects traversal, requires existence).
+// Empty subpath returns the workspace root.
+func (m *Manager) ResolveRepoSubdir(subpath string) (string, error) {
+ _, full, err := m.resolveSubpath(subpath)
+ return full, err
+}
+
// JoinRepoPath validates a repo subpath and returns the workspace-relative
// path obtained by joining `subpath` and `path`. Empty `subpath` returns
// `path` unchanged (single-repo workspaces). Used by file content / update
diff --git a/apps/backend/internal/orchestrator/executor/executor.go b/apps/backend/internal/orchestrator/executor/executor.go
index 077876f702..46bc82cdf5 100644
--- a/apps/backend/internal/orchestrator/executor/executor.go
+++ b/apps/backend/internal/orchestrator/executor/executor.go
@@ -272,6 +272,12 @@ type LaunchAgentRequest struct {
// Setup script from executor profile (runs in execution environment before agent starts)
SetupScript string
+ // CopyFiles is the per-repository copy_files spec resolved from
+ // Repository.CopyFiles. Used by the worktree path (host-side copy via
+ // worktree.Manager) and by remote-executor paths (Docker, Sprites)
+ // which ship the bytes via agentctl.
+ CopyFiles string
+
// Worktree configuration for concurrent agent execution
UseWorktree bool // Whether to use a Git worktree for isolation
WorktreeID string // Existing worktree ID to reuse (skip creation if set)
@@ -318,6 +324,7 @@ type RepoSpec struct {
PullBeforeWorktree bool
RepoSetupScript string
RepoCleanupScript string
+ CopyFiles string
}
// McpModeConfig activates config-mode MCP tools (workflow steps, agents, MCP
diff --git a/apps/backend/internal/orchestrator/executor/executor_execute.go b/apps/backend/internal/orchestrator/executor/executor_execute.go
index 7dcd020537..9acb2ccbfb 100644
--- a/apps/backend/internal/orchestrator/executor/executor_execute.go
+++ b/apps/backend/internal/orchestrator/executor/executor_execute.go
@@ -706,6 +706,7 @@ func buildRepoSpecs(allRepos []*repoInfo) []RepoSpec {
spec.RepoSetupScript = info.Repository.SetupScript
spec.RepoCleanupScript = info.Repository.CleanupScript
spec.DefaultBranch = info.Repository.DefaultBranch
+ spec.CopyFiles = info.Repository.CopyFiles
}
// Containerized executors need a clone URL; reuse the same helper as
// the single-repo path (best-effort — skipped if Repository is nil).
@@ -744,6 +745,9 @@ func (e *Executor) applyRepositoryConfig(req *LaunchAgentRequest, task *v1.Task,
}
metadata[lifecycle.MetadataKeyRepoSetupScript] = repoInfo.Repository.SetupScript
}
+ if repoInfo.Repository != nil {
+ req.CopyFiles = repoInfo.Repository.CopyFiles
+ }
}
// Remote executors need a clone URL since the remote host has no access to the local filesystem.
diff --git a/apps/backend/internal/task/dto/dto.go b/apps/backend/internal/task/dto/dto.go
index 5c20dba586..e3cd0c646e 100644
--- a/apps/backend/internal/task/dto/dto.go
+++ b/apps/backend/internal/task/dto/dto.go
@@ -55,6 +55,7 @@ type RepositoryDTO struct {
SetupScript string `json:"setup_script"`
CleanupScript string `json:"cleanup_script"`
DevScript string `json:"dev_script"`
+ CopyFiles string `json:"copy_files"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
Scripts []RepositoryScriptDTO `json:"scripts,omitempty"`
@@ -443,6 +444,7 @@ func FromRepository(repository *models.Repository) RepositoryDTO {
SetupScript: repository.SetupScript,
CleanupScript: repository.CleanupScript,
DevScript: repository.DevScript,
+ CopyFiles: repository.CopyFiles,
CreatedAt: repository.CreatedAt,
UpdatedAt: repository.UpdatedAt,
}
diff --git a/apps/backend/internal/task/dto/requests.go b/apps/backend/internal/task/dto/requests.go
index 628d40b321..bef6c6d846 100644
--- a/apps/backend/internal/task/dto/requests.go
+++ b/apps/backend/internal/task/dto/requests.go
@@ -82,6 +82,7 @@ type CreateRepositoryRequest struct {
SetupScript string
CleanupScript string
DevScript string
+ CopyFiles string
}
type UpdateRepositoryRequest struct {
@@ -99,6 +100,7 @@ type UpdateRepositoryRequest struct {
SetupScript *string
CleanupScript *string
DevScript *string
+ CopyFiles *string
}
type DeleteRepositoryRequest struct {
diff --git a/apps/backend/internal/task/handlers/repository_handlers.go b/apps/backend/internal/task/handlers/repository_handlers.go
index 2c8b4052cf..cb1c65c333 100644
--- a/apps/backend/internal/task/handlers/repository_handlers.go
+++ b/apps/backend/internal/task/handlers/repository_handlers.go
@@ -267,6 +267,7 @@ type httpCreateRepositoryRequest struct {
SetupScript string `json:"setup_script"`
CleanupScript string `json:"cleanup_script"`
DevScript string `json:"dev_script"`
+ CopyFiles string `json:"copy_files"`
}
func (h *RepositoryHandlers) httpCreateRepository(c *gin.Context) {
@@ -294,6 +295,7 @@ func (h *RepositoryHandlers) httpCreateRepository(c *gin.Context) {
SetupScript: body.SetupScript,
CleanupScript: body.CleanupScript,
DevScript: body.DevScript,
+ CopyFiles: body.CopyFiles,
})
if err != nil {
if errors.Is(err, service.ErrInvalidRepositorySettings) {
@@ -402,6 +404,7 @@ type httpUpdateRepositoryRequest struct {
SetupScript *string `json:"setup_script"`
CleanupScript *string `json:"cleanup_script"`
DevScript *string `json:"dev_script"`
+ CopyFiles *string `json:"copy_files"`
}
func (h *RepositoryHandlers) httpUpdateRepository(c *gin.Context) {
@@ -424,6 +427,7 @@ func (h *RepositoryHandlers) httpUpdateRepository(c *gin.Context) {
SetupScript: body.SetupScript,
CleanupScript: body.CleanupScript,
DevScript: body.DevScript,
+ CopyFiles: body.CopyFiles,
})
if err != nil {
if errors.Is(err, service.ErrInvalidRepositorySettings) {
@@ -499,6 +503,7 @@ type wsCreateRepositoryRequest struct {
SetupScript string `json:"setup_script"`
CleanupScript string `json:"cleanup_script"`
DevScript string `json:"dev_script"`
+ CopyFiles string `json:"copy_files"`
}
func (h *RepositoryHandlers) wsCreateRepository(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
@@ -523,6 +528,7 @@ func (h *RepositoryHandlers) wsCreateRepository(ctx context.Context, msg *ws.Mes
SetupScript: req.SetupScript,
CleanupScript: req.CleanupScript,
DevScript: req.DevScript,
+ CopyFiles: req.CopyFiles,
})
if err != nil {
if errors.Is(err, service.ErrInvalidRepositorySettings) {
@@ -567,6 +573,7 @@ type wsUpdateRepositoryRequest struct {
SetupScript *string `json:"setup_script,omitempty"`
CleanupScript *string `json:"cleanup_script,omitempty"`
DevScript *string `json:"dev_script,omitempty"`
+ CopyFiles *string `json:"copy_files,omitempty"`
}
func (h *RepositoryHandlers) wsUpdateRepository(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
@@ -590,6 +597,7 @@ func (h *RepositoryHandlers) wsUpdateRepository(ctx context.Context, msg *ws.Mes
SetupScript: req.SetupScript,
CleanupScript: req.CleanupScript,
DevScript: req.DevScript,
+ CopyFiles: req.CopyFiles,
})
if err != nil {
if errors.Is(err, service.ErrInvalidRepositorySettings) {
diff --git a/apps/backend/internal/task/handlers/repository_handlers_test.go b/apps/backend/internal/task/handlers/repository_handlers_test.go
new file mode 100644
index 0000000000..4829fe97cf
--- /dev/null
+++ b/apps/backend/internal/task/handlers/repository_handlers_test.go
@@ -0,0 +1,85 @@
+package handlers
+
+import (
+ "encoding/json"
+ "strings"
+ "testing"
+)
+
+// TestRepositoryCreateRequestJSONIncludesCopyFiles verifies that the
+// copy_files field is wired through the JSON encoding/decoding for both the
+// HTTP and WS create-repository request shapes. Failure here means the
+// handler will silently drop a `copy_files` value sent by the client.
+func TestRepositoryCreateRequestJSONIncludesCopyFiles(t *testing.T) {
+ t.Run("http_marshal_contains_copy_files", func(t *testing.T) {
+ req := httpCreateRepositoryRequest{Name: "r", CopyFiles: ".env"}
+ b, err := json.Marshal(&req)
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ if !strings.Contains(string(b), `"copy_files":".env"`) {
+ t.Errorf("missing copy_files in JSON: %s", b)
+ }
+ })
+
+ t.Run("http_unmarshal_populates_copy_files", func(t *testing.T) {
+ var req httpCreateRepositoryRequest
+ if err := json.Unmarshal([]byte(`{"name":"r","copy_files":".env, *.local"}`), &req); err != nil {
+ t.Fatalf("unmarshal: %v", err)
+ }
+ if req.CopyFiles != ".env, *.local" {
+ t.Errorf("CopyFiles = %q, want %q", req.CopyFiles, ".env, *.local")
+ }
+ })
+
+ t.Run("ws_unmarshal_populates_copy_files", func(t *testing.T) {
+ var req wsCreateRepositoryRequest
+ if err := json.Unmarshal([]byte(`{"workspace_id":"w","name":"r","copy_files":".env"}`), &req); err != nil {
+ t.Fatalf("unmarshal: %v", err)
+ }
+ if req.CopyFiles != ".env" {
+ t.Errorf("CopyFiles = %q, want %q", req.CopyFiles, ".env")
+ }
+ })
+}
+
+// TestRepositoryUpdateRequestJSONCopyFilesPointer verifies the pointer-style
+// copy_files field on update requests round-trips correctly — nil when
+// omitted, non-nil and dereferenceable to the supplied value when present.
+func TestRepositoryUpdateRequestJSONCopyFilesPointer(t *testing.T) {
+ t.Run("http_unmarshal_sets_pointer", func(t *testing.T) {
+ var req httpUpdateRepositoryRequest
+ if err := json.Unmarshal([]byte(`{"copy_files":".env, *.local"}`), &req); err != nil {
+ t.Fatalf("unmarshal: %v", err)
+ }
+ if req.CopyFiles == nil {
+ t.Fatal("CopyFiles is nil, want non-nil")
+ }
+ if *req.CopyFiles != ".env, *.local" {
+ t.Errorf("*CopyFiles = %q, want %q", *req.CopyFiles, ".env, *.local")
+ }
+ })
+
+ t.Run("http_omitted_leaves_nil", func(t *testing.T) {
+ var req httpUpdateRepositoryRequest
+ if err := json.Unmarshal([]byte(`{"name":"r"}`), &req); err != nil {
+ t.Fatalf("unmarshal: %v", err)
+ }
+ if req.CopyFiles != nil {
+ t.Errorf("CopyFiles = %v, want nil", req.CopyFiles)
+ }
+ })
+
+ t.Run("ws_unmarshal_sets_pointer", func(t *testing.T) {
+ var req wsUpdateRepositoryRequest
+ if err := json.Unmarshal([]byte(`{"id":"x","copy_files":""}`), &req); err != nil {
+ t.Fatalf("unmarshal: %v", err)
+ }
+ if req.CopyFiles == nil {
+ t.Fatal("CopyFiles is nil, want non-nil pointer to empty string")
+ }
+ if *req.CopyFiles != "" {
+ t.Errorf("*CopyFiles = %q, want empty string", *req.CopyFiles)
+ }
+ })
+}
diff --git a/apps/backend/internal/task/models/models.go b/apps/backend/internal/task/models/models.go
index ab0ec15176..e1ff2a4f14 100644
--- a/apps/backend/internal/task/models/models.go
+++ b/apps/backend/internal/task/models/models.go
@@ -487,6 +487,7 @@ type Repository struct {
SetupScript string `json:"setup_script"`
CleanupScript string `json:"cleanup_script"`
DevScript string `json:"dev_script"`
+ CopyFiles string `json:"copy_files"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
DeletedAt *time.Time `json:"deleted_at,omitempty"`
diff --git a/apps/backend/internal/task/repository/sqlite/base.go b/apps/backend/internal/task/repository/sqlite/base.go
index b8162d4031..1cc5181a7b 100644
--- a/apps/backend/internal/task/repository/sqlite/base.go
+++ b/apps/backend/internal/task/repository/sqlite/base.go
@@ -201,6 +201,7 @@ func (r *Repository) runMigrations() error {
r.migrate.Apply("workflows.agent_profile_id", `ALTER TABLE workflows ADD COLUMN agent_profile_id TEXT DEFAULT ''`)
r.migrate.Apply("workflows.hidden", `ALTER TABLE workflows ADD COLUMN hidden INTEGER NOT NULL DEFAULT 0`)
r.migrate.Apply("task_sessions.workspace_path", `ALTER TABLE task_sessions ADD COLUMN workspace_path TEXT DEFAULT ''`)
+ r.migrate.Apply("repositories.copy_files", `ALTER TABLE repositories ADD COLUMN copy_files TEXT DEFAULT ''`)
// Office task extensions - net-new columns on existing main tables.
// Idempotent ALTERs; main upgrades pick them up at first boot.
@@ -1091,6 +1092,7 @@ func (r *Repository) initTaskSchema() error {
setup_script TEXT DEFAULT '',
cleanup_script TEXT DEFAULT '',
dev_script TEXT DEFAULT '',
+ copy_files TEXT DEFAULT '',
created_at TIMESTAMP NOT NULL,
updated_at TIMESTAMP NOT NULL,
deleted_at TIMESTAMP,
diff --git a/apps/backend/internal/task/repository/sqlite/repository_entity.go b/apps/backend/internal/task/repository/sqlite/repository_entity.go
index 70b788e196..9ddf860da8 100644
--- a/apps/backend/internal/task/repository/sqlite/repository_entity.go
+++ b/apps/backend/internal/task/repository/sqlite/repository_entity.go
@@ -25,11 +25,11 @@ func (r *Repository) CreateRepository(ctx context.Context, repository *models.Re
_, err := r.db.ExecContext(ctx, r.db.Rebind(`
INSERT INTO repositories (
id, workspace_id, name, source_type, local_path, provider, provider_repo_id, provider_owner,
- provider_name, default_branch, worktree_branch_prefix, pull_before_worktree, setup_script, cleanup_script, dev_script, created_at, updated_at, deleted_at
- ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ provider_name, default_branch, worktree_branch_prefix, pull_before_worktree, setup_script, cleanup_script, dev_script, copy_files, created_at, updated_at, deleted_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`), repository.ID, repository.WorkspaceID, repository.Name, repository.SourceType, repository.LocalPath, repository.Provider,
repository.ProviderRepoID, repository.ProviderOwner, repository.ProviderName, repository.DefaultBranch, repository.WorktreeBranchPrefix,
- dialect.BoolToInt(repository.PullBeforeWorktree), repository.SetupScript, repository.CleanupScript, repository.DevScript, repository.CreatedAt, repository.UpdatedAt, repository.DeletedAt)
+ dialect.BoolToInt(repository.PullBeforeWorktree), repository.SetupScript, repository.CleanupScript, repository.DevScript, repository.CopyFiles, repository.CreatedAt, repository.UpdatedAt, repository.DeletedAt)
return err
}
@@ -40,12 +40,12 @@ func (r *Repository) GetRepository(ctx context.Context, id string) (*models.Repo
err := r.ro.QueryRowContext(ctx, r.ro.Rebind(`
SELECT id, workspace_id, name, source_type, local_path, provider, provider_repo_id, provider_owner,
- provider_name, default_branch, worktree_branch_prefix, pull_before_worktree, setup_script, cleanup_script, dev_script, created_at, updated_at, deleted_at
+ provider_name, default_branch, worktree_branch_prefix, pull_before_worktree, setup_script, cleanup_script, dev_script, copy_files, created_at, updated_at, deleted_at
FROM repositories WHERE id = ? AND deleted_at IS NULL
`), id).Scan(
&repository.ID, &repository.WorkspaceID, &repository.Name, &repository.SourceType, &repository.LocalPath,
&repository.Provider, &repository.ProviderRepoID, &repository.ProviderOwner, &repository.ProviderName,
- &repository.DefaultBranch, &repository.WorktreeBranchPrefix, &repository.PullBeforeWorktree, &repository.SetupScript, &repository.CleanupScript, &repository.DevScript, &repository.CreatedAt, &repository.UpdatedAt, &repository.DeletedAt,
+ &repository.DefaultBranch, &repository.WorktreeBranchPrefix, &repository.PullBeforeWorktree, &repository.SetupScript, &repository.CleanupScript, &repository.DevScript, &repository.CopyFiles, &repository.CreatedAt, &repository.UpdatedAt, &repository.DeletedAt,
)
if err == sql.ErrNoRows {
@@ -61,11 +61,11 @@ func (r *Repository) UpdateRepository(ctx context.Context, repository *models.Re
result, err := r.db.ExecContext(ctx, r.db.Rebind(`
UPDATE repositories SET
name = ?, source_type = ?, local_path = ?, provider = ?, provider_repo_id = ?, provider_owner = ?,
- provider_name = ?, default_branch = ?, worktree_branch_prefix = ?, pull_before_worktree = ?, setup_script = ?, cleanup_script = ?, dev_script = ?, updated_at = ?
+ provider_name = ?, default_branch = ?, worktree_branch_prefix = ?, pull_before_worktree = ?, setup_script = ?, cleanup_script = ?, dev_script = ?, copy_files = ?, updated_at = ?
WHERE id = ? AND deleted_at IS NULL
`), repository.Name, repository.SourceType, repository.LocalPath, repository.Provider, repository.ProviderRepoID,
repository.ProviderOwner, repository.ProviderName, repository.DefaultBranch, repository.WorktreeBranchPrefix, dialect.BoolToInt(repository.PullBeforeWorktree),
- repository.SetupScript, repository.CleanupScript, repository.DevScript, repository.UpdatedAt, repository.ID)
+ repository.SetupScript, repository.CleanupScript, repository.DevScript, repository.CopyFiles, repository.UpdatedAt, repository.ID)
if err != nil {
return err
}
@@ -97,7 +97,7 @@ func (r *Repository) DeleteRepository(ctx context.Context, id string) error {
func (r *Repository) ListRepositories(ctx context.Context, workspaceID string) ([]*models.Repository, error) {
rows, err := r.ro.QueryContext(ctx, r.ro.Rebind(`
SELECT id, workspace_id, name, source_type, local_path, provider, provider_repo_id, provider_owner,
- provider_name, default_branch, worktree_branch_prefix, pull_before_worktree, setup_script, cleanup_script, dev_script, created_at, updated_at, deleted_at
+ provider_name, default_branch, worktree_branch_prefix, pull_before_worktree, setup_script, cleanup_script, dev_script, copy_files, created_at, updated_at, deleted_at
FROM repositories WHERE workspace_id = ? AND deleted_at IS NULL ORDER BY created_at DESC
`), workspaceID)
if err != nil {
@@ -111,7 +111,7 @@ func (r *Repository) ListRepositories(ctx context.Context, workspaceID string) (
err := rows.Scan(
&repository.ID, &repository.WorkspaceID, &repository.Name, &repository.SourceType, &repository.LocalPath,
&repository.Provider, &repository.ProviderRepoID, &repository.ProviderOwner, &repository.ProviderName,
- &repository.DefaultBranch, &repository.WorktreeBranchPrefix, &repository.PullBeforeWorktree, &repository.SetupScript, &repository.CleanupScript, &repository.DevScript, &repository.CreatedAt, &repository.UpdatedAt, &repository.DeletedAt,
+ &repository.DefaultBranch, &repository.WorktreeBranchPrefix, &repository.PullBeforeWorktree, &repository.SetupScript, &repository.CleanupScript, &repository.DevScript, &repository.CopyFiles, &repository.CreatedAt, &repository.UpdatedAt, &repository.DeletedAt,
)
if err != nil {
return nil, err
@@ -127,13 +127,13 @@ func (r *Repository) GetRepositoryByProviderInfo(ctx context.Context, workspaceI
repository := &models.Repository{}
err := r.ro.QueryRowContext(ctx, r.ro.Rebind(`
SELECT id, workspace_id, name, source_type, local_path, provider, provider_repo_id, provider_owner,
- provider_name, default_branch, worktree_branch_prefix, pull_before_worktree, setup_script, cleanup_script, dev_script, created_at, updated_at, deleted_at
+ provider_name, default_branch, worktree_branch_prefix, pull_before_worktree, setup_script, cleanup_script, dev_script, copy_files, created_at, updated_at, deleted_at
FROM repositories
WHERE workspace_id = ? AND provider = ? AND provider_owner = ? AND provider_name = ? AND deleted_at IS NULL
`), workspaceID, provider, owner, name).Scan(
&repository.ID, &repository.WorkspaceID, &repository.Name, &repository.SourceType, &repository.LocalPath,
&repository.Provider, &repository.ProviderRepoID, &repository.ProviderOwner, &repository.ProviderName,
- &repository.DefaultBranch, &repository.WorktreeBranchPrefix, &repository.PullBeforeWorktree, &repository.SetupScript, &repository.CleanupScript, &repository.DevScript, &repository.CreatedAt, &repository.UpdatedAt, &repository.DeletedAt,
+ &repository.DefaultBranch, &repository.WorktreeBranchPrefix, &repository.PullBeforeWorktree, &repository.SetupScript, &repository.CleanupScript, &repository.DevScript, &repository.CopyFiles, &repository.CreatedAt, &repository.UpdatedAt, &repository.DeletedAt,
)
if err == sql.ErrNoRows {
return nil, nil
diff --git a/apps/backend/internal/task/repository/sqlite/repository_entity_test.go b/apps/backend/internal/task/repository/sqlite/repository_entity_test.go
new file mode 100644
index 0000000000..0141c729a2
--- /dev/null
+++ b/apps/backend/internal/task/repository/sqlite/repository_entity_test.go
@@ -0,0 +1,143 @@
+package sqlite
+
+import (
+ "context"
+ "path/filepath"
+ "testing"
+
+ "github.com/jmoiron/sqlx"
+
+ "github.com/kandev/kandev/internal/db"
+ "github.com/kandev/kandev/internal/task/models"
+)
+
+func newRepoForEntityTests(t *testing.T) *Repository {
+ t.Helper()
+ dbPath := filepath.Join(t.TempDir(), "repo-entity-test.db")
+ dbConn, err := db.OpenSQLite(dbPath)
+ if err != nil {
+ t.Fatalf("open sqlite: %v", err)
+ }
+ sqlxDB := sqlx.NewDb(dbConn, "sqlite3")
+ repo, err := NewWithDB(sqlxDB, sqlxDB, nil)
+ if err != nil {
+ t.Fatalf("new repo: %v", err)
+ }
+ t.Cleanup(func() { _ = sqlxDB.Close() })
+ return repo
+}
+
+func seedWorkspace(t *testing.T, repo *Repository, id string) {
+ t.Helper()
+ if err := repo.CreateWorkspace(context.Background(), &models.Workspace{ID: id, Name: id}); err != nil {
+ t.Fatalf("seed workspace %s: %v", id, err)
+ }
+}
+
+// TestRepositoryCopyFiles_RoundTrip writes a repository with a non-empty
+// CopyFiles, fetches it back via GetRepository and ListRepositories, and
+// asserts the value survived both code paths.
+func TestRepositoryCopyFiles_RoundTrip(t *testing.T) {
+ repo := newRepoForEntityTests(t)
+ ctx := context.Background()
+ seedWorkspace(t, repo, "ws-copy")
+
+ in := &models.Repository{
+ ID: "repo-copy-1",
+ WorkspaceID: "ws-copy",
+ Name: "with-copy-files",
+ SourceType: "local",
+ CopyFiles: ".env, *.local",
+ }
+ if err := repo.CreateRepository(ctx, in); err != nil {
+ t.Fatalf("create repository: %v", err)
+ }
+
+ got, err := repo.GetRepository(ctx, in.ID)
+ if err != nil {
+ t.Fatalf("get repository: %v", err)
+ }
+ if got.CopyFiles != ".env, *.local" {
+ t.Errorf("GetRepository CopyFiles = %q, want %q", got.CopyFiles, ".env, *.local")
+ }
+
+ list, err := repo.ListRepositories(ctx, "ws-copy")
+ if err != nil {
+ t.Fatalf("list repositories: %v", err)
+ }
+ if len(list) != 1 || list[0].CopyFiles != ".env, *.local" {
+ t.Errorf("ListRepositories CopyFiles = %v, want one repo with %q", list, ".env, *.local")
+ }
+}
+
+// TestRepositoryCopyFiles_Update creates a repo with an empty CopyFiles
+// value, mutates the model in-memory, calls UpdateRepository, and verifies
+// the new value is persisted.
+func TestRepositoryCopyFiles_Update(t *testing.T) {
+ repo := newRepoForEntityTests(t)
+ ctx := context.Background()
+ seedWorkspace(t, repo, "ws-copy-upd")
+
+ in := &models.Repository{
+ ID: "repo-copy-upd",
+ WorkspaceID: "ws-copy-upd",
+ Name: "update-target",
+ SourceType: "local",
+ }
+ if err := repo.CreateRepository(ctx, in); err != nil {
+ t.Fatalf("create repository: %v", err)
+ }
+
+ in.CopyFiles = ".env"
+ if err := repo.UpdateRepository(ctx, in); err != nil {
+ t.Fatalf("update repository: %v", err)
+ }
+
+ got, err := repo.GetRepository(ctx, in.ID)
+ if err != nil {
+ t.Fatalf("get repository: %v", err)
+ }
+ if got.CopyFiles != ".env" {
+ t.Errorf("after update, CopyFiles = %q, want %q", got.CopyFiles, ".env")
+ }
+}
+
+// TestRepositoryCopyFiles_DefaultEmpty ensures older callers that don't
+// populate CopyFiles round-trip to an empty string rather than panicking on
+// a NULL scan.
+func TestRepositoryCopyFiles_DefaultEmpty(t *testing.T) {
+ repo := newRepoForEntityTests(t)
+ ctx := context.Background()
+ seedWorkspace(t, repo, "ws-copy-def")
+
+ in := &models.Repository{
+ ID: "repo-copy-def",
+ WorkspaceID: "ws-copy-def",
+ Name: "no-copy-files",
+ SourceType: "local",
+ }
+ if err := repo.CreateRepository(ctx, in); err != nil {
+ t.Fatalf("create repository: %v", err)
+ }
+
+ got, err := repo.GetRepository(ctx, in.ID)
+ if err != nil {
+ t.Fatalf("get repository: %v", err)
+ }
+ if got.CopyFiles != "" {
+ t.Errorf("default CopyFiles = %q, want empty string", got.CopyFiles)
+ }
+}
+
+// TestRunMigrations_Idempotent verifies that re-running migrations on an
+// already-migrated schema does not error (Apply swallows "duplicate column"
+// failures by design).
+func TestRunMigrations_Idempotent(t *testing.T) {
+ repo := newRepoForEntityTests(t)
+ if err := repo.runMigrations(); err != nil {
+ t.Fatalf("second runMigrations call returned error: %v", err)
+ }
+ if err := repo.runMigrations(); err != nil {
+ t.Fatalf("third runMigrations call returned error: %v", err)
+ }
+}
diff --git a/apps/backend/internal/task/service/service_requests.go b/apps/backend/internal/task/service/service_requests.go
index ba219447f8..7e53cb4287 100644
--- a/apps/backend/internal/task/service/service_requests.go
+++ b/apps/backend/internal/task/service/service_requests.go
@@ -120,6 +120,7 @@ type CreateRepositoryRequest struct {
SetupScript string `json:"setup_script"`
CleanupScript string `json:"cleanup_script"`
DevScript string `json:"dev_script"`
+ CopyFiles string `json:"copy_files"`
}
// UpdateRepositoryRequest contains the data for updating a repository
@@ -137,6 +138,7 @@ type UpdateRepositoryRequest struct {
SetupScript *string `json:"setup_script,omitempty"`
CleanupScript *string `json:"cleanup_script,omitempty"`
DevScript *string `json:"dev_script,omitempty"`
+ CopyFiles *string `json:"copy_files,omitempty"`
}
// CreateExecutorRequest contains the data for creating an executor
diff --git a/apps/backend/internal/task/service/service_resources.go b/apps/backend/internal/task/service/service_resources.go
index cc68a358b7..99403371e1 100644
--- a/apps/backend/internal/task/service/service_resources.go
+++ b/apps/backend/internal/task/service/service_resources.go
@@ -284,6 +284,7 @@ func (s *Service) CreateRepository(ctx context.Context, req *CreateRepositoryReq
SetupScript: req.SetupScript,
CleanupScript: req.CleanupScript,
DevScript: req.DevScript,
+ CopyFiles: req.CopyFiles,
}
// Auto-detect GitHub provider info from git remote if not provided
@@ -412,6 +413,9 @@ func applyRepositoryUpdates(repository *models.Repository, req *UpdateRepository
if req.DevScript != nil {
repository.DevScript = *req.DevScript
}
+ if req.CopyFiles != nil {
+ repository.CopyFiles = *req.CopyFiles
+ }
return nil
}
diff --git a/apps/backend/internal/task/service/service_resources_test.go b/apps/backend/internal/task/service/service_resources_test.go
index 2e1bca8a1c..c00b32e733 100644
--- a/apps/backend/internal/task/service/service_resources_test.go
+++ b/apps/backend/internal/task/service/service_resources_test.go
@@ -127,3 +127,29 @@ func TestService_GetOfficeWorkflowIDs_DBError(t *testing.T) {
t.Errorf("expected nil on DB error, got %v", ids)
}
}
+
+// TestApplyRepositoryUpdates_CopyFilesNilLeavesUntouched verifies the
+// pointer-nil convention: a nil CopyFiles field on the request must not
+// clobber an existing repository value.
+func TestApplyRepositoryUpdates_CopyFilesNilLeavesUntouched(t *testing.T) {
+ repo := &models.Repository{CopyFiles: "existing"}
+ if err := applyRepositoryUpdates(repo, &UpdateRepositoryRequest{}); err != nil {
+ t.Fatalf("applyRepositoryUpdates: %v", err)
+ }
+ if repo.CopyFiles != "existing" {
+ t.Errorf("CopyFiles = %q, want %q (nil request field must not overwrite)", repo.CopyFiles, "existing")
+ }
+}
+
+// TestApplyRepositoryUpdates_CopyFilesEmptyStringClears verifies that an
+// explicit empty-string pointer clears the value (distinct from "no update").
+func TestApplyRepositoryUpdates_CopyFilesEmptyStringClears(t *testing.T) {
+ repo := &models.Repository{CopyFiles: "existing"}
+ empty := ""
+ if err := applyRepositoryUpdates(repo, &UpdateRepositoryRequest{CopyFiles: &empty}); err != nil {
+ t.Fatalf("applyRepositoryUpdates: %v", err)
+ }
+ if repo.CopyFiles != "" {
+ t.Errorf("CopyFiles = %q, want empty string", repo.CopyFiles)
+ }
+}
diff --git a/apps/backend/internal/worktree/copyfiles/copyfiles.go b/apps/backend/internal/worktree/copyfiles/copyfiles.go
new file mode 100644
index 0000000000..0c8f2b239e
--- /dev/null
+++ b/apps/backend/internal/worktree/copyfiles/copyfiles.go
@@ -0,0 +1,634 @@
+// Package copyfiles copies user-specified files (literal paths, directories, or
+// globs) from a source directory into a freshly-created target directory while
+// preserving relative paths. It is designed for the worktree feature that
+// seeds a new worktree with environment / config files that are normally
+// gitignored.
+//
+// Two entry points:
+//
+// - Copy: host-side, streams files directly to disk. Used by the worktree
+// preparer when source and target both live on the host filesystem.
+// - Plan + WriteEntries: split for remote executors. Plan reads source
+// bytes into memory (with a per-file size cap); WriteEntries writes a
+// pre-loaded batch into a target directory. The agentctl HTTP path
+// ships Plan output across the wire and calls WriteEntries on the
+// receiving side.
+package copyfiles
+
+import (
+ "context"
+ "fmt"
+ "io"
+ "io/fs"
+ "os"
+ "path/filepath"
+ "strings"
+
+ "go.uber.org/zap"
+)
+
+// MaxEntryBytes caps the in-memory payload for a single planned entry. A
+// stray pattern like `node_modules` would otherwise pull gigabytes into RAM
+// and across the agentctl wire. Tuned to comfortably hold reasonable
+// .env / config / certificate files while rejecting an accidental
+// directory-of-binaries.
+const MaxEntryBytes int64 = 5 * 1024 * 1024
+
+// Entry is a single file ready to be written into a target directory.
+// RelPath uses forward slashes regardless of host OS — agentctl converts
+// per-platform on write.
+type Entry struct {
+ RelPath string `json:"rel_path"`
+ Mode os.FileMode `json:"mode"`
+ Content []byte `json:"content"`
+}
+
+// Parse splits a comma-separated user spec into trimmed, deduplicated,
+// non-empty patterns. Order is preserved (first occurrence wins on dedupe).
+func Parse(spec string) []string {
+ if spec == "" {
+ return nil
+ }
+ parts := strings.Split(spec, ",")
+ out := make([]string, 0, len(parts))
+ seen := make(map[string]struct{}, len(parts))
+ for _, p := range parts {
+ p = strings.TrimSpace(p)
+ if p == "" {
+ continue
+ }
+ if _, ok := seen[p]; ok {
+ continue
+ }
+ seen[p] = struct{}{}
+ out = append(out, p)
+ }
+ if len(out) == 0 {
+ return nil
+ }
+ return out
+}
+
+// Copy resolves each pattern relative to sourceDir and copies matches into
+// targetDir, preserving relative paths. It returns the relative paths of
+// files newly written into targetDir (skip-if-exists matches are NOT
+// included), one warning per problematic pattern or rejected match, and an
+// error only for IO failures that would corrupt the target.
+func Copy(ctx context.Context, sourceDir, targetDir string, patterns []string, log *zap.Logger) ([]string, []string, error) {
+ if len(patterns) == 0 {
+ return nil, nil, nil
+ }
+ if err := ctx.Err(); err != nil {
+ return nil, nil, fmt.Errorf("copyfiles: %w", err)
+ }
+
+ canonRoot, err := filepath.EvalSymlinks(sourceDir)
+ if err != nil {
+ return nil, nil, fmt.Errorf("copyfiles: resolve source: %w", err)
+ }
+
+ state := ©State{
+ ctx: ctx,
+ targetDir: targetDir,
+ canonRoot: canonRoot,
+ log: log,
+ copied: make(map[string]struct{}),
+ }
+
+ for _, pattern := range patterns {
+ if err := ctx.Err(); err != nil {
+ return state.copiedRel, state.warnings, fmt.Errorf("copyfiles: %w", err)
+ }
+ if err := state.expandPattern(pattern); err != nil {
+ return state.copiedRel, state.warnings, err
+ }
+ }
+ return state.copiedRel, state.warnings, nil
+}
+
+type copyState struct {
+ ctx context.Context
+ targetDir string
+ canonRoot string
+ log *zap.Logger
+ copied map[string]struct{}
+ copiedRel []string
+ warnings []string
+
+ // planMode collects file payloads into entries instead of writing to
+ // targetDir. Set by Plan(). When true, copyFile reads bytes into memory
+ // (respecting MaxEntryBytes) and appends to entries rather than touching
+ // the filesystem.
+ planMode bool
+ entries []Entry
+}
+
+// Plan resolves each pattern relative to sourceDir and reads every match
+// into memory as an Entry — without touching any target filesystem. It is
+// the read half of a remote copy: the agentctl HTTP client ships the
+// returned entries across the wire, and WriteEntries writes them on the
+// receiving side. Files larger than MaxEntryBytes emit a warning and are
+// skipped to keep launch payloads bounded.
+//
+// Returned entries preserve forward-slash relative paths; consumers must
+// not assume host-native separators.
+func Plan(ctx context.Context, sourceDir string, patterns []string, log *zap.Logger) ([]Entry, []string, error) {
+ if len(patterns) == 0 {
+ return nil, nil, nil
+ }
+ if err := ctx.Err(); err != nil {
+ return nil, nil, fmt.Errorf("copyfiles: %w", err)
+ }
+
+ canonRoot, err := filepath.EvalSymlinks(sourceDir)
+ if err != nil {
+ return nil, nil, fmt.Errorf("copyfiles: resolve source: %w", err)
+ }
+
+ state := ©State{
+ ctx: ctx,
+ canonRoot: canonRoot,
+ log: log,
+ copied: make(map[string]struct{}),
+ planMode: true,
+ }
+
+ for _, pattern := range patterns {
+ if err := ctx.Err(); err != nil {
+ return state.entries, state.warnings, fmt.Errorf("copyfiles: %w", err)
+ }
+ if err := state.expandPattern(pattern); err != nil {
+ return state.entries, state.warnings, err
+ }
+ }
+ return state.entries, state.warnings, nil
+}
+
+// WriteEntries writes a pre-planned batch into targetDir, preserving
+// relative paths and file modes. Idempotent: entries whose destination
+// already exists are silently skipped (matches Copy's resume semantics).
+// Returns the list of newly-written relative paths plus per-entry
+// warnings; an error only for IO failures that would corrupt the target.
+//
+// Per-entry RelPath is treated as user-controlled — each is rejected
+// unless it canonicalizes to a path strictly inside targetDir. This is
+// the agentctl-side guard: the planner already validates against the
+// source root, but a compromised sender could craft paths that escape
+// the target.
+func WriteEntries(ctx context.Context, containmentRoot, targetDir string, entries []Entry, log *zap.Logger) ([]string, []string, error) {
+ if len(entries) == 0 {
+ return nil, nil, nil
+ }
+ if err := ctx.Err(); err != nil {
+ return nil, nil, fmt.Errorf("copyfiles: %w", err)
+ }
+ // Explicit containment check: targetDir must lie inside containmentRoot
+ // after both are canonicalized via EvalSymlinks. Gives the WriteEntries
+ // surface a machine-checkable trust boundary — callers pass the workspace
+ // root they control plus a candidate subdir, and any target that escapes
+ // the root is rejected before any filesystem sink (os.Stat, os.WriteFile).
+ canonRoot, err := filepath.EvalSymlinks(containmentRoot)
+ if err != nil {
+ return nil, nil, fmt.Errorf("copyfiles: resolve containment root: %w", err)
+ }
+ canonTarget, err := filepath.EvalSymlinks(targetDir)
+ if err != nil {
+ return nil, nil, fmt.Errorf("copyfiles: resolve target: %w", err)
+ }
+ if !pathInsideRoot(canonTarget, canonRoot) {
+ return nil, nil, fmt.Errorf("copyfiles: target %q outside containment root %q", canonTarget, canonRoot)
+ }
+ info, err := os.Stat(canonTarget)
+ if err != nil || !info.IsDir() {
+ return nil, nil, fmt.Errorf("copyfiles: target %q is not a directory", canonTarget)
+ }
+ absTarget := canonTarget
+
+ var copied, warnings []string
+ for _, e := range entries {
+ if err := ctx.Err(); err != nil {
+ return copied, warnings, fmt.Errorf("copyfiles: %w", err)
+ }
+ written, warn, err := writeOneEntry(absTarget, e, log)
+ if warn != "" {
+ warnings = append(warnings, warn)
+ }
+ if err != nil {
+ return copied, warnings, err
+ }
+ if written {
+ copied = append(copied, filepath.ToSlash(e.RelPath))
+ }
+ }
+ return copied, warnings, nil
+}
+
+// writeOneEntry validates a single Entry, refusing paths that escape
+// targetDir, then writes it (skip-if-exists for idempotency). Resolves
+// symlinks on the destination's parent directory so a pre-existing
+// `config -> /etc` symlink in the target can't smuggle the write
+// outside absTarget.
+func writeOneEntry(absTarget string, e Entry, log *zap.Logger) (written bool, warning string, err error) {
+ rel := filepath.FromSlash(e.RelPath)
+ if rel == "" {
+ return false, "rejected empty path", nil
+ }
+ if filepath.IsAbs(rel) {
+ return false, fmt.Sprintf("rejected absolute path %q", e.RelPath), nil
+ }
+ cleanDst, warn, err := secureDestination(absTarget, rel)
+ if err != nil {
+ return false, "", err
+ }
+ if warn != "" {
+ return false, warn, nil
+ }
+ if _, err := os.Lstat(cleanDst); err == nil {
+ if log != nil {
+ log.Debug("copyfiles: skip existing", zap.String("rel", e.RelPath))
+ }
+ return false, "", nil
+ }
+ mode := e.Mode.Perm()
+ if mode == 0 {
+ mode = 0o644
+ }
+ if err := os.WriteFile(cleanDst, e.Content, mode); err != nil {
+ // Best-effort cleanup so a half-written file doesn't poison the
+ // next idempotent run's skip-if-exists branch (the streaming
+ // copyFile path does the same). Ignore unlink failure.
+ _ = os.Remove(cleanDst)
+ return false, "", fmt.Errorf("copyfiles: write %s: %w", cleanDst, err)
+ }
+ if log != nil {
+ log.Debug("copyfiles: wrote entry", zap.String("rel", e.RelPath))
+ }
+ return true, "", nil
+}
+
+// pathInsideRoot reports whether candidate (already cleaned via
+// EvalSymlinks) sits at or below root. Used as the CodeQL-recognized
+// path-injection sanitizer at the WriteEntries entry point: both
+// arguments must already be canonical (no symlinks, no "..").
+func pathInsideRoot(candidate, root string) bool {
+ if candidate == root {
+ return true
+ }
+ rel, err := filepath.Rel(root, candidate)
+ if err != nil {
+ return false
+ }
+ if rel == "." {
+ return true
+ }
+ if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+ return false
+ }
+ return true
+}
+
+// secureDestination resolves the destination path for a relative entry,
+// creating parent directories only after every existing component along
+// the chain has been verified to be a regular directory (not a symlink).
+// Returns:
+//
+// - (cleanDst, "", nil) on success — safe to write.
+// - ("", warn, nil) when the path is rejected (warn surfaced to caller).
+// - ("", "", err) only on mkdir IO failure — fatal for the batch.
+//
+// Two-step validation closes the symlink-target-escape vector: a
+// pre-existing component like `config -> /etc` would cause MkdirAll to
+// silently create directories at /etc/... because Go's MkdirAll follows
+// symlinks via Stat. validateParentChain refuses to proceed if any
+// existing component is a symlink, and a final EvalSymlinks check on
+// the parent re-confirms containment after the dirs are created.
+func secureDestination(absTarget, rel string) (cleanDst, warning string, err error) {
+ lexical := filepath.Join(absTarget, rel)
+ cleanDst, absErr := filepath.Abs(lexical)
+ if absErr != nil {
+ return "", fmt.Sprintf("rejected %q: %v", rel, absErr), nil
+ }
+ if relCheck, relErr := filepath.Rel(absTarget, cleanDst); relErr != nil ||
+ relCheck == ".." ||
+ strings.HasPrefix(relCheck, ".."+string(filepath.Separator)) {
+ return "", fmt.Sprintf("rejected %q: escapes target", rel), nil
+ }
+ parent := filepath.Dir(cleanDst)
+ if warn, ok := validateParentChain(absTarget, parent); !ok {
+ return "", fmt.Sprintf("rejected %q: %s", rel, warn), nil
+ }
+ if err := os.MkdirAll(parent, 0o755); err != nil {
+ return "", "", fmt.Errorf("copyfiles: mkdir %s: %w", parent, err)
+ }
+ canonParent, evalErr := filepath.EvalSymlinks(parent)
+ if evalErr != nil {
+ return "", fmt.Sprintf("rejected %q: parent resolve failed: %v", rel, evalErr), nil
+ }
+ final := filepath.Join(canonParent, filepath.Base(cleanDst))
+ if relCheck, relErr := filepath.Rel(absTarget, final); relErr != nil ||
+ relCheck == ".." ||
+ strings.HasPrefix(relCheck, ".."+string(filepath.Separator)) {
+ return "", fmt.Sprintf("rejected %q: symlink in parent escapes target", rel), nil
+ }
+ return final, "", nil
+}
+
+// validateParentChain walks from absTarget down to parent (the directory
+// that will host the final file). For every existing component, if it
+// is a symlink the function refuses by returning ok=false plus a human
+// warning. Non-existent components are fine — MkdirAll will create
+// them. Skipping symlinks is intentional: it gives a simple,
+// machine-checkable guarantee that no subsequent MkdirAll call can
+// reach a directory outside absTarget through a pre-planted symlink.
+func validateParentChain(absTarget, parent string) (warning string, ok bool) {
+ rel, err := filepath.Rel(absTarget, parent)
+ if err != nil {
+ return fmt.Sprintf("rel %q: %v", parent, err), false
+ }
+ if rel == "." || rel == "" {
+ return "", true
+ }
+ cur := absTarget
+ for _, part := range strings.Split(rel, string(filepath.Separator)) {
+ cur = filepath.Join(cur, part)
+ info, lerr := os.Lstat(cur)
+ if lerr != nil {
+ // Doesn't exist yet — MkdirAll handles the tail safely from here.
+ return "", true
+ }
+ if info.Mode()&os.ModeSymlink != 0 {
+ return fmt.Sprintf("symlink in parent path at %q", cur), false
+ }
+ }
+ return "", true
+}
+
+func (s *copyState) warn(format string, args ...any) {
+ msg := fmt.Sprintf(format, args...)
+ s.warnings = append(s.warnings, msg)
+ if s.log != nil {
+ s.log.Warn("copyfiles: " + msg)
+ }
+}
+
+func (s *copyState) debug(msg string, fields ...zap.Field) {
+ if s.log != nil {
+ s.log.Debug("copyfiles: "+msg, fields...)
+ }
+}
+
+// expandPattern handles literal files, literal directories, and globs.
+func (s *copyState) expandPattern(pattern string) error {
+ joined := pattern
+ if !filepath.IsAbs(pattern) {
+ joined = filepath.Join(s.canonRoot, pattern)
+ }
+
+ // Fast path: literal existing entry.
+ if _, err := os.Lstat(joined); err == nil {
+ return s.handleMatch(joined, pattern)
+ }
+
+ matches, err := filepath.Glob(joined)
+ if err != nil {
+ s.warn("invalid pattern %q: %v", pattern, err)
+ return nil
+ }
+ if len(matches) == 0 {
+ s.warn("no matches for pattern %q", pattern)
+ return nil
+ }
+ for _, m := range matches {
+ if err := s.ctx.Err(); err != nil {
+ return fmt.Errorf("copyfiles: %w", err)
+ }
+ if _, err := os.Lstat(m); err != nil {
+ s.warn("stat %q: %v", m, err)
+ continue
+ }
+ if err := s.handleMatch(m, pattern); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
+// handleMatch dispatches a single literal/match path to file or directory copy.
+func (s *copyState) handleMatch(matchPath, pattern string) error {
+ safe, ok := s.safePath(matchPath)
+ if !ok {
+ s.warn("path %q is outside source dir (pattern %q)", matchPath, pattern)
+ return nil
+ }
+
+ // Resolve via EvalSymlinks for the actual final target (follows symlinks).
+ resolved, err := filepath.EvalSymlinks(safe)
+ if err != nil {
+ s.warn("resolve %q: %v", matchPath, err)
+ return nil
+ }
+ if !s.underRoot(resolved) {
+ s.warn("symlink %q resolves outside source dir", matchPath)
+ return nil
+ }
+
+ // Use the original match path to compute the relative dest, NOT the
+ // resolved path — a symlink should land at the symlink's location.
+ rel, err := filepath.Rel(s.canonRoot, safe)
+ if err != nil {
+ s.warn("rel %q: %v", matchPath, err)
+ return nil
+ }
+
+ rInfo, err := os.Stat(resolved)
+ if err != nil {
+ s.warn("stat resolved %q: %v", resolved, err)
+ return nil
+ }
+
+ if rInfo.IsDir() {
+ return s.copyDir(resolved, rel)
+ }
+ return s.copyFile(resolved, rel, rInfo)
+}
+
+// copyDir walks src recursively and copies every regular file inside.
+func (s *copyState) copyDir(src, relRoot string) error {
+ return filepath.WalkDir(src, func(path string, d fs.DirEntry, walkErr error) error {
+ if walkErr != nil {
+ s.warn("walk %q: %v", path, walkErr)
+ return nil
+ }
+ if err := s.ctx.Err(); err != nil {
+ return err
+ }
+ if d.IsDir() {
+ return nil
+ }
+ info, err := d.Info()
+ if err != nil {
+ s.warn("info %q: %v", path, err)
+ return nil
+ }
+ rel, err := filepath.Rel(src, path)
+ if err != nil {
+ s.warn("rel %q: %v", path, err)
+ return nil
+ }
+ // If the entry is itself a symlink, resolve and validate it stays in root.
+ resolved := path
+ if info.Mode()&os.ModeSymlink != 0 {
+ r, rerr := filepath.EvalSymlinks(path)
+ if rerr != nil {
+ s.warn("resolve %q: %v", path, rerr)
+ return nil
+ }
+ if !s.underRoot(r) {
+ s.warn("symlink %q resolves outside source dir", path)
+ return nil
+ }
+ ri, rerr := os.Stat(r)
+ if rerr != nil {
+ s.warn("stat %q: %v", r, rerr)
+ return nil
+ }
+ if ri.IsDir() {
+ s.warn("symlink %q resolves to a directory, skipping", path)
+ return nil
+ }
+ info = ri
+ resolved = r
+ }
+ return s.copyFile(resolved, filepath.Join(relRoot, rel), info)
+ })
+}
+
+// copyFile copies a single regular file to targetDir/rel, creating parents.
+// In planMode it instead reads the file's bytes into an Entry (subject to
+// MaxEntryBytes), used by Plan() for the remote-executor path.
+func (s *copyState) copyFile(src, rel string, info os.FileInfo) error {
+ if err := s.ctx.Err(); err != nil {
+ return fmt.Errorf("copyfiles: %w", err)
+ }
+ if !info.Mode().IsRegular() {
+ s.warn("skipping non-regular file %q (mode %s)", rel, info.Mode())
+ return nil
+ }
+ if s.planMode {
+ return s.planFile(src, rel, info)
+ }
+ dst := filepath.Join(s.targetDir, rel)
+ if _, dup := s.copied[dst]; dup {
+ return nil
+ }
+
+ // Skip-if-exists for idempotency on resume.
+ if _, err := os.Lstat(dst); err == nil {
+ s.copied[dst] = struct{}{}
+ s.debug("skip existing", zap.String("rel", rel))
+ return nil
+ }
+
+ if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+ return fmt.Errorf("copyfiles: mkdir %s: %w", filepath.Dir(dst), err)
+ }
+
+ in, err := os.Open(src)
+ if err != nil {
+ s.warn("open %q: %v", src, err)
+ return nil
+ }
+ defer func() { _ = in.Close() }()
+
+ out, err := os.Create(dst)
+ if err != nil {
+ return fmt.Errorf("copyfiles: create %s: %w", dst, err)
+ }
+ if _, err := io.Copy(out, in); err != nil {
+ _ = out.Close()
+ _ = os.Remove(dst)
+ return fmt.Errorf("copyfiles: copy %s: %w", dst, err)
+ }
+ if err := out.Close(); err != nil {
+ _ = os.Remove(dst)
+ return fmt.Errorf("copyfiles: close %s: %w", dst, err)
+ }
+ if err := os.Chmod(dst, info.Mode().Perm()); err != nil {
+ return fmt.Errorf("copyfiles: chmod %s: %w", dst, err)
+ }
+
+ s.copied[dst] = struct{}{}
+ s.copiedRel = append(s.copiedRel, filepath.ToSlash(rel))
+ s.debug("copied", zap.String("rel", rel))
+ return nil
+}
+
+// planFile reads a source file into an in-memory Entry instead of writing
+// it. Files larger than MaxEntryBytes are skipped with a warning; users
+// who hit this are typically pattern-matching too broadly (e.g. catching
+// node_modules) and want feedback, not a silent partial copy.
+func (s *copyState) planFile(src, rel string, info os.FileInfo) error {
+ dedup := filepath.ToSlash(rel)
+ if _, dup := s.copied[dedup]; dup {
+ return nil
+ }
+ if info.Size() > MaxEntryBytes {
+ s.warn("skipping %q: %d bytes exceeds %d-byte plan cap", rel, info.Size(), MaxEntryBytes)
+ return nil
+ }
+ f, err := os.Open(src)
+ if err != nil {
+ s.warn("open %q: %v", src, err)
+ return nil
+ }
+ defer func() { _ = f.Close() }()
+ // LimitReader as belt-and-suspenders against TOCTOU growth between Stat
+ // and Read — a file appended-to mid-walk shouldn't bypass MaxEntryBytes.
+ content, err := io.ReadAll(io.LimitReader(f, MaxEntryBytes+1))
+ if err != nil {
+ s.warn("read %q: %v", src, err)
+ return nil
+ }
+ if int64(len(content)) > MaxEntryBytes {
+ s.warn("skipping %q: read exceeded %d-byte plan cap", rel, MaxEntryBytes)
+ return nil
+ }
+ s.copied[dedup] = struct{}{}
+ s.entries = append(s.entries, Entry{
+ RelPath: filepath.ToSlash(rel),
+ Mode: info.Mode().Perm(),
+ Content: content,
+ })
+ s.copiedRel = append(s.copiedRel, filepath.ToSlash(rel))
+ s.debug("planned", zap.String("rel", rel))
+ return nil
+}
+
+// safePath returns the lexically-cleaned absolute path within sourceDir, or
+// false if the path escapes the source root before any symlink resolution.
+func (s *copyState) safePath(p string) (string, bool) {
+ abs := p
+ if !filepath.IsAbs(abs) {
+ abs = filepath.Join(s.canonRoot, abs)
+ }
+ abs = filepath.Clean(abs)
+ if !s.underRoot(abs) {
+ return "", false
+ }
+ return abs, true
+}
+
+// underRoot reports whether path is canonRoot itself or lies inside canonRoot.
+func (s *copyState) underRoot(path string) bool {
+ rel, err := filepath.Rel(s.canonRoot, path)
+ if err != nil {
+ return false
+ }
+ if rel == "." {
+ return true
+ }
+ if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+ return false
+ }
+ return true
+}
diff --git a/apps/backend/internal/worktree/copyfiles/copyfiles_test.go b/apps/backend/internal/worktree/copyfiles/copyfiles_test.go
new file mode 100644
index 0000000000..a9f5fef2f5
--- /dev/null
+++ b/apps/backend/internal/worktree/copyfiles/copyfiles_test.go
@@ -0,0 +1,682 @@
+package copyfiles
+
+import (
+ "context"
+ "errors"
+ "os"
+ "path/filepath"
+ "reflect"
+ "runtime"
+ "strings"
+ "testing"
+)
+
+func TestParse(t *testing.T) {
+ t.Parallel()
+
+ cases := []struct {
+ name string
+ in string
+ want []string
+ }{
+ {"empty", "", nil},
+ {"only comma", ",", nil},
+ {"single trimmed", " .env ", []string{".env"}},
+ {"two", ".env,.env.local", []string{".env", ".env.local"}},
+ {"dedupe", ".env, .env, .env.local", []string{".env", ".env.local"}},
+ {"empties dropped", " .env , , .env.local ", []string{".env", ".env.local"}},
+ }
+
+ for _, tc := range cases {
+ tc := tc
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+ got := Parse(tc.in)
+ if len(got) == 0 && len(tc.want) == 0 {
+ return
+ }
+ if !reflect.DeepEqual(got, tc.want) {
+ t.Fatalf("Parse(%q) = %#v, want %#v", tc.in, got, tc.want)
+ }
+ })
+ }
+}
+
+func writeFile(t *testing.T, path, content string, mode os.FileMode) {
+ t.Helper()
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ t.Fatalf("mkdir parent: %v", err)
+ }
+ if err := os.WriteFile(path, []byte(content), mode); err != nil {
+ t.Fatalf("write %s: %v", path, err)
+ }
+ // WriteFile honors umask; force exact mode for predictable tests.
+ if err := os.Chmod(path, mode); err != nil {
+ t.Fatalf("chmod %s: %v", path, err)
+ }
+}
+
+func readFile(t *testing.T, path string) string {
+ t.Helper()
+ b, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read %s: %v", path, err)
+ }
+ return string(b)
+}
+
+func TestCopy_LiteralFile(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, ".env"), "X=1", 0o600)
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{".env"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("unexpected warnings: %v", warnings)
+ }
+
+ got := readFile(t, filepath.Join(dst, ".env"))
+ if got != "X=1" {
+ t.Fatalf("content = %q, want %q", got, "X=1")
+ }
+
+ info, err := os.Stat(filepath.Join(dst, ".env"))
+ if err != nil {
+ t.Fatalf("stat: %v", err)
+ }
+ if info.Mode().Perm() != 0o600 {
+ t.Fatalf("mode = %v, want 0o600", info.Mode().Perm())
+ }
+}
+
+func TestCopy_Glob(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, "a.local"), "A", 0o644)
+ writeFile(t, filepath.Join(src, "b.local"), "B", 0o644)
+ writeFile(t, filepath.Join(src, "c.txt"), "C", 0o644)
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{"*.local"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("warnings: %v", warnings)
+ }
+ if readFile(t, filepath.Join(dst, "a.local")) != "A" {
+ t.Fatalf("a.local missing or wrong")
+ }
+ if readFile(t, filepath.Join(dst, "b.local")) != "B" {
+ t.Fatalf("b.local missing or wrong")
+ }
+ if _, err := os.Stat(filepath.Join(dst, "c.txt")); !os.IsNotExist(err) {
+ t.Fatalf("c.txt should not exist, err=%v", err)
+ }
+}
+
+func TestCopy_DirectoryRecursive(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, "config", "local.yml"), "y", 0o644)
+ writeFile(t, filepath.Join(src, "config", "sub", "dev.json"), "j", 0o644)
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{"config"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("warnings: %v", warnings)
+ }
+ if readFile(t, filepath.Join(dst, "config", "local.yml")) != "y" {
+ t.Fatalf("local.yml missing")
+ }
+ if readFile(t, filepath.Join(dst, "config", "sub", "dev.json")) != "j" {
+ t.Fatalf("sub/dev.json missing")
+ }
+}
+
+func TestCopy_NestedFile(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, "config", "local.yml"), "y", 0o644)
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{"config/local.yml"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("warnings: %v", warnings)
+ }
+ if readFile(t, filepath.Join(dst, "config", "local.yml")) != "y" {
+ t.Fatalf("nested file not copied")
+ }
+}
+
+func TestCopy_MissingPattern(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{".env"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 1 {
+ t.Fatalf("warnings = %v, want 1", warnings)
+ }
+ if !strings.Contains(warnings[0], ".env") {
+ t.Fatalf("warning does not mention .env: %q", warnings[0])
+ }
+ entries, _ := os.ReadDir(dst)
+ if len(entries) != 0 {
+ t.Fatalf("dst not empty: %v", entries)
+ }
+}
+
+func TestCopy_GlobNoMatch(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, "foo.txt"), "foo", 0o644)
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{"*.local"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 1 {
+ t.Fatalf("warnings = %v, want 1", warnings)
+ }
+}
+
+func TestCopy_PathTraversal_Relative(t *testing.T) {
+ t.Parallel()
+ parent := t.TempDir()
+ src := filepath.Join(parent, "src")
+ if err := os.Mkdir(src, 0o755); err != nil {
+ t.Fatalf("mkdir src: %v", err)
+ }
+ dst := t.TempDir()
+
+ // Create a file outside src
+ writeFile(t, filepath.Join(parent, "escape.txt"), "leak", 0o644)
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{"../escape.txt"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) == 0 {
+ t.Fatalf("expected warning for traversal")
+ }
+ if _, err := os.Stat(filepath.Join(dst, "escape.txt")); !os.IsNotExist(err) {
+ t.Fatalf("escape.txt should not be copied")
+ }
+ entries, _ := os.ReadDir(dst)
+ if len(entries) != 0 {
+ t.Fatalf("dst not empty: %v", entries)
+ }
+}
+
+func TestCopy_PathTraversal_Absolute(t *testing.T) {
+ t.Parallel()
+ parent := t.TempDir()
+ src := filepath.Join(parent, "src")
+ if err := os.Mkdir(src, 0o755); err != nil {
+ t.Fatalf("mkdir src: %v", err)
+ }
+ dst := t.TempDir()
+
+ outside := filepath.Join(parent, "abs_escape.txt")
+ writeFile(t, outside, "leak", 0o644)
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{outside}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) == 0 {
+ t.Fatalf("expected warning for absolute traversal")
+ }
+ entries, _ := os.ReadDir(dst)
+ if len(entries) != 0 {
+ t.Fatalf("dst not empty: %v", entries)
+ }
+}
+
+func TestCopy_SymlinkInside(t *testing.T) {
+ t.Parallel()
+ if runtime.GOOS == "windows" {
+ t.Skip("symlink creation often requires privilege on Windows")
+ }
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, "real.env"), "REAL=1", 0o644)
+ if err := os.Symlink("real.env", filepath.Join(src, ".env")); err != nil {
+ t.Skipf("symlink unsupported: %v", err)
+ }
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{".env"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("warnings: %v", warnings)
+ }
+ got := readFile(t, filepath.Join(dst, ".env"))
+ if got != "REAL=1" {
+ t.Fatalf("content = %q, want REAL=1", got)
+ }
+
+ // Confirm target is a regular file, not a symlink
+ info, err := os.Lstat(filepath.Join(dst, ".env"))
+ if err != nil {
+ t.Fatalf("lstat: %v", err)
+ }
+ if info.Mode()&os.ModeSymlink != 0 {
+ t.Fatalf("target is symlink, want regular file")
+ }
+}
+
+func TestCopy_SymlinkOutside(t *testing.T) {
+ t.Parallel()
+ if runtime.GOOS == "windows" {
+ t.Skip("symlink creation often requires privilege on Windows")
+ }
+ parent := t.TempDir()
+ src := filepath.Join(parent, "src")
+ if err := os.Mkdir(src, 0o755); err != nil {
+ t.Fatalf("mkdir src: %v", err)
+ }
+ dst := t.TempDir()
+
+ outside := filepath.Join(parent, "secret.txt")
+ writeFile(t, outside, "SECRET", 0o644)
+
+ if err := os.Symlink(outside, filepath.Join(src, "leak")); err != nil {
+ t.Skipf("symlink unsupported: %v", err)
+ }
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{"leak"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) == 0 {
+ t.Fatalf("expected warning for symlink escaping src")
+ }
+ if _, err := os.Stat(filepath.Join(dst, "leak")); !os.IsNotExist(err) {
+ t.Fatalf("leak should not be copied")
+ }
+}
+
+func TestCopy_Idempotent(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, ".env"), "SRC", 0o644)
+ writeFile(t, filepath.Join(dst, ".env"), "DST_ORIGINAL", 0o644)
+
+ _, warnings, err := Copy(context.Background(), src, dst, []string{".env"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("warnings: %v", warnings)
+ }
+ got := readFile(t, filepath.Join(dst, ".env"))
+ if got != "DST_ORIGINAL" {
+ t.Fatalf("content = %q, want DST_ORIGINAL (existing file should not be overwritten)", got)
+ }
+}
+
+func TestCopy_EmptyPatterns(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ for _, patterns := range [][]string{nil, {}} {
+ _, warnings, err := Copy(context.Background(), src, dst, patterns, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("warnings: %v", warnings)
+ }
+ }
+}
+
+func TestCopy_NilLogger(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, ".env"), "X", 0o644)
+
+ defer func() {
+ if r := recover(); r != nil {
+ t.Fatalf("panic with nil logger: %v", r)
+ }
+ }()
+
+ if _, _, err := Copy(context.Background(), src, dst, []string{".env"}, nil); err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+}
+
+func TestCopy_SymlinkedSourceDir(t *testing.T) {
+ t.Parallel()
+ if runtime.GOOS == "windows" {
+ t.Skip("symlink permission/semantics differ on Windows")
+ }
+ realDir := t.TempDir()
+ linkedDir := filepath.Join(t.TempDir(), "linked")
+ if err := os.Symlink(realDir, linkedDir); err != nil {
+ t.Skipf("symlinks unsupported: %v", err)
+ }
+ writeFile(t, filepath.Join(realDir, ".env"), "X=1", 0o600)
+
+ target := t.TempDir()
+ _, warnings, err := Copy(context.Background(), linkedDir, target, []string{".env"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("should not reject symlinked source dir, warnings: %v", warnings)
+ }
+ got := readFile(t, filepath.Join(target, ".env"))
+ if got != "X=1" {
+ t.Fatalf("content = %q, want %q", got, "X=1")
+ }
+}
+
+func TestCopy_MissingSourceDir(t *testing.T) {
+ t.Parallel()
+ _, _, err := Copy(context.Background(), "/nonexistent-dir-xyz", t.TempDir(), []string{".env"}, nil)
+ if err == nil {
+ t.Fatalf("expected error for missing source dir")
+ }
+}
+
+func TestCopy_ContextCancelled(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, ".env"), "X", 0o644)
+
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel()
+
+ _, _, err := Copy(ctx, src, dst, []string{".env"}, nil)
+ if err == nil {
+ t.Fatalf("expected error from cancelled context")
+ }
+ if !errors.Is(err, context.Canceled) {
+ t.Fatalf("err = %v, want wrapping context.Canceled", err)
+ }
+ if _, statErr := os.Stat(filepath.Join(dst, ".env")); !os.IsNotExist(statErr) {
+ t.Fatalf("file should not be copied when ctx cancelled, statErr=%v", statErr)
+ }
+}
+
+func TestPlan_HappyPath(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+
+ writeFile(t, filepath.Join(src, ".env"), "X=1", 0o600)
+ writeFile(t, filepath.Join(src, "config", "local.yml"), "y", 0o644)
+
+ entries, warnings, err := Plan(context.Background(), src,
+ []string{".env", "config"}, nil)
+ if err != nil {
+ t.Fatalf("Plan err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("unexpected warnings: %v", warnings)
+ }
+ got := map[string]Entry{}
+ for _, e := range entries {
+ got[e.RelPath] = e
+ }
+ if string(got[".env"].Content) != "X=1" {
+ t.Errorf(".env content = %q, want %q", got[".env"].Content, "X=1")
+ }
+ if got[".env"].Mode.Perm() != 0o600 {
+ t.Errorf(".env mode = %v, want 0o600", got[".env"].Mode.Perm())
+ }
+ if string(got["config/local.yml"].Content) != "y" {
+ t.Errorf("config/local.yml content = %q, want %q", got["config/local.yml"].Content, "y")
+ }
+}
+
+func TestPlan_OversizedFileSkipped(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+
+ // Write a payload exceeding MaxEntryBytes (5MB). Use a sparse-ish
+ // buffer to avoid stressing the test runner's RAM.
+ huge := make([]byte, MaxEntryBytes+1)
+ writeFile(t, filepath.Join(src, "big.bin"), string(huge), 0o644)
+ writeFile(t, filepath.Join(src, ".env"), "OK=1", 0o644)
+
+ entries, warnings, err := Plan(context.Background(), src,
+ []string{"big.bin", ".env"}, nil)
+ if err != nil {
+ t.Fatalf("Plan err: %v", err)
+ }
+ if len(entries) != 1 || entries[0].RelPath != ".env" {
+ t.Fatalf("entries = %+v, expected just .env", entries)
+ }
+ foundCapWarning := false
+ for _, w := range warnings {
+ if strings.Contains(w, "big.bin") && strings.Contains(w, "cap") {
+ foundCapWarning = true
+ }
+ }
+ if !foundCapWarning {
+ t.Fatalf("expected cap warning for big.bin, got %v", warnings)
+ }
+}
+
+func TestPlan_PathTraversalRejected(t *testing.T) {
+ t.Parallel()
+ parent := t.TempDir()
+ src := filepath.Join(parent, "src")
+ if err := os.Mkdir(src, 0o755); err != nil {
+ t.Fatalf("mkdir: %v", err)
+ }
+ writeFile(t, filepath.Join(parent, "escape.txt"), "leak", 0o644)
+
+ entries, warnings, err := Plan(context.Background(), src,
+ []string{"../escape.txt"}, nil)
+ if err != nil {
+ t.Fatalf("Plan err: %v", err)
+ }
+ if len(entries) != 0 {
+ t.Fatalf("expected zero entries for traversal, got %+v", entries)
+ }
+ if len(warnings) == 0 {
+ t.Fatal("expected warning for traversal")
+ }
+}
+
+func TestWriteEntries_HappyPath(t *testing.T) {
+ t.Parallel()
+ dst := t.TempDir()
+
+ entries := []Entry{
+ {RelPath: ".env", Mode: 0o600, Content: []byte("X=1")},
+ {RelPath: "config/local.yml", Mode: 0o644, Content: []byte("y")},
+ }
+
+ copied, warnings, err := WriteEntries(context.Background(), dst, dst, entries, nil)
+ if err != nil {
+ t.Fatalf("WriteEntries err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("unexpected warnings: %v", warnings)
+ }
+ if len(copied) != 2 {
+ t.Fatalf("copied = %v, want 2 entries", copied)
+ }
+ if got := readFile(t, filepath.Join(dst, ".env")); got != "X=1" {
+ t.Errorf(".env content = %q", got)
+ }
+ info, err := os.Stat(filepath.Join(dst, ".env"))
+ if err != nil {
+ t.Fatalf("stat: %v", err)
+ }
+ if info.Mode().Perm() != 0o600 {
+ t.Errorf(".env mode = %v, want 0o600", info.Mode().Perm())
+ }
+}
+
+func TestWriteEntries_SkipIfExists(t *testing.T) {
+ t.Parallel()
+ dst := t.TempDir()
+ writeFile(t, filepath.Join(dst, ".env"), "PREEXISTING", 0o644)
+
+ copied, _, err := WriteEntries(context.Background(), dst, dst,
+ []Entry{{RelPath: ".env", Mode: 0o600, Content: []byte("NEW")}}, nil)
+ if err != nil {
+ t.Fatalf("WriteEntries err: %v", err)
+ }
+ if len(copied) != 0 {
+ t.Errorf("copied = %v, want empty (skip-if-exists)", copied)
+ }
+ if got := readFile(t, filepath.Join(dst, ".env")); got != "PREEXISTING" {
+ t.Errorf("existing file overwritten: %q", got)
+ }
+}
+
+func TestWriteEntries_RejectsTargetOutsideContainmentRoot(t *testing.T) {
+ t.Parallel()
+ root := t.TempDir()
+ outside := t.TempDir() // sibling tmpdir, NOT under root
+
+ _, _, err := WriteEntries(context.Background(), root, outside,
+ []Entry{{RelPath: ".env", Mode: 0o600, Content: []byte("X")}}, nil)
+ if err == nil {
+ t.Fatal("expected error when target lies outside containment root")
+ }
+ if !strings.Contains(err.Error(), "outside containment root") {
+ t.Errorf("err = %v, want containment-root rejection", err)
+ }
+}
+
+func TestWriteEntries_RejectsSymlinkedParentEscape(t *testing.T) {
+ t.Parallel()
+ if runtime.GOOS == "windows" {
+ t.Skip("symlink creation often requires privilege on Windows")
+ }
+
+ parent := t.TempDir()
+ dst := filepath.Join(parent, "dst")
+ if err := os.Mkdir(dst, 0o755); err != nil {
+ t.Fatalf("mkdir dst: %v", err)
+ }
+ outside := filepath.Join(parent, "outside")
+ if err := os.Mkdir(outside, 0o755); err != nil {
+ t.Fatalf("mkdir outside: %v", err)
+ }
+ // A pre-existing symlinked directory inside the target — `dst/config`
+ // points at a directory completely outside the target root. Writing
+ // `config/sneaky.txt` via lexical join lands at `outside/sneaky.txt`
+ // before the EvalSymlinks guard was added.
+ if err := os.Symlink(outside, filepath.Join(dst, "config")); err != nil {
+ t.Skipf("symlink unsupported: %v", err)
+ }
+
+ copied, warnings, err := WriteEntries(context.Background(), dst, dst,
+ []Entry{{RelPath: "config/sneaky.txt", Mode: 0o644, Content: []byte("PWN")}}, nil)
+ if err != nil {
+ t.Fatalf("WriteEntries err: %v", err)
+ }
+ if len(copied) != 0 {
+ t.Errorf("copied = %v, want zero (escape rejected)", copied)
+ }
+ if len(warnings) == 0 {
+ t.Error("expected warning for symlinked-parent escape")
+ }
+ if _, err := os.Stat(filepath.Join(outside, "sneaky.txt")); !os.IsNotExist(err) {
+ t.Errorf("sneaky.txt should NOT exist outside dst; stat err = %v", err)
+ }
+}
+
+func TestWriteEntries_RejectsTraversalEntries(t *testing.T) {
+ t.Parallel()
+ parent := t.TempDir()
+ dst := filepath.Join(parent, "dst")
+ if err := os.Mkdir(dst, 0o755); err != nil {
+ t.Fatalf("mkdir: %v", err)
+ }
+
+ bad := []Entry{
+ {RelPath: "../escape.txt", Mode: 0o644, Content: []byte("leak")},
+ {RelPath: "/etc/passwd", Mode: 0o644, Content: []byte("leak")},
+ {RelPath: "", Mode: 0o644, Content: []byte("x")},
+ }
+ copied, warnings, err := WriteEntries(context.Background(), dst, dst, bad, nil)
+ if err != nil {
+ t.Fatalf("WriteEntries err: %v", err)
+ }
+ if len(copied) != 0 {
+ t.Errorf("copied = %v, want zero (all rejected)", copied)
+ }
+ if len(warnings) != 3 {
+ t.Errorf("warnings = %v, want 3", warnings)
+ }
+ if _, err := os.Stat(filepath.Join(parent, "escape.txt")); !os.IsNotExist(err) {
+ t.Errorf("escape.txt should not exist outside dst")
+ }
+}
+
+func TestCopy_ReturnsCopiedRelPaths(t *testing.T) {
+ t.Parallel()
+ src := t.TempDir()
+ dst := t.TempDir()
+
+ writeFile(t, filepath.Join(src, ".env"), "X=1", 0o644)
+ writeFile(t, filepath.Join(src, "config", "local.yml"), "y", 0o644)
+ writeFile(t, filepath.Join(src, "config", "sub", "dev.json"), "j", 0o644)
+ // Pre-existing dst file should be skipped and NOT appear in copied.
+ writeFile(t, filepath.Join(src, "already.txt"), "src", 0o644)
+ writeFile(t, filepath.Join(dst, "already.txt"), "preexisting", 0o644)
+
+ copied, warnings, err := Copy(context.Background(), src, dst,
+ []string{".env", "config", "already.txt"}, nil)
+ if err != nil {
+ t.Fatalf("Copy err: %v", err)
+ }
+ if len(warnings) != 0 {
+ t.Fatalf("unexpected warnings: %v", warnings)
+ }
+
+ got := map[string]bool{}
+ for _, p := range copied {
+ got[p] = true
+ }
+ want := []string{".env", "config/local.yml", "config/sub/dev.json"}
+ for _, w := range want {
+ if !got[w] {
+ t.Errorf("expected copied list to contain %q, got %v", w, copied)
+ }
+ }
+ if got["already.txt"] {
+ t.Errorf("skip-if-exists entry should NOT appear in copied list, got %v", copied)
+ }
+ if len(copied) != len(want) {
+ t.Errorf("copied len = %d, want %d (list: %v)", len(copied), len(want), copied)
+ }
+}
diff --git a/apps/backend/internal/worktree/manager.go b/apps/backend/internal/worktree/manager.go
index 25159bc333..d7dce6920c 100644
--- a/apps/backend/internal/worktree/manager.go
+++ b/apps/backend/internal/worktree/manager.go
@@ -15,6 +15,7 @@ import (
"go.uber.org/zap"
"github.com/kandev/kandev/internal/common/logger"
+ "github.com/kandev/kandev/internal/worktree/copyfiles"
)
const (
@@ -396,6 +397,8 @@ func (m *Manager) createInTaskDir(ctx context.Context, req CreateRequest, baseRe
return nil, err
}
+ m.copyConfiguredFiles(ctx, req, wt)
+
if err := m.runWorktreeSetupScript(ctx, wt, req.RepositoryPath); err != nil {
return nil, err
}
@@ -1128,6 +1131,46 @@ func (m *Manager) removeWorktree(ctx context.Context, wt *Worktree, removeBranch
return nil
}
+// copyConfiguredFiles copies user-specified files from the source repo into
+// the freshly created worktree, recording the resulting file list and
+// warnings on wt for the env preparer to surface. Failures are logged but
+// never propagated — worktree creation must succeed even if file seeding
+// partially fails.
+func (m *Manager) copyConfiguredFiles(ctx context.Context, req CreateRequest, wt *Worktree) {
+ if m.repoProvider == nil || req.RepositoryID == "" {
+ return
+ }
+ repo, err := m.repoProvider.GetRepository(ctx, req.RepositoryID)
+ if err != nil {
+ m.logger.Warn("copy-files: failed to fetch repository",
+ zap.String("repository_id", req.RepositoryID),
+ zap.Error(err))
+ return
+ }
+ if repo == nil || repo.CopyFiles == "" {
+ return
+ }
+ patterns := copyfiles.Parse(repo.CopyFiles)
+ if len(patterns) == 0 {
+ return
+ }
+ copied, warnings, err := copyfiles.Copy(ctx, req.RepositoryPath, wt.Path, patterns, m.logger.Zap())
+ if err != nil {
+ m.logger.Warn("worktree copy-files failed",
+ zap.String("session_id", req.SessionID),
+ zap.String("repo_id", req.RepositoryID),
+ zap.Error(err))
+ }
+ for _, w := range warnings {
+ m.logger.Warn("worktree copy-files warning",
+ zap.String("repo_id", req.RepositoryID),
+ zap.String("path", wt.Path),
+ zap.String("warning", w))
+ }
+ wt.CopiedFiles = copied
+ wt.CopyFilesWarnings = warnings
+}
+
func (m *Manager) runWorktreeSetupScript(ctx context.Context, wt *Worktree, repositoryPath string) error {
if m.scriptMsgHandler == nil || m.repoProvider == nil {
return nil
diff --git a/apps/backend/internal/worktree/manager_copyfiles_test.go b/apps/backend/internal/worktree/manager_copyfiles_test.go
new file mode 100644
index 0000000000..104103dc4f
--- /dev/null
+++ b/apps/backend/internal/worktree/manager_copyfiles_test.go
@@ -0,0 +1,195 @@
+package worktree
+
+import (
+ "context"
+ "errors"
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+// fakeRepoProvider lets tests inject a Repository (with CopyFiles) without
+// pulling in the full task service / models layer.
+type fakeRepoProvider struct {
+ repo *Repository
+ err error
+}
+
+func (f *fakeRepoProvider) GetRepository(_ context.Context, _ string) (*Repository, error) {
+ if f.err != nil {
+ return nil, f.err
+ }
+ return f.repo, nil
+}
+
+// writeSourceFile creates a file (and any parent dirs) inside repoPath with
+// the given content. Returned path is the absolute file path.
+func writeSourceFile(t *testing.T, repoPath, rel, content string) string {
+ t.Helper()
+ abs := filepath.Join(repoPath, rel)
+ if err := os.MkdirAll(filepath.Dir(abs), 0o755); err != nil {
+ t.Fatalf("mkdir for %s: %v", rel, err)
+ }
+ if err := os.WriteFile(abs, []byte(content), 0o644); err != nil {
+ t.Fatalf("write %s: %v", rel, err)
+ }
+ return abs
+}
+
+func newManagerForCopyTest(t *testing.T, provider RepositoryProvider) *Manager {
+ t.Helper()
+ cfg := newTestConfig(t)
+ mgr, err := NewManager(cfg, newMockStore(), newTestLogger())
+ if err != nil {
+ t.Fatalf("NewManager failed: %v", err)
+ }
+ if provider != nil {
+ mgr.SetRepositoryProvider(provider)
+ }
+ return mgr
+}
+
+func createReqForCopyTest(repoPath, name string) CreateRequest {
+ return CreateRequest{
+ TaskID: "task-" + name,
+ SessionID: "session-" + name,
+ TaskTitle: "Copy Files Test",
+ RepositoryID: "repo-" + name,
+ RepositoryPath: repoPath,
+ BaseBranch: "main",
+ TaskDirName: "task-" + name,
+ RepoName: "repo-" + name,
+ }
+}
+
+func TestManagerCreate_CopiesFiles_HappyPath(t *testing.T) {
+ repoPath := initGitRepoForWorktreeTest(t)
+ writeSourceFile(t, repoPath, ".env", "SECRET=hunter2\n")
+ writeSourceFile(t, repoPath, "config/local.yml", "debug: true\n")
+
+ provider := &fakeRepoProvider{
+ repo: &Repository{ID: "repo-happy", CopyFiles: ".env, config/local.yml"},
+ }
+ mgr := newManagerForCopyTest(t, provider)
+
+ wt, err := mgr.Create(context.Background(), createReqForCopyTest(repoPath, "happy"))
+ if err != nil {
+ t.Fatalf("Create() unexpected error: %v", err)
+ }
+
+ envBytes, err := os.ReadFile(filepath.Join(wt.Path, ".env"))
+ if err != nil {
+ t.Fatalf("expected .env in worktree: %v", err)
+ }
+ if string(envBytes) != "SECRET=hunter2\n" {
+ t.Fatalf(".env content = %q, want %q", string(envBytes), "SECRET=hunter2\n")
+ }
+
+ cfgBytes, err := os.ReadFile(filepath.Join(wt.Path, "config", "local.yml"))
+ if err != nil {
+ t.Fatalf("expected config/local.yml in worktree: %v", err)
+ }
+ if string(cfgBytes) != "debug: true\n" {
+ t.Fatalf("config/local.yml content = %q, want %q", string(cfgBytes), "debug: true\n")
+ }
+}
+
+func TestManagerCreate_CopyFilesEmpty_NoOp(t *testing.T) {
+ repoPath := initGitRepoForWorktreeTest(t)
+ // Add an untracked file that would be copied if CopyFiles were set —
+ // proves the no-op path doesn't sweep it in.
+ writeSourceFile(t, repoPath, ".env", "should-not-copy")
+
+ provider := &fakeRepoProvider{
+ repo: &Repository{ID: "repo-empty", CopyFiles: ""},
+ }
+ mgr := newManagerForCopyTest(t, provider)
+
+ wt, err := mgr.Create(context.Background(), createReqForCopyTest(repoPath, "empty"))
+ if err != nil {
+ t.Fatalf("Create() unexpected error: %v", err)
+ }
+
+ if _, err := os.Stat(filepath.Join(wt.Path, ".env")); !errors.Is(err, os.ErrNotExist) {
+ t.Fatalf("expected .env to be absent in worktree, stat err = %v", err)
+ }
+}
+
+func TestManagerCreate_NoRepoProvider_NoOp(t *testing.T) {
+ repoPath := initGitRepoForWorktreeTest(t)
+
+ mgr := newManagerForCopyTest(t, nil) // no provider set
+
+ wt, err := mgr.Create(context.Background(), createReqForCopyTest(repoPath, "noprov"))
+ if err != nil {
+ t.Fatalf("Create() unexpected error: %v", err)
+ }
+ if wt == nil {
+ t.Fatal("expected non-nil worktree")
+ }
+}
+
+func TestManagerCreate_RepoProviderError_NoOp(t *testing.T) {
+ repoPath := initGitRepoForWorktreeTest(t)
+
+ provider := &fakeRepoProvider{err: errors.New("not found")}
+ mgr := newManagerForCopyTest(t, provider)
+
+ wt, err := mgr.Create(context.Background(), createReqForCopyTest(repoPath, "providererr"))
+ if err != nil {
+ t.Fatalf("Create() unexpected error: %v", err)
+ }
+ if wt == nil {
+ t.Fatal("expected non-nil worktree")
+ }
+}
+
+func TestManagerCreate_CopiedFiles_RecordedOnWorktree(t *testing.T) {
+ repoPath := initGitRepoForWorktreeTest(t)
+ writeSourceFile(t, repoPath, ".env", "X=1\n")
+ writeSourceFile(t, repoPath, "config/local.yml", "y\n")
+
+ provider := &fakeRepoProvider{
+ repo: &Repository{ID: "repo-list", CopyFiles: ".env, config/local.yml"},
+ }
+ mgr := newManagerForCopyTest(t, provider)
+
+ wt, err := mgr.Create(context.Background(), createReqForCopyTest(repoPath, "list"))
+ if err != nil {
+ t.Fatalf("Create() unexpected error: %v", err)
+ }
+ got := map[string]bool{}
+ for _, p := range wt.CopiedFiles {
+ got[p] = true
+ }
+ for _, want := range []string{".env", "config/local.yml"} {
+ if !got[want] {
+ t.Errorf("wt.CopiedFiles missing %q, got %v", want, wt.CopiedFiles)
+ }
+ }
+ if len(wt.CopyFilesWarnings) != 0 {
+ t.Errorf("unexpected warnings: %v", wt.CopyFilesWarnings)
+ }
+}
+
+func TestManagerCreate_MissingSourceFile_StillSucceeds(t *testing.T) {
+ repoPath := initGitRepoForWorktreeTest(t)
+ // .env intentionally not created in source repo.
+
+ provider := &fakeRepoProvider{
+ repo: &Repository{ID: "repo-missing", CopyFiles: ".env"},
+ }
+ mgr := newManagerForCopyTest(t, provider)
+
+ wt, err := mgr.Create(context.Background(), createReqForCopyTest(repoPath, "missing"))
+ if err != nil {
+ t.Fatalf("Create() should succeed even when source file is missing, got: %v", err)
+ }
+ if wt == nil {
+ t.Fatal("expected non-nil worktree")
+ }
+ // .env should not exist in the worktree either.
+ if _, err := os.Stat(filepath.Join(wt.Path, ".env")); !errors.Is(err, os.ErrNotExist) {
+ t.Fatalf("expected .env to be absent in worktree, stat err = %v", err)
+ }
+}
diff --git a/apps/backend/internal/worktree/repository_adapter.go b/apps/backend/internal/worktree/repository_adapter.go
index e34e6733ad..0dfe003278 100644
--- a/apps/backend/internal/worktree/repository_adapter.go
+++ b/apps/backend/internal/worktree/repository_adapter.go
@@ -11,6 +11,7 @@ type Repository struct {
ID string
SetupScript string
CleanupScript string
+ CopyFiles string
}
// RepositoryProvider provides access to repository information.
@@ -46,5 +47,6 @@ func (a *RepositoryAdapter) GetRepository(ctx context.Context, repositoryID stri
ID: repo.ID,
SetupScript: repo.SetupScript,
CleanupScript: repo.CleanupScript,
+ CopyFiles: repo.CopyFiles,
}, nil
}
diff --git a/apps/backend/internal/worktree/worktree.go b/apps/backend/internal/worktree/worktree.go
index c735f2ae9c..714b8e0c8e 100644
--- a/apps/backend/internal/worktree/worktree.go
+++ b/apps/backend/internal/worktree/worktree.go
@@ -83,6 +83,18 @@ type Worktree struct {
// describing why the original branch was not used. Surfaced as collapsible
// detail alongside BaseBranchFallbackWarning.
BaseBranchFallbackDetail string `json:"base_branch_fallback_detail,omitempty"`
+
+ // CopiedFiles lists the relative paths of files copied from the source
+ // repo into this worktree per the repository's CopyFiles spec. Populated
+ // only on the in-memory record returned by Create — not persisted, since
+ // it describes a one-shot launch action rather than worktree state. The
+ // env preparer reads it to surface a "Copy ignored files" prepare step.
+ CopiedFiles []string `json:"-"`
+
+ // CopyFilesWarnings lists non-fatal warnings emitted while copying files
+ // (e.g. missing patterns, traversal-rejected paths). Like CopiedFiles,
+ // this is in-memory only and read by the env preparer.
+ CopyFilesWarnings []string `json:"-"`
}
// CreateRequest contains the parameters for creating a new worktree.
diff --git a/apps/web/app/actions/workspaces.ts b/apps/web/app/actions/workspaces.ts
index bcfca9b3cc..dd22a6260a 100644
--- a/apps/web/app/actions/workspaces.ts
+++ b/apps/web/app/actions/workspaces.ts
@@ -222,6 +222,7 @@ export async function createRepositoryAction(payload: {
setup_script: string;
cleanup_script: string;
dev_script: string;
+ copy_files: string;
}) {
return fetchJson(
`${apiBaseUrl}/api/v1/workspaces/${payload.workspace_id}/repositories`,
@@ -241,6 +242,7 @@ export async function createRepositoryAction(payload: {
setup_script: payload.setup_script,
cleanup_script: payload.cleanup_script,
dev_script: payload.dev_script,
+ copy_files: payload.copy_files,
}),
},
);
diff --git a/apps/web/app/settings/workspace/workspace-repositories-client.tsx b/apps/web/app/settings/workspace/workspace-repositories-client.tsx
index 5af0cf2f9d..86a5fa9dbb 100644
--- a/apps/web/app/settings/workspace/workspace-repositories-client.tsx
+++ b/apps/web/app/settings/workspace/workspace-repositories-client.tsx
@@ -34,60 +34,19 @@ import {
type ManualValidation,
} from "@/app/settings/workspace/workspace-repositories-dialog";
import { WorkspaceNotFoundCard } from "@/app/settings/workspace/workspace-not-found-card";
+import {
+ areRepositoryScriptsDirty,
+ cloneRepository,
+ isRepositoryDirty,
+ type RepositoryWithScripts,
+} from "@/app/settings/workspace/workspace-repositories-dirty";
-type RepositoryWithScripts = Repository & { scripts: RepositoryScript[] };
type RepositoryItem = RepositoryWithScripts & { __autoOpen?: boolean };
type WorkspaceRepositoriesClientProps = {
workspace: Workspace | null;
repositories: RepositoryWithScripts[];
};
-function cloneRepository(repo: RepositoryWithScripts): RepositoryWithScripts {
- return { ...repo, scripts: repo.scripts.map((script) => ({ ...script })) };
-}
-
-function isRepositoryDirty(
- repo: RepositoryItem,
- saved: RepositoryWithScripts | undefined,
-): boolean {
- if (!saved) return true;
- return (
- repo.name !== saved.name ||
- repo.source_type !== saved.source_type ||
- repo.local_path !== saved.local_path ||
- repo.provider !== saved.provider ||
- repo.provider_repo_id !== saved.provider_repo_id ||
- repo.provider_owner !== saved.provider_owner ||
- repo.provider_name !== saved.provider_name ||
- repo.default_branch !== saved.default_branch ||
- repo.worktree_branch_prefix !== saved.worktree_branch_prefix ||
- repo.pull_before_worktree !== saved.pull_before_worktree ||
- repo.setup_script !== saved.setup_script ||
- repo.cleanup_script !== saved.cleanup_script ||
- repo.dev_script !== saved.dev_script
- );
-}
-
-function areRepositoryScriptsDirty(
- repo: RepositoryItem,
- saved: RepositoryWithScripts | undefined,
-): boolean {
- if (!saved) return repo.scripts.length > 0;
- if (repo.scripts.length !== saved.scripts.length) return true;
- const savedScripts = new Map(saved.scripts.map((script) => [script.id, script]));
- for (const script of repo.scripts) {
- const savedScript = savedScripts.get(script.id);
- if (
- !savedScript ||
- script.name !== savedScript.name ||
- script.command !== savedScript.command ||
- script.position !== savedScript.position
- )
- return true;
- }
- return false;
-}
-
function buildDraftRepo(
workspace: Workspace,
selectedRepo: LocalRepository | undefined,
@@ -113,6 +72,7 @@ function buildDraftRepo(
setup_script: "",
cleanup_script: "",
dev_script: "",
+ copy_files: "",
created_at: "",
updated_at: "",
scripts: [],
@@ -151,6 +111,7 @@ async function saveNewRepository(
setup_script: repo.setup_script,
cleanup_script: repo.cleanup_script,
dev_script: repo.dev_script,
+ copy_files: repo.copy_files,
});
const scripts = await Promise.all(
repo.scripts.map((script, index) =>
@@ -198,6 +159,7 @@ async function saveExistingRepository({
setup_script: repo.setup_script,
cleanup_script: repo.cleanup_script,
dev_script: repo.dev_script,
+ copy_files: repo.copy_files,
});
const savedScripts = savedRepositoriesById.get(repoId)?.scripts ?? [];
const currentScriptIds = new Set(repo.scripts.map((s) => s.id));
diff --git a/apps/web/app/settings/workspace/workspace-repositories-dirty.test.ts b/apps/web/app/settings/workspace/workspace-repositories-dirty.test.ts
new file mode 100644
index 0000000000..d84180d79b
--- /dev/null
+++ b/apps/web/app/settings/workspace/workspace-repositories-dirty.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import {
+ isRepositoryDirty,
+ type RepositoryWithScripts,
+} from "@/app/settings/workspace/workspace-repositories-dirty";
+import { repositoryId as toRepositoryId, workspaceId as toWorkspaceId } from "@/lib/types/http";
+
+function makeRepo(overrides: Partial = {}): RepositoryWithScripts {
+ return {
+ id: toRepositoryId("repo-1"),
+ workspace_id: toWorkspaceId("ws-1"),
+ name: "my-repo",
+ source_type: "local",
+ local_path: "/tmp/my-repo",
+ provider: "",
+ provider_repo_id: "",
+ provider_owner: "",
+ provider_name: "",
+ default_branch: "main",
+ worktree_branch_prefix: "feature/",
+ pull_before_worktree: true,
+ setup_script: "",
+ cleanup_script: "",
+ dev_script: "",
+ copy_files: "",
+ created_at: "",
+ updated_at: "",
+ scripts: [],
+ ...overrides,
+ };
+}
+
+describe("isRepositoryDirty", () => {
+ it("returns false when copy_files matches", () => {
+ const saved = makeRepo({ copy_files: ".env, .env.local" });
+ const repo = makeRepo({ copy_files: ".env, .env.local" });
+ expect(isRepositoryDirty(repo, saved)).toBe(false);
+ });
+
+ it("returns true when copy_files differs", () => {
+ const saved = makeRepo({ copy_files: "" });
+ const repo = makeRepo({ copy_files: ".env" });
+ expect(isRepositoryDirty(repo, saved)).toBe(true);
+ });
+
+ it("returns true when there is no saved repository", () => {
+ const repo = makeRepo();
+ expect(isRepositoryDirty(repo, undefined)).toBe(true);
+ });
+});
diff --git a/apps/web/app/settings/workspace/workspace-repositories-dirty.ts b/apps/web/app/settings/workspace/workspace-repositories-dirty.ts
new file mode 100644
index 0000000000..22354056a1
--- /dev/null
+++ b/apps/web/app/settings/workspace/workspace-repositories-dirty.ts
@@ -0,0 +1,50 @@
+import type { Repository, RepositoryScript } from "@/lib/types/http";
+
+export type RepositoryWithScripts = Repository & { scripts: RepositoryScript[] };
+
+export function cloneRepository(repo: RepositoryWithScripts): RepositoryWithScripts {
+ return { ...repo, scripts: repo.scripts.map((script) => ({ ...script })) };
+}
+
+export function isRepositoryDirty(
+ repo: RepositoryWithScripts,
+ saved: RepositoryWithScripts | undefined,
+): boolean {
+ if (!saved) return true;
+ return (
+ repo.name !== saved.name ||
+ repo.source_type !== saved.source_type ||
+ repo.local_path !== saved.local_path ||
+ repo.provider !== saved.provider ||
+ repo.provider_repo_id !== saved.provider_repo_id ||
+ repo.provider_owner !== saved.provider_owner ||
+ repo.provider_name !== saved.provider_name ||
+ repo.default_branch !== saved.default_branch ||
+ repo.worktree_branch_prefix !== saved.worktree_branch_prefix ||
+ repo.pull_before_worktree !== saved.pull_before_worktree ||
+ repo.setup_script !== saved.setup_script ||
+ repo.cleanup_script !== saved.cleanup_script ||
+ repo.dev_script !== saved.dev_script ||
+ repo.copy_files !== saved.copy_files
+ );
+}
+
+export function areRepositoryScriptsDirty(
+ repo: RepositoryWithScripts,
+ saved: RepositoryWithScripts | undefined,
+): boolean {
+ if (!saved) return repo.scripts.length > 0;
+ if (repo.scripts.length !== saved.scripts.length) return true;
+ const savedScripts = new Map(saved.scripts.map((script) => [script.id, script]));
+ for (const script of repo.scripts) {
+ const savedScript = savedScripts.get(script.id);
+ if (
+ !savedScript ||
+ script.name !== savedScript.name ||
+ script.command !== savedScript.command ||
+ script.position !== savedScript.position
+ )
+ return true;
+ }
+ return false;
+}
diff --git a/apps/web/components/automations/automation-payload.ts b/apps/web/components/automations/automation-payload.ts
index 86bee62461..04d7b2450d 100644
--- a/apps/web/components/automations/automation-payload.ts
+++ b/apps/web/components/automations/automation-payload.ts
@@ -57,6 +57,7 @@ export async function resolveRepositoryId(
setup_script: "",
cleanup_script: "",
dev_script: "",
+ copy_files: "",
});
return created.id;
}
diff --git a/apps/web/components/settings/repository-card.tsx b/apps/web/components/settings/repository-card.tsx
index 8a46eb5de2..f003895eec 100644
--- a/apps/web/components/settings/repository-card.tsx
+++ b/apps/web/components/settings/repository-card.tsx
@@ -108,6 +108,7 @@ type RepositoryScriptFieldsProps = RepoFieldsBaseProps & {
setupScript: string;
cleanupScript: string;
devScript: string;
+ copyFiles: string;
};
function RepositoryScriptFields({
@@ -116,6 +117,7 @@ function RepositoryScriptFields({
setupScript,
cleanupScript,
devScript,
+ copyFiles,
}: RepositoryScriptFieldsProps) {
return (
<>
@@ -162,6 +164,18 @@ function RepositoryScriptFields({
$PORT for automatic port allocation.
+
+
>
);
}
@@ -276,15 +290,13 @@ function RepositoryEditView({
{isDirty && }
-
- onSave(close) : close}
- />
-
+ onSave(close) : close}
+ />
{
await this.request("PATCH", `/api/v1/repositories/${repositoryId}`, updates);
}
diff --git a/apps/web/e2e/tests/session/copyfiles-progress.spec.ts b/apps/web/e2e/tests/session/copyfiles-progress.spec.ts
new file mode 100644
index 0000000000..7f8804e2c8
--- /dev/null
+++ b/apps/web/e2e/tests/session/copyfiles-progress.spec.ts
@@ -0,0 +1,176 @@
+import fs from "node:fs";
+import path from "node:path";
+import { test, expect } from "../../fixtures/test-base";
+import { SessionPage } from "../../pages/session-page";
+
+/**
+ * Verifies the "Copy N ignored files" step the env preparer surfaces in the
+ * prepare-progress panel whenever a worktree-mode repository has a non-empty
+ * `copy_files` spec that actually matches source files.
+ *
+ * Setup:
+ * - Writes `.env` + `config/local.yml` into the worker-scoped seed repo.
+ * - PATCHes `copy_files` on that repo to ".env, config/local.yml".
+ * - Restores both in a finally so this never leaks into sibling tests
+ * (the seedData repo is shared across the whole worker).
+ *
+ * Why an E2E (not just a unit test): the existing unit coverage exercises the
+ * step builder and the manager-level copy. This guards the full WS path —
+ * env preparer → prepare event → store → PrepareProgress panel — so a
+ * regression in any layer flips the panel back to silent.
+ */
+test.describe("Copy ignored files prepare step", () => {
+ test("surfaces 'Copy N ignored files' step when copy_files is configured", async ({
+ testPage,
+ apiClient,
+ seedData,
+ backend,
+ }) => {
+ test.setTimeout(60_000);
+
+ const repoDir = path.join(backend.tmpDir, "repos", "e2e-repo");
+ const envPath = path.join(repoDir, ".env");
+ const configDir = path.join(repoDir, "config");
+ const configPath = path.join(configDir, "local.yml");
+
+ // Snapshot pre-existing state so teardown can restore it. The seed
+ // repo is worker-scoped — a previous test might have left fixtures
+ // in `config/`, and unconditionally rmSync'ing them would silently
+ // poison sibling tests with missing files. Pattern flagged by
+ // CodeRabbit on PR #950.
+ const hadConfigDir = fs.existsSync(configDir);
+ const hadConfigFile = fs.existsSync(configPath);
+ const previousConfig = hadConfigFile ? fs.readFileSync(configPath) : undefined;
+ const hadEnv = fs.existsSync(envPath);
+ const previousEnv = hadEnv ? fs.readFileSync(envPath) : undefined;
+
+ fs.mkdirSync(configDir, { recursive: true });
+ fs.writeFileSync(envPath, "E2E_SECRET=hunter2\n");
+ fs.writeFileSync(configPath, "debug: true\n");
+
+ await apiClient.updateRepository(seedData.repositoryId, {
+ copy_files: ".env, config/local.yml",
+ });
+
+ // Slow `git fetch` (worktree sync step) so the prepare panel is
+ // still streaming when the page mounts + WS subscribes. Without
+ // this shim prepare can complete before the client connects, the
+ // events broadcast into the void, and the panel renders with an
+ // empty steps list — making the "Copy 2 ignored files" assertion
+ // below race against the fallback completed-with-no-steps path.
+ // Same pattern as `setup-script-progress.spec.ts`.
+ const delayFile = path.join(backend.tmpDir, "git-delay-ms");
+ fs.writeFileSync(delayFile, "5000");
+
+ try {
+ const task = await apiClient.createTaskWithAgent(
+ seedData.workspaceId,
+ "Copy Files Prepare Step",
+ seedData.agentProfileId,
+ {
+ description: "/e2e:simple-message",
+ workflow_id: seedData.workflowId,
+ workflow_step_id: seedData.startStepId,
+ repository_ids: [seedData.repositoryId],
+ executor_profile_id: seedData.worktreeExecutorProfileId,
+ },
+ );
+
+ await testPage.goto(`/t/${task.id}`);
+ const session = new SessionPage(testPage);
+ await session.waitForLoad();
+
+ const panel = testPage.getByTestId("prepare-progress-panel");
+ await expect(panel).toBeVisible({ timeout: 30_000 });
+ await expect(panel).toHaveAttribute("data-status", "completed", { timeout: 30_000 });
+
+ // Panel auto-collapses on a clean run — expand it so the step rows render.
+ await panel.getByTestId("prepare-progress-toggle").click();
+ await expect(panel).toHaveAttribute("data-expanded", "true");
+
+ // Pluralized count is what proves the backend wired in CopiedFiles —
+ // a regression in copyfiles.Copy's returned slice or the env preparer's
+ // step builder would land on "Copy ignored files" (no count) or skip
+ // the step entirely.
+ await expect(panel).toContainText("Copy 2 ignored files", { timeout: 5_000 });
+ } finally {
+ if (fs.existsSync(delayFile)) fs.unlinkSync(delayFile);
+ await apiClient.updateRepository(seedData.repositoryId, { copy_files: "" }).catch(() => {
+ // Test teardown is best-effort — a 404 here just means the repo
+ // was already cleaned up by a parallel teardown.
+ });
+ // Restore pre-existing state captured above so sibling tests
+ // sharing this worker repo don't lose any fixture files.
+ if (previousEnv !== undefined) {
+ fs.writeFileSync(envPath, previousEnv);
+ } else {
+ fs.rmSync(envPath, { force: true });
+ }
+ if (previousConfig !== undefined) {
+ fs.writeFileSync(configPath, previousConfig);
+ } else {
+ fs.rmSync(configPath, { force: true });
+ if (!hadConfigDir) {
+ fs.rmSync(configDir, { recursive: true, force: true });
+ }
+ }
+ }
+ });
+
+ test("renders the step with a warning when no files match", async ({
+ testPage,
+ apiClient,
+ seedData,
+ backend,
+ }) => {
+ test.setTimeout(60_000);
+
+ // Configure copy_files to a pattern that matches nothing in the repo —
+ // copyfiles.Copy returns zero copied + one "no matches" warning, but
+ // because the warning IS surfaced the step still appears. Use a pattern
+ // we know cannot match by giving it a path the seed repo never creates.
+ await apiClient.updateRepository(seedData.repositoryId, {
+ copy_files: "definitely-does-not-exist.never",
+ });
+
+ // Same git-fetch delay shim as the happy-path test above — gives the
+ // page time to mount + subscribe before the prepare-completed event
+ // broadcasts. Otherwise the panel falls back to the empty-steps
+ // completed state and the data-status / step-text assertions race.
+ const delayFile = path.join(backend.tmpDir, "git-delay-ms");
+ fs.writeFileSync(delayFile, "5000");
+
+ try {
+ const task = await apiClient.createTaskWithAgent(
+ seedData.workspaceId,
+ "Copy Files Zero Match",
+ seedData.agentProfileId,
+ {
+ description: "/e2e:simple-message",
+ workflow_id: seedData.workflowId,
+ workflow_step_id: seedData.startStepId,
+ repository_ids: [seedData.repositoryId],
+ executor_profile_id: seedData.worktreeExecutorProfileId,
+ },
+ );
+
+ await testPage.goto(`/t/${task.id}`);
+ const session = new SessionPage(testPage);
+ await session.waitForLoad();
+
+ const panel = testPage.getByTestId("prepare-progress-panel");
+ await expect(panel).toBeVisible({ timeout: 30_000 });
+ await expect(panel).toHaveAttribute("data-status", "completed_with_warnings", {
+ timeout: 30_000,
+ });
+
+ // Warnings keep the panel auto-expanded; the step renders with zero
+ // count ("Copy ignored files") and the no-match warning.
+ await expect(panel).toContainText("Copy ignored files");
+ await expect(panel).toContainText("definitely-does-not-exist.never");
+ } finally {
+ if (fs.existsSync(delayFile)) fs.unlinkSync(delayFile);
+ await apiClient.updateRepository(seedData.repositoryId, { copy_files: "" }).catch(() => {});
+ }
+ });
+});
diff --git a/apps/web/hooks/use-responsive-breakpoint.ts b/apps/web/hooks/use-responsive-breakpoint.ts
index fb3d3013dd..fd9dd00288 100644
--- a/apps/web/hooks/use-responsive-breakpoint.ts
+++ b/apps/web/hooks/use-responsive-breakpoint.ts
@@ -61,35 +61,54 @@ function getCurrentResponsiveBreakpoint(): ResponsiveBreakpoint {
return buildResponsiveBreakpoint(window.innerWidth, getPointerMode());
}
-export function useResponsiveBreakpoint(): ResponsiveBreakpoint {
- const [state, setState] = React.useState(() =>
- buildResponsiveBreakpoint(DESKTOP_BREAKPOINT, true),
- );
+const SERVER_SNAPSHOT = buildResponsiveBreakpoint(DESKTOP_BREAKPOINT, true);
- React.useEffect(() => {
- const updateBreakpoint = () => {
- setState(getCurrentResponsiveBreakpoint());
- };
+// Cached snapshot keeps getSnapshot referentially stable across re-renders —
+// useSyncExternalStore loops if getSnapshot returns a fresh object every
+// call. The cache is freshened only when the underlying viewport actually
+// changes (verified by deep-equal against the live readout), so listeners
+// firing without an effective change don't trigger spurious renders.
+let cachedClientSnapshot: ResponsiveBreakpoint | null = null;
- // Set initial value
- updateBreakpoint();
-
- // Listen for resize events
- const mediaQueries = [
- `(max-width: ${MOBILE_BREAKPOINT - 1}px)`,
- `(min-width: ${MOBILE_BREAKPOINT}px) and (max-width: ${COMPACT_DESKTOP_BREAKPOINT - 1}px)`,
- `(min-width: ${COMPACT_DESKTOP_BREAKPOINT}px) and (max-width: ${DESKTOP_BREAKPOINT - 1}px)`,
- `(min-width: ${DESKTOP_BREAKPOINT}px)`,
- "(pointer: fine)",
- ];
- const mediaQueryLists = mediaQueries.map((query) => window.matchMedia(query));
-
- mediaQueryLists.forEach((mql) => mql.addEventListener("change", updateBreakpoint));
-
- return () => {
- mediaQueryLists.forEach((mql) => mql.removeEventListener("change", updateBreakpoint));
- };
- }, []);
-
- return state;
+function breakpointsEqual(a: ResponsiveBreakpoint, b: ResponsiveBreakpoint): boolean {
+ // breakpoint + isFinePointer fully determine every other field (see
+ // buildResponsiveBreakpoint), so equality on those two is sufficient.
+ return a.breakpoint === b.breakpoint && a.isFinePointer === b.isFinePointer;
+}
+
+function getClientSnapshot(): ResponsiveBreakpoint {
+ const fresh = getCurrentResponsiveBreakpoint();
+ if (cachedClientSnapshot !== null && breakpointsEqual(cachedClientSnapshot, fresh)) {
+ return cachedClientSnapshot;
+ }
+ cachedClientSnapshot = fresh;
+ return fresh;
+}
+
+function subscribeBreakpoint(callback: () => void): () => void {
+ if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+ return () => {};
+ }
+ const mediaQueries = [
+ `(max-width: ${MOBILE_BREAKPOINT - 1}px)`,
+ `(min-width: ${MOBILE_BREAKPOINT}px) and (max-width: ${COMPACT_DESKTOP_BREAKPOINT - 1}px)`,
+ `(min-width: ${COMPACT_DESKTOP_BREAKPOINT}px) and (max-width: ${DESKTOP_BREAKPOINT - 1}px)`,
+ `(min-width: ${DESKTOP_BREAKPOINT}px)`,
+ "(pointer: fine)",
+ ];
+ const mediaQueryLists = mediaQueries.map((query) => window.matchMedia(query));
+ mediaQueryLists.forEach((mql) => mql.addEventListener("change", callback));
+ return () => {
+ mediaQueryLists.forEach((mql) => mql.removeEventListener("change", callback));
+ };
+}
+
+// useSyncExternalStore is React 19's canonical pattern for hooks that
+// expose browser-only state. It reads the real viewport on the first
+// client render — no useEffect lag, no desktop→tablet flash, no race
+// where heavyweight desktop-only components mount on narrow viewports
+// before the layout switches. SSR keeps the desktop default via the
+// third arg, matching the prior behavior for hydration.
+export function useResponsiveBreakpoint(): ResponsiveBreakpoint {
+ return React.useSyncExternalStore(subscribeBreakpoint, getClientSnapshot, () => SERVER_SNAPSHOT);
}
diff --git a/apps/web/lib/types/http.ts b/apps/web/lib/types/http.ts
index 709c31d4c3..fae94bf0ca 100644
--- a/apps/web/lib/types/http.ts
+++ b/apps/web/lib/types/http.ts
@@ -174,6 +174,7 @@ export type Repository = {
setup_script: string;
cleanup_script: string;
dev_script: string;
+ copy_files: string;
created_at: string;
updated_at: string;
};
diff --git a/docs/decisions/0010-worktree-copy-files.md b/docs/decisions/0010-worktree-copy-files.md
new file mode 100644
index 0000000000..7b59ef1431
--- /dev/null
+++ b/docs/decisions/0010-worktree-copy-files.md
@@ -0,0 +1,45 @@
+# 0010: Worktree copy-files — per-repo, idempotent, host-local
+
+**Status:** accepted
+**Date:** 2026-05-19
+**Area:** backend, frontend
+
+## Context
+
+Git worktrees don't carry gitignored files. The most painful case for kandev users is `.env` and friends — every new task creates a fresh worktree, and the agent's first step is usually `pnpm dev` or `make run`, which fails immediately because there's no `.env`. Users were copying files manually after each task creation. Issue #946 asked for a built-in solution, citing vibe-kanban's `copy_files` setting as prior art.
+
+The feature has several axes of choice that aren't obvious from the issue text alone, and a couple are surprising enough that future maintainers will reasonably question them.
+
+## Decision
+
+**A per-repository, comma-separated list of paths/globs (`repositories.copy_files`). Copied from the source repo dir into each new worktree at task creation, in the Go process on the host. Target-exists check makes the copy idempotent.**
+
+Concretely:
+
+1. **Scope: per-repository, not per-task or per-workspace.** The set of secret files in a repo (`.env`, `.env.local`, `config/local.yml`) is a property of the repo, not of any individual task. Storing it once per repo means users configure it during workspace setup and never think about it again. A per-task field would push friction back onto every task creation, defeating the purpose. A per-workspace field would force every repo in the workspace to share the same list — wrong for polyglot workspaces.
+
+2. **Wire format: comma-separated string of paths or `filepath.Glob` patterns.** Matches vibe-kanban exactly, which means users migrating between tools don't relearn syntax. Stdlib `filepath.Glob` supports `*`, `?`, `[...]` — enough for `.env`, `*.local`, `config/*.json`. **No `**`/doublestar in v1**: it's a single transitive dependency we don't need to take to ship the feature, and the literal-file-plus-directory-recursion path (`config/` recursively walks all files) covers the rest of the issue's examples. Adding doublestar later is additive.
+
+3. **Trigger: at worktree creation, between `persistAndCacheWorktree` and `runWorktreeSetupScript`.** Setup scripts often read `.env` (e.g. `pnpm install` with `NODE_ENV`-gated postinstalls), so the copy must complete first. Placing it after `persistAndCacheWorktree` means a failed copy doesn't leave a phantom DB row — the worktree is already committed, and copy errors are recoverable.
+
+4. **Host-local Go copy, not an agentctl RPC.** The worktree filesystem is on the host (today). The copy is `io.Copy` between two `*os.File`s under a path-traversal guard. No subprocess, no shell, no Windows `cp` issue, no agentctl round-trip.
+
+5. **Idempotent: skip if target exists.** Re-running the copy on the same worktree (e.g. future "re-prepare worktree" actions, or session resume that re-enters this code path) is a no-op for already-copied files. The cost is that **updating `copy_files` in settings does not propagate to existing worktrees** — only future ones. The frontend helper text says so explicitly. The alternative — overwrite-on-update — would clobber files the agent had already mutated mid-task, which is worse.
+
+6. **Missing files = warning, not error.** Acceptance criterion in the issue. A typo in `copy_files` should not block task creation; the agent failing later with a clearer "ENOENT: .env" is better than the worktree refusing to spawn.
+
+7. **Path-traversal guard: canonicalize, then `filepath.Rel` under canonical root.** `EvalSymlinks(sourceDir)` is called once; all pattern joins and result paths use that canonical root, not the raw `sourceDir` argument. This matters because macOS resolves `/tmp` → `/private/tmp` and many users have `~/code` → `/data/code` style symlinks; without canonicalization, *every* match looks "outside source dir" via `filepath.Rel` and the feature silently no-ops. (Regression test: `TestCopy_SymlinkedSourceDir`.) Resolved matches outside the canonical root are still rejected — symlink traversal as an exfiltration vector is closed.
+
+## Consequences
+
+- **Remote executors are supported** via a parallel "ship bytes through agentctl" path (added 2026-05-24). The host reads source files into memory via `copyfiles.Plan` and POSTs them to `POST /workspace/copy-files`, which calls `copyfiles.WriteEntries` against the container workspace root. Both paths share `Plan` / `WriteEntries` so path-traversal guard, idempotency, and skip-if-exists are identical. Per-file payloads are capped at **5 MB** (`copyfiles.MaxEntryBytes`) to bound launch-time RAM + wire bytes against accidental matches like `node_modules/`; oversize files are warn-skipped rather than silently dropped. Wired into `local_docker` and `sprites`; `remote_docker` / `k8s` (planned) inherit automatically as long as their executors expose an `agentctl.Client` on the returned instance. The shipping step appears in the prepare-progress panel as `Copy N ignored files`, matching the worktree path's naming via the shared `buildCopyFilesStep` helper.
+- **Disk-fill DoS** is bounded for remote paths by the 5 MB cap above. For the host-side worktree path it remains self-inflicted but unbounded — a user adding `**` or `node_modules/` would explode disk usage across many tasks. If support tickets surface this, add a soft warning at >100 MB / >1000 files for the local case as well.
+- **UI feedback for warnings.** The prepare-progress panel now surfaces copy warnings (missing patterns, oversize files, ship failures) inline on the `Copy N ignored files` step. Backend zap logs remain for deeper debugging.
+- **The `worktree.RepositoryAdapter` indirection** stays — it maps `models.Repository` → `worktree.Repository` (a minimal struct exposing only `{ID, SetupScript, CleanupScript, CopyFiles}`). Adding more cross-cutting per-repo settings should go through this adapter, not by widening the worktree package's import surface.
+
+## Alternatives considered
+
+- **Extend `setup_script`.** Users could already write `cp /path/to/.env .` in setup. Rejected: requires every user to write shell, fights Windows (no `cp`), doesn't canonicalize source paths, and surfaces secrets in script output that gets streamed to the session UI. A dedicated field is purpose-built.
+- **Per-task override on the task creation dialog.** Reasonable for one-off needs, but adds friction to the common path. Defer until a user asks.
+- **Watch and re-copy on `copy_files` setting change.** Would make settings updates "live" for existing worktrees. Rejected: existing worktrees may have agent-modified copies, and silent re-copy risks data loss. The current design forces the user to re-create the task if they want the new files, which is the safe default.
+- **JSON or YAML for the spec.** Considered for future expressiveness (`{src, dest, mode}` tuples). Rejected for v1: vibe-kanban's flat comma-separated format is proven, trivial to migrate from, and we have no use case yet for `dest` differing from `src`.
diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md
index 8160d4da25..645b176e99 100644
--- a/docs/decisions/INDEX.md
+++ b/docs/decisions/INDEX.md
@@ -15,3 +15,4 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
| 0007 | [profiles.yaml — runtime defaults for prod / dev / e2e](0007-runtime-feature-flags.md) | accepted | backend, frontend | 2026-05-16 |
| 0008 | [DB upgrade safety - meta table, pre-migration backup, migration logging](0008-db-upgrade-safety.md) | accepted | backend | 2026-05-16 |
| 0009 | [Fail-closed GC semantics for filesystem and container cleanup](0009-fail-closed-gc-semantics.md) | accepted | backend | 2026-05-16 |
+| 0010 | [Worktree copy-files — per-repo, idempotent, host-local](0010-worktree-copy-files.md) | accepted | backend, frontend | 2026-05-19 |