@git.zone/tsrust 1.9.1 → 1.10.0

package/ts/mod_matrix/helpers.matrixconfig.ts

@@ -0,0 +1,222 @@
+import {
+  configuredAssemblyTargets,
+  resolveBuildTargets,
+  targetAliasMap,
+  type INormalizedTarget,
+  type ITsrustConfig,
+} from '../mod_cli/helpers.targets.js';
+
+export const matrixHostKeys = [
+  'linux_amd64',
+  'linux_arm64',
+  'macos_amd64',
+  'macos_arm64',
+] as const;
+
+export type TMatrixHost = (typeof matrixHostKeys)[number];
+
+export interface ITsrustLocalMatrixBuilderConfig {
+  transport: 'local';
+}
+
+export interface ITsrustSshMatrixBuilderConfig {
+  transport: 'ssh';
+  destinationEnv: string;
+  temporaryRootEnv: string;
+}
+
+export type TTsrustMatrixBuilderConfig =
+  | ITsrustLocalMatrixBuilderConfig
+  | ITsrustSshMatrixBuilderConfig;
+
+export interface ITsrustMatrixConfig {
+  builders: Partial<Record<TMatrixHost, TTsrustMatrixBuilderConfig>>;
+  smokeTestArgs?: string[];
+  forwardEnvironment?: string[];
+}
+
+export interface IResolvedMatrixWorker {
+  host: TMatrixHost;
+  hostTriple: string;
+  config: TTsrustMatrixBuilderConfig;
+  targets: INormalizedTarget[];
+}
+
+export interface IResolvedMatrixPlan {
+  workers: IResolvedMatrixWorker[];
+  expectedTargets: INormalizedTarget[];
+  smokeTestArgs?: string[];
+  forwardEnvironment: string[];
+}
+
+const environmentNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const matrixHostKeySet = new Set<string>(matrixHostKeys);
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  !!valueArg && typeof valueArg === 'object' && !Array.isArray(valueArg);
+
+const assertClosedKeys = (
+  valueArg: Record<string, unknown>,
+  allowedKeysArg: string[],
+  labelArg: string,
+): void => {
+  const allowedKeys = new Set(allowedKeysArg);
+  const unexpectedKeys = Object.keys(valueArg).filter((key) => !allowedKeys.has(key));
+  if (unexpectedKeys.length > 0) {
+    throw new Error(`${labelArg} contains unsupported keys: ${unexpectedKeys.join(', ')}`);
+  }
+};
+
+const validateBuilder = (
+  hostArg: TMatrixHost,
+  valueArg: unknown,
+): TTsrustMatrixBuilderConfig => {
+  if (!isRecord(valueArg)) {
+    throw new Error(`matrix.builders.${hostArg} must be an object`);
+  }
+  if (valueArg.transport === 'local') {
+    assertClosedKeys(valueArg, ['transport'], `matrix.builders.${hostArg}`);
+    return { transport: 'local' };
+  }
+  if (valueArg.transport === 'ssh') {
+    assertClosedKeys(
+      valueArg,
+      ['transport', 'destinationEnv', 'temporaryRootEnv'],
+      `matrix.builders.${hostArg}`,
+    );
+    if (
+      typeof valueArg.destinationEnv !== 'string' ||
+      !environmentNamePattern.test(valueArg.destinationEnv)
+    ) {
+      throw new Error(
+        `matrix.builders.${hostArg}.destinationEnv must name an environment variable`,
+      );
+    }
+    if (
+      typeof valueArg.temporaryRootEnv !== 'string' ||
+      !environmentNamePattern.test(valueArg.temporaryRootEnv)
+    ) {
+      throw new Error(
+        `matrix.builders.${hostArg}.temporaryRootEnv must name an environment variable`,
+      );
+    }
+    return {
+      transport: 'ssh',
+      destinationEnv: valueArg.destinationEnv,
+      temporaryRootEnv: valueArg.temporaryRootEnv,
+    };
+  }
+  throw new Error(`matrix.builders.${hostArg}.transport must be local or ssh`);
+};
+
+const validateSmokeTestArgs = (valueArg: unknown): string[] | undefined => {
+  if (valueArg === undefined) return undefined;
+  if (
+    !Array.isArray(valueArg) ||
+    valueArg.length === 0 ||
+    valueArg.some(
+      (argument) =>
+        typeof argument !== 'string' || argument.includes('\0') || /[\r\n]/.test(argument),
+    )
+  ) {
+    throw new Error('matrix.smokeTestArgs must be a non-empty array of single-line strings');
+  }
+  return [...valueArg];
+};
+
+const validateForwardEnvironment = (valueArg: unknown): string[] => {
+  if (valueArg === undefined) return [];
+  if (
+    !Array.isArray(valueArg) ||
+    valueArg.some(
+      (environmentName) =>
+        typeof environmentName !== 'string' ||
+        !environmentNamePattern.test(environmentName),
+    )
+  ) {
+    throw new Error('matrix.forwardEnvironment must contain environment variable names');
+  }
+  return [...new Set(valueArg)];
+};
+
+export const resolveMatrixPlan = (configArg: ITsrustConfig): IResolvedMatrixPlan => {
+  const matrixValue = configArg.matrix as unknown;
+  if (!isRecord(matrixValue)) {
+    throw new Error('tsrust matrix commands require a matrix configuration');
+  }
+  assertClosedKeys(
+    matrixValue,
+    ['builders', 'smokeTestArgs', 'forwardEnvironment'],
+    'matrix',
+  );
+  if (!isRecord(matrixValue.builders) || Object.keys(matrixValue.builders).length === 0) {
+    throw new Error('matrix.builders must define at least one build worker');
+  }
+
+  const workers: IResolvedMatrixWorker[] = [];
+  let localWorkerCount = 0;
+  for (const [host, rawBuilder] of Object.entries(matrixValue.builders)) {
+    if (!matrixHostKeySet.has(host)) {
+      throw new Error(`Unsupported matrix builder host: ${host}`);
+    }
+    const matrixHost = host as TMatrixHost;
+    const builderConfig = validateBuilder(matrixHost, rawBuilder);
+    if (builderConfig.transport === 'local') localWorkerCount += 1;
+    const hostTriple = targetAliasMap[matrixHost];
+    const targets = resolveBuildTargets(configArg, hostTriple);
+    if (targets.length === 0) {
+      throw new Error(`matrix builder ${matrixHost} has no configured targets`);
+    }
+    const expectedFamily = matrixHost.startsWith('linux_') ? 'linux' : 'macos';
+    const crossFamilyTarget = targets.find(
+      (target) => !target.friendly.startsWith(`${expectedFamily}_`),
+    );
+    if (crossFamilyTarget) {
+      throw new Error(
+        `matrix builder ${matrixHost} cannot own cross-family target ${crossFamilyTarget.friendly}`,
+      );
+    }
+    workers.push({ host: matrixHost, hostTriple, config: builderConfig, targets });
+  }
+  if (localWorkerCount > 1) {
+    throw new Error('matrix.builders may define at most one local worker');
+  }
+
+  const expectedTargets = configuredAssemblyTargets(configArg);
+  if (expectedTargets.length === 0) {
+    throw new Error('tsrust matrix commands require configured targets');
+  }
+  const expectedByTriple = new Map(expectedTargets.map((target) => [target.triple, target]));
+  const ownerByTriple = new Map<string, TMatrixHost>();
+  for (const worker of workers) {
+    for (const target of worker.targets) {
+      if (!expectedByTriple.has(target.triple)) {
+        throw new Error(
+          `matrix builder ${worker.host} selected unexpected target ${target.friendly}`,
+        );
+      }
+      const existingOwner = ownerByTriple.get(target.triple);
+      if (existingOwner) {
+        throw new Error(
+          `matrix target ${target.friendly} is assigned to both ${existingOwner} and ${worker.host}`,
+        );
+      }
+      ownerByTriple.set(target.triple, worker.host);
+    }
+  }
+  const missingTargets = expectedTargets.filter((target) => !ownerByTriple.has(target.triple));
+  if (missingTargets.length > 0) {
+    throw new Error(
+      `matrix builders do not cover configured targets: ${missingTargets
+        .map((target) => target.friendly)
+        .join(', ')}`,
+    );
+  }
+
+  return {
+    workers,
+    expectedTargets,
+    smokeTestArgs: validateSmokeTestArgs(matrixValue.smokeTestArgs),
+    forwardEnvironment: validateForwardEnvironment(matrixValue.forwardEnvironment),
+  };
+};

package/ts/mod_matrix/index.ts

@@ -0,0 +1,23 @@
+export {
+  MatrixCommandRunner,
+  type IMatrixCommandOptions,
+  type IMatrixCommandResult,
+  type IMatrixCommandRunner,
+} from './classes.matrixcommandrunner.js';
+export {
+  NativeMatrixBuilder,
+  type INativeMatrixBuilderOptions,
+  type INativeMatrixBuildResult,
+  type INativeMatrixCheckResult,
+} from './classes.nativematrixbuilder.js';
+export {
+  matrixHostKeys,
+  resolveMatrixPlan,
+  type IResolvedMatrixPlan,
+  type IResolvedMatrixWorker,
+  type ITsrustLocalMatrixBuilderConfig,
+  type ITsrustMatrixConfig,
+  type ITsrustSshMatrixBuilderConfig,
+  type TMatrixHost,
+  type TTsrustMatrixBuilderConfig,
+} from './helpers.matrixconfig.js';

package/ts/mod_provenance/classes.gitstate.ts

@@ -7,6 +7,7 @@ export interface IGitSnapshot {
   available: boolean;
   commit: string;
   status: string;
+  unsafeIndexFlags?: string;
 }
 
 export async function captureGitSnapshot(cwdArg: string): Promise<IGitSnapshot> {
@@ -17,7 +18,7 @@ export async function captureGitSnapshot(cwdArg: string): Promise<IGitSnapshot>
     });
     commit = result.stdout.trim();
   } catch {
-    return { available: false, commit: 'unknown', status: '' };
+    return { available: false, commit: 'unknown', status: '', unsafeIndexFlags: '' };
   }
   try {
     const status = await execFile(
@@ -25,10 +26,19 @@ export async function captureGitSnapshot(cwdArg: string): Promise<IGitSnapshot>
       ['-C', cwdArg, 'status', '--porcelain=v1', '--untracked-files=all'],
       { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 },
     );
+    const index = await execFile('git', ['-C', cwdArg, 'ls-files', '-v', '-z'], {
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    const unsafeIndexFlags = index.stdout
+      .split('\0')
+      .filter((entry) => entry.length > 0 && !entry.startsWith('H '))
+      .join('\0');
     return {
       available: true,
       commit,
       status: status.stdout,
+      unsafeIndexFlags,
     };
   } catch {
     throw new Error('Failed to inspect Git worktree state');
@@ -42,7 +52,8 @@ export function assertGitSnapshotUnchanged(
   if (
     beforeArg.available !== afterArg.available ||
     beforeArg.commit !== afterArg.commit ||
-    beforeArg.status !== afterArg.status
+    beforeArg.status !== afterArg.status ||
+    (beforeArg.unsafeIndexFlags || '') !== (afterArg.unsafeIndexFlags || '')
   ) {
     throw new Error('Git source state changed while Cargo was building');
   }

package/ts/mod_provenance/classes.provenancestore.ts

@@ -7,6 +7,7 @@ import { getHostIdentity, isLocalProcessRunning } from './helpers.owneridentity.
 
 const SIDECAR_FORMAT = 'tsrust.build-provenance.v2';
 export const PROVENANCE_SIDECAR_SUFFIX = '.tsrust-build.json';
+export const MAX_PROVENANCE_SIDECAR_BYTES = 1024 * 1024;
 
 interface IProvenanceSidecar {
   format: typeof SIDECAR_FORMAT;
@@ -154,6 +155,9 @@ export class ProvenanceStore {
     if (!sidecar.isFile() || sidecar.isSymbolicLink()) {
       throw new Error(`Provenance sidecar is not a regular file: ${sidecarPath}`);
     }
+    if (sidecar.size > MAX_PROVENANCE_SIDECAR_BYTES) {
+      throw new Error(`Provenance sidecar exceeds the size limit: ${sidecarPath}`);
+    }
     let parsed: unknown;
     try {
       parsed = JSON.parse(await fs.promises.readFile(sidecarPath, 'utf8'));

package/ts/mod_provenance/index.ts

@@ -6,5 +6,6 @@ export {
 export {
   ProvenanceStore,
   PROVENANCE_SIDECAR_SUFFIX,
+  MAX_PROVENANCE_SIDECAR_BYTES,
 } from './classes.provenancestore.js';
 export { getHostIdentity, isLocalProcessRunning } from './helpers.owneridentity.js';

package/ts/mod_toolchain/classes.toolchainmanager.ts

@@ -1,7 +1,16 @@
+import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as plugins from '../plugins.js';
+import { getHostIdentity, isLocalProcessRunning } from '../mod_provenance/index.js';
+
+interface IToolchainInstallLock {
+  format: 'tsrust.toolchain-install-lock.v1';
+  pid: number;
+  hostIdentity: string;
+  token: string;
+}
 
 export class ToolchainManager {
   public static TOOLCHAIN_DIR = '/tmp/tsrust_toolchain';
@@ -17,6 +26,173 @@ export class ToolchainManager {
     });
   }
 
+  private async ensureSecureToolchainDirectory(): Promise<void> {
+    await fs.promises.mkdir(ToolchainManager.TOOLCHAIN_DIR, {
+      recursive: true,
+      mode: 0o700,
+    });
+    const directory = await fs.promises.lstat(ToolchainManager.TOOLCHAIN_DIR);
+    if (!directory.isDirectory() || directory.isSymbolicLink()) {
+      throw new Error('Bundled Rust toolchain root is not a regular directory');
+    }
+    if (typeof process.getuid === 'function' && directory.uid !== process.getuid()) {
+      throw new Error('Bundled Rust toolchain root is owned by another user');
+    }
+    await fs.promises.chmod(ToolchainManager.TOOLCHAIN_DIR, 0o700);
+    const physicalParent = await fs.promises.realpath(
+      path.dirname(ToolchainManager.TOOLCHAIN_DIR),
+    );
+    const expectedPhysicalPath = path.join(
+      physicalParent,
+      path.basename(ToolchainManager.TOOLCHAIN_DIR),
+    );
+    if ((await fs.promises.realpath(ToolchainManager.TOOLCHAIN_DIR)) !== expectedPhysicalPath) {
+      throw new Error('Bundled Rust toolchain root traverses a symbolic link');
+    }
+  }
+
+  private async isSecureToolchainExecutable(filePathArg: string): Promise<boolean> {
+    let entry: fs.Stats;
+    try {
+      entry = await fs.promises.lstat(filePathArg);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+      throw error;
+    }
+    if (!entry.isFile() && !entry.isSymbolicLink()) {
+      throw new Error(`Bundled Rust toolchain entry is not a file: ${filePathArg}`);
+    }
+    const resolvedPath = await fs.promises.realpath(filePathArg);
+    const relativePath = path.relative(
+      await fs.promises.realpath(ToolchainManager.TOOLCHAIN_DIR),
+      resolvedPath,
+    );
+    if (
+      relativePath === '' ||
+      relativePath.startsWith('..') ||
+      path.isAbsolute(relativePath)
+    ) {
+      throw new Error(`Bundled Rust toolchain entry escapes its root: ${filePathArg}`);
+    }
+    const resolved = await fs.promises.stat(resolvedPath);
+    if (!resolved.isFile() || (resolved.mode & 0o111) === 0 || (resolved.mode & 0o022) !== 0) {
+      throw new Error(`Bundled Rust toolchain executable is unsafe: ${filePathArg}`);
+    }
+    if (typeof process.getuid === 'function' && resolved.uid !== process.getuid()) {
+      throw new Error(`Bundled Rust toolchain executable is owned by another user: ${filePathArg}`);
+    }
+    return true;
+  }
+
+  private async acquireInstallLock(): Promise<IToolchainInstallLock> {
+    const lockPath = `${ToolchainManager.TOOLCHAIN_DIR}.install.lock`;
+    const lockDirectory = path.dirname(lockPath);
+    const temporaryPrefix = `${path.basename(lockPath)}.`;
+    const hostIdentity = getHostIdentity();
+    for (const entry of await fs.promises.readdir(lockDirectory, { withFileTypes: true })) {
+      if (!entry.name.startsWith(temporaryPrefix) || !entry.name.endsWith('.tmp')) continue;
+      const suffix = entry.name.slice(temporaryPrefix.length, -'.tmp'.length);
+      const [entryHostIdentity, pidText, token, ...unexpected] = suffix.split('.');
+      const pid = Number(pidText);
+      if (
+        unexpected.length > 0 ||
+        entryHostIdentity !== hostIdentity ||
+        !Number.isSafeInteger(pid) ||
+        pid <= 0 ||
+        !/^[a-f0-9-]{36}$/.test(token || '') ||
+        isLocalProcessRunning(pid)
+      ) {
+        continue;
+      }
+      const temporaryPath = path.join(lockDirectory, entry.name);
+      const temporary = await fs.promises.lstat(temporaryPath);
+      if (
+        temporary.isFile() &&
+        !temporary.isSymbolicLink() &&
+        (typeof process.getuid !== 'function' || temporary.uid === process.getuid())
+      ) {
+        await fs.promises.rm(temporaryPath, { force: true });
+      }
+    }
+    const deadline = Date.now() + 5 * 60 * 1000;
+    while (Date.now() < deadline) {
+      const owner: IToolchainInstallLock = {
+        format: 'tsrust.toolchain-install-lock.v1',
+        pid: process.pid,
+        hostIdentity,
+        token: crypto.randomUUID(),
+      };
+      const temporaryPath = `${lockPath}.${owner.hostIdentity}.${owner.pid}.${owner.token}.tmp`;
+      try {
+        const handle = await fs.promises.open(temporaryPath, 'wx', 0o600);
+        try {
+          await handle.writeFile(`${JSON.stringify(owner)}\n`, 'utf8');
+          await handle.sync();
+        } finally {
+          await handle.close();
+        }
+        try {
+          await fs.promises.link(temporaryPath, lockPath);
+          return owner;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        }
+      } finally {
+        await fs.promises.rm(temporaryPath, { force: true });
+      }
+
+      let lock: fs.Stats;
+      let contents: string;
+      try {
+        lock = await fs.promises.lstat(lockPath);
+        contents = await fs.promises.readFile(lockPath, 'utf8');
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw error;
+      }
+      if (
+        !lock.isFile() ||
+        lock.isSymbolicLink() ||
+        (typeof process.getuid === 'function' && lock.uid !== process.getuid()) ||
+        (lock.mode & 0o077) !== 0 ||
+        lock.size > 4096
+      ) {
+        throw new Error(`Bundled Rust toolchain install lock is unsafe: ${lockPath}`);
+      }
+      let existing: IToolchainInstallLock;
+      try {
+        existing = JSON.parse(contents) as IToolchainInstallLock;
+      } catch {
+        throw new Error(`Bundled Rust toolchain install lock is invalid: ${lockPath}`);
+      }
+      if (
+        existing.format !== 'tsrust.toolchain-install-lock.v1' ||
+        !Number.isSafeInteger(existing.pid) ||
+        existing.pid <= 0 ||
+        !/^[a-f0-9]{64}$/.test(existing.hostIdentity) ||
+        !/^[a-f0-9-]{36}$/.test(existing.token)
+      ) {
+        throw new Error(`Bundled Rust toolchain install lock is invalid: ${lockPath}`);
+      }
+      if (existing.hostIdentity === hostIdentity && !isLocalProcessRunning(existing.pid)) {
+        throw new Error(
+          `Bundled Rust toolchain install lock is stale; inspect and remove ${lockPath} before retrying`,
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+    throw new Error('Timed out waiting for the bundled Rust toolchain install lock');
+  }
+
+  private async releaseInstallLock(ownerArg: IToolchainInstallLock): Promise<void> {
+    const lockPath = `${ToolchainManager.TOOLCHAIN_DIR}.install.lock`;
+    const contents = JSON.parse(await fs.promises.readFile(lockPath, 'utf8')) as IToolchainInstallLock;
+    if (contents.token !== ownerArg.token) {
+      throw new Error('Bundled Rust toolchain install lock ownership changed');
+    }
+    await fs.promises.unlink(lockPath);
+  }
+
   /**
    * Returns the Rust host triple for the current platform.
    */
@@ -37,73 +213,90 @@ export class ToolchainManager {
   /**
    * Checks if the bundled toolchain is already installed at TOOLCHAIN_DIR.
    */
+  private async isInstalledUnlocked(): Promise<boolean> {
+    await this.ensureSecureToolchainDirectory();
+    return (
+      (await this.isSecureToolchainExecutable(path.join(ToolchainManager.BIN_DIR, 'cargo'))) &&
+      (await this.isSecureToolchainExecutable(path.join(ToolchainManager.BIN_DIR, 'rustup')))
+    );
+  }
+
   public async isInstalled(): Promise<boolean> {
-    const cargoPath = path.join(ToolchainManager.BIN_DIR, 'cargo');
+    const lockOwner = await this.acquireInstallLock();
     try {
-      const stat = await fs.promises.stat(cargoPath);
-      return stat.isFile();
-    } catch {
-      return false;
+      return await this.isInstalledUnlocked();
+    } finally {
+      await this.releaseInstallLock(lockOwner);
     }
   }
 
   /**
    * Downloads rustup-init and installs a minimal Rust toolchain to TOOLCHAIN_DIR.
    */
-  public async install(): Promise<void> {
+  private async installUnlocked(): Promise<void> {
+    await this.ensureSecureToolchainDirectory();
     const triple = this.getHostTriple();
     const rustupInitUrl = `https://static.rust-lang.org/rustup/dist/${triple}/rustup-init`;
     const rustupInitPath = path.join(ToolchainManager.TOOLCHAIN_DIR, 'rustup-init');
 
-    // Ensure toolchain directory exists
-    await fs.promises.mkdir(ToolchainManager.TOOLCHAIN_DIR, { recursive: true });
+    await fs.promises.rm(rustupInitPath, { force: true });
 
-    console.log(`Downloading rustup-init for ${triple}...`);
-    const downloadResult = await this.shell.exec(
-      `curl -sSf -o ${rustupInitPath} ${rustupInitUrl} && chmod +x ${rustupInitPath}`
-    );
-    if (downloadResult.exitCode !== 0) {
-      throw new Error(`Failed to download rustup-init: ${downloadResult.stdout}`);
-    }
+    try {
+      console.log(`Downloading rustup-init for ${triple}...`);
+      const downloadResult = await this.shell.exec(
+        `curl -sSf -o ${rustupInitPath} ${rustupInitUrl} && chmod +x ${rustupInitPath}`
+      );
+      if (downloadResult.exitCode !== 0) {
+        throw new Error(`Failed to download rustup-init: ${downloadResult.stdout}`);
+      }
 
-    console.log('Installing minimal Rust toolchain to /tmp/tsrust_toolchain/...');
-    const installCmd = [
-      `RUSTUP_HOME="${ToolchainManager.RUSTUP_HOME}"`,
-      `CARGO_HOME="${ToolchainManager.CARGO_HOME}"`,
-      rustupInitPath,
-      '-y',
-      '--default-toolchain stable',
-      '--profile minimal',
-      '--no-modify-path',
-    ].join(' ');
-
-    const installResult = await this.shell.exec(installCmd);
-    if (installResult.exitCode !== 0) {
-      throw new Error(`Failed to install Rust toolchain: ${installResult.stdout}`);
-    }
+      console.log('Installing minimal Rust toolchain to /tmp/tsrust_toolchain/...');
+      const installCmd = [
+        `RUSTUP_HOME="${ToolchainManager.RUSTUP_HOME}"`,
+        `CARGO_HOME="${ToolchainManager.CARGO_HOME}"`,
+        rustupInitPath,
+        '-y',
+        '--default-toolchain stable',
+        '--profile minimal',
+        '--no-modify-path',
+      ].join(' ');
 
-    // Verify installation
-    const verifyResult = await this.shell.execSilent(
-      `${this.getEnvPrefix()}cargo --version`
-    );
-    if (verifyResult.exitCode !== 0) {
-      throw new Error('Rust toolchain installation verification failed.');
+      const installResult = await this.shell.exec(installCmd);
+      if (installResult.exitCode !== 0) {
+        throw new Error(`Failed to install Rust toolchain: ${installResult.stdout}`);
+      }
+      if (!(await this.isInstalledUnlocked())) {
+        throw new Error('Installed bundled Rust toolchain failed ownership validation.');
+      }
+
+      const verifyResult = await this.shell.execSilent(
+        `${this.getEnvPrefix()}cargo --version`
+      );
+      if (verifyResult.exitCode !== 0) {
+        throw new Error('Rust toolchain installation verification failed.');
+      }
+      console.log(`Installed: ${verifyResult.stdout.trim()}`);
+    } finally {
+      await fs.promises.rm(rustupInitPath, { force: true });
     }
-    console.log(`Installed: ${verifyResult.stdout.trim()}`);
+  }
 
-    // Clean up rustup-init binary
-    await fs.promises.unlink(rustupInitPath).catch(() => {});
+  public async install(): Promise<void> {
+    const lockOwner = await this.acquireInstallLock();
+    try {
+      if (await this.isInstalledUnlocked()) return;
+      await this.installUnlocked();
+    } finally {
+      await this.releaseInstallLock(lockOwner);
+    }
   }
 
   /**
    * Ensures the bundled toolchain is installed. Downloads if not present.
    */
   public async ensureInstalled(): Promise<void> {
-    if (await this.isInstalled()) {
-      console.log('Using bundled Rust toolchain from /tmp/tsrust_toolchain/');
-      return;
-    }
     await this.install();
+    console.log('Using bundled Rust toolchain from /tmp/tsrust_toolchain/');
   }
 
   /**