mecord-connect 1.0.0

package/runtime/app/src/capabilities/project-transaction.js

@@ -0,0 +1,215 @@
+                                                                                                         
+import { evidence } from '../core/evidence.js';
+import { OperatorError } from '../core/errors.js';
+import { GitCheckpointProvider } from './git-checkpoint.js';
+import { ProjectCommandProvider } from './project-command.js';
+
+const SCORE                  = {
+  reliability: 0.99,
+  latency: 0.88,
+  determinism: 0.99,
+  security: 0.99,
+  reversibility: 0.99,
+  informationQuality: 0.99,
+  interactionCost: 0.02
+};
+
+                          
+             
+                                      
+  
+
+                  
+                      
+  
+
+export class ProjectTransactionProvider                               {
+           name = 'project.transaction.git';
+  #commands                        ;
+  #checkpoints                       ;
+
+  constructor(options                                                                                 ) {
+    this.#commands = new ProjectCommandProvider(options);
+    this.#checkpoints = new GitCheckpointProvider({ allowedRoots: options.allowedRoots });
+  }
+
+  supports(action               )          { return action.capability === 'project.transaction.run'; }
+  score()                  { return SCORE; }
+
+  async execute(action               )                        {
+    const started = performance.now();
+    try {
+      if (action.risk !== 'destructive') {
+        throw new OperatorError('TRANSACTION_DESTRUCTIVE_RISK_REQUIRED', 'Automatic rollback transactions must be authorized as destructive before execution.');
+      }
+      const projectRoot = String(action.input.path ?? '');
+      const commandId = String(action.input.commandId ?? '');
+      const expectedRisk = String(action.input.expectedRisk ?? '');
+      if (!['read', 'write'].includes(expectedRisk)) {
+        throw new OperatorError('TRANSACTION_RISK_UNSUPPORTED', 'Automatic rollback supports only trusted read/write commands; external effects are not reversible.');
+      }
+
+      const inspected = await this.#commands.execute({
+        id: `${action.id}:inspect-command`,
+        capability: 'project.command.inspect',
+        risk: 'read',
+        input: { path: projectRoot },
+        provenance: { kind: 'trusted_policy', source: action.id }
+      });
+      if (!inspected.ok) throw childError(inspected, 'TRANSACTION_COMMAND_INSPECT_FAILED');
+      const command = ((inspected.output                                                  )?.commands ?? [])
+        .find((candidate) => candidate.id === commandId);
+      if (!command) throw new OperatorError('PROJECT_COMMAND_NOT_REGISTERED', `Trusted command ${commandId} is not registered for this project.`);
+      if (command.risk === 'external') {
+        throw new OperatorError('TRANSACTION_EXTERNAL_UNSUPPORTED', 'External trusted commands cannot run inside automatic rollback transactions.');
+      }
+      if (command.risk !== expectedRisk) {
+        throw new OperatorError('PROJECT_COMMAND_RISK_MISMATCH', 'Transaction expectedRisk must match the trusted registry risk.', {
+          details: { expectedRisk, registeredRisk: command.risk }
+        });
+      }
+
+      const checkpointResult = await this.#checkpoints.execute({
+        id: `${action.id}:checkpoint`,
+        capability: 'git.checkpoint.create',
+        risk: 'write',
+        input: { cwd: projectRoot, label: `transaction before ${commandId}` },
+        provenance: { kind: 'trusted_policy', source: action.id }
+      });
+      if (!checkpointResult.ok) throw childError(checkpointResult, 'TRANSACTION_CHECKPOINT_FAILED');
+      const checkpoint = checkpointResult.output                                       ;
+
+      const commandResult = await this.#commands.execute({
+        id: `${action.id}:command`,
+        capability: 'project.command.run',
+        risk: command.risk,
+        input: { path: projectRoot, commandId, expectedRisk: command.risk },
+        provenance: { kind: 'trusted_policy', source: action.id }
+      });
+
+      if (commandResult.ok) {
+        return {
+          ok: true,
+          capability: action.capability,
+          provider: this.name,
+          output: {
+            commandId,
+            commandRisk: command.risk,
+            checkpointId: checkpoint.id,
+            checkpointFingerprint: checkpoint.fingerprint,
+            rollbackPerformed: false,
+            rollbackCoverage: 'Git index + non-ignored working-tree state captured by git.checkpoint',
+            command: commandResult
+          },
+          evidence: [
+            evidence('transaction_checkpoint', 'pass', 'Created a non-mutating Git checkpoint before the trusted command.', { checkpointId: checkpoint.id }),
+            evidence('transaction_command', 'pass', 'Trusted command and declared postconditions verified; rollback was not required.', { commandId }),
+            evidence('recovery_checkpoint', 'info', 'Pre-command checkpoint remains available for explicit recovery.', { checkpointId: checkpoint.id })
+          ],
+          durationMs: Math.round(performance.now() - started)
+        };
+      }
+
+      const currentResult = await this.#checkpoints.execute({
+        id: `${action.id}:inspect-after-failure`,
+        capability: 'git.checkpoint.inspect',
+        risk: 'read',
+        input: { cwd: projectRoot },
+        provenance: { kind: 'trusted_policy', source: action.id }
+      });
+      if (!currentResult.ok) {
+        return rollbackFailure(action, started, checkpoint.id, commandResult, currentResult, 'Unable to inspect repository state before rollback.');
+      }
+      const current = (currentResult.output                                       )?.current;
+      if (!current?.fingerprint) {
+        return rollbackFailure(action, started, checkpoint.id, commandResult, currentResult, 'Repository fingerprint was unavailable before rollback.');
+      }
+
+      const restoreResult = await this.#checkpoints.execute({
+        id: `${action.id}:rollback`,
+        capability: 'git.checkpoint.restore',
+        risk: 'destructive',
+        input: {
+          cwd: projectRoot,
+          checkpointId: checkpoint.id,
+          expectedCurrentFingerprint: current.fingerprint
+        },
+        provenance: { kind: 'trusted_policy', source: action.id }
+      });
+
+      if (!restoreResult.ok) {
+        return rollbackFailure(action, started, checkpoint.id, commandResult, restoreResult, 'Trusted command failed and automatic Git rollback could not be verified.');
+      }
+
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: this.name,
+        output: {
+          commandId,
+          commandRisk: command.risk,
+          checkpointId: checkpoint.id,
+          rollbackPerformed: true,
+          rollbackCoverage: 'Git index + non-ignored working-tree state captured by git.checkpoint',
+          command: commandResult,
+          rollback: restoreResult
+        },
+        evidence: [
+          evidence('transaction_checkpoint', 'pass', 'Created a non-mutating Git checkpoint before the trusted command.', { checkpointId: checkpoint.id }),
+          evidence('transaction_command', 'fail', commandResult.error?.message ?? 'Trusted command verification failed.', { commandId, code: commandResult.error?.code }),
+          evidence('transaction_rollback', 'pass', 'Trusted command failed; Git checkpoint restore completed and verified.', { checkpointId: checkpoint.id })
+        ],
+        error: {
+          code: 'TRANSACTION_FAILED_ROLLED_BACK',
+          message: `Trusted command ${commandId} failed verification and repository state was rolled back to the pre-command checkpoint.`,
+          retryable: true
+        },
+        durationMs: Math.round(performance.now() - started)
+      };
+    } catch (error) {
+      const op = error instanceof OperatorError
+        ? error
+        : new OperatorError('PROJECT_TRANSACTION_ERROR', error instanceof Error ? error.message : String(error));
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: this.name,
+        evidence: [evidence('project_transaction', 'fail', op.message, { code: op.code })],
+        error: { code: op.code, message: op.message, retryable: op.retryable },
+        durationMs: Math.round(performance.now() - started)
+      };
+    }
+  }
+}
+
+function childError(result              , fallbackCode        )                {
+  return new OperatorError(result.error?.code ?? fallbackCode, result.error?.message ?? fallbackCode, { retryable: result.error?.retryable });
+}
+
+function rollbackFailure(
+  action               ,
+  started        ,
+  checkpointId        ,
+  commandResult              ,
+  rollbackResult              ,
+  message        
+)               {
+  return {
+    ok: false,
+    capability: action.capability,
+    provider: 'project.transaction.git',
+    output: {
+      checkpointId,
+      rollbackPerformed: false,
+      rollbackCoverage: 'Git index + non-ignored working-tree state captured by git.checkpoint',
+      command: commandResult,
+      rollbackAttempt: rollbackResult
+    },
+    evidence: [
+      evidence('transaction_command', 'fail', commandResult.error?.message ?? 'Trusted command verification failed.', { code: commandResult.error?.code }),
+      evidence('transaction_rollback', 'fail', message, { checkpointId, code: rollbackResult.error?.code })
+    ],
+    error: { code: 'TRANSACTION_FAILED_ROLLBACK_FAILED', message, retryable: false },
+    durationMs: Math.round(performance.now() - started)
+  };
+}

package/runtime/app/src/capabilities/project.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+                                                                                                         
+import { evidence } from '../core/evidence.js';
+import { PathScope } from './path-scope.js';
+
+const SCORE                  = {
+  reliability: 0.97,
+  latency: 0.96,
+  determinism: 0.98,
+  security: 0.96,
+  reversibility: 1,
+  informationQuality: 0.94,
+  interactionCost: 0.01
+};
+
+export class ProjectInspectProvider                               {
+           name = 'project.semantic';
+  #scope           ;
+
+  constructor(options                            ) { this.#scope = new PathScope(options.allowedRoots); }
+  supports(action               )          { return action.capability === 'project.inspect'; }
+  score()                  { return SCORE; }
+
+  async execute(action               )                        {
+    const started = performance.now();
+    const root = await this.#scope.resolveExisting(String(action.input.path ?? ''));
+    const names = await fs.readdir(root);
+    const has = (name        ) => names.includes(name);
+    const packageJson = await maybeJson(path.join(root, 'package.json'));
+    const pyproject = await maybeText(path.join(root, 'pyproject.toml'), 32 * 1024);
+
+    const output = {
+      root,
+      repository: has('.git'),
+      buildSystems: [
+        has('package.json') ? 'node' : null,
+        has('Cargo.toml') ? 'cargo' : null,
+        has('pyproject.toml') ? 'python' : null,
+        has('CMakeLists.txt') ? 'cmake' : null,
+        has('pom.xml') ? 'maven' : null,
+        has('build.gradle') || has('build.gradle.kts') ? 'gradle' : null
+      ].filter(Boolean),
+      packageManager: has('pnpm-lock.yaml') ? 'pnpm' : has('yarn.lock') ? 'yarn' : has('package-lock.json') ? 'npm' : null,
+      scripts: packageJson && typeof packageJson === 'object' ? (packageJson                           ).scripts ?? null : null,
+      manifests: names.filter((name) => ['package.json', 'Cargo.toml', 'pyproject.toml', 'pom.xml', 'CMakeLists.txt', 'build.gradle', 'build.gradle.kts'].includes(name)),
+      pyprojectDetected: pyproject !== null,
+      observedAt: new Date().toISOString()
+    };
+
+    return {
+      ok: true,
+      capability: action.capability,
+      provider: this.name,
+      output,
+      evidence: [evidence('project_model', 'pass', 'Project metadata derived from files in authorized scope.', { root })],
+      durationMs: Math.round(performance.now() - started)
+    };
+  }
+}
+
+async function maybeJson(filePath        )                          {
+  try { return JSON.parse(await fs.readFile(filePath, 'utf8')); } catch { return null; }
+}
+async function maybeText(filePath        , max        )                         {
+  try { return (await fs.readFile(filePath, 'utf8')).slice(0, max); } catch { return null; }
+}

package/runtime/app/src/capabilities/system.js

@@ -0,0 +1,40 @@
+import os from 'node:os';
+                                                                                                         
+import { evidence } from '../core/evidence.js';
+
+const SCORE                  = {
+  reliability: 1,
+  latency: 1,
+  determinism: 1,
+  security: 0.99,
+  reversibility: 1,
+  informationQuality: 0.95,
+  interactionCost: 0
+};
+
+export class SystemInspectProvider                               {
+           name = 'system.native';
+  supports(action               )          { return action.capability === 'computer.inspect'; }
+  score()                  { return SCORE; }
+
+  async execute(action               )                        {
+    const started = performance.now();
+    const output = {
+      hostname: os.hostname(),
+      platform: os.platform(),
+      release: os.release(),
+      arch: os.arch(),
+      cpuCount: os.cpus().length,
+      totalMemoryBytes: os.totalmem(),
+      node: process.version
+    };
+    return {
+      ok: true,
+      capability: action.capability,
+      provider: this.name,
+      output,
+      evidence: [evidence('computer_state', 'pass', 'Computer state gathered using native APIs.')],
+      durationMs: Math.round(performance.now() - started)
+    };
+  }
+}

package/runtime/app/src/capabilities/vscode.js

@@ -0,0 +1,312 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+                                                                                                         
+import { evidence } from '../core/evidence.js';
+import { OperatorError } from '../core/errors.js';
+import { resolveTrustedExecutable } from '../core/trusted-executable.js';
+import { PathScope } from './path-scope.js';
+
+const SCORE                  = {
+  reliability: 0.94,
+  latency: 0.88,
+  determinism: 0.93,
+  security: 0.96,
+  reversibility: 0.96,
+  informationQuality: 0.9,
+  interactionCost: 0.04
+};
+
+const MAX_OUTPUT_BYTES = 512 * 1024;
+const MAX_EXTENSIONS = 1000;
+
+export class VsCodeProvider                               {
+           name = 'vscode.cli.isolated';
+  #scope           ;
+  #allowedRoots          ;
+  #codeExecutable        ;
+  #codeArgsPrefix          ;
+  #dataDir        ;
+
+  constructor(options                                                                                                  ) {
+    this.#scope = new PathScope(options.allowedRoots);
+    this.#allowedRoots = options.allowedRoots.map((root) => path.resolve(root));
+    this.#codeExecutable = options.codeExecutable ?? 'code';
+    this.#codeArgsPrefix = options.codeArgsPrefix ?? [];
+    this.#dataDir = path.resolve(options.dataDir ?? path.join(os.homedir(), '.operator', 'vscode-safe'));
+  }
+
+  supports(action               )          {
+    return action.capability === 'vscode.inspect' || action.capability === 'vscode.open';
+  }
+
+  score()                  { return SCORE; }
+
+  async execute(action               )                        {
+    const started = performance.now();
+    try {
+      await this.#assertDataDirOutsideProjects();
+      if (action.capability === 'vscode.inspect') {
+        const operation = String(action.input.operation ?? 'status');
+        if (operation === 'version') {
+          const result = await this.#run(['--version'], process.cwd(), 10_000);
+          return ok(action, started, { operation, version: result.stdout.trim().split(/\r?\n/)[0] ?? '' }, [
+            evidence('vscode_cli', 'pass', 'Read VS Code CLI version without opening a workspace.')
+          ]);
+        }
+        if (operation === 'extensions') {
+          const result = await this.#run(['--list-extensions', '--show-versions'], process.cwd(), 15_000);
+          const extensions = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(0, MAX_EXTENSIONS).map((line) => {
+            const at = line.lastIndexOf('@');
+            return at > 0 ? { id: line.slice(0, at), version: line.slice(at + 1) } : { id: line };
+          });
+          return ok(action, started, { operation, extensions, truncated: extensions.length >= MAX_EXTENSIONS }, [
+            evidence('vscode_extensions', 'pass', 'Listed installed VS Code extension identifiers and versions without opening a project.', { count: extensions.length })
+          ]);
+        }
+        if (operation === 'status') {
+          const result = await this.#run(['--status'], process.cwd(), 15_000);
+          return ok(action, started, { operation, status: result.stdout.slice(0, MAX_OUTPUT_BYTES), truncated: result.truncated }, [
+            evidence('vscode_status', 'pass', 'Read bounded VS Code process/status diagnostics through the official CLI.')
+          ]);
+        }
+        throw new OperatorError('INVALID_VSCODE_INSPECT_OPERATION', 'operation must be version, extensions, or status.');
+      }
+
+      const mode = String(action.input.mode ?? 'folder');
+      const timeoutMs = boundedInteger(action.input.timeoutMs, 15_000, 1_000, 60_000);
+      await fs.mkdir(this.#dataDir, { recursive: true, mode: 0o700 });
+      const args = ['--new-window', '--disable-extensions', `--user-data-dir=${this.#dataDir}`];
+      let targetSummary                         ;
+      let cwd        ;
+
+      if (mode === 'folder') {
+        const folder = await this.#scope.resolveExisting(String(action.input.path ?? ''));
+        const stat = await fs.stat(folder);
+        if (!stat.isDirectory()) throw new OperatorError('VSCODE_FOLDER_REQUIRED', 'folder mode requires an authorized directory.');
+        args.push(folder);
+        cwd = folder;
+        targetSummary = { mode, path: folder };
+      } else if (mode === 'file' || mode === 'goto') {
+        const file = await this.#scope.resolveExisting(String(action.input.path ?? ''));
+        const stat = await fs.stat(file);
+        if (!stat.isFile()) throw new OperatorError('VSCODE_FILE_REQUIRED', `${mode} mode requires an authorized regular file.`);
+        cwd = path.dirname(file);
+        if (mode === 'goto') {
+          const line = boundedPositiveInt(action.input.line, 1, 1_000_000, 'line');
+          const column = boundedPositiveInt(action.input.column ?? 1, 1, 1_000_000, 'column');
+          args.push('--goto', `${file}:${line}:${column}`);
+          targetSummary = { mode, path: file, line, column };
+        } else {
+          args.push(file);
+          targetSummary = { mode, path: file };
+        }
+      } else if (mode === 'diff') {
+        const left = await this.#scope.resolveExisting(String(action.input.leftPath ?? ''));
+        const right = await this.#scope.resolveExisting(String(action.input.rightPath ?? ''));
+        const [leftStat, rightStat] = await Promise.all([fs.stat(left), fs.stat(right)]);
+        if (!leftStat.isFile() || !rightStat.isFile()) throw new OperatorError('VSCODE_DIFF_FILES_REQUIRED', 'diff mode requires two authorized regular files.');
+        args.push('--diff', left, right);
+        cwd = path.dirname(left);
+        targetSummary = { mode, leftPath: left, rightPath: right };
+      } else {
+        throw new OperatorError('INVALID_VSCODE_OPEN_MODE', 'mode must be folder, file, goto, or diff.');
+      }
+
+      const result = await this.#run(args, cwd, timeoutMs);
+      return ok(action, started, {
+        ...targetSummary,
+        isolated: true,
+        extensionsDisabled: true,
+        accepted: true,
+        stdout: result.stdout.slice(0, 32_000),
+        stderr: result.stderr.slice(0, 32_000)
+      }, [
+        evidence('vscode_isolation', 'pass', 'Opened target in a new Operator-isolated VS Code window with extensions disabled.', {
+          userDataDir: this.#dataDir,
+          reusedExistingWindow: false
+        }),
+        evidence('vscode_cli', 'pass', 'VS Code CLI accepted the bounded semantic open request.', { mode })
+      ]);
+    } catch (error) {
+      const op = error instanceof OperatorError
+        ? error
+        : new OperatorError('VSCODE_ERROR', error instanceof Error ? error.message : String(error), { retryable: true });
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: this.name,
+        evidence: [evidence('vscode', 'fail', op.message, { code: op.code })],
+        error: { code: op.code, message: op.message, retryable: op.retryable },
+        durationMs: Math.round(performance.now() - started)
+      };
+    }
+  }
+
+  async #assertDataDirOutsideProjects()                {
+    const lexicalDataDir = path.resolve(this.#dataDir);
+    for (const configuredRoot of this.#allowedRoots) {
+      const lexicalRoot = path.resolve(configuredRoot);
+      if (inside(lexicalDataDir, lexicalRoot)) {
+        throw new OperatorError('VSCODE_DATA_DIR_INSIDE_PROJECT_DENIED', 'Operator VS Code user-data directory must live outside all authorized project roots.');
+      }
+    }
+    await fs.mkdir(path.dirname(this.#dataDir), { recursive: true, mode: 0o700 });
+    const parent = await fs.realpath(path.dirname(this.#dataDir));
+    const resolvedDataDir = path.join(parent, path.basename(this.#dataDir));
+    for (const configuredRoot of this.#allowedRoots) {
+      let root = configuredRoot;
+      try { root = await fs.realpath(configuredRoot); } catch { /* lexical fallback */ }
+      if (inside(resolvedDataDir, root)) {
+        throw new OperatorError('VSCODE_DATA_DIR_INSIDE_PROJECT_DENIED', 'Operator VS Code user-data directory must live outside all authorized project roots.');
+      }
+    }
+  }
+
+  async #run(args          , cwd        , timeoutMs        )                                                                  {
+    const output = await runCode(this.#codeExecutable, [...this.#codeArgsPrefix, ...args], cwd, timeoutMs);
+    if (output.code !== 0) throw new OperatorError('VSCODE_CLI_FAILED', `VS Code CLI exited with code ${output.code}.`, { details: { stderr: output.stderr.slice(-4000) } });
+    return output;
+  }
+}
+
+function boundedInteger(input         , fallback        , min        , max        )         {
+  const value = Number(input ?? fallback);
+  if (!Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
+
+function boundedPositiveInt(input         , min        , max        , label        )         {
+  const value = Number(input);
+  if (!Number.isInteger(value) || value < min || value > max) throw new OperatorError('VSCODE_POSITION_INVALID', `${label} must be an integer between ${min} and ${max}.`);
+  return value;
+}
+
+function inside(candidate        , root        )          {
+  const rel = path.relative(root, candidate);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function safeEnvironment()                    {
+  const env                    = {};
+  for (const key of [
+    'PATH', 'Path', 'PATHEXT', 'SYSTEMROOT', 'WINDIR', 'COMSPEC',
+    'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'USER', 'USERNAME', 'LOGNAME',
+    'TMP', 'TEMP', 'TMPDIR', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM', 'COLORTERM', 'SHELL',
+    'PROGRAMFILES', 'PROGRAMFILES(X86)', 'PROGRAMW6432', 'PROGRAMDATA', 'LOCALAPPDATA', 'APPDATA',
+    'DISPLAY', 'WAYLAND_DISPLAY', 'XDG_RUNTIME_DIR', 'XDG_DATA_HOME', 'XDG_CONFIG_HOME', 'DBUS_SESSION_BUS_ADDRESS'
+  ]) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  return env;
+}
+
+export function candidateVsCodeExecutablePaths(source                   )           {
+  const candidates           = [];
+  const add = (value                    ) => {
+    if (!value || !path.win32.isAbsolute(value)) return;
+    const normalized = path.win32.normalize(value);
+    if (!candidates.some((item) => item.toLowerCase() === normalized.toLowerCase())) candidates.push(normalized);
+  };
+  if (source.LOCALAPPDATA) add(path.win32.join(source.LOCALAPPDATA, 'Programs', 'Microsoft VS Code', 'Code.exe'));
+  for (const root of [source.PROGRAMFILES, source['PROGRAMFILES(X86)'], source.PROGRAMW6432]) {
+    if (root) add(path.win32.join(root, 'Microsoft VS Code', 'Code.exe'));
+  }
+  return candidates;
+}
+
+function resolveVsCodeExecutable(executable        , environment                   )         {
+  if (process.platform === 'win32' && executable.trim().toLowerCase() === 'code') {
+    for (const candidate of candidateVsCodeExecutablePaths(environment)) {
+      try {
+        return resolveTrustedExecutable(candidate, environment);
+      } catch (error) {
+        if (!(error instanceof OperatorError) || error.code !== 'EXECUTABLE_NOT_FOUND') throw error;
+      }
+    }
+  }
+  return resolveTrustedExecutable(executable, environment);
+}
+
+export async function resolveVsCodeCliScript(codeExecutable        )                  {
+  const realExecutable = await fs.realpath(codeExecutable);
+  const installRoot = path.dirname(realExecutable);
+  const realRoot = await fs.realpath(installRoot);
+  const entries = await fs.readdir(installRoot, { withFileTypes: true });
+  const candidates           = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !/^[0-9a-f]{10,40}$/i.test(entry.name)) continue;
+    const candidate = path.join(installRoot, entry.name, 'resources', 'app', 'out', 'cli.js');
+    try {
+      const stat = await fs.lstat(candidate);
+      if (!stat.isFile() || stat.isSymbolicLink()) continue;
+      const realCandidate = await fs.realpath(candidate);
+      if (!inside(realCandidate, realRoot)) continue;
+      candidates.push(realCandidate);
+    } catch { /* stale or incomplete installation directory */ }
+  }
+  if (candidates.length === 0) throw new OperatorError('VSCODE_CLI_NOT_FOUND', 'VS Code native executable was found but its bounded CLI entrypoint was not.');
+  if (candidates.length > 1) throw new OperatorError('VSCODE_CLI_AMBIGUOUS', 'Multiple VS Code CLI entrypoints were found; complete or clean up the VS Code update first.');
+  return candidates[0] ;
+}
+
+async function runCode(executable        , args          , cwd        , timeoutMs        )                                                                                {
+  const baseEnvironment = safeEnvironment();
+  const codeExecutable = resolveVsCodeExecutable(executable, baseEnvironment);
+  const nativeCli = process.platform === 'win32' && path.win32.basename(codeExecutable).toLowerCase() === 'code.exe'
+    ? await resolveVsCodeCliScript(codeExecutable)
+    : undefined;
+  const environment = nativeCli ? { ...baseEnvironment, ELECTRON_RUN_AS_NODE: '1' } : baseEnvironment;
+  const invocationArgs = nativeCli ? [nativeCli, ...args] : args;
+  return await new Promise((resolve, reject) => {
+    const child = spawn(codeExecutable, invocationArgs, {
+      cwd,
+      shell: false,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: environment
+    });
+    const stdout           = [];
+    const stderr           = [];
+    let bytes = 0;
+    let truncated = false;
+    let timedOut = false;
+    const capture = (bucket          ) => (chunk        ) => {
+      if (bytes >= MAX_OUTPUT_BYTES) { truncated = true; return; }
+      const remaining = MAX_OUTPUT_BYTES - bytes;
+      const piece = chunk.subarray(0, remaining);
+      bucket.push(piece);
+      bytes += piece.byteLength;
+      if (piece.byteLength < chunk.byteLength) truncated = true;
+    };
+    child.stdout.on('data', capture(stdout));
+    child.stderr.on('data', capture(stderr));
+    child.once('error', reject);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 1000).unref();
+    }, timeoutMs);
+    timer.unref();
+    child.once('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        reject(new OperatorError('VSCODE_TIMEOUT', `VS Code CLI exceeded ${timeoutMs}ms timeout.`, { retryable: true }));
+        return;
+      }
+      resolve({ code: code ?? -1, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8'), truncated });
+    });
+  });
+}
+
+function ok(action               , started        , output         , evidenceItems                          )               {
+  return {
+    ok: true,
+    capability: action.capability,
+    provider: 'vscode.cli.isolated',
+    output,
+    evidence: evidenceItems,
+    durationMs: Math.round(performance.now() - started)
+  };
+}