Extract a shared plan→drift-classification walk for status/diff/reconcile/explain

[spxrogers]

Problem. The walk that turns a render.RenderPlan + state + on-disk destinations into classified items exists four times, hand-maintained:

• buildStatusModel (internal/cli/status.go:283-348)
• diff's inline RunE loop (internal/cli/diff.go:141-198)
• collectItems (internal/cli/reconcile.go:610-677)
• a variant in internal/cli/explain_model.go (buildExplainModel, key-merge branch)

All four do: plan.PerAgent → key-merge vs whole-file branch → json.Unmarshal(op.Content) / readDestFile → render.CollectPointers → hash triple → drift.Classify, plus per-path dedupe for whole-file ops and NO dedupe for key-merge ops. Each copy carries a comment warning it must match the others ("matching status's key loop and the apply pipeline", "Deduping by path here dropped the second section's drift…") — synchronization by comment. Orphan enumeration (render.OrphanFiles) is similarly repeated in status + reconcile.

Fix. One iterator in internal/render (or internal/drift) — e.g. WalkPlanItems(plan, reg, state, sc, projectRoot, userHome) yielding {agent, op, ptr, class, srcHash/destHash, srcText/dstText} — with orphan items included behind a flag. Every export it needs (IsKeyMerge, CollectPointers, OrphanFiles, the hash helpers) already exists; only the composition is copy-pasted. status/diff/reconcile/explain then only render.

Payoff. The next change to classification semantics (e.g. mode drift, which today only status layers on at status.go:312) lands in one place instead of one-of-four.

[spxrogers]

Catalogue: what each surface does with a non-regular destination

Gathered while building #240 (the destination-read shape gate, which lands first so this unification inherits one read policy rather than four). Recording it here because the fix belongs to the shared walk, not to the gate — and because the same facts were briefly written into internal/cli/destread.go's doc comment, where they documented other packages' behaviour in the wrong place.

All measured against a 0600 FIFO at a managed destination, both a whole-file one (a rendered SKILL.md) and a key-merge one (~/.claude.json), after a clean apply:

surface	what the user sees
reconcile write-back	names the shape — the only one that does
status	a bare drift. The refusal becomes the opaque not-a-regular-file hash, which exists only to never equal a content hash; statusItem carries {Path, Pointer, Class} and no reason, so nothing reaches the output
diff	the destination renders as empty — "every byte removed", or for a key-merge dest every owned key removed — indistinguishable from an absent file
explain	inherits diff's swallow (explain_model.go, two sites)
doctor	no destination read of its own; see #242

So after #240 the refusal is mostly a better diagnosis available to callers rather than one any of them gives the user. Two of the four walks silently misreport a FIFO as a deleted file.

That is the same "capture it or acknowledge it — never drop it silently" shape CLAUDE.md warns about, and it is squarely this issue's to fix: surfacing it means changing what status, diff and explain print, which is exactly the kind of change that should happen once in the shared walk rather than four times.

Also worth carrying into the unification

• Symlinks split the walks. hashFile Lstats and refuses a link outright; the text reads follow it. So status calls a symlinked destination drifted while diff reads through it and compares the target. Under the documented AGENTSYNC_ALLOW_SYMLINK_DEST=1 setup — where apply writes through the link — that means status reports drift no apply can ever clear. fix(cli): stop status, diff and reconcile hanging on a non-regular destination #240 deliberately left this alone because changing it changes what diff and reconcile have always reported; the walk is the right place to decide it once.
• A regular-but-unreadable destination (EACCES on the file itself) hashes to "", which drift.Classify reads as absent, so it classifies as Orphan rather than as a read failure. Suggested by the round-3 API-design lens as the motivating example for replacing the sentinel-string protocol ("" / not-a-regular-file / symlink-not-regular-file / a hash, all compared only for equality) with a typed destination state through drift.Classify's 9-case table.

---

Generated by Claude Code