knoxis-helper 1.4.8 → 1.5.2

package/bin/knoxis-helper.js

@@ -81,10 +81,26 @@ function ask(rl, question) {
  * Copy agent files to ~/.knoxis/agent/ so they persist across npx cache clears,
  * VPN changes, and reboots. Returns the stable path.
  */
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(src)) return;
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDirRecursive(s, d);
+    else if (entry.isFile()) fs.copyFileSync(s, d);
+  }
+}
+
 function installAgentLocally(force) {
-  const sourceAgent = path.join(__dirname, '..', 'lib', 'knoxis-local-agent.js');
-  const sourcePairProgram = path.join(__dirname, '..', 'lib', 'knoxis-pair-program.js');
-  const sourceInteractivePair = path.join(__dirname, '..', 'lib', 'knoxis-interactive-pair.js');
+  const libDir = path.join(__dirname, '..', 'lib');
+  const sourceAgent = path.join(libDir, 'knoxis-local-agent.js');
+  const sourcePairProgram = path.join(libDir, 'knoxis-pair-program.js');
+  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');
 
   if (!fs.existsSync(sourceAgent)) {
@@ -125,6 +141,26 @@ function installAgentLocally(force) {
     console.log('  Installed: knoxis-interactive-pair.js');
   }
 
+  if (fs.existsSync(sourceStateScaffold)) {
+    fs.copyFileSync(sourceStateScaffold, path.join(AGENT_DIR, 'state-scaffold.js'));
+    console.log('  Installed: state-scaffold.js');
+  }
+
+  if (fs.existsSync(sourcePortalSync)) {
+    fs.copyFileSync(sourcePortalSync, path.join(AGENT_DIR, 'portal-sync.js'));
+    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/');
+  }
+
   if (fs.existsSync(sourcePackage)) {
     fs.copyFileSync(sourcePackage, path.join(AGENT_DIR, 'package.json'));
   }

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

@@ -580,6 +580,47 @@ function resolveInteractiveScript() {
   return null;
 }
 
+// Resolve the kit-aware pair-program runner (used when caller specifies --mode)
+function resolvePairProgramScript() {
+  const candidates = [
+    path.join(__dirname, 'knoxis-pair-program.js'),
+    path.join(__dirname, '..', 'knoxis-pair-program.js'),
+    path.join(os.homedir(), '.knoxis', 'agent', 'knoxis-pair-program.js'),
+    path.join(__dirname, '..', '..', 'knoxis-pair-program.js'),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+const KIT_MODES = new Set(['kickoff', 'resume', 'session-end', 'recovery']);
+
+function buildPairProgramCommand({ scriptPath, workspace, mode, archetype, pattern, productSlug, projectSlug, taskPrompt, userId, workspaceId, taskIds }) {
+  const q = v => `"${escapeForDoubleQuotedShellArg(v)}"`;
+  // Mode/archetype/pattern are constrained to known short tokens — no need to quote.
+  // Slugs and paths can contain spaces or special chars — always quote.
+  const parts = [`node ${q(scriptPath)}`, `--workspace ${q(workspace)}`];
+  if (mode) parts.push(`--mode ${mode}`);
+  if (archetype) parts.push(`--archetype ${archetype}`);
+  if (pattern) parts.push(`--pattern ${pattern}`);
+  if (productSlug) parts.push(`--product-slug ${q(productSlug)}`);
+  if (projectSlug) parts.push(`--project-slug ${q(projectSlug)}`);
+  if (userId) parts.push(`--user-id ${q(userId)}`);
+  if (workspaceId) parts.push(`--workspace-id ${q(workspaceId)}`);
+  if (Array.isArray(taskIds)) {
+    for (const t of taskIds) {
+      if (t) parts.push(`--task-id ${q(t)}`);
+    }
+  }
+  if (taskPrompt && taskPrompt.length) {
+    // Use base64 to avoid shell-quoting hazards (newlines, quotes, backticks).
+    const b64 = Buffer.from(taskPrompt, 'utf8').toString('base64');
+    parts.push(`--prompt-base64 ${b64}`);
+  }
+  return parts.join(' ');
+}
+
 // Request handler
 async function handleRequest(req, res) {
   const parsedUrl = url.parse(req.url, true);
@@ -867,8 +908,22 @@ async function handleRequest(req, res) {
       const body = await parseBody(req);
       const { workspace, task, file, provider, headless, sessionId, claudeMdContent } = body;
       const interactive = body.interactive === true || body.interactive === 'true';
-
-      if (!task) {
+      const kitMode = typeof body.mode === 'string' && KIT_MODES.has(body.mode) ? body.mode : null;
+      const archetype = typeof body.archetype === 'string' ? body.archetype : null;
+      const pattern = typeof body.pattern === 'string' ? body.pattern : null;
+      const productSlug = typeof body.productSlug === 'string' ? body.productSlug : null;
+      const projectSlug = typeof body.projectSlug === 'string' ? body.projectSlug : null;
+      // QIG portal linkage — let session records get tied back to the user / workspace / tasks.
+      const portalUserId = typeof body.userId === 'string' ? body.userId : null;
+      const portalWorkspaceId = typeof body.workspaceId === 'string' ? body.workspaceId : null;
+      const portalTaskIds = Array.isArray(body.taskIds)
+        ? body.taskIds.filter(t => typeof t === 'string' && t)
+        : (typeof body.taskId === 'string' ? [body.taskId] : []);
+
+      // Kickoff and session-end modes don't strictly need a task — the kit prompt
+      // drives the interaction. For all other paths a task is still required.
+      const taskOptionalForMode = kitMode === 'kickoff' || kitMode === 'session-end';
+      if (!task && !taskOptionalForMode) {
         return sendJSON(res, 400, { success: false, error: 'Task description required' }, requestOrigin);
       }
 
@@ -895,20 +950,56 @@ async function handleRequest(req, res) {
         }
       }
 
-      // Write the actual task to a temp file
+      // Write the actual task to a temp file (used by single-shot and interactive paths)
       const promptFile = path.join(os.tmpdir(), `knoxis-task-${sessionId || Date.now()}.txt`);
-      const promptText = file ? `Working on file: ${file}\n\nTask: ${task}` : task;
-      fs.writeFileSync(promptFile, promptText, 'utf8');
+      const promptText = task ? (file ? `Working on file: ${file}\n\nTask: ${task}` : task) : '';
+      if (promptText) fs.writeFileSync(promptFile, promptText, 'utf8');
 
-      // Determine the command to run
+      // Determine the command to run.
       let command;
       let mode = 'single-shot';
 
-      if (interactive) {
+      // Route through knoxis-pair-program.js whenever it's installed — gives
+      // every task auto-scaffold, the standards systemIntro, auto-context, and
+      // portal-sync. Kit mode adds --mode; default mode runs the standard
+      // 4-step pipeline. Interactive (Groq) mode and the legacy claude-pipe
+      // fallback remain available when the runner isn't present.
+      const ppScript = resolvePairProgramScript();
+      if (kitMode && !ppScript) {
+        return sendJSON(res, 500, { success: false, error: 'knoxis-pair-program.js not found — reinstall knoxis-helper.' }, requestOrigin);
+      }
+
+      if (kitMode || (ppScript && !interactive && promptText)) {
+        command = buildPairProgramCommand({
+          scriptPath: ppScript,
+          workspace: workspaceDir,
+          mode: kitMode || null,
+          archetype,
+          pattern,
+          productSlug,
+          projectSlug,
+          taskPrompt: promptText,
+          userId: portalUserId,
+          workspaceId: portalWorkspaceId,
+          taskIds: portalTaskIds
+        });
+        mode = kitMode
+          ? `kit:${kitMode}${archetype ? `/${archetype}` : ''}${pattern ? `/${pattern}` : ''}`
+          : 'pair-program:default';
+        console.log(`🧰 ${kitMode ? 'Kit' : 'Pair-program (default pipeline)'}: ${mode}`);
+      } 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 {
@@ -917,17 +1008,19 @@ async function handleRequest(req, res) {
           command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
         }
       } else {
-        // Standard single-shot mode: pipe task to Claude
+        // Legacy fallback when neither pair-program nor interactive scripts are installed.
         command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
       }
 
       if (headless) {
-        if (interactive && mode === 'interactive') {
-          // Headless interactive: run the script directly as a process
+        // Anything routed through pair-program.js or knoxis-interactive-pair.js
+        // is a script invocation — run the assembled command verbatim.
+        const isScriptInvocation = mode === 'interactive' || mode === 'pair-program:default' || (kitMode != null);
+        if (isScriptInvocation) {
           const result = await runHeadlessProcess({
             workspace: workspaceDir,
             command,
-            sessionLabel: sessionId || 'interactive-pair'
+            sessionLabel: sessionId || (kitMode ? `kit-${kitMode}` : (mode === 'interactive' ? 'interactive-pair' : 'pair-program'))
           });
           return sendJSON(res, result.success ? 200 : 500, { ...result, mode }, requestOrigin);
         }
@@ -956,10 +1049,15 @@ async function handleRequest(req, res) {
 
       return sendJSON(res, 200, {
         success: true,
-        message: interactive ? 'Interactive pair programming session started' : 'Pair programming session started',
+        message: kitMode ? `Pair programming session started (kit mode: ${kitMode})`
+          : interactive ? 'Interactive pair programming session started'
+          : 'Pair programming session started',
         mode,
+        kitMode: kitMode || null,
+        archetype: archetype || null,
+        pattern: pattern || null,
         workspace: workspaceDir,
-        task,
+        task: task || null,
         file: file || null
       }, requestOrigin);
     } catch (error) {
@@ -1338,16 +1436,53 @@ function connectRelayWebSocket() {
         }
 
         const interactive = msg.interactive === true;
-
-        if (taskPrompt) {
+        const kitMode = typeof msg.mode === 'string' && KIT_MODES.has(msg.mode) ? msg.mode : null;
+        const archetype = typeof msg.archetype === 'string' ? msg.archetype : null;
+        const pattern = typeof msg.pattern === 'string' ? msg.pattern : null;
+        const productSlug = typeof msg.productSlug === 'string' ? msg.productSlug : null;
+        const projectSlug = typeof msg.projectSlug === 'string' ? msg.projectSlug : null;
+        const portalUserId = typeof msg.userId === 'string' ? msg.userId : null;
+        const portalWorkspaceId = typeof msg.workspaceId === 'string' ? msg.workspaceId : null;
+        const portalTaskIds = Array.isArray(msg.taskIds)
+          ? msg.taskIds.filter(t => typeof t === 'string' && t)
+          : (typeof msg.taskId === 'string' ? [msg.taskId] : []);
+        const ppScript = resolvePairProgramScript();
+        const routeViaPairProgram = (kitMode || (ppScript && !interactive && taskPrompt));
+
+        if (routeViaPairProgram && ppScript) {
+          command = buildPairProgramCommand({
+            scriptPath: ppScript,
+            workspace: wsDir,
+            mode: kitMode || null,
+            archetype,
+            pattern,
+            productSlug,
+            projectSlug,
+            taskPrompt: taskPrompt || '',
+            userId: portalUserId,
+            workspaceId: portalWorkspaceId,
+            taskIds: portalTaskIds
+          });
+          console.log(`   🧰 ${kitMode ? `Kit mode: ${kitMode}` : 'Pair-program (default pipeline)'}${archetype ? `/${archetype}` : ''}${pattern ? `/${pattern}` : ''}`);
+        } else if (kitMode) {
+          console.warn(`   ⚠️ knoxis-pair-program.js not found — cannot run kit mode`);
+        } else if (taskPrompt) {
           promptFile = path.join(os.tmpdir(), `knoxis-task-${msg.requestId || Date.now()}.txt`);
           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';
@@ -1406,6 +1541,28 @@ function connectRelayWebSocket() {
         }
       } else if (msg.type === 'connected') {
         console.log(`🤝 Backend acknowledged: ${msg.message}`);
+      } else if (msg.type === 'portal_config') {
+        // Backend is auto-distributing the portal-sync token + URL so devs
+        // don't paste them by hand. Merge into ~/.knoxis/config.json so
+        // portal-sync.js picks them up on the next session save.
+        try {
+          ensureKnoxisDir();
+          const cfgPath = path.join(KNOXIS_DIR, 'config.json');
+          let existing = {};
+          try {
+            if (fs.existsSync(cfgPath)) existing = JSON.parse(fs.readFileSync(cfgPath, 'utf8')) || {};
+          } catch (_) {}
+          if (typeof msg.portalToken === 'string' && msg.portalToken) existing.portalToken = msg.portalToken;
+          if (typeof msg.portalUrl === 'string' && msg.portalUrl) existing.portalUrl = msg.portalUrl;
+          if (typeof msg.portalSessionsPath === 'string' && msg.portalSessionsPath) {
+            existing.portalSessionsPath = msg.portalSessionsPath;
+          }
+          fs.writeFileSync(cfgPath, JSON.stringify(existing, null, 2));
+          // Don't log the token itself.
+          console.log(`🔐 Portal-sync config received (token len ${(msg.portalToken || '').length})`);
+        } catch (cfgErr) {
+          console.warn(`⚠️ Failed to persist portal_config: ${cfgErr.message}`);
+        }
       }
     } catch (e) {
       console.error('❌ Relay message handling error:', e.message);