[Xuepoo]

Closes bitty-terminal/bitty#1970. Closes bitty-terminal/bitty#1971.

Priority: P1 | Area: plugins | Labels: feat,area:plugins,P1 | Milestone: v0.1.0 | RFC: W-01 overlay-input-capture | Task: CTX-1156

Summary

• #1970: manifest compat.bitty floor >=0.1,<1.0 to >=0.0.22,<0.1. The install-pipeline CompatibilityCheck refused every 0.0.x host, so the plugin never activated for 0.0.23 testing. The new floor is the verified-against 0.0.22-dev host carrying the v1 commands/events/settings bridge, the W-01 capture mechanism (bitty.ui.overlay.acquire/update/release plus capture-owner surfacing), and overlay.released; ceiling <0.1 stays restrictive because 0.x minors may break.
• #1971: toggle acquires the focusable overlay plus transient input capture per open (bitty.ui.overlay.acquire({ title, placeholder })), paints the non-empty default scene (title plus filtered items, or title plus No entries placeholder when empty) with the session-owned update, destroys the surface on release(cancelled), and resets toggle state on overlay.released. Without the ui.overlay.focus grant, on a live foreign session, or on a host without the capture table, the toggle degrades to command-only counts; a rejected update keeps the last-known-good scene.
• Capability ui.overlay.focus replaces ui.rich + ui.overlay (one coupled grant instead of two; narrowing, no new authority; release ungated so cleanup cannot wedge input). SDK pin moves to bitty-plugin-sdk#d5d117d, which carries the W-01 identifiers transitively via its parent e769117 (W-120, the first ui.overlay.focus commit); mock host plus specs cover acquire/update/release, revocation, conflicts, and degraded modes; README/CHANGELOG/tests updated.

Tested

• just check green (markdownlint 0 issues; prettier clean; bitty-plugin-lint valid; luaparse x3; Lua 5.4 suite 113/113; LuaLS conformance positive 0 diagnostics / negative rejected).
• gitleaks clean; actionlint clean; no hardcoded host paths.
• Headed WS5 (bitty main 0.0.22 dev 2a3fddaf, isolated XDG, recorded PID only, WS5 empty before/after, WS2 restored): plugin install enabled 1/1 (manifest 45508725bc68); headless --headless --log-level debug shows plugin active (1 commands, 2 events); toggle via pid-targeted ctrl+shift+p paints centered PaletteNo entries plus banner bitty-terminal.palette:toggle: 0.
• Shots: bitty/recording/headed/shots/ctx-1156-ws5-20261012T123004Z-pal-01-launch.png, -pal-02b-palette.png (proof). Run dir: bitty/recording/headed/runs/ctx-1156-20261012T123004Z/ (NOTES.md, install-pal.log, plugin-list.log, instance/pid files). Prior run bitty/recording/headed/runs/ctx-1156-20261012T113230Z/ with shots -pal-01-launch.png, -pal-02-palette.png corroborates.

Risks

• Floor >=0.0.22 assumes hosts at that version carry W-01; older 0.0.x hosts degrade to command-only counts (fail-closed) rather than crashing.
• Live query typing still reads settings (no capture-queue drain yet); documented as Known gaps.
• Do NOT merge/close per owning task; implementer stops at review.

[Xuepoo]

Docs-only fix pass for the 2 NEEDS-FIX blockers. Head 3b8406b839e624a8d5727dfd9690e7dfe531b046 (branch ctx-1156/fix-palette-compat-capture). Not merging per instructions.

B1 (AGENTS.md stale) — fixed in 3b8406b:

• Authority boundary now declares only ui.overlay.focus (W-01 coupled focusable surface + transient capture; v1 presentation grants unrequested), replacing the stale only ui.rich and ui.overlay line.
• Origin paragraph now states the W-01 contract (bitty-terminal/bitty#1971) couples surface + capture under the single ui.overlay.focus grant replacing the former ui.rich + ui.overlay pair, and notes the former bundled ui.overlay-only declaration used the Panel Runtime path (removed by bitty PR #1611). Matches bitty-plugin.toml + README.md capability-difference section and satisfies the line-111 guide-update rule.

B2 (SDK "first" claim wrong) — fixed, pin kept at d5d117d:

• Verified in bitty-plugins/sdk/bitty-plugin-sdk: e769117 ([CTX-0065] W-120, #141) is the first ui.overlay.focus commit; d5d117d ([CTX-0068] W-103 S-2, #143) is its direct child (git merge-base --is-ancestor e769117 d5d117d = YES, rev-list --ancestry-path count 1), so it carries the W-01 identifiers transitively.
• CHANGELOG.md reworded to "move the SDK pin to bitty-plugin-sdk#d5d117d, which carries the W-01 identifiers transitively via its parent e769117 (W-120, the first ui.overlay.focus commit)". PR body third bullet edited the same way.
• Kept the pin at d5d117d (no re-pin to e769117): functional and validated (just manifest green with the current package.json+bun.lock pin), and minimal churn — re-pinning would invalidate the lockfile + tested headed evidence for no correctness gain.

Evidence:

• just check green: markdownlint 0 issues; prettier clean; bitty-plugin-lint valid; luaparse x3; Lua 5.4 suite 113/113; LuaLS positive 0 diagnostics / negative rejected.
• actionlint exit 0; gitleaks detect --source . no leaks found (64 commits scanned).
• Commit hooks green (markdownlint-staged, prettier-staged, commitlint).
• Diff: AGENTS.md + CHANGELOG.md only (17+/9-); no code/manifest/lockfile churn.