From 676026a6c34ca3241f8dde8998d2722b26e20439 Mon Sep 17 00:00:00 2001
From: Will Washburn <will.washburn@gmail.com>
Date: Thu, 30 Apr 2026 16:37:10 -0700
Subject: [PATCH] feat(cli): default claude/opencode to sandbox mount with git
 included

Bumps @relayfile/local-mount to ^0.6.0 and passes includeGit: true so
the per-session mount carries .git, letting agents run git inside the
sandbox. Tracked paths matching the hidden patterns (CLEAN_IGNORED_*,
SKILL_INSTALL_IGNORED_*, persona configFile paths) are flagged
skip-worktree and added to .git/info/exclude inside the mount, so
git status doesn't report them as deleted/untracked. The mount's .git
is per-session and noSyncBack, so this state is sandboxed.

Flips the claude branch in decideCleanMode to mirror opencode: mount
engages by default, --install-in-repo opts out. Removes the legacy
--clean flag entirely (mount is now the default behavior on both
harnesses; codex is unchanged).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                    |  44 ++++---
 packages/cli/README.md       |  65 ++++++----
 packages/cli/package.json    |   2 +-
 packages/cli/src/cli.test.ts | 190 +++++++++++++++++----------
 packages/cli/src/cli.ts      | 240 +++++++++++++++++++++--------------
 pnpm-lock.yaml               |  10 +-
 6 files changed, 331 insertions(+), 220 deletions(-)

diff --git a/README.md b/README.md
index 5d9ec546..8f3d0c65 100644
--- a/README.md
+++ b/README.md
@@ -147,13 +147,16 @@ layer for reusing installs across sessions is planned but not yet wired up. See
 **[packages/cli/README.md#skill-staging](./packages/cli/README.md#skill-staging)**
 for the full mechanics.
 
-### Clean mode (`--clean`)
+### Sandbox mount (default for claude / opencode)
 
-For interactive `claude` sessions, `--clean` launches the harness inside a
+Interactive `claude` and `opencode` sessions launch inside a
 [`@relayfile/local-mount`](https://www.npmjs.com/package/@relayfile/local-mount)
-sandbox that hides repo-level Claude Code configuration from the model:
+sandbox by default. The mount hides repo-level harness configuration
+(claude) and routes skill-install writes into the sandbox (opencode), so
+the model sees persona context + user-level context — and nothing the
+repo itself declares. Codex sessions never mount.
 
-| Hidden in `--clean` mode | Still visible |
+| Hidden in the mount (claude) | Still visible |
 | --- | --- |
 | `CLAUDE.md` (at any depth) | `~/.claude/CLAUDE.md` (user-level) |
 | `CLAUDE.local.md` | `~/.claude/skills/` (user-level skills) |
@@ -162,23 +165,26 @@ sandbox that hides repo-level Claude Code configuration from the model:
 |  | your keychain auth (unchanged) |
 
 ```bash
-agent-workforce agent --clean posthog@best
+agent-workforce agent posthog@best
 ```
 
-The repo tree is mirrored into
-`~/.agent-workforce/sessions/<id>/mount/` via symlinks; claude sees the
-mount as its cwd. Writes inside the mount sync back to the real repo on
-exit. Ignore semantics follow gitignore — `.claude` hides nested variants
-like `packages/foo/.claude/` too.
-
-**Scope:** interactive claude only. Pass it to codex/opencode and the flag
-is ignored with a note. `--clean` and `--install-in-repo` are mutually
-exclusive — they ask for opposite things.
-
-**Caveat:** user-level Claude Code config in `~/.claude/` still loads
-inside the session. `--clean` hides the *repo's* context, not the user's.
-If you need to hide user-level config too, launch under a scratch
-`$HOME`. See **[packages/cli/README.md#clean-mode](./packages/cli/README.md#clean-mode)**
+The repo tree is mirrored into `~/.agent-workforce/sessions/<id>/mount/`
+via symlinks; the harness sees the mount as its cwd. Writes inside the
+mount sync back to the real repo on exit. Ignore semantics follow
+gitignore — `.claude` hides nested variants like `packages/foo/.claude/`
+too. `.git` is included in the mount (one-way project→mount sync) so git
+commands work inside the sandbox; mount-side commits are discarded on
+cleanup, so push to persist work.
+
+**Opt out:** `--install-in-repo` runs against the real cwd and stages
+skills into the repo's harness-conventional dirs. Useful when you want to
+inspect installed skills on disk or when the mount conflicts with
+something else (network filesystem, etc.).
+
+**Caveat:** user-level harness config in `~/.claude/` etc. still loads
+inside the session — the mount hides the *repo's* context, not the
+user's. If you need to hide user-level config too, launch under a scratch
+`$HOME`. See **[packages/cli/README.md#sandbox-mount](./packages/cli/README.md#sandbox-mount)**
 for the full mount layout and semantics.
 
 ## Packages
diff --git a/packages/cli/README.md b/packages/cli/README.md
index e3dd9120..ea990989 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -392,11 +392,11 @@ persona session, add it to the persona's `mcpServers` block.
 ## Interactive
 
 ```sh
-agent-workforce agent [--install-in-repo] [--clean] <persona>[@<tier>]
+agent-workforce agent [--install-in-repo] <persona>[@<tier>]
 ```
 
-`--install-in-repo` and `--clean` are mutually exclusive — see
-[**Clean mode**](#clean-mode) below.
+By default, claude and opencode sessions run inside a sandbox mount — see
+[**Sandbox mount**](#sandbox-mount) below. `--install-in-repo` opts out.
 
 1. Resolves the persona, walks the cascade, resolves `$VAR` refs.
 2. **Stages skills outside the repo by default** (claude interactive only —
@@ -483,20 +483,21 @@ stage dir conflicts with something else (network filesystem, read-only
   into a new stage dir. A `~/.agent-workforce/cache/` content-addressed cache
   is planned but not wired up.
 
-## Clean mode
+## Sandbox mount
 
-`--clean` launches an interactive claude session inside a
+By default, claude and opencode interactive sessions run inside a
 [`@relayfile/local-mount`](https://www.npmjs.com/package/@relayfile/local-mount)
-symlink mount that hides the repo's Claude Code configuration from the
-session — so the model sees persona context + user-level context, and
-nothing the repo itself declares.
+symlink mount that hides repo-level harness configuration from the session
+and routes skill-install writes into the sandbox — so the model sees
+persona context + user-level context, and nothing the repo itself declares.
+Codex sessions never mount (no harness-side support).
 
-```sh
-agent-workforce agent --clean <persona>[@<tier>]
-```
+`--install-in-repo` opts out and runs against the real cwd.
 
 **What's hidden (gitignore semantics, at any depth):**
 
+For claude:
+
 | Pattern | Rationale |
 | --- | --- |
 | `CLAUDE.md` | Repo-level project memory |
@@ -504,18 +505,35 @@ agent-workforce agent --clean <persona>[@<tier>]
 | `.claude` | Repo Claude Code config dir (settings, agents, skills, commands) |
 | `.mcp.json` | Repo-declared MCP servers |
 
+For opencode (skill-install pollution that would otherwise leak back to
+the repo):
+
+| Pattern | Rationale |
+| --- | --- |
+| `.agents`, `.claude/skills`, `.factory/skills`, `.kiro/skills`, `skills` | skill.sh universal install root + per-harness symlink farms |
+| `.opencode`, `.skills` | prpm `--as <harness>` output roots |
+| `prpm.lock`, `skills-lock.json` | provider lockfiles |
+
 **What's preserved:**
 
 - **User-level context** under `~/.claude/` — `CLAUDE.md`, skills, etc.
-  still load. `--clean` scrubs the *project*, not the user. To exclude
+  still load. The mount scrubs the *project*, not the user. To exclude
   user-level context too, launch under a scratch `$HOME`.
-- **Persona skills.** The `--plugin-dir` passed to claude resolves to an
-  absolute path *outside* the mount, so staged skills from
-  `~/.agent-workforce/sessions/<id>/claude/plugin/` load normally.
-- **Keychain auth.** `--clean` does NOT pass `--bare`; it only hides
-  files via the mount. Claude Code's macOS keychain login stays active.
+- **Persona skills.** For claude, the `--plugin-dir` passed to the harness
+  resolves to an absolute path *outside* the mount, so staged skills from
+  `~/.agent-workforce/sessions/<id>/claude/plugin/` load normally. For
+  opencode, the install runs inside the mount so the writes land in the
+  sandbox.
+- **Keychain auth.** The mount does not pass `--bare`; it only hides
+  files. Claude Code's macOS keychain login stays active.
 - **Persona `mcpServers`.** Still passed via `--mcp-config` — unaffected
   by the mount. The repo's `.mcp.json` is hidden regardless.
+- **Git.** `.git` is included in the mount (one-way project→mount sync per
+  `@relayfile/local-mount` 0.6+'s `includeGit`). Tracked paths matching
+  the hidden patterns are flagged `skip-worktree` so `git status` doesn't
+  report them as deleted, and the patterns are added to `.git/info/exclude`
+  to suppress untracked-and-hidden files. Mount-side commits/refs are
+  sandboxed and discarded on cleanup — `git push` to persist work.
 
 ### Session layout
 
@@ -531,7 +549,7 @@ is generated once and both paths are derived from it:
     │       ├── .claude-plugin/plugin.json
     │       ├── skills → .claude/skills
     │       └── .claude/skills/<name>/SKILL.md
-    └── mount/                                     ← --clean: claude's cwd
+    └── mount/                                     ← session cwd
         └── <mirrored project tree, minus the hidden patterns>
 ```
 
@@ -539,15 +557,6 @@ is generated once and both paths are derived from it:
 SIGINT/SIGTERM forwarding, write syncback, and cleanup on exit. The
 agent-workforce CLI just wires the paths and passes the persona's argv.
 
-### Interactions with other flags
-
-- **`--clean` + `--install-in-repo` is rejected** — they ask for
-  incompatible things. `--install-in-repo` stages skills into the real
-  repo's `.claude/skills/`; `--clean` hides the real repo. Pick one.
-- **`--clean` on codex/opencode is a warning no-op.** Only the claude
-  harness gets the mount (it's the only one whose native surface includes
-  the hidden patterns).
-
 ### Example
 
 ```sh
@@ -555,7 +564,7 @@ agent-workforce CLI just wires the paths and passes the persona's argv.
 # .mcp.json hidden — session sees the persona's staged skills plus your
 # user-level ~/.claude/CLAUDE.md, nothing else from this repo.
 export POSTHOG_API_KEY=phx_…
-agent-workforce agent --clean posthog@best
+agent-workforce agent posthog@best
 ```
 
 On exit: mount is synced back to the real repo, then torn down; skill
diff --git a/packages/cli/package.json b/packages/cli/package.json
index c2f3d188..14ca4208 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -15,7 +15,7 @@
   "dependencies": {
     "@agentworkforce/harness-kit": "workspace:*",
     "@agentworkforce/workload-router": "workspace:*",
-    "@relayfile/local-mount": "^0.5.0",
+    "@relayfile/local-mount": "^0.6.0",
     "ora": "^9.4.0"
   },
   "repository": {
diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.ts
index ff8227d1..451af593 100644
--- a/packages/cli/src/cli.test.ts
+++ b/packages/cli/src/cli.test.ts
@@ -5,6 +5,8 @@ import {
   CLEAN_IGNORED_PATTERNS,
   SKILL_INSTALL_IGNORED_PATTERNS,
   assertSafeRelativePath,
+  buildMountGitExcludeBlock,
+  configureGitForMount,
   decideCleanMode,
   parseAgentArgs,
   resolveSystemPromptPlaceholders,
@@ -59,91 +61,65 @@ function trapExit(): ExitTrap {
   return trap;
 }
 
-test('parseAgentArgs: --clean sets flag and preserves positional selector', () => {
-  const { flags, positional } = parseAgentArgs(['--clean', 'posthog@best']);
-  assert.equal(flags.clean, true);
-  assert.equal(flags.installInRepo, false);
+test('parseAgentArgs: --install-in-repo sets flag and preserves positional selector', () => {
+  const { flags, positional } = parseAgentArgs(['--install-in-repo', 'posthog@best']);
+  assert.equal(flags.installInRepo, true);
   assert.deepEqual(positional, ['posthog@best']);
 });
 
 test('parseAgentArgs: preserves trailing positionals after the selector', () => {
   const { flags, positional } = parseAgentArgs([
-    '--clean',
+    '--install-in-repo',
     'review@best-value',
     'extra-arg'
   ]);
-  assert.equal(flags.clean, true);
+  assert.equal(flags.installInRepo, true);
   assert.deepEqual(positional, ['review@best-value', 'extra-arg']);
 });
 
-test('parseAgentArgs: no flags → both false', () => {
+test('parseAgentArgs: no flags → installInRepo false', () => {
   const { flags, positional } = parseAgentArgs(['posthog']);
-  assert.equal(flags.clean, false);
   assert.equal(flags.installInRepo, false);
   assert.deepEqual(positional, ['posthog']);
 });
 
-test('parseAgentArgs: --clean + --install-in-repo rejected with clear message', () => {
-  const trap = trapExit();
-  try {
-    assert.throws(
-      () => parseAgentArgs(['--clean', '--install-in-repo', 'posthog']),
-      /__exit_trap__:1/
-    );
-    assert.deepEqual(trap.exits, [1]);
-    assert.match(trap.stderr, /mutually exclusive/);
-    assert.match(trap.stderr, /--install-in-repo/);
-    assert.match(trap.stderr, /--clean/);
-  } finally {
-    trap.restore();
-  }
-});
-
-test('parseAgentArgs: flag conflict rejected regardless of flag order', () => {
-  const trap = trapExit();
-  try {
-    assert.throws(
-      () => parseAgentArgs(['--install-in-repo', '--clean', 'posthog']),
-      /__exit_trap__:1/
-    );
-    assert.match(trap.stderr, /mutually exclusive/);
-  } finally {
-    trap.restore();
-  }
-});
-
 test('parseAgentArgs: -- stops flag parsing, positional args after are preserved', () => {
   const { flags, positional } = parseAgentArgs([
-    '--clean',
     '--',
     '--install-in-repo',
     'posthog'
   ]);
-  // --install-in-repo AFTER `--` is positional, not a flag, so no conflict.
-  assert.equal(flags.clean, true);
+  // --install-in-repo AFTER `--` is positional, not a flag.
   assert.equal(flags.installInRepo, false);
   assert.deepEqual(positional, ['--install-in-repo', 'posthog']);
 });
 
-test('decideCleanMode: claude + clean=false → no mount', () => {
-  assert.deepEqual(decideCleanMode('claude', false), { useClean: false });
+test('decideCleanMode: claude defaults to mount (parity with opencode)', () => {
+  // claude and opencode both default to the sandbox mount; the includeGit
+  // path in relayfile 0.6 keeps `.git` in the mount so git operations work
+  // inside it. --install-in-repo is the only opt-out.
+  assert.deepEqual(decideCleanMode('claude'), { useClean: true });
 });
 
-test('decideCleanMode: codex + clean=false → no mount', () => {
-  assert.deepEqual(decideCleanMode('codex', false), { useClean: false });
+test('decideCleanMode: claude + --install-in-repo disengages mount', () => {
+  assert.deepEqual(decideCleanMode('claude', true), { useClean: false });
 });
 
 test('decideCleanMode: opencode defaults to mount (skills would otherwise land in repo)', () => {
   // Opencode has no installRoot support in the SDK, so the mount is the only
   // way to keep `.opencode/skills/`, `.agents/skills/`, prpm.lock, etc. out
   // of the real repo. Default-on for non-in-repo runs.
-  assert.deepEqual(decideCleanMode('opencode', false), { useClean: true });
-  assert.deepEqual(decideCleanMode('opencode', true), { useClean: true });
+  assert.deepEqual(decideCleanMode('opencode'), { useClean: true });
 });
 
 test('decideCleanMode: opencode + --install-in-repo → no mount', () => {
-  assert.deepEqual(decideCleanMode('opencode', false, true), { useClean: false });
-  assert.deepEqual(decideCleanMode('opencode', true, true), { useClean: false });
+  assert.deepEqual(decideCleanMode('opencode', true), { useClean: false });
+});
+
+test('decideCleanMode: codex never mounts', () => {
+  // No sandbox mount support for codex; --install-in-repo is moot.
+  assert.deepEqual(decideCleanMode('codex'), { useClean: false });
+  assert.deepEqual(decideCleanMode('codex', true), { useClean: false });
 });
 
 test('stripAgentFlag: removes --agent <name> pair preserving surrounding args', () => {
@@ -203,17 +179,6 @@ test('assertSafeRelativePath: rejects empty, absolute, and path-traversal inputs
   assert.throws(() => assertSafeRelativePath('a/../../b.json'), /\.\./);
 });
 
-test('decideCleanMode: claude + clean → engaged', () => {
-  assert.deepEqual(decideCleanMode('claude', true), { useClean: true });
-});
-
-test('decideCleanMode: codex + clean → disengaged with warning naming harness', () => {
-  const codex = decideCleanMode('codex', true);
-  assert.equal(codex.useClean, false);
-  assert.match(codex.warning ?? '', /claude harness/);
-  assert.match(codex.warning ?? '', /codex/);
-});
-
 test('CLEAN_IGNORED_PATTERNS: covers the declared repo-level claude config files', () => {
   // Pinned order + exact set — canary for anyone accidentally shrinking the
   // hidden-from-session footprint. Expand via review, not silently.
@@ -328,22 +293,109 @@ test('main: extra positional after the persona selector is rejected', async () =
   assert.equal(exitCode, 1);
 });
 
-test('main: --clean on an interactive non-claude session warns and proceeds without mount', async () => {
-  // npm-provenance-publisher@best runs on codex. --clean should warn and the
-  // run should continue down the non-mount spawn path (which then fails to
-  // spawn codex because PATH is scrubbed). We should NEVER see a
+test('buildMountGitExcludeBlock: emits a header comment and one line per pattern, leading and trailing newline', () => {
+  const out = buildMountGitExcludeBlock(['CLAUDE.md', '.claude']);
+  // Leading newline ensures the block stays separated from any prior
+  // content already in .git/info/exclude.
+  assert.ok(out.startsWith('\n'), 'expected leading newline');
+  assert.ok(out.endsWith('\n'), 'expected trailing newline');
+  assert.match(out, /^# agentworkforce:/m);
+  assert.match(out, /^CLAUDE\.md$/m);
+  assert.match(out, /^\.claude$/m);
+});
+
+test('configureGitForMount: marks tracked hidden paths as skip-worktree and appends to .git/info/exclude', async () => {
+  // Integration test against a real local git repo: stand up a tiny tracked
+  // tree, run the configurator, and verify the index/exclude state. Mirrors
+  // the runtime call site (onBeforeLaunch in runInteractive), so a regression
+  // in either the ls-files plumbing or the exclude-block format surfaces here.
+  const { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } =
+    await import('node:fs');
+  const { tmpdir } = await import('node:os');
+  const { join } = await import('node:path');
+  const { spawnSync } = await import('node:child_process');
+
+  const dir = mkdtempSync(join(tmpdir(), 'aw-git-mount-'));
+  try {
+    const run = (...args: string[]) => spawnSync('git', args, { cwd: dir });
+    run('init', '-q');
+    run('config', 'user.email', 'test@example.com');
+    run('config', 'user.name', 'Test');
+    // commit.gpgsign defaults vary by host; force off so this test doesn't
+    // hang on a missing/locked GPG agent.
+    run('config', 'commit.gpgsign', 'false');
+
+    writeFileSync(join(dir, 'CLAUDE.md'), 'hidden\n');
+    mkdirSync(join(dir, '.claude'), { recursive: true });
+    writeFileSync(join(dir, '.claude', 'config.json'), '{}\n');
+    writeFileSync(join(dir, 'src.ts'), 'visible\n');
+
+    run('add', '.');
+    run('commit', '-q', '-m', 'init');
+
+    configureGitForMount(dir, ['CLAUDE.md', '.claude']);
+
+    const excludeText = readFileSync(
+      join(dir, '.git', 'info', 'exclude'),
+      'utf8'
+    );
+    assert.match(excludeText, /^CLAUDE\.md$/m);
+    assert.match(excludeText, /^\.claude$/m);
+    assert.match(excludeText, /^# agentworkforce:/m);
+
+    // `git ls-files -v` prefixes each path with a one-letter status: 'H' for
+    // unmodified, 'S' for skip-worktree. Hidden tracked files should flip to
+    // 'S'; visible files stay 'H'.
+    const ls = run('ls-files', '-v');
+    const out = ls.stdout.toString('utf8');
+    assert.match(out, /^S CLAUDE\.md$/m);
+    assert.match(out, /^S \.claude\/config\.json$/m);
+    assert.match(out, /^H src\.ts$/m);
+
+    // Temp exclude list used internally must be cleaned up.
+    const fs = await import('node:fs');
+    assert.ok(
+      !fs.existsSync(join(dir, '.git', 'info', '.aw-skip-list')),
+      'expected internal scratch file to be removed'
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('configureGitForMount: no-op when the mount has no .git', async () => {
+  // Project isn't a repo, or relayfile ran with includeGit:false. Helper
+  // must return silently rather than throw — the rest of onBeforeLaunch
+  // still has install + configFile work to do.
+  const { mkdtempSync, rmSync } = await import('node:fs');
+  const { tmpdir } = await import('node:os');
+  const { join } = await import('node:path');
+  const dir = mkdtempSync(join(tmpdir(), 'aw-git-noop-'));
+  try {
+    assert.doesNotThrow(() =>
+      configureGitForMount(dir, ['CLAUDE.md', '.claude'])
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('configureGitForMount: empty patterns is a no-op', () => {
+  // Defensive: callers that compute patterns dynamically may end up with
+  // an empty list; we should not touch the index in that case.
+  assert.doesNotThrow(() => configureGitForMount('/nonexistent-path', []));
+});
+
+test('main: codex sessions never engage the sandbox mount', async () => {
+  // npm-provenance-publisher@best runs on codex; codex has no sandbox mount
+  // support, so the run continues down the non-mount spawn path (which then
+  // fails to spawn codex because PATH is scrubbed). We should NEVER see a
   // "sandbox mount → …" line, which the mount branch emits before calling
   // launchOnMount.
   const { stderr } = await runCliCapturingStderr([
     'agent',
-    '--clean',
     'npm-provenance-publisher@best'
   ]);
-  assert.match(
-    stderr,
-    /--clean is only supported for the claude harness/,
-    'expected non-claude clean warning to surface'
-  );
   assert.ok(
     !/sandbox mount →/.test(stderr),
     `expected the mount branch to be skipped; saw stderr:\n${stderr}`
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 00c2232a..ce069cf6 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { constants, homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -57,29 +57,20 @@ Commands:
                       session.
 
                       Flags:
-                        --install-in-repo   Install skills into the repo's
+                        --install-in-repo   Disengage the sandbox mount and
+                                            install skills into the repo's
                                             harness-conventional directory
                                             (.claude/skills, .opencode/skills,
                                             .agents/skills, etc.). By default,
-                                            interactive claude sessions stage
-                                            skills under ~/.agent-workforce/
-                                            sessions/<id>/ and pass --plugin-dir;
-                                            interactive opencode sessions run
-                                            inside a @relayfile/local-mount
-                                            sandbox so npx prpm install / npx
-                                            skills add writes never touch the
-                                            real repo.
-                        --clean             Launch interactive claude inside a
-                                            @relayfile/local-mount sandbox that
-                                            also hides the repo's CLAUDE.md,
-                                            CLAUDE.local.md, .claude, and
-                                            .mcp.json from the session. Persona
-                                            skills and keychain auth are
-                                            preserved. No-op for opencode
-                                            (mount is already on by default);
-                                            codex still warns and proceeds
-                                            without a mount. Incompatible
-                                            with --install-in-repo.
+                                            interactive claude and opencode
+                                            sessions run inside a
+                                            @relayfile/local-mount sandbox so
+                                            npx prpm install / npx skills add
+                                            writes never touch the real repo
+                                            and CLAUDE.md / .claude / .mcp.json
+                                            are hidden from the session. Codex
+                                            sessions never mount and ignore
+                                            this flag.
   list [flags]        List available personas from the cascade (pwd → home →
                       library). By default shows one row per persona at the
                       recommended tier for its intent; pass --all to see every
@@ -303,7 +294,7 @@ function removeSessionRoot(sessionRoot: string | undefined): void {
  *
  *   ~/.agent-workforce/sessions/<personaId>-<timestamp>-<rand>/
  *     ├── claude/plugin/     ← skill install target + --plugin-dir
- *     └── mount/             ← @relayfile/local-mount mount (--clean only)
+ *     └── mount/             ← @relayfile/local-mount mount
  *
  * The timestamp + random suffix keep concurrent sessions from colliding on
  * the same dir. Both the skill-install path and the mount path are derived
@@ -371,7 +362,7 @@ export function assertSafeRelativePath(relPath: string): void {
   }
 }
 
-/** Patterns hidden from an interactive claude session when `--clean` is set.
+/** Patterns hidden from an interactive claude session by the sandbox mount.
  * Applied by `@relayfile/local-mount` with gitignore semantics, so bare names
  * match at any depth in the project tree (e.g. `.claude` hides both
  * `./.claude/` and `./packages/foo/.claude/`). */
@@ -407,47 +398,107 @@ export const SKILL_INSTALL_IGNORED_PATTERNS = [
   'skills-lock.json'
 ] as const;
 
+/**
+ * Build the block appended to `<mount>/.git/info/exclude` so untracked-and-
+ * hidden files (e.g. `.claude/skills/` materialized by skill installs, or
+ * `opencode.json` written by `onBeforeLaunch`) don't surface under
+ * "Untracked files" in `git status` inside the mount.
+ *
+ * Exported pure helper for unit-testing the formatting separately from the
+ * disk-writing wrapper below.
+ */
+export function buildMountGitExcludeBlock(patterns: readonly string[]): string {
+  const lines = [
+    '',
+    '# agentworkforce: patterns hidden from this sandboxed session.',
+    '# Tracked paths matching these patterns are also marked skip-worktree',
+    '# so `git status` does not report them as deleted.',
+    ...patterns,
+    ''
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * Configure the mount's per-session `.git` so paths hidden by the relayfile
+ * mount don't show as deleted/untracked inside the sandbox.
+ *
+ * - Appends `patterns` to `.git/info/exclude` so untracked-and-hidden files
+ *   don't show up under "Untracked files".
+ * - Marks every tracked file matching one of the patterns as skip-worktree
+ *   so `git status` doesn't list it as deleted (the work tree omits it on
+ *   purpose, not by user action).
+ *
+ * Best-effort: if the mount has no `.git` (project isn't a repo, or
+ * `includeGit: false`) or any git command fails, returns silently. The
+ * mount's `.git` is per-session and `noSyncBack` per relayfile 0.6+, so
+ * writes here are sandboxed and never leak to the user's main checkout.
+ */
+export function configureGitForMount(mountDir: string, patterns: readonly string[]): void {
+  if (patterns.length === 0) return;
+  const infoDir = join(mountDir, '.git', 'info');
+  if (!existsSync(infoDir)) return;
+
+  appendFileSync(join(infoDir, 'exclude'), buildMountGitExcludeBlock(patterns));
+
+  // Use git's own gitignore matcher to pick which tracked files to flag,
+  // keeping semantics aligned with relayfile's (gitignore-style, basename-
+  // anywhere) filter. `--cached -i --exclude-from=<file>` (without
+  // `--exclude-standard`) lists only tracked files matched by the supplied
+  // patterns — not the repo's own .gitignore.
+  const tmpExcludes = join(infoDir, '.aw-skip-list');
+  try {
+    writeFileSync(tmpExcludes, patterns.join('\n') + '\n');
+    const ls = spawnSync(
+      'git',
+      ['ls-files', '-z', '--cached', '-i', `--exclude-from=${tmpExcludes}`],
+      { cwd: mountDir }
+    );
+    if (ls.status !== 0) return;
+    const files = ls.stdout.toString('utf8').split('\0').filter(Boolean);
+    if (files.length === 0) return;
+    // Chunk to stay well under typical argv-length limits on huge repos.
+    const CHUNK = 200;
+    for (let i = 0; i < files.length; i += CHUNK) {
+      spawnSync(
+        'git',
+        ['update-index', '--skip-worktree', '--', ...files.slice(i, i + CHUNK)],
+        { cwd: mountDir }
+      );
+    }
+  } finally {
+    try {
+      rmSync(tmpExcludes, { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
 /**
  * Decide whether to run the interactive session inside a
  * `@relayfile/local-mount` sandbox.
  *
- * - Claude: mount only engages when the user passes `--clean` explicitly
- *   (its purpose there is to hide CLAUDE.md / .claude / .mcp.json from the
- *   session). Out-of-repo skill staging is handled separately via
- *   `installRoot` + `--plugin-dir`.
- * - Opencode: the SDK cannot stage skills out-of-repo for this harness
- *   (there is no `installRoot` support), so the mount is the only way to
- *   keep `npx prpm install` / `npx skills add` writes out of the project.
- *   Default to mount unless the user opts in with `--install-in-repo`.
- * - Codex: no auto-mount yet. `--clean` still emits the existing
- *   "claude-only" warning so current behavior is preserved.
+ * - Claude / opencode: mount engages by default. Hides CLAUDE.md / .claude
+ *   / .mcp.json (claude) and routes `npx prpm install` / `npx skills add`
+ *   writes (both) into the sandbox. Disengage with `--install-in-repo`.
+ * - Codex: no sandbox mount support, always runs against the real cwd.
  *
  * Pure — no side effects, trivially testable.
  */
 export function decideCleanMode(
   harness: Harness,
-  clean: boolean,
   installInRepo = false
-): { useClean: boolean; warning?: string } {
-  if (harness === 'claude') {
-    return { useClean: clean };
-  }
-  if (harness === 'opencode') {
-    if (installInRepo) return { useClean: false };
-    return { useClean: true };
-  }
-  if (clean) {
-    return {
-      useClean: false,
-      warning: `--clean is only supported for the claude harness (this session uses ${harness}). Ignoring flag.`
-    };
+): { useClean: boolean } {
+  if (harness === 'claude' || harness === 'opencode') {
+    return { useClean: !installInRepo };
   }
   return { useClean: false };
 }
 
 async function runInteractive(
   selection: PersonaSelection,
-  options: { installInRepo?: boolean; clean?: boolean } = {}
+  options: { installInRepo?: boolean } = {}
 ): Promise<number> {
   const { runtime, personaId, tier } = selection;
   // `installRoot` (out-of-repo skill staging via `--plugin-dir`) is currently
@@ -456,18 +507,13 @@ async function runInteractive(
   // running them inside a @relayfile/local-mount sandbox (see `useClean`
   // below). The --install-in-repo flag forces legacy in-repo installs
   // across the board.
-  const cleanDecision = decideCleanMode(
+  const useClean = decideCleanMode(
     runtime.harness,
-    options.clean === true,
     options.installInRepo === true
-  );
-  if (cleanDecision.warning) {
-    process.stderr.write(`warning: ${cleanDecision.warning}\n`);
-  }
-  const useClean = cleanDecision.useClean;
+  ).useClean;
   // A session dir is needed whenever we either (a) stage skills out-of-repo
-  // via claude's installRoot, or (b) open a mount. Opencode reaches (b) by
-  // default; claude reaches both when --clean is set, and just (a) otherwise.
+  // via claude's installRoot, or (b) open a mount. Both engage for claude/
+  // opencode by default; --install-in-repo disengages both.
   const useSessionDir =
     !options.installInRepo && (runtime.harness === 'claude' || useClean);
   const sessionRoot = useSessionDir ? generateSessionRoot(personaId) : undefined;
@@ -521,9 +567,9 @@ async function runInteractive(
   for (const w of spec.warnings) process.stderr.write(`warning: ${w}\n`);
 
   // Config-file materialization strategy:
-  //  - Mount path (opencode default, claude --clean): write each configFile
-  //    into the mount dir via onBeforeLaunch, so it lives only in the
-  //    sandbox and is torn down with the session.
+  //  - Mount path (claude/opencode default): write each configFile into the
+  //    mount dir via onBeforeLaunch, so it lives only in the sandbox and is
+  //    torn down with the session.
   //  - Non-mount path: today the only configFile producer is opencode
   //    (opencode.json for the --agent wiring), and the non-mount opencode
   //    path only engages under --install-in-repo. Writing opencode.json
@@ -570,12 +616,14 @@ async function runInteractive(
   // Mount branch: delegate process lifecycle (spawn, signal forwarding,
   // syncback, cleanup) to @relayfile/local-mount.
   //
-  // For claude: mount engages only when `--clean` is set, to hide the repo's
-  // claude config from the session. Skill plugin dir lives outside the mount
-  // at an absolute path, so claude resolves `--plugin-dir` normally.
+  // For claude and opencode: mount engages by default (unless
+  // `--install-in-repo`). For claude this hides CLAUDE.md / .claude /
+  // .mcp.json; for opencode it routes `npx prpm install` / `npx skills
+  // add` writes into the sandbox (skill plugin dir for claude lives
+  // outside the mount at an absolute path, so claude still resolves
+  // `--plugin-dir` normally).
   //
-  // For opencode: mount engages by default (unless `--install-in-repo`), and
-  // the install itself runs inside the mount via `onBeforeLaunch` so that
+  // The install itself runs inside the mount via `onBeforeLaunch` so that
   // `npx prpm install` / `npx skills add` writes land in the sandbox. The
   // skill-install paths are added to `ignoredPatterns` so they are neither
   // copied in from the real repo nor synced back on exit.
@@ -663,6 +711,13 @@ async function runInteractive(
         // branch: persona env overlays the inherited environment.
         env: resolvedEnv ? { ...process.env, ...resolvedEnv } : process.env,
         agentName: personaId,
+        // Pull `.git` into the mount so git commands work inside the
+        // sandbox. relayfile 0.6+ treats this as a one-way project→mount
+        // sync: host-side `.git` changes propagate in, mount-side commits/
+        // refs stay sandboxed and are discarded on cleanup. The agent must
+        // `git push` to persist work — local-only commits evaporate with
+        // the session.
+        includeGit: true,
         // Second Ctrl-C aborts this signal → local-mount skips autosync's
         // draining reconcile and returns the partial syncBack count. Cleanup
         // still runs, so there's no leaked mount dir.
@@ -693,24 +748,26 @@ async function runInteractive(
             process.stderr.write(`✓ ${message}\n`);
           }
         },
-        ...(deferInstallToMount || hasConfigFiles
-          ? {
-              onBeforeLaunch: (dir: string) => {
-                if (deferInstallToMount) {
-                  runInstallOrThrow(install.command, installLabel, dir);
-                }
-                for (const file of spec.configFiles) {
-                  assertSafeRelativePath(file.path);
-                  const target = join(dir, file.path);
-                  // mkdir -p for any subdirs in file.path — the
-                  // InteractiveConfigFile contract allows nested relative
-                  // paths, and writeFileSync would otherwise throw ENOENT.
-                  mkdirSync(dirname(target), { recursive: true });
-                  writeFileSync(target, file.contents, 'utf8');
-                }
-              }
-            }
-          : {})
+        onBeforeLaunch: (dir: string) => {
+          // Run before install / configFile writes so the freshly written
+          // files (e.g. `.opencode/`, `opencode.json`) aren't yet present
+          // when we run `git ls-files` to pick skip-worktree candidates —
+          // we don't need them flagged in the index, just hidden via the
+          // `.git/info/exclude` block.
+          configureGitForMount(dir, ignoredPatterns);
+          if (deferInstallToMount) {
+            runInstallOrThrow(install.command, installLabel, dir);
+          }
+          for (const file of spec.configFiles) {
+            assertSafeRelativePath(file.path);
+            const target = join(dir, file.path);
+            // mkdir -p for any subdirs in file.path — the
+            // InteractiveConfigFile contract allows nested relative
+            // paths, and writeFileSync would otherwise throw ENOENT.
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, file.contents, 'utf8');
+          }
+        }
       });
       return result.exitCode;
     } catch (err) {
@@ -1275,22 +1332,20 @@ export async function main(): Promise<void> {
   const selection = buildSelection(target.spec, target.tier, target.kind);
 
   const code = await runInteractive(selection, {
-    installInRepo: flags.installInRepo,
-    clean: flags.clean
+    installInRepo: flags.installInRepo
   });
   process.exit(code);
 }
 
 export interface AgentFlags {
   installInRepo: boolean;
-  clean: boolean;
 }
 
 export function parseAgentArgs(args: readonly string[]): {
   flags: AgentFlags;
   positional: string[];
 } {
-  const flags: AgentFlags = { installInRepo: false, clean: false };
+  const flags: AgentFlags = { installInRepo: false };
   const positional: string[] = [];
   let seenDoubleDash = false;
   for (const arg of args) {
@@ -1306,23 +1361,12 @@ export function parseAgentArgs(args: readonly string[]): {
       flags.installInRepo = true;
       continue;
     }
-    if (arg === '--clean') {
-      flags.clean = true;
-      continue;
-    }
     if (arg === '-h' || arg === '--help') {
       process.stdout.write(USAGE);
       process.exit(0);
     }
     positional.push(arg);
   }
-  if (flags.installInRepo && flags.clean) {
-    die(
-      'agent: --install-in-repo and --clean are mutually exclusive. ' +
-        '--install-in-repo stages skills into the real repo; --clean hides ' +
-        'the repo behind a mount. Pick one.'
-    );
-  }
   return { flags, positional };
 }
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b82620da..eb4b3346 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -33,8 +33,8 @@ importers:
         specifier: workspace:*
         version: link:../workload-router
       '@relayfile/local-mount':
-        specifier: ^0.5.0
-        version: 0.5.0
+        specifier: ^0.6.0
+        version: 0.6.0
       ora:
         specifier: ^9.4.0
         version: 9.4.0
@@ -139,8 +139,8 @@ packages:
     resolution: {integrity: sha512-tmmZ3lQxAe/k/+rNnXQRawJ4NjxO2hqiOLTHvWchtGZULp4RyFeh6aU4XdOYBFe2KE1oShQTv4AblOs2iOrNnQ==}
     engines: {node: '>= 10.0.0'}
 
-  '@relayfile/local-mount@0.5.0':
-    resolution: {integrity: sha512-gz/onW56+Qg7WELNopS46+hnEl5BWzlOVZ0WJ4lleL01OlSfFvxNcvJkxh1GNJaQEDCA0W37OoKxKfOdjGZ+RQ==}
+  '@relayfile/local-mount@0.6.0':
+    resolution: {integrity: sha512-Iz2a99ACOiA9pnS+Y8FBik/DqzyhSE9aKMKFkGkx0DQOI/qLveD/Kae9vBQudbvD2ZEcDAtrK86eE44f2yCjMA==}
     engines: {node: '>=18'}
 
   '@types/node@22.19.15':
@@ -336,7 +336,7 @@ snapshots:
       '@parcel/watcher-win32-ia32': 2.5.6
       '@parcel/watcher-win32-x64': 2.5.6
 
-  '@relayfile/local-mount@0.5.0':
+  '@relayfile/local-mount@0.6.0':
     dependencies:
       '@parcel/watcher': 2.5.6
       ignore: 7.0.5