symforge 10.0.0

SymForge — in-memory code intelligence MCP server for Claude Code, Codex, and Gemini CLI
Documentation
# Lessons

- 2026-07-29: A source commit or locally built binary does not update users who install SymForge through npm. For a shipped-runtime defect, trace the configured executable to its distribution channel, merge and push the fix through the repository release workflow, then verify the new platform package and root npm package are published before calling deployment complete.
- 2026-07-21: Once the canonical manifest is the sole terminal-disposition authority, coverage, repair eligibility, and removal authorization must be derived from that same manifest. A scout plan cannot safely erase read-stage failures or circuit-breaker aborts, and an incomplete/degraded rescout cannot prove deletion. Retain failed entries as typed unavailable dispositions, keep coverage Degraded until stable replacement, and authorize removals only from a Complete observation.
- 2026-07-21: A background derived-only publication may legitimately advance `publication_generation` while live repository identity remains unchanged. Tests for failed durability or immutable live state must compare `content_generation`, `project_generation`, source identity/version, manifest/content digests, and query results; never assert that the publication counter stays fixed across an async interval. Re-run timing-sensitive oracles repeatedly before the full serial gate.
- 2026-07-17: When the user says an external review is running and will take time, stop polling and wait for their explicit completion message unless they request monitoring. Immediate persistent-goal continuations are not elapsed-time evidence and must not be counted as repeated blocker turns or used to re-mark the goal blocked.
- 2026-07-16: Once the user says a goal file is for a fresh session and the handover is ready, stop the old session after giving the launch command. An automatic persistent-goal continuation is not permission to begin the handed-off implementation in the exhausted session; limit any further work to explicitly requested handover corrections.
- 2026-07-16: Keep another repository's defect, release, and installation details out of the active SymForge goal and handover once ownership has moved to that repository's agent. Preserve only constraints that materially govern SymForge execution; cross-project operational history dilutes the fresh-session objective.
- 2026-07-16: When a long campaign is interrupted by external tooling defects, timebox the detour, close it with its own verified source branch, and return the campaign through one `/goal <file.md>` restart document. Do not keep extending the already-compacted session: it duplicates hook context, dilutes the objective, and makes implementation state harder to audit. The goal file must link a self-contained handover, carry measurable terminal criteria, and say exactly what not to rediscover.
- 2026-07-16: Repeated hook output is not proof of duplicate configuration. This session had exactly one Ponytail plugin section, one persisted `SessionStart` hook, and one manifest command, yet Codex recorded 13 byte-identical 5,229-character contexts at startup (12 within about 0.6 seconds). Distinguish registration multiplicity from invocation/retry multiplicity with sanitized counts and content digests. Session/resume/compact hooks that emit large context must be idempotent against same-event bursts while still allowing a later genuine compaction refresh.
- 2026-07-16: A headless parent or MCP transport does not guarantee headless Windows descendants. The user again observed SymForge-related console windows stealing focus while Codex subagents used SymForge, despite prior warnings in this file. Until the shared Windows spawn policy is verified, do not delegate SymForge work. Every production `std::process::Command` path that can launch SymForge, daemon, sidecar, hook, updater, helper, shell, or child tool must apply the one tested no-visible-window policy (`CREATE_NO_WINDOW` or the correct stronger equivalent for its process kind) at the shared constructor boundary; tests must inventory all spawn call sites and fail if any bypass it. A completed worker is not lifecycle proof: verify zero worker-owned descendants before resuming.
- 2026-07-16: Do not conflate permission to read/index a source root with permission to create `<root>/.symforge`. Automatic startup from a protected root must remain healthy-but-unbound so a later `index_folder` call can bind an accessible project; an explicit protected-root override may index that exact source but must place derived runtime state in a collision-resistant user-local directory or run memory-only if persistence is unavailable. A local state-directory failure is a persistence degradation, never a reason to poison the process or abandon live indexing.
- 2026-07-15: A release changelog is not a Conventional Commit coverage table. When the user asks for Terminal Commander-style release notes, use the tag-range commits as evidence but write a user-facing narrative with measured scope, behavior, compatibility/operator consequences, verification, and published artifacts. If the version is already published, update and verify BOTH `CHANGELOG.md` and the GitHub release body; a pushed repository edit does not retroactively change the release page.
- 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.
- 2026-07-16: When the user asks for repository knowledge extraction, do not force the feature into the code-intelligence model or default to fixed-size chunks plus embeddings. Model a separate repository knowledge index: parse natural document structures into queryable knowledge units with exact `file:line` provenance, use deterministic ranked retrieval first, and add semantic machinery only if measured vocabulary mismatch requires it.
- 2026-07-16: Repository knowledge is not confined to the active checkout. Indexing must discover once and route files independently to code, knowledge, both, or catalog-only targets; live knowledge identity must include repository plus worktree/ref plus path plus source hash. Distinguish mechanical index freshness from semantic document validity, prefer the current worktree without hiding labeled variants from other active worktrees or local refs, and never silently serve an unverifiable generation.
- 2026-07-16: Discovery resource budgets must count content that will actually be ingested, not the repository's total on-disk bytes. Apply path/size admission before any full read in bulk, watcher, reconciliation, and verification paths; multi-gigabyte model weights and datasets stay catalog-visible but consume zero ingest bytes and are never fully hashed, mapped, decompressed, or deserialized. Index their adjacent model cards/configs normally, and keep separate bounded limits for catalog entries, admitted bytes, per-file reads, and sniff samples.
- 2026-07-16: Project ignore hygiene must not manufacture a missing repository policy file. After explicit normal `index_folder` binding and during project-aware `symforge init`, append canonical `/.symforge/` idempotently only when repository-root `.gitignore` already exists; if absent, do nothing. Automatic startup/scout/watcher/reconciliation/ref ingestion stays read-only, `.symforge/` is always hard-excluded, and a guarded hygiene-write failure is reported without disabling the valid live index.
- 2026-07-16: Windows LLM harnesses commonly launch from `%USERPROFILE%` or `C:\Windows\System32`; no SymForge entry point may interpret launch CWD as permission to index either. Run one raw-plus-canonical root-eligibility gate before scout, watcher, snapshot, runtime-directory, init, daemon/session, or `index_folder` I/O. Automatic and default requests leave drive/filesystem roots, home/profile roots, OS/sensitive trees, broad containers, and alias/junction/symlink forms healthy-but-unbound; only a direct `index_folder(..., allow_protected_root=true)` may bind the exact protected canonical root, and that authority never permits source-local `.symforge` state or unrelated mutation.
- 2026-08-03: For every SymForge repository task, run `index_folder` first and wait for a Ready, correctly bound health result before any repository inspection, review, search, or file-context call. A preliminary unbound `health` call is diagnostic only; do not issue repository queries until indexing is confirmed.