thumbgate 1.1.0 → 1.3.0

package/scripts/claude-feedback-sync.js

@@ -0,0 +1,320 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const {
+  captureFeedback,
+  getFeedbackPaths,
+  readJSONL,
+  analyzeFeedback,
+} = require('./feedback-loop');
+const { normalizeFeedbackText } = require('./feedback-quality');
+const {
+  resolveFeedbackDir,
+  resolveProjectDir,
+} = require('./feedback-paths');
+const { refreshStatuslineCache } = require('./hook-thumbgate-cache-updater');
+
+const SYNC_STATE_FILE = 'claude-feedback-sync-state.json';
+const DEFAULT_RECENT_FEEDBACK_LIMIT = 250;
+const DEFAULT_PROCESSED_ID_LIMIT = 512;
+const DUPLICATE_WINDOW_MS = 30 * 1000;
+
+function getClaudeHistoryPath(options = {}) {
+  if (options.historyPath) return options.historyPath;
+  if (process.env.THUMBGATE_CLAUDE_HISTORY_PATH) return process.env.THUMBGATE_CLAUDE_HISTORY_PATH;
+  const homeDir = options.homeDir || process.env.HOME || process.env.USERPROFILE || '';
+  return path.join(homeDir, '.claude', 'history.jsonl');
+}
+
+function getSyncStatePath(options = {}) {
+  const feedbackDir = resolveFeedbackDir({ feedbackDir: options.feedbackDir });
+  return path.join(feedbackDir, SYNC_STATE_FILE);
+}
+
+function readSyncState(options = {}) {
+  const statePath = getSyncStatePath(options);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    return {
+      historyOffset: Number(parsed.historyOffset || 0),
+      historySize: Number(parsed.historySize || 0),
+      processedIds: Array.isArray(parsed.processedIds) ? parsed.processedIds : [],
+      statePath,
+    };
+  } catch {
+    return {
+      historyOffset: 0,
+      historySize: 0,
+      processedIds: [],
+      statePath,
+    };
+  }
+}
+
+function writeSyncState(state, options = {}) {
+  const statePath = getSyncStatePath(options);
+  const payload = {
+    historyOffset: Number(state.historyOffset || 0),
+    historySize: Number(state.historySize || 0),
+    processedIds: Array.isArray(state.processedIds) ? state.processedIds.slice(-DEFAULT_PROCESSED_ID_LIMIT) : [],
+    updatedAt: new Date().toISOString(),
+  };
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, JSON.stringify(payload, null, 2));
+  return payload;
+}
+
+function readHistoryEntriesSince(filePath, state) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return {
+      entries: [],
+      nextOffset: 0,
+      size: 0,
+    };
+  }
+
+  const stat = fs.statSync(filePath);
+  const safeOffset = state && state.historyOffset > 0 && state.historyOffset <= stat.size
+    ? state.historyOffset
+    : 0;
+
+  const fileBuffer = fs.readFileSync(filePath);
+  const contents = fileBuffer.slice(safeOffset).toString('utf8');
+
+  const entries = contents
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  return {
+    entries,
+    nextOffset: stat.size,
+    size: stat.size,
+  };
+}
+
+function normalizeProjectPath(value) {
+  try {
+    return value ? path.resolve(String(value)) : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseHistoryTimestamp(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value > 1e12 ? value : value * 1000;
+  }
+  const text = String(value || '').trim();
+  if (!text) return null;
+  if (/^\d+$/.test(text)) {
+    const numeric = Number(text);
+    return numeric > 1e12 ? numeric : numeric * 1000;
+  }
+  const parsed = Date.parse(text);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function detectSignal(text) {
+  const normalized = String(text || '').toLowerCase();
+  if (/(thumbs?\s*down|that failed|that was wrong|fix this)/i.test(normalized)) return 'down';
+  if (/(thumbs?\s*up|that worked|looks good|nice work|perfect|good job)/i.test(normalized)) return 'up';
+  return null;
+}
+
+function extractPromptText(entry) {
+  const candidates = [
+    entry && entry.display,
+    entry && entry.message && entry.message.content,
+    entry && entry.attachment && entry.attachment.prompt,
+    entry && entry.content,
+  ];
+
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return '';
+}
+
+function buildExternalId(entry, promptText) {
+  const hash = crypto.createHash('sha256');
+  hash.update(String(entry.sessionId || ''));
+  hash.update('|');
+  hash.update(String(entry.timestamp || ''));
+  hash.update('|');
+  hash.update(String(entry.project || entry.cwd || ''));
+  hash.update('|');
+  hash.update(String(promptText || ''));
+  return `claude-history:${hash.digest('hex')}`;
+}
+
+function toHistoryCandidate(entry, options = {}) {
+  const promptText = extractPromptText(entry);
+  const signal = detectSignal(promptText);
+  if (!signal) return null;
+
+  const projectDir = normalizeProjectPath(options.projectDir);
+  const entryProject = normalizeProjectPath(entry.project || entry.cwd || '');
+  if (projectDir && entryProject && entryProject !== projectDir && !entryProject.startsWith(`${projectDir}${path.sep}`)) {
+    return null;
+  }
+  if (projectDir && !entryProject) {
+    return null;
+  }
+
+  return {
+    externalId: buildExternalId(entry, promptText),
+    promptText,
+    signal,
+    timestampMs: parseHistoryTimestamp(entry.timestamp),
+  };
+}
+
+function normalizeCandidateText(value) {
+  return normalizeFeedbackText(String(value || '').replace(/\s+/g, ' '));
+}
+
+function hasMatchingFeedbackEntry(candidate, feedbackEntries) {
+  const candidateText = normalizeCandidateText(candidate.promptText);
+  if (!candidateText) return false;
+
+  return feedbackEntries.some((entry) => {
+    const signal = entry && entry.signal === 'negative' ? 'down' : 'up';
+    if (signal !== candidate.signal) return false;
+
+    const feedbackText = normalizeCandidateText(
+      entry.submittedContext
+      || entry.context
+      || entry.whatWentWrong
+      || entry.whatWorked
+      || ''
+    );
+    if (feedbackText !== candidateText) return false;
+
+    const feedbackTimestamp = Date.parse(entry.timestamp || '');
+    if (!Number.isFinite(feedbackTimestamp) || !Number.isFinite(candidate.timestampMs)) {
+      return true;
+    }
+    return Math.abs(feedbackTimestamp - candidate.timestampMs) <= DUPLICATE_WINDOW_MS;
+  });
+}
+
+function syncClaudeHistoryFeedback(options = {}) {
+  if (options.disabled || process.env.THUMBGATE_DISABLE_CLAUDE_HISTORY_SYNC === '1') {
+    return {
+      importedCount: 0,
+      skippedCount: 0,
+      reason: 'disabled',
+    };
+  }
+
+  const originalEnv = {
+    THUMBGATE_FEEDBACK_DIR: process.env.THUMBGATE_FEEDBACK_DIR,
+    THUMBGATE_PROJECT_DIR: process.env.THUMBGATE_PROJECT_DIR,
+    THUMBGATE_CLAUDE_HISTORY_PATH: process.env.THUMBGATE_CLAUDE_HISTORY_PATH,
+  };
+
+  if (options.feedbackDir) process.env.THUMBGATE_FEEDBACK_DIR = options.feedbackDir;
+  if (options.projectDir && !options.feedbackDir) process.env.THUMBGATE_PROJECT_DIR = options.projectDir;
+  if (options.historyPath) process.env.THUMBGATE_CLAUDE_HISTORY_PATH = options.historyPath;
+
+  try {
+    const feedbackDir = resolveFeedbackDir({ feedbackDir: options.feedbackDir });
+    const projectDir = normalizeProjectPath(options.projectDir) || resolveProjectDir({
+      cwd: process.cwd(),
+      env: process.env,
+    });
+    const historyPath = getClaudeHistoryPath(options);
+    const state = readSyncState({ feedbackDir });
+    const history = readHistoryEntriesSince(historyPath, state);
+    const existingEntries = readJSONL(path.join(feedbackDir, 'feedback-log.jsonl'), {
+      maxLines: DEFAULT_RECENT_FEEDBACK_LIMIT,
+    });
+
+    let importedCount = 0;
+    let skippedCount = 0;
+    const processedIds = new Set(state.processedIds || []);
+
+    for (const entry of history.entries) {
+      const candidate = toHistoryCandidate(entry, { projectDir });
+      if (!candidate) continue;
+      if (processedIds.has(candidate.externalId)) {
+        skippedCount += 1;
+        continue;
+      }
+
+      if (hasMatchingFeedbackEntry(candidate, existingEntries)) {
+        processedIds.add(candidate.externalId);
+        skippedCount += 1;
+        continue;
+      }
+
+      const captureResult = captureFeedback({
+        signal: candidate.signal,
+        context: candidate.promptText,
+        whatWentWrong: candidate.signal === 'down' ? candidate.promptText : undefined,
+        whatWorked: candidate.signal === 'up' ? candidate.promptText : undefined,
+        tags: ['claude-history-sync', 'auto-capture-fallback'],
+      });
+
+      if (captureResult && captureResult.feedbackEvent) {
+        existingEntries.push(captureResult.feedbackEvent);
+      }
+      processedIds.add(candidate.externalId);
+      importedCount += 1;
+    }
+
+    writeSyncState({
+      historyOffset: history.nextOffset,
+      historySize: history.size,
+      processedIds: Array.from(processedIds),
+    }, { feedbackDir });
+
+    if (importedCount > 0) {
+      refreshStatuslineCache(analyzeFeedback(path.join(feedbackDir, 'feedback-log.jsonl')), path.join(feedbackDir, 'statusline_cache.json'));
+    }
+
+    return {
+      importedCount,
+      skippedCount,
+      historyPath,
+      feedbackDir,
+      projectDir,
+    };
+  } finally {
+    if (originalEnv.THUMBGATE_FEEDBACK_DIR == null) delete process.env.THUMBGATE_FEEDBACK_DIR;
+    else process.env.THUMBGATE_FEEDBACK_DIR = originalEnv.THUMBGATE_FEEDBACK_DIR;
+
+    if (originalEnv.THUMBGATE_PROJECT_DIR == null) delete process.env.THUMBGATE_PROJECT_DIR;
+    else process.env.THUMBGATE_PROJECT_DIR = originalEnv.THUMBGATE_PROJECT_DIR;
+
+    if (originalEnv.THUMBGATE_CLAUDE_HISTORY_PATH == null) delete process.env.THUMBGATE_CLAUDE_HISTORY_PATH;
+    else process.env.THUMBGATE_CLAUDE_HISTORY_PATH = originalEnv.THUMBGATE_CLAUDE_HISTORY_PATH;
+  }
+}
+
+module.exports = {
+  SYNC_STATE_FILE,
+  detectSignal,
+  extractPromptText,
+  getClaudeHistoryPath,
+  hasMatchingFeedbackEntry,
+  parseHistoryTimestamp,
+  readHistoryEntriesSince,
+  readSyncState,
+  syncClaudeHistoryFeedback,
+  toHistoryCandidate,
+  writeSyncState,
+};

package/scripts/cli-telemetry.js

@@ -5,7 +5,9 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
-const TELEMETRY_ENDPOINT = 'https://thumbgate-production.up.railway.app/v1/telemetry/ping';
+const _DEFAULT_TELEMETRY_HOST = 'https://thumbgate-production.up.railway.app';
+// Respect THUMBGATE_API_URL so test environments can point to a local stub
+const TELEMETRY_ENDPOINT = `${process.env.THUMBGATE_API_URL || _DEFAULT_TELEMETRY_HOST}/v1/telemetry/ping`;
 const INSTALL_ID_PATH = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.thumbgate', 'install-id');
 
 /**
@@ -80,6 +82,7 @@ function trackEvent(eventType, metadata = {}) {
     });
     req.on('error', () => {}); // silently ignore
     req.on('timeout', () => req.destroy());
+    req.on('socket', (s) => s.unref()); // fire-and-forget: never block process exit
     req.end(payload);
   } catch (_) {} // never crash the CLI
 }

package/scripts/computer-use-firewall.js

@@ -3,6 +3,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { buildDockerSandboxPlan } = require('./docker-sandbox-planner');
 
 /**
  * Computer-Use Action Firewall — normalizes OpenAI Responses API
@@ -129,13 +130,13 @@ function evaluateAction(action, preset = 'dev-sandbox', customRules = []) {
   const normalized = action.type ? action : normalizeAction(action);
   const presetConfig = PRESETS[preset];
   if (!presetConfig) {
-    return {
+    return attachExecutionSurface({
       decision: 'deny',
       reason: `Unknown preset: ${preset}`,
       preset,
       riskLevel: normalized.riskLevel,
       auditEntry: createAuditEntry(normalized, { decision: 'deny', reason: `Unknown preset: ${preset}`, preset }),
-    };
+    }, normalized);
   }
 
   // Custom rules override preset defaults
@@ -143,81 +144,108 @@ function evaluateAction(action, preset = 'dev-sandbox', customRules = []) {
     if (rule.action === normalized.type) {
       const decision = rule.decision || 'deny';
       const reason = rule.reason || `Custom rule override for ${normalized.type}`;
-      return {
+      return attachExecutionSurface({
         decision,
         reason,
         preset,
         riskLevel: normalized.riskLevel,
         auditEntry: createAuditEntry(normalized, { decision, reason, preset }),
-      };
+      }, normalized);
     }
   }
 
   // Check dangerous shell patterns (always deny)
   const dangerousMatch = matchesDangerousPattern(normalized);
   if (dangerousMatch) {
-    return {
+    return attachExecutionSurface({
       decision: 'deny',
       reason: `Dangerous shell pattern detected: ${dangerousMatch}`,
       preset,
       riskLevel: 'critical',
       auditEntry: createAuditEntry(normalized, { decision: 'deny', reason: `Dangerous shell pattern: ${dangerousMatch}`, preset }),
-    };
+    }, normalized);
   }
 
   // Check secret patterns (always deny)
   const secretMatch = matchesSecretPattern(normalized);
   if (secretMatch) {
-    return {
+    return attachExecutionSurface({
       decision: 'deny',
       reason: `Secret pattern detected in content: ${secretMatch}`,
       preset,
       riskLevel: 'critical',
       auditEntry: createAuditEntry(normalized, { decision: 'deny', reason: `Secret pattern: ${secretMatch}`, preset }),
-    };
+    }, normalized);
   }
 
   // Evaluate against preset
   if (presetConfig.deny.includes(normalized.type)) {
-    return {
+    return attachExecutionSurface({
       decision: 'deny',
       reason: `Action ${normalized.type} denied by ${preset} preset`,
       preset,
       riskLevel: normalized.riskLevel,
       auditEntry: createAuditEntry(normalized, { decision: 'deny', reason: `Denied by preset`, preset }),
-    };
+    }, normalized);
   }
 
   if (presetConfig.requireApproval.includes(normalized.type)) {
-    return {
+    return attachExecutionSurface({
       decision: 'require-approval',
       reason: `Action ${normalized.type} requires approval in ${preset} preset`,
       preset,
       riskLevel: normalized.riskLevel,
       auditEntry: createAuditEntry(normalized, { decision: 'require-approval', reason: `Requires approval`, preset }),
-    };
+    }, normalized);
   }
 
   if (presetConfig.allow.includes(normalized.type)) {
-    return {
+    return attachExecutionSurface({
       decision: 'allow',
       reason: `Action ${normalized.type} allowed by ${preset} preset`,
       preset,
       riskLevel: normalized.riskLevel,
       auditEntry: createAuditEntry(normalized, { decision: 'allow', reason: `Allowed by preset`, preset }),
-    };
+    }, normalized);
   }
 
   // Default: unknown actions require approval
-  return {
+  return attachExecutionSurface({
     decision: 'require-approval',
     reason: `Action ${normalized.type} not in preset; defaulting to require-approval`,
     preset,
     riskLevel: normalized.riskLevel,
     auditEntry: createAuditEntry(normalized, { decision: 'require-approval', reason: `Not in preset`, preset }),
+  }, normalized);
+}
+
+function attachExecutionSurface(result, action) {
+  const executionSurface = buildDockerSandboxPlan({
+    toolName: action.type === 'shell.exec' ? 'Bash' : 'Write',
+    actionType: action.type,
+    command: action.type === 'shell.exec' ? action.target : '',
+    repoPath: action.args.repoPath || action.args.cwd || '',
+    affectedFiles: action.type.startsWith('file.') && action.target ? [action.target] : [],
+    riskBand: toSandboxRiskBand(action.riskLevel),
+    requiresNetwork: ['upload', 'download', 'message.send'].includes(action.type),
+  });
+
+  if (!executionSurface.shouldSandbox) {
+    return result;
+  }
+
+  return {
+    ...result,
+    executionSurface,
   };
 }
 
+function toSandboxRiskBand(riskLevel) {
+  if (riskLevel === 'high') return 'high';
+  if (riskLevel === 'medium') return 'medium';
+  return 'low';
+}
+
 function createAuditEntry(action, decision) {
   return {
     timestamp: action.timestamp || new Date().toISOString(),
@@ -247,4 +275,6 @@ module.exports = {
   loadConfig,
   matchesDangerousPattern,
   matchesSecretPattern,
+  attachExecutionSurface,
+  toSandboxRiskBand,
 };

package/scripts/contextfs.js

@@ -23,9 +23,15 @@ function getFeedbackBaseDir() {
   return resolveFeedbackDir();
 }
 
-const FEEDBACK_DIR = getFeedbackBaseDir();
-const CONTEXTFS_ROOT = process.env.THUMBGATE_CONTEXTFS_DIR
-  || (FEEDBACK_DIR.endsWith('contextfs') ? FEEDBACK_DIR : path.join(FEEDBACK_DIR, 'contextfs'));
+function getContextFsRoot() {
+  const feedbackDir = getFeedbackBaseDir();
+  if (process.env.THUMBGATE_CONTEXTFS_DIR) return process.env.THUMBGATE_CONTEXTFS_DIR;
+  return feedbackDir.endsWith('contextfs') ? feedbackDir : path.join(feedbackDir, 'contextfs');
+}
+
+function contextFsPath(...segments) {
+  return path.join(getContextFsRoot(), ...segments);
+}
 
 const NAMESPACES = {
   rawHistory: 'raw_history',
@@ -101,7 +107,7 @@ function ensureDir(dirPath) {
 
 function ensureContextFs() {
   Object.values(NAMESPACES).forEach((subPath) => {
-    ensureDir(path.join(CONTEXTFS_ROOT, subPath));
+    ensureDir(contextFsPath(subPath));
   });
 }
 
@@ -111,7 +117,7 @@ function nowIso() {
 
 function inferNamespaceFromPath(filePath) {
   if (!filePath) return '';
-  const relativeDir = path.relative(CONTEXTFS_ROOT, path.dirname(filePath));
+  const relativeDir = path.relative(getContextFsRoot(), path.dirname(filePath));
   if (!relativeDir || relativeDir.startsWith('..')) return '';
   return relativeDir;
 }
@@ -211,7 +217,7 @@ function getSemanticCacheConfig() {
 }
 
 function getSemanticCachePath() {
-  return path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'semantic-cache.jsonl');
+  return contextFsPath(NAMESPACES.provenance, 'semantic-cache.jsonl');
 }
 
 function loadSemanticCacheEntries() {
@@ -227,7 +233,7 @@ function getSourceHash(namespaces) {
   const normalizedNamespaces = normalizeNamespaces(namespaces);
 
   for (const ns of normalizedNamespaces) {
-    const dirPath = path.join(CONTEXTFS_ROOT, ns);
+    const dirPath = contextFsPath(ns);
     if (!fs.existsSync(dirPath)) continue;
 
     const files = fs.readdirSync(dirPath).sort();
@@ -291,7 +297,7 @@ function recordProvenance(event) {
     timestamp: nowIso(),
     ...event,
   };
-  appendJsonl(path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'events.jsonl'), payload);
+  appendJsonl(contextFsPath(NAMESPACES.provenance, 'events.jsonl'), payload);
   return payload;
 }
 
@@ -299,7 +305,7 @@ function writeContextObject({ namespace, title, content, tags = [], source, ttl
   ensureContextFs();
 
   const id = `${Date.now()}_${toSlug(title)}`;
-  const filePath = path.join(CONTEXTFS_ROOT, namespace, `${id}.json`);
+  const filePath = contextFsPath(namespace, `${id}.json`);
 
   const doc = {
     id,
@@ -361,7 +367,7 @@ function findExistingContextObject({ namespace, title, content, tags = [], sourc
   ensureContextFs();
 
   const expectedTags = normalizeTagList(tags);
-  const dirPath = path.join(CONTEXTFS_ROOT, namespace);
+  const dirPath = contextFsPath(namespace);
   const files = listJsonFiles(dirPath).sort();
 
   for (const filePath of files) {
@@ -507,7 +513,7 @@ function loadCandidates(namespaces) {
   const docs = [];
 
   selected.forEach((namespace) => {
-    const dir = path.join(CONTEXTFS_ROOT, namespace);
+    const dir = contextFsPath(namespace);
     const files = listJsonFiles(dir);
     files.forEach((filePath) => {
       try {
@@ -624,7 +630,7 @@ function selectFlatContextItems(candidates, maxItems, maxChars) {
 const MEMEX_INDEX_FILE = 'memex-index.jsonl';
 
 function getMemexIndexPath() {
-  return path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, MEMEX_INDEX_FILE);
+  return contextFsPath(NAMESPACES.provenance, MEMEX_INDEX_FILE);
 }
 
 function buildIndexEntry(doc, filePath) {
@@ -751,7 +757,7 @@ function constructMemexPack({ query = '', maxItems = 8, maxChars = 6000, namespa
     cache: { hit: false },
   };
 
-  appendJsonl(path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'packs.jsonl'), pack);
+  appendJsonl(contextFsPath(NAMESPACES.provenance, 'packs.jsonl'), pack);
   recordProvenance({
     type: 'memex_pack_constructed',
     packId,
@@ -792,7 +798,7 @@ function constructContextPack({ query = '', maxItems = 8, maxChars = 6000, names
       },
     };
 
-    appendJsonl(path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'packs.jsonl'), pack);
+    appendJsonl(contextFsPath(NAMESPACES.provenance, 'packs.jsonl'), pack);
     recordProvenance({
       type: 'context_pack_cache_hit',
       packId,
@@ -861,7 +867,7 @@ function constructContextPack({ query = '', maxItems = 8, maxChars = 6000, names
     retrieval: selection.retrieval,
   };
 
-  appendJsonl(path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'packs.jsonl'), pack);
+  appendJsonl(contextFsPath(NAMESPACES.provenance, 'packs.jsonl'), pack);
   appendSemanticCacheEntry({
     id: `cache_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
     timestamp: nowIso(),
@@ -899,7 +905,7 @@ function evaluateContextPack({ packId, outcome, signal = null, notes = '', rubri
     timestamp: nowIso(),
   };
 
-  appendJsonl(path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'evaluations.jsonl'), evaluation);
+  appendJsonl(contextFsPath(NAMESPACES.provenance, 'evaluations.jsonl'), evaluation);
   recordProvenance({
     type: 'context_pack_evaluated',
     packId,
@@ -912,7 +918,7 @@ function evaluateContextPack({ packId, outcome, signal = null, notes = '', rubri
 }
 
 function getProvenance(limit = 50) {
-  const eventsPath = path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'events.jsonl');
+  const eventsPath = contextFsPath(NAMESPACES.provenance, 'events.jsonl');
   const events = readJsonl(eventsPath);
   return events.slice(-limit);
 }
@@ -923,7 +929,7 @@ function getProvenance(limit = 50) {
  * session starts with full context — no manual primer.md needed.
  */
 function writeSessionHandoff({ project, branch, lastTask, nextStep, blockers, openFiles, customContext } = {}) {
-  ensureDir(path.join(CONTEXTFS_ROOT, NAMESPACES.session));
+  ensureDir(contextFsPath(NAMESPACES.session));
 
   let gitContext = {};
   try {
@@ -951,7 +957,7 @@ function writeSessionHandoff({ project, branch, lastTask, nextStep, blockers, op
     customContext: customContext || null,
   };
 
-  const primerPath = path.join(CONTEXTFS_ROOT, NAMESPACES.session, 'primer.json');
+  const primerPath = contextFsPath(NAMESPACES.session, 'primer.json');
   fs.writeFileSync(primerPath, JSON.stringify(primer, null, 2));
 
   // Sync to primer.md if it exists
@@ -991,7 +997,7 @@ function writeSessionHandoff({ project, branch, lastTask, nextStep, blockers, op
  * Read the most recent session handoff primer.
  */
 function readSessionHandoff() {
-  const primerPath = path.join(CONTEXTFS_ROOT, NAMESPACES.session, 'primer.json');
+  const primerPath = contextFsPath(NAMESPACES.session, 'primer.json');
   if (!fs.existsSync(primerPath)) return null;
   try {
     return JSON.parse(fs.readFileSync(primerPath, 'utf8'));
@@ -1192,7 +1198,7 @@ function constructMultiHopPack({ query = '', maxItems = 8, maxChars = 6000, name
     },
   };
 
-  appendJsonl(path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'packs.jsonl'), pack);
+  appendJsonl(contextFsPath(NAMESPACES.provenance, 'packs.jsonl'), pack);
   appendSemanticCacheEntry({
     id: `cache_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
     timestamp: nowIso(),
@@ -1244,7 +1250,10 @@ function listPackTemplates() {
 }
 
 module.exports = {
-  CONTEXTFS_ROOT,
+  get CONTEXTFS_ROOT() {
+    return getContextFsRoot();
+  },
+  getContextFsRoot,
   NAMESPACES,
   ensureContextFs,
   recordProvenance,
@@ -1283,5 +1292,5 @@ module.exports = {
 
 if (require.main === module) {
   ensureContextFs();
-  console.log(`ContextFS ready at ${CONTEXTFS_ROOT}`);
+  console.log(`ContextFS ready at ${getContextFsRoot()}`);
 }