micro-models-agent 0.13.1 → 0.13.2

package/dist/core/bootstrap.js

@@ -22,7 +22,7 @@ import { MCPModule } from "../modules/mcp/index";
 import { setLocale } from "../i18n/index";
 import { Agent } from "./agent";
 import { homedir } from "os";
-import { join } from "path";
+import { join, resolve } from "path";
 import { existsSync, readFileSync, writeFileSync } from "fs";
 function buildSystemInfo(config, baseDir, profileCompressed) {
     const now = new Date().toISOString().replace("T", " ").slice(0, 19);
@@ -45,7 +45,7 @@ function buildSystemInfo(config, baseDir, profileCompressed) {
         `- Do not duplicate code, logic, or configuration (DRY — Don't Repeat Yourself). Extract shared logic into a single place, reuse existing utilities and patterns before writing new ones.`,
     ];
     if (isWin) {
-        lines.push(`OS-specific: You are on Windows. Do not use Unix-only command flags like "mkdir -p". Use the create_dir tool to create directories.`);
+        lines.push(``, `Windows environment — use Windows-compatible commands:`, `- Use "dir" instead of "ls". Use "dir /b" for bare listing.`, `- Use "type" or "Get-Content" instead of "cat".`, `- Use "cd" instead of "pwd". Use "echo %cd%" to print working directory.`, `- Use "copy" instead of "cp", "move" instead of "mv", "del" instead of "rm".`, `- Do not use "mkdir -p" — Windows mkdir creates intermediate dirs by default. Use the create_dir tool instead.`, `- Use forward slashes (/) or escaped backslashes (\\\\) in file paths.`, `- Your working directory is: ${baseDir}`);
     }
     if (config.autoPlan) {
         lines.push(``, `Plan rule: For any task with 2+ steps, create a plan first using the "plan" tool. After each step, call "plan update" to mark progress. Stay focused on the current step.`);
@@ -110,7 +110,7 @@ export async function bootstrap(configDir, projectDir, noAgentsMd, exitOnComplet
         retry: config.retry,
         rateLimits: config.security?.rateLimits,
     });
-    const baseDir = projectDir || process.cwd();
+    const baseDir = projectDir ? resolve(projectDir) : process.cwd();
     const projectMapCacheDir = join(baseDir, ".mma");
     const indexerModule = new IndexerModule({
         baseDir,
@@ -191,6 +191,7 @@ export async function bootstrap(configDir, projectDir, noAgentsMd, exitOnComplet
     toolCtx.trackReadPath = (p) => factualCheck.trackReadPath(p);
     toolCtx.trackCreatedPath = (p) => factualCheck.trackCreatedPath(p);
     toolCtx.trackDeletedPath = (p) => factualCheck.trackDeletedPath(p);
+    toolCtx.trackDocumentContent = (c) => factualCheck.trackDocumentContent(c);
     const moduleRegistry = new ModuleRegistry();
     const execModule = new ExecutionModule(baseDir, config.stuckThreshold);
     moduleRegistry.register(execModule);

package/dist/core/session-logger.js

@@ -0,0 +1,122 @@
+/**
+ * Thin wrapper around SessionManager that eliminates repetitive
+ * `if (sessionManager)` + `new Date().toISOString()` boilerplate
+ * from the agent loop.
+ */
+export class SessionLogger {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    get active() {
+        return !!this.session?.getActive();
+    }
+    logSystem(content) {
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: "system",
+            content,
+        });
+    }
+    logUser(content) {
+        this.session?.appendMessage({
+            role: "user",
+            content,
+            timestamp: new Date().toISOString(),
+        });
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: "user",
+            content,
+        });
+    }
+    logAssistant(content, reasoning, toolCalls, iteration) {
+        if (reasoning) {
+            this.session?.appendLog({
+                ts: new Date().toISOString(),
+                type: "reasoning",
+                content: reasoning,
+                iteration,
+            });
+        }
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: "assistant",
+            content,
+            ...(toolCalls
+                ? { tool_calls: toolCalls.map((tc) => ({ id: tc.id, name: tc.name, arguments: tc.arguments })) }
+                : {}),
+            iteration,
+        });
+    }
+    saveAssistantMessage(content) {
+        this.session?.appendMessage({
+            role: "assistant",
+            content: content.slice(0, 500),
+            timestamp: new Date().toISOString(),
+        });
+    }
+    logToolDefs(toolCount, toolNames, iteration) {
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: "tool_defs",
+            toolCount,
+            toolNames,
+            iteration,
+        });
+    }
+    logToolCall(call, iteration) {
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: "tool_call",
+            tool: call.name,
+            tool_call_id: call.id,
+            args: call.arguments,
+            iteration,
+        });
+    }
+    logToolResult(call, result, duration, iteration) {
+        this.session?.appendMessage({
+            role: "tool",
+            content: result.output.slice(0, 500),
+            name: call.name,
+            timestamp: new Date().toISOString(),
+        });
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: "tool_result",
+            tool: call.name,
+            tool_call_id: call.id,
+            success: result.success,
+            content: result.output.slice(0, 1000),
+            diff: result.diff,
+            duration,
+            iteration,
+        });
+    }
+    logCompaction(content, iteration, contextTokens, contextLimit) {
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: "compaction",
+            content,
+            iteration,
+            ...(contextTokens !== undefined ? { contextTokens } : {}),
+            ...(contextLimit !== undefined ? { contextLimit } : {}),
+        });
+    }
+    logError(message) {
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: "error",
+            content: message,
+        });
+    }
+    logAudit(summary, iteration) {
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: "audit",
+            content: summary,
+            iteration,
+        });
+    }
+}

package/dist/i18n/en.json

@@ -411,6 +411,7 @@
     "migration.dir_bak": "- .mma/ \u2192 .mma.bak/ ({count} files)",
     "migration.migrated": "Migrated:",
     "migration.not_needed": "No migration needed",
+    "migration.security_updated": "[MMA] Security config force-updated from v{from} to v{to} (dangerous operators reset to defaults)",
     "ui.error_prefix": "Error: ",
     "ui.success_prefix": "\u2713 ",
     "ui.warning_prefix": "\u26a0 ",

package/dist/i18n/ru.json

@@ -411,6 +411,7 @@
     "migration.dir_bak": "- .mma/ → .mma.bak/ ({count} файлов)",
     "migration.migrated": "Мигрировано:",
     "migration.not_needed": "Миграция не требуется",
+    "migration.security_updated": "[MMA] Конфигурация безопасности принудительно обновлена с v{from} до v{to} (опасные операторы сброшены)",
     "ui.error_prefix": "Ошибка: ",
     "ui.success_prefix": "✓ ",
     "ui.warning_prefix": "⚠ ",

package/dist/llm/openai-compat.js

@@ -201,13 +201,15 @@ export class OpenAICompatProvider {
             });
             if (!response.ok) {
                 const errorText = await response.text();
-                console.error("[doNonStreaming] HTTP error:", response.status, errorText.slice(0, 500));
-                return [];
+                throw new Error(t("error.llm_api", {
+                    status: response.status,
+                    statusText: response.statusText,
+                    errorText: errorText.slice(0, 500),
+                }));
             }
             const data = await response.json();
             const choice = data.choices?.[0];
             if (!choice) {
-                console.error("[doNonStreaming] No choices in response");
                 return [];
             }
             const msg = choice.message || {};
@@ -230,15 +232,10 @@ export class OpenAICompatProvider {
                     });
                 }
             }
-            console.error("[doNonStreaming] chunks:", chunks.length, "tool_calls:", msg.tool_calls?.length, "content len:", msg.content?.length);
-            if (chunks.length === 0) {
-                console.error("[doNonStreaming] Empty response: no content, no tool_calls, no reasoning");
-            }
             return chunks;
         }
         catch (err) {
-            console.error("[doNonStreaming] Fetch error:", err instanceof Error ? err.message : String(err));
-            return [];
+            throw err instanceof Error ? err : new Error(String(err));
         }
     }
     countTokens(text) {

package/dist/modules/execution/moe-executor.js

@@ -163,6 +163,19 @@ export class MoEExecutor {
         if (waves.length === 0) {
             return { success: false, results: [], errors: ['Failed to topologically sort subtasks (possible cycle)'], warnings: [] };
         }
+        // Verify all subtasks are included — catch silent drops from unresolved dependencies
+        const sortedCount = waves.flat().length;
+        if (sortedCount < plan.subtasks.length) {
+            const missing = plan.subtasks
+                .filter(s => !waves.flat().some(w => w.id === s.id))
+                .map(s => s.id);
+            return {
+                success: false,
+                results: [],
+                errors: [`Missing subtasks after topological sort: ${missing.join(', ')} (dangling or invalid depends_on)`],
+                warnings: [],
+            };
+        }
         for (let waveIdx = 0; waveIdx < waves.length; waveIdx++) {
             const wave = waves[waveIdx];
             const wavePromises = wave.map(subtask => executeSubtask(subtask, this.deps, plan.shared_context)

package/dist/modules/hallucination/confidence.js

@@ -1,13 +1,6 @@
 import { t } from "../../i18n/index";
-const UNCERTAINTY_MARKERS = [
-    "i think",
-    "maybe",
-    "probably",
-    "i believe",
-    "not sure",
-    "might be",
-];
 const MIN_CHARS = 1;
+const MIN_WORDS = 5;
 export class ConfidenceCheck {
     previousResponse = "";
     setPreviousResponse(response) {
@@ -17,6 +10,16 @@ export class ConfidenceCheck {
         if (!response || response.length < MIN_CHARS) {
             return { status: "retry", reason: t("hall.short_response") };
         }
+        // Language-agnostic: very short response with no structured content
+        const wordCount = response.split(/\s+/).filter(Boolean).length;
+        const hasStructure = /```|^\s*[-*]\s|^\s*\d+\.\s|<[^>]+>/m.test(response);
+        if (wordCount < MIN_WORDS && !hasStructure) {
+            return {
+                status: "warn",
+                reason: t("hall.short_response"),
+            };
+        }
+        // Language-agnostic: repetition detection via word overlap
         if (this.previousResponse) {
             const overlap = this.calculateOverlap(response, this.previousResponse);
             if (overlap > 0.5) {
@@ -26,13 +29,17 @@ export class ConfidenceCheck {
                 };
             }
         }
-        const lower = response.toLowerCase();
-        const foundMarkers = UNCERTAINTY_MARKERS.filter((m) => lower.includes(m));
-        if (foundMarkers.length > 0) {
-            return {
-                status: "warn",
-                reason: t("hall.uncertainty", { markers: foundMarkers.join(", ") }),
-            };
+        // Language-agnostic: very low word diversity (same words repeated)
+        const words = response.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+        if (words.length >= 10) {
+            const unique = new Set(words);
+            const diversity = unique.size / words.length;
+            if (diversity < 0.25) {
+                return {
+                    status: "warn",
+                    reason: t("hall.repetitive", { pct: Math.round((1 - diversity) * 100) }),
+                };
+            }
         }
         return { status: "pass" };
     }

package/dist/modules/hallucination/consistency.js

@@ -19,7 +19,35 @@ export class ConsistencyCheck {
         const lower = response.toLowerCase();
         for (const d of this.decisions) {
             const decisionWords = d.decision.toLowerCase().split(/\s+/).filter(w => w.length > 3);
-            const contradicts = decisionWords.some(word => lower.includes(`instead of ${word}`) || lower.includes(`not ${word}`));
+            const contradicts = decisionWords.some(word => {
+                // English patterns
+                if (lower.includes(`instead of ${word}`))
+                    return true;
+                if (lower.includes(`not ${word}`))
+                    return true;
+                if (lower.includes(`replacing ${word} with`))
+                    return true;
+                if (lower.includes(`switching to`))
+                    return true;
+                if (lower.includes(`changing from ${word}`))
+                    return true;
+                if (lower.includes(`abandoning ${word}`))
+                    return true;
+                // Russian patterns
+                if (lower.includes(`вместо ${word}`))
+                    return true;
+                if (lower.includes(`заменяя ${word}`))
+                    return true;
+                if (lower.includes(`заменяем ${word}`))
+                    return true;
+                if (lower.includes(`переключаемся на`))
+                    return true;
+                if (lower.includes(`от ${word} к`))
+                    return true;
+                if (lower.includes(`отказываемся от ${word}`))
+                    return true;
+                return false;
+            });
             if (contradicts) {
                 return {
                     status: 'warn',

package/dist/modules/hallucination/factual.js

@@ -6,6 +6,10 @@ const FILE_EXTENSIONS = new Set([
     "tsx",
     "js",
     "jsx",
+    "mjs",
+    "cjs",
+    "mts",
+    "cts",
     "json",
     "md",
     "yaml",
@@ -32,12 +36,17 @@ const FILE_EXTENSIONS = new Set([
     "cmd",
     "txt",
     "env",
+    "env.local",
+    "env.production",
     "gitignore",
     "dockerignore",
     "dockerfile",
     "makefile",
     "cmake",
     "toml",
+    "lock",
+    "config",
+    "log",
     "xml",
     "sql",
     "graphql",
@@ -45,10 +54,20 @@ const FILE_EXTENSIONS = new Set([
     "wasm",
 ]);
 const VERSION_PATTERN = /^\d+(\.\d+)*$/;
-const COMMON_WORDS = new Set(["node.js", "Node.js"]);
+const COMMON_WORDS = new Set([
+    "node.js", "Node.js",
+    "console.log", "console.error", "console.warn", "console.info",
+    "Math.floor", "Math.ceil", "Math.round", "Math.max", "Math.min",
+    "JSON.parse", "JSON.stringify",
+    "Object.keys", "Object.values", "Object.entries",
+    "Array.from", "Array.isArray",
+    "Date.now", "Date.parse",
+    "RegExp", "Promise",
+]);
 export class FactualCheck {
     knownPaths = new Set();
     createdPaths = new Set();
+    readFiles = new Set();
     baseDir = process.cwd();
     setBaseDir(dir) {
         this.baseDir = dir;
@@ -58,6 +77,8 @@ export class FactualCheck {
         const base = path.split(/[/\\]/).pop();
         if (base && base !== path)
             this.knownPaths.add(base);
+        // Track that this file was actually read by the agent
+        this.readFiles.add(base || path);
     }
     trackCreatedPath(path) {
         this.knownPaths.add(path);
@@ -73,12 +94,30 @@ export class FactualCheck {
             this.knownPaths.add(base);
         this.createdPaths.delete(path);
     }
+    /**
+     * Register file paths found in a document (e.g. structure.md, README).
+     * Files mentioned in project documentation are not hallucinations.
+     */
+    trackDocumentContent(content) {
+        // Match common path patterns in documentation
+        const pathPatterns = /(?:^|\s)([\w\-./]+\.\w{1,10})(?:\s|$|[,;)])/gm;
+        let match;
+        while ((match = pathPatterns.exec(content)) !== null) {
+            const file = match[1];
+            if (file.includes('/') || file.includes('\\')) {
+                this.knownPaths.add(file);
+            }
+            const base = file.split(/[/\\]/).pop();
+            if (base)
+                this.knownPaths.add(base);
+        }
+    }
     pathExistsOnDisk(path) {
         try {
-            if (path.startsWith("/") ||
-                path.startsWith("~") ||
-                /^[A-Za-z]:/.test(path)) {
-                return existsSync(path);
+            // Skip absolute paths — they're either system paths or outside the project.
+            // On Windows, existsSync('/...') can hang on certain paths.
+            if (path.startsWith("/") || path.startsWith("~") || /^[A-Za-z]:/.test(path)) {
+                return false;
             }
             return existsSync(join(this.baseDir, path));
         }
@@ -94,10 +133,13 @@ export class FactualCheck {
                 return false;
             if (VERSION_PATTERN.test(p))
                 return false;
-            if (p.startsWith("/"))
-                return false;
             if (COMMON_WORDS.has(p))
                 return false;
+            // Skip absolute paths — agent responses use relative paths; absolute
+            // paths are either system paths or URLs, and existsSync can hang on
+            // Windows for root-relative paths like "/page.html".
+            if (p.startsWith("/") || p.startsWith("~") || /^[A-Za-z]:/.test(p))
+                return false;
             if (this.pathExistsOnDisk(p))
                 return false;
             const ext = p.split(".").pop()?.toLowerCase() || "";

package/dist/modules/processes/registry.js

@@ -134,6 +134,12 @@ class ProcessRegistry {
         const sorted = Array.from(this.procs.values()).sort((a, b) => a.startedAt.localeCompare(b.startedAt));
         const toRemove = sorted.slice(0, sorted.length - MAX_KEPT_PROCESSES + 1);
         for (const entry of toRemove) {
+            if (entry.status === "running") {
+                const child = this.children.get(entry.id);
+                if (child) {
+                    killTree(child);
+                }
+            }
             this.procs.delete(entry.id);
             this.children.delete(entry.id);
         }

package/dist/modules/security/command-validator.js

@@ -9,6 +9,40 @@ const FALLBACK_BASH_CONFIG = {
     logCommands: true,
 };
 export const DEFAULT_BASH_CONFIG = DEFAULT_SECURITY_CONFIG?.bash || FALLBACK_BASH_CONFIG;
+/**
+ * Extract the actual base command from a shell command string.
+ * Handles path prefixes, env assignments, and sudo.
+ *
+ * Examples:
+ *   "/usr/bin/rm -rf /"           → "rm"
+ *   "sudo /usr/bin/rm file"       → "rm"
+ *   "NODE_ENV=prod node app.js"   → "node"
+ *   "env PATH=/x rm -rf /"        → "rm"
+ *   "cmd=rm; $cmd -rf /"          → "cmd" (variable indirection — not expanded)
+ */
+function extractBaseCommand(trimmed) {
+    const tokens = trimmed.split(/\s+/);
+    let i = 0;
+    // Skip env assignments (KEY=val, KEY="val", etc.) and prefixed commands
+    while (i < tokens.length) {
+        const tok = tokens[i];
+        if (/^[a-zA-Z_][a-zA-Z0-9_]*=/.test(tok)) {
+            i++;
+            continue;
+        }
+        if (tok === "sudo" || tok === "env" || tok === "command" || tok === "exec" || tok === "nohup") {
+            i++;
+            continue;
+        }
+        break;
+    }
+    if (i >= tokens.length)
+        return tokens[0] ?? "";
+    // Extract basename from path (e.g. /usr/bin/rm → rm)
+    const raw = tokens[i];
+    const parts = raw.split(/[\\/]/);
+    return parts[parts.length - 1] || raw;
+}
 /**
  * Check if a command is allowed based on security configuration
  */
@@ -23,8 +57,20 @@ export function isCommandAllowed(command, securityConfig) {
     if (!trimmedCommand) {
         return { allowed: false, reason: "Empty command" };
     }
-    // Extract base command (first word)
-    const baseCommand = trimmedCommand.split(/\s+/)[0];
+    // Check dangerous operators FIRST — before parsing the base command.
+    // e.g. "curl http://x | bash" must be caught even though curl isn't blacklisted.
+    if (config.blockDangerousFlags) {
+        for (const op of config.dangerousOperators || []) {
+            if (trimmedCommand.includes(op)) {
+                return {
+                    allowed: false,
+                    reason: `Operator "${op}" is not allowed`,
+                };
+            }
+        }
+    }
+    // Extract actual base command (handles paths, env vars, sudo)
+    const baseCommand = extractBaseCommand(trimmedCommand);
     // Check whitelist first (if non-empty, only whitelisted commands are allowed)
     if (config.whitelist.length > 0) {
         if (!config.whitelist.includes(baseCommand)) {
@@ -34,30 +80,27 @@ export function isCommandAllowed(command, securityConfig) {
             };
         }
     }
-    // Check blacklist
+    // Check blacklist (against the extracted basename, not the raw token)
     if (config.blacklist.includes(baseCommand)) {
         return {
             allowed: false,
             reason: `Command "${baseCommand}" is blacklisted`,
         };
     }
-    // Check for dangerous operators
-    if (config.blockDangerousFlags) {
-        for (const op of config.dangerousOperators || []) {
-            if (command.includes(op)) {
-                return {
-                    allowed: false,
-                    reason: `Operator "${op}" is not allowed`,
-                };
-            }
-        }
+    // Also check the raw first token in case it's a simple name
+    const rawFirst = trimmedCommand.split(/\s+/)[0];
+    if (rawFirst !== baseCommand && config.blacklist.includes(rawFirst)) {
+        return {
+            allowed: false,
+            reason: `Command "${rawFirst}" is blacklisted`,
+        };
     }
     // Check for dangerous flags
     if (config.blockDangerousFlags) {
         for (const flag of config.dangerousFlags || []) {
             // Check for flag as whole word or with equals
             const flagPattern = new RegExp(`(?:^|\\s)${flag}(?:\\s|$|=)`);
-            if (flagPattern.test(command)) {
+            if (flagPattern.test(trimmedCommand)) {
                 return {
                     allowed: false,
                     reason: `Dangerous flag "${flag}" is not allowed`,

package/dist/modules/security/encryption.js

@@ -1,7 +1,7 @@
 import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
 import { homedir } from 'os';
 import { join } from 'path';
-import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, copyFileSync } from 'fs';
 const DEFAULT_CONFIG = {
     keyPath: join(homedir(), '.mma', '.encryption-key'),
     algorithm: 'aes-256-gcm',
@@ -44,13 +44,15 @@ export function getOrCreateEncryptionKey(config) {
         return Buffer.from(keyBase64, 'base64');
     }
     catch {
-        // If we can't read the key file, generate a new one
-        const key = generateEncryptionKey();
+        // Backup the corrupted key file before throwing
         try {
-            writeFileSync(keyPath, key.toString('base64'), { mode: 0o600 });
+            const backupPath = `${keyPath}.corrupted.${Date.now()}`;
+            copyFileSync(keyPath, backupPath);
         }
-        catch { /* ignore */ }
-        return key;
+        catch { /* backup failed, continue */ }
+        throw new Error(`Encryption key file is corrupted or unreadable: ${keyPath}. ` +
+            `All previously encrypted data will be unrecoverable. ` +
+            `Delete the key file to generate a new one.`);
     }
 }
 /**

package/dist/modules/session/module.js

@@ -19,10 +19,6 @@ export class SessionModule {
     getPlugin() {
         return {
             name: 'session',
-            onSessionStart: (_ctx) => {
-            },
-            onSessionEnd: (_ctx) => {
-            },
         };
     }
 }

package/dist/tools/bash.js

@@ -19,6 +19,25 @@ function adaptCommandForWindows(command) {
     }
     return command;
 }
+/** Common Unix → Windows command mapping for error hints. */
+const UNIX_TO_WIN_HINTS = {
+    'ls': 'Use "dir" or the list_dir tool instead.',
+    'pwd': 'Use "echo %cd%" or the file_info tool instead.',
+    'cat': 'Use "type" or the read_file tool instead.',
+    'cp': 'Use "copy" or the move_file tool instead.',
+    'mv': 'Use "move" or the move_file tool instead.',
+    'rm': 'Use "del" or the delete_file tool instead.',
+    'grep': 'Use "findstr" or the grep tool instead.',
+    'chmod': 'Use icacls or the chmod tool instead.',
+    'touch': 'Use type nul > file or the write_file tool instead.',
+    'find': 'Use "dir /s" or the glob tool instead.',
+    'head': 'Use the read_file tool with offset/limit instead.',
+    'tail': 'Use the read_file tool instead.',
+    'wc': 'Use the read_file tool instead.',
+    'diff': 'Use the diff tool instead.',
+    'which': 'Use "where" instead.',
+    'echo': 'echo works on Windows, but avoid pipes (|).',
+};
 export const bashTool = {
     name: 'bash',
     description: 'Execute a shell command and return its output. Use for running tests, build, git, and shell operations. Long-running commands (dev servers, watchers) start in the background and return a process id immediately — manage them with process_list, process_log, process_kill. Set background=true to force background execution.',
@@ -90,6 +109,14 @@ export const bashTool = {
             else if (!output && res.code !== 0) {
                 output = `(exit code ${res.code})`;
             }
+            // On Windows, hint about Unix commands that don't work
+            if (platform() === 'win32' && res.code !== 0) {
+                const firstWord = command.trim().split(/\s+/)[0]?.split(/[\\/]/).pop();
+                const hint = firstWord ? UNIX_TO_WIN_HINTS[firstWord] : undefined;
+                if (hint) {
+                    output = `${output}\n\nHint: "${firstWord}" may not work on Windows. ${hint}`;
+                }
+            }
             // Update audit log with result
             if (securityConfig?.logCommands) {
                 logBashCommand(ctx.sessionId, sanitizeCommandForLog(command), res.code === 0, `Working directory: ${workdir}, Output length: ${res.stdout.length}`);