CodeNomad/docs
Pascal André de44f7b29c
fix(pending): name the cause, folders and sessions in the recovery warning (#965)
The "Question and permission recovery is incomplete" warning now says
which project it concerns, why recovery failed, which folders failed and
which sessions made them required, instead of a fixed sentence.

## Why
- The previous warning grouped every possible cause into one fixed text
and named none of them, including unrelated failures such as the initial
workspace load.
- Six earlier fixes each removed one measured cause, but every new cause
produced the same text, so it could only be diagnosed by live captures.
- With several projects open, it did not even say which project was
affected.

## Example
Before:
> Question and permission recovery is incomplete. Known requests are
retained; inactive worktrees are not loaded.

Now, for the live case fixed by #964:
> **CodeNomad: questions and permissions not fully recovered**
> Outside this project: prompt-replay-yield. Affected sessions: ISSUES
Codenomad.

## Change
- **Server:** every `error` directory in the pending snapshot carries a
`reason`:
- `not-owned`, `deleting`, `missing` (an owned folder that no longer
exists), `unverified` (Git/filesystem/WSL translation could not verify
it) and `changed` (ownership or repository changed during the read);
- a native placement outside the workspace is reported as `not-owned`,
and a deletion fence raised during the read as `deleting`.
- **UI, `stores/pending-recovery-cause.ts`:** a small module turns
failures into a structured cause:
- folder issues, plus client-side `timeout`, `unavailable` (with the
HTTP status when known) and `excluded` (a required folder reported as
history);
- the plugin being unavailable, repeated supersession, an initial load
failure and a generic request failure.
- **Messages:**
- folder issues are grouped by cause, named by folder basename, and
capped at three with a remainder;
- only the sessions that made a folder required (active, or holding a
request) are named;
- the title uses the same label as the project tab
(`lib/instance-label.ts`, shared with `instance-tab.tsx`).
- **Diagnostics:** the structured cause is also logged at warn level.
- **Unchanged:** the two-attempt threshold, once-per-episode
notification, re-arming on success, retained queues and deferral
handling.
- **i18n:** the generic key is replaced by the cause keys in all 10
locales.

## Tests
- Server: `pending-requests.test.ts` 40/40; every error assertion now
names its reason.
- UI:
- `instances-pending-requests` passes, including the live scenario: an
active session in a folder reported `not-owned` produces "Outside this
project: prompt-replay-yield. Affected sessions: ISSUES Codenomad.",
while an idle session in the same folder is not named. A timed-out batch
names each folder.
  - The unavailable plugin is named.
- New `pending-recovery-cause.test.ts` covers grouping, caps, the detail
variants, request classification and failure combination.
  - 39/39 together with the compaction and permission lifecycle suites.
- i18n tests and both typechecks are clean.
2026-10-15 09:17:31 +02:00
..
features/wake-lock fix(wake-lock): allow display sleep during active work 2026-04-21 20:58:40 +01:00
guides build: ship the Linux deb from Electron and the Windows installer without a ZIP (#955) 2026-10-14 16:45:49 +02:00
help fix(pending): name the cause, folders and sessions in the recovery warning (#965) 2026-10-15 09:17:31 +02:00
screenshots docs: refresh README and workspace screenshot for 0.20 (#782) 2026-09-26 04:13:30 +02:00
superpowers/specs feat(ui): support bracket math delimiters (#588) 2026-07-14 14:00:26 +02:00