Context
A local whitebox/Neural Link test run left an untracked bridge.log at the repository root. Direct inspection traced the file to the Neural Link bridge spawn path rather than the shared MCP logger.
Release classification: post-release/tooling cleanup; this does not block the v13 release board.
Live latest-open sweep: checked the latest 20 open issues at 2026-06-23T00:14:28Z; no equivalent issue found. Narrow live GitHub search for bridge.log OR Neural Link log OR spawnBridge returned no open matches. Recent A2A claim sweep: checked latest 30 messages; no competing claim for this scope found. KB/local sweep found adjacent history (#13473 payload log bounding, #13474/#13508 retention/size, #13483 bridge supervision, #13131 import-time side effects), but no ticket covering the child-process stdio path.
The Problem
ConnectionService.spawnBridge() opens ./bridge.log for the spawned bridge process stdout/stderr. When Playwright whitebox/e2e fixtures run from the repo root and no bridge is already reachable, test/playwright/fixtures.mjs calls manageConnection({action: 'start'}), which can reach spawnBridge(). The relative ./bridge.log then resolves to the repository root and bypasses the configured Neural Link log directory.
The observed repo-root bridge.log contains Neural Link bridge startup/fatal output, including stale-config guard failures and bridge connection logs. That confirms the file is operational logging, not source state.
The Architectural Reality
ai/services/neural-link/ConnectionService.mjs:695-705 owns the in-service bridge spawn path and currently redirects child stdio to ./bridge.log.test/playwright/fixtures.mjs:80-82 starts Neural Link through ConnectionService.manageConnection({action: 'start'}), so whitebox/e2e runs can trigger the spawn path.ai/mcp/server/neural-link/config.mjs:69-78 already defines logPath as <neoRootDir>/.neo-ai-data/logs/, shared with KB and Memory Core logs using distinct filename prefixes.learn/agentos/NeuralLink.md:116-121 still documents repo-root ./bridge.log, which now conflicts with the configured log substrate.
The Fix
Route spawned bridge child-process stdout/stderr into the configured Neural Link log directory, e.g. <neoRootDir>/.neo-ai-data/logs/neural-link-bridge-stdio.log, creating the directory if needed. Update stale comments/docs that still describe repo-root bridge.log. Add unit coverage around the path resolver/spawn wiring without launching a real bridge.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
| Neural Link bridge child-process stdio |
ConnectionService.spawnBridge() plus aiConfig.logPath |
Spawned bridge stdout/stderr append under .neo-ai-data/logs, not the repository root |
If aiConfig.logPath is absent, resolve <neoRootDir>/.neo-ai-data/logs, then cwd as last fallback |
Update learn/agentos/NeuralLink.md and stale test/script comments |
Unit coverage verifies path resolution and spawn stdio wiring without starting the bridge |
| Repository cleanliness |
Neo log substrate convention |
Whitebox/e2e Neural Link startup must not create bridge.log in the repo root |
Existing untracked historical files may be removed manually after verification |
Docs point operators to .neo-ai-data/logs |
git status --short after a spawn-path test has no new root bridge.log |
Decision Record impact
None. This aligns an existing service path with the already documented Neural Link logPath config contract.
Acceptance Criteria
Out of Scope
- Changing bridge lifecycle/supervision behavior from
#13483.
- Changing Neural Link payload logging boundedness from
#13473.
- Changing logger retention policy from
#13474 / #13508.
- Deleting any operator-owned historical
bridge.log files outside this fix.
Avoided Traps
- Do not route this through the shared MCP logger only. The spawned child process still needs a stdout/stderr sink for npm output and startup failures before logger initialization finishes.
- Do not make the unit test start the real bridge; test the path resolver/spawn wiring with seams or pure helpers.
Related
#13131 — import-time Neural Link side effects in unit tests.#13473 — bounded Neural Link bridge payload logging.#13474 / #13508 — MCP log retention and size caps.#13483 — bridge supervision constraints.
Handoff Retrieval Hints: Neural Link spawnBridge bridge.log .neo-ai-data logs child stdio, ConnectionService.spawnBridge fs.openSync bridge.log, whitebox e2e neuralLink fixture manageConnection start bridge stdio
Context
A local whitebox/Neural Link test run left an untracked
bridge.logat the repository root. Direct inspection traced the file to the Neural Link bridge spawn path rather than the shared MCP logger.Release classification: post-release/tooling cleanup; this does not block the v13 release board.
Live latest-open sweep: checked the latest 20 open issues at 2026-06-23T00:14:28Z; no equivalent issue found. Narrow live GitHub search for
bridge.log OR Neural Link log OR spawnBridgereturned no open matches. Recent A2A claim sweep: checked latest 30 messages; no competing claim for this scope found. KB/local sweep found adjacent history (#13473payload log bounding,#13474/#13508retention/size,#13483bridge supervision,#13131import-time side effects), but no ticket covering the child-process stdio path.The Problem
ConnectionService.spawnBridge()opens./bridge.logfor the spawned bridge process stdout/stderr. When Playwright whitebox/e2e fixtures run from the repo root and no bridge is already reachable,test/playwright/fixtures.mjscallsmanageConnection({action: 'start'}), which can reachspawnBridge(). The relative./bridge.logthen resolves to the repository root and bypasses the configured Neural Link log directory.The observed repo-root
bridge.logcontains Neural Link bridge startup/fatal output, including stale-config guard failures and bridge connection logs. That confirms the file is operational logging, not source state.The Architectural Reality
ai/services/neural-link/ConnectionService.mjs:695-705owns the in-service bridge spawn path and currently redirects child stdio to./bridge.log.test/playwright/fixtures.mjs:80-82starts Neural Link throughConnectionService.manageConnection({action: 'start'}), so whitebox/e2e runs can trigger the spawn path.ai/mcp/server/neural-link/config.mjs:69-78already defineslogPathas<neoRootDir>/.neo-ai-data/logs/, shared with KB and Memory Core logs using distinct filename prefixes.learn/agentos/NeuralLink.md:116-121still documents repo-root./bridge.log, which now conflicts with the configured log substrate.The Fix
Route spawned bridge child-process stdout/stderr into the configured Neural Link log directory, e.g.
<neoRootDir>/.neo-ai-data/logs/neural-link-bridge-stdio.log, creating the directory if needed. Update stale comments/docs that still describe repo-rootbridge.log. Add unit coverage around the path resolver/spawn wiring without launching a real bridge.Contract Ledger Matrix
ConnectionService.spawnBridge()plusaiConfig.logPath.neo-ai-data/logs, not the repository rootaiConfig.logPathis absent, resolve<neoRootDir>/.neo-ai-data/logs, then cwd as last fallbacklearn/agentos/NeuralLink.mdand stale test/script commentsbridge.login the repo root.neo-ai-data/logsgit status --shortafter a spawn-path test has no new rootbridge.logDecision Record impact
None. This aligns an existing service path with the already documented Neural Link
logPathconfig contract.Acceptance Criteria
ConnectionService.spawnBridge()no longer opens./bridge.logrelative to process cwd.aiConfig.logPath/.neo-ai-data/logs.bridge.logare updated or explicitly marked historical.stdiowiring without launching a real bridge.Out of Scope
#13483.#13473.#13474/#13508.bridge.logfiles outside this fix.Avoided Traps
Related
#13131— import-time Neural Link side effects in unit tests.#13473— bounded Neural Link bridge payload logging.#13474/#13508— MCP log retention and size caps.#13483— bridge supervision constraints.Handoff Retrieval Hints:
Neural Link spawnBridge bridge.log .neo-ai-data logs child stdio,ConnectionService.spawnBridge fs.openSync bridge.log,whitebox e2e neuralLink fixture manageConnection start bridge stdio