Summary

Remove the embeddedPi: z.unknown().optional() passthrough stub from AgentDefaultsSchema. The Pi orchestrator was replaced by AgentRuntime early in the fork; this stub was kept so existing user configs could parse during the transition window. That window has closed.

Closes #2479.

Migration choice — Option B (rule + auto-migration)

#2478 chose Option A (silent passthrough) for memorySearch / pdfModel because users had no action to take. #2479 is different: the issue explicitly directs us to remove the stub, which means strict-schema configs carrying embeddedPi would reject without a migration. We add a rule + auto-migration so the warning surfaces once and the config keeps loading:

• legacy.rules.ts — new rule at agents.defaults.embeddedPi with message "agents.defaults.embeddedPi is obsolete and ignored — the Pi orchestrator was replaced by AgentRuntime. Remove it from your config (auto-migrated on load)."
• legacy.migrations.ts — new migration strip-agents-defaults-embedded-pi (sibling of strip-agent-default-field from gut: config migration for deprecated default: true field #1581). Strips the field and pushes a change line.
• Gateway startup (server.impl.ts:206-226) already calls migrateLegacyConfig when legacyIssues.length > 0, writes the migrated config back, and re-reads — so users see the warning once, their config is cleaned up, and subsequent loads are silent.

Changes

Schema surface

• src/config/zod-schema.agent-defaults.ts — remove the 3-line stub (comment + field).
• src/config/types.agent-defaults.ts — remove the 2-line @deprecated type mirror.
• src/config/schema.help.ts — remove the two agents.defaults.embeddedPi[.projectSettingsPolicy] help entries.
• src/config/schema.labels.ts — remove the two matching label entries.

Legacy channel

• src/config/legacy.rules.ts — add the detection rule.
• src/config/legacy.migrations.ts — add the stripping migration.

Tests

• src/config/config-misc.test.ts — new describe block with two AC-bound tests:
  1. flags agents.defaults.embeddedPi as a legacy issue — loading a config with embeddedPi: {...} populates snap.legacyIssues with the path.
  2. auto-migration strips agents.defaults.embeddedPi and the migrated config validates — migrateLegacyConfig returns a non-null config (= passed strict validation) with the field stripped and the change line recorded.

Generated

• src/config/schema.base.generated.ts — regenerated via node --import tsx scripts/generate-base-config-schema.ts --write.
• docs/.generated/config-baseline.json + .jsonl — regenerated via node --import tsx scripts/generate-config-doc-baseline.ts --write.

Not touched (deliberately out of scope)

• Runtime identifiers runEmbeddedPiAgent, isEmbeddedPiRunActive, queueEmbeddedPiMessage, etc. in src/auto-reply/, src/agents/, src/commands/agent.test.ts — these use CamelCase EmbeddedPi and refer to the Pi agent runner subsystem, which is orthogonal to the config stub. Issue scopes refactor(config): remove embeddedPi Pi-era config stub #2479 explicitly to the config stub.
• memorySearch and pdfModel passthrough stubs — refactor(config): remove obsolete LLM model feature catalog types #2478 chose Option A for these; they stay.

Acceptance criteria

• rg "embeddedPi" src/ returns hits only from the migration-warning message text. Remaining hits: legacy.rules.ts (rule text), legacy.migrations.ts (migration code + change message), config-misc.test.ts (regression test fixtures). Per the gut(config): remove obsolete LLM model feature catalog types (#2478) #2484 interpretation, these are "inside the migration shim."
• A test exercises: loading a config containing embeddedPi: {...} emits the migration warning AND the config loads successfully (no schema error). Two tests cover both sides.
• tsc --noEmit clean — pnpm tsgo exit 0.
• Test suite passes — pnpm vitest run src/config src/middleware = 129 files / 1396 tests pass.

Test plan

• pnpm check (format:check + tsgo + lint + tmp-no-random-messaging + no-remoteclaw-ai) — all pass.
• pnpm canvas:a2ui:bundle — ok.
• pnpm vitest run src/config — 103 files / 788 tests pass.
• pnpm vitest run src/config src/middleware — 129 files / 1396 tests pass.
• Fork-integrity gates run locally — all pass:
  • zombie-import gate: clean
  • stub-debt gate: 132 == baseline 132
  • throwing-stub-callers gate: 0 violations, 0 allowlisted, 0 unexpected
  • obsolescence-audit gate: 49 == baseline 49

Notes

• The stash-and-rerun check confirmed that the ~55 gateway test file failures observed in a broad local pnpm vitest run src/gateway are pre-existing on main (error: Cannot resolve main session key: no agents configured in test-helpers.server.ts:164). Unrelated to this diff. CI's environment runs these test files successfully.
• Following the fork's "gut" convention: commit prefix gut(config):; branch gut/embedded-pi-config-2479; migration sibling to strip-agent-default-field (gut: config migration for deprecated default: true field #1581).

🤖 Generated with Claude Code