@agentworkforce/cli 0.9.0 → 0.11.0

package/dist/cli.js

@@ -5,10 +5,11 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync,
 import { constants, homedir } from 'node:os';
 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 { HARNESS_VALUES, PERSONA_TAGS, PERSONA_TIERS, personaCatalog, resolveSidecar, routingProfiles, useSelection } from '@agentworkforce/workload-router';
 import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, MissingPersonaInputError, renderPersonaInputs, resolvePersonaInputs, resolveMcpServersLenient, resolveStringMapLenient } from '@agentworkforce/harness-kit';
-import { launchOnMount } from '@relayfile/local-mount';
+import { launchOnMount, readAgentDotfiles } from '@relayfile/local-mount';
 import ora from 'ora';
+import { startLaunchMetadataRecording } from './launch-metadata.js';
 import { buildPersonaSourceDirectories, defaultCwdPersonaDir, loadLocalPersonas, loadPersonaSourceConfig, normalizePersonaDir, savePersonaSourceConfig } from './local-personas.js';
 import { installPersonas } from './persona-install.js';
 const USAGE = `Usage: agentworkforce <command> [args...]
@@ -26,6 +27,8 @@ Commands:
                         --save-default      Persist --to as defaultCreateTarget in
                                             ~/.agentworkforce/workforce/config.json.
                         --install-in-repo   Same behavior as agent.
+                        --no-launch-metadata
+                                            Same behavior as agent.
   agent [flags] <persona>[@<tier>]
                       Run a persona. Tier one of: ${PERSONA_TIERS.join(' | ')}
                       (default: best-value). Drops into an interactive harness
@@ -46,6 +49,10 @@ Commands:
                                             are hidden from the session. Codex
                                             sessions never mount and ignore
                                             this flag.
+                        --no-launch-metadata
+                                            Disable launch metadata recording.
+                                            Also disabled by
+                                            AGENTWORKFORCE_LAUNCH_METADATA=0.
   list [flags]        List available personas from the cascade (cwd →
                       configured persona dirs → library). By default shows
                       one row per persona at the recommended tier for its
@@ -165,7 +172,10 @@ function parseSelector(sel) {
     if ('error' in result)
         die(result.error, false);
     const kind = local.byId.has(key) ? 'local' : 'repo';
-    return { kind, spec: result, tier };
+    if (kind === 'local') {
+        return { kind, source: local.sources.get(result.id) ?? 'cwd', spec: result, tier };
+    }
+    return { kind, source: 'library', spec: result, tier };
 }
 /**
  * Resolve the `<harness>` placeholder used in persona systemPrompts.
@@ -187,6 +197,7 @@ function buildSelection(spec, tier, kind) {
         ...rawRuntime,
         systemPrompt: resolveSystemPromptPlaceholders(rawRuntime.systemPrompt, rawRuntime.harness)
     };
+    const sidecar = resolveSidecar(spec, tier);
     return {
         personaId: spec.id,
         tier,
@@ -196,7 +207,18 @@ function buildSelection(spec, tier, kind) {
         ...(spec.inputs ? { inputs: spec.inputs } : {}),
         ...(spec.env ? { env: spec.env } : {}),
         ...(spec.mcpServers ? { mcpServers: spec.mcpServers } : {}),
-        ...(spec.permissions ? { permissions: spec.permissions } : {})
+        ...(spec.permissions ? { permissions: spec.permissions } : {}),
+        ...(spec.mount ? { mount: spec.mount } : {}),
+        ...(sidecar.claudeMd ? { claudeMd: sidecar.claudeMd } : {}),
+        ...(sidecar.claudeMdContent ? { claudeMdContent: sidecar.claudeMdContent } : {}),
+        ...(sidecar.claudeMd || sidecar.claudeMdContent
+            ? { claudeMdMode: sidecar.claudeMdMode }
+            : {}),
+        ...(sidecar.agentsMd ? { agentsMd: sidecar.agentsMd } : {}),
+        ...(sidecar.agentsMdContent ? { agentsMdContent: sidecar.agentsMdContent } : {}),
+        ...(sidecar.agentsMd || sidecar.agentsMdContent
+            ? { agentsMdMode: sidecar.agentsMdMode }
+            : {})
     };
 }
 function emitDropWarnings(lines) {
@@ -368,7 +390,12 @@ export const CLEAN_IGNORED_PATTERNS = [
     'CLAUDE.md',
     'CLAUDE.local.md',
     '.claude',
-    '.mcp.json'
+    '.mcp.json',
+    // Per-persona AGENTS.md sidecars get materialized into the mount when
+    // running under opencode; without this the user's real-cwd AGENTS.md
+    // would copy in (masking the persona content) and writes from
+    // onBeforeLaunch would sync back out.
+    'AGENTS.md'
 ];
 /**
  * Skill-install artifacts that should never be copied into the mount nor
@@ -392,8 +419,32 @@ export const SKILL_INSTALL_IGNORED_PATTERNS = [
     '.skills',
     // provider lockfiles written at the repo root
     'prpm.lock',
-    'skills-lock.json'
+    'skills-lock.json',
+    // Per-persona AGENTS.md sidecars (opencode harness) get materialized
+    // into the mount; hide so the real-cwd AGENTS.md isn't copied in and
+    // the persona-written copy doesn't sync back out.
+    'AGENTS.md'
 ];
+export function buildRelayfileMountPatterns(input) {
+    const dotfiles = readAgentDotfiles(input.projectDir, {
+        agentName: input.personaId
+    });
+    const builtInIgnored = input.harness === 'claude'
+        ? CLEAN_IGNORED_PATTERNS
+        : SKILL_INSTALL_IGNORED_PATTERNS;
+    return {
+        ignoredPatterns: [
+            ...dotfiles.ignoredPatterns,
+            ...(input.mount?.ignoredPatterns ?? []),
+            ...builtInIgnored,
+            ...(input.configFilePaths ?? [])
+        ],
+        readonlyPatterns: [
+            ...dotfiles.readonlyPatterns,
+            ...(input.mount?.readonlyPatterns ?? [])
+        ]
+    };
+}
 /**
  * Build the block appended to `<mount>/.git/info/exclude` so untracked-and-
  * hidden files (e.g. `.claude/skills/` materialized by skill installs, or
@@ -465,6 +516,96 @@ export function configureGitForMount(mountDir, patterns) {
         }
     }
 }
+/**
+ * Resolve the sidecar for a given selection + harness, returning the
+ * persona-author content the runtime should materialize into the mount.
+ * Returns `{}` when no sidecar applies (no path/content set, or harness
+ * doesn't support sidecar files at all). Read errors surface as a warning
+ * string so the caller can drop the sidecar gracefully rather than
+ * failing the whole session.
+ */
+export function loadSidecarForSelection(selection) {
+    const harness = selection.runtime.harness;
+    if (harness !== 'claude' && harness !== 'opencode')
+        return {};
+    if (harness === 'claude') {
+        if (selection.claudeMdContent) {
+            return {
+                sidecar: {
+                    mountFile: 'CLAUDE.md',
+                    personaContent: selection.claudeMdContent,
+                    mode: selection.claudeMdMode ?? 'overwrite'
+                }
+            };
+        }
+        if (selection.claudeMd) {
+            try {
+                const content = readFileSync(selection.claudeMd, 'utf8');
+                return {
+                    sidecar: {
+                        mountFile: 'CLAUDE.md',
+                        personaContent: content,
+                        mode: selection.claudeMdMode ?? 'overwrite'
+                    }
+                };
+            }
+            catch (err) {
+                return { warning: `claudeMd: could not read ${selection.claudeMd}: ${err.message}` };
+            }
+        }
+        return {};
+    }
+    if (selection.agentsMdContent) {
+        return {
+            sidecar: {
+                mountFile: 'AGENTS.md',
+                personaContent: selection.agentsMdContent,
+                mode: selection.agentsMdMode ?? 'overwrite'
+            }
+        };
+    }
+    if (selection.agentsMd) {
+        try {
+            const content = readFileSync(selection.agentsMd, 'utf8');
+            return {
+                sidecar: {
+                    mountFile: 'AGENTS.md',
+                    personaContent: content,
+                    mode: selection.agentsMdMode ?? 'overwrite'
+                }
+            };
+        }
+        catch (err) {
+            return { warning: `agentsMd: could not read ${selection.agentsMd}: ${err.message}` };
+        }
+    }
+    return {};
+}
+/**
+ * Compute the bytes to write into the mount for a sidecar. In `extend`
+ * mode, prepends the user's real-cwd file (if any) joined to the persona
+ * content with `\n\n---\n\n`. Pure — exposed for unit tests.
+ */
+export function buildSidecarBody(sidecar, realCwdDir) {
+    if (sidecar.mode === 'extend') {
+        const realPath = join(realCwdDir, sidecar.mountFile);
+        try {
+            const realContent = readFileSync(realPath, 'utf8');
+            return `${realContent}\n\n---\n\n${sidecar.personaContent}`;
+        }
+        catch (err) {
+            // Only "missing path" errors degrade to overwrite. Real I/O
+            // problems (EACCES, EISDIR, …) propagate so callers see them
+            // instead of silently dropping the user's CLAUDE.md/AGENTS.md.
+            const code = err.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                return sidecar.personaContent;
+            }
+            throw err;
+        }
+    }
+    return sidecar.personaContent;
+}
 /**
  * Decide whether to run the interactive session inside a
  * `@relayfile/local-mount` sandbox.
@@ -482,7 +623,7 @@ export function decideCleanMode(harness, installInRepo = false) {
     }
     return { useClean: false };
 }
-async function runInteractive(selection, options = {}) {
+async function runInteractive(selection, options) {
     const inputResolution = resolvePersonaInputs(selection.inputs, selection.inputValues, process.env);
     const renderedSystemPrompt = renderPersonaInputs(selection.runtime.systemPrompt, inputResolution.values);
     const effectiveSelection = {
@@ -500,6 +641,21 @@ async function runInteractive(selection, options = {}) {
     // below). The --install-in-repo flag forces legacy in-repo installs
     // across the board.
     const useClean = decideCleanMode(runtime.harness, options.installInRepo === true).useClean;
+    // Per-persona CLAUDE.md / AGENTS.md: load the author content if any. The
+    // file is materialized into the mount inside onBeforeLaunch (claude/
+    // opencode default). Without a mount (codex, --install-in-repo) we
+    // skip-and-warn — writing into the real cwd would pollute the user's
+    // repo and is explicitly out of scope.
+    const sidecarLookup = loadSidecarForSelection(effectiveSelection);
+    if (sidecarLookup.warning) {
+        process.stderr.write(`warning: ${sidecarLookup.warning}\n`);
+    }
+    const resolvedSidecar = useClean ? sidecarLookup.sidecar : undefined;
+    if (sidecarLookup.sidecar && !useClean) {
+        process.stderr.write(`warning: persona declares ${sidecarLookup.sidecar.mountFile} but no sandbox mount is available (` +
+            `${runtime.harness === 'codex' ? 'codex harness has no mount' : '--install-in-repo disengages the mount'})` +
+            `; skipping sidecar materialization to avoid writing into your repo.\n`);
+    }
     // A session dir is needed whenever we either (a) stage skills out-of-repo
     // via claude's installRoot, or (b) open a mount. Both engage for claude/
     // opencode by default; --install-in-repo disengages both.
@@ -511,6 +667,14 @@ async function runInteractive(selection, options = {}) {
     const ctx = useSelection(effectiveSelection, installRoot !== undefined ? { installRoot } : {});
     const { install } = ctx;
     process.stderr.write(`→ ${personaId} [${tier}] via ${runtime.harness} (${runtime.model})\n`);
+    const startLaunchMetadataForLaunch = (cwd = process.cwd()) => startLaunchMetadataRecording({
+        selection: effectiveSelection,
+        personaSpec: options.personaSpec,
+        personaSource: options.personaSource,
+        cwd,
+        noLaunchMetadata: options.noLaunchMetadata,
+        env: process.env
+    });
     const inputEnv = inputResolution.values;
     const callerEnv = { ...process.env, ...inputEnv };
     const envResolution = resolveStringMapLenient(effectiveSelection.env, callerEnv, 'env');
@@ -608,9 +772,7 @@ async function runInteractive(selection, options = {}) {
     // copied in from the real repo nor synced back on exit.
     if (useClean && sessionRoot) {
         const mountDir = sessionMountDir(sessionRoot);
-        const ignoredPatterns = runtime.harness === 'claude'
-            ? [...CLEAN_IGNORED_PATTERNS]
-            : [...SKILL_INSTALL_IGNORED_PATTERNS];
+        let launchMetadata;
         // 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
@@ -618,9 +780,13 @@ async function runInteractive(selection, options = {}) {
         // 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);
-        }
+        const { ignoredPatterns, readonlyPatterns } = buildRelayfileMountPatterns({
+            projectDir: process.cwd(),
+            personaId,
+            harness: runtime.harness,
+            mount: effectiveSelection.mount,
+            configFilePaths: spec.configFiles.map((file) => 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
@@ -696,6 +862,7 @@ async function runInteractive(selection, options = {}) {
                 // `git push` to persist work — local-only commits evaporate with
                 // the session.
                 includeGit: true,
+                readonlyPatterns,
                 // 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.
@@ -726,7 +893,7 @@ async function runInteractive(selection, options = {}) {
                         process.stderr.write(`✓ ${message}\n`);
                     }
                 },
-                onBeforeLaunch: (dir) => {
+                onBeforeLaunch: async (dir) => {
                     // Run before install / configFile writes so the freshly written
                     // files (e.g. `.opencode/`, `opencode.json`) aren't yet present
                     // when we run `git ls-files` to pick skip-worktree candidates —
@@ -745,6 +912,11 @@ async function runInteractive(selection, options = {}) {
                         mkdirSync(dirname(target), { recursive: true });
                         writeFileSync(target, file.contents, 'utf8');
                     }
+                    if (resolvedSidecar) {
+                        const body = buildSidecarBody(resolvedSidecar, process.cwd());
+                        writeFileSync(join(dir, resolvedSidecar.mountFile), body, 'utf8');
+                    }
+                    launchMetadata = await startLaunchMetadataForLaunch(dir);
                 }
             });
             return result.exitCode;
@@ -779,6 +951,7 @@ async function runInteractive(selection, options = {}) {
                 syncSpinner.stop();
                 syncSpinner = undefined;
             }
+            await launchMetadata?.stop();
             process.removeListener('SIGINT', forceExitHandler);
             // When the install ran inside the mount, its cleanup paths are
             // mount-relative (e.g. `.skills/<name>`, `skills/<name>`) and
@@ -792,6 +965,7 @@ async function runInteractive(selection, options = {}) {
             removeSessionRoot(sessionRoot);
         }
     }
+    const launchMetadata = await startLaunchMetadataForLaunch();
     return new Promise((resolve) => {
         let settled = false;
         const finish = (code) => {
@@ -800,7 +974,7 @@ async function runInteractive(selection, options = {}) {
             settled = true;
             runCleanup(install.cleanupCommand, install.cleanupCommandString);
             removeSessionRoot(sessionRoot);
-            resolve(code);
+            void launchMetadata.stop().finally(() => resolve(code));
         };
         const child = spawn(spec.bin, finalArgs, {
             stdio: 'inherit',
@@ -1454,6 +1628,20 @@ function formatPersonaShow(spec, source, tiers, tierNote) {
             lines.push(`  deny:  ${perms.deny.join(', ')}`);
     }
     lines.push('');
+    lines.push('MOUNT');
+    const mount = spec.mount;
+    if (!mount || (!mount.ignoredPatterns?.length && !mount.readonlyPatterns?.length)) {
+        lines.push('  (none)');
+    }
+    else {
+        if (mount.ignoredPatterns?.length) {
+            lines.push(`  ignored:  ${mount.ignoredPatterns.join(', ')}`);
+        }
+        if (mount.readonlyPatterns?.length) {
+            lines.push(`  readonly: ${mount.readonlyPatterns.join(', ')}`);
+        }
+    }
+    lines.push('');
     lines.push('ENV');
     const envKeys = Object.keys(spec.env ?? {});
     if (envKeys.length === 0) {
@@ -1584,7 +1772,10 @@ async function runAgentSelector(selector, flags, inputValues) {
         ...(inputValues ? { inputValues } : {})
     };
     const code = await runInteractive(selection, {
-        installInRepo: flags.installInRepo
+        installInRepo: flags.installInRepo,
+        noLaunchMetadata: flags.noLaunchMetadata,
+        personaSpec: target.spec,
+        personaSource: target.source
     });
     process.exit(code);
 }
@@ -1641,7 +1832,7 @@ export async function main() {
     await runAgentSelector(selector, flags);
 }
 export function parseAgentArgs(args) {
-    const flags = { installInRepo: false };
+    const flags = { installInRepo: false, noLaunchMetadata: false };
     const positional = [];
     let seenDoubleDash = false;
     for (const arg of args) {
@@ -1657,6 +1848,10 @@ export function parseAgentArgs(args) {
             flags.installInRepo = true;
             continue;
         }
+        if (arg === '--no-launch-metadata') {
+            flags.noLaunchMetadata = true;
+            continue;
+        }
         if (arg === '-h' || arg === '--help') {
             process.stdout.write(USAGE);
             process.exit(0);
@@ -1666,7 +1861,7 @@ export function parseAgentArgs(args) {
     return { flags, positional };
 }
 export function parseCreateArgs(args) {
-    const flags = { installInRepo: false, saveDefault: false };
+    const flags = { installInRepo: false, noLaunchMetadata: false, saveDefault: false };
     let seenDoubleDash = false;
     const positional = [];
     const valueOf = (i, flag) => {
@@ -1690,6 +1885,10 @@ export function parseCreateArgs(args) {
             flags.installInRepo = true;
             continue;
         }
+        if (arg === '--no-launch-metadata') {
+            flags.noLaunchMetadata = true;
+            continue;
+        }
         if (arg === '--to') {
             flags.to = valueOf(i, arg);
             i += 1;
@@ -1700,7 +1899,7 @@ export function parseCreateArgs(args) {
             continue;
         }
         if (arg === '-h' || arg === '--help') {
-            process.stdout.write('Usage: agentworkforce create [--to <cwd|user|dir:n|library|path>] [--save-default] [--install-in-repo]\n');
+            process.stdout.write('Usage: agentworkforce create [--to <cwd|user|dir:n|library|path>] [--save-default] [--install-in-repo] [--no-launch-metadata]\n');
             process.exit(0);
         }
         positional.push(arg);