fix: address the agent's source tree when the gateway does source work

The gateway assumed its work directory was the tree the agent calls its
source. A service declaration moves that tree with source-dir, and now that the
gateway resolves symbol patches and import inventories itself, the two sides
addressed different files under the same relative path.

Standardising on the service directory, as the previous commit did, only moved
the seam. It made symbol patches self-consistent but left prepared apply-edit
previewing through the agent while writing beside it, and the preview identity
check could not catch that: it compares the preview against the gateway's own
read, so once both sides read the same tree it passes by construction. With a
byte-identical file at each root it passed while the edit landed on the wrong
one, reporting success and consuming a single-use permit.

The engine decides where an agent roots, so it now answers that question.
AgentSourceRoot mirrors both halves of the decision: source-dir applies only
when a real service is bound, since an ephemeral source workspace resolves its
attachment back to the service directory, and only from the declaration beside
the agent's own work directory. The gateway resolves it once and routes project
reads and writes, both symbol-patch paths, the prepared write and the import
inventory through it, while VCS, terminal and code-unit paths stay on the
service directory where they belong.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: antoinetoussaint-byte

pkg/engine/target.go

@@ -238,3 +238,55 @@ func parentResourceDir(start, configurationName string) (string, error) {
 		current = parent
 	}
 }
+
+// AgentSourceRoot reports the tree an agent bound to root will treat as its
+// source. Callers that perform source work themselves — the Gateway resolves
+// symbol patches and import inventories in-process — must address the same
+// tree the agent does, or they preview one file and write another of the same
+// name.
+//
+// It mirrors the two decisions that place an agent's root. First, a service is
+// only bound from its real declaration when a workspace and a service
+// configuration exist above root; otherwise resolveServiceDescriptor prepares
+// an ephemeral source workspace whose attachment resolves back to root, and any
+// source-dir beside root is not the one the agent reads. Second, the agent
+// reads the declaration beside its own work directory only, so a declaration
+// further up the tree does not move it (see core agents/services.
+// ResolveSourceLocation).
+func AgentSourceRoot(ctx context.Context, root string) string {
+	absolute, err := filepath.Abs(root)
+	if err != nil {
+		return root
+	}
+	absolute = filepath.Clean(absolute)
+	if _, workspaceErr := parentResourceDir(absolute, resources.WorkspaceConfigurationName); workspaceErr != nil {
+		return absolute
+	}
+	if _, serviceErr := parentResourceDir(absolute, resources.ServiceConfigurationName); serviceErr != nil {
+		return absolute
+	}
+	if info, statErr := os.Stat(filepath.Join(absolute, resources.ServiceConfigurationName)); statErr != nil || info.IsDir() {
+		return absolute
+	}
+	declaration, err := resources.LoadServiceFromDir(ctx, absolute)
+	if err != nil || declaration == nil {
+		return absolute
+	}
+	configured, _ := declaration.Spec["source-dir"].(string)
+	configured = strings.TrimSpace(configured)
+	if configured == "" {
+		return absolute
+	}
+	configured = filepath.FromSlash(configured)
+	// Core refuses a source-dir that leaves the service directory, so a
+	// rejected value leaves the agent at its work directory rather than
+	// somewhere outside it.
+	if !filepath.IsLocal(configured) {
+		return absolute
+	}
+	location := filepath.Clean(filepath.Join(absolute, configured))
+	if physical, evalErr := filepath.EvalSymlinks(location); evalErr == nil {
+		return physical
+	}
+	return location
+}

pkg/gateway/engine_source_semantics_test.go

@@ -1,6 +1,8 @@
 package gateway
 
 import (
+	"crypto/ed25519"
+	"crypto/rand"
 	"crypto/sha256"
 	"encoding/hex"
 	"os"
@@ -10,11 +12,13 @@ import (
 	"testing"
 	"time"
 
+	"github.com/codefly-dev/cli/pkg/engine"
 	"github.com/codefly-dev/cli/pkg/internal/protocoltest"
 	basev0 "github.com/codefly-dev/core/generated/go/codefly/base/v0"
 	executionv1 "github.com/codefly-dev/core/generated/go/codefly/execution/v1"
 	codev0 "github.com/codefly-dev/core/generated/go/codefly/services/code/v0"
 	gatewayv1 "github.com/codefly-dev/core/generated/go/mind/gateway/v1"
+	"github.com/google/uuid"
 )
 
 // newSourceSemanticsGateway binds a gateway to one peer-backed service so the
@@ -351,3 +355,125 @@ func TestGatewaySemanticIndexDegradesOnMalformedSource(t *testing.T) {
 		t.Fatalf("degraded index dropped the parseable file's symbols: %+v", index.GetSymbols())
 	}
 }
+
+// newSourceDirGateway builds a gateway whose service declares source-dir, with
+// a byte-identical shadow of the target file at the service root. The shadow is
+// what makes the bug silent: hash-and-size checks cannot tell the two apart, so
+// only the path that is actually written distinguishes right from wrong.
+func newSourceDirGateway(t *testing.T, relative, content string) (*Server, string) {
+	t.Helper()
+	root := t.TempDir()
+	writeCodeUnitFixture(t, root, "workspace.codefly.yaml", "name: shop\nlayout: flat\n")
+	writeCodeUnitFixture(t, root, "service.codefly.yaml", "name: app\nversion: 0.0.1\nspec:\n  source-dir: src\n")
+	writeCodeUnitFixture(t, root, "mind.yaml", "service: app\nplugin: generic-go\n")
+	writeCodeUnitFixture(t, root, filepath.Join("src", relative), content)
+	writeCodeUnitFixture(t, root, relative, content)
+
+	server, err := NewServer(Config{WorkDir: root})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = server.Close() })
+	return server, root
+}
+
+// The gateway resolves symbol patches itself, so it must address the tree the
+// agent calls its source. With source-dir set, patching the service-root copy
+// leaves the compiled source untouched while reporting success.
+func TestSymbolPatchTargetsTheAgentSourceRootNotTheServiceRoot(t *testing.T) {
+	declaration := "func Value() int { return 1 }"
+	body := "package service\n\n" + declaration + "\n"
+	server, root := newSourceDirGateway(t, filepath.Join("pkg", "service.go"), body)
+
+	response, err := server.ApplySymbolPatch(t.Context(), &gatewayv1.ApplySymbolPatchRequest{
+		Service: "app", File: "pkg/service.go", QualifiedName: "service.Value",
+		ExpectedDeclarationSha256: contentSHA256([]byte(declaration)),
+		NewSource:                 "func Value() int { return 2 }",
+	})
+	if err != nil || !response.GetSuccess() {
+		t.Fatalf("apply symbol patch: response=%+v err=%v", response, err)
+	}
+
+	patched, err := os.ReadFile(filepath.Join(root, "src", "pkg", "service.go"))
+	if err != nil || !strings.Contains(string(patched), "return 2") {
+		t.Fatalf("agent source tree was not patched: content=%q err=%v", patched, err)
+	}
+	shadow, err := os.ReadFile(filepath.Join(root, "pkg", "service.go"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(shadow) != body {
+		t.Fatalf("the service-root shadow was patched instead of the agent's source: %q", shadow)
+	}
+}
+
+// The same root has to govern prepared mutations end to end: preview, the
+// authoritative re-read, and the write. A prepared symbol patch must move the
+// agent's source and leave the identical shadow alone.
+func TestPreparedMutationTargetsTheAgentSourceRoot(t *testing.T) {
+	declaration := "func Value() int { return 1 }"
+	body := "package service\n\n" + declaration + "\n"
+	server, root := newSourceDirGateway(t, filepath.Join("pkg", "service.go"), body)
+
+	publicKey, privateKey, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := server.ConfigureMutationAuthority(t.Context(), &gatewayv1.ConfigureMutationAuthorityRequest{
+		AuthorityId: "coordinator-key-v1", WorkspaceId: "workspace-" + uuid.NewString(), Ed25519PublicKey: publicKey,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	preparedResponse, err := server.PrepareMutation(t.Context(), &gatewayv1.PrepareMutationRequest{
+		Service: "app", WorkspaceVersion: "workspace-source-dir-v1",
+		Mutation: &gatewayv1.PrepareMutationRequest_SymbolPatch{SymbolPatch: &gatewayv1.PrepareSymbolPatchMutation{
+			File: "pkg/service.go", SymbolId: "symbol-service-value", QualifiedName: "service.Value",
+			ExpectedDeclarationSha256: contentSHA256([]byte(declaration)),
+			NewSource:                 "func Value() int { return 2 }", FixMode: basev0.FixMode_FIX_MODE_NONE,
+		}},
+	})
+	if err != nil || !preparedResponse.GetSuccess() {
+		t.Fatalf("prepare symbol mutation: response=%+v err=%v", preparedResponse, err)
+	}
+	prepared := preparedResponse.GetPrepared()
+	permit := signPreparedMutationPermit(t, privateKey, prepared, time.Now().UTC().Add(-time.Second), time.Minute)
+	applied, err := server.ApplyPreparedMutation(t.Context(), &gatewayv1.ApplyPreparedMutationRequest{
+		Service: "app", PreparationId: prepared.GetPreparationId(),
+		MutationDigest: prepared.GetMutationDigest(), MutationPermit: permit,
+	})
+	if err != nil || !applied.GetSuccess() {
+		t.Fatalf("apply prepared mutation: response=%+v err=%v", applied, err)
+	}
+
+	patched, err := os.ReadFile(filepath.Join(root, "src", "pkg", "service.go"))
+	if err != nil || !strings.Contains(string(patched), "return 2") {
+		t.Fatalf("agent source tree was not written: content=%q err=%v", patched, err)
+	}
+	shadow, err := os.ReadFile(filepath.Join(root, "pkg", "service.go"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(shadow) != body {
+		t.Fatalf("prepared bytes landed on the service-root shadow: %q", shadow)
+	}
+}
+
+// An ephemeral source workspace is bound when no workspace configuration
+// encloses the root, and its attachment resolves back to that root — so a
+// source-dir beside it is not the declaration the agent reads, and honouring it
+// would move the gateway off the agent's tree instead of onto it.
+func TestAgentSourceRootIgnoresSourceDirWithoutAnEnclosingWorkspace(t *testing.T) {
+	root := t.TempDir()
+	writeCodeUnitFixture(t, root, "service.codefly.yaml", "name: app\nversion: 0.0.1\nspec:\n  source-dir: src\n")
+	writeCodeUnitFixture(t, root, filepath.Join("src", "keep.go"), "package keep\n")
+
+	resolved := engine.AgentSourceRoot(t.Context(), root)
+	physical, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resolved != physical && resolved != root {
+		t.Fatalf("source root = %q, want the service root %q when no workspace encloses it", resolved, root)
+	}
+}

pkg/gateway/prepared_mutation.go

@@ -305,11 +305,10 @@ func (s *Server) ApplyPreparedMutation(ctx context.Context, req *gatewayv1.Apply
 			return applyPreparedFailure(fmt.Sprintf("prepared bytes for %q are unavailable or corrupted", file.GetPath())), nil
 		}
 		// The prepared bytes were previewed, hashed and re-verified against the
-		// tree under serviceRoot(), so they must be written to that same tree.
-		// Routing this write through the agent instead would target whatever
-		// root the agent resolved (a declared source-dir moves it), writing
-		// bytes derived from one file over a different one.
-		response, err := s.rootedSourceExecute(ctx, s.serviceRoot(), &codev0.CodeRequest{Operation: &codev0.CodeRequest_WriteFile{WriteFile: &codev0.WriteFileRequest{
+		// agent's source tree, so they are written to that same tree. Writing
+		// anywhere else puts bytes derived from one file on top of another of
+		// the same name.
+		response, err := s.rootedSourceExecute(ctx, s.sourceRoot(), &codev0.CodeRequest{Operation: &codev0.CodeRequest_WriteFile{WriteFile: &codev0.WriteFileRequest{
 			Path: file.GetPath(), Content: string(after),
 		}}})
 		if err != nil || response.GetWriteFile() == nil || !response.GetWriteFile().GetSuccess() {

pkg/gateway/server.go

@@ -171,6 +171,12 @@ type Server struct {
 
 	executionRecorder   ExecutionRecorder
 	executionDispatcher ExecutionDispatcher
+
+	// resolvedSourceRoot is the agent's source tree, resolved once at
+	// construction. A declaration edited afterwards can only make it stale, and
+	// a stale root fails the prepared-mutation preview check loudly rather than
+	// writing somewhere unverified.
+	resolvedSourceRoot string
 }
 
 // serviceExecution is the transport-independent behavior consumed by the
@@ -260,6 +266,7 @@ func NewServer(cfg Config) (*Server, error) {
 		terminals:           newTerminalManager(),
 		executionRecorder:   cfg.ExecutionRecorder,
 		executionDispatcher: cfg.ExecutionDispatcher,
+		resolvedSourceRoot:  engine.AgentSourceRoot(context.Background(), cfg.WorkDir),
 	}
 
 	path := filepath.Join(cfg.WorkDir, "mind.yaml")
@@ -510,11 +517,25 @@ func pluginToAgentName(plugin string) string {
 	return plugin + ":latest"
 }
 
-// serviceRoot returns the absolute path to the service source tree.
+// serviceRoot returns the absolute path to the service directory. It is the
+// basis for VCS, terminal and code-unit paths, which are addressed relative to
+// the checkout rather than to whatever subtree holds the source.
 func (s *Server) serviceRoot() string {
 	return s.cfg.WorkDir
 }
 
+// sourceRoot returns the tree the service's agent resolves as its source root.
+// A service declaration moves it below the service directory with `source-dir`,
+// and the gateway now performs parser-derived work itself, so both sides must
+// agree on which tree they read and write. Disagreeing means previewing an edit
+// against one file and writing it to another of the same name.
+func (s *Server) sourceRoot() string {
+	if s.resolvedSourceRoot != "" {
+		return s.resolvedSourceRoot
+	}
+	return s.cfg.WorkDir
+}
+
 // controlScope returns a control-plane handle scoped to this gateway's service,
 // rooted at the service source tree. The Gateway is a thin adapter: generic
 // operations (git today) delegate to the one control plane rather than
@@ -528,8 +549,10 @@ func (s *Server) controlScope() control.ServiceScope {
 	return control.ServiceScopeAt(name, s.serviceRoot())
 }
 
+// fileOps reads and writes project bytes, so it is rooted where the agent's
+// source lives rather than at the service directory.
 func (s *Server) fileOps() codecore.FileOperation {
-	return codecore.NewFileOps(codecore.LocalVFS{}, s.serviceRoot())
+	return codecore.NewFileOps(codecore.LocalVFS{}, s.sourceRoot())
 }
 
 func (s *Server) validateService(service string) error {
@@ -1169,7 +1192,7 @@ func (s *Server) ApplySymbolPatch(ctx context.Context, req *gatewayv1.ApplySymbo
 // needs a parser — DeclarationSpans and ValidateSyntax — which is exactly why
 // it belongs in the single binary that carries the analyzer.
 func (s *Server) executeSymbolPatch(ctx context.Context, req *gatewayv1.ApplySymbolPatchRequest, rel string) (*codev0.CodeResponse, error) {
-	return s.rootedSourceExecute(ctx, s.serviceRoot(), &codev0.CodeRequest{Operation: &codev0.CodeRequest_ApplySymbolPatch{ApplySymbolPatch: &codev0.ApplySymbolPatchRequest{
+	return s.rootedSourceExecute(ctx, s.sourceRoot(), &codev0.CodeRequest{Operation: &codev0.CodeRequest_ApplySymbolPatch{ApplySymbolPatch: &codev0.ApplySymbolPatchRequest{
 		File: rel, QualifiedName: req.GetQualifiedName(), ExpectedDeclarationSha256: req.GetExpectedDeclarationSha256(),
 		NewSource: req.GetNewSource(), FixMode: req.GetFixMode(), DryRun: req.GetDryRun(),
 	}}})
@@ -1195,7 +1218,7 @@ func gatewaySymbolPatchResponse(raw *codev0.CodeResponse) *gatewayv1.ApplySymbol
 
 func (s *Server) applySymbolPatchWithReceipt(ctx context.Context, req *gatewayv1.ApplySymbolPatchRequest, rel, beforeSHA256 string, attempt *executionrecorder.Attempt) (*gatewayv1.ApplySymbolPatchResponse, error) {
 	effectStarted := time.Now()
-	raw, err := s.rootedSourceExecute(ctx, s.serviceRoot(), &codev0.CodeRequest{Operation: &codev0.CodeRequest_ApplySymbolPatch{ApplySymbolPatch: &codev0.ApplySymbolPatchRequest{
+	raw, err := s.rootedSourceExecute(ctx, s.sourceRoot(), &codev0.CodeRequest{Operation: &codev0.CodeRequest_ApplySymbolPatch{ApplySymbolPatch: &codev0.ApplySymbolPatchRequest{
 		File: rel, QualifiedName: req.GetQualifiedName(), ExpectedDeclarationSha256: req.GetExpectedDeclarationSha256(),
 		NewSource: req.GetNewSource(), FixMode: req.GetFixMode(), DryRun: false,
 	}}})
@@ -1505,7 +1528,7 @@ func (s *Server) GetProjectInfo(ctx context.Context, req *gatewayv1.GetProjectIn
 	inventory := pi.GetSourceFiles()
 	inventoryFailure := failures.Clone(resp.GetFailure())
 	if pi.GetSourceFilesOmitted() {
-		root := s.serviceRoot()
+		root := s.sourceRoot()
 		if inspected != nil {
 			root = inspected.root
 		}
@@ -1551,10 +1574,7 @@ func (s *Server) GetProjectInfo(ctx context.Context, req *gatewayv1.GetProjectIn
 // agent declined. An empty inventory without that flag is authoritative — the
 // unit genuinely has no source files — so only a declined one is refilled here.
 func (s *Server) takeSourceImports(ctx context.Context, root, language string) ([]*codev0.SourceFileInfo, error) {
-	if s.host == nil {
-		return nil, fmt.Errorf("workspace source behavior is unavailable")
-	}
-	source, err := s.host.SourceAt(root)
+	source, err := s.boundSource(root)
 	if err != nil {
 		return nil, err
 	}
@@ -1566,6 +1586,11 @@ func (s *Server) takeSourceImports(ctx context.Context, root, language string) (
 // the engine, which carries the source-semantics analyzer. Routing it to the
 // owning agent instead would make every language agent link the tree-sitter
 // CGO stack to answer an operation none of them implements.
+//
+// A source_agents entry for the unit therefore selects nothing here: the
+// projection is language-neutral and the analyzer is the same one every agent
+// would have installed. The entry still selects the agent for operations an
+// agent actually owns.
 func (s *Server) GetSemanticIndex(ctx context.Context, req *gatewayv1.GetSemanticIndexRequest) (*gatewayv1.GetSemanticIndexResponse, error) {
 	requestedService := ""
 	if req != nil {
@@ -1606,17 +1631,23 @@ func (s *Server) GetSemanticIndex(ctx context.Context, req *gatewayv1.GetSemanti
 // exact root, so a parser-derived answer describes that tree and no other. The
 // host-wide behavior of sourceExecute can sit above the root in question.
 func (s *Server) rootedSourceExecute(ctx context.Context, root string, request *codev0.CodeRequest) (*codev0.CodeResponse, error) {
-	if s.host == nil {
-		return nil, fmt.Errorf("workspace source behavior is unavailable")
-	}
-	source, err := s.host.SourceAt(root)
+	source, err := s.boundSource(root)
 	if err != nil {
 		return nil, err
 	}
 	defer func() { _ = source.Close() }()
 	return source.ExecuteCode(ctx, request)
 }
 
+// boundSource binds engine source behavior to an exact root. The caller owns
+// the result and closes it.
+func (s *Server) boundSource(root string) (*engine.Source, error) {
+	if s.host == nil {
+		return nil, fmt.Errorf("workspace source behavior is unavailable")
+	}
+	return s.host.SourceAt(root)
+}
+
 // GetSourceManifest invokes the language-neutral rooted Code behavior so every
 // workspace has the same body-free artifact inventory regardless of which
 // language agents are installed. The Gateway forwards typed identities only;