@agentworkforce/cli 0.2.1 → 0.4.0

package/dist/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { constants, homedir } from 'node:os';
-import { join, resolve as resolvePath } from 'node:path';
+import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { HARNESS_VALUES, PERSONA_TAGS, PERSONA_TIERS, personaCatalog, routingProfiles, useSelection } from '@agentworkforce/workload-router';
 import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, resolveMcpServersLenient, resolveStringMapLenient } from '@agentworkforce/harness-kit';
 import { launchOnMount } from '@relayfile/local-mount';
+import ora from 'ora';
 import { loadLocalPersonas } from './local-personas.js';
 const USAGE = `Usage: agent-workforce <command> [args...]
 
@@ -19,19 +21,28 @@ Commands:
 
                       Flags:
                         --install-in-repo   Install skills into the repo's
-                                            .claude/skills/ (legacy). By default,
+                                            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
-                                            so the repo is never touched.
+                                            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
-                                            hides the repo's CLAUDE.md,
+                                            also 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.
+                                            preserved. No-op for opencode
+                                            (mount is already on by default);
+                                            codex still warns and proceeds
+                                            without a mount. 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
@@ -46,6 +57,14 @@ Commands:
                         --filter-tag <tag>            only show personas carrying this tag
                                                       (${PERSONA_TAGS.join(' | ')})
                         --no-display-description      hide the DESCRIPTION column
+  show <persona>[@<tier>]
+                      Print the fully-resolved spec for a single persona,
+                      including which cascade layer defined it (pwd, home,
+                      library). By default shows only the recommended tier for
+                      the persona's intent; pass @<tier> to pick one, or --all
+                      to see every tier. Flags:
+                        --all         include every tier (overrides default)
+                        --json        emit the resolved PersonaSpec as JSON
   harness check       Probe which harnesses (claude, codex, opencode) are
                       installed and runnable on this machine.
 
@@ -60,6 +79,7 @@ Examples:
   agent-workforce agent my-posthog@best
   agent-workforce agent review@best-value "look at the diff on this branch"
   agent-workforce list
+  agent-workforce show posthog
   agent-workforce harness check
 `;
 function die(msg, withUsage = true) {
@@ -108,11 +128,30 @@ function parseSelector(sel) {
     const kind = local.byId.has(key) ? 'local' : 'repo';
     return { kind, spec: result, tier };
 }
+/**
+ * Resolve the `<harness>` placeholder used in persona systemPrompts.
+ * Personas embed `<harness>` inside example install commands (e.g.
+ * `npx prpm install <ref> --as <harness>`) so the docstring stays
+ * harness-agnostic in source. The active harness is known at selection
+ * time, so swap it in here to give the model a concrete command.
+ *
+ * Exported for test coverage. Only `<harness>` is resolved today; other
+ * angle-bracketed tokens in the prompt (e.g. `<ref>`, `<repo-url>`,
+ * `<query>`) are deliberately left as LLM-facing placeholders.
+ */
+export function resolveSystemPromptPlaceholders(prompt, harness) {
+    return prompt.replaceAll('<harness>', harness);
+}
 function buildSelection(spec, tier, kind) {
+    const rawRuntime = spec.tiers[tier];
+    const runtime = {
+        ...rawRuntime,
+        systemPrompt: resolveSystemPromptPlaceholders(rawRuntime.systemPrompt, rawRuntime.harness)
+    };
     return {
         personaId: spec.id,
         tier,
-        runtime: spec.tiers[tier],
+        runtime,
         skills: spec.skills,
         rationale: kind === 'local' ? `local-override: ${spec.id}` : `cli-tier-override: ${tier}`,
         ...(spec.env ? { env: spec.env } : {}),
@@ -159,18 +198,61 @@ function signalExitCode(signal) {
     const num = constants.signals[signal];
     return 128 + (num ?? 1);
 }
-function runInstall(command, label) {
+/**
+ * Derive a meaningful exit code from a `spawnSync` result. `spawnSync`
+ * sets `status` to null and `signal` to the signal name (e.g. `SIGINT`)
+ * when the child was killed before it could set its own exit code, so
+ * a naive `res.status ?? 1` collapses Ctrl-C / SIGTERM onto generic
+ * failure instead of the conventional 128+N.
+ */
+function subprocessExitCode(res) {
+    if (res.status !== null)
+        return res.status;
+    if (res.signal)
+        return signalExitCode(res.signal);
+    return 1;
+}
+function runInstall(command, label, cwd) {
     const [bin, ...args] = command;
     if (!bin)
         return;
     process.stderr.write(`• ${label}\n`);
-    const res = spawnSync(bin, args, { stdio: 'inherit', shell: false });
-    if (res.status !== 0) {
-        const code = res.status ?? 1;
+    const res = spawnSync(bin, args, { stdio: 'inherit', shell: false, ...(cwd ? { cwd } : {}) });
+    const code = subprocessExitCode(res);
+    if (code !== 0) {
         process.stderr.write(`${label} failed (exit ${code}). Aborting.\n`);
         process.exit(code);
     }
 }
+/**
+ * Thrown by `runInstallOrThrow` when the install subprocess exits non-zero.
+ * Carries the underlying exit code so the mount-branch catch can surface it
+ * to the user instead of collapsing every failure onto 127.
+ */
+class InstallCommandError extends Error {
+    exitCode;
+    constructor(label, exitCode) {
+        super(`${label} failed (exit ${exitCode})`);
+        this.name = 'InstallCommandError';
+        this.exitCode = exitCode;
+    }
+}
+/**
+ * Install variant that throws instead of calling `process.exit` on failure.
+ * Used inside `launchOnMount`'s `onBeforeLaunch`, so mount teardown runs
+ * before the error surfaces.
+ */
+function runInstallOrThrow(command, label, cwd) {
+    const [bin, ...args] = command;
+    if (!bin)
+        return;
+    process.stderr.write(`• ${label}\n`);
+    const res = spawnSync(bin, args, { stdio: 'inherit', shell: false, cwd });
+    const code = subprocessExitCode(res);
+    if (code !== 0) {
+        throw new InstallCommandError(label, code);
+    }
+}
 function runCleanup(command, commandString) {
     if (commandString === ':')
         return;
@@ -185,11 +267,19 @@ function runCleanup(command, commandString) {
  * 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/`.
+ *
+ * Uses `fs.rmSync` rather than `spawnSync('rm', …)` so the teardown works
+ * on Windows where `rm` isn't on PATH.
  */
 function removeSessionRoot(sessionRoot) {
     if (!sessionRoot)
         return;
-    spawnSync('rm', ['-rf', sessionRoot], { stdio: 'ignore', shell: false });
+    try {
+        rmSync(sessionRoot, { recursive: true, force: true });
+    }
+    catch {
+        /* best-effort — if teardown fails the dir is harmless under ~/.agent-workforce/sessions */
+    }
 }
 /**
  * Compute the absolute root directory for an interactive claude session.
@@ -213,6 +303,49 @@ function sessionInstallRoot(sessionRoot) {
 function sessionMountDir(sessionRoot) {
     return join(sessionRoot, 'mount');
 }
+/**
+ * Remove every `--agent <id>` pair from a harness argv. Used on the non-mount
+ * opencode path where we cannot safely materialize the persona's
+ * opencode.json (it would land in the user's real repo), so we fall back to
+ * launching opencode without a persona-specific agent selection.
+ *
+ * Strips all occurrences rather than just the first — the current producer
+ * (harness-kit's opencode branch) emits exactly one pair, so both behaviors
+ * are equivalent today, but "remove all" is idempotent and safer if a future
+ * caller ever appends a second `--agent` for any reason. A trailing `--agent`
+ * with no following value is preserved so the malformed argv surfaces at the
+ * harness rather than getting silently swallowed here.
+ */
+export function stripAgentFlag(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] === '--agent' && i + 1 < args.length) {
+            i += 1;
+            continue;
+        }
+        out.push(args[i]);
+    }
+    return out;
+}
+/**
+ * Validate that a configFile's relative path is safe to resolve under a
+ * sandbox/session directory. Rejects absolute paths and any segment equal to
+ * `..` so a malformed or adversarial persona cannot escape the mount via
+ * `join()` and overwrite files elsewhere. Called at materialization time so
+ * the failure surfaces with a clear path before any disk write happens.
+ */
+export function assertSafeRelativePath(relPath) {
+    if (!relPath) {
+        throw new Error('configFile path must be a non-empty relative path');
+    }
+    if (isAbsolute(relPath)) {
+        throw new Error(`configFile path must be relative; got absolute path ${JSON.stringify(relPath)}`);
+    }
+    const segments = relPath.split(/[\\/]+/);
+    if (segments.some((s) => s === '..')) {
+        throw new Error(`configFile path must not contain ".." segments; got ${JSON.stringify(relPath)}`);
+    }
+}
 /** 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
@@ -224,38 +357,84 @@ export const CLEAN_IGNORED_PATTERNS = [
     '.mcp.json'
 ];
 /**
- * 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.
+ * Skill-install artifacts that should never be copied into the mount nor
+ * synced back to the real repo. Applied to non-claude interactive sessions
+ * that rely on the mount to keep `npx skills add` / `npx prpm install`
+ * writes out of the user's project tree. Covers every per-provider output
+ * root that skill.sh / prpm scatter into on install — missing one here
+ * re-introduces repo pollution, so this list is deliberately superset-y.
+ * Claude sessions use `installRoot` for out-of-repo staging instead, so
+ * these patterns don't apply there.
+ */
+export const SKILL_INSTALL_IGNORED_PATTERNS = [
+    // skill.sh universal install root + per-harness symlink farms
+    '.agents',
+    '.claude/skills',
+    '.factory/skills',
+    '.kiro/skills',
+    'skills',
+    // prpm `--as <harness>` output roots
+    '.opencode',
+    '.skills',
+    // provider lockfiles written at the repo root
+    'prpm.lock',
+    'skills-lock.json'
+];
+/**
+ * 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.
+ *
+ * Pure — no side effects, trivially testable.
  */
-export function decideCleanMode(harness, clean) {
-    if (!clean)
-        return { useClean: false };
-    if (harness !== 'claude') {
+export function decideCleanMode(harness, clean, installInRepo = false) {
+    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.`
         };
     }
-    return { useClean: true };
+    return { useClean: false };
 }
 async function runInteractive(selection, options = {}) {
     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);
+    // `installRoot` (out-of-repo skill staging via `--plugin-dir`) is currently
+    // claude-only; the workload-router SDK throws if it's set for other
+    // harnesses. For opencode, we instead keep installs out of the repo by
+    // 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(runtime.harness, options.clean === true, options.installInRepo === true);
     if (cleanDecision.warning) {
         process.stderr.write(`warning: ${cleanDecision.warning}\n`);
     }
     const useClean = cleanDecision.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.
+    const useSessionDir = !options.installInRepo && (runtime.harness === 'claude' || useClean);
+    const sessionRoot = useSessionDir ? generateSessionRoot(personaId) : undefined;
+    const installRoot = sessionRoot && runtime.harness === 'claude'
+        ? sessionInstallRoot(sessionRoot)
+        : undefined;
     const ctx = useSelection(selection, installRoot !== undefined ? { installRoot } : {});
     const { install } = ctx;
     process.stderr.write(`→ ${personaId} [${tier}] via ${runtime.harness} (${runtime.model})\n`);
@@ -268,16 +447,21 @@ async function runInteractive(selection, options = {}) {
     // 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}` : '';
-        const label = install.plan.installs.length === 0
-            ? `Staging session plugin dir${targetLabel}`
-            : `Installing skills: ${skillIds}${targetLabel}`;
-        runInstall(install.command, label);
+    const skillIds = install.plan.installs.map((i) => i.skillId).join(', ');
+    const installLabel = install.plan.installs.length === 0
+        ? `Staging session plugin dir${installRoot ? ` → ${installRoot}` : ''}`
+        : `Installing skills: ${skillIds}${installRoot ? ` → ${installRoot}` : ''}`;
+    // When useClean engages on a non-claude harness, the install must run
+    // INSIDE the mount so `.opencode/skills/`, `.agents/skills/`, prpm.lock,
+    // etc. land in the sandbox rather than the real repo. We defer it to
+    // `onBeforeLaunch` below instead of pre-running here.
+    const deferInstallToMount = useClean && runtime.harness !== 'claude' && install.commandString !== ':';
+    if (install.commandString !== ':' && !deferInstallToMount) {
+        runInstall(install.command, installLabel);
     }
     const spec = buildInteractiveSpec({
         harness: runtime.harness,
+        personaId,
         model: runtime.model,
         systemPrompt: runtime.systemPrompt,
         mcpServers: resolvedMcp,
@@ -286,7 +470,26 @@ async function runInteractive(selection, options = {}) {
     });
     for (const w of spec.warnings)
         process.stderr.write(`warning: ${w}\n`);
-    const finalArgs = spec.initialPrompt ? [...spec.args, spec.initialPrompt] : [...spec.args];
+    // 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.
+    //  - 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
+    //    into the user's real repo would pollute the working tree, so we
+    //    degrade: drop --agent from the argv, warn, and launch opencode with
+    //    its default agent. The persona's prompt will not be applied in that
+    //    mode; users who want it should drop --install-in-repo (the mount
+    //    default handles this cleanly).
+    const hasConfigFiles = spec.configFiles.length > 0;
+    const degradeConfigFiles = hasConfigFiles && !useClean;
+    let effectiveArgs = spec.args;
+    if (degradeConfigFiles) {
+        process.stderr.write('warning: --install-in-repo cannot safely materialize the persona agent config (would write opencode.json into your repo); launching without --agent. Drop --install-in-repo to apply the persona prompt.\n');
+        effectiveArgs = stripAgentFlag(spec.args);
+    }
+    const finalArgs = spec.initialPrompt ? [...effectiveArgs, spec.initialPrompt] : [...effectiveArgs];
     // Print a sanitized summary rather than raw argv: spec.args for the claude
     // harness contains the resolved --mcp-config JSON and the full system
     // prompt, either of which can carry secrets (Bearer tokens, API keys) once
@@ -310,42 +513,194 @@ async function runInteractive(selection, options = {}) {
     if (spec.initialPrompt)
         summary.push('initial-prompt=<systemPrompt>');
     if (useClean)
-        summary.push('clean=on');
+        summary.push('mount=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.
+    // 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 opencode: mount engages by default (unless `--install-in-repo`), and
+    // 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.
     if (useClean && sessionRoot) {
         const mountDir = sessionMountDir(sessionRoot);
-        process.stderr.write(`• clean mount → ${mountDir}\n`);
+        const ignoredPatterns = runtime.harness === 'claude'
+            ? [...CLEAN_IGNORED_PATTERNS]
+            : [...SKILL_INSTALL_IGNORED_PATTERNS];
+        // Anything we materialize into the mount via onBeforeLaunch must be
+        // hidden from the mount-mirror in both directions: without this, any
+        // opencode.json already present in the real repo would be copied into
+        // the mount (masking the per-session agent config we write), and the
+        // fresh write from onBeforeLaunch would sync back out on exit and
+        // pollute the user's working tree. Added dynamically so this stays
+        // generic for any future configFile producer.
+        for (const file of spec.configFiles) {
+            ignoredPatterns.push(file.path);
+        }
+        process.stderr.write(`• sandbox mount → ${mountDir}\n`);
+        // Three-stage SIGINT handler layered on top of launchOnMount's own signal
+        // forwarding. launchOnMount catches the first SIGINT to kill the child
+        // and run its finalize() (autoSync.stop + final syncBack), which walks
+        // both trees and can take several seconds on a large repo — during
+        // which the terminal otherwise looks frozen.
+        //
+        //   1st press  → start an ora spinner so the pause is visibly live
+        //                (replaces the prior static print). onAfterSync below
+        //                transitions the spinner into a succeed/fail state once
+        //                relayfile reports the sync result.
+        //   2nd press  → update the spinner text to the "aborting" warning and
+        //                abort `shutdownSignal`, which local-mount 0.5+ respects
+        //                by skipping autosync's draining reconcile and returning
+        //                the partial count from the final syncBack. Cleanup
+        //                still runs, so no leaked mount dir.
+        //   3rd press  → hard escape: synchronously rm the mount root and
+        //                process.exit(130) in case the abort never resolves.
+        const shutdownController = new AbortController();
+        let sigintCount = 0;
+        let syncSpinner;
+        const forceExitHandler = () => {
+            sigintCount += 1;
+            if (sigintCount === 1) {
+                syncSpinner = ora({
+                    text: 'Syncing session changes back to the repo… (Ctrl-C again to skip)',
+                    stream: process.stderr
+                }).start();
+                return;
+            }
+            if (sigintCount === 2) {
+                if (syncSpinner) {
+                    syncSpinner.text =
+                        'Aborting sync — partial changes will be propagated. (Ctrl-C again to force quit)';
+                }
+                shutdownController.abort();
+                return;
+            }
+            if (syncSpinner) {
+                syncSpinner.fail('Force-quit: mount teardown skipped. Session dir may be left behind.');
+                syncSpinner = undefined;
+            }
+            else {
+                process.stderr.write('\n✗ Force-quit: mount teardown skipped. Session dir may be left behind.\n');
+            }
+            // Node-native removal rather than `rm -rf` so the emergency path
+            // works on Windows too.
+            try {
+                rmSync(sessionRoot, { recursive: true, force: true });
+            }
+            catch {
+                /* swallow — we're exiting anyway */
+            }
+            process.exit(130);
+        };
+        process.on('SIGINT', forceExitHandler);
         try {
             const result = await launchOnMount({
                 cli: spec.bin,
                 projectDir: process.cwd(),
                 mountDir,
                 args: finalArgs,
-                ignoredPatterns: [...CLEAN_IGNORED_PATTERNS],
+                ignoredPatterns,
                 // 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
+                agentName: personaId,
+                // 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.
+                shutdownSignal: shutdownController.signal,
+                // Report sync stats so the user sees confirmation rather than a
+                // silent pause between the child exiting and the CLI returning.
+                //
+                // NOTE: `count` is bidirectional per relayfile's onAfterSync
+                // contract (see @relayfile/local-mount launch.d.ts) — it sums
+                // autosync activity in *both* directions (inbound project→mount
+                // and outbound mount→project, including deletes) plus the final
+                // mount→project syncBack. Phrasing this as "synced back to the
+                // repo" earlier misled sessions where inbound events dominated:
+                // a user who did no edits still saw "Synced 15 changes back"
+                // because ambient initial-mirror traffic counted. Phrase as "file
+                // events during session" so we don't overclaim direction.
+                onAfterSync: (count) => {
+                    const aborted = shutdownController.signal.aborted;
+                    const qualifier = aborted ? ' (partial)' : '';
+                    const message = count > 0
+                        ? `Session complete — ${count} file event${count === 1 ? '' : 's'} during session${qualifier}.`
+                        : 'Session complete — no file events.';
+                    if (syncSpinner) {
+                        syncSpinner.succeed(message);
+                        syncSpinner = undefined;
+                    }
+                    else {
+                        process.stderr.write(`✓ ${message}\n`);
+                    }
+                },
+                ...(deferInstallToMount || hasConfigFiles
+                    ? {
+                        onBeforeLaunch: (dir) => {
+                            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) {
+            // If the spinner is still live when we error out, mark it failed so
+            // the pending animation doesn't hang around under the error message.
+            if (syncSpinner) {
+                syncSpinner.fail('Sync did not complete');
+                syncSpinner = undefined;
+            }
+            // InstallCommandError carries the real install exit code — surfacing
+            // it (rather than collapsing onto 127) lets callers distinguish a
+            // failed `npx prpm install` from a missing harness binary.
+            if (err instanceof InstallCommandError) {
+                process.stderr.write(`${err.message}. Aborting.\n`);
+                return err.exitCode;
+            }
             const e = err;
             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`);
+                process.stderr.write(`Failed to spawn "${spec.bin}" inside sandbox mount: binary not found on PATH. Install the ${runtime.harness} CLI and retry.\n`);
+                return 127;
             }
-            return 127;
+            process.stderr.write(`Failed to launch sandbox mount: ${e.message}\n`);
+            return 1;
         }
         finally {
-            runCleanup(install.cleanupCommand, install.cleanupCommandString);
+            // Defensive: if neither onAfterSync nor the catch branch stopped the
+            // spinner (e.g. unexpected exit path), stop it cleanly here so the
+            // terminal is not left in spinner state.
+            if (syncSpinner) {
+                syncSpinner.stop();
+                syncSpinner = undefined;
+            }
+            process.removeListener('SIGINT', forceExitHandler);
+            // When the install ran inside the mount, its cleanup paths are
+            // mount-relative (e.g. `.skills/<name>`, `skills/<name>`) and
+            // running cleanup here would resolve them against the real repo
+            // cwd — potentially `rm -rf`ing pre-existing user content. The
+            // mount dir is removed wholesale by `removeSessionRoot` below, so
+            // the install's cleanup is redundant anyway in that case.
+            if (!deferInstallToMount) {
+                runCleanup(install.cleanupCommand, install.cleanupCommandString);
+            }
             removeSessionRoot(sessionRoot);
         }
     }
@@ -573,6 +928,192 @@ function runList(args) {
     }
     process.exit(0);
 }
+function parseShowArgs(args) {
+    let json = false;
+    let all = false;
+    let selector;
+    for (const arg of args) {
+        if (arg === '--json') {
+            json = true;
+        }
+        else if (arg === '--all') {
+            all = true;
+        }
+        else if (arg === '-h' || arg === '--help') {
+            process.stdout.write('Usage: agent-workforce show <persona>[@<tier>] [--all] [--json]\n');
+            process.exit(0);
+        }
+        else if (arg.startsWith('--')) {
+            die(`show: unexpected flag "${arg}".`);
+        }
+        else if (selector === undefined) {
+            selector = arg;
+        }
+        else {
+            die(`show: unexpected argument "${arg}".`);
+        }
+    }
+    if (!selector)
+        die('show: missing persona name.');
+    return { selector, json, all };
+}
+function resolveShowTarget(selector, all) {
+    const at = selector.indexOf('@');
+    const key = at === -1 ? selector : selector.slice(0, at);
+    const tierRaw = at === -1 ? undefined : selector.slice(at + 1);
+    if (!key)
+        die('show: missing persona name before "@".');
+    let explicitTier;
+    if (tierRaw !== undefined) {
+        if (!PERSONA_TIERS.includes(tierRaw)) {
+            die(`show: invalid tier "${tierRaw}". Must be one of: ${PERSONA_TIERS.join(', ')}`);
+        }
+        explicitTier = tierRaw;
+        if (all) {
+            die('show: --all cannot be combined with an explicit @<tier> suffix.');
+        }
+    }
+    const localSpec = local.byId.get(key);
+    let spec;
+    let source = 'library';
+    if (localSpec) {
+        spec = localSpec;
+        source = local.sources.get(key) ?? 'pwd';
+    }
+    else {
+        const byIntent = personaCatalog[key];
+        if (byIntent) {
+            spec = byIntent;
+        }
+        else {
+            const byId = Object.values(personaCatalog).find((p) => p.id === key);
+            if (byId)
+                spec = byId;
+        }
+    }
+    if (!spec) {
+        const result = resolveSpec(key);
+        if ('error' in result)
+            die(result.error, false);
+        spec = result;
+    }
+    let tiers;
+    if (all) {
+        tiers = [...PERSONA_TIERS];
+    }
+    else if (explicitTier) {
+        tiers = [explicitTier];
+    }
+    else {
+        const rule = routingProfiles.default.intents[spec.intent];
+        tiers = [rule?.tier ?? 'best-value'];
+    }
+    return { spec, source, tiers, explicitTier };
+}
+function indent(text, prefix) {
+    return text
+        .split('\n')
+        .map((line) => (line.length > 0 ? prefix + line : line))
+        .join('\n');
+}
+function formatPersonaShow(spec, source, tiers, tierNote) {
+    const lines = [];
+    lines.push(`PERSONA      ${spec.id}`);
+    lines.push(`SOURCE       ${source}`);
+    lines.push(`INTENT       ${spec.intent}`);
+    lines.push(`TAGS         ${spec.tags.length ? spec.tags.join(', ') : '(none)'}`);
+    lines.push(`DESCRIPTION  ${spec.description}`);
+    lines.push(`TIERS SHOWN  ${tiers.join(', ')}${tierNote ? `  (${tierNote})` : ''}`);
+    lines.push('');
+    lines.push('SKILLS');
+    if (spec.skills.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const s of spec.skills) {
+            lines.push(`  - ${s.id}`);
+            lines.push(`      source:      ${s.source}`);
+            lines.push(`      description: ${s.description}`);
+        }
+    }
+    lines.push('');
+    lines.push('MCP SERVERS');
+    const servers = Object.entries(spec.mcpServers ?? {});
+    if (servers.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const [name, server] of servers) {
+            lines.push(`  - ${name} (${server.type})`);
+            if (server.type === 'stdio') {
+                lines.push(`      command: ${server.command}${server.args?.length ? ' ' + server.args.join(' ') : ''}`);
+                if (server.env && Object.keys(server.env).length > 0) {
+                    lines.push(`      env:     ${Object.keys(server.env).join(', ')}`);
+                }
+            }
+            else {
+                lines.push(`      url:     ${server.url}`);
+                if (server.headers && Object.keys(server.headers).length > 0) {
+                    lines.push(`      headers: ${Object.keys(server.headers).join(', ')}`);
+                }
+            }
+        }
+    }
+    lines.push('');
+    lines.push('PERMISSIONS');
+    const perms = spec.permissions;
+    if (!perms || (!perms.allow?.length && !perms.deny?.length && !perms.mode)) {
+        lines.push('  (none)');
+    }
+    else {
+        if (perms.mode)
+            lines.push(`  mode:  ${perms.mode}`);
+        if (perms.allow?.length)
+            lines.push(`  allow: ${perms.allow.join(', ')}`);
+        if (perms.deny?.length)
+            lines.push(`  deny:  ${perms.deny.join(', ')}`);
+    }
+    lines.push('');
+    lines.push('ENV');
+    const envKeys = Object.keys(spec.env ?? {});
+    if (envKeys.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const k of envKeys)
+            lines.push(`  ${k}=${spec.env[k]}`);
+    }
+    for (const tier of tiers) {
+        const rt = spec.tiers[tier];
+        lines.push('');
+        lines.push(`TIER: ${tier}`);
+        lines.push(`  harness:  ${rt.harness}`);
+        lines.push(`  model:    ${rt.model}`);
+        lines.push(`  reasoning: ${rt.harnessSettings.reasoning}`);
+        lines.push(`  timeout:  ${rt.harnessSettings.timeoutSeconds}s`);
+        lines.push('  systemPrompt:');
+        lines.push(indent(rt.systemPrompt, '    '));
+    }
+    return lines.join('\n') + '\n';
+}
+function runShow(args) {
+    const { selector, json, all } = parseShowArgs(args);
+    const { spec, source, tiers, explicitTier } = resolveShowTarget(selector, all);
+    const tierNote = all
+        ? 'all tiers'
+        : explicitTier
+            ? 'explicit @<tier>'
+            : 'recommended for intent; pass --all or @<tier> to override';
+    if (json) {
+        const projectedTiers = Object.fromEntries(tiers.map((t) => [t, spec.tiers[t]]));
+        const projected = { ...spec, tiers: projectedTiers };
+        process.stdout.write(JSON.stringify({ source, spec: projected }, null, 2) + '\n');
+    }
+    else {
+        process.stdout.write(formatPersonaShow(spec, source, tiers, tierNote));
+    }
+    process.exit(0);
+}
 function runHarnessCheck() {
     const results = detectHarnesses();
     process.stdout.write(formatAvailabilityTable(results));
@@ -590,6 +1131,9 @@ async function main() {
     if (subcommand === 'list') {
         runList(rest);
     }
+    if (subcommand === 'show') {
+        runShow(rest);
+    }
     if (subcommand === 'harness') {
         const [action, ...extra] = rest;
         if (!action || action === '-h' || action === '--help') {