knoxis-helper 1.8.3 → 1.8.5

package/bin/knoxis-helper.js

@@ -101,6 +101,7 @@ function installAgentLocally(force) {
   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 sourceActiveSession = path.join(libDir, 'active-session.js');
   const sourceFrameworkVersion = path.join(libDir, 'framework-version.js');
   const sourceTemplatesDir = path.join(libDir, 'templates');
   const sourcePackage = path.join(__dirname, '..', 'package.json');
@@ -158,6 +159,11 @@ function installAgentLocally(force) {
     console.log('  Installed: session-recorder.js');
   }
 
+  if (fs.existsSync(sourceActiveSession)) {
+    fs.copyFileSync(sourceActiveSession, path.join(AGENT_DIR, 'active-session.js'));
+    console.log('  Installed: active-session.js');
+  }
+
   if (fs.existsSync(sourceFrameworkVersion)) {
     fs.copyFileSync(sourceFrameworkVersion, path.join(AGENT_DIR, 'framework-version.js'));
     console.log('  Installed: framework-version.js');

package/lib/active-session.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const FILENAME = 'active-session.json';
+
+function activeSessionPath(workspace) {
+  return path.join(workspace, '.knoxis', FILENAME);
+}
+
+/**
+ * Persist the in-progress pair-programming session so session-end can
+ * reference the same IDs (portal recorder, Claude resume, backend relay).
+ */
+function writeActiveSession(workspace, data) {
+  const fp = activeSessionPath(workspace);
+  fs.mkdirSync(path.dirname(fp), { recursive: true });
+  const payload = {
+    ...data,
+    updatedAt: new Date().toISOString()
+  };
+  fs.writeFileSync(fp, JSON.stringify(payload, null, 2), 'utf8');
+  return payload;
+}
+
+function readActiveSession(workspace) {
+  try {
+    const raw = fs.readFileSync(activeSessionPath(workspace), 'utf8');
+    return JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+}
+
+function clearActiveSession(workspace) {
+  try {
+    fs.unlinkSync(activeSessionPath(workspace));
+  } catch (_) {}
+}
+
+module.exports = {
+  writeActiveSession,
+  readActiveSession,
+  clearActiveSession
+};

package/lib/knoxis-interactive-pair.js

@@ -36,6 +36,7 @@ const os = require('os');
 const { SessionRecorder } = require('./session-recorder');
 const { scaffoldStateLayout } = require('./state-scaffold');
 const { syncSessionToPortal } = require('./portal-sync');
+const { writeActiveSession, readActiveSession, clearActiveSession } = require('./active-session');
 const kitTemplates = require('./templates');
 
 // === CONFIG ===
@@ -290,6 +291,24 @@ function readIdentityFromEnv() {
   };
 }
 
+function persistActiveSession(recorder, identity, extra = {}) {
+  if (!recorder || !identity || !identity.workspace) return;
+  try {
+    writeActiveSession(identity.workspace, {
+      claudeSessionId: SESSION_ID,
+      recordedSessionId: recorder.sessionId,
+      backendSessionId: process.env.KNOXIS_BACKEND_SESSION_ID || null,
+      operatorId: identity.userId || identity.engineerId || null,
+      startedAt: recorder.startedAt,
+      mode: extra.mode ?? null,
+      kitMode: extra.kitMode ?? null,
+      taskHint: extra.taskHint ?? null
+    });
+  } catch (e) {
+    console.warn('  Could not persist active session: ' + e.message);
+  }
+}
+
 // === STATE-FILE UPDATE PROMPT ===
 // Forces Claude to actually write docs/state/*.md before the session closes.
 // The QIG dashboard reads these files; without this step they stay as scaffold
@@ -365,6 +384,8 @@ async function finalizeSession(recorder) {
 async function runKitMode(kitMode, task, identity, scaffoldResult) {
   const archetype = process.env.KNOXIS_KIT_ARCHETYPE || null;
   const pattern = process.env.KNOXIS_KIT_PATTERN || null;
+  const closingSession = kitMode === 'session-end';
+  const activeSession = closingSession ? readActiveSession(identity.workspace) : null;
   let tpl;
   try {
     // feature-kickoff additionally consumes identity (userId, workspaceId,
@@ -380,6 +401,7 @@ async function runKitMode(kitMode, task, identity, scaffoldResult) {
       userId: identity.userId,
       workspaceId: identity.workspaceId,
       parentTaskId: (identity.taskIds && identity.taskIds.length) ? identity.taskIds[0] : null,
+      activeSession,
       // Auto-doc opt-in flows through env var since the interactive runner
       // sources its identity from the QIG portal rather than CLI args.
       integrate: process.env.KNOXIS_INTEGRATE === 'true' || process.env.KNOXIS_INTEGRATE === '1'
@@ -409,6 +431,11 @@ async function runKitMode(kitMode, task, identity, scaffoldResult) {
   console.log('  Workspace: ' + identity.workspace);
   console.log('  Session:   ' + SESSION_ID);
   console.log('  Recorded:  ' + recorder.sessionId);
+  if (closingSession && activeSession) {
+    console.log('  Closing:   ' + (activeSession.recordedSessionId || activeSession.claudeSessionId || '(see .knoxis/active-session.json)'));
+  } else if (!closingSession) {
+    persistActiveSession(recorder, identity, { kitMode, taskHint: task || null });
+  }
   if (task) console.log('  Hint:      ' + task.substring(0, 100) + (task.length > 100 ? '...' : ''));
   if (scaffoldResult && (scaffoldResult.dirs.length || scaffoldResult.files.length)) {
     console.log('  Scaffolded: ' + (scaffoldResult.dirs.length + scaffoldResult.files.length) + ' new entries (CODING_RULES + docs/state/)');
@@ -439,6 +466,13 @@ async function runKitMode(kitMode, task, identity, scaffoldResult) {
   console.log('');
 
   await finalizeSession(recorder);
+  if (closingSession) {
+    try {
+      clearActiveSession(identity.workspace);
+    } catch (e) {
+      console.warn('  Could not clear active session: ' + e.message);
+    }
+  }
   process.exit(result.code || 0);
 }
 
@@ -495,6 +529,7 @@ async function main() {
   console.log('  Task:      ' + task.substring(0, 100) + (task.length > 100 ? '...' : ''));
   console.log('  Session:   ' + SESSION_ID);
   console.log('  Recorded:  ' + recorder.sessionId);
+  persistActiveSession(recorder, identity, { mode: 'interactive', taskHint: task });
   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');

package/lib/knoxis-local-agent.js

@@ -991,6 +991,7 @@ async function handleRequest(req, res) {
         if (portalUserId) kitEnv.KNOXIS_USER_ID = portalUserId;
         if (portalWorkspaceId) kitEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
         if (portalTaskIds && portalTaskIds.length) kitEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+        if (sessionId) kitEnv.KNOXIS_BACKEND_SESSION_ID = sessionId;
         command = buildEnvCommand(kitEnv, `node "${scriptPath}"`);
         mode = `kit:${kitMode}${archetype ? `/${archetype}` : ''}`;
         console.log(`🧰 Kit (interactive runner): ${mode} — ${scriptPath}`);
@@ -1024,6 +1025,7 @@ async function handleRequest(req, res) {
           if (portalTaskIds && portalTaskIds.length) interactiveEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
           if (productSlug) interactiveEnv.KNOXIS_PRODUCT_SLUG = productSlug;
           if (projectSlug) interactiveEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+          if (sessionId) interactiveEnv.KNOXIS_BACKEND_SESSION_ID = sessionId;
           command = buildEnvCommand(interactiveEnv, `node "${scriptPath}"`);
           mode = 'interactive';
           console.log(`🤝 Interactive mode: ${scriptPath}`);
@@ -1495,6 +1497,8 @@ function connectRelayWebSocket() {
             if (portalUserId) kitEnv.KNOXIS_USER_ID = portalUserId;
             if (portalWorkspaceId) kitEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
             if (portalTaskIds && portalTaskIds.length) kitEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+            const relaySessionId = typeof msg.sessionId === 'string' ? msg.sessionId : null;
+            if (relaySessionId) kitEnv.KNOXIS_BACKEND_SESSION_ID = relaySessionId;
             command = buildEnvCommand(kitEnv, `node "${scriptPath}"`);
             console.log(`   🧰 Kit (interactive runner): ${kitMode}${archetype ? `/${archetype}` : ''} — ${scriptPath}`);
           } else {
@@ -1533,6 +1537,8 @@ function connectRelayWebSocket() {
               if (portalTaskIds && portalTaskIds.length) interactiveEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
               if (productSlug) interactiveEnv.KNOXIS_PRODUCT_SLUG = productSlug;
               if (projectSlug) interactiveEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+              const relaySessionId = typeof msg.sessionId === 'string' ? msg.sessionId : null;
+              if (relaySessionId) interactiveEnv.KNOXIS_BACKEND_SESSION_ID = relaySessionId;
               command = buildEnvCommand(interactiveEnv, `node "${scriptPath}"`);
               console.log(`   🤝 Interactive mode: ${scriptPath}`);
             } else {

package/lib/knoxis-pair-program.js

@@ -8,6 +8,7 @@ const kitTemplates = require('./templates');
 const { scaffoldStateLayout, assertStateLayout } = require('./state-scaffold');
 const { syncSessionToPortal } = require('./portal-sync');
 const { SessionRecorder } = require('./session-recorder');
+const { writeActiveSession } = require('./active-session');
 
 // ===== RETRY CONFIGURATION =====
 // Can be overridden via environment variables
@@ -891,6 +892,22 @@ async function run() {
       safeExec,
       safeExecAsync
     });
+    if (mode !== 'session-end') {
+      try {
+        writeActiveSession(workspace, {
+          claudeSessionId: null,
+          recordedSessionId: recorder.sessionId,
+          backendSessionId: process.env.KNOXIS_BACKEND_SESSION_ID || null,
+          operatorId: userId || engineerId || null,
+          startedAt: recorder.startedAt,
+          mode: mode || 'pair-program',
+          kitMode: mode || null,
+          taskHint: task || null
+        });
+      } catch (e) {
+        console.warn(`Could not persist active session: ${e.message}`);
+      }
+    }
     console.log(`Recording: ON`);
     console.log('');
   }

package/lib/templates/session-end.js

@@ -28,9 +28,11 @@ Coaching reminders that apply throughout:
 
 Before starting, confirm:
 - **Operator ID** for this session (should match what was set in resume Step 0).
-- **Session ID** held since session start.
+- **Session ID** for the working session you are closing (not the session-end invocation).
 
-If you're unsure of either, surface it before proceeding. Author tags on artifacts must be accurate.
+If **Session context** above includes a **Working session** block, use those IDs directly — do not ask the operator to confirm them. Use **Portal recorded session** as \`session_id\` in the Step 9 SESSION record and in \`last_session_id\` frontmatter unless the framework calls for a new semantic slug for this closeout. Use **Operator ID** from that block for author tags.
+
+If no Working session block is present and you're unsure of either ID, surface it before proceeding. Author tags on artifacts must be accurate.
 
 ---
 
@@ -440,7 +442,15 @@ Otherwise, end with: "Ready to close. Have a good one."
 
 **Begin now.** Start with the preamble.`;
 
-function buildSessionEndPrompt({ archetype, taskDescription, productSlug, projectSlug, workspace } = {}) {
+function buildSessionEndPrompt({
+  archetype,
+  taskDescription,
+  productSlug,
+  projectSlug,
+  workspace,
+  activeSession,
+  userId
+} = {}) {
   const header = [];
   header.push('Mode: session-end');
   if (archetype) header.push(`Archetype: ${archetype}`);
@@ -448,6 +458,24 @@ function buildSessionEndPrompt({ archetype, taskDescription, productSlug, projec
   if (projectSlug) header.push(`Project: ${projectSlug}`);
   if (workspace) header.push(`Workspace: ${workspace}`);
   if (taskDescription) header.push(`Session task: ${taskDescription}`);
+
+  const work = activeSession || null;
+  const operatorId = (work && work.operatorId) || userId || null;
+  if (work) {
+    header.push('');
+    header.push('Working session (close this one — ignore the session-end runner banner IDs):');
+    if (work.recordedSessionId) header.push(`  Portal recorded session: ${work.recordedSessionId}`);
+    if (work.claudeSessionId) header.push(`  Claude session: ${work.claudeSessionId}`);
+    if (work.collabSessionId) header.push(`  Collab session: ${work.collabSessionId}`);
+    if (work.backendSessionId) header.push(`  Knoxis backend session: ${work.backendSessionId}`);
+    if (operatorId) header.push(`  Operator ID: ${operatorId}`);
+    if (work.startedAt) header.push(`  Started at: ${work.startedAt}`);
+    if (work.kitMode) header.push(`  Kit mode: ${work.kitMode}`);
+    if (work.mode) header.push(`  Runner mode: ${work.mode}`);
+  } else if (operatorId) {
+    header.push(`Operator ID (from portal): ${operatorId}`);
+  }
+
   const ctx = `Session context:\n${header.join('\n')}\n\n`;
   return ctx + SESSION_END_BODY;
 }

package/package.json

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