adapter seam: document the qualified-id obligation once, not per backend

[dracic]

Summary

#254 and #291 both landed the same shape — psmux qualifies its window ids to session:@N at the minting/listing seams — but the rule a backend author needs in order to do that safely is still spread across two backend-specific docstrings and a parenthetical in the authoring guide. The TerminalMultiplexer ABC states one half of it (list_window_ids must match new_window, because window_alive is a membership test) and, after #291, that current_window_id must match the window_id column of list_windows. What it does not state is the general obligation those two are instances of.

Split out of the #291 diff deliberately: correcting the stale text was in scope for that fix, writing cross-backend authoring guidance was not.

The rule that is currently undocumented

If a backend returns anything other than a bare native id from an id-minting seam, then every verb that backend's own callers replay the id through must accept that form — and where one cannot, the backend translates inside that verb rather than leaving the id bare.

psmux is the worked example in both directions:

• select_window cannot take session:@N on stock 3.3.7 (the CLI-side existence check matches only window index/name), so the backend resolves the id to an index before sending instead of exempting the id from qualification.
• The window-option verbs ignore the window slot entirely, so they need no override at all — qualified and bare behave identically there (that is psmux: per-window user options are session-scoped - the ctl-window project guard cannot discriminate and the parked-return mechanism is inert #310's problem, not a targeting one).

Getting this wrong is quiet in both directions, which is why it is worth writing down:

• Qualify a mint but not the matching list, and window_alive reads every live window as instantly dead (the trap psmux: pipe_pane targets a bare @N window id — per-server ambiguity binds the sink to the wrong server's pane (empty run logs) #254's notes called ci: bump actions/checkout from 6 to 7 #1).
• Qualify list_windows but not current_window_id, and the ctl-window prune stops recognizing its own window — it kills the window it is running in (found by review on psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291).
• Qualify an id whose consumer verb rejects the form, and the verb fails or silently no-ops, with no error reaching core because these paths are best-effort.

Suggested scope

• One paragraph in docs/adapter-authoring-guide.md's target-grammar section stating the obligation, with psmux's select_window translation named as the worked example of "the verb cannot take it, so translate".
• A sentence on TerminalMultiplexer.new_parked_window noting the id is opaque and MAY be qualified, matching what new_window already says.
• No behavior change, no test changes.

Relevant for the external adapter path too: the herdr adapter is the documented implement-fresh reference, and any native-id backend written against parse_target() faces the same question.

Refs: #291, #290, #254, #310

[coderabbitai]

🔗 Related PRs

#47 - refactor(adapters): extract the shell-dialect seam from new_window/new_parked_window [merged]
#141 - feat(mux): seam-canonical window targets [merged]
#146 - refactor(mux)!: extract the herdr backend to pbean/bmad-loop-adapter-herdr [merged]
#225 - fix(tui): record session-qualified parked-window return target [merged]
#290 - fix(adapters): session-qualify psmux window ids [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[dracic]

Data point for this issue's scope: the prune's kill verdict in #524 (fixing #435) added a third instance of the obligation, and it was undocumented until that PR.

The ABC states two pairings:

• list_window_ids ↔ new_window (the SYMMETRY RULE, because window_alive is a membership test)
• list_windows' window_id column ↔ current_window_id (added by psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291)

The new verdict membership-tests list_windows' window_id column against list_window_ids — a pairing neither rule covers. In-tree it holds by accident of both backends being internally consistent (psmux runs _qualified_window_id on all three; tmux is bare on all three), but a backend that honoured both documented rules and split these two forms would report every killed window as verifiably gone: survived permanently empty, no error anywhere.

I added that third pairing to the list_windows docstring in #524 because the caller landing in the same PR depends on it. It is a third special case papered onto a rule this issue proposes stating once — which is more evidence for doing it generally than for continuing to enumerate.

Worth adding to the suggested scope, if the general statement gets written: the failure modes list here covers "qualify a mint but not the matching list" and "qualify list_windows but not current_window_id". The third is any two id-producing seams whose outputs core compares to each other — the set is not fixed, it grows whenever a new caller crosses two of them, which is exactly why per-pair documentation keeps going stale.

Also noting the reason this is quiet in a new way: the earlier failures were loud-ish in effect (every window reads dead; the prune kills its own window). This one fails optimistic and silent — the report simply says the work was done.

Refs #524, #435