Windows: session_start hook dies with UnicodeEncodeError ('charmap' can't encode U+27E6 ⟦) — entire SessionStart memory injection lost

[mbe14]

Environment: Windows 11 Pro (build 26200), Python 3.13.13, cortex plugin 4.13.0 installed through the marketplace, Western locale (ANSI code page 1252). Same box as #91–#95.

Symptom

Every Claude Code session start shows:

SessionStart:startup hook error
Failed with non-blocking status code: [cortex-launcher] Failed to run mcp_server.hooks.session_start: 'charmap' codec can't encode character '⟦' in position 25: character maps to <undefined>

and — the actual damage — no memory context is injected at all. The whole SessionStart banner (anchors, hot memories, checkpoint, grooming line) is silently lost on Windows.

Root cause

The generic wrapper at scripts/launcher.py:320 is just reporting an exception raised inside the hook. The real crash site is print(context) in mcp_server/hooks/session_start.py (~line 1089).

The banner header is:

## Cortex Memory Context ⟦rcpt:N⟧

"## Cortex Memory Context " is exactly 25 characters, so position 25 is U+27E6 ⟦ — the injection-receipt marker. The hook's stdout is a pipe (Claude Code's hook runner), so CPython encodes it with the locale/ANSI code page (charmap → cp1252) unless PYTHONUTF8/PYTHONIOENCODING is set, and cp1252 has no ⟦.

The receipt marker makes the crash deterministic on every start, but any non-cp1252 character in injected memory content (→, ✅, non-Latin scripts…) triggers the same failure — and auto_recall emits ⟦rcpt:…⟧ markers too, so the UserPromptSubmit injection path is exposed the same way.

Repro (A/B)

# stdout is a pipe, like under the hook runner
echo '{"session_id":"t","cwd":"C:\\src\\myproject"}' | \
  python3 scripts/launcher.py mcp_server.hooks.session_start > out.txt 2>&1
echo $?   # 1; out.txt ends with the charmap UnicodeEncodeError

echo '{"session_id":"t","cwd":"C:\\src\\myproject"}' | \
  PYTHONUTF8=1 python3 scripts/launcher.py mcp_server.hooks.session_start > out.txt 2>&1
echo $?   # 0; out.txt contains the full banner: "## Cortex Memory Context ⟦rcpt:18⟧ …"

Suggested fix

One choke point covers the server and every hook — at the top of main() in scripts/launcher.py:

for stream in (sys.stdout, sys.stderr):
    try:
        stream.reconfigure(encoding="utf-8", errors="replace")
    except Exception:
        pass

Claude Code consumes hook stdout as UTF-8, so the ⟦rcpt:N⟧ markers round-trip fine once they can actually be encoded (verified with the PYTHONUTF8=1 run above — the injected banner renders correctly).

Workaround

"env": { "PYTHONUTF8": "1" } in Claude Code's settings.json — works, but every Windows user hits this out of the box until the launcher sets the encoding itself.

[cdeust]

Fixed on main (80bf474b). Your diagnosis was exact — position 25 is the receipt marker, and the pipe fallback to the locale code page is the mechanism. The fix is your suggested choke point: launcher.py::main() now calls stream.reconfigure(encoding="utf-8", errors="replace") on stdout+stderr before anything else (per-stream try/except), which covers the MCP server, all 8 hooks, and both detached background workers — verified every entry point routes through this launcher. Repro validated here by forcing PYTHONIOENCODING=cp1252 through a pipe: your exact error before the fix, exit 0 + UTF-8 marker bytes after.

Same epistemic caveat as #91–#95: no Windows box here — we forced the codec, not the OS. If you can replay your A/B (hook through a pipe, no PYTHONUTF8) on main, that confirmation closes this. Ships in the next plugin release.

[cdeust]

v4.13.1 is out with this fix — please verify on the installed release rather than main: https://github.com/cdeust/Cortex/releases/tag/v4.13.1

[mbe14]

Confirmed fixed on the real box — Windows 11 Pro (build 26200), cp1252 locale, Python 3.13.13, plugin updated 4.13.0 → 4.13.1 through the marketplace.

A/B replayed as requested — session_start hook through a pipe, PYTHONUTF8 and PYTHONIOENCODING both unset:

• 4.13.0 (control): exit 1 — [cortex-launcher] Failed to run mcp_server.hooks.session_start: 'charmap' codec can't encode character '⟦' in position 25 (byte-identical to the original report).
• 4.13.1: exit 0, full banner emitted. Hexdump of the captured stdout shows the receipt marker as genuine UTF-8:

436f 7274 6578 204d 656d 6f72 7920 436f  Cortex Memory Co
6e74 6578 7420 e29f a672 6370 743a 3234  ntext ...rcpt:24

e2 9f a6 = U+27E6 ⟦, so the marker round-trips instead of killing the hook. The 4.13.1 run was end-to-end through launcher.py (fresh deps dir, full bootstrap, DB-backed banner), not a unit-level probe.

The "env": {"PYTHONUTF8": "1"} settings.json workaround is no longer needed on 4.13.1 (I'm keeping it as belt-and-braces; it coexists fine). Good to close from my side.

[cdeust]

Closing on your real-box A/B — byte-identical control failure on 4.13.0 and the hexdump showing the marker round-tripping as genuine UTF-8 on 4.13.1 is exactly the falsifiable confirmation this needed. Thanks as always for the position-25 precision that made it a one-pass fix.