# Lessons
- 2026-07-14: If the Codex terminal loses focus or stops accepting keyboard input, stop before any commit/install/config mutation and audit Terminal Commander for active command jobs, PTYs, file watches, and campaign helper processes. Resume only after all are zero. Never use direct command execution even for read-only skill files; route those reads through Terminal Commander so every process remains headless and accountable.
- 2026-07-14: Do not merge queued Dependabot or maintenance PRs while the active campaign still has uncommitted, unreviewed, undeployed, unverified, or uncleared work. Finish the current work end to end first; only then review and merge unrelated PRs.
- 2026-07-14: Terminal Commander's argv lane intentionally rejects shell interpreters, and its shell lane may be policy-disabled. Before proposing or attempting `command.exec`, check `policy_status`; when `allow_shell` is off, use the approved direct runner for the bounded shell-only operation instead of treating the rejection as a tool defect. For PowerShell scripts, avoid names that collide case-insensitively with automatic/read-only variables (for example `$home` versus `$HOME`).
- 2026-07-14: Do not overreact to a process leak by reducing useful orchestration to one worker, but verify which controls the active surface actually honors. Codex MultiAgentV2 uses `features.multi_agent_v2.max_concurrent_threads_per_session` (currently defaulting to root plus three), not `[agents].max_threads`, and bypasses the V1 `max_depth` check. Treat the current four-thread total as bounded containment, never as proof that recursive V2 fan-out is disabled; fix explicit lifecycle release in Codex core.
- 2026-07-14: A collaboration worker reporting `completed` or being interrupted does not prove its Windows MCP/runtime children exited. This session repeated the 2026-07-10 leak: three finished research workers left 18 SymForge/Node helper processes alive until the user noticed the console-host spike. Do not delegate on this workspace by default. If delegation is explicitly useful, record the root session's helper bundle before launch, then immediately after every worker finishes verify the new direct-child process trees are gone and terminate only the exact worker-owned trees before doing anything else.
- 2026-07-14: Evidence receipts must specify hash inputs byte-for-byte: row format, casing, ordering, separator/encoding, and trailing-newline behavior. Cleanup receipts must distinguish current live/quarantined state from intentionally retained historical invalidated evidence; never use an unqualified phrase such as “the quarantine was deleted” when both exist.
- 2026-07-14: In evaluation reports, label the provenance of every recommendation: campaign observations may constrain a design without ranking options that come from prior reconnaissance. For trace anatomy, classify calls by structured item status and selected route; raw error strings and alternative-route suggestions can otherwise overcount failures or misstate the chosen leaf.
- 2026-07-13: For SymForge Claude checkpoints, do not drive long Opus reviews through the Codex bridge or a nested direct CLI session. The interaction is slow, truncates/persists output awkwardly, and weakens review independence. Create one self-contained handoff prompt in the repo with an exact report output path; the user links it to a separate Opus terminal and returns the completed report artifact.
- 2026-07-13: SymForge campaign checkpoints use Claude Code with the Opus model. Before patching an agent bridge, verify the installed package against the latest registry release and upstream main. Monitor free disk space before Cargo work; reuse one target directory, clean it when the checkpoint no longer needs it, and remove only verified inactive worktrees/caches.
- 2026-07-13: A SymForge token benchmark has exactly one score: `total tokens without SymForge - total tokens with SymForge` for equivalent completed feature work in two clean sessions with the same model, prompt, and repository state. Report the absolute delta and percentage. Per-call, schema, latency, and retrieval measurements are explanation only; never present them as benchmark metrics or substitutes.
- 2026-07-10: For SymForge repository work, use the full SymForge MCP surface for code inspection and editing after a fresh `index_folder` plus `checkpoint_now(verify_after_write=true)`. If the connector is compact or unbound, report that limitation and repair/reconnect it; never silently fall back to `Get-Content`, Read, Grep, or Glob. Use direct reads only for exact docs/configs or after an explicit SymForge failure.
- 2026-07-10: Run and monitor long or noisy commands such as Cargo builds/tests through Terminal Commander with structured rules and bounded summaries. Never stream raw build logs through repeated terminal polling; report only matched failures and the final exit verdict.
- 2026-07-10: Delegated code tasks must include the full-surface SymForge helper path (`.symforge/codex-mcp-call.ps1 -UseRelease`). A compact or unbound registered connector is not permission for a subagent to inspect source through Terminal Commander or raw file tools; re-run any fallback inspection through SymForge before editing.
- 2026-07-10: In a shared worktree, serialize TDD slices that introduce compile-red tests. An unrelated missing symbol prevents every other focused Cargo test from reaching its test body. Use one compile-red slice at a time (or an isolated worktree), restore a compiling tree, then release the next Cargo gate.
- 2026-07-10: Do not use the Codex delegated-agent harness on this Windows workspace unless every worker is headless, lifecycle-bounded, and verified to leave zero child processes. Completed subagents leaked MCP/runtime sets that repeatedly opened Git terminal windows, stole desktop focus, and prevented user input. Prefer local execution; after any approved delegation, audit and terminate the worker tree before continuing.
- 2026-07-10: Route every shell, Cargo, process-inspection, and process-cleanup operation through the updated Terminal Commander. Do not call direct terminal execution even for small diagnostics; use bounded structured receipts so commands stay headless and cannot spawn focus-stealing windows.
- 2026-07-11: NEVER let library tests reach `spawn_daemon_process`/`ensure_daemon_running`'s spawn path. Under `cargo test`, `current_exe()` is the libtest binary and the `daemon` argument is a TEST FILTER, so auto-spawn re-runs the daemon test subset recursively — an exponential fork bomb that floods the desktop with console windows, steals focus, and makes the machine unusable (2026-07-11 incident; the user had to kill everything). The daemon now refuses to auto-spawn from a test build (cfg(test)), from any Cargo `deps/` artifact (by path), and when `SYMFORGE_DAEMON_AUTOSPAWN=off`; any future code that spawns `current_exe()` must carry the same three guards, and any test that can reach a reconnect/spawn seam must prove the guard holds before running the suite.
- 2026-07-11: Windows self-update DESIGN DECISION (user-set): `symforge update` terminating every same-install-path holder (including other harnesses' live MCP stdio transports) is INTENDED behavior, not a defect. The user prefers killing verified same-install lock holders and manually reconnecting SymForge in each harness over a copy-on-write/rename-aside swap that leaves old renamed images running. A rename-aside implementation was built and then reverted on the user's explicit call (2026-07-11); do not re-propose it. Ownership boundary: SymForge kills verified same-path holders + re-registers configs; the harness/user reconnects sessions.
- 2026-07-11: The embed gate is `cargo test --no-default-features --features embed --lib` (CI's exact command), NOT `cargo check --features embed` — check skips cfg(test) code, so an embed-visible TEST module calling a server-gated helper (process_util) passed check locally and failed CI. Always run the CI job's verbatim command before claiming a gate green.