Default simple persona launches to direct mode

[willwashburn]

Summary

• stop defaulting every simple interactive persona run into a Relayfile mount
• keep the direct path in the real cwd with normal harness auth, so OAuth/keychain credentials still work (no clean HOME, no Claude --bare)
• use the mount only for declared filesystem policy, sidecars/config files, or non-Claude skill installs that still need repo write isolation
• update CLI docs and tests for the direct-launch default

Tests

• corepack pnpm --filter @agentworkforce/cli test

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d0bee50-bc92-478d-bb4c-ad1b523e975a

📥 Commits

Reviewing files that changed from the base of the PR and between 3a196d0 and 385ef88.

📒 Files selected for processing (4)

• packages/cli/CHANGELOG.md
• packages/cli/README.md
• packages/cli/src/cli.test.ts
• packages/cli/src/cli.ts

---

📝 Walkthrough

Walkthrough

This PR refactors the CLI's session sandboxing strategy for interactive agent launches. Instead of mounting sandboxes by default for certain harnesses, simple persona launches now run directly in the user's cwd by default, and Relayfile mounts activate only when declared mount policies, sidecars, config files, or non-Claude skill installs require filesystem isolation.

Changes

Conditional mounting for interactive persona launches

Layer / File(s)	Summary
Documentation of conditional mount behavior packages/cli/CHANGELOG.md, packages/cli/README.md	CHANGELOG and README sections are updated to document that simple persona launches default to unmounted direct execution, and that Relayfile mounts are created only when needed for filesystem mediation (mount policy, sidecars, config files, or non-Claude skill installs).
Mount decision API refactoring packages/cli/src/cli.ts	New DecideCleanModeOptions interface replaces a simple boolean parameter, allowing decideCleanMode to accept mount policy, sidecar presence, config file presence, and sandbox-need inputs. Function returns { useClean } based on the richer decision context. Help text and supporting comments align with the conditional mount model.
Test utilities and mount decision tests packages/cli/src/cli.test.ts	writeStandaloneCodexPersona test helper is updated to accept persona JSON overrides. decideCleanMode test expectations change from mounted-by-default (useClean: true) to unmounted-by-default (useClean: false), with mounting enabled only when context (config, skills, mount policy) requires it.
Integration of mount decision and sidecar materialization packages/cli/src/cli.ts, packages/cli/src/cli.test.ts	runInteractive loads sidecar data earlier and passes richer context to decideCleanMode. Sidecars are materialized only when mounting is enabled; if a sidecar is declared but the session runs unmounted, a warning is emitted and sidecar materialization is skipped. Codex integration tests expect unmounted direct launches by default and validate mount-path switching when mount policy is declared.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• AgentWorkforce/workforce#49: Both PRs modify sidecar and decideCleanMode logic in packages/cli/src/cli.ts to control when sandbox mounts are enabled.
• AgentWorkforce/workforce#46: Both PRs modify session launch logic in packages/cli/src/cli.ts around sidecar materialization and warnings when mounts are unavailable.
• AgentWorkforce/workforce#59: Both PRs modify interactive mount session execution flow in packages/cli/src/cli.ts, including mount lifecycle and sidecar materialization behavior.

Poem

🐰 Mounts unmount by default, what a leap!
Unless policies or sidecars run deep,
Direct launches hop through the repo,
Sandboxes awake when they're needed to grow,
Simpler sessions, and codebase to keep!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately captures the main change: defaulting simple persona launches to direct mode instead of mounted mode.
Description check	✅ Passed	The description clearly explains the motivation and implementation: avoiding default mounts, keeping direct paths, and using mounts only when needed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/persona-profile-launches

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f37df446e7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Honor project Relayfile policies when choosing mount mode

Include project-level Relayfile policy presence (.agentignore / .agentreadonly) in the decideCleanMode inputs; otherwise simple launches skip the mount even when the repo has explicit filesystem rules. In runInteractive, useClean is now derived only from persona-side flags (mount, sidecar, opencode config, non-Claude skills), and the Relayfile dotfiles are only read later inside the mount branch via buildRelayfileMountPatterns. This means repos that relied on .agentignore/.agentreadonly to hide or protect paths will silently lose those protections on default profile launches.

Useful? React with 👍 / 👎.

[khaliqgant]

Peer review — one substantive concern + a few nits.

Substantive: scope expansion vs. the original codex-only ask

The original brief and human approval was 'make codex mount conditional.' This PR also flips claude from mount-by-default to direct launch:

test('decideCleanMode: claude defaults to direct launch without a mount', () => {
  assert.deepEqual(decideCleanMode('claude'), { useClean: false });
});

In runInteractive:

const useClean = decideCleanMode(harness, {
  installInRepo: options.installInRepo === true,
  mount: effectiveSelection.mount,
  hasSidecar: Boolean(sidecarLookup.sidecar),
  hasConfigFiles: harness === 'opencode',
  installNeedsSandbox: harness !== 'claude' && effectiveSelection.skills.length > 0
}).useClean;

For plain claude personas (no claudeMd sidecar, no mount block, skills already staged via installRoot), useClean is now false. The session sees the user's real-repo CLAUDE.md, .claude/, and .mcp.json — which the mount was previously hiding.

This is a meaningful isolation change: a persona without its own claudeMd will inherit the user's CLAUDE.md instructions at runtime. Persona authors who relied on the mount to give them a clean session lose that guarantee silently.

Two ways forward:

1. Narrow the PR back to codex-only, leaving claude/opencode mount-by-default. Smallest diff to current behavior, matches what was approved.
2. Keep the wider change, but flag it explicitly in the PR description (it currently buries the claude flip under 'simple persona launches') and add an explicit test for the claude direct-launch behavior so reviewers see it.

I'd prefer (1) for this PR and a follow-up to design the broader 'direct by default' behavior with explicit human sign-off. The wider change touches the isolation contract for every claude persona shipped today and deserves its own decision.

Nits

• hasConfigFiles: harness === 'opencode' is a hardcoded heuristic, not derived from the actual spec.configFiles.length > 0. Acceptable since useClean is decided before buildInteractiveSpec runs, but worth a comment so a future opencode that loses its config file doesn't silently keep mounting (or vice versa: a future codex with config files doesn't silently skip).
• The decideCleanMode(harness, boolean | options, maybeOptions) overload is a clever back-compat shim, but decideCleanMode is internal — could simplify to just (harness, options) everywhere. Minor.
• Missing test: no assertion for the new 'claude defaults to direct launch with user's CLAUDE.md visible' path. That's the highest-impact new behavior and deserves explicit coverage.

PR #171 (relayfile) review went up separately and is good to go modulo cross-account approval limitation.