@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/permissions.js

@@ -1,17 +1,27 @@
+/**
+ * Permission management for AI coding agents.
+ *
+ * Provides a canonical permission format (PermissionSet with allow/deny rules)
+ * and converters to/from each agent's native format (Claude settings.json,
+ * OpenCode opencode.jsonc, Codex config.toml + .rules). Handles discovery,
+ * installation, removal, and merging of permission groups stored in
+ * ~/.agents/permissions/groups/.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
-import { getPermissionsDir, ensureAgentsDir } from './state.js';
+import { getPermissionsDir, getUserPermissionsDir, ensureAgentsDir } from './state.js';
+import { safeJoin } from './paths.js';
 const HOME = os.homedir();
-// Agents that support permissions
+/** Agents that support the permissions subsystem. */
 export const PERMISSIONS_CAPABLE_AGENTS = ['claude', 'codex', 'opencode'];
-// Codex .rules file name for deny permissions
+/** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export const CODEX_RULES_FILENAME = 'agents-deny.rules';
 /**
  * Convert canonical deny rules to Codex Starlark .rules format.
- * E.g. "Bash(git reset:*)" → prefix_rule(pattern=["git", "reset"], decision="forbidden")
+ * E.g. "Bash(git reset:*)" -> prefix_rule(pattern=["git", "reset"], decision="forbidden")
  */
 export function convertDenyToCodexRules(deny) {
     const rules = [];
@@ -24,7 +34,7 @@ export function convertDenyToCodexRules(deny) {
         if (!command)
             continue;
         const parts = command.split(/\s+/);
-        const patternStr = parts.map(p => `"${p}"`).join(', ');
+        const patternStr = parts.map(p => JSON.stringify(p)).join(', ');
         rules.push(`prefix_rule(\n    pattern = [${patternStr}],\n    decision = "forbidden",\n)`);
     }
     if (rules.length === 0)
@@ -35,7 +45,7 @@ export function convertDenyToCodexRules(deny) {
  * Ensure central permissions directory exists.
  */
 export function ensurePermissionsDir() {
-    const dir = getPermissionsDir();
+    const dir = getUserPermissionsDir();
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
@@ -108,38 +118,37 @@ export function discoverPermissionsFromRepo(repoPath) {
  * Returns groups with their rule counts.
  */
 export function discoverPermissionGroups() {
-    const groupsDir = path.join(getPermissionsDir(), 'groups');
-    if (!fs.existsSync(groupsDir)) {
-        return [];
-    }
+    const seen = new Set();
     const groups = [];
-    try {
-        const entries = fs.readdirSync(groupsDir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isFile())
-                continue;
-            if (!entry.name.endsWith('.yml') && !entry.name.endsWith('.yaml'))
-                continue;
-            const filePath = path.join(groupsDir, entry.name);
-            const name = entry.name.replace(/\.(yaml|yml)$/, '');
-            // Count rules in this group
-            let ruleCount = 0;
-            try {
-                const content = fs.readFileSync(filePath, 'utf-8');
-                // Count lines that look like permission entries (start with - " after optional whitespace)
-                const matches = content.match(/^\s*-\s*"/gm);
-                ruleCount = matches ? matches.length : 0;
-            }
-            catch {
-                // Skip files we can't read
+    // Search user dir first, then system (user wins on name collision)
+    for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        const groupsDir = path.join(baseDir, 'groups');
+        if (!fs.existsSync(groupsDir))
+            continue;
+        try {
+            const entries = fs.readdirSync(groupsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.endsWith('.yml') && !entry.name.endsWith('.yaml'))
+                    continue;
+                const name = entry.name.replace(/\.(yaml|yml)$/, '');
+                if (seen.has(name))
+                    continue;
+                seen.add(name);
+                const filePath = path.join(groupsDir, entry.name);
+                let ruleCount = 0;
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8');
+                    const matches = content.match(/^\s*-\s*"/gm);
+                    ruleCount = matches ? matches.length : 0;
+                }
+                catch { /* Skip files we can't read */ }
+                groups.push({ name, ruleCount, path: filePath });
             }
-            groups.push({ name, ruleCount, path: filePath });
         }
+        catch { /* Skip inaccessible directory */ }
     }
-    catch {
-        // Skip inaccessible directory
-    }
-    // Sort by name (which sorts by numeric prefix)
     return groups.sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
@@ -149,6 +158,45 @@ export function getTotalPermissionRuleCount() {
     const groups = discoverPermissionGroups();
     return groups.reduce((sum, g) => sum + g.ruleCount, 0);
 }
+/** Env var that selects which set recipe to apply at sync time. */
+export const PERMISSION_SET_ENV_VAR = 'AGENTS_PERMISSION_SET';
+/**
+ * Read a permission set recipe by name from ~/.agents/permissions/sets/.
+ * Returns null if the recipe file is missing or malformed.
+ */
+export function readPermissionSetRecipe(name) {
+    const setsDir = path.join(getPermissionsDir(), 'sets');
+    for (const ext of ['.yaml', '.yml']) {
+        const filePath = safeJoin(setsDir, name + ext);
+        if (!fs.existsSync(filePath))
+            continue;
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const parsed = yaml.parse(content);
+            if (!parsed || typeof parsed !== 'object')
+                return null;
+            if (!Array.isArray(parsed.includes))
+                return null;
+            return {
+                name: parsed.name || name,
+                description: parsed.description,
+                includes: parsed.includes.filter((v) => typeof v === 'string'),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Return the active permission set name from AGENTS_PERMISSION_SET env var,
+ * or null if unset. Caller decides the default behavior when null.
+ */
+export function getActivePermissionSetName() {
+    const v = process.env[PERMISSION_SET_ENV_VAR];
+    return v && v.trim() ? v.trim() : null;
+}
 /**
  * Build a PermissionSet from selected groups.
  * Concatenates allow/deny rules from each group.
@@ -157,18 +205,25 @@ export function getTotalPermissionRuleCount() {
  * permission files often contain unescaped nested quotes that break YAML.
  */
 export function buildPermissionsFromGroups(groupNames) {
-    const groupsDir = path.join(getPermissionsDir(), 'groups');
     const allAllow = [];
     const allDeny = [];
     for (const groupName of groupNames) {
-        // Try both .yaml and .yml extensions
-        let filePath = path.join(groupsDir, `${groupName}.yaml`);
-        if (!fs.existsSync(filePath)) {
-            filePath = path.join(groupsDir, `${groupName}.yml`);
+        // Search user dir first, then system dir
+        let filePath = null;
+        for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+            const groupsDir = path.join(baseDir, 'groups');
+            for (const ext of ['.yaml', '.yml']) {
+                const candidate = safeJoin(groupsDir, `${groupName}${ext}`);
+                if (fs.existsSync(candidate)) {
+                    filePath = candidate;
+                    break;
+                }
+            }
+            if (filePath)
+                break;
         }
-        if (!fs.existsSync(filePath)) {
+        if (!filePath)
             continue;
-        }
         try {
             const content = fs.readFileSync(filePath, 'utf-8');
             // Extract rules using line-by-line regex (more robust than YAML parsing)
@@ -241,7 +296,7 @@ export function listInstalledPermissions() {
 export function getPermissionSet(name) {
     const dir = getPermissionsDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(dir, name + ext);
+        const filePath = safeJoin(dir, name + ext);
         if (fs.existsSync(filePath)) {
             const set = parsePermissionSet(filePath);
             if (set) {
@@ -260,7 +315,7 @@ export function installPermissionSet(sourcePath, name) {
     if (!set) {
         return { success: false, error: 'Invalid permission file' };
     }
-    const targetPath = path.join(getPermissionsDir(), name + '.yml');
+    const targetPath = safeJoin(getPermissionsDir(), name + '.yml');
     try {
         fs.copyFileSync(sourcePath, targetPath);
         return { success: true };
@@ -275,7 +330,7 @@ export function installPermissionSet(sourcePath, name) {
 export function removePermissionSet(name) {
     const dir = getPermissionsDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(dir, name + ext);
+        const filePath = safeJoin(dir, name + ext);
         if (fs.existsSync(filePath)) {
             try {
                 fs.unlinkSync(filePath);
@@ -316,6 +371,8 @@ function parseCanonicalPattern(permission) {
         return null;
     return { tool: match[1].toLowerCase(), pattern: match[2] };
 }
+/** Blanket-Bash canonical forms that mean "allow any bash command". */
+const BLANKET_BASH_FORMS = new Set(['Bash', 'Bash(*)', 'Bash(**)']);
 /**
  * Convert canonical permission set to OpenCode format.
  * OpenCode uses: { permission: { bash: { "git *": "allow", "rm *": "deny" } } }
@@ -324,6 +381,12 @@ export function convertToOpenCodeFormat(set) {
     const bashPermissions = {};
     // Process allow list
     for (const perm of set.allow) {
+        if (BLANKET_BASH_FORMS.has(perm)) {
+            // Bare "Bash" has no parens so parseCanonicalPattern returns null;
+            // normalize all three blanket forms to "*".
+            bashPermissions['*'] = 'allow';
+            continue;
+        }
         const parsed = parseCanonicalPattern(perm);
         if (parsed && parsed.tool === 'bash') {
             bashPermissions[parsed.pattern] = 'allow';
@@ -350,10 +413,16 @@ export function convertToOpenCodeFormat(set) {
  */
 export function convertToCodexFormat(set, cwd) {
     const result = {};
-    // Check for broad bash permissions -> suggest full-auto
+    // Check for broad bash permissions -> suggest full-auto.
+    // Treat the bare blanket form "Bash" the same as "Bash(*)" / "Bash(**)";
+    // parseCanonicalPattern requires parens so "Bash" alone wouldn't match
+    // otherwise — the difference determines whether a pod runs unattended
+    // (approval_policy: 'never') or stalls on interactive approvals.
     const hasBroadBash = set.allow.some((p) => {
+        if (BLANKET_BASH_FORMS.has(p))
+            return true;
         const parsed = parseCanonicalPattern(p);
-        return parsed && parsed.tool === 'bash' && (parsed.pattern === '*' || parsed.pattern === '**');
+        return parsed !== null && parsed.tool === 'bash' && (parsed.pattern === '*' || parsed.pattern === '**');
     });
     if (hasBroadBash) {
         result.approval_policy = 'never';
@@ -946,7 +1015,7 @@ export function exportPermissionsFromPath(filePath) {
  */
 export function savePermissionSet(set) {
     ensurePermissionsDir();
-    const filePath = path.join(getPermissionsDir(), set.name + '.yml');
+    const filePath = safeJoin(getUserPermissionsDir(), set.name + '.yml');
     try {
         const content = yaml.stringify({
             name: set.name,
@@ -961,6 +1030,7 @@ export function savePermissionSet(set) {
         return { success: false, error: err.message };
     }
 }
+/** Name used for the default permission set in central storage. */
 const DEFAULT_PERMISSION_SET_NAME = 'default';
 /**
  * Get the default permission set from central storage.
@@ -1019,4 +1089,3 @@ export function saveDefaultPermissionSet(set) {
     set.name = DEFAULT_PERMISSION_SET_NAME;
     return savePermissionSet(set);
 }
-//# sourceMappingURL=permissions.js.map

package/dist/lib/picker.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Interactive fuzzy-filter picker built on @inquirer/core.
+ *
+ * Provides a searchable, paginated list UI with optional preview pane
+ * for selecting items in the terminal. Used by session picker, command
+ * picker, and other interactive selection flows.
+ */
+/** Configuration for the interactive picker prompt. */
 export interface PickerConfig<T> {
     message: string;
     items: T[];
@@ -10,8 +18,9 @@ export interface PickerConfig<T> {
     emptyMessage?: string;
     enterHint?: string;
 }
+/** The result returned when the user selects an item. */
 export interface PickedItem<T> {
     item: T;
 }
+/** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export declare function itemPicker<T>(config: PickerConfig<T>): Promise<PickedItem<T> | null>;
-//# sourceMappingURL=picker.d.ts.map

package/dist/lib/picker.js

@@ -1,5 +1,20 @@
+/**
+ * Interactive fuzzy-filter picker built on @inquirer/core.
+ *
+ * Provides a searchable, paginated list UI with optional preview pane
+ * for selecting items in the terminal. Used by session picker, command
+ * picker, and other interactive selection flows.
+ */
+/**
+ * Custom inquirer prompt for searchable, scrollable selection lists.
+ *
+ * Extends @inquirer/core to support type-ahead filtering, column-aligned
+ * display, and keyboard navigation. Used by sessions, teams, and other
+ * interactive pickers throughout the CLI.
+ */
 import { createPrompt, useState, useKeypress, useEffect, useMemo, usePagination, usePrefix, makeTheme, isEnterKey, isUpKey, isDownKey, isSpaceKey, Separator, } from '@inquirer/core';
 import chalk from 'chalk';
+/** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export function itemPicker(config) {
     const prompt = createPrompt((cfg, done) => {
         const theme = makeTheme({});
@@ -92,4 +107,3 @@ export function itemPicker(config) {
     });
     return prompt(config);
 }
-//# sourceMappingURL=picker.js.map

package/dist/lib/plugins.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Plugin discovery, validation, and syncing.
+ *
+ * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks, and
+ * scripts under a single manifest (plugin.yaml). This module discovers plugins,
+ * validates their manifests, and syncs their contents into agent version homes.
+ */
 import type { AgentId, DiscoveredPlugin, PluginManifest } from './types.js';
 /**
  * Discover all plugins in ~/.agents/plugins/.
@@ -70,4 +77,3 @@ export declare function removePluginFromVersion(pluginName: string, pluginRoot:
  * where the plugin no longer exists in ~/.agents/plugins/.
  */
 export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePluginNames: Set<string>): string[];
-//# sourceMappingURL=plugins.d.ts.map

package/dist/lib/plugins.js

@@ -1,3 +1,10 @@
+/**
+ * Plugin discovery, validation, and syncing.
+ *
+ * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks, and
+ * scripts under a single manifest (plugin.yaml). This module discovers plugins,
+ * validates their manifests, and syncs their contents into agent version homes.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getPluginsDir } from './state.js';
@@ -46,6 +53,9 @@ export function loadPluginManifest(pluginRoot) {
         const parsed = JSON.parse(content);
         if (!parsed.name || !parsed.version)
             return null;
+        if (/[/\\]/.test(parsed.name) || parsed.name.includes('..') || parsed.name.includes('\0')) {
+            return null;
+        }
         return parsed;
     }
     catch {
@@ -546,4 +556,3 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames)
     }
     return removed;
 }
-//# sourceMappingURL=plugins.js.map

package/dist/lib/profiles-presets.d.ts

@@ -1,4 +1,11 @@
+/**
+ * Built-in profile presets for popular model providers.
+ *
+ * Each preset bundles a host CLI, API base URL, default model, and provider
+ * name so users can `agents profiles add kimi` without manual configuration.
+ */
 import type { AgentId } from './types.js';
+/** A pre-configured profile template for a model provider. */
 export interface Preset {
     name: string;
     description: string;
@@ -9,7 +16,9 @@ export interface Preset {
     signupUrl?: string;
 }
 export declare const PRESETS: Preset[];
+/** Look up a preset by name (case-sensitive). */
 export declare function getPreset(name: string): Preset | undefined;
+/** Return a copy of all available presets. */
 export declare function listPresets(): Preset[];
+/** Return the unique set of provider names across all presets. */
 export declare function listProviders(): string[];
-//# sourceMappingURL=profiles-presets.d.ts.map

package/dist/lib/profiles-presets.js

@@ -1,3 +1,9 @@
+/**
+ * Built-in profile presets for popular model providers.
+ *
+ * Each preset bundles a host CLI, API base URL, default model, and provider
+ * name so users can `agents profiles add kimi` without manual configuration.
+ */
 // Model IDs verified against openrouter.ai/api/v1/models on 2026-04-20.
 // Presets target the top-ranked open-source model per provider based on
 // SWE-bench Verified, LiveCodeBench, HumanEval, and Chatbot Arena rankings.
@@ -83,13 +89,15 @@ export const PRESETS = [
         },
     },
 ];
+/** Look up a preset by name (case-sensitive). */
 export function getPreset(name) {
     return PRESETS.find((p) => p.name === name);
 }
+/** Return a copy of all available presets. */
 export function listPresets() {
     return [...PRESETS];
 }
+/** Return the unique set of provider names across all presets. */
 export function listProviders() {
     return [...new Set(PRESETS.map((p) => p.provider))];
 }
-//# sourceMappingURL=profiles-presets.js.map

package/dist/lib/profiles.d.ts

@@ -1,5 +1,13 @@
+/**
+ * Profile management -- named bundles of (host CLI, endpoint, model, auth).
+ *
+ * Profiles let users run agents against alternative providers (OpenRouter,
+ * custom endpoints) without reconfiguring the agent CLI itself. Stored as
+ * YAML files under ~/.agents/profiles/.
+ */
 import type { AgentId } from './types.js';
 import { type Preset } from './profiles-presets.js';
+/** A named profile binding an agent host, env vars, and optional keychain auth. */
 export interface Profile {
     name: string;
     host: {
@@ -15,21 +23,47 @@ export interface Profile {
     preset?: string;
     provider?: string;
 }
+/** Get the directory where profile YAML files are stored. */
 export declare function getProfilesDir(): string;
+/** Validate a profile name against the allowed pattern. Throws on invalid input. */
 export declare function validateProfileName(name: string): void;
+/** Check whether a profile YAML file exists on disk. */
 export declare function profileExists(name: string): boolean;
+/** Read and parse a profile from disk. Throws if not found or malformed. */
 export declare function readProfile(name: string): Profile;
+/** Write a profile to disk atomically (write-to-tmp then rename). */
 export declare function writeProfile(profile: Profile): void;
+/** Delete a profile from disk. Returns false if it did not exist. */
 export declare function deleteProfile(name: string): boolean;
+/** List all valid profiles, sorted by name. Malformed files are silently skipped. */
 export declare function listProfiles(): Profile[];
+/**
+ * Build a profile from a preset. The keychain item is shared across all
+ * profiles that point at the same provider, so adding kimi + deepseek prompts
+ * for the OpenRouter key exactly once.
+ */
 export declare function profileFromPreset(profileName: string, preset: Preset, version?: string): Profile;
+/**
+ * Resolve a profile into the env block that should be injected into the
+ * spawned agent process. Reads the token from keychain at exec time so the
+ * profile YAML never holds secrets.
+ */
 export declare function resolveProfileEnv(profile: Profile): Record<string, string>;
+/** Resolved profile data ready for spawning an agent process. */
 export interface ResolvedProfileRun {
     agent: AgentId;
     version?: string;
     env: Record<string, string>;
     profileName: string;
 }
+/**
+ * Resolve a name into (agent, version, env). Throws if the name is not a
+ * profile. Callers are expected to try agent-id resolution first and fall
+ * back to this when that fails, so we don't need a "isProfile" probe.
+ */
 export declare function resolveProfileForRun(name: string): ResolvedProfileRun;
+/**
+ * Look up the preset a profile was created from, if any. Used by
+ * `profiles view` to show upstream metadata like signup URLs.
+ */
 export declare function getPresetForProfile(profile: Profile): Preset | undefined;
-//# sourceMappingURL=profiles.d.ts.map

package/dist/lib/profiles.js

@@ -1,24 +1,35 @@
+/**
+ * Profile management -- named bundles of (host CLI, endpoint, model, auth).
+ *
+ * Profiles let users run agents against alternative providers (OpenRouter,
+ * custom endpoints) without reconfiguring the agent CLI itself. Stored as
+ * YAML files under ~/.agents/profiles/.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getAgentsDir } from './state.js';
-import { getKeychainToken, keychainItemName } from './profiles-keychain.js';
+import { getUserAgentsDir } from './state.js';
+import { getKeychainToken, keychainItemName } from './secrets/profiles.js';
 import { getPreset } from './profiles-presets.js';
 const PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
+/** Get the directory where profile YAML files are stored. */
 export function getProfilesDir() {
-    return path.join(getAgentsDir(), 'profiles');
+    return path.join(getUserAgentsDir(), 'profiles');
 }
 function profilePath(name) {
     return path.join(getProfilesDir(), `${name}.yml`);
 }
+/** Validate a profile name against the allowed pattern. Throws on invalid input. */
 export function validateProfileName(name) {
     if (!PROFILE_NAME_PATTERN.test(name)) {
         throw new Error(`Invalid profile name '${name}'. Use letters, digits, dash, underscore (max 48 chars).`);
     }
 }
+/** Check whether a profile YAML file exists on disk. */
 export function profileExists(name) {
     return fs.existsSync(profilePath(name));
 }
+/** Read and parse a profile from disk. Throws if not found or malformed. */
 export function readProfile(name) {
     validateProfileName(name);
     const file = profilePath(name);
@@ -40,6 +51,7 @@ export function readProfile(name) {
     }
     return parsed;
 }
+/** Write a profile to disk atomically (write-to-tmp then rename). */
 export function writeProfile(profile) {
     validateProfileName(profile.name);
     const dir = getProfilesDir();
@@ -50,6 +62,7 @@ export function writeProfile(profile) {
     fs.writeFileSync(tmp, body, 'utf-8');
     fs.renameSync(tmp, file);
 }
+/** Delete a profile from disk. Returns false if it did not exist. */
 export function deleteProfile(name) {
     validateProfileName(name);
     const file = profilePath(name);
@@ -58,6 +71,7 @@ export function deleteProfile(name) {
     fs.unlinkSync(file);
     return true;
 }
+/** List all valid profiles, sorted by name. Malformed files are silently skipped. */
 export function listProfiles() {
     const dir = getProfilesDir();
     if (!fs.existsSync(dir))
@@ -75,9 +89,11 @@ export function listProfiles() {
     }
     return profiles.sort((a, b) => a.name.localeCompare(b.name));
 }
-// Build a profile from a preset. The keychain item is shared across all
-// profiles that point at the same provider, so adding kimi + deepseek prompts
-// for the OpenRouter key exactly once.
+/**
+ * Build a profile from a preset. The keychain item is shared across all
+ * profiles that point at the same provider, so adding kimi + deepseek prompts
+ * for the OpenRouter key exactly once.
+ */
 export function profileFromPreset(profileName, preset, version) {
     return {
         name: profileName,
@@ -92,9 +108,11 @@ export function profileFromPreset(profileName, preset, version) {
         provider: preset.provider,
     };
 }
-// Resolve a profile into the env block that should be injected into the
-// spawned agent process. Reads the token from keychain at exec time so the
-// profile YAML never holds secrets.
+/**
+ * Resolve a profile into the env block that should be injected into the
+ * spawned agent process. Reads the token from keychain at exec time so the
+ * profile YAML never holds secrets.
+ */
 export function resolveProfileEnv(profile) {
     const env = { ...profile.env };
     if (profile.auth) {
@@ -103,9 +121,11 @@ export function resolveProfileEnv(profile) {
     }
     return env;
 }
-// Resolve a name into (agent, version, env). Throws if the name is not a
-// profile. Callers are expected to try agent-id resolution first and fall
-// back to this when that fails, so we don't need a "isProfile" probe.
+/**
+ * Resolve a name into (agent, version, env). Throws if the name is not a
+ * profile. Callers are expected to try agent-id resolution first and fall
+ * back to this when that fails, so we don't need a "isProfile" probe.
+ */
 export function resolveProfileForRun(name) {
     const profile = readProfile(name);
     return {
@@ -115,9 +135,10 @@ export function resolveProfileForRun(name) {
         profileName: profile.name,
     };
 }
-// Look up the preset a profile was created from, if any. Used by
-// `profiles view` to show upstream metadata like signup URLs.
+/**
+ * Look up the preset a profile was created from, if any. Used by
+ * `profiles view` to show upstream metadata like signup URLs.
+ */
 export function getPresetForProfile(profile) {
     return profile.preset ? getPreset(profile.preset) : undefined;
 }
-//# sourceMappingURL=profiles.js.map

package/dist/lib/pty-client.d.ts

@@ -4,6 +4,7 @@
  * Thin client that connects to the PTY sidecar server over unix socket.
  * Each call opens a connection, sends a JSON request, reads the JSON response, and closes.
  */
+/** JSON response envelope from the PTY server. */
 export interface PtyResponse {
     ok: boolean;
     error?: string;
@@ -19,4 +20,3 @@ export declare function ptyRequest(action: string, id?: string, params?: Record<
  * Handles: \n \r \t \e \xHH \\
  */
 export declare function unescapeInput(input: string): string;
-//# sourceMappingURL=pty-client.d.ts.map

package/dist/lib/pty-client.js

@@ -178,4 +178,3 @@ export function unescapeInput(input) {
         }
     });
 }
-//# sourceMappingURL=pty-client.js.map

package/dist/lib/pty-server.d.ts

@@ -6,11 +6,25 @@
  * across multiple CLI invocations. Each session holds a real PTY (via node-pty)
  * and a headless terminal emulator (via @xterm/headless) for screen rendering.
  *
- * Protocol: newline-delimited JSON over ~/.agents/pty.sock
+ * Protocol: newline-delimited JSON over ~/.agents-system/pty.sock
  */
+/**
+ * Capture a stable identifier for a process at the moment it was started.
+ * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
+ * still occupies the PID we observed at spawn time.
+ *
+ * Linux:  field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
+ * macOS:  output of `ps -o lstart= -p <pid>` (start time in human format).
+ * Returns null on any error so callers can skip the guard rather than crash.
+ */
+export declare function captureProcessStartTime(pid: number): string | null;
+/** Get the unix socket path for the PTY server. */
 export declare function getSocketPath(): string;
+/** Get the path to the PTY server PID file. */
 export declare function getPtyPidPath(): string;
+/** Get the path to the PTY server log file. */
 export declare function getPtyLogPath(): string;
+/** Check if the PTY server process is alive by probing the stored PID. */
 export declare function isPtyServerRunning(): boolean;
+/** Start the PTY sidecar server, listening on the unix socket for JSON requests. */
 export declare function runPtyServer(): Promise<void>;
-//# sourceMappingURL=pty-server.d.ts.map