@chemx/create-chemx 26.9.26-253 → 26.9.28-276

package/cli/audit/ast-visitors.js

@@ -23,12 +23,18 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
       const isCustomHook = isCustomHookFunction(astPath);
 
       // Pillar 3: Hook Saturation
+      const CONTROLLER_WRAPPER_EXCLUSIONS = new Set([
+        'useSharedStatusController',
+        'useSharedController',
+        'useController'
+      ]);
       let hookCount = 0;
       astPath.traverse({
         CallExpression(callPath) {
           const callee = callPath.node.callee;
           if (t.isIdentifier(callee) && /^use[A-Z0-9]/.test(callee.name)) {
-            if (callPath.getFunctionParent() === astPath) {
+            const isExcluded = CONTROLLER_WRAPPER_EXCLUSIONS.has(callee.name);
+            if (!isExcluded && callPath.getFunctionParent() === astPath) {
               hookCount += 1;
             }
           }

package/cli/audit/extended-text-patterns.js

@@ -32,7 +32,10 @@ const JAVASCRIPT_URL_TEMPLATE_PATTERN = /\b(?:href|src|action|formaction)\s*=\s*
 /**
  * Pillar 10: Check for co-located test files for molecule capsules.
  */
-export const checkMoleculeCoLocatedTest = (filePath, relativePath, violations) => {
+export const checkMoleculeCoLocatedTest = (filePath, relativePath, violations, config = {}) => {
+  const enforceColocated = config.enforceColocatedTests ?? (config.profile === 'atomic-strict');
+  if (!enforceColocated) return;
+
   const baseName = path.basename(filePath);
   const ext = path.extname(filePath);
 
@@ -194,8 +197,8 @@ export const checkControllerViewContract = (filePath, relativePath, content, vio
   }
 };
 
-export const checkExtendedTextPatterns = (content, lines, relativePath, filePath, violations) => {
-  checkMoleculeCoLocatedTest(filePath, relativePath, violations);
+export const checkExtendedTextPatterns = (content, lines, relativePath, filePath, violations, config = {}) => {
+  checkMoleculeCoLocatedTest(filePath, relativePath, violations, config);
   checkControllerViewContract(filePath, relativePath, content, violations);
 
   const isTestFile = /\.(test|spec)\.[jt]sx?$/.test(filePath)

package/cli/audit/rules-helpers.js

@@ -17,7 +17,13 @@ export const countLogicalOperators = (node) => {
 export const extractParseableCode = (content, ext) => {
   if (ext === '.vue') {
     const scriptMatch = content.match(/<script\b[^>]*>([\s\S]*?)<\/script>/i);
-    return scriptMatch ? scriptMatch[1] : '';
+    if (!scriptMatch) return '';
+    const scriptStartIndex = scriptMatch.index || 0;
+    const preScript = content.slice(0, scriptStartIndex);
+    const openTag = scriptMatch[0].match(/<script\b[^>]*>/i)?.[0] || '';
+    const preContent = preScript + openTag;
+    const leadingNewlines = preContent.split('\n').length - 1;
+    return '\n'.repeat(leadingNewlines) + scriptMatch[1];
   }
   return content;
 };

package/cli/audit/rules.js

@@ -107,7 +107,7 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   checkSlopTextPatterns(content, lines, relativePath, violations);
 
   // Pillars 8-11: Extended Fast Checks (A11y, Security secrets, Fake tests, Co-located specs)
-  checkExtendedTextPatterns(content, lines, relativePath, filePath, violations);
+  checkExtendedTextPatterns(content, lines, relativePath, filePath, violations, config);
 
   const lang = getLanguageForFile(filePath);
   if (lang?.id === 'csharp') {

package/cli/config/loader.js

@@ -25,6 +25,7 @@ const normalizeRuleKeys = (rules = {}) => {
     'max-prop-count': 'maxPropCount',
     'prefer-design-tokens': 'preferDesignTokens',
     'enforce-file-length': 'enforceFileLength',
+    'enforce-colocated-tests': 'enforceColocatedTests',
     'rule-of-three-abstractions': 'ruleOfThreeAbstractions',
     'ai-slop-detection': 'aiSlopDetection',
     'max-line-count-warning': 'maxLineCountWarning'

package/cli/config/profiles.js

@@ -14,6 +14,7 @@ export const PROFILES = {
     maxPropCount: 7,
     preferDesignTokens: 'warning',
     enforceFileLength: false,
+    enforceColocatedTests: false,
     ruleOfThreeAbstractions: true,
     aiSlopDetection: 'critical',
     maxLineCountWarning: 250
@@ -28,6 +29,7 @@ export const PROFILES = {
     maxPropCount: 5,
     preferDesignTokens: 'error',
     enforceFileLength: true,
+    enforceColocatedTests: true,
     ruleOfThreeAbstractions: false,
     aiSlopDetection: 'critical',
     maxLineCountWarning: 100
@@ -42,6 +44,7 @@ export const PROFILES = {
     maxPropCount: 12,
     preferDesignTokens: 'off',
     enforceFileLength: false,
+    enforceColocatedTests: false,
     ruleOfThreeAbstractions: true,
     aiSlopDetection: 'medium',
     maxLineCountWarning: 500

package/cli/friction-fixes.spec.js

@@ -0,0 +1,96 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { handleChemx } from './mcp/tools.js';
+import { auditCode } from './audit/rules.js';
+
+test('Friction 1: team_task add and team task add persist task rows', async () => {
+  const resCmd = await handleChemx({ command: 'team task add CLI Task Test' });
+  assert.ok(resCmd && resCmd.id, 'Expected task object with id from team task add');
+  assert.strictEqual(resCmd.title, 'CLI Task Test');
+
+  const resCmd2 = await handleChemx({ command: 'team_task add Direct SubCmd Task' });
+  assert.ok(resCmd2 && resCmd2.id, 'Expected task object with id from team_task add');
+  assert.strictEqual(resCmd2.title, 'Direct SubCmd Task');
+
+  const resInfer = await handleChemx({ action: 'team_task', params: { title: 'Inferred Add Task' } });
+  assert.ok(resInfer && resInfer.id, 'Expected task object with id when title is given');
+  assert.strictEqual(resInfer.title, 'Inferred Add Task');
+});
+
+test('Friction 2: patch handles all parameter aliases and command strings', async () => {
+  const testFile = path.resolve('test-patch-spec.txt');
+  fs.writeFileSync(testFile, 'line 1\nOLD_STRING\nline 3\n');
+
+  try {
+    await handleChemx({ action: 'patch', params: { path: 'test-patch-spec.txt', target: 'OLD_STRING', replace: 'NEW_STRING_1' } });
+    assert.strictEqual(fs.readFileSync(testFile, 'utf8'), 'line 1\nNEW_STRING_1\nline 3\n');
+
+    await handleChemx({ action: 'patch', params: { path: 'test-patch-spec.txt', search: 'NEW_STRING_1', replacement: 'NEW_STRING_2' } });
+    assert.strictEqual(fs.readFileSync(testFile, 'utf8'), 'line 1\nNEW_STRING_2\nline 3\n');
+
+    await handleChemx({ action: 'patch', params: { path: 'test-patch-spec.txt', targetContent: 'NEW_STRING_2', replacementContent: 'FINAL_STRING' } });
+    assert.strictEqual(fs.readFileSync(testFile, 'utf8'), 'line 1\nFINAL_STRING\nline 3\n');
+  } finally {
+    if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
+  }
+});
+
+test('Friction 3: Vue file AST line numbers match file line numbers exactly', () => {
+  const vueContent = [
+    '<template>',
+    '  <div>',
+    '    <p>Line 3</p>',
+    '    <p>Line 4</p>',
+    '    <p>Line 5</p>',
+    '    <p>Line 6</p>',
+    '    <p>Line 7</p>',
+    '    <p>Line 8</p>',
+    '    <p>Line 9</p>',
+    '    <p>Line 10</p>',
+    '  </div>',
+    '</template>',
+    '',
+    '<script setup lang="ts">',
+    'const cond = a && b && c;',
+    '</script>'
+  ].join('\n');
+
+  const recorded = [];
+  const fakeReg = { record: (type, sig, loc) => recorded.push({ type, sig, loc }) };
+  auditCode(vueContent, 'SampleVue.vue', 'SampleVue.vue', { patternRegistry: fakeReg });
+
+  const condRec = recorded.find((r) => r.type === 'PREDICATE_LOGIC');
+  assert.ok(condRec, 'Expected PREDICATE_LOGIC recorded');
+  assert.strictEqual(condRec.loc.line, 15, 'Expected condition on line 15');
+});
+
+test('Friction 4: HOOK_SATURATION excludes canonical controller return wrappers', () => {
+  const hookCode = [
+    'export function useMyComposable() {',
+    '  const a = useA();',
+    '  const b = useB();',
+    '  const c = useC();',
+    '  const d = useD();',
+    '  const e = useE();',
+    '  return useSharedStatusController({ a, b, c, d, e });',
+    '}'
+  ].join('\n');
+
+  const hookViolations = auditCode(hookCode, 'useMyComposable.ts', 'src/useMyComposable.ts');
+  const hookSat = hookViolations.filter((v) => v.rule === 'HOOK_SATURATION');
+  assert.strictEqual(hookSat.length, 0, 'useSharedStatusController should not trigger HOOK_SATURATION');
+});
+
+test('Friction 5: TEST_MISSING_COLOCATED is gated by profile', () => {
+  const compCode = '<template><button>Click</button></template>';
+
+  const defaultViolations = auditCode(compCode, 'src/components/molecules/m-button.vue', 'src/components/molecules/m-button.vue', { config: { profile: 'pragmatic' } });
+  const testMissingDefault = defaultViolations.filter((v) => v.rule === 'TEST_MISSING_COLOCATED');
+  assert.strictEqual(testMissingDefault.length, 0, 'Pragmatic profile should not flag TEST_MISSING_COLOCATED');
+
+  const strictViolations = auditCode(compCode, 'src/components/molecules/m-button.vue', 'src/components/molecules/m-button.vue', { config: { profile: 'atomic-strict' } });
+  const testMissingStrict = strictViolations.filter((v) => v.rule === 'TEST_MISSING_COLOCATED');
+  assert.strictEqual(testMissingStrict.length, 1, 'Atomic-strict profile should flag TEST_MISSING_COLOCATED');
+});

package/cli/mcp/manifests.js

@@ -303,10 +303,15 @@ export const SUB_TOOLS = [
       properties: {
         path: { type: 'string', description: 'Target file path' },
         targetContent: { type: 'string', description: 'Exact string chunk to replace' },
+        target: { type: 'string', description: 'Alias for target text chunk to replace' },
+        search: { type: 'string', description: 'Alias for target text chunk to replace' },
         replacementContent: { type: 'string', description: 'New replacement content' },
-        allowMultiple: { type: 'boolean', description: 'Allow multiple replacements' }
+        replacement: { type: 'string', description: 'Alias for replacement content' },
+        replace: { type: 'string', description: 'Alias for replacement content' },
+        allowMultiple: { type: 'boolean', description: 'Allow multiple replacements' },
+        multiple: { type: 'boolean', description: 'Alias for allowMultiple' }
       },
-      required: ['path', 'targetContent', 'replacementContent']
+      required: ['path']
     }
   },
   {

package/cli/mcp/tools-patch.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { syncSingleFileIndex } from '../search.js';
 import { patchFile } from '../patcher.js';
 import { handleCheckCommand } from '../search-commands.js';
+import { resolveSafePath } from '../path-scope.js';
 
 export const isSevereViolation = (v) => {
   const isCritical = v.severity === 'CRITICAL';
@@ -36,10 +37,10 @@ export const handleChemxPatch = (args = {}, cwd = process.cwd()) => {
   const hasRequiredArgs = hasPath && hasTargetContent && hasReplacementContent;
 
   if (!hasRequiredArgs) {
-    throw new Error('chemx_patch requires "path", "targetContent", and "replacementContent" arguments.');
+    throw new Error('chemx_patch requires "path", target content ("targetContent", "target", or "search"), and replacement content ("replacementContent", "replacement", or "replace").');
   }
 
-  const targetPath = path.isAbsolute(args.path) ? args.path : path.resolve(cwd, args.path);
+  const targetPath = resolveSafePath(args.path, cwd);
   const result = patchFile(targetPath, {
     targetContent,
     replacementContent,
@@ -69,6 +70,6 @@ export const handleChemxCheck = (args = {}, cwd = process.cwd()) => {
   if (!args.path) {
     throw new Error('chemx_check requires "path" argument.');
   }
-  const targetPath = path.isAbsolute(args.path) ? args.path : path.resolve(cwd, args.path);
+  const targetPath = resolveSafePath(args.path, cwd);
   return handleCheckCommand(targetPath, { isJson: true, isCli: false });
 };

package/cli/mcp/tools-read.js

@@ -6,6 +6,7 @@ import {
 } from '../search-queries.js';
 import { findSimilarSymbols } from '../search-queries-similar.js';
 import { readTokenOptimized } from '../reader.js';
+import { resolveSafePath } from '../path-scope.js';
 import { EXT_LANG_MAP, resolveTargetCwd } from './tools-search-util.js';
 
 const buildConnectionCard = (db, symbol, targetPath) => {
@@ -72,8 +73,9 @@ export const handleChemxRead = (args = {}, cwd = process.cwd()) => {
     if (endLine === undefined && colonMatch[3]) endLine = parseInt(colonMatch[3], 10);
   }
 
-  const targetPath = path.isAbsolute(rawPath) ? rawPath : path.resolve(targetCwd, rawPath);
+  const targetPath = resolveSafePath(rawPath, targetCwd);
   const res = readTokenOptimized(targetPath, {
+    cwd: targetCwd,
     outline: args.outline,
     logic: args.logic,
     template: args.template,

package/cli/mcp/tools-team-locks.js

@@ -6,23 +6,30 @@ import {
   getFileLockStatus
 } from '../team/team-db.js';
 import { handleError } from '../errors/index.js';
+import { isPathTraversal } from '../path-scope.js';
 
 export const handleChemxTeamLock = async (args = {}, cwd = process.cwd()) => {
   const db = openIndexDb(cwd);
   if (!db) return { error: 'sqlite_unavailable' };
   const action = args.action || 'status';
 
+  if (args.filePath && isPathTraversal(args.filePath, cwd)) {
+    return { error: 'path_traversal' };
+  }
+
   if (action === 'acquire') {
     return requestFileLock(db, args.filePath, args.agentId, {
       purpose: args.purpose,
-      ttlMs: args.ttlMs
+      ttlMs: args.ttlMs,
+      cwd
     });
   }
   if (action === 'release') {
-    return releaseFileLock(db, args.filePath, args.agentId);
+    return releaseFileLock(db, args.filePath, args.agentId, { cwd });
   }
   if (action === 'status') {
-    const status = getFileLockStatus(db, args.filePath);
+    const status = getFileLockStatus(db, args.filePath, { cwd });
+    if (!status) return null;
     return {
       lease: status.lease,
       waiters: toColumnar(status.waiters, ['id', 'agent_id', 'priority', 'status', 'requested_at'])

package/cli/mcp/tools-team-tasks.js

@@ -12,7 +12,10 @@ import { freezeReleaseTrain } from '../team/team-release-train.js';
 export const handleChemxTeamTask = async (args = {}, cwd = process.cwd()) => {
   const db = openIndexDb(cwd);
   if (!db) return { error: 'sqlite_unavailable' };
-  const action = args.action || args.subAction || 'list';
+  let action = args.action || args.subAction;
+  if (!action) {
+    action = Boolean(args.title) ? 'add' : 'list';
+  }
 
   if (action === 'list') {
     const parentId = args.parentId !== undefined ? args.parentId : args.parent;
@@ -53,7 +56,7 @@ export const handleChemxTeamTask = async (args = {}, cwd = process.cwd()) => {
     const parentId = args.parentId !== undefined ? args.parentId : args.parent;
     const task = createTask(db, {
       title: args.title,
-      target_path: args.targetPath,
+      target_path: args.targetPath || args.target,
       tier: args.tier || 'molecule',
       priority: args.priority || 2,
       assigned_agent_id: args.assignedAgentId || null,

package/cli/mcp/tools-write.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { syncSingleFileIndex } from '../search.js';
 import { writeFile } from '../patcher.js';
 import { formatPatchWarnings } from './tools-patch.js';
+import { resolveSafePath } from '../path-scope.js';
 
 export const handleChemxWrite = (args = {}, cwd = process.cwd()) => {
   const hasPath = Boolean(args.path);
@@ -12,7 +13,7 @@ export const handleChemxWrite = (args = {}, cwd = process.cwd()) => {
     throw new Error('chemx_write requires "path" and "content" arguments.');
   }
 
-  const targetPath = path.isAbsolute(args.path) ? args.path : path.resolve(cwd, args.path);
+  const targetPath = resolveSafePath(args.path, cwd);
   const result = writeFile(targetPath, {
     content: args.content,
     cwd

package/cli/mcp/tools.js

@@ -76,10 +76,53 @@ const parseCommand = (command, params) => {
       }
     };
   }
+  if (subCmd === 'patch') {
+    return {
+      action: 'patch',
+      params: {
+        path: parts[1] || params?.path,
+        target: params?.target || params?.targetContent || params?.search,
+        replacement: params?.replacement || params?.replacementContent || params?.replace,
+        ...params
+      }
+    };
+  }
   if (subCmd === 'q' || subCmd === 'search') return { action: 'q', params: { query: parts.slice(1).join(' '), ...params } };
   if (subCmd === 'team') {
     const TEAM_ACTIONS = { status: 'team_status', feed: 'team_feed', task: 'team_task', lock: 'team_lock', inbox: 'team_inbox', dm: 'team_dm' };
-    return { action: TEAM_ACTIONS[parts[1] || 'status'] || 'team_task', params };
+    const sub = parts[1] || 'status';
+    const action = TEAM_ACTIONS[sub] || 'team_task';
+    const parsedParams = { ...params };
+    const isTaskSub = sub === 'task' || !TEAM_ACTIONS[parts[1]];
+    if (isTaskSub) {
+      const taskSub = TEAM_ACTIONS[parts[1]] ? parts[2] : parts[1];
+      const isCreate = ['add', 'create', 'new'].includes(taskSub);
+      if (isCreate) {
+        parsedParams.subAction = 'add';
+        const titleTokens = parts.slice(TEAM_ACTIONS[parts[1]] ? 3 : 2);
+        if (titleTokens.length > 0 && !parsedParams.title) {
+          parsedParams.title = titleTokens.join(' ').replace(/^["']|["']$/g, '');
+        }
+      } else if (taskSub) {
+        parsedParams.subAction = taskSub;
+      }
+    }
+    return { action, params: parsedParams };
+  }
+  if (subCmd === 'team_task') {
+    const parsedParams = { ...params };
+    const taskSub = parts[1];
+    const isCreate = ['add', 'create', 'new'].includes(taskSub);
+    if (isCreate) {
+      parsedParams.subAction = 'add';
+      const titleTokens = parts.slice(2);
+      if (titleTokens.length > 0 && !parsedParams.title) {
+        parsedParams.title = titleTokens.join(' ').replace(/^["']|["']$/g, '');
+      }
+    } else if (taskSub) {
+      parsedParams.subAction = taskSub;
+    }
+    return { action: 'team_task', params: parsedParams };
   }
   if (subCmd === 'project' || subCmd === 'coordinator') {
     const subAction = parts[1] || 'status';

package/cli/patcher.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { ANSI } from './theme.js';
 import { syncSingleFileIndex } from './search.js';
 import { auditFile } from './audit.js';
+import { resolveSafePath } from './path-scope.js';
 
 /**
  * Surgically applies a search-and-replace block to a file.
@@ -37,7 +38,7 @@ export const patchFile = (targetPath, params = {}) => {
     throw new Error('replacementContent is required for patching');
   }
 
-  const resolvedPath = path.resolve(cwd, targetPath);
+  const resolvedPath = resolveSafePath(targetPath, cwd);
   if (!fs.existsSync(resolvedPath)) {
     throw new Error(`File not found: ${targetPath}`);
   }
@@ -253,7 +254,7 @@ export const writeFile = (targetPath, params = {}) => {
     throw new Error('content is required for writeFile');
   }
 
-  const resolvedPath = path.resolve(cwd, targetPath);
+  const resolvedPath = resolveSafePath(targetPath, cwd);
   const dir = path.dirname(resolvedPath);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });

package/cli/path-scope.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Resolves a target path against a base directory and ensures it does not escape the boundary.
+ *
+ * @param {string} targetPath File or directory path to validate.
+ * @param {string} [baseDir=process.cwd()] Allowed root boundary directory.
+ * @returns {string} Fully resolved, validated path within baseDir.
+ * @throws {Error} If path contains null bytes, attempts traversal, or escapes baseDir.
+ */
+export const resolveSafePath = (targetPath, baseDir = process.cwd()) => {
+  if (!targetPath || typeof targetPath !== 'string') {
+    throw new Error('A valid file path string is required.');
+  }
+
+  if (targetPath.includes('\0')) {
+    throw new Error('Null byte detected in path.');
+  }
+
+  const realBase = fs.existsSync(baseDir) ? fs.realpathSync(baseDir) : path.resolve(baseDir);
+  const resolvedTarget = path.isAbsolute(targetPath)
+    ? path.resolve(targetPath)
+    : path.resolve(realBase, targetPath);
+
+  const relLexical = path.relative(realBase, resolvedTarget);
+  const isLexicalEscape = relLexical.startsWith('..') || path.isAbsolute(relLexical);
+
+  if (isLexicalEscape) {
+    throw new Error(`Path traversal rejected: "${targetPath}" is outside allowed workspace root "${realBase}".`);
+  }
+
+  if (fs.existsSync(resolvedTarget)) {
+    const realTarget = fs.realpathSync(resolvedTarget);
+    const relReal = path.relative(realBase, realTarget);
+    const isSymlinkEscape = relReal.startsWith('..') || path.isAbsolute(relReal);
+    if (isSymlinkEscape) {
+      throw new Error(`Path traversal rejected: "${targetPath}" resolves outside allowed workspace root via symlink.`);
+    }
+    return realTarget;
+  }
+
+  return resolvedTarget;
+};
+
+/**
+ * Checks whether a target path attempts traversal or escapes the boundary.
+ *
+ * @param {string} targetPath Path to inspect.
+ * @param {string} [baseDir=process.cwd()] Boundary directory.
+ * @returns {boolean} True if the path escapes baseDir or is invalid, false otherwise.
+ */
+export const isPathTraversal = (targetPath, baseDir = process.cwd()) => {
+  try {
+    const resolved = resolveSafePath(targetPath, baseDir);
+    const realBase = fs.existsSync(baseDir) ? fs.realpathSync(baseDir) : path.resolve(baseDir);
+    const rel = path.relative(realBase, resolved);
+    if (rel === '') return true;
+    return false;
+  } catch {
+    return true;
+  }
+};

package/cli/path-traversal.spec.js

@@ -0,0 +1,242 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { DatabaseSync } from 'node:sqlite';
+
+import { resolveSafePath, isPathTraversal } from './path-scope.js';
+import { readTokenOptimized } from './reader.js';
+import { handleChemxRead } from './mcp/tools-read.js';
+import { patchFile, writeFile } from './patcher.js';
+import { handleChemxPatch } from './mcp/tools-patch.js';
+import { handleChemxWrite } from './mcp/tools-write.js';
+import { requestFileLock, releaseFileLock, getFileLockStatus } from './team/team-db-locks.js';
+import { handleChemxTeamLock } from './mcp/tools-team-locks.js';
+import { handleLockCommand, handleUnlockCommand } from './team/team-commands-lock.js';
+import { initTeamSchema } from './team/team-schema.js';
+
+test('path-scope: resolveSafePath allows legitimate workspace paths', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-scope-test-'));
+  const testFile = path.join(tmpDir, 'src', 'index.js');
+  fs.mkdirSync(path.dirname(testFile), { recursive: true });
+  fs.writeFileSync(testFile, 'export const x = 1;', 'utf-8');
+
+  try {
+    const relResolved = resolveSafePath('src/index.js', tmpDir);
+    assert.strictEqual(relResolved, testFile);
+
+    const absResolved = resolveSafePath(testFile, tmpDir);
+    assert.strictEqual(absResolved, testFile);
+
+    assert.strictEqual(isPathTraversal('src/index.js', tmpDir), false);
+    assert.strictEqual(isPathTraversal(testFile, tmpDir), false);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('path-scope: resolveSafePath and isPathTraversal reject traversal attacks', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-scope-attack-'));
+
+  try {
+    assert.throws(
+      () => resolveSafePath('../../../etc/passwd', tmpDir),
+      /Path traversal rejected/
+    );
+    assert.throws(
+      () => resolveSafePath('/etc/passwd', tmpDir),
+      /Path traversal rejected/
+    );
+    assert.throws(
+      () => resolveSafePath('foo\0bar.js', tmpDir),
+      /Null byte detected/
+    );
+
+    assert.strictEqual(isPathTraversal('../../../etc/passwd', tmpDir), true);
+    assert.strictEqual(isPathTraversal('/etc/passwd', tmpDir), true);
+    assert.strictEqual(isPathTraversal('.', tmpDir), true);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('path-scope: rejects symlink escapes targeting outside workspace', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-symlink-root-'));
+  const outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-symlink-outside-'));
+  const outsideFile = path.join(outsideDir, 'secret.txt');
+  fs.writeFileSync(outsideFile, 'secret-data', 'utf-8');
+
+  const symlinkPath = path.join(tmpDir, 'symlink-secret.txt');
+  try {
+    fs.symlinkSync(outsideFile, symlinkPath);
+    assert.throws(
+      () => resolveSafePath('symlink-secret.txt', tmpDir),
+      /Path traversal rejected/
+    );
+    assert.strictEqual(isPathTraversal('symlink-secret.txt', tmpDir), true);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(outsideDir, { recursive: true, force: true });
+  }
+});
+
+test('reader: readTokenOptimized and handleChemxRead block path traversal', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-reader-sec-'));
+  const legitimateFile = path.join(tmpDir, 'legit.ts');
+  fs.writeFileSync(legitimateFile, 'export const safe = true;\n', 'utf-8');
+
+  try {
+    const safeRes = readTokenOptimized('legit.ts', { cwd: tmpDir });
+    assert.ok(safeRes.content.includes('export const safe = true;'));
+
+    assert.throws(
+      () => readTokenOptimized('../../../etc/passwd', { cwd: tmpDir }),
+      /Path traversal rejected/
+    );
+    assert.throws(
+      () => readTokenOptimized('/etc/passwd', { cwd: tmpDir }),
+      /Path traversal rejected/
+    );
+
+    assert.throws(
+      () => handleChemxRead({ path: '../../../etc/passwd', cwd: tmpDir }, tmpDir),
+      /Path traversal rejected/
+    );
+    assert.throws(
+      () => handleChemxRead({ path: '/etc/passwd', cwd: tmpDir }, tmpDir),
+      /Path traversal rejected/
+    );
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('patcher: patchFile, writeFile, and MCP tools block path traversal', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-patcher-sec-'));
+  const legitimateFile = path.join(tmpDir, 'legit.ts');
+  fs.writeFileSync(legitimateFile, 'export const val = 1;\n', 'utf-8');
+
+  try {
+    const patchRes = patchFile('legit.ts', {
+      targetContent: 'val = 1;',
+      replacementContent: 'val = 2;',
+      cwd: tmpDir,
+      skipIndex: true
+    });
+    assert.strictEqual(patchRes.status, 'ok');
+
+    assert.throws(
+      () => patchFile('../../../etc/passwd', {
+        targetContent: 'root',
+        replacementContent: 'hacked',
+        cwd: tmpDir,
+        skipIndex: true
+      }),
+      /Path traversal rejected/
+    );
+    assert.throws(
+      () => patchFile('/etc/passwd', {
+        targetContent: 'root',
+        replacementContent: 'hacked',
+        cwd: tmpDir,
+        skipIndex: true
+      }),
+      /Path traversal rejected/
+    );
+
+    assert.throws(
+      () => writeFile('../../../etc/evil.txt', {
+        content: 'exploit',
+        cwd: tmpDir,
+        skipIndex: true
+      }),
+      /Path traversal rejected/
+    );
+    assert.throws(
+      () => writeFile('/tmp/evil-outside.txt', {
+        content: 'exploit',
+        cwd: tmpDir,
+        skipIndex: true
+      }),
+      /Path traversal rejected/
+    );
+
+    assert.throws(
+      () => handleChemxPatch({
+        path: '../../../etc/passwd',
+        targetContent: 'a',
+        replacementContent: 'b'
+      }, tmpDir),
+      /Path traversal rejected/
+    );
+
+    assert.throws(
+      () => handleChemxWrite({
+        path: '../../../etc/passwd',
+        content: 'malicious'
+      }, tmpDir),
+      /Path traversal rejected/
+    );
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('team lock: requestFileLock, releaseFileLock, and getFileLockStatus block path traversal', () => {
+  const db = new DatabaseSync(':memory:');
+  db.exec('PRAGMA foreign_keys = ON;');
+  initTeamSchema(db);
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-team-sec-'));
+
+  try {
+    const safeLock = requestFileLock(db, 'src/button.vue', '@agent-1', { cwd: tmpDir });
+    assert.strictEqual(safeLock.granted, true);
+    assert.strictEqual(safeLock.lease.file_path, 'src/button.vue');
+
+    const safeStatus = getFileLockStatus(db, 'src/button.vue', { cwd: tmpDir });
+    assert.strictEqual(safeStatus.lease.locked_by, '@agent-1');
+
+    const safeUnlock = releaseFileLock(db, 'src/button.vue', '@agent-1', { cwd: tmpDir });
+    assert.strictEqual(safeUnlock.success, true);
+
+    const badLock1 = requestFileLock(db, '../../../etc/passwd', '@attacker', { cwd: tmpDir });
+    assert.strictEqual(badLock1.granted, false);
+    assert.strictEqual(badLock1.reason, 'path_traversal');
+
+    const badLock2 = requestFileLock(db, '/etc/passwd', '@attacker', { cwd: tmpDir });
+    assert.strictEqual(badLock2.granted, false);
+    assert.strictEqual(badLock2.reason, 'path_traversal');
+
+    const badUnlock = releaseFileLock(db, '../../../etc/passwd', '@attacker', { cwd: tmpDir });
+    assert.strictEqual(badUnlock.success, false);
+    assert.strictEqual(badUnlock.reason, 'path_traversal');
+
+    const badStatus = getFileLockStatus(db, '../../../etc/passwd', { cwd: tmpDir });
+    assert.strictEqual(badStatus.error, 'path_traversal');
+
+    const cliLockRes = handleLockCommand(db, ['acquire', '../../../etc/passwd'], {}, false, tmpDir);
+    assert.strictEqual(cliLockRes.error, 'path_traversal');
+
+    const cliUnlockRes = handleUnlockCommand(db, ['../../../etc/passwd'], {}, false, tmpDir);
+    assert.strictEqual(cliUnlockRes.error, 'path_traversal');
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('team lock: handleChemxTeamLock MCP handler rejects path traversal', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-mcp-lock-sec-'));
+  try {
+    const res = await handleChemxTeamLock({
+      action: 'acquire',
+      filePath: '../../../etc/passwd',
+      agentId: '@attacker'
+    }, tmpDir);
+
+    assert.strictEqual(res.error, 'path_traversal');
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});

package/cli/reader.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { parse } from '@babel/parser';
 import traverseModule from '@babel/traverse';
 import { ANSI } from './theme.js';
+import { resolveSafePath } from './path-scope.js';
 
 import {
   stripCodeComments,
@@ -214,7 +215,8 @@ export const readTokenOptimized = (targetPath, options = {}) => {
     if (endLine === undefined && colonMatch[3]) endLine = parseInt(colonMatch[3], 10);
   }
 
-  const resolvedPath = path.resolve(process.cwd(), rawPath);
+  const cwd = options.cwd || process.cwd();
+  const resolvedPath = resolveSafePath(rawPath, cwd);
 
   if (!fs.existsSync(resolvedPath)) {
     throw new Error(`File not found: ${rawPath}`);

package/cli/team/team-commands-lock.js

@@ -1,7 +1,8 @@
 import { requestFileLock, releaseFileLock } from './team-db.js';
 import { formatLockHelpCard } from './team-format.js';
+import { isPathTraversal } from '../path-scope.js';
 
-export const handleLockCommand = (db, nonFlagPositional, flags, isCli) => {
+export const handleLockCommand = (db, nonFlagPositional, flags, isCli, cwd = process.cwd()) => {
   const isLockHelp = flags.help || nonFlagPositional.includes('--help') || nonFlagPositional.includes('-h') || nonFlagPositional.includes('help');
   if (isLockHelp) {
     if (isCli) process.stdout.write(formatLockHelpCard());
@@ -24,13 +25,19 @@ export const handleLockCommand = (db, nonFlagPositional, flags, isCli) => {
   }
 
   if (action === 'release') {
-    return handleUnlockCommand(db, [file], flags, isCli);
+    return handleUnlockCommand(db, [file], flags, isCli, cwd);
+  }
+
+  if (isPathTraversal(file, cwd)) {
+    if (isCli) process.stderr.write('\x1b[31m✕ Path traversal rejected: file path must be within workspace\x1b[0m\n');
+    return { error: 'path_traversal' };
   }
 
   const res = requestFileLock(db, file, flags.as || '@agent', {
     purpose: flags.purpose,
     priority: flags.priority,
-    pid: flags.pid ? Number(flags.pid) : 0
+    pid: flags.pid ? Number(flags.pid) : 0,
+    cwd
   });
 
   if (isCli) {
@@ -41,7 +48,7 @@ export const handleLockCommand = (db, nonFlagPositional, flags, isCli) => {
   return res;
 };
 
-export const handleUnlockCommand = (db, nonFlagPositional, flags, isCli) => {
+export const handleUnlockCommand = (db, nonFlagPositional, flags, isCli, cwd = process.cwd()) => {
   const isUnlockHelp = flags.help || nonFlagPositional.includes('--help') || nonFlagPositional.includes('-h') || nonFlagPositional.includes('help');
   if (isUnlockHelp) {
     if (isCli) process.stdout.write(formatLockHelpCard());
@@ -54,7 +61,12 @@ export const handleUnlockCommand = (db, nonFlagPositional, flags, isCli) => {
     return { error: 'filePath required' };
   }
 
-  const res = releaseFileLock(db, file, flags.as || '@agent');
+  if (isPathTraversal(file, cwd)) {
+    if (isCli) process.stderr.write('\x1b[31m✕ Path traversal rejected: file path must be within workspace\x1b[0m\n');
+    return { error: 'path_traversal' };
+  }
+
+  const res = releaseFileLock(db, file, flags.as || '@agent', { cwd });
   if (isCli) {
     if (flags.isJson) process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
     else if (res.success) process.stdout.write(`\x1b[32m✔\x1b[0m Released lock on ${file}\n`);

package/cli/team/team-commands.js

@@ -396,11 +396,11 @@ export const runTeamCli = (rawArgs = [], isCli = false, cwd = process.cwd()) =>
   }
 
   if (subCommand === 'lock') {
-    return handleLockCommand(db, nonFlagPositional, flags, isCli);
+    return handleLockCommand(db, nonFlagPositional, flags, isCli, cwd);
   }
 
   if (subCommand === 'unlock') {
-    return handleUnlockCommand(db, nonFlagPositional, flags, isCli);
+    return handleUnlockCommand(db, nonFlagPositional, flags, isCli, cwd);
   }
 
   if (subCommand === 'triage') {

package/cli/team/team-db-locks.js

@@ -3,12 +3,29 @@
  * Prevents race collisions with deterministic queueing and reactive promotion
  */
 
+import path from 'node:path';
+import { isPathTraversal, resolveSafePath } from '../path-scope.js';
 import { postFeedEvent } from './team-db-feed.js';
 import { DEFAULT_TTL_MS, cleanExpiredLeases, promoteNextWaiter, enqueueWaiter } from './team-db-lock-promotion.js';
 import { withImmediateTransaction } from './team-db-transaction.js';
 
 export { cleanExpiredLeases, promoteNextWaiter } from './team-db-lock-promotion.js';
 
+const resolveBaseDir = (db, options = {}) => {
+  if (options.cwd) return options.cwd;
+  try {
+    if (typeof db?.location === 'function') {
+      const loc = db.location();
+      if (loc && loc !== ':memory:' && loc.includes('.chemx')) {
+        return path.dirname(path.dirname(path.resolve(loc)));
+      }
+    }
+  } catch {
+    // fallback
+  }
+  return process.cwd();
+};
+
 const normalizeAgentId = (id) => {
   const hasId = Boolean(id);
   if (!hasId) return null;
@@ -23,13 +40,19 @@ export const requestFileLock = (db, filePath, agentId, options = {}) => {
   const canRequest = hasDb && hasPath && hasAgent;
   if (!canRequest) return { granted: false, reason: 'missing_args' };
 
+  const baseDir = resolveBaseDir(db, options);
+  if (isPathTraversal(filePath, baseDir)) {
+    return { granted: false, reason: 'path_traversal' };
+  }
+  const cleanPath = path.relative(baseDir, resolveSafePath(filePath, baseDir));
+
   const cleanId = normalizeAgentId(agentId);
   const pid = typeof options.pid === 'number' ? options.pid : 0;
 
   return withImmediateTransaction(db, () => {
     cleanExpiredLeases(db);
 
-    const existingLease = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(filePath);
+    const existingLease = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(cleanPath);
     const now = Date.now();
     const ttlMs = options.ttlMs || DEFAULT_TTL_MS;
     const expiresAt = now + ttlMs;
@@ -43,63 +66,75 @@ export const requestFileLock = (db, filePath, agentId, options = {}) => {
           expires_at = excluded.expires_at,
           purpose = excluded.purpose,
           pid = excluded.pid`;
-      db.prepare(upsertSql).run(filePath, cleanId, now, expiresAt, purpose, pid);
+      db.prepare(upsertSql).run(cleanPath, cleanId, now, expiresAt, purpose, pid);
 
       postFeedEvent(db, {
         author_id: cleanId,
         event_type: 'lock_acquired',
-        file_path: filePath,
-        message: `${cleanId} acquired lock on ${filePath}`
+        file_path: cleanPath,
+        message: `${cleanId} acquired lock on ${cleanPath}`
       });
 
-      return { granted: true, lease: { file_path: filePath, locked_by: cleanId, expires_at: expiresAt, pid } };
+      return { granted: true, lease: { file_path: cleanPath, locked_by: cleanId, expires_at: expiresAt, pid } };
     }
 
-    return enqueueWaiter(db, filePath, cleanId, existingLease, options, now);
+    return enqueueWaiter(db, cleanPath, cleanId, existingLease, options, now);
   });
 };
 
-export const releaseFileLock = (db, filePath, agentId) => {
+export const releaseFileLock = (db, filePath, agentId, options = {}) => {
   const hasDb = Boolean(db);
   const hasPath = Boolean(filePath);
   const hasAgent = Boolean(agentId);
   const canRelease = hasDb && hasPath && hasAgent;
   if (!canRelease) return { success: false, reason: 'missing_args' };
 
+  const baseDir = resolveBaseDir(db, options);
+  if (isPathTraversal(filePath, baseDir)) {
+    return { success: false, reason: 'path_traversal' };
+  }
+  const cleanPath = path.relative(baseDir, resolveSafePath(filePath, baseDir));
+
   const cleanId = normalizeAgentId(agentId);
 
   return withImmediateTransaction(db, () => {
     cleanExpiredLeases(db);
 
-    const existingLease = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(filePath);
+    const existingLease = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(cleanPath);
     const isHolder = Boolean(existingLease) && existingLease.locked_by === cleanId;
     if (!isHolder) {
       return { success: false, reason: 'not_holder' };
     }
 
-    db.prepare('DELETE FROM file_leases WHERE file_path = ?').run(filePath);
+    db.prepare('DELETE FROM file_leases WHERE file_path = ?').run(cleanPath);
     postFeedEvent(db, {
       author_id: cleanId,
       event_type: 'lock_released',
-      file_path: filePath,
-      message: `${cleanId} released lock on ${filePath}`
+      file_path: cleanPath,
+      message: `${cleanId} released lock on ${cleanPath}`
     });
 
-    const next = promoteNextWaiter(db, filePath);
+    const next = promoteNextWaiter(db, cleanPath);
     const promotedWaiter = next ? next.waiter.agent_id : null;
     return { success: true, promotedWaiter };
   });
 };
 
-export const getFileLockStatus = (db, filePath) => {
+export const getFileLockStatus = (db, filePath, options = {}) => {
   const hasDb = Boolean(db);
   const hasPath = Boolean(filePath);
   const canGet = hasDb && hasPath;
   if (!canGet) return null;
 
+  const baseDir = resolveBaseDir(db, options);
+  if (isPathTraversal(filePath, baseDir)) {
+    return { lease: null, waiters: [], error: 'path_traversal' };
+  }
+  const cleanPath = path.relative(baseDir, resolveSafePath(filePath, baseDir));
+
   cleanExpiredLeases(db);
-  const lease = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(filePath);
+  const lease = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(cleanPath);
   const query = "SELECT * FROM file_lock_queue WHERE file_path = ? AND status = 'waiting' ORDER BY priority ASC, id ASC";
-  const waiters = db.prepare(query).all(filePath);
+  const waiters = db.prepare(query).all(cleanPath);
   return { lease: lease || null, waiters };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemx/create-chemx",
-  "version": "26.9.26-253",
+  "version": "26.9.28-276",
   "description": "Chemical X Protocol: Private drop-in architecture starter kit and capsule generator",
   "type": "module",
   "bin": {