fix(setup): session_start warning conflates legacy and unknown-field cases and stays noisy when only configVersion is missing

[samsen3]

Summary

Starting from OpenPI 0.9.0 pulled from source, the very first session prints a startup warning whose text covers three unrelated situations in one line. When the only real diagnostic is a missing top-level configVersion on a previously-written my-pi-setup.json, the warning still tells the user to "run /openpi-setup for details" and points at "unknown fields", even though there are no unknown fields and the file loads correctly.

Environment

• OpenPI: from source checkout (@tt-a1i/openpi@0.9.0)
• Pi: @earendil-works/pi-coding-agent (installed under workbuddy-managed Node)
• Node: v22.22.2
• Config file: ~/.pi/agent/my-pi-setup.json, written by an earlier OpenPI version (no top-level configVersion)
• Fields present in the file (all recognised by setupShape): suggestions, workflows, ui, postEdit, subagents, plus nested ui.showHeader, ui.customFooter, ui.footerStyle, ui.footerLines, ui.footerItems, ui.subagentResultDisplay, ui.bashToolDisplay, ui.fileMutationDisplay, etc.

Reproduction

1. Have an older OpenPI (or pre-configVersion) write my-pi-setup.json without a top-level configVersion.

2. Pull the current source (main), restart Pi (or run /reload).

3. On session_start, the user immediately sees:

   OpenPI configuration loaded with warnings (legacy format or unknown fields). The file is unchanged. Run /openpi-setup for details.
   

Actual diagnostic

Calling the built-in inspectSetupConfig() / formatSetupDiagnostics() directly returns:

Configuration path: /Users/<user>/.pi/agent/my-pi-setup.json
Configuration source: disk
Configuration version: legacy (unversioned); supported: 1
Configuration writes: allowed
warning: "configVersion" — Legacy unversioned document; migration occurs on explicit save
writable: true

• The diagnostics array contains exactly one warning.
• The only path is configVersion.
• No unknown fields are reported; every key in the file is recognised by setupShape.

Root cause

extensions/setup/index.ts:244-255 treats any warning as the same generic notification:

pi.on("session_start", (_event, ctx) => {
  resetEpisode();
  if (!ctx.hasUI) return;
  const inspected = inspectSetupConfig();
  if (inspected.diagnostics.length === 0) return;
  ctx.ui.notify(
    inspected.writable
      ? "OpenPI configuration loaded with warnings (legacy format or unknown fields). The file is unchanged. Run /openpi-setup for details."
      : "OpenPI could not load the saved configuration; safe defaults are in use and configuration writes are blocked. The file is unchanged. Run /openpi-setup for diagnostics and recovery guidance.",
    inspected.writable ? "warning" : "error",
  );
});

Three categories of warning are folded into one message:

Category	Reality today	Trigger	What the user should do
Legacy unversioned	warning, missing configVersion	pre-configVersion file	Nothing — explicit save will migrate it
Unknown field	key preserved, warned	schema-external key	Decide: remove key or accept
Real error / corrupted config	reads blocked	malformed JSON, IO error, unsupported version	Run /openpi-setup for diagnostics

The wording "legacy format or unknown fields" simultaneously suggests both, even though their nature, fix path, and risk are completely different. In the legacy-only case there is no second problem to investigate.

Why this is a bug

1. Misleading: in a pure legacy scenario the user is told to suspect unknown fields, and is pushed to /openpi-setup to debug a non-problem.
2. Overly noisy: writable: true legacy load is already a safe, documented state. SETUP.md:43 ("Unversioned documents migrate only on an explicit save") makes it an intentional compatibility mode, not a failure. Repeated warnings on every startup after upgrading from an older OpenPI do not help the user — they tell them to redo /openpi-setup for a file that is already valid and already loaded.
3. Lacks precise diagnosis: the warning carries no path. The user has to run /openpi-setup to learn what is actually wrong. For a pure legacy case this is wasted effort.

Suggested direction (minimum-change)

The fix should make sure the upgrade-from-older-openpi experience is silent when the only diagnostic is a missing configVersion on a writable: true file, because the existing design already treats that state as safe and migration-only. Concretely:

1. In extensions/setup/index.ts's session_start handler, branch on the diagnostics instead of treating them as one bucket. Only notify when at least one entry is not a pure-legacy case (i.e. there is an unknown field, a read error, or an unsupported version).
2. When notifying, change the text so it no longer conflates "legacy format" with "unknown fields" — describe the actual category and include the relevant path from the diagnostic entry (the inspectSetupConfig output already carries it).
3. Do not auto-write the file on startup. The migration remains opt-in via /openpi-setup, per the contract in setup: 配置诊断与 fail-closed 回滚，不新增第二条配置入口 #498 and SETUP.md:43.
4. Keep the error branch for the truly unreadable / unsupported-version case (current second message) intact.

A user upgrading from any pre-configVersion OpenPI should be able to keep their existing my-pi-setup.json and see no warning until they explicitly choose to migrate.

References

• Source: extensions/setup/index.ts:244-255 (session_start handler).
• Config contract & 404: SETUP.md:43 — Unversioned documents migrate only on an explicit save.
• Design background: setup: 配置诊断与 fail-closed 回滚，不新增第二条配置入口 #498 (closed) — setup: 配置诊断与 fail-closed 回滚，不新增第二条配置入口. This issue is not a regression of setup: 配置诊断与 fail-closed 回滚，不新增第二条配置入口 #498; it reports that the warning text introduced around setup: 配置诊断与 fail-closed 回滚，不新增第二条配置入口 #498 still needs tightening to honour the legacy-is-safe design.
• Diagnostic entrypoint used in reproduction: inspectSetupConfig() / formatSetupDiagnostics() in the same extensions/setup extension.

[samsen3]

我来认领这个问题。

本 PR 我会尽量保持最小改动，只动 extensions/setup/index.ts 中 session_start 的通知分支：

• 只缺 configVersion、writable: true 的 legacy 场景：不再弹警告（升级后用户不需要重跑 /openpi-setup，配置照常生效，文件保持不变）。
• 真正存在 unknown field / 读取错误 / 不支持的版本时：仍然通知，但去掉"legacy format or unknown fields"这种笼统措辞，写明具体类别，并把 path 一并带上。
• 现有的错误分支保持不变。

明确不做的：

• 不改 inspectSetupConfig / diagnostics schema；
• 不改 setup-config.ts 的 fail-closed 与写入语义（属于 setup: 配置诊断与 fail-closed 回滚，不新增第二条配置入口 #498 已定下来的范围）；
• 不在启动时自动写入 configVersion: 1，迁移仍按 SETUP.md:43 保持 opt-in。

测试会在 tests/extensions/setup/ 加几条：legacy-only writable → 不通知；legacy + unknown field → 通知且文案点名 unknown field；corrupted/unsupported → 维持原错误分支。

[627150795]

我来处理这个问题，范围限定在 extensions/setup/index.ts 的 session_start 诊断分支：仅当唯一诊断是可写旧配置缺少 configVersion 时不再重复提示；未知字段、读取错误和不支持版本继续显示准确类别及路径。不在启动时写回配置，并补充最小回归测试。