cortex-agents 2.3.1 → 3.4.0

package/dist/utils/plan-extract.js

@@ -2,6 +2,25 @@ import * as fs from "fs";
 import * as path from "path";
 const CORTEX_DIR = ".cortex";
 const PLANS_DIR = "plans";
+/**
+ * Extract GitHub issue references from plan frontmatter.
+ *
+ * Looks for `issues: [42, 51]` in YAML frontmatter.
+ * Returns an array of issue numbers, or an empty array if none found.
+ */
+export function extractIssueRefs(planContent) {
+    const frontmatterMatch = planContent.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch)
+        return [];
+    // Match issues: [42, 51] or issues: [42]
+    const issuesMatch = frontmatterMatch[1].match(/issues:\s*\[([^\]]*)\]/);
+    if (!issuesMatch)
+        return [];
+    return issuesMatch[1]
+        .split(",")
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => !isNaN(n) && n > 0);
+}
 /**
  * Extract relevant sections from a plan markdown file for composing a PR body.
  *
@@ -106,7 +125,12 @@ export function findPlanContent(worktree, planFilename, branchName) {
     if (!fs.existsSync(plansDir))
         return null;
     if (planFilename) {
-        const filepath = path.join(plansDir, planFilename);
+        // Prevent path traversal — resolve and verify the path is strictly inside plansDir
+        const filepath = path.resolve(plansDir, planFilename);
+        const resolvedPlansDir = path.resolve(plansDir);
+        if (!filepath.startsWith(resolvedPlansDir + path.sep)) {
+            return null; // Reject traversal attempts and directory-level references (".", "")
+        }
         if (fs.existsSync(filepath)) {
             return { content: fs.readFileSync(filepath, "utf-8"), filename: planFilename };
         }

package/dist/utils/repl.d.ts

@@ -0,0 +1,114 @@
+/**
+ * REPL Loop Utilities
+ *
+ * State management, plan task parsing, build/test command auto-detection,
+ * and progress formatting for the implement agent's iterative task loop.
+ *
+ * State is persisted to `.cortex/repl-state.json` so it survives context
+ * compaction, session restarts, and agent switches.
+ */
+export type TaskStatus = "pending" | "in_progress" | "passed" | "failed" | "skipped";
+export interface TaskIteration {
+    /** ISO timestamp of this iteration */
+    at: string;
+    /** Outcome of this iteration */
+    result: "pass" | "fail" | "skip";
+    /** Test output summary, error message, or skip reason */
+    detail: string;
+}
+export interface ReplTask {
+    /** Zero-based index in the task list */
+    index: number;
+    /** Task description from the plan */
+    description: string;
+    /** Current status in the state machine */
+    status: TaskStatus;
+    /** Number of failed attempts (resets on pass) */
+    retries: number;
+    /** Full iteration history */
+    iterations: TaskIteration[];
+}
+export interface ReplState {
+    /** Source plan filename */
+    planFilename: string;
+    /** ISO timestamp when the loop started */
+    startedAt: string;
+    /** ISO timestamp when the loop completed (all tasks done or aborted) */
+    completedAt?: string;
+    /** Auto-detected or user-provided build command */
+    buildCommand: string | null;
+    /** Auto-detected or user-provided test command */
+    testCommand: string | null;
+    /** Optional lint command */
+    lintCommand: string | null;
+    /** Max retries per task before escalating to user (default: 3) */
+    maxRetries: number;
+    /** Index of the currently active task (-1 if not started) */
+    currentTaskIndex: number;
+    /** All tasks in the loop */
+    tasks: ReplTask[];
+}
+export interface CommandDetection {
+    buildCommand: string | null;
+    testCommand: string | null;
+    lintCommand: string | null;
+    /** Detected framework name (e.g., "vitest", "jest", "pytest") */
+    framework: string;
+    /** Whether auto-detection found anything */
+    detected: boolean;
+}
+/**
+ * Parse plan tasks from plan markdown content.
+ *
+ * Looks for unchecked checkbox items (`- [ ] ...`) in a `## Tasks` section.
+ * Falls back to any unchecked checkboxes anywhere in the document.
+ * Strips the `Task N:` prefix if present to get a clean description.
+ */
+export declare function parseTasksFromPlan(planContent: string): string[];
+/**
+ * Auto-detect build, test, and lint commands from project configuration files.
+ *
+ * Detection priority:
+ *   1. package.json (npm/node projects)
+ *   2. Makefile
+ *   3. Cargo.toml (Rust)
+ *   4. go.mod (Go)
+ *   5. pyproject.toml / setup.py (Python)
+ *   6. mix.exs (Elixir)
+ */
+export declare function detectCommands(cwd: string): Promise<CommandDetection>;
+/**
+ * Read the current REPL state from .cortex/repl-state.json.
+ * Returns null if no state file exists.
+ */
+export declare function readReplState(cwd: string): ReplState | null;
+/**
+ * Write REPL state to .cortex/repl-state.json.
+ * Uses atomic write (temp file + rename) to prevent corruption.
+ */
+export declare function writeReplState(cwd: string, state: ReplState): void;
+/**
+ * Get the next pending task (first task with status "pending").
+ * Returns null if all tasks are done.
+ */
+export declare function getNextTask(state: ReplState): ReplTask | null;
+/**
+ * Get the currently in-progress task.
+ * Returns null if no task is in progress.
+ */
+export declare function getCurrentTask(state: ReplState): ReplTask | null;
+/**
+ * Check if the loop is complete (no pending or in_progress tasks).
+ */
+export declare function isLoopComplete(state: ReplState): boolean;
+/**
+ * Format the current loop status as a human-readable string.
+ * Used by repl_status tool output.
+ */
+export declare function formatProgress(state: ReplState): string;
+/**
+ * Format a full summary of the loop results for PR body inclusion.
+ * Returns a markdown block with a results table, counts, and timing.
+ */
+export declare function formatSummary(state: ReplState): string;
+//# sourceMappingURL=repl.d.ts.map

package/dist/utils/repl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../../src/utils/repl.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAErF,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,MAAM,EAAE,UAAU,CAAC;IACnB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kDAAkD;IAClD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4BAA4B;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,CAAC;IACzB,4BAA4B;IAC5B,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAsBhE;AA4BD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6H3E;AAWD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAwB3D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAuBlE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAIxD;AAWD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAwEvD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CA+EtD"}

package/dist/utils/repl.js

@@ -0,0 +1,434 @@
+/**
+ * REPL Loop Utilities
+ *
+ * State management, plan task parsing, build/test command auto-detection,
+ * and progress formatting for the implement agent's iterative task loop.
+ *
+ * State is persisted to `.cortex/repl-state.json` so it survives context
+ * compaction, session restarts, and agent switches.
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const CORTEX_DIR = ".cortex";
+const REPL_STATE_FILE = "repl-state.json";
+// ─── Task Parsing ────────────────────────────────────────────────────────────
+/**
+ * Parse plan tasks from plan markdown content.
+ *
+ * Looks for unchecked checkbox items (`- [ ] ...`) in a `## Tasks` section.
+ * Falls back to any unchecked checkboxes anywhere in the document.
+ * Strips the `Task N:` prefix if present to get a clean description.
+ */
+export function parseTasksFromPlan(planContent) {
+    // Try to find a ## Tasks section first
+    const tasksSection = extractTasksSection(planContent);
+    const source = tasksSection || planContent;
+    const tasks = [];
+    const lines = source.split("\n");
+    for (const line of lines) {
+        // Match unchecked checkbox items: - [ ] Description
+        const match = line.match(/^[-*]\s*\[\s\]\s+(.+)$/);
+        if (match) {
+            let description = match[1].trim();
+            // Strip "Task N:" prefix if present
+            description = description.replace(/^Task\s+\d+\s*:\s*/i, "");
+            if (description) {
+                tasks.push(description);
+            }
+        }
+    }
+    return tasks;
+}
+/**
+ * Extract the content of the ## Tasks section from plan markdown.
+ * Returns null if no Tasks section found.
+ */
+function extractTasksSection(content) {
+    const lines = content.split("\n");
+    let inTasksSection = false;
+    const sectionLines = [];
+    for (const line of lines) {
+        if (/^##\s+Tasks/i.test(line)) {
+            inTasksSection = true;
+            continue;
+        }
+        if (inTasksSection) {
+            // End of section when we hit another ## heading
+            if (/^##\s+/.test(line))
+                break;
+            sectionLines.push(line);
+        }
+    }
+    return sectionLines.length > 0 ? sectionLines.join("\n") : null;
+}
+// ─── Command Auto-Detection ──────────────────────────────────────────────────
+/**
+ * Auto-detect build, test, and lint commands from project configuration files.
+ *
+ * Detection priority:
+ *   1. package.json (npm/node projects)
+ *   2. Makefile
+ *   3. Cargo.toml (Rust)
+ *   4. go.mod (Go)
+ *   5. pyproject.toml / setup.py (Python)
+ *   6. mix.exs (Elixir)
+ */
+export async function detectCommands(cwd) {
+    const result = {
+        buildCommand: null,
+        testCommand: null,
+        lintCommand: null,
+        framework: "unknown",
+        detected: false,
+    };
+    // 1. Check package.json (most common for this project type)
+    const pkgPath = path.join(cwd, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            const scripts = pkg.scripts || {};
+            const devDeps = pkg.devDependencies || {};
+            const deps = pkg.dependencies || {};
+            // Build command
+            if (scripts.build) {
+                result.buildCommand = "npm run build";
+            }
+            // Test command — prefer specific runner detection
+            if (devDeps.vitest || deps.vitest) {
+                result.testCommand = "npx vitest run";
+                result.framework = "vitest";
+            }
+            else if (devDeps.jest || deps.jest) {
+                result.testCommand = "npx jest";
+                result.framework = "jest";
+            }
+            else if (devDeps.mocha || deps.mocha) {
+                result.testCommand = "npx mocha";
+                result.framework = "mocha";
+            }
+            else if (scripts.test && scripts.test !== 'echo "Error: no test specified" && exit 1') {
+                result.testCommand = "npm test";
+                result.framework = "npm-test";
+            }
+            // Lint command
+            if (scripts.lint) {
+                result.lintCommand = "npm run lint";
+            }
+            result.detected = !!(result.buildCommand || result.testCommand);
+            if (result.detected)
+                return result;
+        }
+        catch {
+            // Malformed package.json — continue to next detector
+        }
+    }
+    // 2. Check Makefile
+    const makefilePath = path.join(cwd, "Makefile");
+    if (fs.existsSync(makefilePath)) {
+        try {
+            const makefile = fs.readFileSync(makefilePath, "utf-8");
+            if (/^build\s*:/m.test(makefile)) {
+                result.buildCommand = "make build";
+            }
+            if (/^test\s*:/m.test(makefile)) {
+                result.testCommand = "make test";
+                result.framework = "make";
+            }
+            if (/^lint\s*:/m.test(makefile)) {
+                result.lintCommand = "make lint";
+            }
+            result.detected = !!(result.buildCommand || result.testCommand);
+            if (result.detected)
+                return result;
+        }
+        catch {
+            // Continue to next detector
+        }
+    }
+    // 3. Check Cargo.toml (Rust)
+    if (fs.existsSync(path.join(cwd, "Cargo.toml"))) {
+        result.buildCommand = "cargo build";
+        result.testCommand = "cargo test";
+        result.framework = "cargo";
+        result.detected = true;
+        return result;
+    }
+    // 4. Check go.mod (Go)
+    if (fs.existsSync(path.join(cwd, "go.mod"))) {
+        result.buildCommand = "go build ./...";
+        result.testCommand = "go test ./...";
+        result.framework = "go-test";
+        result.detected = true;
+        return result;
+    }
+    // 5. Check pyproject.toml or setup.py (Python)
+    const pyprojectPath = path.join(cwd, "pyproject.toml");
+    if (fs.existsSync(pyprojectPath)) {
+        try {
+            const pyproject = fs.readFileSync(pyprojectPath, "utf-8");
+            if (pyproject.includes("pytest")) {
+                result.testCommand = "pytest";
+                result.framework = "pytest";
+            }
+            else {
+                result.testCommand = "python -m pytest";
+                result.framework = "pytest";
+            }
+            result.detected = true;
+            return result;
+        }
+        catch {
+            // Continue
+        }
+    }
+    if (fs.existsSync(path.join(cwd, "setup.py"))) {
+        result.testCommand = "python -m pytest";
+        result.framework = "pytest";
+        result.detected = true;
+        return result;
+    }
+    // 6. Check mix.exs (Elixir)
+    if (fs.existsSync(path.join(cwd, "mix.exs"))) {
+        result.buildCommand = "mix compile";
+        result.testCommand = "mix test";
+        result.framework = "ExUnit";
+        result.detected = true;
+        return result;
+    }
+    return result;
+}
+// ─── State Management ────────────────────────────────────────────────────────
+/**
+ * Get the path to the REPL state file.
+ */
+function statePath(cwd) {
+    return path.join(cwd, CORTEX_DIR, REPL_STATE_FILE);
+}
+/**
+ * Read the current REPL state from .cortex/repl-state.json.
+ * Returns null if no state file exists.
+ */
+export function readReplState(cwd) {
+    const filepath = statePath(cwd);
+    if (!fs.existsSync(filepath))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(filepath, "utf-8"));
+        // Runtime shape validation — reject corrupted or tampered state
+        if (typeof raw !== "object" ||
+            raw === null ||
+            typeof raw.planFilename !== "string" ||
+            typeof raw.startedAt !== "string" ||
+            typeof raw.maxRetries !== "number" ||
+            typeof raw.currentTaskIndex !== "number" ||
+            !Array.isArray(raw.tasks)) {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write REPL state to .cortex/repl-state.json.
+ * Uses atomic write (temp file + rename) to prevent corruption.
+ */
+export function writeReplState(cwd, state) {
+    const filepath = statePath(cwd);
+    const dir = path.dirname(filepath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Atomic write: write to unique temp file, then rename
+    const suffix = crypto.randomBytes(6).toString("hex");
+    const tmpPath = `${filepath}.${suffix}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2));
+        fs.renameSync(tmpPath, filepath);
+    }
+    catch (err) {
+        // Clean up temp file on failure
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw err;
+    }
+}
+/**
+ * Get the next pending task (first task with status "pending").
+ * Returns null if all tasks are done.
+ */
+export function getNextTask(state) {
+    return state.tasks.find((t) => t.status === "pending") ?? null;
+}
+/**
+ * Get the currently in-progress task.
+ * Returns null if no task is in progress.
+ */
+export function getCurrentTask(state) {
+    return state.tasks.find((t) => t.status === "in_progress") ?? null;
+}
+/**
+ * Check if the loop is complete (no pending or in_progress tasks).
+ */
+export function isLoopComplete(state) {
+    return state.tasks.every((t) => t.status === "passed" || t.status === "failed" || t.status === "skipped");
+}
+// ─── Formatting ──────────────────────────────────────────────────────────────
+/** Visual progress bar using block characters. */
+function progressBar(done, total, width = 20) {
+    if (total === 0)
+        return "░".repeat(width);
+    const filled = Math.round((done / total) * width);
+    return "█".repeat(filled) + "░".repeat(width - filled);
+}
+/**
+ * Format the current loop status as a human-readable string.
+ * Used by repl_status tool output.
+ */
+export function formatProgress(state) {
+    const total = state.tasks.length;
+    const passed = state.tasks.filter((t) => t.status === "passed").length;
+    const failed = state.tasks.filter((t) => t.status === "failed").length;
+    const skipped = state.tasks.filter((t) => t.status === "skipped").length;
+    const done = passed + failed + skipped;
+    const pending = state.tasks.filter((t) => t.status === "pending").length;
+    const pct = total > 0 ? Math.round((done / total) * 100) : 0;
+    const lines = [];
+    lines.push(`Progress: ${progressBar(done, total)} ${done}/${total} tasks (${pct}%)`);
+    lines.push(`  Passed: ${passed}  |  Failed: ${failed}  |  Skipped: ${skipped}  |  Pending: ${pending}`);
+    // Current or next task
+    const current = getCurrentTask(state);
+    const next = getNextTask(state);
+    if (current) {
+        lines.push("");
+        lines.push(`Current Task (#${current.index + 1}):`);
+        lines.push(`  "${current.description}"`);
+        if (current.retries > 0) {
+            lines.push(`  Attempt: ${current.retries + 1}/${state.maxRetries}`);
+        }
+    }
+    else if (next) {
+        lines.push("");
+        lines.push(`Next Task (#${next.index + 1}):`);
+        lines.push(`  "${next.description}"`);
+    }
+    else if (isLoopComplete(state)) {
+        lines.push("");
+        lines.push("All tasks complete.");
+    }
+    // Commands
+    lines.push("");
+    lines.push(`Build: ${state.buildCommand || "(not detected)"}`);
+    lines.push(`Test:  ${state.testCommand || "(not detected)"}`);
+    if (state.lintCommand) {
+        lines.push(`Lint:  ${state.lintCommand}`);
+    }
+    lines.push(`Max retries: ${state.maxRetries}`);
+    // Task history
+    lines.push("");
+    lines.push("Task History:");
+    for (const task of state.tasks) {
+        const num = `#${task.index + 1}`;
+        const iterInfo = task.iterations.length > 0
+            ? ` (${task.iterations.length} iteration${task.iterations.length > 1 ? "s" : ""}${task.retries > 0 ? `, ${task.retries} retr${task.retries > 1 ? "ies" : "y"}` : ""})`
+            : "";
+        switch (task.status) {
+            case "passed":
+                lines.push(`  \u2713 ${num} ${task.description}${iterInfo}`);
+                break;
+            case "failed":
+                lines.push(`  \u2717 ${num} ${task.description}${iterInfo}`);
+                break;
+            case "skipped":
+                lines.push(`  \u2298 ${num} ${task.description}`);
+                break;
+            case "in_progress":
+                lines.push(`  \u25B6 ${num} ${task.description}${iterInfo}`);
+                break;
+            case "pending":
+                lines.push(`  \u25CB ${num} ${task.description}`);
+                break;
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Format a full summary of the loop results for PR body inclusion.
+ * Returns a markdown block with a results table, counts, and timing.
+ */
+export function formatSummary(state) {
+    const total = state.tasks.length;
+    const passed = state.tasks.filter((t) => t.status === "passed").length;
+    const failed = state.tasks.filter((t) => t.status === "failed").length;
+    const skipped = state.tasks.filter((t) => t.status === "skipped").length;
+    const totalIterations = state.tasks.reduce((sum, t) => sum + t.iterations.length, 0);
+    const lines = [];
+    lines.push("## REPL Loop Summary");
+    lines.push("");
+    lines.push("| # | Task | Status | Attempts |");
+    lines.push("|---|------|--------|----------|");
+    for (const task of state.tasks) {
+        const num = task.index + 1;
+        // Truncate long descriptions for the table and sanitize for markdown
+        const rawDesc = task.description.length > 60
+            ? task.description.substring(0, 57) + "..."
+            : task.description;
+        const desc = rawDesc.replace(/\|/g, "\\|").replace(/\n/g, " ");
+        let statusIcon;
+        let attempts;
+        switch (task.status) {
+            case "passed":
+                statusIcon = "Passed";
+                attempts = String(task.iterations.length);
+                break;
+            case "failed":
+                statusIcon = "Failed";
+                attempts = String(task.iterations.length);
+                break;
+            case "skipped":
+                statusIcon = "Skipped";
+                attempts = "—";
+                break;
+            case "in_progress":
+                statusIcon = "In Progress";
+                attempts = String(task.iterations.length);
+                break;
+            default:
+                statusIcon = "Pending";
+                attempts = "—";
+        }
+        lines.push(`| ${num} | ${desc} | ${statusIcon} | ${attempts} |`);
+    }
+    lines.push("");
+    lines.push(`**Results: ${passed} passed, ${failed} failed, ${skipped} skipped** (${totalIterations} total iterations)`);
+    // Timing
+    if (state.startedAt) {
+        const start = new Date(state.startedAt);
+        const end = state.completedAt ? new Date(state.completedAt) : new Date();
+        const durationMs = end.getTime() - start.getTime();
+        const durationMin = Math.round(durationMs / 60_000);
+        lines.push(`Duration: ${durationMin > 0 ? `${durationMin} minute${durationMin > 1 ? "s" : ""}` : "< 1 minute"}`);
+    }
+    lines.push(`Plan: ${state.planFilename}`);
+    // List failed tasks with details if any
+    const failedTasks = state.tasks.filter((t) => t.status === "failed");
+    if (failedTasks.length > 0) {
+        lines.push("");
+        lines.push("### Failed Tasks");
+        for (const task of failedTasks) {
+            lines.push(`- **#${task.index + 1}**: ${task.description}`);
+            const lastIter = task.iterations[task.iterations.length - 1];
+            if (lastIter) {
+                lines.push(`  Last error: ${lastIter.detail.substring(0, 200)}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/dist/utils/terminal.d.ts

@@ -21,7 +21,7 @@ export interface TerminalSession {
     dbusPath?: string;
     pid?: number;
     ptyId?: string;
-    mode: "terminal" | "pty" | "background";
+    mode: "terminal" | "pty" | "background" | "ide";
     branch: string;
     agent: string;
     worktreePath: string;
@@ -63,4 +63,56 @@ export declare function getDriverByName(name: string): TerminalDriver | null;
  * This is the main entry point for worktree_remove cleanup.
  */
 export declare function closeSession(session: TerminalSession): Promise<boolean>;
+/**
+ * Check if a given driver is an IDE driver (VS Code, Cursor, Windsurf, Zed, JetBrains).
+ * Used to determine whether to attempt a fallback when the IDE CLI is unavailable.
+ */
+export declare function isIDEDriver(driver: TerminalDriver): boolean;
+/**
+ * Detect the first non-IDE terminal driver that matches the environment.
+ * Used as a fallback when the IDE CLI is not available (e.g., `code` not in PATH).
+ *
+ * Skips IDE drivers and JetBrains, tries tmux, iTerm2, Terminal.app, kitty, etc.
+ * Returns null if no terminal driver matches (only fallback driver left).
+ */
+export declare function detectFallbackDriver(): TerminalDriver | null;
+/**
+ * Check if we're currently inside an IDE's integrated terminal.
+ * Returns the IDE driver if detected, null otherwise.
+ */
+export declare function detectIDE(): TerminalDriver | null;
+/**
+ * Check if a specific IDE's CLI is available on the system.
+ */
+export declare function isIDECliAvailable(ideName: string): Promise<boolean>;
+/**
+ * Get a list of all available IDE CLIs on the system.
+ * Useful for offering launch options.
+ */
+export declare function getAvailableIDEs(): Promise<string[]>;
+/**
+ * Result from the multi-strategy detection chain.
+ * Includes the matched driver and how it was found (for diagnostics).
+ */
+export interface TerminalDetectionResult {
+    driver: TerminalDriver;
+    strategy: "env" | "process-tree" | "frontmost-app" | "user-config" | "fallback";
+    detail?: string;
+}
+/**
+ * Async multi-strategy detection of the user's terminal emulator.
+ *
+ * This is the PRIMARY function for "Open in terminal tab" — it NEVER returns
+ * an IDE driver. Use `detectDriver()` for IDE-first detection (e.g., "Open in IDE").
+ *
+ * Strategy chain:
+ *   1. Environment variables (fast, synchronous)
+ *   2. Process-tree walk (macOS: ps, Linux: /proc)
+ *   3. Frontmost application (macOS: AppleScript)
+ *   4. User preference (.cortex/config.json)
+ *   5. FallbackDriver (last resort)
+ *
+ * @param projectRoot — optional project root for reading .cortex/config.json
+ */
+export declare function detectTerminalDriver(projectRoot?: string): Promise<TerminalDetectionResult>;
 //# sourceMappingURL=terminal.d.ts.map

package/dist/utils/terminal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/utils/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAG1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,IAAI,EAAE,UAAU,GAAG,KAAK,GAAG,YAAY,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,IAAI,OAAO,CAAC;IAClB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtD;AAMD,yEAAyE;AACzE,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,eAAe,GACvB,IAAI,CASN;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CACzB,YAAY,EAAE,MAAM,GACnB,eAAe,GAAG,IAAI,CAQxB;AA6kBD;;;GAGG;AACH,wBAAgB,YAAY,IAAI,cAAc,CAM7C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAEnE;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAY7E"}
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/utils/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAG1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,IAAI,EAAE,UAAU,GAAG,KAAK,GAAG,YAAY,GAAG,KAAK,CAAC;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,IAAI,OAAO,CAAC;IAClB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtD;AAMD,yEAAyE;AACzE,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,eAAe,GACvB,IAAI,CASN;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CACzB,YAAY,EAAE,MAAM,GACnB,eAAe,GAAG,IAAI,CAQxB;AA68BD;;;GAGG;AACH,wBAAgB,YAAY,IAAI,cAAc,CAM7C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAEnE;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAY7E;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,GAAG,IAAI,CAU5D;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,cAAc,GAAG,IAAI,CAajD;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAazE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAW1D;AAMD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,KAAK,GAAG,cAAc,GAAG,eAAe,GAAG,aAAa,GAAG,UAAU,CAAC;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA8MD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA2BjG"}