fix: improve settings distributor robustness and security

[nikuscs]

Summary

Fixed multiple bugs in the settings distributor module, added process.env fallback for env resolution, and introduced .env.agents for dedicated agent secrets.

Key fixes:

• TOML string escaping now handles newlines, tabs, carriage returns (prevents invalid TOML)
• TOML inline table parsing now respects quoted strings with commas (prevents silent data loss)
• TOML scalar insertion now scoped to top-level keys (prevents accidental overwrites in sections)
• Added warnings for Cursor project-level permission limitations and unsupported Codex keys
• Deduplicated constants and logic across modules to prevent silent divergence
• Env resolution now falls back to process.env for CI/shell-exported variables
• Default env file lookup now includes .env.agents first for dedicated secrets

Test plan

• All 52 test files pass (379 tests) with 99.83% coverage
• 7 env-resolver tests including new process.env fallback cases
• 20 settings-distributor tests covering all provider formats and edge cases
• Type check passes clean

🤖 Generated with Claude Code

---

[devin-ai-integration]

Devin Review found 1 potential issue.

View 7 additional findings in Devin Review.

[devin-ai-integration]

🟡 Sequential regex replacements in unquote corrupt values containing escaped backslashes

The unquote function in src/core/env-resolver.ts:10-15 processes escape sequences using sequential regex replacements in an order that cannot correctly handle escaped backslashes preceding other escape characters like \n, \r, or \t.

Root Cause and Impact

For a .env file containing KEY="hello\\nworld" (intended to represent the literal string hello\nworld), the inner content after stripping quotes is the character sequence h,e,l,l,o,\,\,n,w,o,r,l,d.

Step 1 (replace(/\\n/g, '\n')) matches the second backslash + n first, converting it to a newline character. The first backslash is left as-is, producing hello\<newline>world instead of the intended hello\nworld.

Processing \\ last at step 5 cannot fix this because the \n has already been consumed. Reordering the replacements does not help either—processing \\ first would turn \\n into \n, which step 2 would then convert to a newline.

The fix requires a single-pass replacement, e.g.:

inner.replace(/\\([\\nrt"])/g, (_, ch) => {
  const map: Record<string, string> = { '\\': '\\', n: '\n', r: '\r', t: '\t', '"': '"' };
  return map[ch] ?? ch;
});

Impact: Any double-quoted .env value containing a literal escaped backslash before n, r, t, or " (e.g. Windows paths like C:\\new_folder) will be silently corrupted.

Suggested change

	return inner
	.replace(/\\n/g, '\n')
	.replace(/\\r/g, '\r')
	.replace(/\\t/g, '\t')
	.replace(/\\"/g, '"')
	.replace(/\\\\/g, '\\');
	return inner
	.replace(/\\([\\nrt"])/g, (_, ch) => {
	const map: Record<string, string> = { '\\': '\\', n: '\n', r: '\r', t: '\t', '"': '"' };
	return map[ch] ?? ch;
	});

---

Was this helpful? React with 👍 or 👎 to provide feedback.