5chan/docs/agent-playbooks/known-surprises.md

Known Surprises

This file tracks repository-specific confusion points that caused agent mistakes.

Entry Criteria

Add an entry only if all are true:

• It is specific to this repository (not generic advice).
• It is likely to recur for future agents.
• It has a concrete mitigation that can be followed.

If uncertain, ask the developer before adding an entry.

Entry Template

### [Short title]

- **Date:** YYYY-MM-DD
- **Observed by:** agent name or contributor
- **Context:** where/when it happened
- **What was surprising:** concrete unexpected behavior
- **Impact:** what went wrong or could go wrong
- **Mitigation:** exact step future agents should take
- **Status:** confirmed | superseded

Entries

Android release signing still uses legacy keystore names

• Date: 2026-04-23
• Observed by: Codex
• Context: Cutting the v0.8.0 release after the core terminology rename changed release workflow signing references.
• What was surprising: The tracked Android release keystore is still android/plebbit.keystore, and the available GitHub secret is still PLEBBIT_REACT_KEYSTORE_PASSWORD; changing only the workflow references to bitsocial.keystore / BITSOCIAL_KEYSTORE_PASSWORD made the Android release artifact fail at signing.
• Impact: Tag releases can pass the Android build and then fail before publishing because apksigner cannot find the keystore or password secret.
• Mitigation: Until the keystore migration is done, keep release APK signing pointed at android/plebbit.keystore and PLEBBIT_REACT_KEYSTORE_PASSWORD. If renaming, migrate the tracked file, workflow path, and GitHub secret in one change and verify with a tag release dry run or full release.
• Status: confirmed

5chan consumes a pinned hooks tarball instead of using the local hooks repo

• Date: 2026-04-15
• Observed by: Codex
• Context: Debugging strict {name, publicKey} community refs after upstream fixes landed in bitsocial-react-hooks
• What was surprising: 5chan does not consume the nearby /Users/Tommaso/Desktop/bitsocial/bitsocial-react-hooks checkout by default; package.json installs a pinned GitHub tarball of @bitsocialnet/bitsocial-react-hooks.
• Impact: Agents can wrongly assume local hooks source changes are already active in 5chan, or debug the wrong package build when the app is really running a tarball revision from GitHub.
• Mitigation: Before debugging hooks behavior from 5chan, check package.json to see whether the app points at a tarball commit or a local path. If you need fresh hooks behavior, update the tarball commit or temporarily switch 5chan to a local path intentionally.
• Status: confirmed

Hooks source commits can land before the generated tarball payload

• Date: 2026-04-18
• Observed by: Codex
• Context: 5chan CI failed after expandTimeWindow landed in bitsocial-react-hooks because the app was pinned to the feature source commit.
• What was surprising: bitsocial-react-hooks uses dist/ as its published entrypoint, and the repo's CI writes that generated payload in a follow-up chore(ci): update dist and coverage badge commit after the source commit lands on master.
• Impact: Pinning 5chan to the feature source SHA can install a tarball whose runtime and typings still omit the new API, causing downstream type errors even though the hooks repo's source and CI look green.
• Mitigation: When updating 5chan to a new hooks change, verify whether hooks master has a newer follow-up chore(ci): update dist and coverage badge commit and pin 5chan to that dist-synced SHA rather than the source-only SHA.
• Status: confirmed

Portless breaks Windows installs

• Date: 2026-03-04
• Observed by: Codex
• Context: GitHub Actions Test Windows dependency install on windows-2022
• What was surprising: portless@0.5.2 is a local dev-only tool, but keeping it in devDependencies makes yarn install fail on Windows because the package declares win32 unsupported.
• Impact: Windows CI fails before build steps run, even though the app does not need portless there.
• Mitigation: Keep portless in optionalDependencies and make yarn start fall back to direct vite startup when portless is unavailable.
• Status: confirmed

Electron RPC uses direct pkc-js imports

• Date: 2026-03-07
• Observed by: Codex
• Context: The desktop bootstrap now imports @pkcprotocol/pkc-js/rpc directly from electron/start-pkc-rpc.js.
• What was surprising: Most app data access still goes through @bitsocialnet/bitsocial-react-hooks, but the Electron-local RPC bootstrap is intentionally a direct pkc-js integration.
• Impact: Agents may try to route Electron RPC back through hooks, or reintroduce the legacy protocol package name while fixing dependency/tooling warnings.
• Mitigation: Keep Electron RPC on direct @pkcprotocol/pkc-js imports. If knip flags electron/start-pkc-rpc.js, audit the actual dependency graph before adding ignores or legacy packages.
• Status: confirmed

Electron packaging can ship a broken better-sqlite3 binary

• Date: 2026-03-17
• Observed by: Codex
• Context: Investigating the v0.7.1 macOS arm64 DMG after the app showed a live IPFS node but never loaded boards or comments.
• What was surprising: The packaged app can start IPFS successfully while electron/start-pkc-rpc.js loops forever because /Applications/5chan.app/.../better_sqlite3.node was built for plain Node 22 (NODE_MODULE_VERSION 127) instead of Electron 36 (NODE_MODULE_VERSION 135).
• Impact: The local RPC server on ws://localhost:9138 never starts, so the desktop app cannot load boards, posts, or comments even though node stats look healthy.
• Mitigation: Before any Electron package/build job, run yarn electron:prepare-package so better-sqlite3 is rebuilt for Electron and immediately verified via ELECTRON_RUN_AS_NODE=1 electron.
• Status: confirmed

Plain Vite fallback used to hard-fail on port 1355

• Date: 2026-03-30
• Observed by: Codex
• Context: Running PORTLESS=0 yarn start while another local service already owned port 1355
• What was surprising: The non-Portless dev fallback forced Vite onto 5chan.localhost:1355 with --strictPort, so the fallback path could fail immediately even though the main Portless flow is collision-safe.
• Impact: Contributors could lose the fallback dev path or interrupt their startup flow when 1355 was already busy.
• Mitigation: Keep the fallback behind scripts/start-dev.js, which now probes from 1355 upward and starts Vite on the next free port instead of exiting.
• Status: confirmed

Fixed Portless app names collide across 5chan worktrees

• Date: 2026-03-30
• Observed by: Codex
• Context: Starting yarn start in one 5chan worktree while another 5chan worktree was already serving through Portless
• What was surprising: Using the literal Portless app name 5chan in every worktree makes the route itself collide, even when the backing ports are different, so the second process fails with "5chan.localhost" is already registered.
• Impact: Parallel 5chan branches can block each other even though Portless is meant to let them coexist safely.
• Mitigation: Keep Portless startup behind scripts/start-dev.js, which now uses a branch-scoped *.5chan.localhost:1355 route outside the canonical case and automatically increments a -2, -3, ... suffix when that branch-scoped route is already occupied.
• Status: confirmed

Toolchain model names are not interchangeable

• Date: 2026-04-08
• Observed by: contributor + Codex
• Context: Reviewing repo-managed agent configs under .codex/agents, .cursor/agents, and .claude/agents
• What was surprising: composer-2 is only available for Cursor in this repo, while Codex agents using gpt-5.3-codex or gpt-5.3-codex-spark perform poorly enough that they should not be configured by default.
• Impact: Agents can silently inherit invalid or weak model settings, leading to broken subagent runs or degraded implementation quality.
• Mitigation: Keep .cursor agent configs on Cursor-supported models only, never use composer-2 in .claude, and standardize .codex/agents/*.toml on gpt-5.4 unless a contributor explicitly requests an override.
• Status: confirmed