@phnx-labs/agents-cli 1.18.6 → 1.19.1

package/dist/lib/session/cloud.js

@@ -17,6 +17,7 @@ import { getCacheDir } from '../state.js';
 const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 const CLOUD_CACHE_DIR = path.join(getCacheDir(), 'cloud-runs');
+const CLOUD_EXECUTION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 function readToken() {
     if (!fs.existsSync(USER_YAML)) {
         throw new Error('Not logged in to Rush. Run `rush login` first.');
@@ -45,6 +46,24 @@ function agentToFormat(agent) {
         return 'rush';
     return null;
 }
+export function assertContained(candidate, rootDir) {
+    const root = path.resolve(rootDir);
+    const resolved = path.resolve(root, candidate);
+    if (!resolved.startsWith(root + path.sep)) {
+        throw new Error(`Path escapes cloud session cache: ${candidate}`);
+    }
+    return resolved;
+}
+export function validateCloudExecutionId(executionId) {
+    if (!CLOUD_EXECUTION_ID_RE.test(executionId)) {
+        throw new Error(`Invalid cloud execution_id: ${JSON.stringify(executionId)}`);
+    }
+    return executionId;
+}
+function cachePathForExecution(executionId, agent) {
+    const id = validateCloudExecutionId(executionId);
+    return assertContained(path.join(id, `session.${agent}.jsonl`), CLOUD_CACHE_DIR);
+}
 /**
  * List cloud executions the user has captured sessions for. Includes
  * completed + needs_review + failed; an empty session_path means capture
@@ -64,13 +83,13 @@ export async function discoverCloudSessions(options) {
         const agent = agentToFormat(row.agent);
         if (!agent)
             continue;
-        const id = row.execution_id;
+        const id = validateCloudExecutionId(row.execution_id);
         const timestamp = row.updated_at || row.created_at || new Date().toISOString();
         const project = row.repo_owner && row.repo_name ? `${row.repo_owner}/${row.repo_name}` : undefined;
         // filePath doubles as the sink path for the cached jsonl. parseSession
         // dispatches on detectAgent which recognizes the `session.<format>.jsonl`
         // suffix — so the local cache file name must preserve it.
-        const filePath = path.join(CLOUD_CACHE_DIR, id, `session.${agent}.jsonl`);
+        const filePath = cachePathForExecution(id, agent);
         out.push({
             id,
             shortId: id.slice(0, 8),
@@ -91,8 +110,10 @@ export async function discoverCloudSessions(options) {
  * are immutable once complete). Callers may pass an already-known filePath.
  */
 export async function ensureCloudSessionCached(executionId, destPath) {
+    const id = validateCloudExecutionId(executionId);
+    const callerPath = destPath ? assertContained(destPath, CLOUD_CACHE_DIR) : undefined;
     const token = readToken();
-    const res = await api('GET', `/api/v1/cloud-runs/${encodeURIComponent(executionId)}/session.jsonl`, token);
+    const res = await api('GET', `/api/v1/cloud-runs/${encodeURIComponent(id)}/session.jsonl`, token);
     if (!res.ok) {
         const body = await res.text().catch(() => '');
         throw new Error(`session.jsonl fetch ${res.status}: ${body.slice(0, 200)}`);
@@ -101,7 +122,7 @@ export async function ensureCloudSessionCached(executionId, destPath) {
     if (!['claude', 'codex', 'rush'].includes(format)) {
         throw new Error(`Unknown X-Session-Format on cloud response: "${format}"`);
     }
-    const finalPath = destPath ?? path.join(CLOUD_CACHE_DIR, executionId, `session.${format}.jsonl`);
+    const finalPath = callerPath ?? cachePathForExecution(id, format);
     fs.mkdirSync(path.dirname(finalPath), { recursive: true });
     const body = Buffer.from(await res.arrayBuffer());
     fs.writeFileSync(finalPath, body);
@@ -109,7 +130,9 @@ export async function ensureCloudSessionCached(executionId, destPath) {
 }
 /** True if filePath points into the cloud session cache dir. */
 export function isCloudSessionPath(filePath) {
-    return filePath.startsWith(CLOUD_CACHE_DIR);
+    const root = path.resolve(CLOUD_CACHE_DIR);
+    const resolved = path.resolve(filePath);
+    return resolved.startsWith(root + path.sep);
 }
 /** Extract execution_id from a cloud cache path. */
 export function executionIdFromCloudPath(filePath) {
@@ -117,5 +140,10 @@ export function executionIdFromCloudPath(filePath) {
         return null;
     const rel = path.relative(CLOUD_CACHE_DIR, filePath);
     const parts = rel.split(path.sep);
-    return parts[0] || null;
+    try {
+        return parts[0] ? validateCloudExecutionId(parts[0]) : null;
+    }
+    catch {
+        return null;
+    }
 }

package/dist/lib/session/parse.js

@@ -6,7 +6,7 @@
  * objects suitable for rendering, filtering, and summarization.
  */
 import * as fs from 'fs';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
  * error instead of OOMing or hitting V8's ERR_STRING_TOO_LONG. Aligns with
@@ -668,7 +668,12 @@ export function parseOpenCode(filePath) {
       WHERE m.session_id = '${sessionId.replace(/'/g, "''")}'
       ORDER BY m.time_created ASC, p.time_created ASC;
     `.replace(/\n/g, ' ');
-        const out = execSync(`sqlite3 -separator '|||' "${dbPath}"`, { encoding: 'utf-8', input: query, stdio: ['pipe', 'pipe', 'ignore'], timeout: 10000 });
+        const out = execFileSync('sqlite3', ['-separator', '|||', dbPath, query], {
+            encoding: 'utf-8',
+            timeout: 10000,
+            maxBuffer: 32 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
         for (const line of out.split('\n')) {
             if (!line.trim())
                 continue;

package/dist/lib/session/render.d.ts

@@ -94,7 +94,10 @@ export declare function filterEvents(events: SessionEvent[], opts: FilterOptions
  * order so reasoning sits where it actually occurred relative to the assistant
  * reply.
  */
-export declare function renderConversationMarkdown(events: SessionEvent[]): string;
+export interface RenderConversationMarkdownOptions {
+    redact?: boolean;
+}
+export declare function renderConversationMarkdown(events: SessionEvent[], opts?: RenderConversationMarkdownOptions): string;
 /**
  * Render session as JSON (normalized events).
  */

package/dist/lib/session/render.js

@@ -10,6 +10,7 @@ import chalk from 'chalk';
 import { summarizeToolUse } from './parse.js';
 import { cleanSessionPrompt, extractSessionTopic } from './prompt.js';
 import { renderMarkdown } from '../markdown.js';
+import { redactSecrets } from '../redact.js';
 // ── Path helpers ──────────────────────────────────────────────────────────────
 /**
  * Return absPath relative to cwd; fall back to ~/… then absolute.
@@ -405,6 +406,26 @@ function renderFileGroup(lines, groups, absPathMap) {
         }
     }
 }
+// ── Recent activity renderer ──────────────────────────────────────────────────
+/** Render a single Recent Activity line as `<kind-tag> <label>`, colored by kind. */
+function renderActivityLine(item) {
+    const MAX = 90;
+    const trim = (s) => (s.length <= MAX ? s : s.slice(0, MAX - 1) + '…');
+    switch (item.kind) {
+        case 'edit': {
+            const linked = item.absPath ? linkPath(item.absPath, item.label) : item.label;
+            return chalk.cyan('Edit ') + ' ' + linked;
+        }
+        case 'cmd':
+            return chalk.yellow('Bash ') + ' ' + chalk.gray(trim(item.label));
+        case 'agent':
+            return chalk.magenta('Agent') + ' ' + trim(item.label);
+        case 'error':
+            return chalk.red('Error') + ' ' + chalk.gray(trim(item.label));
+        case 'msg':
+            return chalk.green('Msg  ') + ' ' + chalk.gray('"' + trim(item.label) + '"');
+    }
+}
 // ── Main summary renderer ─────────────────────────────────────────────────────
 /**
  * Render session as an activity summary.
@@ -429,6 +450,7 @@ export function renderSummary(events, cwd) {
     const subagents = [];
     // Errors
     const errors = [];
+    const recentActivity = [];
     // Assistant message count (used to decide whether the session produced any narration)
     let assistantCount = 0;
     const isInsideCwd = (p) => !!(cwd && p.startsWith(cwd + '/'));
@@ -451,13 +473,16 @@ export function renderSummary(events, cwd) {
                     }
                     else {
                         (isInsideCwd(p) || !cwd ? filesModifiedAbs : filesModifiedExternal).add(p);
+                        recentActivity.push({ kind: 'edit', label: relativeToCwd(p, cwd), ts, absPath: p });
                     }
                 }
             }
             if (event.command) {
                 const cmd = event.command.replace(/\n/g, ' ').trim();
-                if (cmd)
+                if (cmd) {
                     cmdList.push({ cmd, ts });
+                    recentActivity.push({ kind: 'cmd', label: cmd, ts });
+                }
             }
             // Plan items: TodoWrite items + TaskCreate descriptions (project's task tracker)
             if (tool === 'TodoWrite' && Array.isArray(args.todos)) {
@@ -477,18 +502,26 @@ export function renderSummary(events, cwd) {
             }
             // Subagent spawns
             if ((tool === 'Agent' || tool === 'Task') && (args.description || args.prompt)) {
-                subagents.push({
-                    description: String(args.description || args.prompt || '').slice(0, 120),
-                    subagentType: String(args.subagent_type || ''),
-                });
+                const description = String(args.description || args.prompt || '').slice(0, 120);
+                const subagentType = String(args.subagent_type || '');
+                subagents.push({ description, subagentType });
+                const typeSuffix = subagentType ? ` (${subagentType})` : '';
+                recentActivity.push({ kind: 'agent', label: description + typeSuffix, ts });
             }
         }
         else if (event.type === 'error') {
-            errors.push({
+            const err = {
                 tool: event.tool || 'unknown',
                 cmd: event.args?.command ? String(event.args.command).slice(0, 80) : undefined,
                 content: event.content?.slice(0, 120),
-            });
+            };
+            errors.push(err);
+            const errLabel = err.cmd
+                ? `${err.tool} "${err.cmd.slice(0, 60)}"`
+                : err.content
+                    ? `${err.tool}: ${err.content.slice(0, 60)}`
+                    : err.tool;
+            recentActivity.push({ kind: 'error', label: errLabel, ts });
         }
         else if (event.type === 'message') {
             if (event.role === 'user') {
@@ -504,6 +537,9 @@ export function renderSummary(events, cwd) {
             else if (event.role === 'assistant' && event.content) {
                 lastAssistantMessage = event.content;
                 assistantCount++;
+                const preview = event.content.replace(/\s+/g, ' ').trim().slice(0, 100);
+                if (preview)
+                    recentActivity.push({ kind: 'msg', label: preview, ts });
             }
         }
         else if (event.type === 'attachment') {
@@ -549,7 +585,18 @@ export function renderSummary(events, cwd) {
     }
     if (firstUserMessage || attachments.length > 0)
         lines.push('');
-    // 2. Plan
+    // 2. Recent Activity (first content section — chronological tail of the
+    // session so the top of the recap reflects what happened most recently).
+    if (recentActivity.length > 0) {
+        const RECENT_LIMIT = 7;
+        const tail = recentActivity.slice(-RECENT_LIMIT);
+        lines.push(chalk.bold('Recent Activity') + chalk.gray(` (last ${tail.length} of ${recentActivity.length})`));
+        for (const item of tail) {
+            lines.push('  ' + renderActivityLine(item));
+        }
+        lines.push('');
+    }
+    // 3. Plan
     if (todoItems.length > 0 || exitPlanContent || planFilePath) {
         lines.push(chalk.bold('Plan'));
         if (planFilePath) {
@@ -569,7 +616,8 @@ export function renderSummary(events, cwd) {
         }
         lines.push('');
     }
-    // 3. Subagents
+    // 4. Subagents (describe attempts — grouped with Plan and Errors above the
+    // file/command deltas because they speak to *what was tried*, not the final state).
     if (subagents.length > 0) {
         lines.push(chalk.bold('Subagents') + chalk.gray(` (${subagents.length})`));
         for (const s of subagents) {
@@ -578,14 +626,28 @@ export function renderSummary(events, cwd) {
         }
         lines.push('');
     }
-    // 4. Modified files
+    // 5. Errors (moved up from the bottom: it describes failed attempts, not the
+    // session's final state. Sitting at the bottom previously made early errors
+    // look recent, which confused readers.)
+    if (errors.length > 0) {
+        const first = errors[0];
+        const firstDesc = first.cmd
+            ? `${first.tool} "${first.cmd.slice(0, 60)}"`
+            : first.content
+                ? `${first.tool}: ${first.content.slice(0, 60)}`
+                : first.tool;
+        lines.push(chalk.red(chalk.bold('Errors')) +
+            chalk.gray(`: ${errors.length} failure${errors.length !== 1 ? 's' : ''} — first: ${firstDesc}`));
+        lines.push('');
+    }
+    // 6. Modified files
     if (filesModifiedAbs.size > 0) {
         lines.push(chalk.bold('Modified') + chalk.gray(` (${filesModifiedAbs.size})`));
         const groups = groupByParentDir(filesModifiedAbs, cwd);
         renderFileGroup(lines, groups, modifiedAbsMap);
         lines.push('');
     }
-    // 4b. External edits (files edited outside the project root — typically /tmp)
+    // 6b. External edits (files edited outside the project root — typically /tmp)
     // Filter out plan files (already shown in Plan section)
     const externalNonPlan = [...filesModifiedExternal].filter(p => !(p.includes('.claude/plans/') && p.endsWith('.md')));
     if (externalNonPlan.length > 0) {
@@ -596,7 +658,7 @@ export function renderSummary(events, cwd) {
         lines.push(chalk.gray(`External edits (${externalList.length}): ${display.join(', ')}${more}`));
         lines.push('');
     }
-    // 5. Read files
+    // 7. Read files
     if (filesReadAbs.size > 0) {
         if (filesReadAbs.size <= 5) {
             lines.push(chalk.bold('Read') + chalk.gray(` (${filesReadAbs.size})`));
@@ -608,20 +670,8 @@ export function renderSummary(events, cwd) {
         }
         lines.push('');
     }
-    // 6. Commands
+    // 8. Commands
     renderCommandsSection(cmdList, lines);
-    // 7. Errors
-    if (errors.length > 0) {
-        const first = errors[0];
-        const firstDesc = first.cmd
-            ? `${first.tool} "${first.cmd.slice(0, 60)}"`
-            : first.content
-                ? `${first.tool}: ${first.content.slice(0, 60)}`
-                : first.tool;
-        lines.push(chalk.red(chalk.bold('Errors')) +
-            chalk.gray(`: ${errors.length} failure${errors.length !== 1 ? 's' : ''} — first: ${firstDesc}`));
-        lines.push('');
-    }
     // 9. Final message
     if (lastAssistantMessage) {
         const hasActivity = filesModifiedAbs.size > 0 || filesReadAbs.size > 0 || cmdList.length > 0;
@@ -749,15 +799,10 @@ export function filterEvents(events, opts) {
     const sliced = applyTurnSlice(events, opts);
     return applyRoleFilter(sliced, opts);
 }
-// ── Conversation renderers ────────────────────────────────────────────────────
-/**
- * Build the conversation as a single markdown string: user / assistant
- * messages, inline thinking blocks, tool calls, and errors. Emitted in event
- * order so reasoning sits where it actually occurred relative to the assistant
- * reply.
- */
-export function renderConversationMarkdown(events) {
+export function renderConversationMarkdown(events, opts = {}) {
     const parts = [];
+    const shouldRedact = opts.redact !== false;
+    const sanitize = (text) => shouldRedact ? redactSecrets(text) : text;
     for (const event of events) {
         if (event.type === 'message') {
             if (event.role === 'user') {
@@ -774,7 +819,7 @@ export function renderConversationMarkdown(events) {
         else if (event.type === 'tool_use') {
             const tool = event.tool || 'unknown';
             if (event.command) {
-                parts.push(`### Tool: ${tool}\n\n\`\`\`bash\n${event.command}\n\`\`\``);
+                parts.push(`### Tool: ${tool}\n\n\`\`\`bash\n${sanitize(event.command)}\n\`\`\``);
             }
             else if (event.path) {
                 parts.push(`### Tool: ${tool}\n\n\`${shortenPathTrace(event.path)}\``);
@@ -786,7 +831,8 @@ export function renderConversationMarkdown(events) {
         }
         else if (event.type === 'tool_result') {
             if (event.content) {
-                const body = event.content.length > 2000 ? event.content.slice(0, 2000) + '\n…' : event.content;
+                const truncated = event.content.length > 2000 ? event.content.slice(0, 2000) + '\n…' : event.content;
+                const body = sanitize(truncated);
                 parts.push(`### Tool Result\n\n\`\`\`\n${body}\n\`\`\``);
             }
         }

package/dist/lib/shims.d.ts

@@ -52,8 +52,11 @@ export interface ConflictInfo {
  *        .oauth_token file on Linux (keychain-less sandbox fallback).
  *   v11 — when no default is set or the configured version is not installed,
  *         interactively propose the latest already-installed version.
+ *   v12 — helper calls inside generated shims use the absolute agents-cli
+ *         entrypoint instead of PATH-resolved `agents`.
+ *   v13 — validate agents.yaml version strings before constructing binary paths.
  */
-export declare const SHIM_SCHEMA_VERSION = 11;
+export declare const SHIM_SCHEMA_VERSION = 13;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -206,7 +209,7 @@ export declare function getPathShadowingExecutable(agent: AgentId): string | nul
  * Delete the legacy ~/.agents/shims/<cli> file if it exists, returning whether
  * anything was removed. Pre-split installs put shims under ~/.agents/shims/;
  * the new layout uses ~/.agents-system/shims/. The leftover file causes the
- * repair-prompt loop reported in RUSH-664 — `getPathShadowingExecutable` flags
+ * repair-prompt loop reported in EXAMPLE-664 — `getPathShadowingExecutable` flags
  * it as a shadow but `addShimsToPath` only edits rc files, never the file
  * itself. Removing it ends the loop.
  */

package/dist/lib/shims.js

@@ -11,6 +11,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
 import { getShimsDir, getVersionsDir, getBackupsDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
@@ -175,10 +176,19 @@ async function promptConflictStrategy(conflictInfos) {
  *        .oauth_token file on Linux (keychain-less sandbox fallback).
  *   v11 — when no default is set or the configured version is not installed,
  *         interactively propose the latest already-installed version.
+ *   v12 — helper calls inside generated shims use the absolute agents-cli
+ *         entrypoint instead of PATH-resolved `agents`.
+ *   v13 — validate agents.yaml version strings before constructing binary paths.
  */
-export const SHIM_SCHEMA_VERSION = 11;
+export const SHIM_SCHEMA_VERSION = 13;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function getAgentsBinForGeneratedShim() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'index.js');
+}
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -187,6 +197,7 @@ export function generateShimScript(agent) {
     const agentConfig = AGENTS[agent];
     const cliCommand = agentConfig.cliCommand;
     const configDirName = `.${agent}`;
+    const agentsBin = shellQuote(getAgentsBinForGeneratedShim());
     const managedEnv = agent === 'claude'
         ? `
 # Claude stores OAuth credentials in the macOS keychain. Scope them to the
@@ -217,7 +228,7 @@ export CODEX_HOME="$VERSION_DIR/home/${configDirName}"
 # Recompile rules if any rule/preset source has changed since last sync.
 # Fast-path check (~10-20ms) when nothing changed; full recompile only on
 # actual diff. Non-blocking failure — if the refresh errors, we still launch.
-agents refresh-rules --agent "$AGENT" --agent-version "$VERSION" --quiet 2>/dev/null || true
+"$AGENTS_BIN" refresh-rules --agent "$AGENT" --agent-version "$VERSION" --quiet 2>/dev/null || true
 `
         : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
@@ -228,9 +239,15 @@ agents refresh-rules --agent "$AGENT" --agent-version "$VERSION" --quiet 2>/dev/
 
 AGENTS_SYSTEM_DIR="$HOME/.agents-system"
 AGENTS_USER_DIR="$HOME/.agents"
+AGENTS_BIN=${agentsBin}
 AGENT="${agent}"
 CLI_COMMAND="${cliCommand}"
 
+if [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then
+  echo "agents: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2
+  exit 127
+fi
+
 # Find project agents.yaml walking up from cwd (skip $HOME/.agents-system/agents.yaml)
 find_project_version() {
   local dir="$PWD"
@@ -325,7 +342,7 @@ if [ -z "$VERSION" ]; then
       read -r _ans </dev/tty
       case "$_ans" in
         ""|y|Y)
-          agents use "$AGENT" "$LATEST" >/dev/null 2>&1
+          "$AGENTS_BIN" use "$AGENT" "$LATEST" >/dev/null 2>&1
           VERSION="$LATEST"
           VERSION_SOURCE="default"
           ;;
@@ -345,6 +362,11 @@ if [ -z "$VERSION" ]; then
   fi
 fi
 
+if [[ ! "$VERSION" =~ ^(latest|[A-Za-z0-9._+-]{1,64})$ || "$VERSION" == *..* ]]; then
+  echo "agents: invalid version in agents.yaml for $AGENT: $VERSION. Allowed: latest or [A-Za-z0-9._+-]{1,64}" >&2
+  exit 1
+fi
+
 VERSION_DIR="$AGENTS_USER_DIR/.history/versions/$AGENT/$VERSION"
 BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 
@@ -366,7 +388,7 @@ if [ ! -x "$BINARY" ]; then
     }
 
     # Run install in background with spinner
-    agents add "$AGENT@$VERSION" --yes >/dev/null 2>&1 &
+    "$AGENTS_BIN" add "$AGENT@$VERSION" --yes >/dev/null 2>&1 &
     install_pid=$!
     spin $install_pid
     wait $install_pid
@@ -387,7 +409,7 @@ if [ ! -x "$BINARY" ]; then
         read -r _ans </dev/tty
         case "$_ans" in
           ""|y|Y)
-            agents use "$AGENT" "$LATEST" >/dev/null 2>&1
+            "$AGENTS_BIN" use "$AGENT" "$LATEST" >/dev/null 2>&1
             VERSION="$LATEST"
             VERSION_DIR="$AGENTS_USER_DIR/.history/versions/$AGENT/$VERSION"
             BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
@@ -412,7 +434,7 @@ fi
 # Sync project-scoped resources into version home if a project .agents/ is present
 PROJECT_AGENTS_DIR=$(find_project_agents_dir)
 if [ -n "$PROJECT_AGENTS_DIR" ]; then
-  agents sync --agent "$AGENT" --agent-version "$VERSION" --project-dir "$PROJECT_AGENTS_DIR" --quiet >/dev/null 2>&1
+  "$AGENTS_BIN" sync --agent "$AGENT" --agent-version "$VERSION" --project-dir "$PROJECT_AGENTS_DIR" --quiet >/dev/null 2>&1
 fi
 ${refreshRulesCall}${managedEnv}
 
@@ -1144,7 +1166,7 @@ export function getPathShadowingExecutable(agent) {
  * Delete the legacy ~/.agents/shims/<cli> file if it exists, returning whether
  * anything was removed. Pre-split installs put shims under ~/.agents/shims/;
  * the new layout uses ~/.agents-system/shims/. The leftover file causes the
- * repair-prompt loop reported in RUSH-664 — `getPathShadowingExecutable` flags
+ * repair-prompt loop reported in EXAMPLE-664 — `getPathShadowingExecutable` flags
  * it as a shadow but `addShimsToPath` only edits rc files, never the file
  * itself. Removing it ends the loop.
  */

package/dist/lib/state.d.ts

@@ -13,7 +13,7 @@
  *                          `agents repo push`.
  *  - ~/.agents/.cache/   — regenerable runtime data (shims, packages, helpers
  *                          for daemon/pty, terminals, cloud, drive, browser
- *                          chrome-data, logs, swarmify). Gitignored.
+ *                          chrome-data, logs, companion). Gitignored.
  *
  * Resolution precedence for resources: project > user > system.
  * Every module that needs a path or reads/writes agents.yaml goes through here.
@@ -135,8 +135,8 @@ export declare function getTerminalsDir(): string;
 export declare function getLogsDir(): string;
 /** Path to per-process runtime state (~/.agents/.cache/state/). */
 export declare function getRuntimeStateDir(): string;
-/** Path to swarmify-extension scratch (~/.agents/.cache/swarmify/). */
-export declare function getSwarmifyDir(): string;
+/** Path to companion-extension scratch (~/.agents/.cache/companion/). */
+export declare function getCompanionDir(): string;
 /** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
 export declare function getBrowserRuntimeDir(): string;
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
@@ -195,8 +195,8 @@ export declare function createDefaultMeta(): Meta;
 export declare function readMeta(): Meta;
 /** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export declare function writeMeta(meta: Meta): void;
-/** Shallow-merge updates into agents.yaml and return the new state. */
-export declare function updateMeta(updates: Partial<Meta>): Meta;
+/** Update agents.yaml under lock and return the new state. */
+export declare function updateMeta(updates: Partial<Meta> | ((meta: Meta) => Meta)): Meta;
 /** Derive a filesystem-safe local clone path for a package source URL. */
 export declare function getPackageLocalPath(source: string): string;
 import type { AgentId, ResourceType, VersionResources, ResourcePattern } from './types.js';

package/dist/lib/state.js

@@ -13,7 +13,7 @@
  *                          `agents repo push`.
  *  - ~/.agents/.cache/   — regenerable runtime data (shims, packages, helpers
  *                          for daemon/pty, terminals, cloud, drive, browser
- *                          chrome-data, logs, swarmify). Gitignored.
+ *                          chrome-data, logs, companion). Gitignored.
  *
  * Resolution precedence for resources: project > user > system.
  * Every module that needs a path or reads/writes agents.yaml goes through here.
@@ -22,6 +22,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
+import { ensureLockTarget, atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 import { SEEDED_REGISTRIES } from './types.js';
 const HOME = process.env.HOME ?? os.homedir();
 // ─── Root directories ─────────────────────────────────────────────────────────
@@ -73,7 +74,7 @@ const DRIVE_DIR = path.join(CACHE_DIR, 'drive');
 const TERMINALS_DIR = path.join(CACHE_DIR, 'terminals');
 const LOGS_DIR = path.join(CACHE_DIR, 'logs');
 const RUNTIME_STATE_DIR = path.join(CACHE_DIR, 'state');
-const SWARMIFY_DIR = path.join(CACHE_DIR, 'swarmify');
+const SWARMIFY_DIR = path.join(CACHE_DIR, 'companion');
 const BROWSER_RUNTIME_DIR = path.join(CACHE_DIR, 'browser');
 const HELPERS_DIR = path.join(CACHE_DIR, 'helpers');
 const DAEMON_DIR = path.join(HELPERS_DIR, 'daemon');
@@ -292,8 +293,8 @@ export function getTerminalsDir() { return TERMINALS_DIR; }
 export function getLogsDir() { return LOGS_DIR; }
 /** Path to per-process runtime state (~/.agents/.cache/state/). */
 export function getRuntimeStateDir() { return RUNTIME_STATE_DIR; }
-/** Path to swarmify-extension scratch (~/.agents/.cache/swarmify/). */
-export function getSwarmifyDir() { return SWARMIFY_DIR; }
+/** Path to companion-extension scratch (~/.agents/.cache/companion/). */
+export function getCompanionDir() { return SWARMIFY_DIR; }
 /** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
 export function getBrowserRuntimeDir() { return BROWSER_RUNTIME_DIR; }
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
@@ -411,6 +412,34 @@ export function createDefaultMeta() {
     return {};
 }
 let metaCache = null;
+let metaLockDepth = 0;
+function withMetaLock(fn) {
+    ensureAgentsDir();
+    if (metaLockDepth > 0) {
+        metaLockDepth++;
+        try {
+            return fn();
+        }
+        finally {
+            metaLockDepth--;
+        }
+    }
+    ensureLockTarget(META_FILE, META_HEADER + yaml.stringify(createDefaultMeta()), 0o700);
+    return withFileLock(META_FILE, () => {
+        metaLockDepth = 1;
+        try {
+            return fn();
+        }
+        finally {
+            metaLockDepth = 0;
+        }
+    });
+}
+function writeMetaUnlocked(meta) {
+    const content = META_HEADER + yaml.stringify(meta);
+    atomicWriteFileSync(META_FILE, content);
+    metaCache = null;
+}
 function applyRegistrySeeds(meta) {
     const seeded = new Set(meta.seededPresets || []);
     let changed = false;
@@ -540,17 +569,18 @@ export function readMeta() {
 }
 /** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export function writeMeta(meta) {
-    ensureAgentsDir();
-    const content = META_HEADER + yaml.stringify(meta);
-    fs.writeFileSync(META_FILE, content, 'utf-8');
-    metaCache = null;
+    withMetaLock(() => writeMetaUnlocked(meta));
 }
-/** Shallow-merge updates into agents.yaml and return the new state. */
+/** Update agents.yaml under lock and return the new state. */
 export function updateMeta(updates) {
-    const meta = readMeta();
-    const newMeta = { ...meta, ...updates };
-    writeMeta(newMeta);
-    return newMeta;
+    return withMetaLock(() => {
+        const meta = readMeta();
+        const newMeta = typeof updates === 'function'
+            ? updates(meta)
+            : { ...meta, ...updates };
+        writeMetaUnlocked(newMeta);
+        return newMeta;
+    });
 }
 /** Derive a filesystem-safe local clone path for a package source URL. */
 export function getPackageLocalPath(source) {

package/dist/lib/teams/agents.js

@@ -295,7 +295,7 @@ export function checkCliAvailable(agentType) {
         return [false, `Unknown agent type: ${agentType}`];
     }
     try {
-        const whichPath = execSync(`which ${executable}`, { encoding: 'utf-8' }).trim();
+        const whichPath = execFileSync('which', [executable], { encoding: 'utf-8' }).trim();
         return [true, whichPath];
     }
     catch {