@git.zone/cli 3.2.0 → 4.0.0

package/ts/mod_services/classes.dockercontainer.ts

@@ -1,6 +1,17 @@
 import * as plugins from './mod.plugins.js';
 import * as helpers from './helpers.js';
 import { logger } from '../gitzone.logging.js';
+import {
+  getServiceDataDirectory,
+  markerProvesServiceDataDirectory,
+  readServiceDataMarker,
+  serviceBindOperation,
+  serviceDataOwner,
+  serviceOperationLabel,
+  serviceToolLabel,
+  type TServiceName,
+} from './classes.servicedatamarker.js';
+import { withServiceDataOperationLock } from './classes.interprocesslock.js';
 
 export type ContainerStatus = 'running' | 'stopped' | 'not_exists';
 
@@ -28,6 +39,8 @@ export interface IDockerRunOptions {
 export interface IDockerCreateArgvOptions extends Omit<IDockerRunOptions, 'command'> {
   /** Container command passed as exact argv entries. */
   command?: readonly string[];
+  user?: string;
+  entrypoint?: string;
 }
 
 export interface IDockerExecArgvOptions {
@@ -47,6 +60,130 @@ export interface IDockerArgvExecutionErrorOptions {
   signal?: NodeJS.Signals;
 }
 
+export interface IFencedBindOperationOptions {
+  image: string;
+  hostPath: string;
+  containerPath: string;
+  entrypoint: string;
+  command: readonly string[];
+  labels: Record<string, string>;
+  executionOptions: () => IDockerExecArgvOptions;
+  rollbackTimeoutMs?: number;
+}
+
+interface IFencedBindRuntimeOptions extends IFencedBindOperationOptions {
+  name: string;
+  labels: Record<string, string>;
+}
+
+export const fencedBindOperationSpecLabel = 'git.zone.operation-spec';
+export const fencedBindOperationInvocationLabel = 'git.zone.operation-invocation';
+export const fencedBindOperationSpec = '1';
+export const fencedBindOperationStaleAfterMs = 60_000;
+
+/** One Docker-reserved lock name for every canonical host bind target. */
+export const getFencedBindOperationName = (hostPathArg: string): string => {
+  const targetHash = plugins.crypto
+    .createHash('sha256')
+    .update(plugins.path.resolve(hostPathArg))
+    .digest('hex')
+    .slice(0, 24);
+  return `gitzone-services-bind-${targetHash}`;
+};
+
+export interface IRemoveDataDirectoryOptions {
+  projectPath: string;
+  service: TServiceName;
+  preDeleteCheck?: () => Promise<void>;
+}
+
+interface IServiceDataDeletionIntent {
+  owner: typeof serviceDataOwner;
+  kind: 'service-data-deletion';
+  schemaVersion: 1;
+  projectPath: string;
+  service: TServiceName;
+  canonicalPath: string;
+  quarantinePath: string;
+  token: string;
+  createdAt: string;
+}
+
+const getServiceDataDeletionIntentPath = (
+  projectPathArg: string,
+  serviceArg: TServiceName,
+): string =>
+  plugins.path.join(
+    plugins.path.resolve(projectPathArg),
+    '.nogit',
+    `.gitzone-delete-${serviceArg}.json`,
+  );
+
+const getServiceDataQuarantinePath = (canonicalPathArg: string, tokenArg: string): string =>
+  `${plugins.path.resolve(canonicalPathArg)}.gitzone-delete-${tokenArg}`;
+
+const readServiceDataDeletionIntent = async (
+  projectPathArg: string,
+  serviceArg: TServiceName,
+): Promise<IServiceDataDeletionIntent | undefined> => {
+  const projectPath = plugins.path.resolve(projectPathArg);
+  const canonicalPath = getServiceDataDirectory(projectPath, serviceArg);
+  const intentPath = getServiceDataDeletionIntentPath(projectPath, serviceArg);
+  try {
+    const stats = await plugins.fs.lstat(intentPath);
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+      throw new Error(`Refusing non-regular service data deletion intent: ${intentPath}`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await plugins.fs.readFile(intentPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Refusing invalid service data deletion intent: ${intentPath}`, {
+      cause: error,
+    });
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Refusing invalid service data deletion intent: ${intentPath}`);
+  }
+  const intent = parsed as Record<string, unknown>;
+  const allowedKeys = [
+    'owner',
+    'kind',
+    'schemaVersion',
+    'projectPath',
+    'service',
+    'canonicalPath',
+    'quarantinePath',
+    'token',
+    'createdAt',
+  ];
+  const token = intent.token;
+  if (
+    Object.keys(intent).length !== allowedKeys.length ||
+    !Object.keys(intent).every((keyArg) => allowedKeys.includes(keyArg)) ||
+    intent.owner !== serviceDataOwner ||
+    intent.kind !== 'service-data-deletion' ||
+    intent.schemaVersion !== 1 ||
+    intent.projectPath !== projectPath ||
+    intent.service !== serviceArg ||
+    intent.canonicalPath !== canonicalPath ||
+    typeof token !== 'string' ||
+    !/^[a-f0-9]{32}$/u.test(token) ||
+    intent.quarantinePath !== getServiceDataQuarantinePath(canonicalPath, token) ||
+    typeof intent.createdAt !== 'string' ||
+    !intent.createdAt
+  ) {
+    throw new Error(`Refusing invalid service data deletion intent: ${intentPath}`);
+  }
+  return intent as unknown as IServiceDataDeletionIntent;
+};
+
 /** Sanitised failure from the shell-free Docker execution path. */
 export class DockerArgvExecutionError extends Error {
   public readonly exitCode?: number;
@@ -78,6 +215,38 @@ export interface IContainerInspectInfo {
   mountSources: string[];
 }
 
+const isExactStoppedBindHelperForTarget = (
+  containerArg: IContainerInspectInfo,
+  hostPathArg: string,
+  optionsArg: IRemoveDataDirectoryOptions,
+): boolean => {
+  const invocationId = containerArg.labels[fencedBindOperationInvocationLabel];
+  const expectedLabels: Record<string, string> = {
+    'git.zone.tool': serviceToolLabel,
+    'git.zone.service': optionsArg.service,
+    'git.zone.project-path': plugins.path.resolve(optionsArg.projectPath),
+    'git.zone.data-path': plugins.path.resolve(hostPathArg),
+    'git.zone.safe-to-prune': 'false',
+    [serviceOperationLabel]: serviceBindOperation,
+    [fencedBindOperationSpecLabel]: fencedBindOperationSpec,
+    [fencedBindOperationInvocationLabel]: invocationId,
+  };
+  const actualGitZoneLabels = Object.entries(containerArg.labels).filter(([keyArg]) =>
+    keyArg.startsWith('git.zone.'),
+  );
+  return (
+    !containerArg.running &&
+    containerArg.name === getFencedBindOperationName(hostPathArg) &&
+    /^[a-f0-9]{32}$/u.test(invocationId || '') &&
+    actualGitZoneLabels.length === Object.keys(expectedLabels).length &&
+    Object.entries(expectedLabels).every(
+      ([keyArg, valueArg]) => containerArg.labels[keyArg] === valueArg,
+    ) &&
+    containerArg.mountSources.length === 1 &&
+    plugins.path.resolve(containerArg.mountSources[0]) === plugins.path.resolve(hostPathArg)
+  );
+};
+
 /** Single-quote a value for safe interpolation into a bash command. */
 export const shellQuote = (valueArg: string): string => `'${valueArg.replace(/'/g, `'"'"'`)}'`;
 
@@ -141,6 +310,104 @@ export const matchDockerUlimits = (
   return 'match';
 };
 
+const isUnknownRecord = (valueArg: unknown): valueArg is Record<string, any> => {
+  return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+};
+
+interface IFencedBindInspection {
+  id: string;
+  name: string;
+  createdAtMs: number;
+  image: string;
+  running: boolean;
+  status: string;
+  exitCode: number;
+  user: string;
+  entrypoint: string[];
+  command: string[];
+  labels: Record<string, string>;
+  mounts: Array<{ source: string; destination: string; readWrite: boolean }>;
+}
+
+const parseFencedBindInspection = (
+  stdoutArg: string,
+  expectedNameArg?: string,
+): IFencedBindInspection => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdoutArg);
+  } catch {
+    throw new Error(`Docker returned an invalid bind-operation inspection for ${expectedNameArg}.`);
+  }
+  if (!Array.isArray(parsed) || parsed.length !== 1 || !isUnknownRecord(parsed[0])) {
+    throw new Error(`Docker returned an invalid bind-operation inspection for ${expectedNameArg}.`);
+  }
+  const inspected = parsed[0];
+  const config = inspected.Config;
+  const state = inspected.State;
+  const normalizedName = String(inspected.Name || '').replace(/^\//u, '');
+  const createdAtMs = Date.parse(String(inspected.Created || ''));
+  if (
+    typeof inspected.Id !== 'string' ||
+    !/^[a-f0-9]{64}$/u.test(inspected.Id) ||
+    !/^gitzone-services-bind-[a-f0-9]{24}$/u.test(normalizedName) ||
+    (expectedNameArg !== undefined && normalizedName !== expectedNameArg) ||
+    !Number.isFinite(createdAtMs) ||
+    !isUnknownRecord(config) ||
+    typeof config.Image !== 'string' ||
+    typeof config.User !== 'string' ||
+    !Array.isArray(config.Entrypoint) ||
+    !config.Entrypoint.every((entry: unknown) => typeof entry === 'string') ||
+    !Array.isArray(config.Cmd) ||
+    !config.Cmd.every((entry: unknown) => typeof entry === 'string') ||
+    !isUnknownRecord(config.Labels) ||
+    !isUnknownRecord(state) ||
+    typeof state.Running !== 'boolean' ||
+    typeof state.Status !== 'string' ||
+    typeof state.ExitCode !== 'number' ||
+    !Array.isArray(inspected.Mounts)
+  ) {
+    throw new Error(`Docker returned an invalid bind-operation inspection for ${expectedNameArg}.`);
+  }
+  const labels: Record<string, string> = {};
+  for (const [key, value] of Object.entries(config.Labels)) {
+    if (typeof value !== 'string') {
+      throw new Error(`Docker returned an invalid bind-operation inspection for ${expectedNameArg}.`);
+    }
+    labels[key] = value;
+  }
+  const mounts = inspected.Mounts.map((mountArg: unknown) => {
+    if (
+      !isUnknownRecord(mountArg) ||
+      mountArg.Type !== 'bind' ||
+      typeof mountArg.Source !== 'string' ||
+      typeof mountArg.Destination !== 'string' ||
+      typeof mountArg.RW !== 'boolean'
+    ) {
+      throw new Error(`Docker returned an invalid bind-operation inspection for ${expectedNameArg}.`);
+    }
+    return {
+      source: plugins.path.resolve(mountArg.Source),
+      destination: mountArg.Destination,
+      readWrite: mountArg.RW,
+    };
+  });
+  return {
+    id: inspected.Id,
+    name: normalizedName,
+    createdAtMs,
+    image: config.Image,
+    running: state.Running,
+    status: state.Status,
+    exitCode: state.ExitCode,
+    user: config.User,
+    entrypoint: [...config.Entrypoint],
+    command: [...config.Cmd],
+    labels,
+    mounts,
+  };
+};
+
 export class DockerContainer {
   private smartshell: plugins.smartshell.Smartshell;
   /**
@@ -152,8 +419,10 @@ export class DockerContainer {
    * @git.zone/tsdocker.
    */
   private queryTimeoutSeconds = 60;
-  /** Longer bound for privileged cleanup, which may delete a large tree. */
+  /** Longer bound for root-helper cleanup, which may delete a large tree. */
   private cleanupTimeoutSeconds = 600;
+  private bindOperationDelay = async (millisecondsArg: number): Promise<void> =>
+    plugins.smartdelay.delayFor(millisecondsArg);
 
   constructor() {
     this.smartshell = new plugins.smartshell.Smartshell({
@@ -259,6 +528,12 @@ export class DockerContainer {
     if (optionsArg.restart) {
       argv.push('--restart', optionsArg.restart);
     }
+    if (optionsArg.user) {
+      argv.push('--user', optionsArg.user);
+    }
+    if (optionsArg.entrypoint) {
+      argv.push('--entrypoint', optionsArg.entrypoint);
+    }
 
     argv.push(optionsArg.image);
     if (optionsArg.command) {
@@ -268,15 +543,332 @@ export class DockerContainer {
     return this.execArgvInternal(argv, executionOptionsArg, childEnvironment);
   }
 
+  private assertFencedBindInspection(
+    inspectionArg: IFencedBindInspection,
+    optionsArg: IFencedBindRuntimeOptions,
+  ): void {
+    const expectedGitZoneLabels = Object.entries(optionsArg.labels).filter(([key]) =>
+      key.startsWith('git.zone.'),
+    );
+    const actualGitZoneLabels = Object.entries(inspectionArg.labels).filter(([key]) =>
+      key.startsWith('git.zone.'),
+    );
+    const labelsMatch =
+      expectedGitZoneLabels.length === actualGitZoneLabels.length &&
+      expectedGitZoneLabels.every(
+        ([key, value]) => inspectionArg.labels[key] === value,
+      );
+    const mountsMatch =
+      inspectionArg.mounts.length === 1 &&
+      inspectionArg.mounts[0].source === plugins.path.resolve(optionsArg.hostPath) &&
+      inspectionArg.mounts[0].destination === optionsArg.containerPath &&
+      inspectionArg.mounts[0].readWrite;
+    if (
+      inspectionArg.name !== optionsArg.name ||
+      inspectionArg.image !== optionsArg.image ||
+      inspectionArg.user !== '0' ||
+      inspectionArg.entrypoint.length !== 1 ||
+      inspectionArg.entrypoint[0] !== optionsArg.entrypoint ||
+      inspectionArg.command.length !== optionsArg.command.length ||
+      !inspectionArg.command.every((entry, index) => entry === optionsArg.command[index]) ||
+      !labelsMatch ||
+      !mountsMatch
+    ) {
+      throw new Error(
+        `Refusing bind-operation container ${optionsArg.name}: exact ownership and configuration are not proven.`,
+      );
+    }
+  }
+
+  private assertRecoverableFencedBindInspection(
+    inspectionArg: IFencedBindInspection,
+    optionsArg: IFencedBindOperationOptions,
+    expectedNameArg: string,
+  ): void {
+    const expectedLabels = {
+      ...optionsArg.labels,
+      [fencedBindOperationSpecLabel]: fencedBindOperationSpec,
+    };
+    const expectedGitZoneLabels = Object.entries(expectedLabels).filter(([key]) =>
+      key.startsWith('git.zone.'),
+    );
+    const actualGitZoneLabels = Object.entries(inspectionArg.labels).filter(([key]) =>
+      key.startsWith('git.zone.'),
+    );
+    const invocationId = inspectionArg.labels[fencedBindOperationInvocationLabel];
+    const labelsMatch =
+      actualGitZoneLabels.length === expectedGitZoneLabels.length + 1 &&
+      expectedGitZoneLabels.every(
+        ([key, value]) => inspectionArg.labels[key] === value,
+      ) &&
+      typeof invocationId === 'string' &&
+      /^[a-f0-9]{32}$/u.test(invocationId);
+    const mountMatches =
+      inspectionArg.mounts.length === 1 &&
+      inspectionArg.mounts[0].source === plugins.path.resolve(optionsArg.hostPath) &&
+      inspectionArg.mounts[0].readWrite;
+    if (
+      inspectionArg.name !== expectedNameArg ||
+      inspectionArg.image !== optionsArg.image ||
+      inspectionArg.user !== '0' ||
+      inspectionArg.entrypoint.length !== 1 ||
+      inspectionArg.entrypoint[0] !== optionsArg.entrypoint ||
+      inspectionArg.command.length !== optionsArg.command.length ||
+      !inspectionArg.command.every(
+        (entryArg, indexArg) => entryArg === optionsArg.command[indexArg],
+      ) ||
+      !labelsMatch ||
+      !mountMatches ||
+      inspectionArg.mounts[0].destination !== optionsArg.containerPath
+    ) {
+      throw new Error(
+        `Refusing bind-operation container ${expectedNameArg}: canonical helper ownership is not proven.`,
+      );
+    }
+  }
+
+  private async readFencedBindInspection(
+    referenceArg: string,
+    expectedNameArg: string,
+    executionOptionsArg: IDockerExecArgvOptions,
+  ): Promise<IFencedBindInspection> {
+    const result = await this.execArgv(['inspect', referenceArg], executionOptionsArg);
+    const inspection = parseFencedBindInspection(result.stdout, expectedNameArg);
+    if (/^[a-f0-9]{64}$/u.test(referenceArg) && inspection.id !== referenceArg) {
+      throw new Error(
+        `Refusing bind-operation container ${expectedNameArg}: its immutable id changed.`,
+      );
+    }
+    return inspection;
+  }
+
+  private async inspectFencedBindOperation(
+    referenceArg: string,
+    optionsArg: IFencedBindRuntimeOptions,
+    executionOptionsArg: IDockerExecArgvOptions,
+  ): Promise<IFencedBindInspection> {
+    const inspection = await this.readFencedBindInspection(
+      referenceArg,
+      optionsArg.name,
+      executionOptionsArg,
+    );
+    this.assertFencedBindInspection(inspection, optionsArg);
+    return inspection;
+  }
+
+  private async discoverFencedBindOperationId(
+    nameArg: string,
+    executionOptionsArg: IDockerExecArgvOptions,
+  ): Promise<string | undefined> {
+    const result = await this.execArgv(
+      [
+        'container',
+        'ls',
+        '-a',
+        '--no-trunc',
+        '--filter',
+        `name=^/${nameArg}$`,
+        '--format',
+        '{{.ID}}',
+      ],
+      executionOptionsArg,
+    );
+    const ids = result.stdout
+      .split(/\r?\n/u)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    if (ids.length === 0) {
+      return undefined;
+    }
+    if (ids.length !== 1 || !/^[a-f0-9]{64}$/u.test(ids[0])) {
+      throw new Error(`Docker returned ambiguous bind-operation identity for ${nameArg}.`);
+    }
+    return ids[0];
+  }
+
+  private async reclaimStaleFencedBindOperation(
+    optionsArg: IFencedBindOperationOptions,
+    nameArg: string,
+  ): Promise<void> {
+    const existingId = await this.discoverFencedBindOperationId(
+      nameArg,
+      optionsArg.executionOptions(),
+    );
+    if (!existingId) {
+      return;
+    }
+    const inspection = await this.readFencedBindInspection(
+      existingId,
+      nameArg,
+      optionsArg.executionOptions(),
+    );
+    this.assertRecoverableFencedBindInspection(inspection, optionsArg, nameArg);
+    if (inspection.running) {
+      throw new Error(`Bind-operation container ${nameArg} is still running.`);
+    }
+    if (inspection.status !== 'created' && inspection.status !== 'exited') {
+      throw new Error(
+        `Refusing bind-operation container ${nameArg}: its stopped state is not proven.`,
+      );
+    }
+    if (Date.now() - inspection.createdAtMs < fencedBindOperationStaleAfterMs) {
+      throw new Error(
+        `Bind-operation container ${nameArg} may belong to another active invocation.`,
+      );
+    }
+    // Non-forced removal is the atomic handoff: if another process starts the
+    // helper after inspection, Docker refuses removal instead of killing it.
+    await this.execArgv(['rm', inspection.id], optionsArg.executionOptions());
+  }
+
+  /**
+   * Run one root bind-mount operation with a stopped-create and immutable-ID fence.
+   * Every ambiguous or failed path proves ownership again before forced removal.
+   */
+  public async runFencedBindOperation(optionsArg: IFencedBindOperationOptions): Promise<void> {
+    if (
+      Object.hasOwn(optionsArg.labels, fencedBindOperationSpecLabel) ||
+      Object.hasOwn(optionsArg.labels, fencedBindOperationInvocationLabel)
+    ) {
+      throw new Error('Fenced bind operation labels contain reserved lifecycle keys.');
+    }
+    if (
+      optionsArg.labels[serviceOperationLabel] !== serviceBindOperation ||
+      optionsArg.labels['git.zone.safe-to-prune'] !== 'false'
+    ) {
+      throw new Error('Fenced bind operation labels do not declare the protected helper contract.');
+    }
+    const operationName = getFencedBindOperationName(optionsArg.hostPath);
+    const invocationId = plugins.crypto.randomBytes(16).toString('hex');
+    const runtimeOptions: IFencedBindRuntimeOptions = {
+      ...optionsArg,
+      name: operationName,
+      labels: {
+        ...optionsArg.labels,
+        [fencedBindOperationSpecLabel]: fencedBindOperationSpec,
+        [fencedBindOperationInvocationLabel]: invocationId,
+      },
+    };
+    await this.reclaimStaleFencedBindOperation(optionsArg, operationName);
+
+    const normalizeError = (errorArg: unknown): Error =>
+      errorArg instanceof Error
+        ? errorArg
+        : new Error('Docker bind operation failed with a non-Error rejection.');
+    const rollbackErrors: Error[] = [];
+    let operationError: Error | undefined;
+    let containerId: string | undefined;
+
+    try {
+      const creation = await this.createArgv(
+        {
+          name: operationName,
+          image: runtimeOptions.image,
+          volumes: {
+            [plugins.path.resolve(runtimeOptions.hostPath)]: runtimeOptions.containerPath,
+          },
+          labels: runtimeOptions.labels,
+          user: '0',
+          entrypoint: runtimeOptions.entrypoint,
+          command: runtimeOptions.command,
+        },
+        runtimeOptions.executionOptions(),
+      );
+      const createdContainerId = creation.stdout.trim();
+      if (!/^[a-f0-9]{64}$/u.test(createdContainerId)) {
+        throw new Error(`Docker returned an invalid id for bind operation ${operationName}.`);
+      }
+      containerId = createdContainerId;
+      const created = await this.inspectFencedBindOperation(
+        containerId,
+        runtimeOptions,
+        runtimeOptions.executionOptions(),
+      );
+      if (created.running || created.status !== 'created') {
+        throw new Error(`Bind-operation container ${operationName} was not created stopped.`);
+      }
+
+      await this.execArgv(
+        ['start', '--attach', containerId],
+        runtimeOptions.executionOptions(),
+      );
+      const completed = await this.inspectFencedBindOperation(
+        containerId,
+        runtimeOptions,
+        runtimeOptions.executionOptions(),
+      );
+      if (completed.running || completed.status !== 'exited' || completed.exitCode !== 0) {
+        throw new Error(`Bind-operation container ${operationName} did not exit successfully.`);
+      }
+      await this.execArgv(['rm', containerId], runtimeOptions.executionOptions());
+      return;
+    } catch (error) {
+      operationError = normalizeError(error);
+    }
+
+    if (!containerId) {
+      const rollbackTimeoutMs = runtimeOptions.rollbackTimeoutMs ?? 5_000;
+      const rollbackDeadlineAt = Date.now() + rollbackTimeoutMs;
+      while (!containerId) {
+        const remainingMs = Math.floor(rollbackDeadlineAt - Date.now());
+        if (remainingMs <= 0) {
+          break;
+        }
+        try {
+          const discoveredId = await this.discoverFencedBindOperationId(
+            operationName,
+            { timeoutMs: remainingMs },
+          );
+          if (discoveredId) {
+            const inspection = await this.inspectFencedBindOperation(
+              discoveredId,
+              runtimeOptions,
+              { timeoutMs: Math.max(1, rollbackDeadlineAt - Date.now()) },
+            );
+            containerId = inspection.id;
+            break;
+          }
+        } catch (error) {
+          rollbackErrors.push(normalizeError(error));
+          break;
+        }
+        const remainingAfterDiscovery = Math.floor(rollbackDeadlineAt - Date.now());
+        if (remainingAfterDiscovery <= 0) {
+          break;
+        }
+        await this.bindOperationDelay(Math.min(100, remainingAfterDiscovery));
+      }
+    }
+    if (containerId) {
+      try {
+        await this.inspectFencedBindOperation(containerId, runtimeOptions, {
+          timeoutMs: runtimeOptions.rollbackTimeoutMs ?? 5_000,
+        });
+        await this.execArgv(['rm', '-f', containerId], {
+          timeoutMs: runtimeOptions.rollbackTimeoutMs ?? 5_000,
+        });
+      } catch (error) {
+        rollbackErrors.push(normalizeError(error));
+      }
+    }
+
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [operationError!, ...rollbackErrors],
+        `Docker bind operation ${operationName} failed and cleanup could not be confirmed.`,
+      );
+    }
+    throw operationError!;
+  }
+
   /**
    * Check if Docker is installed and available
    */
   public async checkDocker(): Promise<boolean> {
     try {
-      // Silent: this must not print to stdout, which would corrupt --json output.
-      const result = await this.smartshell.execSilent('docker --version');
-      return result.exitCode === 0;
-    } catch (error) {
+      await this.execArgv(['--version'], { timeoutMs: this.queryTimeoutSeconds * 1_000 });
+      return true;
+    } catch {
       return false;
     }
   }
@@ -285,29 +877,17 @@ export class DockerContainer {
    * Get container status
    */
   public async getStatus(containerName: string): Promise<ContainerStatus> {
-    try {
-      // Check if running
-      const runningResult = await this.smartshell.exec(
-        `docker ps --format '{{.Names}}' | grep -q "^${containerName}$"`
-      );
-      
-      if (runningResult.exitCode === 0) {
-        return 'running';
-      }
-      
-      // Check if exists but stopped
-      const existsResult = await this.smartshell.exec(
-        `docker ps -a --format '{{.Names}}' | grep -q "^${containerName}$"`
-      );
-      
-      if (existsResult.exitCode === 0) {
-        return 'stopped';
-      }
-      
-      return 'not_exists';
-    } catch (error) {
+    const ids = await this.listIds([`name=^/${containerName}$`]);
+    if (ids.length === 0) {
       return 'not_exists';
     }
+    const matches = (await this.inspectMany(ids)).filter(
+      (containerArg) => containerArg.name === containerName,
+    );
+    if (matches.length !== 1) {
+      throw new Error(`Docker returned ambiguous identity for container ${containerName}.`);
+    }
+    return matches[0].running ? 'running' : 'stopped';
   }
   
   /**
@@ -315,9 +895,11 @@ export class DockerContainer {
    */
   public async start(containerName: string): Promise<boolean> {
     try {
-      const result = await this.smartshell.exec(`docker start ${containerName}`);
-      return result.exitCode === 0;
-    } catch (error) {
+      await this.execArgv(['start', containerName], {
+        timeoutMs: this.queryTimeoutSeconds * 1_000,
+      });
+      return true;
+    } catch {
       return false;
     }
   }
@@ -327,9 +909,11 @@ export class DockerContainer {
    */
   public async stop(containerName: string): Promise<boolean> {
     try {
-      const result = await this.smartshell.exec(`docker stop ${containerName}`);
-      return result.exitCode === 0;
-    } catch (error) {
+      await this.execArgv(['stop', containerName], {
+        timeoutMs: this.queryTimeoutSeconds * 1_000,
+      });
+      return true;
+    } catch {
       return false;
     }
   }
@@ -339,10 +923,11 @@ export class DockerContainer {
    */
   public async remove(containerName: string, force: boolean = false): Promise<boolean> {
     try {
-      const forceFlag = force ? '-f' : '';
-      const result = await this.smartshell.exec(`docker rm ${forceFlag} ${containerName}`);
-      return result.exitCode === 0;
-    } catch (error) {
+      await this.execArgv(['rm', ...(force ? ['-f'] : []), containerName], {
+        timeoutMs: this.queryTimeoutSeconds * 1_000,
+      });
+      return true;
+    } catch {
       return false;
     }
   }
@@ -351,10 +936,10 @@ export class DockerContainer {
    * Run a new container
    */
   public async run(options: IDockerRunOptions): Promise<boolean> {
-    let command = 'docker run -d';
+    let command = `${this.bounded(this.queryTimeoutSeconds)} run -d`;
     
     // Add name
-    command += ` --name ${options.name}`;
+    command += ` --name ${shellQuote(options.name)}`;
     
     // Add ports
     if (options.ports) {
@@ -393,7 +978,7 @@ export class DockerContainer {
     }
     
     // Add image
-    command += ` ${options.image}`;
+    command += ` ${shellQuote(options.image)}`;
     
     // Add command if provided
     if (options.command) {
@@ -460,11 +1045,109 @@ export class DockerContainer {
     }
   }
 
+  /** Exact persisted quarantine path for an interrupted deletion, if present. */
+  public async getPendingDataDeletionPath(
+    projectPathArg: string,
+    serviceArg: TServiceName,
+  ): Promise<string | undefined> {
+    const intent = await readServiceDataDeletionIntent(projectPathArg, serviceArg);
+    if (!intent) {
+      return undefined;
+    }
+    if (await this.assertRegularDeletionDirectory(intent.quarantinePath)) {
+      return intent.quarantinePath;
+    }
+    if (await this.assertRegularDeletionDirectory(intent.canonicalPath)) {
+      return intent.canonicalPath;
+    }
+    // The intent still needs a locked cleanup pass even when deletion finished
+    // just before the process was interrupted.
+    return intent.quarantinePath;
+  }
+
+  private getDataCleanupOperation(
+    hostPathArg: string,
+    imageArg: string,
+    optionsArg: IRemoveDataDirectoryOptions,
+  ): IFencedBindOperationOptions {
+    const hostPath = plugins.path.resolve(hostPathArg);
+    return {
+      image: imageArg,
+      hostPath,
+      containerPath: '/gitzone-target',
+      entrypoint: '/bin/sh',
+      command: [
+        '-c',
+        'rm -rf /gitzone-target/..?* /gitzone-target/.[!.]* /gitzone-target/*',
+      ],
+      labels: {
+        'git.zone.tool': serviceToolLabel,
+        'git.zone.service': optionsArg.service,
+        'git.zone.project-path': plugins.path.resolve(optionsArg.projectPath),
+        'git.zone.data-path': hostPath,
+        'git.zone.safe-to-prune': 'false',
+        [serviceOperationLabel]: serviceBindOperation,
+      },
+      executionOptions: () => ({ timeoutMs: this.cleanupTimeoutSeconds * 1_000 }),
+      rollbackTimeoutMs: this.queryTimeoutSeconds * 1_000,
+    };
+  }
+
+  private async writeServiceDataDeletionIntent(
+    intentArg: IServiceDataDeletionIntent,
+  ): Promise<void> {
+    const intentPath = getServiceDataDeletionIntentPath(
+      intentArg.projectPath,
+      intentArg.service,
+    );
+    const tempPath = `${intentPath}.tmp-${process.pid}-${plugins.crypto
+      .randomBytes(12)
+      .toString('hex')}`;
+    let handle: Awaited<ReturnType<typeof plugins.fs.open>> | undefined;
+    try {
+      handle = await plugins.fs.open(tempPath, 'wx', 0o600);
+      await handle.writeFile(`${JSON.stringify(intentArg, null, 2)}\n`, 'utf8');
+      await handle.sync();
+      await handle.close();
+      handle = undefined;
+      await plugins.fs.rename(tempPath, intentPath);
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      await plugins.fs.rm(tempPath, { force: true }).catch(() => {});
+      throw new Error(`Could not persist service data deletion intent: ${intentPath}`, {
+        cause: error,
+      });
+    }
+  }
+
+  private async assertRegularDeletionDirectory(pathArg: string): Promise<boolean> {
+    try {
+      const stats = await plugins.fs.lstat(pathArg);
+      if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw new Error(`Refusing non-directory service data cleanup target: ${pathArg}`);
+      }
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  private async renameDataDirectory(sourcePathArg: string, targetPathArg: string): Promise<void> {
+    await plugins.fs.rename(sourcePathArg, targetPathArg);
+  }
+
+  private async deleteDataDirectory(pathArg: string): Promise<void> {
+    await plugins.fs.rm(pathArg, { recursive: true, force: true });
+  }
+
   /**
    * Remove a service data directory, escalating to a root one-off container
    * when the invoking user cannot delete the contents.
    *
-   * Service containers write as their own uid (mongod as 999, MinIO as root)
+   * Service containers write as their own uid
    * with restrictive modes, so a plain recursive delete only removes part of the
    * tree. For MongoDB that left a half-deleted, corrupt WiredTiger dataset that
    * crash-looped on the next start — so a partial delete is worse than none.
@@ -473,53 +1156,182 @@ export class DockerContainer {
    * The one-off container mounts only the target directory, so `rm -rf` inside
    * it cannot reach anything else on the host.
    */
-  public async removeDataDirectory(hostPathArg: string, imageArg: string): Promise<void> {
+  public async removeDataDirectory(
+    hostPathArg: string,
+    imageArg: string,
+    optionsArg: IRemoveDataDirectoryOptions,
+  ): Promise<boolean> {
+    return withServiceDataOperationLock(
+      optionsArg.projectPath,
+      optionsArg.service,
+      () => this.removeDataDirectoryLocked(hostPathArg, imageArg, optionsArg),
+    );
+  }
+
+  private async removeDataDirectoryLocked(
+    hostPathArg: string,
+    imageArg: string,
+    optionsArg: IRemoveDataDirectoryOptions,
+  ): Promise<boolean> {
+    await optionsArg.preDeleteCheck?.();
+    const projectPath = plugins.path.resolve(optionsArg.projectPath);
     const hostPath = plugins.path.resolve(hostPathArg);
-    if (!(await plugins.smartfs.directory(hostPath).exists())) {
-      return;
+    if (hostPath !== getServiceDataDirectory(projectPath, optionsArg.service)) {
+      throw new Error(`Refusing cleanup outside the canonical service data path: ${hostPath}`);
+    }
+    for (const pathComponent of [projectPath, plugins.path.dirname(hostPath)]) {
+      const stats = await plugins.fs.lstat(pathComponent);
+      if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw new Error(`Refusing symbolic or non-directory cleanup path component: ${pathComponent}`);
+      }
+    }
+
+    let intent = await readServiceDataDeletionIntent(projectPath, optionsArg.service);
+    let canonicalExists = await this.assertRegularDeletionDirectory(hostPath);
+    let quarantinePath: string;
+    if (intent) {
+      quarantinePath = intent.quarantinePath;
+    } else {
+      const token = plugins.crypto.randomBytes(16).toString('hex');
+      quarantinePath = getServiceDataQuarantinePath(hostPath, token);
+      intent = {
+        owner: serviceDataOwner,
+        kind: 'service-data-deletion',
+        schemaVersion: 1,
+        projectPath,
+        service: optionsArg.service,
+        canonicalPath: hostPath,
+        quarantinePath,
+        token,
+        createdAt: new Date().toISOString(),
+      };
+    }
+    let quarantineExists = await this.assertRegularDeletionDirectory(quarantinePath);
+    if (canonicalExists && quarantineExists) {
+      throw new Error(
+        `Refusing ambiguous service data deletion with both canonical and quarantine paths present: ${hostPath}`,
+      );
     }
 
-    // Fast path: the current user may already own everything.
+    if (optionsArg.service === 'objectstorage' && (canonicalExists || quarantineExists)) {
+      const marker = await readServiceDataMarker(projectPath);
+      if (
+        !markerProvesServiceDataDirectory(
+          marker,
+          projectPath,
+          optionsArg.service,
+        )
+      ) {
+        throw new Error(`Refusing ObjectStorage cleanup with unproven ownership: ${hostPath}`);
+      }
+    }
+    const targetPaths = [hostPath, quarantinePath];
+    const serviceContainerFilters = [
+      `label=git.zone.project-path=${projectPath}`,
+      `label=git.zone.service=${optionsArg.service}`,
+    ];
+    let serviceContainerIds = await this.listIds(serviceContainerFilters);
+    if (serviceContainerIds.length > 0) {
+      const serviceContainers = await this.inspectMany(serviceContainerIds);
+      const helperTargets = new Set<string>();
+      for (const container of serviceContainers) {
+        const helperTarget = targetPaths.find((targetPathArg) =>
+          isExactStoppedBindHelperForTarget(container, targetPathArg, optionsArg),
+        );
+        if (!helperTarget) {
+          throw new Error(
+            `Refusing service data cleanup while container ${container.name} exists.`,
+          );
+        }
+        helperTargets.add(helperTarget);
+      }
+      for (const helperTarget of helperTargets) {
+        await this.reclaimStaleFencedBindOperation(
+          this.getDataCleanupOperation(helperTarget, imageArg, optionsArg),
+          getFencedBindOperationName(helperTarget),
+        );
+      }
+      serviceContainerIds = await this.listIds(serviceContainerFilters);
+      if (serviceContainerIds.length > 0) {
+        const [container] = await this.inspectMany(serviceContainerIds);
+        throw new Error(
+          `Refusing service data cleanup while container ${container?.name || serviceContainerIds[0]} exists.`,
+        );
+      }
+    }
+    const containerMountSources = await this.listAllMountSources();
+    const mountConflict = containerMountSources.find((sourceArg) =>
+      targetPaths.some((targetPathArg) => helpers.pathsOverlap(targetPathArg, sourceArg)),
+    );
+    if (mountConflict) {
+      throw new Error(
+        `Refusing mounted service data path: ${hostPath} or its quarantine is used by ${mountConflict}`,
+      );
+    }
+
+    if (!canonicalExists && !quarantineExists) {
+      if (await plugins.smartfs.file(getServiceDataDeletionIntentPath(projectPath, optionsArg.service)).exists()) {
+        await plugins.fs.rm(getServiceDataDeletionIntentPath(projectPath, optionsArg.service));
+        return true;
+      }
+      return false;
+    }
+
+    if (!(await plugins.smartfs.file(getServiceDataDeletionIntentPath(projectPath, optionsArg.service)).exists())) {
+      await this.writeServiceDataDeletionIntent(intent);
+    }
+    if (canonicalExists) {
+      try {
+        await this.renameDataDirectory(hostPath, quarantinePath);
+      } catch (error) {
+        throw new Error(
+          `Could not quarantine ${hostPath} before deletion; the persisted intent is safe to retry.`,
+          { cause: error },
+        );
+      }
+      canonicalExists = false;
+      quarantineExists = true;
+    }
+
+    // All destructive work happens under the persisted quarantine name. A
+    // failure can leave bytes to resume, but never a partial canonical dataset.
     try {
-      await plugins.smartfs.directory(hostPath).recursive().delete();
-    } catch (error) {
-      // fall through to privileged removal
+      await this.deleteDataDirectory(quarantinePath);
+    } catch {
+      // Fall through to root-helper removal.
     }
-    if (!(await plugins.smartfs.directory(hostPath).exists())) {
-      return;
+    quarantineExists = await this.assertRegularDeletionDirectory(quarantinePath);
+    if (!quarantineExists) {
+      await plugins.fs.rm(getServiceDataDeletionIntentPath(projectPath, optionsArg.service));
+      return true;
     }
 
     if (!(await this.imageExists(imageArg))) {
       throw new Error(
-        `Cannot remove ${hostPath}: its contents belong to the container user and image ` +
-          `${imageArg} is not available locally to perform a privileged cleanup. ` +
-          `Pull ${imageArg} and retry, or remove the directory manually as root.`,
+        `Cannot finish removing quarantined data at ${quarantinePath}: its contents belong to the container user and image ` +
+          `${imageArg} is not available locally to perform a root-helper cleanup. ` +
+          `Pull ${imageArg} and retry; the canonical path remains absent and the deletion intent is preserved.`,
       );
     }
 
-    // Empty the mounted directory from inside a root container, then remove the
-    // now-empty directory from the host.
-    const emptied = await this.runOneOff({
-      image: imageArg,
-      shell: 'sh',
-      command: 'rm -rf /gitzone-target/..?* /gitzone-target/.[!.]* /gitzone-target/*',
-      volumes: { [hostPath]: '/gitzone-target' },
-      user: '0',
-    });
-    if (!emptied) {
-      throw new Error(`Privileged cleanup of ${hostPath} failed`);
-    }
+    await this.runFencedBindOperation(
+      this.getDataCleanupOperation(quarantinePath, imageArg, optionsArg),
+    );
 
     try {
-      await plugins.smartfs.directory(hostPath).recursive().delete();
+      await this.deleteDataDirectory(quarantinePath);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new Error(`Could not remove ${hostPath} after privileged cleanup: ${errorMessage}`);
+      throw new Error(
+        `Could not remove quarantine ${quarantinePath} after root-helper cleanup: ${errorMessage}`,
+      );
     }
 
-    if (await plugins.smartfs.directory(hostPath).exists()) {
-      throw new Error(`Refusing to report success: ${hostPath} still exists`);
+    if (await plugins.smartfs.directory(quarantinePath).exists()) {
+      throw new Error(`Refusing to report success: quarantine ${quarantinePath} still exists`);
     }
+    await plugins.fs.rm(getServiceDataDeletionIntentPath(projectPath, optionsArg.service));
+    return true;
   }
 
   /**
@@ -564,9 +1376,11 @@ export class DockerContainer {
    */
   public async logs(containerName: string, lines?: number): Promise<string> {
     try {
-      const tailFlag = lines ? `--tail ${lines}` : '';
-      const result = await this.smartshell.exec(`docker logs ${tailFlag} ${containerName}`);
-      return result.combinedOutput;
+      const result = await this.execArgv(
+        ['logs', ...(lines ? ['--tail', String(lines)] : []), containerName],
+        { timeoutMs: this.queryTimeoutSeconds * 1_000 },
+      );
+      return `${result.stdout}${result.stderr}`;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       return `Error getting logs: ${errorMessage}`;
@@ -607,12 +1421,11 @@ export class DockerContainer {
    */
   public async inspect(containerName: string): Promise<any> {
     try {
-      const result = await this.smartshell.execSilent(`docker inspect ${containerName}`);
-      if (result.exitCode === 0) {
-        return JSON.parse(result.stdout);
-      }
-      return null;
-    } catch (error) {
+      const result = await this.execArgv(['inspect', containerName], {
+        timeoutMs: this.queryTimeoutSeconds * 1_000,
+      });
+      return JSON.parse(result.stdout);
+    } catch {
       return null;
     }
   }
@@ -623,10 +1436,8 @@ export class DockerContainer {
   public async getPortMappings(containerName: string): Promise<{ [key: string]: string } | null> {
     try {
       // Use docker inspect without format to get full JSON, then extract PortBindings
-      const result = await this.smartshell.execSilent(`docker inspect ${containerName}`);
-      
-      if (result.exitCode === 0 && result.stdout) {
-        const inspectData = JSON.parse(result.stdout);
+      const inspectData = await this.inspect(containerName);
+      if (inspectData) {
         if (inspectData && inspectData[0] && inspectData[0].HostConfig && inspectData[0].HostConfig.PortBindings) {
           const portBindings = inspectData[0].HostConfig.PortBindings;
           const mappings: { [key: string]: string } = {};
@@ -658,14 +1469,13 @@ export class DockerContainer {
    * mistaking an unreachable daemon for "no containers exist".
    */
   public async listIds(filterArgs: string[], includeStopped: boolean = true): Promise<string[]> {
-    const filters = filterArgs.map((filter) => `--filter ${shellQuote(filter)}`).join(' ');
-    const allFlag = includeStopped ? '-a' : '';
-    const result = await this.smartshell.execSilent(
-      `${this.bounded(this.queryTimeoutSeconds)} ps ${allFlag} ${filters} --format '{{.ID}}'`,
-    );
-    if (result.exitCode !== 0) {
-      throw new Error(result.combinedOutput);
-    }
+    const argv = ['ps'];
+    if (includeStopped) argv.push('-a');
+    for (const filter of filterArgs) argv.push('--filter', filter);
+    argv.push('--format', '{{.ID}}');
+    const result = await this.execArgv(argv, {
+      timeoutMs: this.queryTimeoutSeconds * 1_000,
+    });
     if (!result.stdout.trim()) {
       return [];
     }
@@ -684,12 +1494,9 @@ export class DockerContainer {
     if (idsArg.length === 0) {
       return [];
     }
-    const result = await this.smartshell.execSilent(
-      `${this.bounded(this.queryTimeoutSeconds)} inspect ${idsArg.map((id) => shellQuote(id)).join(' ')}`,
-    );
-    if (result.exitCode !== 0) {
-      throw new Error(result.combinedOutput);
-    }
+    const result = await this.execArgv(['inspect', ...idsArg], {
+      timeoutMs: this.queryTimeoutSeconds * 1_000,
+    });
     let parsed: any;
     try {
       parsed = JSON.parse(result.stdout);
@@ -726,7 +1533,16 @@ export class DockerContainer {
    * mounted by anything running is never a deletion candidate.
    */
   public async listRunningMountSources(): Promise<string[]> {
-    const ids = await this.listIds([], false);
+    return this.listMountSources(false);
+  }
+
+  /** Resolved host bind paths configured on running and stopped containers. */
+  public async listAllMountSources(): Promise<string[]> {
+    return this.listMountSources(true);
+  }
+
+  private async listMountSources(includeStoppedArg: boolean): Promise<string[]> {
+    const ids = await this.listIds([], includeStoppedArg);
     const containers = await this.inspectMany(ids);
     const sources = new Set<string>();
     for (const container of containers) {