feat(import): report upstream freshness for pinned pack imports

[superlzyguy]

The gap

gc import check and gc doctor are offline. They answer "is what I declared installed, pinned, and cached?" and never contact the source, so a pin can be months stale and pass both cleanly. gc import upgrade then printed Upgraded import "x" unconditionally — including over a sha: pin, which names a fixed commit and cannot move — so the one command that looked like a freshness answer returned a false all-clear.

What this adds

A sibling entry point, not an extension of the offline walk, so nothing that runs today gains a network dependency. internal/packman/check.go and resolve.go are unchanged.

• packman.CheckUpstream (new internal/packman/freshness.go) resolves each declared remote import's source and compares it against its packs.lock pin, returning one of current / behind / unreachable / not_applicable. A per-import failure is data, never a returned error, so one dead remote cannot hide every other verdict. Resolution memoizes by clone URL — freshness is a property of the repository, so two subpath imports of one repo cost one round trip.
• gc import status --check-upstream renders those verdicts in text and JSON, names every stale import on stderr with both commits, and exits 1 when any pin is behind. --fail-on-unreachable extends the failure to unresolvable sources and is rejected without --check-upstream (a silently ignored flag reads as a passing gate). Without the flag the command is unchanged: no network call, neither new field emitted, exit 0.
• gc import upgrade diffs the lock before and after syncing and reports what actually moved, so an unmoved sha: pin says so and names the re-pin path.

schemas/import/status/result.schema.json is updated in the same commit — it sets additionalProperties: false, and TestImportStatusJSONProductionRun validates real output against it, so a struct field without a schema property is a red test. verdict is pinned there as a four-value enum.

Two traps worth reviewing closely

ls-remote --symref against a file:// source returns four lines, not two. A file:// clone of a non-bare repository also advertises its remote-tracking refs, and the HEAD refspec glob-matches refs/remotes/origin/HEAD — whose sha is a different commit:

ref: refs/heads/main	HEAD
bd29eb3830f4da727f5d1184092192d5dec29142	HEAD
ref: refs/remotes/origin/main	refs/remotes/origin/HEAD
4999445bdd5f5695f67ea182eee69f60e0187598	refs/remotes/origin/HEAD

The parser therefore requires the second tab-separated field to be exactly "HEAD". Suffix-matching or "last matching line" reads 4999445b and reports an up-to-date import behind, while every unit test over a two-line https fixture stays green. Both shapes are covered.

file:// is a remote source. remotesource.IsRemote returns true for it and ls-remote works against it, so it takes the network path and reaches a real verdict; not_applicable is for scheme-less path sources only.

Deliberate scope decision

No --version re-pin flag. Import declarations live in three scopes (pack.toml [imports.*], [defaults.rig.imports.*], rig [imports.*]), and a write-back that silently picked one — or handled only the root-pack scope — is worse than none. Instead the CLI explicitly names the supported path (edit the declaring manifest, then gc import install) in gc import --help, gc import upgrade --help, the unmoved-upgrade output, the ErrImportExists arm, and the guide. Happy to add the write-back in a follow-up if you'd prefer it.

Testing

The load-bearing test is TestUpstreamFreshnessSeesWhatCheckInstalledCannot: on one fixture whose on-disk state never changes, CheckInstalled reports no issues and CheckUpstream reports that same import behind. Both assertions are in one function on purpose — the contrast is the test.

Also covered: both constraint kinds in both directions (a sha: pin equal to the head must resolve current, not a blanket "behind"); the offline contract (CheckInstalled with the network seam counted and hard-failing; the doctor check with the seam stubbed to t.Fatal); exit codes and stderr; unreachable never falling through to current, with *gitcred.AuthError surviving wrapped so the existing credential hint still fires; and the symref-absent fallback.

internal/packman and every import/freshness test in cmd/gc pass. go vet, check-schema, check-release-dist-ignore, check-routed-test-rows, check-split-topology-rows, check-residency-boundary, and gen-command-census -check are all green. docs/reference/cli.md is regenerated by make generate, never hand-edited.

Two notes on my local environment, both reproduced on an unmodified upstream/main checkout and neither reachable from this change — CI pins its own toolchain, so please treat CI as authoritative:

• golangci-lint v2.12.0 panics inside the Go stdlib (buildir: package "poll": unexpected expr: *ast.KeyValueExpr) under the host's Go 1.27.0; reproduced on ./internal/remotesource, untouched here.
• make test has pre-existing failures in unrelated packages from chmod-based failure-injection tests defeated by running as root (TestHashPathContentUnreadableChild, TestWriteCityAndRigSiteBindings*, TestDoRigSetEndpoint*RollsBack*, …). Verified identical at base commit a85f857b in a clean worktree.

Live run

Against a real city, this branch reports 4 of 9 declared imports behind and exits 1, while gc import check on the same unchanged state still exits 0 — which is the point: the offline walk was never wrong, it was answering a different question.

🤖 Generated with Claude Code

https://claude.ai/code/session_014iydcoJjKEV5m2EMF5i3xi

---

Opened against superlzyguy/gascity rather than the upstream gastownhall/gascity at the maintainer's direction. Supersedes gastownhall#5817, which is closed.