Linked-worktree builds mis-stamp vcs.revision: wrong release-row revision + false stale-binary WARN (self-update path unaffected)

[linhdmn]

Summary

PR #349 added build-revision self-identification (internal/version.Revision() reads debug.ReadBuildInfo's vcs.revision) so a stale driver binary is loud. A devagent binary built inside a linked git worktree stamps the wrong commit: Go's -buildvcs resolves vcs.revision from the shared common gitdir (the primary checkout's refs/heads/main tip) instead of the worktree's own HEAD. This defeats both consumers of #349's feature — but only for linked-worktree builds (a build in a normal checkout stamps correctly; see the control below).

Evidence — same commit 8ca0688, built two ways (2026-09-12)

Linked worktree (.devagent-worktrees/…, git rev-parse HEAD = 8ca0688) — wrong:

$ go build -o /tmp/dg-wt ./cmd/devagent
$ go version -m /tmp/dg-wt | grep -E 'mod |vcs'
	mod	github.com/FreePeak/devagent	v1.13.6+dirty
	build	vcs=git
	build	vcs.revision=50b03e8d72869f066260f704b355fba112deddfa   # = primary refs/heads/main (#350 merge), predates #349
	build	vcs.time=2026-09-12T20:48:05Z                              # = #350 merge time
	build	vcs.modified=true                                          # worktree tree differs from the 50b03e8 it stamped
$ /tmp/dg-wt --version
0.1.0 (rev 50b03e8d72869f066260f704b355fba112deddfa)
$ git rev-parse HEAD
8ca0688993bf777ae74f7e11028932e33aee3e9a

Plain clone, detached at the same commit 8ca0688 (not a worktree) — correct:

$ git clone <local> /tmp/clone && git -C /tmp/clone checkout 8ca0688
$ go build -C /tmp/clone -o /tmp/dg-clone ./cmd/devagent
$ go version -m /tmp/dg-clone | grep vcs
	build	vcs=git
	build	vcs.revision=8ca0688993bf777ae74f7e11028932e33aee3e9a
	build	vcs.time=2026-09-12T21:24:20Z
	build	vcs.modified=false
$ /tmp/dg-clone --version
0.1.0 (rev 8ca0688993bf777ae74f7e11028932e33aee3e9a)   # == its own HEAD

Same source commit; non-worktree stamps 8ca0688 (modified=false), linked worktree stamps 50b03e8 (modified=true, module reported +dirty). The rev string is confirmed to originate from vcs.revision in the build-info, so this is a worktree VCS-resolution issue, not a non-buildinfo source.

Impact (scoped to linked-worktree builds)

Every devagent binary built inside this repo's per-task worktrees (task/gate builds, ad-hoc verification like this one, record release if invoked from such a binary):

1. writes a wrong revision into release-created ledger rows (ReleaseRecord.Revision) — e.g. devagent record release … from the worktree binary above recorded "revision":"50b03e8…".
2. trips RunLoop's stale-binary guard, which compares version.Revision() against git rev-parse HEAD in the loop's cwd. Built-in-worktree stamp (50b03e8) ≠ worktree HEAD (8ca0688) → false [loop] WARN: stale binary on a current binary. The guard is advisory-only (loop still runs), so the cost is a false alarm that erodes the signal Diagnosis complete: loops 290/291 died on transient infra retries mid-implement  #349 was added to provide.

The shipped self-update path is unaffected: scripts/self-update.sh does git pull --ff-only + go build -trimpath ./cmd/devagent in the primary non-worktree checkout, so the live driver stamps correctly (modified=false) and its guard behaves as intended. The live loop does not false-WARN today; the defect is latent for worktree-built binaries.

No user data is corrupted; ReleaseRecord.Tag/SHA are correct (fixed in #351) — only revision is mis-stamped, and the WARN is noise.

Suggested fix direction

Lead: follow the repo's existing -X stamp precedent (#249). .github/workflows/release.yml:134 already stamps -X github.com/FreePeak/devagent/internal/version.Version=${TAG} into every release binary precisely so --version self-reports the published release, and doctor.go:304 already special-cases the unstamped 0.1.0 default. Revision was added as a var of the same stampable shape — so add to the same ldflags:

-X github.com/FreePeak/devagent/internal/version.Revision=$(git rev-parse HEAD)

Applied in release.yml and in scripts/self-update.sh:24 (which currently builds with no -X at all), this is the one-line route that fixes both consumers: release rows name the actual writing commit, and the stale-binary guard compares a trustworthy stamp. When the build injects Revision explicitly, version.Revision() should prefer the injected value over the (possibly mis-resolved) buildinfo vcs.revision. Note RevisionOverride is already the test-only injection seam; the production stamp should ride the same path or a dedicated -X var rather than that name.

Belt-and-braces for the guard (suppresses the WARN only): Go's build-info also exposes vcs.modified, and no git plumbing is needed — go version -m showed vcs.modified=true for the linked-worktree build and false for the clone at the same commit. So the guard can WARN only when Revision() != git rev-parse HEAD and vcs.modified == false, staying quiet on worktree/+dirty builds without extra git rev-parse --absolute-git-dir/--git-common-dir calls. This preserves #349's actual target (a clean driver built from an older commit — self-update builds are clean, modified=false, so a genuinely stale seat still trips). Use it alongside the -X fix, not instead of it: on its own it leaves worktree-built release rows still naming the wrong commit.

Test gap: TestRevision only exercises the unstamped/unknown path, and CI's actions/checkout@v4 plain clone never reproduces the mis-stamp, so the suite stays green despite the defect. Add a case pinning the worktree condition (or the -X-stamped path and the modified-aware guard).

Notes

Surfaced while landing/verifying PR #349 (rebased onto 50b03e8, merged as 7aef356). Filed rather than fixed here because the remediation is a design decision for the feature owner; main is green and the tag/sha fix is independent. The 2026-09-13 PRD footer (#353, merged as 68c36cf, head d8d86fd) links this issue as #349's caveat.

[linhdmn]

Stray-work snapshot from the 2026-09-13 incident (loops 295-297 era). Two independent in-flight implementations of #352 were found uncommitted in linked worktrees after the main loop halted; both apply cleanly to main @ 68c36cf (git apply --check rc=0). The task pane for loop 297 was closed by a stray smoke-loop driver's herdr sweep at 22:59:59Z, so this work never reached a PR.

wt-smoke patch (smoke worktree, /private/tmp/wt-smoke — 2 files: Makefile, internal/version/version.go, 162 lines)

diff --git a/Makefile b/Makefile
index 17aa2dd..76583a0 100644
--- a/Makefile
+++ b/Makefile
@@ -167,8 +167,16 @@ orca-quit:
 #   make build    # ./devagent-go — the production CLI
 #
 # The unstamped default in internal/version is 0.1.0; release tooling stamps
-# the version at publish time, so local builds stay unstamped.
+# the version at publish time, so local builds stay unstamped. The revision is
+# stamped here instead of left to Go's -buildvcs, because in a linked git
+# worktree -buildvcs resolves vcs.revision from the shared common gitdir and
+# stamps the primary checkout's tip rather than this checkout's HEAD (#352) —
+# a wrong release-row revision plus a false stale-binary WARN. An empty REV
+# (no git, no commits yet) leaves RevisionStamped unset and the build falls
+# back to the build info.
+REV = $(shell git rev-parse HEAD 2>/dev/null)
+GO_LDFLAGS = -X github.com/FreePeak/devagent/internal/version.RevisionStamped=$(REV)
 
 .PHONY: build
 build:
-	go build -trimpath -o devagent-go ./cmd/devagent
+	go build -trimpath -ldflags "$(GO_LDFLAGS)" -o devagent-go ./cmd/devagent
diff --git a/internal/version/version.go b/internal/version/version.go
index a8a554b..d4761e8 100644
--- a/internal/version/version.go
+++ b/internal/version/version.go
@@ -11,40 +11,114 @@ import (
 // build time; the unstamped default stays 0.1.0.
 var Version = "0.1.0"
 
-// RevisionUnknown is what Revision returns when the binary was built
-// without a VCS stamp (go-test binaries, builds from a tarball): it cannot
-// prove which commit it drives, so consumers must not treat it as clean.
+// RevisionUnknown is what Revision returns when the binary carries no VCS
+// stamp at all (go-test binaries, builds from a tarball): it cannot prove
+// which commit it drives, so consumers must not treat it as clean.
 const RevisionUnknown = "unknown"
 
+// RevisionStamped is the build revision injected by the build recipe with
+// -ldflags "-X github.com/FreePeak/devagent/internal/version.RevisionStamped=$(git rev-parse HEAD)".
+// It beats the build info's own vcs.revision because that stamp cannot be
+// trusted inside a linked git worktree: Go resolves vcs.revision from the
+// shared common gitdir, so such a build names the primary checkout's branch
+// tip instead of its own HEAD (issue #352). The recipe that compiled the
+// binary knows which checkout it built, so its injected value is the
+// authoritative one. A var of the same stampable shape as Version; an
+// unstamped build leaves it empty.
+var RevisionStamped string
+
 // RevisionOverride injects the build revision in tests — go-test binaries
 // carry no vcs.revision build setting, so the real stamp is unreachable
-// there. A non-empty value wins over the memoized build info; production
-// leaves it empty (same stampable-var shape as Version).
+// there. A non-empty value wins over every other source (same stampable-var
+// shape as Version).
 var RevisionOverride string
 
+// ModifiedOverride injects the build info's vcs.modified answer in tests: a
+// go-test binary carries no vcs.* build setting at all (probed 2026-09-12),
+// so the real flag is unreachable there. nil — what production always leaves
+// it — reads the build info.
+var ModifiedOverride *bool
+
 var (
-	revisionOnce sync.Once
-	revisionMemo string
+	stampOnce    sync.Once
+	stampRevMemo string
+	stampModMemo bool
 )
 
-// Revision returns the VCS revision the binary was built from
-// (debug.ReadBuildInfo's vcs.revision), memoized on first call, or
-// RevisionUnknown when the build carries no stamp.
-func Revision() string {
-	revisionOnce.Do(func() {
-		rev := RevisionUnknown
+// buildStamp returns the vcs.revision / vcs.modified pair the binary was
+// compiled with, memoized on first call. An unstamped build reports the empty
+// revision and modified=false — absence of evidence of a dirty tree, not
+// proof of a clean one, which is why Revision must still be checked against
+// RevisionUnknown before this pair means anything.
+func buildStamp() (rev string, modified bool) {
+	stampOnce.Do(func() {
 		if bi, ok := debug.ReadBuildInfo(); ok {
 			for _, s := range bi.Settings {
-				if s.Key == "vcs.revision" && s.Value != "" {
-					rev = s.Value
-					break
+				switch s.Key {
+				case "vcs.revision":
+					if s.Value != "" {
+						stampRevMemo = s.Value
+					}
+				case "vcs.modified":
+					stampModMemo = s.Value == "true"
 				}
 			}
 		}
-		revisionMemo = rev
 	})
-	if RevisionOverride != "" {
-		return RevisionOverride
+	return stampRevMemo, stampModMemo
+}
+
+// Revision returns the VCS revision the binary was built from: the -X
+// RevisionStamped when the build recipe injected one, otherwise
+// debug.ReadBuildInfo's vcs.revision, or RevisionUnknown when the build
+// carries neither stamp.
+func Revision() string {
+	rev, _ := buildStamp()
+	return chooseRevision(RevisionOverride, RevisionStamped, rev)
+}
+
+// chooseRevision picks the first non-empty source in precedence order — test
+// override, -X stamp, build info — falling back to RevisionUnknown. Split out
+// so the ordering (the #352 fix) is testable without a stamped binary.
+func chooseRevision(override, stamped, buildInfo string) string {
+	for _, rev := range []string{override, stamped, buildInfo} {
+		if rev != "" {
+			return rev
+		}
+	}
+	return RevisionUnknown
+}
+
+// RevisionTrusted reports whether Revision() names the exact commit this
+// binary was built from, so a caller may compare it against `git rev-parse
+// HEAD` and treat a difference as evidence of staleness:
+//
+//   - no stamp at all is never trusted;
+//   - an -X RevisionStamped is always trusted — the build recipe resolved
+//     HEAD in the checkout it compiled, which is exactly what survives the
+//     linked-worktree mis-resolve of #352;
+//   - a revision that came from the build info is trusted only while
+//     vcs.modified is false: a modified tree is the worktree/+dirty shape
+//     where vcs.revision can describe a commit this source was never built
+//     from, so a mismatch against HEAD proves nothing.
+func RevisionTrusted() bool {
+	if Revision() == RevisionUnknown {
+		return false
+	}
+	if RevisionStamped != "" {
+		return true
+	}
+	return !RevisionModified()
+}
+
+// RevisionModified reports whether the tree this binary was compiled from
+// carried uncommitted changes relative to its stamped revision, per the build
+// info's vcs.modified. False when the build carries no such setting (go test,
+// -buildvcs=off) or when it reports false.
+func RevisionModified() bool {
+	if ModifiedOverride != nil {
+		return *ModifiedOverride
 	}
-	return revisionMemo
+	_, modified := buildStamp()
+	return modified
 }

[linhdmn]

TASK-mtyxiu6m-ife2 patch (task worktree — 9 files incl. internal/version/version.go, internal/loopdriver/run.go, internal/pipeline/consume.go, scripts/self-update.sh, 470 lines)

diff --git a/Makefile b/Makefile
index 17aa2dd..76583a0 100644
--- a/Makefile
+++ b/Makefile
@@ -167,8 +167,16 @@ orca-quit:
 #   make build    # ./devagent-go — the production CLI
 #
 # The unstamped default in internal/version is 0.1.0; release tooling stamps
-# the version at publish time, so local builds stay unstamped.
+# the version at publish time, so local builds stay unstamped. The revision is
+# stamped here instead of left to Go's -buildvcs, because in a linked git
+# worktree -buildvcs resolves vcs.revision from the shared common gitdir and
+# stamps the primary checkout's tip rather than this checkout's HEAD (#352) —
+# a wrong release-row revision plus a false stale-binary WARN. An empty REV
+# (no git, no commits yet) leaves RevisionStamped unset and the build falls
+# back to the build info.
+REV = $(shell git rev-parse HEAD 2>/dev/null)
+GO_LDFLAGS = -X github.com/FreePeak/devagent/internal/version.RevisionStamped=$(REV)
 
 .PHONY: build
 build:
-	go build -trimpath -o devagent-go ./cmd/devagent
+	go build -trimpath -ldflags "$(GO_LDFLAGS)" -o devagent-go ./cmd/devagent
diff --git a/docs/PRD.md b/docs/PRD.md
index c121673..2448453 100644
--- a/docs/PRD.md
+++ b/docs/PRD.md
@@ -1695,7 +1695,7 @@ existing driver with validation surfaces (test, command, telemetry, chaos
 schedule) so "the driver works perfectly" is a checkable claim, not a hope.
 
 ---
-*Last updated: 2026-09-13 (caveat on #349's revision stamp: linked-worktree builds mis-stamp — [#352](https://github.com/FreePeak/devagent/issues/352)) — while verifying #349's landing we found Go's `-buildvcs` resolves `vcs.revision` from the shared common gitdir in a linked worktree, so a `devagent` binary built inside a per-task worktree stamps the primary checkout's `refs/heads/main` tip rather than its own HEAD (`vcs.modified=true`). Proven A/B at the same commit `8ca0688`: a plain clone stamps `8ca0688`, a linked worktree stamps `50b03e8`. Scope: this is a latent defect confined to *worktree-built* binaries — the shipped driver is built by `scripts/self-update.sh` from the primary non-worktree checkout (`go build -trimpath ./cmd/devagent` after `git pull --ff-only`), so it stamps correctly and `RunLoop`'s stale-binary guard behaves as intended in the live loop; only a manually-built worktree binary writes a wrong `release-created` revision and false-trips the (advisory-only) WARN. #349's "a stale binary is loud" holds for the normal-checkout build path; the worktree edge is tracked in #352.
+*Last updated: 2026-09-13 (issue #352 fixed: linked-worktree builds no longer mis-stamp the revision) — #349 relied on Go's `-buildvcs`, which resolves `vcs.revision` from the shared common gitdir inside a linked worktree, so a `devagent` binary built in a per-task worktree stamped the primary checkout's `refs/heads/main` tip instead of its own HEAD: a wrong `revision` in `release-created` rows plus a false `[loop] WARN: stale binary` on a current binary. Fixed at the shared build recipe: `make build` (Makefile `REV`/`GO_LDFLAGS`) and the shell `scripts/self-update.sh` (now delegating to `make build`) stamp `-X github.com/FreePeak/devagent/internal/version.RevisionStamped=$(git rev-parse HEAD)`, and the Go-side `cnsRunSelfUpdate` — the path the live factory driver rebuilds itself with, where `make` is absent on Windows runners — injects the same `-X` from its own post-pull `git rev-parse HEAD`. `version.Revision()` prefers that recipe-resolved stamp over the build info (`chooseRevision`: override → `-X` stamp → build info), so a stamped binary names the commit its recipe resolved. The stale-binary guard is now `version.RevisionTrusted()`-gated: a build-info-only revision warns on a mismatch only while `vcs.modified` is false (the clean-checkout shape), the worktree/`+dirty` shape stays silent because that stamp describes some other checkout, and a `-X`-stamped revision is trusted even on a dirty tree so real staleness (loops 290/291) still WARNs. Proven hermetically by `TestChooseRevisionPrecedence`/`TestRevisionStampedWins`/`TestRevisionTrusted` (guard arms: modified=true silent, modified=false WARNs) + `TestCnsSelfUpdateGreenPath`, and by an out-of-band linked-worktree `make build` smoke: `loop --dry-run` prints no stale-binary WARN and `--version`/`record release` name the worktree HEAD. Supersedes the caveat filed with #353.
 *Last updated: 2026-09-13 (release-created rows carry `tag`/`sha` again: PR #349's Revision stamp landed as a silent data-loss regression) — #349 added a `Revision` field to the Go `ReleaseRecord` but dropped `Tag`/`SHA` from the `record release` literal while still printing `(tag @ sha)` to stdout, so every Go-written release row persisted `"tag":""` `"sha":""` (the Q24 fields the record exists to carry) and no test covered the write site, so it shipped green. Restored both fields; `internal/cli/actions_release_test.go` now pins the CLI row shape (proven red on the regressed literal, green after); regenerated `docs/PRD.html` so the styled mirror matches `PRD.md`.
 *Last updated: 2026-09-13 (herdr orphan-pane reaping: both probes were dead, repaired as one change) — `devagent herdr-sweep --orphans` had never reaped a live orphan: `pane process-info` went out without `--session`, so herdr answered for its own default session and "no such pane" was every devagent pane's liveness, which left the FR-VIS-07 in-flight guard, the FR-VIS-02 roster upgrade (#317) and the orphan class — gated on a live foreground worker — inert at once; the owner probe was `herdr.*pane run .*<pane_id>`, a process that does not exist while a pane runs (`pane run` types the script into the pane's shell and exits; verified live parent chain `omp -> -zsh -> herdr --session <s> server -> launchd`), so `PaneRunOwnerOrphaned` always took its "no owner CLI -> orphaned" exit and the driver spare behind it was unreachable. Each half alone is a regression — a working owner probe over an inert liveness probe closes live workers — so the fix lands atomically: `PaneForegroundWorker(cli, session, paneID)` scopes the probe (roster and sweep share it), the owner is now the surviving dispatcher (argv0-anchored `devagent`/`devagent-go` `task`/`pane-run`, optionally behind the driver's `timeout` wrapper, so a prompt quoting devagent cannot impersonate its own collector), non-worktree panes need positive per-pane dispatch evidence (the capture contract on the worker's fd 1/2), and the orphan class moved ahead of the roster spare. Reaping also fails closed: `psPidsMatching` and `pidAncestryCommands` now report whether the probe answered at all — pgrep's exit-1 "no match" is an answer (no collector, reap), an absent binary / the 5s cap / a rejected pattern / an unfinished ancestry walk is not (spare) — because a reaper that read "could not inspect" as "no collector" would close every live pane on such a host. Test seams: `DEVAGENT_SWEEP_OWNER_PIDS_JSON` is keyed by the pattern asked for and a miss now counts as an unanswered probe (never a clean no-match), `DEVAGENT_SWEEP_PANE_CAPTURE_JSON` supplies pane-keyed evidence — and because the 2026-09-13 bug survived a green stub suite, both shapes are pinned from outside: `TestProcFdsCaptureSeesRealCaptureContract` runs the real `lsof` probe against a live child holding `<tmp>/devagent-herdr-<n>/out` on fd 1/2 (skipped where lsof is absent), `TestPaneRunOwnerPatternMatchesRealDispatchShapes` checks `paneRunOwnerPattern` against the command lines `internal/loopdriver` really builds and against the transient `herdr pane run` shape it used to search for, and `TestOrphanClassGoesInertWhenProbesCannotAnswer` pins the spare-on-no-answer direction at the matrix level. `TestPsPidsMatchingAnswersOnlyWhenPgrepAnswers` pins the same split against real `pgrep` exit codes: 1 means no collector (reap), 2 means the probe could not run (spare). Docs corrected: FR-VIS-02/07/10, §18 Q23, `docs/HERDR.md` sweep safety.
 *Last updated: 2026-09-12 (build-revision self-identification: a stale driver binary is loud, and Go-written release rows name their writer) — loops 290/291 burned implement-and-gate cycles while the driver seat ran a binary built from an older commit, and nothing announced the mismatch. `internal/version.Revision()` (new, memoized) reads `debug.ReadBuildInfo`'s `vcs.revision` and returns `version.RevisionUnknown` (`"unknown"`) when the build carries no stamp — go-test binaries carry none (probed 2026-09-12), so `version.RevisionOverride` is the injection seam. `RunLoop` compares `Revision()` against `git rev-parse HEAD` before the first iteration and warns `[loop] WARN: stale binary` when the revision is unknown or differs, naming both SHAs (advisory only: the loop still runs). `ledger.ReleaseRecord` gains `revision` (stamped at the `record release` write site; `omitempty` keeps unstamped Go rows byte-compatible with the TS writer — Node readers tolerate the extra key, pinned by `TestSchemaDriftUnknownFieldsTolerated`), and `devagent --version` prints `0.1.0 (rev <sha>)`. Pinned by `TestRevision` (sentinel, memoization, override) and `TestRunLoopStaleBinaryWarns` (unknown warn, mismatch warn, matching-revision silence, rc 0 on every arm).
diff --git a/internal/loopdriver/run.go b/internal/loopdriver/run.go
index 7bd2bec..c899263 100644
--- a/internal/loopdriver/run.go
+++ b/internal/loopdriver/run.go
@@ -93,9 +93,17 @@ func RunLoop(cfg LoopConfig) int {
 	// gate cycles while a driver built from an older commit held the loop
 	// seat, and nothing announced the mismatch. Advisory only — the warning
 	// names both sides and the loop still runs.
+	//
+	// A mismatch warns only when the revision is trustworthy (#352): Go's
+	// -buildvcs resolves vcs.revision from the shared common gitdir, so a
+	// binary built inside a linked worktree stamps the primary checkout's
+	// branch tip with vcs.modified=true, and comparing that against this
+	// checkout's HEAD cries stale on a current binary. Builds stamped with
+	// -X (make build, self-update) carry a revision the recipe resolved in
+	// the very checkout it compiled, so their mismatch is the real signal.
 	if rev := version.Revision(); rev == version.RevisionUnknown {
 		_, _ = fmt.Fprintln(cfg.Stderr, "[loop] WARN: stale binary: build carries no revision (go test / unstamped build) — rebuild with `make build` before trusting this loop")
-	} else if head, ok := d.gitQuiet("rev-parse", "HEAD"); ok && strings.TrimSpace(head) != rev {
+	} else if head, ok := d.gitQuiet("rev-parse", "HEAD"); ok && strings.TrimSpace(head) != rev && version.RevisionTrusted() {
 		_, _ = fmt.Fprintf(cfg.Stderr, "[loop] WARN: stale binary: built from %s, repo HEAD is %s — rebuild with `make build`\n", rev, strings.TrimSpace(head))
 	}
 
diff --git a/internal/loopdriver/run_test.go b/internal/loopdriver/run_test.go
index 458fffb..6138a2d 100644
--- a/internal/loopdriver/run_test.go
+++ b/internal/loopdriver/run_test.go
@@ -2184,13 +2184,23 @@ func TestRunLoopRejectsMalformedGoalShape(t *testing.T) {
 }
 
 // TestRunLoopStaleBinaryWarns pins the driver's self-identification guard
-// (2026-09-12): a binary that cannot name its revision — the go-test binary
-// is exactly that shape — must WARN at startup; a revision differing from
-// the fixture HEAD must WARN naming both sides; a matching revision stays
-// quiet. The warn is advisory: every arm still runs and exits 0.
+// (2026-09-12, modified-aware for #352): a binary that cannot name its
+// revision — the go-test binary is exactly that shape — must WARN at
+// startup; a trustworthy revision differing from the fixture HEAD must WARN
+// naming both sides, including when the build tree was dirty; the linked-
+// worktree shape (a build-info revision on a tree Go stamped modified, which
+// describes some other checkout) stays quiet; and a matching revision warns
+// nowhere. The warn is advisory: every arm still runs and exits 0.
 func TestRunLoopStaleBinaryWarns(t *testing.T) {
-	old := version.RevisionOverride
-	t.Cleanup(func() { version.RevisionOverride = old })
+	oldRev, oldStamped := version.RevisionOverride, version.RevisionStamped
+	oldModified := version.ModifiedOverride
+	t.Cleanup(func() {
+		version.RevisionOverride, version.RevisionStamped = oldRev, oldStamped
+		version.ModifiedOverride = oldModified
+	})
+
+	const foreignRev = "0000000000000000000000000000000000000000"
+	dirty, clean := true, false
 
 	// committedFixture returns a fixture repo with one commit plus its HEAD.
 	committedFixture := func() (string, string) {
@@ -2227,27 +2237,52 @@ func TestRunLoopStaleBinaryWarns(t *testing.T) {
 		return RunLoop(cfg), stderr.String()
 	}
 
+	warned := func(out string) bool { return strings.Contains(out, "WARN: stale binary") }
+
 	// Arm 1 — unknown revision (the go-test binary's own shape).
-	version.RevisionOverride = ""
+	version.RevisionOverride, version.RevisionStamped, version.ModifiedOverride = "", "", nil
 	repo, _ := committedFixture()
 	if rc, out := runLoop(repo); rc != 0 {
 		t.Fatalf("rc = %d, want 0 (the warn is advisory)", rc)
-	} else if !strings.Contains(out, "WARN: stale binary") || !strings.Contains(out, "no revision") {
+	} else if !warned(out) || !strings.Contains(out, "no revision") {
 		t.Fatalf("unstamped warn missing from stderr:\n%s", out)
 	}
 
-	// Arm 2 — revision differs from HEAD.
-	version.RevisionOverride = "0000000000000000000000000000000000000000"
+	// Arm 2 — build-info revision differs from HEAD on a clean tree: the one
+	// shape where a mismatch is evidence, so it names both sides.
+	version.RevisionOverride, version.RevisionStamped, version.ModifiedOverride = foreignRev, "", &clean
 	repo, _ = committedFixture()
 	if rc, out := runLoop(repo); rc != 0 {
 		t.Fatalf("rc = %d, want 0 (the warn is advisory)", rc)
-	} else if !strings.Contains(out, "WARN: stale binary") || !strings.Contains(out, "repo HEAD is") {
+	} else if !warned(out) || !strings.Contains(out, "repo HEAD is") {
 		t.Fatalf("mismatch warn missing from stderr:\n%s", out)
 	}
 
-	// Arm 3 — matching revision: quiet, a current binary warns nowhere.
+	// Arm 3 — the #352 false alarm: a build-info revision stamped by Go from
+	// a linked worktree names another checkout and reports the tree modified.
+	// Quiet, because that stamp proves nothing about this HEAD.
+	version.RevisionOverride, version.RevisionStamped, version.ModifiedOverride = foreignRev, "", &dirty
 	repo, head := committedFixture()
-	version.RevisionOverride = head
+	if rc, out := runLoop(repo); rc != 0 {
+		t.Fatalf("rc = %d, want 0 (the warn is advisory)", rc)
+	} else if strings.Contains(out, "stale binary") {
+		t.Fatalf("modified build-info stamp false-warned on %s:\n%s", head, out)
+	}
+
+	// Arm 4 — an -X stamped revision is authoritative even on a dirty tree:
+	// the recipe resolved HEAD itself, so a mismatch is the real stale signal
+	// loops 290/291 needed.
+	version.RevisionOverride, version.RevisionStamped, version.ModifiedOverride = "", foreignRev, &dirty
+	repo, head = committedFixture()
+	if rc, out := runLoop(repo); rc != 0 {
+		t.Fatalf("rc = %d, want 0 (the warn is advisory)", rc)
+	} else if !warned(out) || !strings.Contains(out, head[:7]) {
+		t.Fatalf("stamped mismatch warn missing or unnamed from stderr:\n%s", out)
+	}
+
+	// Arm 5 — matching stamped revision: quiet, a current binary warns
+	// nowhere even while its worktree is dirty.
+	version.RevisionOverride, version.RevisionStamped, version.ModifiedOverride = "", head, &dirty
 	if rc, out := runLoop(repo); rc != 0 {
 		t.Fatalf("rc = %d, want 0 (the warn is advisory)", rc)
 	} else if strings.Contains(out, "stale binary") {
diff --git a/internal/pipeline/consume.go b/internal/pipeline/consume.go
index cfa1c12..ca8a047 100644
--- a/internal/pipeline/consume.go
+++ b/internal/pipeline/consume.go
@@ -945,9 +945,26 @@ func cnsRunSelfUpdate(repoPath string, log RunLog) error {
 	}
 	steps = append(steps, "pull")
 
-	// 3) rebuild the Go binary (the make build target's exact recipe; the
-	// unstamped internal/version default is 0.1.0)
-	build := run("go", []string{"build", "-trimpath", "-o", "devagent-go", "./cmd/devagent"}, 120_000)
+	// 3) rebuild the Go binary, stamping the revision the way `make build`
+	// does (#352): -buildvcs resolves vcs.revision from the shared common
+	// gitdir inside a linked worktree, so the build recipe must resolve HEAD
+	// in this checkout and inject it via -X RevisionStamped. It resolves HEAD
+	// after the pull so the stamp names the commit actually compiled. `make`
+	// is absent on the Windows runners this path may build on, so the stamp
+	// goes straight to go rather than through the make target — the same
+	// -X revision the Makefile passes. An unresolvable HEAD (no git) falls
+	// back to the unstamped default, which RevisionTrusted treats as unknown.
+	sha := ""
+	if head := run("git", []string{"rev-parse", "HEAD"}, 10_000); !head.TimedOut && head.ExitCode == 0 {
+		sha = strings.TrimSpace(head.Stdout)
+	}
+	buildArgs := []string{"build", "-trimpath", "-o", "devagent-go", "./cmd/devagent"}
+	if sha != "" {
+		buildArgs = []string{"build", "-trimpath",
+			"-ldflags", "-X github.com/FreePeak/devagent/internal/version.RevisionStamped=" + sha,
+			"-o", "devagent-go", "./cmd/devagent"}
+	}
+	build := run("go", buildArgs, 120_000)
 	if build.TimedOut || build.ExitCode != 0 {
 		return fmt.Errorf("self-update: go build failed")
 	}
diff --git a/internal/pipeline/consume_test.go b/internal/pipeline/consume_test.go
index c5afff9..d254a24 100644
--- a/internal/pipeline/consume_test.go
+++ b/internal/pipeline/consume_test.go
@@ -695,9 +695,13 @@ func TestCnsSelfUpdateDirtyWorktreeSkips(t *testing.T) {
 
 func TestCnsSelfUpdateGreenPath(t *testing.T) {
 	oldRunner := cnsSelfUpdateRunner
+	const headSHA = "8ca0688993bf777ae74f7e11028932e33aee3e9a"
 	var calls []string
 	cnsSelfUpdateRunner = func(cmd string, args []string, opts spawn.Options) spawn.Result {
 		calls = append(calls, cmd+" "+strings.Join(args, " "))
+		if cmd == "git" && len(args) > 1 && args[0] == "rev-parse" && args[1] == "HEAD" {
+			return spawn.Result{ExitCode: 0, Stdout: headSHA + "\n"}
+		}
 		return spawn.Result{ExitCode: 0}
 	}
 	t.Cleanup(func() { cnsSelfUpdateRunner = oldRunner })
@@ -706,11 +710,19 @@ func TestCnsSelfUpdateGreenPath(t *testing.T) {
 	if err := cnsRunSelfUpdate("/tmp/ignored", rec); err != nil {
 		t.Fatal(err)
 	}
-	if len(calls) < 3 || !strings.HasPrefix(calls[0], "git status --porcelain") ||
+	// status -> pull -> rev-parse HEAD -> stamped go build. The stamp is the
+	// #352 fix: the recipe resolves HEAD in this checkout so a linked-worktree
+	// rebuild names its own commit, not the shared gitdir tip.
+	if len(calls) < 4 || !strings.HasPrefix(calls[0], "git status --porcelain") ||
 		!strings.HasPrefix(calls[1], "git pull --ff-only") ||
-		!strings.HasPrefix(calls[2], "go build -trimpath -o devagent-go") {
+		!strings.HasPrefix(calls[2], "git rev-parse HEAD") {
 		t.Fatalf("calls = %v", calls)
 	}
+	build := calls[3]
+	if !strings.HasPrefix(build, "go build -trimpath -ldflags -X github.com/FreePeak/devagent/internal/version.RevisionStamped="+headSHA) ||
+		!strings.HasSuffix(build, " -o devagent-go ./cmd/devagent") {
+		t.Fatalf("stamped go build call = %q", build)
+	}
 	found := false
 	for _, e := range rec.entries {
 		if e.Level == "info" && strings.HasPrefix(e.Message, "self-update ok: pull -> build") {
diff --git a/internal/version/version.go b/internal/version/version.go
index a8a554b..d4761e8 100644
--- a/internal/version/version.go
+++ b/internal/version/version.go
@@ -11,40 +11,114 @@ import (
 // build time; the unstamped default stays 0.1.0.
 var Version = "0.1.0"
 
-// RevisionUnknown is what Revision returns when the binary was built
-// without a VCS stamp (go-test binaries, builds from a tarball): it cannot
-// prove which commit it drives, so consumers must not treat it as clean.
+// RevisionUnknown is what Revision returns when the binary carries no VCS
+// stamp at all (go-test binaries, builds from a tarball): it cannot prove
+// which commit it drives, so consumers must not treat it as clean.
 const RevisionUnknown = "unknown"
 
+// RevisionStamped is the build revision injected by the build recipe with
+// -ldflags "-X github.com/FreePeak/devagent/internal/version.RevisionStamped=$(git rev-parse HEAD)".
+// It beats the build info's own vcs.revision because that stamp cannot be
+// trusted inside a linked git worktree: Go resolves vcs.revision from the
+// shared common gitdir, so such a build names the primary checkout's branch
+// tip instead of its own HEAD (issue #352). The recipe that compiled the
+// binary knows which checkout it built, so its injected value is the
+// authoritative one. A var of the same stampable shape as Version; an
+// unstamped build leaves it empty.
+var RevisionStamped string
+
 // RevisionOverride injects the build revision in tests — go-test binaries
 // carry no vcs.revision build setting, so the real stamp is unreachable
-// there. A non-empty value wins over the memoized build info; production
-// leaves it empty (same stampable-var shape as Version).
+// there. A non-empty value wins over every other source (same stampable-var
+// shape as Version).
 var RevisionOverride string
 
+// ModifiedOverride injects the build info's vcs.modified answer in tests: a
+// go-test binary carries no vcs.* build setting at all (probed 2026-09-12),
+// so the real flag is unreachable there. nil — what production always leaves
+// it — reads the build info.
+var ModifiedOverride *bool
+
 var (
-	revisionOnce sync.Once
-	revisionMemo string
+	stampOnce    sync.Once
+	stampRevMemo string
+	stampModMemo bool
 )
 
-// Revision returns the VCS revision the binary was built from
-// (debug.ReadBuildInfo's vcs.revision), memoized on first call, or
-// RevisionUnknown when the build carries no stamp.
-func Revision() string {
-	revisionOnce.Do(func() {
-		rev := RevisionUnknown
+// buildStamp returns the vcs.revision / vcs.modified pair the binary was
+// compiled with, memoized on first call. An unstamped build reports the empty
+// revision and modified=false — absence of evidence of a dirty tree, not
+// proof of a clean one, which is why Revision must still be checked against
+// RevisionUnknown before this pair means anything.
+func buildStamp() (rev string, modified bool) {
+	stampOnce.Do(func() {
 		if bi, ok := debug.ReadBuildInfo(); ok {
 			for _, s := range bi.Settings {
-				if s.Key == "vcs.revision" && s.Value != "" {
-					rev = s.Value
-					break
+				switch s.Key {
+				case "vcs.revision":
+					if s.Value != "" {
+						stampRevMemo = s.Value
+					}
+				case "vcs.modified":
+					stampModMemo = s.Value == "true"
 				}
 			}
 		}
-		revisionMemo = rev
 	})
-	if RevisionOverride != "" {
-		return RevisionOverride
+	return stampRevMemo, stampModMemo
+}
+
+// Revision returns the VCS revision the binary was built from: the -X
+// RevisionStamped when the build recipe injected one, otherwise
+// debug.ReadBuildInfo's vcs.revision, or RevisionUnknown when the build
+// carries neither stamp.
+func Revision() string {
+	rev, _ := buildStamp()
+	return chooseRevision(RevisionOverride, RevisionStamped, rev)
+}
+
+// chooseRevision picks the first non-empty source in precedence order — test
+// override, -X stamp, build info — falling back to RevisionUnknown. Split out
+// so the ordering (the #352 fix) is testable without a stamped binary.
+func chooseRevision(override, stamped, buildInfo string) string {
+	for _, rev := range []string{override, stamped, buildInfo} {
+		if rev != "" {
+			return rev
+		}
+	}
+	return RevisionUnknown
+}
+
+// RevisionTrusted reports whether Revision() names the exact commit this
+// binary was built from, so a caller may compare it against `git rev-parse
+// HEAD` and treat a difference as evidence of staleness:
+//
+//   - no stamp at all is never trusted;
+//   - an -X RevisionStamped is always trusted — the build recipe resolved
+//     HEAD in the checkout it compiled, which is exactly what survives the
+//     linked-worktree mis-resolve of #352;
+//   - a revision that came from the build info is trusted only while
+//     vcs.modified is false: a modified tree is the worktree/+dirty shape
+//     where vcs.revision can describe a commit this source was never built
+//     from, so a mismatch against HEAD proves nothing.
+func RevisionTrusted() bool {
+	if Revision() == RevisionUnknown {
+		return false
+	}
+	if RevisionStamped != "" {
+		return true
+	}
+	return !RevisionModified()
+}
+
+// RevisionModified reports whether the tree this binary was compiled from
+// carried uncommitted changes relative to its stamped revision, per the build
+// info's vcs.modified. False when the build carries no such setting (go test,
+// -buildvcs=off) or when it reports false.
+func RevisionModified() bool {
+	if ModifiedOverride != nil {
+		return *ModifiedOverride
 	}
-	return revisionMemo
+	_, modified := buildStamp()
+	return modified
 }
diff --git a/internal/version/version_test.go b/internal/version/version_test.go
index 2a51b85..c4b47dd 100644
--- a/internal/version/version_test.go
+++ b/internal/version/version_test.go
@@ -43,3 +43,84 @@ func TestRevision(t *testing.T) {
 		t.Fatalf("Revision() = %q, want the override deadbeef", got)
 	}
 }
+
+// TestChooseRevisionPrecedence pins the #352 fix's ordering on the pure
+// chooser: a -X RevisionStamped must beat the build info's vcs.revision,
+// because in a linked worktree that setting names a commit this source was
+// never built from. The build info cannot be given a real value under go
+// test (nothing is stamped), so the wiring is proved separately by
+// TestRevisionStampedWins.
+func TestChooseRevisionPrecedence(t *testing.T) {
+	const (
+		buildInfoRev = "1111111111111111111111111111111111111111"
+		stampedRev   = "2222222222222222222222222222222222222222"
+		overrideRev  = "3333333333333333333333333333333333333333"
+	)
+	cases := []struct {
+		name                         string
+		override, stamped, buildInfo string
+		want                         string
+	}{
+		{"nothing stamped", "", "", "", RevisionUnknown},
+		{"build info alone", "", "", buildInfoRev, buildInfoRev},
+		{"stamp beats build info", "", stampedRev, buildInfoRev, stampedRev},
+		{"stamp with no build info", "", stampedRev, "", stampedRev},
+		{"override beats the stamp", overrideRev, stampedRev, buildInfoRev, overrideRev},
+	}
+	for _, tc := range cases {
+		if got := chooseRevision(tc.override, tc.stamped, tc.buildInfo); got != tc.want {
+			t.Errorf("%s: chooseRevision(%q, %q, %q) = %q, want %q",
+				tc.name, tc.override, tc.stamped, tc.buildInfo, got, tc.want)
+		}
+	}
+}
+
+// TestRevisionStampedWins proves the same ordering through the exported
+// surface: with RevisionStamped set (what -X does at build time) Revision()
+// reports it instead of falling through to RevisionUnknown, which is all the
+// unstamped go-test binary can offer as the build-info side.
+func TestRevisionStampedWins(t *testing.T) {
+	oldOverride, oldStamped := RevisionOverride, RevisionStamped
+	t.Cleanup(func() { RevisionOverride, RevisionStamped = oldOverride, oldStamped })
+
+	RevisionOverride = ""
+	RevisionStamped = "2222222222222222222222222222222222222222"
+	if got := Revision(); got != RevisionStamped {
+		t.Fatalf("Revision() = %q, want the stamped %q", got, RevisionStamped)
+	}
+}
+
+// TestRevisionTrusted pins when Revision() may be compared against HEAD.
+// Under go test RevisionOverride stands in for a build-info-sourced revision,
+// so: no stamp at all is untrusted, a clean-tree build info is trusted, and
+// the linked-worktree shape (#352: build info revision + modified tree) is
+// not — its revision describes some other checkout. A -X stamp is trusted
+// even on a dirty tree, because the recipe resolved HEAD itself.
+func TestRevisionTrusted(t *testing.T) {
+	oldOverride, oldStamped, oldModified := RevisionOverride, RevisionStamped, ModifiedOverride
+	yes, no := true, false
+	t.Cleanup(func() {
+		RevisionOverride, RevisionStamped, ModifiedOverride = oldOverride, oldStamped, oldModified
+	})
+
+	cases := []struct {
+		name     string
+		override string
+		stamped  string
+		modified *bool
+		want     bool
+	}{
+		{"no stamp at all", "", "", &no, false},
+		{"build info, clean tree", "1111111111111111111111111111111111111111", "", &no, true},
+		{"build info, modified tree (#352)", "1111111111111111111111111111111111111111", "", &yes, false},
+		{"-X stamp, modified tree", "", "2222222222222222222222222222222222222222", &yes, true},
+		{"-X stamp beats the build info", "3333333333333333333333333333333333333333", "2222222222222222222222222222222222222222", &yes, true},
+	}
+	for _, tc := range cases {
+		RevisionOverride, RevisionStamped, ModifiedOverride = tc.override, tc.stamped, tc.modified
+		if got := RevisionTrusted(); got != tc.want {
+			t.Errorf("%s: RevisionTrusted() = %v, want %v (Revision() = %q, modified = %v)",
+				tc.name, got, tc.want, Revision(), *tc.modified)
+		}
+	}
+}
diff --git a/scripts/self-update.sh b/scripts/self-update.sh
index b8e2094..91477a9 100755
--- a/scripts/self-update.sh
+++ b/scripts/self-update.sh
@@ -20,8 +20,8 @@ fi
 echo "[self-update] git pull --ff-only"
 git pull --ff-only
 
-echo "[self-update] go build (devagent-go)"
-go build -trimpath -o devagent-go ./cmd/devagent
+echo "[self-update] make build (devagent-go)"
+make build
 
 if [ "$(uname -s)" = "Darwin" ] && launchctl print "gui/${UID_NUM}/${LABEL}" >/dev/null 2>&1; then
   echo "[self-update] launchctl kickstart ${LABEL}"

[linhdmn]

Two more findings for whoever implements this

1. The mechanism is not only linked worktrees — untracked scratch also dirties the stamp. Reproduced live in the main checkout while preparing this issue:

# main tree: git status --porcelain  ->  "?? goal.tmp"  (untracked, the loop's own PO scratch)
make build && go version -m ./devagent-go
  build vcs.revision=68c36cf...        # correct
  build vcs.modified=true              # WRONG — nothing tracked is modified
after rm goal.tmp && make build:
  build vcs.modified=false             # correct

Go's -buildvcs cleanliness check is a git status on the whole tree, so a single leftover untracked file makes the revision read as modified. Any RevisionModified() seam this issue introduces should decide deliberately whether untracked files count (the loop's own goal.tmp/goal.tmp.raw are written into cfg.Repo by runPOPhase, run.go:709-712, and are untracked by design). Note run.go:96-100 only WARNs on rev != HEAD, so this class stays silent.

2. Other uncommitted variants of this work exist in stray worktrees — do not re-implement blindly. Snapshotted to ~/.devagent/patches/selfbuild-strays-20260913/:

• TASK-mty8qv5x-gp4v: untracked internal/version/revision.go + revision_test.go (a different file split of this same stamping work — not in any patch comment above because it is untracked, captured as .untracked.tgz).
• TASK-mtydxuxu-15bm: tracked diff touching internal/version/version.go + version_test.go (another variant).
• TASK-mtylq3cj-2yhb: superseded residue, not this issue — goal-shape validation variant (canonicalGoalLead, goalVerdict, validateGoalShapeVerdict); main already landed validateGoalShape (Goal: Validate goal shape at the dispatch boundary in internal/loopdriver. A g #343), so landing this would put two conventions in the same place.