fix(runtime): refuse an unsafe agent provider home before planning, and let doctor --fix tighten it (#1265)

[mrthankyou]

Fixes #1265.

Problem

The agent adapters (templates/smithers/agents/provider-home.tsx) accept a provider home only if it is a directory the operator owns, with mode exactly 0700, below directories only the operator can write. Claude Code and Codex create their own homes from the umask, so the result is usually 0755 or 0775:

CLI	umask	Home it creates
Claude Code 2.1.207 (Linux)	0022	~/.claude 755
Claude Code 2.1.207 (Linux)	0002 (Ubuntu desktop)	~/.claude 775
Codex 0.146.0 (Linux)	0022	~/.codex 755
Codex (macOS, a maintainer's machine)	0022	~/.codex 755

The Codex adapter uses its provider home in both subscription and api-key mode, and ultrafuzz init defaults to Codex. So a default Codex run fails for anyone whose Codex CLI created ~/.codex, on macOS or Linux, and a Claude run fails on Linux. It fails only when the engine renders the workflow, after about 2 minutes of planning and execution-snapshot preparation, as INTERNAL_ERROR: render frame: provider homes must be operator-owned with private 0700 permissions, with no directory named. CI misses it because the e2e campaign sets CODEX_HOME to a fresh 0700 directory.

Change

• provider-home-preflight.ts:
  • predictedProviderHome mirrors the adapters' resolution order: config_dir or ULTRAFUZZ_PROVIDER_HOME_ROOT, then CLAUDE_CONFIG_DIR / CODEX_HOME / KIMI_*, then ~/.claude / ~/.codex / ~/.kimi-code, and ~/.ultrafuzz-provider-homes/<provider> for the rest.
  • providerHomeProblems applies the adapters' checks to each selected agent's home.
  • A test runs the adapter's own resolveProviderHome under Bun and checks the prediction matches it.
• validate (and so run, which validates before planning) reports PROVIDER_HOME_UNSAFE in the agents check, naming the directory and the fix:

  CodexAgent would use /Users/…/.codex as its provider home, but /Users/…/.codex has mode 755; agents refuse a provider home that is not a private directory you own (mode 0700) under directories only you can write, so run ultrafuzz doctor --fix or chmod 700 /Users/…/.codex

• ultrafuzz doctor gains a provider-homes check. ultrafuzz doctor --fix applies the repair first, then checks:
  • it sets each refused provider home that is a real directory the operator owns to 0700, and reports PROVIDER_HOME_FIXED (tightened <dir> from mode 755 to 700);
  • it never changes a directory above a provider home. That case gets a manual message: fix it, or point ULTRAFUZZ_PROVIDER_HOME_ROOT at a private directory.
• When the check runs: it uses the launch environment's HOME, as the engine does. A launch without HOME, such as the unit tests' empty environments, isn't checked, so the suite never reads a developer's real ~/.codex.
• Unchanged: the adapters' own checks in the engine stay as they are, as a second line of defense.
• Docs: CLI reference (doctor, --fix), docs/config.md, CHANGELOG.

Not done: tightening the directory automatically during launch

Ultrafuzz could also chmod 700 an operator-owned ~/.codex or ~/.claude silently whenever it launches. That would need no user action, and it's arguably correct, since those directories hold credentials and both CLIs run as the same user. This PR deliberately doesn't do it. Per Chesterton's fence, the 0700 rule and the decision not to change other tools' directories should be reviewed first:

• The directories belong to Claude Code and Codex, not Ultrafuzz.
• A silent change could break setups where another user or tool reads the directory through group permissions (shared groups, backup or sync tools).
• The operator wouldn't know it happened.

doctor --fix gives the same result with the operator's consent. If maintainers agree automatic tightening is safe, it can be added on top of this change. A related option is to accept an operator-owned home that isn't group- or world-writable (such as 0755), as the checks on parent directories already do. That also changes the security rule, so it also needs review.

Verification

• Real CLI on macOS, fresh project (Codex default):
  • validate against the real HOME reports the maintainer's real ~/.codex (755) as PROVIDER_HOME_UNSAFE (read only; not modified).
  • With a throwaway HOME whose .codex is 755: doctor reports provider-homes: error; doctor --fix reports PROVIDER_HOME_FIXED … from mode 755 to 700; validate then passes.
• New provider-home-preflight.test.ts:
  • the resolution order;
  • 755, 775, symlinked and group-writable-ancestor homes refused, and private or missing homes accepted;
  • --fix tightens only the operator's own home and leaves an ancestor alone;
  • validate refuses before launch and passes once fixed;
  • the prediction matches the adapter's resolveProviderHome run under Bun.
• Existing tests: the runtime doctor/validate tests (12) and the CLI doctor tests pass. Strict eslint, prettier and the docs check are clean.

🤖 Generated with Claude Code

Confidence Score: 4/5

The PR should not merge while its advertised provider-home repair command is unavailable.

Summary

The PR adds provider-home validation before planning and changes doctor to report manual remedies. Changes since the previous review also add early duplicate-run detection, timeout-shadowing warnings, and retry handling for failed optional producers, including Modal resume decisions.

• The promised doctor --fix repair is no longer available.
• Node timeout warnings miss a longer group default shadowed by a node pin.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[validate or run] --> B[Check selected provider homes]
  B -->|unsafe| C[PROVIDER_HOME_UNSAFE]
  C --> D[Manual permission repair]
  B -->|safe| E[Plan and launch]
  F[doctor] --> B

Loading

_{Reviews (4) · Last reviewed commit: "Merge remote-tracking branch 'origin/uns..."}

[aviggiano]

Thanks, the preflight is the right fix. Failing at validate / run with PROVIDER_HOME_UNSAFE and the directory name is exactly what #1265 needed.

One change before we merge: please drop doctor --fix. We want doctor to stay report-only. It should list problems, not repair them. Changing permissions on the user's home config directories (fd-pinned fchmod, the EACCES path fallback, the multi-pass re-check loop) is a lot of code to maintain for a one-line chmod 700 <dir> the user can run themselves.

Concretely:

• Remove fixProviderHomes, tightenDirectory, sameDirectory, ownedByOperator, DoctorInput.fix, the CLI flag, PROVIDER_HOME_FIXED / PROVIDER_HOME_FIX_FAILED, the fixable field, the fix-only tests, and the --fix docs and CHANGELOG text.
• Drop the extra provider-homes doctor check too. doctor already reports PROVIDER_HOME_UNSAFE through validateProject's diagnostics.
• Have the diagnostic print the exact chmod 700 <dir> command.

We'll take care of the smaller items ourselves in a follow-up after merge, so no need to handle them here:

• Run lifecycle-inspection.test.ts with a temporary HOME. It now fails locally on any machine with a 0755/0775 ~/.codex.
• Add OpenRouterAgent to PROVIDER_HOMES.
• Reject a relative CODEX_HOME / CLAUDE_CONFIG_DIR / KIMI_* the way the adapter does.