#4827·gastown

doctor witness-exists check flags healthy witnesses as 'incomplete' (stale legacy-clone requirement)

Author: rokasomniCreated Sep 8, 2026Updated Sep 8, 2026
Labelsstatus/needs-triage

Summary

gt doctor's witness-exists check (internal/doctor/rig_check.go) reports "Witness structure incomplete" for a fully healthy, actively-running witness, because it requires a witness/rig/ git clone that the current witness architecture no longer needs.

Root cause

WitnessExistsCheck.Run (internal/doctor/rig_check.go) treats a missing <rig>/witness/rig/.git as an error condition:

go
rigGit := filepath.Join(rigClone, ".git")
if _, err := os.Stat(rigGit); os.IsNotExist(err) {
    issues = append(issues, "Missing: witness/rig/ (git clone)")
    c.needsClone = true
}

But internal/witness/manager.go's witnessDir() explicitly documents witness/rig/ as a legacy path and falls back to running the witness directly out of witness/ (no clone) when it's absent:

go
// witnessDir returns the working directory for the witness.
// Prefers witness/rig/ for existing legacy clones, otherwise uses witness/.
func (m *Manager) witnessDir() string {
	witnessRigDir := filepath.Join(m.rig.Path, "witness", "rig")
	if _, err := os.Stat(witnessRigDir); err == nil {
		return witnessRigDir
	}
	return filepath.Join(m.rig.Path, "witness")
}

The witness doesn't run git commands in its own working directory in the current design (unlike refinery/polecats/crew), so it doesn't need a clone at all. The doctor check appears to predate this change and was never updated.

Impact

  • gt doctor --fix cannot resolve this — WitnessExistsCheck.Fix explicitly refuses: "cannot auto-create witness/rig/ clone (requires repo URL)".
  • Every rig whose witness was set up (or has been running for a while) without a legacy witness/rig/ clone will permanently show witness-exists: Witness structure incomplete in gt doctor output, even though the witness is running correctly. This is a standing false positive that muddies real doctor output.

Repro

  1. Have a rig whose witness has no witness/rig/ directory (current/modern setup, or one where it was never created).
  2. Confirm the witness is actually healthy: gt witness status <rig> shows it running normally.
  3. Run gt doctor --rig <rig>witness-exists reports "Witness structure incomplete", listing Missing: witness/rig/ (git clone).
  4. gt doctor --fix --rig <rig> leaves it unresolved (can't auto-create the clone).

Suggested fix

WitnessExistsCheck.Run should only flag a missing clone when it's actually required — e.g. treat witness/rig/ as optional/legacy the same way witnessDir() does, and only check for witness/mail/inbox.jsonl (and the witness/ directory itself) as the real requirements. Alternatively, drop the clone requirement from the check entirely if no current code path depends on it.