create-byan-agent 2.9.5 → 2.9.7

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.9.7] - 2026-04-21
+
+### Fixed - MCP server empty-directory install bug
+
+- **`copyMcpServer` now asserts `server.js` exists after copy** — previously, a partial copy could leave `_byan/mcp/byan-mcp-server/` empty, causing Claude Code to fail with `Cannot find module '.../server.js'` on the next launch. The post-copy check now throws a clear error instead of silently succeeding.
+- **`create-byan-agent-v2.js` surfaces Claude native-setup failures in red** — prior behavior showed a yellow "partial" warning that users missed; now the failure is explicit and points at the MCP directory to inspect.
+- **Regression test** added in `claude-native-setup.test.js` that mocks `fs.copy` to a no-op and verifies the post-copy assertion throws.
+- **Observed on**: byan_web install with 2.9.6, dossier `_byan/mcp/byan-mcp-server/` vide, MCP failed in Claude Code.
+
+---
+
 ## [2.7.0] - 2026-02-21
 
 ### Added - Soul System + Tao System

package/install/bin/create-byan-agent-v2.js

@@ -16,6 +16,7 @@ const { generateProjectAgentsDoc } = require('../lib/project-agents-generator');
 const { launchPhase2Chat, generateDefaultConfig } = require('../lib/phase2-chat');
 const { setupByanWebIntegration } = require('../lib/byan-web-integration');
 const { setupClaudeNative } = require('../lib/claude-native-setup');
+const { setupStagingConsent } = require('../lib/staging-consent');
 
 const BYAN_VERSION = require('../package.json').version;
 
@@ -1348,18 +1349,36 @@ async function install() {
     try {
       await setupClaudeNative(projectRoot);
     } catch (error) {
-      console.log(chalk.yellow(`  ⚠ Claude native setup partial: ${error.message}`));
+      console.log(chalk.red(`  ✘ Claude native setup failed: ${error.message}`));
+      console.log(
+        chalk.yellow(
+          `    → MCP, hooks or skills may be incomplete. Inspect _byan/mcp/byan-mcp-server/ and re-run if empty.`
+        )
+      );
     }
   }
 
   if (needsClaude || needsCopilot) {
     console.log();
     console.log(chalk.cyan('byan_web integration (optional — service payant)'));
+    let byanWebResult = { configured: false };
     try {
-      await setupByanWebIntegration(projectRoot);
+      byanWebResult = await setupByanWebIntegration(projectRoot);
     } catch (error) {
       console.log(chalk.yellow(`  ⚠ byan_web setup skipped: ${error.message}`));
     }
+
+    if (byanWebResult && byanWebResult.configured) {
+      console.log();
+      console.log(chalk.cyan('byan_web memory-sync opt-in (consent)'));
+      try {
+        await setupStagingConsent(projectRoot, {
+          byanWebConfigured: true,
+        });
+      } catch (error) {
+        console.log(chalk.yellow(`  ⚠ memory-sync setup skipped: ${error.message}`));
+      }
+    }
   }
 
   // Step 8: Create config.yaml

package/install/lib/claude-native-setup.js

@@ -56,6 +56,15 @@ async function copyMcpServer(projectRoot) {
   if (!(await fs.pathExists(src))) return { copied: false };
   await fs.ensureDir(dst);
   await fs.copy(src, dst, { overwrite: true, filter: (s) => !s.includes('node_modules') });
+  // Post-copy sanity check: server.js must exist, otherwise the MCP client will
+  // fail on next Claude Code launch with "Cannot find module" (seen on 2.9.6).
+  const serverFile = path.join(dst, 'server.js');
+  if (!(await fs.pathExists(serverFile))) {
+    throw new Error(
+      `MCP server copy produced no server.js at ${serverFile}. ` +
+        `Template source: ${src}. Re-run install or copy manually.`
+    );
+  }
   return { copied: true, path: dst };
 }
 

package/install/lib/staging-consent.js

@@ -0,0 +1,149 @@
+/**
+ * Installer step — BYAN memory-sync opt-in + consent (SM5).
+ *
+ * Shown during create-byan-agent. Only prompts when the user already
+ * provided a byan_web URL + token (via setupByanWebIntegration), since
+ * memory-sync without credentials is a no-op.
+ *
+ * On opt-in, writes :
+ *   _byan/config.yaml  → memory_sync: { enabled: true }
+ *   OR loadbalancer.yaml if _byan/config.yaml not present
+ *
+ * Prints a clear consent notice listing what gets sent and how to
+ * disable. The user must type "oui" / "yes" to enable — no default to
+ * true.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+
+const CONSENT_NOTICE = [
+  '',
+  chalk.yellow.bold('BYAN memory-sync — consent requis'),
+  '',
+  'Si vous activez cette option, apres chaque interaction avec',
+  'Claude Code ou Copilot CLI, BYAN envoie automatiquement a votre',
+  'instance byan_web les elements suivants :',
+  '',
+  '  - messages utilisateur (prompts)',
+  '  - reponses assistant',
+  '  - chemins de fichiers modifies',
+  '  - sessionId et timestamp',
+  '',
+  'Filtrage applique AVANT envoi :',
+  '  - chit-chat (moins de 50 caracteres) -> ignore',
+  '  - doublons (hash SHA256 du contenu)   -> ignore',
+  '  - categories : fact | decision | blocker | artifact',
+  '',
+  'Les donnees sont stockees dans VOTRE instance byan_web',
+  '(pas de tierce partie). Le token JWT identifie l auteur.',
+  '',
+  chalk.cyan('Desactiver plus tard :'),
+  '  - editer _byan/config.yaml    -> memory_sync: { enabled: false }',
+  '  - OU invoquer le skill        -> /byan-no-stage pour un turn',
+  '',
+].join('\n');
+
+async function promptConsent({ skipPrompts, defaultAnswer } = {}) {
+  if (skipPrompts) return { enabled: defaultAnswer === true };
+
+  console.log(CONSENT_NOTICE);
+
+  const { enable } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'enable',
+      message:
+        'Activer la synchronisation automatique de vos conversations vers byan_web ?',
+      default: false,
+    },
+  ]);
+
+  return { enabled: enable };
+}
+
+function configPaths(projectRoot) {
+  return {
+    byanConfig: path.join(projectRoot, '_byan', 'config.yaml'),
+    lbConfig: path.join(projectRoot, 'loadbalancer.yaml'),
+  };
+}
+
+async function writeMemorySyncFlag(projectRoot, enabled) {
+  const { byanConfig, lbConfig } = configPaths(projectRoot);
+
+  // Prefer _byan/config.yaml (BYAN primary config). Fall back to
+  // loadbalancer.yaml only if _byan/config.yaml is missing AND
+  // loadbalancer.yaml already exists.
+  let target;
+  if (await fs.pathExists(byanConfig)) {
+    target = byanConfig;
+  } else if (await fs.pathExists(lbConfig)) {
+    target = lbConfig;
+  } else {
+    target = byanConfig;
+  }
+  await fs.ensureDir(path.dirname(target));
+
+  let doc = {};
+  if (await fs.pathExists(target)) {
+    try {
+      doc = yaml.load(await fs.readFile(target, 'utf8')) || {};
+    } catch {
+      doc = {};
+    }
+  }
+  doc.memory_sync = { ...(doc.memory_sync || {}), enabled: enabled === true };
+
+  await fs.writeFile(target, yaml.dump(doc), 'utf8');
+  return target;
+}
+
+async function setupStagingConsent(projectRoot, options = {}) {
+  const tokenPresent = options.byanWebConfigured === true;
+  if (!tokenPresent) {
+    if (!options.quiet) {
+      console.log(
+        chalk.gray('  i memory-sync skipped (no byan_web token configured)')
+      );
+    }
+    return { configured: false, reason: 'no_token' };
+  }
+
+  const { enabled } = await promptConsent({
+    skipPrompts: options.skipPrompts === true,
+    defaultAnswer: options.presetEnabled === true,
+  });
+
+  const target = await writeMemorySyncFlag(projectRoot, enabled);
+
+  if (!options.quiet) {
+    if (enabled) {
+      console.log(chalk.green('  OK memory-sync ENABLED in ' + path.relative(projectRoot, target)));
+      console.log(
+        chalk.gray(
+          '     a chaque fin de turn, votre hook Stop (Claude) et votre'
+        )
+      );
+      console.log(
+        chalk.gray(
+          '     extension Copilot staging enverront les memoires a byan_web.'
+        )
+      );
+    } else {
+      console.log(chalk.gray('  i memory-sync left DISABLED (opt-in declined)'));
+    }
+  }
+
+  return { configured: true, enabled, configPath: target };
+}
+
+module.exports = {
+  setupStagingConsent,
+  writeMemorySyncFlag,
+  promptConsent,
+  CONSENT_NOTICE,
+};

package/install/templates/.claude/hooks/stage-to-byan.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — stage the ending turn to byan_web memory (SM1b).
+ *
+ * Reads the Stop payload on stdin, extracts user + assistant messages,
+ * delegates to src/staging/staging.js processTurn().
+ *
+ * Config source (first present wins) :
+ *   - .claude/settings.local.json env.BYAN_API_URL / BYAN_API_TOKEN
+ *   - process.env.BYAN_API_URL / BYAN_API_TOKEN
+ *   - loadbalancer.yaml or _byan/config.yaml memory_sync: section
+ *
+ * Never blocks : this hook always exits 0 with continue:true. Failures
+ * are queued locally for retry, not surfaced to the user mid-turn.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve('');
+    let data = '';
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+function readSettingsEnv() {
+  const p = path.join(projectDir, '.claude', 'settings.local.json');
+  if (!fs.existsSync(p)) return {};
+  try {
+    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return j.env || {};
+  } catch {
+    return {};
+  }
+}
+
+function readMemorySyncConfig() {
+  const paths = [
+    path.join(projectDir, 'loadbalancer.yaml'),
+    path.join(projectDir, '_byan', 'config.yaml'),
+  ];
+  for (const p of paths) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      const yaml = require('js-yaml');
+      const doc = yaml.load(fs.readFileSync(p, 'utf8'));
+      if (doc && doc.memory_sync) return doc.memory_sync;
+    } catch {
+      // fall through
+    }
+  }
+  return null;
+}
+
+function buildConfig() {
+  const settingsEnv = readSettingsEnv();
+  const apiUrl = settingsEnv.BYAN_API_URL || process.env.BYAN_API_URL || null;
+  const apiToken = settingsEnv.BYAN_API_TOKEN || process.env.BYAN_API_TOKEN || null;
+  const memorySync = readMemorySyncConfig() || {};
+  return {
+    byan_api_url: apiUrl,
+    byan_api_token: apiToken,
+    memory_sync: memorySync,
+  };
+}
+
+function extractTurn(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+
+  const transcript = payload.transcript || payload.messages;
+  if (!Array.isArray(transcript)) return null;
+
+  return {
+    sessionId: payload.session_id || payload.sessionId || null,
+    messages: transcript
+      .filter((m) => m && (m.role === 'user' || m.role === 'assistant'))
+      .slice(-4),
+  };
+}
+
+(async () => {
+  const raw = await readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch {
+    payload = {};
+  }
+
+  const config = buildConfig();
+  const turn = extractTurn(payload);
+
+  if (!turn) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    process.exit(0);
+  }
+
+  try {
+    const { processTurn } = require(path.join(projectDir, 'src', 'staging', 'staging.js'));
+    await processTurn({
+      turn,
+      cliSource: 'claude-code',
+      config,
+      projectRoot: projectDir,
+      flushNow: true,
+    });
+  } catch {
+    // staging must never break the session
+  }
+
+  process.stdout.write(JSON.stringify({ continue: true }));
+  process.exit(0);
+})();

package/install/templates/.claude/settings.json

@@ -45,6 +45,10 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fd-response-check.js"
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stage-to-byan.js"
           }
         ]
       }

package/install/templates/.github/extensions/byan-staging/extension.mjs

@@ -0,0 +1,169 @@
+/**
+ * Copilot CLI extension — BYAN staging (SM1c).
+ *
+ * Attaches to the current Copilot session via joinSession() and
+ * triggers the BYAN staging pipeline at the end of each assistant
+ * turn. Delegates to src/staging/staging.js so Claude Code and Copilot
+ * CLI share the exact same extract / filter / dedup / queue / flush
+ * logic.
+ *
+ * How it's discovered : Copilot CLI scans .github/extensions/
+ * (project) and the user's copilot config for subdirectories
+ * containing extension.mjs. This file is auto-launched as a child
+ * process, gets @github/copilot-sdk on its module path, and calls
+ * joinSession with the hook registration below.
+ */
+
+import { joinSession } from '@github/copilot-sdk/extension';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const require = createRequire(import.meta.url);
+
+const EXTENSION_DIR = path.dirname(new URL(import.meta.url).pathname);
+const PROJECT_ROOT =
+  process.env.BYAN_PROJECT_ROOT ||
+  process.env.CLAUDE_PROJECT_DIR ||
+  findProjectRoot(EXTENSION_DIR);
+
+function findProjectRoot(startDir) {
+  // Walk up until we find a package.json or .git — else cwd
+  let dir = startDir;
+  for (let i = 0; i < 6; i++) {
+    if (
+      fs.existsSync(path.join(dir, 'package.json')) ||
+      fs.existsSync(path.join(dir, '.git'))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+function loadStaging() {
+  try {
+    return require(path.join(PROJECT_ROOT, 'src', 'staging', 'staging.js'));
+  } catch {
+    return null;
+  }
+}
+
+function readSettingsEnv() {
+  const p = path.join(PROJECT_ROOT, '.claude', 'settings.local.json');
+  if (!fs.existsSync(p)) return {};
+  try {
+    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return j.env || {};
+  } catch {
+    return {};
+  }
+}
+
+function readMemorySyncConfig() {
+  const paths = [
+    path.join(PROJECT_ROOT, 'loadbalancer.yaml'),
+    path.join(PROJECT_ROOT, '_byan', 'config.yaml'),
+  ];
+  for (const p of paths) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      const yaml = require('js-yaml');
+      const doc = yaml.load(fs.readFileSync(p, 'utf8'));
+      if (doc && doc.memory_sync) return doc.memory_sync;
+    } catch {
+      // fall through
+    }
+  }
+  return null;
+}
+
+function buildConfig() {
+  const envFile = readSettingsEnv();
+  return {
+    byan_api_url: envFile.BYAN_API_URL || process.env.BYAN_API_URL || null,
+    byan_api_token: envFile.BYAN_API_TOKEN || process.env.BYAN_API_TOKEN || null,
+    memory_sync: readMemorySyncConfig() || {},
+  };
+}
+
+// Per-turn buffer of recent messages/tool calls keyed by sessionId.
+const turnBuffer = new Map();
+
+function bufferFor(sessionId) {
+  const key = sessionId || 'default';
+  if (!turnBuffer.has(key)) {
+    turnBuffer.set(key, { userMessages: [], assistantMessages: [], toolCalls: [] });
+  }
+  return turnBuffer.get(key);
+}
+
+function clearBuffer(sessionId) {
+  turnBuffer.delete(sessionId || 'default');
+}
+
+const session = await joinSession({
+  hooks: {
+    onSessionStart: async () => {
+      await session.log('BYAN staging extension loaded', { ephemeral: true });
+    },
+
+    onUserPromptSubmitted: async (input) => {
+      const buf = bufferFor(input.sessionId);
+      buf.userMessages.push({ role: 'user', content: input.prompt });
+    },
+
+    onPreToolUse: async (input) => {
+      const buf = bufferFor(input.sessionId);
+      buf.toolCalls.push({
+        name: input.toolName,
+        input: input.toolArgs || {},
+      });
+    },
+
+    onPostToolUse: async (input) => {
+      const buf = bufferFor(input.sessionId);
+      // If the last tool call has a text result, treat it as assistant output
+      if (input.toolResult && typeof input.toolResult.content === 'string') {
+        buf.assistantMessages.push({
+          role: 'assistant',
+          content: input.toolResult.content,
+        });
+      }
+    },
+
+    onSessionEnd: async (input) => {
+      const staging = loadStaging();
+      if (!staging) {
+        clearBuffer(input?.sessionId);
+        return;
+      }
+
+      const buf = bufferFor(input?.sessionId);
+      const turn = {
+        sessionId: input?.sessionId || null,
+        messages: [...buf.userMessages, ...buf.assistantMessages],
+        toolCalls: buf.toolCalls,
+      };
+
+      try {
+        await staging.processTurn({
+          turn,
+          cliSource: 'copilot-cli',
+          config: buildConfig(),
+          projectRoot: PROJECT_ROOT,
+          flushNow: true,
+        });
+      } catch {
+        // never block session end
+      }
+
+      clearBuffer(input?.sessionId);
+    },
+  },
+
+  tools: [],
+});

package/install/templates/.github/extensions/byan-staging/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@byan/copilot-staging-extension",
+  "version": "0.1.0",
+  "description": "Copilot CLI extension that stages conversation knowledge to byan_web /api/memory via the shared BYAN staging core.",
+  "type": "module",
+  "main": "extension.mjs",
+  "private": true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.9.5",
+  "version": "2.9.7",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Copilot CLI, Claude Code, Codex). Merise Agile + TDD + 64 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {

package/src/staging/staging.js

@@ -0,0 +1,394 @@
+/**
+ * BYAN staging core — extract / filter / dedup / queue / flush conversation
+ * knowledge from any supported CLI (claude-code, copilot-cli, codex) to a
+ * byan_web instance via POST /api/memory.
+ *
+ * Usage from a Claude Code Stop hook :
+ *   const { processTurn } = require('./staging');
+ *   await processTurn({ turn, cliSource: 'claude-code', config, projectRoot });
+ *
+ * Usage from a Copilot CLI extension.mjs :
+ *   import { processTurn } from '<repo>/src/staging/staging.js';
+ *   await processTurn({ turn, cliSource: 'copilot-cli', config, projectRoot });
+ *
+ * Contract :
+ *   - processTurn() is idempotent (dedup by content hash)
+ *   - never throws — errors go to the retry queue
+ *   - if enabled=false, it's a pure no-op (zero bytes sent)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+
+const QUEUE_FILENAME = 'staging-queue.jsonl';
+const SEEN_FILENAME = 'staging-seen.json';
+const STAGING_DIR = path.join('_byan-output', 'staging');
+
+// Patterns considered "chit-chat" — skipped by the triage filter.
+const CHITCHAT_PATTERNS = [
+  /^(hi|hello|ok|thanks|merci|salut|bye|lol|yep|nope)[!. ]*$/i,
+  /^(y|yes|n|no|go|stop)$/i,
+];
+
+const MIN_CONTENT_CHARS = 50;
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.env.BYAN_PROJECT_ROOT || process.cwd();
+}
+
+function stagingDir(projectRoot) {
+  return path.join(resolveRoot(projectRoot), STAGING_DIR);
+}
+
+function queuePath(projectRoot) {
+  return path.join(stagingDir(projectRoot), QUEUE_FILENAME);
+}
+
+function seenPath(projectRoot) {
+  return path.join(stagingDir(projectRoot), SEEN_FILENAME);
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function sha256(s) {
+  return crypto.createHash('sha256').update(String(s)).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Enablement + config
+// ---------------------------------------------------------------------------
+
+function isEnabled(config) {
+  if (!config || typeof config !== 'object') return false;
+  const ms = config.memory_sync || config.memorySync;
+  if (!ms) return false;
+  return ms.enabled === true;
+}
+
+function apiUrl(config) {
+  if (!config) return null;
+  return config.byan_api_url || config.BYAN_API_URL || process.env.BYAN_API_URL || null;
+}
+
+function apiToken(config) {
+  if (!config) return process.env.BYAN_API_TOKEN || null;
+  return config.byan_api_token || config.BYAN_API_TOKEN || process.env.BYAN_API_TOKEN || null;
+}
+
+// ---------------------------------------------------------------------------
+// Extract — normalize a turn payload into a memory entry draft
+// ---------------------------------------------------------------------------
+
+function extractUserText(turn) {
+  if (!turn) return '';
+  if (typeof turn.userMessage === 'string') return turn.userMessage;
+  if (typeof turn.prompt === 'string') return turn.prompt;
+  if (Array.isArray(turn.messages)) {
+    const u = [...turn.messages].reverse().find((m) => m && m.role === 'user');
+    if (u && typeof u.content === 'string') return u.content;
+  }
+  return '';
+}
+
+function extractAssistantText(turn) {
+  if (!turn) return '';
+  if (typeof turn.assistantMessage === 'string') return turn.assistantMessage;
+  if (Array.isArray(turn.messages)) {
+    const a = [...turn.messages].reverse().find((m) => m && m.role === 'assistant');
+    if (a) {
+      if (typeof a.content === 'string') return a.content;
+      if (Array.isArray(a.content)) {
+        return a.content
+          .map((c) => (c && typeof c === 'object' && c.text ? c.text : ''))
+          .join(' ')
+          .trim();
+      }
+    }
+  }
+  return '';
+}
+
+function extractFilesTouched(turn) {
+  if (!turn) return [];
+  if (Array.isArray(turn.filesTouched)) return turn.filesTouched.filter(Boolean);
+  if (Array.isArray(turn.toolCalls)) {
+    const files = [];
+    for (const tc of turn.toolCalls) {
+      const p = tc?.input?.file_path || tc?.args?.file_path || tc?.input?.path;
+      if (p && typeof p === 'string') files.push(p);
+    }
+    return files;
+  }
+  return [];
+}
+
+function classify(content, turn) {
+  const c = String(content || '').toLowerCase();
+  if (/\b(decid(e|ed|ing)|choix|trade-?off|architecture)\b/i.test(c)) return 'decision';
+  if (/\b(bug|error|fail|broken|bloque|blocked|can't|impossible)\b/i.test(c)) return 'blocker';
+  const files = extractFilesTouched(turn);
+  if (files.length > 0) return 'artifact';
+  return 'fact';
+}
+
+function extract({ turn, cliSource }) {
+  const user = extractUserText(turn);
+  const assistant = extractAssistantText(turn);
+  const filesTouched = extractFilesTouched(turn);
+  const content = [user, assistant].filter(Boolean).join('\n\n').trim();
+
+  return {
+    cliSource: cliSource || 'unknown',
+    sessionId: turn?.sessionId || null,
+    category: classify(content, turn),
+    content,
+    metadata: {
+      userMessageLen: user.length,
+      assistantMessageLen: assistant.length,
+      filesTouched,
+      timestamp: new Date().toISOString(),
+    },
+    pinned: false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Filter — triage chit-chat
+// ---------------------------------------------------------------------------
+
+function shouldKeep(entry) {
+  if (!entry || typeof entry.content !== 'string') return false;
+  if (entry.content.length < MIN_CONTENT_CHARS) return false;
+
+  const trimmed = entry.content.trim();
+  for (const re of CHITCHAT_PATTERNS) {
+    if (re.test(trimmed)) return false;
+  }
+
+  // Must have at least one of : files touched, substantive content, or decision keywords
+  if (entry.metadata && Array.isArray(entry.metadata.filesTouched) && entry.metadata.filesTouched.length > 0) {
+    return true;
+  }
+  // Otherwise require reasonable content length
+  return trimmed.length >= MIN_CONTENT_CHARS * 2;
+}
+
+// ---------------------------------------------------------------------------
+// Dedup — hash-based, persisted
+// ---------------------------------------------------------------------------
+
+function readSeen(projectRoot) {
+  const p = seenPath(projectRoot);
+  if (!fs.existsSync(p)) return { hashes: [] };
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return { hashes: [] };
+  }
+}
+
+function writeSeen(projectRoot, seen) {
+  ensureDir(stagingDir(projectRoot));
+  // Keep only last 500 hashes to cap disk use
+  const trimmed = { hashes: seen.hashes.slice(-500) };
+  fs.writeFileSync(seenPath(projectRoot), JSON.stringify(trimmed));
+}
+
+function isDuplicate(entry, projectRoot) {
+  const h = sha256(entry.content);
+  const seen = readSeen(projectRoot);
+  return seen.hashes.includes(h);
+}
+
+function markSeen(entry, projectRoot) {
+  const h = sha256(entry.content);
+  const seen = readSeen(projectRoot);
+  if (!seen.hashes.includes(h)) {
+    seen.hashes.push(h);
+    writeSeen(projectRoot, seen);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Queue — local append-only, flushed by flush()
+// ---------------------------------------------------------------------------
+
+function enqueue(entry, projectRoot) {
+  ensureDir(stagingDir(projectRoot));
+  const p = queuePath(projectRoot);
+  const line = JSON.stringify({
+    ...entry,
+    enqueued_at: new Date().toISOString(),
+    attempts: 0,
+  });
+  fs.appendFileSync(p, line + '\n');
+}
+
+function readQueue(projectRoot) {
+  const p = queuePath(projectRoot);
+  if (!fs.existsSync(p)) return [];
+  return fs
+    .readFileSync(p, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function writeQueue(projectRoot, entries) {
+  const p = queuePath(projectRoot);
+  if (entries.length === 0) {
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+    return;
+  }
+  fs.writeFileSync(
+    p,
+    entries.map((e) => JSON.stringify(e)).join('\n') + '\n'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Project ID — derived from git remote or cwd
+// ---------------------------------------------------------------------------
+
+function detectProjectId(projectRoot) {
+  const root = resolveRoot(projectRoot);
+  try {
+    const url = execSync('git remote get-url origin', {
+      cwd: root,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+    }).trim();
+    if (url) return sha256(url).slice(0, 16);
+  } catch {
+    // no git remote, fall through
+  }
+  return sha256(root).slice(0, 16);
+}
+
+// ---------------------------------------------------------------------------
+// Flush — POST queued entries to /api/memory with retry
+// ---------------------------------------------------------------------------
+
+async function postEntry({ entry, url, token, projectId }) {
+  const body = {
+    projectId,
+    sessionId: entry.sessionId,
+    cliSource: entry.cliSource,
+    category: entry.category,
+    content: entry.content,
+    metadata: entry.metadata,
+    pinned: entry.pinned === true,
+  };
+  const res = await fetch(`${url.replace(/\/$/, '')}/api/memory`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    const err = new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`);
+    err.status = res.status;
+    throw err;
+  }
+  return res.json().catch(() => ({}));
+}
+
+async function flush({ config, projectRoot, maxAttempts = 5 } = {}) {
+  const url = apiUrl(config);
+  const token = apiToken(config);
+  if (!url || !token) {
+    return { flushed: 0, requeued: 0, dropped: 0, reason: 'missing url or token' };
+  }
+
+  const projectId = detectProjectId(projectRoot);
+  const queue = readQueue(projectRoot);
+  if (queue.length === 0) return { flushed: 0, requeued: 0, dropped: 0 };
+
+  let flushed = 0;
+  const remaining = [];
+  let dropped = 0;
+
+  for (const entry of queue) {
+    try {
+      await postEntry({ entry, url, token, projectId });
+      flushed += 1;
+    } catch (err) {
+      const attempts = (entry.attempts || 0) + 1;
+      if (attempts >= maxAttempts) {
+        dropped += 1;
+        continue;
+      }
+      remaining.push({ ...entry, attempts, last_error: err.message });
+    }
+  }
+
+  writeQueue(projectRoot, remaining);
+
+  return { flushed, requeued: remaining.length, dropped };
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration — the single entry point used by both hooks/extensions
+// ---------------------------------------------------------------------------
+
+async function processTurn({ turn, cliSource, config, projectRoot, flushNow = true } = {}) {
+  if (!isEnabled(config)) {
+    return { skipped: 'disabled' };
+  }
+
+  const entry = extract({ turn, cliSource });
+
+  if (!shouldKeep(entry)) {
+    return { skipped: 'filtered', category: entry.category };
+  }
+
+  if (isDuplicate(entry, projectRoot)) {
+    return { skipped: 'duplicate', category: entry.category };
+  }
+
+  enqueue(entry, projectRoot);
+  markSeen(entry, projectRoot);
+
+  if (!flushNow) {
+    return { queued: true, flushed: 0, category: entry.category };
+  }
+
+  const result = await flush({ config, projectRoot });
+  return { queued: true, ...result, category: entry.category };
+}
+
+module.exports = {
+  processTurn,
+  extract,
+  shouldKeep,
+  isEnabled,
+  isDuplicate,
+  markSeen,
+  enqueue,
+  readQueue,
+  writeQueue,
+  flush,
+  detectProjectId,
+  sha256,
+  classify,
+  queuePath,
+  seenPath,
+  STAGING_DIR,
+  QUEUE_FILENAME,
+  SEEN_FILENAME,
+  MIN_CONTENT_CHARS,
+};