Summary

• Problem: hot model-catalog and manifest-contract readers that omitted workspaceDir could reject the Gateway's current workspace-scoped plugin metadata snapshot and fall back to cold plugin metadata scans.
• Why it matters: those fallbacks can repeat plugin manifest/package stat sweeps on control-plane paths involved in slow agent startup and laggy Gateway/TUI reports.
• What changed: added an explicit snapshot-compatibility opt-in for unscoped control-plane readers, then used it for model catalog and manifest-contract metadata lookups.
• What did NOT change (scope boundary): explicit workspace callers still require an exact workspace match; env/config compatibility remains enforced before reuse.
• CI unblock: updated a stale kitchen-sink prerelease canary assertion from 0.1.5 to the current script default 0.2.5; this was already failing on origin/main and is test-only.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Fixes [Bug]: getCurrentPluginMetadataSnapshot workspaceDir mismatch defeats snapshot reuse — 192-stat sweep per dispatch (regression of #76182 / #73353 fix) #77519
• Related Agent bootstrap takes 3+ minutes per turn; core-plugin-tools, system-prompt, stream-setup each 45-75s #77532
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: current metadata snapshots are workspace-scoped, while some hot control-plane readers intentionally operate without a workspace. The strict default compatibility check rejected those snapshots even when the stored workspace was the correct current Gateway scope.
• Missing detection / guardrail: tests covered strict workspace rejection and explicit workspace reuse, but not safe unscoped control-plane reuse with env/config compatibility preserved.
• Contributing context: [codex] Preserve workspace metadata reuse for model refreshes #77554 fixed explicit agent-dir model refresh paths; this follows up on unscoped catalog/contract readers that still needed a safe reuse path.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/plugins/current-plugin-metadata-snapshot.test.ts, src/agents/model-catalog.test.ts, src/plugins/manifest-contract-eligibility.test.ts
• Scenario the test should lock in: unscoped readers opt into current workspace-scoped snapshot reuse only while passing env/config through compatibility checks.
• Why this is the smallest reliable guardrail: these tests exercise the snapshot compatibility seam and the two hot readers without needing a live Gateway.
• Existing test that already covers this (if any): strict workspace rejection coverage already existed; this PR extends it for the safe opt-in path.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Plugin/model catalog metadata lookups should avoid repeated cold scans on compatible hot paths, reducing latency and event-loop pressure for affected Gateway sessions.

Diagram (if applicable)

Before:
unscoped catalog lookup -> current snapshot rejected -> cold plugin metadata scan

After:
unscoped catalog lookup -> env/config-compatible snapshot reused -> no cold scan

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local; Linux via Blacksmith Testbox
• Runtime/container: Node/pnpm repo scripts
• Model/provider: N/A
• Integration/channel (if any): plugin metadata/model catalog surfaces
• Relevant config (redacted): N/A

Steps

1. Call manifest/model catalog readers without a workspace while a workspace-scoped current metadata snapshot exists.
2. Verify they can reuse the compatible snapshot instead of falling back to loadPluginMetadataSnapshot.
3. Verify explicit env and omitted config are still passed into compatibility checks.

Expected

• Compatible unscoped control-plane readers reuse the current snapshot.
• Explicit workspace mismatch remains rejected.
• Env/config mismatches still force fallback.

Actual

• Matches expected with the new tests.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • pnpm exec oxfmt --check --threads=1 src/plugins/current-plugin-metadata-snapshot.ts src/plugins/current-plugin-metadata-snapshot.test.ts src/agents/model-catalog.ts src/agents/model-catalog.test.ts src/plugins/manifest-contract-eligibility.ts src/plugins/manifest-contract-eligibility.test.ts
  • pnpm check:changelog-attributions
  • pnpm test src/plugins/current-plugin-metadata-snapshot.test.ts src/plugins/manifest-contract-eligibility.test.ts src/agents/model-catalog.test.ts
  • pnpm exec oxfmt --check --threads=1 test/scripts/plugin-prerelease-test-plan.test.ts
  • pnpm test test/scripts/plugin-prerelease-test-plan.test.ts
  • Testbox pnpm check:changed on tbx_01kqtrar6geep8cka08mk7cyq4 before the stale-test canary update
  • Testbox pnpm check:changed on tbx_01kqtrsq3225b6xpgfjxbvbbkb after the final diff
• Edge cases checked: explicit env forwarding, omitted config normalization, strict default rejection without opt-in.
• What you did not verify: live multi-agent Gateway strace/syscall reduction.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: overly broad reuse could hide workspace/env/config-specific plugin metadata differences.
  • Mitigation: reuse is explicit opt-in, still runs policy/fingerprint compatibility with normalized config and caller env, and preserves exact matching for explicit workspace callers.