knoxis-helper 1.4.4 → 1.4.6

package/lib/knoxis-local-agent.js

@@ -28,6 +28,8 @@ const DEFAULT_PORT = parseInt(process.env.KNOXIS_AGENT_PORT || '3456', 10);
 const CERT_DIR = process.env.KNOXIS_CERT_DIR || path.join(os.homedir(), '.knoxis', 'certs');
 const CERT_FILE = process.env.KNOXIS_CERT_FILE || path.join(CERT_DIR, 'localhost.pem');
 const KEY_FILE = process.env.KNOXIS_CERT_KEY || path.join(CERT_DIR, 'localhost-key.pem');
+const PFX_FILE = process.env.KNOXIS_CERT_PFX || path.join(CERT_DIR, 'localhost.pfx');
+const PFX_PASS = 'knoxis-local'; // Not a real secret — self-signed cert for localhost only
 
 // Trusted origins for CORS (deployed frontends)
 const TRUSTED_ORIGINS = [
@@ -77,10 +79,116 @@ function generateSelfSignedCert() {
     return true;
   }
 
-  console.warn('⚠️  OpenSSL failed - running in HTTP mode');
+  console.warn('⚠️  OpenSSL not available');
   return false;
 }
 
+/**
+ * Windows fallback: generate a self-signed certificate via PowerShell.
+ * Uses New-SelfSignedCertificate (built into Windows 10+ / Server 2016+).
+ * Always produces a PFX file. Also attempts PEM export when .NET 5+ is present.
+ * Cert is created in the user's personal store (no admin required) and removed
+ * from the store after export.
+ */
+function generateSelfSignedCertWindows() {
+  console.log('🔐 Generating self-signed certificate via PowerShell...');
+
+  if (!fs.existsSync(CERT_DIR)) {
+    fs.mkdirSync(CERT_DIR, { recursive: true });
+  }
+
+  // Write a PS1 script to a temp file to avoid all shell-escaping issues.
+  const psLines = [
+    '$ErrorActionPreference = "Stop"',
+    '$cert = New-SelfSignedCertificate -Subject "CN=localhost" -DnsName "localhost","127.0.0.1" `',
+    '  -CertStoreLocation "Cert:\\CurrentUser\\My" -NotAfter (Get-Date).AddDays(365) `',
+    '  -KeyExportPolicy Exportable -KeySpec KeyExchange',
+    '$thumb = $cert.Thumbprint',
+    '',
+    '# Export PFX (works on all Windows versions with this cmdlet)',
+    '$pwd = ConvertTo-SecureString -String "' + PFX_PASS + '" -Force -AsPlainText',
+    'Export-PfxCertificate -Cert "Cert:\\CurrentUser\\My\\$thumb" -FilePath "' + PFX_FILE + '" -Password $pwd | Out-Null',
+    '',
+    '# Attempt PEM export — only works on .NET 5+ (PowerShell 7+)',
+    'try {',
+    '  $certDer = $cert.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Cert)',
+    '  $certB64 = [Convert]::ToBase64String($certDer, "InsertLineBreaks")',
+    '  $certPem = "-----BEGIN CERTIFICATE-----`r`n$certB64`r`n-----END CERTIFICATE-----"',
+    '  [System.IO.File]::WriteAllText("' + CERT_FILE + '", $certPem)',
+    '',
+    '  $rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)',
+    '  $keyBytes = $rsa.ExportPkcs8PrivateKey()',
+    '  $keyB64 = [Convert]::ToBase64String($keyBytes, "InsertLineBreaks")',
+    '  $keyPem = "-----BEGIN PRIVATE KEY-----`r`n$keyB64`r`n-----END PRIVATE KEY-----"',
+    '  [System.IO.File]::WriteAllText("' + KEY_FILE + '", $keyPem)',
+    '} catch {',
+    '  # PEM export not available on this .NET version — PFX is sufficient',
+    '}',
+    '',
+    '# Remove cert from user store (the exported files are all we need)',
+    'Remove-Item "Cert:\\CurrentUser\\My\\$thumb" -Force -ErrorAction SilentlyContinue',
+  ];
+
+  const tmpScript = path.join(os.tmpdir(), 'knoxis-cert-' + Date.now() + '.ps1');
+  fs.writeFileSync(tmpScript, psLines.join('\r\n'), 'utf8');
+
+  try {
+    const result = spawnSync('powershell', [
+      '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+      '-File', tmpScript
+    ], { stdio: 'pipe', timeout: 30000 });
+
+    if (result.status === 0 && fs.existsSync(PFX_FILE)) {
+      console.log('✅ Certificate generated via PowerShell');
+      if (fs.existsSync(CERT_FILE) && fs.existsSync(KEY_FILE)) {
+        console.log('   PEM files exported (PFX + PEM)');
+      } else {
+        console.log('   PFX exported (PEM not available on this .NET version)');
+      }
+      return true;
+    }
+
+    console.warn('⚠️  PowerShell certificate generation failed');
+    if (result.stderr) {
+      const firstLine = result.stderr.toString().trim().split('\n')[0];
+      if (firstLine) console.warn('   ' + firstLine);
+    }
+    return false;
+  } finally {
+    try { fs.unlinkSync(tmpScript); } catch (e) {}
+  }
+}
+
+/**
+ * Try to create an HTTPS server from the available cert material.
+ * Returns { opts, source } on success, null on failure.
+ * Checks PEM first (cross-platform), then PFX (Windows PowerShell fallback).
+ */
+function tryLoadCerts() {
+  // Prefer PEM files (generated by openssl or PS .NET 5+)
+  try {
+    if (fs.existsSync(KEY_FILE) && fs.existsSync(CERT_FILE)) {
+      const key = fs.readFileSync(KEY_FILE);
+      const cert = fs.readFileSync(CERT_FILE);
+      return { opts: { key, cert }, source: 'PEM' };
+    }
+  } catch (err) {
+    console.warn('⚠️  Failed to load PEM certificates:', err.message);
+  }
+
+  // Fallback: PFX file (Windows PS 5.1 where PEM export isn't available)
+  try {
+    if (fs.existsSync(PFX_FILE)) {
+      const pfx = fs.readFileSync(PFX_FILE);
+      return { opts: { pfx, passphrase: PFX_PASS }, source: 'PFX' };
+    }
+  } catch (err) {
+    console.warn('⚠️  Failed to load PFX certificate:', err.message);
+  }
+
+  return null;
+}
+
 /**
  * Get CORS headers for the given request origin
  */
@@ -132,6 +240,38 @@ function buildShellCommand(command) {
   return { cmd: 'bash', args: ['-lc', command] };
 }
 
+/**
+ * Build a cross-platform command to pipe a file's contents to stdout.
+ * Uses `type` on Windows (cmd.exe) and `cat` on Unix.
+ */
+function buildCatCommand(filePath) {
+  if (os.platform() === 'win32') {
+    return `type "${filePath}"`;
+  }
+  return `cat "${filePath}"`;
+}
+
+/**
+ * Build a cross-platform command string that sets environment variables
+ * before running a child command.
+ *   Unix:    VAR="val" command
+ *   Windows: set "VAR=val" && command
+ * @param {Record<string,string>} envVars
+ * @param {string} command
+ */
+function buildEnvCommand(envVars, command) {
+  if (os.platform() === 'win32') {
+    const sets = Object.entries(envVars)
+      .map(([k, v]) => `set "${k}=${v}"`)
+      .join(' && ');
+    return `${sets} && ${command}`;
+  }
+  const prefix = Object.entries(envVars)
+    .map(([k, v]) => `${k}="${v}"`)
+    .join(' ');
+  return `${prefix} ${command}`;
+}
+
 function commandExists(cmd) {
   const detector = os.platform() === 'win32' ? 'where' : 'which';
   const result = spawnSync(detector, [cmd], { stdio: 'ignore' });
@@ -509,7 +649,7 @@ async function handleRequest(req, res) {
       if (prompt && prompt.trim().length > 0) {
         promptFile = path.join(os.tmpdir(), 'knoxis-task-' + (sessionId || Date.now()) + '.txt');
         fs.writeFileSync(promptFile, prompt, 'utf8');
-        finalCommand = 'cat "' + promptFile + '" | claude --dangerously-skip-permissions';
+        finalCommand = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
         console.log('📝 Task written to ' + promptFile + ' (' + prompt.length + ' chars)');
       }
 
@@ -768,17 +908,17 @@ async function handleRequest(req, res) {
         const scriptPath = resolveInteractiveScript();
         if (scriptPath) {
           // Interactive mode: multi-turn with Groq pair programmer
-          command = `KNOXIS_TASK_FILE="${promptFile}" node "${scriptPath}"`;
+          command = buildEnvCommand({ KNOXIS_TASK_FILE: promptFile }, `node "${scriptPath}"`);
           mode = 'interactive';
           console.log(`🤝 Interactive mode: ${scriptPath}`);
         } else {
           // Interactive requested but script not found - fall back to single-shot
           console.warn('⚠️ Interactive script not found, falling back to single-shot');
-          command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+          command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
         }
       } else {
         // Standard single-shot mode: pipe task to Claude
-        command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+        command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
       }
 
       if (headless) {
@@ -979,34 +1119,38 @@ function openLinuxTerminal(workspaceDir, command) {
 }
 
 function createServer() {
-  // Try to load existing certs
-  try {
-    if (fs.existsSync(KEY_FILE) && fs.existsSync(CERT_FILE)) {
-      const key = fs.readFileSync(KEY_FILE);
-      const cert = fs.readFileSync(CERT_FILE);
+  // 1. Try to load existing certs (PEM or PFX)
+  const existing = tryLoadCerts();
+  if (existing) {
+    try {
       serverMeta.secure = true;
-      return https.createServer({ key, cert }, handleRequest);
+      console.log('🔒 Loaded existing ' + existing.source + ' certificate');
+      return https.createServer(existing.opts, handleRequest);
+    } catch (err) {
+      console.warn('⚠️  Failed to create HTTPS server from existing certs:', err.message);
     }
-  } catch (err) {
-    console.warn('⚠️  Failed to load TLS certificates:', err.message);
   }
 
-  // No certs exist - try to generate them
-  if (!fs.existsSync(CERT_FILE) || !fs.existsSync(KEY_FILE)) {
-    const generated = generateSelfSignedCert();
-    if (generated && fs.existsSync(KEY_FILE) && fs.existsSync(CERT_FILE)) {
+  // 2. Generate new certs — try openssl first, then Windows PowerShell
+  let generated = generateSelfSignedCert();
+  if (!generated && os.platform() === 'win32') {
+    generated = generateSelfSignedCertWindows();
+  }
+
+  if (generated) {
+    const fresh = tryLoadCerts();
+    if (fresh) {
       try {
-        const key = fs.readFileSync(KEY_FILE);
-        const cert = fs.readFileSync(CERT_FILE);
         serverMeta.secure = true;
-        return https.createServer({ key, cert }, handleRequest);
+        console.log('🔒 Using freshly generated ' + fresh.source + ' certificate');
+        return https.createServer(fresh.opts, handleRequest);
       } catch (err) {
-        console.warn('⚠️  Failed to load generated certificates:', err.message);
+        console.warn('⚠️  Failed to create HTTPS server from generated certs:', err.message);
       }
     }
   }
 
-  // Fallback to HTTP (will cause mixed content issues from HTTPS frontends)
+  // 3. Fallback to HTTP (will cause mixed content issues from HTTPS frontends)
   serverMeta.secure = false;
   console.warn('');
   console.warn('⚠️  RUNNING IN HTTP MODE - This will cause 405/CORS errors from HTTPS frontends!');
@@ -1203,14 +1347,14 @@ function connectRelayWebSocket() {
             // Interactive mode: use multi-turn pair programming script
             const scriptPath = resolveInteractiveScript();
             if (scriptPath) {
-              command = `KNOXIS_TASK_FILE="${promptFile}" node "${scriptPath}"`;
+              command = buildEnvCommand({ KNOXIS_TASK_FILE: promptFile }, `node "${scriptPath}"`);
               console.log(`   🤝 Interactive mode: ${scriptPath}`);
             } else {
-              command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+              command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
               console.warn(`   ⚠️ Interactive script not found, falling back to single-shot`);
             }
           } else {
-            command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+            command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
           }
           console.log(`   📝 Task written to ${promptFile} (${taskPrompt.length} chars)`);
         } else {
@@ -1429,9 +1573,17 @@ server.listen(serverMeta.port, () => {
     console.warn('║  Browsers will block requests from HTTPS sites (like qig.ai) ║');
     console.warn('╚══════════════════════════════════════════════════════════════╝');
     console.warn('');
-    console.warn('To fix this, either:');
-    console.warn(`  1. Install OpenSSL and restart (auto-generates certs)`);
-    console.warn(`  2. Manually place certs in: ${CERT_DIR}`);
+    if (os.platform() === 'win32') {
+      console.warn('To fix this on Windows, try one of:');
+      console.warn('  1. winget install ShiningLight.OpenSSL.Light   (then restart)');
+      console.warn('  2. choco install openssl                      (then restart)');
+      console.warn('  3. Install Git for Windows (ships with OpenSSL)');
+      console.warn(`  4. Manually place PEM or PFX certs in: ${CERT_DIR}`);
+    } else {
+      console.warn('To fix this, either:');
+      console.warn('  1. Install OpenSSL and restart (auto-generates certs)');
+      console.warn(`  2. Manually place certs in: ${CERT_DIR}`);
+    }
     console.warn('');
   } else {
     console.log('✅ HTTPS enabled - ready for secure connections from deployed frontends');

package/lib/knoxis-pair-program.js

@@ -5,6 +5,24 @@ const path = require('path');
 const os = require('os');
 const { spawn, spawnSync, execSync } = require('child_process');
 
+// ===== RETRY CONFIGURATION =====
+// Can be overridden via environment variables
+const RETRY_CONFIG = {
+  maxRetries: parseInt(process.env.KNOXIS_MAX_RETRIES || '3'),
+  retryDelay: parseInt(process.env.KNOXIS_RETRY_DELAY || '30000'), // 30 seconds
+  gitTimeout: parseInt(process.env.KNOXIS_GIT_TIMEOUT || '30000'), // 30 seconds
+  aiCallTimeout: parseInt(process.env.KNOXIS_AI_TIMEOUT || '300000'), // 5 minutes
+  enableRetryLogging: process.env.KNOXIS_RETRY_LOG !== 'false'
+};
+
+// Global retry statistics
+let retryStats = {
+  totalRetries: 0,
+  successfulRetries: 0,
+  failedCommands: [],
+  startTime: Date.now()
+};
+
 function parseArgs(argv) {
   const args = {};
   const multi = {};
@@ -59,7 +77,45 @@ function commandExists(cmd) {
   return result.status === 0;
 }
 
-// Resolve workspace name to path using knoxis registry
+// Resolve workspace name to path using knoxis registry (async version)
+async function resolveWorkspacePathAsync(nameOrPath) {
+  const os = require('os');
+
+  // Direct path - check if exists
+  try {
+    await fs.promises.stat(nameOrPath);
+    return path.resolve(nameOrPath);
+  } catch (e) {
+    // Not a direct path, continue
+  }
+
+  // Try knoxis workspace registry
+  const workspacesFile = path.join(os.homedir(), '.knoxis', 'workspaces.json');
+  try {
+    const data = await fs.promises.readFile(workspacesFile, 'utf8');
+    const workspaces = JSON.parse(data);
+
+    // Exact match
+    if (workspaces[nameOrPath]) {
+      return workspaces[nameOrPath];
+    }
+
+    // Fuzzy match
+    const lower = nameOrPath.toLowerCase();
+    for (const [name, wsPath] of Object.entries(workspaces)) {
+      if (name.toLowerCase().includes(lower)) {
+        console.log(`Matched workspace: ${name} -> ${wsPath}`);
+        return wsPath;
+      }
+    }
+  } catch (e) {
+    // Registry file not found or parse error
+  }
+
+  return null;
+}
+
+// Sync version kept for backward compatibility
 function resolveWorkspacePath(nameOrPath) {
   const os = require('os');
 
@@ -132,32 +188,62 @@ function toArray(value) {
   return [value];
 }
 
-function gatherContext(workspace, inputs) {
+async function gatherContext(workspace, inputs) {
   const sections = [];
   const labels = [];
   const seen = new Set();
+  const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB limit
+  const ALLOWED_EXTENSIONS = /\.(js|jsx|ts|tsx|java|py|json|md|txt|yml|yaml|xml|html|css|scss|sql|sh|bash|env|config|conf)$/i;
 
-  toArray(inputs).forEach(entry => {
+  for (const entry of toArray(inputs)) {
     if (typeof entry !== 'string') {
-      return;
+      continue;
     }
     const trimmed = entry.trim();
     if (!trimmed) {
-      return;
+      continue;
     }
     const absolute = path.isAbsolute(trimmed) ? trimmed : path.join(workspace, trimmed);
-    if (!fs.existsSync(absolute)) {
-      return;
-    }
-    if (seen.has(absolute)) {
-      return;
+
+    try {
+      const stats = await fs.promises.stat(absolute);
+
+      // Skip directories
+      if (stats.isDirectory()) {
+        console.warn(`[Context] Skipping directory: ${absolute}`);
+        continue;
+      }
+
+      // Skip if already processed
+      if (seen.has(absolute)) {
+        continue;
+      }
+
+      // Check file size
+      if (stats.size > MAX_FILE_SIZE) {
+        console.warn(`[Context] Skipping large file (${(stats.size/1048576).toFixed(2)}MB): ${absolute}`);
+        labels.push(path.basename(absolute) + ' [too large]');
+        sections.push(formatSection(path.basename(absolute), `[File too large: ${(stats.size/1048576).toFixed(2)}MB]`));
+        continue;
+      }
+
+      // Check file extension
+      if (!ALLOWED_EXTENSIONS.test(absolute)) {
+        console.warn(`[Context] Skipping non-text file: ${absolute}`);
+        continue;
+      }
+
+      seen.add(absolute);
+      const content = await fs.promises.readFile(absolute, 'utf8');
+      const title = path.relative(workspace, absolute) || path.basename(absolute);
+      labels.push(title);
+      sections.push(formatSection(title, content));
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        console.error(`[Context] Error reading ${absolute}: ${err.message}`);
+      }
     }
-    seen.add(absolute);
-    const content = fs.readFileSync(absolute, 'utf8');
-    const title = path.relative(workspace, absolute) || path.basename(absolute);
-    labels.push(title);
-    sections.push(formatSection(title, content));
-  });
+  }
 
   return { sections, labels };
 }
@@ -309,7 +395,7 @@ function buildPrompt(options) {
   return sections.join('\n\n');
 }
 
-async function callAi(aiConfig, prompt, livePrinter) {
+async function callAiBase(aiConfig, prompt, livePrinter) {
   return new Promise((resolve, reject) => {
     const proc = spawn(aiConfig.cmd, aiConfig.args, { stdio: ['pipe', 'pipe', 'pipe'] });
     let stdout = '';
@@ -350,6 +436,60 @@ async function callAi(aiConfig, prompt, livePrinter) {
   });
 }
 
+async function callAi(aiConfig, prompt, livePrinter, options = {}) {
+  const maxRetries = options.maxRetries || RETRY_CONFIG.maxRetries;
+  const retryDelay = options.retryDelay || RETRY_CONFIG.retryDelay;
+  const enableLogging = options.silent === false || RETRY_CONFIG.enableRetryLogging;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const timestamp = new Date().toISOString();
+      if (enableLogging) {
+        console.log(`[${timestamp}] [AI Call - Attempt ${attempt}/${maxRetries}] Invoking ${aiConfig.label}...`);
+      }
+      if (attempt > 1) {
+        retryStats.totalRetries++;
+      }
+
+      const result = await callAiBase(aiConfig, prompt, livePrinter);
+
+      if (attempt > 1) {
+        retryStats.successfulRetries++;
+        if (enableLogging) {
+          console.log(`[AI Call - Success] Recovered after ${attempt} attempts`);
+        }
+      }
+      return result;
+    } catch (error) {
+      const isLastAttempt = attempt === maxRetries;
+      const timestamp = new Date().toISOString();
+
+      if (enableLogging) {
+        console.error(`[${timestamp}] [AI Call - Attempt ${attempt}/${maxRetries}] Failed`);
+        console.error(`  Provider: ${aiConfig.label}`);
+        console.error(`  Error: ${error.message}`);
+      }
+
+      if (!isLastAttempt) {
+        if (enableLogging) {
+          console.log(`[AI Call - Retry] Waiting ${retryDelay/1000} seconds before retry...`);
+        }
+        await new Promise(resolve => setTimeout(resolve, retryDelay));
+      } else {
+        if (enableLogging) {
+          console.error(`[AI Call - Failed] Max retries reached. AI call failed permanently.`);
+        }
+        retryStats.failedCommands.push({
+          command: `AI call to ${aiConfig.label}`,
+          error: error.message,
+          timestamp: timestamp
+        });
+        throw error;
+      }
+    }
+  }
+}
+
 // ===== SESSION RECORDING =====
 // Records full prompts, responses, git diffs, and timing for model training
 
@@ -359,8 +499,134 @@ function ensureSessionDir() {
   if (!fs.existsSync(SESSIONS_DIR)) fs.mkdirSync(SESSIONS_DIR, { recursive: true });
 }
 
-function safeExec(cmd, cwd) {
-  try { return execSync(cmd, { cwd, encoding: 'utf8', timeout: 10000 }).trim(); } catch (e) { return null; }
+// Async version with proper setTimeout
+async function safeExecAsync(cmd, cwd, options = {}) {
+  const { exec } = require('child_process');
+  const util = require('util');
+  const execAsync = util.promisify(exec);
+
+  const maxRetries = options.maxRetries || RETRY_CONFIG.maxRetries;
+  const retryDelay = options.retryDelay || RETRY_CONFIG.retryDelay;
+  const timeout = options.timeout || RETRY_CONFIG.gitTimeout;
+  const silent = options.silent || !RETRY_CONFIG.enableRetryLogging;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      if (!silent && attempt > 1) {
+        console.log(`[Git Retry ${attempt}/${maxRetries}] Executing: ${cmd.substring(0, 50)}...`);
+        retryStats.totalRetries++;
+      }
+
+      const { stdout } = await execAsync(cmd, {
+        cwd,
+        encoding: 'utf8',
+        timeout,
+        maxBuffer: 10 * 1024 * 1024 // 10MB buffer
+      });
+
+      const result = stdout.trim();
+
+      if (attempt > 1) {
+        retryStats.successfulRetries++;
+        if (!silent) {
+          console.log(`[Git Success] Command recovered after ${attempt} attempts`);
+        }
+      }
+      return result;
+    } catch (e) {
+      const isLastAttempt = attempt === maxRetries;
+      if (!silent) {
+        const timestamp = new Date().toISOString();
+        console.error(`[${timestamp}] [Git Attempt ${attempt}/${maxRetries}] Command failed: ${cmd.substring(0, 50)}...`);
+        console.error(`  Error: ${e.message || 'Unknown error'}`);
+        if (e.code === 'ETIMEDOUT') {
+          console.error(`  Timeout after ${timeout/1000} seconds`);
+        }
+      }
+
+      if (!isLastAttempt) {
+        if (!silent) {
+          console.log(`  Waiting ${retryDelay/1000} seconds before retry...`);
+        }
+        // Proper async delay
+        await new Promise(resolve => setTimeout(resolve, retryDelay));
+      } else {
+        if (!silent) {
+          console.error(`  Max retries reached. Command failed permanently.`);
+        }
+        retryStats.failedCommands.push({
+          command: cmd.substring(0, 100),
+          error: e.message,
+          timestamp: new Date().toISOString()
+        });
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+// Sync version (kept for backward compatibility)
+function safeExec(cmd, cwd, options = {}) {
+  const maxRetries = options.maxRetries || RETRY_CONFIG.maxRetries;
+  const retryDelay = options.retryDelay || RETRY_CONFIG.retryDelay;
+  const timeout = options.timeout || RETRY_CONFIG.gitTimeout;
+  const silent = options.silent || !RETRY_CONFIG.enableRetryLogging;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      if (!silent && attempt > 1) {
+        console.log(`[Git Retry ${attempt}/${maxRetries}] Executing: ${cmd.substring(0, 50)}...`);
+        retryStats.totalRetries++;
+      }
+      const result = execSync(cmd, { cwd, encoding: 'utf8', timeout }).trim();
+      if (attempt > 1) {
+        retryStats.successfulRetries++;
+        if (!silent) {
+          console.log(`[Git Success] Command recovered after ${attempt} attempts`);
+        }
+      }
+      return result;
+    } catch (e) {
+      const isLastAttempt = attempt === maxRetries;
+      if (!silent) {
+        const timestamp = new Date().toISOString();
+        console.error(`[${timestamp}] [Git Attempt ${attempt}/${maxRetries}] Command failed: ${cmd.substring(0, 50)}...`);
+        console.error(`  Error: ${e.message || 'Unknown error'}`);
+        if (e.code === 'ETIMEDOUT') {
+          console.error(`  Timeout after ${timeout/1000} seconds`);
+        }
+      }
+
+      if (!isLastAttempt) {
+        if (!silent) {
+          console.log(`  Waiting ${retryDelay/1000} seconds before retry...`);
+        }
+        // Cross-platform sleep
+        const sleepCmd = process.platform === 'win32'
+          ? `powershell -Command "Start-Sleep -Seconds ${retryDelay/1000}"`
+          : `sleep ${retryDelay/1000}`;
+        try {
+          execSync(sleepCmd, { stdio: 'ignore' });
+        } catch (sleepError) {
+          // If sleep command fails, we have to skip the delay
+          // Busy-wait is too CPU intensive and blocks the event loop
+          console.warn(`[Warning] Unable to sleep between retries, continuing immediately`);
+        }
+      } else {
+        if (!silent) {
+          console.error(`  Max retries reached. Command failed permanently.`);
+        }
+        retryStats.failedCommands.push({
+          command: cmd.substring(0, 100),
+          error: e.message,
+          timestamp: new Date().toISOString()
+        });
+        return null;
+      }
+    }
+  }
+  return null;
 }
 
 function slugify(text) {
@@ -404,6 +670,34 @@ class SessionRecorder {
     s.error = error || null;
   }
 
+  async saveAsync() {
+    const record = {
+      sessionId: this.sessionId, version: '1.0.0',
+      task: this.task, workspace: this.workspace, aiProvider: this.aiProvider,
+      startedAt: this.startedAt, completedAt: new Date().toISOString(),
+      totalDurationMs: Date.now() - new Date(this.startedAt).getTime(),
+      steps: this.steps,
+      totalSteps: this.steps.length,
+      completedSteps: this.steps.filter(s => s.completedAt && !s.error).length,
+      git: {
+        initialCommit: this.initialCommit,
+        finalCommit: await safeExecAsync('git rev-parse --short HEAD', this.workspace) || '',
+        totalDiff: await safeExecAsync('git diff', this.workspace) || ''
+      },
+      environment: { platform: os.platform(), nodeVersion: process.version }
+    };
+    const filename = `${this.sessionId}-${slugify(this.task)}.json`;
+    const filepath = path.join(SESSIONS_DIR, filename);
+    await fs.promises.writeFile(filepath, JSON.stringify(record, null, 2), 'utf8');
+    // Append to index
+    try {
+      await fs.promises.appendFile(path.join(SESSIONS_DIR, 'index.jsonl'),
+        JSON.stringify({ sessionId: record.sessionId, task: record.task, startedAt: record.startedAt, totalDurationMs: record.totalDurationMs, file: filename }) + '\n');
+    } catch (e) {}
+    return filepath;
+  }
+
+  // Sync version kept for backward compatibility
   save() {
     const record = {
       sessionId: this.sessionId, version: '1.0.0',
@@ -484,7 +778,7 @@ async function run() {
     globalContextInputs.push(timeline.sharedContext);
   }
 
-  const globalContext = gatherContext(workspace, globalContextInputs);
+  const globalContext = await gatherContext(workspace, globalContextInputs);
   const globalContextBlock = globalContext.sections.join('\n\n');
 
   let scheduledSteps;
@@ -557,7 +851,7 @@ IMPORTANT: Work autonomously. Do not ask questions or wait for confirmation. Mak
 Only work inside the provided workspace and preserve user data.`;
 
   for (const step of scheduledSteps) {
-    const stepContext = gatherContext(workspace, step.contextPaths);
+    const stepContext = await gatherContext(workspace, step.contextPaths);
     if (stepContext.labels.length) {
       console.log(`Step context for ${step.displayName}: ${stepContext.labels.join(', ')}`);
       console.log('');
@@ -614,10 +908,49 @@ Only work inside the provided workspace and preserve user data.`;
     console.log('');
   }
 
+  // Print retry statistics if any retries occurred
+  printRetryStatistics();
+
   console.log('Session complete. Knoxis and the AI partner are standing by for further instructions.');
 }
 
+function printRetryStatistics() {
+  if (retryStats.totalRetries === 0 && retryStats.failedCommands.length === 0) {
+    return; // No retries needed, don't print stats
+  }
+
+  console.log('');
+  console.log('===== RETRY STATISTICS =====');
+  console.log(`Total Retries: ${retryStats.totalRetries}`);
+  console.log(`Successful Recoveries: ${retryStats.successfulRetries}`);
+  console.log(`Failed After Max Retries: ${retryStats.failedCommands.length}`);
+
+  if (retryStats.failedCommands.length > 0) {
+    console.log('\nFailed Commands:');
+    retryStats.failedCommands.forEach((failure, index) => {
+      console.log(`  ${index + 1}. [${failure.timestamp}]`);
+      console.log(`     Command: ${failure.command}`);
+      console.log(`     Error: ${failure.error}`);
+    });
+  }
+
+  const sessionDuration = Date.now() - retryStats.startTime;
+  const minutes = Math.floor(sessionDuration / 60000);
+  const seconds = Math.floor((sessionDuration % 60000) / 1000);
+  console.log(`\nSession Duration: ${minutes}m ${seconds}s`);
+
+  if (retryStats.totalRetries > 0) {
+    const retryOverhead = retryStats.totalRetries * RETRY_CONFIG.retryDelay;
+    const overheadMinutes = Math.floor(retryOverhead / 60000);
+    const overheadSeconds = Math.floor((retryOverhead % 60000) / 1000);
+    console.log(`Estimated Retry Overhead: ${overheadMinutes}m ${overheadSeconds}s`);
+  }
+  console.log('============================');
+  console.log('');
+}
+
 run().catch(err => {
-  console.error(err.message);
+  console.error('Fatal error:', err.message);
+  printRetryStatistics();
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knoxis-helper",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "Local helper for Knoxis pair programming - connects your machine to Knoxis on qig.ai",
   "bin": {
     "knoxis-helper": "./bin/knoxis-helper.js"