soul.demarkus.io:6309/journal/2026-07-05.md/v5 draft reader meta

2026-07-05

Ergonomics release chain completed — all three legs shipped

Finished the release topology for the MCP client ergonomics work (#225):

  • Leg 1: client/v0.15.0 auto-released from the #225 merge.
  • Leg 2 (#226): clientVersion 0.13.2 → 0.15.0 in tools/demarkus-plugin/internal/provision/provision.go → auto-released tools/v0.4.1.
  • Leg 3 (#227): TOOLS_VERSION 0.3.5 → 0.4.1 in all four plugins' bootstrap.sh (lockstep, shared binary) + patch bumps: demarkus-memory 0.12.4, demarkus-knowledge 0.5.4, pi-memory 0.12.5, pi-knowledge 0.5.5, with CHANGELOG entries for the pi pair. Next session start re-provisions demarkus-plugin v0.4.1 → demarkus-mcp v0.15.0; outline mode, #section slicing, session dedup, and mark_explore now reach users.

Also fixed in #227: .claude-plugin/marketplace.json had been desynced since #217/#221 (still 0.12.2/0.5.2 while the plugin manifests were at 0.12.3/0.5.3) — the manual repins bumped the manifests but missed the marketplace. Synced to 0.12.4/0.5.4.

Open observations for later (not blocking):

  • The plugin-pin-bump workflow's daily runs have reported success since 07-02 without opening a PR, despite pins being behind released versions (client 0.14.0/0.15.0, server 0.19.0, tools 0.4.0/0.4.1 all newer than the pins at the time). Either changed=false is mis-computed in .github/scripts/bump-plugin-pins.sh or something in the PR step is short-circuiting — worth a debugging pass.
  • serverVersion pin still 0.18.0 (server/v0.19.0 released 07-02) and fallbackToolsVersion still 0.3.3 — both deliberately left out of the repin PRs to keep them narrow; decide whether to sweep them.

plugin-pin-bump silent failure: root-caused and fixed

The "workflow succeeds but no PR" mystery from this morning's loose ends: gh pr view "$branch" in the workflow's upsert step resolves closed PRs, so after #210 was closed unmerged it edited that dead PR daily instead of creating a new one. Proof: #210 (closed 06-24) carries a title naming server 0.19.0 (released 07-02) and updatedAt 07-03. Fix on branch fix/plugin-pin-bump-closed-pr: look up an OPEN PR via gh pr list --head … --state open and edit by number, else create. Verified both paths read-only against the live repo. Gotcha generalized in /debugging.md.

Once merged, dispatching the workflow will sweep the remaining stale pins (serverVersion 0.18.0 → 0.19.0, fallbackToolsVersion 0.3.3 → 0.4.1) via a proper auto PR — closing this morning's second loose end through the automation instead of another manual repin.

Automation restored — first proper bump PR since 06-24

#228 (the closed-PR upsert fix) merged; dispatched plugin-pin-bump and it opened #229 — the first real auto bump PR since #210 was closed. It sweeps serverVersion 0.18.0 → 0.19.0 and fallbackToolsVersion 0.3.3 → 0.4.1 plus lineage patch bumps; bootstraps stay at 0.4.1 (already current). Both of this morning's loose ends closed.

Merge note for #229: it updates source pins only. Plugin users still provision server 0.18.0 until a new tools release ships the updated provision.go and the bootstraps repin to it — the standing three-leg topology; the now-working daily automation opens that follow-up bump PR when the tools release appears. Script gap (cosmetic): auto bumps don't add pi CHANGELOG entries.

Wrap: #229 merged, loop fully closed

#229 merged (d0d4b2d) and — correcting the earlier merge note — the chore(plugins) commit DID auto-release tools/v0.4.2 (release tooling keys on module changes, not commit type). So server 0.19.0 + fallbackToolsVersion 0.4.1 are now baked into a shipped demarkus-plugin, and the next scheduled plugin-pin-bump run (daily 07:23 UTC) will see tools 0.4.2 ≠ bootstrap pin 0.4.1 and open the bootstrap repin PR on its own. From here the pin pipeline is fully self-driving again: release → auto bump PR → merge → repeat. Day's arc: ergonomics phase shipped to users (#225/#226/#227), pin automation un-wedged (#228), stale pins swept (#229).

Broker gateway ergonomics parity built (feature/broker-ergonomics-parity)

Ported the client ergonomics to the broker MCP gateway so knowledge-system agents get the same surface; awaiting Fritz's commit.

  • Shared code (D4 payoff): the tools module already imports client, so the new client/mdoutline/render.go (OutlineBody, LinkLines, CappedList) is consumed by BOTH client cmd and broker — client's local copies were refactored out, no duplication.
  • W1: broker handleMarkFetch moved to mcp_tools_fetchmode.go with outline mode, #anchor slicing, force. Fragments are cut BEFORE parseToolURL (which rejects them for the other verbs by design — for fetch the fragment now has defined meaning).
  • W3 with the multi-tenant twist: dedup keyed by MCP session ID (ClientSessionFromContext), nested map sessionID → world+path → (version,etag). No session → no dedup, never a cross-user "unchanged". Eviction via Hooks.AddOnUnregisterSession; caps (4096 sessions × 1024 docs) bound memory if a transport never unregisters — beyond cap it degrades to no-dedup, not eviction of someone else's state.
  • W2: mark_explore (16th tool; mcpToolNames + handler map + count test 15→16). Backlinks from the broker's ephemeral per-pod graph store with an honest reset note; siblings via dispatcher LIST, degrades on failure.
  • W4: description pass mirrored (fetch/lookup/list/backlinks + explore).
  • Proof of session scoping end-to-end: a new HTTP-level test drives initialize → Mcp-Session-Id → two tools/call fetches (second returns status: unchanged) → second initialize gets a fresh session and the full body. Not just a hand-attached session in ctx.

The gateway's fidelity contract is untouched — formatToolResult unchanged; the new modes compose via a mirrored formatToolResultWith (cloned metadata, never mutates the response map).

trail
  1. soul.demarkus.io:6309 v5