knoxis-helper 1.8.6 → 1.10.0

package/lib/knoxis-local-agent.js

@@ -46,7 +46,52 @@ const ALLOWED_ORIGINS = (process.env.KNOXIS_ALLOWED_ORIGINS || '')
   .map(origin => origin.trim())
   .filter(Boolean);
 // Merge custom origins with trusted ones
-const ALL_ALLOWED_ORIGINS = [...new Set([...TRUSTED_ORIGINS, ...ALLOWED_ORIGINS])];
+const ALL_ALLOWED_ORIGINS = Array.from(new Set([...TRUSTED_ORIGINS, ...ALLOWED_ORIGINS]));
+
+/**
+ * Collect Maker-related Markdown documents for persistence and syncing.
+ * These include backlog, PRD, glossary, product, and strategy files.
+ */
+function collectMakerDocs(workspaceDir) {
+  try {
+    if (!workspaceDir || !fs.existsSync(workspaceDir)) return [];
+    const makerFiles = [];
+    const candidates = [
+      'BACKLOG.md',
+      'GLOSSARY.md',
+      'PRD.md',
+      'PRODUCT.md',
+      'STRATEGY.md'
+    ];
+    candidates.forEach(name => {
+      const full = path.join(workspaceDir, name);
+      if (fs.existsSync(full)) makerFiles.push(full);
+    });
+    const docsDir = path.join(workspaceDir, 'docs');
+    if (fs.existsSync(docsDir)) {
+      fs.readdirSync(docsDir).forEach(f => {
+        if (f.endsWith('.md')) makerFiles.push(path.join(docsDir, f));
+      });
+    }
+    const mvpDir = path.join(workspaceDir, '.mvp');
+    if (fs.existsSync(mvpDir)) {
+      const walk = dir => {
+        fs.readdirSync(dir, { withFileTypes: true }).forEach(entry => {
+          const res = path.join(dir, entry.name);
+          if (entry.isDirectory()) walk(res);
+          else if (entry.name.endsWith('.md')) makerFiles.push(res);
+        });
+      };
+      walk(mvpDir);
+    }
+    console.log(`📁 Maker-aware discovery found ${makerFiles.length} planning docs.`);
+    return makerFiles;
+  } catch (err) {
+    console.warn('⚠️  collectMakerDocs failed:', err.message);
+    return [];
+  }
+}
+
 
 const serverMeta = { secure: false, port: DEFAULT_PORT };
 
@@ -580,55 +625,6 @@ 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', 'feature-kickoff', 'resume', 'session-end', 'recovery']);
-// Every kit mode rewrites files on disk — STATUS / HANDOFF / DECISIONS for
-// session-end, the docs/state/* + docs/features/<slug>/* bag for kickoff /
-// feature-kickoff / resume, and recovery's triage notes. The interactive
-// runner invokes `claude -p --session-id`, which gives Claude proper tool
-// access; the older pair-program.js pipes to `claude` without -p and silently
-// skips the file writes. Route every kit mode through the interactive runner
-// so their kit prompts actually do their work.
-const KIT_MODES_VIA_INTERACTIVE = new Set(['kickoff', 'feature-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);
@@ -685,7 +681,14 @@ async function handleRequest(req, res) {
       if (body.claudeMdContent && workspace && fs.existsSync(workspace)) {
         try {
           fs.writeFileSync(path.join(workspace, 'CLAUDE.md'), body.claudeMdContent, 'utf8');
-          console.log('📄 Wrote CLAUDE.md (' + body.claudeMdContent.length + ' chars)');
+           console.log('📄 Wrote CLAUDE.md (' + body.claudeMdContent.length + ' chars)');
+           // Maker-aware discovery integration
+           try {
+             const makerDocs = collectMakerDocs(workspace);
+             console.log(`   Maker doc sync: ${makerDocs.length} files found.`);
+           } catch (err) {
+             console.warn('⚠️ Maker doc sync failed:', err.message);
+           }
         } catch (writeErr) {
           console.warn('⚠️ Failed to write CLAUDE.md:', writeErr.message);
         }
@@ -916,22 +919,8 @@ 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';
-      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) {
+
+      if (!task) {
         return sendJSON(res, 400, { success: false, error: 'Task description required' }, requestOrigin);
       }
 
@@ -953,80 +942,32 @@ async function handleRequest(req, res) {
         try {
           fs.writeFileSync(path.join(workspaceDir, 'CLAUDE.md'), effectiveClaudeMd, 'utf8');
           console.log(`📄 Wrote CLAUDE.md to ${workspaceDir} (${effectiveClaudeMd.length} chars)`);
+          // Maker-aware discovery integration
+          try {
+            const makerDocs = collectMakerDocs(workspaceDir);
+            console.log(`   Maker doc sync: ${makerDocs.length} files found.`);
+          } catch (err) {
+            console.warn('⚠️ Maker doc sync failed:', err.message);
+          }
         } catch (e) {
           console.warn(`⚠️ Failed to write CLAUDE.md: ${e.message}`);
         }
       }
 
-      // Write the actual task to a temp file (used by single-shot and interactive paths)
+      // Write the actual task to a temp file
       const promptFile = path.join(os.tmpdir(), `knoxis-task-${sessionId || Date.now()}.txt`);
-      const promptText = task ? (file ? `Working on file: ${file}\n\nTask: ${task}` : task) : '';
-      if (promptText) fs.writeFileSync(promptFile, promptText, 'utf8');
+      const promptText = file ? `Working on file: ${file}\n\nTask: ${task}` : task;
+      fs.writeFileSync(promptFile, promptText, 'utf8');
 
-      // Determine the command to run.
+      // Determine the command to run
       let command;
       let mode = 'single-shot';
 
-      // 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();
-      const kitViaInteractive = kitMode && KIT_MODES_VIA_INTERACTIVE.has(kitMode);
-      if (kitMode && !kitViaInteractive && !ppScript) {
-        return sendJSON(res, 500, { success: false, error: 'knoxis-pair-program.js not found — reinstall knoxis-helper.' }, requestOrigin);
-      }
-      if (kitViaInteractive) {
-        const scriptPath = resolveInteractiveScript();
-        if (!scriptPath) {
-          return sendJSON(res, 500, { success: false, error: 'knoxis-interactive-pair.js not found — reinstall knoxis-helper.' }, requestOrigin);
-        }
-        const kitEnv = { KNOXIS_WORKSPACE_PATH: workspaceDir, KNOXIS_KIT_MODE: kitMode };
-        if (promptText) kitEnv.KNOXIS_TASK_FILE = promptFile;
-        if (archetype) kitEnv.KNOXIS_KIT_ARCHETYPE = archetype;
-        if (pattern) kitEnv.KNOXIS_KIT_PATTERN = pattern;
-        if (productSlug) kitEnv.KNOXIS_PRODUCT_SLUG = productSlug;
-        if (projectSlug) kitEnv.KNOXIS_PROJECT_SLUG = projectSlug;
-        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}`);
-      } else 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) {
+      if (interactive) {
         const scriptPath = resolveInteractiveScript();
         if (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;
-          if (sessionId) interactiveEnv.KNOXIS_BACKEND_SESSION_ID = sessionId;
-          command = buildEnvCommand(interactiveEnv, `node "${scriptPath}"`);
+          // Interactive mode: multi-turn with Groq pair programmer
+          command = buildEnvCommand({ KNOXIS_TASK_FILE: promptFile }, `node "${scriptPath}"`);
           mode = 'interactive';
           console.log(`🤝 Interactive mode: ${scriptPath}`);
         } else {
@@ -1035,19 +976,17 @@ async function handleRequest(req, res) {
           command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
         }
       } else {
-        // Legacy fallback when neither pair-program nor interactive scripts are installed.
+        // Standard single-shot mode: pipe task to Claude
         command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
       }
 
       if (headless) {
-        // 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) {
+        if (interactive && mode === 'interactive') {
+          // Headless interactive: run the script directly as a process
           const result = await runHeadlessProcess({
             workspace: workspaceDir,
             command,
-            sessionLabel: sessionId || (kitMode ? `kit-${kitMode}` : (mode === 'interactive' ? 'interactive-pair' : 'pair-program'))
+            sessionLabel: sessionId || 'interactive-pair'
           });
           return sendJSON(res, result.success ? 200 : 500, { ...result, mode }, requestOrigin);
         }
@@ -1076,15 +1015,10 @@ async function handleRequest(req, res) {
 
       return sendJSON(res, 200, {
         success: true,
-        message: kitMode ? `Pair programming session started (kit mode: ${kitMode})`
-          : interactive ? 'Interactive pair programming session started'
-          : 'Pair programming session started',
+        message: interactive ? 'Interactive pair programming session started' : 'Pair programming session started',
         mode,
-        kitMode: kitMode || null,
-        archetype: archetype || null,
-        pattern: pattern || null,
         workspace: workspaceDir,
-        task: task || null,
+        task,
         file: file || null
       }, requestOrigin);
     } catch (error) {
@@ -1437,6 +1371,13 @@ function connectRelayWebSocket() {
           try {
             fs.writeFileSync(path.join(wsDir, 'CLAUDE.md'), msg.claudeMdContent, 'utf8');
             console.log(`   📄 Wrote CLAUDE.md (${msg.claudeMdContent.length} chars)`);
+            // Maker-aware discovery integration
+            try {
+              const makerDocs = collectMakerDocs(wsDir);
+              console.log(`      Maker doc sync: ${makerDocs.length} files found.`);
+            } catch (err) {
+              console.warn('⚠️ Maker doc sync failed:', err.message);
+            }
           } catch (writeErr) {
             console.warn(`   ⚠️ Failed to write CLAUDE.md: ${writeErr.message}`);
           }
@@ -1463,84 +1404,31 @@ function connectRelayWebSocket() {
         }
 
         const interactive = msg.interactive === true;
-        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 kitViaInteractive = kitMode && KIT_MODES_VIA_INTERACTIVE.has(kitMode);
-        const routeViaPairProgram = !kitViaInteractive && (kitMode || (ppScript && !interactive && taskPrompt));
-
-        if (kitViaInteractive) {
-          const scriptPath = resolveInteractiveScript();
-          if (scriptPath) {
-            // kickoff/resume need Claude's tool path (claude -p --session-id),
-            // which the interactive runner provides. Pass the kit mode + identity
-            // via env so the runner picks the kit branch instead of the 4-phase
-            // Groq flow.
-            if (taskPrompt) {
-              promptFile = path.join(os.tmpdir(), `knoxis-task-${msg.requestId || Date.now()}.txt`);
-              fs.writeFileSync(promptFile, taskPrompt, 'utf8');
-            }
-            const kitEnv = { KNOXIS_WORKSPACE_PATH: wsDir, KNOXIS_KIT_MODE: kitMode };
-            if (promptFile) kitEnv.KNOXIS_TASK_FILE = promptFile;
-            if (archetype) kitEnv.KNOXIS_KIT_ARCHETYPE = archetype;
-            if (pattern) kitEnv.KNOXIS_KIT_PATTERN = pattern;
-            if (productSlug) kitEnv.KNOXIS_PRODUCT_SLUG = productSlug;
-            if (projectSlug) kitEnv.KNOXIS_PROJECT_SLUG = projectSlug;
-            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 {
-            console.warn(`   ⚠️ knoxis-interactive-pair.js not found — cannot run kit mode ${kitMode}`);
-          }
-        } else 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) {
+
+        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.
-            // Pass identity env vars so the script can build a schema-aligned
-            // session record and POST it via portal-sync.
+            // Interactive mode: use multi-turn pair programming script
             const scriptPath = resolveInteractiveScript();
             if (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;
-              const relaySessionId = typeof msg.sessionId === 'string' ? msg.sessionId : null;
-              if (relaySessionId) interactiveEnv.KNOXIS_BACKEND_SESSION_ID = relaySessionId;
-              command = buildEnvCommand(interactiveEnv, `node "${scriptPath}"`);
+              // Forward QIG attribution from relay message → env vars so
+              // SessionRecorder writes non-null workspace_id / product_slug /
+              // project_slug / task_ids to pair_programmer_sessions.
+              const envVars = { KNOXIS_TASK_FILE: promptFile, KNOXIS_WORKSPACE_PATH: wsDir };
+              if (msg.userId) envVars.KNOXIS_USER_ID = msg.userId;
+              if (msg.workspaceId) envVars.KNOXIS_WORKSPACE_ID = msg.workspaceId;
+              if (msg.productSlug) envVars.KNOXIS_PRODUCT_SLUG = msg.productSlug;
+              if (msg.projectSlug) envVars.KNOXIS_PROJECT_SLUG = msg.projectSlug;
+              if (msg.kitMode) envVars.KNOXIS_KIT_MODE = msg.kitMode;
+              if (Array.isArray(msg.taskIds) && msg.taskIds.length > 0) {
+                envVars.KNOXIS_TASK_IDS = msg.taskIds.filter(Boolean).join(',');
+              }
+              command = buildEnvCommand(envVars, `node "${scriptPath}"`);
               console.log(`   🤝 Interactive mode: ${scriptPath}`);
+              const forwarded = Object.keys(envVars).filter(k => k !== 'KNOXIS_TASK_FILE' && k !== 'KNOXIS_WORKSPACE_PATH');
+              if (forwarded.length > 0) console.log(`   🏷️  Identity vars: ${forwarded.join(', ')}`);
             } else {
               command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
               console.warn(`   ⚠️ Interactive script not found, falling back to single-shot`);
@@ -1598,28 +1486,6 @@ 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);
@@ -1803,4 +1669,4 @@ server.listen(serverMeta.port, () => {
     console.log('✅ HTTPS enabled - ready for secure connections from deployed frontends');
     console.log('');
   }
-});
+});

package/lib/session-recorder.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
 const { execSync } = require('child_process');
 const util = require('util');
 const { exec } = require('child_process');
@@ -34,89 +35,139 @@ function extractFilesTouched(diff) {
   return Array.from(seen);
 }
 
-// Snapshot the canonical state files so the session record carries the
-// latest STATUS / HANDOFF / DECISIONS / etc. up to the portal for display
-// on qig.ai. Three groups are captured into a single bag keyed by relative
-// path; the frontend distinguishes them by path prefix.
+// Snapshot the project's maker-framework markdown docs so the session record
+// carries the latest STATUS / HANDOFF / ARCHITECTURE / PRD / etc. up to the
+// portal for display on qig.ai. Captured as a single bag keyed by relative
+// path; the frontend distinguishes by path prefix.
 //
-//   docs/state/*.md            — project-level state (always present after scaffold)
-//   docs/architecture/*.md     — ARCHITECTURE.md + ADRs from project-kickoff
-//   docs/features/<slug>/*     — per-feature ROADMAP / PHASES / STATUS / manifest
-//                                from feature-kickoff (one entry per feature)
+// All 11 dirs under `docs/` listed in the maker framework are walked
+// recursively for `.md` files in priority order, until a total-bag budget
+// is hit. The Java PairProgrammerSessionService persists the bag to the
+// `state_files` JSONB column.
 //
-// All three flow through `stateFiles` on the session record. The Java
-// PairProgrammerSessionService persists the bag to the `state_files` JSONB
-// column; no schema change is needed to add new path prefixes.
-const STATE_FILES_TO_CAPTURE = [
-  'docs/state/STATUS.md',
-  'docs/state/HANDOFF.md',
-  'docs/state/DECISIONS.md',
-  'docs/state/CHANGELOG.md',
-  'docs/state/OPEN_QUESTIONS.md',
-  'docs/state/RISKS.md',
-  // Project architecture pack from kickoff v7.
-  'docs/architecture/ARCHITECTURE.md'
+// Priority order matters: when the budget is exhausted, the high-value docs
+// must already be in. State first, then architecture, then product / planning,
+// then features, then the rest alphabetical.
+const STATE_DOC_DIRS = [
+  'state',
+  'architecture',
+  'product',
+  'planning',
+  'features',
+  'compliance',
+  'design',
+  'operations',
+  'reports',
+  'requirements',
+  'standards'
 ];
-const FEATURE_FILE_NAMES = [
-  'ROADMAP.md',
-  'PHASES.md',
-  'STATUS.md',
-  'OPEN_QUESTIONS.md',
-  'manifest.json'
-];
-const MAX_STATE_FILE_BYTES = 256 * 1024; // 256KB per file
+const MAX_STATE_FILE_BYTES = 256 * 1024;      // 256KB per file
+const MAX_BAG_BYTES = 2 * 1024 * 1024;        // 2MB total — fits Postgres JSONB row comfortably + keeps frontend fast.
+const MAX_FILES_PER_DIR = 50;                 // Bounds runaway dirs (e.g. archive of old reports).
+const MAX_WALK_DEPTH = 5;
+
+/**
+ * Walk the workspace's framework markdown docs and return a SPLIT representation:
+ *   manifest[relPath] = { sha256, size }                  // small — goes into the JSONB column
+ *   contents[sha256]  = base64(utf8 content)              // large — uploaded to Supabase Storage
+ *
+ * Legacy placeholders (oversized-file notes, truncation marker) stay as string
+ * values in the manifest — they're not real files, just metadata the frontend
+ * already knows how to render.
+ */
+function readStateFiles(workspace) {
+  const manifest = {};
+  const contents = {};
+  const skipped = [];
+  const state = { bytes: 0, halted: false };
+  if (!workspace) return { manifest, contents };
+
+  for (const dir of STATE_DOC_DIRS) {
+    walkMdFiles(path.join(workspace, 'docs', dir), `docs/${dir}`, manifest, contents, 0, state, skipped);
+    if (state.halted) break;
+  }
+
+  if (skipped.length > 0) {
+    manifest['__truncated__'] = JSON.stringify({
+      reason: `state_files bag hit ${MAX_BAG_BYTES}-byte budget`,
+      capturedBytes: state.bytes,
+      skippedFiles: skipped.slice(0, 200)
+    }, null, 2);
+  }
 
-function readSafe(absPath, relPath, out) {
+  return { manifest, contents };
+}
+
+function walkMdFiles(absDir, relDir, manifest, contents, depth, state, skipped) {
+  if (state.halted || depth > MAX_WALK_DEPTH) return;
+  let entries;
   try {
-    const stat = fs.statSync(absPath);
-    if (!stat.isFile()) return;
-    if (stat.size > MAX_STATE_FILE_BYTES) {
-      out[relPath] = `[File omitted: ${stat.size} bytes exceeds ${MAX_STATE_FILE_BYTES}-byte cap]`;
-      return;
-    }
-    out[relPath] = fs.readFileSync(absPath, 'utf8');
+    entries = fs.readdirSync(absDir, { withFileTypes: true });
   } catch (e) {
-    // Missing file is normal — skip silently.
+    return; // Missing or unreadable dir — skip silently.
   }
-}
 
-function readStateFiles(workspace) {
-  const out = {};
-  if (!workspace) return out;
+  // Sort: directories last, files alphabetically. Gives stable, predictable
+  // capture order so truncation skips the same low-priority files each run.
+  entries.sort((a, b) => {
+    if (a.isDirectory() !== b.isDirectory()) return a.isDirectory() ? 1 : -1;
+    return a.name.localeCompare(b.name);
+  });
 
-  // Fixed list (state pack + ARCHITECTURE).
-  for (const rel of STATE_FILES_TO_CAPTURE) {
-    readSafe(path.join(workspace, rel), rel, out);
+  let filesInDir = 0;
+  for (const entry of entries) {
+    if (state.halted) return;
+    if (entry.name.startsWith('.')) continue; // Skip hidden entries.
+    const absPath = path.join(absDir, entry.name);
+    const relPath = `${relDir}/${entry.name}`;
+    if (entry.isDirectory()) {
+      walkMdFiles(absPath, relPath, manifest, contents, depth + 1, state, skipped);
+    } else if (entry.isFile()) {
+      if (!entry.name.endsWith('.md')) continue;
+      if (entry.name.includes('.bak-')) continue; // Skip *.bak-<timestamp> backups.
+      if (filesInDir >= MAX_FILES_PER_DIR) {
+        skipped.push(`${relPath} (per-dir cap)`);
+        continue;
+      }
+      filesInDir++;
+      readSafe(absPath, relPath, manifest, contents, state, skipped);
+    }
   }
+}
 
-  // ADRs — docs/architecture/adr/*.md.
-  const adrDir = path.join(workspace, 'docs', 'architecture', 'adr');
+function readSafe(absPath, relPath, manifest, contents, state, skipped) {
+  let stat;
   try {
-    for (const entry of fs.readdirSync(adrDir, { withFileTypes: true })) {
-      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-      const rel = `docs/architecture/adr/${entry.name}`;
-      readSafe(path.join(adrDir, entry.name), rel, out);
-    }
+    stat = fs.statSync(absPath);
   } catch (e) {
-    // No ADR dir is normal.
+    return; // Missing file is normal.
   }
-
-  // Per-feature files — docs/features/<slug>/{ROADMAP,PHASES,STATUS,OPEN_QUESTIONS}.md
-  // and manifest.json. One slug = one folder.
-  const featuresDir = path.join(workspace, 'docs', 'features');
+  if (!stat.isFile()) return;
+  if (stat.size > MAX_STATE_FILE_BYTES) {
+    // Oversized files stay as inline placeholder strings — the frontend treats
+    // these as "metadata, not file content" and shows them as-is.
+    manifest[relPath] = `[File omitted: ${stat.size} bytes exceeds ${MAX_STATE_FILE_BYTES}-byte cap]`;
+    return;
+  }
+  if (state.bytes + stat.size > MAX_BAG_BYTES) {
+    skipped.push(`${relPath} (bag budget)`);
+    state.halted = true;
+    return;
+  }
+  let buf;
   try {
-    for (const entry of fs.readdirSync(featuresDir, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      for (const filename of FEATURE_FILE_NAMES) {
-        const rel = `docs/features/${entry.name}/${filename}`;
-        readSafe(path.join(featuresDir, entry.name, filename), rel, out);
-      }
-    }
+    buf = fs.readFileSync(absPath);
   } catch (e) {
-    // No features dir is normal.
+    return; // Read failure (perms etc.) — skip silently.
   }
-
-  return out;
+  const sha256 = crypto.createHash('sha256').update(buf).digest('hex');
+  manifest[relPath] = { sha256, size: buf.length };
+  // Dedupe: only one base64 payload per unique sha. Multiple paths with the
+  // same content reference the same Storage object.
+  if (!Object.prototype.hasOwnProperty.call(contents, sha256)) {
+    contents[sha256] = buf.toString('base64');
+  }
+  state.bytes += buf.length;
 }
 
 // Enumerate feature slugs from the workspace so the frontend can list features
@@ -314,6 +365,10 @@ class SessionRecorder {
   _buildRecord(finalCommit, totalDiff) {
     const completedSteps = this.steps.filter(s => s.completedAt && !s.error).length;
     const closedCleanly = this.steps.length > 0 && completedSteps === this.steps.length;
+    // Split the state-files snapshot into a manifest (small, goes to JSONB) and
+    // a base64 contents map (large, backend offloads to Supabase Storage and
+    // strips before persisting the row).
+    const { manifest: stateFilesManifest, contents: stateFileContents } = readStateFiles(this.workspace);
     return {
       sessionId: this.sessionId,
       version: '1.1.0',
@@ -337,13 +392,14 @@ class SessionRecorder {
       completedSteps,
       closedCleanly,
       filesTouched: extractFilesTouched(totalDiff),
-      // Snapshot of state-pack + architecture + feature files at session-end
-      // so the QIG frontend can display the latest STATUS / HANDOFF /
-      // DECISIONS / ROADMAP / etc. without needing live filesystem access
-      // on the dev's machine. Single bag keyed by relative path; frontend
-      // filters by prefix (docs/state/*, docs/architecture/*,
-      // docs/features/<slug>/*).
-      stateFiles: readStateFiles(this.workspace),
+      // Manifest keyed by relative path. Each entry is either a `{sha256, size}`
+      // pointer (Supabase Storage), an inline placeholder string (oversized
+      // file / truncation marker), or — in older agents — the raw content
+      // string. The frontend renders all three shapes; see useStateFileBody.
+      stateFiles: stateFilesManifest,
+      // sha → base64(utf8). Drained server-side into pair-programmer-files
+      // bucket; never persisted to the JSONB column.
+      stateFileContents,
       // Quick index of feature slugs found in docs/features/. Lets the
       // frontend enumerate features without parsing the bag.
       featureSlugs: listFeatureSlugs(this.workspace),

package/package.json

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