aiwcli 0.15.5 → 0.17.0

package/dist/lib/context/plan-manager.js

@@ -0,0 +1,282 @@
+/**
+ * Plan lifecycle management — archival, lookup, and path extraction.
+ * See SPEC.md §9
+ *
+ * Provides pure-data operations on plan files:
+ * - archivePlan: copy plan to context plans/ folder, compute hash + signature
+ * - findLatestPlan: locate the most relevant plan for a context
+ * - extractPlanPathFromResult: parse plan path from ExitPlanMode output
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "../runtime/atomic-write.js";
+import { getContextPlansDir, sanitizeTitle } from "../runtime/constants.js";
+import { logDebug, logInfo, logWarn, logError } from "../runtime/logger.js";
+import { generateSlug } from "../runtime/utils.js";
+// ---------------------------------------------------------------------------
+// Plan archival
+// ---------------------------------------------------------------------------
+/**
+ * Archive a plan file to the context's plans/ folder.
+ * Computes a content hash and signature.
+ * Does NOT modify state.json or mode.
+ * See SPEC.md §9.2
+ *
+ * Returns [archivedPath, planHash, planSignature] on success,
+ * or [null, null, null] on error.
+ */
+export function archivePlan(planPath, contextId, projectRoot) {
+    if (!fs.existsSync(planPath)) {
+        logWarn("plan_manager", `Plan file not found: ${planPath}`);
+        return [null, null, null];
+    }
+    let content;
+    try {
+        content = fs.readFileSync(planPath, "utf8");
+    }
+    catch (error_) {
+        logError("plan_manager", `Failed to read plan: ${error_}`);
+        return [null, null, null];
+    }
+    // Compute hash and signature
+    const planHash = crypto.createHash("sha256").update(content, "utf8").digest("hex").slice(0, 12);
+    const planSignature = content.slice(0, 200);
+    // Ensure plans directory exists
+    const plansDir = getContextPlansDir(contextId, projectRoot);
+    fs.mkdirSync(plansDir, { recursive: true });
+    // Generate archive filename: YYYY-MM-DD-HHMM-<slug>.md
+    const now = new Date();
+    const dateStr = [
+        now.getFullYear(),
+        "-",
+        String(now.getMonth() + 1).padStart(2, "0"),
+        "-",
+        String(now.getDate()).padStart(2, "0"),
+        "-",
+        String(now.getHours()).padStart(2, "0"),
+        String(now.getMinutes()).padStart(2, "0"),
+    ].join("");
+    // Extract a clean summary from plan content for slug generation.
+    // Headings describe the plan's intent better than raw markdown body.
+    const summary = extractPlanSummary(content);
+    const slug = generateSlug(summary, 60, sanitizeTitle(path.basename(planPath, path.extname(planPath)), 30));
+    let archiveName = `${dateStr}-${slug}.md`;
+    let archivePath = path.join(plansDir, archiveName);
+    // Handle filename collisions
+    let counter = 2;
+    while (fs.existsSync(archivePath)) {
+        archiveName = `${dateStr}-${slug}-${counter}.md`;
+        archivePath = path.join(plansDir, archiveName);
+        counter++;
+    }
+    // Write archived plan atomically
+    const [success, error] = atomicWrite(archivePath, content);
+    if (!success) {
+        logError("plan_manager", `Failed to write archive: ${error}`);
+        return [null, null, null];
+    }
+    logInfo("plan_manager", `Archived plan to: ${archivePath}`);
+    return [archivePath, planHash, planSignature];
+}
+/**
+ * Extract a human-readable summary from plan markdown content.
+ * Pulls headings and the first substantial paragraph, producing
+ * text suitable for the AI slug generator (which expects conversational input).
+ */
+function extractPlanSummary(content) {
+    const lines = content.split(/\r?\n/);
+    const parts = [];
+    let firstParagraph = "";
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Collect markdown headings (strip # prefix)
+        if (trimmed.startsWith("#")) {
+            const heading = trimmed.replace(/^#+\s*/, "");
+            if (heading.length > 2)
+                parts.push(heading);
+        }
+        // Grab first substantial non-heading line as context
+        if (!firstParagraph && !trimmed.startsWith("#") && trimmed.length > 20) {
+            firstParagraph = trimmed.slice(0, 120);
+        }
+        // Enough material for the AI
+        if (parts.length >= 5)
+            break;
+    }
+    if (firstParagraph)
+        parts.push(firstParagraph);
+    return parts.join(" ").slice(0, 500) || content.slice(0, 500);
+}
+// ---------------------------------------------------------------------------
+// Plan lookup
+// ---------------------------------------------------------------------------
+/**
+ * Find the most relevant plan file for a context.
+ * Priority: state.json plan_path > most recent .md in plans/ dir.
+ * See SPEC.md §9.3
+ */
+export function findLatestPlan(contextId, projectRoot) {
+    // 1. Check state.json plan_path first
+    try {
+        // Dynamic import to avoid circular dependency at module level
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, no-undef -- dynamic require to avoid circular dependency
+        const stateIo = require("../runtime/state-io.js");
+        const state = stateIo.readStateJson(contextId, projectRoot);
+        if (state?.plan_path && fs.existsSync(state.plan_path)) {
+            return state.plan_path;
+        }
+    }
+    catch (error) {
+        logWarn("plan_manager", `Failed to check state.json plan_path: ${error}`);
+    }
+    // 2. Fall back to most recent .md in plans/ dir
+    const plansDir = getContextPlansDir(contextId, projectRoot);
+    if (fs.existsSync(plansDir)) {
+        try {
+            const files = fs.readdirSync(plansDir)
+                .filter(f => f.endsWith(".md"))
+                .map(f => {
+                const fullPath = path.join(plansDir, f);
+                return { path: fullPath, mtime: fs.statSync(fullPath).mtimeMs };
+            })
+                .sort((a, b) => b.mtime - a.mtime);
+            if (files.length > 0) {
+                return files[0].path;
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Plan identification and normalization
+// ---------------------------------------------------------------------------
+/**
+ * Generate a short unique plan identifier (8 hex chars).
+ * See SPEC.md §9.4
+ */
+export function generatePlanId() {
+    return crypto.randomUUID().replaceAll('-', "").slice(0, 8);
+}
+/**
+ * Aggressively normalize plan content for hashing.
+ * Strips all XML/HTML tags and collapses whitespace.
+ * See SPEC.md §9.5
+ */
+export function normalizePlanContent(text) {
+    let result = text.replaceAll(/<[^>]+>/g, "");
+    result = result.replaceAll(/\s+/g, " ").trim();
+    return result;
+}
+/**
+ * Extract structural anchors from plan content.
+ * Returns markdown headings + first substantial paragraph as short strings.
+ * See SPEC.md §9.6
+ */
+export function extractPlanAnchors(content, maxAnchors = 5) {
+    const anchors = [];
+    for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("#") && trimmed.length > 3) {
+            anchors.push(trimmed.slice(0, 80));
+        }
+        else if (anchors.length === 0 && trimmed.length > 20) {
+            anchors.push(trimmed.slice(0, 80));
+        }
+        if (anchors.length >= maxAnchors)
+            break;
+    }
+    return anchors;
+}
+// ---------------------------------------------------------------------------
+// Transcript-based plan path extraction
+// ---------------------------------------------------------------------------
+const MAX_TRANSCRIPT_SIZE = 50 * 1024 * 1024; // 50 MB
+/**
+ * Find the plan file path by parsing the session transcript JSONL.
+ * Searches in reverse for the most recent Write tool call targeting .claude/plans/.
+ * See SPEC.md §9.7
+ */
+export function findPlanPathInTranscript(transcriptPath) {
+    if (!transcriptPath)
+        return null;
+    if (!fs.existsSync(transcriptPath)) {
+        logDebug("plan_manager", `Transcript not found: ${transcriptPath}`);
+        return null;
+    }
+    let size;
+    try {
+        size = fs.statSync(transcriptPath).size;
+    }
+    catch {
+        return null;
+    }
+    if (size > MAX_TRANSCRIPT_SIZE) {
+        logWarn("plan_manager", `Transcript too large (${size} bytes), skipping`);
+        return null;
+    }
+    let lines;
+    try {
+        lines = fs.readFileSync(transcriptPath, "utf8").split(/\r?\n/);
+    }
+    catch (error) {
+        logWarn("plan_manager", `Failed to read transcript: ${error}`);
+        return null;
+    }
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let data;
+        try {
+            data = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        let contentArr;
+        try {
+            const message = data.message;
+            contentArr = message?.content;
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(contentArr))
+            continue;
+        for (const block of contentArr) {
+            if (typeof block !== "object" || block === null)
+                continue;
+            if (block.type !== "tool_use" || block.name !== "Write")
+                continue;
+            const filePath = block.input?.file_path;
+            if (!filePath)
+                continue;
+            // Check if path contains .claude/plans/ as consecutive parts
+            const parts = filePath.replaceAll('\\', "/").split("/");
+            for (let j = 0; j < parts.length - 1; j++) {
+                if (parts[j] === ".claude" && parts[j + 1] === "plans") {
+                    logInfo("plan_manager", `Extracted plan path from transcript: ${filePath}`);
+                    return filePath;
+                }
+            }
+        }
+    }
+    logDebug("plan_manager", "No plan Write found in transcript");
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Path extraction from tool output
+// ---------------------------------------------------------------------------
+/**
+ * Extract plan file path from ExitPlanMode tool result.
+ * Parses the pattern: "Your plan has been saved to: <path>"
+ * See SPEC.md §9.8
+ */
+export function extractPlanPathFromResult(toolResult) {
+    if (!toolResult)
+        return null;
+    const match = toolResult.match(/Your plan has been saved to:\s*(.+\.md)/);
+    return match ? match[1].trim() : null;
+}

package/dist/lib/context/task-tracker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Task tracker — direct state.json CRUD for tasks.
+ * See SPEC.md §10
+ *
+ * Writes tasks directly to the tasks[] array in state.json.
+ * Uses state-io for I/O to avoid circular imports with context-store.
+ */
+import type { Task } from "../types.js";
+/**
+ * Scan tasks[] for highest aiw-N, return aiw-(N+1).
+ * See SPEC.md §10.2
+ */
+export declare function generateNextTaskId(contextId: string, projectRoot?: string): string;
+/**
+ * Add a new task to state.json tasks[] and return the task object.
+ * See SPEC.md §10.3
+ */
+export declare function addTask(contextId: string, subject: string, description?: string, activeForm?: string, sessionId?: string, projectRoot?: string): null | Task;
+/**
+ * Find task by task_id in tasks[], update fields, return true on success.
+ * See SPEC.md §10.4
+ */
+export declare function updateTask(contextId: string, taskId: string, opts?: {
+    evidence?: string;
+    files_changed?: string[];
+    session_id?: string;
+    status?: string;
+    work_summary?: string;
+}, projectRoot?: string): boolean;
+/**
+ * Remove task from tasks[] and return true on success.
+ * See SPEC.md §10.5
+ */
+export declare function deleteTask(contextId: string, taskId: string, projectRoot?: string): boolean;
+/**
+ * Return tasks[] from state.json.
+ * See SPEC.md §10.6
+ */
+export declare function getTasks(contextId: string, projectRoot?: string): Task[];
+/**
+ * Partition tasks and format as markdown checklist.
+ * See SPEC.md §10.7
+ */
+export declare function generateTaskSummary(contextId: string, projectRoot?: string): string;

package/dist/lib/context/task-tracker.js

@@ -0,0 +1,146 @@
+/**
+ * Task tracker — direct state.json CRUD for tasks.
+ * See SPEC.md §10
+ *
+ * Writes tasks directly to the tasks[] array in state.json.
+ * Uses state-io for I/O to avoid circular imports with context-store.
+ */
+import { logWarn } from "../runtime/logger.js";
+import { readStateJson, writeStateJson } from "../runtime/state-io.js";
+import { nowIso } from "../runtime/utils.js";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Scan tasks[] for highest aiw-N, return aiw-(N+1).
+ * See SPEC.md §10.2
+ */
+export function generateNextTaskId(contextId, projectRoot) {
+    const state = readStateJson(contextId, projectRoot);
+    const tasks = state?.tasks ?? [];
+    let maxNum = 0;
+    for (const t of tasks) {
+        const match = /^aiw-(\d+)$/.exec(t.id);
+        if (match) {
+            const num = Number.parseInt(match[1], 10);
+            if (num > maxNum)
+                maxNum = num;
+        }
+    }
+    return `aiw-${maxNum + 1}`;
+}
+/**
+ * Add a new task to state.json tasks[] and return the task object.
+ * See SPEC.md §10.3
+ */
+export function addTask(contextId, subject, description = "", activeForm = "", sessionId = "", projectRoot) {
+    const state = readStateJson(contextId, projectRoot);
+    if (!state)
+        return null;
+    const taskId = generateNextTaskId(contextId, projectRoot);
+    const task = {
+        id: taskId,
+        subject,
+        description,
+        active_form: activeForm,
+        status: "pending",
+        created_at: nowIso(),
+        completed_at: null,
+        evidence: "",
+        work_summary: "",
+        files_changed: [],
+        session_id: sessionId,
+    };
+    state.tasks.push(task);
+    state.last_active = nowIso();
+    const [success] = writeStateJson(contextId, state, projectRoot);
+    return success ? task : null;
+}
+/**
+ * Find task by task_id in tasks[], update fields, return true on success.
+ * See SPEC.md §10.4
+ */
+export function updateTask(contextId, taskId, opts, projectRoot) {
+    const state = readStateJson(contextId, projectRoot);
+    if (!state)
+        return false;
+    for (const task of state.tasks) {
+        if (task.id === taskId) {
+            if (opts?.status !== undefined) {
+                task.status = opts.status;
+                if (opts.status === "completed") {
+                    task.completed_at = nowIso();
+                }
+            }
+            if (opts?.evidence)
+                task.evidence = opts.evidence;
+            if (opts?.work_summary)
+                task.work_summary = opts.work_summary;
+            if (opts?.files_changed !== undefined)
+                task.files_changed = opts.files_changed;
+            if (opts?.session_id)
+                task.session_id = opts.session_id;
+            state.last_active = nowIso();
+            const [success] = writeStateJson(contextId, state, projectRoot);
+            return success;
+        }
+    }
+    logWarn("task_tracker", `Task '${taskId}' not found in context '${contextId}'`);
+    return false;
+}
+/**
+ * Remove task from tasks[] and return true on success.
+ * See SPEC.md §10.5
+ */
+export function deleteTask(contextId, taskId, projectRoot) {
+    const state = readStateJson(contextId, projectRoot);
+    if (!state)
+        return false;
+    const originalLen = state.tasks.length;
+    state.tasks = state.tasks.filter(t => t.id !== taskId);
+    if (state.tasks.length === originalLen) {
+        logWarn("task_tracker", `Task '${taskId}' not found in context '${contextId}'`);
+        return false;
+    }
+    state.last_active = nowIso();
+    const [success] = writeStateJson(contextId, state, projectRoot);
+    return success;
+}
+/**
+ * Return tasks[] from state.json.
+ * See SPEC.md §10.6
+ */
+export function getTasks(contextId, projectRoot) {
+    const state = readStateJson(contextId, projectRoot);
+    if (!state)
+        return [];
+    return state.tasks;
+}
+/**
+ * Partition tasks and format as markdown checklist.
+ * See SPEC.md §10.7
+ */
+export function generateTaskSummary(contextId, projectRoot) {
+    const tasks = getTasks(contextId, projectRoot);
+    if (tasks.length === 0)
+        return "No tasks in this context.";
+    const completed = tasks.filter(t => t.status === "completed");
+    const inProgress = tasks.filter(t => t.status === "in_progress");
+    const pending = tasks.filter(t => t.status === "pending");
+    const blocked = tasks.filter(t => t.status === "blocked");
+    const lines = [`### Tasks (${tasks.length} total)`, ""];
+    for (const t of completed) {
+        const ws = t.work_summary ? `\n  Work: ${t.work_summary}` : "";
+        lines.push(`- [x] ${t.id}: ${t.subject}${ws}`);
+    }
+    for (const t of inProgress) {
+        lines.push(`- [~] ${t.id}: ${t.subject}`);
+    }
+    for (const t of pending) {
+        lines.push(`- [ ] ${t.id}: ${t.subject}`);
+    }
+    for (const t of blocked) {
+        lines.push(`- [!] ${t.id}: ${t.subject}`);
+    }
+    return lines.join("\n");
+}

package/dist/lib/core-ide-base.d.ts

@@ -0,0 +1,4 @@
+import type { ClaudeSettings } from './claude-settings-types.js';
+import type { WindsurfHooks } from './windsurf-hooks-types.js';
+export declare function getCoreClaudeSettingsBase(): ClaudeSettings;
+export declare function getCoreWindsurfHooksBase(): WindsurfHooks;

package/dist/lib/core-ide-base.js

@@ -0,0 +1,77 @@
+const RESOLVER = 'bun .aiwcli/_core/scripts/resolve-run.ts';
+const CORE_ROOT = '.aiwcli/_core';
+function cmd(relativePath) {
+    return `${RESOLVER} ${CORE_ROOT}/${relativePath}`;
+}
+export function getCoreClaudeSettingsBase() {
+    return {
+        statusLine: {
+            type: 'command',
+            command: cmd('scripts/status_line.ts'),
+        },
+        fileSuggestion: {
+            type: 'command',
+            command: cmd('hooks-ts/file-suggestion.ts'),
+        },
+        hooks: {
+            UserPromptSubmit: [
+                {
+                    matcher: '*',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/user_prompt_submit.ts'), timeout: 10 * 1000 }],
+                },
+                {
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/codex_explorer.ts'), timeout: 55 * 1000 }],
+                },
+            ],
+            PostToolUse: [
+                {
+                    matcher: '*',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/context_monitor.ts'), timeout: 5000 }],
+                },
+                {
+                    matcher: 'TaskCreate',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/task_create_capture.ts'), timeout: 3000 }],
+                },
+                {
+                    matcher: 'TaskUpdate',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/task_update_capture.ts'), timeout: 3000 }],
+                },
+                {
+                    matcher: 'ExitPlanMode',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/archive_plan.ts'), timeout: 5000 }],
+                },
+                {
+                    matcher: 'Write|Edit',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/lint_after_edit.ts'), timeout: 10 * 1000 }],
+                },
+            ],
+            SessionStart: [
+                {
+                    matcher: '*',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/session_start.ts'), timeout: 5000 }],
+                },
+            ],
+            SessionEnd: [
+                {
+                    matcher: '*',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/session_end.ts'), timeout: 5000 }],
+                },
+            ],
+            PreCompact: [
+                {
+                    matcher: '*',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/pre_compact.ts'), timeout: 5000 }],
+                },
+            ],
+            PermissionRequest: [
+                {
+                    matcher: 'ExitPlanMode',
+                    hooks: [{ type: 'command', command: cmd('hooks-ts/archive_plan.ts'), timeout: 5000 }],
+                },
+            ],
+        },
+    };
+}
+export function getCoreWindsurfHooksBase() {
+    return { hooks: {} };
+}

package/dist/lib/core-installer.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Install core runtime assets into .aiwcli/_core.
+ */
+export declare function installCoreAssets(targetDir: string, ides: string[]): Promise<string[]>;
+export declare function getCoreResolverSourcePath(): Promise<string>;

package/dist/lib/core-installer.js

@@ -0,0 +1,33 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { IdePathResolver } from './ide-path-resolver.js';
+import { pathExists } from './paths.js';
+import { copyDir, mergeDirectory } from './template-installer.js';
+import { getTemplatePath } from './template-resolver.js';
+/**
+ * Install core runtime assets into .aiwcli/_core.
+ */
+export async function installCoreAssets(targetDir, ides) {
+    const resolver = new IdePathResolver(targetDir);
+    const containerDir = resolver.getAiwcliContainer();
+    const coreDir = resolver.getCoreFolder();
+    await fs.mkdir(containerDir, { recursive: true });
+    const sourceRoot = await getTemplatePath('core');
+    if (!(await pathExists(sourceRoot))) {
+        throw new Error(`Core assets not found at ${sourceRoot}. This indicates a corrupted installation.`);
+    }
+    // Copy runtime payload into .aiwcli/_core
+    await copyDir(sourceRoot, coreDir, true);
+    // Copy core IDE content (Codex skills, Windsurf workflows, etc.) from source dot folders.
+    for (const ide of ides) {
+        const srcIdeDir = join(sourceRoot, `.${ide}`);
+        if (!(await pathExists(srcIdeDir)))
+            continue; // eslint-disable-line no-await-in-loop
+        const dstIdeDir = resolver.getIdeDir(ide);
+        await mergeDirectory(srcIdeDir, dstIdeDir); // eslint-disable-line no-await-in-loop
+    }
+    return ['_core'];
+}
+export async function getCoreResolverSourcePath() {
+    return join(await getTemplatePath('core'), 'scripts', 'resolve-run.ts');
+}

package/dist/lib/debug.d.ts

@@ -16,16 +16,6 @@ export declare function setDebugEnabled(enabled: boolean): void;
  * @param message - The message to log
  */
 export declare function debug(message: string): void;
-/**
- * Log configuration details in debug mode.
- * Only logs AIW_DIR path to avoid accidentally logging sensitive data.
- * @param config - Configuration object
- * @param config.aiwDir - AIW_DIR path
- */
-export declare function debugConfig(config: {
-    [key: string]: unknown;
-    aiwDir: string;
-}): void;
 /**
  * Log process spawn details in debug mode.
  * @param command - Command being spawned

package/dist/lib/debug.js

@@ -33,16 +33,6 @@ export function debug(message) {
         }
     }
 }
-/**
- * Log configuration details in debug mode.
- * Only logs AIW_DIR path to avoid accidentally logging sensitive data.
- * @param config - Configuration object
- * @param config.aiwDir - AIW_DIR path
- */
-export function debugConfig(config) {
-    debug(`AIW_DIR resolved to ${config.aiwDir}`);
-    // NOTE: Do NOT log full config - may contain API keys/tokens in future
-}
 /**
  * Log process spawn details in debug mode.
  * @param command - Command being spawned

package/dist/lib/env-sanitizer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Centralized env var management for REPL nesting detection.
+ * Replaces scattered cleanClaudeEnv(), UNSET_NESTING_SH, etc.
+ */
+/**
+ * Env vars set by REPL tools (Claude Code, Codex, Devin) that trigger
+ * nesting detection. Must be cleared when spawning a new REPL pane so
+ * the child tool starts fresh instead of refusing to launch.
+ */
+export declare const REPL_NESTING_VARS: readonly ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_SESSION_ID", "CODEX_THREAD_ID", "AIWCLI_INTERNAL_CALL"];
+/**
+ * Check whether the current process was invoked from a REPL tool.
+ * Must be called BEFORE clearProcessNestingVars().
+ */
+export declare function isCalledFromRepl(): boolean;
+/**
+ * Clear REPL nesting vars from the current process environment.
+ * Call once at orchestrator startup so inline launches don't see them.
+ */
+export declare function clearProcessNestingVars(): void;
+/**
+ * Build a clean process env with nesting vars removed and optional extras merged.
+ * Used for createSession() spawn calls that inherit process.env.
+ */
+export declare function sanitizedProcessEnv(extraEnv?: Record<string, string>): NodeJS.ProcessEnv;