omarchy/plugins/io.github.elevate08.qs-bitwarden-cli/tasks/bugs.md

# Known Defects

Found outside a task's own verification, during the Task 20 manual matrix.
Each entry records what was observed, what the code actually does, and how it
was resolved.

## 1. README described `sshAgentUnlockOnDemand` as gating signing

**Status:** fixed in the same commit. Found 2026-08-31 on `feature/ssh-agent`.

**Observed:** With **Unlock on demand** switched off and the vault locked,
`ssh-add -T` against a projected public key still opened the panel's unlock
prompt. Dismissing it returned "agent refused operation" for both the Ed25519
and the RSA key.

**Verdict: the code is correct and the documentation was wrong.** The setting
governs the identity listing on a cold cache, not signing. A locked signing
request for a key the helper already holds in its public cache always raises
the unlock prompt and parks the request; dismissing the prompt is what refuses
it, and it refuses immediately rather than at the deadline.

**Where that is settled:**

- `docs/ideas/ssh-agent.md:178` -- the state table row for "Locked, cache
  available" reads "List public identities; signing asks panel to unlock",
  with no condition attached.
- `docs/ideas/ssh-agent.md:310` -- "When it is on, unlock-on-demand must begin
  at `SSH_AGENTC_REQUEST_IDENTITIES` rather than at the sign request: with no
  cache there are no identities to offer, so no sign request will ever
  arrive."
- `agent/src/main.rs:475` consults `unlock_on_demand` in the `Identities` arm;
  the `Sign` arm at `main.rs:511` deliberately does not.
- `agent/tests/lifecycle.rs:320` and `:444` both assert the locked-sign
  behavior without ever setting the option, so the default already covers it.

**Fixed by** rewriting README "While the vault is locked" to separate the two
moments, and rewriting the `sshAgentUnlockOnDemand` row in the configuration
reference. No code change; the helper binary is unaffected and needs no
rebuild.

**Consequence for the Task 20 matrix:** the "off -> refused, no panel" row as
originally written cannot pass, because it describes behavior the design does
not have. Signing refusal while locked is tested by dismissing the prompt, and
by asking for a key the public cache does not know.

## 2. A grant's remaining time never counted down

**Status:** fixed. Found 2026-08-31 on `feature/ssh-agent`, during the Task 20
manual matrix.

**Observed:** With one live grant, the ACTIVE APPROVALS row on the SSH agent
settings screen read "1m 59s left" for the whole two minutes and then the row
disappeared, having never counted down. `sshAgentStatus` reported
`"grants":1` throughout.

**Cause:** `sshAgentGrantViews` computed `remainingLabel` from the companion's
`expiresInSec` at the instant of the announcement, and the companion announces
a grant once and says nothing further until the set changes. The view was a
snapshot rendered for the life of the grant; nothing re-derived it, and
nothing dropped a lapsed grant until the next announcement arrived.

**Fixed by** stamping each announced grant with `expiresAtMs` -- when it runs
out rather than how long it had left -- and adding `sshAgentGrantsAt(views,
nowMs)`, which re-derives the remaining time for a given moment and drops what
has lapsed. `Panel.sshGrants` became a derived property over
`sshGrantsAnnounced` and a `sshGrantTick` driven by a 1s timer that runs only
while grants exist, matching the cooldown countdown. Both fallbacks are
deliberate: an unstamped view, or any view before the first tick, is shown as
announced rather than dropped, because a grant must never disappear merely
because a timer has not run yet.

**Also worth knowing:** the same staleness would have hidden a grant that had
genuinely expired, since `sshAgentStatus` reported the announced count rather
than the live one. It now reports the live one.

## 3. The helper leaks its runtime files when the plugin is removed

**Status:** open, low severity. Found 2026-08-31 during the Task 20 manual
matrix.

**Observed:** After `omarchy plugin remove` with the SSH agent still enabled,
`/run/user/1000/qs-bitwarden-cli/` still held `ssh-agent.sock`,
`ssh-agent.lock` and `ssh-keys.fifo`, with no helper process running.

**Cause:** `ServiceRuntime` and `Runtime` in `agent/src/runtime.rs:264` and
`:320` unlink those files from `Drop`, which runs on a graceful shutdown --
which is why turning the agent off leaves nothing behind. Tearing the plugin
down kills the helper rather than shutting it down, so `Drop` never runs.

**Impact:** Small. The files are on a tmpfs and go with the login session, and
`omarchy plugin remove` has no uninstall hook, so nothing of ours can run at
that moment anyway. Until the next login, a client routed at that path finds a
socket that answers nothing rather than no socket at all.

**Possible fix:** A SIGTERM handler in the helper that runs the same cleanup,
if the shell terminates rather than kills the process. `Drop` cannot help
against SIGKILL and nothing can. Worth checking which signal the shell
actually sends before writing the handler.

**Documented meanwhile** in the README's Uninstall section: turn the agent off
before removing the plugin, and what the three files are if you did not.

## 4. The uninstall instructions destroyed a stow-managed shell.json

**Status:** fixed. Found 2026-08-31 during the Task 20 manual matrix, on the
maintainer's own machine.

**Observed:** Following the Uninstall section, the step "delete the
`io.github.elevate08.qs-bitwarden-cli` key under `plugins`" was carried out by
removing `~/.config/omarchy/shell.json`. Every configured plugin disappeared
from the bar, not only this one, and the shell came up on its built-in
defaults.

**Cause:** That path was a `stow` symlink into `~/projects/dotfiles`. Deleting
it removed the link, not the configuration; the shell then found no user
config at all. The real file was intact in the repository throughout, and
restoring the symlink restored everything.

The instruction was also redundant: `omarchy plugin remove` already calls
`omarchy-shell shell setPluginEnabled <id> false`, which removes the bar entry
and its settings before the directory goes.

**Fixed by** deleting the hand-edit step, naming `omarchy plugin disable` for
the stale-entry case, and warning plainly that `shell.json` is often a symlink
and must be changed through the shell rather than edited. Nothing in the
Uninstall section now tells a user to touch a file the shell owns.

**Worth remembering:** every other path in that section is under this plugin's
own directories, where a mistake costs the user only this plugin's data. This
one step reached into a file shared by every plugin on the system, and that is
what made a documentation error destructive.