From 9d1ef08bba9b2f11c120d112234ee84d0cc35a5a Mon Sep 17 00:00:00 2001
From: lukasWuttke <54042461+LukasWodka@users.noreply.github.com>
Date: Mon, 17 Aug 2026 13:37:03 +0200
Subject: [PATCH 1/5] feat(interactive): the guided `?` line carries a label,
 not just an answer (cli#504) (#518)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(interactive): the guided `?` line carries a label, not just an answer (cli#504)

The guided flow built its prompter as `surveyPrompter{bare: true}`, which set
survey's Message to "". The prompt line rendered as a lone `?` — and since #505
started pre-filling answers, as `? [~/mydata]`: a question mark, a bracket and a
path, with no verb.

The bare mode's premise was sound (the CLI already prints `Step 3 of 4 · Where
is your data?`, so repeating it on the `?` line would duplicate it) but the
conclusion was not — and the codebase already said so. `Confirm` refused to go
bare because "a bare `? (y/N)` there would be a label-less destructive prompt";
that objection was never Confirm-specific.

Each guided prompt now passes a short noun label: the shortest noun phrase that
names the answer, with a trailing colon. `? Path: ~/mydata`, `? Task:
tabular_classification`, `? Column types:`. The header still asks the question;
the label says what you are typing into. The label-column question keeps its
two wordings on both lines — `Label:` for a class, `Target:` for a numeric
value — so the branches stay distinguishable on the prompt line too.

`bare` is deleted rather than left unused, so no future call site can reach the
label-less rendering.

Flows with no step header of their own (client create, delete, resources set)
are untouched: they still pass the whole question, which is right for them.

Tests: the ~110 scripted answers keyed by prompt label are rekeyed across
interactive_test.go, copy_catalog_test.go and task_scope_test.go (the issue's
file list missed the third; path_examples_test.go turned out to key on
nothing). Two assertions were rewritten rather than rekeyed, because rekeying
would have made them vacuous: the #181 file-or-folder copy check now reads the
PRINTED step (a short label cannot carry that sentence), and the MLM
no-label-question check names both `Label:` and `Target:` instead of matching a
shared "Which column holds" stem that no longer exists.

New guard TestRunInteractive_EveryGuidedPromptCarriesAShortLabel drives the
real flow across seven scenarios and asserts a property of whatever it asks —
non-empty, ends in ':', carries no '?', within a 16-rune budget — with the
confirm asserted to be the opposite (a whole question). Nothing is scripted by
label, so there is no list agreeing with itself; zero recorded prompts is a
failure, not a pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(release): bump VERSION to 0.10.9 (cli#504)

version-bump-gate failed this PR: v0.10.8 is already released and the diff
touches published paths (internal/*). The release train reads VERSION and cuts
the tag from it — it never bumps for you, so leaving it stale does not fail
here, it fails the next prod hop days later on somebody else (backend#1561).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 STYLE.md                                      |  29 +-
 VERSION                                       |   2 +-
 internal/cli/copy_catalog_test.go             |  63 ++--
 internal/cli/data_ingest_cmd.go               |   8 +-
 internal/cli/interactive.go                   |  91 ++---
 internal/cli/interactive_test.go              | 331 +++++++++++++-----
 internal/cli/task_scope_test.go               |  40 +--
 .../cli/testdata/golden/01-data-ingest.golden |  37 +-
 .../cli/testdata/golden/zz-all-strings.golden |  11 +-
 9 files changed, 406 insertions(+), 206 deletions(-)

diff --git a/STYLE.md b/STYLE.md
index fcbde6b..7ba0644 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -55,10 +55,31 @@ flow) use one uniform rhythm so every question reads the same:
 - **A result that belongs to an answer attaches to it with no blank** — e.g. the
   `✔ Found a CSV table …` sniff echo sits directly under the path answer.
 
-So: `header → blank → [supporting text → blank] → ? prompt`. The prompt line is
-answer-only (`? train`); the question lives in the header (the prompter runs
-`bare`), never repeated on the `?` line. Keep it uniform — don't hand-tune the
-spacing of individual questions.
+So: `header → blank → [supporting text → blank] → ? prompt`. Keep it uniform —
+don't hand-tune the spacing of individual questions.
+
+## Guided-prompt labels
+
+The `?` line carries a **short noun label**, not the question: `? Path: ~/mydata`,
+`? Task: tabular_classification`. The question lives in the header and is never
+repeated on the `?` line; the label says what you are typing into.
+
+- The label is the **shortest noun phrase that names the answer**, with a trailing
+  colon — `Split:`, `Name:`, `Path:`, `Task:`, `Data type:`, `Label:` / `Target:`,
+  `Keypoints:`, `Resolution:`, `Column types:`, `Label policy:`, `Time column:`.
+- **A prompt never goes label-less.** The guided flow used to blank survey's
+  `Message` (a `bare` mode), which rendered a lone `?` — and once answers were
+  pre-filled, `? [~/mydata]`: a question mark, a bracket and a path, with no verb
+  (cli#504). `internal/cli/interactive_test.go` asserts the property — non-empty,
+  ends in `:`, no `?`, within a length budget — against whatever the real flow
+  asks, so a new question is covered without editing the test.
+- **A confirm is the exception: it carries the whole question** (`? Proceed with
+  the ingest? (y/N)`). A y/N prompt has no header of its own, and the
+  overwrite-replace confirm fires with nothing printed before it — a noun there
+  would name the object and hide the stakes.
+- Flows with no step headers of their own (`client create`, `delete`,
+  `resources set`) pass the whole question as the label. The register follows the
+  header, not the prompter.
 
 ## Terminology
 
diff --git a/VERSION b/VERSION
index 1a46c7f..f314d02 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.10.8
+0.10.9
diff --git a/internal/cli/copy_catalog_test.go b/internal/cli/copy_catalog_test.go
index 5826d4e..cd6b50c 100644
--- a/internal/cli/copy_catalog_test.go
+++ b/internal/cli/copy_catalog_test.go
@@ -140,29 +140,29 @@ func TestCopyCatalog(t *testing.T) {
 	imgDir := imageDirLayout(t)
 	txtDir := textDirLayout(t)
 	tabularIngest := driveIngest(tabDir, "~/data/patients", map[string]string{
-		"Do you want to ingest training or test data?": "train",
-		"Please name the dataset.":                     "hospital_train",
-		"Where is your data?":                          tabDir,
-		"Which task?":                                  "tabular_classification",
-		"Which column holds the label?":                "churned",
+		"Split:": "train",
+		"Name:":  "hospital_train",
+		"Path:":  tabDir,
+		"Task:":  "tabular_classification",
+		"Label:": "churned",
 	})
 	imageIngest := driveIngest(imgDir, "~/data/xray", map[string]string{
-		"Do you want to ingest training or test data?": "train",
-		"Please name the dataset.":                     "xray_train",
-		"Where is your data?":                          imgDir,
-		"Which task?":                                  "image_classification",
-		"Which column holds the label?":                "label",
-		"Image resolution":                             "224x224",
+		"Split:":      "train",
+		"Name:":       "xray_train",
+		"Path:":       imgDir,
+		"Task:":       "image_classification",
+		"Label:":      "label",
+		"Resolution:": "224x224",
 	})
 	// Text family: text_classification shows the label question; the picker lists
 	// every text task + blurb. (Self-supervised text — masked/causal LM, seq2seq
 	// — skips the label step; that path is covered by the backstop.)
 	textIngest := driveIngest(txtDir, "~/data/reviews", map[string]string{
-		"Do you want to ingest training or test data?": "train",
-		"Please name the dataset.":                     "reviews_train",
-		"Where is your data?":                          txtDir,
-		"Which task?":                                  "text_classification",
-		"Which column holds the label?":                "label",
+		"Split:": "train",
+		"Name:":  "reviews_train",
+		"Path:":  txtDir,
+		"Task:":  "text_classification",
+		"Label:": "label",
 	})
 	// execIngest renders the run that follows the confirm — the three steps and
 	// the final summary. printLocalSummary + submit.RenderSummary are the REAL
@@ -211,7 +211,7 @@ func TestCopyCatalog(t *testing.T) {
 	}
 	dataIngestFile := doc(
 		"tb data ingest — stage a dataset into your secure environment",
-		"What you see when you run `tb data ingest` with no flags: a short intro, a\nfour-step guided setup (intent, name, path, task) then the task-specific\nquestions, and — after you confirm — the run itself. The setup is\ndriven through the real flow for one task in each family (tabular, image, text)\nso the task-specific questions are visible; each core question prints as a\n`Step N of 4 · …` header, the task-specific ones (the label column, and extras\nlike resolution or schema) as their own header, the\nsupporting line beneath it, and the `?` line shows your answer. The run (shown\nonce, for tabular) is the three steps + the final summary as the CLI renders\nthem. Values passed as flags (--as, --task, a path, …) pre-fill the matching\nquestions rather than skipping them — guided mode always asks. The\nother tasks' extra questions (keypoints, label policy, time column),\nself-supervised text (which skips the label question), and the failure-summary\nwordings are in zz-all-strings.golden. The raw ingestor stream the CLI streams\nthrough (MySQL waits, the 📊 banner, per-validator lines) is the engine's own\nstdout — not CLI copy — so it isn't shown. (`tb ingest` is a hidden deprecated\nalias; `push` is a deprecated alias of the verb.)",
+		"What you see when you run `tb data ingest` with no flags: a short intro, a\nfour-step guided setup (intent, name, path, task) then the task-specific\nquestions, and — after you confirm — the run itself. The setup is\ndriven through the real flow for one task in each family (tabular, image, text)\nso the task-specific questions are visible; each core question prints as a\n`Step N of 4 · …` header, the task-specific ones (the label column, and extras\nlike resolution or schema) as their own header, the\nsupporting line beneath it, and the `?` line carries a short noun label\n(`Path:`, `Task:`) plus your answer. The run (shown\nonce, for tabular) is the three steps + the final summary as the CLI renders\nthem. Values passed as flags (--as, --task, a path, …) pre-fill the matching\nquestions rather than skipping them — guided mode always asks. The\nother tasks' extra questions (keypoints, label policy, time column),\nself-supervised text (which skips the label question), and the failure-summary\nwordings are in zz-all-strings.golden. The raw ingestor stream the CLI streams\nthrough (MySQL waits, the 📊 banner, per-validator lines) is the engine's own\nstdout — not CLI copy — so it isn't shown. (`tb ingest` is a hidden deprecated\nalias; `push` is a deprecated alias of the verb.)",
 		[]run{
 			{"tb data ingest   # guided · tabular classification", tabularIngest},
 			{"tb data ingest   # guided · image classification", imageIngest},
@@ -476,8 +476,8 @@ func quoteAll(in []string) []string {
 	return out
 }
 
-// catalogPrompter is the prompter seam's catalog double: it prints each question
-// the way the terminal shows it ("? <question> <answer>") and returns a scripted
+// catalogPrompter is the prompter seam's catalog double: it prints each prompt
+// the way the terminal shows it ("? <label> <answer>") and returns a scripted
 // answer, so driving the REAL runInteractive produces a byte-exact transcript of
 // the guided flow — every prompt, in order. The description line above each
 // question is the real p.PromptHint in runInteractive; only the "? …" line is
@@ -494,32 +494,35 @@ func (c *catalogPrompter) pick(label, def string) string {
 	return def
 }
 
-// answerLine renders the input line the way the bare surveyPrompter does for the
-// guided flow: the question is already printed by the CLI (PromptStep/Section),
-// so the prompt shows only "? <answer>" (or "?" on a blank/accept-default).
-func (c *catalogPrompter) answerLine(ans string) {
+// answerLine renders the input line the way survey does: the icon, the
+// prompter's Message verbatim, then the answer separated by one space. The
+// guided flow's Message is a short noun label ("Path:"), so the catalog shows
+// "? Path: ~/data/patients" — the question itself is already printed by the CLI
+// as a PromptStep/Section header (#504). A blank answer (Enter accepts the
+// default) leaves the label alone on the line rather than a trailing space.
+func (c *catalogPrompter) answerLine(label, ans string) {
 	if ans == "" {
-		fmt.Fprintf(c.w, "?\n")
+		fmt.Fprintf(c.w, "? %s\n", label)
 		return
 	}
-	fmt.Fprintf(c.w, "? %s\n", ans)
+	fmt.Fprintf(c.w, "? %s %s\n", label, ans)
 }
 
 func (c *catalogPrompter) Input(label, _, def string, _ func(string) error) (string, error) {
 	ans := c.pick(label, def)
-	c.answerLine(ans)
+	c.answerLine(label, ans)
 	return ans, nil
 }
 
 func (c *catalogPrompter) Select(label, _ string, _ []string, def string) (string, error) {
 	ans := c.pick(label, def)
-	c.answerLine(ans)
+	c.answerLine(label, ans)
 	return ans, nil
 }
 
-// Confirm keeps its label (never bare — see surveyPrompter.Confirm): a y/N
-// prompt has no header of its own, so survey draws "? <question> <answer>".
-// Mirror that here so the catalog shows the confirm question.
+// Confirm carries the WHOLE question, not a short label (see
+// surveyPrompter.Confirm): a y/N prompt has no header of its own, so survey
+// draws "? <question> <answer>". Mirror that here so the catalog shows it.
 func (c *catalogPrompter) Confirm(label string, def bool) (bool, error) {
 	ans := "No"
 	if def {
diff --git a/internal/cli/data_ingest_cmd.go b/internal/cli/data_ingest_cmd.go
index b1ab3f2..77245bc 100644
--- a/internal/cli/data_ingest_cmd.go
+++ b/internal/cli/data_ingest_cmd.go
@@ -202,9 +202,11 @@ Exit codes:
 			interactive := !noInput && !outputJSON && isInteractiveTTY()
 			var pr prompter
 			if interactive {
-				// bare: the guided flow prints each question as a step header
-				// (PromptStep), so the prompt line itself stays answer-only.
-				pr = surveyPrompter{bare: true}
+				// The guided flow prints each question as a step header
+				// (PromptStep) and passes the prompter a short noun label, so
+				// the `?` line reads "? Path: …" without repeating the question
+				// (#504).
+				pr = surveyPrompter{}
 			}
 			// In --output-json mode, human output goes to stderr so
 			// stdout carries only the JSON result.
diff --git a/internal/cli/interactive.go b/internal/cli/interactive.go
index 27d1a50..a6c9d7f 100644
--- a/internal/cli/interactive.go
+++ b/internal/cli/interactive.go
@@ -41,23 +41,24 @@ type prompter interface {
 // surveyPrompter is the production prompter, backed by
 // AlecAivazis/survey/v2 against the real terminal.
 //
-// bare drops the question text from the prompt line (survey's Message), for
-// flows where the CLI already prints the question itself as a step header
-// (the guided ingest flow, via PromptStep) — so the prompt reads "? <answer>"
-// with no duplicate question. Confirm always keeps its label (a short y/n with
-// no header of its own).
-type surveyPrompter struct{ bare bool }
-
-func (s surveyPrompter) message(label string) string {
-	if s.bare {
-		return ""
-	}
-	return label
-}
+// label is drawn verbatim as survey's Message, so the prompt line always
+// carries one. Callers choose the register: the flows that have no header of
+// their own (client create, delete, resources set) pass the whole question;
+// the guided ingest flow, which already prints the question as a step header,
+// passes a short noun label with a trailing colon ("Path:", "Task:") so the
+// line reads "? Path: ~/mydata" — context without repeating the question
+// (#504).
+//
+// It used to have a `bare` mode that blanked the Message for the guided flow,
+// leaving a label-less "? " — which, once answers were pre-filled, rendered as
+// "? [~/mydata]": a question mark, a bracket and a path, with no verb. Confirm
+// already refused to go bare for that reason; the objection was never
+// Confirm-specific.
+type surveyPrompter struct{}
 
 func (s surveyPrompter) Input(label, help, def string, validate func(string) error) (string, error) {
 	var ans string
-	q := &survey.Input{Message: s.message(label), Help: help, Default: def}
+	q := &survey.Input{Message: label, Help: help, Default: def}
 	var opts []survey.AskOpt
 	if validate != nil {
 		// survey hands the validator the raw answer as interface{};
@@ -76,7 +77,7 @@ func (s surveyPrompter) Input(label, help, def string, validate func(string) err
 
 func (s surveyPrompter) Select(label, help string, options []string, def string) (string, error) {
 	var ans string
-	q := &survey.Select{Message: s.message(label), Help: help, Options: options, Default: def}
+	q := &survey.Select{Message: label, Help: help, Options: options, Default: def}
 	// Arrow keys only work while the console delivers VK_* key events; see
 	// enableKeyEventInput. Without this, ↓ typed "[B" into the filter on Windows and
 	// the selection never moved (#475).
@@ -88,10 +89,10 @@ func (s surveyPrompter) Select(label, help string, options []string, def string)
 }
 
 func (s surveyPrompter) Confirm(label string, def bool) (bool, error) {
-	// Confirm always keeps its label (never bare): a y/N prompt has no step
-	// header of its own, and the overwrite-replace confirm fires later, during
-	// the cluster phase, with nothing printed before it — a bare "? (y/N)"
-	// there would be a label-less destructive prompt.
+	// Confirm keeps the WHOLE question, not a short label: a y/N prompt has no
+	// step header of its own, and the overwrite-replace confirm fires later,
+	// during the cluster phase, with nothing printed before it — "? Overwrite:
+	// (y/N)" there would name the noun and hide the stakes.
 	ans := def
 	defer enableKeyEventInput()()
 	if err := survey.AskOne(&survey.Confirm{Message: label, Default: def}, &ans); err != nil {
@@ -215,8 +216,12 @@ func runInteractive(p *ui.Printer, pr prompter, a *runDataIngestArgs) error {
 
 	// The guided flow is a four-step setup: intent → name → path → task. Each
 	// question prints as its own step header (PromptStep), with any supporting
-	// line beneath it and an answer-only prompt (the prompter runs bare — see
-	// surveyPrompter). Everything task-dependent comes AFTER the four steps as
+	// line beneath it and a prompt line carrying a SHORT NOUN LABEL — the
+	// shortest noun phrase that names the answer ("Path:", "Task:", "Column
+	// types:"), never the question again (#504). The header asks; the label
+	// says what you are typing into.
+	//
+	// Everything task-dependent comes AFTER the four steps as
 	// unnumbered refinements (Section headers): the label column, and per-task
 	// extras like schema, resolution, keypoints. These aren't numbered because
 	// which ones apply — and whether any apply at all — depends on the task
@@ -225,9 +230,9 @@ func runInteractive(p *ui.Printer, pr prompter, a *runDataIngestArgs) error {
 	//
 	// Spacing is uniform (STYLE.md "Guided-prompt spacing"): the header carries
 	// its own leading blank; then one blank line, the optional supporting text,
-	// one blank line, and the `?` prompt. With no supporting text the single
-	// blank sits directly between header and prompt. A result that belongs to an
-	// answer (the sniff echo) attaches to it with no blank.
+	// one blank line, and the `? <label>:` prompt. With no supporting text the
+	// single blank sits directly between header and prompt. A result that
+	// belongs to an answer (the sniff echo) attaches to it with no blank.
 
 	// Guided mode ASKS. A value that arrived on the command line becomes the
 	// prompt's DEFAULT — never a reason to skip the question (#509).
@@ -255,7 +260,7 @@ func runInteractive(p *ui.Printer, pr prompter, a *runDataIngestArgs) error {
 		def := defaultInOptions(a.Spec.Intent, opts, "train")
 		p.PromptStep(1, 4, "Do you want to ingest training or test data?")
 		p.Newline()
-		ans, err := pr.Select("Do you want to ingest training or test data?", "which split this data is",
+		ans, err := pr.Select("Split:", "which split this data is",
 			opts, def)
 		if err != nil {
 			return err
@@ -268,7 +273,7 @@ func runInteractive(p *ui.Printer, pr prompter, a *runDataIngestArgs) error {
 	{
 		p.PromptStep(2, 4, "Please name the dataset.")
 		p.Newline()
-		ans, err := pr.Input("Please name the dataset.",
+		ans, err := pr.Input("Name:",
 			"letters, digits, and underscores — no hyphens or spaces, use _; start with a letter or underscore  e.g. churn_train",
 			a.Spec.Table,
 			push.ValidateTableName)
@@ -289,7 +294,7 @@ func runInteractive(p *ui.Printer, pr prompter, a *runDataIngestArgs) error {
 		p.Infof("Images    a folder with labels.csv + images/   e.g. %s", exImg)
 		p.Infof("Text      a folder with labels.csv + texts/     e.g. %s", exTxt)
 		p.Newline()
-		ans, err := pr.Input("Where is your data?", fmt.Sprintf("e.g. %s or %s", exTab, exImg),
+		ans, err := pr.Input("Path:", fmt.Sprintf("e.g. %s or %s", exTab, exImg),
 			a.LocalPath, validateDatasetPath)
 		if err != nil {
 			return err
@@ -405,7 +410,7 @@ func resolveFamily(p *ui.Printer, pr prompter, path string) (push.Family, error)
 	p.Hintf("We couldn't tell from the layout — tabular = a CSV table; image = labels.csv + images/; text = labels.csv + texts/.")
 	p.Newline()
 	opts := push.FamilyNouns()
-	ans, err := pr.Select("What kind of data is this?",
+	ans, err := pr.Select("Data type:",
 		"tabular = a CSV table; image = labels.csv + images/; text = labels.csv + texts/",
 		opts, opts[0])
 	if err != nil {
@@ -475,7 +480,7 @@ func pickTask(p *ui.Printer, pr prompter, fam push.Family, want string) (string,
 	// otherwise render a default the user cannot see, and an Enter on it would be
 	// unexplainable.
 	def := defaultInOptions(want, opts, opts[0])
-	ans, err := pr.Select("Which task?", "pick the task this data is for", opts, def)
+	ans, err := pr.Select("Task:", "pick the task this data is for", opts, def)
 	if err != nil {
 		return "", err
 	}
@@ -513,17 +518,20 @@ func promptCategorySpecific(p *ui.Printer, pr prompter, a *runDataIngestArgs) (b
 	// be corrected here the same way a stale path can. Only self-supervised text
 	// (no label at all) still bypasses it.
 	if !push.SelfSupervisedText(cat) {
-		question := "Which column holds the label?"
+		// The prompt label tracks the wording: a class to sort into is a "Label",
+		// a numeric target is a "Target". Keeping them distinct is what lets the
+		// two branches be told apart on the prompt line as well as in the header.
+		question, label := "Which column holds the label?", "Label:"
 		desc := "The answer the model learns to produce — for classification, the class.  e.g. diagnosis, churned"
 		if push.IsRegressionClass(cat) {
-			question = "Which column holds the value to predict?"
+			question, label = "Which column holds the value to predict?", "Target:"
 			desc = "The number the model learns to predict.  e.g. price, age, days_to_event"
 		}
 		p.Section(question)
 		p.Newline()
 		p.Hintf("%s", desc)
 		p.Newline()
-		ans, err := promptLabelColumn(pr, cat, a.LocalPath, question, a.Spec.LabelColumn)
+		ans, err := promptLabelColumn(pr, cat, a.LocalPath, label, a.Spec.LabelColumn)
 		if err != nil {
 			return prompted, err
 		}
@@ -545,7 +553,7 @@ func promptCategorySpecific(p *ui.Printer, pr prompter, a *runDataIngestArgs) (b
 			if a.Spec.NumberOfKeypoints > 0 {
 				kpDef = strconv.Itoa(a.Spec.NumberOfKeypoints)
 			}
-			ans, err := pr.Input("How many keypoints per sample?",
+			ans, err := pr.Input("Keypoints:",
 				"e.g. 17 for COCO pose", kpDef, validatePositiveInt)
 			if err != nil {
 				return prompted, err
@@ -559,7 +567,7 @@ func promptCategorySpecific(p *ui.Printer, pr prompter, a *runDataIngestArgs) (b
 			p.Newline()
 			p.Hintf("The size your images already are, as WxH — tracebloc checks every image matches and never resizes. Press Enter to read it from your first image.  e.g. 224x224")
 			p.Newline()
-			ans, err := pr.Input("Image resolution",
+			ans, err := pr.Input("Resolution:",
 				"the size your images already are; tracebloc checks it, it never resizes", a.TargetSizeFlag,
 				validateOptionalTargetSize)
 			if err != nil {
@@ -574,7 +582,7 @@ func promptCategorySpecific(p *ui.Printer, pr prompter, a *runDataIngestArgs) (b
 			p.Newline()
 			p.Hintf("We infer each column's type from your CSV. Press Enter to accept, or type overrides like age:INT,price:FLOAT.")
 			p.Newline()
-			ans, err := pr.Input("Column types", "e.g. age:INT,price:FLOAT", a.SchemaFlag, validateOptionalSchema)
+			ans, err := pr.Input("Column types:", "e.g. age:INT,price:FLOAT", a.SchemaFlag, validateOptionalSchema)
 			if err != nil {
 				return prompted, err
 			}
@@ -590,7 +598,7 @@ func promptCategorySpecific(p *ui.Printer, pr prompter, a *runDataIngestArgs) (b
 			// A supplied --label-policy pre-fills only when valid; a typo like
 			// "buckets" would otherwise abort the Select on a TTY (defaultInOptions).
 			lpDef := defaultInOptions(a.Spec.LabelPolicy, opts, "bucket")
-			ans, err := pr.Select("Label policy",
+			ans, err := pr.Select("Label policy:",
 				"bucket bins the target before it leaves the cluster",
 				opts, lpDef)
 			if err != nil {
@@ -608,7 +616,7 @@ func promptCategorySpecific(p *ui.Printer, pr prompter, a *runDataIngestArgs) (b
 			if tcDef == "" {
 				tcDef = "time"
 			}
-			ans, err := pr.Input("Time column", "the duration/time column name", tcDef, nil)
+			ans, err := pr.Input("Time column:", "the duration/time column name", tcDef, nil)
 			if err != nil {
 				return prompted, err
 			}
@@ -625,20 +633,23 @@ func promptCategorySpecific(p *ui.Printer, pr prompter, a *runDataIngestArgs) (b
 // named "label" if present; otherwise — the header isn't readable yet — it falls
 // back to free text pre-filled with the supplied value so the flow never stalls.
 //
+// label is the short noun the `?` line carries ("Label:" / "Target:"); the full
+// question is already printed as the Section header by the caller (#504).
+//
 // supplied is resolved to the header's own spelling (canonicalHeader) and then
 // guarded through defaultInOptions before it reaches survey.Select: a mistyped
 // --label-column that is not one of the real headers would otherwise abort the
 // prompt on a TTY, the same default-not-in-options crash guarded everywhere
 // else in the guided flow.
-func promptLabelColumn(pr prompter, category, root, question, supplied string) (string, error) {
+func promptLabelColumn(pr prompter, category, root, label, supplied string) (string, error) {
 	headers, err := push.PreviewLabelHeaders(category, root)
 	if err == nil && len(headers) > 0 {
-		ans, serr := pr.Select(question,
+		ans, serr := pr.Select(label,
 			"pick the label/target column from your CSV header", headers,
 			defaultInOptions(canonicalHeader(supplied, headers), headers, defaultLabelChoice(headers)))
 		return strings.TrimSpace(ans), serr
 	}
-	ans, ierr := pr.Input(question, "the label/target column name", supplied, nil)
+	ans, ierr := pr.Input(label, "the label/target column name", supplied, nil)
 	return strings.TrimSpace(ans), ierr
 }
 
diff --git a/internal/cli/interactive_test.go b/internal/cli/interactive_test.go
index e96a259..3350913 100644
--- a/internal/cli/interactive_test.go
+++ b/internal/cli/interactive_test.go
@@ -115,11 +115,11 @@ func textDirLayout(t *testing.T) string {
 func TestRunInteractive_PromptOrder(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Do you want to ingest training or test data?": "test",
-		"Please name the dataset.":                     "churn_train",
-		"Where is your data?":                          dir,
-		"Which task?":                                  "tabular_classification",
-		"Which column holds the label?":                "churned",
+		"Split:": "test",
+		"Name:":  "churn_train",
+		"Path:":  dir,
+		"Task:":  "tabular_classification",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{}
 	if err := runInteractive(discardPrinter(), f, a); err != nil {
@@ -129,11 +129,11 @@ func TestRunInteractive_PromptOrder(t *testing.T) {
 	// The four core questions must appear in data-first order, ahead of the
 	// label question.
 	want := []string{
-		"Do you want to ingest training or test data?",
-		"Please name the dataset.",
-		"Where is your data?",
-		"Which task?",
-		"Which column holds the label?",
+		"Split:",
+		"Name:",
+		"Path:",
+		"Task:",
+		"Label:",
 	}
 	if !orderedSubsequence(f.asked, want) {
 		t.Errorf("prompt order = %v, want subsequence %v", f.asked, want)
@@ -148,31 +148,35 @@ func TestRunInteractive_PromptOrder(t *testing.T) {
 // TestRunInteractive_PathPromptCopyIsFileOrFolder pins the #181 copy
 // restoration: now that the walk accepts a bare .csv, the path prompt says
 // "file or folder" again (softened to folder-only in #180b).
+//
+// The copy is asserted against the PRINTED step, not the prompt label. Since
+// #504 the label is the short noun "Path:", which cannot carry the sentence —
+// checking the label for it would be a check nothing can fail. The supporting
+// line under the Step 3 header is where that copy actually lives.
 func TestRunInteractive_PathPromptCopyIsFileOrFolder(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Do you want to ingest training or test data?": "train",
-		"Please name the dataset.":                     "churn",
-		"Where is your data?":                          dir,
-		"Which task?":                                  "tabular_classification",
-		"Which column holds the label?":                "churned",
+		"Split:": "train",
+		"Name:":  "churn",
+		"Path:":  dir,
+		"Task:":  "tabular_classification",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{}
-	if err := runInteractive(discardPrinter(), f, a); err != nil {
+	var buf bytes.Buffer
+	p := ui.New(&buf, ui.WithColor(false))
+	if err := runInteractive(p, f, a); err != nil {
 		t.Fatalf("runInteractive: %v", err)
 	}
-	found := false
-	for _, label := range f.asked {
-		if label == "Where is your data?" {
-			found = true
-		}
-		if strings.Contains(label, "the folder holding it") {
-			t.Errorf("path prompt still uses the folder-only copy: %q", label)
-		}
-	}
-	if !found {
+	if !contains(f.asked, "Path:") {
 		t.Errorf("path prompt label not asked; got %v", f.asked)
 	}
+	if !strings.Contains(buf.String(), "a file or a folder") {
+		t.Errorf("path step lost the file-or-folder copy (#181):\n%s", buf.String())
+	}
+	if strings.Contains(buf.String(), "the folder holding it") {
+		t.Errorf("path step still uses the folder-only copy:\n%s", buf.String())
+	}
 }
 
 // TestRunInteractive_SniffEchoesFamily: a confident layout is echoed back
@@ -180,8 +184,8 @@ func TestRunInteractive_PathPromptCopyIsFileOrFolder(t *testing.T) {
 func TestRunInteractive_SniffEchoesFamily(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which column holds the label?": "churned",
+		"Name:":  "t",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{LocalPath: dir, Spec: push.SpecArgs{Intent: "train"}}
 	var buf bytes.Buffer
@@ -193,7 +197,7 @@ func TestRunInteractive_SniffEchoesFamily(t *testing.T) {
 		t.Errorf("expected a tabular sniff echo, got:\n%s", buf.String())
 	}
 	for _, l := range f.asked {
-		if l == "What kind of data is this?" {
+		if l == "Data type:" {
 			t.Errorf("a confident sniff must not ask the family question")
 		}
 	}
@@ -207,16 +211,16 @@ func TestRunInteractive_SniffEchoesFamily(t *testing.T) {
 func TestRunInteractive_SniffIsHintNotLock(t *testing.T) {
 	empty := t.TempDir() // no csv, no images/, no texts/ → ambiguous
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"What kind of data is this?":    "image",
-		"Which task?":                   "image_classification",
-		"Which column holds the label?": "label",
+		"Name:":      "t",
+		"Data type:": "image",
+		"Task:":      "image_classification",
+		"Label:":     "label",
 	}}
 	a := &runDataIngestArgs{LocalPath: empty, Spec: push.SpecArgs{Intent: "train"}}
 	if err := runInteractive(discardPrinter(), f, a); err != nil {
 		t.Fatalf("runInteractive: %v", err)
 	}
-	if !contains(f.asked, "What kind of data is this?") {
+	if !contains(f.asked, "Data type:") {
 		t.Errorf("ambiguous layout should ask the family plainly; asked=%v", f.asked)
 	}
 	if a.Spec.Category != "image_classification" {
@@ -244,7 +248,7 @@ func TestResolveFamily_SurfacesMiscasedHint(t *testing.T) {
 
 	var buf bytes.Buffer
 	p := ui.New(&buf, ui.WithColor(false))
-	f := &fakePrompter{answers: map[string]string{"What kind of data is this?": "image"}}
+	f := &fakePrompter{answers: map[string]string{"Data type:": "image"}}
 	fam, err := resolveFamily(p, f, dir)
 	if err != nil {
 		t.Fatalf("resolveFamily: %v", err)
@@ -257,7 +261,7 @@ func TestResolveFamily_SurfacesMiscasedHint(t *testing.T) {
 		if !strings.Contains(buf.String(), "fix it and ingest again") {
 			t.Errorf("resolveFamily must surface the mis-cased rename hint; got:\n%s", buf.String())
 		}
-		if !contains(f.asked, "What kind of data is this?") {
+		if !contains(f.asked, "Data type:") {
 			t.Errorf("hint is advisory — the family question must still be asked; asked=%v", f.asked)
 		}
 	} else {
@@ -269,7 +273,7 @@ func TestResolveFamily_SurfacesMiscasedHint(t *testing.T) {
 		if strings.Contains(buf.String(), "fix it and ingest again") {
 			t.Errorf("no false rename hint when the walk sees the folder; got:\n%s", buf.String())
 		}
-		if contains(f.asked, "What kind of data is this?") {
+		if contains(f.asked, "Data type:") {
 			t.Errorf("a confident sniff must not ask the family question; asked=%v", f.asked)
 		}
 	}
@@ -281,8 +285,8 @@ func TestResolveFamily_SurfacesMiscasedHint(t *testing.T) {
 func TestRunInteractive_ExplicitTaskStillAsks(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which column holds the label?": "churned",
+		"Name:":  "t",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
@@ -293,13 +297,13 @@ func TestRunInteractive_ExplicitTaskStillAsks(t *testing.T) {
 	if err := runInteractive(p, f, a); err != nil {
 		t.Fatalf("runInteractive: %v", err)
 	}
-	if !slices.Contains(f.asked, "Which task?") {
+	if !slices.Contains(f.asked, "Task:") {
 		t.Errorf("the task question must still be asked; asked: %v", f.asked)
 	}
 	// The family came from the supplied task, so the layout sniff is not needed
 	// and its echo must not appear.
 	for _, l := range f.asked {
-		if l == "What kind of data is this?" {
+		if l == "Data type:" {
 			t.Errorf("a supplied task settles the family; must not ask %q", l)
 		}
 	}
@@ -321,7 +325,7 @@ func TestPickTask_FamilyScoped(t *testing.T) {
 	// Text family: all tasks are available now — fill-mask (gloss),
 	// classification, the two structured-pair tasks, and the two seq tasks;
 	// image/tabular tasks must not appear.
-	f := &fakePrompter{answers: map[string]string{"Which task?": "text_classification"}}
+	f := &fakePrompter{answers: map[string]string{"Task:": "text_classification"}}
 	var buf bytes.Buffer
 	p := ui.New(&buf, ui.WithColor(false))
 	id, err := pickTask(p, f, push.FamilyText, "")
@@ -361,7 +365,7 @@ func TestPickTask_FamilyScoped(t *testing.T) {
 // image task is available in the CLI, so the image picker lists them all under
 // "Available now:" with no greyed "Not yet in the CLI" pending section.
 func TestPickTask_ImageAllAvailable(t *testing.T) {
-	f := &fakePrompter{answers: map[string]string{"Which task?": "image_classification"}}
+	f := &fakePrompter{answers: map[string]string{"Task:": "image_classification"}}
 	var buf bytes.Buffer
 	p := ui.New(&buf, ui.WithColor(false))
 	if _, err := pickTask(p, f, push.FamilyImage, ""); err != nil {
@@ -387,7 +391,7 @@ func TestPickTask_ImageAllAvailable(t *testing.T) {
 // TestPickTask_TabularGloss: the tabular picker shows the survival-analysis
 // gloss for time_to_event_prediction and can select it back to its id.
 func TestPickTask_TabularGloss(t *testing.T) {
-	f := &fakePrompter{answers: map[string]string{"Which task?": "time_to_event_prediction"}}
+	f := &fakePrompter{answers: map[string]string{"Task:": "time_to_event_prediction"}}
 	var buf bytes.Buffer
 	p := ui.New(&buf, ui.WithColor(false))
 	id, err := pickTask(p, f, push.FamilyTabular, "")
@@ -409,9 +413,9 @@ func TestRunInteractive_LabelSelectFromHeaders(t *testing.T) {
 	dir := tabularDir(t) // header: age,income,churned
 	// Script an answer that only works if the options were the real headers.
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which task?":                   "tabular_classification",
-		"Which column holds the label?": "income",
+		"Name:":  "t",
+		"Task:":  "tabular_classification",
+		"Label:": "income",
 	}}
 	a := &runDataIngestArgs{LocalPath: dir, Spec: push.SpecArgs{Intent: "train"}}
 	if err := runInteractive(discardPrinter(), f, a); err != nil {
@@ -423,24 +427,35 @@ func TestRunInteractive_LabelSelectFromHeaders(t *testing.T) {
 }
 
 // TestRunInteractive_RegressionLabelWording: a regression-class task words
-// the label question as the value to predict, not a class.
+// the label question as the value to predict, not a class — in the HEADER the
+// user reads and in the short prompt label the `?` line carries (#504). Both
+// are asserted: the header carries the sentence, the label carries the noun,
+// and a task that swapped only one of them would be half-relabelled.
 func TestRunInteractive_RegressionLabelWording(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Which column holds the value to predict?": "income",
+		"Target:": "income",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
 		Spec:      push.SpecArgs{Category: "tabular_regression", Table: "t", Intent: "train"},
 	}
-	if err := runInteractive(discardPrinter(), f, a); err != nil {
+	var buf bytes.Buffer
+	p := ui.New(&buf, ui.WithColor(false))
+	if err := runInteractive(p, f, a); err != nil {
 		t.Fatalf("runInteractive: %v", err)
 	}
-	if !contains(f.asked, "Which column holds the value to predict?") {
+	if !contains(f.asked, "Target:") {
 		t.Errorf("regression should ask for the value to predict; asked=%v", f.asked)
 	}
-	if contains(f.asked, "Which column holds the label?") {
-		t.Errorf("regression must not use the class wording")
+	if contains(f.asked, "Label:") {
+		t.Errorf("regression must not use the class label on the prompt line")
+	}
+	if !strings.Contains(buf.String(), "Which column holds the value to predict?") {
+		t.Errorf("regression header must ask for the value to predict:\n%s", buf.String())
+	}
+	if strings.Contains(buf.String(), "Which column holds the label?") {
+		t.Errorf("regression header must not use the class wording:\n%s", buf.String())
 	}
 	if a.Spec.LabelColumn != "income" {
 		t.Errorf("LabelColumn = %q, want income", a.Spec.LabelColumn)
@@ -453,7 +468,7 @@ func TestRunInteractive_RegressionLabelWording(t *testing.T) {
 func TestRunInteractive_LabelFreeTextFallback(t *testing.T) {
 	empty := t.TempDir() // no labels.csv → PreviewLabelHeaders errors
 	f := &fakePrompter{answers: map[string]string{
-		"Which column holds the label?": "my_label",
+		"Label:": "my_label",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: empty,
@@ -472,16 +487,19 @@ func TestRunInteractive_LabelFreeTextFallback(t *testing.T) {
 func TestRunInteractive_MLMSkipsLabel(t *testing.T) {
 	dir := textDirLayout(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.": "mlm_train",
-		"Which task?":              "masked_language_modeling",
+		"Name:": "mlm_train",
+		"Task:": "masked_language_modeling",
 	}}
 	a := &runDataIngestArgs{LocalPath: dir, Spec: push.SpecArgs{Intent: "train"}}
 	if err := runInteractive(discardPrinter(), f, a); err != nil {
 		t.Fatalf("runInteractive: %v", err)
 	}
+	// Both label-column spellings — the classification "Label:" and the
+	// regression "Target:" — must be absent. Naming both rather than a prefix
+	// keeps this honest now that the labels are short nouns with no shared stem.
 	for _, l := range f.asked {
-		if strings.HasPrefix(l, "Which column holds") {
-			t.Errorf("masked_language_modeling should not ask for a label column")
+		if l == "Label:" || l == "Target:" {
+			t.Errorf("masked_language_modeling should not ask for a label column, asked %q", l)
 		}
 	}
 	if a.Spec.Category != "masked_language_modeling" {
@@ -510,10 +528,10 @@ func TestRunInteractive_AsksEvenWhenFullySpecified(t *testing.T) {
 		t.Fatalf("runInteractive: %v", err)
 	}
 	for _, want := range []string{
-		"Do you want to ingest training or test data?",
-		"Please name the dataset.",
-		"Where is your data?",
-		"Which task?",
+		"Split:",
+		"Name:",
+		"Path:",
+		"Task:",
 	} {
 		if !slices.Contains(f.asked, want) {
 			t.Errorf("guided mode must ask %q even when it was supplied; asked: %v", want, f.asked)
@@ -534,9 +552,9 @@ func TestRunInteractive_AsksEvenWhenFullySpecified(t *testing.T) {
 func TestRunInteractive_UnsuppliedDefaultsUnchanged(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which task?":                   "time_to_event_prediction",
-		"Which column holds the label?": "churned",
+		"Name:":  "t",
+		"Task:":  "time_to_event_prediction",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{LocalPath: dir}
 	if err := runInteractive(discardPrinter(), f, a); err != nil {
@@ -553,9 +571,9 @@ func TestRunInteractive_UnsuppliedDefaultsUnchanged(t *testing.T) {
 func TestRunInteractive_LabelPolicyDefaultUnchanged(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which task?":                   "tabular_regression",
-		"Which column holds the label?": "churned",
+		"Name:":  "t",
+		"Task:":  "tabular_regression",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{LocalPath: dir}
 	if err := runInteractive(discardPrinter(), f, a); err != nil {
@@ -572,7 +590,7 @@ func TestRunInteractive_LabelPolicyDefaultUnchanged(t *testing.T) {
 func TestRunInteractive_SuppliedValuesArePrefilled(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Which column holds the label?": "churned",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
@@ -634,7 +652,7 @@ func TestDefaultInOptions(t *testing.T) {
 func TestRunInteractive_InvalidSuppliedSelectDefaultFallsBack(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Which column holds the value to predict?": "income",
+		"Target:": "income",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
@@ -672,7 +690,7 @@ func TestRunInteractive_SuppliedLabelColumnStillAsks(t *testing.T) {
 	f := &fakePrompter{answers: map[string]string{
 		// Re-answer the label with a different real column: only reachable if the
 		// question was actually asked rather than skipped by the supplied value.
-		"Which column holds the label?": "churned",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
@@ -684,7 +702,7 @@ func TestRunInteractive_SuppliedLabelColumnStillAsks(t *testing.T) {
 	if err := runInteractive(discardPrinter(), f, a); err != nil {
 		t.Fatalf("runInteractive: %v", err)
 	}
-	if !contains(f.asked, "Which column holds the label?") {
+	if !contains(f.asked, "Label:") {
 		t.Errorf("a supplied --label-column must still ASK the label question; asked=%v", f.asked)
 	}
 	if a.Spec.LabelColumn != "churned" {
@@ -706,7 +724,7 @@ func TestRunInteractive_SuppliedLabelColumnStillAsks(t *testing.T) {
 func TestPromptLabelColumn_SuppliedDefaultPrefillsAndGuards(t *testing.T) {
 	dir := tabularDir(t) // header: age,income,churned  (no column named "label")
 	const cat = "tabular_classification"
-	const q = "Which column holds the label?"
+	const label = "Label:"
 
 	cases := []struct {
 		name, supplied, want string
@@ -728,7 +746,7 @@ func TestPromptLabelColumn_SuppliedDefaultPrefillsAndGuards(t *testing.T) {
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			f := &fakePrompter{answers: map[string]string{}}
-			got, err := promptLabelColumn(f, cat, dir, q, tc.supplied)
+			got, err := promptLabelColumn(f, cat, dir, label, tc.supplied)
 			if err != nil {
 				t.Fatalf("promptLabelColumn(supplied=%q) errored (default not guarded into options?): %v", tc.supplied, err)
 			}
@@ -744,8 +762,8 @@ func TestPromptLabelColumn_SuppliedDefaultPrefillsAndGuards(t *testing.T) {
 func TestRunInteractive_Keypoint(t *testing.T) {
 	dir := imageDirLayout(t)
 	f := &fakePrompter{answers: map[string]string{
-		"How many keypoints per sample?": "17",
-		"Which column holds the label?":  "image_label",
+		"Keypoints:": "17",
+		"Label:":     "image_label",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
@@ -767,8 +785,8 @@ func TestRunInteractive_Keypoint(t *testing.T) {
 func TestRunInteractive_TabularRegression(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Label policy": "passthrough",
-		"Which column holds the value to predict?": "income",
+		"Label policy:": "passthrough",
+		"Target:":       "income",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
@@ -792,8 +810,8 @@ func TestRunInteractive_Cancel(t *testing.T) {
 	no := false
 	f := &fakePrompter{
 		answers: map[string]string{
-			"Please name the dataset.":      "t",
-			"Which column holds the label?": "churned",
+			"Name:":  "t",
+			"Label:": "churned",
 		},
 		confirm: &no,
 	}
@@ -806,7 +824,7 @@ func TestRunInteractive_Cancel(t *testing.T) {
 // TestRunInteractive_RejectsBadName: the name prompt runs
 // push.ValidateTableName, so an unsafe name surfaces as an error.
 func TestRunInteractive_RejectsBadName(t *testing.T) {
-	f := &fakePrompter{answers: map[string]string{"Please name the dataset.": "../bad"}}
+	f := &fakePrompter{answers: map[string]string{"Name:": "../bad"}}
 	a := &runDataIngestArgs{Spec: push.SpecArgs{Intent: "train"}}
 	if err := runInteractive(discardPrinter(), f, a); err == nil {
 		t.Fatal("expected an error for an invalid name, got nil")
@@ -818,8 +836,8 @@ func TestRunInteractive_RejectsBadName(t *testing.T) {
 // directory (empty path → Abs("") → cwd).
 func TestRunInteractive_RejectsEmptyPath(t *testing.T) {
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.": "t",
-		"Where is your data?":      "   ",
+		"Name:": "t",
+		"Path:": "   ",
 	}}
 	a := &runDataIngestArgs{Spec: push.SpecArgs{Intent: "train"}}
 	if err := runInteractive(discardPrinter(), f, a); err == nil {
@@ -835,9 +853,9 @@ func TestRunInteractive_RejectsEmptyPath(t *testing.T) {
 func TestRunInteractive_TrimsPath(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Where is your data?":           "  " + dir + "  ",
-		"Which column holds the label?": "churned",
+		"Name:":  "t",
+		"Path:":  "  " + dir + "  ",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{Spec: push.SpecArgs{Intent: "train"}}
 	if err := runInteractive(discardPrinter(), f, a); err != nil {
@@ -859,9 +877,9 @@ func TestRunInteractive_TrimsPath(t *testing.T) {
 func TestRunInteractive_ShowsExampleHints(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "churn_train",
-		"Where is your data?":           dir,
-		"Which column holds the label?": "churned",
+		"Name:":  "churn_train",
+		"Path:":  dir,
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{Spec: push.SpecArgs{Intent: "train"}}
 	var buf bytes.Buffer
@@ -876,6 +894,141 @@ func TestRunInteractive_ShowsExampleHints(t *testing.T) {
 	}
 }
 
+// labelRecorder is fakePrompter plus the Confirm labels, which fakePrompter
+// deliberately drops (its Confirm needs no key). The #504 guard asserts a
+// property of the confirm label too, so it needs to see it.
+type labelRecorder struct {
+	*fakePrompter
+	confirms []string
+}
+
+func (r *labelRecorder) Confirm(label string, def bool) (bool, error) {
+	r.confirms = append(r.confirms, label)
+	return r.fakePrompter.Confirm(label, def)
+}
+
+// maxGuidedLabel is the length budget that makes "short noun label" testable.
+// The longest label the flow ships is "Column types:" (13); the shortest thing
+// it replaced is "Which task?" (11) — so a cap alone would not catch a
+// regression, which is why noQuestionMark below is asserted alongside it.
+const maxGuidedLabel = 16
+
+// TestRunInteractive_EveryGuidedPromptCarriesAShortLabel is the guard for #504.
+//
+// The guided flow used to hand survey an EMPTY Message (surveyPrompter{bare:
+// true}), so the prompt line rendered as a lone "?" — and once command-line
+// values began pre-filling answers, as "? [~/mydata]": a question mark, a
+// bracket and a path, with no verb. Every guided prompt must now carry a short
+// noun label, which survey draws verbatim.
+//
+// The labels are DERIVED, never restated: the test drives the REAL flow and
+// asserts a property of whatever it asks, so a question added later is covered
+// without editing this test. Nothing is scripted by label either — every answer
+// comes from the pre-filled args — so there is no list here to agree with
+// itself (the pass-a-list-to-check-the-list trap).
+//
+// The scenarios exist to widen what the flow asks: one per family plus the
+// variants that unlock the extra questions (regression → label policy,
+// time-to-event → time column, keypoints → keypoint count + resolution,
+// self-supervised text → no label, ambiguous layout → the data-type question).
+func TestRunInteractive_EveryGuidedPromptCarriesAShortLabel(t *testing.T) {
+	cases := []struct {
+		name string
+		args *runDataIngestArgs
+	}{
+		{"tabular-classification", &runDataIngestArgs{
+			LocalPath: tabularDir(t),
+			Spec: push.SpecArgs{
+				Table: "t", Intent: "train",
+				Category: "tabular_classification", LabelColumn: "churned",
+			}}},
+		{"tabular-regression", &runDataIngestArgs{
+			LocalPath: tabularDir(t),
+			Spec: push.SpecArgs{
+				Table: "t", Intent: "train",
+				Category: "tabular_regression", LabelColumn: "income",
+			}}},
+		{"time-to-event", &runDataIngestArgs{
+			LocalPath: tabularDir(t),
+			Spec: push.SpecArgs{
+				Table: "t", Intent: "train",
+				Category: "time_to_event_prediction", LabelColumn: "churned",
+			}}},
+		{"image-keypoints", &runDataIngestArgs{
+			LocalPath: imageDirLayout(t),
+			Spec: push.SpecArgs{
+				Table: "t", Intent: "train",
+				Category: "keypoint_detection", LabelColumn: "label", NumberOfKeypoints: 17,
+			}}},
+		{"text-classification", &runDataIngestArgs{
+			LocalPath: textDirLayout(t),
+			Spec: push.SpecArgs{
+				Table: "t", Intent: "train",
+				Category: "text_classification", LabelColumn: "label",
+			}}},
+		{"self-supervised-text", &runDataIngestArgs{
+			LocalPath: textDirLayout(t),
+			Spec: push.SpecArgs{
+				Table: "t", Intent: "train", Category: "masked_language_modeling",
+			}}},
+		{"ambiguous-layout-asks-data-type", &runDataIngestArgs{
+			LocalPath: t.TempDir(), // no csv, no images/, no texts/
+			Spec:      push.SpecArgs{Table: "t", Intent: "train"},
+		}},
+	}
+
+	total := 0
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			// Nothing is scripted: every answer is the prompt's own default,
+			// pre-filled from args. So the recorded labels are the flow's, not
+			// this test's.
+			r := &labelRecorder{fakePrompter: &fakePrompter{answers: map[string]string{}}}
+			if err := runInteractive(discardPrinter(), r, tc.args); err != nil {
+				t.Fatalf("runInteractive: %v", err)
+			}
+			if len(r.asked) == 0 {
+				// Fail closed: zero labels trivially satisfy every property
+				// below, so "nothing was asked" must be a finding, not a pass.
+				t.Fatalf("no prompts recorded — the guard would be vacuous")
+			}
+			// Each property is its own `if`, never a switch: a full question
+			// violates several at once, and a switch would report only the
+			// first — leaving the others never exercised by any mutation and
+			// therefore unproven.
+			for _, l := range r.asked {
+				if strings.TrimSpace(l) == "" {
+					t.Errorf("prompt label is empty — the `?` line would have no verb (#504)")
+				}
+				if !strings.HasSuffix(l, ":") {
+					t.Errorf("prompt label %q must end in ':' so the line reads `? Path: <answer>`", l)
+				}
+				if strings.Contains(l, "?") {
+					t.Errorf("prompt label %q is a question — the header asks, the label names the answer", l)
+				}
+				if n := len([]rune(l)); n > maxGuidedLabel {
+					t.Errorf("prompt label %q is %d runes, over the %d-rune short-label budget",
+						l, n, maxGuidedLabel)
+				}
+			}
+			// The confirm is the deliberate exception: it has no header of its
+			// own, so it carries the WHOLE question (surveyPrompter.Confirm).
+			if len(r.confirms) == 0 {
+				t.Fatalf("the guided flow must end in a confirm; recorded none")
+			}
+			for _, c := range r.confirms {
+				if !strings.Contains(c, "?") {
+					t.Errorf("confirm label %q must be the whole question — a y/N prompt has no header to carry it", c)
+				}
+			}
+			total += len(r.asked)
+		})
+	}
+	if total == 0 {
+		t.Fatal("no guided prompts observed across any scenario")
+	}
+}
+
 // --- small assertion helpers -------------------------------------------
 
 func contains(hay []string, needle string) bool {
diff --git a/internal/cli/task_scope_test.go b/internal/cli/task_scope_test.go
index 81fc78e..a40d439 100644
--- a/internal/cli/task_scope_test.go
+++ b/internal/cli/task_scope_test.go
@@ -16,9 +16,9 @@ import (
 func TestGuided_TaskScopedValuesDoNotSurviveATaskChange(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which task?":                   "tabular_classification",
-		"Which column holds the label?": "churned",
+		"Name:":  "t",
+		"Task:":  "tabular_classification",
+		"Label:": "churned",
 	}}
 	// A LEGAL starting state: every value here is in scope for the supplied
 	// task. Starting from an illegal one would test the wrong thing — a flag
@@ -56,9 +56,9 @@ func TestGuided_TaskScopedValuesDoNotSurviveATaskChange(t *testing.T) {
 func TestGuided_KeypointsGoWhenTheTaskStopsUsingThem(t *testing.T) {
 	dir := imageDirLayout(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which task?":                   "image_classification",
-		"Which column holds the label?": "label",
+		"Name:":  "t",
+		"Task:":  "image_classification",
+		"Label:": "label",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath:      dir,
@@ -89,9 +89,9 @@ func TestGuided_KeypointsGoWhenTheTaskStopsUsingThem(t *testing.T) {
 func TestGuided_TaskScopedValuesSurviveWhenTheTaskIsUnchanged(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":                 "t",
-		"Which task?":                              "time_to_event_prediction",
-		"Which column holds the value to predict?": "days",
+		"Name:":   "t",
+		"Task:":   "time_to_event_prediction",
+		"Target:": "days",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
@@ -152,9 +152,9 @@ func TestEveryTaskScopedValueRejectsOutOfScopeAndNamesItsFlag(t *testing.T) {
 func TestGuided_AMisappliedFlagIsStillRejectedWhenTheTaskIsKept(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which task?":                   "tabular_classification",
-		"Which column holds the label?": "churned",
+		"Name:":  "t",
+		"Task:":  "tabular_classification",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
@@ -176,9 +176,9 @@ func TestGuided_AMisappliedFlagIsStillRejectedWhenTheTaskIsKept(t *testing.T) {
 func TestGuided_AMisappliedFlagIsStillRejectedWhenNoTaskWasSupplied(t *testing.T) {
 	dir := tabularDir(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which task?":                   "tabular_classification",
-		"Which column holds the label?": "churned",
+		"Name:":  "t",
+		"Task:":  "tabular_classification",
+		"Label:": "churned",
 	}}
 	a := &runDataIngestArgs{LocalPath: dir, Spec: push.SpecArgs{TimeColumn: "t"}}
 	if err := runInteractive(discardPrinter(), f, a); err != nil {
@@ -203,8 +203,8 @@ func TestGuided_AMisappliedFlagIsStillRejectedWhenNoTaskWasSupplied(t *testing.T
 func TestGuided_AnUnrecognizedTaskIsNotATaskChange(t *testing.T) {
 	dir := textDirLayout(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.": "mlm_train",
-		"Which task?":              "masked_language_modeling",
+		"Name:": "mlm_train",
+		"Task:": "masked_language_modeling",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
@@ -233,9 +233,9 @@ func TestGuided_AnUnrecognizedTaskIsNotATaskChange(t *testing.T) {
 func TestGuided_AFlagInvalidForBothTasksIsStillRejected(t *testing.T) {
 	dir := imageDirLayout(t)
 	f := &fakePrompter{answers: map[string]string{
-		"Please name the dataset.":      "t",
-		"Which task?":                   "image_classification",
-		"Which column holds the label?": "label",
+		"Name:":  "t",
+		"Task:":  "image_classification",
+		"Label:": "label",
 	}}
 	a := &runDataIngestArgs{
 		LocalPath: dir,
diff --git a/internal/cli/testdata/golden/01-data-ingest.golden b/internal/cli/testdata/golden/01-data-ingest.golden
index 15f6427..587805d 100644
--- a/internal/cli/testdata/golden/01-data-ingest.golden
+++ b/internal/cli/testdata/golden/01-data-ingest.golden
@@ -7,7 +7,8 @@ driven through the real flow for one task in each family (tabular, image, text)
 so the task-specific questions are visible; each core question prints as a
 `Step N of 4 · …` header, the task-specific ones (the label column, and extras
 like resolution or schema) as their own header, the
-supporting line beneath it, and the `?` line shows your answer. The run (shown
+supporting line beneath it, and the `?` line carries a short noun label
+(`Path:`, `Task:`) plus your answer. The run (shown
 once, for tabular) is the three steps + the final summary as the CLI renders
 them. Values passed as flags (--as, --task, a path, …) pre-fill the matching
 questions rather than skipping them — guided mode always asks. The
@@ -25,11 +26,11 @@ $ tb data ingest   # guided · tabular classification
 
   Step 1 of 4 · Do you want to ingest training or test data?
 
-? train
+? Split: train
 
   Step 2 of 4 · Please name the dataset.
 
-? hospital_train
+? Name: hospital_train
 
   Step 3 of 4 · Where is your data?
 
@@ -38,7 +39,7 @@ $ tb data ingest   # guided · tabular classification
   · Images    a folder with labels.csv + images/   e.g. ~/data/xray/
   · Text      a folder with labels.csv + texts/     e.g. ~/data/reviews/
 
-? ~/data/patients
+? Path: ~/data/patients
   ✔ Found a CSV table — this is tabular data.
 
   Step 4 of 4 · What kind of machine learning task is this data for?
@@ -49,19 +50,19 @@ $ tb data ingest   # guided · tabular classification
     time_series_classification   predict a class for each whole sequence
     time_to_event_prediction     predict how long until an event happens
 
-? tabular_classification
+? Task: tabular_classification
 
   Which column holds the label?
 
   The answer the model learns to produce — for classification, the class.  e.g. diagnosis, churned
 
-? churned
+? Label: churned
 
   Column types
 
   We infer each column's type from your CSV. Press Enter to accept, or type overrides like age:INT,price:FLOAT.
 
-?
+? Column types:
 
   Review
     name:          hospital_train
@@ -80,11 +81,11 @@ $ tb data ingest   # guided · image classification
 
   Step 1 of 4 · Do you want to ingest training or test data?
 
-? train
+? Split: train
 
   Step 2 of 4 · Please name the dataset.
 
-? xray_train
+? Name: xray_train
 
   Step 3 of 4 · Where is your data?
 
@@ -93,7 +94,7 @@ $ tb data ingest   # guided · image classification
   · Images    a folder with labels.csv + images/   e.g. ~/data/xray/
   · Text      a folder with labels.csv + texts/     e.g. ~/data/reviews/
 
-? ~/data/xray
+? Path: ~/data/xray
   ✔ Found labels.csv and an images/ folder — this is image data.
 
   Step 4 of 4 · What kind of machine learning task is this data for?
@@ -103,19 +104,19 @@ $ tb data ingest   # guided · image classification
     keypoint_detection      locate landmark points on an image (e.g. pose)
     semantic_segmentation   label every pixel in an image
 
-? image_classification
+? Task: image_classification
 
   Which column holds the label?
 
   The answer the model learns to produce — for classification, the class.  e.g. diagnosis, churned
 
-? label
+? Label: label
 
   Image resolution
 
   The size your images already are, as WxH — tracebloc checks every image matches and never resizes. Press Enter to read it from your first image.  e.g. 224x224
 
-? 224x224
+? Resolution: 224x224
 
   Review
     name:          xray_train
@@ -134,11 +135,11 @@ $ tb data ingest   # guided · text classification
 
   Step 1 of 4 · Do you want to ingest training or test data?
 
-? train
+? Split: train
 
   Step 2 of 4 · Please name the dataset.
 
-? reviews_train
+? Name: reviews_train
 
   Step 3 of 4 · Where is your data?
 
@@ -147,7 +148,7 @@ $ tb data ingest   # guided · text classification
   · Images    a folder with labels.csv + images/   e.g. ~/data/xray/
   · Text      a folder with labels.csv + texts/     e.g. ~/data/reviews/
 
-? ~/data/reviews
+? Path: ~/data/reviews
   ✔ Found labels.csv and a texts/ folder — this looks like text data.
 
   Step 4 of 4 · What kind of machine learning task is this data for?
@@ -160,13 +161,13 @@ $ tb data ingest   # guided · text classification
     sentence_pair_classification   label how two texts relate
     embeddings                     learn vector representations from text pairs
 
-? text_classification
+? Task: text_classification
 
   Which column holds the label?
 
   The answer the model learns to produce — for classification, the class.  e.g. diagnosis, churned
 
-? label
+? Label: label
 
   Review
     name:          reviews_train
diff --git a/internal/cli/testdata/golden/zz-all-strings.golden b/internal/cli/testdata/golden/zz-all-strings.golden
index 3dec5c0..ea60b29 100644
--- a/internal/cli/testdata/golden/zz-all-strings.golden
+++ b/internal/cli/testdata/golden/zz-all-strings.golden
@@ -121,6 +121,7 @@ screen. %s/%d are runtime placeholders.
 "Clients in your account"
 "Cluster teardown reported: %v"
 "Column types"
+"Column types:"
 "Connected to tracebloc"
 "Connecting to your secure environment to submit the run"
 "Connecting to your secure environment…"
@@ -146,6 +147,7 @@ screen. %s/%d are runtime placeholders.
 "DB failures"
 "DELETE FROM `%s`.`%s` WHERE table_name='%s'"
 "DROP TABLE IF EXISTS `%s`.`%s`"
+"Data type:"
 "Datasets in %s (0)"
 "Datasets in %s — %d"
 "Delete %q and its files?"
@@ -199,8 +201,10 @@ screen. %s/%d are runtime placeholders.
 "Ingests a local dataset into your secure environment's storage,\nsubmits the ingestion run, and follows it to completion (streaming\nprogress + the final summary). Your data never leaves your own\ninfrastructure. Supports %[1]d tasks across the image, text, and\ntabular / time-series families; pick one with --task.\n\n<dataset> is the data itself. What it looks like depends on the task:\n\n  tabular / time-series — the dataset is a single CSV. Pass the .csv\n  file directly, or a folder holding exactly one .csv:\n\n      churn.csv                (the .csv file itself)\n    or\n      churn/\n        data.csv               (the one .csv in the folder)\n\n  image (classification, object/keypoint detection) — a folder with\n  labels.csv + an images/ subfolder:\n\n      cats_dogs/\n        labels.csv             (required)\n        images/                (required)\n          001.jpg\n          ...\n\n  text (classification, masked language modeling) — a folder with\n  labels.csv + a %[2]s/ subfolder (masked language modeling uses %[3]s/):\n\n      reviews/\n        labels.csv             (required)\n        %[2]s/                 (required — %[3]s/ for masked language modeling)\n          001.txt\n          ...\n\nA bare .csv file is accepted only for the tabular / time-series family;\nimage and text datasets must be a folder.\n\nAccepted image extensions: .jpg, .jpeg, or .png (case-insensitive).\nAll images in one dataset must share a single type — the cluster\nvalidates the type it was told to expect.\n\nv0.1 caps the dataset at 1 GiB total + 500 MiB per file. Larger\ndatasets need the v0.2 cloud-source story (S3/GCS/HTTPS sources) —\nsee tracebloc/client#147 non-goals.\n\nExit codes:\n  0   files staged + ingested successfully (or --detach: just staged + submitted)\n  2   schema validation failed (synthesized spec rejected) or\n      v0.1-unsupported task passed\n  3   local-layout or kubeconfig error\n  4   cluster reachable but no tracebloc client / shared storage missing\n  5   ingestor SA token couldn't be obtained, or jobs-manager\n      rejected the token (401/403)\n  6   destination table already exists (re-run with --overwrite to\n      replace it, or pick a different --name)\n  7   pre-flight succeeded but staging the files failed\n      (Pod creation, image pull, exec stream, or remote tar error) —\n      or, with --overwrite, removing the old table failed\n  8   jobs-manager rejected the submit (4xx/5xx other than auth)\n  9   ingestion Job exited non-zero, or completed with row-level\n      failures the summary panel reports"
 "Kept local data and config (~/.tracebloc); cleared the active-client pointer — --keep-data."
 "Kept on tracebloc"
+"Keypoints:"
 "Kubeconfig"
 "Label policy"
+"Label policy:"
 "Left %s in place — it isn't tracebloc's `tb` alias."
 "Left alone"
 "Let each training run use up to %s?"
@@ -208,6 +212,7 @@ screen. %s/%d are runtime placeholders.
 "Machine credential — needed by the installer to connect this client"
 "Memory"
 "Memory for one run in GiB (2–%d)"
+"Name:"
 "No client in namespace %q — using the one in %q (override with --namespace)."
 "No clients yet. Run `tracebloc client create`."
 "No datasets yet — ingest one with `%s data ingest`."
@@ -235,6 +240,7 @@ screen. %s/%d are runtime placeholders.
 "Open"
 "POST %s%s: %w"
 "PVC is %v, not ReadWriteMany — the stage Pod will co-locate with the existing mounter"
+"Path:"
 "Pending > %s: %v"
 "Pick this dataset when you set it up."
 "Please name the dataset."
@@ -265,6 +271,7 @@ screen. %s/%d are runtime placeholders.
 "Removed the tracebloc CLI from this machine."
 "Removing in-cluster artifacts…"
 "Removing the existing %q first"
+"Resolution:"
 "Review"
 "Revoked this machine's credential — your secure environment %q stays on tracebloc as a record."
 "Run '%s --help' for the available commands."
@@ -287,6 +294,7 @@ screen. %s/%d are runtime placeholders.
 "Signed-in token was rejected by the backend — run `tracebloc login`."
 "Some pods are stuck starting — usually not enough free compute, or a training image that can't be pulled. %s Then re-run `%s doctor`; if it persists, email support@tracebloc.io with `%s doctor --diagnose`."
 "Some tracebloc images couldn't be reclaimed (harmless) — remove them later with `docker rmi $(docker images --filter=reference='ghcr.io/tracebloc/*' --format '{{.Repository}}:{{.Tag}}')`."
+"Split:"
 "Still stuck? Email support@tracebloc.io with the output of `%s doctor --diagnose`."
 "Stopped following after 1 hour — the ingestion is still running and will finish on its own."
 "Stopped watching — the ingestion keeps running on your secure environment."
@@ -299,6 +307,7 @@ screen. %s/%d are runtime placeholders.
 "Tabular   one CSV file                        e.g. %s"
 "Target"
 "Target cluster"
+"Task:"
 "Text      a folder with labels.csv + texts/     e.g. %s"
 "The column holding the duration / time-to-event.  e.g. time, tenure_days"
 "The dataset's catalog metadata is kept as a record on tracebloc, marked unavailable — never removed."
@@ -318,6 +327,7 @@ screen. %s/%d are runtime placeholders.
 "This secure environment isn't in the signed-in account — continuing; if that's unexpected, check you're logged into the right account."
 "This will remove"
 "Time column"
+"Time column:"
 "To train or benchmark models on it, create a use case at https://ai.tracebloc.io/my-use-cases"
 "To update tracebloc on Windows, run this in a new PowerShell window:"
 "Training results can't reach tracebloc — experiments will stall."
@@ -342,7 +352,6 @@ screen. %s/%d are runtime placeholders.
 "What kind of machine learning task is this data for?"
 "What's next"
 "Where is your data?"
-"Which task?"
 "Will delete"
 "Wrote a support bundle to ./%s"
 "Wrote client id + namespace to %s (no new credential — the existing one stands)."

From a36053658245836abfe24a0a90cdaca850627dc2 Mon Sep 17 00:00:00 2001
From: lukasWuttke <54042461+LukasWodka@users.noreply.github.com>
Date: Mon, 17 Aug 2026 13:37:07 +0200
Subject: [PATCH 2/5] fix(sanitize): strip SS3 escapes and floor escape-only
 names (#516) (#520)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(sanitize): strip SS3 escapes and floor escape-only names (cli#516)

sanitizeClientName handled CSI (ESC '[' … final) only. SS3 (ESC 'O' final) is
what the same arrow / Home / End / F-keys emit once the terminal is in DECCKM
application-cursor mode — the state vim, less or tmux leave behind on an unclean
exit. That residue was worse than the CSI residue fixed in cli#364 / client#362
(2026-07-21, not re-litigated here): CSI cleans to empty and re-prompts, while
'O' and the final byte are printable, so ESC OD ×3 ESC OA ×3 survived as the
plausible name "ODODODOAOAOA" and minted the permanent namespace "odododoaoaoa".

Nothing downstream can refuse it: is_dns1123_label validates by idempotence
against the slug rule, so escape-derived garbage is a perfectly canonical label.
Form is exactly what this input preserves.

Two changes, both in sanitizeClientName — deliberately NOT in internal/slug,
which must stay a faithful mirror of backend/common/utils/slug.py:

  1. escSequence now matches CSI and SS3 in one pattern.
  2. A post-sanitise floor. If an ESC SURVIVES step 1 the value carries an escape
     family we do not recognise — which is precisely how SS3 got here — so it
     must show one alphanumeric that did not come from an escape final byte,
     probed with a greedier pattern whose output is never returned. Nothing but
     residue returns "", the same path an omitted --name takes. Scoped to "an ESC
     survived" so a clean name never reaches it and real content beside an
     unknown escape is kept; the failure it chooses is the recoverable one.

Tests: 10 new cases in the table (SS3 arrows / Home-End / F-keys / mixed with
CSI / truncated / a bare O is not an escape; the floor with SS2 standing in for
"the next family", including the non-Latin-content case) plus a test pinning the
ticket's exact repro and the slug it used to mint.

Mutation-proven, three anchors, each applied and each detected:
  • SS3 dropped from escSequence  -> 2 cases red ("na\x1bODme", SS3+CSI mixed)
  • floor short-circuited to false -> 2 cases red (truncated SS3, unknown family)
  • hasAlphanumeric made ASCII-only -> 1 case red (non-Latin content)
The "SS3 arrows only" case is green under anchor 1 because the floor also covers
it; anchor 1 is carried by the mixed-content cases, which the floor cannot mask.

The bash and PowerShell peers get the same two changes in tracebloc/client.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(release): VERSION 0.10.8 -> 0.10.9 (cli#516)

version-bump-gate is a required check and it refuses a PR that touches
internal/* while VERSION still names an already-released version: v0.10.8 is
out, so shipping this fix under it would put different bytes under an existing
release. 0.10.9 is untagged and above every released final version, and it is
the same target the other two open PRs on develop bump to — identical one-line
changes merge without conflict, and all three then ship under the pending
0.10.9.

Not a hand-cut release: the release train still reads this file and cuts the tag
from it at the prod hop. The gate's own message is explicit that it never bumps
for you, and that a stale VERSION fails days later on somebody else's hop
(backend#1561) rather than here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(sanitize): bound the floor's probe to two final bytes (cli#516)

Bugbot, Medium, on tracebloc/client#736: the floor's probe used an unbounded
`[A-Za-z~]+` after an unrecognised ESC, so every ASCII letter following the
escape was swallowed into the probe and the value read as residue-only. It is
right, and the sharper half of it is the part I had not seen: `\x1bNChello` was
refused while `\x1bNC日本` was kept, which makes keep-vs-reject depend on the
script the user's name is written in. I had accepted the over-strictness on
purpose; I had not noticed it was inconsistent.

Bounded to `{1,2}`. Two, not one and not unbounded: one leaves the 'D' of an
unrecognised SS3-shaped pair behind and the floor stops firing on the exact
family shape this ticket is about, while unbounded eats a whole name. An escape
final is one byte, an intro plus a final is two, and every keyboard-input escape
family (SS2, SS3, the 7-bit C1 forms) fits in that — so the bound is a statement
about escapes rather than a tuning constant.

Every case the floor is meant to catch is unaffected: ESC N B / ESC N C, a
truncated ESC O, and ESC [ ; ] A all still collapse to empty.

Applied to all three copies so the rule stays one rule.

Mutation-proven: reverting `{1,2}` to `+` turns the new case red in Go
("\x1bNChello" -> "") and in bats.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 internal/cli/sanitize.go      | 105 +++++++++++++++++++++++++++-------
 internal/cli/sanitize_test.go |  47 +++++++++++++++
 2 files changed, 132 insertions(+), 20 deletions(-)

diff --git a/internal/cli/sanitize.go b/internal/cli/sanitize.go
index f14ae13..0847bf2 100644
--- a/internal/cli/sanitize.go
+++ b/internal/cli/sanitize.go
@@ -3,41 +3,98 @@ package cli
 import (
 	"regexp"
 	"strings"
+	"unicode"
 )
 
-// csiSequence matches an ANSI CSI sequence: ESC '[' <params ∈ [0-9;]> <final ∈
-// [A-Za-z~]>. This is what a terminal emits for arrow keys / cursor moves
-// (ESC[A/B/C/D, ESC[1;5C, ESC[3~ …) and for bracketed-paste wrappers
-// (ESC[200~ … ESC[201~). It is deliberately broader than submit.stripANSI,
-// which only strips SGR colour codes (final byte 'm').
-var csiSequence = regexp.MustCompile("\x1b\\[[0-9;]*[A-Za-z~]")
+// escSequence matches the two ANSI escape families a terminal actually sends for
+// cursor / function keys:
+//
+//	CSI  ESC '[' <params ∈ [0-9;]> <final ∈ [A-Za-z~]>
+//	     ESC[A/B/C/D (arrows), ESC[1;5C (Ctrl+arrow), ESC[3~ (Delete),
+//	     ESC[200~ … ESC[201~ (bracketed paste)
+//	SS3  ESC 'O' <final ∈ [A-Za-z~]>
+//	     ESC OA/OB/OC/OD (arrows), ESC OH/OF (Home/End), ESC OP…OS (F1–F4)
+//
+// SS3 is what the *same* keys emit once the terminal is in DECCKM
+// application-cursor mode — the state vim, less or tmux leave behind on an
+// unclean exit (cli#516). Handling only CSI was the remaining hole: an ESC alone
+// is a C0 byte and gets dropped below, but 'O' and the final byte are printable,
+// so "\x1bOD\x1bOD\x1bOA" survived as the plausible-looking name "ODODOA" and
+// minted the immutable namespace "ododoa". CSI residue never did: it cleans to
+// empty, fails the non-empty check and re-prompts.
+//
+// Deliberately broader than submit.stripANSI, which only strips SGR colour codes
+// (final byte 'm').
+var escSequence = regexp.MustCompile("\x1b(?:\\[[0-9;]*|O)[A-Za-z~]")
+
+// escResidue is the post-sanitise floor's *probe*, not a strip: ESC, any run of
+// non-final intermediate bytes, then AT MOST TWO bytes that could be escape final
+// bytes. Its only job is to answer one question — "is there an alphanumeric here
+// that did NOT come from an escape final byte?" — and its output is never
+// returned as a name.
+//
+// Two, not one and not unbounded. One is too few: it leaves the 'D' of an
+// unrecognised SS3-shaped pair behind, and the floor stops firing on exactly the
+// family shape this ticket is about. Unbounded is too many: `\x1bNChello` would
+// have the whole name swallowed and be refused, while `\x1bNC日本` survives —
+// making keep-vs-reject depend on the script the user's name is written in
+// (Bugbot, tracebloc/client#736). Two is the honest bound: an escape final is one
+// byte, an intro plus a final is two, and every keyboard-input escape family
+// (SS2, SS3, the 7-bit C1 forms) fits in that.
+var escResidue = regexp.MustCompile("\x1b[^A-Za-z0-9~]*[A-Za-z~]{1,2}")
 
 // sanitizeClientName strips terminal escape sequences and C0 control characters
 // from a user-supplied client name or location before it becomes the stored
 // display name and is slugified into an immutable Kubernetes namespace.
 //
-// Defense-in-depth for the name-garble bug (customer-reported 2026-07-20): typing
-// arrow keys at the installer's name prompt injected raw ESC[D/ESC[A bytes. The
-// installer now strips them at the source, but a name can also arrive here
-// directly via --name / $TRACEBLOC_CLIENT_NAME, and slug.Slugify would otherwise
-// turn each ESC[<x> run into a "-" — ESC (0x1B) survives Slugify's ASCII pass, so
-// "se-\e[D\e[D\e[A\e[A" mints the garbage namespace "se-d-d-a-a". Cleaning here,
-// at the CLI boundary, keeps slug.Slugify a faithful mirror of the backend's
-// slug.py (which must NOT strip — the backend validates exactly what it produces);
-// input hygiene belongs at ingestion, not in the shared slug rule.
+// Defense-in-depth for the name-garble bug (customer-reported 2026-07-20, fixed
+// 2026-07-21 in cli#364 / client#362): typing arrow keys at the installer's name
+// prompt injected raw ESC[D/ESC[A bytes. The installer strips them at the source,
+// but a name can also arrive here directly via --name / $TRACEBLOC_CLIENT_NAME,
+// and slug.Slugify would otherwise turn each ESC[<x> run into a "-" — ESC (0x1B)
+// survives Slugify's ASCII pass, so "se-\e[D\e[D\e[A\e[A" mints the garbage
+// namespace "se-d-d-a-a". Cleaning here, at the CLI boundary, keeps slug.Slugify
+// a faithful mirror of the backend's slug.py (which must NOT strip — the backend
+// validates exactly what it produces); input hygiene belongs at ingestion, not in
+// the shared slug rule.
+//
+// Escape-derived garbage cannot be caught downstream: is_dns1123_label validates
+// by idempotence against the slug rule, so "ododoa" is a perfectly canonical
+// label. Form is exactly what this class of input preserves — hence the floor
+// below, which is about *content*, not form.
 //
 // UTF-8 bytes (>= 0x80) are preserved so international names survive.
 func sanitizeClientName(s string) string {
-	// 1) Whole CSI sequences (arrow keys, paste wrappers). ReplaceAll handles
-	//    consecutive sequences in one pass; any orphaned ESC left behind is a C0
-	//    byte and is removed by step 3.
-	s = csiSequence.ReplaceAllString(s, "")
+	// 1) Whole escape sequences (arrow keys in either cursor mode, function keys,
+	//    paste wrappers). ReplaceAll handles consecutive sequences in one pass;
+	//    any orphaned ESC left behind is a C0 byte and is removed by step 4.
+	s = escSequence.ReplaceAllString(s, "")
 	// 2) Post-corruption case: an earlier (buggy) sanitizer dropped the ESC but
 	//    left the literal bracketed-paste markers. Only these two well-defined
 	//    markers are removed — a generic "[x~" could be real name content.
 	s = strings.ReplaceAll(s, "[200~", "")
 	s = strings.ReplaceAll(s, "[201~", "")
-	// 3) Drop any remaining C0 control characters and DEL; keep printable ASCII
+	// 3) The floor. Steps 1–2 know CSI, SS3 and the paste markers; they cannot
+	//    know the escape family nobody has reported yet, and that is precisely how
+	//    SS3 got here — one rule, three hand-copied implementations, no member of
+	//    the family beyond CSI ever tested. So: if an ESC SURVIVED step 1, this
+	//    value carries an escape shape we do not recognise, and the printable
+	//    bytes around it are not trustworthy name content. Require at least one
+	//    alphanumeric that did not come from an escape final byte (at most two of
+	//    them — see escResidue); if there is none, the whole value was residue —
+	//    return "" and let the caller auto-name (the same path an omitted --name
+	//    takes).
+	//
+	//    Scoped to "an ESC survived" on purpose. It is the narrowest trigger that
+	//    still covers unknown families: a clean name never reaches it, a name with
+	//    real content next to an unknown escape keeps that content, and only a
+	//    value that is *nothing but* escape residue is rejected. The failure it
+	//    chooses is the recoverable one — auto-naming a name is annoying; minting
+	//    a permanent namespace from keyboard noise is not.
+	if strings.ContainsRune(s, 0x1b) && !hasAlphanumeric(escResidue.ReplaceAllString(s, "")) {
+		return ""
+	}
+	// 4) Drop any remaining C0 control characters and DEL; keep printable ASCII
 	//    and all multi-byte UTF-8 (>= 0x80).
 	return strings.Map(func(r rune) rune {
 		if r < 0x20 || r == 0x7f {
@@ -46,3 +103,11 @@ func sanitizeClientName(s string) string {
 		return r
 	}, s)
 }
+
+// hasAlphanumeric reports whether s contains any letter or digit, Unicode
+// included — a name written entirely in a non-Latin script is real content.
+func hasAlphanumeric(s string) bool {
+	return strings.IndexFunc(s, func(r rune) bool {
+		return unicode.IsLetter(r) || unicode.IsDigit(r)
+	}) >= 0
+}
diff --git a/internal/cli/sanitize_test.go b/internal/cli/sanitize_test.go
index ec4c765..5e9915a 100644
--- a/internal/cli/sanitize_test.go
+++ b/internal/cli/sanitize_test.go
@@ -22,6 +22,30 @@ func TestSanitizeClientName(t *testing.T) {
 		{"CSI with params (Ctrl+arrow)", "x\x1b[1;5Dy", "xy"},
 		{"Delete key (ESC[3~)", "ab\x1b[3~", "ab"},
 
+		// SS3 (cli#516): the SAME keys once the terminal is in DECCKM
+		// application-cursor mode, which vim/less/tmux leave behind on an unclean
+		// exit. Unlike CSI residue these used to survive as a plausible name.
+		{"SS3 arrows around real content", "na\x1bODme", "name"},
+		{"SS3 arrows only cleans to empty (→ auto-name)", "\x1bOD\x1bOD\x1bOD\x1bOA\x1bOA\x1bOA", ""},
+		{"SS3 Home/End only", "\x1bOH\x1bOF", ""},
+		{"SS3 F1/F2 only", "\x1bOP\x1bOQ", ""},
+		{"SS3 and CSI mixed", "a\x1bODb\x1b[Dc", "abc"},
+		{"truncated SS3 (ESC O, no final)", "\x1bO", ""},
+		{"a bare O is not an escape", "OPTIMUS-01", "OPTIMUS-01"},
+
+		// The floor: an ESC that survived the known families means an escape shape
+		// we don't recognise, so what is left has to prove it is real content.
+		// SS2 (ESC N <final>) stands in for "the next family" — it is not stripped
+		// by escSequence, so these exercise the floor and nothing else.
+		{"unknown escape family, nothing but residue (→ auto-name)", "\x1bNB\x1bNC", ""},
+		{"unknown escape family beside real content is kept", "box\x1bNC", "boxNC"},
+		{"floor counts non-Latin letters as real content", "\x1bNC日本", "NC日本"},
+		// The probe's final-byte run is bounded at two, so an ASCII name after an
+		// unknown escape is kept just like a non-Latin one — keep-vs-reject must
+		// not depend on the script the name is written in (Bugbot,
+		// tracebloc/client#736).
+		{"floor keeps an ASCII name after an unknown escape", "\x1bNChello", "NChello"},
+
 		// Bracketed paste.
 		{"bracketed-paste wrappers", "\x1b[200~hello\x1b[201~", "hello"},
 		{"post-corruption literal paste markers", "[200~hello[201~", "hello"},
@@ -63,3 +87,26 @@ func TestSanitizeClientName_neutralizesSlugGarble(t *testing.T) {
 		t.Fatalf("slug.Slugify(sanitizeClientName(raw)) = %q, want %q", got, "se")
 	}
 }
+
+// TestSanitizeClientName_ss3SurvivesAsAPlausibleName is the cli#516 half: SS3
+// residue was worse than the CSI residue fixed in cli#364 / client#362, because
+// it did NOT clean to empty. 'O' and the final byte are printable, so dropping
+// only the ESC left a non-empty, plausible-looking name that passed every
+// downstream check — is_dns1123_label validates by idempotence against the slug
+// rule, and "odododoaoaoa" is a perfectly canonical label. Form is exactly what
+// this input preserves, so nothing but this function can refuse it.
+func TestSanitizeClientName_ss3SurvivesAsAPlausibleName(t *testing.T) {
+	const garbled = "\x1bOD\x1bOD\x1bOD\x1bOA\x1bOA\x1bOA" // ← ← ← ↑ ↑ ↑ in DECCKM mode
+
+	// What the CSI-only sanitizer produced: ESC removed as a C0 byte, the rest
+	// kept verbatim — and slugifying that mints a permanent namespace.
+	if got := slug.Slugify("ODODODOAOAOA"); got != "odododoaoaoa" {
+		t.Fatalf("precondition: slug.Slugify(%q) = %q, want the documented garble %q", "ODODODOAOAOA", got, "odododoaoaoa")
+	}
+
+	// With SS3 handled, the value cleans to empty, which client create treats
+	// exactly like an omitted --name: it auto-names instead of minting garbage.
+	if got := sanitizeClientName(garbled); got != "" {
+		t.Fatalf("sanitizeClientName(%q) = %q, want %q (the auto-name path)", garbled, got, "")
+	}
+}

From b81e5f98cc1b19661956a49f4779785a0be45889 Mon Sep 17 00:00:00 2001
From: lukasWuttke <54042461+LukasWodka@users.noreply.github.com>
Date: Mon, 17 Aug 2026 15:21:48 +0200
Subject: [PATCH 3/5] =?UTF-8?q?fix(cli):=20diagnose=20before=20advising=20?=
 =?UTF-8?q?=E2=80=94=20a=20wrong=20active-client=20pointer=20has=20a=20way?=
 =?UTF-8?q?=20back=20(cli#515)=20(#519)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(cluster): say which namespace, instead of offering --namespace blindly

The §7.3 binding-miss error is RFC-0001's sentence with the remedy deleted:
it names --namespace but never says WHICH namespace, and nothing else in the
CLI will tell you. On a laptop with a healthy local install that left no
supported way back.

explain now diagnoses before advising. A binding-applied noParentReleaseError
carries the clientset and server URL of the cluster that actually missed, and
explain spends one naming-only cluster.FindClientNamespaces — the same read
discoverRelease already spends purely to write a better message — then branches
on isLocalServerURL:

  one client + local server URL  name it, offer `client create` (a re-run on a
                                 cluster that already hosts a client adopts it,
                                 so the repoint mints nothing)
  client(s) on a remote cluster  name the namespaces, offer ONLY --namespace;
                                 never `client create` there, because the client
                                 we found may be a colleague's (§7.5)
  none, scan clean               today's text plus "No tracebloc client is
                                 running on this cluster either", which is when
                                 the installer is the right advice
  could not look                 today's text, byte for byte

The last branch is the point of the three-valued clientSurvey: a nil probe or a
failed scan is an absence of evidence, and printing it as "nothing is running
here" would tell a user with a working client the opposite of the truth.

allowScan() is untouched and still false for an applied binding: this changes
what the CLI says, never what it targets. TestActiveClientBinding_AllowScan and
TestDiscoverRelease_NoScanWhenExplicit pass unmodified, and
TestExplain_BindingMiss_NamesTheLocalClientWithoutRetargeting pins both halves
at once — the namespace appears in the message and nowhere else.

The probe travels on the error rather than through explain's signature so a
caller cannot hand it a clientset for a different cluster than the one that
missed; six of the seven call sites never held one anyway (resolveClusterTarget
builds it internally and returns nil on the error path).

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(doctor,home): a wrong pointer is not proof there is no environment

#401 taught the home screen that an EMPTY active-client pointer says nothing
about what runs on this machine. The wrong-pointer case was never covered, and
it is the worse one: doctor binds the stale pointer, probes only that namespace,
never scans, and prints "No secure environment on this machine yet" with the
installer command underneath — over a perfectly healthy install. home has the
same hole from the other side: its local-env fallback sat behind
`if !binding.applied`, so a non-empty pointer skipped the #401 fix entirely.

Both now route the miss through the same fallback:

  home    the ErrNoParentRelease branch returns localEnvFallback(ctx) instead of
          a bare localNoRelease. Every failure inside the fallback degrades to
          localNoRelease, so this branch's old return value is still its floor.
  doctor  on a ReachNoEnv result that a BINDING (not the user) aimed, re-probe
          the namespace the kubeconfig itself selects, via localEnvNamespace.

The ownership gate is what makes this safe, and it is unchanged: both adopt only
when isLocalServerURL says the kubeconfig's server is this machine — a cluster
that is this machine by definition, so whatever runs there is this machine's
environment. On a remote or shared cluster the honest no-environment answer
stands, and a colleague's client is never greeted as yours (§7.5).

No scan is spent either: the installer points the kubeconfig context at the
client's namespace (client/scripts/lib/install-client-helm.sh runs `kubectl
config set-context --current --namespace <ns>`), so reading the context is
enough to find a healthy install that the pointer missed.

doctor keeps the original results unless the re-probe actually finds an
environment, so a genuinely bare machine still gets the installer advice and the
--diagnose bundle still describes the namespace the user is configured for. An
explicit --namespace is never second-guessed — no binding, no re-probe.

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(client): list `create`, and stop calling a stale pointer "this machine"

Two things the diagnose-before-advising fix needs in order to reach anyone.

`client create` is visible. It was Hidden because a human running it standalone
on a cluster with no client mints one the installer never deploys — an orphaned
phantom (backend#970). That risk is real and unchanged, but hiding the command
was never what prevented it. The two guards that do are untouched, and now have
tests naming them:

  • on a TTY, the review + "Provision this client?" confirm. A re-run on a
    cluster that already hosts a client never reaches it — adoption happens
    first — so the repoint stays prompt-free and mints nothing.
  • off a TTY, a hard refusal without --yes/--credential-file, so a pipe or CI
    can never mint silently.

What hiding did cost is #515: the one command that repoints a machine was
unlisted, so the error telling a user to repoint pointed at nothing they could
find. Its Short/Long now describe what it does for a user (adopt/repoint) rather
than the installer's use of it. `client list` stays hidden.

`client list` marks residency, not just selection. It labelled the active
pointer "(active — this machine)" without ever checking where that client runs —
so in exactly the state this ticket is about, the listing sat there confirming a
client provably not on this machine. Selection (the local pointer) and residency
(does it run on the cluster the kubeconfig reaches, keyed on the §7.2 cluster
anchor) are now two separate facts, and a mismatch names the repoint.

An unreadable anchor is a third state, not a "no": with no kubeconfig or an
unreachable API server, no row claims to be here and none is denied — the marker
degrades to bare "(active)". The installer's #303 pre-flight is unaffected; the
markers sit in the row label and the greppable `namespace=<ns>` field is
untouched (client_list_contract_test.go still passes).

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(cli): regenerate the copy catalog; `client create` is no longer hidden

The golden diff is the whole user-visible change, reviewed line by line:

  08-client.golden      `create` now appears under Available Commands, with its
                        new Short and the Long that explains adoption.
  zz-all-strings.golden the five §7.3 branches and the `client list` mismatch
                        hint.

Each branch of repointMessage is one format literal rather than a `+`-joined
string, because the catalog's AST harvest only sees literal arguments — the
message it replaced was invisible there for exactly that reason, and half a
sentence in the completeness backstop is worse than none.

cli-navigation.md carried two statements this change makes false: it drew
`client create` as a hidden node, and its exit-4 remedy line said "run the
installer (or --namespace)", which is now only one of three answers.

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(release): bump VERSION to 0.10.9

v0.10.8 is already released and this PR changes published files under
`internal/*`, so version-bump-gate (a required check) asks for the bump here
rather than leaving it to fail the next prod hop on somebody else
(backend#1561). The release train reads VERSION and cuts the tag from it.

Patch, matching this repo's dominant pattern for user-facing copy and surface
changes — say so on the PR if 0.11.0 is wanted for the `client create` unhide.

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(cluster): say why explain replaces the error instead of wrapping it

`%w` is the house convention (~325 sites), which makes a bare errors.New here
read as an oversight. It is the same deliberate replacement the fmt.Errorf it
replaced did: the §7.3 guidance is meant to BE the message, not to trail the raw
"no release in namespace X". Wrapping would also make the result re-match
errors.As(*noParentReleaseError) and so re-explainable. Recorded in place so a
reviewer doesn't have to re-derive it.

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(doctor,home,client): finding the environment is only half the story

Both Bugbot findings on this PR were right, and both are the same mistake:
a two-valued answer where the honest answer has three values.

HIGH — "stale pointer still blocks after fallback". Re-probing found the
healthy environment and then said nothing about the pointer that missed. So
doctor printed "Everything looks good — you're ready to run training" and exited
0 while `data`/`resources`/`seal` all still bind the stale namespace and exit 4;
before this PR that state at least exited 3. doctor now names the stale pointer
and the repoint, and exits 2 — the code it already uses for every actionable
finding. A problem WAS found; it just isn't in the cluster.

The home half was worse, and was newly introduced here: local liveness came from
the fallback's client while the heartbeat is still looked up by the STALE
client's id, so a colleague's machine being online could render this one green.
envProbe carries pointerStale, and resolveHomeModel refuses both directions off
it — a stale heartbeat can no longer green the screen, nor harden into
"backend reports not online" for a client it isn't about. It drops to "running,
couldn't confirm", which is exactly true.

MEDIUM — "empty cluster ID marked absent". `client list` compared anchors as a
boolean, so a client whose OWN anchor is empty — legacy / not-yet-backfilled,
which api.ProvisionedClient documents — was reported as "NOT on the cluster your
kubeconfig reaches", with the repoint hint, possibly while running on this very
machine. Exactly the collapse this PR's cluster-anchor handling was careful to
avoid, missed one level down. Residency is now a three-valued residencyOf():
either anchor missing is resUnknown, and unknown claims nothing either way.

realProbeEnv moved to home_local_fallback.go: home.go went 13 lines over its
file budget, and the probe is now mostly a decision about WHICH fallback to
take, so it reads better beside them than beside the renderer.

Six mutations, each with its anchor asserted and each reddening an assertion
rather than the compiler: collapse the empty client anchor; let doctor green a
stale pointer; drop doctor's stale-pointer note; stop marking the fallback's
result stale; let a stale pointer render Online; let another client's not-online
harden into a verdict. TestDoctor_HealthyPointer_StillGreen is the control —
without it, "never says Everything looks good" would pass vacuously.

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(doctor): put the stale-pointer finding IN the readiness line

Rendering the previous commit showed the fix was half done: the closing verdict
was honest, but the line above it still read

    ✔ Connected to tracebloc
    ✔ Ready to run training
    ⚠ Your active client points at namespace "stale-ns" …

— a green tick and, directly beneath it, a warning saying the opposite. That is
the same unearned success the finding was about, moved up the screen.

`Ready to run training` is false whenever the pointer is stale, however green
the cluster checks are, because every data command binds the pointer. So the
readiness healthLine is replaced rather than accompanied, and it carries the
remedy, so the finding and the fix read as one thing:

    ✔ Connected to tracebloc
    ✖ Not ready — your active client points at namespace "stale-ns", which
      isn't on this cluster, so data commands will keep failing until you
      repoint.
         Point this machine at the environment above: tracebloc client create
         (this cluster already runs a client, so it adopts it — no new credential)

Phrased "Not ready — …" to match the three readiness failures already in the
catalog. `--diagnose` records the replaced line, which is what triage needs.
Exit stays 2 via the pointerStale branch, which skips the "email support" nudge
a doctorVerdict fail would add — we just gave a precise one-command fix.

Three more mutations: disable the replacement (green tick returns) → red;
drop the remedy → red; stop naming the stale namespace → red. The
already-added TestDoctor_HealthyPointer_StillGreen now also asserts the green
tick IS present when nothing is stale, so "no green tick" can't pass by the
line disappearing entirely.

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(client,home): don't name a target we haven't confirmed exists

Bugbot round 2, two Mediums, and the same class a third time: a sentence
asserting something the code never established.

`client list` set the mismatch hint from the ACTIVE row alone, so with the
pointer elsewhere and nothing confirmed on this cluster it still said "point
this machine at the client that IS there: … client create". There may be no
client there — and on a cluster with none, `client create` falls through to the
MINT path and produces the orphaned phantom backend#970 exists to prevent. So
this PR's own advice could manufacture the bug the command was hidden for.

The repoint is now offered only when some row is resHere — that is what earns
the phrase "the client that IS there". Otherwise the mismatch is still reported,
without a target: "no client here is confirmed. Check your kubeconfig context,
then run: … doctor". Deliberately covers BOTH remaining cases, because they are
equally unnameable — no client here at all, and clients that might be here but
carry no anchor to prove it (resUnknown).

The home screen had the label version of the same thing: with a stale pointer,
`env.name` was still overridden by the remembered handle, so the client the
pointer names was printed as the environment running here — a client that is by
construction NOT what the fallback found, and a name contradicting doctor's for
the identical state. The override is now skipped when the pointer is stale, so
the screen falls through to the probe's own name for the release that is
actually running.

Three mutations: let the repoint hint fire without anyHere → red; source anyHere
from the active row instead of residency → red; restore the unconditional
remembered-name override → red. Both fixes carry a control assertion in the same
test (the repoint IS offered when a row is here; the remembered name IS still
preferred when the pointer is fresh), so neither can pass by the behaviour
disappearing altogether. N10's first attempt left `anyHere` unused and reddened
the compiler; rewritten to keep it used and re-run.

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(doctor): adopt the re-probe only on a CONFIRMED reachable cluster

Bugbot round 3, High, and correct. The re-probe adopted on
`reachStateOf(retry) != doctor.ReachNoEnv`, and ReachState has four members:
ReachUnreachable and ReachError also satisfy that. Both mean "we could not
tell". So a stale pointer plus RBAC on the context namespace, or a transient
read failure, would have:

  • named an unconfirmed namespace as `Secure environment "…"`,
  • set pointerStale and printed "this cluster already runs a client, so it
    adopts it — no new credential",
  • and sent the user to `client create` on a cluster that may host nothing,
    where it does not adopt but MINTS — the backend#970 phantom.

Which is the exact absence-as-presence collapse surveyCluster's `looked` and
residencyOf's resUnknown exist to prevent, made twice more in the same PR.

Adoption now requires a positive confirmation, via reachConfirmedOK(). It is
deliberately NOT `reachStateOf(results) == ReachOK`: reachStateOf defaults to
ReachOK when the check is ABSENT, which is the right lenient default on the main
path and precisely the wrong one here, where the whole question is whether an
unproven namespace may be believed. Absent, unreachable and errored all answer
"could not tell", and none may authorize naming an environment or advising a
repoint.

The test derives its input domain from doctor.ReachState's declared surface —
every non-OK member, plus the absent case — rather than picking the states that
came to mind: mutation coverage cannot see a vocabulary gap, so a future member
has to be added to the enum's own list to escape it.

Three mutations: restore `!= ReachNoEnv` → three subtests red; make an absent
check count as confirmed → red; let ReachError confirm → red.

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(bugbot): make the recurring finding on this PR a rule

Org standard: "A finding that recurs across PRs becomes a rule: add it to
.cursor/BUGBOT.md". This one recurred three times inside a SINGLE PR — a failed
scan read as "nothing is here", an empty legacy cluster_id read as "runs
elsewhere", and `!= ReachNoEnv` read as "an environment is here" — each found by
Bugbot only after the previous was fixed. Three instances of one root cause is
past the threshold.

BUGBOT.md already had the neighbouring rule, but scoped to the value a function
RETURNS ("prefer a three-valued return"). Every instance here got the return
type right and then collapsed it at the `if` that consumed it, so the existing
bullet didn't catch any of them. The new bullet is about the branch, and names
the two concrete shapes rather than restating the principle:

  • a negated comparison against ONE member of a multi-valued enum, which
    silently absorbs every member added later — with the corollary that the
    test's input domain must come from the enum's declared surface, since
    mutation coverage cannot see a vocabulary gap;
  • a lenient "not found" default reused where the question is "may I believe
    this?" — reachStateOf returning ReachOK for an ABSENT check is right for a
    verdict roll-up and wrong for authorising a claim, which is why
    reachConfirmedOK exists beside it.

It closes with the customer-visible cost, per this file's own Tone section: each
instance ended in advice to run `client create` on a cluster nothing was
confirmed on, where it mints instead of adopting — the guidance manufacturing
the orphaned phantom backend#970 is about.

Refs cli#515

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .cursor/BUGBOT.md                             |  21 ++
 docs/cli-navigation.md                        |   4 +-
 internal/cli/client.go                        | 132 ++++++-
 internal/cli/client_test.go                   | 256 +++++++++++++-
 internal/cli/cluster.go                       |   5 +-
 internal/cli/clustertarget.go                 | 135 ++++++-
 internal/cli/clustertarget_test.go            | 175 ++++++++-
 internal/cli/data_delete.go                   |   2 +-
 internal/cli/data_ingest_cluster.go           |   2 +-
 internal/cli/data_list.go                     |   2 +-
 internal/cli/doctor.go                        |  80 ++++-
 internal/cli/doctor_pointer_test.go           | 331 ++++++++++++++++++
 internal/cli/home.go                          |  98 ++----
 internal/cli/home_local_fallback.go           | 140 +++++++-
 internal/cli/home_local_fallback_test.go      | 135 +++++++
 internal/cli/resources.go                     |   2 +-
 internal/cli/resources_set.go                 |   2 +-
 internal/cli/seal.go                          |   2 +-
 internal/cli/testdata/golden/08-client.golden |  11 +-
 .../cli/testdata/golden/zz-all-strings.golden |   9 +
 20 files changed, 1417 insertions(+), 127 deletions(-)
 create mode 100644 internal/cli/doctor_pointer_test.go

diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.md
index 6b3306c..9e6d70c 100644
--- a/.cursor/BUGBOT.md
+++ b/.cursor/BUGBOT.md
@@ -73,6 +73,27 @@ Two things make this repo unusual and should shape every finding:
   (`internal/api/client.go`, `nextPath`). Where "empty" and "unknown" are different answers,
   prefer a three-valued return (`internal/cluster/discover.go:302`).
 
+- **"Couldn't confirm" used as "confirmed" — in a BRANCH, not just a return type.** The rule
+  above is about the value a function hands back; this is about the `if` that consumes it, and
+  it is the defect this repo produces most often. cli#515 shipped it three times in one PR,
+  each in a different file, each after the previous one was fixed: a failed cluster scan
+  reported as "no client is running here"; an empty `cluster_id` on a legacy client read as
+  "runs elsewhere" (`ProvisionedClient.ClusterID` is documented empty on not-yet-backfilled
+  records); and `reachStateOf(x) != ReachNoEnv` used to mean "an environment is here", when
+  `ReachState` also has `ReachUnreachable` and `ReachError`. Two concrete shapes to flag:
+  - **A negated comparison against ONE member of a multi-valued enum.** `!= ReachNoEnv`,
+    `!= StatusFail` and friends silently include every member added later. Compare against the
+    member you actually require (`== ReachOK`), and derive the test's input domain from the
+    enum's declared surface — mutation coverage cannot see a vocabulary gap.
+  - **A lenient "not found" default reused where the question is "may I believe this?"**
+    `reachStateOf` returns `ReachOK` for an ABSENT check, which is right for a verdict roll-up
+    and wrong for authorising a claim — hence the separate `reachConfirmedOK`
+    (`internal/cli/doctor.go`). The same default is rarely correct for both.
+
+  The customer-visible cost is never a wrong log line: on #515 each instance ended in advice to
+  run `client create` on a cluster nothing was confirmed on, where it MINTS rather than adopts —
+  i.e. the guidance manufactured the orphaned phantom of `backend#970`.
+
 - **A cross-repo contract change that only lands on one side.** `scripts/.data-ingestors-ref`,
   `scripts/.client-ref` and `scripts/.backend-ref` pin upstream refs deliberately so an
   unrelated upstream commit can't red every open PR. Flag a hand-edit to a generated artifact
diff --git a/docs/cli-navigation.md b/docs/cli-navigation.md
index f8ce400..cba1423 100644
--- a/docs/cli-navigation.md
+++ b/docs/cli-navigation.md
@@ -22,7 +22,7 @@ flowchart TD
   ACCT --> logout["logout"]
   ACCT --> authst["auth status"]
   ACCT --> clis["client status"]
-  ACCT -.-> clcreate["client create"]:::hidden
+  ACCT --> clcreate["client create — point this machine at its client"]
   ACCT -.-> cllist["client list"]:::hidden
 
   ENVC --> di["data ingest"]
@@ -172,7 +172,7 @@ flowchart TD
 - **not signed in / token 401·403** → `login`
 - **426 upgrade-required** → upgrade the CLI
 - **kubeconfig (exit 3)** → fix `--kubeconfig`/`--context`, then `doctor`
-- **no client / environment (exit 4)** → run the installer (or `--namespace`); triage with `doctor`
+- **no client / environment (exit 4)** → the error now says what IS on the reached cluster before advising (cli#515): one client on a local cluster → `client create` repoints this machine (it adopts, no new credential); a client on a remote/shared cluster → `--namespace <ns>` only; nothing there → run the installer. Triage with `doctor`
 - **no token (exit 5)** → grant RBAC; diagnose with `cluster info` / `doctor`
 - **destination exists (exit 6)** → `--overwrite`, a different `--name`, or `data delete` first
 - **staging partial (exit 7)** → `data delete` then re-ingest
diff --git a/internal/cli/client.go b/internal/cli/client.go
index cd662a4..d7246ee 100644
--- a/internal/cli/client.go
+++ b/internal/cli/client.go
@@ -39,8 +39,9 @@ var readInClusterClient = cluster.DiscoverInClusterClient
 // The single-machine CLI (RFC-0001 §7.10) owns exactly one client, so there is
 // nothing to *select*: `client use` is withdrawn, and `client list` is hidden
 // (kept callable for the installer's one-client-per-machine pre-flight, off the
-// user-facing surface). `create` provisions this machine's client; offboarding
-// is the top-level `tracebloc delete`.
+// user-facing surface). `create` points this machine at its client — adopting
+// the one already on the cluster, which is the supported repoint (#515) —
+// and offboarding is the top-level `tracebloc delete`.
 func newClientCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "client",
@@ -63,15 +64,31 @@ func newClientCreateCmd() *cobra.Command {
 	var yes bool
 	cmd := &cobra.Command{
 		Use:   "create",
-		Short: "Provision a tracebloc client for this machine (auto-named; no flags required)",
-		// HIDDEN: provisioning is the installer's job — provision.sh calls this with
-		// zero flags (cli#137). It stays fully callable (including `--help`, so the
-		// installer's capability probe still works), but is kept off the user-facing
-		// surface: a human running `client create` STANDALONE mints a client the
-		// installer never deploys — an orphaned "phantom" (backend#970). Mirrors the
-		// hidden `list`; leaves `tracebloc client` showing only the user-useful `status`.
-		Hidden: true,
-		Args:   cobra.NoArgs,
+		Short: "Point this machine at its tracebloc client — adopts the one already on this cluster",
+		Long: `Point this machine at its tracebloc client.
+
+Keyed on the cluster your kubeconfig reaches: if a tracebloc client already runs
+there, this ADOPTS it — no prompt, no new credential, no duplicate — which is how
+you repoint a machine whose active client went stale. On a cluster that runs no
+client yet it provisions a new one, and asks first.
+
+Provisioning a brand-new machine is normally the installer's job — it calls this
+for you, with no flags.`,
+		// WAS HIDDEN (backend#970), and the reason still stands: a human running
+		// this STANDALONE on a cluster with no client mints one the installer never
+		// deploys — an orphaned "phantom". Hiding it was never what prevented that,
+		// though; the mint-path guards below are, and they are untouched:
+		//   • on a TTY, the review + `Provision this client?` confirm (which a
+		//     re-run on an already-registered cluster never reaches — it adopts
+		//     before the prompt, so the repoint stays zero-friction);
+		//   • off a TTY, a hard refusal without --yes/--credential-file, so a pipe
+		//     or CI can never mint silently.
+		// What hiding DID cost is #515: the §7.3 "your active client runs on another
+		// machine" error had no supported way back, because the one command that
+		// repoints a machine was unlisted. Advice pointing at a hidden command is
+		// not advice, so it is listed now — described by what it does for a user
+		// (adopt/repoint) rather than by the installer's use of it.
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return runClientCreate(cmd.Context(), printerFor(cmd), clientPrompter(),
 				clientCreateOpts{name: name, location: location, kubeconfigPath: kubeconfigPath, contextOverride: contextOverride, credentialFile: credentialFile, yes: yes})
@@ -747,21 +764,106 @@ func runClientList(ctx context.Context, p *ui.Printer) error {
 	}
 	p.Section("Clients in your account")
 	active := cfg.Current().ActiveClientID
+	// #515: "active" is a LOCAL POINTER, and this listing used to render it as
+	// "(active — this machine)" — a claim about location it never checked. When
+	// the pointer is stale that label sits next to a client provably not on the
+	// cluster this machine reaches, which is the state the whole ticket is about.
+	// Read the cluster anchor (kube-system UID, the §7.2 identity `client create`
+	// keys on) and mark residency separately from selection. A failed read is
+	// three-valued on purpose: unknown is not "elsewhere", so the marker then
+	// claims nothing about where anything runs.
+	clusterID, cidErr := readClusterID(ctx, cluster.KubeconfigOptions{})
+	hereKnown := cidErr == nil && clusterID != ""
+	activeElsewhere, anyHere := false, false
 	for _, c := range clients {
-		marker := ""
-		if strconv.Itoa(c.ID) == active {
-			marker = "  (active — this machine)"
+		isActive := strconv.Itoa(c.ID) == active
+		res := residencyOf(hereKnown, clusterID, c.ClusterID)
+		if isActive && res == resElsewhere {
+			activeElsewhere = true
 		}
-		p.Field(strconv.Itoa(c.ID)+marker,
+		if res == resHere {
+			anyHere = true
+		}
+		p.Field(strconv.Itoa(c.ID)+clientListMarker(isActive, res),
 			fmt.Sprintf("%s   state=%s   namespace=%s   location=%s",
 				c.Name, clientStateLabel(c.Status), c.Namespace, c.Location))
 	}
 	// §7.3: separate "selected" (this machine's local pointer) from "connected"
 	// (the backend's last-heartbeat state) so a stale pointer is visible.
 	p.Hintf("\"active\" is this machine's selected client; state is its last reported status to tracebloc.")
+	switch {
+	case activeElsewhere && anyHere:
+		// The exact state #515 describes, and the one supported way out of it:
+		// re-running create on a cluster that already hosts a client adopts it —
+		// no prompt, no new credential (§7.2). anyHere is what earns the phrase
+		// "the client that IS there": without a row we KNOW is on this cluster,
+		// `client create` would fall through to the mint path and produce the
+		// phantom backend#970 is about (Bugbot).
+		p.Hintf("Your active client is not on the cluster your kubeconfig reaches. To point this machine at the client that IS there: %s client create", launcher())
+	case activeElsewhere:
+		// The pointer is provably wrong, but no listed client is provably here —
+		// either none is, or the ones that might be carry no anchor to prove it
+		// (resUnknown). Both are "we can't name a target", so name none: send
+		// them to the command whose whole job is to say what's on this cluster
+		// rather than advertise a repoint that may have nothing to adopt.
+		p.Hintf("Your active client is not on the cluster your kubeconfig reaches, and no client here is confirmed. Check your kubeconfig context, then run: %s doctor", launcher())
+	}
 	return nil
 }
 
+// residency answers "does this client run on the cluster the kubeconfig
+// reaches" in THREE values, because two of them are absences and an absence is
+// never a "no" (Bugbot, #515).
+type residency int
+
+const (
+	// resUnknown: we cannot tell. Either the local cluster anchor was
+	// unreadable (no kubeconfig, unreachable API server, RBAC on kube-system),
+	// or the CLIENT carries no anchor — `ProvisionedClient.ClusterID` is empty
+	// on legacy / not-yet-backfilled records (api/client.go), and a record that
+	// never learned where it lives is not a record that lives elsewhere.
+	resUnknown residency = iota
+	resHere
+	resElsewhere
+)
+
+// residencyOf compares the local cluster anchor with a client's, keeping both
+// missing-anchor cases at resUnknown. Collapsing either into "elsewhere" would
+// print "NOT on the cluster your kubeconfig reaches" — and the repoint hint —
+// next to a legacy client that may be running on this very machine.
+func residencyOf(hereKnown bool, localAnchor, clientAnchor string) residency {
+	if !hereKnown || clientAnchor == "" {
+		return resUnknown
+	}
+	if clientAnchor == localAnchor {
+		return resHere
+	}
+	return resElsewhere
+}
+
+// clientListMarker renders one row's suffix in `client list`, keeping SELECTION
+// (this machine's local pointer) and RESIDENCY (where the client actually runs)
+// as two separate facts (#515). Under resUnknown the marker degrades to bare
+// "(active)" — which says only what the local config actually knows — and
+// claims nothing about location in either direction.
+func clientListMarker(isActive bool, res residency) string {
+	switch {
+	case res == resUnknown:
+		if isActive {
+			return "  (active)"
+		}
+		return ""
+	case isActive && res == resHere:
+		return "  (active — on this cluster)"
+	case isActive:
+		return "  (active — NOT on the cluster your kubeconfig reaches)"
+	case res == resHere:
+		return "  (on this cluster)"
+	default:
+		return ""
+	}
+}
+
 // setActiveClient points this env's profile at c, caching its namespace and
 // display name alongside the id so the data commands can bind to the active
 // client's cluster (§7.3) without a backend round-trip. Callers Save() after.
diff --git a/internal/cli/client_test.go b/internal/cli/client_test.go
index fab9bd4..d771124 100644
--- a/internal/cli/client_test.go
+++ b/internal/cli/client_test.go
@@ -1470,19 +1470,18 @@ func TestClientStatus_WaitCtrlCIsSilent(t *testing.T) {
 }
 
 func TestClientSubcommandVisibility(t *testing.T) {
-	// `create` and `list` are installer-internal — Hidden so a user isn't invited to
-	// run them (a standalone `tracebloc client create` mints a client the installer
-	// never deploys, i.e. an orphaned phantom, backend#970). `status` stays
-	// user-visible. Hidden != disabled: all remain runnable (the installer still
-	// invokes create/list).
+	// `create` is VISIBLE since #515: it is the supported way to repoint a machine
+	// whose active client went stale, and the §7.3 error now names it — advice
+	// pointing at a hidden command is not advice. `list` stays installer-internal.
+	// `status` stays user-visible. Hidden != disabled: all remain runnable.
 	hidden := map[string]bool{}
 	runnable := map[string]bool{}
 	for _, c := range newClientCmd().Commands() {
 		hidden[c.Name()] = c.Hidden
 		runnable[c.Name()] = c.RunE != nil
 	}
-	if !hidden["create"] {
-		t.Error("client create must be Hidden (installer-internal; standalone mints a phantom)")
+	if hidden["create"] {
+		t.Error("client create must be visible — the #515 repoint advice names it")
 	}
 	if !hidden["list"] {
 		t.Error("client list must stay Hidden")
@@ -1491,7 +1490,248 @@ func TestClientSubcommandVisibility(t *testing.T) {
 		t.Error("client status must stay user-visible")
 	}
 	if !runnable["create"] {
-		t.Error("hidden create must still be runnable (the installer invokes it)")
+		t.Error("create must still be runnable (the installer invokes it)")
+	}
+}
+
+// Unhiding `create` must not reopen backend#970: hiding it was never what
+// stopped a standalone run from minting a phantom — these two guards are, and
+// they have to survive the visibility change. Off a TTY (pr == nil) with no
+// --yes and no --credential-file, a fresh mint is REFUSED; nothing is posted.
+func TestClientCreate_UnhiddenStillRefusesSilentMint(t *testing.T) {
+	posted := false
+	withClientBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodPost {
+			posted = true
+		}
+		_, _ = w.Write([]byte(`[]`)) // no clients on the account → a mint, not an adopt
+	})
+	signInAs(t, "Lab", "lab@example.com")
+	var out bytes.Buffer
+	err := runClientCreate(context.Background(), ui.New(&out), nil, clientCreateOpts{})
+	if err == nil {
+		t.Fatal("a non-interactive bare `client create` must refuse to mint")
+	}
+	if !strings.Contains(err.Error(), "refusing to provision non-interactively") {
+		t.Errorf("want the pipe refusal, got: %v", err)
+	}
+	if posted {
+		t.Error("nothing may be provisioned by a refused run")
+	}
+}
+
+// The TTY half of the same guard: on a terminal a fresh mint asks first, and a
+// "no" provisions nothing. (The repoint itself never reaches this prompt — an
+// already-registered cluster adopts before it, covered by the adopt tests.)
+func TestClientCreate_UnhiddenStillPromptsBeforeMinting(t *testing.T) {
+	posted := false
+	withClientBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodPost {
+			posted = true
+		}
+		_, _ = w.Write([]byte(`[]`))
+	})
+	signInAs(t, "Lab", "lab@example.com")
+	no := false
+	var out bytes.Buffer
+	if err := runClientCreate(context.Background(), ui.New(&out), &fakePrompter{confirm: &no}, clientCreateOpts{}); err != nil {
+		t.Fatalf("declining is a clean exit, got: %v", err)
+	}
+	if posted {
+		t.Error("a declined confirm must provision nothing")
+	}
+}
+
+// #515: `client list` used to label the active pointer "(active — this machine)"
+// without ever checking where that client runs, so a stale pointer read as
+// confirmation. Selection and residency are now two separate facts, keyed on the
+// cluster anchor (§7.2).
+func TestClientListMarker(t *testing.T) {
+	cases := []struct {
+		name     string
+		isActive bool
+		res      residency
+		want     string
+	}{
+		{"residency unknown, active → claims only selection", true, resUnknown, "  (active)"},
+		{"residency unknown, other → no claim", false, resUnknown, ""},
+		{"active and here", true, resHere, "  (active — on this cluster)"},
+		{"active but elsewhere", true, resElsewhere, "  (active — NOT on the cluster your kubeconfig reaches)"},
+		{"here but not selected", false, resHere, "  (on this cluster)"},
+		{"elsewhere and not selected", false, resElsewhere, ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := clientListMarker(c.isActive, c.res); got != c.want {
+				t.Errorf("clientListMarker(%v,%v) = %q, want %q", c.isActive, c.res, got, c.want)
+			}
+		})
+	}
+	// The specific claim #515 calls out: unknown residency must never let a row
+	// assert — or deny — that it is here.
+	for _, isActive := range []bool{true, false} {
+		if strings.Contains(clientListMarker(isActive, resUnknown), "this cluster") {
+			t.Errorf("isActive=%v: unknown residency must claim nothing about location", isActive)
+		}
+	}
+}
+
+// Bugbot (#515): residency has to stay THREE-valued on both sides of the
+// comparison. An unreadable LOCAL anchor was already handled; a client whose OWN
+// anchor is empty — legacy / not-yet-backfilled, per api.ProvisionedClient —
+// was being forced to "elsewhere", which told the owner of a perfectly local
+// legacy client that it is not on this cluster.
+func TestResidencyOf(t *testing.T) {
+	cases := []struct {
+		name        string
+		hereKnown   bool
+		local, clnt string
+		want        residency
+	}{
+		{"local anchor unreadable", false, "", "uid-A", resUnknown},
+		{"client anchor empty (legacy record)", true, "uid-A", "", resUnknown},
+		{"both unknown", false, "", "", resUnknown},
+		{"anchors match", true, "uid-A", "uid-A", resHere},
+		{"anchors differ", true, "uid-A", "uid-B", resElsewhere},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := residencyOf(c.hereKnown, c.local, c.clnt); got != c.want {
+				t.Errorf("residencyOf(%v,%q,%q) = %v, want %v", c.hereKnown, c.local, c.clnt, got, c.want)
+			}
+		})
+	}
+}
+
+// End to end: a legacy ACTIVE client with no anchor, on a machine whose cluster
+// anchor reads fine, must not be accused of running elsewhere — and must not
+// trigger the repoint hint, which would be advice to fix a non-problem.
+func TestClientList_LegacyClientWithNoAnchorIsNotAccused(t *testing.T) {
+	withClientBackend(t, func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`[{"id":1,"first_name":"legacy","namespace":"legacy-ns"}]`)) // no cluster_id
+	})
+	stubClusterID(t, "uid-HERE", nil)
+	cfg, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg.Current().ActiveClientID = "1"
+	if err := cfg.Save(); err != nil {
+		t.Fatal(err)
+	}
+
+	var out bytes.Buffer
+	if err := runClientList(context.Background(), ui.New(&out, ui.WithColor(false))); err != nil {
+		t.Fatal(err)
+	}
+	got := out.String()
+	if strings.Contains(got, "NOT on the cluster") {
+		t.Errorf("a client with no anchor has UNKNOWN residency, not elsewhere:\n%s", got)
+	}
+	if strings.Contains(got, "client create") {
+		t.Errorf("no mismatch is known, so the repoint must not be advised:\n%s", got)
+	}
+	if !strings.Contains(got, "1  (active)") {
+		t.Errorf("want the bare selection marker:\n%s", got)
+	}
+}
+
+// End-to-end: with the anchor readable, the row that matches the LOCAL cluster
+// is marked as such — even when the pointer names a different one — and the
+// listing names the repoint.
+func TestClientList_MarksTheClientOnThisCluster(t *testing.T) {
+	withClientBackend(t, func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`[{"id":1,"first_name":"stale","namespace":"stale-ns","cluster_id":"uid-OTHER"},` +
+			`{"id":2,"first_name":"here","namespace":"lukas-02","cluster_id":"uid-HERE"}]`))
+	})
+	stubClusterID(t, "uid-HERE", nil)
+	cfg, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg.Current().ActiveClientID = "1" // the pointer names the client that is NOT here
+	if err := cfg.Save(); err != nil {
+		t.Fatal(err)
+	}
+
+	var out bytes.Buffer
+	if err := runClientList(context.Background(), ui.New(&out, ui.WithColor(false))); err != nil {
+		t.Fatal(err)
+	}
+	got := out.String()
+	if !strings.Contains(got, "1  (active — NOT on the cluster your kubeconfig reaches)") {
+		t.Errorf("the stale active pointer must be marked as not here:\n%s", got)
+	}
+	if !strings.Contains(got, "2  (on this cluster)") {
+		t.Errorf("the client that IS here must be marked:\n%s", got)
+	}
+	if !strings.Contains(got, "client create") {
+		t.Errorf("a mismatch must name the repoint:\n%s", got)
+	}
+}
+
+// Bugbot (#515): the repoint hint says "the client that IS there", which is only
+// true if some row is provably here. With the active client elsewhere and NOTHING
+// confirmed on this cluster, `client create` would fall through to the MINT path
+// and produce exactly the phantom backend#970 exists to prevent — so the advice
+// must not be given.
+func TestClientList_MismatchWithNoLocalClient_DoesNotPushCreate(t *testing.T) {
+	withClientBackend(t, func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`[{"id":1,"first_name":"stale","namespace":"stale-ns","cluster_id":"uid-OTHER"},` +
+			`{"id":2,"first_name":"third","namespace":"third-ns","cluster_id":"uid-THIRD"}]`))
+	})
+	stubClusterID(t, "uid-HERE", nil) // this cluster hosts NEITHER
+	cfg, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg.Current().ActiveClientID = "1"
+	if err := cfg.Save(); err != nil {
+		t.Fatal(err)
+	}
+
+	var out bytes.Buffer
+	if err := runClientList(context.Background(), ui.New(&out, ui.WithColor(false))); err != nil {
+		t.Fatal(err)
+	}
+	got := out.String()
+	if strings.Contains(got, "client create") {
+		t.Errorf("no client is confirmed here — advising the repoint would push a MINT:\n%s", got)
+	}
+	if !strings.Contains(got, "no client here is confirmed") {
+		t.Errorf("the mismatch is still real and must be reported, just without a target:\n%s", got)
+	}
+	// The mismatch itself must still be visible on the row.
+	if !strings.Contains(got, "NOT on the cluster your kubeconfig reaches") {
+		t.Errorf("the stale active pointer must still be marked:\n%s", got)
+	}
+}
+
+// The unreadable-anchor path end to end: no cluster reachable ⇒ no row claims a
+// location, and the mismatch hint stays silent (we cannot know there is one).
+func TestClientList_UnreadableAnchorClaimsNoLocation(t *testing.T) {
+	withClientBackend(t, func(w http.ResponseWriter, _ *http.Request) { // stubs readClusterID to an error
+		_, _ = w.Write([]byte(`[{"id":1,"first_name":"stale","namespace":"stale-ns","cluster_id":"uid-OTHER"}]`))
+	})
+	cfg, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg.Current().ActiveClientID = "1"
+	if err := cfg.Save(); err != nil {
+		t.Fatal(err)
+	}
+
+	var out bytes.Buffer
+	if err := runClientList(context.Background(), ui.New(&out, ui.WithColor(false))); err != nil {
+		t.Fatal(err)
+	}
+	got := out.String()
+	if !strings.Contains(got, "1  (active)") {
+		t.Errorf("want the bare selection marker when the anchor is unreadable:\n%s", got)
+	}
+	if strings.Contains(got, "this cluster") || strings.Contains(got, "kubeconfig reaches") {
+		t.Errorf("an unreadable anchor must claim nothing about location:\n%s", got)
 	}
 }
 
diff --git a/internal/cli/cluster.go b/internal/cli/cluster.go
index 6d331a9..b75b8e2 100644
--- a/internal/cli/cluster.go
+++ b/internal/cli/cluster.go
@@ -164,7 +164,10 @@ func runClusterInfo(
 		// installed on this cluster". A binding miss gets the §7.3
 		// "runs elsewhere" explanation, same as the data commands.
 		if errors.Is(err, cluster.ErrNoParentRelease) {
-			return binding.explain(&exitError{code: exitNoWorkspace, err: &noParentReleaseError{err}})
+			return binding.explain(ctx, &exitError{code: exitNoWorkspace, err: &noParentReleaseError{
+				err:   err,
+				probe: &clusterProbe{cs: cs, serverURL: resolved.ServerURL},
+			}})
 		}
 		return &exitError{code: exitNoWorkspace, err: err}
 	}
diff --git a/internal/cli/clustertarget.go b/internal/cli/clustertarget.go
index b760867..1ebcb68 100644
--- a/internal/cli/clustertarget.go
+++ b/internal/cli/clustertarget.go
@@ -5,11 +5,13 @@ import (
 	"errors"
 	"fmt"
 	"strings"
+	"time"
 
 	"k8s.io/client-go/kubernetes"
 
 	"github.com/tracebloc/cli/internal/cluster"
 	"github.com/tracebloc/cli/internal/config"
+	"github.com/tracebloc/cli/internal/installer"
 	"github.com/tracebloc/cli/internal/ui"
 )
 
@@ -19,11 +21,36 @@ import (
 // release, an API/RBAC list failure, or an ambiguous multiple-release match.
 // §7.3 uses it to turn an active-client binding miss into a clear "runs on
 // another machine" message; the other failures keep their own diagnostics.
-type noParentReleaseError struct{ err error }
+//
+// probe carries the read-only handles explain needs to say what IS on the
+// reached cluster before advising (#515). It is attached wherever the error is
+// built — both sites already hold a clientset and the resolved server URL — and
+// travels ON the error rather than through the call signature so a caller can
+// never hand explain a clientset for a DIFFERENT cluster than the one that
+// missed. A nil probe (a synthesised error, a resolveClusterTargetFn test
+// double) means "we could not look", and explain then claims nothing.
+type noParentReleaseError struct {
+	err   error
+	probe *clusterProbe
+}
 
 func (e *noParentReleaseError) Error() string { return e.err.Error() }
 func (e *noParentReleaseError) Unwrap() error { return e.err }
 
+// clusterProbe is the pair explain needs to diagnose before advising: a
+// clientset for the cluster the kubeconfig actually reached, and that cluster's
+// server URL (which isLocalServerURL judges).
+type clusterProbe struct {
+	cs        kubernetes.Interface
+	serverURL string
+}
+
+// explainScanTimeout bounds the naming-only cluster scan explain runs on the
+// §7.3 error path. The scan only makes the message better, so it must never
+// make the failure slower than the failure itself: past this, explain falls
+// back to the message it would have printed without looking.
+const explainScanTimeout = 5 * time.Second
+
 // loadClusterFn / newClientsetFn are the kubeconfig-load + clientset-build
 // seams every command that reaches a cluster goes through — resolveClusterTarget
 // (data ingest/list/delete), runClusterInfo, and runClusterDoctor. Production
@@ -87,7 +114,10 @@ func resolveClusterTarget(ctx context.Context, p *ui.Printer, opts cluster.Kubec
 		// "runs elsewhere" rewrite; an API/RBAC list failure or an
 		// ambiguous multiple-release match keeps its own message.
 		if errors.Is(err, cluster.ErrNoParentRelease) {
-			return nil, &exitError{code: exitNoWorkspace, err: &noParentReleaseError{err}}
+			return nil, &exitError{code: exitNoWorkspace, err: &noParentReleaseError{
+				err:   err,
+				probe: &clusterProbe{cs: cs, serverURL: resolved.ServerURL},
+			}}
 		}
 		return nil, &exitError{code: exitNoWorkspace, err: err}
 	}
@@ -214,7 +244,18 @@ func (b activeClientBinding) allowScan() bool { return !b.applied && !b.explicit
 // came from the active-client binding: the cluster the kubeconfig reaches
 // doesn't host that client. Non-binding errors (and PVC-missing, where the
 // release *was* found) pass through unchanged.
-func (b activeClientBinding) explain(err error) error {
+//
+// DIAGNOSE BEFORE ADVISING (#515). The shipped §7.3 sentence named no way back:
+// it offered --namespace without ever saying WHICH namespace, so a user on a
+// healthy local install had no supported recovery. explain now spends one
+// naming-only cluster scan — the same read discoverRelease already spends
+// purely to write a better message — and says what is actually here.
+//
+// This changes what the CLI SAYS, never what it TARGETS: allowScan() stays
+// false, so a binding miss still never silently retargets to some other
+// machine's client (§7.5). The scan's result reaches the user as text they must
+// act on, which is the whole difference.
+func (b activeClientBinding) explain(ctx context.Context, err error) error {
 	if !b.applied {
 		return err
 	}
@@ -226,8 +267,88 @@ func (b activeClientBinding) explain(err error) error {
 	if handle == "" {
 		handle = b.namespace
 	}
-	return &exitError{code: exitNoWorkspace, err: fmt.Errorf(
-		"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at; "+
-			"run this command there, or override with --namespace/--context",
-		handle, b.namespace)}
+	// errors.New, not %w: the rewrite deliberately REPLACES the discovery error
+	// rather than wrapping it, so the §7.3 guidance is the whole message and the
+	// raw "no release in namespace X" doesn't trail it. That was already true of
+	// the fmt.Errorf this replaced — the exit code (exitNoWorkspace, on the
+	// *exitError above) is the machine-readable contract here, not the chain.
+	// Wrapping would also make the result re-match errors.As(*noParentReleaseError)
+	// and so re-explainable, which nothing wants.
+	return &exitError{code: exitNoWorkspace,
+		err: errors.New(repointMessage(handle, b.namespace, surveyCluster(ctx, npr.probe)))}
+}
+
+// clientSurvey is what explain managed to learn about the reached cluster
+// before advising.
+//
+// looked distinguishes "we scanned and the cluster hosts none" from "we could
+// not scan at all" (no probe on the error, or the cluster-wide list failed —
+// RBAC, a timeout, an unreachable API server). Collapsing the two would let an
+// absence of evidence print as evidence of absence: the CLI would tell a user
+// with a perfectly healthy client that nothing is running here. When looked is
+// false the message says nothing about the cluster's contents at all.
+type clientSurvey struct {
+	looked     bool
+	namespaces []string
+	local      bool // the kubeconfig's server is THIS machine (isLocalServerURL)
+}
+
+// surveyCluster runs cluster.FindClientNamespaces FOR NAMING ONLY — nothing in
+// this path changes the namespace anything targets. A nil probe (synthesised
+// error / test double) or a failed scan both return a survey that looked at
+// nothing, so explain falls back to the message it printed before #515.
+func surveyCluster(ctx context.Context, probe *clusterProbe) clientSurvey {
+	if probe == nil || probe.cs == nil {
+		return clientSurvey{}
+	}
+	ctx, cancel := context.WithTimeout(ctx, explainScanTimeout)
+	defer cancel()
+	found, err := cluster.FindClientNamespaces(ctx, probe.cs)
+	if err != nil {
+		return clientSurvey{}
+	}
+	return clientSurvey{looked: true, namespaces: found, local: isLocalServerURL(probe.serverURL)}
+}
+
+// repointMessage is the §7.3 error text, branched on what surveyCluster found.
+// Pure (no I/O) so every branch is unit-testable as text.
+//
+//   - exactly one client on a LOCAL cluster — a cluster that IS this machine —
+//     name it and offer the repoint. `client create` re-run on a cluster that
+//     already hosts a client adopts it: no prompt, no new credential (§7.2).
+//   - any client on a remote/shared cluster (or several anywhere) — name the
+//     namespaces and offer ONLY --namespace. Never `client create` here: that
+//     is the §7.5 boundary, and on a shared cluster the client we found may well
+//     be a colleague's.
+//   - none, scan clean — say so, and point at the installer, which is then the
+//     correct advice rather than a guess.
+//   - could not look — the pre-#515 sentence, unchanged. We make no claim.
+//
+// Each branch is ONE format literal rather than a concatenation, so the whole
+// sentence lands in the copy catalog (zz-all-strings harvests literal arguments;
+// a `+`-joined message is only ever half-visible there) and can be reviewed as
+// the user reads it.
+func repointMessage(handle, boundNS string, s clientSurvey) string {
+	switch {
+	case !s.looked:
+		return fmt.Sprintf(
+			"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at; run this command there, or override with --namespace/--context",
+			handle, boundNS)
+	case len(s.namespaces) == 0:
+		return fmt.Sprintf(
+			"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at; run this command there, or override with --namespace/--context.\n\nNo tracebloc client is running on this cluster either — if this machine should have one, set one up: %s",
+			handle, boundNS, installer.Cmd)
+	case len(s.namespaces) == 1 && s.local:
+		return fmt.Sprintf(
+			"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at.\n\nA tracebloc client IS running on this machine, in namespace %q.\n  Point this machine at it:  %s client create\n      (this cluster already runs a client, so it adopts it — no new credential)\n  Or target it just this once:  --namespace %s",
+			handle, boundNS, s.namespaces[0], launcher(), s.namespaces[0])
+	case len(s.namespaces) == 1:
+		return fmt.Sprintf(
+			"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at.\n\nA tracebloc client is running on this cluster, in namespace %q.\n  Target it just this once:  --namespace %s",
+			handle, boundNS, s.namespaces[0], s.namespaces[0])
+	default:
+		return fmt.Sprintf(
+			"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at.\n\ntracebloc clients are running on this cluster, in namespaces: %s.\n  Target one just this once:  --namespace %s",
+			handle, boundNS, strings.Join(s.namespaces, ", "), s.namespaces[0])
+	}
 }
diff --git a/internal/cli/clustertarget_test.go b/internal/cli/clustertarget_test.go
index e9e394d..1772496 100644
--- a/internal/cli/clustertarget_test.go
+++ b/internal/cli/clustertarget_test.go
@@ -18,6 +18,7 @@ import (
 	"github.com/tracebloc/cli/internal/api"
 	"github.com/tracebloc/cli/internal/cluster"
 	"github.com/tracebloc/cli/internal/config"
+	"github.com/tracebloc/cli/internal/installer"
 	"github.com/tracebloc/cli/internal/ui"
 )
 
@@ -162,12 +163,13 @@ func TestBindActiveClientNamespace_NoActiveClient(t *testing.T) {
 }
 
 func TestActiveClientBinding_Explain(t *testing.T) {
-	noRelease := &exitError{code: 4, err: &noParentReleaseError{errors.New("no release")}}
+	noRelease := &exitError{code: 4, err: &noParentReleaseError{err: errors.New("no release")}}
 	pvcMissing := &exitError{code: 4, err: errors.New("shared PVC not bound")}
+	ctx := context.Background()
 
 	// Applied + "no release here" → rewritten to the §7.3 guidance.
 	bound := activeClientBinding{applied: true, name: "gpu-box-01", namespace: "gpu-box-01"}
-	got := bound.explain(noRelease)
+	got := bound.explain(ctx, noRelease)
 	if got == noRelease {
 		t.Fatal("expected a rewritten error")
 	}
@@ -180,16 +182,181 @@ func TestActiveClientBinding_Explain(t *testing.T) {
 	}
 
 	// Applied but a PVC failure (release WAS found) → pass through untouched.
-	if bound.explain(pvcMissing) != pvcMissing {
+	if bound.explain(ctx, pvcMissing) != pvcMissing {
 		t.Error("PVC-missing error should not be rewritten")
 	}
 
 	// Not applied → always pass through.
-	if (activeClientBinding{}).explain(noRelease) != noRelease {
+	if (activeClientBinding{}).explain(ctx, noRelease) != noRelease {
 		t.Error("unbound explain should pass the error through")
 	}
 }
 
+// #515 — the three branches of the §7.3 message, as text. A binding miss used to
+// name --namespace without ever saying WHICH namespace; each branch below is the
+// answer explain now derives from what is actually on the reached cluster.
+//
+// repointMessage is pure, so this pins the exact wording; the surveyCluster
+// tests below pin that the survey fed to it is honest.
+func TestRepointMessage_Branches(t *testing.T) {
+	const handle, boundNS = "gpu-box-01", "gpu-box-01"
+	lead := `active client "gpu-box-01" runs on another machine — namespace "gpu-box-01" isn't on the cluster your kubeconfig points at`
+
+	t.Run("one client on a local cluster offers the repoint", func(t *testing.T) {
+		got := repointMessage(handle, boundNS, clientSurvey{looked: true, namespaces: []string{"lukas-02"}, local: true})
+		for _, want := range []string{
+			lead,
+			`A tracebloc client IS running on this machine, in namespace "lukas-02".`,
+			"client create",
+			"no new credential",
+			"--namespace lukas-02",
+		} {
+			if !strings.Contains(got, want) {
+				t.Errorf("missing %q:\n%s", want, got)
+			}
+		}
+	})
+
+	t.Run("remote cluster never suggests client create", func(t *testing.T) {
+		got := repointMessage(handle, boundNS, clientSurvey{looked: true, namespaces: []string{"colleague-07"}, local: false})
+		if !strings.Contains(got, "colleague-07") || !strings.Contains(got, "--namespace colleague-07") {
+			t.Errorf("remote branch must name the namespace and offer --namespace:\n%s", got)
+		}
+		// The §7.5 boundary: on a shared cluster the client we found may be
+		// someone else's, so the repoint must NOT be advertised.
+		if strings.Contains(got, "client create") {
+			t.Errorf("remote/shared cluster must never suggest `client create`:\n%s", got)
+		}
+	})
+
+	t.Run("several clients name them all and offer only --namespace", func(t *testing.T) {
+		// Local or not: with more than one client here, "point this machine at
+		// it" has no unambiguous "it" — so this stays the --namespace branch even
+		// on a local cluster.
+		for _, local := range []bool{true, false} {
+			got := repointMessage(handle, boundNS, clientSurvey{looked: true, namespaces: []string{"alpha", "beta"}, local: local})
+			if !strings.Contains(got, "alpha, beta") || !strings.Contains(got, "--namespace alpha") {
+				t.Errorf("local=%v: multi branch should list both and offer --namespace:\n%s", local, got)
+			}
+			if strings.Contains(got, "client create") {
+				t.Errorf("local=%v: ambiguous multi-client must not suggest `client create`:\n%s", local, got)
+			}
+		}
+	})
+
+	t.Run("clean scan finding nothing points at the installer", func(t *testing.T) {
+		got := repointMessage(handle, boundNS, clientSurvey{looked: true})
+		for _, want := range []string{
+			lead,
+			"--namespace/--context",
+			"No tracebloc client is running on this cluster either",
+			installer.Cmd,
+		} {
+			if !strings.Contains(got, want) {
+				t.Errorf("missing %q:\n%s", want, got)
+			}
+		}
+	})
+
+	t.Run("could not look claims nothing", func(t *testing.T) {
+		got := repointMessage(handle, boundNS, clientSurvey{})
+		want := lead + "; run this command there, or override with --namespace/--context"
+		if got != want {
+			t.Errorf("unlooked message must stay the pre-#515 sentence exactly\n got: %q\nwant: %q", got, want)
+		}
+		// An absence of evidence must never print as evidence of absence.
+		if strings.Contains(got, "No tracebloc client is running") {
+			t.Errorf("a failed/absent scan must not claim the cluster is empty:\n%s", got)
+		}
+	})
+}
+
+// surveyCluster is the only thing standing between the message and a false
+// claim, so each way of "we could not look" has to come back as looked=false.
+func TestSurveyCluster_FailsClosed(t *testing.T) {
+	t.Run("nil probe", func(t *testing.T) {
+		if s := surveyCluster(context.Background(), nil); s.looked {
+			t.Errorf("a nil probe must not report as looked: %+v", s)
+		}
+	})
+
+	t.Run("nil clientset", func(t *testing.T) {
+		if s := surveyCluster(context.Background(), &clusterProbe{serverURL: "https://127.0.0.1:6550"}); s.looked {
+			t.Errorf("a probe with no clientset must not report as looked: %+v", s)
+		}
+	})
+
+	t.Run("scan forbidden", func(t *testing.T) {
+		cs := fake.NewSimpleClientset()
+		cs.PrependReactor("list", "deployments", func(ktesting.Action) (bool, runtime.Object, error) {
+			return true, nil, errors.New("forbidden: cannot list deployments at the cluster scope")
+		})
+		s := surveyCluster(context.Background(), &clusterProbe{cs: cs, serverURL: "https://127.0.0.1:6550"})
+		if s.looked {
+			t.Errorf("an RBAC-refused scan must not report as looked: %+v", s)
+		}
+	})
+
+	t.Run("clean empty scan looked and found nothing", func(t *testing.T) {
+		s := surveyCluster(context.Background(), &clusterProbe{cs: fake.NewSimpleClientset(), serverURL: "https://127.0.0.1:6550"})
+		if !s.looked || len(s.namespaces) != 0 {
+			t.Errorf("a clean empty scan is looked-with-nothing: %+v", s)
+		}
+		if !s.local {
+			t.Error("a loopback server URL must survey as local")
+		}
+	})
+
+	t.Run("finds the client and judges locality", func(t *testing.T) {
+		cs := fake.NewSimpleClientset(jmDep("lukas-02"))
+		s := surveyCluster(context.Background(), &clusterProbe{cs: cs, serverURL: "https://k8s.corp.example:6443"})
+		if !s.looked || len(s.namespaces) != 1 || s.namespaces[0] != "lukas-02" {
+			t.Errorf("survey = %+v, want the one namespace", s)
+		}
+		if s.local {
+			t.Error("a corporate API server must not survey as local")
+		}
+	})
+}
+
+// End-to-end through the real resolve path: a binding miss on a LOCAL cluster
+// that hosts the client elsewhere must NAME it — and must still not target it.
+// This is the pairing that matters (§7.5): the namespace appears in the message
+// and nowhere else.
+func TestExplain_BindingMiss_NamesTheLocalClientWithoutRetargeting(t *testing.T) {
+	cs := fake.NewSimpleClientset(jmDep("lukas-02"))
+	origLoad, origCS := loadClusterFn, newClientsetFn
+	t.Cleanup(func() { loadClusterFn, newClientsetFn = origLoad, origCS })
+	loadClusterFn = func(o cluster.KubeconfigOptions) (*cluster.ResolvedConfig, error) {
+		return &cluster.ResolvedConfig{
+			Namespace:  o.Namespace,
+			ServerURL:  "https://127.0.0.1:6550",
+			RestConfig: &rest.Config{},
+		}, nil
+	}
+	newClientsetFn = func(*cluster.ResolvedConfig) (kubernetes.Interface, error) { return cs, nil }
+
+	binding := activeClientBinding{applied: true, name: "gpu-box-01", namespace: "stale-ns"}
+	target, err := resolveClusterTarget(context.Background(), nil,
+		cluster.KubeconfigOptions{Namespace: "stale-ns"}, binding, false, false)
+	if err == nil {
+		t.Fatal("a binding miss must still fail — this changes the message, not the target")
+	}
+	if target != nil {
+		t.Fatalf("no target may be resolved from a binding miss, got %+v", target)
+	}
+	got := binding.explain(context.Background(), err)
+	if !strings.Contains(got.Error(), "lukas-02") {
+		t.Errorf("the message must name the client that IS here:\n%s", got)
+	}
+	if !strings.Contains(got.Error(), "client create") {
+		t.Errorf("a single client on a local cluster must be offered the repoint:\n%s", got)
+	}
+	if ExitCodeFromError(got) != 4 {
+		t.Errorf("exit code = %d, want 4", ExitCodeFromError(got))
+	}
+}
+
 // jmDep builds a chart-labeled jobs-manager Deployment in the given namespace,
 // for the fallback-scan tests (mirrors the cluster package's fixture).
 func jmDep(namespace string) *appsv1.Deployment {
diff --git a/internal/cli/data_delete.go b/internal/cli/data_delete.go
index e90c9fc..98c84d2 100644
--- a/internal/cli/data_delete.go
+++ b/internal/cli/data_delete.go
@@ -175,7 +175,7 @@ undone — re-ingesting the data is the only way back.`)
 	// mid-output blank between the warning and the note (§380).
 	target, err := resolveClusterTargetFn(ctx, a.Printer, opts, binding, true, false)
 	if err != nil {
-		return binding.explain(err)
+		return binding.explain(ctx, err)
 	}
 	resolved, cs, release, pvc := target.Resolved, target.Clientset, target.Release, target.PVC
 
diff --git a/internal/cli/data_ingest_cluster.go b/internal/cli/data_ingest_cluster.go
index ffd17b4..a750d80 100644
--- a/internal/cli/data_ingest_cluster.go
+++ b/internal/cli/data_ingest_cluster.go
@@ -58,7 +58,7 @@ func connectIngestTarget(ctx context.Context, a *runDataIngestArgs) (target *clu
 	// mid-output blank between "Connecting…" and the note (§380).
 	target, err = resolveClusterTarget(ctx, a.Printer, opts, binding, true, false)
 	if err != nil {
-		return nil, "", false, binding.explain(err)
+		return nil, "", false, binding.explain(ctx, err)
 	}
 	resolved, cs, release, pvc := target.Resolved, target.Clientset, target.Release, target.PVC
 	// release.IngestorSAName is discovered from the ingestionAuthz ConfigMap by
diff --git a/internal/cli/data_list.go b/internal/cli/data_list.go
index 0196273..f89cbab 100644
--- a/internal/cli/data_list.go
+++ b/internal/cli/data_list.go
@@ -124,7 +124,7 @@ func runDataList(ctx context.Context, a runDataListArgs) (err error) {
 	// multi-client redirect note is the opening line and self-leads its blank.
 	target, err := resolveClusterTarget(ctx, p, opts, binding, false, true)
 	if err != nil {
-		return binding.explain(err)
+		return binding.explain(ctx, err)
 	}
 	resolved, cs, release := target.Resolved, target.Clientset, target.Release
 
diff --git a/internal/cli/doctor.go b/internal/cli/doctor.go
index 3e22d3e..cd3341a 100644
--- a/internal/cli/doctor.go
+++ b/internal/cli/doctor.go
@@ -156,7 +156,7 @@ func runClusterDoctor(
 	//    problem goes unexplained. (A 401/426 is a hard stop earlier; only the
 	//    soft tokenUnreachable/tokenServerErr states reach here.)
 	opts := cluster.KubeconfigOptions{Path: kubeconfigPath, Context: contextOverride, Namespace: nsOverride}
-	bindActiveClientNamespace(&opts)
+	binding := bindActiveClientNamespace(&opts)
 	resolved, err = loadClusterFn(opts)
 	if err != nil {
 		p.Newline()
@@ -176,6 +176,39 @@ func runClusterDoctor(
 	// 4. Probe the cluster.
 	results = doctorRunFn(ctx, cs, doctor.Options{Namespace: resolved.Namespace, ServerURL: resolved.ServerURL})
 
+	// #515: a namespace we CHOSE for the user can be wrong, and a miss on it is
+	// not evidence that this machine has no environment — yet doctor's only
+	// reading of "no chart here" is "no secure environment on this machine yet",
+	// which then recommends reinstalling over a healthy install. Extend #401's
+	// local fallback to the wrong-pointer case: re-probe the namespace the
+	// KUBECONFIG selects, but only when the binding (not the user) picked the
+	// namespace that missed, and only on a LOCAL cluster — on a remote/shared one
+	// the ownership gate stands and we would risk naming a colleague's client.
+	// The retry is adopted only if it actually finds an environment, so a genuine
+	// no-environment machine keeps the original results (and the --diagnose
+	// bundle keeps describing the namespace the user is configured for).
+	// pointerStale records that the re-probe SUCCEEDED — i.e. this machine has a
+	// healthy environment AND its active-client pointer is wrong. Both halves
+	// have to be said; see the verdict block below for why finding the
+	// environment is not on its own good news.
+	pointerStale := false
+	if binding.applied && reachStateOf(results) == doctor.ReachNoEnv {
+		if ns, ok := localEnvNamespace(cluster.KubeconfigOptions{Path: kubeconfigPath, Context: contextOverride}); ok && ns != resolved.Namespace {
+			// Adopt the re-probe ONLY on a positive confirmation that a client is
+			// there. `!= ReachNoEnv` was wrong (Bugbot): ReachUnreachable and
+			// ReachError also satisfy it, and both mean "we could not tell" — so a
+			// stale pointer plus RBAC or a transient read on the context namespace
+			// would have named an unconfirmed namespace as a secure environment and
+			// told the user this cluster already runs a client, pushing `client
+			// create` into a MINT. Same absence-as-presence collapse surveyCluster
+			// and residencyOf exist to avoid; an unconfirmed re-probe keeps the
+			// original results and the honest no-environment path.
+			if retry := doctorRunFn(ctx, cs, doctor.Options{Namespace: ns, ServerURL: resolved.ServerURL}); reachConfirmedOK(retry) {
+				resolved.Namespace, results, pointerStale = ns, retry, true
+			}
+		}
+	}
+
 	// A reachable cluster with no tracebloc chart installed is the same "no secure
 	// environment here" state as a missing kubeconfig — route it through the same
 	// message (which also surfaces any session fault) rather than naming an
@@ -194,6 +227,23 @@ func runClusterDoctor(
 	// "Signed in" above, so the two context lines read as a pair), then roll up.
 	p.Para(fmt.Sprintf("Secure environment %q", envDisplayName(resolved)))
 	connected, ready = summarizeDoctor(results, tok)
+	if pointerStale {
+		// The environment above is healthy — but `data ingest`, `data list`,
+		// `resources` and `seal` all bind the active-client POINTER, and that
+		// still misses, so they keep failing with exit 4. "Ready to run training"
+		// is therefore false no matter how green the cluster checks are. Replace
+		// the readiness line rather than printing a green tick with a warning
+		// beside it that contradicts it — and the replacement carries the remedy,
+		// so the finding and the fix read as one thing. The support bundle
+		// records this line too, which is what triage needs to see.
+		ready = healthLine{
+			status: doctor.StatusFail,
+			text: fmt.Sprintf("Not ready — your active client points at namespace %q, which isn't on this cluster, so data commands will keep failing until you repoint.",
+				binding.namespace),
+			remedy: fmt.Sprintf("Point this machine at the environment above: %s client create  (this cluster already runs a client, so it adopts it — no new credential)",
+				launcher()),
+		}
+	}
 
 	p.Newline()
 	renderHealth(p, connected)
@@ -206,6 +256,14 @@ func runClusterDoctor(
 	p.Newline()
 	fail, allGood := doctorVerdict(connected.status, ready.status)
 	switch {
+	case pointerStale:
+		// A problem WAS found — it just isn't in the cluster. Exit 2 (the code
+		// doctor already uses for every actionable finding), never 0 with
+		// "you're ready to run training": the very next `data ingest` exits 4,
+		// and a doctor that greens that is reporting success it hasn't earned
+		// — the class BUGBOT.md flags first. The remedy is already printed
+		// above, so this doesn't also send them to write a support bundle.
+		return &exitError{code: exitChecksFailed, err: nil}
 	case fail:
 		if !diagnose { // they just wrote a bundle — don't send them to write it again
 			p.Hintf("Still stuck? Email support@tracebloc.io with the output of `%s doctor --diagnose`.", launcher())
@@ -531,6 +589,26 @@ func reachStateOf(results []doctor.Result) doctor.ReachState {
 	return doctor.ReachOK
 }
 
+// reachConfirmedOK reports whether the "Cluster reachable" check RAN and came
+// back ReachOK — a positive confirmation that a tracebloc client is in the probed
+// namespace.
+//
+// Deliberately not `reachStateOf(results) == ReachOK`: reachStateOf defaults to
+// ReachOK when the check is ABSENT, which is the right lenient default for the
+// main path (an older probe set shouldn't block a verdict) and precisely the
+// wrong one for #515's re-probe, where the whole question is whether we may
+// believe an unproven namespace. Absent, unreachable and errored all answer
+// "we could not tell", and none of them may authorize naming a secure
+// environment or advising `client create`.
+func reachConfirmedOK(results []doctor.Result) bool {
+	for _, r := range results {
+		if r.Name == "Cluster reachable" {
+			return r.Reach == doctor.ReachOK
+		}
+	}
+	return false
+}
+
 // worseStatus returns the more severe of two doctor statuses (Fail > Warn > OK).
 // StatusUnknown carries no signal, so it never worsens the verdict.
 func worseStatus(a, b doctor.Status) doctor.Status {
diff --git a/internal/cli/doctor_pointer_test.go b/internal/cli/doctor_pointer_test.go
new file mode 100644
index 0000000..d7a03b3
--- /dev/null
+++ b/internal/cli/doctor_pointer_test.go
@@ -0,0 +1,331 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"net/http"
+	"strings"
+	"testing"
+
+	"k8s.io/client-go/kubernetes"
+	"k8s.io/client-go/kubernetes/fake"
+	"k8s.io/client-go/rest"
+
+	"github.com/tracebloc/cli/internal/cluster"
+	"github.com/tracebloc/cli/internal/doctor"
+	"github.com/tracebloc/cli/internal/ui"
+)
+
+// #515 — a WRONG active-client pointer must not read as "no environment".
+// Split from doctor_test.go, which is already at its file budget.
+
+// stubDoctorForNamespace makes doctor's cluster I/O deterministic: the kubeconfig
+// resolves to a caller-chosen server URL with the namespace opts asked for (or
+// kubeconfigNS when nothing was pinned — exactly how cluster.Load layers an
+// explicit namespace over the context's own), and the probe reports a healthy
+// environment in envNS and ReachNoEnv anywhere else. It returns the list of
+// namespaces the probe ran against, so a test can assert what was and wasn't
+// re-probed rather than inferring it from the rendered text.
+func stubDoctorForNamespace(t *testing.T, serverURL, kubeconfigNS, envNS string) *[]string {
+	t.Helper()
+	origLoad, origCS, origRun := loadClusterFn, newClientsetFn, doctorRunFn
+	t.Cleanup(func() { loadClusterFn, newClientsetFn, doctorRunFn = origLoad, origCS, origRun })
+
+	loadClusterFn = func(o cluster.KubeconfigOptions) (*cluster.ResolvedConfig, error) {
+		ns := o.Namespace
+		if ns == "" {
+			ns = kubeconfigNS
+		}
+		return &cluster.ResolvedConfig{
+			Namespace: ns, Context: "test-ctx", ServerURL: serverURL, RestConfig: &rest.Config{},
+		}, nil
+	}
+	newClientsetFn = func(*cluster.ResolvedConfig) (kubernetes.Interface, error) {
+		return fake.NewSimpleClientset(), nil
+	}
+	var probed []string
+	doctorRunFn = func(_ context.Context, _ kubernetes.Interface, o doctor.Options) []doctor.Result {
+		probed = append(probed, o.Namespace)
+		if o.Namespace != envNS {
+			return []doctor.Result{{Name: "Cluster reachable", Status: doctor.StatusFail, Reach: doctor.ReachNoEnv}}
+		}
+		return []doctor.Result{
+			{Name: "Cluster reachable", Status: doctor.StatusOK, Reach: doctor.ReachOK},
+			{Name: "Pod health", Status: doctor.StatusOK},
+		}
+	}
+	return &probed
+}
+
+// okWhoAmI stubs the session probe so these tests reach the cluster stage.
+func okWhoAmI(t *testing.T) {
+	t.Helper()
+	stubBackend(t, func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"email":"a@b.io","account":"Acme"}`))
+	})
+}
+
+// The field symptom: a healthy local k3d install whose active-client pointer
+// names a namespace that isn't on this cluster. doctor bound the wrong pointer,
+// probed only it, and told the user to reinstall over a working environment
+// (#401 fixed only the EMPTY-pointer case).
+func TestDoctor_WrongPointerOnLocalCluster_FindsTheEnvironment(t *testing.T) {
+	writeActiveClientConfig(t, "stale-ns", "Stale")
+	okWhoAmI(t)
+	probed := stubDoctorForNamespace(t, "https://127.0.0.1:6550", "lukas-02", "lukas-02")
+
+	var out bytes.Buffer
+	err := runClusterDoctor(context.Background(), ui.New(&out, ui.WithColor(false)), "", "", "", false)
+	if strings.Contains(out.String(), "No secure environment") {
+		t.Errorf("must not recommend a reinstall over a healthy install:\n%s", out.String())
+	}
+	if !strings.Contains(out.String(), "lukas-02") {
+		t.Errorf("doctor should name the environment that IS here:\n%s", out.String())
+	}
+	if len(*probed) != 2 || (*probed)[0] != "stale-ns" || (*probed)[1] != "lukas-02" {
+		t.Errorf("probe namespaces = %v, want [stale-ns lukas-02] (bound pointer first, then the kubeconfig's own)", *probed)
+	}
+
+	// Bugbot (#515): finding the environment is only HALF the story. The pointer
+	// is still stale, so `data ingest`/`resources`/`seal` keep exiting 4 — doctor
+	// must say so and must not green the machine.
+	if strings.Contains(out.String(), "Everything looks good") {
+		t.Errorf("a stale pointer means data commands still fail — this is not 'ready to run training':\n%s", out.String())
+	}
+	// …and the readiness LINE must carry it too: a green "✔ Ready to run
+	// training" beside a warning that contradicts it is the same unearned
+	// success, just moved up the screen.
+	if strings.Contains(out.String(), "✔ Ready to run training") {
+		t.Errorf("the readiness line must not tick green while the pointer is stale:\n%s", out.String())
+	}
+	if !strings.Contains(out.String(), "Not ready") {
+		t.Errorf("want the readiness line to carry the finding:\n%s", out.String())
+	}
+	if !strings.Contains(out.String(), "stale-ns") {
+		t.Errorf("doctor must name the stale pointer, not just the environment it found:\n%s", out.String())
+	}
+	if !strings.Contains(out.String(), "client create") {
+		t.Errorf("doctor must name the repoint:\n%s", out.String())
+	}
+	var ee *exitError
+	if !errors.As(err, &ee) || ee.Code() != 2 {
+		t.Fatalf("a stale pointer is a problem doctor found → want exit 2, got %v", err)
+	}
+}
+
+// The other side of the same coin: with NO stale pointer, a healthy machine
+// still gets its green line and exit 0. Without this, the assertion above could
+// be satisfied by doctor never saying "Everything looks good" at all.
+func TestDoctor_HealthyPointer_StillGreen(t *testing.T) {
+	writeActiveClientConfig(t, "lukas-02", "Lukas") // pointer matches reality
+	okWhoAmI(t)
+	probed := stubDoctorForNamespace(t, "https://127.0.0.1:6550", "lukas-02", "lukas-02")
+
+	var out bytes.Buffer
+	if err := runClusterDoctor(context.Background(), ui.New(&out, ui.WithColor(false)), "", "", "", false); err != nil {
+		t.Fatalf("a healthy machine with a correct pointer must exit 0, got %v", err)
+	}
+	if !strings.Contains(out.String(), "Everything looks good") {
+		t.Errorf("want the green verdict when nothing is stale:\n%s", out.String())
+	}
+	if !strings.Contains(out.String(), "✔ Ready to run training") {
+		t.Errorf("control: the readiness line must still tick green when nothing is stale:\n%s", out.String())
+	}
+	if strings.Contains(out.String(), "client create") {
+		t.Errorf("no repoint advice when the pointer is correct:\n%s", out.String())
+	}
+	if len(*probed) != 1 {
+		t.Errorf("probe namespaces = %v, want one (nothing to re-probe)", *probed)
+	}
+}
+
+// The ownership gate is what keeps the fallback honest, so it gets its own test:
+// on a REMOTE/shared cluster a pointer miss stays "no secure environment" and the
+// re-probe never runs — the client sitting in another namespace there may well be
+// a colleague's (§7.5).
+func TestDoctor_WrongPointerOnRemoteCluster_StaysGated(t *testing.T) {
+	writeActiveClientConfig(t, "stale-ns", "Stale")
+	okWhoAmI(t)
+	probed := stubDoctorForNamespace(t, "https://k8s.corp.example:6443", "colleague-07", "colleague-07")
+
+	var out bytes.Buffer
+	err := runClusterDoctor(context.Background(), ui.New(&out, ui.WithColor(false)), "", "", "", false)
+	if err == nil {
+		t.Fatal("a pointer miss on a remote cluster is still a problem — want a non-zero exit")
+	}
+	if !strings.Contains(out.String(), "No secure environment") {
+		t.Errorf("remote cluster must keep the honest no-environment message:\n%s", out.String())
+	}
+	if strings.Contains(out.String(), "colleague-07") {
+		t.Errorf("a remote cluster's other namespace must never be named as yours:\n%s", out.String())
+	}
+	if len(*probed) != 1 {
+		t.Errorf("probe namespaces = %v, want exactly one (no re-probe off a remote cluster)", *probed)
+	}
+}
+
+// A user who pinned --namespace themselves is never second-guessed: no binding
+// was applied, so nothing re-probes and the miss stands as they asked for it.
+func TestDoctor_ExplicitNamespaceMiss_IsNotReprobed(t *testing.T) {
+	writeActiveClientConfig(t, "stale-ns", "Stale")
+	okWhoAmI(t)
+	probed := stubDoctorForNamespace(t, "https://127.0.0.1:6550", "lukas-02", "lukas-02")
+
+	var out bytes.Buffer
+	err := runClusterDoctor(context.Background(), ui.New(&out, ui.WithColor(false)), "", "", "chosen-ns", false)
+	if err == nil {
+		t.Fatal("an explicit --namespace miss must still fail")
+	}
+	if len(*probed) != 1 || (*probed)[0] != "chosen-ns" {
+		t.Errorf("probe namespaces = %v, want only the namespace the user pinned", *probed)
+	}
+	if !strings.Contains(out.String(), "No secure environment") {
+		t.Errorf("want the no-environment message for an explicitly-pinned miss:\n%s", out.String())
+	}
+}
+
+// A machine that genuinely has nothing must keep the installer advice: the
+// re-probe runs, finds no environment either, and the original results stand.
+func TestDoctor_LocalClusterWithNothing_KeepsInstallerAdvice(t *testing.T) {
+	writeActiveClientConfig(t, "stale-ns", "Stale")
+	okWhoAmI(t)
+	probed := stubDoctorForNamespace(t, "https://127.0.0.1:6550", "default", "nowhere")
+
+	var out bytes.Buffer
+	if err := runClusterDoctor(context.Background(), ui.New(&out, ui.WithColor(false)), "", "", "", false); err == nil {
+		t.Fatal("a machine with no environment must still exit non-zero")
+	}
+	if !strings.Contains(out.String(), "No secure environment") {
+		t.Errorf("want the no-environment message when the re-probe finds nothing too:\n%s", out.String())
+	}
+	if len(*probed) != 2 {
+		t.Errorf("probe namespaces = %v, want the bound namespace and the kubeconfig's own", *probed)
+	}
+}
+
+// Bugbot (#515): the re-probe used to adopt on anything that wasn't ReachNoEnv,
+// which swept in ReachUnreachable and ReachError — both of which mean "we could
+// not tell". Adopting either would name an unconfirmed namespace as a secure
+// environment and tell the user this cluster already runs a client, pushing
+// `client create` into a MINT on a cluster that may host nothing.
+//
+// The input domain is derived from doctor.ReachState's declared surface rather
+// than hand-picked, plus the ABSENT case (reachStateOf's lenient default is
+// exactly what must not apply here). Only ReachOK may adopt.
+func TestDoctor_ReProbeAdoptsOnlyOnConfirmedReach(t *testing.T) {
+	// Every non-OK member of the enum, and the missing-check case.
+	cases := []struct {
+		name    string
+		results []doctor.Result
+	}{
+		{"unreachable", []doctor.Result{{Name: "Cluster reachable", Status: doctor.StatusFail, Reach: doctor.ReachUnreachable}}},
+		{"error (RBAC/NotFound)", []doctor.Result{{Name: "Cluster reachable", Status: doctor.StatusFail, Reach: doctor.ReachError}}},
+		{"no env", []doctor.Result{{Name: "Cluster reachable", Status: doctor.StatusFail, Reach: doctor.ReachNoEnv}}},
+		{"check absent entirely", []doctor.Result{{Name: "Pod health", Status: doctor.StatusOK}}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			writeActiveClientConfig(t, "stale-ns", "Stale")
+			okWhoAmI(t)
+
+			origLoad, origCS, origRun := loadClusterFn, newClientsetFn, doctorRunFn
+			t.Cleanup(func() { loadClusterFn, newClientsetFn, doctorRunFn = origLoad, origCS, origRun })
+			loadClusterFn = func(o cluster.KubeconfigOptions) (*cluster.ResolvedConfig, error) {
+				ns := o.Namespace
+				if ns == "" {
+					ns = "unproven-ns"
+				}
+				return &cluster.ResolvedConfig{Namespace: ns, ServerURL: "https://127.0.0.1:6550", RestConfig: &rest.Config{}}, nil
+			}
+			newClientsetFn = func(*cluster.ResolvedConfig) (kubernetes.Interface, error) {
+				return fake.NewSimpleClientset(), nil
+			}
+			doctorRunFn = func(_ context.Context, _ kubernetes.Interface, o doctor.Options) []doctor.Result {
+				if o.Namespace == "stale-ns" { // the bound pointer always misses
+					return []doctor.Result{{Name: "Cluster reachable", Status: doctor.StatusFail, Reach: doctor.ReachNoEnv}}
+				}
+				return c.results // the re-probe's inconclusive answer
+			}
+
+			var out bytes.Buffer
+			err := runClusterDoctor(context.Background(), ui.New(&out, ui.WithColor(false)), "", "", "", false)
+			got := out.String()
+			if strings.Contains(got, "unproven-ns") {
+				t.Errorf("an unconfirmed namespace must never be named as a secure environment:\n%s", got)
+			}
+			if strings.Contains(got, "client create") {
+				t.Errorf("advising the repoint here can push a MINT — the cluster was never confirmed to run a client:\n%s", got)
+			}
+			if !strings.Contains(got, "No secure environment") {
+				t.Errorf("an unconfirmed re-probe must keep the honest no-environment path:\n%s", got)
+			}
+			if err == nil {
+				t.Error("want a non-zero exit when nothing was confirmed")
+			}
+		})
+	}
+}
+
+// reachConfirmedOK is the guard above, tested directly against the whole
+// declared enum so a future ReachState member can't quietly slip through the
+// "could not tell" side. Mutation coverage cannot see a vocabulary gap.
+func TestReachConfirmedOK(t *testing.T) {
+	res := func(r doctor.ReachState) []doctor.Result {
+		return []doctor.Result{{Name: "Cluster reachable", Reach: r}}
+	}
+	if !reachConfirmedOK(res(doctor.ReachOK)) {
+		t.Error("ReachOK is the one positive confirmation")
+	}
+	for _, r := range []doctor.ReachState{doctor.ReachUnreachable, doctor.ReachNoEnv, doctor.ReachError} {
+		if reachConfirmedOK(res(r)) {
+			t.Errorf("Reach %v must not count as confirmed", r)
+		}
+	}
+	if reachConfirmedOK([]doctor.Result{{Name: "Pod health"}}) {
+		t.Error("an ABSENT reachability check is 'could not tell', not OK — reachStateOf's lenient default must not leak in here")
+	}
+	if reachConfirmedOK(nil) {
+		t.Error("no results at all is not a confirmation")
+	}
+}
+
+// localEnvNamespace is the doctor-side half of the #401 carve-out; its three
+// refusals are what stop the re-probe from ever naming someone else's client.
+func TestLocalEnvNamespace(t *testing.T) {
+	set := func(rc *cluster.ResolvedConfig, err error) {
+		t.Helper()
+		orig := loadClusterFn
+		t.Cleanup(func() { loadClusterFn = orig })
+		loadClusterFn = func(cluster.KubeconfigOptions) (*cluster.ResolvedConfig, error) { return rc, err }
+	}
+
+	t.Run("local server with a namespace", func(t *testing.T) {
+		set(&cluster.ResolvedConfig{Namespace: "lukas-02", ServerURL: "https://127.0.0.1:6550"}, nil)
+		ns, ok := localEnvNamespace(cluster.KubeconfigOptions{})
+		if !ok || ns != "lukas-02" {
+			t.Errorf("= %q,%v; want lukas-02,true", ns, ok)
+		}
+	})
+
+	t.Run("remote server is refused", func(t *testing.T) {
+		set(&cluster.ResolvedConfig{Namespace: "colleague-07", ServerURL: "https://k8s.corp.example:6443"}, nil)
+		if ns, ok := localEnvNamespace(cluster.KubeconfigOptions{}); ok {
+			t.Errorf("= %q,%v; a remote cluster must be refused", ns, ok)
+		}
+	})
+
+	t.Run("empty namespace is refused", func(t *testing.T) {
+		set(&cluster.ResolvedConfig{Namespace: "", ServerURL: "https://127.0.0.1:6550"}, nil)
+		if ns, ok := localEnvNamespace(cluster.KubeconfigOptions{}); ok {
+			t.Errorf("= %q,%v; an empty namespace is not a reading", ns, ok)
+		}
+	})
+
+	t.Run("load failure is refused", func(t *testing.T) {
+		set(nil, context.DeadlineExceeded)
+		if ns, ok := localEnvNamespace(cluster.KubeconfigOptions{}); ok {
+			t.Errorf("= %q,%v; an unreadable kubeconfig is not a reading", ns, ok)
+		}
+	})
+}
diff --git a/internal/cli/home.go b/internal/cli/home.go
index c438ff8..7855db3 100644
--- a/internal/cli/home.go
+++ b/internal/cli/home.go
@@ -30,7 +30,6 @@ package cli
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"math"
 	"os"
@@ -155,6 +154,13 @@ type envProbe struct {
 	name       string
 	compute    computeInfo
 	hasCompute bool
+	// pointerStale: the environment above was found by the #515 local fallback
+	// AFTER the active-client pointer missed — so the release we can see running
+	// here is NOT the client the pointer names. The heartbeat is looked up by
+	// that pointer's client id, so it describes a different machine's client and
+	// must never be allowed to green this one (Bugbot: local liveness from one
+	// client + a heartbeat from another is an Online nobody earned).
+	pointerStale bool
 }
 
 // homeDeps are the detection seams. defaultHomeDeps wires the real
@@ -270,7 +276,14 @@ func resolveHomeModel(ctx context.Context, d homeDeps) homeModel {
 	// a release present on a machine that never cached a client. This also keeps
 	// the "provisioned ⇒ named offline" fallback (a degraded probe returns no
 	// name) living in exactly one place.
-	if remembered != "" {
+	//
+	// EXCEPT when the pointer is stale (#515): the remembered name is the handle
+	// of the client the pointer names, and that client is NOT what the fallback
+	// found running here. Applying it would print another machine's handle as the
+	// environment on this one — a wrong label, and one that contradicts doctor's
+	// namespace-based name for the very same state (Bugbot). Fall through to the
+	// probe's own name, which at least describes what is actually running.
+	if remembered != "" && !env.pointerStale {
 		env.name = remembered
 	}
 
@@ -291,11 +304,16 @@ func resolveHomeModel(ctx context.Context, d homeDeps) homeModel {
 		// honest "· running" state, never a green Online — but the model records
 		// WHICH kind of not-Online it is, so the running line can word a
 		// backend-confirmed "not online" differently from a mere couldn't-confirm.
-		if beat == beatOnline {
+		// #515: with a stale pointer the heartbeat is about a DIFFERENT client
+		// than the release running here, so it carries no signal about this one
+		// in either direction — it can neither green it (a colleague's machine
+		// being online is not this one being online) nor red it. Drop to the
+		// honest "running, couldn't confirm" line, which is exactly true.
+		if beat == beatOnline && !env.pointerStale {
 			m.state = homeOnline
 		} else {
 			m.state = homeRunning
-			m.confirmedNotOnline = beat == beatNotOnline
+			m.confirmedNotOnline = beat == beatNotOnline && !env.pointerStale
 		}
 		m.fullMenu = true
 	case localDegraded:
@@ -463,78 +481,6 @@ func realRememberedClient() (provisioned bool, name string) {
 	return p.ActiveClientNamespace != "", name
 }
 
-// realProbeEnv is the bounded cluster probe. It reuses the exact namespace
-// binding + discovery the data/cluster commands use, so the home screen reports
-// the very environment those commands would target. Best-effort throughout: any
-// failure degrades to unreachable/no-release, never an error.
-func realProbeEnv(ctx context.Context) envProbe {
-	ctx, cancel := context.WithTimeout(ctx, homeProbeTimeout)
-	defer cancel()
-
-	// The name for a discovered release is set below; the unreachable / no-release
-	// returns leave it empty and let resolveHomeModel fill the remembered name, so
-	// the "provisioned ⇒ named offline" fallback lives in exactly one place.
-	opts := cluster.KubeconfigOptions{}
-	binding := bindActiveClientNamespace(&opts)
-	// OWNERSHIP GATE: no active-client binding ⇒ nothing was ever provisioned
-	// for this profile, so no release the kubeconfig can reach is honestly
-	// YOURS. Without the binding, discovery would fall back to the kubeconfig's
-	// default namespace and then the cluster-wide scan — either can surface an
-	// UNRELATED client (a shared cluster, a colleague's install), which this
-	// screen would then greet as "your secure environment". The data commands
-	// run that scan behind a visible retarget note and an explicit user action;
-	// a status screen has neither, and §7.5's rule (a miss must never silently
-	// retarget to some other client) applies doubly here. Report no-release —
-	// resolveHomeModel renders the honest no-env screen (or a named offline via
-	// the remembered-name fallback) — and skip the cluster I/O entirely, which
-	// also keeps the common unprovisioned re-entry instant.
-	if !binding.applied {
-		// #401: an empty pointer isn't proof of "no environment" — the Windows
-		// installer never writes it. localEnvFallback adopts a release only on
-		// a LOCAL (loopback/k3d) cluster, so the shared-cluster guarantee above
-		// is preserved; everything else still reads as no-release.
-		return localEnvFallback(ctx)
-	}
-	resolved, err := loadClusterFn(opts)
-	if err != nil {
-		return envProbe{local: localUnreachable}
-	}
-	// Bound every API call so an unreachable API server can't hang the home
-	// screen (mirrors cluster.ClusterID's time-boxed best-effort read).
-	resolved.RestConfig.Timeout = homeProbeTimeout
-	cs, err := newClientsetFn(resolved)
-	if err != nil {
-		return envProbe{local: localUnreachable}
-	}
-
-	release, nsUsed, err := discoverRelease(ctx, nil, cs, resolved.Namespace, binding.allowScan(), false)
-	if err != nil {
-		if errors.Is(err, cluster.ErrNoParentRelease) {
-			// Cluster reachable, but this release isn't in the resolved context.
-			// Provisioned ⇒ resolveHomeModel turns this into a named "offline".
-			return envProbe{local: localNoRelease}
-		}
-		// A list/RBAC/connect failure: we couldn't confirm what's here. Treat it
-		// as unreachable (→ offline if provisioned, else no-env).
-		return envProbe{local: localUnreachable}
-	}
-
-	ep := envProbe{name: release.ReleaseName}
-	if jobsManagerReady(ctx, cs, nsUsed, release) {
-		ep.local = localLive
-	} else {
-		ep.local = localDegraded
-	}
-	// Compute is only surfaced on the Online line, and only worth reading when the
-	// environment is actually up.
-	if ep.local == localLive {
-		if c, ok := machineCapacity(ctx, cs); ok {
-			ep.compute, ep.hasCompute = c, true
-		}
-	}
-	return ep
-}
-
 // realHeartbeat reports tracebloc's view of this machine's client — the honest
 // "is it heartbeating" signal.
 //
diff --git a/internal/cli/home_local_fallback.go b/internal/cli/home_local_fallback.go
index 8900154..abbd580 100644
--- a/internal/cli/home_local_fallback.go
+++ b/internal/cli/home_local_fallback.go
@@ -1,10 +1,15 @@
 package cli
 
-// Home-screen fallbacks for machines the provisioning pointer never reached
-// (#401). Split from home.go to respect its file budget.
+// The home screen's environment probe, and the fallbacks it leans on when the
+// provisioning pointer can't be trusted — never reached this machine at all
+// (#401) or names a namespace that isn't on the reached cluster (#515). Split
+// from home.go to respect its file budget; realProbeEnv moved here under #515
+// because it is now mostly a decision about WHICH fallback to take, and reads
+// better next to them than next to the renderer.
 
 import (
 	"context"
+	"errors"
 	"net"
 	"net/url"
 	"os"
@@ -15,10 +20,23 @@ import (
 )
 
 // localEnvFallback answers "is there a secure environment on THIS machine?"
-// when the active-client pointer is empty — the state every pre-#388 Windows
-// install is in permanently, because only `client create` writes the pointer
-// and the Windows installer never ran it. Field case: `doctor` said "Ready to
-// run training" while home said "No secure environment on this machine yet".
+// when the active-client pointer cannot be trusted:
+//
+//   - it is EMPTY (#401) — the state every pre-#388 Windows install is in
+//     permanently, because only `client create` writes the pointer and the
+//     Windows installer never ran it. Field case: `doctor` said "Ready to run
+//     training" while home said "No secure environment on this machine yet".
+//   - it is SET BUT WRONG (#515) — it names a namespace that isn't on the
+//     cluster this kubeconfig reaches (an orphaned record left by a cluster
+//     recreation, a pointer written on another machine). #401 covered only the
+//     empty case, so a wrong pointer went on recommending a reinstall over a
+//     healthy install.
+//
+// Both are the same question, and the answer must not come from the pointer:
+// this reloads the kubeconfig with NO binding applied, so it probes the
+// namespace the kubeconfig itself selects — which is the client's own namespace
+// on any installer-provisioned machine (install-client-helm.sh runs
+// `kubectl config set-context --current --namespace <ns>`).
 //
 // The ownership gate in realProbeEnv exists so a status screen never greets a
 // SHARED cluster's unrelated client as yours (§7.5). This fallback keeps that
@@ -62,6 +80,31 @@ func localEnvFallback(ctx context.Context) envProbe {
 	return ep
 }
 
+// localEnvNamespace reports the namespace the KUBECONFIG itself selects, and
+// whether that reading is usable — i.e. the kubeconfig loads and the cluster it
+// reaches is LOCAL (the #401 carve-out: a cluster that is this machine by
+// definition, so whatever tracebloc release runs there is this machine's).
+//
+// It is the doctor-side half of localEnvFallback (#515), for the one caller that
+// already holds a clientset and only needs the namespace to re-probe. Like the
+// fallback it applies NO active-client binding — that pointer is precisely the
+// thing under suspicion — and it never scans: the installer points the
+// kubeconfig context at the client's namespace
+// (install-client-helm.sh: `kubectl config set-context --current --namespace`),
+// so reading it is enough and no cluster-wide list is spent. On a remote or
+// shared cluster it returns false, so the ownership gate holds exactly as it
+// does on the home screen.
+func localEnvNamespace(opts cluster.KubeconfigOptions) (string, bool) {
+	resolved, err := loadClusterFn(opts)
+	if err != nil || resolved == nil {
+		return "", false
+	}
+	if !isLocalServerURL(resolved.ServerURL) || resolved.Namespace == "" {
+		return "", false
+	}
+	return resolved.Namespace, true
+}
+
 // isLocalServerURL reports whether a kubeconfig server URL points at THIS
 // machine. Covers loopback names/addresses, the wildcard binds k3d writes when
 // no host is pinned, and Docker Desktop's host alias (the same signals
@@ -116,3 +159,88 @@ func tbCmdAliasOurs(dir, exe string) bool {
 	}
 	return strings.Contains(strings.ToLower(string(b)), strings.ToLower(filepath.Clean(exe)))
 }
+
+// realProbeEnv is the bounded cluster probe. It reuses the exact namespace
+// binding + discovery the data/cluster commands use, so the home screen reports
+// the very environment those commands would target. Best-effort throughout: any
+// failure degrades to unreachable/no-release, never an error.
+func realProbeEnv(ctx context.Context) envProbe {
+	ctx, cancel := context.WithTimeout(ctx, homeProbeTimeout)
+	defer cancel()
+
+	// The name for a discovered release is set below; the unreachable / no-release
+	// returns leave it empty and let resolveHomeModel fill the remembered name, so
+	// the "provisioned ⇒ named offline" fallback lives in exactly one place.
+	opts := cluster.KubeconfigOptions{}
+	binding := bindActiveClientNamespace(&opts)
+	// OWNERSHIP GATE: no active-client binding ⇒ nothing was ever provisioned
+	// for this profile, so no release the kubeconfig can reach is honestly
+	// YOURS. Without the binding, discovery would fall back to the kubeconfig's
+	// default namespace and then the cluster-wide scan — either can surface an
+	// UNRELATED client (a shared cluster, a colleague's install), which this
+	// screen would then greet as "your secure environment". The data commands
+	// run that scan behind a visible retarget note and an explicit user action;
+	// a status screen has neither, and §7.5's rule (a miss must never silently
+	// retarget to some other client) applies doubly here. Report no-release —
+	// resolveHomeModel renders the honest no-env screen (or a named offline via
+	// the remembered-name fallback) — and skip the cluster I/O entirely, which
+	// also keeps the common unprovisioned re-entry instant.
+	if !binding.applied {
+		// #401: an empty pointer isn't proof of "no environment" — the Windows
+		// installer never writes it. localEnvFallback adopts a release only on
+		// a LOCAL (loopback/k3d) cluster, so the shared-cluster guarantee above
+		// is preserved; everything else still reads as no-release.
+		return localEnvFallback(ctx)
+	}
+	resolved, err := loadClusterFn(opts)
+	if err != nil {
+		return envProbe{local: localUnreachable}
+	}
+	// Bound every API call so an unreachable API server can't hang the home
+	// screen (mirrors cluster.ClusterID's time-boxed best-effort read).
+	resolved.RestConfig.Timeout = homeProbeTimeout
+	cs, err := newClientsetFn(resolved)
+	if err != nil {
+		return envProbe{local: localUnreachable}
+	}
+
+	release, nsUsed, err := discoverRelease(ctx, nil, cs, resolved.Namespace, binding.allowScan(), false)
+	if err != nil {
+		if errors.Is(err, cluster.ErrNoParentRelease) {
+			// Cluster reachable, but this release isn't in the resolved context.
+			// #515: a WRONG pointer is no more proof of "no environment" than the
+			// empty one #401 covered — the binding above overrode the kubeconfig's
+			// own namespace with a stale/foreign one, so this miss says nothing
+			// about what runs here. Re-ask through the same local-only fallback:
+			// it adopts a release ONLY when the kubeconfig's server is this
+			// machine, so the shared-cluster guarantee is untouched, and every
+			// other outcome is localNoRelease — exactly what this branch returned
+			// before. Provisioned ⇒ resolveHomeModel turns that into a named
+			// "offline".
+			ep := localEnvFallback(ctx)
+			// Mark it: the release the fallback found is not the client the
+			// pointer names, so the heartbeat keyed on that pointer describes
+			// someone else. resolveHomeModel refuses to render Online off this.
+			ep.pointerStale = ep.local != localNoRelease
+			return ep
+		}
+		// A list/RBAC/connect failure: we couldn't confirm what's here. Treat it
+		// as unreachable (→ offline if provisioned, else no-env).
+		return envProbe{local: localUnreachable}
+	}
+
+	ep := envProbe{name: release.ReleaseName}
+	if jobsManagerReady(ctx, cs, nsUsed, release) {
+		ep.local = localLive
+	} else {
+		ep.local = localDegraded
+	}
+	// Compute is only surfaced on the Online line, and only worth reading when the
+	// environment is actually up.
+	if ep.local == localLive {
+		if c, ok := machineCapacity(ctx, cs); ok {
+			ep.compute, ep.hasCompute = c, true
+		}
+	}
+	return ep
+}
diff --git a/internal/cli/home_local_fallback_test.go b/internal/cli/home_local_fallback_test.go
index b8e3894..a194067 100644
--- a/internal/cli/home_local_fallback_test.go
+++ b/internal/cli/home_local_fallback_test.go
@@ -6,6 +6,7 @@ import (
 	"os"
 	"path/filepath"
 	"testing"
+	"time"
 
 	appsv1 "k8s.io/api/apps/v1"
 	corev1 "k8s.io/api/core/v1"
@@ -91,6 +92,140 @@ func TestLocalEnvFallback_NoKubeconfigIsNoRelease(t *testing.T) {
 	}
 }
 
+// #515: the home screen's hole was the mirror of doctor's. Its local-env
+// fallback was reached only when the pointer was EMPTY (`if !binding.applied`),
+// so a pointer that was set but WRONG skipped the #401 fix entirely and the
+// screen said "No secure environment on this machine yet" over a live install.
+func TestRealProbeEnv_WrongPointerOnLocalCluster_FallsBack(t *testing.T) {
+	writeActiveClientConfig(t, "stale-ns", "Stale") // binding APPLIED, and wrong
+	o := fallbackRelease("lukas-02")
+	cs := fake.NewClientset(o[0].(*appsv1.Deployment), o[1].(*corev1.Service))
+
+	origLoad, origCS := loadClusterFn, newClientsetFn
+	t.Cleanup(func() { loadClusterFn, newClientsetFn = origLoad, origCS })
+	// Models cluster.Load: an explicit opts.Namespace wins, otherwise the
+	// context's own namespace — which the installer points at the client's
+	// namespace (install-client-helm.sh `kubectl config set-context --current
+	// --namespace`). So the binding sends the first probe to "stale-ns" and the
+	// unbound fallback reload lands on "lukas-02".
+	loadClusterFn = func(o cluster.KubeconfigOptions) (*cluster.ResolvedConfig, error) {
+		ns := o.Namespace
+		if ns == "" {
+			ns = "lukas-02"
+		}
+		return &cluster.ResolvedConfig{
+			Namespace: ns, ServerURL: "https://127.0.0.1:6550", RestConfig: &rest.Config{},
+		}, nil
+	}
+	newClientsetFn = func(*cluster.ResolvedConfig) (kubernetes.Interface, error) { return cs, nil }
+
+	ep := realProbeEnv(context.Background())
+	if ep.local != localLive || ep.name != "tracebloc" {
+		t.Fatalf("=> %+v, want the live local environment despite the stale pointer", ep)
+	}
+	// Bugbot (#515): the release we found is NOT the client the pointer names, so
+	// the heartbeat (looked up by that pointer's id) is about a different machine
+	// and must be barred from greening this one.
+	if !ep.pointerStale {
+		t.Error("a fallback that fired after a pointer MISS must mark the pointer stale")
+	}
+}
+
+// The stale mark must actually change the verdict: local liveness from one
+// client plus a beatOnline from another is an Online nobody earned.
+func TestResolveHomeModel_StalePointerNeverRendersOnline(t *testing.T) {
+	base := func(stale bool) homeModel {
+		return resolveHomeModel(context.Background(), homeDeps{
+			budget:           2 * time.Second,
+			invoked:          func() string { return binTB },
+			tbAvailable:      func() bool { return true },
+			hasResources:     func() bool { return true },
+			signIn:           func() (bool, string, string) { return true, "a@b.io", "Lukas" },
+			rememberedClient: func() (bool, string) { return true, "stale-01" },
+			probeBeat:        func(context.Context) heartbeatState { return beatOnline },
+			probeEnv: func(context.Context) envProbe {
+				return envProbe{local: localLive, name: "tracebloc", pointerStale: stale}
+			},
+		})
+	}
+
+	if m := base(false); m.state != homeOnline {
+		t.Fatalf("control: live + beatOnline + fresh pointer must be Online, got %v", m.state)
+	}
+	m := base(true)
+	if m.state == homeOnline {
+		t.Error("a stale pointer must never render Online — the heartbeat is another client's")
+	}
+	if m.state != homeRunning {
+		t.Errorf("want the honest running state, got %v", m.state)
+	}
+	if m.confirmedNotOnline {
+		t.Error("nor may another client's heartbeat be reported as THIS one being not-online")
+	}
+	// Bugbot (#515): the LABEL is a claim too. "stale-01" is the handle of the
+	// client the pointer names — not what the fallback found running here — so
+	// presenting it as this machine's environment is a wrong name, and one that
+	// contradicts doctor's namespace-based label for the same state.
+	if m.envName == "stale-01" {
+		t.Errorf("a stale pointer's client handle must not label the environment running here, got %q", m.envName)
+	}
+	if m.envName != "tracebloc" {
+		t.Errorf("want the probe's own name for the release that IS here, got %q", m.envName)
+	}
+
+	// Control: with a fresh pointer the remembered handle is still preferred —
+	// otherwise "don't use the remembered name" could pass by never using it.
+	if fresh := base(false); fresh.envName != "stale-01" {
+		t.Errorf("a non-stale pointer must still prefer the remembered client name, got %q", fresh.envName)
+	}
+}
+
+// …and a beatNotOnline off a stale pointer is equally uninformative: it must not
+// harden into "backend reports not online" for a client it isn't about.
+func TestResolveHomeModel_StalePointerNotOnlineIsNotConfirmed(t *testing.T) {
+	m := resolveHomeModel(context.Background(), homeDeps{
+		budget:           2 * time.Second,
+		invoked:          func() string { return binTB },
+		tbAvailable:      func() bool { return true },
+		hasResources:     func() bool { return true },
+		signIn:           func() (bool, string, string) { return true, "a@b.io", "Lukas" },
+		rememberedClient: func() (bool, string) { return true, "stale-01" },
+		probeBeat:        func(context.Context) heartbeatState { return beatNotOnline },
+		probeEnv: func(context.Context) envProbe {
+			return envProbe{local: localLive, name: "tracebloc", pointerStale: true}
+		},
+	})
+	if m.confirmedNotOnline {
+		t.Error("a stale pointer's heartbeat carries no signal in either direction")
+	}
+}
+
+// …and the ownership gate survives it: the same wrong pointer on a REMOTE
+// cluster stays no-release, so a shared cluster's unrelated client is never
+// greeted as yours (§7.5).
+func TestRealProbeEnv_WrongPointerOnRemoteCluster_StaysGated(t *testing.T) {
+	writeActiveClientConfig(t, "stale-ns", "Stale")
+	o := fallbackRelease("colleague-07")
+	cs := fake.NewClientset(o[0].(*appsv1.Deployment), o[1].(*corev1.Service))
+
+	origLoad, origCS := loadClusterFn, newClientsetFn
+	t.Cleanup(func() { loadClusterFn, newClientsetFn = origLoad, origCS })
+	loadClusterFn = func(o cluster.KubeconfigOptions) (*cluster.ResolvedConfig, error) {
+		ns := o.Namespace
+		if ns == "" {
+			ns = "colleague-07"
+		}
+		return &cluster.ResolvedConfig{
+			Namespace: ns, ServerURL: "https://k8s.corp.example:6443", RestConfig: &rest.Config{},
+		}, nil
+	}
+	newClientsetFn = func(*cluster.ResolvedConfig) (kubernetes.Interface, error) { return cs, nil }
+
+	if ep := realProbeEnv(context.Background()); ep.local != localNoRelease || ep.name != "" {
+		t.Fatalf("=> %+v, want localNoRelease (a shared cluster's client is not yours)", ep)
+	}
+}
+
 func TestIsLocalServerURL(t *testing.T) {
 	local := []string{
 		"https://127.0.0.1:6550",
diff --git a/internal/cli/resources.go b/internal/cli/resources.go
index b2ac85c..c636297 100644
--- a/internal/cli/resources.go
+++ b/internal/cli/resources.go
@@ -92,7 +92,7 @@ func runResourcesShow(ctx context.Context, p *ui.Printer, opts cluster.Kubeconfi
 	// multi-client redirect note self-leads its one leading blank (§380).
 	target, err := resolveClusterTargetFn(ctx, p, opts, binding, false, true)
 	if err != nil {
-		return binding.explain(err)
+		return binding.explain(ctx, err)
 	}
 	return renderResources(ctx, p, target)
 }
diff --git a/internal/cli/resources_set.go b/internal/cli/resources_set.go
index b9f5048..c9f5c27 100644
--- a/internal/cli/resources_set.go
+++ b/internal/cli/resources_set.go
@@ -145,7 +145,7 @@ func runResourcesSet(ctx context.Context, p *ui.Printer, pr prompter, opts clust
 	// and never regresses the #375 double-blank (§380).
 	target, err := resolveClusterTarget(ctx, p, opts, binding, false, true)
 	if err != nil {
-		return binding.explain(err)
+		return binding.explain(ctx, err)
 	}
 	return applyResourcesSet(ctx, p, pr, target, opts, req)
 }
diff --git a/internal/cli/seal.go b/internal/cli/seal.go
index 04ec661..d2dca1f 100644
--- a/internal/cli/seal.go
+++ b/internal/cli/seal.go
@@ -78,7 +78,7 @@ func runSealCheck(ctx context.Context, p *ui.Printer, opts cluster.KubeconfigOpt
 	// multi-client redirect note is the opening line and self-leads its blank.
 	target, err := resolveClusterTargetFn(ctx, p, opts, binding, false, true)
 	if err != nil {
-		return binding.explain(err)
+		return binding.explain(ctx, err)
 	}
 	tt := helm.TestTarget{
 		Release:    target.Release.ReleaseName,
diff --git a/internal/cli/testdata/golden/08-client.golden b/internal/cli/testdata/golden/08-client.golden
index 8a94809..f8ff84e 100644
--- a/internal/cli/testdata/golden/08-client.golden
+++ b/internal/cli/testdata/golden/08-client.golden
@@ -57,6 +57,7 @@ Usage:
   tracebloc client [command]
 
 Available Commands:
+  create      Point this machine at its tracebloc client — adopts the one already on this cluster
   status      Show whether tracebloc can see this machine's client (online)
 
 Flags:
@@ -69,7 +70,15 @@ Global Flags:
 Use "tracebloc client [command] --help" for more information about a command.
 
 $ tracebloc client create --help
-Provision a tracebloc client for this machine (auto-named; no flags required)
+Point this machine at its tracebloc client.
+
+Keyed on the cluster your kubeconfig reaches: if a tracebloc client already runs
+there, this ADOPTS it — no prompt, no new credential, no duplicate — which is how
+you repoint a machine whose active client went stale. On a cluster that runs no
+client yet it provisions a new one, and asks first.
+
+Provisioning a brand-new machine is normally the installer's job — it calls this
+for you, with no flags.
 
 Usage:
   tracebloc client create [flags]
diff --git a/internal/cli/testdata/golden/zz-all-strings.golden b/internal/cli/testdata/golden/zz-all-strings.golden
index ea60b29..84dc4ee 100644
--- a/internal/cli/testdata/golden/zz-all-strings.golden
+++ b/internal/cli/testdata/golden/zz-all-strings.golden
@@ -230,6 +230,7 @@ screen. %s/%d are runtime placeholders.
 "Not ready — part of your secure environment can't start yet."
 "Not ready — part of your secure environment isn't running."
 "Not ready — the training images can't be pulled."
+"Not ready — your active client points at namespace %q, which isn't on this cluster, so data commands will keep failing until you repoint."
 "Not signed in yet."
 "Not signed in — run `%s login`."
 "Not signed in. Run `tracebloc login`."
@@ -244,6 +245,7 @@ screen. %s/%d are runtime placeholders.
 "Pending > %s: %v"
 "Pick this dataset when you set it up."
 "Please name the dataset."
+"Point this machine at the environment above: %s client create  (this cluster already runs a client, so it adopts it — no new credential)"
 "Preparing this host and granting %s container-runtime access — re-running the installer's prepare-host step (needs administrator rights once)."
 "Preparing this host — re-running the installer's prepare-host step (installs the container runtime and prerequisites; needs administrator rights once). Pass a researcher's username to also grant them access: tracebloc prepare-host <username>"
 "Private image pulls will ImagePullBackOff. Reinstall the chart with valid registry credentials."
@@ -357,6 +359,8 @@ screen. %s/%d are runtime placeholders.
 "Wrote client id + namespace to %s (no new credential — the existing one stands)."
 "You don't have permission to %s in this account."
 "Your CPU and memory budget is unchanged — but this machine has no GPU while the cluster still requests one, so I'll clear that stale GPU setting so runs can schedule."
+"Your active client is not on the cluster your kubeconfig reaches, and no client here is confirmed. Check your kubeconfig context, then run: %s doctor"
+"Your active client is not on the cluster your kubeconfig reaches. To point this machine at the client that IS there: %s client create"
 "Your data is registered as a dataset. View it at https://ai.tracebloc.io/metadata"
 "Your dataset records (marked unavailable, not deleted)"
 "Your files are copied securely into your secure environment's storage — set up and cleaned up for you."
@@ -372,6 +376,11 @@ screen. %s/%d are runtime placeholders.
 "a training run needs at least %s — %s is too little."
 "account"
 "active client"
+"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at.\n\nA tracebloc client IS running on this machine, in namespace %q.\n  Point this machine at it:  %s client create\n      (this cluster already runs a client, so it adopts it — no new credential)\n  Or target it just this once:  --namespace %s"
+"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at.\n\nA tracebloc client is running on this cluster, in namespace %q.\n  Target it just this once:  --namespace %s"
+"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at.\n\ntracebloc clients are running on this cluster, in namespaces: %s.\n  Target one just this once:  --namespace %s"
+"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at; run this command there, or override with --namespace/--context"
+"active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at; run this command there, or override with --namespace/--context.\n\nNo tracebloc client is running on this cluster either — if this machine should have one, set one up: %s"
 "annotations"
 "app version"
 "authorized — confirming the token with the backend …"

From f9a25216951b044230912ff8940fc35a63615a37 Mon Sep 17 00:00:00 2001
From: lukasWuttke <54042461+LukasWodka@users.noreply.github.com>
Date: Mon, 17 Aug 2026 16:23:52 +0200
Subject: [PATCH 4/5] fix(auth): a transient poll failure retries; the expiry
 copy names the window (#517) (#521)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(auth): a transient poll failure retries; the expiry copy names the window

cli#517. The device-poll loop's `default:` branch was terminal, so anything
that was not one of the four RFC 8628 sentinels ended the sign-in — a DNS
blip, a backend restart, a proxy 502. Inside a ten-minute human-paced window
that is a long exposure, and under the installer it threw away a run that had
already built a cluster.

The default is inverted: unknown failures retry, and every terminal state is
now enumerated in classifyPollError — the four sentinels, a 426 version floor,
a cancelled context, and any *APIError that is not 5xx / 408 / 429. So a
server's refusal still stops on the first poll; only failures that never
reached a verdict are ridden out. Retries are bounded by maxPollFailures
consecutive failures (reset by any answer), so an unreachable backend reports
itself instead of burning the code's window and then blaming the user.

Also from #517:
  • the expiry message names the window ("sign-in codes are valid for 10
    minutes"), derived from the server's expires_in rather than hardcoded —
    without it a ten-minute timeout reads as an instant failure;
  • "Run `tracebloc login` to start a new one" is suppressed when
    TRACEBLOC_INSTALLER is set. That advice is right for a hand-typed login
    and wrong under the installer, which prints its own next step; the two
    used to contradict each other on screen.
  • a Ctrl-C landing mid-request now exits quietly, like one landing between
    polls, instead of reporting the operator's interrupt as a sign-in failure.

Every message stays a literal argument of errors.New / fmt.Errorf so the copy
catalog's AST harvest can still see it; TestCopyCatalogSeesTheSignInStrings
pins that, because composing copy inside a helper drops it from the catalog
silently.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(release): VERSION 0.10.8 -> 0.10.9

version-bump-gate: v0.10.8 is already released and this PR changes a published
path (internal/*), so the train would otherwise cut the next tag from a stale
file. 0.10.9 is the same pending version cli#518, #519 and #520 bump to — they
all ship under it together, and the identical change merges without conflict.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 internal/cli/auth.go                          | 166 ++++++++-
 internal/cli/auth_test.go                     | 340 ++++++++++++++++++
 .../cli/testdata/golden/zz-all-strings.golden |   8 +-
 3 files changed, 500 insertions(+), 14 deletions(-)

diff --git a/internal/cli/auth.go b/internal/cli/auth.go
index 6982161..c4237eb 100644
--- a/internal/cli/auth.go
+++ b/internal/cli/auth.go
@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
+	"os"
 	"time"
 
 	"github.com/spf13/cobra"
@@ -130,6 +131,128 @@ func runLogin(ctx context.Context, p *ui.Printer, envFlag string) error {
 	return nil
 }
 
+// pollDisposition is what the poll loop does with a failed PollToken call.
+type pollDisposition int
+
+const (
+	// pollStop — the sign-in cannot succeed. Report it and exit.
+	pollStop pollDisposition = iota
+	// pollAgain — an expected non-answer (not approved yet). Poll again unchanged.
+	pollAgain
+	// pollSlower — the server asked us to back off (RFC 8628 §3.5).
+	pollSlower
+	// pollRetry — an infrastructure failure, not a verdict on the sign-in. Poll
+	// again, but count it: a backend that never answers must say so eventually.
+	pollRetry
+)
+
+// maxPollFailures bounds how many CONSECUTIVE pollRetry outcomes the loop rides
+// out before giving up and naming the last one. At the RFC's 5-second floor
+// that is a minute of unbroken failure — long enough to cross a wifi handover,
+// a DNS blip, or a backend restart; short enough that a genuinely unreachable
+// backend reports itself instead of silently burning the code's whole window.
+// The code's own expiry still bounds the loop; the counter only makes the
+// give-up message honest when the network, not the human, is at fault.
+const maxPollFailures = 12
+
+// classifyPollError decides whether a PollToken failure ends the sign-in or is
+// worth another poll inside the code's remaining window (cli#517).
+//
+// The default used to be "stop", which made one DNS hiccup fatal to an
+// installer run that had already built a cluster. The default is now "retry",
+// so every genuinely terminal state is enumerated HERE rather than being the
+// leftover case — a refusal must never become an infinite loop:
+//
+//   - the four RFC 8628 §3.5 sentinels are terminal or not by the spec;
+//   - a 426 means this CLI is below the server's version floor — polling can't
+//     make it newer;
+//   - an *APIError carries a server VERDICT: 5xx / 408 / 429 are the server or a
+//     proxy failing temporarily, every other status is a refusal we must respect;
+//   - a cancelled context is the operator, not a blip;
+//   - everything left never reached a server verdict at all — DNS, refused
+//     connection, TLS, a truncated read, a body we couldn't decode — and is the
+//     class this function exists to keep alive.
+func classifyPollError(err error) pollDisposition {
+	switch {
+	case errors.Is(err, api.ErrAuthorizationPending):
+		return pollAgain
+	case errors.Is(err, api.ErrSlowDown):
+		return pollSlower
+	case errors.Is(err, api.ErrExpiredToken), errors.Is(err, api.ErrAccessDenied):
+		return pollStop
+	case errors.Is(err, context.Canceled):
+		return pollStop
+	}
+	var ue *api.UpgradeRequiredError
+	if errors.As(err, &ue) {
+		return pollStop
+	}
+	var ae *api.APIError
+	if errors.As(err, &ae) {
+		switch {
+		case ae.StatusCode >= 500,
+			ae.StatusCode == http.StatusRequestTimeout,
+			ae.StatusCode == http.StatusTooManyRequests:
+			return pollRetry
+		default:
+			return pollStop
+		}
+	}
+	return pollRetry
+}
+
+// withSignInAdvice appends the command that starts a fresh sign-in — or leaves
+// the error exactly as it is when the installer is driving us (cli#517).
+// "`tracebloc login`" is right when a human typed it and WRONG under the
+// installer, where a bare login leaves the client mint and the Helm install
+// undone; the installer prints its own, correct next step, and two contradicting
+// instructions are worse than one. The installer announces itself with
+// TRACEBLOC_INSTALLER.
+//
+// The advice is appended by wrapping rather than composed into each message, so
+// every sentence stays a literal argument of an errors.New / fmt.Errorf call —
+// which is what keeps this copy visible to the copy catalog's AST harvest.
+func withSignInAdvice(err error) error {
+	if os.Getenv("TRACEBLOC_INSTALLER") != "" {
+		return err
+	}
+	return fmt.Errorf("%w. Run `tracebloc login` to start a new one", err)
+}
+
+// signInWindow renders the code's advertised lifetime as a clause for the
+// expiry copy, or "" when the server didn't say. Named in the message because
+// without it a ten-minute timeout reads as an instant failure to anyone who
+// stepped away — which is exactly how cli#517 was first reported. Derived from
+// expires_in rather than hardcoded, so the sentence cannot outlive a change to
+// the backend's DEVICE_CODE_TTL.
+func signInWindow(expiresIn int) string {
+	if expiresIn <= 0 {
+		return ""
+	}
+	d := time.Duration(expiresIn) * time.Second
+	human := d.Round(time.Second).String()
+	switch {
+	case d == time.Minute:
+		human = "1 minute"
+	case d%time.Minute == 0:
+		human = fmt.Sprintf("%d minutes", int(d/time.Minute))
+	}
+	return fmt.Sprintf(" — sign-in codes are valid for %s", human)
+}
+
+// terminalSignInError renders the user-facing copy for a poll outcome the loop
+// must stop on. An error we have no bespoke copy for is surfaced verbatim: a
+// vague "sign-in failed" would hide the only diagnostic we have.
+func terminalSignInError(err error, window string) error {
+	switch {
+	case errors.Is(err, api.ErrExpiredToken):
+		return withSignInAdvice(fmt.Errorf("the sign-in code expired%s", window))
+	case errors.Is(err, api.ErrAccessDenied):
+		return withSignInAdvice(errors.New("sign-in was denied in the browser"))
+	}
+	return err
+}
+
 // pollForToken runs the RFC 8628 device-token poll loop behind a live wait
 // spinner, returning the issued token or an *exitError. The spinner is cleared
 // on every return path (deferred Stop), so the caller prints the ✔ / error line
@@ -143,13 +266,18 @@ func pollForToken(ctx context.Context, p *ui.Printer, client *api.Client, dc *ap
 	if dc.ExpiresIn > 0 {
 		deadline = time.Now().Add(time.Duration(dc.ExpiresIn) * time.Second)
 	}
+	window := signInWindow(dc.ExpiresIn)
 
 	sp := p.Spinner("Waiting for your browser…", "Ctrl-C to cancel")
 	defer sp.Stop()
 
+	// Consecutive infrastructure failures. Reset by any answer from the server —
+	// a blip mid-way through a long wait must not accumulate toward the cap.
+	var failures int
 	for {
 		if !deadline.IsZero() && time.Now().After(deadline) {
-			return "", &exitError{code: exitFailure, err: errors.New("login timed out — re-run `tracebloc login`")}
+			return "", &exitError{code: exitFailure, err: withSignInAdvice(
+				fmt.Errorf("the sign-in code expired before it was approved%s", window))}
 		}
 		select {
 		case <-ctx.Done():
@@ -158,21 +286,35 @@ func pollForToken(ctx context.Context, p *ui.Printer, client *api.Client, dc *ap
 		}
 
 		tok, err := client.PollToken(ctx, dc.DeviceCode)
-		switch {
-		case err == nil:
+		if err == nil {
 			return tok, nil
-		case errors.Is(err, api.ErrAuthorizationPending):
-			// not approved yet — keep polling
-		case errors.Is(err, api.ErrSlowDown):
+		}
+		// Ctrl-C landing DURING the request surfaces as a cancelled context on the
+		// HTTP call, not on the select above — exit quietly there too, rather than
+		// reporting the operator's own interrupt as a sign-in failure.
+		if ctx.Err() != nil {
+			return "", &exitError{code: exitInterrupted}
+		}
+		switch classifyPollError(err) {
+		case pollAgain:
+			failures = 0 // not approved yet — keep polling
+		case pollSlower:
 			// RFC 8628 §3.5: on slow_down the client MUST increase the poll
 			// interval by 5 seconds for this and all subsequent polls.
+			failures = 0
 			interval += 5
-		case errors.Is(err, api.ErrExpiredToken):
-			return "", &exitError{code: exitFailure, err: errors.New("the sign-in code expired — re-run `tracebloc login`")}
-		case errors.Is(err, api.ErrAccessDenied):
-			return "", &exitError{code: exitFailure, err: errors.New("sign-in was denied in the browser")}
-		default:
-			return "", &exitError{code: exitFailure, err: err}
+		case pollRetry:
+			failures++
+			if failures >= maxPollFailures {
+				// One literal, not a concatenation: the copy catalog's AST harvest
+				// only sees whole string literals, so a "+"-joined message is copy
+				// nothing inventories.
+				return "", &exitError{code: exitFailure, err: fmt.Errorf(
+					"couldn't reach the backend to finish signing in — %d attempts failed in a row (check your network / HTTPS_PROXY): %w",
+					failures, err)}
+			}
+		default: // pollStop
+			return "", &exitError{code: exitFailure, err: terminalSignInError(err, window)}
 		}
 	}
 }
diff --git a/internal/cli/auth_test.go b/internal/cli/auth_test.go
index 6c46a38..ff8e7ed 100644
--- a/internal/cli/auth_test.go
+++ b/internal/cli/auth_test.go
@@ -2,6 +2,10 @@ package cli
 
 import (
 	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -166,6 +170,342 @@ func TestLogin_Denied(t *testing.T) {
 	}
 }
 
+// ── cli#517: which poll failures end the sign-in, and which are worth another try ──
+
+// deviceCodeBody is the /device/code reply the poll tests share: a ten-minute
+// window (so the expiry copy has a duration to name) and the RFC's 5s interval.
+const deviceCodeBody = `{"device_code":"dc","user_code":"X","verification_uri":"https://x/activate","expires_in":600,"interval":5}`
+
+// pollBackend serves /device/code + /userinfo/ and hands every /device/token
+// poll to tokenH, which sees the 1-based poll number. Returns a pointer to the
+// live poll count so a test can assert the loop STOPPED (or kept going).
+func pollBackend(t *testing.T, tokenH func(w http.ResponseWriter, poll int)) *int {
+	t.Helper()
+	polls := 0
+	withTestBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/device/code":
+			_, _ = w.Write([]byte(deviceCodeBody))
+		case "/device/token":
+			polls++
+			tokenH(w, polls)
+		case "/userinfo/":
+			_, _ = w.Write([]byte(`{"email":"ds@tracebloc.io"}`))
+		default:
+			t.Errorf("unexpected request path %s", r.URL.Path)
+		}
+	})
+	return &polls
+}
+
+// TestClassifyPollError_Table pins the retry classification directly, on the
+// production function the loop calls (never a re-implementation of it). The
+// inputs are written down independently of the matcher: each is the error a
+// specific real-world failure produces, not a value read back off the rule.
+func TestClassifyPollError_Table(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		want pollDisposition
+	}{
+		// The RFC 8628 §3.5 sentinels, bare and wrapped — PollToken returns them
+		// bare today, but a future wrapper must not silently reclassify them.
+		{"pending", api.ErrAuthorizationPending, pollAgain},
+		{"pending wrapped", fmt.Errorf("poll: %w", api.ErrAuthorizationPending), pollAgain},
+		{"slow_down", api.ErrSlowDown, pollSlower},
+		{"slow_down wrapped", fmt.Errorf("poll: %w", api.ErrSlowDown), pollSlower},
+		{"expired_token", api.ErrExpiredToken, pollStop},
+		{"expired_token wrapped", fmt.Errorf("poll: %w", api.ErrExpiredToken), pollStop},
+		{"access_denied", api.ErrAccessDenied, pollStop},
+		{"access_denied wrapped", fmt.Errorf("poll: %w", api.ErrAccessDenied), pollStop},
+
+		// A server verdict we must respect: retrying an identical request cannot
+		// change any of these, and looping on one would hang the installer.
+		{"400 unrecognized", &api.APIError{StatusCode: 400, Body: `{"error":"invalid_grant"}`}, pollStop},
+		{"401", &api.APIError{StatusCode: 401}, pollStop},
+		{"403", &api.APIError{StatusCode: 403}, pollStop},
+		{"404 no such endpoint", &api.APIError{StatusCode: 404}, pollStop},
+		{"426 upgrade required", &api.UpgradeRequiredError{MinVersion: "1.2.3"}, pollStop},
+		{"426 wrapped", fmt.Errorf("poll: %w", &api.UpgradeRequiredError{}), pollStop},
+		{"operator cancelled", context.Canceled, pollStop},
+		{"operator cancelled wrapped", fmt.Errorf("POST /device/token: %w", context.Canceled), pollStop},
+
+		// Temporary: the server (or a proxy in front of it) is failing, and the
+		// human at the browser has done nothing wrong.
+		{"500", &api.APIError{StatusCode: 500}, pollRetry},
+		{"502 proxy", &api.APIError{StatusCode: 502}, pollRetry},
+		{"503 deploying", &api.APIError{StatusCode: 503}, pollRetry},
+		{"504 gateway timeout", &api.APIError{StatusCode: 504}, pollRetry},
+		{"408 request timeout", &api.APIError{StatusCode: 408}, pollRetry},
+		{"429 rate limited", &api.APIError{StatusCode: 429}, pollRetry},
+
+		// Never reached a verdict at all — the class cli#517 exists to keep alive.
+		{"dns failure", fmt.Errorf("POST /device/token: %w", &net.OpError{
+			Op: "dial", Net: "tcp", Err: &net.DNSError{Err: "no such host", Name: "api.tracebloc.io"}}), pollRetry},
+		{"connection refused", fmt.Errorf("POST /device/token: %w",
+			&net.OpError{Op: "dial", Net: "tcp", Err: errors.New("connect: connection refused")}), pollRetry},
+		{"http client timeout", fmt.Errorf("POST /device/token: %w", context.DeadlineExceeded), pollRetry},
+		{"undecodable body", errors.New(`device-token success response missing token (got "<html>")`), pollRetry},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := classifyPollError(tc.err); got != tc.want {
+				t.Errorf("classifyPollError(%v) = %v, want %v", tc.err, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestClassifyPollError_CoversPollTokenVocabulary derives the input domain from
+// the PRODUCER instead of restating it: every error code RFC 8628 §3.5 lets the
+// device-token endpoint return is driven through the real api.PollToken, and the
+// error it actually produces is classified. A code the client stops mapping (or
+// starts mapping differently) shows up here as a changed disposition — which a
+// hand-written list of sentinels could not see.
+func TestClassifyPollError_CoversPollTokenVocabulary(t *testing.T) {
+	want := map[string]pollDisposition{
+		"authorization_pending": pollAgain,
+		"slow_down":             pollSlower,
+		"expired_token":         pollStop,
+		"access_denied":         pollStop,
+		// Not in §3.5's happy vocabulary, but §3.5 defers to RFC 6749 §5.2 for
+		// the rest; those are refusals of the request, not transient conditions.
+		"invalid_request": pollStop,
+		"invalid_grant":   pollStop,
+	}
+	for code, wantDisp := range want {
+		t.Run(code, func(t *testing.T) {
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusBadRequest)
+				_, _ = w.Write([]byte(`{"error":"` + code + `"}`))
+			}))
+			t.Cleanup(srv.Close)
+			c := &api.Client{BaseURL: srv.URL, HTTP: srv.Client()}
+			_, err := c.PollToken(context.Background(), "dc")
+			if err == nil {
+				t.Fatalf("PollToken returned no error for %q", code)
+			}
+			if got := classifyPollError(err); got != wantDisp {
+				t.Errorf("%q → %v, want %v (err=%v)", code, got, wantDisp, err)
+			}
+		})
+	}
+}
+
+// TestLogin_TransientFailureRetriesWithinWindow is the headline cli#517 fix: a
+// backend blip mid-poll used to abort the whole sign-in (and with it an
+// installer run that had already built a cluster). It must be ridden out.
+func TestLogin_TransientFailureRetriesWithinWindow(t *testing.T) {
+	polls := pollBackend(t, func(w http.ResponseWriter, poll int) {
+		switch {
+		case poll <= 3: // three 503s in a row — a backend restart
+			w.WriteHeader(http.StatusServiceUnavailable)
+		default:
+			_, _ = w.Write([]byte(`{"token":"cat_ok"}`))
+		}
+	})
+	if _, err := runCmd(t, "login"); err != nil {
+		t.Fatalf("a transient backend failure must not abort sign-in, got: %v", err)
+	}
+	if *polls != 4 {
+		t.Errorf("polls = %d, want 4 (three 503s ridden out, then the token)", *polls)
+	}
+	cfg, _ := config.Load()
+	if cfg.Current().Token != "cat_ok" {
+		t.Errorf("stored token = %q, want cat_ok", cfg.Current().Token)
+	}
+}
+
+// TestLogin_TerminalErrorStopsImmediately is the other half of the same
+// contract: making transient errors retryable must NOT turn a refusal into a
+// loop. A 400 the client can't map to a §3.5 sentinel is a refusal — one poll,
+// then out.
+func TestLogin_TerminalErrorStopsImmediately(t *testing.T) {
+	polls := pollBackend(t, func(w http.ResponseWriter, _ int) {
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = w.Write([]byte(`{"error":"invalid_grant"}`))
+	})
+	_, err := runCmd(t, "login")
+	if err == nil {
+		t.Fatal("a refused device code must fail the sign-in")
+	}
+	if *polls != 1 {
+		t.Errorf("polls = %d, want 1 — a refusal must not be retried", *polls)
+	}
+	if !strings.Contains(err.Error(), "invalid_grant") {
+		t.Errorf("the refusal must be surfaced verbatim, got: %v", err)
+	}
+}
+
+// TestLogin_AccessDeniedStopsImmediately: the user said no in the browser.
+// Polling past that would ignore an explicit refusal.
+func TestLogin_AccessDeniedStopsImmediately(t *testing.T) {
+	polls := pollBackend(t, func(w http.ResponseWriter, _ int) {
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = w.Write([]byte(`{"error":"access_denied"}`))
+	})
+	if _, err := runCmd(t, "login"); err == nil {
+		t.Fatal("a denied sign-in must fail")
+	}
+	if *polls != 1 {
+		t.Errorf("polls = %d, want 1 — an explicit denial must not be retried", *polls)
+	}
+}
+
+// TestLogin_TransientFailuresGiveUpAtTheCap: retrying is bounded. A backend
+// that never answers must report ITSELF as the cause, not burn the code's whole
+// window and then blame the user for being slow.
+func TestLogin_TransientFailuresGiveUpAtTheCap(t *testing.T) {
+	polls := pollBackend(t, func(w http.ResponseWriter, _ int) {
+		w.WriteHeader(http.StatusServiceUnavailable)
+	})
+	_, err := runCmd(t, "login")
+	if err == nil {
+		t.Fatal("an unreachable backend must eventually fail the sign-in")
+	}
+	// Written down independently of the constant: a cap of 1 would satisfy the
+	// equality below while restoring exactly the cli#517 behaviour this fixes —
+	// one failure, no retry. The loop must ride out at least a few.
+	if *polls < 5 {
+		t.Errorf("polls = %d — a transient failure must be retried several times before giving up", *polls)
+	}
+	if *polls != maxPollFailures {
+		t.Errorf("polls = %d, want %d (the consecutive-failure cap)", *polls, maxPollFailures)
+	}
+	if !strings.Contains(err.Error(), "couldn't reach the backend") {
+		t.Errorf("the give-up message must name the network as the cause, got: %v", err)
+	}
+}
+
+// TestLogin_TransientFailureStreakResets: the cap counts CONSECUTIVE failures.
+// A blip every few polls during a long human-paced wait must not accumulate
+// into a give-up — that would re-introduce cli#517 on a flaky link.
+func TestLogin_TransientFailureStreakResets(t *testing.T) {
+	polls := pollBackend(t, func(w http.ResponseWriter, poll int) {
+		switch {
+		case poll >= 3*maxPollFailures:
+			_, _ = w.Write([]byte(`{"token":"cat_ok"}`))
+		case poll%2 == 0: // every other poll fails — never maxPollFailures in a row
+			w.WriteHeader(http.StatusBadGateway)
+		default:
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte(`{"error":"authorization_pending"}`))
+		}
+	})
+	if _, err := runCmd(t, "login"); err != nil {
+		t.Fatalf("an intermittent failure must not exhaust the cap, got: %v", err)
+	}
+	if *polls != 3*maxPollFailures {
+		t.Errorf("polls = %d, want %d", *polls, 3*maxPollFailures)
+	}
+}
+
+// TestLogin_ExpiredNamesTheWindow (cli#517 §4): "the sign-in code expired" with
+// no duration reads as an instant failure to a user who stepped away. The
+// message must name the window the server advertised.
+func TestLogin_ExpiredNamesTheWindow(t *testing.T) {
+	pollBackend(t, func(w http.ResponseWriter, _ int) {
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = w.Write([]byte(`{"error":"expired_token"}`))
+	})
+	_, err := runCmd(t, "login")
+	if err == nil {
+		t.Fatal("an expired code must fail the sign-in")
+	}
+	if !strings.Contains(err.Error(), "10 minutes") {
+		t.Errorf("the expiry message must name the 600s window as 10 minutes, got: %v", err)
+	}
+}
+
+// TestSignInWindow renders expires_in as the clause the copy carries. Derived
+// from the server's value, never hardcoded, so it can't outlive a TTL change.
+func TestSignInWindow(t *testing.T) {
+	cases := []struct {
+		expiresIn int
+		want      string
+	}{
+		{600, " — sign-in codes are valid for 10 minutes"},
+		{60, " — sign-in codes are valid for 1 minute"},
+		{300, " — sign-in codes are valid for 5 minutes"},
+		{90, " — sign-in codes are valid for 1m30s"},
+		{0, ""},  // server didn't say — say nothing rather than guess
+		{-1, ""}, // ditto
+	}
+	for _, tc := range cases {
+		if got := signInWindow(tc.expiresIn); got != tc.want {
+			t.Errorf("signInWindow(%d) = %q, want %q", tc.expiresIn, got, tc.want)
+		}
+	}
+}
+
+// TestCopyCatalogSeesTheSignInStrings guards the guard: the copy catalog
+// harvests string LITERALS passed to errors.New / fmt.Errorf / the Printer, so
+// composing a message inside a helper (and handing the helper a variable) drops
+// it silently out of the catalog — the completeness backstop goes on passing
+// while the copy it exists to inventory is invisible. These sentences must stay
+// literal arguments; assembling them here proves they still are.
+func TestCopyCatalogSeesTheSignInStrings(t *testing.T) {
+	catalog := strings.Join(harvestMessages(t), "\n")
+	for _, want := range []string{
+		"the sign-in code expired%s",
+		"the sign-in code expired before it was approved%s",
+		"sign-in was denied in the browser",
+		"%w. Run `tracebloc login` to start a new one",
+		"— sign-in codes are valid for %s", // the harvest trims leading space
+		"couldn't reach the backend to finish signing in",
+	} {
+		if !strings.Contains(catalog, want) {
+			t.Errorf("copy %q is not reachable by the catalog harvest — keep it a literal argument "+
+				"of errors.New/fmt.Errorf, not a variable built inside a helper", want)
+		}
+	}
+}
+
+// TestSignInAdvice_ContradictsNobody (cli#517 §3): standalone, the CLI names the
+// command that starts a fresh sign-in. Under the installer it must NOT — a bare
+// `tracebloc login` there leaves the client mint and the Helm install undone,
+// and the installer prints its own, correct next step a line later.
+func TestSignInAdvice_ContradictsNobody(t *testing.T) {
+	t.Run("standalone names the command", func(t *testing.T) {
+		t.Setenv("TRACEBLOC_INSTALLER", "")
+		err := terminalSignInError(api.ErrExpiredToken, " — sign-in codes are valid for 10 minutes")
+		if !strings.Contains(err.Error(), "tracebloc login") {
+			t.Errorf("a hand-run login should say how to retry, got: %v", err)
+		}
+	})
+	t.Run("under the installer names nothing", func(t *testing.T) {
+		t.Setenv("TRACEBLOC_INSTALLER", "1")
+		err := terminalSignInError(api.ErrExpiredToken, " — sign-in codes are valid for 10 minutes")
+		if strings.Contains(err.Error(), "tracebloc login") {
+			t.Errorf("under the installer `tracebloc login` is wrong advice, got: %v", err)
+		}
+		if !strings.Contains(err.Error(), "expired") || !strings.Contains(err.Error(), "10 minutes") {
+			t.Errorf("suppressing the advice must not suppress the FACT, got: %v", err)
+		}
+	})
+}
+
+// TestLogin_InstallerContextSuppressesTheCliAdvice pins the same rule through
+// the command, not just the helper — the env var has to reach the message a
+// user actually sees.
+func TestLogin_InstallerContextSuppressesTheCliAdvice(t *testing.T) {
+	pollBackend(t, func(w http.ResponseWriter, _ int) {
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = w.Write([]byte(`{"error":"expired_token"}`))
+	})
+	t.Setenv("TRACEBLOC_INSTALLER", "1")
+	_, err := runCmd(t, "login")
+	if err == nil {
+		t.Fatal("an expired code must fail the sign-in")
+	}
+	if strings.Contains(err.Error(), "tracebloc login") {
+		t.Errorf("under the installer the CLI must not tell the user to re-run login, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "10 minutes") {
+		t.Errorf("the window must still be named under the installer, got: %v", err)
+	}
+}
+
 func TestLogout(t *testing.T) {
 	// logout now revokes server-side (cli#112) — route it at a stub, not prod.
 	var revoked bool
diff --git a/internal/cli/testdata/golden/zz-all-strings.golden b/internal/cli/testdata/golden/zz-all-strings.golden
index 84dc4ee..2116c6e 100644
--- a/internal/cli/testdata/golden/zz-all-strings.golden
+++ b/internal/cli/testdata/golden/zz-all-strings.golden
@@ -21,6 +21,7 @@ screen. %s/%d are runtime placeholders.
 "%d image(s) without an annotation (%s)"
 "%d mask(s) not named <image>_mask.png (%s)"
 "%d mask(s) without an image (%s)"
+"%d minutes"
 "%d of %d"
 "%d pod(s), none crash-looping or stuck Pending"
 "%d pod(s), none restarted ≥%d times"
@@ -63,6 +64,7 @@ screen. %s/%d are runtime placeholders.
 "%s: %w"
 "%s=%s,%s=%s"
 "%v (policy: %v)"
+"%w. Run `tracebloc login` to start a new one"
 "(%d CPU · %d GiB"
 "(+%d more)"
 "(Pod phase: %s)"
@@ -407,6 +409,7 @@ screen. %s/%d are runtime placeholders.
 "constructing kubernetes clientset: %w"
 "context"
 "could not check — cluster API unreachable (see 'Cluster reachable' above)"
+"couldn't reach the backend to finish signing in — %d attempts failed in a row (check your network / HTTPS_PROXY): %w"
 "couldn't read RESOURCE_REQUESTS from jobs-manager — skipping node-fit"
 "couldn't read capacity: %v"
 "couldn't read jobs-manager to resolve image pull secrets — skipping"
@@ -489,7 +492,6 @@ screen. %s/%d are runtime placeholders.
 "loading kubeconfig: %w"
 "locating mysql pod: %w"
 "location"
-"login timed out — re-run `tracebloc login`"
 "love from tracebloc 💚"
 "marshaling submit request: %w"
 "marshaling synthesized spec: %w"
@@ -621,7 +623,8 @@ screen. %s/%d are runtime placeholders.
 "the cluster API server at %s isn't answering — is the cluster running?"
 "the duration/time column name"
 "the label/target column name"
-"the sign-in code expired — re-run `tracebloc login`"
+"the sign-in code expired before it was approved%s"
+"the sign-in code expired%s"
 "the size your images already are; tracebloc checks it, it never resizes"
 "this machine has %s, but you asked for %s."
 "time column"
@@ -654,4 +657,5 @@ screen. %s/%d are runtime placeholders.
 "~%s (requested; server may cap shorter)"
 "· %d GPU"
 "· %d classes"
+"— sign-in codes are valid for %s"
 "— this machine could give a run up to cpu=%d,memory=%dGi ('tracebloc resources set max')"

From 465c8801b756b128e33db06cb088006b4880bb6f Mon Sep 17 00:00:00 2001
From: lukasWuttke <54042461+LukasWodka@users.noreply.github.com>
Date: Mon, 17 Aug 2026 16:48:23 +0200
Subject: [PATCH 5/5] fix(test): the copy catalog skipped every message written
 as a join (104 invisible) (#522)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(test): the copy catalog skipped every message written as a join

harvestMessages type-asserted arguments straight to *ast.BasicLit, so a message
split across source lines —

    fmt.Errorf("unknown backend environment %q — valid values are … "+
        "set CLIENT_ENV or pass --env", env)

— is an *ast.BinaryExpr and was skipped ENTIRELY. Not the second half: the whole
message. This file's own header calls the golden "the completeness backstop",
and it passed forever while a whole syntactic class of copy was invisible to it.

104 previously-unseen messages, 0 removed. They are not marginal — they are the
long validation errors that tell a user how to fix their data: the BOM in an
Excel "CSV UTF-8" export, non-UTF-8 CSVs, masks that don't match the image
resolution, labels.csv rows referencing absent images, symlinks in the dataset
tree. The copy most worth guarding against drift was the copy the guard could
not see.

literalString folds ADD chains of literals (and parenthesised ones), refusing any
join with a non-literal operand. That refusal is the load-bearing half: emitting
the literal fragments of a part-computed message would put a sentence in the
catalog that no user ever sees, and mark it inventoried while the real text
drifts. Absent is honest; half is not.

Proven in BOTH directions on the same mutation — breaking the reported message in
auth.go:

  with the fix     TestCopyCatalog FAILS
  without the fix  TestCopyCatalog passes   <- the guard could not see it

TestLiteralString pins the fold with inputs written down independently of the
matcher, so a typo in one cannot plant itself in the other; reverting the fold
reddens 5 of its cases. TestHarvestMessages_SeesConcatenatedCopy pins the
reported defect itself.

Found while doing cli#517 (#521), where new copy composed inside a helper
vanished from the catalog the same way; that PR worked around it by keeping
every sentence a direct literal argument. This is the underlying scanner gap.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(version): 0.10.8 -> 0.10.9

version-bump-gate fails any PR touching a published path while the current
VERSION names a released tag, and its publish glob is `internal/*` — which
matches internal/cli/copy_catalog_test.go even though a _test.go file ships
nothing. 0.10.9 is being cut regardless (cli#518, #519, #520 and #521 all bump
to it), so this change genuinely rides under that version; the identical one-line
edit merges without conflict.

Preferred over the skip-version-gate override: the label is for a false positive
nobody should have to reason about later, and the honest statement here is that
this is part of 0.10.9.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 internal/cli/copy_catalog_test.go             | 122 +++++++++++++++++-
 .../cli/testdata/golden/zz-all-strings.golden | 103 +++++++++++++++
 2 files changed, 219 insertions(+), 6 deletions(-)

diff --git a/internal/cli/copy_catalog_test.go b/internal/cli/copy_catalog_test.go
index cd6b50c..40405a9 100644
--- a/internal/cli/copy_catalog_test.go
+++ b/internal/cli/copy_catalog_test.go
@@ -532,6 +532,57 @@ func (c *catalogPrompter) Confirm(label string, def bool) (bool, error) {
 	return def, nil
 }
 
+// literalString folds a compile-time-constant string expression to its value.
+//
+// A message written across two source lines —
+//
+//	fmt.Errorf("unknown backend environment %q — valid values are … "+
+//		"set CLIENT_ENV or pass --env", env)
+//
+// — is an *ast.BinaryExpr, not a *ast.BasicLit. The harvest used to type-assert
+// straight to *ast.BasicLit, so it skipped those arguments entirely: not the
+// second half, the WHOLE message. That made this file's own header claim ("the
+// completeness backstop") false for an entire syntactic class of copy, and it
+// passed forever because nothing it could see had gone missing. The env-validation
+// error above was absent from the golden while being plainly user-facing.
+//
+// Only an ALL-literal join folds. An operand that is a variable, a call, or a
+// constant identifier makes the whole expression unfoldable and yields false —
+// deliberately, because emitting the literal half of a part-computed message
+// would put a sentence in the catalog that no user ever sees, and mark it
+// inventoried while the real text drifts. Absent is honest; half is not.
+func literalString(e ast.Expr) (string, bool) {
+	switch n := e.(type) {
+	case *ast.BasicLit:
+		if n.Kind != token.STRING {
+			return "", false
+		}
+		s, err := strconv.Unquote(n.Value)
+		if err != nil {
+			return "", false
+		}
+		return s, true
+	case *ast.ParenExpr:
+		return literalString(n.X)
+	case *ast.BinaryExpr:
+		// ADD only: any other operator on strings is not a concatenation, and
+		// arithmetic on non-strings is filtered by the BasicLit kind check above.
+		if n.Op != token.ADD {
+			return "", false
+		}
+		l, ok := literalString(n.X)
+		if !ok {
+			return "", false
+		}
+		r, ok := literalString(n.Y)
+		if !ok {
+			return "", false
+		}
+		return l + r, true
+	}
+	return "", false
+}
+
 // harvestMessages parses the user-facing packages and returns every string
 // literal that reaches a user: ALL arguments to a Printer method or an error /
 // format constructor (errors.New, fmt.Errorf, fmt.Sprintf), PLUS the string
@@ -593,12 +644,8 @@ func harvestMessages(t *testing.T) []string {
 	seen := map[string]struct{}{}
 	collect := func(prefix string, exprs []ast.Expr) {
 		for _, arg := range exprs {
-			lit, ok := arg.(*ast.BasicLit)
-			if !ok || lit.Kind != token.STRING {
-				continue
-			}
-			s, uerr := strconv.Unquote(lit.Value)
-			if uerr != nil {
+			s, ok := literalString(arg)
+			if !ok {
 				continue
 			}
 			s = strings.TrimSpace(s)
@@ -653,3 +700,66 @@ func harvestMessages(t *testing.T) []string {
 	sort.Strings(out)
 	return out
 }
+
+// TestLiteralString pins the fold itself. The inputs are written down here
+// independently of the implementation — never derived from it — so a typo in the
+// matcher cannot also plant the same typo in its own fixture (the "never test a
+// list against itself" rule).
+func TestLiteralString(t *testing.T) {
+	cases := []struct {
+		name string
+		src  string // an expression
+		want string
+		ok   bool
+	}{
+		{"plain literal", `"hello there"`, "hello there", true},
+		{"raw literal", "`raw string`", "raw string", true},
+		{"two-part join", `"first half " + "second half"`, "first half second half", true},
+		{"three-part join", `"a " + "b " + "c"`, "a b c", true},
+		{"join across quote styles", "`raw ` + \"interpreted\"", "raw interpreted", true},
+		{"parenthesised join", `("a " + "b")`, "a b", true},
+		// The load-bearing refusals: a part-computed message must not be emitted
+		// half-harvested, or the catalog would claim to inventory a sentence no
+		// user ever sees.
+		{"literal + identifier", `"prefix " + name`, "", false},
+		{"identifier + literal", `name + " suffix"`, "", false},
+		{"literal + call", `"prefix " + fmt.Sprint(x)`, "", false},
+		{"nested unfoldable operand", `"a " + ("b " + c)`, "", false},
+		{"non-ADD operator", `"a" == "b"`, "", false},
+		{"numeric literal", `42`, "", false},
+		{"numeric addition", `1 + 2`, "", false},
+		{"bare identifier", `msg`, "", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			expr, err := parser.ParseExpr(tc.src)
+			if err != nil {
+				t.Fatalf("ParseExpr(%q): %v", tc.src, err)
+			}
+			got, ok := literalString(expr)
+			if ok != tc.ok {
+				t.Fatalf("literalString(%q) ok = %v, want %v (got %q)", tc.src, ok, tc.ok, got)
+			}
+			if got != tc.want {
+				t.Errorf("literalString(%q) = %q, want %q", tc.src, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestHarvestMessages_SeesConcatenatedCopy is the regression pin for the reported
+// defect: a real, plainly user-facing error written as a two-line join was absent
+// from the catalog entirely. Reverting the fold to a bare *ast.BasicLit assertion
+// reddens this.
+func TestHarvestMessages_SeesConcatenatedCopy(t *testing.T) {
+	msgs := harvestMessages(t)
+	// runLogin's env validation (auth.go) — split across source lines, so it was
+	// invisible to an operand-blind scan.
+	const needle = "unknown backend environment"
+	for _, m := range msgs {
+		if strings.Contains(m, needle) {
+			return
+		}
+	}
+	t.Fatalf("harvest is missing the concatenated message %q — the fold is not applied", needle)
+}
diff --git a/internal/cli/testdata/golden/zz-all-strings.golden b/internal/cli/testdata/golden/zz-all-strings.golden
index 2116c6e..c5feb3b 100644
--- a/internal/cli/testdata/golden/zz-all-strings.golden
+++ b/internal/cli/testdata/golden/zz-all-strings.golden
@@ -17,22 +17,36 @@ screen. %s/%d are runtime placeholders.
 "%d files"
 "%d files (%s)"
 "%d image pull secret(s) present and well-formed"
+"%d image(s) are smaller than the %dx%d minimum you set with --min-size: %s. Provide larger images, or lower the floor with --min-size, then re-run."
+"%d image(s) can't be ingested: %s. The cluster rejects these after the upload — fix or remove them and re-run."
+"%d image(s) don't match the %dx%d resolution: %s. The cluster validates the size, it does not resize — make them uniform, or pass --target-size to match your data."
 "%d image(s) without a mask (%s)"
 "%d image(s) without an annotation (%s)"
+"%d labels.csv row(s) reference images that aren't in images/: %s. Those records would fail after the upload — fix the rows or add the files, then re-run."
+"%d mask(s) are smaller than the %dx%d minimum you set with --min-size: %s. Provide larger masks, or lower the floor with --min-size, then re-run."
+"%d mask(s) don't match the %dx%d resolution the images use: %s. Semantic-segmentation masks are pixel-wise label maps, so each mask must be exactly the image size — the cluster validates this after the upload. Resize the masks to match and re-run."
+"%d mask(s) in masks/ can't be ingested: %s. The cluster reads every mask as a PNG and rejects these after the upload — fix or remove them and re-run."
 "%d mask(s) not named <image>_mask.png (%s)"
 "%d mask(s) without an image (%s)"
 "%d minutes"
 "%d of %d"
 "%d pod(s), none crash-looping or stuck Pending"
 "%d pod(s), none restarted ≥%d times"
+"%d row(s) in %s have an empty %q (e.g. %s). Every row must name its mask file — an empty value makes the training client derive a garbage filename and fail. Fill in %q or drop those rows, then re-run."
+"%d sequence(s) grouped by %q change their %q value mid-sequence (first offending sequences start at data row(s) %v%s). Time-series classification assigns ONE label per sequence: every row of a sequence must repeat the same label value. The cluster rejects this after the upload — fix the labels and re-run."
+"%d sequence(s) grouped by %q have out-of-order %q values (first offending data row(s) %v%s). Timestep rows must be sorted ascending by %q within each sequence — sort each sequence and re-run. Interleaving different sequences is fine; ordering is only checked within a sequence. The cluster rejects this after the upload."
 "%d system table(s) hidden — show with --all."
 "%dd ago"
 "%dh ago"
 "%dm ago"
 "%q exists but is not a directory"
 "%q is a directory, not a file"
+"%q is a directory, not a file. labels.csv must be the CSV file holding the filename,label rows."
+"%q is a symbolic link, which v0.1 does not allow in the dataset layout (security: a symlink could escape the dataset tree or bypass size caps). Materialize the link target (e.g. `cp -L`) and re-run, or wait for v0.2's cloud-source story if the data lives elsewhere."
+"%q is not a .csv file. Tabular / time-series data is a single CSV — pass the .csv file itself, or a directory containing exactly one .csv."
 "%q is not a directory; pass the directory containing labels.csv + images/"
 "%q is not a directory; pass the directory containing labels.csv + the text files"
+"%q won't work — no hyphens or spaces (use _); use letters, digits, and underscores, starting with a letter or underscore (e.g. churn_train)"
 "%s   state=%s   namespace=%s   location=%s"
 "%s %q must be WxH (e.g. 512x512)"
 "%s %q: height is not an integer: %w"
@@ -42,12 +56,16 @@ screen. %s/%d are runtime placeholders.
 "%s (%dx%d)"
 "%s (unreadable: %v)"
 "%s Bound, mounted at %s"
+"%s contains a NUL byte — the file is corrupt or not really a CSV. The cluster rejects it after the upload; re-export the file and re-run."
 "%s has a header but no data rows (0 ingestable records). Add at least one data row and re-run."
+"%s has duplicate column name(s): %s. Each column must be unique — the cluster rejects duplicates, and the schema would map onto the wrong column. Rename them and re-run."
 "%s is empty — add a header and at least one data row, then re-run"
 "%s is empty — no header row"
+"%s isn't valid UTF-8 (likely a Latin-1/Windows-1252 export). The cluster rejects non-UTF-8 CSVs after the upload — re-save it as UTF-8 and re-run."
 "%s of %s GiB"
 "%s of %s cores"
 "%s requires CLIENT_WRITE permission"
+"%s starts with a UTF-8 byte-order mark (Excel's \"CSV UTF-8\" export adds it), which the cluster's schema check can't read — the ingestion would fail after uploading everything. Re-save it without the mark (in Excel choose plain \"CSV\"; or: tail -c +4 %s > fixed.csv) and re-run."
 "%s still present after removal"
 "%s unreachable: %v"
 "%s · %d"
@@ -64,6 +82,9 @@ screen. %s/%d are runtime placeholders.
 "%s: %w"
 "%s=%s,%s=%s"
 "%v (policy: %v)"
+"%w in namespace %q, but tracebloc clients are running in: %s. Pass --namespace to pick one."
+"%w in namespace %q. If your client runs in another namespace, pass --namespace; if this cluster has no tracebloc client yet, run the installer: %s. Diagnose with `tracebloc doctor`."
+"%w on the cluster your kubeconfig points at — if this machine should have one, run the installer to provision it; otherwise point at the right cluster with --context/--namespace"
 "%w. Run `tracebloc login` to start a new one"
 "(%d CPU · %d GiB"
 "(+%d more)"
@@ -79,11 +100,14 @@ screen. %s/%d are runtime placeholders.
 "-%02d"
 "--%s has no effect without --seal"
 "--label-column doesn't apply to task %q — it trains on the text itself, with no label column"
+"--label-policy is regression-class tasks only (tabular_regression, time_series_forecasting, time_to_event_prediction); it doesn't apply to task %q"
 "--min-size is image tasks only; it doesn't apply to task %q"
 "--number-of-keypoints is keypoint_detection only; it doesn't apply to task %q"
+"--number-of-keypoints must be a positive integer (got %d); it's the number of keypoints per sample (e.g. 17 for COCO pose)"
 "--overwrite can't be combined with --idempotency-key: a reused key makes the cluster replay the previous run instead of ingesting the new data — after --overwrite's removal that would report success while loading nothing. Drop one of the two (a fresh per-run key is the default)."
 "--schema is empty; expected col:TYPE,col:TYPE,..."
 "--schema is tabular/time-series tasks only; it doesn't apply to task %q"
+"--schema names column(s) that aren't in %s: %s. The cluster rejects this after the upload — fix the schema or the CSV header, then re-run."
 "--target-size is image tasks only; it doesn't apply to task %q"
 "--time-column is time_to_event_prediction only; it doesn't apply to task %q"
 "--timeout has no effect without --wait or --seal"
@@ -131,14 +155,18 @@ screen. %s/%d are runtime placeholders.
 "Copying %s"
 "Correlation id: %s"
 "Couldn't check for active training runs (%v) — continuing; the confirmation below still guards you."
+"Couldn't clear the stored active-client pointer (%v) — the on-disk config still names the revoked client; run `tracebloc logout` or remove it by hand."
 "Couldn't connect to your secure environment — check your kubeconfig/context."
+"Couldn't determine this client's namespace — skipped the Helm uninstall. If a release is still installed, re-run with --namespace <ns>."
 "Couldn't locate the CLI binary to remove it (%v) — delete it by hand."
 "Couldn't read the target cluster's identity — provisioning without a cluster anchor, so re-running won't be idempotent. Point --kubeconfig/--context at the reachable cluster to enable that."
 "Couldn't read your tracebloc config — run `%s login` to recreate it."
 "Couldn't reclaim the temporary copy (%v). It's harmless — the next re-ingest of %q or a `tracebloc data delete %s` will clear it."
+"Couldn't remove local data (%v) — cleared the active-client pointer; remove the data by hand: rm -rf %s"
 "Couldn't remove the CLI (%v) — remove it by hand: rm -f %s"
 "Couldn't remove the CLI (%v). It looks Homebrew-managed — finish with: brew uninstall tracebloc"
 "Couldn't remove the `tb` alias (%v) — remove it by hand: rm -f %s"
+"Couldn't revoke the credential server-side (%v) — continuing with local teardown. The credential may still be live on tracebloc; revoke it from the dashboard if needed."
 "Couldn't save the active-client pointer (%v) — re-run `tracebloc client create` (it adopts this cluster's client) to set it."
 "Couldn't save the active-client pointer (%v) — re-run `tracebloc client create` (it adopts this cluster's client)."
 "Couldn't verify your session with the backend (%v)."
@@ -175,6 +203,7 @@ screen. %s/%d are runtime placeholders.
 "Fix the failing checks above, then re-run `tracebloc client status --seal` to confirm the seal."
 "Follow it later with:  kubectl logs -f -n %s job/%s"
 "For help: https://docs.tracebloc.io/create-use-case/prepare-dataset"
+"Found a %q entry, but image and text data need a real lowercase folder like %q (not a symlink or a file). If that's your data folder, fix it and ingest again."
 "Found labels.csv and a %s folder — this looks like text data."
 "Free some up on this machine, or %s."
 "Free some up, give Docker more memory (WSL2 backend: `[wsl2] memory=…` in %%UserProfile%%\\.wslconfig then `wsl --shutdown`; Hyper-V backend: Docker Desktop → Settings → Resources → Advanced), or %s."
@@ -238,10 +267,13 @@ screen. %s/%d are runtime placeholders.
 "Not signed in. Run `tracebloc login`."
 "Not yet in the CLI:"
 "Note: %d file(s) in images/ have no labels.csv row and won't be part of the dataset: %s"
+"Note: %d sequence(s) grouped by %q — the platform counts this dataset in sequences, not rows"
 "Offboarded %q. This machine is no longer connected to tracebloc."
+"Offboarded %q: the machine credential is revoked, so it can no longer connect to tracebloc — but some cleanup above didn't complete. Finish the flagged steps by hand."
 "Only tracebloc's small jobs-manager restarts — running training isn't interrupted."
 "Open"
 "POST %s%s: %w"
+"PVC %s/%s is in phase %q, not Bound. The shared volume hasn't been provisioned — check that the cluster has a usable StorageClass (kubectl get sc) and that the PVC's storageClassName matches."
 "PVC is %v, not ReadWriteMany — the stage Pod will co-locate with the existing mounter"
 "Path:"
 "Pending > %s: %v"
@@ -280,6 +312,7 @@ screen. %s/%d are runtime placeholders.
 "Revoked this machine's credential — your secure environment %q stays on tracebloc as a record."
 "Run '%s --help' for the available commands."
 "SELECT '%s',%s,COUNT(*),%s,%s FROM `%s`.`%s`"
+"SELECT r.table_name, COALESCE(r.task,'') FROM `%s`.`%s` r JOIN (SELECT table_name, MAX(started_at) ms FROM `%s`.`%s` WHERE task IS NOT NULL GROUP BY table_name) m ON r.table_name = m.table_name AND r.started_at = m.ms WHERE r.task IS NOT NULL"
 "SELECT table_name FROM information_schema.tables WHERE table_schema='%s' ORDER BY table_name"
 "Seal check — secure environment %q"
 "Seal unknown — this chart ships no conformance checks, so this environment's protections can't be verified. Not claiming sealed."
@@ -315,6 +348,7 @@ screen. %s/%d are runtime placeholders.
 "Text      a folder with labels.csv + texts/     e.g. %s"
 "The column holding the duration / time-to-event.  e.g. time, tenure_days"
 "The dataset's catalog metadata is kept as a record on tracebloc, marked unavailable — never removed."
+"The ingestion hasn't started yet (usually a slow image pull or a busy cluster). It's queued to run once the cluster can schedule it — check on it with the command below."
 "The name you provided was only control characters — auto-naming this client instead."
 "The number of landmark points each sample is annotated with — dataset-specific.  e.g. 17 for COCO human pose"
 "The size your images already are, as WxH — tracebloc checks every image matches and never resizes. Press Enter to read it from your first image.  e.g. 224x224"
@@ -334,6 +368,8 @@ screen. %s/%d are runtime placeholders.
 "Time column:"
 "To train or benchmark models on it, create a use case at https://ai.tracebloc.io/my-use-cases"
 "To update tracebloc on Windows, run this in a new PowerShell window:"
+"Tore down %q on this machine, but some cleanup above didn't complete and the server-side revoke didn't complete — the credential may still be live on tracebloc (revoke it from the dashboard). Finish the flagged steps by hand."
+"Tore down %q on this machine. The server-side revoke didn't complete, so the credential may still be live on tracebloc — revoke it from the dashboard if needed (the orphan reaper sweeps it otherwise)."
 "Training results can't reach tracebloc — experiments will stall."
 "Try again shortly; if it persists, email support@tracebloc.io with `%s doctor --diagnose`."
 "Type %q to offboard this machine"
@@ -346,6 +382,7 @@ screen. %s/%d are runtime placeholders.
 "VARCHAR(%d)"
 "Validate and load"
 "Verify the requests-proxy is wired: kubectl set env deploy/<release>-jobs-manager --list | grep PROXY"
+"WARNING: %d orphan stage Pod%s detected in this namespace — likely leftover from a previously crashed `data ingest`:"
 "Waiting for the ingestion to start (scheduling + pulling the image)"
 "Waiting for tracebloc to confirm…"
 "Waiting for your browser…"
@@ -371,6 +408,7 @@ screen. %s/%d are runtime placeholders.
 "Your secure environment is equipped with:"
 "Your session expired — run `%s login`."
 "Your use cases and the models trained here"
+"`tracebloc ingest` doesn't stage datasets — did you mean:\n    tracebloc data ingest %s"
 "a Ready node can schedule a training job (%s)"
 "a dataset path is required"
 "a tracebloc client is already running on this cluster, but listing your account to verify ownership failed (%w) — re-run once tracebloc is reachable, or resolve manually"
@@ -383,7 +421,9 @@ screen. %s/%d are runtime placeholders.
 "active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at.\n\ntracebloc clients are running on this cluster, in namespaces: %s.\n  Target one just this once:  --namespace %s"
 "active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at; run this command there, or override with --namespace/--context"
 "active client %q runs on another machine — namespace %q isn't on the cluster your kubeconfig points at; run this command there, or override with --namespace/--context.\n\nNo tracebloc client is running on this cluster either — if this machine should have one, set one up: %s"
+"active client %s isn't in your account — run `tracebloc client create` (or re-run the installer) to provision this machine"
 "annotations"
+"another tracebloc client (%s) in your account is already live on this cluster — offboard it first with `tracebloc delete`, or provision on a separate machine (cluster_in_use)"
 "app version"
 "authorized — confirming the token with the backend …"
 "auto-detect"
@@ -395,6 +435,7 @@ screen. %s/%d are runtime placeholders.
 "building rest config from kubeconfig: %w"
 "building submit request: %w"
 "building tar archive: %w"
+"can't confirm %q exists on this client — refusing to delete without confirming the target first: %w"
 "can't read %q: %w"
 "cancelled by user"
 "chart version"
@@ -403,16 +444,21 @@ screen. %s/%d are runtime placeholders.
 "client id"
 "closing tar writer: %w"
 "cluster"
+"column %q isn't all %s: %d value(s) don't match its declared type (e.g. %s). The cluster's data-type check rejects these after the table is created — fix the values, or correct the column's type with --schema, then re-run."
 "columns"
 "command"
 "connected: %s — %s"
 "constructing kubernetes clientset: %w"
 "context"
 "could not check — cluster API unreachable (see 'Cluster reachable' above)"
+"couldn't check whether a tracebloc client is already running on this cluster (%w) — provisioning now could mint a duplicate that never deploys and locks the cluster to it. Re-run (if this was transient); if it persists, ensure your kubeconfig/context can list deployments and secrets across namespaces. Diagnose with `tracebloc doctor`"
+"couldn't determine the installed client chart version (the release is missing its helm.sh/chart version label), so the upgrade can't be pinned to it. Refusing to change resources with an unpinned upgrade — it would pull the latest chart and could silently change your client. Re-run the tracebloc installer to repair the release, then try again"
+"couldn't reach the backend to choose a unique client name (%v) — retry, or pass --name explicitly"
 "couldn't reach the backend to finish signing in — %d attempts failed in a row (check your network / HTTPS_PROXY): %w"
 "couldn't read RESOURCE_REQUESTS from jobs-manager — skipping node-fit"
 "couldn't read capacity: %v"
 "couldn't read jobs-manager to resolve image pull secrets — skipping"
+"couldn't read the account's client list to tell whether this cluster is new or already registered (%v) — retry when the backend is reachable (a re-run adopts an existing client), or pass --yes/--credential-file to provision now"
 "couldn't read the chart's conformance checks: %w"
 "couldn't read this machine's capacity: %w"
 "cpu=%s, memory=%s"
@@ -428,6 +474,10 @@ screen. %s/%d are runtime placeholders.
 "data CSV"
 "data row %d"
 "dataset exceeded v0.1 total cap of %s after streaming %s (reached %s)"
+"dataset exceeded v0.1 total cap of %s after streaming %s (reached %s; file growth between pre-flight and stream)"
+"dataset exceeded v0.1 total cap of %s during stream (labels.csv alone is %s; pre-flight likely raced with a file growing on disk)"
+"dataset is %s, exceeds v0.1 cap of %s. For larger datasets, the cloud-source path (S3/GCS/HTTPS) is on the v0.2 roadmap — see tracebloc/client#147 non-goals. Workaround for v0.1: split the push into multiple smaller tables, or stage directly via the existing helm flow."
+"dataset is %s, exceeds v0.1 cap of %s. For larger datasets, the cloud-source path is on the v0.2 roadmap (tracebloc/client#147)."
 "dataset name is required (set --name)"
 "dataset name is required — pass it as an argument: tracebloc data delete <dataset>"
 "decoding image header %q: %w"
@@ -443,10 +493,15 @@ screen. %s/%d are runtime placeholders.
 "exactly %d"
 "exec stream against %s/%s: %w"
 "exit %d"
+"expected %s %s-separated fields (%s), found %d. Separate each field with exactly one %s"
+"expected a single %s record but the file spans multiple lines. Put one %s per .txt"
 "expires"
 "expires in"
 "field %d is empty — every field (%s) must be non-empty"
+"file %q is %s, exceeds v0.1 single-file cap of %s. For larger files, see tracebloc/client#147's v0.2 cloud-source story."
 "file failures"
+"found %d .csv files in %q (%s); the tabular layout expects exactly one. Put the dataset CSV in its own directory and re-run."
+"found %d tracebloc clients in namespace %q (%s); this CLI doesn't yet support disambiguating between multiple. Pass --namespace to target a namespace with exactly one client."
 "full log: %s"
 "generating Pod-name random suffix: %w"
 "generating idempotency key: %w"
@@ -458,6 +513,8 @@ screen. %s/%d are runtime placeholders.
 "http://localhost:%d"
 "image pull secret %q not found"
 "images"
+"images/ and annotations/ don't pair up: %s. Every image needs a same-named .xml annotation (and vice versa) — the cluster rejects mismatches after the upload."
+"images/ and masks/ don't pair up: %s. Every image needs a same-named \"<image>_mask.png\" in masks/ (and vice versa) — the cluster rejects mismatches after the upload."
 "infer from CSV"
 "inferring schema from CSV: %w"
 "ingested %s of %s records (%.1f%%)"
@@ -476,12 +533,17 @@ screen. %s/%d are runtime placeholders.
 "jobs-manager %s returned HTTP %d: %s"
 "jobs-manager has no literal REQUESTS_PROXY_URL (chart too old, or it's set via a configMap/secret ref)"
 "jobs-manager: %s"
+"keypoint_detection requires --number-of-keypoints (e.g. --number-of-keypoints 17); it's dataset-specific and has no default"
 "keypoints"
 "kube-system namespace has no UID"
 "kubectl set env deploy/<release>-jobs-manager --list | grep RESOURCE_REQUESTS"
 "label column"
+"label column %q isn't in %s's header (columns: %s). Pass --label-column with one of the existing columns, or add a %q column to the CSV."
 "label policy"
 "labels.csv"
+"labels.csv column %q must be lowercase \"filename\": the cluster reads each image's file with a case-sensitive record.get(\"filename\") at transfer, so %q would upload, then fail with \"No filename found in record\". Rename it to \"filename\" and re-run."
+"labels.csv has no \"filename\" column (columns: %s) — image tasks match each row to its file by that column, and the cluster drops every row without it (the ingest uploads, then fails with \"No filename found in record\"). Rename your file column to \"filename\" and re-run."
+"labels.csv has no \"filename\" column (columns: %s) — the ingestor matches each row to its text file by that column and rejects a manifest without it. Add a filename column and re-run."
 "letters, digits, and underscores — no hyphens or spaces, use _; start with a letter or underscore  e.g. churn_train"
 "listing Pods for service %s/%s: %w"
 "listing chart-managed deployments in namespace %s: %w"
@@ -490,6 +552,7 @@ screen. %s/%d are runtime placeholders.
 "listing stage Pods in %s: %w"
 "loading embedded schema: %w"
 "loading kubeconfig: %w"
+"local dataset path is required — pass it as an argument, or run on a terminal without --no-input for guided prompts"
 "locating mysql pod: %w"
 "location"
 "love from tracebloc 💚"
@@ -499,6 +562,9 @@ screen. %s/%d are runtime placeholders.
 "min size"
 "minting token for ServiceAccount %s/%s via TokenRequest: %w"
 "missing %s/ subdirectory in %q"
+"missing images/ subdirectory in %q. The CLI expects <dir>/labels.csv + <dir>/images/*.{jpg,jpeg,png}."
+"missing labels.csv in %q. Text categories expect <dir>/labels.csv + <dir>/%s/."
+"missing labels.csv in %q. The CLI expects <dir>/labels.csv + <dir>/images/ for image_classification; see https://docs.tracebloc.io for the dataset layout."
 "must be a positive integer"
 "must be between %d and %d"
 "mysql -uroot -p\"$MYSQL_ROOT_PASSWORD\" -N -e \"%s\""
@@ -507,18 +573,28 @@ screen. %s/%d are runtime placeholders.
 "name"
 "namespace"
 "never (static-secret fallback)"
+"no .csv file found in %q. Tabular / time-series categories expect a single CSV holding the dataset (one column per feature, plus the label column)."
+"no .png mask files found in %q. semantic_segmentation expects <dir>/masks/*.png (one PNG mask per image, named <image>_mask.png)."
+"no .txt files found in %q. Text categories expect <dir>/%s/*.txt."
+"no .xml annotation files found in %q. object_detection expects <dir>/annotations/*.xml (Pascal VOC)."
 "no CLI-supported tasks for %s data yet"
+"no PersistentVolumeClaim named %q found in namespace %q. The chart's _helpers.tpl pins this name; if your install renamed it out-of-band, the CLI doesn't yet support that (read-name-from-jobs-manager is a v0.2 follow-up). Verify with: kubectl get pvc -n %s"
 "no Ready node can fit a training job (needs %s)"
 "no Ready node on this machine to size a training run against"
+"no Running Pod backing service %s/%s (found %d Pod(s); check `kubectl get pods -n %s -l %s`)"
 "no Running pod with name containing %q in namespace %q"
+"no Secret of type kubernetes.io/service-account-token bound to ServiceAccount %s found in namespace %s"
 "no active client on this machine — nothing to offboard"
 "no active client on this machine — run `tracebloc client create` (or re-run the installer) first"
 "no dataset named %q on this client%s"
+"no image files found in %q. Expected .jpg, .jpeg, or .png; got %d non-image entries."
 "no image files to detect a type from"
 "no image pull secret in use (public/digest-pinned images)"
 "no single Ready node satisfies cpu+memory AND %s — GPU jobs rely on the CPU fallback (needs %s)"
 "no such file or directory: %q — check the path to your dataset"
 "no tracebloc client found"
+"no usable image files in %q — found %s, but the ingestor accepts only .jpg, .jpeg, or .png. Convert the images and re-run."
+"no usable ingestor token. TokenRequest failed: %v. Fallback to static secret also failed: %w. Remediation: either grant your user the `create` verb on `serviceaccounts/token` (RBAC), or have an admin create a long-lived Secret of type kubernetes.io/service-account-token that references the %s ServiceAccount in namespace %s."
 "none detected"
 "not signed in — run `tracebloc login` first"
 "outcome:   early exit before the cluster was probed"
@@ -536,6 +612,8 @@ screen. %s/%d are runtime placeholders.
 "port-forward to %s/%s failed during startup: %w"
 "prepare-host didn't complete (%w). You can run the installer directly:\n    %s"
 "prepare-host readies a Linux server or HPC login node so a non-admin user can install tracebloc without root — it doesn't apply to Windows. Run it as an administrator on the Unix host the researcher will use."
+"push.FinalDestPrefix: unsafe table name %q — caller must ValidateTableName before constructing a PVC path"
+"push.StagedPrefix: unsafe table name %q — caller must ValidateTableName before constructing a PVC path"
 "pvc path"
 "querying datasets: %w%s"
 "reading %q: %w"
@@ -560,6 +638,7 @@ screen. %s/%d are runtime placeholders.
 "refusing to change the ceiling without confirmation: pass --yes, or run on a terminal"
 "refusing to delete without confirmation: pass --yes or run on a terminal"
 "refusing to offboard without confirmation: pass --yes, or run on a terminal to type the client name"
+"refusing to provision non-interactively without confirmation — pass --yes to confirm, and --credential-file to write the credential to a file instead of stdout"
 "refusing to stream symbolic link %q (defense-in-depth; should have been rejected by Discover)"
 "release"
 "release %q, chart %s, appVersion %s (namespace %s)"
@@ -567,6 +646,7 @@ screen. %s/%d are runtime placeholders.
 "removed — runs will use CPU only"
 "removing PVC paths: %w%s"
 "removing staged copy %s: %w%s"
+"replacing table %q failed partway — its removal may be incomplete, and a plain re-run would hit the leftovers after uploading everything. Run `tracebloc data delete %s` first, then re-run this ingest. Nothing new was staged. (%w)"
 "requests-proxy deployment not found"
 "requests-proxy is running, but egress to Service Bus is not actively verified — readiness only confirms the relay started, not that it can reach Service Bus"
 "requests-proxy not ready (%d/%d replicas)"
@@ -582,13 +662,17 @@ screen. %s/%d are runtime placeholders.
 "scanning the cluster for tracebloc clients: %w"
 "schema"
 "schema entry %q must be col:TYPE (e.g. age:INT,price:FLOAT)"
+"schema type %q for column %q isn't a supported SQL type — the ingestor would reject it in-cluster. Supported types: %s (with optional length/precision, e.g. VARCHAR(255), DECIMAL(10,2))"
 "secret %q has an empty or malformed %s"
 "secret %q is type %q, not %s"
 "see why: kubectl logs -n %s %s"
+"semantic_segmentation needs a %q column in %s (columns: %s) linking each image to its mask file. Add it — the training client reads it to locate each mask."
+"semantic_segmentation needs a %q column in %s, but found %q (wrong case). Rename it to exactly %q — the training client reads that column to locate each mask."
 "sent to API"
 "server"
 "service %s/%s has no selector — can't resolve to a Pod for port-forwarding"
 "session:   %s"
+"set -e\nrm -rf %q\nmkdir -p %q\n/bin/tar -xf - -C %q\nif [ -e %q ]; then mv %q %q; fi\nif ! mv %q %q; then\n  if [ -e %q ]; then mv %q %q; fi\n  exit 1\nfi\nrm -rf %q\nfind %q -maxdepth 1 \\( -name %q -o -name %q \\) -mmin +60 -exec rm -rf {} + 2>/dev/null || true"
 "setting up jobs-manager port-forward: %w"
 "sha256[:8]"
 "shared PVC"
@@ -614,20 +698,35 @@ screen. %s/%d are runtime placeholders.
 "submit response missing job_name (got body %q)"
 "submit response missing namespace (got body %q)"
 "synthesized spec failed schema validation; check the flag values above"
+"table %q already exists in this secure environment. Re-ingesting the same table doesn't merge or replace — the run would fail after uploading everything. Re-run with --overwrite to replace it, or pick a different --name. (`tracebloc data delete %s` also removes it.)"
+"table name is %d characters; the max is %d (matches both the MySQL identifier limit and the Kubernetes label-value limit, which the stage Pod's tracebloc.io/table label is bound by). Use a shorter name."
 "tabular = a CSV table; image = labels.csv + images/; text = labels.csv + texts/"
 "task"
 "task %q isn't a recognized task. Supported tasks: %s."
 "task %q isn't supported by the CLI yet%s. Supported tasks: %s."
 "teardown failed: %w"
+"teardown incomplete — the table %s.%s was dropped, but removing its files failed: %w; re-run `tracebloc data delete %s`, or delete the leftover staging dirs on the node"
+"text category %q has no primary_subdir in the vendored layout contract — the Go registry has drifted from layout.v1.json; re-run scripts/sync-schema.sh"
+"that doesn't fit. This machine has %s · %s, and tracebloc keeps about %s and %s for itself, so one run can use at most %d cores and %d GiB. Try --cores %d --memory %d."
 "the client running in this namespace is anchored to a different cluster (%s) than --kubeconfig/--context points at (%s) — check you're targeting the right cluster"
 "the cluster API server at %s isn't answering — is the cluster running?"
 "the duration/time column name"
+"the label column %q has %d distinct value(s) — a classification dataset needs at least 2 classes. The cluster rejects this after the upload; check the labels and re-run."
 "the label/target column name"
+"the sequence column %q has %d empty/null value(s) (first at data row %d). Every timestep row must carry the id of the sequence it belongs to — the cluster rejects this after the upload; fill in the ids and re-run."
 "the sign-in code expired before it was approved%s"
 "the sign-in code expired%s"
 "the size your images already are; tracebloc checks it, it never resizes"
+"the time column %q has %d missing/invalid value(s) (first at data row(s) %v%s). Every timestep row needs a valid value to order it within its sequence — the cluster rejects this after the upload; fix the values and re-run."
+"this backend (%s) doesn't support browser login yet — the device-grant endpoints land in backend#835: %w"
+"this cluster is already registered to another tracebloc account (%s) — ask them to release it, or sign in as that account (cluster_conflict)"
 "this machine has %s, but you asked for %s."
+"this machine is too small to choose an amount — after tracebloc's ~1 core and 3 GiB overhead it can offer a training run at most %d core(s) and %d GiB. Free up resources or use a larger machine."
+"this task's data is sequence-grouped: the schema must declare %q (groups the timestep rows of one sequence — e.g. a patient/device/session id) and %q (orders the rows within each sequence). Missing: %s. The column names are fixed by the platform — rename your CSV columns to match and re-run."
 "time column"
+"timed out after %s before tracebloc could confirm this client — retry, or run `tracebloc doctor`."
+"timed out after %s waiting for tracebloc to report this client online (last state: %s). Run `tracebloc doctor` to diagnose, or re-run the installer."
+"timed out after %s waiting for tracebloc to report this client online; the last status check failed: %v"
 "token saved to ~/.tracebloc (0600)"
 "total records"
 "total size"
@@ -642,6 +741,7 @@ screen. %s/%d are runtime placeholders.
 "tracebloc-doctor-%s.txt"
 "tracebloc-stage-%s-%s"
 "unavailable"
+"unknown backend environment %q — valid values are dev, stg, prod (default). Check --env / $CLIENT_ENV"
 "unknown command %q for %q"
 "upgrade didn't complete (%w). You can run the installer directly:\n    %s"
 "values:"
@@ -651,9 +751,12 @@ screen. %s/%d are runtime placeholders.
 "waiting for teardown pod: %w"
 "watching ingestor Job: %w"
 "which split this data is"
+"which task is this data for? pass --task — one of: %s. (On a terminal without --no-input, tracebloc asks you to pick.)"
 "whole GPUs a single run may use"
 "would set each run to"
 "writing credential file %s: %w"
+"your images mix file types (%s) — the ingestor requires one type per dataset. Convert them to a single type, or split them into separate tables."
+"your secure environment %q has %d training run(s) active — offboarding would stop them. Wait for them to finish or cancel them, then run `%s delete` again — or `%s delete --force` to stop them and offboard now"
 "~%s (requested; server may cap shorter)"
 "· %d GPU"
 "· %d classes"