From 09b200426aea4567d1fcd70d2a3993da6387937d Mon Sep 17 00:00:00 2001
From: Will Washburn <will.washburn@gmail.com>
Date: Sat, 18 Apr 2026 23:02:10 -0400
Subject: [PATCH 1/3] Add --clean and out-of-repo skill staging

Introduce interactive Claude session staging and a clean sandbox mode.

Features:
- New CLI flags: --install-in-repo (legacy) and --clean (mount sandbox). They are mutually exclusive.
- By default interactive claude sessions stage skills under ~/.agent-workforce/sessions/<id>/claude/plugin and pass --plugin-dir to Claude so the repo's .claude/ is not touched. --install-in-repo restores legacy in-repo installs.
- --clean launches the harness inside a @relayfile/local-mount symlink mount that hides repo-level Claude config (CLAUDE.md, CLAUDE.local.md, .claude, .mcp.json) while preserving persona skills and user-level ~/.claude/. One-shot runs and non-claude harnesses print notes/warnings and ignore --clean.

Code changes:
- CLI: parseAgentArgs, AgentFlags, session path generation, install root plumbing, decideCleanMode, launchOnMount integration, and wiring of pluginDirs to interactive spec. Added runtime checks and messaging for one-shot and non-claude behavior.
- workload-router: add SkillMaterializationOptions.installRoot, materializeSkills/materializeSkillsFor/useSelection/usePersona support for installRoot, scaffold generation, session-mode install/cleanup behavior, and related tests.
- harness-kit: support pluginDirs (emit --plugin-dir for claude, warn for others).
- Tests added/updated across packages (cli, harness-kit, workload-router) exercising flag parsing, clean behavior, pluginDirs, and materialization.
- package.json: add @relayfile/local-mount dependency and update README docs describing skill staging and clean mode.

This change isolates interactive Claude sessions from repo artifacts and provides an opt-out legacy path, while leaving one-shot and other harnesses unchanged for v1.
---
 README.md                                  |  66 ++++++
 packages/cli/README.md                     | 173 ++++++++++++++-
 packages/cli/package.json                  |   3 +-
 packages/cli/src/cli.test.ts               | 235 ++++++++++++++++++++
 packages/cli/src/cli.ts                    | 238 +++++++++++++++++++--
 packages/harness-kit/src/harness.test.ts   |  54 +++++
 packages/harness-kit/src/harness.ts        |  26 ++-
 packages/workload-router/src/index.test.ts |  92 +++++++-
 packages/workload-router/src/index.ts      | 168 +++++++++++++--
 9 files changed, 1017 insertions(+), 38 deletions(-)
 create mode 100644 packages/cli/src/cli.test.ts

diff --git a/README.md b/README.md
index 82471239..163dba3f 100644
--- a/README.md
+++ b/README.md
@@ -109,6 +109,72 @@ The full docs — cascade rules, `${VAR}` interpolation, MCP transport
 options, permission grammar, troubleshooting — live in
 **[packages/cli/README.md](./packages/cli/README.md)**.
 
+### Skill staging (interactive claude only)
+
+Interactive `claude` sessions stage skills **outside the repo** by default.
+The CLI materializes a Claude Code plugin under the user's home directory
+and passes it via `--plugin-dir`, so the session sees exactly the persona's
+declared skills — and nothing the repo happens to have in `.claude/skills/`.
+
+```
+~/.agent-workforce/
+└── sessions/<personaId>-<timestamp>-<rand>/
+    └── claude/
+        └── plugin/                                ← passed as --plugin-dir
+            ├── .claude-plugin/plugin.json         ← generated scaffold
+            ├── skills → .claude/skills            ← relative symlink
+            └── .claude/skills/<name>/SKILL.md     ← prpm install output
+```
+
+On exit the whole stage dir is removed with a single `rm -rf`. To fall back
+to the legacy behavior and install into the repo's `.claude/skills/`, pass
+`--install-in-repo`:
+
+```bash
+agent-workforce agent --install-in-repo code-reviewer@best
+```
+
+V1 scope: claude interactive only. codex, opencode, and one-shot runs still
+use the repo-relative install path. A content-addressed
+`~/.agent-workforce/cache/` 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`)
+
+For interactive `claude` sessions, `--clean` launches the harness inside a
+[`@relayfile/local-mount`](https://www.npmjs.com/package/@relayfile/local-mount)
+sandbox that hides repo-level Claude Code configuration from the model:
+
+| Hidden in `--clean` mode | Still visible |
+| --- | --- |
+| `CLAUDE.md` (at any depth) | `~/.claude/CLAUDE.md` (user-level) |
+| `CLAUDE.local.md` | `~/.claude/skills/` (user-level skills) |
+| `.claude/` | persona's staged skills (via `--plugin-dir`) |
+| `.mcp.json` | persona's own `mcpServers` block |
+|  | your keychain auth (unchanged) |
+
+```bash
+agent-workforce agent --clean 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 or to a
+one-shot run 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)**
+for the full mount layout and semantics.
+
 ## Packages
 
 - `packages/workload-router` — TypeScript SDK for typed persona + routing profile resolution (harness-agnostic).
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 93470707..6fb94efc 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -380,22 +380,34 @@ persona session, add it to the persona's `mcpServers` block.
 ### Interactive
 
 ```sh
-agent-workforce agent <persona>[@<tier>]
+agent-workforce agent [--install-in-repo] [--clean] <persona>[@<tier>]
 ```
 
+`--install-in-repo` and `--clean` are mutually exclusive — see
+[**Clean mode**](#clean-mode) below.
+
 1. Resolves the persona, walks the cascade, resolves `$VAR` refs.
-2. Runs skill install (`prpm install …`) if the persona declares any skills.
-3. Execs the harness binary with stdio inherited:
+2. **Stages skills outside the repo by default** (claude interactive only —
+   see **Skill staging** below). For codex / opencode, or when
+   `--install-in-repo` is passed, falls back to the legacy repo-relative
+   install path (`.claude/skills/`, `.agents/skills/`, `.skills/`).
+3. Runs skill install (`prpm install …`) if the persona declares any skills,
+   using the computed target (stage dir or repo).
+4. Execs the harness binary with stdio inherited:
    - `claude`: `claude --model <model> --append-system-prompt <prompt>
-     --mcp-config '<json>' --strict-mcp-config`. Both flags are always passed
-     so the session only sees the persona's declared MCP servers — see
-     **MCP isolation** above.
+     --mcp-config '<json>' --strict-mcp-config [--plugin-dir <stage>]`. The
+     `--plugin-dir` flag is appended when the session uses out-of-repo
+     staging so Claude Code loads exactly the staged skills — and nothing
+     the repo happens to carry. Both MCP flags are always passed so the
+     session only sees the persona's declared MCP servers (see **MCP
+     isolation** above).
    - `codex`: `codex -m <model>` with the system prompt as the initial
      positional `[PROMPT]`. (codex has no `--system-prompt` flag today.)
    - `opencode`: `opencode --model <model>` with the system prompt as the
      initial argument.
-4. Runs the skill cleanup command on exit, regardless of exit status.
-5. Propagates the harness's exit code.
+5. Runs the skill cleanup command on exit, regardless of exit status. In
+   stage-dir mode this is a single `rm -rf <stage-dir>`.
+6. Propagates the harness's exit code.
 
 Signals (SIGINT, SIGTERM) are forwarded to the child.
 
@@ -414,6 +426,151 @@ Env from the persona is passed through via `ExecuteOptions.env`. `mcpServers`
 is currently **ignored with a warning** in one-shot mode — the SDK workflow
 path doesn't thread MCP config yet.
 
+One-shot mode still installs into the repo regardless of `--install-in-repo`;
+out-of-repo staging only applies to the interactive path today because the
+agent-relay workflow SDK doesn't yet thread `--plugin-dir` into the claude
+agent adapter. `--install-in-repo` passed to a one-shot run prints a `note:`
+and is a no-op.
+
+## Skill staging
+
+By default, interactive `claude` sessions stage skills under the user's home
+directory instead of the current repo. Nothing gets written to `.claude/` in
+the working tree, and the session only sees the skills the persona declares
+— never whatever skills the repo happens to carry on disk.
+
+**Layout:**
+
+```
+~/.agent-workforce/
+└── sessions/<personaId>-<timestamp>-<rand>/
+    └── claude/
+        └── plugin/                                ← passed as --plugin-dir
+            ├── .claude-plugin/plugin.json         ← generated scaffold
+            ├── skills → .claude/skills            ← relative symlink
+            └── .claude/skills/<name>/SKILL.md     ← prpm install output
+```
+
+- **Stage dir** — `~/.agent-workforce/sessions/<id>/claude/plugin/`.
+  `<id>` is `<personaId>-<base36-timestamp>-<hex-random>` so parallel
+  sessions never collide.
+- **Plugin wrapper** — the CLI writes a minimal `.claude-plugin/plugin.json`
+  (`{"name":"agent-workforce-session","version":"0.0.0",…}`) and a relative
+  symlink `skills → .claude/skills` so Claude Code's plugin layout
+  (`skills/<name>/SKILL.md`) resolves to prpm's actual output
+  (`.claude/skills/<name>/SKILL.md`) without moving any files.
+- **prpm install** — still runs `npx -y prpm install <ref> --as claude`,
+  but inside `cd <stage-dir>` so the harness-conventional `.claude/skills/`
+  lands in the stage dir, not the repo.
+- **Cleanup** — on exit, a single `rm -rf <stage-dir>` removes the whole
+  session directory. The provider lockfile (`prpm.lock`) is inside the stage
+  dir and goes with it — no repeat-run resolution cache today. Restart cost
+  is one prpm install per session.
+
+**Opt-out — `--install-in-repo`:**
+
+Pass `--install-in-repo` to fall back to the legacy behavior (skills land in
+the repo's `.claude/skills/` directory, cleaned on exit):
+
+```sh
+agent-workforce agent --install-in-repo code-reviewer@best
+```
+
+Useful when you want to inspect the installed skills on disk, or when the
+stage dir conflicts with something else (network filesystem, read-only
+`$HOME`, etc.).
+
+**Caveats for V1:**
+
+- **Claude harness only.** codex and opencode continue to install into their
+  conventional repo-relative directories. The SDK throws if `installRoot` is
+  passed with a non-claude harness.
+- **No cache layer yet.** Every interactive session runs a fresh prpm install
+  into a new stage dir. A `~/.agent-workforce/cache/` content-addressed cache
+  is planned but not wired up.
+- **One-shot path unchanged.** See the paragraph under "One-shot" above.
+
+## Clean mode
+
+`--clean` launches an interactive claude session 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.
+
+```sh
+agent-workforce agent --clean <persona>[@<tier>]
+```
+
+**What's hidden (gitignore semantics, at any depth):**
+
+| Pattern | Rationale |
+| --- | --- |
+| `CLAUDE.md` | Repo-level project memory |
+| `CLAUDE.local.md` | Developer-local project memory |
+| `.claude` | Repo Claude Code config dir (settings, agents, skills, commands) |
+| `.mcp.json` | Repo-declared MCP servers |
+
+**What's preserved:**
+
+- **User-level context** under `~/.claude/` — `CLAUDE.md`, skills, etc.
+  still load. `--clean` 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 `mcpServers`.** Still passed via `--mcp-config` — unaffected
+  by the mount. The repo's `.mcp.json` is hidden regardless.
+
+### Session layout
+
+Both the skill install root and the clean mount live under a single
+session directory. The session id (`<personaId>-<base36-timestamp>-<hex>`)
+is generated once and both paths are derived from it:
+
+```
+~/.agent-workforce/
+└── sessions/<personaId>-<timestamp>-<rand>/
+    ├── claude/
+    │   └── plugin/                                ← passed as --plugin-dir
+    │       ├── .claude-plugin/plugin.json
+    │       ├── skills → .claude/skills
+    │       └── .claude/skills/<name>/SKILL.md
+    └── mount/                                     ← --clean: claude's cwd
+        └── <mirrored project tree, minus the hidden patterns>
+```
+
+`@relayfile/local-mount` handles mount creation, process spawn,
+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).
+- **`--clean` on a one-shot run is a warning no-op.** The agent-relay
+  workflow SDK doesn't thread mount integration today; matches how
+  `--install-in-repo` behaves in one-shot mode.
+
+### Example
+
+```sh
+# Interactive PostHog session with the repo's CLAUDE.md, .claude/, and
+# .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
+```
+
+On exit: mount is synced back to the real repo, then torn down; skill
+stage dir is cleaned up by the existing `rm -rf` cleanup command.
+
 ## Selecting a harness per tier
 
 A persona's three tiers can use different harnesses. The built-in
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 92a54b06..930ae32f 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -14,7 +14,8 @@
   ],
   "dependencies": {
     "@agentworkforce/harness-kit": "workspace:*",
-    "@agentworkforce/workload-router": "workspace:*"
+    "@agentworkforce/workload-router": "workspace:*",
+    "@relayfile/local-mount": "^0.2.0"
   },
   "repository": {
     "type": "git",
diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.ts
new file mode 100644
index 00000000..66724238
--- /dev/null
+++ b/packages/cli/src/cli.test.ts
@@ -0,0 +1,235 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { CLEAN_IGNORED_PATTERNS, decideCleanMode, parseAgentArgs } from './cli.js';
+
+// The conflict-detection path inside parseAgentArgs uses the module-local
+// `die()` helper, which calls process.exit(1) after writing to stderr. Tests
+// trap both so we can assert on the emitted error text without killing the
+// test runner.
+interface ExitTrap {
+  exits: number[];
+  stderr: string;
+  stdout: string;
+  restore: () => void;
+}
+
+function trapExit(): ExitTrap {
+  const trap: ExitTrap = {
+    exits: [],
+    stderr: '',
+    stdout: '',
+    restore: () => {
+      /* replaced below */
+    }
+  };
+
+  const origExit = process.exit;
+  const origErr = process.stderr.write.bind(process.stderr);
+  const origOut = process.stdout.write.bind(process.stdout);
+
+  const fakeExit = ((code?: number) => {
+    trap.exits.push(code ?? 0);
+    throw new Error(`__exit_trap__:${code ?? 0}`);
+  }) as typeof process.exit;
+
+  process.exit = fakeExit;
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    trap.stderr += typeof chunk === 'string' ? chunk : chunk.toString();
+    return true;
+  }) as typeof process.stderr.write;
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    trap.stdout += typeof chunk === 'string' ? chunk : chunk.toString();
+    return true;
+  }) as typeof process.stdout.write;
+
+  trap.restore = () => {
+    process.exit = origExit;
+    process.stderr.write = origErr;
+    process.stdout.write = origOut;
+  };
+  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);
+  assert.deepEqual(positional, ['posthog@best']);
+});
+
+test('parseAgentArgs: --clean accepts a task after the selector', () => {
+  const { flags, positional } = parseAgentArgs([
+    '--clean',
+    'review@best-value',
+    'look at the diff'
+  ]);
+  assert.equal(flags.clean, true);
+  assert.deepEqual(positional, ['review@best-value', 'look at the diff']);
+});
+
+test('parseAgentArgs: no flags → both 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);
+  assert.equal(flags.installInRepo, false);
+  assert.deepEqual(positional, ['--install-in-repo', 'posthog']);
+});
+
+test('decideCleanMode: clean=false → no-op regardless of harness', () => {
+  assert.deepEqual(decideCleanMode('claude', false), { useClean: false });
+  assert.deepEqual(decideCleanMode('codex', false), { useClean: false });
+  assert.deepEqual(decideCleanMode('opencode', false), { useClean: false });
+});
+
+test('decideCleanMode: claude + clean → engaged', () => {
+  assert.deepEqual(decideCleanMode('claude', true), { useClean: true });
+});
+
+test('decideCleanMode: non-claude + 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/);
+
+  const opencode = decideCleanMode('opencode', true);
+  assert.equal(opencode.useClean, false);
+  assert.match(opencode.warning ?? '', /opencode/);
+});
+
+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.
+  assert.deepEqual([...CLEAN_IGNORED_PATTERNS], [
+    'CLAUDE.md',
+    'CLAUDE.local.md',
+    '.claude',
+    '.mcp.json'
+  ]);
+});
+
+// Integration-ish subprocess helper: spawn the built CLI, collect stderr,
+// and return once the child exits. We force the harness binary to fail to
+// spawn (PATH scrubbed) so these runs terminate quickly regardless of what
+// the dispatch path tries next — the assertions target stderr shape alone.
+async function runCliCapturingStderr(args: string[]): Promise<{
+  stderr: string;
+  exitCode: number | null;
+}> {
+  const { spawn } = await import('node:child_process');
+  const { fileURLToPath } = await import('node:url');
+  const { join, dirname } = await import('node:path');
+
+  const here = dirname(fileURLToPath(import.meta.url));
+  // Tests run out of dist/, so cli.js is a sibling.
+  const cliPath = join(here, 'cli.js');
+
+  const child = spawn(process.execPath, [cliPath, ...args], {
+    env: {
+      ...process.env,
+      // Force any harness spawn to ENOENT so the run terminates quickly.
+      PATH: '/nonexistent-path-for-test',
+      POSTHOG_API_KEY: 'dummy'
+    },
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+
+  let stderr = '';
+  child.stderr.on('data', (buf: Buffer) => {
+    stderr += buf.toString();
+  });
+
+  const exitCode: number | null = await new Promise((resolve) => {
+    let settled = false;
+    child.on('exit', (code) => {
+      if (settled) return;
+      settled = true;
+      resolve(code);
+    });
+    // Safety net — kill after 15s so a hung subprocess never wedges the suite.
+    setTimeout(() => {
+      if (child.exitCode === null) {
+        child.kill('SIGKILL');
+        if (!settled) {
+          settled = true;
+          resolve(null);
+        }
+      }
+    }, 15_000);
+  });
+
+  return { stderr, exitCode };
+}
+
+test('main: --clean on a one-shot run emits the ignore note', async () => {
+  const { stderr } = await runCliCapturingStderr([
+    'agent',
+    '--clean',
+    'posthog',
+    'hello'
+  ]);
+  assert.match(stderr, /--clean is ignored for one-shot runs/);
+});
+
+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
+  // "clean mount → …" line, which the clean 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(
+    !/clean mount →/.test(stderr),
+    `expected the clean mount branch to be skipped; saw stderr:\n${stderr}`
+  );
+});
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 8ce506c0..6bab0144 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
-import { constants } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { constants, homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 import {
   HARNESS_VALUES,
@@ -25,16 +28,33 @@ import {
   type HarnessAvailability,
   type InteractiveSpec
 } from '@agentworkforce/harness-kit';
+import { launchOnMount } from '@relayfile/local-mount';
 import { loadLocalPersonas, type PersonaSource } from './local-personas.js';
 
 const USAGE = `Usage: agent-workforce <command> [args...]
 
 Commands:
-  agent <persona>[@<tier>] [task...]
+  agent [flags] <persona>[@<tier>] [task...]
                       Run a persona. Tier one of: ${PERSONA_TIERS.join(' | ')}
                       (default: best-value). If [task] is provided, runs one-shot
                       non-interactively; otherwise drops into an interactive
                       harness session.
+
+                      Flags:
+                        --install-in-repo   Install skills into the repo's
+                                            .claude/skills/ (legacy). By default,
+                                            interactive claude sessions stage
+                                            skills under ~/.agent-workforce/
+                                            sessions/<id>/ and pass --plugin-dir
+                                            so the repo is never touched.
+                        --clean             Launch interactive claude inside a
+                                            @relayfile/local-mount sandbox that
+                                            hides the repo's CLAUDE.md,
+                                            CLAUDE.local.md, .claude, and
+                                            .mcp.json from the session. Persona
+                                            skills and keychain auth are
+                                            preserved. Claude interactive only;
+                                            incompatible with --install-in-repo.
   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
@@ -199,9 +219,85 @@ function runCleanup(command: readonly string[], commandString: string): void {
   spawnSync(bin, args, { stdio: 'inherit', shell: false });
 }
 
-function runInteractive(selection: PersonaSelection): Promise<number> {
-  const ctx = useSelection(selection);
+/**
+ * Compute the absolute root directory for an interactive claude session.
+ * Layout (under `root`):
+ *
+ *   ~/.agent-workforce/sessions/<personaId>-<timestamp>-<rand>/
+ *     ├── claude/plugin/     ← skill install target + --plugin-dir
+ *     └── mount/             ← @relayfile/local-mount mount (--clean only)
+ *
+ * The timestamp + random suffix keep concurrent sessions from colliding on
+ * the same dir. Both the skill-install path and the mount path are derived
+ * from the same `root` so a single session ID describes the whole run.
+ */
+function generateSessionRoot(personaId: string): string {
+  const sessionId = `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+  return join(homedir(), '.agent-workforce', 'sessions', `${personaId}-${sessionId}`);
+}
+
+function sessionInstallRoot(sessionRoot: string): string {
+  return join(sessionRoot, 'claude', 'plugin');
+}
+
+function sessionMountDir(sessionRoot: string): string {
+  return join(sessionRoot, 'mount');
+}
+
+/** Patterns hidden from an interactive claude session when `--clean` is set.
+ * 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/`). */
+export const CLEAN_IGNORED_PATTERNS = [
+  'CLAUDE.md',
+  'CLAUDE.local.md',
+  '.claude',
+  '.mcp.json'
+] as const;
+
+/**
+ * Decide whether `--clean` should engage for this run. Returns a warning
+ * string when the flag was requested but cannot apply (e.g. non-claude
+ * harness); callers emit the warning to stderr and proceed with
+ * `useClean: false`. Pure — no side effects, trivially testable.
+ */
+export function decideCleanMode(
+  harness: Harness,
+  clean: boolean
+): { useClean: boolean; warning?: string } {
+  if (!clean) return { useClean: false };
+  if (harness !== 'claude') {
+    return {
+      useClean: false,
+      warning: `--clean is only supported for the claude harness (this session uses ${harness}). Ignoring flag.`
+    };
+  }
+  return { useClean: true };
+}
+
+async function runInteractive(
+  selection: PersonaSelection,
+  options: { installInRepo?: boolean; clean?: boolean } = {}
+): Promise<number> {
   const { runtime, personaId, tier } = selection;
+  // Out-of-repo staging only applies to the claude harness today (it's the
+  // only one with a `--plugin-dir` hook). For codex/opencode, keep the legacy
+  // behavior of installing into the repo's harness-conventional directory.
+  // The --install-in-repo flag forces legacy behavior across the board.
+  const useSessionDir = !options.installInRepo && runtime.harness === 'claude';
+  const sessionRoot = useSessionDir ? generateSessionRoot(personaId) : undefined;
+  const installRoot = sessionRoot ? sessionInstallRoot(sessionRoot) : undefined;
+  // --clean applies to interactive claude only. For non-claude harnesses, warn
+  // and drop the flag (same pattern as pluginDirs warnings in buildInteractiveSpec).
+  const cleanDecision = decideCleanMode(runtime.harness, options.clean === true);
+  if (cleanDecision.warning) {
+    process.stderr.write(`warning: ${cleanDecision.warning}\n`);
+  }
+  const useClean = cleanDecision.useClean;
+  const ctx = useSelection(
+    selection,
+    installRoot !== undefined ? { installRoot } : {}
+  );
   const { install } = ctx;
   process.stderr.write(`→ ${personaId} [${tier}] via ${runtime.harness} (${runtime.model})\n`);
 
@@ -215,7 +311,8 @@ function runInteractive(selection: PersonaSelection): Promise<number> {
 
   if (install.plan.installs.length > 0) {
     const skillIds = install.plan.installs.map((i) => i.skillId).join(', ');
-    runInstall(install.command, `Installing skills: ${skillIds}`);
+    const targetLabel = installRoot ? ` → ${installRoot}` : '';
+    runInstall(install.command, `Installing skills: ${skillIds}${targetLabel}`);
   }
 
   const spec = buildInteractiveSpec({
@@ -223,7 +320,8 @@ function runInteractive(selection: PersonaSelection): Promise<number> {
     model: runtime.model,
     systemPrompt: runtime.systemPrompt,
     mcpServers: resolvedMcp,
-    permissions: selection.permissions
+    permissions: selection.permissions,
+    ...(installRoot !== undefined ? { pluginDirs: [installRoot] } : {})
   });
   for (const w of spec.warnings) process.stderr.write(`warning: ${w}\n`);
   const finalArgs = spec.initialPrompt ? [...spec.args, spec.initialPrompt] : [...spec.args];
@@ -249,8 +347,42 @@ function runInteractive(selection: PersonaSelection): Promise<number> {
     }
   }
   if (spec.initialPrompt) summary.push('initial-prompt=<systemPrompt>');
+  if (useClean) summary.push('clean=on');
   process.stderr.write(`• spawning ${spec.bin} (${summary.join(', ')})\n`);
 
+  // --clean branch: delegate process lifecycle (spawn, signal forwarding,
+  // syncback, cleanup) to @relayfile/local-mount. Skill plugin dir lives
+  // outside the mount, so claude resolves --plugin-dir normally regardless
+  // of cwd.
+  if (useClean && sessionRoot) {
+    const mountDir = sessionMountDir(sessionRoot);
+    process.stderr.write(`• clean mount → ${mountDir}\n`);
+    try {
+      const result = await launchOnMount({
+        cli: spec.bin,
+        projectDir: process.cwd(),
+        mountDir,
+        args: finalArgs,
+        ignoredPatterns: [...CLEAN_IGNORED_PATTERNS],
+        env: resolvedEnv,
+        agentName: personaId
+      });
+      return result.exitCode;
+    } catch (err) {
+      const e = err as NodeJS.ErrnoException;
+      if (e.code === 'ENOENT') {
+        process.stderr.write(
+          `Failed to spawn "${spec.bin}" inside clean mount: binary not found on PATH. Install the ${runtime.harness} CLI and retry.\n`
+        );
+      } else {
+        process.stderr.write(`Failed to launch clean mount: ${e.message}\n`);
+      }
+      return 127;
+    } finally {
+      runCleanup(install.cleanupCommand, install.cleanupCommandString);
+    }
+  }
+
   return new Promise((resolve) => {
     let settled = false;
     const finish = (code: number) => {
@@ -557,21 +689,103 @@ async function main(): Promise<void> {
     die(`Unknown subcommand "${subcommand}".`);
   }
 
-  const [selector, ...taskParts] = rest;
+  const { flags, positional } = parseAgentArgs(rest);
+  const [selector, ...taskParts] = positional;
   if (!selector) die('agent: missing persona selector.');
 
   const target = parseSelector(selector);
   const selection = buildSelection(target.spec, target.tier, target.kind);
 
   if (taskParts.length > 0) {
+    // One-shot (sendMessage) currently goes through the agent-relay workflow
+    // SDK, which doesn't yet thread `--plugin-dir` into claude. For now it
+    // keeps the legacy in-repo install regardless of --install-in-repo so
+    // skills remain visible to the model. Flipping this requires upstream
+    // SDK work on the claude agent adapter.
+    if (flags.installInRepo) {
+      process.stderr.write(
+        'note: --install-in-repo is redundant for one-shot runs (already the current behavior).\n'
+      );
+    }
+    if (flags.clean) {
+      // Parallel to --install-in-repo: the agent-relay workflow SDK doesn't
+      // thread @relayfile/local-mount integration today, so --clean on a
+      // one-shot run is a no-op. Interactive mode gets the sandbox.
+      process.stderr.write(
+        'note: --clean is ignored for one-shot runs; it currently only applies to interactive claude sessions.\n'
+      );
+    }
     await runOneShot(selection, taskParts.join(' '));
   } else {
-    const code = await runInteractive(selection);
+    const code = await runInteractive(selection, {
+      installInRepo: flags.installInRepo,
+      clean: flags.clean
+    });
     process.exit(code);
   }
 }
 
-main().catch((err) => {
-  process.stderr.write(`${(err as Error)?.stack ?? String(err)}\n`);
-  process.exit(1);
-});
+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 positional: string[] = [];
+  let seenDoubleDash = false;
+  for (const arg of args) {
+    if (seenDoubleDash) {
+      positional.push(arg);
+      continue;
+    }
+    if (arg === '--') {
+      seenDoubleDash = true;
+      continue;
+    }
+    if (arg === '--install-in-repo') {
+      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 };
+}
+
+// Only run main when invoked as the CLI entry, not when imported by tests.
+// Node ESM: import.meta.url is the module URL; argv[1] is the entry script
+// path. Compare after normalizing both to file URLs.
+const isCliEntry = (() => {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return import.meta.url === pathToFileURL(entry).href;
+  } catch {
+    return false;
+  }
+})();
+
+if (isCliEntry) {
+  main().catch((err) => {
+    process.stderr.write(`${(err as Error)?.stack ?? String(err)}\n`);
+    process.exit(1);
+  });
+}
diff --git a/packages/harness-kit/src/harness.test.ts b/packages/harness-kit/src/harness.test.ts
index 0e02b91d..c902b9d7 100644
--- a/packages/harness-kit/src/harness.test.ts
+++ b/packages/harness-kit/src/harness.test.ts
@@ -118,6 +118,60 @@ test('opencode carries system prompt and strips provider prefix', () => {
   assert.equal(result.initialPrompt, 'x');
 });
 
+test('claude branch appends --plugin-dir per entry in pluginDirs', () => {
+  const result = buildInteractiveSpec({
+    harness: 'claude',
+    model: 'claude-opus-4-6',
+    systemPrompt: 'x',
+    pluginDirs: ['/tmp/session-a/claude/plugin', '/tmp/session-b/claude/plugin']
+  });
+  const args = result.args;
+  const indices: number[] = [];
+  args.forEach((a, i) => {
+    if (a === '--plugin-dir') indices.push(i);
+  });
+  assert.equal(indices.length, 2);
+  assert.equal(args[indices[0] + 1], '/tmp/session-a/claude/plugin');
+  assert.equal(args[indices[1] + 1], '/tmp/session-b/claude/plugin');
+  assert.deepEqual(result.warnings, []);
+});
+
+test('claude branch omits --plugin-dir when pluginDirs is empty or absent', () => {
+  const withEmpty = buildInteractiveSpec({
+    harness: 'claude',
+    model: 'claude-opus-4-6',
+    systemPrompt: 'x',
+    pluginDirs: []
+  });
+  const without = buildInteractiveSpec({
+    harness: 'claude',
+    model: 'claude-opus-4-6',
+    systemPrompt: 'x'
+  });
+  assert.ok(!withEmpty.args.includes('--plugin-dir'));
+  assert.ok(!without.args.includes('--plugin-dir'));
+});
+
+test('non-claude harnesses warn and ignore pluginDirs', () => {
+  const codex = buildInteractiveSpec({
+    harness: 'codex',
+    model: 'x',
+    systemPrompt: 'x',
+    pluginDirs: ['/tmp/session/plugin']
+  });
+  assert.ok(!codex.args.includes('--plugin-dir'));
+  assert.ok(codex.warnings.some((w) => /pluginDirs is currently claude-only/.test(w)));
+
+  const opencode = buildInteractiveSpec({
+    harness: 'opencode',
+    model: 'x',
+    systemPrompt: 'x',
+    pluginDirs: ['/tmp/session/plugin']
+  });
+  assert.ok(!opencode.args.includes('--plugin-dir'));
+  assert.ok(opencode.warnings.some((w) => /pluginDirs is currently claude-only/.test(w)));
+});
+
 test('warnings are returned, not printed — library consumers route I/O themselves', () => {
   // Ensure no side effects on stderr: if the function wrote to stderr, this
   // test would leak output into the test runner. We just assert the shape.
diff --git a/packages/harness-kit/src/harness.ts b/packages/harness-kit/src/harness.ts
index 76bb7892..fdf7639a 100644
--- a/packages/harness-kit/src/harness.ts
+++ b/packages/harness-kit/src/harness.ts
@@ -31,6 +31,14 @@ export interface BuildInteractiveSpecInput {
   /** Env-resolved MCP servers (pass the output of `resolveMcpServersLenient().servers`). */
   mcpServers?: Record<string, McpServerSpec>;
   permissions?: PersonaPermissions;
+  /**
+   * Absolute paths of directories to load as Claude Code plugins for this
+   * session (`--plugin-dir <path>` per entry). Used to wire in out-of-repo
+   * skill stages produced by
+   * {@link import('@agentworkforce/workload-router').SkillMaterializationOptions.installRoot}.
+   * Claude-only: other harnesses emit a warning and ignore the field.
+   */
+  pluginDirs?: readonly string[];
 }
 
 function stripProviderPrefix(model: string): string {
@@ -59,8 +67,9 @@ function hasAnyPermission(p: PersonaPermissions | undefined): boolean {
  * harnesses yet.
  */
 export function buildInteractiveSpec(input: BuildInteractiveSpecInput): InteractiveSpec {
-  const { harness, model, systemPrompt, mcpServers, permissions } = input;
+  const { harness, model, systemPrompt, mcpServers, permissions, pluginDirs } = input;
   const warnings: string[] = [];
+  const hasPluginDirs = pluginDirs !== undefined && pluginDirs.length > 0;
 
   switch (harness) {
     case 'claude': {
@@ -74,6 +83,11 @@ export function buildInteractiveSpec(input: BuildInteractiveSpecInput): Interact
         mcpPayload,
         '--strict-mcp-config'
       ];
+      if (hasPluginDirs) {
+        for (const dir of pluginDirs!) {
+          args.push('--plugin-dir', dir);
+        }
+      }
       if (permissions?.allow && permissions.allow.length > 0) {
         args.push('--allowedTools', ...permissions.allow);
       }
@@ -96,6 +110,11 @@ export function buildInteractiveSpec(input: BuildInteractiveSpecInput): Interact
           'persona declares permissions but the codex harness is not yet wired for runtime permission injection; proceeding with codex defaults.'
         );
       }
+      if (hasPluginDirs) {
+        warnings.push(
+          'pluginDirs is currently claude-only; ignoring under the codex harness. Skills must be staged via codex conventions.'
+        );
+      }
       return {
         bin: 'codex',
         args: ['-m', stripProviderPrefix(model)],
@@ -114,6 +133,11 @@ export function buildInteractiveSpec(input: BuildInteractiveSpecInput): Interact
           'persona declares permissions but the opencode harness is not yet wired for runtime permission injection; proceeding with opencode defaults.'
         );
       }
+      if (hasPluginDirs) {
+        warnings.push(
+          'pluginDirs is currently claude-only; ignoring under the opencode harness. Skills must be staged via opencode conventions.'
+        );
+      }
       return {
         bin: 'opencode',
         args: ['--model', stripProviderPrefix(model)],
diff --git a/packages/workload-router/src/index.test.ts b/packages/workload-router/src/index.test.ts
index 2b1e6383..d08c16da 100644
--- a/packages/workload-router/src/index.test.ts
+++ b/packages/workload-router/src/index.test.ts
@@ -12,7 +12,8 @@ import {
   personaCatalog,
   resolvePersona,
   resolvePersonaByTier,
-  usePersona
+  usePersona,
+  useSelection
 } from './index.js';
 
 function writeNodeExecutable(dir: string, name: string, source: string): string {
@@ -412,6 +413,95 @@ test('usePersona cleanupCommandString is a shell no-op when the persona declares
   assert.equal(context.install.cleanupCommandString, ':');
 });
 
+test('materializeSkills with installRoot stages claude skills under the stage dir', () => {
+  const installRoot = '/tmp/agent-workforce/sessions/test-run/claude/plugin';
+  const plan = materializeSkills(
+    [
+      {
+        id: 'prpm/npm-trusted-publishing',
+        source: '@prpm/npm-trusted-publishing',
+        description: 'bare ref form'
+      }
+    ],
+    'claude',
+    { installRoot }
+  );
+
+  assert.equal(plan.sessionInstallRoot, installRoot);
+  const [install] = plan.installs;
+  assert.equal(
+    install.installedDir,
+    `${installRoot}/.claude/skills/npm-trusted-publishing`
+  );
+  assert.equal(
+    install.installedManifest,
+    `${installRoot}/.claude/skills/npm-trusted-publishing/SKILL.md`
+  );
+  // Per-install command is self-contained: runs prpm inside the stage dir.
+  assert.equal(install.installCommand[0], 'sh');
+  assert.equal(install.installCommand[1], '-c');
+  const script = install.installCommand[2];
+  assert.match(script, /^cd /);
+  assert.match(script, /agent-workforce\/sessions\/test-run\/claude\/plugin/);
+  assert.match(script, /npx -y prpm install @prpm\/npm-trusted-publishing --as claude/);
+  // Per-skill cleanupPaths is empty; cleanup lives at the plan level.
+  assert.deepEqual([...install.cleanupPaths], []);
+});
+
+test('materializeSkills rejects installRoot for non-claude harnesses', () => {
+  assert.throws(
+    () =>
+      materializeSkills(
+        [
+          {
+            id: 'prpm/x',
+            source: '@prpm/x',
+            description: 'x'
+          }
+        ],
+        'codex',
+        { installRoot: '/tmp/agent-workforce/sessions/abc/claude/plugin' }
+      ),
+    /installRoot is only supported for the claude harness/
+  );
+});
+
+test('useSelection with installRoot emits scaffold + chained prpm in install.commandString', () => {
+  const installRoot = '/tmp/agent-workforce/sessions/scaffold-test/claude/plugin';
+  const selection = resolvePersonaByTier('npm-provenance', 'best-value');
+  // Force harness=claude so the installRoot path is exercised regardless of
+  // the persona's default tier harness.
+  const context = useSelection(selection, { harness: 'claude', installRoot });
+  assert.equal(context.install.plan.sessionInstallRoot, installRoot);
+  const cmd = context.install.commandString;
+  // Scaffold: the three mkdir/ln/printf steps go first.
+  assert.match(cmd, /^mkdir -p /);
+  assert.match(cmd, /\.claude-plugin/);
+  assert.match(cmd, /ln -sfn \.claude\/skills /);
+  assert.match(cmd, /printf '%s' /);
+  // Then a single cd into the stage dir, then the prpm call.
+  assert.match(cmd, / && cd '?\/tmp\/agent-workforce\/sessions\/scaffold-test\/claude\/plugin'? && /);
+  assert.match(cmd, /npx -y prpm install @prpm\/npm-trusted-publishing --as claude/);
+});
+
+test('useSelection with installRoot collapses cleanup to a single rm -rf of the stage dir', () => {
+  const installRoot = '/tmp/agent-workforce/sessions/cleanup-test/claude/plugin';
+  const selection = resolvePersonaByTier('npm-provenance', 'best-value');
+  const context = useSelection(selection, { harness: 'claude', installRoot });
+  // shellEscape leaves paths made of [A-Za-z0-9_./:@%+=,-] unquoted.
+  assert.equal(
+    context.install.cleanupCommandString,
+    `rm -rf /tmp/agent-workforce/sessions/cleanup-test/claude/plugin`
+  );
+});
+
+test('materializeSkills with installRoot + no skills still reports the sessionInstallRoot', () => {
+  const installRoot = '/tmp/agent-workforce/sessions/empty/claude/plugin';
+  const plan = materializeSkills([], 'claude', { installRoot });
+  assert.equal(plan.sessionInstallRoot, installRoot);
+  assert.equal(plan.installs.length, 0);
+});
+
 test('resolves capability-discovery persona carrying both skill.sh and prpm skills', () => {
   const selection = resolvePersona('capability-discovery');
   assert.equal(selection.personaId, 'capability-discoverer');
diff --git a/packages/workload-router/src/index.ts b/packages/workload-router/src/index.ts
index 1c6397f1..a2607d4b 100644
--- a/packages/workload-router/src/index.ts
+++ b/packages/workload-router/src/index.ts
@@ -200,6 +200,24 @@ export const HARNESS_SKILL_TARGETS: Record<Harness, HarnessSkillTarget> = {
   opencode: { asFlag: 'opencode', dir: '.skills' }
 };
 
+/**
+ * Options for {@link materializeSkills} / {@link materializeSkillsFor}.
+ *
+ * `installRoot` stages skills under an out-of-repo directory (typically
+ * `~/.agent-workforce/sessions/<id>/claude/plugin`) that doubles as a Claude
+ * Code plugin root. The SDK generates the scaffold (`.claude-plugin/plugin.json`
+ * and a `skills` symlink pointing at `.claude/skills/`), prpm installs into
+ * `<installRoot>/.claude/skills/<name>/`, and post-run cleanup removes the
+ * entire `installRoot` in one `rm -rf` — no files ever touch the repo.
+ *
+ * Only honored for `harness === 'claude'`. Passing `installRoot` with another
+ * harness throws. The absolute path is the caller's responsibility; the SDK
+ * does not create parent directories on its own.
+ */
+export interface SkillMaterializationOptions {
+  installRoot?: string;
+}
+
 export interface SkillInstall {
   skillId: string;
   /** Original `source` string from the persona JSON. */
@@ -226,6 +244,13 @@ export interface SkillInstall {
 export interface SkillMaterializationPlan {
   harness: Harness;
   installs: SkillInstall[];
+  /**
+   * Absolute path to the out-of-repo stage directory, when the plan was
+   * produced with {@link SkillMaterializationOptions.installRoot}. When set,
+   * the install artifacts emit plugin scaffolding at this root and cleanup
+   * removes the whole directory instead of individual skill paths.
+   */
+  sessionInstallRoot?: string;
 }
 
 export interface PersonaInstallContext {
@@ -627,26 +652,56 @@ function providerFor(kind: SkillSourceKind): SkillProvider {
  */
 export function materializeSkills(
   skills: readonly PersonaSkill[],
-  harness: Harness
+  harness: Harness,
+  options: SkillMaterializationOptions = {}
 ): SkillMaterializationPlan {
   const target = HARNESS_SKILL_TARGETS[harness];
   if (!target) {
     throw new Error(`No skill install target configured for harness: ${harness}`);
   }
+  const { installRoot } = options;
+  if (installRoot !== undefined && harness !== 'claude') {
+    throw new Error(
+      `installRoot is only supported for the claude harness (got: ${harness}). ` +
+        `codex and opencode still install into the harness's conventional repo-relative directory.`
+    );
+  }
 
   const installs = skills.map((skill): SkillInstall => {
     const resolved = resolveSkillSource(skill.source);
     const provider = providerFor(resolved.kind);
-    const installCommand = provider.buildInstallCommand(resolved, harness);
-    const cleanupPaths = provider.cleanupPaths(resolved, harness);
+    const baseCommand = provider.buildInstallCommand(resolved, harness);
+    // In session-install-root mode, the install runs `cd <installRoot> && <prpm>`
+    // so that prpm's harness-relative dirs (`.claude/skills/<name>`) land
+    // inside the stage dir instead of the user's repo. The per-install command
+    // stays self-contained so callers who run a single install.installCommand
+    // directly still get the correct placement.
+    const installCommand =
+      installRoot !== undefined
+        ? (Object.freeze([
+            'sh',
+            '-c',
+            `cd ${shellEscape(installRoot)} && ${commandToShellString(baseCommand)}`
+          ]) as readonly string[])
+        : baseCommand;
     // For prompt-injection fallback we still want a single canonical manifest
     // path. prpm installs into the harness target dir; skill.sh installs into
     // its universal `.agents/skills` dir regardless of harness, so key off
     // whichever cleanup path ends in the installed name.
-    const installedDir =
+    const repoRelativeDir =
       resolved.kind === 'skill.sh'
         ? `.agents/skills/${resolved.installedName}`
         : `${target.dir}/${resolved.installedName}`;
+    const installedDir =
+      installRoot !== undefined ? `${installRoot}/${repoRelativeDir}` : repoRelativeDir;
+    // When the plan stages into `installRoot`, cleanup targets the whole
+    // session dir (handled at plan level in buildCleanupArtifacts). Leave
+    // per-skill cleanupPaths empty so Mode B callers running individual
+    // install.cleanupPaths don't accidentally remove unrelated things.
+    const cleanupPaths =
+      installRoot !== undefined
+        ? (Object.freeze([]) as readonly string[])
+        : provider.cleanupPaths(resolved, harness);
     return {
       skillId: skill.id,
       source: skill.source,
@@ -660,15 +715,22 @@ export function materializeSkills(
     };
   });
 
-  return { harness, installs };
+  return {
+    harness,
+    installs,
+    ...(installRoot !== undefined ? { sessionInstallRoot: installRoot } : {})
+  };
 }
 
 /**
  * Convenience wrapper: derive the install plan directly from a resolved
  * persona selection, using its tier's harness automatically.
  */
-export function materializeSkillsFor(selection: PersonaSelection): SkillMaterializationPlan {
-  return materializeSkills(selection.skills, selection.runtime.harness);
+export function materializeSkillsFor(
+  selection: PersonaSelection,
+  options: SkillMaterializationOptions = {}
+): SkillMaterializationPlan {
+  return materializeSkills(selection.skills, selection.runtime.harness, options);
 }
 
 function shellEscape(value: string): string {
@@ -682,15 +744,70 @@ function commandToShellString(command: readonly string[]): string {
   return command.map(shellEscape).join(' ');
 }
 
+/**
+ * Minimal Claude Code plugin manifest written to `<root>/.claude-plugin/plugin.json`
+ * in session-install-root mode. Claude's plugin loader treats any directory
+ * that contains this file (alongside a `skills/` tree) as a plugin; we pass
+ * the root to `claude --plugin-dir <root>` so the session sees exactly the
+ * skills we staged — and nothing the repo happens to carry.
+ */
+const SESSION_PLUGIN_MANIFEST = JSON.stringify({
+  name: 'agent-workforce-session',
+  version: '0.0.0',
+  description: 'Ephemeral skills staged by agent-workforce for this session.'
+});
+
+function buildSessionScaffoldCommand(root: string): string {
+  const q = shellEscape(root);
+  // mkdir -p creates both the plugin metadata dir and the prpm target.
+  // `ln -sfn .claude/skills skills` makes Claude's expected plugin layout
+  // (`<root>/skills/<name>/SKILL.md`) resolve to prpm's actual output
+  // (`<root>/.claude/skills/<name>/SKILL.md`) without moving any files.
+  // The -n guards against following into an existing `skills/` dir (e.g.
+  // when the session dir is reused), and -f replaces a prior symlink so
+  // the scaffold is idempotent.
+  return [
+    `mkdir -p ${q}/.claude-plugin ${q}/.claude/skills`,
+    `ln -sfn .claude/skills ${q}/skills`,
+    `printf '%s' ${shellEscape(SESSION_PLUGIN_MANIFEST)} > ${q}/.claude-plugin/plugin.json`
+  ].join(' && ');
+}
+
 function buildInstallArtifacts(plan: SkillMaterializationPlan): {
   installCommand: readonly string[];
   installCommandString: string;
 } {
-  const installCommandString =
-    plan.installs.length === 0
-      ? ':'
-      : plan.installs.map((install) => commandToShellString(install.installCommand)).join(' && ');
+  if (plan.installs.length === 0) {
+    return {
+      installCommand: Object.freeze(['sh', '-c', ':']) as readonly string[],
+      installCommandString: ':'
+    };
+  }
 
+  if (plan.sessionInstallRoot !== undefined) {
+    // In session mode, chain the raw provider commands after a single
+    // `cd <root>` so we emit one shell invocation instead of repeating the
+    // cd per skill. Each install.installCommand is already self-contained
+    // (`sh -c 'cd <root> && …'`) for callers who want to run one at a time,
+    // but here we flatten to the underlying prpm argv for a cleaner chain.
+    const root = plan.sessionInstallRoot;
+    const perSkill = plan.installs
+      .map((install) => {
+        const resolved = resolveSkillSource(install.source);
+        const provider = providerFor(resolved.kind);
+        return commandToShellString(provider.buildInstallCommand(resolved, plan.harness));
+      })
+      .join(' && ');
+    const installCommandString = `${buildSessionScaffoldCommand(root)} && cd ${shellEscape(root)} && ${perSkill}`;
+    return {
+      installCommand: Object.freeze(['sh', '-c', installCommandString]) as readonly string[],
+      installCommandString
+    };
+  }
+
+  const installCommandString = plan.installs
+    .map((install) => commandToShellString(install.installCommand))
+    .join(' && ');
   return {
     installCommand: Object.freeze(['sh', '-c', installCommandString]) as readonly string[],
     installCommandString
@@ -710,6 +827,17 @@ function buildCleanupArtifacts(plan: SkillMaterializationPlan): {
   cleanupCommand: readonly string[];
   cleanupCommandString: string;
 } {
+  // Session mode: cleanup is the whole stage dir. Even if no skills were
+  // actually installed, we still drop the directory the scaffold created so
+  // nothing remains on disk after the run.
+  if (plan.sessionInstallRoot !== undefined) {
+    const cleanupCommandString =
+      plan.installs.length === 0 ? ':' : `rm -rf ${shellEscape(plan.sessionInstallRoot)}`;
+    return {
+      cleanupCommand: Object.freeze(['sh', '-c', cleanupCommandString]) as readonly string[],
+      cleanupCommandString
+    };
+  }
   const allPaths = plan.installs.flatMap((install) => [...install.cleanupPaths]);
   const cleanupCommandString =
     allPaths.length === 0 ? ':' : `rm -rf ${allPaths.map(shellEscape).join(' ')}`;
@@ -1474,13 +1602,21 @@ export function usePersona(
     harness?: Harness;
     tier?: PersonaTier;
     profile?: RoutingProfile | RoutingProfileId;
+    /**
+     * Stage claude skills under this absolute directory instead of the
+     * repo's `.claude/skills/`. See {@link SkillMaterializationOptions.installRoot}.
+     */
+    installRoot?: string;
   } = {}
 ): PersonaContext {
   const baseSelection = options.tier
     ? resolvePersonaByTier(intent, options.tier)
     : resolvePersona(intent, options.profile ?? 'default');
 
-  return useSelection(baseSelection, { harness: options.harness });
+  return useSelection(baseSelection, {
+    harness: options.harness,
+    installRoot: options.installRoot
+  });
 }
 
 /**
@@ -1491,7 +1627,7 @@ export function usePersona(
  */
 export function useSelection(
   baseSelection: PersonaSelection,
-  options: { harness?: Harness } = {}
+  options: { harness?: Harness; installRoot?: string } = {}
 ): PersonaContext {
   const effectiveHarness = options.harness ?? baseSelection.runtime.harness;
   const selection =
@@ -1505,10 +1641,12 @@ export function useSelection(
           }
         };
 
+  const materializationOptions: SkillMaterializationOptions =
+    options.installRoot !== undefined ? { installRoot: options.installRoot } : {};
   const installPlan =
     effectiveHarness === baseSelection.runtime.harness
-      ? materializeSkillsFor(selection)
-      : materializeSkills(selection.skills, effectiveHarness);
+      ? materializeSkillsFor(selection, materializationOptions)
+      : materializeSkills(selection.skills, effectiveHarness, materializationOptions);
 
   const { installCommand, installCommandString } = buildInstallArtifacts(installPlan);
   const { cleanupCommand, cleanupCommandString } = buildCleanupArtifacts(installPlan);

From f636167be1844e8e70812ab3f31f7ce86b67dfdd Mon Sep 17 00:00:00 2001
From: Will Washburn <will.washburn@gmail.com>
Date: Sun, 19 Apr 2026 19:22:45 -0400
Subject: [PATCH 2/3] Address PR #18 review comments

- workload-router: session-mode install always emits the scaffold so
  `claude --plugin-dir <root>` resolves even for skill-less personas
  (e.g. posthog). Session cleanup unconditionally drops the stage dir.
- cli: after each interactive session, `rm -rf` the whole session root
  so empty parent dirs don't accumulate under
  `~/.agent-workforce/sessions/`.
- cli: `--clean` launchOnMount now merges `process.env` with persona env
  so PATH/HOME/etc. aren't stripped from the child.
- cli: `isCliEntry` resolves argv[1] to absolute before pathToFileURL,
  so `node ./dist/cli.js` still detects the CLI entry.
- Regenerate pnpm-lock.yaml for @relayfile/local-mount (unblocks CI's
  `pnpm install --frozen-lockfile`).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/cli/src/cli.ts                    | 26 ++++++++++--
 packages/workload-router/src/index.test.ts | 22 ++++++++++
 packages/workload-router/src/index.ts      | 47 +++++++++++++---------
 pnpm-lock.yaml                             | 26 ++++++++++++
 4 files changed, 99 insertions(+), 22 deletions(-)

diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 6bab0144..a6c8dd59 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -2,7 +2,7 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { constants, homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import {
@@ -219,6 +219,18 @@ function runCleanup(command: readonly string[], commandString: string): void {
   spawnSync(bin, args, { stdio: 'inherit', shell: false });
 }
 
+/**
+ * Remove the whole per-session directory after the run, including the
+ * enclosing `<homedir>/.agent-workforce/sessions/<id>/` that the CLI
+ * created. The workload-router cleanup only covers the install subtree
+ * (`<root>/claude/plugin`), so without this step empty parent dirs
+ * would accumulate under `~/.agent-workforce/sessions/`.
+ */
+function removeSessionRoot(sessionRoot: string | undefined): void {
+  if (!sessionRoot) return;
+  spawnSync('rm', ['-rf', sessionRoot], { stdio: 'ignore', shell: false });
+}
+
 /**
  * Compute the absolute root directory for an interactive claude session.
  * Layout (under `root`):
@@ -364,7 +376,10 @@ async function runInteractive(
         mountDir,
         args: finalArgs,
         ignoredPatterns: [...CLEAN_IGNORED_PATTERNS],
-        env: resolvedEnv,
+        // launchOnMount passes `env` straight to the child spawn, so without
+        // merging process.env we'd strip PATH/HOME/etc. Match the non-clean
+        // branch: persona env overlays the inherited environment.
+        env: resolvedEnv ? { ...process.env, ...resolvedEnv } : process.env,
         agentName: personaId
       });
       return result.exitCode;
@@ -380,6 +395,7 @@ async function runInteractive(
       return 127;
     } finally {
       runCleanup(install.cleanupCommand, install.cleanupCommandString);
+      removeSessionRoot(sessionRoot);
     }
   }
 
@@ -389,6 +405,7 @@ async function runInteractive(
       if (settled) return;
       settled = true;
       runCleanup(install.cleanupCommand, install.cleanupCommandString);
+      removeSessionRoot(sessionRoot);
       resolve(code);
     };
 
@@ -772,12 +789,13 @@ export function parseAgentArgs(args: readonly string[]): {
 
 // Only run main when invoked as the CLI entry, not when imported by tests.
 // Node ESM: import.meta.url is the module URL; argv[1] is the entry script
-// path. Compare after normalizing both to file URLs.
+// path, which may be relative (e.g. `node ./dist/cli.js`) and pathToFileURL
+// throws on relative paths. Resolve to absolute first.
 const isCliEntry = (() => {
   const entry = process.argv[1];
   if (!entry) return false;
   try {
-    return import.meta.url === pathToFileURL(entry).href;
+    return import.meta.url === pathToFileURL(resolvePath(entry)).href;
   } catch {
     return false;
   }
diff --git a/packages/workload-router/src/index.test.ts b/packages/workload-router/src/index.test.ts
index d08c16da..f5c26890 100644
--- a/packages/workload-router/src/index.test.ts
+++ b/packages/workload-router/src/index.test.ts
@@ -502,6 +502,28 @@ test('materializeSkills with installRoot + no skills still reports the sessionIn
   assert.equal(plan.installs.length, 0);
 });
 
+test('useSelection with installRoot + no skills emits scaffold so --plugin-dir target exists', () => {
+  // Skill-less claude personas (e.g. posthog) still need the stage dir to
+  // exist so `claude --plugin-dir <installRoot>` finds a valid plugin.
+  const installRoot = '/tmp/agent-workforce/sessions/empty-scaffold/claude/plugin';
+  const selection = resolvePersonaByTier('posthog', 'best');
+  const context = useSelection(selection, { harness: 'claude', installRoot });
+  assert.equal(context.install.plan.sessionInstallRoot, installRoot);
+  assert.equal(context.install.plan.installs.length, 0);
+  const cmd = context.install.commandString;
+  // Must NOT be the `:` no-op; must run the scaffold.
+  assert.notEqual(cmd, ':');
+  assert.match(cmd, /^mkdir -p /);
+  assert.match(cmd, /\.claude-plugin/);
+  assert.match(cmd, /ln -sfn \.claude\/skills /);
+  assert.match(cmd, /printf '%s' /);
+  // Cleanup always drops the stage dir in session mode, even with zero skills.
+  assert.equal(
+    context.install.cleanupCommandString,
+    `rm -rf ${installRoot}`
+  );
+});
+
 test('resolves capability-discovery persona carrying both skill.sh and prpm skills', () => {
   const selection = resolvePersona('capability-discovery');
   assert.equal(selection.personaId, 'capability-discoverer');
diff --git a/packages/workload-router/src/index.ts b/packages/workload-router/src/index.ts
index a2607d4b..421ed07f 100644
--- a/packages/workload-router/src/index.ts
+++ b/packages/workload-router/src/index.ts
@@ -777,20 +777,24 @@ function buildInstallArtifacts(plan: SkillMaterializationPlan): {
   installCommand: readonly string[];
   installCommandString: string;
 } {
-  if (plan.installs.length === 0) {
-    return {
-      installCommand: Object.freeze(['sh', '-c', ':']) as readonly string[],
-      installCommandString: ':'
-    };
-  }
-
   if (plan.sessionInstallRoot !== undefined) {
-    // In session mode, chain the raw provider commands after a single
-    // `cd <root>` so we emit one shell invocation instead of repeating the
-    // cd per skill. Each install.installCommand is already self-contained
-    // (`sh -c 'cd <root> && …'`) for callers who want to run one at a time,
-    // but here we flatten to the underlying prpm argv for a cleaner chain.
+    // Session mode always stages a plugin dir so the caller can pass
+    // `--plugin-dir <root>` to claude unconditionally. Even for personas
+    // with zero skills, we emit the scaffold (mkdir + manifest + symlink)
+    // so the `--plugin-dir` target exists.
     const root = plan.sessionInstallRoot;
+    const scaffold = buildSessionScaffoldCommand(root);
+    if (plan.installs.length === 0) {
+      return {
+        installCommand: Object.freeze(['sh', '-c', scaffold]) as readonly string[],
+        installCommandString: scaffold
+      };
+    }
+    // Chain the raw provider commands after a single `cd <root>` so we emit
+    // one shell invocation instead of repeating the cd per skill. Each
+    // install.installCommand is already self-contained (`sh -c 'cd <root> &&
+    // …'`) for callers who want to run one at a time, but here we flatten
+    // to the underlying prpm argv for a cleaner chain.
     const perSkill = plan.installs
       .map((install) => {
         const resolved = resolveSkillSource(install.source);
@@ -798,13 +802,20 @@ function buildInstallArtifacts(plan: SkillMaterializationPlan): {
         return commandToShellString(provider.buildInstallCommand(resolved, plan.harness));
       })
       .join(' && ');
-    const installCommandString = `${buildSessionScaffoldCommand(root)} && cd ${shellEscape(root)} && ${perSkill}`;
+    const installCommandString = `${scaffold} && cd ${shellEscape(root)} && ${perSkill}`;
     return {
       installCommand: Object.freeze(['sh', '-c', installCommandString]) as readonly string[],
       installCommandString
     };
   }
 
+  if (plan.installs.length === 0) {
+    return {
+      installCommand: Object.freeze(['sh', '-c', ':']) as readonly string[],
+      installCommandString: ':'
+    };
+  }
+
   const installCommandString = plan.installs
     .map((install) => commandToShellString(install.installCommand))
     .join(' && ');
@@ -827,12 +838,12 @@ function buildCleanupArtifacts(plan: SkillMaterializationPlan): {
   cleanupCommand: readonly string[];
   cleanupCommandString: string;
 } {
-  // Session mode: cleanup is the whole stage dir. Even if no skills were
-  // actually installed, we still drop the directory the scaffold created so
-  // nothing remains on disk after the run.
+  // Session mode: cleanup is the whole stage dir. The scaffold always runs
+  // (even for zero-skill personas), so cleanup unconditionally drops the
+  // stage dir. The CLI is responsible for removing the enclosing session
+  // root; this command covers the install subtree.
   if (plan.sessionInstallRoot !== undefined) {
-    const cleanupCommandString =
-      plan.installs.length === 0 ? ':' : `rm -rf ${shellEscape(plan.sessionInstallRoot)}`;
+    const cleanupCommandString = `rm -rf ${shellEscape(plan.sessionInstallRoot)}`;
     return {
       cleanupCommand: Object.freeze(['sh', '-c', cleanupCommandString]) as readonly string[],
       cleanupCommandString
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 18220954..9b0c9ad2 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -29,6 +29,9 @@ importers:
       '@agentworkforce/workload-router':
         specifier: workspace:*
         version: link:../workload-router
+      '@relayfile/local-mount':
+        specifier: ^0.2.0
+        version: 0.2.0
 
   packages/harness-kit:
     dependencies:
@@ -91,6 +94,10 @@ packages:
   '@relaycast/types@1.1.0':
     resolution: {integrity: sha512-d0zByxvWK2PeZRnrhzbmDkE8Yar84/XH1H+89qGJj3lA82kTf/7Z76a2cqOIoxFXLgIjK959w9hTctXLem+lhA==}
 
+  '@relayfile/local-mount@0.2.0':
+    resolution: {integrity: sha512-OF83jJdvgDtCPbJ6/U8n7lHuX2tcGcWvUGKblH0M+vnZv9OEWsDnt7WXnJRM8kjSsBWPjfzuZdxsJboFYg1TeQ==}
+    engines: {node: '>=18'}
+
   '@relayfile/sdk@0.1.6':
     resolution: {integrity: sha512-XxYcTqBAgL9vZuejfmPXqnpRC7MvMYb0HZFjrG/r87TDA1HU7lstA1i4VEq6RhdHUS7Rt0nloM4TL/l/uaA4lg==}
     engines: {node: '>=18'}
@@ -126,6 +133,10 @@ packages:
     resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
     engines: {node: '>=10'}
 
+  chokidar@4.0.3:
+    resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
+    engines: {node: '>= 14.16.0'}
+
   chownr@3.0.0:
     resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
     engines: {node: '>=18'}
@@ -202,6 +213,10 @@ packages:
   picocolors@1.1.1:
     resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
 
+  readdirp@4.1.2:
+    resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==}
+    engines: {node: '>= 14.18.0'}
+
   restore-cursor@5.1.0:
     resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
     engines: {node: '>=18'}
@@ -339,6 +354,11 @@ snapshots:
     dependencies:
       zod: 4.3.6
 
+  '@relayfile/local-mount@0.2.0':
+    dependencies:
+      chokidar: 4.0.3
+      ignore: 7.0.5
+
   '@relayfile/sdk@0.1.6': {}
 
   '@sinclair/typebox@0.34.49': {}
@@ -370,6 +390,10 @@ snapshots:
       ansi-styles: 4.3.0
       supports-color: 7.2.0
 
+  chokidar@4.0.3:
+    dependencies:
+      readdirp: 4.1.2
+
   chownr@3.0.0: {}
 
   cli-cursor@5.0.0:
@@ -435,6 +459,8 @@ snapshots:
 
   picocolors@1.1.1: {}
 
+  readdirp@4.1.2: {}
+
   restore-cursor@5.1.0:
     dependencies:
       onetime: 7.0.0

From 8950dea0989c55dedd950b818945bbf646276821 Mon Sep 17 00:00:00 2001
From: Will Washburn <will.washburn@gmail.com>
Date: Mon, 20 Apr 2026 05:40:18 -0400
Subject: [PATCH 3/3] Address PR #18 follow-up review comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- cli: the scaffold install step was gated on
  `install.plan.installs.length > 0`, which skipped running the scaffold
  for skill-less personas — leaving `--plugin-dir` pointing at a
  directory that never existed. Gate on `commandString !== ':'` so the
  scaffold always runs in session mode, with a "Staging session plugin
  dir" label when there are no actual installs.
- workload-router: correct the `installRoot` docstring — the generated
  install command `mkdir -p`s the root and its parents, so the caller
  only needs to supply an absolute path.
- cli/README: clarify that stage-dir cleanup (workload-router) and
  session-root cleanup (CLI `removeSessionRoot`) are separate scopes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/cli/README.md                | 11 +++++++----
 packages/cli/src/cli.ts               | 12 ++++++++++--
 packages/workload-router/src/index.ts |  5 +++--
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/packages/cli/README.md b/packages/cli/README.md
index 6fb94efc..534b5bbb 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -462,10 +462,13 @@ the working tree, and the session only sees the skills the persona declares
 - **prpm install** — still runs `npx -y prpm install <ref> --as claude`,
   but inside `cd <stage-dir>` so the harness-conventional `.claude/skills/`
   lands in the stage dir, not the repo.
-- **Cleanup** — on exit, a single `rm -rf <stage-dir>` removes the whole
-  session directory. The provider lockfile (`prpm.lock`) is inside the stage
-  dir and goes with it — no repeat-run resolution cache today. Restart cost
-  is one prpm install per session.
+- **Cleanup** — on exit, two cleanup scopes run. The workload-router removes
+  `<stage-dir>` (e.g. `.../sessions/<id>/claude/plugin/`) via its generated
+  `rm -rf` command. The CLI additionally removes the enclosing session root
+  (`.../sessions/<id>/`) so the mount dir and any empty parents don't
+  accumulate under `~/.agent-workforce/sessions/`. The provider lockfile
+  (`prpm.lock`) is inside the stage dir and goes with it — no repeat-run
+  resolution cache today. Restart cost is one prpm install per session.
 
 **Opt-out — `--install-in-repo`:**
 
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index a6c8dd59..a6a6029c 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -321,10 +321,18 @@ async function runInteractive(
   const resolvedEnv = envResolution.value;
   const resolvedMcp = mcpResolution.servers;
 
-  if (install.plan.installs.length > 0) {
+  // In session mode the install command is never `:` — it at minimum runs
+  // the plugin scaffold (mkdir + manifest + symlink) so `--plugin-dir` has a
+  // valid target even for skill-less personas like posthog. Gate on the
+  // command string rather than `installs.length` so we don't skip that.
+  if (install.commandString !== ':') {
     const skillIds = install.plan.installs.map((i) => i.skillId).join(', ');
     const targetLabel = installRoot ? ` → ${installRoot}` : '';
-    runInstall(install.command, `Installing skills: ${skillIds}${targetLabel}`);
+    const label =
+      install.plan.installs.length === 0
+        ? `Staging session plugin dir${targetLabel}`
+        : `Installing skills: ${skillIds}${targetLabel}`;
+    runInstall(install.command, label);
   }
 
   const spec = buildInteractiveSpec({
diff --git a/packages/workload-router/src/index.ts b/packages/workload-router/src/index.ts
index 421ed07f..98eb9638 100644
--- a/packages/workload-router/src/index.ts
+++ b/packages/workload-router/src/index.ts
@@ -211,8 +211,9 @@ export const HARNESS_SKILL_TARGETS: Record<Harness, HarnessSkillTarget> = {
  * entire `installRoot` in one `rm -rf` — no files ever touch the repo.
  *
  * Only honored for `harness === 'claude'`. Passing `installRoot` with another
- * harness throws. The absolute path is the caller's responsibility; the SDK
- * does not create parent directories on its own.
+ * harness throws. The caller must supply an absolute path; when the generated
+ * install command runs, it `mkdir -p`s `installRoot` and any missing parents
+ * needed for the scaffold (`.claude-plugin/`, `.claude/skills/`).
  */
 export interface SkillMaterializationOptions {
   installRoot?: string;