@proletariat/cli 0.3.9 → 0.3.11

package/dist/lib/pmo/storage/roadmaps.js

@@ -0,0 +1,301 @@
+/**
+ * Roadmap operations for PMO.
+ * Roadmaps are curated collections of projects for documentation/visualization.
+ */
+import { PMO_TABLES } from '../schema.js';
+import { PMOError } from '../types.js';
+const T = PMO_TABLES;
+export class RoadmapStorage {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    // ===== Roadmap CRUD =====
+    /**
+     * Create a new roadmap.
+     */
+    async createRoadmap(roadmap) {
+        const id = roadmap.id || `roadmap-${Date.now()}`;
+        const now = Date.now();
+        // If setting as default, unset other defaults first
+        if (roadmap.isDefault) {
+            this.ctx.db.prepare(`UPDATE ${T.roadmaps} SET is_default = 0`).run();
+        }
+        this.ctx.db.prepare(`
+      INSERT INTO ${T.roadmaps} (id, name, description, is_default, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(id, roadmap.name, roadmap.description || null, roadmap.isDefault ? 1 : 0, now, now);
+        return {
+            id,
+            name: roadmap.name,
+            description: roadmap.description,
+            isDefault: roadmap.isDefault || false,
+            createdAt: new Date(now),
+            updatedAt: new Date(now),
+        };
+    }
+    /**
+     * Get a roadmap by ID.
+     */
+    async getRoadmap(id) {
+        const row = this.ctx.db.prepare(`
+      SELECT * FROM ${T.roadmaps} WHERE id = ?
+    `).get(id);
+        if (!row)
+            return null;
+        return this.rowToRoadmap(row);
+    }
+    /**
+     * List roadmaps with optional filters.
+     */
+    async listRoadmaps(filter) {
+        let query = `SELECT * FROM ${T.roadmaps} WHERE 1=1`;
+        const params = [];
+        if (filter?.search) {
+            query += ' AND (name LIKE ? OR description LIKE ?)';
+            params.push(`%${filter.search}%`, `%${filter.search}%`);
+        }
+        if (filter?.isDefault !== undefined) {
+            query += ' AND is_default = ?';
+            params.push(filter.isDefault ? 1 : 0);
+        }
+        query += ' ORDER BY is_default DESC, name ASC';
+        const rows = this.ctx.db.prepare(query).all(...params);
+        return rows.map(row => this.rowToRoadmap(row));
+    }
+    /**
+     * Update a roadmap.
+     */
+    async updateRoadmap(id, changes) {
+        const roadmap = await this.getRoadmap(id);
+        if (!roadmap) {
+            throw new PMOError('NOT_FOUND', `Roadmap not found: ${id}`);
+        }
+        const updates = [];
+        const params = [];
+        if (changes.name !== undefined) {
+            updates.push('name = ?');
+            params.push(changes.name);
+        }
+        if (changes.description !== undefined) {
+            updates.push('description = ?');
+            params.push(changes.description || null);
+        }
+        if (changes.isDefault !== undefined) {
+            // If setting as default, unset other defaults first
+            if (changes.isDefault) {
+                this.ctx.db.prepare(`UPDATE ${T.roadmaps} SET is_default = 0`).run();
+            }
+            updates.push('is_default = ?');
+            params.push(changes.isDefault ? 1 : 0);
+        }
+        if (updates.length > 0) {
+            updates.push('updated_at = ?');
+            params.push(Date.now());
+            params.push(id);
+            this.ctx.db.prepare(`UPDATE ${T.roadmaps} SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+        }
+        return (await this.getRoadmap(id));
+    }
+    /**
+     * Delete a roadmap.
+     */
+    async deleteRoadmap(id) {
+        const roadmap = await this.getRoadmap(id);
+        if (!roadmap) {
+            throw new PMOError('NOT_FOUND', `Roadmap not found: ${id}`);
+        }
+        // Delete roadmap (cascades to roadmap_projects)
+        this.ctx.db.prepare(`DELETE FROM ${T.roadmaps} WHERE id = ?`).run(id);
+    }
+    /**
+     * Get the default roadmap.
+     */
+    async getDefaultRoadmap() {
+        const row = this.ctx.db.prepare(`
+      SELECT * FROM ${T.roadmaps} WHERE is_default = 1 LIMIT 1
+    `).get();
+        if (!row)
+            return null;
+        return this.rowToRoadmap(row);
+    }
+    /**
+     * Set a roadmap as the default.
+     */
+    async setDefaultRoadmap(id) {
+        return this.updateRoadmap(id, { isDefault: true });
+    }
+    // ===== Roadmap Projects =====
+    /**
+     * List projects in a roadmap, ordered by position.
+     */
+    async listRoadmapProjects(roadmapId) {
+        const rows = this.ctx.db.prepare(`
+      SELECT p.* FROM ${T.projects} p
+      JOIN ${T.roadmap_projects} rp ON p.id = rp.project_id
+      WHERE rp.roadmap_id = ?
+      ORDER BY rp.position ASC
+    `).all(roadmapId);
+        return rows.map(row => this.rowToProject(row));
+    }
+    /**
+     * Add a project to a roadmap.
+     */
+    async addProjectToRoadmap(roadmapId, projectId, position) {
+        // Verify roadmap exists
+        const roadmap = await this.getRoadmap(roadmapId);
+        if (!roadmap) {
+            throw new PMOError('NOT_FOUND', `Roadmap not found: ${roadmapId}`);
+        }
+        // Check if project is already in roadmap
+        const existing = this.ctx.db.prepare(`
+      SELECT * FROM ${T.roadmap_projects} WHERE roadmap_id = ? AND project_id = ?
+    `).get(roadmapId, projectId);
+        if (existing) {
+            throw new PMOError('CONFLICT', `Project ${projectId} is already in roadmap ${roadmapId}`);
+        }
+        // Get next position if not provided
+        if (position === undefined) {
+            const maxPos = this.ctx.db.prepare(`
+        SELECT COALESCE(MAX(position), -1) as max_pos FROM ${T.roadmap_projects} WHERE roadmap_id = ?
+      `).get(roadmapId);
+            position = maxPos.max_pos + 1;
+        }
+        else {
+            // Shift existing projects at or after this position
+            this.ctx.db.prepare(`
+        UPDATE ${T.roadmap_projects}
+        SET position = position + 1
+        WHERE roadmap_id = ? AND position >= ?
+      `).run(roadmapId, position);
+        }
+        const now = Date.now();
+        this.ctx.db.prepare(`
+      INSERT INTO ${T.roadmap_projects} (roadmap_id, project_id, position, created_at)
+      VALUES (?, ?, ?, ?)
+    `).run(roadmapId, projectId, position, now);
+        // Update roadmap timestamp
+        this.ctx.db.prepare(`UPDATE ${T.roadmaps} SET updated_at = ? WHERE id = ?`).run(now, roadmapId);
+        return {
+            roadmapId,
+            projectId,
+            position,
+            createdAt: new Date(now),
+        };
+    }
+    /**
+     * Remove a project from a roadmap.
+     */
+    async removeProjectFromRoadmap(roadmapId, projectId) {
+        // Get current position for reordering
+        const current = this.ctx.db.prepare(`
+      SELECT position FROM ${T.roadmap_projects} WHERE roadmap_id = ? AND project_id = ?
+    `).get(roadmapId, projectId);
+        if (!current) {
+            throw new PMOError('NOT_FOUND', `Project ${projectId} not in roadmap ${roadmapId}`);
+        }
+        // Delete the association
+        this.ctx.db.prepare(`
+      DELETE FROM ${T.roadmap_projects} WHERE roadmap_id = ? AND project_id = ?
+    `).run(roadmapId, projectId);
+        // Reorder remaining projects to fill the gap
+        this.ctx.db.prepare(`
+      UPDATE ${T.roadmap_projects}
+      SET position = position - 1
+      WHERE roadmap_id = ? AND position > ?
+    `).run(roadmapId, current.position);
+        // Update roadmap timestamp
+        this.ctx.db.prepare(`UPDATE ${T.roadmaps} SET updated_at = ? WHERE id = ?`).run(Date.now(), roadmapId);
+    }
+    /**
+     * Reorder a project within a roadmap.
+     */
+    async reorderRoadmapProject(roadmapId, projectId, newPosition) {
+        // Get current position
+        const current = this.ctx.db.prepare(`
+      SELECT position, created_at FROM ${T.roadmap_projects} WHERE roadmap_id = ? AND project_id = ?
+    `).get(roadmapId, projectId);
+        if (!current) {
+            throw new PMOError('NOT_FOUND', `Project ${projectId} not in roadmap ${roadmapId}`);
+        }
+        const oldPosition = current.position;
+        if (oldPosition === newPosition) {
+            return {
+                roadmapId,
+                projectId,
+                position: newPosition,
+                createdAt: new Date(current.created_at),
+            };
+        }
+        // Shift positions (same pattern as EpicStorage.reorderEpic)
+        if (newPosition < oldPosition) {
+            // Moving up: increment positions in between
+            this.ctx.db.prepare(`
+        UPDATE ${T.roadmap_projects}
+        SET position = position + 1
+        WHERE roadmap_id = ? AND position >= ? AND position < ?
+      `).run(roadmapId, newPosition, oldPosition);
+        }
+        else {
+            // Moving down: decrement positions in between
+            this.ctx.db.prepare(`
+        UPDATE ${T.roadmap_projects}
+        SET position = position - 1
+        WHERE roadmap_id = ? AND position > ? AND position <= ?
+      `).run(roadmapId, oldPosition, newPosition);
+        }
+        // Update the target project's position
+        this.ctx.db.prepare(`
+      UPDATE ${T.roadmap_projects}
+      SET position = ?
+      WHERE roadmap_id = ? AND project_id = ?
+    `).run(newPosition, roadmapId, projectId);
+        // Update roadmap timestamp
+        this.ctx.db.prepare(`UPDATE ${T.roadmaps} SET updated_at = ? WHERE id = ?`).run(Date.now(), roadmapId);
+        return {
+            roadmapId,
+            projectId,
+            position: newPosition,
+            createdAt: new Date(current.created_at),
+        };
+    }
+    /**
+     * Get all roadmaps that contain a project.
+     */
+    async getRoadmapsForProject(projectId) {
+        const rows = this.ctx.db.prepare(`
+      SELECT r.* FROM ${T.roadmaps} r
+      JOIN ${T.roadmap_projects} rp ON r.id = rp.roadmap_id
+      WHERE rp.project_id = ?
+      ORDER BY r.name ASC
+    `).all(projectId);
+        return rows.map(row => this.rowToRoadmap(row));
+    }
+    // ===== Helpers =====
+    rowToRoadmap(row) {
+        return {
+            id: row.id,
+            name: row.name,
+            description: row.description || undefined,
+            isDefault: row.is_default === 1,
+            createdAt: new Date(row.created_at),
+            updatedAt: new Date(row.updated_at),
+        };
+    }
+    rowToProject(row) {
+        return {
+            id: row.id,
+            name: row.name,
+            template: row.template || undefined,
+            description: row.description || undefined,
+            status: (row.status || 'active'),
+            phaseId: row.phase_id || undefined,
+            workflowId: row.workflow_id || undefined,
+            isArchived: row.is_archived === 1,
+            targetDate: row.target_date ? new Date(row.target_date) : undefined,
+            initiativeId: row.initiative_id || undefined,
+            createdAt: new Date(row.created_at),
+            updatedAt: new Date(row.updated_at),
+        };
+    }
+}

package/dist/lib/pmo/storage/specs.js

@@ -294,6 +294,7 @@ export class SpecStorage {
     `).all(specId);
         const specs = [];
         for (const row of rows) {
+            // eslint-disable-next-line no-await-in-loop -- Sequential lookup for relationship chain
             const spec = await this.getSpec(row.depends_on);
             if (spec)
                 specs.push(spec);
@@ -309,6 +310,7 @@ export class SpecStorage {
     `).all(specId);
         const specs = [];
         for (const row of rows) {
+            // eslint-disable-next-line no-await-in-loop -- Sequential lookup for relationship chain
             const spec = await this.getSpec(row.spec_id);
             if (spec)
                 specs.push(spec);

package/dist/lib/pmo/storage/types.d.ts

@@ -198,3 +198,17 @@ export interface TicketTemplateRow {
     is_builtin: number;
     created_at: string;
 }
+export interface RoadmapRow {
+    id: string;
+    name: string;
+    description: string | null;
+    is_default: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface RoadmapProjectRow {
+    roadmap_id: string;
+    project_id: string;
+    position: number;
+    created_at: string;
+}

package/dist/lib/pmo/sync-manager.d.ts

@@ -85,7 +85,7 @@ export declare function getWorkspaceDbPath(pmoPath: string): string;
  * - 'git' mode enables multi-machine sync via git push/pull
  * - 'sqlite' mode is local-only (no multi-machine sync)
  */
-export declare function getStorageWithAutoSync(pmoPath: string, storageType: 'sqlite' | 'git', logger?: (msg: string) => void): SQLiteStorage;
+export declare function getStorageWithAutoSync(pmoPath: string, _storageType: 'sqlite' | 'git', _logger?: (msg: string) => void): SQLiteStorage;
 /**
  * Wrapper for write operations that auto-exports to board.md after
  */

package/dist/lib/pmo/sync-manager.js

@@ -207,7 +207,7 @@ export function getWorkspaceDbPath(pmoPath) {
  * - 'git' mode enables multi-machine sync via git push/pull
  * - 'sqlite' mode is local-only (no multi-machine sync)
  */
-export function getStorageWithAutoSync(pmoPath, storageType, logger) {
+export function getStorageWithAutoSync(pmoPath, _storageType, _logger) {
     // Storage is always workspace.db (unified PMO tables with foreign keys to agents)
     const dbPath = getWorkspaceDbPath(pmoPath);
     if (!fs.existsSync(dbPath)) {

package/dist/lib/pmo/types.d.ts

@@ -217,6 +217,29 @@ export interface PhaseTemplatePhase {
     description?: string;
     isDefault?: boolean;
 }
+/**
+ * Roadmap - a curated collection of projects for documentation/visualization.
+ * Roadmaps group projects in a specific order for generating roadmap documents.
+ * Projects can appear in multiple roadmaps (e.g., "Public Roadmap" vs "Internal Roadmap").
+ */
+export interface Roadmap {
+    id: string;
+    name: string;
+    description?: string;
+    isDefault: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * RoadmapProject - association between a roadmap and a project with ordering.
+ * Projects can be in multiple roadmaps with different positions.
+ */
+export interface RoadmapProject {
+    roadmapId: string;
+    projectId: string;
+    position: number;
+    createdAt: Date;
+}
 /**
  * Work action - defines what an agent should do with a ticket.
  * Actions are reusable prompts that can be applied to any ticket.
@@ -576,6 +599,10 @@ export interface BoardViewFilter {
     isDefault?: boolean;
     search?: string;
 }
+export interface RoadmapFilter {
+    isDefault?: boolean;
+    search?: string;
+}
 export interface SyncResult {
     success: boolean;
     changes: number;
@@ -702,6 +729,20 @@ export interface PMOStorage {
     deleteBoardView(id: string): Promise<void>;
     getDefaultBoardView(projectId: string): Promise<BoardView | null>;
     getBoardWithView(projectId: string, viewId?: string, filters?: BoardViewFilters): Promise<Board>;
+    listRoadmaps(filter?: RoadmapFilter): Promise<Roadmap[]>;
+    getRoadmap(id: string): Promise<Roadmap | null>;
+    createRoadmap(roadmap: Partial<Roadmap> & {
+        name: string;
+    }): Promise<Roadmap>;
+    updateRoadmap(id: string, changes: Partial<Roadmap>): Promise<Roadmap>;
+    deleteRoadmap(id: string): Promise<void>;
+    getDefaultRoadmap(): Promise<Roadmap | null>;
+    setDefaultRoadmap(id: string): Promise<Roadmap>;
+    listRoadmapProjects(roadmapId: string): Promise<Project[]>;
+    addProjectToRoadmap(roadmapId: string, projectId: string, position?: number): Promise<RoadmapProject>;
+    removeProjectFromRoadmap(roadmapId: string, projectId: string): Promise<void>;
+    reorderRoadmapProject(roadmapId: string, projectId: string, newPosition: number): Promise<RoadmapProject>;
+    getRoadmapsForProject(projectId: string): Promise<Roadmap[]>;
     pull(): Promise<SyncResult>;
     push(): Promise<SyncResult>;
     status(): Promise<SyncStatus>;

package/dist/lib/pmo/utils.d.ts

@@ -44,6 +44,8 @@ interface DatabaseLike {
  * Uses pmo_settings table to track the next ID for each entity type.
  * IDs are zero-padded to 3 digits (001-999), then expand (1000+).
  *
+ * Self-healing: If counter is behind MAX(id) in the table, auto-corrects.
+ *
  * @param db - Database instance with prepare method
  * @param entityType - Type of entity (ticket, epic, spec, project)
  * @returns Generated ID like "TKT-001"

package/dist/lib/pmo/utils.js

@@ -41,6 +41,15 @@ export const ENTITY_PREFIXES = {
     spec: 'SPEC',
     project: 'PROJ',
 };
+/**
+ * Entity type to table name mapping for self-healing ID generation
+ */
+const ENTITY_TABLES = {
+    ticket: 'pmo_tickets',
+    epic: 'pmo_epics',
+    spec: 'pmo_specs',
+    project: 'pmo_projects',
+};
 /**
  * Generate a sequential ID for an entity.
  *
@@ -49,16 +58,28 @@ export const ENTITY_PREFIXES = {
  * Uses pmo_settings table to track the next ID for each entity type.
  * IDs are zero-padded to 3 digits (001-999), then expand (1000+).
  *
+ * Self-healing: If counter is behind MAX(id) in the table, auto-corrects.
+ *
  * @param db - Database instance with prepare method
  * @param entityType - Type of entity (ticket, epic, spec, project)
  * @returns Generated ID like "TKT-001"
  */
 export function generateEntityId(db, entityType) {
     const typePrefix = ENTITY_PREFIXES[entityType];
+    const tableName = ENTITY_TABLES[entityType];
     const settingKey = `next_${entityType}_id`;
+    // Get MAX(id) from the entity table for self-healing
+    // Extract numeric part: TKT-001 → 1, EPIC-042 → 42
+    const prefixLen = typePrefix.length + 1; // e.g., "TKT-" = 4 chars
+    const maxResult = db.prepare(`SELECT MAX(CAST(SUBSTR(id, ${prefixLen + 1}) AS INTEGER)) as max_num FROM ${tableName}`).get();
+    const maxExistingId = maxResult?.max_num || 0;
     // Get current counter
     const row = db.prepare(`SELECT value FROM pmo_settings WHERE key = ?`).get(settingKey);
-    const nextNum = row ? parseInt(row.value, 10) : 1;
+    let nextNum = row ? parseInt(row.value, 10) : 1;
+    // Self-healing: if counter is behind existing IDs, fix it
+    if (nextNum <= maxExistingId) {
+        nextNum = maxExistingId + 1;
+    }
     // Update counter
     db.prepare(`
     INSERT INTO pmo_settings (key, value) VALUES (?, ?)

package/dist/lib/repos/index.js

@@ -76,9 +76,10 @@ export async function promptForRepositories(currentDir = process.cwd(), existing
             }
         }
     }
-    // Loop to add more repos
+    // Loop to add more repos - user interaction requires sequential processing
     let addingRepos = true;
     while (addingRepos) {
+        // eslint-disable-next-line no-await-in-loop
         const { repoAction } = await inquirer.prompt([{
                 type: 'list',
                 name: 'repoAction',
@@ -98,6 +99,7 @@ export async function promptForRepositories(currentDir = process.cwd(), existing
             break;
         }
         if (repoAction === 'create') {
+            // eslint-disable-next-line no-await-in-loop
             const newRepo = await createNewRepository();
             if (newRepo) {
                 repos.push(newRepo);
@@ -105,10 +107,12 @@ export async function promptForRepositories(currentDir = process.cwd(), existing
             continue;
         }
         if (repoAction === 'search') {
+            // eslint-disable-next-line no-await-in-loop
             const foundRepos = await searchForRepositories();
             repos.push(...foundRepos);
             // After search, ask if they want to add more (unless they selected nothing)
             if (foundRepos.length > 0) {
+                // eslint-disable-next-line no-await-in-loop
                 const { addMoreAfterSearch } = await inquirer.prompt([{
                         type: 'list',
                         name: 'addMoreAfterSearch',
@@ -127,6 +131,7 @@ export async function promptForRepositories(currentDir = process.cwd(), existing
             continue;
         }
         // Manual entry (existing logic)
+        // eslint-disable-next-line no-await-in-loop
         const { repoPath } = await inquirer.prompt([{
                 type: 'input',
                 name: 'repoPath',
@@ -152,6 +157,7 @@ export async function promptForRepositories(currentDir = process.cwd(), existing
                 repos.push({ path: resolvedPath, action: 'clone' });
             }
             else {
+                // eslint-disable-next-line no-await-in-loop
                 const { action } = await inquirer.prompt([{
                         type: 'list',
                         name: 'action',

package/dist/lib/terminal.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Terminal utilities for controlling terminal behavior.
+ *
+ * Provides ANSI escape sequence utilities for:
+ * - Setting terminal tab/window titles
+ * - Future: clearing screen, notifications, etc.
+ */
+/**
+ * Generate shell commands to set the terminal tab/window title.
+ * Uses ANSI escape sequences that work across most terminal emulators.
+ *
+ * \033]0;Title\007 - Sets both window and tab title (most compatible)
+ * \033]1;Title\007 - Sets tab title only (iTerm2, some others)
+ * \033]2;Title\007 - Sets window title only
+ *
+ * @param title - The title to set
+ * @returns Shell commands to execute
+ */
+export declare function getSetTitleCommands(title: string): string;
+/**
+ * Set the terminal title directly using ANSI escape sequences.
+ * Writes directly to stdout.
+ *
+ * @param title - The title to set (empty string to reset)
+ */
+export declare function setTerminalTitle(title: string): void;
+/**
+ * Reset the terminal title to default (shell will set its own).
+ * This sends an empty title which most terminals interpret as "use default".
+ */
+export declare function resetTerminalTitle(): void;

package/dist/lib/terminal.js

@@ -0,0 +1,48 @@
+/**
+ * Terminal utilities for controlling terminal behavior.
+ *
+ * Provides ANSI escape sequence utilities for:
+ * - Setting terminal tab/window titles
+ * - Future: clearing screen, notifications, etc.
+ */
+/**
+ * Generate shell commands to set the terminal tab/window title.
+ * Uses ANSI escape sequences that work across most terminal emulators.
+ *
+ * \033]0;Title\007 - Sets both window and tab title (most compatible)
+ * \033]1;Title\007 - Sets tab title only (iTerm2, some others)
+ * \033]2;Title\007 - Sets window title only
+ *
+ * @param title - The title to set
+ * @returns Shell commands to execute
+ */
+export function getSetTitleCommands(title) {
+    // Escape any special characters in the title
+    const safeTitle = title.replace(/[\\'"]/g, '');
+    return `
+# Set terminal tab/window title
+echo -ne "\\033]0;${safeTitle}\\007"
+echo -ne "\\033]1;${safeTitle}\\007"
+`;
+}
+/**
+ * Set the terminal title directly using ANSI escape sequences.
+ * Writes directly to stdout.
+ *
+ * @param title - The title to set (empty string to reset)
+ */
+export function setTerminalTitle(title) {
+    // Escape any special characters
+    const safeTitle = title.replace(/[\\'"]/g, '');
+    // OSC 0 - Set both window and tab title (most compatible)
+    process.stdout.write(`\u001B]0;${safeTitle}\u0007`);
+    // OSC 1 - Set tab title (iTerm2 and others)
+    process.stdout.write(`\u001B]1;${safeTitle}\u0007`);
+}
+/**
+ * Reset the terminal title to default (shell will set its own).
+ * This sends an empty title which most terminals interpret as "use default".
+ */
+export function resetTerminalTitle() {
+    setTerminalTitle('');
+}

package/dist/lib/themes.d.ts

@@ -1,3 +1,4 @@
+import { Agent } from './database/index.js';
 /**
  * Default workspace directory for persistent agents (fallback if no theme)
  */
@@ -111,11 +112,16 @@ export interface GenerateEphemeralNameOptions {
      * Optional callback for logging/messaging when conflicts are detected
      */
     onConflictSkipped?: (name: string, reason: string) => void;
+    /**
+     * Optional set of base names currently in use by active agents.
+     * If provided, the generator will prefer base names NOT in this set.
+     */
+    inUseBaseNames?: Set<string>;
 }
 /**
  * Generate a unique ephemeral agent name.
- * Format: {adjective}-{theme_name}-{number}
- * Example: "bold-bezos-1", "keen-camry-2"
+ * Format: {adjective}-{theme_name} or {adjective}-{theme_name}-{number}
+ * Example: "bold-bezos", "keen-camry", "bold-bezos-2" (if bold-bezos exists)
  *
  * @param existingNames - Set of existing agent names (for uniqueness checking)
  * @param options - Optional configuration for name generation
@@ -123,6 +129,18 @@ export interface GenerateEphemeralNameOptions {
 export declare function generateEphemeralAgentName(existingNames: Set<string>, options?: GenerateEphemeralNameOptions | string): string;
 /**
  * Check if a name looks like an ephemeral agent name.
- * Ephemeral names follow pattern: {adjective}-{name}-{number}
+ * Ephemeral names follow pattern: {adjective}-{name} or {adjective}-{name}-{number}
  */
 export declare function isEphemeralAgentName(name: string): boolean;
+/**
+ * Extract the base name from an ephemeral agent name.
+ * Handles both formats: "bold-bezos" -> "bezos", "bold-bezos-2" -> "bezos"
+ */
+export declare function extractBaseName(agentName: string): string;
+/**
+ * Get the base name for any agent type.
+ * - If agent has explicit base_name, use it
+ * - If ephemeral, extract from name pattern
+ * - Otherwise (staff), use agent name directly
+ */
+export declare function getAgentBaseName(agent: Agent): string;