@proletariat/cli 0.3.14 → 0.3.15

package/dist/lib/agents/index.js

@@ -74,29 +74,45 @@ export async function promptAgentNames(existingAgents = []) {
     return agentNames.trim().split(/\s+/).filter(Boolean);
 }
 /**
- * Create agent worktrees (shared between HQ and workspace-only modes)
+ * Get the remote URL for a git repository
+ */
+function getRemoteUrl(repoPath) {
+    try {
+        const url = execSync('git remote get-url origin', { cwd: repoPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        return url || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Create agent repos (worktree or clone mode)
+ * - worktree mode: Uses git worktree add (shared .git, requires parent repo mounts in container)
+ * - clone mode: Uses git clone (independent repo, no path translation needed)
  */
 export async function createAgentWorktrees(workspacePath, agents, hqPath, options) {
+    const mountMode = options?.mountMode || 'worktree'; // Default to worktree for real-time file sync
+    const modeLabel = mountMode === 'worktree' ? 'worktree' : 'clone';
     if (hqPath) {
-        // HQ mode - create worktrees for all repos in repos/ directory
+        // HQ mode - create worktrees/clones for all repos in repos/ directory
         const reposDir = path.join(hqPath, 'repos');
         // Get repositories from database instead of JSON config
         const repos = getWorkspaceRepositories(hqPath);
         if (repos.length > 0) {
-            // Create worktrees for each agent across all repositories
+            // Create worktrees/clones for each agent across all repositories
             for (const agent of agents) {
                 const agentDir = path.join(workspacePath, agent);
-                console.log(chalk.blue(`Creating agent: ${agent}...`));
+                console.log(chalk.blue(`Creating agent: ${agent} (${modeLabel} mode)...`));
                 try {
                     // Create agent directory
                     fs.mkdirSync(agentDir, { recursive: true });
-                    // Track which repos successfully had worktrees created
-                    const createdWorktrees = [];
-                    // Create worktrees for all repositories
+                    // Track which repos were successfully created
+                    const createdRepos = [];
+                    // Create repos for all repositories
                     for (const repo of repos) {
                         const sourceRepo = path.join(reposDir, repo.name);
-                        // Worktree directory is just the repo name (the agent name is already in the parent path)
-                        const worktreeDir = path.join(agentDir, repo.name);
+                        // Target directory is just the repo name (the agent name is already in the parent path)
+                        const targetDir = path.join(agentDir, repo.name);
                         if (fs.existsSync(sourceRepo)) {
                             // Check if repo is empty (no commits)
                             let isEmptyRepo = false;
@@ -110,85 +126,109 @@ export async function createAgentWorktrees(workspacePath, agents, hqPath, option
                                 console.log(chalk.yellow(`  Skipping ${repo.name} (empty repository with no commits)`));
                                 continue;
                             }
-                            console.log(styles.muted(`  Creating worktree for ${repo.name}...`));
-                            // Fetch latest from origin to ensure we have up-to-date main
-                            try {
-                                execSync(`git fetch origin main`, {
-                                    cwd: sourceRepo,
-                                    stdio: 'pipe'
-                                });
-                            }
-                            catch {
-                                // Ignore fetch errors (might be offline)
-                                console.log(chalk.yellow(`  Warning: Could not fetch origin/main, using local state`));
-                            }
-                            // Determine the base ref to use (origin/main, main, or HEAD)
-                            let baseRef = 'origin/main';
-                            try {
-                                execSync(`git rev-parse ${baseRef}`, { cwd: sourceRepo, stdio: 'pipe' });
+                            if (mountMode === 'clone') {
+                                // CLONE MODE: Create independent git clone
+                                console.log(styles.muted(`  Cloning ${repo.name}...`));
+                                // Get remote URL from source repo
+                                const remoteUrl = getRemoteUrl(sourceRepo);
+                                if (!remoteUrl) {
+                                    console.log(chalk.yellow(`  Skipping ${repo.name} (no remote URL configured)`));
+                                    continue;
+                                }
+                                try {
+                                    // Clone the repository
+                                    execSync(`git clone "${remoteUrl}" "${targetDir}"`, {
+                                        stdio: 'inherit'
+                                    });
+                                    createdRepos.push(repo.name);
+                                }
+                                catch (cloneError) {
+                                    console.log(chalk.yellow(`  Warning: Clone failed for ${repo.name}: ${cloneError}`));
+                                }
                             }
-                            catch {
-                                // origin/main doesn't exist, try local main
+                            else {
+                                // WORKTREE MODE: Create git worktree (original behavior)
+                                console.log(styles.muted(`  Creating worktree for ${repo.name}...`));
+                                // Fetch latest from origin to ensure we have up-to-date main
                                 try {
-                                    execSync('git rev-parse main', { cwd: sourceRepo, stdio: 'pipe' });
-                                    baseRef = 'main';
+                                    execSync(`git fetch origin main`, {
+                                        cwd: sourceRepo,
+                                        stdio: 'pipe'
+                                    });
                                 }
                                 catch {
-                                    // No main branch, use HEAD
-                                    baseRef = 'HEAD';
+                                    // Ignore fetch errors (might be offline)
+                                    console.log(chalk.yellow(`  Warning: Could not fetch origin/main, using local state`));
                                 }
-                            }
-                            // Create git worktree for the agent
-                            const branchName = `agent-${agent}`;
-                            try {
-                                execSync(`git worktree add "${worktreeDir}" -b ${branchName} ${baseRef}`, {
-                                    cwd: sourceRepo,
-                                    stdio: 'inherit'
-                                });
-                                createdWorktrees.push(repo.name);
-                            }
-                            catch {
-                                // Branch might already exist, try to use it or clean up
-                                console.log(chalk.yellow(`  Branch ${branchName} already exists, attempting to reuse or clean up...`));
+                                // Determine the base ref to use (origin/main, main, or HEAD)
+                                let baseRef = 'origin/main';
+                                try {
+                                    execSync(`git rev-parse ${baseRef}`, { cwd: sourceRepo, stdio: 'pipe' });
+                                }
+                                catch {
+                                    // origin/main doesn't exist, try local main
+                                    try {
+                                        execSync('git rev-parse main', { cwd: sourceRepo, stdio: 'pipe' });
+                                        baseRef = 'main';
+                                    }
+                                    catch {
+                                        // No main branch, use HEAD
+                                        baseRef = 'HEAD';
+                                    }
+                                }
+                                // Create git worktree for the agent
+                                const branchName = `agent-${agent}`;
                                 try {
-                                    // Try without creating a new branch (use existing)
-                                    execSync(`git worktree add "${worktreeDir}" ${branchName}`, {
+                                    execSync(`git worktree add "${targetDir}" -b ${branchName} ${baseRef}`, {
                                         cwd: sourceRepo,
                                         stdio: 'inherit'
                                     });
-                                    createdWorktrees.push(repo.name);
+                                    createdRepos.push(repo.name);
                                 }
                                 catch {
-                                    // If that fails too, clean up the orphaned branch and try again
+                                    // Branch might already exist, try to use it or clean up
+                                    console.log(chalk.yellow(`  Branch ${branchName} already exists, attempting to reuse or clean up...`));
                                     try {
-                                        execSync(`git branch -D ${branchName}`, {
-                                            cwd: sourceRepo,
-                                            stdio: 'pipe'
-                                        });
-                                        execSync(`git worktree add "${worktreeDir}" -b ${branchName} ${baseRef}`, {
+                                        // Try without creating a new branch (use existing)
+                                        execSync(`git worktree add "${targetDir}" ${branchName}`, {
                                             cwd: sourceRepo,
                                             stdio: 'inherit'
                                         });
-                                        createdWorktrees.push(repo.name);
+                                        createdRepos.push(repo.name);
                                     }
-                                    catch (finalError) {
-                                        throw new Error(`Failed to create worktree after cleanup: ${finalError}`);
+                                    catch {
+                                        // If that fails too, clean up the orphaned branch and try again
+                                        try {
+                                            execSync(`git branch -D ${branchName}`, {
+                                                cwd: sourceRepo,
+                                                stdio: 'pipe'
+                                            });
+                                            execSync(`git worktree add "${targetDir}" -b ${branchName} ${baseRef}`, {
+                                                cwd: sourceRepo,
+                                                stdio: 'inherit'
+                                            });
+                                            createdRepos.push(repo.name);
+                                        }
+                                        catch (finalError) {
+                                            throw new Error(`Failed to create worktree after cleanup: ${finalError}`);
+                                        }
                                     }
                                 }
                             }
                         }
                     }
-                    // Create devcontainer config for sandboxed execution (only for repos with worktrees)
+                    // Create devcontainer config for sandboxed execution (only for repos that were created)
                     // Note: Agent metadata is stored in SQLite (agents table), not in config files
-                    if (!options?.skipDevcontainer && createdWorktrees.length > 0) {
+                    if (!options?.skipDevcontainer && createdRepos.length > 0) {
                         console.log(styles.muted(`  Creating devcontainer config...`));
                         createDevcontainerConfig({
                             agentName: agent,
                             agentDir,
-                            repoWorktrees: createdWorktrees,
+                            repoWorktrees: mountMode === 'worktree' ? createdRepos : undefined, // Only pass repos for worktree mode
+                            mountMode,
                         });
                     }
-                    console.log(chalk.green(`✅ Agent ${agent} created with ${createdWorktrees.length} worktree(s)`));
+                    console.log(chalk.green(`✅ Agent ${agent} created with ${createdRepos.length} ${modeLabel}(s)`));
                 }
                 catch (error) {
                     console.log(chalk.red(`Failed to create agent ${agent}: ${error}`));
@@ -211,9 +251,9 @@ export async function createAgentWorktrees(workspacePath, agents, hqPath, option
         const repoName = path.basename(sourceRepo);
         for (const agent of agents) {
             const agentDir = path.join(workspacePath, agent);
-            // Worktree directory is just the repo name (the agent name is already in the parent path)
-            const worktreeDir = path.join(agentDir, repoName);
-            console.log(chalk.blue(`Creating agent: ${agent}...`));
+            // Target directory is just the repo name (the agent name is already in the parent path)
+            const targetDir = path.join(agentDir, repoName);
+            console.log(chalk.blue(`Creating agent: ${agent} (${modeLabel} mode)...`));
             try {
                 // Check if repo is empty (no commits)
                 let isEmptyRepo = false;
@@ -229,65 +269,82 @@ export async function createAgentWorktrees(workspacePath, agents, hqPath, option
                 }
                 // Create agent directory
                 fs.mkdirSync(agentDir, { recursive: true });
-                // Fetch latest from origin to ensure we have up-to-date main
-                try {
-                    execSync(`git fetch origin main`, {
-                        cwd: sourceRepo,
-                        stdio: 'pipe'
+                if (mountMode === 'clone') {
+                    // CLONE MODE: Create independent git clone
+                    console.log(styles.muted(`  Cloning ${repoName}...`));
+                    // Get remote URL from source repo
+                    const remoteUrl = getRemoteUrl(sourceRepo);
+                    if (!remoteUrl) {
+                        console.log(chalk.yellow(`  Skipping ${repoName} (no remote URL configured)`));
+                        continue;
+                    }
+                    // Clone the repository
+                    execSync(`git clone "${remoteUrl}" "${targetDir}"`, {
+                        stdio: 'inherit'
                     });
                 }
-                catch {
-                    // Ignore fetch errors (might be offline)
-                    console.log(chalk.yellow(`  Warning: Could not fetch origin/main, using local state`));
-                }
-                // Determine the base ref to use (origin/main, main, or HEAD)
-                let baseRef = 'origin/main';
-                try {
-                    execSync(`git rev-parse ${baseRef}`, { cwd: sourceRepo, stdio: 'pipe' });
-                }
-                catch {
-                    // origin/main doesn't exist, try local main
+                else {
+                    // WORKTREE MODE: Create git worktree (original behavior)
+                    // Fetch latest from origin to ensure we have up-to-date main
                     try {
-                        execSync('git rev-parse main', { cwd: sourceRepo, stdio: 'pipe' });
-                        baseRef = 'main';
+                        execSync(`git fetch origin main`, {
+                            cwd: sourceRepo,
+                            stdio: 'pipe'
+                        });
                     }
                     catch {
-                        // No main branch, use HEAD
-                        baseRef = 'HEAD';
+                        // Ignore fetch errors (might be offline)
+                        console.log(chalk.yellow(`  Warning: Could not fetch origin/main, using local state`));
                     }
-                }
-                // Create git worktree for the agent
-                const branchName = `agent-${agent}`;
-                try {
-                    execSync(`git worktree add "${worktreeDir}" -b ${branchName} ${baseRef}`, {
-                        cwd: sourceRepo,
-                        stdio: 'inherit'
-                    });
-                }
-                catch {
-                    // Branch might already exist, try to use it or clean up
-                    console.log(chalk.yellow(`  Branch ${branchName} already exists, attempting to reuse or clean up...`));
+                    // Determine the base ref to use (origin/main, main, or HEAD)
+                    let baseRef = 'origin/main';
                     try {
-                        // Try without creating a new branch (use existing)
-                        execSync(`git worktree add "${worktreeDir}" ${branchName}`, {
+                        execSync(`git rev-parse ${baseRef}`, { cwd: sourceRepo, stdio: 'pipe' });
+                    }
+                    catch {
+                        // origin/main doesn't exist, try local main
+                        try {
+                            execSync('git rev-parse main', { cwd: sourceRepo, stdio: 'pipe' });
+                            baseRef = 'main';
+                        }
+                        catch {
+                            // No main branch, use HEAD
+                            baseRef = 'HEAD';
+                        }
+                    }
+                    // Create git worktree for the agent
+                    const branchName = `agent-${agent}`;
+                    try {
+                        execSync(`git worktree add "${targetDir}" -b ${branchName} ${baseRef}`, {
                             cwd: sourceRepo,
                             stdio: 'inherit'
                         });
                     }
                     catch {
-                        // If that fails too, clean up the orphaned branch and try again
+                        // Branch might already exist, try to use it or clean up
+                        console.log(chalk.yellow(`  Branch ${branchName} already exists, attempting to reuse or clean up...`));
                         try {
-                            execSync(`git branch -D ${branchName}`, {
-                                cwd: sourceRepo,
-                                stdio: 'pipe'
-                            });
-                            execSync(`git worktree add "${worktreeDir}" -b ${branchName} ${baseRef}`, {
+                            // Try without creating a new branch (use existing)
+                            execSync(`git worktree add "${targetDir}" ${branchName}`, {
                                 cwd: sourceRepo,
                                 stdio: 'inherit'
                             });
                         }
-                        catch (finalError) {
-                            throw new Error(`Failed to create worktree after cleanup: ${finalError}`);
+                        catch {
+                            // If that fails too, clean up the orphaned branch and try again
+                            try {
+                                execSync(`git branch -D ${branchName}`, {
+                                    cwd: sourceRepo,
+                                    stdio: 'pipe'
+                                });
+                                execSync(`git worktree add "${targetDir}" -b ${branchName} ${baseRef}`, {
+                                    cwd: sourceRepo,
+                                    stdio: 'inherit'
+                                });
+                            }
+                            catch (finalError) {
+                                throw new Error(`Failed to create worktree after cleanup: ${finalError}`);
+                            }
                         }
                     }
                 }
@@ -298,10 +355,11 @@ export async function createAgentWorktrees(workspacePath, agents, hqPath, option
                     createDevcontainerConfig({
                         agentName: agent,
                         agentDir,
-                        repoWorktrees: [repoName],
+                        repoWorktrees: mountMode === 'worktree' ? [repoName] : undefined, // Only pass repos for worktree mode
+                        mountMode,
                     });
                 }
-                console.log(chalk.green(`✅ Agent ${agent} created with worktree`));
+                console.log(chalk.green(`✅ Agent ${agent} created with ${modeLabel}`));
             }
             catch (error) {
                 console.log(chalk.red(`Failed to create agent ${agent}: ${error}`));

package/dist/lib/database/index.d.ts

@@ -17,6 +17,7 @@ export interface Repository {
 }
 export type AgentType = 'persistent' | 'ephemeral';
 export type AgentStatus = 'active' | 'cleaned';
+export type MountMode = 'worktree' | 'clone';
 export interface Agent {
     name: string;
     type: AgentType;
@@ -24,6 +25,7 @@ export interface Agent {
     base_name: string | null;
     theme_id: string | null;
     worktree_path: string | null;
+    mount_mode: MountMode;
     created_at: string;
     cleaned_at: string | null;
 }
@@ -91,11 +93,11 @@ export declare function addRepositoriesToDatabase(workspacePath: string, repos:
 /**
  * Add agents to database (case-insensitive uniqueness)
  */
-export declare function addAgentsToDatabase(workspacePath: string, agentNames: string[], themeId?: string): void;
+export declare function addAgentsToDatabase(workspacePath: string, agentNames: string[], themeId?: string, mountMode?: MountMode): void;
 /**
  * Add an ephemeral agent to the database
  */
-export declare function addEphemeralAgentToDatabase(workspacePath: string, agentName: string, baseName: string, themeId?: string): Agent;
+export declare function addEphemeralAgentToDatabase(workspacePath: string, agentName: string, baseName: string, themeId?: string, mountMode?: MountMode): Agent;
 /**
  * Get all ephemeral agent names from the database
  */

package/dist/lib/database/index.js

@@ -51,6 +51,7 @@ CREATE TABLE IF NOT EXISTS agents (
   base_name TEXT,
   theme_id TEXT,
   worktree_path TEXT,
+  mount_mode TEXT NOT NULL DEFAULT 'worktree' CHECK (mount_mode IN ('worktree', 'clone')),
   created_at TEXT NOT NULL,
   cleaned_at TEXT,
   FOREIGN KEY (theme_id) REFERENCES agent_themes(id) ON DELETE SET NULL
@@ -183,6 +184,17 @@ export function openWorkspaceDatabase(workspacePath) {
     catch {
         // Ignore migration errors - table might not exist yet
     }
+    // Migration: add mount_mode column to agents table (TKT-686)
+    try {
+        const agentsTableInfo = db.prepare("PRAGMA table_info(agents)").all();
+        if (!agentsTableInfo.some(col => col.name === 'mount_mode')) {
+            // Add mount_mode column with default 'worktree' for existing agents (backward compat)
+            db.exec("ALTER TABLE agents ADD COLUMN mount_mode TEXT NOT NULL DEFAULT 'worktree' CHECK (mount_mode IN ('worktree', 'clone'))");
+        }
+    }
+    catch {
+        // Ignore migration errors - table might not exist yet or column already exists
+    }
     return db;
 }
 /**
@@ -307,13 +319,13 @@ export function addRepositoriesToDatabase(workspacePath, repos) {
 /**
  * Add agents to database (case-insensitive uniqueness)
  */
-export function addAgentsToDatabase(workspacePath, agentNames, themeId) {
+export function addAgentsToDatabase(workspacePath, agentNames, themeId, mountMode = 'worktree') {
     const db = openWorkspaceDatabase(workspacePath);
     // Check for existing agents (case-insensitive)
     const checkExisting = db.prepare('SELECT name FROM agents WHERE LOWER(name) = LOWER(?)');
     const insertAgent = db.prepare(`
-    INSERT OR REPLACE INTO agents (name, type, base_name, theme_id, worktree_path, created_at)
-    VALUES (?, ?, ?, ?, ?, ?)
+    INSERT OR REPLACE INTO agents (name, type, base_name, theme_id, worktree_path, mount_mode, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
   `);
     const insertWorktree = db.prepare(`
     INSERT OR REPLACE INTO agent_worktrees (agent_name, repo_name, worktree_path, branch, created_at)
@@ -339,7 +351,7 @@ export function addAgentsToDatabase(workspacePath, agentNames, themeId) {
                 ? `agents/${persistentDir}/${agentName}`
                 : agentName;
             // Add agent (persistent type for manually added agents)
-            insertAgent.run(agentName, 'persistent', null, effectiveThemeId || null, agentWorktreePath, now);
+            insertAgent.run(agentName, 'persistent', null, effectiveThemeId || null, agentWorktreePath, mountMode, now);
             // Add worktrees for all repos
             for (const repo of repos) {
                 const worktreePath = workspace.type === 'hq'
@@ -355,14 +367,14 @@ export function addAgentsToDatabase(workspacePath, agentNames, themeId) {
 /**
  * Add an ephemeral agent to the database
  */
-export function addEphemeralAgentToDatabase(workspacePath, agentName, baseName, themeId) {
+export function addEphemeralAgentToDatabase(workspacePath, agentName, baseName, themeId, mountMode = 'worktree') {
     const db = openWorkspaceDatabase(workspacePath);
     const now = new Date().toISOString();
     const worktreePath = `agents/temp/${agentName}`;
     db.prepare(`
-    INSERT INTO agents (name, type, status, base_name, theme_id, worktree_path, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
-  `).run(agentName, 'ephemeral', 'active', baseName, themeId || null, worktreePath, now);
+    INSERT INTO agents (name, type, status, base_name, theme_id, worktree_path, mount_mode, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(agentName, 'ephemeral', 'active', baseName, themeId || null, worktreePath, mountMode, now);
     const agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(agentName);
     db.close();
     return {
@@ -372,6 +384,7 @@ export function addEphemeralAgentToDatabase(workspacePath, agentName, baseName,
         base_name: agent.base_name,
         theme_id: agent.theme_id,
         worktree_path: agent.worktree_path,
+        mount_mode: (agent.mount_mode || 'clone'),
         created_at: agent.created_at,
         cleaned_at: agent.cleaned_at,
     };
@@ -411,6 +424,7 @@ export function getWorkspaceAgents(workspacePath, includeCleanedUp = false) {
         base_name: row.base_name,
         theme_id: row.theme_id,
         worktree_path: row.worktree_path,
+        mount_mode: (row.mount_mode || 'worktree'),
         created_at: row.created_at,
         cleaned_at: row.cleaned_at,
     }));
@@ -445,6 +459,7 @@ export function getAgentByPath(workspacePath, absolutePath) {
                     base_name: row.base_name,
                     theme_id: row.theme_id,
                     worktree_path: row.worktree_path,
+                    mount_mode: (row.mount_mode || 'worktree'),
                     created_at: row.created_at,
                     cleaned_at: row.cleaned_at,
                 };
@@ -527,10 +542,10 @@ export function discoverAgentsOnDisk(workspacePath) {
               `).run(worktreePath, entry.name);
                         }
                         else {
-                            // Register new agent
+                            // Register new agent - discovered agents default to 'worktree' mode (legacy behavior)
                             db.prepare(`
-                INSERT INTO agents (name, type, status, worktree_path, created_at)
-                VALUES (?, 'persistent', 'active', ?, ?)
+                INSERT INTO agents (name, type, status, worktree_path, mount_mode, created_at)
+                VALUES (?, 'persistent', 'active', ?, 'worktree', ?)
               `).run(entry.name, worktreePath, now);
                         }
                         result.discovered.push({ name: entry.name, type: 'persistent', path: worktreePath });
@@ -559,10 +574,10 @@ export function discoverAgentsOnDisk(workspacePath) {
               `).run(worktreePath, entry.name);
                         }
                         else {
-                            // Register new agent
+                            // Register new agent - discovered agents default to 'worktree' mode (legacy behavior)
                             db.prepare(`
-                INSERT INTO agents (name, type, status, worktree_path, created_at)
-                VALUES (?, 'ephemeral', 'active', ?, ?)
+                INSERT INTO agents (name, type, status, worktree_path, mount_mode, created_at)
+                VALUES (?, 'ephemeral', 'active', ?, 'worktree', ?)
               `).run(entry.name, worktreePath, now);
                         }
                         result.discovered.push({ name: entry.name, type: 'ephemeral', path: worktreePath });

package/dist/lib/execution/context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Execution Context Utilities
+ *
+ * Shared helpers for building ExecutionContext and detecting repository worktrees.
+ */
+/**
+ * Detect git repository worktrees within an agent directory.
+ *
+ * Scans the agent directory for subdirectories that contain a .git file or folder,
+ * indicating they are git repositories (either worktrees or clones).
+ *
+ * @param agentDir - The agent's working directory
+ * @returns Array of repository directory names found within the agent directory
+ */
+export declare function detectRepoWorktrees(agentDir: string): string[];
+/**
+ * Determine the worktree path for an agent based on detected repositories.
+ *
+ * @param agentDir - The agent's working directory
+ * @param repoWorktrees - Array of repository names (from detectRepoWorktrees)
+ * @param fallbackPath - Path to use if no worktrees found (defaults to process.cwd())
+ * @returns The resolved worktree path
+ */
+export declare function resolveWorktreePath(agentDir: string, repoWorktrees: string[], fallbackPath?: string): string;

package/dist/lib/execution/context.js

@@ -0,0 +1,55 @@
+/**
+ * Execution Context Utilities
+ *
+ * Shared helpers for building ExecutionContext and detecting repository worktrees.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Detect git repository worktrees within an agent directory.
+ *
+ * Scans the agent directory for subdirectories that contain a .git file or folder,
+ * indicating they are git repositories (either worktrees or clones).
+ *
+ * @param agentDir - The agent's working directory
+ * @returns Array of repository directory names found within the agent directory
+ */
+export function detectRepoWorktrees(agentDir) {
+    if (!fs.existsSync(agentDir)) {
+        return [];
+    }
+    const agentContents = fs.readdirSync(agentDir);
+    return agentContents.filter(item => {
+        const itemPath = path.join(agentDir, item);
+        const gitPath = path.join(itemPath, '.git');
+        try {
+            return fs.statSync(itemPath).isDirectory() && fs.existsSync(gitPath);
+        }
+        catch {
+            // Handle permission errors or race conditions
+            return false;
+        }
+    });
+}
+/**
+ * Determine the worktree path for an agent based on detected repositories.
+ *
+ * @param agentDir - The agent's working directory
+ * @param repoWorktrees - Array of repository names (from detectRepoWorktrees)
+ * @param fallbackPath - Path to use if no worktrees found (defaults to process.cwd())
+ * @returns The resolved worktree path
+ */
+export function resolveWorktreePath(agentDir, repoWorktrees, fallbackPath) {
+    if (repoWorktrees.length === 1) {
+        // Single repo - open directly in the repo worktree
+        return path.join(agentDir, repoWorktrees[0]);
+    }
+    else if (repoWorktrees.length > 1) {
+        // Multiple repos - use agent directory, let user navigate between them
+        return agentDir;
+    }
+    else {
+        // No git worktrees found - use fallback
+        return fallbackPath ?? process.cwd();
+    }
+}

package/dist/lib/execution/devcontainer.d.ts

@@ -5,6 +5,7 @@
  * Uses a custom Dockerfile with network firewall for security sandboxing.
  */
 import { ExecutionConfig } from './types.js';
+export type MountMode = 'worktree' | 'clone';
 export interface DevcontainerOptions {
     agentName: string;
     agentDir: string;
@@ -14,6 +15,8 @@ export interface DevcontainerOptions {
     timezone?: string;
     /** prlt channel: "npm", "npm:dev", "gh", "gh:dev", "mount", or version like "npm:1.2.3" */
     prltChannel?: string;
+    /** Mount mode: 'worktree' needs parent repo mounts + git wrapper, 'clone' is self-contained */
+    mountMode?: MountMode;
 }
 export interface DevcontainerJson {
     name: string;