Read every release's notes between current (exclusive) and target
(inclusive) — not just the target's diff summary, since intermediate
point releases can carry changes too:
gh release list --repo openclaw/openclaw --limit 20
gh release view v<version> --repo openclaw/openclaw
Read the full text, not just headline "Highlights" — the "Additional ...
fixes" subsections often contain the entry that actually matters to us.
Work through it against these four questions, in this order, and write
down what you find for each before moving to step 3:
a. Incompatibility risk. Anything touching session keys, tools.allow
semantics, config.apply timing, plugin config/manifest resolution, or
provider baseUrl handling — the areas that have bitten us before (see
reference_oc_* / reference_openclaw_* memory entries). Look at
sections titled "Sessions", "Gateway, Security, and Trust", "Plugins and
Packaging", and any breaking/migration language anywhere else. Watch
especially for new gateway-startup / config self-healing behavior — these
don't show up in pnpm test/tsc at all and only fail in the docker E2Es.
The agent:bootstrap hook contract is one of these silent dependencies.
config/pinchy-hooks/bootstrap-memory-group-filter/ (the #369 leak fix)
assumes the event carries context.bootstrapFiles (array) and
context.sessionKey (string), that reassigning context.bootstrapFiles is
read back by the caller, and that internal hooks load via native import().
If the notes touch bootstrap/hook events, session-key shape, or the internal
hook loader, verify against the installed dist that these still hold — the
hook now console.warns instead of failing open, so also check the gateway
logs on the staging deploy for that warning. A silent contract change here
re-opens a P0 eu-ai-act memory leak. See the hook's HOOK.md Verification
section for the exact staging check.
Real example the 2026.6.11 bump tripped: OpenClaw 2026.6.x added startup
config auto-restore — on a size-drop / missing-meta vs last-known-good it
restores openclaw.json.last-good over openclaw.json at gateway start
(recoverConfigFromLastKnownGood). This broke the setup-wizard reset (it
deleted openclaw.json but not the backups, so OC restored the prior test's
config referencing wiped secrets → crash-loop). If notes mention config
backup / last-known-good / recovery / restore, expect the setup-wizard +
integration E2Es to need reset-choreography updates.
b. Resolved issues we have workarounds for. Grep our own code for
the upstream issue/PR numbers and version-guard comments before reading
notes:
git grep -rniE "openclaw/openclaw#[0-9]+|openclaw issue|version.?guard|workaround|TODO\(#" -- packages/ config/ | grep -vi node_modules
For each hit, check the upstream issue state (gh issue view <n> --repo openclaw/openclaw --json state,closedAt). But "issue closed" is
necessary, not sufficient — a closed issue is where naive audits go
wrong. Before removing any workaround, confirm ALL of:
- The fix shipped in a release ≤ our target pin. Close date ≠ release
date, and release notes often don't name the issue. When in doubt,
inspect the actually-installed bundle in
node_modules/.pnpm/openclaw@<target>/node_modules/openclaw/dist for
the fixed code, not just the changelog.
- The fix targets OUR code path, not a sibling. Real example: openclaw
#75534 (config.apply no-op restart, tracked on our side by #215) fixed
OpenClaw's own
writeConfigFile short-circuit — but Pinchy writes the
config file itself and then calls config.apply, a different path whose
env.*→default-restart mechanism was still present verbatim in
2026.6.11. Issue closed, workaround NOT removable.
- The workaround is actually a bug-workaround, not a defensive
error-UX classifier or an architectural decoupling that stays valuable
after the bug is fixed. Real examples that are NOT removable-on-close:
the
thought_signature error classifier (model-error-classifier.ts,
#338 — renders graceful UX whenever the upstream error surfaces, and its
removal is gated on an empirical live-path condition, not the issue
state), and the Telegram store-based allowFrom (#47458 — a
restart-avoiding design choice, see
reference_ollama_local_rewrite_decoupling.md for the "decoupling, not a
version workaround" pattern).
- Prefer the tracking issue's own stated verification (e.g. "remove X,
run E2E
agent-create-no-restart.spec.ts, confirm it stays green") over
bundle archaeology. Bundle-reading can prove a workaround is STILL needed
(mechanism present) but is weak evidence that one is safe to REMOVE —
that needs the prescribed test. Memory: reference_config_apply_rate_limit_drop.md
warns version guards can become bugs after an upstream fix, so this
cuts both ways.
If all four hold, remove the workaround in the same change with a test
proving native behavior now covers it. Otherwise leave it and record why.
c. Features we built ourselves that OpenClaw now does natively. Scan
for "native", new config keys, or new built-in capabilities in areas where
Pinchy has a bespoke plugin or workaround (e.g. transcript capture,
session identity, memory, approvals — see reference_pinchy_owned_transcript.md,
reference_openclaw_approval_primitives.md, reference_mcp_native_credential_proxy.md
for precedent: MCP was migrated from a Pinchy-built plugin to native
mcp.servers + a thin credential proxy once OpenClaw grew native support).
Same feature name ≠ same scope — check whether the native capability
covers the REASON we built the bespoke version, not just its surface.
Real example: 2026.6.10 added a native "session-transcript SDK" (read,
append, publish, lock), which sounds like it could replace pinchy-transcript.
But its methods are all keyed by { agentId, sessionKey, sessionId } —
session-scoped. Pinchy owns channel_messages precisely because it
needs a channel-lifetime record that survives /new/reset/compaction
(per PR #553 / reference_pinchy_owned_transcript.md); adopting the
session-scoped SDK would reintroduce the exact blank-on-/new bug it fixed.
So: not adoptable. If a native capability genuinely covers the reason,
flag it as a follow-up simplification; if it only matches the name, record
why it doesn't fit so the next bump doesn't re-litigate it.
d. New OpenClaw features worth exposing in Pinchy. Anything new that
fits Pinchy's enterprise-governance angle (permissions, audit, channels,
models) or that Pinchy's target audience (self-hosted enterprise teams,
see "Product Context" in AGENTS.md) would plausibly want surfaced in the
UI/API. Note these separately as feature ideas — they are out of scope
for the bump itself, not blockers.
