Discovery at this layer runs after runRunCommand has already made the sandbox decision from args[0]:

• resolveSandboxDefault(ctx, agentRef, ...) receives agentRef == "" on a no-arg run, so runtime.sandbox: true in a discovered docker-agent.yaml is silently ignored. The same file passed explicitly runs sandboxed.
• On a --sandbox no-arg run, runInSandbox receives an empty agentRef: the kit build is skipped and sandbox.EnvForAgent forwards nothing. The inner run only works because it re-discovers the file inside the workspace, in a degraded mode compared to an explicit path.

The --agent-picker block already solves this shape of problem by normalizing args before dispatch. Discovery can reuse that pattern in runRunCommand, right after the picker block and before resolveSandboxDefault:

if len(args) == 0 && f.remoteAddress == "" {
	if name, ok := discoverProjectDefaultAgentFile(); ok {
		args = prependAgentRef(name, args)
	}
}

resolveRunAgentFileName then reduces to the previous args[0] read, and explicit, discovered, sandboxed, and remote runs all agree on which config is in play.

Discovery is silent: nothing in the output distinguishes a run that picked ./docker-agent.yaml from one using the built-in default agent. Recording mode and worktrees both announce themselves via out.Println; a similar one-liner here keeps surprises down, and matters most for --exec where no TUI sidebar hints at the loaded agent:

out.Println("Using project config: " + agentFileName)

Printed only when the name came from discovery, not from an explicit argument.

This branch reports a candidate as discovered even though os.Stat failed (e.g. permission error), so the downstream load surfaces a real error instead of silently running the built-in default next to an unreadable docker-agent.yaml. Failing loudly seems right, but two things are missing:

• a comment: without one the code reads like a bug, and the branch also means an unreadable docker-agent.yaml shadows a readable docker-agent.yml later in the list, which is a deliberate choice worth stating
• optionally a test locking the behavior; a self-referential symlink named docker-agent.yaml triggers a non-ErrNotExist stat error portably on unix (skip on Windows)

Three more spots still describe the pre-discovery behavior and now contradict this paragraph: