knoxis-helper 1.5.0 → 1.5.2

package/bin/knoxis-helper.js

@@ -99,6 +99,7 @@ function installAgentLocally(force) {
   const sourceInteractivePair = path.join(libDir, 'knoxis-interactive-pair.js');
   const sourceStateScaffold = path.join(libDir, 'state-scaffold.js');
   const sourcePortalSync = path.join(libDir, 'portal-sync.js');
+  const sourceSessionRecorder = path.join(libDir, 'session-recorder.js');
   const sourceTemplatesDir = path.join(libDir, 'templates');
   const sourcePackage = path.join(__dirname, '..', 'package.json');
 
@@ -150,6 +151,11 @@ function installAgentLocally(force) {
     console.log('  Installed: portal-sync.js');
   }
 
+  if (fs.existsSync(sourceSessionRecorder)) {
+    fs.copyFileSync(sourceSessionRecorder, path.join(AGENT_DIR, 'session-recorder.js'));
+    console.log('  Installed: session-recorder.js');
+  }
+
   if (fs.existsSync(sourceTemplatesDir)) {
     copyDirRecursive(sourceTemplatesDir, path.join(AGENT_DIR, 'templates'));
     console.log('  Installed: templates/');

package/lib/knoxis-interactive-pair.js

@@ -33,6 +33,9 @@ const https = require('https');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { SessionRecorder } = require('./session-recorder');
+const { scaffoldStateLayout } = require('./state-scaffold');
+const { syncSessionToPortal } = require('./portal-sync');
 
 // === CONFIG ===
 const CONFIG_PATH = path.join(os.homedir(), '.knoxis', 'config.json');
@@ -269,6 +272,42 @@ async function runSingleShot(task) {
   return result.code || 0;
 }
 
+// === IDENTITY (passed by knoxis-local-agent via env vars) ===
+function readIdentityFromEnv() {
+  const taskIds = (process.env.KNOXIS_TASK_IDS || '')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
+  return {
+    workspace: process.env.KNOXIS_WORKSPACE_PATH || process.cwd(),
+    userId: process.env.KNOXIS_USER_ID || (config && config.userId) || null,
+    workspaceId: process.env.KNOXIS_WORKSPACE_ID || null,
+    taskIds,
+    productSlug: process.env.KNOXIS_PRODUCT_SLUG || null,
+    projectSlug: process.env.KNOXIS_PROJECT_SLUG || null,
+    engineerId: process.env.KNOXIS_USER_ID || (config && config.userId) || null
+  };
+}
+
+// === RECORDER + PORTAL FINALIZATION ===
+// Saves the session JSON locally and POSTs to the portal stub. Called from
+// every exit path so partial / fallback sessions still surface in the UI.
+async function finalizeSession(recorder) {
+  if (!recorder) return;
+  try {
+    const filepath = await recorder.saveAsync();
+    console.log('  Session JSON: ' + filepath);
+  } catch (e) {
+    console.warn('  Could not save session JSON: ' + e.message);
+  }
+  try {
+    const record = recorder.buildFinalRecord();
+    await syncSessionToPortal(record);
+  } catch (e) {
+    console.warn('  Portal-sync errored: ' + e.message);
+  }
+}
+
 // === MAIN ===
 async function main() {
   const task = loadTask();
@@ -282,15 +321,40 @@ async function main() {
 
   initSessionLog();
 
+  // Auto-scaffold + recorder. Idempotent — pre-existing files preserved.
+  const identity = readIdentityFromEnv();
+  let scaffoldResult = null;
+  try {
+    scaffoldResult = scaffoldStateLayout(identity.workspace);
+  } catch (e) {
+    console.warn('  Scaffold failed: ' + e.message);
+  }
+
+  const recorder = new SessionRecorder(task, identity.workspace, 'Claude Code + Knoxis (Groq)', {
+    mode: null,             // interactive flow isn't a kit mode
+    archetype: null,
+    productSlug: identity.productSlug,
+    projectSlug: identity.projectSlug,
+    engineerId: identity.engineerId,
+    userId: identity.userId,
+    workspaceId: identity.workspaceId,
+    taskIds: identity.taskIds
+  });
+
   console.log('');
   console.log('╔══════════════════════════════════════════════════════════════╗');
   console.log('║        KNOXIS INTERACTIVE PAIR PROGRAMMING                  ║');
   console.log('╚══════════════════════════════════════════════════════════════╝');
   console.log('');
-  console.log('  Task:    ' + task.substring(0, 100) + (task.length > 100 ? '...' : ''));
-  console.log('  Session: ' + SESSION_ID);
-  console.log('  Pair:    ' + (hasGroq ? 'Groq (' + GROQ_MODEL + ')' : 'Disabled (no GROQ_API_KEY)'));
-  console.log('  Timeout: ' + (MAX_PHASE_MS / 60000).toFixed(0) + ' min per phase');
+  console.log('  Task:      ' + task.substring(0, 100) + (task.length > 100 ? '...' : ''));
+  console.log('  Session:   ' + SESSION_ID);
+  console.log('  Recorded:  ' + recorder.sessionId);
+  console.log('  Workspace: ' + identity.workspace);
+  console.log('  Pair:      ' + (hasGroq ? 'Groq (' + GROQ_MODEL + ')' : 'Disabled (no GROQ_API_KEY)'));
+  console.log('  Timeout:   ' + (MAX_PHASE_MS / 60000).toFixed(0) + ' min per phase');
+  if (scaffoldResult && (scaffoldResult.dirs.length || scaffoldResult.files.length)) {
+    console.log('  Scaffolded: ' + (scaffoldResult.dirs.length + scaffoldResult.files.length) + ' new entries (CODING_RULES + docs/state/)');
+  }
   console.log('');
 
   appendLog('# Knoxis Interactive Pair Programming Session');
@@ -301,7 +365,11 @@ async function main() {
 
   // If no Groq, fall back to enhanced single-shot
   if (!hasGroq) {
+    const idx = recorder.startStep('single-shot', 'Claude Code', task);
+    recorder.setStepPrompt(idx, task);
     const code = await runSingleShot(task);
+    recorder.completeStep(idx, '(single-shot mode; output streamed live)', code !== 0 ? `exit ${code}` : null);
+    await finalizeSession(recorder);
     process.exit(code);
   }
 
@@ -352,8 +420,11 @@ async function main() {
     'Share your plan and then STOP. Do not implement yet. I will review it first.',
   ].join('\n');
 
+  const phase1Idx = recorder.startStep('understand-plan', 'Claude Code', planPrompt);
+  recorder.setStepPrompt(phase1Idx, planPrompt);
   const phase1 = await runClaudeTurn(planPrompt, false);
   appendLog(phase1.stdout + '\n');
+  recorder.completeStep(phase1Idx, phase1.stdout, phase1.code !== 0 && !phase1.stdout ? `exit ${phase1.code}: ${phase1.stderr || '(empty)'}` : null);
 
   if (phase1.code !== 0 && !phase1.stdout) {
     console.log('');
@@ -362,9 +433,13 @@ async function main() {
       console.log('  stderr: ' + phase1.stderr.split('\n').slice(0, 5).join('\n  '));
     }
     appendLog('Phase 1 failed (exit ' + phase1.code + '). stderr: ' + (phase1.stderr || '(empty)') + '\n');
+    const fallbackIdx = recorder.startStep('single-shot-fallback', 'Claude Code', task);
+    recorder.setStepPrompt(fallbackIdx, task);
     const code = await runSingleShot(task);
+    recorder.completeStep(fallbackIdx, '(single-shot fallback; output streamed live)', code !== 0 ? `exit ${code}` : null);
     const logFile = saveSessionLog();
     if (logFile) console.log('  Log: ' + logFile);
+    await finalizeSession(recorder);
     process.exit(code);
   }
 
@@ -377,12 +452,13 @@ async function main() {
   console.log('  KNOXIS: Reviewing plan...');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
 
-  const planReview = await callGroq(
-    groqSystem,
-    'Claude produced the following plan:\n\n'
-      + phase1.stdout.substring(0, 8000)
-      + '\n\nReview this plan. Answer any questions Claude asked. Approve or suggest specific changes. Then tell Claude to proceed with implementation.'
-  );
+  const planReviewPrompt = 'Claude produced the following plan:\n\n'
+    + phase1.stdout.substring(0, 8000)
+    + '\n\nReview this plan. Answer any questions Claude asked. Approve or suggest specific changes. Then tell Claude to proceed with implementation.';
+  const planReviewIdx = recorder.startStep('knoxis-plan-review', 'Knoxis (Groq)', planReviewPrompt);
+  recorder.setStepPrompt(planReviewIdx, planReviewPrompt);
+  const planReview = await callGroq(groqSystem, planReviewPrompt);
+  recorder.completeStep(planReviewIdx, planReview, null);
 
   console.log('');
   console.log('  Knoxis: ' + planReview);
@@ -399,8 +475,11 @@ async function main() {
   console.log('');
   appendLog('## Phase 2: Implementation\n');
 
+  const phase2Idx = recorder.startStep('implement', 'Claude Code', planReview);
+  recorder.setStepPrompt(phase2Idx, planReview);
   const phase2 = await runClaudeTurn(planReview, true);
   appendLog(phase2.stdout.substring(0, 10000) + '\n');
+  recorder.completeStep(phase2Idx, phase2.stdout, phase2.code !== 0 ? `exit ${phase2.code}: ${(phase2.stderr || '').slice(0, 200)}` : null);
 
   // If resume failed (session not found), try context accumulation fallback
   if (phase2.code !== 0 && phase2.stderr && phase2.stderr.includes('session')) {
@@ -418,9 +497,11 @@ async function main() {
       'Now implement the solution. Follow existing patterns in the codebase.',
     ].join('\n');
 
+    const phase2bIdx = recorder.startStep('implement-fallback', 'Claude Code', fallbackPrompt);
+    recorder.setStepPrompt(phase2bIdx, fallbackPrompt);
     const phase2b = await runClaudeTurn(fallbackPrompt, false);
-    // Use new session for subsequent turns
     appendLog(phase2b.stdout.substring(0, 10000) + '\n');
+    recorder.completeStep(phase2bIdx, phase2b.stdout, phase2b.code !== 0 ? `exit ${phase2b.code}` : null);
 
     // Skip to verification with this result
     const verifyPrompt = 'Verify the changes compile/build correctly. Run the most relevant test or build command. Give a brief summary of what was done.';
@@ -430,8 +511,11 @@ async function main() {
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     console.log('');
 
+    const phase3bIdx = recorder.startStep('verify', 'Claude Code', verifyPrompt);
+    recorder.setStepPrompt(phase3bIdx, verifyPrompt);
     const phase3b = await runClaudeTurn(verifyPrompt, true);
     appendLog('## Phase 3: Verification\n' + phase3b.stdout.substring(0, 5000) + '\n');
+    recorder.completeStep(phase3bIdx, phase3b.stdout, phase3b.code !== 0 ? `exit ${phase3b.code}` : null);
 
     console.log('');
     console.log('╔══════════════════════════════════════════════════════════════╗');
@@ -441,6 +525,7 @@ async function main() {
     if (logFile) console.log('  Log: ' + logFile);
     console.log('  Resume: claude --resume ' + SESSION_ID);
     console.log('');
+    await finalizeSession(recorder);
     process.exit(phase3b.code || 0);
   }
 
@@ -453,12 +538,13 @@ async function main() {
   console.log('  KNOXIS: Reviewing implementation...');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
 
-  const implReview = await callGroq(
-    groqSystem,
-    'Claude implemented the following:\n\n'
-      + phase2.stdout.substring(0, 8000)
-      + '\n\nReview the implementation. If there are issues, describe specifically what needs fixing. If it looks correct, tell Claude to verify the build/tests and summarize what was done.'
-  );
+  const implReviewPrompt = 'Claude implemented the following:\n\n'
+    + phase2.stdout.substring(0, 8000)
+    + '\n\nReview the implementation. If there are issues, describe specifically what needs fixing. If it looks correct, tell Claude to verify the build/tests and summarize what was done.';
+  const implReviewIdx = recorder.startStep('knoxis-impl-review', 'Knoxis (Groq)', implReviewPrompt);
+  recorder.setStepPrompt(implReviewIdx, implReviewPrompt);
+  const implReview = await callGroq(groqSystem, implReviewPrompt);
+  recorder.completeStep(implReviewIdx, implReview, null);
 
   console.log('');
   console.log('  Knoxis: ' + implReview);
@@ -475,12 +561,13 @@ async function main() {
   console.log('');
   appendLog('## Phase 3: Verification\n');
 
-  const phase3 = await runClaudeTurn(
-    implReview
-      + '\n\nAfter addressing any feedback above, verify the changes compile/build correctly. Run the most relevant test or build command. Give a brief summary of everything that was done.',
-    true
-  );
+  const phase3Prompt = implReview
+    + '\n\nAfter addressing any feedback above, verify the changes compile/build correctly. Run the most relevant test or build command. Give a brief summary of everything that was done.';
+  const phase3Idx = recorder.startStep('verify', 'Claude Code', phase3Prompt);
+  recorder.setStepPrompt(phase3Idx, phase3Prompt);
+  const phase3 = await runClaudeTurn(phase3Prompt, true);
   appendLog(phase3.stdout.substring(0, 5000) + '\n');
+  recorder.completeStep(phase3Idx, phase3.stdout, phase3.code !== 0 ? `exit ${phase3.code}` : null);
 
 
   // ═══════════════════════════════════════════
@@ -497,6 +584,7 @@ async function main() {
   if (logFile) console.log('  Log:     ' + logFile);
   console.log('');
 
+  await finalizeSession(recorder);
   process.exit(phase3.code || 0);
 }
 

package/lib/knoxis-local-agent.js

@@ -990,8 +990,16 @@ async function handleRequest(req, res) {
       } else if (interactive) {
         const scriptPath = resolveInteractiveScript();
         if (scriptPath) {
-          // Interactive mode: multi-turn with Groq pair programmer
-          command = buildEnvCommand({ KNOXIS_TASK_FILE: promptFile }, `node "${scriptPath}"`);
+          // Interactive mode: multi-turn with Groq pair programmer.
+          // Pass identity env vars so the script can build a schema-aligned
+          // session record and POST it via portal-sync.
+          const interactiveEnv = { KNOXIS_TASK_FILE: promptFile, KNOXIS_WORKSPACE_PATH: workspaceDir };
+          if (portalUserId) interactiveEnv.KNOXIS_USER_ID = portalUserId;
+          if (portalWorkspaceId) interactiveEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
+          if (portalTaskIds && portalTaskIds.length) interactiveEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+          if (productSlug) interactiveEnv.KNOXIS_PRODUCT_SLUG = productSlug;
+          if (projectSlug) interactiveEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+          command = buildEnvCommand(interactiveEnv, `node "${scriptPath}"`);
           mode = 'interactive';
           console.log(`🤝 Interactive mode: ${scriptPath}`);
         } else {
@@ -1463,10 +1471,18 @@ function connectRelayWebSocket() {
           fs.writeFileSync(promptFile, taskPrompt, 'utf8');
 
           if (interactive) {
-            // Interactive mode: use multi-turn pair programming script
+            // Interactive mode: use multi-turn pair programming script.
+            // Pass identity env vars so the script can build a schema-aligned
+            // session record and POST it via portal-sync.
             const scriptPath = resolveInteractiveScript();
             if (scriptPath) {
-              command = buildEnvCommand({ KNOXIS_TASK_FILE: promptFile }, `node "${scriptPath}"`);
+              const interactiveEnv = { KNOXIS_TASK_FILE: promptFile, KNOXIS_WORKSPACE_PATH: wsDir };
+              if (portalUserId) interactiveEnv.KNOXIS_USER_ID = portalUserId;
+              if (portalWorkspaceId) interactiveEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
+              if (portalTaskIds && portalTaskIds.length) interactiveEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+              if (productSlug) interactiveEnv.KNOXIS_PRODUCT_SLUG = productSlug;
+              if (projectSlug) interactiveEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+              command = buildEnvCommand(interactiveEnv, `node "${scriptPath}"`);
               console.log(`   🤝 Interactive mode: ${scriptPath}`);
             } else {
               command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';

package/lib/knoxis-pair-program.js

@@ -7,6 +7,7 @@ const { spawn, spawnSync, execSync } = require('child_process');
 const kitTemplates = require('./templates');
 const { scaffoldStateLayout, assertStateLayout } = require('./state-scaffold');
 const { syncSessionToPortal } = require('./portal-sync');
+const { SessionRecorder } = require('./session-recorder');
 
 // ===== RETRY CONFIGURATION =====
 // Can be overridden via environment variables
@@ -494,13 +495,10 @@ async function callAi(aiConfig, prompt, livePrinter, options = {}) {
 }
 
 // ===== SESSION RECORDING =====
-// Records full prompts, responses, git diffs, and timing for model training
-
-const SESSIONS_DIR = path.join(os.homedir(), '.knoxis', 'sessions');
-
-function ensureSessionDir() {
-  if (!fs.existsSync(SESSIONS_DIR)) fs.mkdirSync(SESSIONS_DIR, { recursive: true });
-}
+// SessionRecorder + helpers live in ./session-recorder.js (shared with
+// knoxis-interactive-pair.js). The retry-aware safeExec/safeExecAsync below
+// are still defined here and injected into SessionRecorder via constructor
+// meta so this script keeps its existing retry behavior on git calls.
 
 // Async version with proper setTimeout
 async function safeExecAsync(cmd, cwd, options = {}) {
@@ -632,153 +630,6 @@ function safeExec(cmd, cwd, options = {}) {
   return null;
 }
 
-function slugify(text) {
-  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60);
-}
-
-class SessionRecorder {
-  constructor(task, workspace, aiProvider, meta = {}) {
-    this.sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    this.task = task;
-    this.workspace = workspace;
-    this.aiProvider = aiProvider;
-    this.startedAt = new Date().toISOString();
-    this.steps = [];
-    this.initialCommit = safeExec('git rev-parse --short HEAD', workspace);
-    // Schema-aligned metadata — maps to portal contract §3.4 SESSION fields.
-    this.mode = meta.mode || null;
-    this.archetype = meta.archetype || null;
-    this.productSlug = meta.productSlug || null;
-    this.projectSlug = meta.projectSlug || null;
-    this.engineerId = meta.engineerId || null;
-    // QIG portal linkage (set when launching from collaboration/tasks UI).
-    this.userId = meta.userId || null;            // profiles.id (auth user)
-    this.workspaceId = meta.workspaceId || null;  // collab_workspaces.id
-    this.taskIds = Array.isArray(meta.taskIds) ? meta.taskIds.filter(Boolean) : [];
-    ensureSessionDir();
-  }
-
-  startStep(key, agent, instruction) {
-    const step = {
-      stepKey: key, agentName: agent, instruction,
-      prompt: null, response: null,
-      startedAt: new Date().toISOString(), completedAt: null, durationMs: null,
-      gitDiffBefore: safeExec('git diff', this.workspace) || '',
-      gitDiffAfter: null, error: null
-    };
-    this.steps.push(step);
-    return this.steps.length - 1;
-  }
-
-  setStepPrompt(idx, prompt) { if (this.steps[idx]) this.steps[idx].prompt = prompt; }
-
-  completeStep(idx, response, error) {
-    const s = this.steps[idx];
-    if (!s) return;
-    s.response = response;
-    s.completedAt = new Date().toISOString();
-    s.durationMs = new Date(s.completedAt) - new Date(s.startedAt);
-    s.gitDiffAfter = safeExec('git diff', this.workspace) || '';
-    s.codeChanged = s.gitDiffBefore !== s.gitDiffAfter;
-    s.error = error || null;
-  }
-
-  async saveAsync() {
-    const finalCommit = await safeExecAsync('git rev-parse --short HEAD', this.workspace) || '';
-    const totalDiff = await safeExecAsync('git diff', this.workspace) || '';
-    const record = this._buildRecord(finalCommit, totalDiff);
-    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, mode: record.mode, archetype: record.archetype, task: record.task, startedAt: record.startedAt, totalDurationMs: record.totalDurationMs, file: filename }) + '\n');
-    } catch (e) {}
-    return filepath;
-  }
-
-  // Sync version kept for backward compatibility
-  save() {
-    const finalCommit = safeExec('git rev-parse --short HEAD', this.workspace);
-    const totalDiff = safeExec('git diff', this.workspace) || '';
-    const record = this._buildRecord(finalCommit, totalDiff);
-    const filename = `${this.sessionId}-${slugify(this.task)}.json`;
-    const filepath = path.join(SESSIONS_DIR, filename);
-    fs.writeFileSync(filepath, JSON.stringify(record, null, 2), 'utf8');
-    // Append to index
-    try {
-      fs.appendFileSync(path.join(SESSIONS_DIR, 'index.jsonl'),
-        JSON.stringify({ sessionId: record.sessionId, mode: record.mode, archetype: record.archetype, task: record.task, startedAt: record.startedAt, totalDurationMs: record.totalDurationMs, file: filename }) + '\n');
-    } catch (e) {}
-    return filepath;
-  }
-
-  buildFinalRecord() {
-    const finalCommit = safeExec('git rev-parse --short HEAD', this.workspace);
-    const totalDiff = safeExec('git diff', this.workspace) || '';
-    return this._buildRecord(finalCommit, totalDiff);
-  }
-
-  _buildRecord(finalCommit, totalDiff) {
-    const completedSteps = this.steps.filter(s => s.completedAt && !s.error).length;
-    const closedCleanly = this.steps.length > 0 && completedSteps === this.steps.length;
-    return {
-      // Identification
-      sessionId: this.sessionId,
-      version: '1.1.0',
-      // Portal contract §3.4 SESSION shape
-      mode: this.mode,
-      archetype: this.archetype,
-      productSlug: this.productSlug,
-      projectSlug: this.projectSlug,
-      engineerId: this.engineerId,
-      // QIG portal linkage
-      userId: this.userId,
-      workspaceId: this.workspaceId,
-      taskIds: this.taskIds,
-      task: this.task,
-      workspace: this.workspace,
-      aiProvider: this.aiProvider,
-      startedAt: this.startedAt,
-      completedAt: new Date().toISOString(),
-      totalDurationMs: Date.now() - new Date(this.startedAt).getTime(),
-      // Step-level detail (preserved from v1.0.0)
-      steps: this.steps,
-      totalSteps: this.steps.length,
-      completedSteps,
-      closedCleanly,
-      // Derived collections — populated initially as empty arrays so the
-      // portal can index them; structured extraction from Claude responses
-      // is a follow-up. Maps to portal contract fields decisions_logged,
-      // waivers_requested, incidents_flagged, rule_violations.
-      filesTouched: extractFilesTouched(totalDiff),
-      decisionsLogged: [],
-      waiversRequested: [],
-      incidentsFlagged: [],
-      ruleViolations: [],
-      archetypeSpecificData: {},
-      git: {
-        initialCommit: this.initialCommit,
-        finalCommit,
-        totalDiff
-      },
-      environment: { platform: os.platform(), nodeVersion: process.version }
-    };
-  }
-}
-
-function extractFilesTouched(diff) {
-  if (!diff || typeof diff !== 'string') return [];
-  const seen = new Set();
-  const re = /^diff --git a\/(\S+) b\/(\S+)/gm;
-  let match;
-  while ((match = re.exec(diff)) !== null) {
-    seen.add(match[2] || match[1]);
-  }
-  return Array.from(seen);
-}
-
 // ===== MAIN =====
 
 async function run() {
@@ -990,7 +841,11 @@ async function run() {
       engineerId,
       userId,
       workspaceId: workspaceIdArg,
-      taskIds: taskIdsArg
+      taskIds: taskIdsArg,
+      // Inject this script's retry-aware exec helpers so git timeouts
+      // don't lose recordings.
+      safeExec,
+      safeExecAsync
     });
     console.log(`Recording: ON`);
     console.log('');

package/lib/session-recorder.js

@@ -0,0 +1,228 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const util = require('util');
+const { exec } = require('child_process');
+
+const SESSIONS_DIR = path.join(os.homedir(), '.knoxis', 'sessions');
+
+function ensureSessionDir() {
+  if (!fs.existsSync(SESSIONS_DIR)) fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+}
+
+function slugify(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 60);
+}
+
+function extractFilesTouched(diff) {
+  if (!diff || typeof diff !== 'string') return [];
+  const seen = new Set();
+  const re = /^diff --git a\/(\S+) b\/(\S+)/gm;
+  let match;
+  while ((match = re.exec(diff)) !== null) {
+    seen.add(match[2] || match[1]);
+  }
+  return Array.from(seen);
+}
+
+// Default git-call helpers — return null on any failure (callers want a string or null).
+function defaultSafeExec(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: 'utf8', timeout: 30000 }).trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+const execAsync = util.promisify(exec);
+async function defaultSafeExecAsync(cmd, cwd) {
+  try {
+    const { stdout } = await execAsync(cmd, { cwd, encoding: 'utf8', timeout: 30000, maxBuffer: 10 * 1024 * 1024 });
+    return stdout.trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Records a multi-step pair-programming session — prompts, responses, git
+ * diffs, timings — and emits a JSON record on save() that is schema-aligned
+ * with the portal contract §3.4 SESSION shape.
+ *
+ * Used by both:
+ *   - knoxis-pair-program.js  (Claude-only pipelines, default + kit modes)
+ *   - knoxis-interactive-pair.js  (Groq-reviewed multi-phase flow)
+ *
+ * `meta.safeExec` / `meta.safeExecAsync` may be injected to reuse a caller's
+ * retry-aware exec wrappers; otherwise simple defaults run with no retries.
+ */
+class SessionRecorder {
+  constructor(task, workspace, aiProvider, meta = {}) {
+    this.sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    this.task = task;
+    this.workspace = workspace;
+    this.aiProvider = aiProvider;
+    this.startedAt = new Date().toISOString();
+    this.steps = [];
+
+    this._safeExec = meta.safeExec || defaultSafeExec;
+    this._safeExecAsync = meta.safeExecAsync || defaultSafeExecAsync;
+
+    this.initialCommit = this._safeExec('git rev-parse --short HEAD', workspace);
+
+    // Schema-aligned metadata — maps to portal contract §3.4 SESSION fields.
+    this.mode = meta.mode || null;
+    this.archetype = meta.archetype || null;
+    this.productSlug = meta.productSlug || null;
+    this.projectSlug = meta.projectSlug || null;
+    this.engineerId = meta.engineerId || null;
+    // QIG portal linkage (set when launching from collaboration/tasks UI).
+    this.userId = meta.userId || null;
+    this.workspaceId = meta.workspaceId || null;
+    this.taskIds = Array.isArray(meta.taskIds) ? meta.taskIds.filter(Boolean) : [];
+
+    ensureSessionDir();
+  }
+
+  startStep(key, agent, instruction) {
+    const step = {
+      stepKey: key,
+      agentName: agent,
+      instruction,
+      prompt: null,
+      response: null,
+      startedAt: new Date().toISOString(),
+      completedAt: null,
+      durationMs: null,
+      gitDiffBefore: this._safeExec('git diff', this.workspace) || '',
+      gitDiffAfter: null,
+      codeChanged: false,
+      error: null
+    };
+    this.steps.push(step);
+    return this.steps.length - 1;
+  }
+
+  setStepPrompt(idx, prompt) {
+    if (this.steps[idx]) this.steps[idx].prompt = prompt;
+  }
+
+  completeStep(idx, response, error) {
+    const s = this.steps[idx];
+    if (!s) return;
+    s.response = response;
+    s.completedAt = new Date().toISOString();
+    s.durationMs = new Date(s.completedAt) - new Date(s.startedAt);
+    s.gitDiffAfter = this._safeExec('git diff', this.workspace) || '';
+    s.codeChanged = s.gitDiffBefore !== s.gitDiffAfter;
+    s.error = error || null;
+  }
+
+  buildFinalRecord() {
+    const finalCommit = this._safeExec('git rev-parse --short HEAD', this.workspace);
+    const totalDiff = this._safeExec('git diff', this.workspace) || '';
+    return this._buildRecord(finalCommit, totalDiff);
+  }
+
+  async saveAsync() {
+    const finalCommit = await this._safeExecAsync('git rev-parse --short HEAD', this.workspace) || '';
+    const totalDiff = await this._safeExecAsync('git diff', this.workspace) || '';
+    const record = this._buildRecord(finalCommit, totalDiff);
+    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');
+    try {
+      await fs.promises.appendFile(
+        path.join(SESSIONS_DIR, 'index.jsonl'),
+        JSON.stringify({
+          sessionId: record.sessionId,
+          mode: record.mode,
+          archetype: record.archetype,
+          task: record.task,
+          startedAt: record.startedAt,
+          totalDurationMs: record.totalDurationMs,
+          file: filename
+        }) + '\n'
+      );
+    } catch (_) {}
+    return filepath;
+  }
+
+  save() {
+    const finalCommit = this._safeExec('git rev-parse --short HEAD', this.workspace);
+    const totalDiff = this._safeExec('git diff', this.workspace) || '';
+    const record = this._buildRecord(finalCommit, totalDiff);
+    const filename = `${this.sessionId}-${slugify(this.task)}.json`;
+    const filepath = path.join(SESSIONS_DIR, filename);
+    fs.writeFileSync(filepath, JSON.stringify(record, null, 2), 'utf8');
+    try {
+      fs.appendFileSync(
+        path.join(SESSIONS_DIR, 'index.jsonl'),
+        JSON.stringify({
+          sessionId: record.sessionId,
+          mode: record.mode,
+          archetype: record.archetype,
+          task: record.task,
+          startedAt: record.startedAt,
+          totalDurationMs: record.totalDurationMs,
+          file: filename
+        }) + '\n'
+      );
+    } catch (_) {}
+    return filepath;
+  }
+
+  _buildRecord(finalCommit, totalDiff) {
+    const completedSteps = this.steps.filter(s => s.completedAt && !s.error).length;
+    const closedCleanly = this.steps.length > 0 && completedSteps === this.steps.length;
+    return {
+      sessionId: this.sessionId,
+      version: '1.1.0',
+      mode: this.mode,
+      archetype: this.archetype,
+      productSlug: this.productSlug,
+      projectSlug: this.projectSlug,
+      engineerId: this.engineerId,
+      userId: this.userId,
+      workspaceId: this.workspaceId,
+      taskIds: this.taskIds,
+      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,
+      closedCleanly,
+      filesTouched: extractFilesTouched(totalDiff),
+      decisionsLogged: [],
+      waiversRequested: [],
+      incidentsFlagged: [],
+      ruleViolations: [],
+      archetypeSpecificData: {},
+      git: {
+        initialCommit: this.initialCommit,
+        finalCommit,
+        totalDiff
+      },
+      environment: { platform: os.platform(), nodeVersion: process.version }
+    };
+  }
+}
+
+module.exports = {
+  SessionRecorder,
+  SESSIONS_DIR,
+  ensureSessionDir,
+  slugify,
+  extractFilesTouched
+};

package/package.json

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