@proletariat/cli 0.3.16 → 0.3.18

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

@@ -13,6 +13,55 @@ export class TicketStorage {
     constructor(ctx) {
         this.ctx = ctx;
     }
+    /**
+     * Resolve a project identifier to its actual ID.
+     * Tries multiple strategies:
+     * 1. Exact ID match
+     * 2. Case-insensitive ID match
+     * 3. Exact name match
+     * 4. Case-insensitive name match
+     * 5. Slugified name match
+     */
+    resolveProjectId(identifier) {
+        if (!identifier)
+            return null;
+        // 1. Exact ID match
+        const exactMatch = this.ctx.db.prepare(`
+      SELECT id FROM ${T.projects} WHERE id = ?
+    `).get(identifier);
+        if (exactMatch)
+            return exactMatch.id;
+        // 2. Case-insensitive ID match
+        const caseInsensitiveId = this.ctx.db.prepare(`
+      SELECT id FROM ${T.projects} WHERE LOWER(id) = LOWER(?)
+    `).get(identifier);
+        if (caseInsensitiveId)
+            return caseInsensitiveId.id;
+        // 3. Exact name match
+        const nameMatch = this.ctx.db.prepare(`
+      SELECT id FROM ${T.projects} WHERE name = ?
+    `).get(identifier);
+        if (nameMatch)
+            return nameMatch.id;
+        // 4. Case-insensitive name match
+        const caseInsensitiveName = this.ctx.db.prepare(`
+      SELECT id FROM ${T.projects} WHERE LOWER(name) = LOWER(?)
+    `).get(identifier);
+        if (caseInsensitiveName)
+            return caseInsensitiveName.id;
+        // 5. Slugified name match
+        const allProjects = this.ctx.db.prepare(`
+      SELECT id, name FROM ${T.projects}
+    `).all();
+        const identifierLower = identifier.toLowerCase();
+        for (const project of allProjects) {
+            const projectSlug = slugify(project.name);
+            if (projectSlug === identifierLower || projectSlug === identifier) {
+                return project.id;
+            }
+        }
+        return null;
+    }
     /**
      * Create a new ticket.
      * Gets default status from the project's workflow.
@@ -298,11 +347,20 @@ export class TicketStorage {
     }
     /**
      * List tickets with optional filters.
-     * @param projectId - The project to filter by. Pass undefined to list all tickets across all projects.
+     * @param projectIdOrName - The project ID, name, or slug to filter by. Pass undefined to list all tickets across all projects.
      * @param filter - Additional filters to apply.
      */
-    async listTickets(projectId, filter) {
+    async listTickets(projectIdOrName, filter) {
         const params = [];
+        // Resolve project identifier to actual ID if provided
+        let resolvedProjectId;
+        if (projectIdOrName !== undefined) {
+            resolvedProjectId = this.resolveProjectId(projectIdOrName) || undefined;
+            // If resolution fails, use original value to allow normal "not found" behavior
+            if (!resolvedProjectId) {
+                resolvedProjectId = projectIdOrName;
+            }
+        }
         // Build the base query using workflow_statuses
         let query = `
       SELECT t.*,
@@ -316,9 +374,9 @@ export class TicketStorage {
       WHERE 1=1
     `;
         // Apply project scoping
-        if (projectId !== undefined) {
+        if (resolvedProjectId !== undefined) {
             query += ' AND t.project_id = ?';
-            params.push(projectId);
+            params.push(resolvedProjectId);
         }
         // If projectId is undefined, list all tickets across all projects
         if (filter?.statusId) {
@@ -363,7 +421,7 @@ export class TicketStorage {
             params.push(filter.column);
         }
         // Order by project, then status position, then priority, then created_at
-        if (projectId === undefined) {
+        if (projectIdOrName === undefined) {
             query += ` ORDER BY p.name, ws.position,
         CASE t.priority
           WHEN 'P0' THEN 0

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

@@ -3,13 +3,17 @@
  * These types are shared between storage modules but not exported publicly.
  */
 import Database from 'better-sqlite3';
+import { DrizzleDB } from '../../database/drizzle.js';
 /**
  * Base context passed to all storage modules.
- * Contains the database connection only - project ID is passed explicitly to operations.
+ * Contains both raw SQLite and Drizzle connections for gradual migration.
+ * Project ID is passed explicitly to operations.
  */
 export interface StorageContext {
-    /** Database connection */
+    /** Raw better-sqlite3 database connection (for legacy queries) */
     db: Database.Database;
+    /** Drizzle ORM database connection (for type-safe queries) */
+    drizzle: DrizzleDB;
     /** Update the board timestamp for a project */
     updateBoardTimestamp: (projectId: string) => void;
 }
@@ -57,7 +61,7 @@ export interface SpecRow {
     status: string;
     type: string | null;
     tags: string | null;
-    depends_on: string | null;
+    depends_on?: string | null;
     problem: string | null;
     solution: string | null;
     decisions: string | null;

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

@@ -6,6 +6,16 @@ import { StorageContext } from './types.js';
 export declare class ViewStorage {
     private ctx;
     constructor(ctx: StorageContext);
+    /**
+     * Resolve a project identifier to its actual ID.
+     * Tries multiple strategies:
+     * 1. Exact ID match
+     * 2. Case-insensitive ID match
+     * 3. Exact name match
+     * 4. Case-insensitive name match
+     * 5. Slugified name match
+     */
+    private resolveProjectId;
     /**
      * List board views.
      */
@@ -32,8 +42,9 @@ export declare class ViewStorage {
     getDefaultBoardView(projectId: string): Promise<BoardView | null>;
     /**
      * Get board with optional filters applied.
+     * @param projectIdOrName - Project ID, name, or slug. Will be resolved to actual ID.
      */
-    getBoardWithView(projectId: string, viewId?: string, filters?: BoardViewFilters): Promise<Board>;
+    getBoardWithView(projectIdOrName: string, viewId?: string, filters?: BoardViewFilters): Promise<Board>;
     /**
      * Get tickets for a column (workflow status) with filters applied.
      */

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

@@ -11,6 +11,55 @@ export class ViewStorage {
     constructor(ctx) {
         this.ctx = ctx;
     }
+    /**
+     * Resolve a project identifier to its actual ID.
+     * Tries multiple strategies:
+     * 1. Exact ID match
+     * 2. Case-insensitive ID match
+     * 3. Exact name match
+     * 4. Case-insensitive name match
+     * 5. Slugified name match
+     */
+    resolveProjectId(identifier) {
+        if (!identifier)
+            return null;
+        // 1. Exact ID match
+        const exactMatch = this.ctx.db.prepare(`
+      SELECT id FROM ${T.projects} WHERE id = ?
+    `).get(identifier);
+        if (exactMatch)
+            return exactMatch.id;
+        // 2. Case-insensitive ID match
+        const caseInsensitiveId = this.ctx.db.prepare(`
+      SELECT id FROM ${T.projects} WHERE LOWER(id) = LOWER(?)
+    `).get(identifier);
+        if (caseInsensitiveId)
+            return caseInsensitiveId.id;
+        // 3. Exact name match
+        const nameMatch = this.ctx.db.prepare(`
+      SELECT id FROM ${T.projects} WHERE name = ?
+    `).get(identifier);
+        if (nameMatch)
+            return nameMatch.id;
+        // 4. Case-insensitive name match
+        const caseInsensitiveName = this.ctx.db.prepare(`
+      SELECT id FROM ${T.projects} WHERE LOWER(name) = LOWER(?)
+    `).get(identifier);
+        if (caseInsensitiveName)
+            return caseInsensitiveName.id;
+        // 5. Slugified name match
+        const allProjects = this.ctx.db.prepare(`
+      SELECT id, name FROM ${T.projects}
+    `).all();
+        const identifierLower = identifier.toLowerCase();
+        for (const project of allProjects) {
+            const projectSlug = slugify(project.name);
+            if (projectSlug === identifierLower || projectSlug === identifier) {
+                return project.id;
+            }
+        }
+        return null;
+    }
     /**
      * List board views.
      */
@@ -138,8 +187,14 @@ export class ViewStorage {
     }
     /**
      * Get board with optional filters applied.
+     * @param projectIdOrName - Project ID, name, or slug. Will be resolved to actual ID.
      */
-    async getBoardWithView(projectId, viewId, filters) {
+    async getBoardWithView(projectIdOrName, viewId, filters) {
+        // Resolve project identifier to actual ID
+        const resolvedId = this.resolveProjectId(projectIdOrName);
+        if (!resolvedId) {
+            throw new PMOError('NOT_FOUND', `Project not found: ${projectIdOrName}. Run init() first.`);
+        }
         let viewFilters = {};
         let viewSortBy;
         // Load view if specified
@@ -152,15 +207,15 @@ export class ViewStorage {
         }
         // Override with explicit filters if provided
         const effectiveFilters = { ...viewFilters, ...filters };
-        // Get project metadata
-        const projectRow = this.ctx.db.prepare(`SELECT * FROM ${T.projects} WHERE id = ?`).get(projectId);
+        // Get project metadata using resolved ID
+        const projectRow = this.ctx.db.prepare(`SELECT * FROM ${T.projects} WHERE id = ?`).get(resolvedId);
         if (!projectRow) {
-            throw new PMOError('NOT_FOUND', `Project not found: ${projectId}. Run init() first.`);
+            throw new PMOError('NOT_FOUND', `Project not found: ${projectIdOrName}. Run init() first.`);
         }
         // Get the project's workflow
         const projectMeta = this.ctx.db.prepare(`
       SELECT workflow_id FROM ${T.projects} WHERE id = ?
-    `).get(projectId);
+    `).get(resolvedId);
         const workflowId = projectMeta?.workflow_id || 'default';
         // Get workflow statuses as columns
         const columnRows = this.ctx.db.prepare(`
@@ -175,7 +230,7 @@ export class ViewStorage {
             : columnRows;
         // Get tickets with filters applied
         const columns = await Promise.all(filteredColumnRows.map(async (col) => {
-            const tickets = await this.getTicketsForColumnWithFilters(col.id, projectId, effectiveFilters);
+            const tickets = await this.getTicketsForColumnWithFilters(col.id, resolvedId, effectiveFilters);
             // Apply sorting if specified
             const sortedTickets = viewSortBy ? this.sortTickets(tickets, viewSortBy) : tickets;
             return {

package/dist/lib/prompt-command.d.ts

@@ -0,0 +1,90 @@
+import { Command } from '@oclif/core';
+import { type JsonFlags } from './prompt-json.js';
+/**
+ * Lightweight base command with prompt() method for JSON mode support.
+ *
+ * Extends oclif Command with a drop-in replacement for inquirer.prompt()
+ * that works in both interactive and JSON/agent modes. Use this as the
+ * base class for commands that need interactive prompts but don't require
+ * PMO database context (for PMO commands, use PMOCommand which extends this).
+ *
+ * Usage:
+ * ```typescript
+ * import { PromptCommand } from '../../lib/prompt-command.js';
+ *
+ * export default class MyCommand extends PromptCommand {
+ *   async run(): Promise<void> {
+ *     const { flags } = await this.parse(MyCommand);
+ *     const { selection } = await this.prompt([{
+ *       type: 'list',
+ *       name: 'selection',
+ *       message: 'Pick one:',
+ *       choices: items.map(i => ({
+ *         name: i.name,
+ *         value: i.id,
+ *         command: `prlt my-command --selection "${i.id}" --json`,
+ *       })),
+ *     }], { flags, commandName: 'my-command' });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class PromptCommand extends Command {
+    /**
+     * Prompt wrapper - drop-in replacement for inquirer.prompt
+     *
+     * Works in BOTH modes:
+     * - Interactive mode: calls inquirer.prompt normally (human sees menu)
+     * - JSON/Agent mode: outputs prompt as structured JSON and exits
+     *
+     * This is the simplest way to make any inquirer.prompt call work for both humans and agents.
+     * Just replace `await inquirer.prompt(questions)` with `await this.prompt(questions, jsonModeConfig)`
+     *
+     * @param questions - Inquirer question config(s)
+     * @param jsonModeConfig - JSON mode configuration (null to disable JSON mode handling)
+     * @returns Answers object (only in interactive mode)
+     *
+     * @example
+     * ```typescript
+     * // Before (breaks in JSON mode):
+     * const { column } = await inquirer.prompt([{
+     *   type: 'list',
+     *   name: 'column',
+     *   message: 'Select column:',
+     *   choices: columns.map(c => ({ name: c, value: c })),
+     * }]);
+     *
+     * // After (works in both modes):
+     * const { column } = await this.prompt([{
+     *   type: 'list',
+     *   name: 'column',
+     *   message: 'Select column:',
+     *   choices: columns.map(c => ({
+     *     name: c,
+     *     value: c,
+     *     command: `prlt ticket move --column "${c}" --json`,
+     *   })),
+     * }], {
+     *   flags,
+     *   commandName: 'ticket move',
+     * });
+     * ```
+     */
+    protected prompt<T extends Record<string, unknown>>(questions: Array<{
+        type: string;
+        name: string;
+        message: string;
+        choices?: Array<string | {
+            name: string;
+            value: unknown;
+            disabled?: boolean | string;
+            command?: string;
+        } | unknown>;
+        default?: unknown;
+        validate?: (input: unknown) => boolean | string;
+        when?: boolean | ((answers: Record<string, unknown>) => boolean);
+    }>, jsonModeConfig?: {
+        flags: JsonFlags & Record<string, unknown>;
+        commandName: string;
+    } | null): Promise<T>;
+}

package/dist/lib/prompt-command.js

@@ -0,0 +1,102 @@
+import { Command } from '@oclif/core';
+import inquirer from 'inquirer';
+import { isAgentMode, outputPromptAsJson, createMetadata, normalizeChoices, } from './prompt-json.js';
+/**
+ * Lightweight base command with prompt() method for JSON mode support.
+ *
+ * Extends oclif Command with a drop-in replacement for inquirer.prompt()
+ * that works in both interactive and JSON/agent modes. Use this as the
+ * base class for commands that need interactive prompts but don't require
+ * PMO database context (for PMO commands, use PMOCommand which extends this).
+ *
+ * Usage:
+ * ```typescript
+ * import { PromptCommand } from '../../lib/prompt-command.js';
+ *
+ * export default class MyCommand extends PromptCommand {
+ *   async run(): Promise<void> {
+ *     const { flags } = await this.parse(MyCommand);
+ *     const { selection } = await this.prompt([{
+ *       type: 'list',
+ *       name: 'selection',
+ *       message: 'Pick one:',
+ *       choices: items.map(i => ({
+ *         name: i.name,
+ *         value: i.id,
+ *         command: `prlt my-command --selection "${i.id}" --json`,
+ *       })),
+ *     }], { flags, commandName: 'my-command' });
+ *   }
+ * }
+ * ```
+ */
+export class PromptCommand extends Command {
+    /**
+     * Prompt wrapper - drop-in replacement for inquirer.prompt
+     *
+     * Works in BOTH modes:
+     * - Interactive mode: calls inquirer.prompt normally (human sees menu)
+     * - JSON/Agent mode: outputs prompt as structured JSON and exits
+     *
+     * This is the simplest way to make any inquirer.prompt call work for both humans and agents.
+     * Just replace `await inquirer.prompt(questions)` with `await this.prompt(questions, jsonModeConfig)`
+     *
+     * @param questions - Inquirer question config(s)
+     * @param jsonModeConfig - JSON mode configuration (null to disable JSON mode handling)
+     * @returns Answers object (only in interactive mode)
+     *
+     * @example
+     * ```typescript
+     * // Before (breaks in JSON mode):
+     * const { column } = await inquirer.prompt([{
+     *   type: 'list',
+     *   name: 'column',
+     *   message: 'Select column:',
+     *   choices: columns.map(c => ({ name: c, value: c })),
+     * }]);
+     *
+     * // After (works in both modes):
+     * const { column } = await this.prompt([{
+     *   type: 'list',
+     *   name: 'column',
+     *   message: 'Select column:',
+     *   choices: columns.map(c => ({
+     *     name: c,
+     *     value: c,
+     *     command: `prlt ticket move --column "${c}" --json`,
+     *   })),
+     * }], {
+     *   flags,
+     *   commandName: 'ticket move',
+     * });
+     * ```
+     */
+    async prompt(questions, jsonModeConfig) {
+        // Auto-detect non-TTY: switch to JSON mode when no TTY present
+        if (!jsonModeConfig && !process.stdin.isTTY) {
+            jsonModeConfig = { flags: { json: true }, commandName: this.id ?? 'unknown' };
+        }
+        // Check for JSON/agent mode
+        if (jsonModeConfig && isAgentMode(jsonModeConfig.flags)) {
+            // Find first question that should be shown (respecting 'when' conditions)
+            const firstQuestion = questions[0];
+            if (firstQuestion) {
+                // Convert choices to agent-compatible format
+                const choices = firstQuestion.choices
+                    ? normalizeChoices(firstQuestion.choices)
+                    : undefined;
+                outputPromptAsJson({
+                    type: firstQuestion.type,
+                    name: firstQuestion.name,
+                    message: firstQuestion.message,
+                    choices,
+                    default: firstQuestion.default,
+                }, createMetadata(jsonModeConfig.commandName, jsonModeConfig.flags));
+                // outputPromptAsJson calls process.exit, never returns
+            }
+            return {};
+        }
+        // Interactive mode: just call inquirer
+        return inquirer.prompt(questions);
+    }
+}

package/dist/lib/prompt-json.d.ts

@@ -128,11 +128,22 @@ export interface ErrorJsonOutput {
  */
 export type JsonOutput = PromptJsonOutput | SuccessJsonOutput | ErrorJsonOutput;
 /**
- * Flags interface for shouldOutputJson
+ * Flags interface for JSON mode detection (legacy)
+ * @deprecated Use MachineOutputFlags instead
  */
 export interface JsonFlags {
     json?: boolean;
 }
+/**
+ * Flags interface for machine-readable output mode detection
+ * Supports both new --machine format and legacy --json boolean
+ */
+export interface MachineOutputFlags {
+    /** New format: --machine (enables machine-readable JSON output for AI agents) */
+    machine?: boolean;
+    /** Legacy format: --json (deprecated, use --machine instead) */
+    json?: boolean;
+}
 /**
  * Check if the current environment is non-TTY (piped output)
  *
@@ -140,16 +151,35 @@ export interface JsonFlags {
  */
 export declare function isNonTTY(): boolean;
 /**
- * Determine if JSON output should be used
+ * Determine if JSON output mode is active (for AI agents)
  *
  * Returns true if:
+ * - The --machine flag is explicitly set
  * - The --json flag is explicitly set
  * - The environment is non-TTY (piped output)
  *
  * @param flags - Command flags object
- * @returns true if JSON output should be used
+ * @returns true if JSON mode should be used
+ */
+export declare function shouldOutputJson(flags: JsonFlags & {
+    machine?: boolean;
+}): boolean;
+/**
+ * Alias for shouldOutputJson - clearer name for agent-focused code
+ */
+export declare const isAgentMode: typeof shouldOutputJson;
+/**
+ * Determine if machine-readable output mode is active (for AI agents/scripts)
+ *
+ * Returns true if:
+ * - The --machine flag is set
+ * - The --json flag is explicitly set (legacy support)
+ * - The environment is non-TTY (piped output)
+ *
+ * @param flags - Command flags object
+ * @returns true if machine-readable output mode should be used
  */
-export declare function shouldOutputJson(flags: JsonFlags): boolean;
+export declare function isMachineOutput(flags: MachineOutputFlags): boolean;
 /**
  * Create metadata object for JSON output
  *

package/dist/lib/prompt-json.js

@@ -38,17 +38,49 @@ export function isNonTTY() {
     return !process.stdout.isTTY;
 }
 /**
- * Determine if JSON output should be used
+ * Determine if JSON output mode is active (for AI agents)
  *
  * Returns true if:
+ * - The --machine flag is explicitly set
  * - The --json flag is explicitly set
  * - The environment is non-TTY (piped output)
  *
  * @param flags - Command flags object
- * @returns true if JSON output should be used
+ * @returns true if JSON mode should be used
  */
 export function shouldOutputJson(flags) {
-    // Explicit flag takes precedence
+    // New --machine flag
+    if (flags.machine === true) {
+        return true;
+    }
+    // Legacy --json flag
+    if (flags.json === true) {
+        return true;
+    }
+    // Automatic detection for non-TTY environments
+    return isNonTTY();
+}
+/**
+ * Alias for shouldOutputJson - clearer name for agent-focused code
+ */
+export const isAgentMode = shouldOutputJson;
+/**
+ * Determine if machine-readable output mode is active (for AI agents/scripts)
+ *
+ * Returns true if:
+ * - The --machine flag is set
+ * - The --json flag is explicitly set (legacy support)
+ * - The environment is non-TTY (piped output)
+ *
+ * @param flags - Command flags object
+ * @returns true if machine-readable output mode should be used
+ */
+export function isMachineOutput(flags) {
+    // New --machine flag takes precedence
+    if (flags.machine === true) {
+        return true;
+    }
+    // Legacy --json flag support
     if (flags.json === true) {
         return true;
     }

package/dist/lib/repos/index.js

@@ -497,21 +497,21 @@ export async function removeRepository(hqPath, repoName, keepFiles = false) {
  */
 async function createWorktreesForRepo(hqPath, repoName, repoPath) {
     const db = openWorkspaceDatabase(hqPath);
-    // Get workspace config for theme info
-    const workspace = db.prepare('SELECT theme FROM workspace').get();
-    const theme = db.prepare('SELECT workspace_dir FROM themes WHERE name = ?').get(workspace.theme);
-    // Get all agents
-    const agents = db.prepare('SELECT name FROM agents').all();
+    // Get all agents with their worktree paths
+    const agents = db.prepare('SELECT name, worktree_path FROM agents WHERE status = \'active\' OR status IS NULL').all();
     if (agents.length === 0) {
         db.close();
         return;
     }
-    const agentsBasePath = path.join(hqPath, 'agents', theme.workspace_dir);
     for (const agent of agents) {
+        // Skip agents without a worktree path
+        if (!agent.worktree_path) {
+            continue;
+        }
         // Name worktree directory as {repoName}-{agentName} so git creates unique worktree entries
         // e.g., proletariat-branson instead of proletariat (which causes proletariat1, proletariat2, etc.)
         const worktreeDirName = `${repoName}-${agent.name}`;
-        const agentRepoPath = path.join(agentsBasePath, agent.name, worktreeDirName);
+        const agentRepoPath = path.join(hqPath, agent.worktree_path, worktreeDirName);
         const branchName = `agent-${agent.name}`;
         try {
             // Create worktree
@@ -524,7 +524,7 @@ async function createWorktreesForRepo(hqPath, repoName, repoPath) {
         INSERT OR REPLACE INTO agent_worktrees
         (agent_name, repo_name, worktree_path, branch, created_at, commits_ahead, is_clean)
         VALUES (?, ?, ?, ?, ?, 0, 1)
-      `).run(agent.name, repoName, `agents/${theme.workspace_dir}/${agent.name}/${worktreeDirName}`, branchName, new Date().toISOString());
+      `).run(agent.name, repoName, `${agent.worktree_path}/${worktreeDirName}`, branchName, new Date().toISOString());
         }
         catch {
             console.log(chalk.yellow(`Warning: Could not create worktree for ${agent.name}/${repoName}`));
@@ -537,15 +537,15 @@ async function createWorktreesForRepo(hqPath, repoName, repoPath) {
  */
 async function removeWorktreesForRepo(hqPath, repoName) {
     const db = openWorkspaceDatabase(hqPath);
-    // Get workspace config for theme info
-    const workspace = db.prepare('SELECT theme FROM workspace').get();
-    const theme = db.prepare('SELECT workspace_dir FROM themes WHERE name = ?').get(workspace.theme);
-    // Get all agents
-    const agents = db.prepare('SELECT name FROM agents').all();
+    // Get all agents with their worktree paths
+    const agents = db.prepare('SELECT name, worktree_path FROM agents').all();
     const repoPath = path.join(hqPath, 'repos', repoName);
-    const agentsBasePath = path.join(hqPath, 'agents', theme.workspace_dir);
     for (const agent of agents) {
-        const agentRepoPath = path.join(agentsBasePath, agent.name, repoName);
+        // Skip agents without a worktree path
+        if (!agent.worktree_path) {
+            continue;
+        }
+        const agentRepoPath = path.join(hqPath, agent.worktree_path, repoName);
         try {
             // Remove worktree from git
             if (fs.existsSync(repoPath)) {

package/dist/lib/workspace.d.ts

@@ -2,7 +2,7 @@
  * Central headquarters resolution utilities.
  *
  * Search priority:
- * 1. PRLT_HQ_PATH env var (ONLY when DEVCONTAINER=true - for devcontainer mounts)
+ * 1. PRLT_HQ_PATH env var (ONLY when DEVCONTAINER=true or PRLT_TEST_ENV=true)
  * 2. Walk up directory tree looking for .proletariat/config.json with type='hq'
  *    - If found but not registered, emit warning to register
  * 3. ~/.proletariat/config.json activeHeadquarters (fallback when NOT in any HQ)
@@ -12,8 +12,9 @@
  * working in different HQs simultaneously. Each agent uses the HQ
  * they're physically in, not a global env var that could cause conflicts.
  *
- * For testing HQ isolation, see TKT-400.
- * For CI/CD HQ isolation, see TKT-401.
+ * Environment variables:
+ * - DEVCONTAINER=true: Enables PRLT_HQ_PATH (for devcontainer mounts)
+ * - PRLT_TEST_ENV=true: Enables PRLT_HQ_PATH (for E2E test isolation)
  */
 export interface WorkspaceLocation {
     path: string;

package/dist/lib/workspace.js

@@ -22,11 +22,11 @@ export function findHQRoot(startDir = process.cwd()) {
  * Useful for debugging and logging where the workspace was resolved from.
  */
 export function findHQRootWithSource(startDir = process.cwd()) {
-    // 1. Check PRLT_HQ_PATH environment variable (only in devcontainers)
+    // 1. Check PRLT_HQ_PATH environment variable (only in devcontainers or test environments)
     // On host machines, we use directory walk to support multiple workspaces/agents
     const envHqPath = process.env.PRLT_HQ_PATH;
-    const isDevcontainer = process.env.DEVCONTAINER === 'true';
-    if (envHqPath && isDevcontainer) {
+    const allowEnvHqPath = process.env.DEVCONTAINER === 'true' || process.env.PRLT_TEST_ENV === 'true';
+    if (envHqPath && allowEnvHqPath) {
         const resolvedPath = path.resolve(envHqPath);
         // Validate it's actually an HQ
         if (isValidHQ(resolvedPath)) {