harness-everything 0.3.6 → 0.4.0

package/plugins/harness-everything/hooks/scripts/lib/platforms/copilot.js

@@ -0,0 +1,85 @@
+const path = require('path');
+const fs = require('fs');
+
+// Copilot's own skills location (.github/skills/) is unchanged - it already
+// has an established home. Only bookkeeping that never had a home (runtime
+// state, install manifest) converges into .github/harness-everything/.
+module.exports = {
+  name: 'copilot',
+  label: 'GitHub Copilot',
+  getHarnessDir(workspaceRoot) { return path.join(workspaceRoot, '.github', 'harness-everything'); },
+  getStateDir(workspaceRoot) { return path.join(this.getHarnessDir(workspaceRoot), 'state'); },
+  getSkillsDir(workspaceRoot) { return path.join(workspaceRoot, '.github', 'skills'); },
+  getIgnorePatterns(workspaceRoot) {
+    const patterns = ['.github/harness-everything/'];
+    const skillsDir = path.join(workspaceRoot, '.github', 'skills');
+    if (fs.existsSync(skillsDir)) {
+      try {
+        for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+          if (!entry.isDirectory()) continue;
+          const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md');
+          if (!fs.existsSync(skillMdPath)) continue;
+          const content = fs.readFileSync(skillMdPath, 'utf8');
+          const authorLine = content.split('\n').find(line => line.trim().startsWith('author:'));
+          if (authorLine && authorLine.includes('Miya Daniel')) patterns.push(`.github/skills/${entry.name}/`);
+        }
+      } catch (e) {
+        // Fallback or ignore to prevent breaking execution
+      }
+    }
+    return patterns;
+  },
+  isMatch(pattern, trimmedLine) {
+    if (trimmedLine === '.github/' || trimmedLine === '.github') return true;
+    if (pattern === '.github/harness-everything/') {
+      return trimmedLine === '.github/harness-everything' || trimmedLine === '.github/harness-everything/';
+    }
+    return trimmedLine === pattern || trimmedLine === pattern.slice(0, -1);
+  },
+  isInstalled(workspaceRoot, userHome, isGlobal) {
+    if (isGlobal) return false;
+    return fs.existsSync(path.join(workspaceRoot, '.github', 'copilot-instructions.md'));
+  },
+  getSkillsTarget({ workspaceRoot, userHome, isGlobal, manifest }) {
+    if (isGlobal) {
+      const globalAgentsDir = path.join(userHome, '.agents');
+      return {
+        path: path.join(globalAgentsDir, 'skills'),
+        label: '~/.agents/skills/',
+        manifestPath: manifest.getManifestPath(globalAgentsDir),
+      };
+    }
+    const githubDir = path.join(workspaceRoot, '.github');
+    return {
+      path: path.join(githubDir, 'skills'),
+      label: '.github/skills/',
+      manifestPath: manifest.getManifestPath(githubDir),
+    };
+  },
+  install({ isGlobal, targetWorkspaceRoot, getUserPromptsDir, advisory }) {
+    if (!isGlobal) {
+      const targetFile = path.join(targetWorkspaceRoot, '.github', 'copilot-instructions.md');
+      advisory.injectAdvisoryText(targetFile, '# Copilot Instructions', '.github/copilot-instructions.md');
+      return;
+    }
+    const promptsDir = getUserPromptsDir();
+    if (!fs.existsSync(promptsDir)) fs.mkdirSync(promptsDir, { recursive: true });
+    const vscodeInstFile = path.join(promptsDir, 'harness.instructions.md');
+    advisory.assertHarnessOwnedOrAbsent(vscodeInstFile, 'global Copilot instructions');
+    fs.writeFileSync(vscodeInstFile, advisory.buildCopilotGlobalContent(), 'utf8');
+    console.log(`  ✅ Installed global Copilot instructions to VS Code: ${vscodeInstFile}`);
+  },
+  uninstall({ removeLocal, removeGlobal, workspaceRoot, userHome, getUserPromptsDir, cleanEmptyDirs }) {
+    const advisory = require('../../../../scripts/lib/advisory-text');
+    if (removeLocal) advisory.removeAdvisoryText(path.join(workspaceRoot, '.github', 'copilot-instructions.md'));
+    if (removeGlobal) {
+      const promptsDir = getUserPromptsDir();
+      const vscodeInstFile = path.join(promptsDir, 'harness.instructions.md');
+      if (fs.existsSync(vscodeInstFile) && advisory.hasHarnessMarker(fs.readFileSync(vscodeInstFile, 'utf8'))) {
+        fs.unlinkSync(vscodeInstFile);
+        console.log(`  ✅ Removed global Copilot instructions: ${vscodeInstFile}`);
+      }
+      cleanEmptyDirs(promptsDir, [userHome]);
+    }
+  }
+};

package/plugins/harness-everything/hooks/scripts/lib/platforms/cursor.js

@@ -0,0 +1,89 @@
+const path = require('path');
+const fs = require('fs');
+
+// Cursor's own skills location (.cursor/skills/) is unchanged - it already
+// has an established home. Only bookkeeping that never had a home (runtime
+// state, install manifest) converges into .cursor/harness-everything/.
+module.exports = {
+  name: 'cursor',
+  label: 'Cursor',
+  getHarnessDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.cursor', 'harness-everything');
+  },
+  getStateDir(workspaceRoot) {
+    return path.join(this.getHarnessDir(workspaceRoot), 'state');
+  },
+  getSkillsDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.cursor', 'skills');
+  },
+  getIgnorePatterns(workspaceRoot) {
+    const patterns = ['.cursor/harness-everything/'];
+    const skillsDir = path.join(workspaceRoot, '.cursor', 'skills');
+    if (fs.existsSync(skillsDir)) {
+      try {
+        const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md');
+            if (fs.existsSync(skillMdPath)) {
+              const content = fs.readFileSync(skillMdPath, 'utf8');
+              const authorLine = content.split('\n').find(line => line.trim().startsWith('author:'));
+              if (authorLine && (authorLine.includes('Miya Daniel'))) {
+                patterns.push(`.cursor/skills/${entry.name}/`);
+              }
+            }
+          }
+        }
+      } catch (e) {
+        // Fallback or ignore to prevent breaking execution
+      }
+    }
+    return patterns;
+  },
+  isMatch(pattern, trimmedLine) {
+    if (trimmedLine === '.cursor/' || trimmedLine === '.cursor') {
+      return true;
+    }
+    if (pattern === '.cursor/harness-everything/') {
+      return trimmedLine === '.cursor/harness-everything' ||
+             trimmedLine === '.cursor/harness-everything/';
+    }
+    return trimmedLine === pattern || trimmedLine === pattern.slice(0, -1);
+  },
+  isInstalled(workspaceRoot, userHome, isGlobal) {
+    if (isGlobal) {
+      return fs.existsSync(path.join(userHome, '.cursorrules'));
+    }
+    return fs.existsSync(path.join(workspaceRoot, '.cursorrules'));
+  },
+  getSkillsTarget({ workspaceRoot, userHome, isGlobal, manifest }) {
+    if (isGlobal) {
+      const globalAgentsDir = path.join(userHome, '.agents');
+      return {
+        path: path.join(globalAgentsDir, 'skills'),
+        label: '~/.agents/skills/',
+        manifestPath: manifest.getManifestPath(globalAgentsDir),
+      };
+    } else {
+      const cursorDir = path.join(workspaceRoot, '.cursor');
+      return {
+        path: path.join(cursorDir, 'skills'),
+        label: '.cursor/skills/',
+        manifestPath: manifest.getManifestPath(cursorDir),
+      };
+    }
+  },
+  install({ isGlobal, targetWorkspaceRoot, userHome, advisory }) {
+    const targetFile = isGlobal ? path.join(userHome, '.cursorrules') : path.join(targetWorkspaceRoot, '.cursorrules');
+    advisory.injectAdvisoryText(targetFile, '# Cursor Project Rules', isGlobal ? '~/.cursorrules' : '.cursorrules');
+  },
+  uninstall({ removeLocal, removeGlobal, workspaceRoot, userHome }) {
+    const advisory = require('../../../../scripts/lib/advisory-text');
+    if (removeLocal) {
+      advisory.removeAdvisoryText(path.join(workspaceRoot, '.cursorrules'));
+    }
+    if (removeGlobal) {
+      advisory.removeAdvisoryText(path.join(userHome, '.cursorrules'));
+    }
+  }
+};

package/plugins/harness-everything/hooks/scripts/lib/platforms/hermes.js

@@ -0,0 +1,108 @@
+const path = require('path');
+const fs = require('fs');
+
+const GLOBAL_MARKER = 'hermes-global.json';
+
+function appendHarnessSkillPatterns(patterns, skillsDir, prefix) {
+  if (!fs.existsSync(skillsDir)) return;
+  try {
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md');
+      if (!fs.existsSync(skillMdPath)) continue;
+      const content = fs.readFileSync(skillMdPath, 'utf8');
+      const authorLine = content.split('\n').find(line => line.trim().startsWith('author:'));
+      if (authorLine && authorLine.includes('Miya Daniel')) patterns.push(`${prefix}/${entry.name}/`);
+    }
+  } catch (e) {
+    // Best effort only; ignore-pattern generation must not break installation.
+  }
+}
+
+module.exports = {
+  name: 'hermes',
+  label: 'Hermes Agent',
+  getHarnessDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.hermes', 'harness-everything');
+  },
+  getStateDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.hermes', 'harness-state');
+  },
+  getSkillsDir(workspaceRoot) {
+    // Hermes discovers trusted project skills from `.agents/skills/` as well
+    // as `.hermes/skills/`. Use the shared Agent Skills location locally so
+    // explicit `--copy` and canonical auto mode are both discoverable.
+    return path.join(workspaceRoot, '.agents', 'skills');
+  },
+  getIgnorePatterns(workspaceRoot) {
+    const patterns = [];
+    if (fs.existsSync(path.join(workspaceRoot, '.hermes', 'harness-state'))) patterns.push('.hermes/harness-state/');
+    if (fs.existsSync(path.join(workspaceRoot, '.hermes', 'harness-everything'))) patterns.push('.hermes/harness-everything/');
+    appendHarnessSkillPatterns(patterns, path.join(workspaceRoot, '.agents', 'skills'), '.agents/skills');
+    return patterns;
+  },
+  isMatch(pattern, trimmedLine) {
+    if (pattern === '.hermes/harness-state/' || pattern === '.hermes/harness-everything/') {
+      return trimmedLine === '.hermes/' ||
+             trimmedLine === '.hermes' ||
+             trimmedLine === pattern.slice(0, -1) ||
+             trimmedLine === pattern;
+    }
+    if ((trimmedLine === '.agents/' || trimmedLine === '.agents') && pattern.startsWith('.agents/skills/')) return true;
+    return trimmedLine === pattern || trimmedLine === pattern.slice(0, -1);
+  },
+  isInstalled(workspaceRoot, userHome, isGlobal) {
+    if (isGlobal) {
+      return fs.existsSync(path.join(userHome, '.hermes', 'skills')) ||
+        fs.existsSync(path.join(userHome, '.agents', 'harness-everything', GLOBAL_MARKER));
+    }
+    return fs.existsSync(path.join(workspaceRoot, '.hermes.md'));
+  },
+  getSkillsTarget({ workspaceRoot, userHome, isGlobal, manifest }) {
+    if (isGlobal) {
+      const hermesDir = path.join(userHome, '.hermes');
+      return {
+        path: path.join(hermesDir, 'skills'),
+        label: '~/.hermes/skills/',
+        manifestPath: manifest.getManifestPath(hermesDir),
+      };
+    }
+    const hermesDir = path.join(workspaceRoot, '.hermes');
+    return {
+      path: path.join(workspaceRoot, '.agents', 'skills'),
+      label: '.agents/skills/',
+      manifestPath: manifest.getManifestPath(hermesDir),
+    };
+  },
+  install({ isGlobal, targetWorkspaceRoot, advisory, userHome }) {
+    if (!isGlobal) {
+      const targetFile = path.join(targetWorkspaceRoot, '.hermes.md');
+      advisory.injectAdvisoryText(targetFile, '# .hermes.md', '.hermes.md');
+    } else {
+      // Hermes has no global advisory-context file. Keep a tiny Harness-owned
+      // marker in the existing global bookkeeping home so non-interactive
+      // uninstall can distinguish an intentional Hermes global install from
+      // an unrelated ~/.hermes directory without changing Hermes config.
+      const markerDir = path.join(userHome, '.agents', 'harness-everything');
+      fs.mkdirSync(markerDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(markerDir, GLOBAL_MARKER),
+        JSON.stringify({ package: 'harness-everything', platform: 'hermes' }, null, 2),
+        'utf8'
+      );
+      console.log('  ℹ️  Hermes global skills install to ~/.hermes/skills/. Project advisory context remains project-scoped via .hermes.md.');
+    }
+  },
+  uninstall({ removeLocal, removeGlobal, workspaceRoot, userHome, cleanEmptyDirs }) {
+    const advisory = require('../../../../scripts/lib/advisory-text');
+    if (removeLocal) advisory.removeAdvisoryText(path.join(workspaceRoot, '.hermes.md'));
+    if (removeGlobal) {
+      const marker = path.join(userHome, '.agents', 'harness-everything', GLOBAL_MARKER);
+      if (fs.existsSync(marker)) fs.unlinkSync(marker);
+      if (typeof cleanEmptyDirs === 'function') {
+        cleanEmptyDirs(path.join(userHome, '.hermes', 'skills'), [userHome]);
+        cleanEmptyDirs(path.dirname(marker), [userHome]);
+      }
+    }
+  }
+};

package/plugins/harness-everything/hooks/scripts/lib/platforms/index.js

@@ -0,0 +1,17 @@
+const claude = require('./claude');
+const cursor = require('./cursor');
+const copilot = require('./copilot');
+const codex = require('./codex');
+const _continue = require('./continue');
+const hermes = require('./hermes');
+const worktrees = require('./worktrees');
+
+module.exports = [
+  claude,
+  cursor,
+  copilot,
+  codex,
+  _continue,
+  hermes,
+  worktrees
+];

package/plugins/harness-everything/hooks/scripts/lib/platforms/worktrees.js

@@ -0,0 +1,20 @@
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  name: 'worktrees',
+  label: 'Git Worktrees',
+  getIgnorePatterns(workspaceRoot) {
+    const patterns = [];
+    if (fs.existsSync(path.join(workspaceRoot, '.worktrees'))) {
+      patterns.push('.worktrees/');
+    }
+    if (fs.existsSync(path.join(workspaceRoot, 'worktrees'))) {
+      patterns.push('worktrees/');
+    }
+    return patterns;
+  },
+  isInstalled() {
+    return false; // Not a standalone platform hook/settings installer
+  }
+};

package/plugins/harness-everything/hooks/scripts/lib/workspace.js

@@ -0,0 +1,290 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const WORKSPACE_CONTEXT_KEYS = [
+  'workspace_root', 'workspaceRoot', 'project_root', 'projectRoot',
+  'working_directory', 'workingDirectory', 'cwd', 'root'
+];
+const SESSION_CONTEXT_KEYS = ['session_id', 'sessionId'];
+const HOST_CONTEXT_KEYS = [
+  'host_id', 'hostId', 'agent_id', 'agentId', 'client_id', 'clientId',
+  'machine_id', 'machineId', 'runtime_id', 'runtimeId'
+];
+const SESSION_REGISTRY_DIR = 'session-workspaces';
+const SESSION_REGISTRY_VERSION = 1;
+const UNBOUND_WORKSPACE_KEY = 'unbound-workspace';
+
+function findWorkspaceRoot(startPath, allowNonGit = false) {
+  if (typeof startPath !== 'string' || !startPath.trim()) return null;
+  let dir = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.git'))) return canonicalPath(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return allowNonGit ? canonicalPath(startPath) : null;
+}
+
+function canonicalPath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const resolved = path.resolve(value);
+  try { return fs.realpathSync(resolved); } catch (err) { return resolved; }
+}
+
+function getSessionId(context) {
+  if (!context || typeof context !== 'object') return null;
+  for (const key of SESSION_CONTEXT_KEYS) {
+    if (typeof context[key] === 'string' && context[key].trim()) {
+      return context[key].trim();
+    }
+  }
+  for (const key of ['session', 'metadata', 'context']) {
+    if (context[key] && typeof context[key] === 'object') {
+      const nested = getSessionId(context[key]);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+function getHostId(context) {
+  if (!context || typeof context !== 'object') return null;
+  for (const key of HOST_CONTEXT_KEYS) {
+    if (typeof context[key] === 'string' && context[key].trim()) return context[key].trim();
+  }
+  if (typeof context.host === 'string' && context.host.trim()) return context.host.trim();
+  if (context.host && typeof context.host === 'object') return getHostId(context.host);
+  for (const key of ['agent', 'client', 'machine', 'runtime', 'metadata', 'context']) {
+    if (context[key] && typeof context[key] === 'object') {
+      const nested = getHostId(context[key]);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+function contextPath(context, depth = 0) {
+  if (typeof context === 'string' && context.trim()) return context.trim();
+  if (!context || typeof context !== 'object' || depth > 2) return null;
+
+  for (const key of WORKSPACE_CONTEXT_KEYS) {
+    const value = context[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+    if (value && typeof value === 'object') {
+      const nested = contextPath(value, depth + 1);
+      if (nested) return nested;
+    }
+  }
+
+  for (const key of ['workspace', 'project', 'host', 'context']) {
+    const nested = contextPath(context[key], depth + 1);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+function sessionRegistryPath(sessionId, hostId) {
+  const namespace = hostId ? `${hostId}\0${sessionId}` : String(sessionId);
+  const hash = crypto.createHash('sha256').update(namespace).digest('hex');
+  return path.join(getStateHome(), SESSION_REGISTRY_DIR, `${hash}.json`);
+}
+
+function readRegistryRecord(filePath) {
+  try {
+    const record = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (record.version !== SESSION_REGISTRY_VERSION || typeof record.workspaceRoot !== 'string') return null;
+    return record;
+  } catch (err) {
+    return null;
+  }
+}
+
+function findSessionRecords(sessionId) {
+  const registryDir = path.join(getStateHome(), SESSION_REGISTRY_DIR);
+  try {
+    return fs.readdirSync(registryDir, { withFileTypes: true })
+      .filter(entry => entry.isFile() && entry.name.endsWith('.json'))
+      .map(entry => readRegistryRecord(path.join(registryDir, entry.name)))
+      .filter(record => record && record.sessionId === sessionId);
+  } catch (err) {
+    return [];
+  }
+}
+
+function readWorkspaceSession(sessionId, context) {
+  if (!sessionId) return null;
+  const hostId = getHostId(context);
+  const records = [];
+  const preferred = readRegistryRecord(sessionRegistryPath(sessionId, hostId));
+  if (preferred && (!hostId || !preferred.hostId || preferred.hostId === hostId)) records.push(preferred);
+  if (hostId) {
+    // A session may have been first observed by a caller that did not expose
+    // host metadata. Reuse that unscoped binding rather than forking state.
+    const unscoped = readRegistryRecord(sessionRegistryPath(sessionId, null));
+    if (unscoped && !unscoped.hostId) records.push(unscoped);
+  } else {
+    records.push(...findSessionRecords(sessionId));
+  }
+
+  const unique = [...new Map(records.map(record => [
+    `${record.hostId || ''}\0${record.workspaceRoot}`,
+    record
+  ])).values()];
+  if (unique.length === 1) return unique[0];
+  if (unique.length > 1) {
+    // Hostless payloads are safe only when all known host bindings agree on
+    // the same workspace. Otherwise select nothing and require context.
+    const roots = new Set(unique.map(record => canonicalPath(record.workspaceRoot)));
+    if (roots.size === 1) return unique[0];
+  }
+  return null;
+}
+
+function bindWorkspaceSession(sessionId, workspaceRoot, context, force = false) {
+  if (!sessionId) return null;
+  const root = findWorkspaceRoot(workspaceRoot, true);
+  if (!root) return null;
+  const hostId = getHostId(context);
+  const target = sessionRegistryPath(sessionId, hostId);
+  const record = {
+    version: SESSION_REGISTRY_VERSION,
+    sessionId,
+    hostId: hostId || undefined,
+    workspaceRoot: root,
+    workspaceKey: getWorkspaceKey(root),
+    updatedAt: new Date().toISOString()
+  };
+  const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(temporary, JSON.stringify(record, null, 2), 'utf8');
+    // Keep the first successful binding when two hooks initialize together.
+    if (fs.existsSync(target)) {
+      if (readRegistryRecord(target) && !force) fs.unlinkSync(temporary);
+      else {
+        fs.unlinkSync(target);
+        fs.renameSync(temporary, target);
+      }
+    } else fs.renameSync(temporary, target);
+  } catch (err) {
+    // Identity persistence is best effort. The caller still receives the
+    // resolved root and the next invocation can retry the binding.
+    try { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); } catch (cleanupErr) { /* ignore */ }
+  }
+  return root;
+}
+
+function isIdentityReset(context) {
+  if (!context || typeof context !== 'object') return false;
+  return context.workspace_identity_reset === true ||
+    context.workspaceIdentityReset === true ||
+    context.new_session === true ||
+    context.newSession === true;
+}
+
+function getWorkspaceRoot(context) {
+  const sessionId = getSessionId(context);
+  const existing = readWorkspaceSession(sessionId, context);
+  const explicit = contextPath(context);
+
+  // SessionStart is the host's authoritative opportunity to establish (or
+  // re-establish) the project identity. All later hook invocations keep that
+  // binding even if the agent changes cwd or reports a nested repository.
+  if (existing && !isIdentityReset(context)) return existing.workspaceRoot;
+
+  const hostRoot = explicit || process.env.HARNESS_WORKSPACE_ROOT ||
+    process.env.CLAUDE_PROJECT_DIR || process.env.CODEX_PROJECT_DIR;
+  const root = findWorkspaceRoot(hostRoot || process.cwd(), Boolean(hostRoot));
+  if (sessionId) bindWorkspaceSession(sessionId, root, context, isIdentityReset(context));
+  return root;
+}
+
+// Single global root for ALL Harness runtime state (session counters,
+// circuit-breaker trips, audit logs, handoff timestamps, ...). Never
+// cwd-derived, so a script invoked from a fixture dir, worktree, submodule,
+// or any other nested non-git directory can never scatter files there
+// (issue #42). `$HARNESS_STATE_HOME` matches the env var the opencode
+// plugin already used for its own (differently-rooted) global state.
+function getStateHome() {
+  return process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything');
+}
+
+// Keys runtime state per real workspace instead of per invocation cwd, so
+// two different repos (or a repo and a stray subdirectory someone `cd`ed
+// into) never collide or fork the same state stream. Uses the resolved real
+// path (symlinks collapsed) hashed short, prefixed with a readable slug
+// purely so `~/.agents/harness-everything/workspaces/` stays eyeballable.
+function getWorkspaceKey(root) {
+  const workspaceRoot = typeof root === 'string' && root.trim() ? root : getWorkspaceRoot(root);
+  if (!workspaceRoot) return UNBOUND_WORKSPACE_KEY;
+  const resolved = path.resolve(workspaceRoot);
+  let real = resolved;
+  try { real = fs.realpathSync(resolved); } catch (err) { /* path may not exist yet (tests) */ }
+  const slug = path.basename(real).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'workspace';
+  const hashInput = process.platform === 'win32' ? real.toLowerCase() : real;
+  const hash = crypto.createHash('sha1').update(hashInput).digest('hex').slice(0, 12);
+  return `${slug}-${hash}`;
+}
+
+function getWorkspaceStateDir(root) {
+  return path.join(getStateHome(), 'workspaces', getWorkspaceKey(root));
+}
+
+function resolveWorkspaceIdentity(context) {
+  const workspaceRoot = getWorkspaceRoot(context);
+  return {
+    workspaceRoot,
+    workspaceKey: getWorkspaceKey(workspaceRoot),
+    stateDir: getWorkspaceStateDir(workspaceRoot),
+    sessionId: getSessionId(context)
+  };
+}
+
+function getUserPromptsDir() {
+  if (process.env.VSCODE_USER_PROMPTS_FOLDER) {
+    return process.env.VSCODE_USER_PROMPTS_FOLDER;
+  }
+  const home = os.homedir();
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Code', 'User', 'prompts');
+  } else if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'Code', 'User', 'prompts');
+  } else {
+    return path.join(home, '.config', 'Code', 'User', 'prompts');
+  }
+}
+
+// The harness repo must never be "repaired" into carrying its own generated
+// advisory files. Identify it by repo identity, not by comparing the caller's
+// __dirname: when harness runs from an npx/global install against its own
+// source checkout, the installed path and the workspace path differ and a
+// path-based guard silently fails open (issue #40).
+const HARNESS_PACKAGE_NAME = 'harness-everything';
+
+function isHarnessRepo(workspaceRoot) {
+  try {
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.name === HARNESS_PACKAGE_NAME;
+  } catch (err) {
+    return false;
+  }
+}
+
+module.exports = {
+  getWorkspaceRoot,
+  resolveWorkspaceIdentity,
+  bindWorkspaceSession,
+  readWorkspaceSession,
+  getSessionId,
+  getHostId,
+  getStateHome,
+  getWorkspaceKey,
+  getWorkspaceStateDir,
+  getUserPromptsDir,
+  isHarnessRepo,
+  HARNESS_PACKAGE_NAME,
+};