diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index f1c0bd5..a1eba46 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -97,6 +97,8 @@ rules: | BDR-085 | 2026-08-25 | User permanent rules: writing-style always-on in rules/, web build+security path-scoped | accepted | | BDR-086 | 2026-08-26 | darwin: threshold gates full loops; verified defects fixed regardless of unit score (paired-validated, batched checkpoint) | accepted | | BDR-087 | 2026-09-03 | Stop hook = attention signal only, never control flow; one script for Notification + Stop | accepted | +| BDR-088 | 2026-09-15 | gstack Playwright bump shared via lib, re-applied after submodule update; update helper never touches the submodule tree | accepted | +| BDR-089 | 2026-09-15 | No Playwright browser-cache pruner; read-only doctor report — .links proved 0 bytes reclaimable | accepted | --- @@ -1123,3 +1125,24 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Guard vs prior refusal**: [[BDR-083]] (unlazy review, GATE 0) REFUSED a Stop hook using `decision:"block"` (forces continuation, inverts human gates). THIS Stop hook returns `terminalSequence` + `suppressOutput` only, exit 0, zero control-flow effect. Signal ≠ control. Do not read the refusal as banning Stop outright. - **Status**: accepted. - **Reference**: [[LRN-146]] event-coverage gap, [[BLK-020]] client-side faults, [[LRN-145]] terminalSequence pattern. Verified live: turn-end + AskUserQuestion both ring; `permission_prompt` unexercisable under `defaultMode: auto`. + +--- + +## BDR-088 — gstack Playwright bump shared via lib; update helper never touches submodule tree +- **Date**: 2026-09-15 +- **Decision**: `gstack_bump_playwright_if_unsupported` moved out of `install-plugins.sh` into `lib/gstack-playwright.sh`, sourced by install-plugins + update-all + doctor. update-all's submodule block now calls `gstack_submodule_update_with_bump`: re-applies bump after successful `submodule update --remote`; on failure prints git's own message, hints `make plugin`, returns 1. Never touches submodule worktree. +- **Why**: [[BDR-029]] caveat open — bump survived only till next `make plugin`, update path never re-checked OS support. Real gap, user-reported. +- **Alternatives rejected**: conflict-RECOVERY branch (discard package.json+bun.lock → retry → backup/restore). Withdrawn at human gate after 4-agent challenge: concentrated 3 BLOCKER + 4 MAJOR. Worst case = bump discarded, re-apply silently no-ops (bun absent / registry down — bump returns 0 on every path), `./setup` rebuilds browse against unsupported Playwright → [[BLK-008]] returns. Pre-existing behavior just failed the update and kept bump intact, so the "improvement" could regress a working install. +- **Deviations carried from "code MOVED not changed"**: `|| true` on ostag capture (line exited 1 on every non-Ubuntu host → aborted caller under inherited errexit, reproduced); `timeout` on all 3 bun calls, exit 124 → warn + no bump (TERM'd install leaves node_modules half-written, poisons the support grep). +- **Status**: accepted. +- **Reference**: commit 2cebecb, `lib/gstack-playwright.sh`. Links [[BDR-029]], [[LRN-070]], [[LRN-071]], [[LRN-150]], [[BLK-008]]. + +--- + +## BDR-089 — No Playwright browser-cache pruner; read-only doctor report instead +- **Date**: 2026-09-15 +- **Decision**: `doctor.sh` gains own `── Playwright browsers ──` section — cache size, per-revision the installs requiring it, counts of unreferenced dirs + broken links. Zero deletion anywhere in the lib. +- **Why**: measured, not assumed. `~/.cache/ms-playwright/.links/` registers 3 installs — gstack 1.61.1 → rev 1228, gsd-pi nvm 1.61.0 → 1228, gsd-pi ~/.local 1.63.0 → 1243. Every dir on disk referenced → 0 bytes reclaimable. Playwright's own `_deleteStaleBrowsers` already unions across all registered installs on every `install`. +- **Alternatives rejected**: hand-rolled pruner guarded on "revision resolved by gstack's local playwright" (the originally requested shape) — that guard keeps 1228 and DELETES 1243, breaking gsd-pi. The guard was wrong, not just its implementation. +- **Status**: accepted. +- **Reference**: commit 2cebecb. Links [[LRN-151]], [[BDR-088]]. diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md index 814446a..f1c382d 100644 --- a/.claude/memory/evals.md +++ b/.claude/memory/evals.md @@ -39,6 +39,7 @@ rules: | EVAL-025 | 2026-07-17 | opening seo/geo inventory (subagents): 7/7 verifiable claims false or overstated; real contact corrected all, 6 plan corrections + 4 features killed at measurement | keep | | EVAL-027 | 2026-08-24 | contract-gates behavioral RED: 16/16 fresh unprimed runs followed new doctrine (GATE 0 order, vacuous oracle, ABANDONED routing, scope temptation resisted) | keep | | EVAL-028 | 2026-08-26 | darwin v2.1 paired run 54 units: 60 paired verdicts 0 revert/tie; skeptics found 3 real residuals — engaged, not rubber-stamp | keep | +| EVAL-029 | 2026-09-15 | 4-agent plan challenge: 6 BLOCKER; 3 of 3 confirmation-pass BLOCKERs came from the fixes themselves; caught a false 654 MB orphan claim | keep | --- @@ -267,3 +268,14 @@ Dogfood: 3 blind lenses attacked the v1 plan for the plan-challenge feature itse - **Method**: paired same-judge 3-majority per round (v2.1); judges live-exec where artifact executable (5 units: skills-perso, profile, plugin-pair, status-reporter, gitflow). Absolute scores triage-only. Totals main-thread (LRN-018 applied). - **Anomalies**: (1) 0 reverts/ties in 60 verdicts — homogeneous-better checked: skeptic lens found real residuals 3x (doctor.sh cost source, hotfix RULES leftover restore, FILE(S) new-marker) → judges engaged. (2) census lock RED on line-rewrap, make test caught → LRN-144. (3) head-pipe masked grep exit 2x → LRN-143. - **Action**: v2.1 paired = standard. Post-run absolute rescore skipped by design (would be judge-noise theater). + +--- + +## EVAL-029 — 4-agent plan challenge: 6 BLOCKERs, and the fix round produced 3 of them +- **Date**: 2026-09-15 +- **Method**: 3 blind lenses (correctness / robustness / simplicity) on plan rev 1, then 1 confirmation lens on rev 2. Subject = the gstack Playwright lib plan ([[BDR-088]]). +- **Result**: rev 1 → 3 BLOCKER + 12 MAJOR. Rev 2, written specifically to close them → 3 NEW BLOCKERs, and 2 of the 3 were INTRODUCED BY the fixes: the new "every public function returns 0" rule contradicted the new "return rc", and the printer-name clause came verbatim from my own contract criterion 9. Rev 3 dropped the recovery branch entirely at the human gate — 6 findings closed by deletion instead of code. +- **Anomaly**: my first user-facing answer asserted ~654 MB of orphan Playwright revisions. FALSE — `.links` showed every dir referenced, 0 reclaimable. Caught only while designing the guard, not while asserting the number. Worse, the guard I proposed would itself have deleted gsd-pi's rev 1243. +- **Action**: (1) never state a disk-reclaimable figure before reading the registry that owns it ([[LRN-151]]). (2) A fix round deserves the same challenge as the original plan — 3/3 confirmation BLOCKERs came from fixes, not from the original. (3) The confirmation pass earned its cost: without it the printer override would have shipped and silently disconnected doctor's counters ([[LRN-150]]). +- **Status**: keep. +- **Reference**: `.claude/tasks/plans/2026-09-13-gstack-playwright-lib-2220.md` (rev 3). Links [[BDR-088]], [[LRN-150]]. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index e7b64d3..bdff5fa 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -460,3 +460,5 @@ rules: - Post-merge regression: toast dead again after re-attach from a RESTORED terminal, bell fine. Root cause [[LRN-147]]: ext hooks only terminals born after its activation; `enablePersistentSessions` restores terminals before it. Fix = disable persistent sessions, or fresh terminal + `dtach -a`. Verified: 3/3 toasts on fresh pty. - Same-day counter-example broke that cause: second session's terminal deaf though created LATER, same window, ext global, shells identical. Trigger unknown; [[LRN-148]] adds the 5s pre-flight test + demotes LRN-147's mechanism claim. - Attention signal refined: per-event labels (BDR-087 follow-on), silence on non-attention events, and no turn-end signal while `background_tasks` non-empty ([[LRN-149]]). Payload dump beat the docs: `background_tasks` undocumented for Stop but present on the wire. Branch bugfix/notify-subagent-spawn. +- gstack Playwright: bump extracted to `lib/gstack-playwright.sh`, now re-applied after a successful submodule update ([[BDR-088]]); read-only browsers report in doctor, no pruner — `.links` proved 0 bytes reclaimable and the guard I first proposed would have deleted gsd-pi's rev 1243 ([[BDR-089]], [[LRN-151]]). 4 challengers → 6 BLOCKER, recovery branch withdrawn at the gate ([[EVAL-029]]). 2cebecb on feature/gstack-playwright-lib. +- Node checked against Playwright: already v24 (1.61 needs >=18, 1.63 needs >=20), not the macOS constraint. macOS audit deferred to its own cycle — found statically: `sed -i` with no suffix x3 in install-plugins.sh (BSD sed eats the next arg), `${x,,}` in url-guard.sh (bash 4+, macOS ships 3.2), `readlink -f` in doctor.sh (absent pre-Monterey 12.3). diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index dcf98b2..a98a94f 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -139,6 +139,9 @@ rules: | LRN-134 | 2026-07-17 | resolve-then-pin in stdlib http.client beats monkeypatching getaddrinfo — dual-stack, thread-safe, no requests; classify the OS-resolved IP not the URL text | closing SSRF/DNS-rebinding on any Python HTTP egress | | LRN-135 | 2026-07-17 | a prefix-only scan for a dangerous construct is bypassable by padding — scan the WHOLE document | refusing any hostile construct (DTD/directive/marker) before parse | | LRN-143 | 2026-08-26 | `cmd \| head \|\| fallback` — pipeline rc is head's (0), fallback dead; bounded output → drop head, else pipefail | any probe/fallback bash in skills before trusting `\|\|` | +| LRN-150 | 2026-09-15 | Sourced lib shares caller shell: bare `ok/warn/info` override its printers, and its `set -e` applies inside | any new lib/*.sh | +| LRN-151 | 2026-09-15 | Playwright cache truth = union over `.links`, dir name maps `_`→`-`, revisionOverrides exist | shared versioned binary caches | +| LRN-152 | 2026-09-15 | git `protocol.file=user` blocks submodule fixtures; `-c` misses the code under test, `GIT_CONFIG_*` env does not | tests building git fixtures | --- @@ -1421,3 +1424,29 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **Fail-open**: field absent (older client) → still signal. Missed notification worse than extra one. - **Cross-session gotcha**: hook is user-scope, so EVERY session runs it. A single-file dump (`> file`) gets overwritten by another project's session — append JSONL and filter on `.cwd`. That accident proved `permission_prompt` fires with `message="Claude needs your permission"` (unexercisable in this session under `defaultMode: auto`). - **Future**: any hook needing turn-completion semantics must check background_tasks; "turn ended" ≠ "work done". Verified live: Stop with 0 tasks signals, Stop with 1 running subagent silent. + +--- + +## LRN-150 — Sourced shell lib is not a subprocess: prefix printers, honor inherited errexit +- **Date**: 2026-09-15 +- **Pattern**: `source lib.sh` shares the caller's shell. Two bites. (a) bare `ok()`/`warn()`/`info()` in the lib OVERRIDE the caller's same-named funcs. `doctor.sh` counts ERRORS/WARNS inside its own `warn()` → a lib `warn` disconnects the counter and doctor prints "No errors" while warnings scroll. Prefix every lib printer (`_gspw_ok`, `_gspw_warn`, `_gspw_info`). (b) caller's `set -euo pipefail` applies INSIDE the lib's functions: a failing command-substitution assignment (`x="$(. /etc/os-release; [ "$ID" = ubuntu ] && printf ...)"`) aborts the CALLER when the func is called as a bare statement. Reproduced — exit 1 on every non-Ubuntu host, latent in `install-plugins.sh` since [[BDR-029]]. +- **Rule**: public func called bare → `return 0` on every path + `|| true` on every capture. Func allowed to return non-zero → call it ONLY as an `if` condition. +- **Future application**: any new `lib/*.sh` sourced by a script that owns printers or sets `-e`. Check BOTH facets before wiring; the printer one is silent (no error, just a lying summary). +- **Reference**: `lib/gstack-playwright.sh`, `doctor.sh:12-15`. Links [[BDR-088]]. + +--- + +## LRN-151 — Playwright cache truth lives in `.links`, never in one install's view +- **Date**: 2026-09-15 +- **Pattern**: `~/.cache/ms-playwright/.links/` = one file per registered `playwright-core`, content = its path. Required set = UNION of `browsers.json` revisions across ALL of them. Dir name on disk = `${name//-/_}-${revision}`: `chromium-headless-shell` → `chromium_headless_shell-1228`. Miss that mapping and 2 live dirs read as orphan forever. `revisionOverrides` exists (webkit, ffmpeg on mac / debian11 / ubuntu20.04) so the base revision alone under-matches. Playwright prunes this set itself on every `install` (`_deleteStaleBrowsers`, coreBundle.js). +- **Future application**: never call a browser dir orphan from one project's playwright view — read `.links` first. Generalizes to any tool with a shared versioned binary cache plus a registry of consumers: the consumer registry is the source of truth, not the consumer you happen to be standing in. +- **Reference**: `lib/gstack-playwright.sh` `_gspw_browser_referenced`. Links [[BDR-089]], [[EVAL-029]]. + +--- + +## LRN-152 — git `protocol.file=user` kills submodule fixtures; `-c` misses the code under test +- **Date**: 2026-09-15 +- **Pattern**: since the CVE-2022-39253 hardening git refuses submodule clone/fetch over a local path by default (git 2.53 → `protocol.file` = `user`). `-c protocol.file.allow=always` fixes the FIXTURE's own git calls but NOT the `git` the code under test spawns — fresh process, inherits nothing from `-c`. Export for the whole test process instead: `GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=protocol.file.allow GIT_CONFIG_VALUE_0=always`. Env propagates, `-c` does not. +- **Also**: fixture repos need LOCAL `user.email`/`user.name` (no global identity here) and `git init -b main` + explicit `submodule..branch`, else `--remote` resolves a different branch than production does. +- **Future application**: any test building a git submodule fixture. Symptom is a hard "transport 'file' not allowed" before the first assertion, which reads like a broken test rather than a policy. +- **Reference**: `lib/tests/gstack-playwright.test.sh`. diff --git a/.claude/tasks/contracts/2026-09-13-gstack-playwright-lib-2220.md b/.claude/tasks/contracts/2026-09-13-gstack-playwright-lib-2220.md new file mode 100644 index 0000000..985a8bb --- /dev/null +++ b/.claude/tasks/contracts/2026-09-13-gstack-playwright-lib-2220.md @@ -0,0 +1,115 @@ +# CONTRACT — gstack-playwright-lib +- date: 2026-09-13 | flow: feat | branch: feature/gstack-playwright-lib +- status: active + +## REQUEST (verbatim — IMMUTABLE) + +Message 1: +> l'installation de chromium, c'est une version fix ou en latest ? Il faudrait mettre en lateste, et d'ailleurs son update est pris en compt dans l'update ? quelq version a besoin gstack ? Ca serait pas plus simple d'installer perplexity a la place ? + +Message 2 (after the assistant proposed fix A + fix B): +> les deux + +Message 3 (answer to the scope question on fix B, after the "654 Mo orphelins" +premise was proven wrong): +> Check read-only dans doctor.sh + +## CLARIFICATIONS + +Q: "mettre en latest" — pin Chromium to latest? +A: Not actionable as asked. Playwright downloads the browser revision its own + version pins (1.61.1 → chromium 1228); the CDP client is coupled to that + build. "Latest" = track the latest Playwright, which is what BDR-029's bump + already does. No change to the pinning mechanism is in scope. + +Q: Volet B — purge the orphan Playwright revisions? +A: Superseded by evidence. `~/.cache/ms-playwright/.links/` registers THREE + playwright installs (gstack 1.61.1 → rev 1228; gsd-pi nvm 1.61.0 → 1228; + gsd-pi ~/.local 1.63.0 → 1243). Every directory on disk is referenced; + zero bytes reclaimable. Playwright already GCs correctly on every + `install` (`_deleteStaleBrowsers`, unions across all registered installs). + User chose: read-only report in doctor.sh, NO deletion anywhere. + +## ACCEPTANCE CRITERIA + +1. `lib/gstack-playwright.sh` exists, is source-safe (sourcing prints nothing + and runs no side effect), and its verb dispatcher works when executed. + CHECK: out=$( . lib/gstack-playwright.sh; echo READY ); [ "$out" = READY ] && bash lib/gstack-playwright.sh 2>&1 | grep -q 'usage:' && echo LIB_OK + EXPECT: LIB_OK + EVIDENCE: MET exit=0 marker-found :: LIB_OK + +2. The bump logic lives ONLY in the lib: `install-plugins.sh` no longer + defines `gstack_bump_playwright_if_unsupported`, sources the lib instead, + and still calls it BEFORE gstack `./setup` (BDR-029 behavior unchanged: + OS-gated, idempotent, non-fatal). + CHECK: grep -q '^gstack_bump_playwright_if_unsupported() {' install-plugins.sh && exit 1; grep -q 'lib/gstack-playwright.sh' install-plugins.sh || exit 1; c=$(grep -n 'gstack_bump_playwright_if_unsupported' install-plugins.sh | grep -v ':[[:space:]]*#' | tail -1 | cut -d: -f1); s=$(grep -n '&& \./setup)' install-plugins.sh | head -1 | cut -d: -f1); [ -n "$c" ] && [ -n "$s" ] && [ "$c" -lt "$s" ] && echo EXTRACT_OK + EXPECT: EXTRACT_OK + EVIDENCE: MET exit=0 marker-found :: EXTRACT_OK + +3. `update-all.sh` delegates the gstack submodule update to the lib + (`gstack_submodule_update_with_bump`) instead of calling + `git submodule update --remote` bare, so the bump is re-applied after every + successful update. + CHECK: grep -q 'gstack_submodule_update_with_bump' update-all.sh && grep -q 'lib/gstack-playwright.sh' update-all.sh && ! grep -qE '^[[:space:]]*if git submodule update --remote skills-external/gstack' update-all.sh && echo WIRED_OK + EXPECT: WIRED_OK + EVIDENCE: MET exit=0 marker-found :: WIRED_OK + +4. [gated 2026-09-15] `gstack_submodule_update_with_bump` NEVER modifies the + submodule working tree. On a successful `git submodule update --remote` it + re-applies the bump; on failure it returns non-zero, touches nothing, and + emits git's own message plus a hint naming the local Playwright bump when + `package.json`/`bun.lock` are the dirty files. The conflict-RECOVERY branch + of the earlier revision (discard, retry, backup, restore) is withdrawn: it + could leave the bump discarded and un-reapplied, regressing a working + browser into BLK-008, which the pre-existing behavior never did. + CHECK: sed 's/#.*//' lib/gstack-playwright.sh | grep -qE 'git [^|;]*(checkout|reset|clean|stash)' && exit 1; bash lib/tests/gstack-playwright.test.sh 2>&1 | grep -q 'update-conflict' && bash lib/tests/gstack-playwright.test.sh 2>&1 | grep -qE '^PASS=[0-9]+ FAIL=0$' && echo NONDESTRUCTIVE_OK + EXPECT: NONDESTRUCTIVE_OK + EVIDENCE: MET exit=0 marker-found :: NONDESTRUCTIVE_OK + +5. `doctor.sh` prints a Playwright-browsers section: total cache size, one line + per browser directory naming the registered playwright install(s) that + reference it, plus counts of unreferenced directories and broken links. + CHECK: bash doctor.sh 2>/dev/null | grep -qi 'playwright browsers' && bash lib/gstack-playwright.sh browsers-report | grep -qE 'chromium-[0-9]+' && bash lib/gstack-playwright.sh browsers-report | grep -qi 'unreferenced' && echo REPORT_OK + EXPECT: REPORT_OK + EVIDENCE: MET exit=0 marker-found :: REPORT_OK + +6. The report is provably read-only: no destructive verb anywhere in the lib, + and the cache directory listing is identical before and after a report run. + CHECK: sed 's/#.*//' lib/gstack-playwright.sh | grep -qwE '(rm|rmdir|unlink|truncate|mv)' && exit 1; b=$(ls -la ~/.cache/ms-playwright ~/.cache/ms-playwright/.links 2>/dev/null | cksum); bash lib/gstack-playwright.sh browsers-report >/dev/null 2>&1; a=$(ls -la ~/.cache/ms-playwright ~/.cache/ms-playwright/.links 2>/dev/null | cksum); [ "$b" = "$a" ] && echo READONLY_OK + EXPECT: READONLY_OK + EVIDENCE: MET exit=0 marker-found :: READONLY_OK + +7. `lib/tests/gstack-playwright.test.sh` exists, passes, and covers at least: + bump skipped when the OS tag is already supported; bump fired when it is + not; submodule-update conflict recovery; browsers-report on a fixture cache + holding a referenced revision, an unreferenced one and a broken link. + CHECK: bash lib/tests/gstack-playwright.test.sh | tail -1 | grep -qE '^PASS=[0-9]+ FAIL=0$' && echo TESTS_OK + EXPECT: TESTS_OK + EVIDENCE: MET exit=0 marker-found :: TESTS_OK + +8. shellcheck clean on every touched shell file. + CHECK: shellcheck lib/gstack-playwright.sh lib/tests/gstack-playwright.test.sh install-plugins.sh update-all.sh doctor.sh >/dev/null 2>&1 && echo SHELLCHECK_OK + EXPECT: SHELLCHECK_OK + EVIDENCE: MET exit=0 marker-found :: SHELLCHECK_OK + +9. [gated 2026-09-15] (judgement) No new dependency; the report degrades + silently when `~/.cache/ms-playwright` is absent, when its `.links` + directory is absent, when `PLAYWRIGHT_BROWSERS_PATH` is `0` or not a + directory, or when no playwright install is registered — doctor must stay + green on a machine that never installed a browser. The lib's printers are + named `_gspw_ok`/`_gspw_warn`/`_gspw_info` and it defines NO bare + `ok`/`warn`/`info`/`pass`/`fail`: doctor.sh sources the lib before every + check, so bare names would override its own printers and silently + disconnect its `ERRORS`/`WARNS` counters. + +## FILE SCOPE + +- lib/gstack-playwright.sh (new) +- lib/tests/gstack-playwright.test.sh (new) +- install-plugins.sh (remove inline fn, source + call lib) +- update-all.sh (call bump + conflict recovery) +- doctor.sh (new read-only report section) + +Out of scope: the gstack submodule itself, the pinning mechanism, any +deletion of cached browsers, the `GSTACK_CHROMIUM_NO_SANDBOX` layer +(LRN-040 layer 2, unchanged). diff --git a/.claude/tasks/plans/2026-09-13-gstack-playwright-lib-2220.md b/.claude/tasks/plans/2026-09-13-gstack-playwright-lib-2220.md new file mode 100644 index 0000000..5f4e8d5 --- /dev/null +++ b/.claude/tasks/plans/2026-09-13-gstack-playwright-lib-2220.md @@ -0,0 +1,201 @@ +# PLAN — gstack-playwright-lib (feat) — REVISION 3 + +Contract: `.claude/tasks/contracts/2026-09-13-gstack-playwright-lib-2220.md` +Revision 3 (2026-09-15). Rev 1 → 3-lens challenge → rev 2 → confirmation pass +→ rev 3. The conflict-RECOVERY branch is WITHDRAWN at the human gate: it +concentrated 3 BLOCKERs and 4 MAJORs, and its worst case regressed a working +browser into BLK-008, which the pre-existing behavior never did. + +## Context + +- Chromium is not an apt package. It is the browser revision pinned by the + installed Playwright (`gstack/setup:483`). gstack: playwright 1.61.1 → + chromium rev 1228 (`Chrome for Testing 149`). +- `~/.cache/ms-playwright/.links/` registers 3 playwright installs: gstack + 1.61.1 (1228), gsd-pi nvm 1.61.0 (1228), gsd-pi ~/.local 1.63.0 (1243). + Every dir on disk is referenced → 0 bytes reclaimable. Playwright already + prunes correctly on every `install` (`_deleteStaleBrowsers`). No pruner is + written here. +- The gstack submodule is intentionally dirty: `package.json` + `bun.lock` + carry the BDR-029 bump; `.gitmodules` sets `ignore = dirty`. It also carries + an untracked `?? bin/bin`. +- `update-all.sh:87` calls `git submodule update --remote` bare, swallows + stderr, and never re-applies the bump afterwards. THAT is the gap. + +## Hard constraints the code must respect + +**Inherited errexit.** All three callers run `set -euo pipefail` and source +the lib. `gstack_bump_playwright_if_unsupported` and `gstack_browsers_report` +are called as bare statements, so they MUST `return 0` on every path and every +capture inside them takes `|| true`. +`gstack_submodule_update_with_bump` is the ONE exception: it returns non-zero +on failure and is therefore called ONLY as an `if` condition, keeping +`update-all.sh:87`'s existing `if / else warn` shape. An offline update stays +non-fatal, exactly as today. + +**Printer names.** The lib defines `_gspw_ok`, `_gspw_warn`, `_gspw_info` and +NEVER a bare `ok`/`warn`/`info`/`pass`/`fail`. `doctor.sh:22` sources the lib +before every check, so bare names would override `doctor.sh:12-15` and +silently disconnect its `ERRORS`/`WARNS` counters. + +**No destructive command in the lib, at all.** No `rm`, `rmdir`, `unlink`, +`truncate`, `mv`, and no `git checkout`/`reset`/`clean`/`stash`. Contract +criteria 4 and 6 both grep for this. + +**macOS-safe.** No `timeout` without a `command -v` guard (absent from stock +macOS), no `readlink -f` (absent before Monterey 12.3), no `md5sum`, no +`sed -i` without a suffix, no bash-4-only expansions (`${x,,}`), no `grep -P`. + +## Files + +1. `lib/gstack-playwright.sh` — NEW. Sourceable lib + verb dispatcher. No + `set -euo pipefail` at top level (mirrors `lib/detect-plugins.sh`). + Dispatcher guarded by `[ "${BASH_SOURCE[0]}" = "${0}" ]`, exposing + `browsers-report` ONLY. Any other argument → `usage:` on stderr, exit 2. + The write functions stay sourced-only: a CLI verb would expose + `bun add playwright@latest` as a command-line entry point. + + - `_gspw_ok` / `_gspw_warn` / `_gspw_info ` — fixed-prefix printers. + - `gstack_pw_ostag [os_release_path]` — prints `ubuntu` for + Ubuntu, nothing otherwise. The capture takes `|| true`: the moved line + exits 1 on every non-Ubuntu host and would abort the caller under + inherited errexit. `return 0` always. + - `gstack_pw_supports ` — 0/1 by grep. + - `gstack_bump_playwright_if_unsupported ` — BDR-029 logic, + parameterized. Prepends `$HOME/.bun/bin` to PATH when `bun` is not + resolvable (LRN-036). Wraps ALL THREE bun invocations + (`bun install --frozen-lockfile`, the `bun install` fallback, + `bun add playwright@latest`) in `timeout 300` when `command -v timeout` + succeeds, plain otherwise. Exit 124 from any of them → `_gspw_warn` and + `return 0` WITHOUT attempting the bump: a TERM'd install leaves + `node_modules` half-written, and the support grep would then read a + truncated tree. One `_gspw_info` line before the network work so a + stalled registry is visible. `return 0` on every path (BDR-029 + non-fatal). + - `gstack_submodule_update_with_bump [sub_path]`: + 1. `git -C "$repo" submodule update --remote "$sub"`, stderr captured. + 2. exit 0 → `gstack_bump_playwright_if_unsupported "$repo/$sub"` → + `return 0`. + 3. exit != 0 → `_gspw_warn` with git's own message, verbatim and + unparsed. Then, when `git -C "$sub" status --porcelain -- + package.json bun.lock` is non-empty, one extra `_gspw_info` hint line + naming the local Playwright bump and pointing at `make plugin`. + `return 1`. NOTHING in the working tree is touched. + No locale pin is needed: git's message is displayed, never parsed for a + decision. The hint is advisory, so its constant-true condition is + correct here, unlike the withdrawn recovery branch where it gated a + destructive step. + - `_gspw_browser_referenced ` — does that + install require this cache directory? Splits `` into name + + revision on the LAST `-`, then normalizes `_` → `-` on the name + (Playwright writes `chromium_headless_shell-1228` while `browsers.json` + says `chromium-headless-shell`; without this, two live directories are + reported unreferenced forever). Matches the base `revision` OR any value + under that browser's `revisionOverrides` (webkit and ffmpeg carry them + for mac and debian11 and ubuntu20.04 hosts). awk only: no jq, no + python3, no fallback ladder. + - `_gspw_install_label ` — ` + `, e.g. `gstack 1.61.1`, `gsd-pi 1.63.0`. + - `gstack_browsers_report [cache_dir]` — read-only. Resolves the cache as + `${1:-${PLAYWRIGHT_BROWSERS_PATH:-$HOME/.cache/ms-playwright}}`; the + documented value `0` means "bundle into node_modules", so `0` and any + non-directory degrade to the silent no-cache path. Prints the header + `Playwright browsers`, the total from `du -sh … || true`, one line per + cache dir matching `*-` with the installs requiring it, then + ` unreferenced, broken link(s)`. When N or M > 0, one + `_gspw_warn` naming them and the remedy, phrased without the words `rm` + or `mv` (criterion 6 word-greps the source): "re-run `playwright + install`, which prunes stale revisions". A dir whose NAME is listed by + some install but at another revision counts as `unknown revision`, not + unreferenced. `return 0` on every path. + +2. `install-plugins.sh` — delete the inline function (294-321), source the lib + next to detect-plugins (line 30), call site at ~370 becomes + `gstack_bump_playwright_if_unsupported "$GSTACK_DIR"`. + +3. `update-all.sh` — source the lib next to detect-plugins (line 19). Line 87 + becomes `if gstack_submodule_update_with_bump "$REPO"; then` and the + existing `else warn …` arm is KEPT verbatim. No other structural change. + +4. `doctor.sh` — source the lib next to detect-plugins (line 22). Add its own + `── Playwright browsers ──` section (NOT nested under gstack: 2 of the 3 + registered installs are gsd-pi), called as `gstack_browsers_report || true`. + +5. `lib/tests/gstack-playwright.test.sh` — NEW, auto-globbed by `make test`. + +## Edge cases + +- Every public function except the update returns 0 under the callers' + `set -euo pipefail`, including the all-zero-counts case, which is this + machine's nominal state and would otherwise kill `doctor.sh` before its + summary and take `update-all.sh:519` down with it. +- `.links` entry whose target is gone or whose `browsers.json` is unreadable + → counted as a broken link, never dereferenced further. +- Two installs of the same tool at different versions → both labels listed. +- gstack submodule absent → bump and update both no-op 0. +- Sourcing the lib prints nothing and does not change the caller's options. + +## Tests (`lib/tests/gstack-playwright.test.sh`) + +Shape of `lib/tests/fast-libs.test.sh` (`check` helper, `PASS=n FAIL=n` last +line, `mktemp -d` + trap). git 2.53 defaults `protocol.file` to `user`, which +blocks submodule clone and fetch. The fixture git calls are not enough: the +`git submodule update --remote` under test runs INSIDE the lib, in a fresh +process. So the test exports, for the whole test process, +`GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=protocol.file.allow +GIT_CONFIG_VALUE_0=always`, which the lib's own git inherits. Fixtures use +`git init -b main` with `submodule..branch = main` set explicitly, so +`--remote` resolves the way production does. + +- `T1-ostag-ubuntu` / `T2-ostag-other`: fixture os-release files. +- `T3-errexit-safe`: the bump called as a bare statement under + `set -euo pipefail` with a non-Ubuntu os-release → the script reaches the + next line. Regression test for the latent abort. +- `T4-supports-hit` / `T5-supports-miss`: fixture lib dir with and without the + tag. Proves idempotence both ways without invoking bun. +- `T6-update-success-bumps`: fixture superproject + submodule, an upstream + commit, bump stubbed by redefining it after sourcing → update succeeds, the + stub ran once, returns 0. +- `T7-update-conflict-nondestructive`: local edit to the submodule's + `package.json` plus a conflicting upstream commit → returns non-zero, BOTH + bump-owned files are byte-identical to before the call, and the hint line + was printed. Carries the literal `update-conflict` (contract criterion 4). +- `T8-no-destructive-command`: greps the lib source for `git + checkout|reset|clean|stash` and for `rm|rmdir|unlink|truncate|mv` outside + comments. Stronger than criterion 6 alone. +- `T9-report-referenced`, `T10-report-underscore-dir` + (`chromium_headless_shell-1228` against a `chromium-headless-shell` entry), + `T11-report-unreferenced`, `T12-report-broken-link`, + `T13-report-revision-override`: fixture cache + `.links` → fixture + playwright-core dirs with hand-written `browsers.json`. +- `T14-report-zero-counts-exit-0`: everything referenced → exit 0. The nominal + case, not covered by the absent-dir case. +- `T15-report-no-cache` / `T16-report-browsers-path-zero`: exit 0, nothing on + stderr. +- `T17-source-safe`: sourcing emits nothing. + +## Disposition (STEP 0.6) + +- honors **BDR-029** by keeping the bump OS-gated, idempotent, non-fatal, and + by closing its stated caveat: the bump is now re-applied after every + successful update, not only at the next `make plugin`. +- honors **LRN-024** by extracting a helper and refactoring the existing + caller before adding the other callers. Deviations from "code MOVED not + changed" are named: `|| true` on the ostag capture (a latent abort on every + non-Ubuntu host, reproduced), and the `timeout` guard. +- honors **LRN-070** by never touching the submodule working tree at all. The + revision that did (discard, retry, restore) was withdrawn at the gate. +- honors **LRN-071** (recurrent 3x) by returning the update's real status, not + a non-fatal helper's 0. +- honors **LRN-040** by touching layer 1 only; `GSTACK_CHROMIUM_NO_SANDBOX` + is untouched. +- honors **LRN-085** by keeping the update idempotent, presence-guarded, no + `--force`. +- honors **LRN-036** by putting `$HOME/.bun/bin` on PATH inside the lib. +- honors **LRN-002** by grepping the moved function name repo-wide, readers + included. +- **LRN-038** already seen: the host-platform override is a dead end. +- BDR-029's reference line (`decisions.md:544`) and BLK-008's caveat + (`blockers.md:118`) describe behavior this plan changes. Registries are + append-only, so the plan does NOT edit them: the /feat CAPITALIZE step + owns the superseding entry.