@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/commands.js

@@ -1,10 +1,20 @@
+/**
+ * Slash command management -- discovery, installation, and syncing.
+ *
+ * Commands are markdown files in ~/.agents/commands/ exposed as `/command-name`
+ * shortcuts by agents. This module discovers them, converts between formats
+ * (markdown for Claude/Codex, TOML for Gemini), and installs them into
+ * agent version homes.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { AGENTS, COMMANDS_CAPABLE_AGENTS, ensureCommandsDir } from './agents.js';
 import { markdownToToml } from './convert.js';
-import { getCommandsDir, getProjectAgentsDir } from './state.js';
+import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
+import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
+/** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
 export function parseCommandMetadata(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
@@ -40,6 +50,7 @@ export function parseCommandMetadata(filePath) {
         return null;
     }
 }
+/** Validate command metadata, returning errors and warnings. */
 export function validateCommandMetadata(metadata, commandName) {
     const errors = [];
     const warnings = [];
@@ -61,6 +72,7 @@ export function validateCommandMetadata(metadata, commandName) {
     }
     return { valid: errors.length === 0, errors, warnings };
 }
+/** Discover all command markdown files in a repository's commands/ directory. */
 export function discoverCommands(repoPath) {
     const commands = [];
     const commandsDir = path.join(repoPath, 'commands');
@@ -93,6 +105,7 @@ function extractDescription(content) {
     const firstLine = content.split('\n').find((l) => l.trim() && !l.startsWith('---'));
     return firstLine?.slice(0, 80) || '';
 }
+/** Find the source path for a command in a repository. */
 export function resolveCommandSource(repoPath, commandName) {
     const commandPath = path.join(repoPath, 'commands', `${commandName}.md`);
     if (fs.existsSync(commandPath)) {
@@ -100,6 +113,7 @@ export function resolveCommandSource(repoPath, commandName) {
     }
     return null;
 }
+/** Install a command into an agent's config directory, with optional format conversion. */
 export function installCommand(sourcePath, agentId, commandName, method = 'symlink') {
     // Validate command metadata before installation
     const metadata = parseCommandMetadata(sourcePath);
@@ -149,6 +163,11 @@ export function getVersionCommandsDir(agent, version) {
  * List command names (without extension) installed in a specific version home.
  */
 export function listCommandsInVersionHome(agent, version) {
+    const versionHome = getVersionHomePath(agent, version);
+    const agentDir = path.join(versionHome, `.${agent}`);
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        return listCommandSkillsInVersion(agentDir);
+    }
     const dir = getVersionCommandsDir(agent, version);
     if (!fs.existsSync(dir))
         return [];
@@ -166,6 +185,11 @@ function versionCommandMatches(agent, version, commandName) {
     const sourcePath = path.join(getCommandsDir(), `${commandName}.md`);
     if (!fs.existsSync(sourcePath))
         return false;
+    const versionHome = getVersionHomePath(agent, version);
+    const agentDir = path.join(versionHome, `.${agent}`);
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        return commandSkillMatches(agentDir, commandName, sourcePath);
+    }
     const agentConfig = AGENTS[agent];
     const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
     const installedPath = path.join(getVersionCommandsDir(agent, version), `${commandName}${ext}`);
@@ -220,6 +244,14 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
     if (!fs.existsSync(sourcePath)) {
         return { success: false, error: `Command '${commandName}' not found in central` };
     }
+    const versionHome = getVersionHomePath(agent, version);
+    const agentDir = path.join(versionHome, `.${agent}`);
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        return installCommandSkillToVersion(agentDir, commandName, sourcePath, [
+            getSkillsDir(),
+            ...getEnabledExtraRepos().map((repo) => path.join(repo.dir, 'skills')),
+        ]);
+    }
     const agentConfig = AGENTS[agent];
     const commandsDir = getVersionCommandsDir(agent, version);
     fs.mkdirSync(commandsDir, { recursive: true });
@@ -249,6 +281,11 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
  * Remove a single command from a specific version home.
  */
 export function removeCommandFromVersion(agent, version, commandName) {
+    const versionHome = getVersionHomePath(agent, version);
+    const agentDir = path.join(versionHome, `.${agent}`);
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        return removeCommandSkillFromVersion(agentDir, commandName);
+    }
     const ext = AGENTS[agent].format === 'toml' ? '.toml' : '.md';
     const targetPath = path.join(getVersionCommandsDir(agent, version), `${commandName}${ext}`);
     if (!fs.existsSync(targetPath) && !fs.lstatSync(targetPath, { throwIfNoEntry: false })) {
@@ -281,6 +318,7 @@ export function iterCommandsCapableVersions(filter) {
     }
     return pairs;
 }
+/** Remove a command from an agent's config directory. */
 export function uninstallCommand(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -293,6 +331,7 @@ export function uninstallCommand(agentId, commandName) {
     }
     return false;
 }
+/** List command names installed for an agent in the active version home. */
 export function listInstalledCommands(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -448,7 +487,7 @@ export function installCommandCentrally(sourcePath, commandName) {
             warnings: validation.warnings,
         };
     }
-    const centralDir = getCommandsDir();
+    const centralDir = getUserCommandsDir();
     if (!fs.existsSync(centralDir)) {
         fs.mkdirSync(centralDir, { recursive: true });
     }
@@ -466,17 +505,19 @@ export function installCommandCentrally(sourcePath, commandName) {
     }
 }
 /**
- * List commands from central ~/.agents/commands/ directory.
+ * List commands from user (~/.agents/commands/) and system (~/.agents-system/commands/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export function listCentralCommands() {
-    const centralDir = getCommandsDir();
-    if (!fs.existsSync(centralDir)) {
-        return [];
+    const seen = new Set();
+    for (const dir of [getUserCommandsDir(), getCommandsDir()]) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const f of fs.readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+            seen.add(f.replace('.md', ''));
+        }
     }
-    return fs
-        .readdirSync(centralDir)
-        .filter((f) => f.endsWith('.md'))
-        .map((f) => f.replace('.md', ''));
+    return Array.from(seen);
 }
 /**
  * Get detailed info about a command from central storage.
@@ -496,4 +537,3 @@ export function getCommandInfo(name) {
         content,
     };
 }
-//# sourceMappingURL=commands.js.map

package/dist/lib/convert.d.ts

@@ -1,11 +1,20 @@
+/**
+ * Format conversion between Markdown (Claude/Codex) and TOML (Gemini) command files.
+ *
+ * Handles frontmatter parsing and bidirectional translation so that slash commands
+ * authored in one format can be synced to agents that expect the other.
+ */
+/** Parsed YAML frontmatter from a Markdown command file. */
 export interface MarkdownFrontmatter {
     description?: string;
     [key: string]: unknown;
 }
+/** Extract YAML frontmatter and body from a Markdown string. Returns empty frontmatter if none found. */
 export declare function parseMarkdownFrontmatter(content: string): {
     frontmatter: MarkdownFrontmatter;
     body: string;
 };
+/** Convert a Markdown command file to Gemini's TOML format, translating $ARGUMENTS to {{args}}. */
 export declare function markdownToToml(skillName: string, markdown: string): string;
+/** Convert a Gemini TOML command file back to Markdown format, translating {{args}} to $ARGUMENTS. */
 export declare function tomlToMarkdown(toml: string): string;
-//# sourceMappingURL=convert.d.ts.map

package/dist/lib/convert.js

@@ -1,3 +1,10 @@
+/**
+ * Format conversion between Markdown (Claude/Codex) and TOML (Gemini) command files.
+ *
+ * Handles frontmatter parsing and bidirectional translation so that slash commands
+ * authored in one format can be synced to agents that expect the other.
+ */
+/** Extract YAML frontmatter and body from a Markdown string. Returns empty frontmatter if none found. */
 export function parseMarkdownFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
     if (!match) {
@@ -16,6 +23,7 @@ export function parseMarkdownFrontmatter(content) {
     }
     return { frontmatter, body };
 }
+/** Convert a Markdown command file to Gemini's TOML format, translating $ARGUMENTS to {{args}}. */
 export function markdownToToml(skillName, markdown) {
     const { frontmatter, body } = parseMarkdownFrontmatter(markdown);
     const description = frontmatter.description || `Run ${skillName} command`;
@@ -32,6 +40,7 @@ export function markdownToToml(skillName, markdown) {
     ];
     return lines.join('\n');
 }
+/** Convert a Gemini TOML command file back to Markdown format, translating {{args}} to $ARGUMENTS. */
 export function tomlToMarkdown(toml) {
     const nameMatch = toml.match(/name\s*=\s*"([^"]+)"/);
     const descMatch = toml.match(/description\s*=\s*"([^"]+)"/);
@@ -42,4 +51,3 @@ export function tomlToMarkdown(toml) {
     const lines = ['---', `description: ${description}`, '---', '', prompt, ''];
     return lines.join('\n');
 }
-//# sourceMappingURL=convert.js.map

package/dist/lib/daemon.d.ts

@@ -1,22 +1,42 @@
+/**
+ * Daemon lifecycle management for the routines scheduler.
+ *
+ * The daemon is a long-running process that holds a JobScheduler and
+ * triggers jobs on their cron schedules. It can be managed via launchd
+ * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
+ * log output, reload (SIGHUP), and graceful shutdown are handled here.
+ */
+/** Read the stored daemon PID from disk. Returns null if not present or invalid. */
 export declare function readDaemonPid(): number | null;
+/** Write the daemon PID to the pid file. */
 export declare function writeDaemonPid(pid: number): void;
+/** Remove the daemon PID file. */
 export declare function removeDaemonPid(): void;
+/** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export declare function isDaemonRunning(): boolean;
+/** Append a timestamped log line to the daemon log file (owner-only permissions). */
 export declare function log(level: string, message: string): void;
+/** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 export declare function runDaemon(): Promise<void>;
+/** Generate a macOS launchd plist for auto-starting the daemon. */
 export declare function generateLaunchdPlist(): string;
+/** Generate a Linux systemd user unit for auto-starting the daemon. */
 export declare function generateSystemdUnit(): string;
+/** Start the daemon via launchd, systemd, or as a detached process. */
 export declare function startDaemon(): {
     pid: number | null;
     method: string;
 };
+/** Stop the daemon, unloading it from launchd/systemd if applicable. */
 export declare function stopDaemon(): boolean;
+/** Get current daemon status including running state, PID, and enabled job count. */
 export declare function getDaemonStatus(): {
     running: boolean;
     pid: number | null;
     jobCount: number;
     logPath: string;
 };
+/** Read the daemon log, optionally limited to the last N lines. */
 export declare function readDaemonLog(lines?: number): string;
+/** Send SIGHUP to the daemon to trigger a job reload. */
 export declare function signalDaemonReload(): boolean;
-//# sourceMappingURL=daemon.d.ts.map

package/dist/lib/daemon.js

@@ -1,3 +1,11 @@
+/**
+ * Daemon lifecycle management for the routines scheduler.
+ *
+ * The daemon is a long-running process that holds a JobScheduler and
+ * triggers jobs on their cron schedules. It can be managed via launchd
+ * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
+ * log output, reload (SIGHUP), and graceful shutdown are handled here.
+ */
 import { spawn, execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -7,12 +15,57 @@ import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
 const PID_FILE = 'daemon.pid';
+const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'daemon.log';
-const PLIST_NAME = 'co.swarmify.agents-daemon';
+const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
 function getPidPath() {
     return path.join(getAgentsDir(), PID_FILE);
 }
+function getLockPath() {
+    return path.join(getAgentsDir(), LOCK_FILE);
+}
+/**
+ * Acquire an exclusive start lock. Returns a release function on success,
+ * or null if another process already holds the lock. Uses O_EXCL to
+ * atomically create the file — no TOCTOU window.
+ */
+function acquireStartLock() {
+    const lockPath = getLockPath();
+    try {
+        const fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
+        fs.writeSync(fd, String(process.pid));
+        fs.closeSync(fd);
+        return () => {
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch { /* already removed */ }
+        };
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            // Lock file exists — check if the holder is still alive (stale lock recovery)
+            try {
+                const holderPid = parseInt(fs.readFileSync(lockPath, 'utf-8').trim(), 10);
+                if (!isNaN(holderPid)) {
+                    try {
+                        process.kill(holderPid, 0);
+                        return null; // holder is alive, lock is valid
+                    }
+                    catch {
+                        // holder is dead, remove stale lock and retry once
+                        fs.unlinkSync(lockPath);
+                        return acquireStartLock();
+                    }
+                }
+            }
+            catch { /* can't read lock file — treat as held */ }
+            return null;
+        }
+        throw err;
+    }
+}
 function getLogPath() {
     return path.join(getAgentsDir(), LOG_FILE);
 }
@@ -22,6 +75,7 @@ function getLaunchdPlistPath() {
 function getSystemdUnitPath() {
     return path.join(os.homedir(), '.config', 'systemd', 'user', `${SYSTEMD_UNIT}`);
 }
+/** Read the stored daemon PID from disk. Returns null if not present or invalid. */
 export function readDaemonPid() {
     const pidPath = getPidPath();
     if (!fs.existsSync(pidPath))
@@ -34,15 +88,18 @@ export function readDaemonPid() {
         return null;
     }
 }
+/** Write the daemon PID to the pid file. */
 export function writeDaemonPid(pid) {
     fs.writeFileSync(getPidPath(), String(pid), 'utf-8');
 }
+/** Remove the daemon PID file. */
 export function removeDaemonPid() {
     const pidPath = getPidPath();
     if (fs.existsSync(pidPath)) {
         fs.unlinkSync(pidPath);
     }
 }
+/** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export function isDaemonRunning() {
     const pid = readDaemonPid();
     if (!pid)
@@ -56,11 +113,27 @@ export function isDaemonRunning() {
         return false;
     }
 }
+/** Redact values that look like tokens or credentials in a log message. */
+function redactSecrets(message) {
+    let safe = message;
+    safe = safe.replace(/eyJ[A-Za-z0-9_-]{20,}/g, '[REDACTED_TOKEN]');
+    safe = safe.replace(/Bearer\s+\S+/gi, 'Bearer [REDACTED]');
+    safe = safe.replace(/(sk-[a-zA-Z0-9]{20,})/g, '[REDACTED_KEY]');
+    safe = safe.replace(/(ANTHROPIC_API_KEY|OPENAI_API_KEY|API_KEY|SECRET|TOKEN|PASSWORD)=\S+/gi, '$1=[REDACTED]');
+    return safe;
+}
+/** Append a timestamped log line to the daemon log file (owner-only permissions). */
 export function log(level, message) {
     const timestamp = new Date().toISOString();
-    const line = `[${timestamp}] [${level.toUpperCase()}] ${message}\n`;
-    fs.appendFileSync(getLogPath(), line, 'utf-8');
+    const line = `[${timestamp}] [${level.toUpperCase()}] ${redactSecrets(message)}\n`;
+    const logPath = getLogPath();
+    fs.appendFileSync(logPath, line, 'utf-8');
+    try {
+        fs.chmodSync(logPath, 0o600);
+    }
+    catch { /* best effort */ }
 }
+/** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 export async function runDaemon() {
     writeDaemonPid(process.pid);
     log('INFO', `Daemon started (PID: ${process.pid})`);
@@ -101,6 +174,7 @@ export async function runDaemon() {
     process.on('SIGINT', handleShutdown);
     await new Promise(() => { });
 }
+/** Generate a macOS launchd plist for auto-starting the daemon. */
 export function generateLaunchdPlist() {
     const agentsBin = getAgentsBinPath();
     const logPath = getLogPath();
@@ -132,6 +206,7 @@ export function generateLaunchdPlist() {
 </dict>
 </plist>`;
 }
+/** Generate a Linux systemd user unit for auto-starting the daemon. */
 export function generateSystemdUnit() {
     const agentsBin = getAgentsBinPath();
     return `[Unit]
@@ -156,11 +231,26 @@ function getAgentsBinPath() {
         return 'agents';
     }
 }
+/** Start the daemon via launchd, systemd, or as a detached process. */
 export function startDaemon() {
     if (isDaemonRunning()) {
         const pid = readDaemonPid();
         return { pid, method: 'already-running' };
     }
+    const releaseLock = acquireStartLock();
+    if (!releaseLock) {
+        // Another process is already starting the daemon
+        const pid = waitForPid(3000);
+        return { pid, method: 'already-starting' };
+    }
+    try {
+        return startDaemonLocked();
+    }
+    finally {
+        releaseLock();
+    }
+}
+function startDaemonLocked() {
     const platform = os.platform();
     if (platform === 'darwin') {
         try {
@@ -225,6 +315,7 @@ function waitForPid(timeoutMs) {
     }
     return readDaemonPid();
 }
+/** Stop the daemon, unloading it from launchd/systemd if applicable. */
 export function stopDaemon() {
     const platform = os.platform();
     if (platform === 'darwin') {
@@ -276,6 +367,7 @@ export function stopDaemon() {
     removeDaemonPid();
     return true;
 }
+/** Get current daemon status including running state, PID, and enabled job count. */
 export function getDaemonStatus() {
     const running = isDaemonRunning();
     const pid = readDaemonPid();
@@ -286,6 +378,7 @@ export function getDaemonStatus() {
     catch { /* job listing failed */ }
     return { running, pid, jobCount, logPath: getLogPath() };
 }
+/** Read the daemon log, optionally limited to the last N lines. */
 export function readDaemonLog(lines) {
     const logPath = getLogPath();
     if (!fs.existsSync(logPath))
@@ -296,6 +389,7 @@ export function readDaemonLog(lines) {
     const allLines = content.split('\n');
     return allLines.slice(-lines).join('\n');
 }
+/** Send SIGHUP to the daemon to trigger a job reload. */
 export function signalDaemonReload() {
     const pid = readDaemonPid();
     if (!pid)
@@ -308,4 +402,3 @@ export function signalDaemonReload() {
         return false;
     }
 }
-//# sourceMappingURL=daemon.js.map

package/dist/lib/drive-sync.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Remote drive sync for agent sessions and config.
+ *
+ * Provides rsync-based push/pull between the local ~/.agents/drive/
+ * directory and a remote host, plus attach/detach to swap the active
+ * agent's config directory symlink to the drive directory (for working
+ * with a remote machine's session data locally).
+ */
+/** Persisted drive configuration stored at ~/.agents/drive/config.json. */
 export interface DriveConfig {
     remote: string | null;
     attached: boolean;
@@ -8,13 +17,21 @@ export interface DriveConfig {
     lastPull: string | null;
     lastPush: string | null;
 }
+/** Read drive config from disk, returning defaults if missing. */
 export declare function readDriveConfig(): DriveConfig;
+/** Write drive config to disk. */
 export declare function writeDriveConfig(config: DriveConfig): void;
+/** Set the remote target (user@host) for rsync operations. */
 export declare function setRemote(target: string): void;
+/** Pull drive data from the remote host via rsync. */
 export declare function pull(): Promise<void>;
+/** Push local drive data to the remote host via rsync. */
 export declare function push(): Promise<void>;
+/** Attach drive by swapping the agent's config directory symlink to the drive directory. */
 export declare function attach(): void;
+/** Detach drive by restoring the agent's config directory to its previous symlink target. */
 export declare function detach(): void;
+/** Current drive state for display purposes. */
 export interface DriveStatus {
     remote: string | null;
     attached: boolean;
@@ -24,5 +41,5 @@ export interface DriveStatus {
     configDirTarget: string | null;
     homeFileTargets: Record<string, string | null>;
 }
+/** Gather current drive status by inspecting config, symlinks, and timestamps. */
 export declare function getDriveStatus(): DriveStatus;
-//# sourceMappingURL=drive-sync.d.ts.map

package/dist/lib/drive-sync.js

@@ -1,27 +1,61 @@
+/**
+ * Remote drive sync for agent sessions and config.
+ *
+ * Provides rsync-based push/pull between the local ~/.agents/drive/
+ * directory and a remote host, plus attach/detach to swap the active
+ * agent's config directory symlink to the drive directory (for working
+ * with a remote machine's session data locally).
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { exec } from 'child_process';
+import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { getDriveDir } from './state.js';
 import { AGENTS } from './agents.js';
-const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+// `remote` flows from disk into rsync/ssh argv. Use a strict regex so a
+// tampered ~/.agents/drive/config.json can't sneak shell metacharacters or
+// argv flags (leading -) past the boundary.
+const REMOTE_RE = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+$/;
+function assertValidRemote(remote) {
+    if (!REMOTE_RE.test(remote)) {
+        throw new Error(`Invalid drive remote: ${JSON.stringify(remote)}. Expected: user@host`);
+    }
+}
 const AGENT = 'claude';
 function configPath() {
     return path.join(getDriveDir(), 'config.json');
 }
+/** Read drive config from disk, returning defaults if missing. */
 export function readDriveConfig() {
     const p = configPath();
     if (fs.existsSync(p)) {
         try {
-            return JSON.parse(fs.readFileSync(p, 'utf-8'));
+            const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            // Re-validate `remote` on every read. setRemote validates on write, but
+            // the file can be tampered with out-of-band (a malicious skill, a synced
+            // config from a hostile repo, etc.) and pull/push shell out with the value.
+            if (parsed.remote != null) {
+                assertValidRemote(parsed.remote);
+            }
+            return parsed;
         }
-        catch {
-            // Fall through to default
+        catch (err) {
+            // If the config is malformed or has a tainted remote, fail closed rather
+            // than silently fall back to defaults — a tainted remote that fell back
+            // to null would mask the attack.
+            if (err instanceof SyntaxError) {
+                // Bad JSON: fall through to defaults.
+            }
+            else {
+                throw err;
+            }
         }
     }
     return { remote: null, attached: false, previousTargets: null, lastPull: null, lastPush: null };
 }
+/** Write drive config to disk. */
 export function writeDriveConfig(config) {
     const dir = getDriveDir();
     if (!fs.existsSync(dir)) {
@@ -29,36 +63,43 @@ export function writeDriveConfig(config) {
     }
     fs.writeFileSync(configPath(), JSON.stringify(config, null, 2));
 }
+/** Set the remote target (user@host) for rsync operations. */
 export function setRemote(target) {
-    if (!target.match(/^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+$/)) {
-        throw new Error(`Invalid remote: ${target}. Expected: user@host`);
-    }
+    assertValidRemote(target);
     const config = readDriveConfig();
     config.remote = target;
     writeDriveConfig(config);
 }
+/** Pull drive data from the remote host via rsync. */
 export async function pull() {
     const config = readDriveConfig();
     if (!config.remote)
         throw new Error('No remote configured. Run: agents drive remote <user@host>');
+    assertValidRemote(config.remote);
     const localDir = getDriveDir() + '/';
-    const remote = `${config.remote}:~/.agents/drive/`;
-    await execAsync(`rsync -az --exclude='config.json' ${remote} ${localDir}`);
+    const remoteSpec = `${config.remote}:~/.agents/drive/`;
+    // Argv form: no shell, no interpolation — even a tainted `config.remote` that
+    // somehow got past the regex cannot escape into command syntax.
+    await execFileAsync('rsync', ['-az', '--exclude=config.json', remoteSpec, localDir]);
     config.lastPull = new Date().toISOString();
     writeDriveConfig(config);
 }
+/** Push local drive data to the remote host via rsync. */
 export async function push() {
     const config = readDriveConfig();
     if (!config.remote)
         throw new Error('No remote configured. Run: agents drive remote <user@host>');
+    assertValidRemote(config.remote);
     const localDir = getDriveDir() + '/';
-    const remote = `${config.remote}:~/.agents/drive/`;
-    // Ensure remote directory exists
-    await execAsync(`ssh ${config.remote} 'mkdir -p ~/.agents/drive'`);
-    await execAsync(`rsync -az --exclude='config.json' ${localDir} ${remote}`);
+    const remoteSpec = `${config.remote}:~/.agents/drive/`;
+    // Ensure remote directory exists. ssh's command argument is one positional
+    // string; we hand it as a single argv element so no local shell sees it.
+    await execFileAsync('ssh', [config.remote, 'mkdir -p ~/.agents/drive']);
+    await execFileAsync('rsync', ['-az', '--exclude=config.json', localDir, remoteSpec]);
     config.lastPush = new Date().toISOString();
     writeDriveConfig(config);
 }
+/** Attach drive by swapping the agent's config directory symlink to the drive directory. */
 export function attach() {
     const config = readDriveConfig();
     if (config.attached)
@@ -123,6 +164,7 @@ export function attach() {
     config.attached = true;
     writeDriveConfig(config);
 }
+/** Detach drive by restoring the agent's config directory to its previous symlink target. */
 export function detach() {
     const config = readDriveConfig();
     if (!config.attached)
@@ -151,6 +193,7 @@ export function detach() {
     config.previousTargets = null;
     writeDriveConfig(config);
 }
+/** Gather current drive status by inspecting config, symlinks, and timestamps. */
 export function getDriveStatus() {
     const config = readDriveConfig();
     const home = os.homedir();
@@ -190,4 +233,3 @@ export function getDriveStatus() {
         homeFileTargets,
     };
 }
-//# sourceMappingURL=drive-sync.js.map