@git.zone/cli 3.0.0 → 3.0.2

package/ts/mod_services/classes.servicemanager.ts

@@ -1,7 +1,15 @@
 import * as plugins from './mod.plugins.js';
 import * as helpers from './helpers.js';
-import { ServiceConfiguration } from './classes.serviceconfiguration.js';
-import { DockerContainer } from './classes.dockercontainer.js';
+import {
+  ServiceConfiguration,
+  getS3BucketNameValidationError,
+} from './classes.serviceconfiguration.js';
+import {
+  DockerContainer,
+  matchDockerUlimits,
+  type IDockerExecArgvResult,
+  type TDockerUlimits,
+} from './classes.dockercontainer.js';
 import { GlobalRegistry } from './classes.globalregistry.js';
 import {
   getServiceContainerLabels,
@@ -44,11 +52,261 @@ export interface IServicesStatus {
   totalDataBytes: number;
 }
 
+export const mongoServiceUlimits = {
+  nofile: {
+    soft: 65_536,
+    hard: 65_536,
+  },
+} as const satisfies TDockerUlimits;
+
+export const minioReconciliationTimeoutMs = 30_000;
+const minioProbeTimeoutCapMs = 2_000;
+const minioProbeIntervalMs = 250;
+const minioRollbackTimeoutMs = 5_000;
+const minioAlias = 'gitzone-local';
+const minioAliasSetupScript =
+  'mc alias set gitzone-local http://127.0.0.1:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD" >/dev/null';
+
+export interface IMinioReconciliationClock {
+  now(): number;
+  delay(millisecondsArg: number): Promise<void>;
+}
+
+export interface IMinioReconciliationOptions {
+  docker: Pick<DockerContainer, 'execArgv'>;
+  /** Full immutable Docker container id; mutable names are never accepted here. */
+  containerId: string;
+  bucket: string;
+  /** Shared absolute deadline. Defaults to 30 seconds from this call. */
+  deadlineAt?: number;
+  clock?: IMinioReconciliationClock;
+}
+
+const defaultMinioClock: IMinioReconciliationClock = {
+  now: () => Date.now(),
+  delay: async (millisecondsArg) => plugins.smartdelay.delayFor(millisecondsArg),
+};
+
+class MinioStageError extends Error {
+  constructor(stageArg: string, timedOutArg: boolean, causeArg?: unknown) {
+    const message = timedOutArg
+      ? `MinIO ${stageArg} did not complete before the shared reconciliation deadline.`
+      : `MinIO ${stageArg} failed.`;
+    super(message, causeArg === undefined ? undefined : { cause: causeArg });
+    this.name = 'MinioStageError';
+  }
+}
+
+const minioStageError = (
+  stageArg: string,
+  timedOutArg: boolean,
+  causeArg?: unknown,
+): MinioStageError => {
+  return new MinioStageError(stageArg, timedOutArg, causeArg);
+};
+
+const minioStageCause = (errorArg: unknown): unknown => {
+  if (errorArg instanceof MinioStageError && errorArg.cause !== undefined) {
+    return errorArg.cause;
+  }
+  return errorArg;
+};
+
+const normalizeMinioLifecycleError = (errorArg: unknown): Error => {
+  return errorArg instanceof Error
+    ? errorArg
+    : new Error('MinIO lifecycle failed with a non-Error rejection.');
+};
+
+interface IMinioContainerInspection {
+  id: string;
+  name: string;
+  running: boolean;
+  portBindings: Record<string, unknown>;
+  environmentEntries: string[];
+  labels: Record<string, string>;
+}
+
+const isUnknownRecord = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+};
+
+const parseMinioInspection = (
+  stdoutArg: string,
+  expectedContainerNameArg: string,
+): IMinioContainerInspection => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdoutArg);
+  } catch {
+    throw new Error(`Docker returned an invalid MinIO inspection for ${expectedContainerNameArg}.`);
+  }
+  if (!Array.isArray(parsed) || parsed.length !== 1 || !isUnknownRecord(parsed[0])) {
+    throw new Error(`Docker returned an invalid MinIO inspection for ${expectedContainerNameArg}.`);
+  }
+
+  const inspected = parsed[0];
+  const state = inspected.State;
+  const config = inspected.Config;
+  const hostConfig = inspected.HostConfig;
+  const normalizedName =
+    typeof inspected.Name === 'string' ? inspected.Name.replace(/^\//u, '') : undefined;
+  if (
+    typeof inspected.Id !== 'string' ||
+    !/^[a-f0-9]{64}$/u.test(inspected.Id) ||
+    normalizedName !== expectedContainerNameArg ||
+    !isUnknownRecord(state) ||
+    typeof state.Running !== 'boolean' ||
+    !isUnknownRecord(config) ||
+    !isUnknownRecord(hostConfig) ||
+    !isUnknownRecord(hostConfig.PortBindings) ||
+    !Array.isArray(config.Env) ||
+    !config.Env.every((entryArg) => typeof entryArg === 'string')
+  ) {
+    throw new Error(`Docker returned an invalid MinIO inspection for ${expectedContainerNameArg}.`);
+  }
+
+  const labels: Record<string, string> = {};
+  if (config.Labels !== null && config.Labels !== undefined) {
+    if (!isUnknownRecord(config.Labels)) {
+      throw new Error(`Docker returned an invalid MinIO inspection for ${expectedContainerNameArg}.`);
+    }
+    for (const [key, value] of Object.entries(config.Labels)) {
+      if (typeof value !== 'string') {
+        throw new Error(
+          `Docker returned an invalid MinIO inspection for ${expectedContainerNameArg}.`,
+        );
+      }
+      labels[key] = value;
+    }
+  }
+
+  return {
+    id: inspected.Id,
+    name: normalizedName,
+    running: state.Running,
+    portBindings: hostConfig.PortBindings,
+    environmentEntries: config.Env,
+    labels,
+  };
+};
+
+const minioPortMatches = (
+  portBindingsArg: Record<string, unknown>,
+  containerPortArg: string,
+  expectedHostPortArg: string,
+): boolean => {
+  const bindings = portBindingsArg[containerPortArg];
+  return (
+    Array.isArray(bindings) &&
+    bindings.some(
+      (bindingArg) =>
+        isUnknownRecord(bindingArg) && bindingArg.HostPort === expectedHostPortArg,
+    )
+  );
+};
+
+/** Converge a running MinIO container to an authenticated, verified bucket. */
+export const reconcileMinioBucket = async (
+  optionsArg: IMinioReconciliationOptions,
+): Promise<void> => {
+  if (!/^[a-f0-9]{64}$/u.test(optionsArg.containerId)) {
+    throw new Error('MinIO reconciliation requires a full immutable Docker container id.');
+  }
+  const clock = optionsArg.clock || defaultMinioClock;
+  const deadlineAt = optionsArg.deadlineAt ?? clock.now() + minioReconciliationTimeoutMs;
+  if (!Number.isFinite(deadlineAt)) {
+    throw new Error('MinIO reconciliation deadline must be finite');
+  }
+
+  const remainingMs = (): number => Math.floor(deadlineAt - clock.now());
+  const execOnce = async (
+    stageArg: string,
+    argvArg: readonly string[],
+    timeoutCapMsArg?: number,
+  ): Promise<IDockerExecArgvResult> => {
+    const remaining = remainingMs();
+    if (remaining <= 0) {
+      throw minioStageError(stageArg, true);
+    }
+    try {
+      return await optionsArg.docker.execArgv(argvArg, {
+        timeoutMs: Math.max(
+          1,
+          timeoutCapMsArg === undefined ? remaining : Math.min(timeoutCapMsArg, remaining),
+        ),
+      });
+    } catch (error) {
+      throw minioStageError(stageArg, remainingMs() <= 0, error);
+    }
+  };
+  const execUntilReady = async (
+    stageArg: string,
+    argvArg: readonly string[],
+  ): Promise<IDockerExecArgvResult> => {
+    let lastCause: unknown;
+    while (true) {
+      try {
+        return await execOnce(stageArg, argvArg, minioProbeTimeoutCapMs);
+      } catch (error) {
+        const currentCause = minioStageCause(error);
+        if (currentCause !== undefined) {
+          lastCause = currentCause;
+        }
+        const remaining = remainingMs();
+        if (remaining <= 0) {
+          throw minioStageError(stageArg, true, lastCause);
+        }
+        await clock.delay(Math.min(minioProbeIntervalMs, remaining));
+        if (remainingMs() <= 0) {
+          throw minioStageError(stageArg, true, lastCause);
+        }
+      }
+    }
+  };
+
+  await execUntilReady('container readiness', ['exec', optionsArg.containerId, 'true']);
+  // The fixed script reads credentials only from the container environment.
+  await execUntilReady('alias configuration', [
+    'exec',
+    optionsArg.containerId,
+    'sh',
+    '-c',
+    minioAliasSetupScript,
+  ]);
+  await execUntilReady('authenticated readiness', [
+    'exec',
+    optionsArg.containerId,
+    'mc',
+    'ready',
+    '--json',
+    minioAlias,
+  ]);
+
+  const bucketTarget = `${minioAlias}/${optionsArg.bucket}`;
+  await execOnce('bucket creation', [
+    'exec',
+    optionsArg.containerId,
+    'mc',
+    'mb',
+    '--ignore-existing',
+    bucketTarget,
+  ]);
+  await execOnce('bucket verification', [
+    'exec',
+    optionsArg.containerId,
+    'mc',
+    'stat',
+    bucketTarget,
+  ]);
+};
+
 export class ServiceManager {
   private config: ServiceConfiguration;
   private docker: DockerContainer;
   private enabledServices: string[] | null = null;
   private globalRegistry: GlobalRegistry;
+  private minioClock: IMinioReconciliationClock = defaultMinioClock;
 
   constructor() {
     this.config = new ServiceConfiguration();
@@ -297,24 +555,60 @@ export class ServiceManager {
 
     const status = await this.docker.getStatus(containers.mongo);
 
-    // Containers created before replica-set support, with a changed port, or
-    // running the other auth mode must be recreated; the data is preserved.
+    // Containers created before replica-set or managed-limit support, with a
+    // changed port, or running the other auth mode must be recreated; the data
+    // is preserved.
     let needsRecreate = false;
     if (status !== 'not_exists') {
-      const containerCmd = await this.getMongoContainerCmd(containers.mongo);
+      const inspectInfo = await this.docker.inspect(containers.mongo);
+      if (!Array.isArray(inspectInfo) || inspectInfo.length !== 1) {
+        throw new Error(
+          `Unable to inspect MongoDB container ${containers.mongo}; refusing to recreate it.`,
+        );
+      }
+      const inspectedContainer = inspectInfo[0];
+      if (
+        !inspectedContainer?.Config ||
+        !Array.isArray(inspectedContainer.Config.Cmd) ||
+        !inspectedContainer.HostConfig ||
+        !Object.hasOwn(inspectedContainer.HostConfig, 'PortBindings')
+      ) {
+        throw new Error(
+          `Incomplete inspection for MongoDB container ${containers.mongo}; refusing to recreate it.`,
+        );
+      }
+      const containerCmd = inspectedContainer.Config.Cmd;
       const hasReplSet = containerCmd.includes('--replSet');
       const hasKeyFile = containerCmd.includes('--keyFile');
-      const portMappings = await this.docker.getPortMappings(containers.mongo);
+      const mongoPortBindings =
+        inspectedContainer.HostConfig.PortBindings?.[`${config.MONGODB_PORT}/tcp`];
       const portMatches =
-        !!portMappings && portMappings[config.MONGODB_PORT] === config.MONGODB_PORT;
+        Array.isArray(mongoPortBindings) &&
+        mongoPortBindings.length > 0 &&
+        mongoPortBindings.some(
+          (bindingArg: { HostPort?: string }) => bindingArg?.HostPort === config.MONGODB_PORT,
+        );
       const authMatches = hasKeyFile === this.config.isMongoAuthEnabled();
-      needsRecreate = !hasReplSet || !portMatches || !authMatches;
+      const ulimitMatch = matchDockerUlimits(inspectInfo, mongoServiceUlimits);
+      if (ulimitMatch === 'unavailable') {
+        throw new Error(
+          `Unable to inspect MongoDB container limits for ${containers.mongo}; refusing to recreate it.`,
+        );
+      }
+      needsRecreate =
+        !hasReplSet ||
+        !portMatches ||
+        !authMatches ||
+        ulimitMatch === 'mismatch';
       if (!authMatches) {
         logger.log(
           'note',
           `  Auth mode changed to ${this.config.isMongoAuthEnabled() ? 'enabled' : 'disabled'}, recreating container...`,
         );
       }
+      if (ulimitMatch === 'mismatch') {
+        logger.log('note', '  MongoDB file-descriptor limit changed, recreating container...');
+      }
     }
 
     switch (status) {
@@ -323,7 +617,7 @@ export class ServiceManager {
           logger.log('ok', '  Already running ✓');
           break;
         }
-        logger.log('note', '  Upgrading to single-node replica set, recreating container...');
+        logger.log('note', '  MongoDB service configuration changed, recreating container...');
         await this.docker.remove(containers.mongo, true);
         await this.createMongoContainer();
         break;
@@ -420,6 +714,7 @@ export class ServiceManager {
       },
       environment,
       labels,
+      ulimits: mongoServiceUlimits,
       restart: 'unless-stopped',
       command
     });
@@ -428,6 +723,7 @@ export class ServiceManager {
       logger.log('ok', '  Created and started ✓');
     } else {
       logger.log('error', '  Failed to create container');
+      throw new Error(`Failed to create MongoDB container ${containers.mongo}.`);
     }
   }
 
@@ -451,14 +747,6 @@ export class ServiceManager {
     });
   }
 
-  /**
-   * The mongod argv the container was created with
-   */
-  private async getMongoContainerCmd(containerName: string): Promise<string[]> {
-    const info = await this.docker.inspect(containerName);
-    return info?.[0]?.Config?.Cmd ?? [];
-  }
-
   /**
    * Make sure the configured root user exists when auth is enabled.
    *
@@ -557,137 +845,328 @@ export class ServiceManager {
     logger.log('error', '  Replica set not ready after 30s — transactions unavailable');
     return false;
   }
+
+  private async inspectMinioContainer(
+    containerReferenceArg: string,
+    expectedContainerNameArg: string,
+    dockerTimeoutArg: () => { timeoutMs: number },
+  ): Promise<IMinioContainerInspection> {
+    const result = await this.docker.execArgv(
+      ['inspect', containerReferenceArg],
+      dockerTimeoutArg(),
+    );
+    return parseMinioInspection(result.stdout, expectedContainerNameArg);
+  }
+
+  private async assertMinioOwnership(
+    inspectionArg: IMinioContainerInspection,
+    expectedLabelsArg: Record<string, string>,
+    allowLegacyRegistryArg: boolean,
+  ): Promise<void> {
+    const actualGitZoneLabels = Object.entries(inspectionArg.labels).filter(([key]) =>
+      key.startsWith('git.zone.'),
+    );
+    const expectedEntries = Object.entries(expectedLabelsArg);
+    const hasExactCurrentLabels =
+      actualGitZoneLabels.length === expectedEntries.length &&
+      expectedEntries.every(([key, value]) => inspectionArg.labels[key] === value);
+    if (hasExactCurrentLabels) {
+      return;
+    }
+
+    const refusal = (): Error =>
+      new Error(
+        `Refusing to use MinIO container ${inspectionArg.name}: ` +
+          'its ownership is not proven for the current project.',
+      );
+
+    if (!allowLegacyRegistryArg) {
+      throw refusal();
+    }
+
+    // Any ownership label is authoritative. A partial, stale, or foreign set
+    // must never be reinterpreted through the legacy registry fallback.
+    if (actualGitZoneLabels.length > 0 || Object.keys(inspectionArg.labels).length > 0) {
+      throw refusal();
+    }
+
+    // Containers created before labels were introduced may be reclaimed only
+    // when the old global registry has one unambiguous claim for this exact
+    // name and the current resolved project path.
+    const currentProjectPath = plugins.path.resolve(process.cwd());
+    const registryProjects = await this.globalRegistry.getAllProjects();
+    const claims = Object.entries(registryProjects).filter(
+      ([, project]) => project.containers.minio === inspectionArg.name,
+    );
+    if (claims.length !== 1) {
+      throw refusal();
+    }
+    const [registryPath, project] = claims[0];
+    if (
+      plugins.path.resolve(registryPath) !== currentProjectPath ||
+      plugins.path.resolve(project.projectPath) !== currentProjectPath
+    ) {
+      throw refusal();
+    }
+  }
+
+  private async revalidateMinioContainer(
+    containerIdArg: string,
+    expectedContainerNameArg: string,
+    expectedLabelsArg: Record<string, string>,
+    allowLegacyRegistryArg: boolean,
+    dockerTimeoutArg: () => { timeoutMs: number },
+  ): Promise<IMinioContainerInspection> {
+    const inspection = await this.inspectMinioContainer(
+      containerIdArg,
+      expectedContainerNameArg,
+      dockerTimeoutArg,
+    );
+    if (inspection.id !== containerIdArg) {
+      throw new Error(
+        `Refusing to use MinIO container ${expectedContainerNameArg}: ` +
+          'its immutable id changed during reconciliation.',
+      );
+    }
+    await this.assertMinioOwnership(
+      inspection,
+      expectedLabelsArg,
+      allowLegacyRegistryArg,
+    );
+    return inspection;
+  }
   
   /**
    * Start MinIO service
    */
   public async startMinIO(): Promise<void> {
     logger.log('note', '📦 S3/MinIO:');
-    
+
     const config = this.config.getConfig();
     const containers = this.config.getContainerNames();
     const directories = this.config.getDataDirectories();
-    
+
+    // Validation lives on the mutating path so recovery commands remain usable.
+    const bucketValidationError = getS3BucketNameValidationError(config.S3_BUCKET);
+    if (bucketValidationError) {
+      throw new Error(
+        `Invalid S3_BUCKET in .nogit/env.json: ${bucketValidationError}. ` +
+          'Choose a valid custom bucket name or remove the field to regenerate the project default.',
+      );
+    }
+
     // Ensure data directory exists and is marked as tool-owned
     const minioLabels = await this.prepareDataDirectory('minio', directories.minio);
+    const deadlineAt = this.minioClock.now() + minioReconciliationTimeoutMs;
+    const dockerTimeout = (): { timeoutMs: number } => {
+      const remaining = Math.floor(deadlineAt - this.minioClock.now());
+      if (remaining <= 0) {
+        throw new Error(
+          'MinIO container setup did not complete before the shared reconciliation deadline.',
+        );
+      }
+      return { timeoutMs: Math.max(1, remaining) };
+    };
 
-    const status = await this.docker.getStatus(containers.minio);
-    
-    switch (status) {
-      case 'running':
-        logger.log('ok', '  Already running ✓');
-        break;
-        
-      case 'stopped':
-        // Check if port mapping matches config
-        const minioPortMappings = await this.docker.getPortMappings(containers.minio);
-        if (minioPortMappings && 
-            (minioPortMappings['9000'] !== config.S3_PORT || 
-             minioPortMappings['9001'] !== config.S3_CONSOLE_PORT)) {
-          logger.log('note', '  Port configuration changed, recreating container...');
-          await this.docker.remove(containers.minio, true);
-          // Fall through to create new container
-          const success = await this.docker.run({
-            name: containers.minio,
-            image: 'minio/minio',
-            ports: {
-              [config.S3_PORT]: '9000',
-              [config.S3_CONSOLE_PORT]: '9001'
-            },
-            volumes: {
-              [directories.minio]: '/data'
-            },
-            environment: {
-              MINIO_ROOT_USER: config.S3_ACCESSKEY,
-              MINIO_ROOT_PASSWORD: config.S3_SECRETKEY
-            },
-            labels: minioLabels,
-            restart: 'unless-stopped',
-            command: 'server /data --console-address ":9001"'
-          });
+    const startedContainerIds: string[] = [];
+    const startById = async (containerIdArg: string): Promise<void> => {
+      const executionOptions = dockerTimeout();
+      // Record ownership of the lifecycle before awaiting Docker: a timed-out
+      // start may still have reached the daemon and must be rolled back.
+      startedContainerIds.push(containerIdArg);
+      await this.docker.execArgv(['start', containerIdArg], executionOptions);
+    };
 
-          if (success) {
-            logger.log('ok', '  Recreated with new ports ✓');
-            
-            // Wait for MinIO to be ready
-            await plugins.smartdelay.delayFor(3000);
-            
-            // Create default bucket
-            await this.docker.exec(
-              containers.minio,
-              `mc alias set local http://localhost:9000 ${config.S3_ACCESSKEY} ${config.S3_SECRETKEY}`
-            );
-            
-            await this.docker.exec(
-              containers.minio,
-              `mc mb local/${config.S3_BUCKET}`
-            );
-            
-            logger.log('ok', `  Bucket '${config.S3_BUCKET}' created ✓`);
-          } else {
-            logger.log('error', '  Failed to recreate container');
-          }
-        } else {
-          // Ports match, just start the container
-          if (await this.docker.start(containers.minio)) {
-            logger.log('ok', '  Started ✓');
-          } else {
-            logger.log('error', '  Failed to start');
-          }
-        }
-        break;
-        
-      case 'not_exists':
-        logger.log('note', '  Creating container...');
-        
-        const success = await this.docker.run({
-          name: containers.minio,
-          image: 'minio/minio',
-          ports: {
-            [config.S3_PORT]: '9000',
-            [config.S3_CONSOLE_PORT]: '9001'
-          },
-          volumes: {
-            [directories.minio]: '/data'
-          },
-          environment: {
-            MINIO_ROOT_USER: config.S3_ACCESSKEY,
-            MINIO_ROOT_PASSWORD: config.S3_SECRETKEY
-          },
-          labels: minioLabels,
-          restart: 'unless-stopped',
-          command: 'server /data --console-address ":9001"'
-        });
+    let outcome: string;
+    try {
+      const listResult = await this.docker.execArgv(
+        [
+          'container',
+          'ls',
+          '-a',
+          '--filter',
+          `name=${containers.minio}`,
+          '--format',
+          '{{.Names}}',
+        ],
+        dockerTimeout(),
+      );
+      const containerExists = listResult.stdout
+        .split(/\r?\n/u)
+        .map((lineArg) => lineArg.trim())
+        .includes(containers.minio);
+
+      let initialInspection: IMinioContainerInspection | undefined;
+      if (containerExists) {
+        initialInspection = await this.inspectMinioContainer(
+          containers.minio,
+          containers.minio,
+          dockerTimeout,
+        );
+        // No existing container is started or receives an in-container command
+        // until it proves current or unambiguous legacy ownership.
+        await this.assertMinioOwnership(initialInspection, minioLabels, true);
+      }
 
-        if (success) {
-          logger.log('ok', '  Created and started ✓');
-          
-          // Wait for MinIO to be ready
-          await plugins.smartdelay.delayFor(3000);
-          
-          // Create default bucket
-          await this.docker.exec(
-            containers.minio,
-            `mc alias set local http://localhost:9000 ${config.S3_ACCESSKEY} ${config.S3_SECRETKEY}`
-          );
-          
-          await this.docker.exec(
-            containers.minio,
-            `mc mb local/${config.S3_BUCKET}`
+      let needsRecreate = false;
+      let credentialsChanged = false;
+      if (initialInspection) {
+        const apiMatches = minioPortMatches(
+          initialInspection.portBindings,
+          '9000/tcp',
+          config.S3_PORT,
+        );
+        const consoleMatches = minioPortMatches(
+          initialInspection.portBindings,
+          '9001/tcp',
+          config.S3_CONSOLE_PORT,
+        );
+        const readExactEnvironmentValue = (nameArg: string): string | undefined => {
+          const prefix = `${nameArg}=`;
+          const matches = initialInspection.environmentEntries.filter((entryArg) =>
+            entryArg.startsWith(prefix),
           );
-          
-          logger.log('ok', `  Bucket '${config.S3_BUCKET}' created ✓`);
-        } else {
-          logger.log('error', '  Failed to create container');
+          return matches.length === 1 ? matches[0].slice(prefix.length) : undefined;
+        };
+        credentialsChanged =
+          readExactEnvironmentValue('MINIO_ROOT_USER') !== config.S3_ACCESSKEY ||
+          readExactEnvironmentValue('MINIO_ROOT_PASSWORD') !== config.S3_SECRETKEY;
+        needsRecreate = !apiMatches || !consoleMatches || credentialsChanged;
+      }
+
+      let activeInspection: IMinioContainerInspection;
+      let activeAllowsLegacyRegistry: boolean;
+      if (initialInspection && needsRecreate) {
+        logger.log(
+          'note',
+          credentialsChanged
+            ? '  Credential configuration changed, recreating container...'
+            : '  Port configuration changed, recreating container...',
+        );
+        await this.revalidateMinioContainer(
+          initialInspection.id,
+          containers.minio,
+          minioLabels,
+          true,
+          dockerTimeout,
+        );
+        await this.docker.execArgv(['rm', '-f', initialInspection.id], dockerTimeout());
+        activeInspection = await this.createMinioContainer(minioLabels, dockerTimeout);
+        activeAllowsLegacyRegistry = false;
+        await startById(activeInspection.id);
+        outcome = 'Recreated with configured ports and reconciled';
+      } else if (initialInspection && !initialInspection.running) {
+        logger.log('note', '  Starting existing container...');
+        activeInspection = initialInspection;
+        activeAllowsLegacyRegistry = true;
+        await startById(activeInspection.id);
+        outcome = 'Started and reconciled';
+      } else if (!initialInspection) {
+        logger.log('note', '  Creating container...');
+        activeInspection = await this.createMinioContainer(minioLabels, dockerTimeout);
+        activeAllowsLegacyRegistry = false;
+        await startById(activeInspection.id);
+        outcome = 'Created, started, and reconciled';
+      } else {
+        logger.log('note', '  Already running; reconciling bucket...');
+        activeInspection = initialInspection;
+        activeAllowsLegacyRegistry = true;
+        outcome = 'Already running and reconciled';
+      }
+
+      const reconciliationInspection = await this.revalidateMinioContainer(
+        activeInspection.id,
+        containers.minio,
+        minioLabels,
+        activeAllowsLegacyRegistry,
+        dockerTimeout,
+      );
+      await reconcileMinioBucket({
+        docker: this.docker,
+        containerId: reconciliationInspection.id,
+        bucket: config.S3_BUCKET,
+        deadlineAt,
+        clock: this.minioClock,
+      });
+    } catch (error) {
+      const originalError = normalizeMinioLifecycleError(error);
+      const rollbackErrors: Error[] = [];
+      for (let index = startedContainerIds.length - 1; index >= 0; index--) {
+        try {
+          await this.docker.execArgv(['stop', startedContainerIds[index]], {
+            timeoutMs: minioRollbackTimeoutMs,
+          });
+        } catch (rollbackError) {
+          rollbackErrors.push(normalizeMinioLifecycleError(rollbackError));
         }
-        break;
+      }
+      if (rollbackErrors.length > 0) {
+        throw new AggregateError(
+          [originalError, ...rollbackErrors],
+          'MinIO startup failed and rollback could not stop every container started by this invocation.',
+        );
+      }
+      throw originalError;
     }
-    
+
+    logger.log('ok', `  ${outcome} ✓`);
+    logger.log('ok', `  Bucket '${config.S3_BUCKET}' exists and is authenticated ✓`);
     logger.log('info', `  Container: ${containers.minio}`);
     logger.log('info', `  Port: ${config.S3_PORT}`);
     logger.log('info', `  Bucket: ${config.S3_BUCKET}`);
     logger.log('info', `  API: http://${config.S3_HOST}:${config.S3_PORT}`);
-    logger.log('info', `  Console: http://${config.S3_HOST}:${config.S3_CONSOLE_PORT} (login: ${config.S3_ACCESSKEY}/***)`);
+    logger.log(
+      'info',
+      `  Console: http://${config.S3_HOST}:${config.S3_CONSOLE_PORT} (credentials: ***)`,
+    );
+  }
+
+  /** Create stopped MinIO, inspect its id, and prove exact current labels. */
+  private async createMinioContainer(
+    labelsArg: { [key: string]: string },
+    dockerTimeoutArg: () => { timeoutMs: number },
+  ): Promise<IMinioContainerInspection> {
+    const config = this.config.getConfig();
+    const containers = this.config.getContainerNames();
+    const directories = this.config.getDataDirectories();
+    const creationResult = await this.docker.createArgv(
+      {
+        name: containers.minio,
+        image: 'minio/minio',
+        ports: {
+          [config.S3_PORT]: '9000',
+          [config.S3_CONSOLE_PORT]: '9001',
+        },
+        volumes: {
+          [directories.minio]: '/data',
+        },
+        environment: {
+          MINIO_ROOT_USER: config.S3_ACCESSKEY,
+          MINIO_ROOT_PASSWORD: config.S3_SECRETKEY,
+        },
+        labels: labelsArg,
+        restart: 'unless-stopped',
+        command: ['server', '/data', '--console-address', ':9001'],
+      },
+      dockerTimeoutArg(),
+    );
+    const containerId = creationResult.stdout.trim();
+    if (!/^[a-f0-9]{64}$/u.test(containerId)) {
+      throw new Error(`Docker returned an invalid id while creating ${containers.minio}.`);
+    }
+    const inspection = await this.inspectMinioContainer(
+      containerId,
+      containers.minio,
+      dockerTimeoutArg,
+    );
+    if (inspection.id !== containerId) {
+      throw new Error(
+        `Refusing to start MinIO container ${containers.minio}: ` +
+          'Docker inspection did not return the created immutable id.',
+      );
+    }
+    await this.assertMinioOwnership(inspection, labelsArg, false);
+    return inspection;
   }
 
   /**
@@ -1103,7 +1582,7 @@ export class ServiceManager {
     logger.log('info', `  Host: ${config.S3_HOST}`);
     logger.log('info', `  API Port: ${config.S3_PORT}`);
     logger.log('info', `  Console Port: ${config.S3_CONSOLE_PORT}`);
-    logger.log('info', `  Access Key: ${config.S3_ACCESSKEY}`);
+    logger.log('info', '  Access Key: ***');
     logger.log('info', '  Secret Key: ***');
     logger.log('info', `  Bucket: ${config.S3_BUCKET}`);
     logger.log('info', `  Use SSL: ${config.S3_USESSL}`);